/**
 *  Access control configuration for specialists.
 *
 *  PRD Reference: Section 6.2 (lines 508-549)
 *
 *  This defines fine-grained access control for specialists using
 *  ABAC (Attribute-Based Access Control) and ReBAC (Relationship-Based Access Control).
 */
declare type AccessControl = {
    /**  Visibility level determining who can see this specialist */
    visibility?: Visibility;
    /**
     *  IdP groups that must ALL be present (AND logic)
     *  Example: ["okta:engineering", "azure:ai-approved"]
     */
    requiredGroups?: string[];
    /**
     *  Tags that must ALL be present (AND logic)
     *  Example: ["cost-center:R&D", "clearance:internal"]
     */
    requiredTags?: string[];
    /**
     *  Groups that are explicitly blocked (checked first for fail-fast)
     *  Example: ["okta:external-contractors"]
     */
    denyGroups?: string[];
    /**  Minimum autonomy level required */
    minAutonomyCeiling?: AutonomyCeiling | null;
    /**  Whether MFA must be verified */
    requireMfaVerified?: boolean;
    /**  Advanced Cerbos policy conditions (evaluated at origin) */
    cerbosCondition?: CerbosCondition | null;
};

/**
 *  Public A2A Agent Card metadata authored by a specialist manifest.
 *
 *  The manifest only owns stable publication hints. Runtime-owned values such
 *  as tenant, OAuth flow endpoints, feature availability, and signing material
 *  stay outside the manifest so deployment policy cannot be bypassed by
 *  authored metadata.
 */
declare type AgentCardManifest = {
    /**  A2A protocol version to advertise for the supported interface. */
    protocolVersion?: string | null;
    /**  A2A protocol binding to advertise for the supported interface. */
    protocolBinding?: AgentCardProtocolBinding | null;
    /**  Public invocation URL for this Agent Card. */
    url?: string | null;
    /**  Public documentation URL. */
    documentationUrl?: string | null;
    /**  Public icon URL for registries and remote clients. */
    iconUrl?: string | null;
    /**  Default accepted input media modes for derived Agent Cards. */
    defaultInputModes?: string[];
    /**  Default emitted output media modes for derived Agent Cards. */
    defaultOutputModes?: string[];
    /**  Optional streaming capability override for derived Agent Cards. */
    streaming?: boolean | null;
};

/**
 *  Wire protocol binding a manifest may request for its public Agent Card.
 *
 *  Only JSON-RPC is supported in this slice. Keeping this as an enum instead of
 *  a free string lets future bindings be added without accepting arbitrary
 *  protocol names in manifests.
 */
declare type AgentCardProtocolBinding = 
/**  JSON-RPC A2A binding. */
'JSONRPC';

export declare type AppConfig = {
    ui?: readonly UIEntrypoint[];
    tools?: Record<string, ToolDefinition>;
};

/**
 *  Authentication configuration for specialist execution.
 *
 *  This struct is designed for CONFIGURATION ONLY. Actual credentials
 *  are stored in the OS keyring via `ApiKeyManager` and are referenced
 *  by `credential_ref`.
 *
 *  # Example (JSON5)
 *
 *  ```json5
 *  {
 *    type: "api-key",
 *    credentialRef: "openrouter",  // References key in ApiKeyManager
 *    headerName: "Authorization",
 *    headerPrefix: "Bearer "
 *  }
 *  ```
 */
declare type AuthConfig = {
    /**  The type of authentication to use. */
    type: AuthType;
    /**
     *  Reference to the credential in the keyring.
     *
     *  This is NOT the actual credential - just an identifier used to
     *  look up the credential in `ApiKeyManager`.
     *
     *  Examples: "openrouter", "cloudflare-ai", "custom-provider-1"
     */
    credentialRef?: string | null;
    /**
     *  Optional header name for API key authentication.
     *  Default: "Authorization"
     */
    headerName?: string | null;
    /**
     *  Optional header prefix (e.g., "Bearer ", "X-API-Key ").
     *  Default: "Bearer " for most providers
     */
    headerPrefix?: string | null;
};

/**
 *  Authentication type for provider endpoints.
 *
 *  # Security Note
 *
 *  Actual credentials are NEVER stored in manifests. The `credential_ref`
 *  field in `AuthConfig` references a key stored in the OS keyring via
 *  `ApiKeyManager`. The auth type determines HOW the credential is used,
 *  not WHERE it's stored.
 */
declare type AuthType = 
/**
*  Simple API key authentication.
*  The key is sent in the Authorization header (or custom header).
*/
'api-key'
/**
*  OAuth 2.0 flow.
*  User authorizes via OAuth, tokens managed by the app.
*/
| 'o-auth'
/**
*  Organization-scoped API key.
*  Shared credential managed by the organization admin.
*  Retrieved via authenticated backend call, never stored locally.
*/
| 'organization-key'
/**
*  Forward user's JWT token to the endpoint.
*
*  # Security Warning
*
*  This is the highest-risk auth type. It sends the user's identity
*  to a third-party endpoint. Requirements:
*  - Endpoint MUST be HTTPS
*  - Endpoint SHOULD be in the verified allowlist
*  - User MUST provide explicit consent
*  - JWT audience claim should include the endpoint domain
*/
| 'jwt-forwarding';

/**
 *  Autonomy ceiling levels for agent operations
 *
 *  This defines the maximum level of autonomy an agent can operate at.
 *  PRD Reference: Progressive Trust Model (Listen → Plan → Do)
 */
declare type AutonomyCeiling = 
/**  Read-only context, no actions */
'listen'
/**  Propose actions, require approval */
| 'plan'
/**  Execute autonomously with audit trail */
| 'do';

/**
 *  Availability level for specialist discovery in the marketplace.
 *
 *  Controls who can see and access a specialist in the marketplace.
 */
declare type Availability = 
/**  Listed in marketplace, discoverable by all users. */
'public'
/**  Visible only within the specialist author's organization. */
| 'internal'
/**  Visible only to specified users or teams. */
| 'private'
/**
*  Visible to all users, but requires group membership to install or use.
*  New in PRD v0.0.5.
*/
| 'restricted';

/**  Defines what tasks this specialist can help with. */
declare type Capabilities = {
    /**  Short tags for quick filtering (e.g., ["rust", "backend", "api"]). */
    tags?: string[];
    /**
     *  One capability summary (schema 2.0). Replaces the category-keyed
     *  `descriptions` map — the migration folds the legacy
     *  primary/secondary/advanced keys into this field.
     */
    summary?: string;
    /**
     *  Example user asks shown in marketplace UI and embedded (bounded)
     *  into the routing vector (schema 2.0). Replaces the category-keyed
     *  `examples` map.
     */
    tryAsking?: string[];
    /**  Skill-specific input and output media mode overrides keyed by capability. */
    mediaModes?: {
        [key in string]: CapabilityMediaModes;
    };
};

/**  Skill-specific media mode overrides for derived Agent Card skills. */
declare type CapabilityMediaModes = {
    /**  Input media modes accepted by this capability. */
    inputModes?: string[];
    /**  Output media modes emitted by this capability. */
    outputModes?: string[];
};

/**
 *  Cerbos condition for advanced policy evaluation
 *
 *  This structure represents Cerbos policy expressions that are too complex
 *  for edge evaluation and must be evaluated at the origin service.
 */
declare type CerbosCondition = {
    /**  Match condition (all/any of expressions) */
    match: ConditionMatch;
};

/**
 *  A single condition expression for Cerbos evaluation
 *
 *  Example: `{ "expr": "P.attr.device_trust_level >= 'managed'" }`
 */
declare type ConditionExpr = {
    /**  The Cerbos expression string */
    expr: string;
};

/**  Condition match type (all/any) */
declare type ConditionMatch = 
/**  All conditions must be true (AND logic) */
({
    all: {
        of: ConditionExpr[];
    };
} & {
    any?: never;
})
/**  Any condition must be true (OR logic) */
| ({
    any: {
        of: ConditionExpr[];
    };
} & {
    all?: never;
});

/**
 *  Cost attribution model for sub-specialist usage.
 *
 *  Determines how costs are attributed when a sub-specialist is invoked.
 */
declare type CostAttribution = 
/**
*  All costs attributed to the parent specialist.
*  The parent's billing account is charged for all sub-specialist usage.
*/
'CHARGE_PARENT'
/**
*  Unsupported/deferred. Child billing is not currently supported and
*  runtime validation rejects this value. Use `CHARGE_PARENT` or
*  `CHARGE_USER` instead.
*/
| 'CHARGE_CHILD'
/**
*  Costs attributed to the end user.
*  The user who triggered the parent specialist is charged directly.
*/
| 'CHARGE_USER';

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

export declare type CreateChannelResult = {
    roomId: string;
};

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

export declare type CreateProjectResult = {
    projectId: string;
};

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

export declare type CreateTaskResult = {
    task: MiniAppTask;
};

/**
 *  Data classification inheritance for sub-specialists.
 *
 *  Controls how data classification levels are inherited from parent to child.
 *  Local A2A delegation records this policy as metadata and rejects a downgrade
 *  when both parent and child labels are known enough to compare.
 */
declare type DataClassification = 
/**
*  Child inherits the parent's data classification level.
*  This is the safest option for most use cases.
*/
'INHERIT_FROM_PARENT'
/**
*  Child has an explicit data classification.
*  Must be at same or higher security level than parent.
*/
| {
    EXPLICIT: {
        /**  The explicit classification level (e.g., "CONFIDENTIAL", "PUBLIC"). */
        level: string;
    };
};

export declare function defineApp<const TConfig extends AppConfig>(config: TConfig): TConfig;

/** Preserve the inferred tool signatures for a package-runtime MCP server. */
export declare function defineMcpServer<const TServer extends McpServerDefinition>(server: TServer): TServer;

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

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

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

/**
 *  Specialist avatar/icon source.
 *
 *  The host resolves a bundled path relative to the specialist's source: the app public asset root
 *  for first-party specialists and the verified package artifact root for package contributions.
 */
declare type DisplayIcon = 
/**  Bundled asset under the specialist source's asset root. */
    {
    type: 'bundled';
    /**
     *  Path under the source asset root, such as `/tap-logo.svg` for an app-bundled specialist
     *  or `assets/avatar.png` for a package contribution.
     */
    path: string;
};

/**  Domain grounding configuration for specialist context. */
declare type DomainGrounding = 
/**  Tech stack grounding for coding specialists. */
    {
    type: 'techStack';
    /**  Technologies, frameworks, languages, or tools. */
    items: GroundingItem[];
}
/**  Domain context grounding for non-coding specialists. */
| {
    type: 'domainContext';
    /**  Domain-specific context items: regulations, methodologies, terminology. */
    items: GroundingItem[];
};

export declare type ExactSourceManifestV2 = Readonly<{
    rawBytes: Uint8Array<ArrayBuffer>;
    parsedManifest: SourceManifestV2;
    sha256: string;
    byteLength: number;
}>;

/**
 *  Execution configuration for specialist LLM provider routing.
 *
 *  This configuration determines how and where a specialist sends
 *  LLM requests. It supports multiple execution modes and provider types.
 *
 *  # Default Behavior
 *
 *  If `execution` is `None` in a manifest, the specialist defaults to:
 *  - Mode: `Direct`
 *  - Provider: `OpenRouter`
 *  - Auth: Uses the user's OpenRouter API key from keyring
 *
 *  # Example (JSON5)
 *
 *  ```json5
 *  {
 *    execution: {
 *      mode: "direct",
 *      provider: "open-router",
 *      auth: {
 *        type: "api-key",
 *        credentialRef: "openrouter"
 *      },
 *      timeoutMs: 30000,
 *      maxRetries: 3
 *    }
 *  }
 *  ```
 */
