/**
 * Public miniapp API installed by the host. Importing this value is safe in
 * build tools and tests; an unsupported-environment error is raised only when a
 * property is read before the host installs the API.
 */
export declare const app: MiniAppPlatformApi;

export declare function applyMiniAppTheme(theme: MiniAppTheme): void;

export declare function applyMiniAppUiScale(scale: MiniAppUiScale): void;

declare type CreateChannelOptions = {
    workspaceId?: string;
    name: string;
    description?: string;
    projectId?: string | null;
    visibility?: string;
};

declare type CreateChannelResult = {
    roomId: string;
};

declare type CreateProjectOptions = {
    workspaceId?: string;
    id?: string;
    name: string;
    discoverable?: boolean;
};

declare type CreateProjectResult = {
    projectId: string;
};

declare type CreateTaskOptions = {
    workspaceId?: string;
    title: string;
    description?: string;
    status?: MiniAppTaskStatus;
    priority?: MiniAppTaskPriority;
    assignees?: MiniAppTaskAssignee[];
    channelIds?: string[];
    dueDate?: number;
};

declare type CreateTaskResult = {
    task: MiniAppTask;
};

declare type DeleteTaskOptions = {
    workspaceId?: string;
    taskId: string;
};

/** Delete is a soft archive in the tasks silo. */
declare type DeleteTaskResult = {
    taskId: string;
    archived: true;
};

declare type DeleteUserFileRequest = {
    handle: MiniappUserFileHandle;
    expectedRevision: string;
};

declare type GetChannelAccessOptions = {
    workspaceId?: string;
    channelId: string;
};

declare type GetChannelAccessResult = {
    archived: boolean;
    capabilities: string[];
    isParticipant: boolean;
    /**
     * Last timeline sequence retained for a former participant. When present,
     * the channel remains readable through this sequence even though
     * `isParticipant` is false.
     */
    visibleUntilSequence?: number | null;
};

declare type GetChannelTimelineOptions = {
    workspaceId?: string;
    channelId: string;
};

declare type GetChannelTimelineResult = {
    timeline: {
        messages: MiniAppChannelMessage[];
        sequence: number;
    };
};

export declare function getMiniAppThemeFromSearch(search?: string | URLSearchParams): MiniAppTheme;

export declare function getMiniAppUiScaleFromSearch(search?: string | URLSearchParams): MiniAppUiScale;

/** Returns the public miniapp API proxy, which fails only when it is used. */
export declare function getPlatform(): MiniAppPlatform;

declare type GetProjectOptions = {
    workspaceId?: string;
    projectId: string;
};

declare type GetProjectResult = {
    project: MiniAppProject | null;
};

declare type GetWorkflowRunOptions = {
    workspaceId?: string;
    runId: string;
};

declare type GetWorkflowRunResult = {
    run: MiniAppWorkflowRun | null;
};

/** Synchronizes both theme and UI scale from the exact parent miniapp host. */
export declare function installMiniAppAppearanceSync({ applyTheme, applyUiScale, search, }?: InstallMiniAppAppearanceSyncOptions): () => void;

export declare type InstallMiniAppAppearanceSyncOptions = InstallMiniAppThemeSyncOptions & {
    applyUiScale?: (scale: MiniAppUiScale) => void;
};

export declare function installMiniAppThemeSync({ applyTheme, search, }?: InstallMiniAppThemeSyncOptions): () => void;

export declare type InstallMiniAppThemeSyncOptions = {
    applyTheme?: (theme: MiniAppTheme) => void;
    search?: string | URLSearchParams;
};

declare type InvokeSavedWorkflowOptions<TPayload = unknown> = {
    workflowId: string;
    payload?: TPayload;
    /**
     * Correlates the resulting run with the canonical plot revision that asked
     * for it. The host stamps this onto the observable run record.
     */
    correlation?: {
        plotId?: string;
        expectedSourceRevision?: string;
    };
};

declare type InvokeWorkflowOptions<TPayload = unknown> = {
    workflowJson: string;
    payload?: TPayload;
};

declare type InvokeWorkflowResult = {
    success: boolean;
    status: string;
    message: string;
    runId?: string | null;
    error?: string | null;
};

/**
 * Fail-closed check that a candidate slot value is a real host surface.
 *
 * Every member the type makes required is validated, not a sample: a stale
 * or partial host must be rejected here rather than surfaced as a value the
 * SDK claims is complete.
 */
export declare function isMiniappHostSurface(value: unknown): value is MiniappHostSurface;

declare type ListChannelsOptions = {
    workspaceId?: string;
};

declare type ListChannelsResult = {
    rooms: MiniAppChannel[];
    readMode: string;
};

declare type ListTasksOptions = {
    workspaceId?: string;
    includeArchived?: boolean;
    /** Page size. Defaults to 25 and must be between 1 and 50. */
    limit?: number;
    /** Opaque continuation from the preceding page. */
    cursor?: string;
};

declare type ListTasksResult = {
    tasks: MiniAppTask[];
    /** Opaque continuation when more tasks are available. */
    nextCursor?: string;
};

declare type ListWorkflowsOptions = {
    workspaceId?: string;
};

declare type ListWorkflowsResult = {
    workflows: MiniAppWorkflow[];
};

/**
 * Host-mediated elicitation available only while a package MCP tool executes.
 * Each tool invocation may request at most one elicitation.
 */
declare type McpElicitationApi = {
    elicit(request: McpElicitationRequest): MiniAppMaybePromise<McpElicitationResult>;
};

/** Closed flat-object schema supported by package MCP elicitation forms. */
declare type McpElicitationFormSchema = {
    type: 'object';
    title?: string;
    description?: string;
    properties: Record<string, McpElicitationPropertySchema>;
    required?: readonly string[];
};

declare type McpElicitationPropertyBase<TType extends string, TDefault> = {
    type: TType;
    title?: string;
    description?: string;
    default?: TDefault;
};

/** One primitive field the trusted host can render in an elicitation form. */
declare type McpElicitationPropertySchema = (McpElicitationPropertyBase<'string', string> & {
    enum?: readonly string[];
    minLength?: number;
    maxLength?: number;
    pattern?: string;
    format?: 'email';
}) | (McpElicitationPropertyBase<'number' | 'integer', number> & {
    minimum?: number;
    maximum?: number;
}) | McpElicitationPropertyBase<'boolean', boolean>;

/** One host-mediated elicitation initiated by a package-runtime MCP tool. */
declare type McpElicitationRequest = {
    mode: 'form';
    message: string;
    requestedSchema: McpElicitationFormSchema;
} | {
    mode: 'url';
    message: string;
    url: string;
    elicitationId: string;
};

/** The user's decision for one package-runtime MCP elicitation. */
declare type McpElicitationResult = {
    action: 'accept' | 'cancel' | 'decline';
    content?: Record<string, MiniAppJsonValue>;
};

/** Stable host-injected surface slot, read only inside a miniapp realm. */
export declare const MINIAPP_HOST_SURFACE_GLOBAL_KEY = "tap.platform-provider.v1";

export declare const MINIAPP_UI_SCALE_DEFAULT = 16;

export declare const MINIAPP_UI_SCALE_MAX = 20;

export declare const MINIAPP_UI_SCALE_MIN = 12;

/** Durable outcome of one narrow host action, recoverable after interruption. */
declare type MiniAppActionReceipt = {
    receiptId: string;
    /** Caller-supplied stable key; replaying it returns the same receipt. */
    idempotencyKey: string;
    /** Stable host action vocabulary, for example `tasks.create-with-receipt`. */
    action: string;
    status: 'completed' | 'duplicate-suppressed' | 'pending' | 'failed';
    workspaceId: string;
    /** Host-stamped actor identity; never package-supplied. */
    actorUserId: string;
    createdAt: number;
    /** Action-specific outcome, for example `{ taskId }` or `{ issueUrl }`. */
    result: MiniAppJsonValue | null;
    error: string | null;
};

/** 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;
};

declare type MiniAppArtifactsApi = {
    resolve(options: {
        readonly reference: MiniAppArtifactReference;
    }): MiniAppMaybePromise<{
        readonly artifact: MiniAppResolvedArtifact | null;
    }>;
};

declare type MiniAppAttentionItem = {
    /** Package-scoped stable id; republishing the same id replaces it. */
    id: string;
    kind: MiniAppAttentionKind;
    title: string;
    summary?: string;
    /** Miniapp-relative navigation path Home deep-links into. */
    deepLink: string;
    /** Narrows host assignment filtering when present. */
    assigneeUserId?: string;
};

/**
 * Normalized attention kinds the Home surface renders natively. Packages
 * publish bounded data and a deep link; arbitrary package HTML never mounts
 * on Home.
 */
declare type MiniAppAttentionKind = 'approval' | 'assignment' | 'reassessment' | 'failure';

declare type MiniAppAuthApi = {
    getUserProfile(): MiniAppMaybePromise<MiniAppUserProfile | null>;
};

/**
 * Read-only authorization introspection for custom surface behavior.
 *
 * The host rejects action IDs that are not declared by the exact mounted
 * surface. A declared action resolves to the current dynamic allow/deny
 * decision without executing the action.
 */
declare type MiniAppAuthorizationApi = {
    check(options: MiniAppAuthorizationCheckOptions): Promise<MiniAppAuthorizationCheckResult>;
};

/** Canonical autonomy requested for one descriptor-declared package action. */
declare type MiniAppAuthorizationAutonomy = 'listen' | 'plan' | 'do';

declare type MiniAppAuthorizationCheckOptions = {
    actionId: string;
    autonomy: MiniAppAuthorizationAutonomy;
};

declare type MiniAppAuthorizationCheckResult = {
    allowed: boolean;
};

declare type MiniAppChannel = {
    roomId: string;
    title?: string;
    kind?: string;
    description?: string;
    visibility: string;
    archived: boolean;
    projectId?: string;
    createdAt: number;
    updatedAt: number;
};

/**
 * One bounded JSON timeline row. The row schema is host-versioned, so callers
 * must narrow it before reading fields.
 */
declare type MiniAppChannelMessage = MiniAppJsonValue;

declare type MiniAppChatApi = {
    /**
     * Select the miniapp's active conversation, reveal the shared chat panel,
     * and place text in its composer without unmounting the miniapp surface.
     */
    sendTextToChat(text: string): MiniAppMaybePromise<void>;
    /**
     * Stage a host-rendered link to one of this installed package's resources in
     * the active chat composer. Optional so packages can feature-detect hosts
     * released before package-owned deep links were introduced.
     */
    stageDeepLink?(options: MiniAppStageDeepLinkOptions): MiniAppMaybePromise<void>;
    /**
     * Stage a package-owned deep link and return the opaque handle required to
     * compensate if a later operation in the same package flow fails.
     */
    stageDeepLinkWithRollback?(options: MiniAppStageDeepLinkOptions): MiniAppMaybePromise<MiniAppStagedDeepLink>;
    /**
     * Roll back one link staged by this exact package surface. Hosts reject
     * unknown handles and handles owned by another package surface.
     */
    unstageDeepLink?(staged: MiniAppStagedDeepLink): MiniAppMaybePromise<void>;
    archiveConversation?(workspaceId: string, userId: string, conversationId: string, projectId: string): MiniAppMaybePromise<null>;
};

