import { ModuleFederationOptions } from '@module-federation/rsbuild-plugin';

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

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

export declare type CompiledTapMiniapp = Readonly<{
    definition: TapMiniappDefinition;
    build: TapMiniappBuildContext;
    buildManifest: TapMiniappJsonObject;
    buildManifestPath: string;
    targets: Readonly<Partial<Record<TapPackageTarget, ResolvedTapMiniappTargetDefinition>>>;
    builders: Readonly<Partial<Record<TapPackageTarget, TargetBuilder>>>;
    publisher?: PublisherAdapter;
    verify: TapMiniappVerificationHooks;
}>;

/**
 * Compiles project-owned authoring data into one finalized build manifest.
 * The compiler never writes tracked project inputs.
 */
export declare function compileTapMiniapp(options: CompileTapMiniappOptions): Promise<CompiledTapMiniapp>;

export declare type CompileTapMiniappOptions = Readonly<{
    root: string;
    stagingRoot: string;
    outputRoot: string;
    configPath?: string;
}>;

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

declare type Config = {
    manifest?: string;
    entryName?: string;
    output?: string;
    federation?: ModuleFederationOptions;
    /** Descriptor target updated by this build, such as desktop or mobile. */
    packageTarget?: 'desktop' | 'mobile' | 'quickjs' | 'worker' | 'node' | 'workflow-host';
    /** Filesystem root for this independently compiled target graph. */
    packageOutputRoot?: string;
};

/** Produces logical contributions and generated inputs for one local build. */
export declare type ContributionProvider = Readonly<{
    id: string;
    provide(build: TapMiniappBuildContext): TapMiniappMaybePromise<ContributionProviderOutput>;
}>;

export declare type ContributionProviderOutput = Readonly<{
    contributions?: readonly TapMiniappJsonObject[];
    files?: readonly GeneratedFile[];
}>;

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

/**
 *  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 defineContributionProvider<const TProvider extends ContributionProvider>(provider: TProvider): TProvider;

export declare function defineTapMiniapp<const TDefinition extends TapMiniappDefinition>(definition: TDefinition): TDefinition;

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

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 GeneratedFile = Readonly<{
    path: string;
    contents: string | Uint8Array;
    kind?: 'asset' | 'module';
}>;

/**
 *  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 function isTapMiniappTarget(value: string): value is TapPackageTarget;

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

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

/** Loads the one project-owned typed authoring config. */
export declare function loadTapMiniappDefinition(rootInput: string, configPathInput?: string): Promise<Readonly<{
    root: string;
    configPath: string;
    definition: TapMiniappDefinition;
}>>;

export declare type LogicalChatBlockDefinition = Readonly<{
    id: string;
    specialist: string;
    primitive: 'table' | 'report' | 'notice';
    accessibilityLabel: string;
    fallbackFormat: 'text' | 'markdown';
}>;

export declare type LogicalSpecialistDefinition = Omit<SpecialistManifest, 'name' | 'slug' | 'version' | 'schemaVersion'> & Readonly<{
    id: string;
    targets?: readonly TapPackageTarget[];
}>;

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

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

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

/**
 * Discovers logical, versionless specialist/chat-block JSON definitions and
 * materializes their version-labelled package artifacts in SDK staging.
 */
export declare function packageContributionProvider(options?: Readonly<{
    specialists?: string;
    chatBlocks?: string;
}>): ContributionProvider & Readonly<{
    logicalDefinitionDirectories: Readonly<{
        specialists: string;
        chatBlocks: 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';

/** Publishes exactly one already-verified assembled package. */
export declare type PublisherAdapter<TResult = unknown> = Readonly<{
    id: string;
    publish(context: PublisherContext): TapMiniappMaybePromise<TResult>;
}>;

export declare type PublisherContext = Readonly<{
    build: TapMiniappBuildContext;
    sourceManifest: ExactSourceManifestV2;
    manifestPath: string;
    packageRoot: string;
}>;

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

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

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

export declare type ResolvedTapMiniappTargetDefinition = Readonly<{
    remoteName: string;
    exposes: Readonly<Record<string, ResolvedTapMiniappTargetExpose>>;
}>;

export declare type ResolvedTapMiniappTargetExpose = Readonly<{
    runtime: TapMiniappTargetExpose['runtime'];
    source: string;
}>;

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

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

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

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

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

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

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

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

/**
 * Strict JSON specialist manifest authored inside a TAP Miniapp package.
 * Identity fields are explicit and legacy host-loader fields are excluded.
 */
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;
};

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

export declare function stringifyTapMiniappJson(value: unknown): string;

export declare type TapMiniappArtifactVerificationContext = Readonly<{
    build: TapMiniappBuildContext;
    sourceManifest: ExactSourceManifestV2;
    manifestPath: string;
    packageRoot: string;
}>;

export declare type TapMiniappBuildContext = Readonly<{
    buildSchemaVersion: 2;
    sdkVersion: string;
    versionLabel: string;
    localDisplay: Required<SourceManifestLocalDisplayV2>;
    projectRoot: string;
    stagingRoot: string;
    outputRoot: string;
    buildManifestPath: string;
    targets: readonly TapPackageTarget[];
}>;

export declare type TapMiniappBuildVerificationContext = Readonly<{
    build: TapMiniappBuildContext;
    buildManifest: TapMiniappJsonObject;
    buildManifestPath: string;
}>;

export declare type TapMiniappDefinition = Readonly<{
    versionLabel: string;
    presentation: TapMiniappJsonObject & Readonly<{
        name: string;
        slug: string;
        description: string;
    }>;
    compatibility: Readonly<{
        tapHost: string;
    }>;
    targets: Partial<Readonly<Record<TapPackageTarget, TapMiniappTargetDefinition>>>;
    contributions: readonly (TapMiniappJsonObject | ContributionProvider)[];
    events?: TapMiniappJsonObject;
    runtimePolicy?: TapMiniappJsonObject;
    publisher?: PublisherAdapter;
    verify?: TapMiniappVerificationHooks;
}>;

export declare type TapMiniappJsonObject = Readonly<Record<string, unknown>>;

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

export declare type TapMiniappTargetDefinition = Readonly<{
    remoteName: string;
    exposes: Readonly<Record<string, TapMiniappTargetExpose>>;
    builder: TargetBuilder;
}>;

export declare type TapMiniappTargetExpose = Readonly<{
    runtime: 'webview' | 'quickjs' | 'worker' | 'node' | 'workflow-host';
    source: string | Readonly<{
        generated: string;
    }>;
}>;

export declare type TapMiniappVerificationHooks = Readonly<{
    verifyBuild?(context: TapMiniappBuildVerificationContext): TapMiniappMaybePromise<void>;
    verifyArtifacts?(context: TapMiniappArtifactVerificationContext): TapMiniappMaybePromise<void>;
    verifyRuntime?(context: TapMiniappArtifactVerificationContext): TapMiniappMaybePromise<void>;
}>;

declare type TapPackageTarget = NonNullable<Config['packageTarget']>;

/** Compiles one application target into the SDK-owned target output root. */
export declare type TargetBuilder = Readonly<{
    id: string;
    build(context: TargetBuilderContext): TapMiniappMaybePromise<void>;
}>;

export declare type TargetBuilderContext = Readonly<{
    target: TapPackageTarget;
    build: TapMiniappBuildContext;
    buildManifestPath: string;
    stagingRoot: string;
    outputRoot: string;
    targetDefinition: ResolvedTapMiniappTargetDefinition;
}>;

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

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

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

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