declare type ExecutionConfig = {
    /**  Execution mode (direct, proxied, or fallback). */
    mode?: ExecutionMode;
    /**
     *  Provider type (OpenRouter, CloudflareWorkers, etc.).
     *  Required for Direct mode unless using default OpenRouter.
     */
    provider?: ProviderType | null;
    /**
     *  Custom endpoint URL.
     *  Required for Custom provider type and Proxied mode.
     *  Must be HTTPS for non-localhost URLs.
     *
     *  Format: `https://{specialist-author}.workers.dev/invoke`
     */
    endpoint?: string | null;
    /**  Authentication configuration. */
    auth?: AuthConfig | null;
    /**
     *  Request timeout in milliseconds.
     *  Default: 30000 (30 seconds)
     *  Range: 1000-300000 (1 second to 5 minutes)
     */
    timeoutMs?: number | null;
    /**
     *  Maximum retries on transient failures.
     *  Default: 3
     *  Range: 0-10
     */
    maxRetries?: number | null;
    /**  Optional caps for the reserved welcome built-in provider. */
    welcomeLimits?: WelcomeExecutionLimits | null;
};

/**
 *  How a specialist should execute LLM requests.
 *
 *  This determines the routing strategy for LLM API calls.
 */
declare type ExecutionMode = 
/**
*  Direct execution using user's API keys with known providers.
*  This is the default mode when no execution config is specified.
*/
'direct'
/**
*  Route requests through a custom proxy/worker endpoint.
*  The specialist author's endpoint handles the LLM call.
*/
| 'proxied'
/**
*  Try direct execution first, fall back to proxy on failure.
*  Useful for specialists that want to use user's keys when available
*  but can also function via proxy.
*/
| 'fallback';

/**  Formality preference for authored specialist persona guidance. */
declare type Formality = 'formal' | 'semi-formal' | 'conversational' | 'casual';

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

export 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;
};

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

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

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

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

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

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

/**
 *  One grounding entry (schema 2.0): a noun phrase plus an optional one-line
 *  gotcha. 1.x manifests authored plain strings; those deserialize as a
 *  name with no note.
 */
declare type GroundingItem = {
    /**  Technology, framework, regulation, methodology, or domain term. */
    name: string;
    /**  Optional non-obvious gotcha about this item, one line. */
    note?: string | null;
};

/**
 *  Inheritance specification for parent specialist.
 *
 *  Similar to Dockerfile `FROM`, allows specialists to inherit
 *  attributes from parent specialists with semver version constraints.
 *
 *  # PRD Reference
 *
 *  Section 6.1 defines inheritance behavior:
 *  - Semver wildcards (~, ^, *) for version matching
 *  - Resolution to specific version at mint time
 *  - Inheritable attributes: Maintainers, Spawner prompts, Tools, Permissions, Persona defaults
 *
 *  # Example
 *
 *  ```json5
 *  {
 *    "from": {
 *      "parentId": "zephyr/base-coding-specialist",
 *      "versionConstraint": "^1.0.0"
 *    }
 *  }
 *  ```
 */
declare type InheritanceSpec = {
    /**
     *  Parent specialist ID (e.g., "zephyr/base-coding-specialist").
     *  This is the unique identifier of the specialist to inherit from.
     */
    parentId: string;
    /**
     *  Version constraint with semver wildcards.
     *
     *  Supported formats:
     *  - Exact version: "1.0.0"
     *  - Patch updates (~): "~1.0.0" matches 1.0.x
     *  - Minor updates (^): "^1.0.0" matches 1.x.x
     *  - Latest version: "*"
     */
    versionConstraint: string;
    /**
     *  Resolved version (populated at mint time).
     *
     *  This is the immutable resolved version embedded in minted manifest.
     *  When a specialist is minted, the wildcard constraint is resolved
     *  to a specific version and stored here.
     */
    resolvedVersion?: string | null;
    /**
     *  When the version was resolved (ISO 8601 timestamp).
     *  Populated at mint time along with resolved_version.
     */
    resolvedAt?: string | null;
};

/**  Prompt interpolation settings. */
declare type InterpolationConfig = {
    /**  Whether handlebars interpolation is enabled. */
    enabled?: boolean;
    /**  Whether missing placeholders should fail rendering. */
    strict?: boolean;
    /**  How unknown placeholders should be handled during prompt rendering. */
    unknownPlaceholderPolicy?: UnknownPlaceholderPolicy;
};

export 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;
    };
};

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

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

/** Narrow an SDK rejection without matching user-facing error-message text. */
export declare function isMiniAppHostActionError(error: unknown): error is MiniAppHostActionError;

/**  Jargon intensity preference for authored specialist persona guidance. */
declare type JargonLevel = 'none' | 'minimal' | 'moderate' | 'technical' | 'expert' | 'domain-specific';

export declare type JsonSchema = {
    readonly [key: string]: unknown;
};

/**
 *  Lifecycle status for authoring-time knowledge sources.
 *
 *  Crawl/index progress is intentionally not stored in manifests; that runtime
 *  state belongs to the crawler index keyed by source identity.
 */
declare type KnowledgeSourceStatus = 
/**  Source is eligible for use by the crawler and retrieval pipeline. */
'active'
/**  Source remains available for compatibility but should not be used for new authoring. */
| 'deprecated'
/**  Source is declared but should not be crawled or used. */
| 'disabled';

/**
 *  Licensing model for specialist usage and monetization.
 *
 *  Defines how users are charged (if at all) for using a specialist.
 *  This enables the marketplace to support various business models from
 *  free open-source specialists to commercial premium specialists.
 *
 *  # Example (JSON5)
 *
 *  ```json5
 *  // Free specialist
 *  { licensing: { type: "free" } }
 *
 *  // Paid per use
 *  { licensing: { type: "paid-per-use", pricePerInvocation: 100 } }
 *
 *  // Token markup (20% added to LLM costs)
 *  { licensing: { type: "token-markup", markupPercentage: 20 } }
 *  ```
 */
declare type LicensingModel = 
/**  Free to use, no cost. */
    {
    type: 'free';
}
/**
*  Charged per invocation of the specialist.
*  Price is in the smallest currency unit (e.g., cents).
*/
| {
    type: 'paid-per-use';
    /**  Price per invocation in smallest currency unit. */
    pricePerInvocation: number;
}
/**
*  Percentage markup added to underlying LLM costs.
*  For example, a 20% markup means the user pays 120% of the LLM cost.
*/
| {
    type: 'token-markup';
    /**  Markup percentage (e.g., 20 for 20% markup). */
    markupPercentage: number;
}
/**
*  Requires an external subscription to use.
*  The subscription_url points to where users can subscribe.
*/
| {
    type: 'subscription';
    /**  URL to the subscription management page. */
    subscriptionUrl: string;
}
/**
*  Charged per successful outcome (result-based pricing).
*  New in PRD v0.0.5.
*/
| {
    type: 'outcome-based';
    /**  Price per successful outcome in smallest currency unit. */
    pricePerOutcome: number;
};

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

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

export 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;
};

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

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

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

/**
 *  Maintainer of a specialist.
 *
 *  Represents an individual, organization, or group responsible for the specialist.
 *  Required fields are name and email; url is optional for linking to profiles
 *  or organization pages.
 *
 *  # Example (JSON5)
 *
 *  ```json5
 *  {
 *    name: "Zephyr Cloud",
 *    email: "specialists@zephyr.dev",
 *    url: "https://zephyr.dev"
 *  }
 *  ```
 */
declare type Maintainer = {
    /**  Name of the maintainer (individual, organization, or group). */
    name: string;
    /**  Contact email address for the maintainer. */
    email: string;
    /**  Optional URL to the maintainer's profile, website, or organization page. */
    url?: string | null;
};

/**  Knowledge source declarations authored directly in a specialist manifest. */
declare type ManifestKnowledgeSource = 
/**  Crawlable URL source. */
    {
    type: 'url';
    /**  HTTPS URL to crawl. */
    url: string;
    /**  Crawl depth for this source, constrained to 1..=5. */
    crawlDepth?: number;
    /**  Authoring lifecycle status. */
    status?: KnowledgeSourceStatus;
    /**  Optional human-readable source name. */
    name?: string | null;
    /**  Optional source-specific refresh interval. */
    refreshHours?: number | null;
    /**  Optional authoring tags for grouping sources. */
    tags?: string[];
}
/**  Repository-relative file path. */
| {
    type: 'file';
    /**  Relative path to a file in the project or bundle. */
    path: string;
    /**  Authoring lifecycle status. */
    status?: KnowledgeSourceStatus;
    /**  Optional human-readable source name. */
    name?: string | null;
}
/**  Linked Knowledge Garden plot. */
| {
    type: 'knowledgeGardenPlot';
    /**  Knowledge Garden plot identifier. */
    plotId: string;
    /**  Authoring lifecycle status. */
    status?: KnowledgeSourceStatus;
    /**  Optional human-readable source name. */
    name?: string | null;
};

/**
 *  Pointer to real code, docs, tests, or rubrics (schema 2.0 `references`).
 *
 *  Exactly one of `path` (repository/bundle-relative) or `url` must be set;
 *  validation rejects entries with both or neither.
 */
declare type ManifestReference = {
    /**  Repository- or bundle-relative file path. */
    path?: string | null;
    /**  HTTPS URL to the referenced material. */
    url?: string | null;
    /**  Why the specialist should consult this instead of trusting memory. */
    why: string;
};

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

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

/** Closed elicitation capabilities a package-runtime MCP server may request. */
export declare type McpElicitationMode = 'form' | 'url';

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. */
export 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. */
export 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. */
export declare type McpElicitationResult = {
    action: 'accept' | 'cancel' | 'decline';
    content?: Record<string, MiniAppJsonValue>;
};

/** The tools exposed by one package-runtime MCP server. */
export declare type McpServerDefinition = {
    tools: Record<string, McpServerToolDefinition>;
};

/** One tool implemented by a package-runtime MCP server. */
export declare type McpServerToolDefinition<TArguments extends MiniAppJsonValue = MiniAppJsonValue, TResult extends MiniAppJsonValue = MiniAppJsonValue> = {
    description: string;
    inputSchema: JsonSchema;
    execute(arguments_: TArguments): MiniAppMaybePromise<TResult>;
};

/**  Authoring-time tool exposure policy for a portable MCP template. */
declare type McpToolPolicy = {
    /**  Default exposure behavior for tools discovered from the MCP server. */
    default?: McpToolPolicyDefault;
    /**  Exact upstream tool names to allow. */
    allowedTools?: string[];
    /**  Exact upstream tool names to block. */
    blockedTools?: string[];
    /**  Prefix globs identifying write-capable tools that require consent. */
    writeToolPatterns?: string[];
};

/**  Default exposure posture for a portable MCP template's discovered tools. */
declare type McpToolPolicyDefault = 
/**  Expose every discovered upstream tool unless narrowed elsewhere. */
'exposeAll'
/**  Expose only tools named in the allowlist. */
| 'allowlistOnly'
/**  Expose read tools automatically and require a future consent path for write tools. */
| 'readAutoWriteConsent';

/** Durable outcome of one narrow host action, recoverable after interruption. */
export 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. */
export 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.
 */
export 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;
};

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

export 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.
 */
export declare type MiniAppAttentionKind = 'approval' | 'assignment' | 'reassessment' | 'failure';

export 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.
 */
export declare type MiniAppAuthorizationApi = {
    check(options: MiniAppAuthorizationCheckOptions): Promise<MiniAppAuthorizationCheckResult>;
};

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

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

