/** Host artifact kinds accepted by launch delivery and artifact resolution. */
declare type MiniAppArtifactKind = 'channel-message' | 'pull-request' | 'task' | 'repository-issue';

/**
 * An immutable, host-minted reference to a host artifact. A host invocation
 * receives this reference plus launch context — never copied content — and
 * packages resolve it through
 * {@link MiniAppArtifactsApi.resolve} under the package's permissions.
 */
declare type MiniAppArtifactReference = {
    /** Opaque host authority handle; artifact coordinates alone are not resolvable. */
    readonly referenceId: string;
    readonly kind: MiniAppArtifactKind;
    readonly artifactId: string;
    readonly workspaceId: string;
    readonly mintedAt: number;
    readonly expiresAt: number;
};

/**
 * Opaque, host-issued authority to one user-selected file.
 *
 * Handles deliberately contain no native path. The revision is the snapshot
 * observed when the handle was issued, refreshed by `metadata` or `watch`, or
 * returned after a mutation. Callers may also pass a newer observed revision
 * as a mutation fence without modifying the handle. `recoverable` tells callers
 * whether `recover` may restore the handle in a later desktop session.
 */
declare type MiniAppFileHandle = Readonly<Omit<MiniappUserFileHandle, 'expiresAt'> & {
    expiresAt: number | null;
}>;

declare type MiniappUserFileHandle = {
    id: string;
    revision: string;
    recoverable: boolean;
    expiresAt?: string | undefined;
};

/**
 * Resolves one raw package-relative asset path inside the descriptor-selected
 * target directory. Absolute, encoded-alias, and traversal inputs fail closed.
 */
export declare function resolvePackageAssetUrl(context: Pick<TapFederatedSurfaceMountContext, 'packageAssetBaseUrl'>, relativePath: string): URL;

/**
 * Host-owned entropy for release-scoped identifiers.
 *
 * Ordinary TAP surfaces use the browser's cryptographically strong UUID
 * source. Test Lab mounts derive a deterministic stream from the selected
 * profile seed and exact frame identity, then reset it before each mount so
 * app-owned state is reproducible without weakening production identifiers,
 * colliding across retained remounts, or relying on ambient test globals.
 */
export declare interface TapFederatedSurfaceEntropy {
    randomUUID(): string;
}

/**
 * Read-only authority projected by TAP for the exact package release/frame.
 * A candidate frame starts without authority and may only perform host-backed
 * work after the host confirms that release. Subscribers are notified only
 * when the boolean snapshot changes.
 */
export declare interface TapFederatedSurfaceHostAuthority {
    getSnapshot(): boolean;
    subscribe(listener: () => void): () => void;
}

/** One verified host invocation routed to this exact surface realm. */
export declare interface TapFederatedSurfaceLaunch {
    readonly requestId: string;
    readonly actionContributionId: string;
    readonly invokedAt: number;
    readonly reference: MiniAppArtifactReference;
    readonly owner?: TapFederatedSurfaceLaunchOwnerContext;
}

/**
 * Ordered, at-least-once context-action delivery.
 *
 * The runtime acknowledges a launch only after one listener returns `true`.
 * Consumers must use `requestId` as the idempotency key for durable effects.
 */
export declare interface TapFederatedSurfaceLaunches {
    subscribe(listener: (launch: TapFederatedSurfaceLaunch) => boolean | Promise<boolean>): () => void;
}

/** Bounded host ownership snapshot attached to one immutable launch. */
export declare interface TapFederatedSurfaceLaunchOwnerContext {
    readonly workspaceId: string;
    readonly channelId: string | null;
    readonly conversationId: string | null;
}

/** Cleanup handle returned by a federated surface mount. */
export declare interface TapFederatedSurfaceMount {
    unmount(): void | Promise<void>;
}

/** Context supplied by TAP's isolated webview surface runtime. */
export declare interface TapFederatedSurfaceMountContext {
    readonly packageId: string;
    readonly packageNamespace: string;
    readonly releaseId: string;
    readonly installationId: string;
    readonly contributionId: string;
    readonly instanceId: string;
    readonly hostOrigin: string;
    readonly packageAssetBaseUrl: string;
    /**
     * Host-canonical control-plane user identity for this interactive mount.
     *
     * This is intentionally distinct from an OAuth/OIDC profile subject. It is
     * the same user identity used when resolving MCP `{userId}` storage reads.
     * Activation preflight mounts do not receive user state and may omit it.
     */
    readonly userId?: string;
    readonly workspaceId?: string;
    readonly channelId?: string;
    readonly conversationId?: string;
    /**
     * One host-validated file-handler invocation for this mount. Later OS
     * launches create a fresh mount; they are never delivered over an event or
     * ambient subscription.
     */
    readonly userFileLaunchContext?: TapFederatedSurfaceUserFileLaunchContext;
    readonly events: TapPackageEventPublisher;
    readonly entropy: TapFederatedSurfaceEntropy;
    readonly hostAuthority: TapFederatedSurfaceHostAuthority;
    readonly owner: TapFederatedSurfaceOwner;
    readonly launches: TapFederatedSurfaceLaunches;
}

/**
 * Live host-selected owner for broad retained realms.
 *
 * The snapshot starts as `null` until the host projects an owner. Consumers
 * must subscribe when their behavior depends on channel or conversation
 * selection because `per-workspace` and `singleton` realms can change owners
 * without remounting.
 */
export declare interface TapFederatedSurfaceOwner {
    getSnapshot(): TapFederatedSurfaceOwnerSnapshot | null;
    subscribe(listener: () => void): () => void;
}

/**
 * Host-selected owner of one retained surface realm.
 *
 * These fields describe the current UI owner, not the immutable instance
 * policy scope exposed directly on `TapFederatedSurfaceMountContext`.
 */
export declare interface TapFederatedSurfaceOwnerSnapshot {
    readonly workspaceId: string | null;
    readonly channelId: string | null;
    readonly conversationId: string | null;
}

/** Initial file-handler invocation delivered only with a Surface mount. */
export declare type TapFederatedSurfaceUserFileLaunchContext = Readonly<{
    apiVersion: 1;
    intent: 'open' | 'import' | 'export';
    handle: MiniAppFileHandle;
}>;

/**
 * Narrowly rejects a file-handler mount so the host may try another handler.
 * Other mount failures remain ordinary package failures and must not trigger
 * fallback.
 */
export declare class TapFederatedSurfaceUserFileLaunchUnsupportedError extends Error {
    readonly reason: TapFederatedSurfaceUserFileLaunchUnsupportedReason;
    readonly code: 'file_unsupported';
    constructor(reason: TapFederatedSurfaceUserFileLaunchUnsupportedReason, message?: string);
}

export declare type TapFederatedSurfaceUserFileLaunchUnsupportedReason = 'unsupported-version' | 'newer-version';

/** Declared package-event channel supplied to an isolated UI contribution. */
export declare interface TapPackageEventPublisher {
    publish(name: string, payload: Readonly<Record<string, unknown>>): void | Promise<void>;
    subscribe(name: string, listener: (payload: unknown, envelope: Readonly<Record<string, unknown>>) => void | Promise<void>): () => void;
}

export { }