/**
 * Read-only repository-scoped Code Knowledge Graph capability. Payloads are
 * bounded host-versioned JSON the caller narrows; every result carries a
 * {@link MiniAppCodeIntelProvenance} envelope.
 */
declare type MiniAppCodeIntelApi = {
    getIndexStatus(options: MiniAppCodeIntelScope): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        status: MiniAppJsonValue;
    }>;
    /** Semantic and intent search over the indexed graph. */
    search(options: MiniAppCodeIntelScope & {
        query: string;
        mode?: 'semantic' | 'intent' | 'hybrid';
        limit?: number;
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        results: MiniAppJsonValue[];
    }>;
    listCommunities(options: MiniAppCodeIntelScope): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        communities: MiniAppJsonValue[];
    }>;
    getCommunity(options: MiniAppCodeIntelScope & {
        communityId: string;
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        community: MiniAppJsonValue | null;
    }>;
    listProcesses(options: MiniAppCodeIntelScope): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        processes: MiniAppJsonValue[];
    }>;
    getProcess(options: MiniAppCodeIntelScope & {
        processId: string;
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        process: MiniAppJsonValue | null;
    }>;
    /** Exact branch diff against the indexed repository revision. */
    getBranchDiff(options: MiniAppCodeIntelScope & {
        baseRef: string;
        headRef: string;
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        diff: MiniAppJsonValue;
    }>;
    /** Callers/impact closure for the given symbols or files. */
    getImpactAnalysis(options: MiniAppCodeIntelScope & {
        symbolIds?: string[];
        paths?: string[];
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        /** One impact closure per distinct requested symbol or path. */
        impact: MiniAppJsonValue[];
    }>;
    getCoverage(options: MiniAppCodeIntelScope & {
        paths?: string[];
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        coverage: MiniAppJsonValue;
    }>;
    getFragility(options: MiniAppCodeIntelScope & {
        paths?: string[];
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        fragility: MiniAppJsonValue;
    }>;
    /** History and evolution for one stable graph symbol. */
    getHistory(options: MiniAppCodeIntelScope & {
        symbolId: string;
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        history: MiniAppJsonValue;
    }>;
    /** Workspace specialists with declared affinity for the given symbols. */
    getSpecialistAffinities(options: MiniAppCodeIntelScope & {
        symbolIds: string[];
    }): MiniAppMaybePromise<{
        provenance: MiniAppCodeIntelProvenance;
        affinities: MiniAppJsonValue[];
    }>;
};

/**
 * Revision-bound provenance attached to every Code Knowledge Graph result.
 * Consumers must be able to explain which graph build and source commit an
 * answer came from.
 */
declare type MiniAppCodeIntelProvenance = {
    projectId: string;
    /** Immutable graph build revision, when the index has produced one. */
    graphBuildRevision: string | null;
    /** Source commit the graph build was produced from, when applicable. */
    sourceCommit: string | null;
    /** Host-estimated confidence in the result, from 0 to 1. */
    confidence: number | null;
};

/**
 * Repository/project scope for Code Knowledge Graph operations. Callers pass
 * host-resolved project references — never arbitrary local filesystem paths.
 */
declare type MiniAppCodeIntelScope = {
    workspaceId?: string;
    projectId: string;
};

declare type MiniAppCreateSpecialistOptions = {
    name: string;
    domain: string;
    description: string | null;
    configuration: MiniAppJsonValue;
};

declare type MiniAppCreateSpecialistResult = {
    id: string;
    name: string;
    domain: string;
    description: string | null;
    isActive: boolean;
};

/** Metadata-only access to host-managed credentials in the active workspace. */
declare type MiniAppCredentialsApi = {
    listHttp(): MiniAppMaybePromise<MiniAppHttpCredentialMetadata[]>;
};

declare type MiniAppDeepLinkOpenRequest = Readonly<{
    requestId: string;
    target: MiniAppDeepLinkTarget;
}>;

/**
 * Package-owned locator for a resource that the host can persist and later
 * return to the same installed package. The host derives package, release,
 * installation, and surface provenance from the calling frame.
 */
declare type MiniAppDeepLinkTarget = Readonly<{
    kind: string;
    [key: string]: MiniAppJsonValue;
}>;

declare type MiniAppEmbeddingInput = {
    kind: 'text';
    text: string;
};

declare type MiniAppEmbeddingModality = 'text';

declare type MiniAppEmbeddingModel = Readonly<{
    id: string;
    displayName: string;
    description: string;
    source: 'platform' | 'hugging-face';
    revision: string;
    availability: 'installed' | 'downloadable' | 'gated';
    capabilities: MiniAppEmbeddingModelCapabilities;
    estimatedDownloadBytes: number | null;
    estimatedMemoryBytes: number | null;
    license: string | null;
    licenseUrl: string | null;
    gated: boolean;
}>;

declare type MiniAppEmbeddingModelCapabilities = Readonly<{
    modalities: readonly MiniAppEmbeddingModality[];
    dimensions: number;
    maxInputs: number;
    maxInputTokens: number | null;
    maxInputBytes: number | null;
    roles: readonly ('query' | 'document')[];
    normalization: 'l2' | 'none';
    supportsBackground: boolean;
}>;

declare type MiniAppEmbeddingRecommendation = Readonly<{
    model: MiniAppEmbeddingModel;
    score: number;
    reasons: readonly string[];
}>;

declare type MiniAppEmbeddingsApi = {
    listModels(): MiniAppMaybePromise<readonly MiniAppEmbeddingModel[]>;
    recommend(options: {
        modality: MiniAppEmbeddingModality;
        locality?: 'local-only' | 'local-preferred' | 'remote-allowed';
        dimensions?: number;
        background?: boolean;
    }): MiniAppMaybePromise<readonly MiniAppEmbeddingRecommendation[]>;
    embed(options: {
        model: string;
        revision: string;
        inputs: readonly MiniAppEmbeddingInput[];
        role: 'query' | 'document';
    }): MiniAppMaybePromise<{
        vectors: readonly MiniAppEmbeddingVector[];
        binding: MiniAppEmbeddingSpaceBinding;
    }>;
};

declare type MiniAppEmbeddingSpaceBinding = Readonly<{
    /** Stable host catalog coordinate, or the package's custom coordinate. */
    model: string;
    /** Immutable upstream or package-selected model revision. */
    revision: string;
    dimensions: number;
    /** Digest of model artifacts, tokenizer/preprocessor, role handling, pooling, and normalization. */
    fingerprint: string;
    provenance: 'host-verified' | 'custom-unverified';
}>;

declare type MiniAppEmbeddingVector = Readonly<{
    values: readonly number[];
    binding: MiniAppEmbeddingSpaceBinding;
    /** Opaque host authentication required when `binding.provenance` is `host-verified`. */
    attestation?: string;
}>;

declare type MiniAppFileDeleteOptions = Readonly<Pick<DeleteUserFileRequest, 'expectedRevision'> & {
    signal?: AbortSignal;
}>;

declare type MiniAppFileDeleteReceipt = Readonly<Omit<MiniappUserFileDeleteReceipt, 'deletedAt'> & {
    deletedAt: 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 MiniAppFileMetadata = Readonly<Omit<MiniappUserFileMetadata, 'handle' | 'mimeType' | 'extension' | 'contentHash' | 'modifiedAt'> & {
    /** Host-issued handle pinned to `revision`; use it for subsequent reads. */
    handle: MiniAppFileHandle;
    mimeType: NonNullable<MiniappUserFileMetadata['mimeType']> | null;
    extension: NonNullable<MiniappUserFileMetadata['extension']> | null;
    contentHash: NonNullable<MiniappUserFileMetadata['contentHash']> | null;
    modifiedAt: number | null;
}>;

declare type MiniAppFilePickOpenOptions = Readonly<{
    /** Lowercase, parameterless MIME types or dot-prefixed extensions. */
    accept?: readonly string[];
    multiple?: boolean;
    recoverable?: boolean;
}>;

declare type MiniAppFilePickSaveOptions = Readonly<{
    suggestedName: string;
    mimeType?: string | null;
    recoverable?: boolean;
}>;

declare type MiniAppFileReadOptions = Readonly<{
    /** Reject instead of returning more than this many bytes. Defaults to 16 MiB. */
    maxBytes?: number;
    signal?: AbortSignal;
}>;

declare type MiniAppFileReadRangeOptions = Readonly<{
    signal?: AbortSignal;
}>;

declare type MiniAppFileReadStreamOptions = Readonly<{
    /** Requested range size, from 1 byte through 1 MiB. Defaults to 256 KiB. */
    chunkBytes?: number;
    signal?: AbortSignal;
}>;

declare type MiniAppFileRenameOptions = Readonly<Pick<RenameUserFileRequest, 'expectedRevision' | 'newName'> & {
    signal?: AbortSignal;
}>;

declare type MiniAppFileRenameReceipt = Readonly<Omit<MiniappUserFileRenameReceipt, 'handle' | 'renamedAt'> & {
    handle: MiniAppFileHandle;
    renamedAt: number;
}>;

/**
 * Desktop-only, host-mediated access to explicit user-selected files.
 *
 * This is intentionally separate from the package VFS: callers exchange only
 * opaque handles and never receive or submit native paths.
 */
declare type MiniAppFilesApi = {
    pickOpen(options?: MiniAppFilePickOpenOptions): MiniAppMaybePromise<readonly MiniAppFileHandle[]>;
    pickSave(options: MiniAppFilePickSaveOptions): MiniAppMaybePromise<MiniAppFileHandle>;
    metadata(handle: MiniAppFileHandle): MiniAppMaybePromise<MiniAppFileMetadata>;
    read(handle: MiniAppFileHandle, options?: MiniAppFileReadOptions): MiniAppMaybePromise<Uint8Array>;
    readRange(handle: MiniAppFileHandle, offset: number, length: number, options?: MiniAppFileReadRangeOptions): MiniAppMaybePromise<Uint8Array>;
    createReadStream(handle: MiniAppFileHandle, options?: MiniAppFileReadStreamOptions): ReadableStream<Uint8Array>;
    write(handle: MiniAppFileHandle, data: Uint8Array, options: MiniAppFileWriteOptions): MiniAppMaybePromise<MiniAppFileWriteReceipt>;
    createWriteStream(handle: MiniAppFileHandle, options: MiniAppFileWriteStreamOptions): Promise<MiniAppFileWriteStream>;
    rename(handle: MiniAppFileHandle, options: MiniAppFileRenameOptions): MiniAppMaybePromise<MiniAppFileRenameReceipt>;
    delete(handle: MiniAppFileHandle, options: MiniAppFileDeleteOptions): MiniAppMaybePromise<MiniAppFileDeleteReceipt>;
    /** Performs one bounded long poll for a revision change. */
    watch(handle: MiniAppFileHandle, options: MiniAppFileWatchOptions): MiniAppMaybePromise<MiniAppFileWatchReceipt>;
    revoke(handle: MiniAppFileHandle): MiniAppMaybePromise<null>;
    recover(handle: MiniAppFileHandle): MiniAppMaybePromise<MiniAppFileHandle>;
};

declare type MiniAppFileWatchOptions = Readonly<Pick<WatchUserFileRequest, 'previousRevision' | 'waitMs'> & {
    signal?: AbortSignal;
}>;

declare type MiniAppFileWatchReceipt = Readonly<Omit<MiniappUserFileWatchReceipt, 'handle' | 'observedAt'> & {
    /** Host-issued handle pinned to the observed `revision`. */
    handle: MiniAppFileHandle;
    observedAt: number;
}>;

declare type MiniAppFileWriteOptions = Readonly<{
    /** Revision explicitly observed before starting this atomic write. */
    expectedRevision: string;
    /** Caller-owned retry key for this logical write, bounded to 256 UTF-8 bytes. */
    idempotencyKey: string;
    /** Cancels staging before commit starts; an in-flight commit remains authoritative. */
    signal?: AbortSignal;
}>;

declare type MiniAppFileWriteReceipt = Readonly<Omit<MiniappUserFileWriteReceipt, 'handle' | 'committedAt'> & {
    handle: MiniAppFileHandle;
    committedAt: number;
}>;

declare type MiniAppFileWriteStream = Readonly<{
    writable: WritableStream<Uint8Array>;
    /** Resolves only after close commits the atomic write. */
    receipt: Promise<MiniAppFileWriteReceipt>;
}>;

declare type MiniAppFileWriteStreamOptions = MiniAppFileWriteOptions & Readonly<{
    /** Maximum accepted chunk size. Defaults to 256 KiB. */
    chunkBytes?: number;
}>;

/**
 * Home attention projections. Published items are revision-bound to the
 * canonical plot state they were derived from; the host owns rendering,
 * sorting, authorization, assignment filtering, and stale-projection
 * cleanup.
 */
declare type MiniAppHomeApi = {
    /** Atomically replaces the package's projection for one source revision. */
    publishAttention(options: {
        /** Canonical source the items were derived from, typically a plot id. */
        sourceId: string;
        sourceRevision: string;
        items: MiniAppAttentionItem[];
    }): MiniAppMaybePromise<{
        published: number;
    }>;
    clearAttention(options: {
        sourceId: string;
    }): MiniAppMaybePromise<void>;
};

/** The chat operations a host injects — the shared composer is not one. */
export declare type MiniappHostChatApi = Required<Pick<MiniAppChatApi, 'archiveConversation'>>;

export declare interface MiniappHostSurface {
    readonly hasBrowserView: boolean;
    readonly hasUpdater: boolean;
    readonly hasEditorView: boolean;
    readonly hasHostHttpRequest: boolean;
    readonly hasQRCodeProvider: boolean;
    readonly hasQRCodeScanner: boolean;
    readonly auth: MiniAppAuthApi;
    readonly vfs: MiniAppVfsApi;
    readonly inference?: MiniAppInferenceApi;
    readonly specialist: Required<MiniAppSpecialistApi>;
    readonly chat: MiniappHostChatApi;
}

/** Host-mediated bounded HTTP(S); browser fetch is not the authority. */
declare type MiniAppHttpApi = {
    request(input: MiniAppHttpRequestInput, options?: MiniAppHttpRequestOptions): MiniAppMaybePromise<MiniAppHttpResponse>;
};

/** Metadata-only stored HTTP credential. Secret fields never cross IPC. */
declare type MiniAppHttpCredentialMetadata = {
    id: string;
    credentialType: MiniAppHttpCredentialType;
    displayName: string;
    metadataFields: Record<string, string>;
};

declare type MiniAppHttpCredentialType = 'http_bearer' | 'http_basic' | 'http_header_auth' | 'http_api_key';

declare type MiniAppHttpHeader = {
    name: string;
    value: string;
};

declare type MiniAppHttpHeaderInput = {
    name: string;
    value: string;
    /** Defaults to true when omitted. */
    enabled?: boolean;
};

declare type MiniAppHttpQueryInput = {
    name: string;
    value: string;
    /** Defaults to true when omitted. */
    enabled?: boolean;
};

declare type MiniAppHttpRequestInput = {
    method: string;
    url: string;
    query?: MiniAppHttpQueryInput[];
    headers?: MiniAppHttpHeaderInput[];
    body?: string | null;
    /** Defaults to 30 seconds and is capped by the host at 120 seconds. */
    timeoutMs?: number | null;
    /** Defaults to 5 MiB and is capped by the host at 10 MiB. */
    responseBodyLimitBytes?: number | null;
    /**
     * Defaults to false. The host follows at most ten same-origin redirects;
     * cross-origin redirects require a separate request and grant.
     */
    followRedirects?: boolean | null;
};

declare type MiniAppHttpRequestOptions = {
    /**
     * Opaque host-managed credential reference, or the reserved
     * `platform-session` reference for the active TAP account. Secret material
     * never enters miniapp JavaScript.
     */
    credentialRef?: string;
    /**
     * Requests one host-managed integration credential. The host attaches it
     * only after the package declares and receives the corresponding credential
     * permission; secret material never enters miniapp JavaScript.
     */
    auth?: 'github';
};

declare type MiniAppHttpResponse = {
    finalUrl: string;
    status: number;
    statusText: string;
    /** Ordered entries; duplicate response header names remain separate. */
    headers: MiniAppHttpHeader[];
    bodyText: string | null;
    bodyBase64: string | null;
    bodyKind: 'text' | 'binary';
    bodyTruncated: boolean;
    sizeBytes: number;
    elapsedMs: number;
    contentType: string | null;
};

/**
 * Low-level isolated generation for comparisons and evaluation. Prefer a
 * specialist when the app needs tools, durable context, or product behavior.
 */
declare type MiniAppInferenceApi = {
    listModels(): MiniAppMaybePromise<MiniAppInferenceModel[]>;
    send(request: MiniAppInferenceRequest): MiniAppMaybePromise<MiniAppInferenceResult>;
};

declare type MiniAppInferenceMessage = {
    role: 'system' | 'user' | 'assistant';
    content: string;
};

declare type MiniAppInferenceModel = {
    canonicalName: string;
    displayName: string;
    description: string | null;
    providerIds: string[];
    contextLength: number | null;
    maxOutputTokens: number | null;
};

declare type MiniAppInferenceRequest = {
    /** Conversation that owns the user action and any later VFS writes. */
    conversationId: string;
    model: string;
    messages: MiniAppInferenceMessage[];
    temperature?: number;
    /** Defaults to 4,096 and is capped by the host at 16,384. */
    maxTokens?: number;
    /** Defaults to 120 seconds and is capped by the host at five minutes. */
    timeoutMs?: number;
};

declare type MiniAppInferenceResult = {
    turnId: string;
    text: string;
    finishReason: string;
    modelUsed: string;
    providerUsed: string;
    generationId: string | null;
    usage: MiniAppInferenceUsage;
    latencyMs: number;
    /** Null for the current unary transport. */
    ttftMs: number | null;
    zdrApplied: boolean;
    managed: boolean;
};

declare type MiniAppInferenceUsage = {
    inputTokens: number | null;
    outputTokens: number | null;
    totalTokens: number | null;
    reasoningTokens: number | null;
    cacheReadTokens: number | null;
    cacheWriteTokens: number | null;
    costUsd: number | null;
};

/**
 * Typed actions against connected external integrations. Provider tokens
 * remain host-owned; packages reference a connected repository by its
 * host-resolved id.
 */
declare type MiniAppIntegrationsApi = {
    createRepositoryIssue(options: {
        workspaceId?: string;
        repositoryId: string;
        title: string;
        body?: string;
        idempotencyKey: string;
    }): MiniAppMaybePromise<{
        receipt: MiniAppActionReceipt;
    }>;
    linkRepositoryIssue(options: {
        workspaceId?: string;
        repositoryId: string;
        issueUrl: string;
        target: MiniAppArtifactReference;
        idempotencyKey: string;
    }): MiniAppMaybePromise<{
        receipt: MiniAppActionReceipt;
    }>;
};

/** JSON-compatible values accepted by public miniapp operations. */
declare type MiniAppJsonValue = null | boolean | number | string | MiniAppJsonValue[] | {
    [key: string]: MiniAppJsonValue;
};

/**
 * Namespaced local-service failures, including codes introduced by newer hosts.
 */
declare type MiniAppLocalServiceErrorCode = `local_service.${string}`;

/** Exact ready snapshot for one manifest-declared local service generation. */
declare type MiniAppLocalServiceRunning = {
    contributionId: string;
    /** Opaque host-generated identity that changes whenever the service restarts. */
    generation: string;
    endpoint: {
        /** Exact `http://127.0.0.1:<host-selected-port>` origin. */
        origin: string;
    };
};

/** Read-only state for one manifest-declared local service. */
declare type MiniAppLocalServiceStatus = {
    state: 'unavailable';
    code: MiniAppLocalServiceErrorCode;
} | {
    state: 'stopped';
} | {
    state: 'installing';
    /** Opaque host-generated operation identity. */
    operationId: string;
} | {
    state: 'starting';
    /** Opaque host-generated operation identity. */
    operationId: string;
} | ({
    state: 'running';
} & MiniAppLocalServiceRunning) | {
    state: 'failed';
    code: MiniAppLocalServiceErrorCode;
    retryable: boolean;
    retryAfterMs: number | null;
};

/**
 * Author-controlled manifest accepted by the host-managed specialist
 * persistence operation. Ownership, visibility, installation, and verification
 * metadata are derived by the host and cannot be supplied by a miniapp.
 */
declare type MiniAppManagedSpecialist = {
    id: string;
    slug: string;
    name: string;
    publisher: string;
    description: string;
    icon: string;
    category?: string;
    categoryDisplayName?: string;
    version?: string;
    schemaVersion?: string;
    displayName?: string;
    maintainers?: Array<{
        name: string;
        email: string;
        url?: string;
    }>;
    license?: string;
    lastUpdated?: string;
    fullDescription?: string;
    knowledgeSources?: MiniAppJsonValue[];
    ownedKnowledgePlotId?: string;
    links?: {
        terms?: string;
        privacy?: string;
        website?: string;
    };
    systemPrompt?: string;
    prompts?: MiniAppJsonValue;
    skills?: string[];
    tooling?: MiniAppJsonValue;
    orchestration?: MiniAppJsonValue;
    taskModels?: Record<string, string>;
    knowledgeTargeting?: MiniAppJsonValue;
    tasks?: MiniAppJsonValue[];
    identity?: MiniAppJsonValue;
    audience?: MiniAppJsonValue;
    constraints?: MiniAppJsonValue;
    domainContext?: MiniAppJsonValue;
    purpose?: string;
    values?: MiniAppJsonValue[];
    attributes?: string[];
    techStack?: string[];
    writingStyle?: MiniAppJsonValue;
    tags?: string[];
    /**
     * Legacy singular spelling of the specialist default model. Honored by
     * the host as `preferredModels: [preferredModel]`; prefer `preferredModels`
     * for the ordered plural form the manifest consumes. When both are
     * present, `preferredModels` wins.
     */
    preferredModel?: string;
    /** Ordered soft model preferences for the specialist's default lane. */
    preferredModels?: string[];
    supportsLocal?: boolean;
    requiresNetwork?: boolean;
    knowledgeGardens?: string[];
};

declare type MiniAppManagedSpecialistResult = {
    specialistId: string;
};

declare type MiniAppMaybePromise<T> = T | Promise<T>;

/** Package-runtime MCP execution metadata stamped by the host. */
declare type MiniAppMcpApi = McpElicitationApi & {
    getExecutionContext(): MiniAppMcpExecutionContext;
};

/** Trusted identity available only while a package-runtime MCP tool executes. */
declare type MiniAppMcpExecutionContext = {
    /** Trusted channel scope for this call, or null for workspace/user-scoped execution. */
    channelId: string | null;
    userId: string | null;
};

/** Outcome of one host-mediated OS notification presentation attempt. */
declare type MiniAppNotificationResult = {
    disposition: 'shown';
} | {
    disposition: 'suppressed';
    reason: 'notifications-disabled' | 'permission-denied' | 'rate-limited';
};

/**
 * Host-mediated OS notifications attributed to the exact mounted miniapp.
 *
 * Package code supplies only the message. The host owns the application name
 * and all native presentation metadata.
 */
declare type MiniAppNotificationsApi = {
    show(options: {
        message: string;
    }): MiniAppMaybePromise<MiniAppNotificationResult>;
};

/** Browser view of the public miniapp API. */
export declare type MiniAppPlatform = MiniAppPlatformApi;

export declare type MiniAppPlatformApi = {
    channels: {
        create(options: CreateChannelOptions): CreateChannelResult | Promise<CreateChannelResult>;
        list(options?: ListChannelsOptions): ListChannelsResult | Promise<ListChannelsResult>;
        sendMessage(options: SendChannelMessageOptions): SendChannelMessageResult | Promise<SendChannelMessageResult>;
        getAccess(options: GetChannelAccessOptions): GetChannelAccessResult | Promise<GetChannelAccessResult>;
        getTimeline(options: GetChannelTimelineOptions): GetChannelTimelineResult | Promise<GetChannelTimelineResult>;
    };
    projects: {
        create(options: CreateProjectOptions): CreateProjectResult | Promise<CreateProjectResult>;
        get(options: GetProjectOptions): GetProjectResult | Promise<GetProjectResult>;
        update(options: UpdateProjectOptions): UpdateProjectResult | Promise<UpdateProjectResult>;
    };
    workflows: {
        list(options?: ListWorkflowsOptions): ListWorkflowsResult | Promise<ListWorkflowsResult>;
        invokeSaved<TPayload = unknown>(options: InvokeSavedWorkflowOptions<TPayload>): InvokeWorkflowResult | Promise<InvokeWorkflowResult>;
        invoke?<TPayload = unknown>(options: InvokeWorkflowOptions<TPayload>): InvokeWorkflowResult | Promise<InvokeWorkflowResult>;
        /**
         * Observe one workflow transition run. Runs are short-lived, idempotent,
         * revision-aware executors; canonical lifecycle state stays in the plot.
         */
        getRun?(options: GetWorkflowRunOptions): GetWorkflowRunResult | Promise<GetWorkflowRunResult>;
        /**
         * Subscribe to run state changes until the returned unsubscribe function
         * is called. The listener observes the initial state and every later
         * transition the host reports.
         */
        subscribeRun?(options: {
            workspaceId?: string;
            runId: string;
        }, listener: (event: MiniAppWorkflowRunEvent) => void): (() => void) | Promise<() => void>;
    };
    navigation: {
        open(options: OpenNavigationOptions): void | Promise<void>;
        /** Desktop-only system-browser navigation. Feature-detect before use. */
        openExternal?(options: OpenExternalNavigationOptions): void | Promise<void>;
        /** Receive opaque links addressed to this exact mounted package release. */
        subscribeDeepLinks?(listener: (request: MiniAppDeepLinkOpenRequest) => MiniAppMaybePromise<void>): () => void;
    };
    authorization: MiniAppAuthorizationApi;
    chat: MiniAppChatApi;
    storage: MiniAppStorageApi;
    /** Available only in a host-managed package-runtime MCP execution realm. */
    mcp?: MiniAppMcpApi;
    session: MiniAppSessionApi;
    presence: MiniAppPresenceApi;
    /** Desktop host capability; feature-detect before use on portable targets. */
    http?: MiniAppHttpApi;
    /** Desktop host capability; feature-detect before use on portable targets. */
    credentials?: MiniAppCredentialsApi;
    /** Desktop host capability; feature-detect before use on portable targets. */
    printing?: MiniAppReceiptPrintingApi;
    /** Desktop host capability; feature-detect before opening a terminal. */
    terminal?: MiniAppTerminalApi;
    /** Desktop host capability; launch details remain owned by the signed manifest. */
    services?: MiniAppServicesApi;
    /** Desktop and mobile host capability; feature-detect for older hosts. */
    notifications?: MiniAppNotificationsApi;
    /** Workspace task CRUD and receipt-backed creation via the host tasks silo. */
    tasks?: MiniAppTasksApi;
    /** Browser capabilities appear only when the selected target supports them. */
    auth?: MiniAppAuthApi;
    vfs?: MiniAppVfsApi;
    /** Desktop host capability for explicit user-selected files. */
    files?: MiniAppFilesApi;
    /** Permissioned low-level generation; feature-detect for older hosts. */
    inference?: MiniAppInferenceApi;
    /** Permissioned native embedding acceleration; feature-detect for older hosts. */
    embeddings?: MiniAppEmbeddingsApi;
    specialist?: MiniAppSpecialistApi;
    /** Reserved plot contract; the current host does not install it. */
    plots?: MiniAppPlotsApi;
    /** Desktop artifact-resolution capability; feature-detect before use. */
    artifacts?: MiniAppArtifactsApi;
    /** Reserved Home-projection contract; the current host does not install it. */
    home?: MiniAppHomeApi;
    /** Read-only repository-scoped Code Knowledge Graph capability. */
    codeIntel?: MiniAppCodeIntelApi;
    /** Read-only retention reporting over the reading principal's own ledger. */
    trr?: MiniAppTrrApi;
    /**
     * The signed-in user's own identity. Feature-detect: a host older than this
     * capability does not install it.
     */
    user?: MiniAppUserApi;
    /** Permissioned workspace team/project scope discovery. */
    workspace?: MiniAppWorkspaceApi;
    /** Reserved integration-action contract; the current host does not install it. */
    integrations?: MiniAppIntegrationsApi;
    hasEditorView?: boolean;
    hasHostHttpRequest?: boolean;
};

/**
 * One app-defined plot instance. Plot state is canonical and Git-like:
 * `headRevision` is an immutable revision identifier minted by the backing
 * provider, never by the package.
 */
declare type MiniAppPlot = {
    plotId: string;
    /** Opaque definition identity supplied by a future host plot runtime. */
    definitionId: string;
    backing: MiniAppPlotBacking;
    headRevision: string;
    syncState: MiniAppPlotSyncState;
    createdAt: number;
    updatedAt: number;
};

/** Backing providers admitted by a future host-owned plot definition. */
declare type MiniAppPlotBacking = 'managed-artifacts' | 'connected-git';

declare type MiniAppPlotDiff = {
    baseRevision: string;
    headRevision: string;
    entries: MiniAppPlotDiffEntry[];
};

declare type MiniAppPlotDiffEntry = {
    path: string;
    change: 'added' | 'modified' | 'deleted' | 'moved';
    fromPath?: string;
};

declare type MiniAppPlotEntry = {
    path: string;
    kind: 'file' | 'directory';
    sizeBytes: number;
    /** Revision that last changed this entry. */
    revision: string;
};

/** One plot file body. Contents are bounded UTF-8 text owned by the package. */
declare type MiniAppPlotFile = {
    path: string;
    content: string;
    revision: string;
};

declare type MiniAppPlotRevision = {
    revision: string;
    parentRevisions: string[];
    /** Host-stamped actor identity; never package-supplied. */
    actor: string;
    authoredAt: number;
    message: string;
};

/**
 * Provider-neutral, Git-like plot contract. New plots default to the
 * Cloudflare artifact-backed managed repository; connecting an external Git
 * provider is explicit and performed as a controlled single-authority
 * migration via {@link MiniAppPlotsApi.migrateBacking}. Packages never
 * receive raw provider credentials or unrestricted filesystem paths.
 */
declare type MiniAppPlotsApi = {
    create(options: {
        definitionId: string;
        /** Defaults to the definition's first admitted backing. */
        backing?: MiniAppPlotBacking;
    }): MiniAppMaybePromise<{
        plot: MiniAppPlot;
    }>;
    list(options?: {
        definitionId?: string;
    }): MiniAppMaybePromise<{
        plots: MiniAppPlot[];
    }>;
    get(options: {
        plotId: string;
    }): MiniAppMaybePromise<{
        plot: MiniAppPlot | null;
    }>;
    delete(options: {
        plotId: string;
    }): MiniAppMaybePromise<void>;
    readFile(options: {
        plotId: string;
        path: string;
        /** Reads at `headRevision` when omitted. */
        revision?: string;
    }): MiniAppMaybePromise<{
        file: MiniAppPlotFile | null;
    }>;
    listFiles(options: {
        plotId: string;
        /** Prefix-scopes the listing when present. */
        path?: string;
        revision?: string;
    }): MiniAppMaybePromise<{
        entries: MiniAppPlotEntry[];
    }>;
    /**
     * Optimistic-concurrency write: the host rejects the commit when
     * `expectedRevision` no longer matches the plot head.
     */
    writeFile(options: {
        plotId: string;
        path: string;
        content: string;
        expectedRevision: string;
        message?: string;
    }): MiniAppMaybePromise<{
        revision: string;
    }>;
    moveFile(options: {
        plotId: string;
        fromPath: string;
        toPath: string;
        expectedRevision: string;
        message?: string;
    }): MiniAppMaybePromise<{
        revision: string;
    }>;
    deleteFile(options: {
        plotId: string;
        path: string;
        expectedRevision: string;
        message?: string;
    }): MiniAppMaybePromise<{
        revision: string;
    }>;
    compare(options: {
        plotId: string;
        baseRevision: string;
        headRevision: string;
    }): MiniAppMaybePromise<{
        diff: MiniAppPlotDiff;
    }>;
    history(options: {
        plotId: string;
        limit?: number;
    }): MiniAppMaybePromise<{
        revisions: MiniAppPlotRevision[];
    }>;
    /**
     * Watch head-revision changes. The listener fires at least once per
     * observed transition; the returned function unsubscribes.
     */
    subscribeRevisions(options: {
        plotId: string;
    }, listener: (event: {
        plotId: string;
        headRevision: string;
    }) => void): () => void;
    /**
     * Controlled single-authority migration to another admitted backing. The
     * connected Git target references a host-owned integration connection by
     * id; provider tokens never cross into the package.
     */
    migrateBacking(options: {
        plotId: string;
        backing: MiniAppPlotBacking;
        connectionId?: string;
    }): MiniAppMaybePromise<{
        plot: MiniAppPlot;
    }>;
};

/** Host-observed synchronization state of one plot instance. */
declare type MiniAppPlotSyncState = 'clean' | 'syncing' | 'conflicted' | 'migrating' | 'unavailable';

declare type MiniAppPresenceAddress = {
    namespace: string;
    room: string;
};

/**
 * Ephemeral realtime presence scoped by the host to the active workspace and
 * exact package. Participant identity is stamped by the host, not the app.
 */
declare type MiniAppPresenceApi = {
    join(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
    update(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
    leave(options: MiniAppPresenceAddress): MiniAppMaybePromise<void>;
    subscribe(options: MiniAppPresenceAddress, listener: MiniAppPresenceListener): () => void;
};

declare type MiniAppPresenceListener = (snapshot: MiniAppPresenceSnapshot) => void;

declare type MiniAppPresenceParticipant = {
    /** Host-derived, ephemeral participant identity. */
    participantId: string;
    displayName: string;
    state: MiniAppJsonValue;
    updatedAtMs: number;
};

declare type MiniAppPresenceSnapshot = MiniAppPresenceAddress & {
    selfParticipantId: string;
    participants: MiniAppPresenceParticipant[];
};

declare type MiniAppPresenceUpdateOptions = MiniAppPresenceAddress & {
    state: MiniAppJsonValue;
};

declare type MiniAppPrivateFileEntry = {
    name: string;
    kind: 'file' | 'directory';
    /** Physical bytes charged to quota. */
    storedBytes: number;
};

declare type MiniAppPrivateFileMetadata = {
    kind: 'file' | 'directory';
    /** Plaintext file size; directories report zero. */
    size: number;
};

declare type MiniAppPrivateFilesApi = {
    read(path: string): MiniAppMaybePromise<Uint8Array>;
    write(path: string, data: Uint8Array): MiniAppMaybePromise<void>;
    readRange(path: string, offset: number, length: number): MiniAppMaybePromise<Uint8Array>;
    writeRange(path: string, offset: number, data: Uint8Array): MiniAppMaybePromise<void>;
    createDirectory(path: string): MiniAppMaybePromise<void>;
    list(path?: string): MiniAppMaybePromise<{
        entries: MiniAppPrivateFileEntry[];
    }>;
    metadata(path: string): MiniAppMaybePromise<MiniAppPrivateFileMetadata>;
    rename(from: string, to: string): MiniAppMaybePromise<void>;
    delete(path: string, options?: {
        recursive?: boolean;
    }): MiniAppMaybePromise<void>;
    /** Pulls bounded chunks without exposing a host filesystem path. */
    createReadStream(path: string, options?: {
        chunkBytes?: number;
    }): ReadableStream<Uint8Array>;
    /** Buffers at most one bounded chunk before each atomic range write. */
    createWriteStream(path: string, options?: {
        chunkBytes?: number;
    }): WritableStream<Uint8Array>;
};

declare type MiniAppPrivateSqlDatabase = MiniAppPrivateSqlTransaction & {
    close(): MiniAppMaybePromise<void>;
    transaction<T>(callback: (transaction: MiniAppPrivateSqlTransaction) => T | Promise<T>): Promise<T>;
    migrate(migrations: readonly MiniAppSqlMigration[]): MiniAppMaybePromise<{
        version: number;
    }>;
    schemaVersion(): MiniAppMaybePromise<number>;
    /** Persist the current in-memory database as one atomic SQLite snapshot. */
    checkpoint(): MiniAppMaybePromise<void>;
    /** Discard volatile state and reload the last complete snapshot. */
    recover(): MiniAppMaybePromise<void>;
};

declare type MiniAppPrivateSqlTransaction = {
    execute(sql: string, params?: readonly MiniAppSqlValue[]): MiniAppMaybePromise<MiniAppSqlResult>;
    query(sql: string, params?: readonly MiniAppSqlValue[]): MiniAppMaybePromise<MiniAppSqlQueryResult>;
};

declare type MiniAppPrivateStorageAccess = {
    /** Defaults to true. Write access also requires read access. */
    filesRead?: boolean;
    /** Defaults to true. */
    filesWrite?: boolean;
    /** Defaults to true. */
    sqlite?: boolean;
    /** Defaults to true. */
    zvec?: boolean;
};

/**
 * Opens one host-selected private storage scope for this publisher/package.
 * The owning `storage.profile` or `storage.workspace` property determines the
 * scope; package code cannot supply or change it.
 */
declare type MiniAppPrivateStorageApi = {
    open(access?: MiniAppPrivateStorageAccess): MiniAppMaybePromise<MiniAppPrivateStorageHandle>;
};

declare type MiniAppPrivateStorageHandle = {
    readonly quota: MiniAppPrivateStorageQuota;
    readonly files: MiniAppPrivateFilesApi;
    readonly sqlite: {
        open(name: string): MiniAppMaybePromise<MiniAppPrivateSqlDatabase>;
    };
    readonly zvec: {
        /** Opens an existing collection; `schema` creates it when missing. */
        open(name: string, schema?: MiniAppZvecSchema): MiniAppMaybePromise<MiniAppPrivateZvecCollection>;
    };
    usage(): MiniAppMaybePromise<MiniAppPrivateStorageUsage>;
    close(): MiniAppMaybePromise<void>;
};

declare type MiniAppPrivateStorageQuota = {
    defaultBytes: number;
    effectiveBytes: number;
};

declare type MiniAppPrivateStorageUsage = {
    usedBytes: number;
    quotaBytes: number;
    hostLimitBytes: number;
};

declare type MiniAppPrivateZvecCollection = {
    /** Empty only for a pre-0.12 unbound legacy collection. */
    readonly bindings: Readonly<Record<string, MiniAppEmbeddingSpaceBinding>>;
    insert(documents: readonly MiniAppZvecDocument[]): MiniAppMaybePromise<MiniAppZvecMutationResult>;
    upsert(documents: readonly MiniAppZvecDocument[]): MiniAppMaybePromise<MiniAppZvecMutationResult>;
    update(documents: readonly MiniAppZvecDocument[]): MiniAppMaybePromise<MiniAppZvecMutationResult>;
    delete(options: {
        pks: readonly string[];
        filter?: never;
    } | {
        filter: MiniAppZvecFilter;
        pks?: never;
    }): MiniAppMaybePromise<MiniAppZvecMutationResult>;
    query(query: MiniAppZvecQuery): MiniAppMaybePromise<MiniAppZvecSearchResult[]>;
    fetch(pks: readonly string[]): MiniAppMaybePromise<MiniAppZvecSearchResult[]>;
    stats(): MiniAppMaybePromise<MiniAppZvecStats>;
    flush(): MiniAppMaybePromise<MiniAppZvecStats>;
    close(): MiniAppMaybePromise<void>;
};

declare type MiniAppProject = {
    id: string;
    name: string;
    workspaceId: string;
    discoverable: boolean;
};

declare type MiniAppProvisionProjectChatOptions = {
    conversationId: string;
    projectId: string;
    baseBranch?: string | null;
    workingBranch?: string | null;
};

declare type MiniAppProvisionProjectChatResult = {
    mountedRoots: string[];
    worktreeBranch?: string | null;
    worktreeBaseCommit?: string | null;
};

/** Bounded semantic receipt rendered, wrapped, fed, and cut by the desktop host. */
declare type MiniAppReceiptDocument = {
    version: 1;
    /** One to 200 rows; each text field is capped at 512 printable ASCII characters. */
    lines: MiniAppReceiptLine[];
    /** Defaults to 3 and is capped at 8. */
    feedLines?: number;
    /** Defaults to true. */
    cut?: boolean;
};

/** One semantic receipt row. Raw printer commands are intentionally absent. */
declare type MiniAppReceiptLine = {
    kind: 'text';
    text: string;
    alignment?: MiniAppReceiptTextAlignment;
    weight?: MiniAppReceiptTextWeight;
} | {
    kind: 'key-value';
    label: string;
    value: string;
} | {
    kind: 'divider';
} | {
    kind: 'blank';
};

/** Host rendering capabilities for one supported receipt paper width. */
declare type MiniAppReceiptPaperProfile = {
    id: MiniAppReceiptPrinterProfile;
    widthMm: 58 | 80;
    columns: 32 | 48;
};

/** Bounded metadata for one machine-local printer visible to an authorized miniapp. */
declare type MiniAppReceiptPrinter = {
    name: string;
    isDefault: boolean;
};

declare type MiniAppReceiptPrinterDiscovery = {
    printers: MiniAppReceiptPrinter[];
    paperProfiles: MiniAppReceiptPaperProfile[];
};

declare type MiniAppReceiptPrinterProfile = 'receipt-58mm' | 'receipt-80mm';

/** Miniapp-owned selection passed explicitly to status and submission calls. */
declare type MiniAppReceiptPrinterSelection = {
    printerName: string;
    profile: MiniAppReceiptPrinterProfile;
};

/** Readiness for an exact machine-local printer selection. */
declare type MiniAppReceiptPrinterStatus = {
    availability: 'ready' | 'unavailable';
};

/** Desktop-only silent receipt output through a discovered OS spooler. */
declare type MiniAppReceiptPrintingApi = {
    listPrinters(): MiniAppMaybePromise<MiniAppReceiptPrinterDiscovery>;
    getStatus(selection: MiniAppReceiptPrinterSelection): MiniAppMaybePromise<MiniAppReceiptPrinterStatus>;
    submit(options: MiniAppReceiptPrintOptions): MiniAppMaybePromise<MiniAppReceiptPrintResult>;
};

declare type MiniAppReceiptPrintOptions = {
    /**
     * Stable caller key, capped at 128 characters. The host journals it within
     * installation, workspace, and selected-destination scope.
     */
    jobKey: string;
    selection: MiniAppReceiptPrinterSelection;
    document: MiniAppReceiptDocument;
};

declare type MiniAppReceiptPrintResult = {
    disposition: 'submitted' | 'duplicate-suppressed' | 'indeterminate';
    /** Always false: spooler acknowledgement cannot prove physical exactly-once output. */
    physicalExactlyOnce: false;
};

declare type MiniAppReceiptTextAlignment = 'left' | 'center' | 'right';

declare type MiniAppReceiptTextWeight = 'normal' | 'bold';

/** A permissioned, provenance-stamped artifact snapshot. */
declare type MiniAppResolvedArtifact = {
    readonly reference: MiniAppArtifactReference;
    /** Bounded snapshot; the payload schema is host-versioned, so narrow it. */
    readonly snapshot: MiniAppJsonValue;
    readonly provenance: {
        readonly source: string;
        readonly observedAt: number;
        /** Source-system revision (for example a commit SHA), when one exists. */
        readonly revision: string | null;
    };
    /** Ids of plot instances already linked to this artifact, when known. */
    readonly linkedPlotIds: readonly string[];
};

declare type MiniAppServicesApi = {
    readonly v1: MiniAppServicesV1Api;
};

declare type MiniAppServicesV1Api = {
    /**
     * Idempotently install and start the signed service declaration.
     *
     * The manifest readiness deadline is authoritative; this call has no
     * independent SDK timeout.
     */
    ensureRunning(options: {
        contributionId: string;
    }): Promise<MiniAppLocalServiceRunning>;
    /** Inspect state without installing, starting, stopping, or restarting. */
    getStatus(options: {
        contributionId: string;
    }): Promise<MiniAppLocalServiceStatus>;
};

/**
 * Secure session storage backed by the operating system credential store.
 *
 * The host derives the signed-in TAP account, active workspace, installation,
 * and package from the authenticated frame. Channel, surface, document, and
 * release are deliberately excluded, so every surface of one installed
 * miniapp shares the same session only within a workspace and package updates
 * retain it. Unlike host-managed HTTP credentials, values returned here enter
 * miniapp JavaScript.
 */
declare type MiniAppSessionApi = {
    get(): MiniAppMaybePromise<MiniAppSessionEntry>;
    set(value: MiniAppSessionValue): MiniAppMaybePromise<void>;
    clear(): MiniAppMaybePromise<void>;
};

declare type MiniAppSessionEntry = {
    /** Null means that no session value currently exists for this installation. */
    value: MiniAppSessionValue | null;
};

declare type MiniAppSessionValue = {
    [key: string]: MiniAppJsonValue;
};

declare type MiniAppSpecialistApi = {
    joinToChannel(channelId: string, specialistId: string): MiniAppMaybePromise<string>;
    prepareChannel(options: {
        channelId: string;
        workspaceId?: string;
        specialistIds: readonly string[];
    }): MiniAppMaybePromise<Readonly<{
        channelId: string;
        specialists: readonly Readonly<{
            specialistId: string;
            sessionId: string;
        }>[];
    }>>;
    listWorkspace(workspaceId: string): MiniAppMaybePromise<MiniAppSpecialistSummary[]>;
    create(options: MiniAppCreateSpecialistOptions): MiniAppMaybePromise<MiniAppCreateSpecialistResult>;
    upsertManaged?(specialist: MiniAppManagedSpecialist): MiniAppMaybePromise<MiniAppManagedSpecialistResult>;
    runTurnWithTools?(options: MiniAppSpecialistTurnOptions): MiniAppMaybePromise<MiniAppSpecialistTurnResult>;
    streamTurnWithTools?(options: MiniAppSpecialistTurnOptions, observer: MiniAppSpecialistTurnObserver): MiniAppMaybePromise<MiniAppSpecialistTurnResult>;
};

declare type MiniAppSpecialistConversationPart = {
    type: 'text';
    content: string;
} | {
    type: 'tool';
    toolCallId: string;
    toolName: string;
    arguments: MiniAppJsonValue;
    toolIntent: string | null;
    success: boolean;
    content: MiniAppJsonValue;
    mediaCost?: MiniAppJsonValue | null;
    error?: string | null;
    executionTimeMs: number;
} | {
    type: 'stepEnd';
    iteration: number;
};

declare type MiniAppSpecialistInteractionMode = 'conversational' | 'agentic' | 'planning' | 'background' | 'longRunning' | 'inlineEdit' | 'focus';

declare type MiniAppSpecialistMessageSnapshot = Readonly<{
    type: 'messageSnapshot';
    channelId: string;
    messageId: string;
    streamVersion: number;
    body: string;
}>;

declare type MiniAppSpecialistSummary = {
    id: string;
    slug: string;
    displayName: string;
    description: string;
    tags: string[];
    version: string;
    availability: 'public' | 'internal' | 'private' | 'restricted';
    canRunLocally: boolean;
    category: string;
    categoryDisplayName: string;
    requiredCapabilities: {
        inputModalities: string[];
        toolUse?: boolean | null;
        reasoning?: boolean | null;
    } | null;
    omnipresence?: {
        autoJoinChannels: boolean;
        includeDms: boolean;
        pinSidebar: boolean;
    } | null;
    displayIcon?: {
        type: 'bundled';
        path: string;
    } | null;
    resolvedDisplayIconUrl?: string | null;
};

declare type MiniAppSpecialistTurnObserver = Readonly<{
    onSnapshot(snapshot: MiniAppSpecialistMessageSnapshot): void;
}>;

declare type MiniAppSpecialistTurnOptions = {
    /** Defaults to the surface's own workspace, like the rest of the SDK. */
    workspaceId?: string;
    /**
     * Channel to run the turn in.
     *
     * Omit it to run without a channel. The host then resolves or creates a
     * **private room** of its own per (workspace, package, specialist) and runs
     * the turn there, so the turn needs only `specialists.invoke` and never any
     * `channels.*` permission — the guest neither creates nor joins a channel.
     *
     * That room is **persistent and keyed on the same triple**, so repeat calls
     * continue one conversation rather than starting fresh. This is deliberate:
     * it is what lets a surface offer regenerate or amend. Do not treat a
     * channel-less turn as fire-and-forget with no history.
     */
    channelId?: string;
    /**
     * Opt in to a dispatched turn, and only meaningful alongside `channelId`.
     *
     * The host persists `content` into that channel as an ordinary message and
     * dispatches through routing, so the **specialist runtime writes the reply
     * itself**, under the provenance chat requires. The reply lands in the
     * channel timeline like any other specialist message rather than coming back
     * to you as loose completion parts, so read it from the timeline — the
     * returned completion is the turn's own record, not the thing to render.
     *
     * This mode requires `channels.send-message` with `do` autonomy in addition
     * to the base `specialists.invoke` grant. The calling surface must declare
     * both permissions, and the package must hold both grants.
     *
     * The specialist must already be seated in the channel; joining one is
     * `channels.manage-specialists`, a separate grant.
     *
     * Omit it (or pass `false`) and a channelled turn stays silent: it commits no
     * room message and you get the reply only in the result. A channel-less turn
     * is always dispatched, so this says nothing there.
     */
    dispatch?: boolean;
    specialistId: string;
    content: string;
    /**
     * Model to run with. Omit or pass `null` to use the workspace's choice, which
     * is what a surface normally wants — naming a model in app code pins it.
     */
    modelOverride?: null | string;
    messageId: null;
    interactionMode: MiniAppSpecialistInteractionMode;
    timeoutMs: number;
};

declare type MiniAppSpecialistTurnResult = {
    completionEvent: {
        parts: MiniAppSpecialistConversationPart[];
        finishReason?: string;
        modelUsed?: string;
    };
};

declare type MiniAppSqlMigration = {
    /** Positive, contiguous version applied after the current schema version. */
    version: number;
    sql: string;
};

declare type MiniAppSqlQueryResult = {
    columns: string[];
    rows: MiniAppSqlValue[][];
};

declare type MiniAppSqlResult = {
    rowsAffected: number;
    lastInsertRowId: number | bigint;
};

declare type MiniAppSqlValue = null | number | bigint | string | Uint8Array;

/** Opaque host handle for one staged package-owned deep link. */
declare type MiniAppStagedDeepLink = Readonly<{
    id: string;
}>;

declare type MiniAppStageDeepLinkOptions = Readonly<{
    label: string;
    target: MiniAppDeepLinkTarget;
}>;

/** Caller-selected partition inside the host-derived workspace/package scope. */
declare type MiniAppStorageAddress = {
    namespace: string;
    key: string;
};

/**
 * Durable, non-secret JSON storage. The host derives workspace and package
 * identity from the authenticated frame; apps control only the namespace and
 * key inside that scope. Package-runtime MCP tools receive a bounded
 * point-in-time snapshot: `get` is available during execution while `set` and
 * `delete` fail closed.
 */
declare type MiniAppStorageApi = {
    get(options: MiniAppStorageAddress): MiniAppMaybePromise<MiniAppStorageEntry>;
    set(options: MiniAppStorageSetOptions): MiniAppMaybePromise<MiniAppStorageMutationResult>;
    delete(options: MiniAppStorageDeleteOptions): MiniAppMaybePromise<void>;
    /** Desktop-only private profile-local files, SQLite, and zvec. */
    profile?: MiniAppPrivateStorageApi;
    /** Desktop-only private files, SQLite, and zvec bound to the current workspace. */
    workspace?: MiniAppPrivateStorageApi;
};

declare type MiniAppStorageDeleteOptions = MiniAppStorageAddress & {
    expectedRevision: number;
};

declare type MiniAppStorageEntry = {
    value: MiniAppJsonValue | null;
    /** Null means that no value currently exists at this address. */
    revision: number | null;
};

declare type MiniAppStorageMutationResult = {
    revision: number;
};

declare type MiniAppStorageSetOptions = MiniAppStorageAddress & {
    value: MiniAppJsonValue;
    /** Optimistic concurrency token returned by `get`; null creates a missing key. */
    expectedRevision: number | null;
};

declare type MiniAppTask = {
    id: string;
    title: string;
    description?: string;
    status: MiniAppTaskStatus;
    priority: MiniAppTaskPriority;
    assignees: MiniAppTaskAssignee[];
    workspaceId: string;
    channelIds: string[];
    createdAt: number;
    updatedAt: number;
    dueDate?: number;
    archived: boolean;
};

declare type MiniAppTaskAssignee = {
    id: string;
    type: 'human' | 'specialist';
    name: string;
    avatar?: string;
    specialistSlug?: string;
};

declare type MiniAppTaskPriority = 'low' | 'medium' | 'high' | 'urgent';

/** Workspace task CRUD plus receipt-backed task creation. */
declare type MiniAppTasksApi = {
    create(options: CreateTaskOptions): CreateTaskResult | Promise<CreateTaskResult>;
    update(options: UpdateTaskOptions): UpdateTaskResult | Promise<UpdateTaskResult>;
    delete(options: DeleteTaskOptions): DeleteTaskResult | Promise<DeleteTaskResult>;
    list(options?: ListTasksOptions): ListTasksResult | Promise<ListTasksResult>;
    /**
     * Create a task through the durable receipt journal. Replaying one
     * `idempotencyKey` returns the journaled receipt instead of creating a
     * second task.
     */
    createWithReceipt(options: {
        workspaceId?: string;
        title: string;
        description?: string;
        projectId?: string;
        channelIds?: string[];
        assigneeUserIds?: string[];
        idempotencyKey: string;
    }): MiniAppMaybePromise<{
        receipt: MiniAppActionReceipt;
    }>;
};

declare type MiniAppTaskStatus = 'backlog' | 'toDo' | 'inProgress' | 'blocked' | 'done';

declare type MiniAppTerminalApi = {
    readonly v1: MiniAppTerminalV1Api;
};

/** Versioned, desktop-only host terminal capability. */
declare type MiniAppTerminalV1Api = {
    getCapabilities(): Promise<MiniAppTerminalV1Capabilities>;
    open(options: MiniAppTerminalV1OpenOptions): Promise<MiniAppTerminalV1Session>;
};

declare type MiniAppTerminalV1Capabilities = {
    profiles: MiniAppTerminalV1Profile[];
    limits: MiniAppTerminalV1Limits;
};

declare type MiniAppTerminalV1DataEvent = {
    type: 'data';
    sequence: number;
    data: Uint8Array;
};

declare type MiniAppTerminalV1Event = MiniAppTerminalV1DataEvent | MiniAppTerminalV1ExitEvent;

declare type MiniAppTerminalV1ExitEvent = {
    type: 'exit';
    sequence: number;
    code: number | null;
    signal: string | null;
    reason: 'exited' | 'closed' | 'revoked' | 'error';
};

declare type MiniAppTerminalV1Limits = {
    maxSessionsPerDocument: number;
    maxWriteBytes: number;
    maxOutputBytesInFlight: number;
    maxCols: number;
    maxRows: number;
};

declare type MiniAppTerminalV1OpenOptions = {
    profile: MiniAppTerminalV1ProfileId;
    cols: number;
    rows: number;
};

declare type MiniAppTerminalV1Profile = {
    id: MiniAppTerminalV1ProfileId;
    available: boolean;
    unavailableReason: string | null;
};

/** Host-owned terminal runtime profiles exposed by `sdk.terminal.v1`. */
declare type MiniAppTerminalV1ProfileId = 'workspace-shell' | 'neovim';

declare type MiniAppTerminalV1ResizeOptions = {
    cols: number;
    rows: number;
};

declare type MiniAppTerminalV1Session = {
    /** Opaque host-minted session identity; it carries no ambient authority. */
    readonly id: string;
    readonly profile: MiniAppTerminalV1ProfileId;
    /** Ordered output with byte-sized backpressure owned by the host session. */
    readonly events: ReadableStream<MiniAppTerminalV1Event>;
    write(data: Uint8Array): Promise<void>;
    resize(options: MiniAppTerminalV1ResizeOptions): Promise<void>;
    close(): Promise<void>;
};

export declare type MiniAppTheme = 'light' | 'dark';

/**
 * Read-only retention reporting for the reading principal's own local ledger.
 *
 * Every payload is shaped by the host, which strips its research-only fields before a guest sees
 * it, so the result is deliberately `MiniAppJsonValue` rather than a structural type — the host
 * can then add a field without republishing this package.
 *
 * `state` distinguishes the three outcomes a caller must render differently: `ok` has cells,
 * `withheld` means a guardrail suppressed them, and `no-data` means nothing was captured. It
 * never reveals which guardrail applied.
 *
 * The three count reads have no `withheld` state at all: they are scoped to the reader's own rows,
 * so no k-anonymity floor can suppress them.
 *
 * Cost lives behind its own `trr.read-cost` permission, so a package granted retention ratios is
 * not thereby granted spend.
 *
 * A cell may carry `cohortLabel`, which names the cohort the number belongs to (a project title, or
 * a specialist, model, or harness id), so granting `trr.read` discloses which of the reader's own
 * projects and specialists exist and not only anonymous ratios.
 */
declare type MiniAppTrrApi = {
    /** Retention ratio and its confidence band, per cohort. */
    getAggregate(options: MiniAppTrrScope): MiniAppMaybePromise<{
        dimension: string;
        horizonSeconds: number;
        state: 'ok' | 'withheld' | 'no-data';
        cells: MiniAppJsonValue[];
    }>;
    /** Retention pooled per cohort, the slice-comparison surface. */
    getMdTrr(options: MiniAppTrrScope): MiniAppMaybePromise<{
        dimension: string;
        horizonSeconds: number;
        state: 'ok' | 'withheld' | 'no-data';
        cells: MiniAppJsonValue[];
    }>;
    /**
     * Modeled spend per surviving code unit — never per provider token, since the denominator is
     * authored-code units.
     */
    getEcrt(options: MiniAppTrrScope): MiniAppMaybePromise<{
        dimension: string;
        horizonSeconds: number;
        state: 'ok' | 'withheld' | 'no-data';
        cells: MiniAppJsonValue[];
    }>;
    /**
     * How the reader's own retained work died, counted over the whole ledger.
     *
     * `window` is `'all-time'` because these counts are not horizon-scoped: they must never be
     * rendered as the complement of a horizon-scoped ratio, and `totalDeaths` counts span charges
     * rather than messages, so it exceeds the dead-message count from `getSurvivalCounts`.
     */
    getDeathCauses(options?: {
        workspaceId?: string;
    }): MiniAppMaybePromise<{
        window: 'all-time';
        state: 'ok' | 'no-data';
        totalDeaths: number;
        causes: {
            deathMode: string;
            deaths: number;
        }[];
    }>;
    /**
     * Which actor relation edited the reader's own work, counted over the whole ledger.
     *
     * A relation with no countable charge is absent rather than zero, and no severity is reported
     * because severity scores the relation and not the count.
     */
    getRelationMix(options?: {
        workspaceId?: string;
    }): MiniAppMaybePromise<{
        window: 'all-time';
        state: 'ok' | 'no-data';
        relations: {
            relation: string;
            edits: number;
            deaths: number;
        }[];
    }>;
    /** How many of the reader's own messages were evaluated, and how many died, at one horizon. */
    getSurvivalCounts(options?: {
        workspaceId?: string;
        syntheticHorizonSeconds?: number;
    }): MiniAppMaybePromise<{
        horizonSeconds: number;
        horizonLabel: string;
        state: 'ok' | 'no-data';
        snapshotCount: number;
        deadCount: number;
    }>;
    /**
     * Recompute this workspace's retention verdicts over the canonical horizons, which is the only
     * write on this surface and needs the separate `trr.sweep` grant at `do` autonomy.
     *
     * Only a `TRR_SWEEP_THROTTLED` rejection means "try later"; every other code — a missing grant,
     * an authentication or authority failure, `TRR_SWEEP_FAILED` — is handled like any other host
     * action error and must not be retried on a loop.
     *
     * No counts come back, because the sweep tallies every principal's rows while the reads above are
     * scoped to the caller; re-read those instead once this resolves.
     */
    runSweep(options?: {
        workspaceId?: string;
    }): MiniAppMaybePromise<{
        swept: true;
    }>;
};

/**
 * Which slice of retention to read.
 *
 * `dimension` is a string rather than a union so the host can add a cohort dimension without a
 * lockstep SDK release; unsupported values are rejected by the host, not by this type.
 */
declare type MiniAppTrrScope = {
    workspaceId?: string;
    dimension: string;
    /** Selects a non-default horizon; omit for the canonical 7-day one. */
    syntheticHorizonSeconds?: number;
};

export declare type MiniAppUiScale = number;

/**
 * The person using this surface, as the host knows them.
 *
 * Host-derived and not supplyable by a miniapp. Needs no permission and prompts
 * for nothing: the mount context already carries `userId`, so the name that goes
 * with that id is not new authority. Anyone *else's* identity is a different
 * question — it exposes people who never opened this package — and belongs behind
 * a directory capability with its own grant and consent.
 */
declare type MiniAppUser = {
    userId: string;
    /**
     * What the host calls this person. Empty when the signed-in profile has no
     * usable name, which a guest mount can produce — render a fallback rather than
     * an empty row.
     */
    displayName: string;
};

declare type MiniAppUserApi = {
    current(): MiniAppMaybePromise<MiniAppUser>;
};

declare type MiniappUserFileDeleteReceipt = {
    handleId: string;
    revision: string;
    deletedAt: string;
};

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

declare type MiniappUserFileMetadata = {
    name: string;
    mimeType?: string | undefined;
    extension?: string | undefined;
    byteLength: number;
    contentHash?: string | undefined;
    modifiedAt?: string | undefined;
    revision: string;
    provenance: 'user-selected' | 'recovered' | 'workspace' | 'provider';
    handle: MiniappUserFileHandle;
};

declare type MiniappUserFileRenameReceipt = {
    handle: MiniappUserFileHandle;
    name: string;
    revision: string;
    renamedAt: string;
};

declare type MiniappUserFileWatchReceipt = {
    handleId: string;
    previousRevision: string;
    revision: string;
    change: 'unchanged' | 'created' | 'modified' | 'deleted';
    observedAt: string;
    timedOut: boolean;
    handle: MiniappUserFileHandle;
};

declare type MiniappUserFileWriteReceipt = {
    handle: MiniappUserFileHandle;
    revision: string;
    contentHash: string;
    byteLength: number;
    committedAt: string;
    idempotencyKey: string;
};

declare type MiniAppUserProfile = {
    sub: string;
    name?: string | null;
    givenName?: string | null;
    familyName?: string | null;
    middleName?: string | null;
    nickname?: string | null;
    preferredUsername?: string | null;
    profile?: string | null;
    picture?: string | null;
    website?: string | null;
    email?: string | null;
    emailVerified?: boolean | null;
    gender?: string | null;
    birthdate?: string | null;
    zoneinfo?: string | null;
    locale?: string | null;
    phoneNumber?: string | null;
    phoneNumberVerified?: boolean | null;
    address?: MiniAppJsonValue | null;
    updatedAt?: string | null;
};

declare type MiniAppVfsApi = {
    provisionProjectChat(options: MiniAppProvisionProjectChatOptions): MiniAppMaybePromise<MiniAppProvisionProjectChatResult>;
    writeFile(conversationId: string, path: string, data: Uint8Array): MiniAppMaybePromise<null>;
    writeFiles(conversationId: string, files: readonly {
        path: string;
        data: Uint8Array;
    }[]): MiniAppMaybePromise<null>;
    mkdir(conversationId: string, path: string): MiniAppMaybePromise<null>;
};

declare type MiniAppWorkflow = {
    id: string;
    name: string;
    type: string;
    createdAt: number;
    updatedAt: number;
};

/** One observed workflow run, correlated to the plot revision that asked for it. */
declare type MiniAppWorkflowRun = {
    runId: string;
    workflowId: string;
    workspaceId: string;
    /** Host-versioned status vocabulary; narrow before branching on it. */
    status: string;
    startedAt: number | null;
    completedAt: number | null;
    /** Bounded structured outputs, when the run produced any. */
    result: MiniAppJsonValue | null;
    failure: {
        message: string;
        details: MiniAppJsonValue | null;
    } | null;
    correlation: {
        plotId: string | null;
        expectedSourceRevision: string | null;
    } | null;
};

declare type MiniAppWorkflowRunEvent = {
    run: MiniAppWorkflowRun;
    observedAt: number;
};

/**
 * Permissioned workspace scope discovery so a package can resolve
 * workspace-, team-, and project-scoped configuration without inventing its
 * own organization model.
 */
declare type MiniAppWorkspaceApi = {
    listTeams(options?: {
        workspaceId?: string;
    }): MiniAppMaybePromise<{
        teams: MiniAppWorkspaceTeam[];
    }>;
    /** What this workspace is called. Requires `workspace.read`. */
    current(options?: {
        workspaceId?: string;
    }): MiniAppMaybePromise<MiniAppWorkspaceProfile>;
    /**
     * The workspace roster. Requires `workspace.read`, the same authority as teams
     * and projects.
     */
    listMembers(options?: {
        workspaceId?: string;
    }): MiniAppMaybePromise<{
        members: MiniAppWorkspaceMember[];
    }>;
    listProjects(options?: {
        workspaceId?: string;
    }): MiniAppMaybePromise<{
        projects: MiniAppProject[];
    }>;
};

/**
 * One workspace member, reduced to what a package can justify knowing.
 *
 * The host's own roster carries email, role, title, timezone, invitation
 * timestamps and who invited whom. A miniapp gets a user id and a name: enough to
 * render a person, and not a workspace's contact list. Only joined members are
 * listed — an invitation is not a teammate, and pending invites would reveal
 * hiring before it is announced.
 */
declare type MiniAppWorkspaceMember = {
    userId: string;
    displayName: string;
};

/**
 * The workspace a surface is mounted in.
 *
 * `displayName` falls back to the workspace id when the workspace has no name, so
 * it is never empty — a header reading nothing is worse than one reading something
 * opaque.
 */
declare type MiniAppWorkspaceProfile = {
    workspaceId: string;
    displayName: string;
};

/** One canonical workspace team, as resolved by the host. */
declare type MiniAppWorkspaceTeam = {
    id: string;
    name: string;
    workspaceId: string;
};

declare type MiniAppZvecDocument = {
    pk: string;
    fields: {
        [key: string]: MiniAppJsonValue | MiniAppEmbeddingVector;
    };
};

declare type MiniAppZvecFilter = {
    op: 'eq' | 'ne' | 'lt' | 'lte' | 'gt' | 'gte';
    field: string;
    value: MiniAppZvecFilterValue;
} | {
    op: 'in' | 'notIn';
    field: string;
    values: MiniAppZvecFilterValue[];
} | {
    op: 'isNull' | 'isNotNull';
    field: string;
} | {
    op: 'and' | 'or';
    filters: MiniAppZvecFilter[];
} | {
    op: 'not';
    filter: MiniAppZvecFilter;
};

declare type MiniAppZvecFilterValue = boolean | number | string;

declare type MiniAppZvecMetric = 'L2' | 'IP' | 'COSINE' | 'MIPSL2';

declare type MiniAppZvecMutationResult = {
    writeResults: MiniAppZvecWriteResult[];
    affectedCount?: number;
    deletedByFilter?: boolean;
};

declare type MiniAppZvecQuery = Readonly<{
    fieldName: string;
    vector: MiniAppEmbeddingVector;
    topK: number;
    filter?: MiniAppZvecFilter;
    outputFields?: readonly string[];
    /** At most 100 results may include stored vectors. */
    includeVector?: boolean;
    fts?: {
        queryString?: string;
        matchString?: string;
        defaultOperator?: 'AND' | 'OR';
    };
}>;

declare type MiniAppZvecScalarDataType = 'BINARY' | 'STRING' | 'BOOL' | 'INT32' | 'INT64' | 'UINT32' | 'UINT64' | 'FLOAT' | 'DOUBLE' | 'ARRAY_BINARY' | 'ARRAY_BOOL' | 'ARRAY_STRING' | 'ARRAY_INT32' | 'ARRAY_INT64' | 'ARRAY_UINT32' | 'ARRAY_UINT64' | 'ARRAY_FLOAT' | 'ARRAY_DOUBLE';

declare type MiniAppZvecScalarField = Readonly<{
    name: string;
    dataType: MiniAppZvecScalarDataType;
    nullable?: boolean;
    index?: MiniAppZvecScalarIndex;
}>;

declare type MiniAppZvecScalarIndex = {
    type: 'INVERT';
} | {
    type: 'FTS';
    tokenizerName?: string;
    filters?: readonly string[];
    extraParams?: string;
};

declare type MiniAppZvecSchema = Readonly<{
    fields: readonly (MiniAppZvecScalarField | MiniAppZvecVectorField)[];
}>;

declare type MiniAppZvecSearchResult = {
    pk: string;
    score: number;
    fields: {
        [key: string]: MiniAppJsonValue;
    };
};

declare type MiniAppZvecStats = {
    docCount: number;
    storedBytes: number;
    indexes: Array<{
        name: string;
        completeness: number;
    }>;
};

declare type MiniAppZvecVectorDataType = 'VECTOR_FP16' | 'VECTOR_FP32' | 'VECTOR_FP64' | 'VECTOR_BINARY32' | 'VECTOR_BINARY64' | 'VECTOR_INT4' | 'VECTOR_INT8' | 'VECTOR_INT16';

declare type MiniAppZvecVectorField = Readonly<{
    name: string;
    dataType: MiniAppZvecVectorDataType;
    dimension: number;
    nullable?: boolean;
    index: MiniAppZvecVectorIndex;
    /** Mandatory for newly created vector fields. */
    binding: MiniAppEmbeddingSpaceBinding;
}>;

declare type MiniAppZvecVectorIndex = {
    type: 'FLAT';
    metric: MiniAppZvecMetric;
} | {
    type: 'HNSW';
    metric: MiniAppZvecMetric;
    m?: number;
    efConstruction?: number;
} | {
    type: 'IVF';
    metric: MiniAppZvecMetric;
};

declare type MiniAppZvecWriteResult = {
    pk: string;
    code: number;
    message: string;
};

/** Requests the host-owned editor capability for this exact miniapp frame. */
export declare function openEditorProject(options: OpenEditorProjectOptions): Promise<void>;

export declare type OpenEditorProjectOptions = {
    conversationId: string;
    files?: Array<{
        path: string;
        selection?: {
            line: number;
            column: number;
        };
    }>;
    mode: 'embedded';
    projectId?: string | null;
};

/** A canonical HTTPS URL opened solely by the desktop operating-system browser. */
declare type OpenExternalNavigationOptions = {
    url: string;
};

declare type OpenNavigationOptions = {
    path: string;
};

/** Unknown capabilities fail closed. */
export declare function platformSatisfiesApp(platform: MiniAppPlatform, requiredCapabilities: readonly string[]): boolean;

/**
 * The host surface installed in this realm, or `null` outside one.
 *
 * Reading is lazy and side-effect free so module init order never decides
 * whether a guest sees its host.
 */
export declare function readInjectedMiniappHostSurface(): MiniappHostSurface | null;

declare type RenameUserFileRequest = {
    handle: MiniappUserFileHandle;
    expectedRevision: string;
    newName: string;
};

declare type SendChannelMessageOptions = {
    workspaceId?: string;
    channelId: string;
    /**
     * Optional stable client id for product-owned messages such as seeded
     * lifecycle notices. Omit for ordinary miniapp messages.
     */
    clientMessageId?: string;
    name?: string;
    /** Display body to persist. When omitted, the host formats `name` and `content`. */
    body?: string;
    content: string;
    /** Optional structured chat content persisted with the message. */
    messageContent?: Record<string, MiniAppJsonValue>;
};

declare type SendChannelMessageResult = {
    messageId: string;
    clientMessageId: string;
};

export declare type SpecialistEvent = SpecialistTurnCompletedEvent | SpecialistTurnErrorEvent;

export declare type SpecialistTurnCompletedEvent = {
    type: 'turnCompleted';
    channelId: string;
    clientMessageId?: string | null;
    finishReason?: string | null;
    messageId: string | null;
    modelUsed?: string | null;
    parts?: MiniAppSpecialistConversationPart[];
    providerUsed?: string | null;
    specialistId: string;
    totalIterations?: number | null;
    totalTimeMs?: number | null;
    totalToolCalls?: number | null;
    turnId?: string | null;
};

export declare type SpecialistTurnErrorEvent = {
    type: 'turnError';
    channelId: string;
    clientMessageId?: string | null;
    error?: string | null;
    messageId?: string | null;
    specialistId: string;
    turnId?: string | null;
};

declare type UpdateProjectOptions = {
    workspaceId?: string;
    projectId: string;
    name?: string;
    discoverable?: boolean;
};

declare type UpdateProjectResult = {
    project: MiniAppProject;
};

declare type UpdateTaskOptions = {
    workspaceId?: string;
    taskId: string;
    title?: string;
    description?: string;
    status?: MiniAppTaskStatus;
    priority?: MiniAppTaskPriority;
    assignees?: MiniAppTaskAssignee[];
    /** Pass `null` to clear the due date. */
    dueDate?: number | null;
};

declare type UpdateTaskResult = {
    task: MiniAppTask;
};

declare type WatchUserFileRequest = {
    handle: MiniappUserFileHandle;
    previousRevision: string;
    waitMs: number;
};

export { }