export declare type MiniAppAuthorizationCheckResult = {
    allowed: boolean;
};

/** Closed discovery taxonomy accepted by `presentation.categories`. */
export declare type MiniAppCategory = 'productivity' | 'developer-tools' | 'creativity' | 'communication' | 'data-and-analytics' | 'business' | 'education' | 'media-and-entertainment' | 'utilities' | 'other';

export 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.
 */
export declare type MiniAppChannelMessage = MiniAppJsonValue;

export 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.
 */
export 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.
 */
export 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.
 */
export declare type MiniAppCodeIntelScope = {
    workspaceId?: string;
    projectId: string;
};

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

export 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. */
export declare type MiniAppCredentialsApi = {
    listHttp(): MiniAppMaybePromise<MiniAppHttpCredentialMetadata[]>;
};

export 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.
 */
export declare type MiniAppDeepLinkTarget = Readonly<{
    kind: string;
    [key: string]: MiniAppJsonValue;
}>;

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

export declare type MiniAppEmbeddingModality = 'text';

export 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;
}>;

export 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;
}>;

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

export 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;
    }>;
};

export 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';
}>;

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

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

export declare type MiniAppFileDeleteReceipt = Readonly<Omit<MiniappUserFileDeleteReceipt, 'deletedAt'> & {
    deletedAt: number;
}>;

/** Stable host error codes used by the user-selected file capability. */
export declare type MiniAppFileErrorCode = MiniappUserFileDomainError['code'];

/**
 * 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.
 */
export declare type MiniAppFileHandle = Readonly<Omit<MiniappUserFileHandle, 'expiresAt'> & {
    expiresAt: number | null;
}>;

export 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;
}>;

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

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

export declare type MiniAppFileProvenance = MiniappUserFileMetadata['provenance'];

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

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

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

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

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

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

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

export 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;
}>;

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

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

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

/**
 * A host-owned action error with a stable, non-secret machine-readable code.
 *
 * The host bounds both fields before they cross the miniapp frame boundary.
 */
export declare type MiniAppHostActionError = Error & {
    readonly code: string;
    readonly name: 'MiniAppHostActionError';
};

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

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

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

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

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

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

export 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;
};

export 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';
};

export 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.
 */
export declare type MiniAppInferenceApi = {
    listModels(): MiniAppMaybePromise<MiniAppInferenceModel[]>;
    send(request: MiniAppInferenceRequest): MiniAppMaybePromise<MiniAppInferenceResult>;
};

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

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

export 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;
};

export 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;
};

export 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.
 */
export 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. */
export declare type MiniAppJsonValue = null | boolean | number | string | MiniAppJsonValue[] | {
    [key: string]: MiniAppJsonValue;
};

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

/** Failures currently defined by the host-managed local-service capability. */
export declare type MiniAppLocalServiceKnownErrorCode = 'local_service.not_declared' | 'local_service.unsupported_platform' | 'local_service.untrusted_package' | 'local_service.permission_denied' | 'local_service.installation_disabled' | 'local_service.integrity_failed' | 'local_service.sandbox_unavailable' | 'local_service.port_exhausted' | 'local_service.spawn_failed' | 'local_service.readiness_timeout' | 'local_service.crash_loop' | 'local_service.host_unavailable' | 'local_service.internal';

/** Exact ready snapshot for one manifest-declared local service generation. */
export 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. */
export 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.
 */
export 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[];
};

export declare type MiniAppManagedSpecialistResult = {
    specialistId: string;
};

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

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

/** Trusted identity available only while a package-runtime MCP tool executes. */
export 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. */
export 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.
 */
export declare type MiniAppNotificationsApi = {
    show(options: {
        message: string;
    }): MiniAppMaybePromise<MiniAppNotificationResult>;
};

/** Stable failures returned by the desktop external-navigation contract. */
export declare type MiniAppOpenExternalErrorCode = 'unsupported-host' | 'authorization-denied' | 'authorization-unavailable' | 'user-gesture-required' | 'stale-installation' | 'origin-rejected' | 'request-expired' | 'native-open-failed';

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.
 */
export 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. */
export declare type MiniAppPlotBacking = 'managed-artifacts' | 'connected-git';

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

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

export 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. */
export declare type MiniAppPlotFile = {
    path: string;
    content: string;
    revision: string;
};

export 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.
 */
export 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. */
export declare type MiniAppPlotSyncState = 'clean' | 'syncing' | 'conflicted' | 'migrating' | 'unavailable';

export 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.
 */
export declare type MiniAppPresenceApi = {
    join(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
    update(options: MiniAppPresenceUpdateOptions): MiniAppMaybePromise<MiniAppPresenceSnapshot>;
    leave(options: MiniAppPresenceAddress): MiniAppMaybePromise<void>;
    subscribe(options: MiniAppPresenceAddress, listener: MiniAppPresenceListener): () => void;
};

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

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

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

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

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

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

export 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>;
};

export 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>;
};

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

export 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.
 */
export declare type MiniAppPrivateStorageApi = {
    open(access?: MiniAppPrivateStorageAccess): MiniAppMaybePromise<MiniAppPrivateStorageHandle>;
};

export 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>;
};

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

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

export 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>;
};

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

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

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

export declare type MiniAppRankedItem<T> = Readonly<{
    id: string;
    value: T;
}>;

/** Bounded semantic receipt rendered, wrapped, fed, and cut by the desktop host. */
export 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. */
export 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. */
export declare type MiniAppReceiptPaperProfile = {
    id: MiniAppReceiptPrinterProfile;
    widthMm: 58 | 80;
    columns: 32 | 48;
};

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

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

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

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

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

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

export 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;
};

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

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

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

/** A permissioned, provenance-stamped artifact snapshot. */
export 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[];
};

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

export 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.
 */
export declare type MiniAppSessionApi = {
    get(): MiniAppMaybePromise<MiniAppSessionEntry>;
    set(value: MiniAppSessionValue): MiniAppMaybePromise<void>;
    clear(): MiniAppMaybePromise<void>;
};

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

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

export 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>;
};

export 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;
};

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

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

export 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;
};

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

export 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;
};

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

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

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

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

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

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

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

/** Caller-selected partition inside the host-derived workspace/package scope. */
export 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.
 */
export 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;
};

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

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

export declare type MiniAppStorageMutationResult = {
    revision: number;
};

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

export 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;
};

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

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

/** Workspace task CRUD plus receipt-backed task creation. */
export 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;
    }>;
};

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

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

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

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

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

export declare type MiniAppTerminalV1Event = MiniAppTerminalV1DataEvent | MiniAppTerminalV1ExitEvent;

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

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

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

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

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

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

export 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>;
};

/**
 * 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.
 */
export 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.
 */
export declare type MiniAppTrrScope = {
    workspaceId?: string;
    dimension: string;
    /** Selects a non-default horizon; omit for the canonical 7-day one. */
    syntheticHorizonSeconds?: 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.
 */
export 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;
};

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

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

declare type MiniappUserFileDomainError = {
    code: 'file_denied' | 'file_cancelled' | 'file_stale' | 'file_revoked' | 'file_unavailable' | 'file_too_large' | 'file_malformed' | 'file_encrypted' | 'file_quota_exceeded' | 'file_unsupported';
    message: 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;
};

export 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;
};

export 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>;
};

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

export 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.
 */
export 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.
 */
export 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.
 */
export declare type MiniAppWorkspaceProfile = {
    workspaceId: string;
    displayName: string;
};

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

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

export 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;
};

export declare type MiniAppZvecFilterValue = boolean | number | string;

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

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

export 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';
    };
}>;

export 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';

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

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

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

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

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

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

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

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

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

/**
 *  Schema 2.0 `models` block: hard constraints plus soft preferences.
 *
 *  `require` filters every candidate and is the only manifest authority that
 *  can reject a user/workspace default; `prefer` is consulted after personal
 *  and workspace defaults (a stale pin must never silently override the
 *  user's chosen model). Parsed from 2.0 wire manifests and drained into the
 *  canonical `preferred_models`/`required_capabilities` fields by the
 *  manifest migration.
 */
declare type ModelsBlock = {
    /**  Hard model constraints. */
    require?: RequiredModelCapabilities | null;
    /**  Ordered soft preferences; rolling aliases preferred over dated ids. */
    prefer?: string[];
};

/**  Workspace-level presence behavior requested by a first-party specialist. */
declare type OmnipresenceSpec = {
    /**  Auto-join every channel. */
    autoJoinChannels?: boolean;
    /**  Include DMs in auto-join. Defaults to false. */
    includeDms?: boolean;
    /**  Pin the specialist in workspace navigation. */
    pinSidebar?: boolean;
};

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

export declare type OpenNavigationOptions = {
    path: string;
};

/**  Package identity selected by one instructional skill reference. */
declare type PackageSkillReference = 
/**  A contribution owned by the same package as the specialist. */
    {
    kind: 'own';
    /**  Exact `agent.skill` contribution ID. */
    contributionId: string;
}
/**
*  Host-resolved immutable package identity.
*
*  Package authors cannot submit this form. The package manager derives it
*  from the owning package before specialist projection.
*/
| {
    kind: 'resolved';
    /**  Exact package installation ID. */
    installationId: string;
    /**  Exact signed package ID. */
    packageId: string;
    /**  Exact active release ID. */
    releaseId: string;
    /**  Exact `agent.skill` contribution ID. */
    contributionId: string;
    /**  Owning workspace for a workspace-installed package. `None` is account-owned. */
    workspaceId?: string | null;
};

/**  Marketplace grouping metadata for partner specialist suites. */
declare type PartnerSuite = {
    /**  Stable marketplace slug for the suite. */
    slug: string;
    /**  Human-readable suite name. */
    displayName: string;
    /**  One-line marketplace positioning text. */
    tagline: string;
    /**  Local public asset path for the suite logo. */
    logoPath: string;
    /**  Optional marketplace category. */
    category?: string | null;
    /**  Optional display ordering hint. */
    displayOrder?: number | null;
};

/**
 *  Permission inheritance mode for spawned sub-specialists.
 *
 *  Determines how child specialists inherit permissions from their parent.
 *  The default mode `ScopeToParent` ensures children can never escalate
 *  beyond parent permissions (AND logic).
 *
 *  # PRD Reference
 *
 *  Section 6.3 (lines 585-586): "Child inherits parent permissions (AND logic, never escalates)"
 */
declare type PermissionInheritance = 
/**
*  Child scoped to parent's permissions (AND logic).
*  Child permissions = Parent permissions intersection Child declared permissions.
*  This is the default and most secure mode.
*/
'SCOPE_TO_PARENT'
/**
*  Child uses own permissions independently.
*  Requires explicit admin approval for the spawn relationship.
*/
| 'INDEPENDENT';

/**  Defines the specialist's persona and expertise area. */
declare type Persona = {
    /**
     *  A description of the specialist's purpose and expertise. The
     *  embedding anchor and identity opener.
     */
    purpose: string;
    /**
     *  Optional structured identity (schema 2.0): who the specialist is and
     *  what sets it apart, promoted from builder-only draft state.
     */
    identity?: PersonaIdentity | null;
    /**
     *  Optional hard rules (schema 2.0): the only place non-negotiables
     *  live, promoted from builder-only draft state.
     */
    constraints?: PersonaConstraints | null;
    /**  Optional communication style preferences for prompt construction. */
    writingStyle?: WritingStyle | null;
} & ({
    /**
     *  Judgment heuristics guiding behavior — merged 1.x `values` +
     *  `attributes` (schema 2.0). Heuristics, not adjectives.
     */
    principles?: string[];
} & {
    /**
     *  Judgment heuristics guiding behavior — merged 1.x `values` +
     *  `attributes` (schema 2.0). Heuristics, not adjectives.
     */
    values?: string[];
});

/**
 *  Hard behavioral rules (schema 2.0). Everything else in the persona is
 *  judgment guidance; these are the non-negotiables.
 */
declare type PersonaConstraints = {
    /**  Rules the specialist must never break. */
    guardrails?: string[];
    /**  Work this specialist deliberately does not do. */
    nonGoals?: string[];
    /**  Conditions that require handing off or asking instead of proceeding. */
    escalationTriggers?: string[];
    /**  How the specialist decides when guidance conflicts. */
    decisionPolicy?: string | null;
};

/**  Structured identity block (schema 2.0). */
declare type PersonaIdentity = {
    /**  One-line role, e.g. "Rust reviewer for TAP's crate workspace". */
    role?: string | null;
    /**  Short prose summary of who this specialist is. */
    summary?: string | null;
    /**  What sets this specialist apart from a competent generalist. */
    differentiators?: string[];
};

/**
 *  Exact immutable identity of one personal skill installation and release.
 *
 *  The installation id selects the user-owned installation, while the release id and artifact
 *  digest pin the immutable content that may be projected into a specialist turn.
 */
declare type PersonalSkillOwner = {
    /**  Exact personal skill installation ID. */
    skillInstallationId: string;
    /**  Exact immutable skill release ID. */
    skillReleaseId: string;
    /**  Exact immutable artifact digest for the selected release. */
    artifactDigest: string;
};

/**  Specifies a preferred AI model for the specialist. */
declare type PreferredModel = {
    /**  Model identifier (e.g., "anthropic/claude-sonnet-4.5"). */
    model: string;
    /**  Optional specific version to pin to (e.g., "20250514"). */
    version?: string | null;
    /**  Optional provider override for this specific model. */
    providerOverride?: ProviderType | null;
};

/**  Privacy and network requirements for a specialist. */
declare type PrivacySettings = {
    /**  Whether this specialist can operate without network access. */
    supportsLocal?: boolean;
    /**  Whether this specialist requires network access to function. */
    requiresNetwork?: boolean;
};

/**  Prompt fallback strategy for model/task resolution. */
declare type PromptFallback = 
/**  Use the default prompt when no specific override exists. */
'default';

/**  Prompt templates for the specialist. */
declare type Prompts = {
    /**
     *  The spawner prompt (schema 2.0): author voice and non-obvious context
     *  only. The single spawner source after migration — legacy
     *  `default.{spawnerPrompt,systemPrompt,extra}` shapes are drained into
     *  this field on load.
     */
    spawner?: string;
    /**
     *  Optional high-scaffolding spawner variant, selected when the resolved
     *  model's prompt profile is `Verbose` (no thinking support, or small
     *  local models). Replaces the 1.x `modelSpecific` override map with a
     *  capability-selected variant instead of model-id string matching.
     */
    guidedSpawner?: string | null;
} & ({
    /**
     *  Prompt rendering/resolution strategy. Serialized as `strategy`
     *  (schema 2.0); the 1.x `promptStrategy` key is still accepted.
     */
    strategy?: PromptStrategy;
} & {
    /**
     *  Prompt rendering/resolution strategy. Serialized as `strategy`
     *  (schema 2.0); the 1.x `promptStrategy` key is still accepted.
     */
    promptStrategy?: PromptStrategy;
});

/**  Prompt strategy settings. */
declare type PromptStrategy = {
    /**  How to resolve missing model/task variants. */
    fallback?: PromptFallback;
    /**  Handlebars interpolation behavior. */
    interpolation?: InterpolationConfig;
};

/**
 *  Supported LLM provider types.
 *
 *  These represent the known providers that can be used in Direct mode.
 *  For custom endpoints, use `ProviderType::Custom` with an endpoint URL.
 */
declare type ProviderType = 
/**
*  OpenRouter API aggregator (default).
*  Supports a wide variety of models via unified API.
*/
'open-router'
/**
*  Cloudflare Workers AI.
*  For specialists using Cloudflare's AI inference.
*/
| 'cloudflare-workers'
/**
*  Amazon Bedrock.
*  For enterprise specialists using AWS infrastructure.
*/
| 'amazon-bedrock'
/**
*  HuggingFace Inference API.
*  OpenAI-compatible serverless inference via HF token.
*/
| 'hugging-face'
/**
*  NVIDIA Build/NIM hosted inference.
*  OpenAI-compatible chat completions via NVIDIA API key.
*/
| 'nvidia'
/**  Reserved built-in route for the first-party welcome specialist. */
| 'the-ai-platform-welcome-builtin'
/**  Reserved built-in route for the first-party Chloe specialist. */
| 'chloe-builtin'
/**
*  Custom endpoint.
*  Requires `endpoint` URL in ExecutionConfig.
*/
| 'custom';

/**  Quota ledger scope for a first-party bypass provider. */
declare type QuotaScope = 
/**  A separate ledger per workspace/user pair. */
'per-user-per-workspace';

/**  Per-user-per-workspace daily/monthly cost cap for a first-party provider. */
declare type QuotaSpec = {
    /**  Scope of the quota ledger. */
    scope: QuotaScope;
    /**  Reset window for the quota counters. */
    window: QuotaWindow;
    /**  Daily cap in USD cents. */
    dailyUsdCents: number;
    /**  Monthly cap in USD cents. */
    monthlyUsdCents: number;
    /**  Reserved provider id that quota-bypass requests route to. */
    bypassProvider: string;
};

/**  Quota reset window for a first-party bypass provider. */
declare type QuotaWindow = 
/**  Daily and monthly counters reset on UTC calendar boundaries. */
'utc-calendar';

/**  Reading-level preference for authored specialist persona guidance. */
declare type ReadingLevel = 'kindergarten' | 'elementary' | 'middle-school' | 'high-school' | 'college' | 'expert';

/**
 * Pure reciprocal-rank fusion over caller-provided SQLite, zvec, or other
 * ranked lists. Earlier lists receive no implicit preference.
 */
export declare function reciprocalRankFusion<T>(lists: readonly (readonly MiniAppRankedItem<T>[])[], options?: {
    /** Per-list weights. Omitted entries default to one. */
    weights?: readonly number[];
    /** RRF rank constant. Defaults to 60. */
    rankConstant?: number;
    limit?: number;
}): Array<MiniAppRankedItem<T> & {
    score: number;
}>;

/**
 *  Authentication schemes a manifest may allow for remote A2A delegation.
 *
 *  These values describe the remote Agent Card security scheme after TAP has
 *  normalized it. They do not grant credentials; they only narrow which remote
 *  auth schemes this specialist may use if Cerbos and the card pin both allow
 *  invocation.
 */
declare type RemoteAuthScheme = 
/**  No remote credential is required. */
'none'
/**  API key based remote authentication. */
| 'apiKey'
/**  OAuth 2.0 remote authentication. */
| 'oauth2'
/**  HTTP bearer remote authentication, including TAP JWT forwarding. */
| 'bearer';

/**
 *  Manifest-authored policy for invoking remote A2A agents.
 *
 *  An absent `remote_delegation` field disables remote delegation entirely. A
 *  present policy is still fail-closed by default: origins and auth schemes must
 *  be explicitly allowlisted before a remote agent can be invoked.
 */
declare type RemoteDelegationPolicy = {
    /**  Allowed remote Agent Card origins or canonical card URLs. */
    agentCardAllowlist?: string[];
    /**  Maximum remote delegation depth allowed by this manifest. */
    maxRemoteDepth?: number;
    /**  Remote authentication schemes this specialist may use. */
    allowedAuthSchemes?: RemoteAuthScheme[];
    /**  Highest data classification this policy permits for remote delegation. */
    dataClassificationCeiling?: DataClassification;
};

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

/**  Optional model requirements a specialist needs before routing. */
declare type RequiredModelCapabilities = {
    /**  Input modalities required by the specialist, e.g. "image" for Figma. */
    inputModalities?: string[];
    /**  Whether the selected model must support tool/function calling. */
    toolUse?: boolean | null;
    /**  Whether the selected model must support reasoning/thinking metadata. */
    reasoning?: boolean | null;
    /**  Whether the selected provider/model route must support hosted web search. */
    webSearch?: boolean | null;
    /**
     *  When `Some(true)`, the runtime selects a provider/model whose
     *  canonical metadata has `tool_result_image_blocks.supported == true`.
     */
    computerUseImageResults?: boolean | null;
    /**
     *  Provider-neutral generation floor (schema 2.0): only models whose
     *  canonical lifecycle release date is on or after this ISO date
     *  (`YYYY-MM-DD`) qualify. "Any 5-gen era model" is
     *  `releasedAfter: "2026-01-01"` plus `reasoning: true` — it composes
     *  with local models and future providers without naming families.
     */
    releasedAfter?: string | null;
};

/**
 *  Resource limits for delegated runtime work.
 *
 *  `maxExecutionTimeSec` controls delegated runtime timeout cancellation.
 *  `maxOutputTokens` is the aggregate completion-token budget passed to the
 *  delegated runtime for the child turn.
 *  CPU and memory values are advisory scheduling metadata today; they are
 *  persisted for status/telemetry but are not hard-enforced by the local runtime.
 *
 *  # Specta Compliance
 *
 *  All numeric fields use `i32` instead of `u64`/`usize` for JavaScript safety.
 *  CPU and memory specifications use `String` for flexibility (e.g., "1 vCPU", "512 MB").
 *
 *  # Example (JSON)
 *
 *  ```json
 *  {
 *    "cpuPerInstance": "1 vCPU",
 *    "memoryPerInstance": "512 MB",
 *    "maxExecutionTimeSec": 300,
 *    "maxOutputTokens": 50000
 *  }
 *  ```
 */
declare type ResourceLimits = {
    /**
     *  Advisory CPU allocation metadata (e.g., "1 vCPU", "500m", "0.5 cores").
     *  Flexible string format to support schedulers; not hard-enforced locally.
     */
    cpuPerInstance: string;
    /**
     *  Advisory memory allocation metadata (e.g., "512 MB", "1 GB", "1024 MiB").
     *  Flexible string format to support schedulers; not hard-enforced locally.
     */
    memoryPerInstance: string;
    /**
     *  Maximum execution time in seconds.
     *  After this duration, delegated runtime cancellation ends the child turn
     *  and marks the spawned instance failed.
     *  Use `i32` for JavaScript Number safety (max ~2.1 billion seconds).
     */
    maxExecutionTimeSec: number;
    /**
     *  Aggregate completion-token budget for the child turn.
     *  Passed to the delegated runtime before execution starts.
     *  Use `i32` for JavaScript Number safety.
     */
    maxOutputTokens: number;
};

/**
 * Runs one specialist turn and resolves with a discriminated outcome.
 *
 * Never rejects: every failure path resolves as `{ ok: false }` with an
 * enumerated reason, so a caller cannot accidentally treat "the workspace
 * withheld a grant" and "the provider is down" the same way.
 *
 * ```ts
 * const outcome = await runSpecialist({
 *   specialist: sdk.specialist,
 *   workspaceId,
 *   specialistId: 'standup-drafter@0.2.0',
 *   content: 'Draft my standup.',
 *   parse: (text) => Draft.safeParse(JSON.parse(text)).data,
 * });
 * if (outcome.ok) render(outcome.data);
 * else showMessage(outcome.failure.message);
 * ```
 */
export declare function runSpecialist<TData = string>(options: RunSpecialistOptions<TData>): Promise<SpecialistOutcome<TData>>;

export declare type RunSpecialistOptions<TData = string> = {
    /**
     * Defaults to `sdk.specialist`, so most callers omit it.
     *
     * Supply it to inject a fake in a test, or to pass a capability you already
     * hold. Typed as only the method this needs, so a caller that narrowed its own
     * dependency to `Pick<MiniAppSpecialistApi, 'runTurnWithTools'>` — the honest
     * shape for code that runs turns and nothing else — can pass it straight
     * through.
     */
    specialist?: Pick<MiniAppSpecialistApi, 'runTurnWithTools'> | undefined;
    /** Defaults to the surface's own workspace. */
    workspaceId?: string;
    /**
     * The specialist your package declares, in its resolved `<name>@<version>`
     * form — for example `standup-drafter@0.2.0`.
     */
    specialistId: string;
    /** The prompt to send. */
    content: string;
    /**
     * Channel to run in. **Omit it** to run channel-less: the host uses a private
     * room it owns for your `(workspace, package, specialist)`, which needs no
     * `channels.*` permission and never appears in the user's channel list.
     *
     * That room is persistent, so repeat calls continue one conversation. This is
     * what makes a regenerate affordance meaningful — and why a channel-less turn
     * is not fire-and-forget.
     */
    channelId?: string;
    interactionMode?: MiniAppSpecialistInteractionMode;
    /**
     * Model to run with. Omit to use the workspace's choice, which is normally what
     * a surface wants — naming a model in app code pins it.
     */
    modelOverride?: null | string;
    /** Host-enforced range is 1–90000 ms. Defaults to 60000. */
    timeoutMs?: number;
    /**
     * Turn the answer text into your own type.
     *
     * Return `undefined` to reject the answer as `off-contract`. Omit `parse` and
     * the data is the raw text.
     */
    /**
     * Turn the answer text into your type. Return `null` or `undefined` to reject
     * it as `off-contract`.
     *
     * Both rejection values are accepted because a parser returning `T | null` is
     * the common convention — a Zod-backed one especially — and demanding
     * `undefined` would make every such call site write `?? undefined`.
     */
    parse?: (text: string) => TData | null | undefined;
};

/**
 *  Diagnostic sandbox-isolation hint for spawned child specialists.
 *
 *  Current A2A child delegation does not create separate VFS/session/process
 *  sandboxes for these values. The chosen value is retained in spawn metadata
 *  and UI diagnostics only; do not treat it as an enforced security boundary.
 */
declare type SandboxIsolation = 
/**  Diagnostic hint for lightweight isolation. */
'lightweight'
/**  Diagnostic hint for full isolation. */
| 'full';

/**
 * 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 sdk: MiniAppPlatformApi;

export 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>;
};

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

/**  Controls whether a specialist may activate skills beyond its preferred set. */
declare type SkillAccess = 
/**  Preferred skills guide selection without excluding other available skills. */
'open'
/**  Only skills declared by the specialist or its selected task may be activated. */
| 'restricted';

/**  Skill reference with backward-compatible bare-string support. */
declare type SkillRef = 
/**  Backward-compatible skill name. */
string
/**  Detailed skill reference with source and optional version. */
| {
    /**  Skill name. */
    name: string;
    /**  Skill source registry. */
    source?: SkillSource;
    /**  Optional semver version or range. */
    version?: string | null;
    /**  Exact personal selector required only when `source` is `agentskills`. */
    personal?: PersonalSkillOwner | null;
    /**  Exact workspace selector required for a workspace-owned `agentskills` skill. */
    workspace?: WorkspaceSkillOwner | null;
    /**  Package selector required only when `source` is `package`. */
    package?: PackageSkillReference | null;
};

/**  Source registry for a specialist skill reference. */
declare type SkillSource = 
/**  Skill bundled with the app. */
'bundled'
/**  Skill installed through the Agent Skills authority. */
| 'agentskills'
/**  Skill loaded from a local skills directory. */
| 'local'
/**  Immutable skill contributed by an installed package. */
| 'package';

/**
 *  Specialist- or task-level preferences and optional activation restriction.
 *
 *  Preference order is authored order. `open` is intentionally the default:
 *  declaring a useful skill should not silently hide every other installed skill.
 */
declare type SkillUsePolicy = {
    /**  Skills that should be considered before other available skills. */
    preferred?: SkillRef[];
    /**  Activation boundary for this policy. */
    access?: SkillAccess;
};

declare const SOURCE_MANIFEST_SCHEMA_VERSION = 2;

export declare type SourceManifestArtifactV2 = Readonly<{
    path: string;
    digest: string;
    length: number;
}>;

export declare type SourceManifestClosureV2 = Readonly<{
    artifacts: readonly SourceManifestArtifactV2[];
    targetLocks: readonly SourceManifestTargetV2[];
    permissions: readonly string[];
    runtimeEffects: readonly SourceManifestRuntimeEffectV2[];
}>;

export declare type SourceManifestLocalDisplayV2 = Readonly<{
    name?: string;
    slug?: string;
}>;

export declare type SourceManifestRuntimeEffectV2 = Readonly<{
    kind: string;
    resources: readonly string[];
}>;

export declare type SourceManifestTargetV2 = Readonly<{
    target: string;
    path: string;
    digest: string;
    length: number;
}>;

export declare type SourceManifestV2 = Readonly<{
    schemaVersion: typeof SOURCE_MANIFEST_SCHEMA_VERSION;
    versionLabel: string;
    localDisplay?: SourceManifestLocalDisplayV2;
    targets: readonly SourceManifestTargetV2[];
    artifacts: readonly SourceManifestArtifactV2[];
    permissions: readonly string[];
    runtimeEffects: readonly SourceManifestRuntimeEffectV2[];
}>;

/**
 *  Configuration for a spawnable sub-specialist.
 *
 *  Defines all parameters for a child specialist that can be spawned
 *  by a parent specialist. These configurations are declared at schema
 *  time. `childSpecialistId: "*"` is a wildcard relationship that resolves to
 *  a concrete child ID at spawn time.
 *
 *  # PRD Reference
 *
 *  Section 6.3 (lines 562-582) defines the schema structure.
 *
 *  # Governance Controls
 *
 *  - Parent must declare exact child specialists or an explicit wildcard policy at schema time
 *  - Child inherits parent permissions (AND logic, never escalates)
 *  - Resource limits govern delegated runtime cancellation and aggregate completion-token budgets
 *  - Admin approval required for new spawn relationships
 *  - Default spawn depth: 3 levels; organization setting hard-capped at 5
 *  - Circular dependencies blocked at validation
 *
 *  # Example (JSON)
 *
 *  ```json
 *  {
 *    "childSpecialistId": "@org/pdf-parser@1.0.0",
 *    "maxConcurrentInstances": 10,
 *    "maxInstancesPerDay": 100,
 *    "permissionInheritance": "SCOPE_TO_PARENT",
 *    "dataClassification": "INHERIT_FROM_PARENT",
 *    "resourceLimits": {
 *      "cpuPerInstance": "1 vCPU",
 *      "memoryPerInstance": "512 MB",
 *      "maxExecutionTimeSec": 300,
 *      "maxOutputTokens": 50000
 *    },
 *    "costAttribution": "CHARGE_PARENT",
 *    "sandboxIsolation": "lightweight",
 *    "allowedTools": ["file_read", "text_extraction"]
 *  }
 *  ```
 */
declare type SpawnableSubSpecialist = {
    /**
     *  Child specialist ID with version (e.g., "@org/pdf-parser@1.0.0"),
     *  or `*` to apply this spawn policy to any specialist in the current
     *  specialist store.
     */
    childSpecialistId: string;
    /**
     *  Maximum concurrent instances of this sub-specialist.
     *  Use i32 for JavaScript Number safety.
     *  Default: 10
     */
    maxConcurrentInstances?: number;
    /**
     *  Maximum instances per day to prevent runaway spawning.
     *  Use i32 for JavaScript Number safety.
     *  Default: 100
     */
    maxInstancesPerDay?: number;
    /**
     *  How the child inherits parent permissions.
     *  Default: `ScopeToParent` (AND logic, never escalates)
     */
    permissionInheritance?: PermissionInheritance;
    /**
     *  Whether this spawn relationship is approved to bypass parent scoping.
     *
     *  `INDEPENDENT` children use their own access control and tooling, so the
     *  relationship must carry explicit admin approval before runtime accepts it.
     */
    independentSpawnApproved?: boolean;
    /**
     *  Data classification mode for the child.
     *  Default: `InheritFromParent`
     */
    dataClassification?: DataClassification;
    /**  Resource limits for delegated runtime cancellation and aggregate completion-token budgets. */
    resourceLimits?: ResourceLimits;
    /**
     *  Cost attribution model.
     *  Default: `ChargeParent`
     */
    costAttribution?: CostAttribution;
    /**
     *  Diagnostic delegated sandbox hint retained in spawn metadata.
     *
     *  Current local delegation does not create separate VFS/session/process
     *  sandboxes for these values.
     *
     *  Default: `Lightweight`
     */
    sandboxIsolation?: SandboxIsolation;
    /**
     *  Optional per-child delegation depth override.
     *
     *  Values are clamped to the supported 1-5 range and capped by the
     *  organization maximum delegation depth at runtime.
     */
    maxDepthOverride?: number | null;
    /**
     *  Additional tool restriction for this spawn relationship.
     *
     *  Empty means this edge adds no extra narrowing: the child uses its own
     *  declared tools, still intersected with the parent's effective tools.
     *  Non-empty means the child is restricted to the intersection of parent
     *  effective tools, child declared tools, and this list. Empty is not a
     *  deny-all sentinel.
     */
    allowedTools?: string[];
    /**  Authoring hint for how aggressively the parent should invoke this child. */
    invocationPolicy?: SpawnInvocationPolicy;
};

/**  Authoring hint for when a parent specialist should invoke a child. */
declare type SpawnInvocationPolicy = 
/**  Suggest delegation and require user consent before spawning. */
'suggest-with-consent'
/**  Allow the orchestrator to spawn the child automatically when routing confidence is high. */
| 'auto-spawn'
/**  Always delegate matching work to the child specialist. */
| 'always-delegate';

/**  Routing cues authored by a specialist creator. */
declare type SpecialistConfidenceHints = {
    /**  Cues that should increase routing confidence for this specialist. */
    positiveCues?: string[];
    /**  Cues that should decrease routing confidence for this specialist. */
    negativeCues?: string[];
    /**  Guidance for ambiguous matches. */
    ambiguityGuidance?: string | null;
    /**  Guidance for when another specialist or a human should handle the request. */
    fallbackGuidance?: string | null;
};

/**  Authored eval-gate configuration persisted with a specialist. */
declare type SpecialistEvalGateConfig = {
    /**  Whether gate failures warn, block, or are disabled. */
    policy?: SpecialistEvalGatePolicy;
    /**  Benchmark suite IDs required to satisfy this gate. */
    requiredSuites?: string[];
    /**  Minimum aggregate benchmark score from 0.0 to 1.0. */
    minimumOverallScore?: number | null;
    /**  Require reports to match the current specialist snapshot hash. */
    requireCurrentSnapshot?: boolean;
    /**  Require specialist runs to beat a raw-prompt baseline. */
    requireBeatsRawPrompt?: boolean;
    /**  Optional latency, throughput, and error thresholds. */
    performance?: SpecialistPerformanceGateConfig;
};

/**  Aggregated eval error summary for publish gate diagnostics. */
declare type SpecialistEvalGateErrorSummary = {
    /**  Optional machine-readable error code. */
    code?: string | null;
    /**  Human-readable error summary. */
    message: string;
    /**  Number of occurrences represented by this summary. */
    count: number;
    /**  Optional scenario associated with this error. */
    scenarioId?: string | null;
};

/**  Publish gate policy for benchmark/evaluation checks. */
declare type SpecialistEvalGatePolicy = 
/**  Do not apply eval gates. */
'off'
/**  Surface stale, missing, or failing evals without blocking publish. */
| 'warn'
/**  Block publish when configured gates fail. */
| 'block';

/**  Persisted eval gate result for the current authored specialist snapshot. */
declare type SpecialistEvalGateResults = {
    /**  Gate status after evaluating configured thresholds. */
    status?: SpecialistEvalGateStatus;
    /**  ISO 8601 timestamp when these results were measured. */
    evaluatedAt?: string | null;
    /**  Specialist snapshot hash used to detect stale results. */
    specialistSnapshotHash?: string | null;
    /**  Model used for the representative result. */
    modelId?: string | null;
    /**  Benchmark/eval run mode used for the representative result. */
    runMode?: string | null;
    /**  Suite IDs represented by the result. */
    suiteIds?: string[];
    /**  Report IDs represented by the result. */
    reportIds?: string[];
    /**  Aggregate score from 0.0 to 1.0, when measured. */
    overallScore?: number | null;
    /**  Whether specialist performance beat a raw-prompt baseline. */
    beatsRawPrompt?: boolean | null;
    /**  Observed latency, throughput, and error metrics. */
    performance?: SpecialistObservedPerformance;
    /**  Aggregated errors from the gate run. */
    errors?: SpecialistEvalGateErrorSummary[];
};

/**  Current status of persisted eval gate results. */
declare type SpecialistEvalGateStatus = 
/**  No current gate result is available. */
'unmeasured'
/**  Configured gates pass. */
| 'passing'
/**  Gates are incomplete, stale, or under warning thresholds. */
| 'warning'
/**  One or more configured gates failed. */
| 'failing';

/** A failed turn, with copy safe to show and optional non-secret detail. */
export declare type SpecialistFailure = {
    reason: SpecialistFailureReason;
    /** One sentence, user-facing. Override it if your product voice differs. */
    message: string;
    /**
     * Extra context for logs or a details affordance — the raw answer for
     * `off-contract`, the host's error message otherwise. Non-secret, but not
     * guaranteed to be friendly.
     */
    detail?: string;
    /**
     * Stable recovery code from the host, when it set one — e.g.
     * `package-mcp-activation-required`, which means "activate the package's MCP
     * server in Settings", not "retry".
     *
     * Distinct from `reason`: `reason` is this SDK's enumerated classification,
     * `code` is the host's own routable identifier passed through untranslated.
     */
    code?: string;
};

/**
 * Why a specialist turn produced no usable answer.
 *
 * Each reason maps to a distinct cause, so a surface can say something accurate
 * instead of collapsing every failure into one retry message. The distinction
 * that matters most in practice is `empty-completion` (a model or provider
 * problem) versus `off-contract` (the model answered, but not in the shape the
 * app asked for) — identical from the outside, opposite fixes.
 */
export declare type SpecialistFailureReason = 
/** This host predates `runTurnWithTools`. Nothing to do but update the app. */
'unsupported-host'
/** A required grant is withheld for this workspace. */
| 'denied'
/** The turn completed but carried no text at all. */
| 'empty-completion'
/** Text came back, but `parse` rejected it. */
| 'off-contract'
/** The turn itself failed — a backend, model, or host error. */
| 'turn-failed';

/**
 * Strict JSON specialist manifest authored inside a TAP Miniapp package.
 * Identity fields are explicit and legacy host-loader fields are excluded.
 */
export declare type SpecialistManifest = Omit<SpecialistManifestWire, 'name' | 'slug' | 'version' | 'schemaVersion' | 'preferredModels' | 'requiredCapabilities' | 'knowledgeGardens' | 'domainGrounding' | 'usesTsxPrompts' | 'persona' | 'capabilities' | 'prompts' | 'skills'> & {
    name: string;
    slug: string;
    version: string;
    schemaVersion: '2.0.0';
    persona: Omit<SpecialistManifestWire['persona'], 'attributes' | 'techStack' | 'values'>;
    capabilities: Omit<SpecialistManifestWire['capabilities'], 'descriptions' | 'examples'>;
    prompts: Omit<SpecialistManifestWire['prompts'], 'default' | 'modelSpecific' | 'promptStrategy' | 'tasks'>;
    skills?: Omit<SkillUsePolicy, 'preferred'> & {
        preferred?: Array<string | SpecialistPackageSkill | SpecialistNonPackageSkill>;
    };
    models?: ModelsBlock;
};

/**
 *  A specialist manifest defining an AI specialist's identity, capabilities,
 *  and execution requirements.
 *
 *  This is the core configuration for a specialist agent in The AI Platform
 *  orchestration system. Manifests can be authored in JSON5, JSONC, YAML, or
 *  TOON format for developer flexibility.
 *
 *  # Example (JSON5)
 *
 *  ```json5
 *  {
 *    name: "rust-backend",
 *    displayName: "Rust Backend Specialist",
 *    version: "1.0.0",
 *    persona: {
 *      purpose: "Expert in Rust backend development",
 *      tech_stack: ["rust", "tokio", "axum", "sqlx"]
 *    },
 *    capabilities: {
 *      tags: ["rust", "backend", "api", "async"],
 *      descriptions: {
 *        primary: "Helps with Rust backend development including async code, APIs, and database integration"
 *      }
 *    },
 *    prompts: {
 *      default: {
 *        spawnerPrompt: "You are an expert Rust backend developer..."
 *      }
 *    },
 *    preferred_models: [
 *      { model: "anthropic/claude-sonnet-4.5", version: "20250514" }
 *    ],
 *    privacy: {
 *      supports_local: false,
 *      requires_network: true
 *    }
 *  }
 *  ```
 */
declare type SpecialistManifestWire = {
    /**
     *  Unique per-version identifier for the specialist.
     *
     *  Legacy flat manifests keep their authored value. Version-folder manifests
     *  derive this as `{slug}@{version}` so multiple versions can coexist.
     */
    name?: string;
    /**
     *  Version-independent logical identity for this specialist.
     *
     *  Older manifests omit this field; the loader defaults it to `name` so
     *  existing single-version specialists continue to resolve unchanged.
     */
    slug?: string;
    /**
     *  Human-readable display name (e.g., "Rust Backend Specialist").
     *  Shown in the UI when suggesting or listing specialists.
     */
    displayName: string;
    /**
     *  Semantic version of this manifest (e.g., "1.0.0").
     *  Enables specialist versioning and pinning.
     */
    version?: string;
    /**
     *  Schema version for the specialist manifest format (semver).
     *  Ensures platform compatibility as the schema evolves.
     *  Example: "1.0.0"
     */
    schemaVersion?: string | null;
    /**
     *  List of maintainers responsible for this specialist.
     *  At least one maintainer with name and email is required for marketplace listing.
     */
    maintainers?: Maintainer[];
    /**  Optional marketplace grouping metadata for partner specialist suites. */
    partnerSuite?: PartnerSuite | null;
    /**
     *  Availability level controlling visibility in the marketplace.
     *  Default: Public (listed in marketplace, discoverable by all).
     */
    availability?: Availability;
    /**
     *  Legal license identifier (SPDX format preferred, e.g., "MIT", "Apache-2.0").
     *  Required for marketplace listing.
     */
    license?: string | null;
    /**
     *  Licensing/pricing model for the specialist.
     *  Determines how users are charged for using this specialist.
     *  Default: Free.
     */
    licensing?: LicensingModel | null;
    /**
     *  Parent specialist for attribute inheritance (FROM directive).
     *
     *  Functions like Dockerfile `FROM`. Child specialists inherit attributes
     *  from parent with specific merge strategies:
     *  - maintainers: APPEND (child authors add to parent's list)
     *  - prompts.spawner: REPLACE (child overrides parent prompt)
     *  - prompts.task: DEEP_MERGE (child adds/overrides specific tasks)
     *  - tools: DEEP_MERGE (child adds tools, overrides configs)
     *  - permissions: AND logic (child cannot escalate beyond parent)
     *  - persona: REPLACE (child defines own identity)
     *  - capabilities.tags: APPEND (accumulate capabilities)
     *
     *  # PRD Reference
     *
     *  Section 6.1 (From/Inheritance, lines 473-507)
     */
    from?: InheritanceSpec | null;
    /**  The specialist's persona defining purpose and expertise. */
    persona: Persona;
    /**
     *  Capabilities defining what this specialist can help with.
     *  Used for semantic routing and matching user queries.
     */
    capabilities: Capabilities;
    /**  Prompt templates for the specialist. */
    prompts: Prompts;
    /**
     *  First-class routable task lanes (schema 2.0).
     *
     *  The single home for a task's routing descriptor, prompt addendum,
     *  examples, and knowledge/model/eval hooks. Legacy `prompts.tasks` +
     *  `capabilities.descriptions["task:*"]` pairs are drained into this
     *  list by the manifest migration.
     */
    tasks?: SpecialistTask[];
    /**
     *  Preferred AI models for this specialist, in priority order.
     *  Optional on the wire (schema 2.0 authors `models.prefer` instead;
     *  the migration drains it into this field).
     */
    preferredModels?: PreferredModel[];
    /**  Optional capability requirements used to filter preferred models. */
    requiredCapabilities?: RequiredModelCapabilities | null;
    /**  Privacy and network requirements for this specialist. */
    privacy: PrivacySettings;
    /**
     *  Optional execution configuration for custom provider routing.
     *
     *  If not specified, defaults to Direct mode with OpenRouter provider
     *  using the user's OpenRouter API key from the keyring.
     */
    execution?: ExecutionConfig | null;
    /**
     *  Spawnable sub-specialists that this specialist can delegate tasks to.
     *
     *  Sub-specialists are fine-tuned specialists that a parent can spawn for
     *  specific tasks. The parent controls which sub-specialists can be invoked
     *  rather than requiring users to add them manually.
     *
     *  # PRD Reference
     *
     *  Section 6.3 (lines 550-592) defines spawnable sub-specialists.
     *
     *  # Use Cases
     *
     *  - Document Processing: Contract Review spawns PDF Parser sub-specialists
     *  - Research Delegation: Investment Research spawns Sector Analyst sub-specialists
     *  - Code Analysis: Code Reviewer spawns Security Scanner sub-specialist
     *
     *  # Governance Controls
     *
     *  - Must declare exact children or `childSpecialistId: "*"` at schema time (no undeclared
     *    dynamic spawning)
     *  - Child inherits parent permissions (AND logic, never escalates)
     *  - Resource limits govern delegated runtime cancellation and aggregate completion-token
     *    budgets
     *  - Default spawn depth: 3 levels; organization setting hard-capped at 5
     *  - Circular dependencies blocked at validation
     */
    spawnableSubSpecialists?: SpawnableSubSpecialist[] | null;
    /**
     *  Remote A2A delegation policy authored by this specialist.
     *
     *  When absent, remote delegation is disabled for this specialist. When
     *  present, runtime authorization must still intersect this policy with
     *  Cerbos decisions, card hash pinning, depth limits, auth scheme, and data
     *  classification checks.
     */
    remoteDelegation?: RemoteDelegationPolicy | null;
    /**
     *  Public A2A Agent Card publication metadata for this specialist.
     *
     *  This metadata is descriptive only. It does not grant remote delegation
     *  authority and cannot carry credentials, tenant policy, or signing keys.
     */
    agentCard?: AgentCardManifest | null;
    /**
     *  History freshness threshold in hours (default: 24 hours).
     *
     *  Messages older than this threshold are replaced with summaries in the agent's context.
     *  This helps manage context window limits while preserving historical context.
     *
     *  - If None or 0, all history is included (no summarization)
     *  - If Some(n), messages older than n hours are summarized
     *
     *  # Example
     *
     *  ```json5
     *  {
     *    historyFreshnessHours: 24  // Summarize messages older than 24 hours
     *  }
     *  ```
     */
    historyFreshnessHours?: number | null;
    /**
     *  Knowledge Garden plots linked to this specialist.
     *
     *  Restricts file access to sourceDir and symlinkDirs of linked plots.
     *  When a specialist has linked Knowledge Gardens, all command execution
     *  is sandboxed to only access directories from those plots.
     *
     *  # Example (JSON5)
     *
     *  ```json5
     *  {
     *    knowledgeGardens: ["plot-id-1", "plot-id-2"]
     *  }
     *  ```
     */
    knowledgeGardens?: string[];
    /**  First-class authored knowledge sources for crawler and retrieval consumers. */
    knowledgeSources?: ManifestKnowledgeSource[];
    /**
     *  Pointers to real code, docs, tests, or rubrics instead of paraphrase
     *  (schema 2.0). The composed prompt renders these as one-line pointers
     *  that the model can inspect through its available tools.
     */
    references?: ManifestReference[];
    /**
     *  Access control configuration for this specialist.
     *
     *  Defines fine-grained access control rules using ABAC (Attribute-Based Access Control)
     *  and ReBAC (Relationship-Based Access Control).
     *
     *  # PRD Reference
     *
     *  Section 6.2 (lines 508-549) defines the permission system with:
     *  - Visibility levels (public/internal/private/restricted)
     *  - Group-based access control (required/deny groups)
     *  - Tag-based access control (user attributes)
     *  - Autonomy ceilings (listen/plan/do)
     *  - MFA requirements
     *  - Advanced Cerbos policy conditions
     *
     *  # Example (JSON5)
     *
     *  ```json5
     *  {
     *    accessControl: {
     *      visibility: "internal",
     *      requiredGroups: ["okta:engineering"],
     *      requiredTags: ["cost-center:R&D"],
     *      minAutonomyCeiling: "plan",
     *      requireMfaVerified: true
     *    }
     *  }
     *  ```
     *
     *  If not specified, defaults to public visibility with no restrictions.
     */
    accessControl?: AccessControl | null;
    /**
     *  Preferred skills and optional activation restriction for this specialist.
     *
     *  Skills are external capabilities following the Agent Skills specification.
     *  Preferred skills are injected first. With the default `open` access,
     *  other installed skills remain available for on-demand activation. Set
     *  access to `restricted` only when the specialist must not use anything
     *  beyond its own and its selected task's declared preferences.
     *
     *  Skills provide specialized capabilities like:
     *  - PDF processing
     *  - Database operations
     *  - API integrations
     *  - Specialized analysis
     *
     *  # Progressive Disclosure
     *
     *  - Level 1 (Current): Only metadata (name + description) is injected (~100 tokens per skill)
     *  - Level 2: Full instructions loaded on-demand via `activate_skill`
     *  - Level 3: Bounded supporting text loaded via `read_skill_resource`
     *
     *  # Example (JSON5)
     *
     *  ```json5
     *  {
     *    skills: {
     *      preferred: ["pdf-processing", "database-query", "api-integration"],
     *      access: "open"
     *    }
     *  }
     *  ```
     *
     *  If omitted, the specialist has no preferences and may use any available skill.
     */
    skills?: SkillUsePolicy;
    /**
     *  Authored tool visibility policy for this specialist.
     *
     *  Runtime enforcement always applies the platform's built-in guardrails
     *  first, then narrows the remaining candidate set using this contract.
     */
    tooling?: SpecialistTooling | null;
    /**
     *  Allows this specialist to propose local skill drafts through `author_skill`.
     *
     *  Defaults to false so community and legacy specialists cannot expand the
     *  user's skill surface unless their manifest opts in explicitly.
     */
    canAuthorSkills?: boolean | null;
    /**  Durable orchestration metadata for routing, fan-out, tool posture, and eval gates. */
    orchestration?: SpecialistOrchestrationMetadata;
    /**  Optional omnipresence contract for first-party workspace specialists. */
    omnipresence?: OmnipresenceSpec | null;
    /**  Optional per-user quota contract for first-party bypass providers. */
    quota?: QuotaSpec | null;
    /**  Optional specialist avatar/icon contract. */
    displayIcon?: DisplayIcon | null;
} & ({
    /**
     *  Domain grounding configuration for context-aware specialist behavior.
     *
     *  PRD Section 7.5 defines two types of grounding:
     *  - **TechStack**: For coding specialists (frameworks, languages, tools)
     *  - **DomainContext**: For non-coding specialists (regulations, methodologies, terminology)
     *
     *  This is the PRD-compliant field with type discriminator. For backwards
     *  compatibility, `persona.tech_stack` is still supported as a fallback.
     *
     *  # Example (JSON5)
     *
     *  ```json5
     *  {
     *    domainGrounding: {
     *      type: "techStack",
     *      items: ["React 18", "TypeScript 5", "shadcn/ui", "Tailwind CSS"]
     *    }
     *  }
     *  ```
     */
    grounding?: DomainGrounding | null;
} & {
    /**
     *  Domain grounding configuration for context-aware specialist behavior.
     *
     *  PRD Section 7.5 defines two types of grounding:
     *  - **TechStack**: For coding specialists (frameworks, languages, tools)
     *  - **DomainContext**: For non-coding specialists (regulations, methodologies, terminology)
     *
     *  This is the PRD-compliant field with type discriminator. For backwards
     *  compatibility, `persona.tech_stack` is still supported as a fallback.
     *
     *  # Example (JSON5)
     *
     *  ```json5
     *  {
     *    domainGrounding: {
     *      type: "techStack",
     *      items: ["React 18", "TypeScript 5", "shadcn/ui", "Tailwind CSS"]
     *    }
     *  }
     *  ```
     */
    domainGrounding?: DomainGrounding | null;
});

/**
 *  Portable MCP template bundled with a specialist definition.
 *
 *  Templates are install-time blueprints only. They must be materialized into
 *  the managed workspace MCP server store before a specialist can use them.
 */
declare type SpecialistMcpTemplate = {
    /**  Stable identifier used to match existing project/workspace/org MCP entries. */
    id?: string | null;
    /**  Template/server display name used when pre-filling the MCP installer. */
    name: string;
    /**  Whether this template must be connected before the specialist can run. */
    required?: boolean;
    /**  Preferred materialization scope. Defaults to the active project when present. */
    preferScope?: SpecialistMcpTemplateScope | null;
    /**  MCP transport definition to prefill in the installer. */
    transport: SpecialistMcpTemplateTransport;
    /**  Requested upstream tool names. When present, this becomes the MCP tool allowlist. */
    tools?: string[];
    /**  Optional policy metadata for upstream MCP tool exposure. */
    toolPolicy?: McpToolPolicy | null;
    /**  Optional manually authored tools to prefill into the installer. */
    manualTools?: SpecialistMcpTemplateTool[];
};

/**
 *  Environment variable requirement for a portable MCP template.
 *
 *  Secret-backed rows may declare metadata like `description`, but they must
 *  never persist literal secret values in the specialist definition.
 */
declare type SpecialistMcpTemplateEnvVar = {
    /**  Environment variable name (for example `GITHUB_TOKEN`). */
    key: string;
    /**  Optional fixed non-secret value that should be prefilled during install. */
    value?: string | null;
    /**  Whether the user must provide this value during installation. */
    secret?: boolean;
    /**  Optional guidance shown when installing the template. */
    description?: string | null;
};

/**  Preferred scope for a portable MCP template when it is materialized. */
declare type SpecialistMcpTemplateScope = 
/**  Prefer the active project when one exists; otherwise fall back to workspace scope. */
'projectIfPresent'
/**  Materialize the MCP server into the active project. */
| 'project'
/**  Materialize the MCP server into the active workspace. */
| 'workspace'
/**  Materialize the MCP server for the organization. */
| 'org';

/**
 *  Manual tool definition bundled with a portable MCP template.
 *
 *  These tools are not executed directly from the specialist manifest. Instead,
 *  they prefill the existing MCP server setup flow so a user can materialize
 *  the template into their workspace server inventory.
 */
declare type SpecialistMcpTemplateTool = {
    /**  Unique tool identifier inside the server namespace. */
    name: string;
    /**  Human-readable description surfaced in the MCP editor. */
    description: string;
    /**  JSON Schema describing the tool parameters. */
    parametersSchema: Value;
};

/**
 *  Transport definition for a portable MCP template.
 *
 *  This mirrors the MCP setup flow closely enough to prefill the existing UI,
 *  but remains a separate manifest contract so templates never become directly
 *  executable persisted transports.
 */
declare type SpecialistMcpTemplateTransport = 
/**  Spawn a local process and communicate over stdio after installation. */
    {
    type: 'stdio';
    /**  Executable command. */
    command: string;
    /**  Command-line arguments. */
    args?: string[];
    /**  Environment variables to prefill or request during install. */
    env?: SpecialistMcpTemplateEnvVar[];
}
/**  Connect to a remote MCP server over Streamable HTTP after installation. */
| ({
    type: 'streamableHttp';
} & {
    /**  Full URL of the Streamable HTTP endpoint. */
    url: string;
} & ({
    /**  Optional auth header requirement or preset. */
    authHeader?: SpecialistMcpTemplateValue | null;
} & {
    /**  Optional auth header requirement or preset. */
    auth_header?: SpecialistMcpTemplateValue | null;
}));

/**  Optional value requirement for portable MCP template auth headers. */
declare type SpecialistMcpTemplateValue = {
    /**  Optional fixed non-secret value that can be prefilled during install. */
    value?: string | null;
    /**  Whether the user must provide this value during installation. */
    secret?: boolean;
    /**  Optional guidance shown when installing the template. */
    description?: string | null;
};

declare type SpecialistNonPackageSkill = Omit<Exclude<SkillRef, string>, 'source' | 'package'> & {
    source?: Exclude<SkillSource, 'package'>;
    package?: null;
};

/**  Observed performance summary persisted from eval or benchmark reports. */
declare type SpecialistObservedPerformance = {
    /**  Median time to first token in milliseconds. */
    p50TimeToFirstTokenMs?: number | null;
    /**  P95 time to first token in milliseconds. */
    p95TimeToFirstTokenMs?: number | null;
    /**  Median total latency in milliseconds. */
    p50TotalLatencyMs?: number | null;
    /**  P95 total latency in milliseconds. */
    p95TotalLatencyMs?: number | null;
    /**  Median output tokens per second. */
    p50OutputTokensPerSecond?: number | null;
    /**  P95 output tokens per second. */
    p95OutputTokensPerSecond?: number | null;
    /**  Scenario error rate from 0.0 to 1.0. */
    errorRate?: number | null;
    /**  Timeout rate from 0.0 to 1.0. */
    timeoutRate?: number | null;
    /**  Tool-call error rate from 0.0 to 1.0. */
    toolErrorRate?: number | null;
    /**  Number of scenarios/turns represented by this summary. */
    sampleSize?: number;
};

/**  Durable orchestration metadata authored in Specialist Builder. */
declare type SpecialistOrchestrationMetadata = {
    /**  Response style to apply when this specialist answers. */
    responseStyle?: SpecialistResponseStyle;
    /**  Fan-out suitability for channel orchestration. */
    parallelSuitability?: SpecialistParallelSuitability;
    /**  Tool-use posture within the authored allowlist and authorization boundaries. */
    toolPosture?: SpecialistToolPosture;
    /**  Selection cues for semantic routing and fallback decisions. */
    confidenceHints?: SpecialistConfidenceHints;
    /**  VCV-oriented routing descriptor and keywords. */
    routingDescriptor?: SpecialistRoutingDescriptor;
    /**  Publish-time eval gate configuration. */
    evalGateConfig?: SpecialistEvalGateConfig;
    /**  Persisted eval gate results for the latest measured snapshot. */
    evalGateResults?: SpecialistEvalGateResults;
};

/** Discriminated outcome of one turn. */
export declare type SpecialistOutcome<TData = string> = {
    ok: true;
    data: TData;
    text: string;
    modelUsed?: string;
} | {
    ok: false;
    failure: SpecialistFailure;
    text?: string;
};

declare type SpecialistPackageSkill = Omit<Exclude<SkillRef, string>, 'source' | 'package'> & {
    source: 'package';
    package: Extract<PackageSkillReference, {
        kind: 'own';
    }>;
};

/**  Authored guidance for whether a specialist can participate in fan-out. */
declare type SpecialistParallelSuitability = 
/**  Safe to run alongside other specialists. */
'parallel-safe'
/**  Prefer selecting this specialist alone, but allow fan-out when useful. */
| 'solo-preferred'
/**  Select this specialist alone unless explicitly invoked with others. */
| 'solo-required';

/**  Performance thresholds used by publish/eval gates. */
declare type SpecialistPerformanceGateConfig = {
    /**  Maximum allowed time to first token in milliseconds. */
    maxTimeToFirstTokenMs?: number | null;
    /**  Maximum allowed total latency in milliseconds. */
    maxTotalLatencyMs?: number | null;
    /**  Minimum allowed output tokens per second. */
    minOutputTokensPerSecond?: number | null;
    /**  Maximum allowed scenario error rate from 0.0 to 1.0. */
    maxErrorRate?: number | null;
    /**  Maximum allowed timeout rate from 0.0 to 1.0. */
    maxTimeoutRate?: number | null;
    /**  Maximum allowed tool error rate from 0.0 to 1.0. */
    maxToolErrorRate?: number | null;
};

/**  Authored response profile applied when a specialist is selected. */
declare type SpecialistResponseStyle = 
/**  Prefer short answers with only the minimum necessary context. */
'concise'
/**  Balance clarity, detail, and actionability. */
| 'balanced'
/**  Explain reasoning and context more fully. */
| 'explanatory'
/**  Emphasize concrete next actions and decisions. */
| 'action-oriented';

/**  Selection-oriented text and keywords included in VCV routing extraction. */
declare type SpecialistRoutingDescriptor = {
    /**  VCV-optimized description of when to select this specialist. */
    text?: string;
    /**  Additional routing keywords to include in embedding text. */
    keywords?: string[];
};

/**
 *  A first-class routable task lane (schema 2.0).
 *
 *  Replaces the 1.x trio of `prompts.tasks{key}`, the
 *  `capabilities.descriptions["task:{key}"]` magic-key descriptor, and the
 *  builder-only task entity: one entry carries the routing descriptor, the
 *  prompt addendum, and the task's knowledge/model/eval hooks together.
 */
declare type SpecialistTask = {
    /**  Stable task key (lowercase, underscored) used for routing and switch. */
    key: string;
    /**  Human-readable title shown in builder and switch surfaces. */
    title?: string;
    /**
     *  Routing descriptor (≤300 chars) — becomes the VCV task descriptor
     *  and the model-visible switch menu entry.
     */
    description?: string;
    /**  Example user asks for this lane (bounded; embeds for routing). */
    examples?: string[];
    /**  The task prompt addendum rendered when this lane is active. */
    prompt?: string;
    /**  Optional high-scaffolding variant (see [`Prompts::guided_spawner`]). */
    guided?: string | null;
    /**  Selection exposure for this lane. */
    routing?: TaskPromptRouting;
    /**  Optional per-task model override (alias or canonical id). */
    modelOverride?: string | null;
    /**  Optional task-scoped knowledge targeting. */
    knowledgeTargeting?: TaskKnowledgeTargeting | null;
    /**
     *  Task-level skill preferences and optional activation restriction.
     *
     *  These preferences are evaluated before specialist-level preferences.
     */
    skills?: SkillUsePolicy;
    /**  Benchmark suites that cover this lane (eval hook). */
    benchmarkSuiteIds?: string[];
    /**
     *  Author-declared success criteria for this lane. Travel with the
     *  specialist into every benchmark judge prompt as the rubric for what
     *  good looks like; suites may override per-scenario.
     */
    successCriteria?: string[];
    /**
     *  Optional exact tool surface for this routed task.
     *
     *  `Some([])` is an intentional no-tools policy. `None` preserves the
     *  specialist-level tool policy for tasks that have not opted into a
     *  narrower surface.
     */
    allowedTools?: string[] | null;
};

/**
 *  Authored tool visibility contract for a specialist.
 *
 *  This is a narrowing layer over the runtime's built-in guardrails. Exact
 *  names and prefix globs are expanded into a concrete allowlist before tools
 *  are exposed to the model or executed.
 */
declare type SpecialistTooling = {
    /**
     *  Exact built-in tool names to allow (for example `github_create_issue`).
     *
     *  Built-in tools use underscore-separated names. Namespaced MCP tools use
     *  `tooling.mcpTools` instead.
     */
    tools?: string[];
    /**  Prefix globs for built-in tools (for example `vfs_*`). */
    toolPatterns?: string[];
    /**  Exact MCP server names whose discovered tools should be allowed. */
    mcps?: string[];
    /**
     *  Exact namespaced MCP tool names to allow (for example `github/create_issue`).
     *
     *  Use this only for MCP-discovered tools. Built-in tools such as
     *  `github_create_issue` belong in `tooling.tools`.
     */
    mcpTools?: string[];
    /**  Prefix globs for namespaced MCP tools (for example `github/issues_*`). */
    mcpToolPatterns?: string[];
    /**  Portable MCP templates that can be installed into the workspace MCP inventory. */
    mcpTemplates?: SpecialistMcpTemplate[];
    /**
     *  Per-tool one-line specialist notes (schema 2.0), keyed by tool name.
     *
     *  Appended to that tool's description at registration — guidance rides
     *  the tool it concerns, not the system prompt. A note for a tool
     *  outside the effective allowlist is a validation warning.
     */
    toolNotes?: {
        [key in string]: string;
    };
};

/**  Authored tool-use posture that never widens the allowed tool set. */
declare type SpecialistToolPosture = 
/**  Use tools only when clearly necessary. */
'minimal'
/**  Use tools when they materially improve answer quality. */
| 'balanced'
/**  Proactively use authored tools when confidence depends on fresh evidence. */
| 'proactive';

/**
 *  Task-scoped knowledge targeting (schema 2.0): which knowledge focus areas
 *  and sources a task lane should prefer when retrieving context.
 */
declare type TaskKnowledgeTargeting = {
    /**  Focus areas to bias retrieval toward. */
    focus?: string[];
    /**  Free-form retrieval instructions for this task lane. */
    instructions?: string | null;
    /**  Specific knowledge source ids this task should draw from. */
    sourceIds?: string[];
};

/**  How an authored task prompt may enter specialist routing. */
declare type TaskPromptRouting = 
/**  User text may select this task through lexical or vector routing. */
'userRoutable'
/**
*  Use this user-visible task only when lexical/semantic ranking abstains.
*
*  A manifest may declare at most one user fallback. The reserved
*  `tap.default` base prompt remains the fallback when none is authored.
*/
| 'userFallback'
/**  Only a trusted internal caller may select this prompt by exact key. */
| 'internalOnly';

/**  Primary communication tone for authored specialist persona guidance. */
declare type Tone = 'authoritative' | 'collaborative' | 'supportive' | 'innovative' | 'conservative' | 'friendly' | 'professional' | 'casual' | 'witty' | 'serious';

export declare type ToolDefinition<TArguments = unknown, TResult = unknown> = {
    displayName?: string;
    description: string;
    parametersSchema: JsonSchema;
    timeoutMs?: number;
    actionMessageTemplate?: string;
    execute(arguments_: TArguments): TResult;
};

export declare type UIEntrypoint = {
    type: UIEntrypointType;
    id: string;
    name: string;
    entryPoint: string;
    icon?: string;
    persistWhenClosed?: boolean;
};

export declare type UIEntrypointType = 'workspace-left-sidebar' | 'workspace-left-sidebar-item' | 'chat-right-sidebar' | 'chat-right-sidebar-item';

/**  Policy for placeholders that are not present in the TAP prompt context. */
declare type UnknownPlaceholderPolicy = 
/**  Keep the existing non-strict Handlebars behavior: missing values render empty. */
'empty'
/**  Preserve unknown `{{...}}` placeholders as literal prompt text. */
| 'preserve'
/**  Fail rendering when a prompt references an unknown placeholder. */
| 'error';

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

export declare type UpdateProjectResult = {
    project: MiniAppProject;
};

export 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;
};

export declare type UpdateTaskResult = {
    task: MiniAppTask;
};

declare type Value = null | boolean | number | string | Value[] | {
    [key in string]: Value;
};

/**  Response length preference for authored specialist persona guidance. */
declare type Verbosity = 'very concise' | 'concise' | 'balanced' | 'detailed' | 'very detailed';

/**  Visibility levels for specialists */
declare type Visibility = 
/**  Visible to all users */
'public'
/**  Visible to users in the same organization */
| 'internal'
/**  Visible only to users with specific permissions */
| 'private'
/**  Restricted access with advanced access control rules */
| 'restricted';

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

/**  Execution limits enforced by the first-party welcome provider route. */
declare type WelcomeExecutionLimits = {
    /**  Maximum tokens accepted in the welcome request prompt. */
    maxInputTokens?: number;
    /**  Maximum tokens the welcome route may emit. */
    maxOutputTokens?: number;
    /**  Maximum prior conversation messages included in context. */
    maxPriorMessages?: number;
    /**  Maximum tool calls allowed in one welcome turn. */
    maxToolCallsPerTurn?: number;
    /**  Maximum user message length accepted by the welcome route. */
    maxUserMessageChars?: number;
};

/**
 *  Exact immutable identity of one workspace skill installation and release.
 *
 *  Workspace identity is part of the selector because installation ids are
 *  scoped to one workspace graph. The release id and artifact digest pin the
 *  exact content a specialist or task may prefer.
 */
declare type WorkspaceSkillOwner = {
    /**  Workspace that owns the installation graph. */
    workspaceId: string;
    /**  Exact workspace skill installation ID. */
    skillInstallationId: string;
    /**  Exact immutable skill release ID. */
    skillReleaseId: string;
    /**  Exact immutable artifact digest for the selected release. */
    artifactDigest: string;
};

/**  Communication style preferences for prompt construction. */
declare type WritingStyle = {
    /**  Primary communication tone. */
    primaryTone: Tone;
    /**  Optional secondary tone that can blend with the primary style. */
    secondaryTone?: string | null;
    /**  Preferred response verbosity. */
    verbosity?: Verbosity | null;
    /**  Preferred formality level. */
    formality?: Formality | null;
    /**  Preferred reading level. */
    readingLevel?: ReadingLevel | null;
    /**  Preferred jargon intensity. */
    jargonLevel?: JargonLevel | null;
    /**  Additional free-form style guidance. */
    styleModifiers?: string[] | null;
};

export { }