@agent-surface/core 0.7.0 → 0.8.0

package/dist/registry-DmWUlnta.d.ts

@@ -0,0 +1,759 @@
+/** JSON value constraint: every agent-crossing payload MUST be a JsonValue. */
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/** A JSON Schema document restricted to the supported subset (docs/03 D19). */
+type JsonSchema = Record<string, unknown>;
+type AgentEnvironment = "development" | "production" | "test";
+type AgentEffect = "read" | "local-state" | "navigation" | "server-query" | "server-mutation" | "external-side-effect" | "destructive";
+type AgentProcedureEffect = "server-query" | "server-mutation" | "external-side-effect" | "destructive";
+interface AgentConsumer {
+    id: string;
+    kind: "embedded" | "webmcp" | "mcp-bridge" | "test" | "other";
+    /** Free-form grant strings interpreted by host policies. */
+    grants?: string[];
+}
+interface AgentRouteInfo {
+    path: string;
+    params?: Record<string, string>;
+}
+/**
+ * Concurrency group for an action or procedure reference (D25). Not
+ * model-visible: it is runtime behavior, not planning information.
+ *
+ * - `instance` (default) — every action on the registration shares one FIFO
+ *   queue. Safest: two actions on the same component can never interleave.
+ * - `capability` — one queue per capability, so a slow export does not block
+ *   closing a drawer.
+ * - `key` — one queue per author-chosen key, for actions that contend over
+ *   the same resource across capabilities.
+ * - `parallel` — bounded parallelism; `max` is required and must be ≥ 1.
+ *
+ * `queueDepth` overrides `limits.actionQueueDepth` for this group only.
+ */
+type AgentConcurrency = {
+    mode: "instance";
+    queueDepth?: number;
+} | {
+    mode: "capability";
+    queueDepth?: number;
+} | {
+    mode: "key";
+    key: string;
+    queueDepth?: number;
+} | {
+    mode: "parallel";
+    max: number;
+    queueDepth?: number;
+};
+interface AgentSurfaceLimits {
+    maxComponentDescription: number;
+    maxCapabilityDescription: number;
+    maxMetaBytes: number;
+    maxOutputBytes: number;
+    maxSchemaBytes: number;
+    maxSchemaDepth: number;
+    observationTimeoutMs: number;
+    actionTimeoutMs: number;
+    procedureTimeoutMs: number;
+    actionQueueDepth: number;
+    maxConcurrentObservationsPerConsumer: number;
+    maxConcurrentObservationsTotal: number;
+    maxQueuedObservationsPerConsumer: number;
+    dedupeCacheSize: number;
+    dedupeCacheTtlMs: number;
+    tombstoneSize: number;
+    tombstoneTtlMs: number;
+    confirmationTtlMs: number;
+    maxPendingConfirmations: number;
+}
+declare const DEFAULT_LIMITS: AgentSurfaceLimits;
+type Unsubscribe = () => void;
+
+interface AgentSchemaIssue {
+    path: string;
+    message: string;
+}
+/** Thrown by AgentSchema.parse on invalid input; carries safe, structured issues. */
+declare class AgentSchemaError extends Error {
+    readonly issues: AgentSchemaIssue[];
+    constructor(issues: AgentSchemaIssue[]);
+}
+interface AgentSchema<T> {
+    /** Agent-visible JSON Schema (draft 2020-12, restricted subset). */
+    readonly jsonSchema: JsonSchema;
+    /**
+     * Validates and returns a typed value. MUST throw `AgentSchemaError`
+     * (with a safe, structured message) on invalid input.
+     */
+    parse(value: unknown): T;
+}
+/** Minimal Standard Schema mirror (https://standardschema.dev). */
+interface StandardSchemaV1<I = unknown, O = I> {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        validate(value: unknown): {
+            value: O;
+            issues?: undefined;
+        } | {
+            issues: ReadonlyArray<{
+                message: string;
+                path?: ReadonlyArray<PropertyKey | {
+                    key: PropertyKey;
+                }>;
+            }>;
+        } | Promise<unknown>;
+        readonly types?: {
+            readonly input: I;
+            readonly output: O;
+        } | undefined;
+    };
+}
+/**
+ * Wraps any Standard Schema (Zod ≥3.24, Valibot, ArkType) as an AgentSchema.
+ * The JSON Schema MUST be supplied explicitly — core does not depend on a
+ * converter (docs/03, D20).
+ */
+declare function fromStandardSchema<T>(schema: StandardSchemaV1<unknown, T>, options: {
+    jsonSchema: JsonSchema;
+}): AgentSchema<T>;
+/**
+ * Builds an AgentSchema from a raw JSON Schema, validated by the built-in
+ * minimal structural validator covering exactly the supported subset.
+ */
+declare function fromJsonSchema<T = JsonValue>(schema: JsonSchema): AgentSchema<T>;
+/** Convenience for actions with no input / observations of constant shape. */
+declare const emptyObjectSchema: AgentSchema<Record<string, never>>;
+interface SchemaSubsetResult {
+    ok: boolean;
+    reason?: string;
+}
+/**
+ * Validates that a JSON Schema document stays inside the D19 subset.
+ * Anything outside MUST be rejected at registration with INVALID_DEFINITION /
+ * UNSUPPORTED_SCHEMA (docs/03, docs/07).
+ */
+declare function validateJsonSchemaDocument(schema: JsonSchema, limits: {
+    maxSchemaBytes: number;
+    maxSchemaDepth: number;
+}): SchemaSubsetResult;
+/**
+ * Validates a value against a subset schema. Returns issues (empty = valid).
+ * JSON Schema semantics: `default` is annotation-only and never applied.
+ */
+declare function validateValueAgainstSchema(value: unknown, schema: unknown, root: JsonSchema, path: string): AgentSchemaIssue[];
+
+/** The closed agent-facing error enum — one runtime source, cross-validated
+ * against spec/error-matrix.json (docs/07 §principles, AS-ERR-001). */
+declare const AGENT_CAPABILITY_ERROR_CODES: readonly ["CAPABILITY_NOT_FOUND", "CAPABILITY_NOT_AVAILABLE", "AMBIGUOUS_INSTANCE", "COMPONENT_UNMOUNTED", "STALE_CAPABILITY", "INVOCATION_CONFLICT", "INVALID_INPUT", "NOT_AUTHENTICATED", "NOT_AUTHORIZED", "PRECONDITION_FAILED", "CONFIRMATION_REQUIRED", "CONFIRMATION_INVALID", "RATE_LIMITED", "TIMEOUT", "CANCELLED", "EXECUTION_FAILED"];
+type AgentCapabilityErrorCode = (typeof AGENT_CAPABILITY_ERROR_CODES)[number];
+type AgentErrorRetry = "no" | "yes" | "after-refresh" | "after-delay" | "with-confirmation" | "with-changes";
+interface AgentCapabilityErrorPayload {
+    code: AgentCapabilityErrorCode;
+    /** Agent-safe, imperative, ≤ 300 chars. */
+    message: string;
+    retry: AgentErrorRetry;
+    /** Code-specific, agent-safe, JsonValue only. */
+    details?: Record<string, JsonValue>;
+}
+/** Thrown form used inside policies/handlers; serialized at the boundary. */
+declare class AgentSurfaceError extends Error {
+    readonly payload: AgentCapabilityErrorPayload;
+    constructor(payload: AgentCapabilityErrorPayload, opts?: {
+        cause?: unknown;
+    });
+}
+declare function isAgentSurfaceError(e: unknown): e is AgentSurfaceError;
+type AgentSurfaceDefinitionErrorCode = "INVALID_ID" | "INVALID_DEFINITION" | "UNSUPPORTED_SCHEMA" | "PLANE_VIOLATION" | "DUPLICATE_CAPABILITY" | "LIMIT_EXCEEDED";
+/** Structural defects at registration time. Always thrown, never agent-facing. */
+declare class AgentSurfaceDefinitionError extends Error {
+    readonly code: AgentSurfaceDefinitionErrorCode;
+    constructor(code: AgentSurfaceDefinitionErrorCode, message: string);
+}
+
+interface AgentInvocation {
+    /** Idempotency key. Adapters SHOULD pass their tool-call id. Generated if absent. */
+    invocationId?: string;
+    capabilityId: string;
+    /** Required when >1 live instance of the target component exists. */
+    instanceId?: string;
+    /** Staleness token from discovery. Adapters SHOULD always send it. */
+    registrationId?: string;
+    /** Version hint; enforced only for destructive/external effects. */
+    surfaceVersion?: string;
+    input?: JsonValue;
+    /** Evidence from a resolved confirmation (docs/06). */
+    confirmationId?: string;
+}
+interface InvokeOptions {
+    consumer?: AgentConsumer;
+    signal?: AbortSignal;
+    timeoutMs?: number;
+}
+type AgentInvocationResult = {
+    status: "ok";
+    invocationId: string;
+    capabilityId: string;
+    output?: JsonValue;
+    surfaceVersion: string;
+    /** Set when the surface changed during execution. */
+    surfaceChanged?: boolean;
+} | {
+    status: "error";
+    invocationId: string;
+    capabilityId: string;
+    error: AgentCapabilityErrorPayload;
+    surfaceVersion: string;
+    surfaceChanged?: boolean;
+};
+
+interface AuditEvent {
+    at: string;
+    type: "registration" | "unregistration" | "registration-rejected" | "invocation-started" | "invocation-settled" | "confirmation-requested" | "confirmation-approved" | "confirmation-denied" | "confirmation-expired" | "confirmation-consumed" | "late-settlement" | "collision-suspected";
+    capabilityId?: string;
+    registrationId?: string;
+    invocationId?: string;
+    consumerId?: string;
+    status?: "ok" | "error";
+    code?: AgentCapabilityErrorCode;
+    durationMs?: number;
+    /** Time spent waiting for a concurrency slot (docs/06 §audit; distinct
+     * from execution — §7.1 observability). Settled invocations only. */
+    queueWaitMs?: number;
+    /** Time spent inside the handler/executor guards, excluding queue wait. */
+    executionMs?: number;
+    /** Present only for capabilities with audit: "full"; size-capped. */
+    payload?: {
+        input?: JsonValue;
+        output?: JsonValue;
+    };
+}
+interface AuditSink {
+    /** MUST NOT throw; MUST be non-blocking. */
+    record(event: AuditEvent): void;
+}
+declare function memoryAuditSink(opts?: {
+    capacity?: number;
+}): AuditSink & {
+    events(): AuditEvent[];
+};
+declare function consoleAuditSink(): AuditSink;
+
+type DiscoveryDecision = {
+    decision: "expose";
+} | {
+    decision: "disable";
+    reason: string;
+} | {
+    decision: "hide";
+};
+interface AgentPolicyContext {
+    capabilityId: string;
+    plane: "view" | "domain";
+    kind: "observation" | "action" | "procedure";
+    effect: AgentEffect;
+    registrationId: string;
+    consumer: AgentConsumer;
+    host: Readonly<Record<string, unknown>>;
+    meta: {
+        component?: Record<string, JsonValue>;
+        capability?: Record<string, JsonValue>;
+    };
+    internal: Readonly<Record<string, unknown>>;
+    /** Registry environment (additive convenience for built-ins). */
+    environment: AgentEnvironment;
+    /** Registry's injectable clock — built-ins MUST use this, never Date.now(). */
+    now(): number;
+}
+/** Phase-4 context: no agent input is available here, by construction (D21). */
+type AgentAuthorizationContext = AgentPolicyContext;
+/** Phase-6 context: only the validated effective input is visible (D21). */
+interface AgentInvocationPolicyContext extends AgentAuthorizationContext {
+    invocationId: string;
+    effectiveInput: JsonValue;
+}
+interface AgentPolicy {
+    name: string;
+    /**
+     * Discovery-time filter. MUST be synchronous, cheap, side-effect free.
+     * Advisory: hides/disables in catalogs. Default when absent: expose.
+     */
+    onDiscovery?(ctx: AgentPolicyContext): DiscoveryDecision;
+    /**
+     * Pre-input authority gate (pipeline phase 4): authn/authz/tenant/
+     * environment/input-independent rate. MAY be async. Onion order; call
+     * next() to proceed. Throw AgentSurfaceError to deny.
+     */
+    onAuthorize?(ctx: AgentAuthorizationContext, next: () => Promise<AgentInvocationResult>): Promise<AgentInvocationResult>;
+    /**
+     * Post-input invocation gate (pipeline phase 6). Receives ONLY the
+     * validated effective input — never raw agent input (D21).
+     */
+    onInvoke?(ctx: AgentInvocationPolicyContext, next: () => Promise<AgentInvocationResult>): Promise<AgentInvocationResult>;
+}
+/**
+ * Marker read by the invocation pipeline: policies carrying it escalate the
+ * capability's confirmation requirement (docs/06 requireConfirmation).
+ */
+declare const CONFIRMATION_ESCALATION: unique symbol;
+interface ConfirmationEscalation {
+    /** Evaluated at phase 6 over the validated effective input (D21). */
+    if?: (ctx: AgentPolicyContext & {
+        effectiveInput: JsonValue;
+    }) => boolean;
+    summary?: (effectiveInput: JsonValue) => string;
+}
+/** Most-restrictive-wins composition of discovery decisions (docs/06). */
+declare function evaluateDiscovery(policies: ReadonlyArray<AgentPolicy>, ctx: AgentPolicyContext): DiscoveryDecision;
+/** Onion composition of onInvoke handlers (registry outermost, phase 6). */
+declare function composeInvokeChain(policies: ReadonlyArray<AgentPolicy>, ctx: AgentInvocationPolicyContext, core: () => Promise<AgentInvocationResult>): Promise<AgentInvocationResult>;
+/** Requires ctx.host[key] (default "user"). Fails NOT_AUTHENTICATED; hides. */
+declare function authenticated(opts?: {
+    key?: string;
+}): AgentPolicy;
+/** Delegates to a host authorizer. Fails NOT_AUTHORIZED; hides at discovery. */
+declare function hasPermission(permission: string, check: (host: Record<string, unknown>, permission: string) => boolean): AgentPolicy;
+/** Tenant boundary: hides unless current(host) === expected(ctx). */
+declare function tenantBoundary(opts: {
+    current: (host: Record<string, unknown>) => string | undefined;
+    expected: (ctx: AgentPolicyContext) => string | undefined;
+}): AgentPolicy;
+/** Restricts to environments. Others: hidden. */
+declare function environment(allowed: AgentEnvironment[]): AgentPolicy;
+/**
+ * Token bucket per (consumer, capability). Advisory, input-independent —
+ * runs pre-input (phase 4). Author input-aware rate policies as onInvoke.
+ * Fails RATE_LIMITED. Uses the injectable clock (AS-POLICY-001).
+ */
+declare function rateLimit(opts: {
+    limit: number;
+    windowMs: number;
+}): AgentPolicy;
+/** Escalates confirmation to "required" (optionally conditionally).
+ * Predicates run at phase 6 over the validated effective input (D21). */
+declare function requireConfirmation(opts?: {
+    if?: (ctx: AgentPolicyContext & {
+        effectiveInput: JsonValue;
+    }) => boolean;
+    summary?: (effectiveInput: JsonValue) => string;
+}): AgentPolicy;
+/** Forwards invocation events to a sink at the given detail level.
+ * Runs at phase 6 (onInvoke): its enrichment sees the effective input. */
+declare function audit(sink?: AuditSink, level?: "metadata" | "full"): AgentPolicy;
+
+interface AgentReadContext {
+    capabilityId: string;
+    registrationId: string;
+    consumer: AgentConsumer;
+    /** Host context (user, tenant, env…) from RegistryOptions.context(). */
+    host: Readonly<Record<string, unknown>>;
+}
+interface AgentActionContext extends AgentReadContext {
+    invocationId: string;
+    /** Aborted on timeout, external cancellation, or unmount. Cooperative. */
+    signal: AbortSignal;
+    /** Present iff this invocation carries approved confirmation evidence. */
+    confirmation?: {
+        id: string;
+        approvedAt: string;
+    };
+}
+interface PreconditionFailure {
+    message: string;
+    details?: Record<string, JsonValue>;
+}
+interface AgentObservationDefinition<TOut extends JsonValue> {
+    /** Agent-visible description, ≤ 300 chars. */
+    description: string;
+    output: AgentSchema<TOut>;
+    /**
+     * Reads current semantic state. MUST be side-effect free. SHOULD be
+     * synchronous; MAY return a promise (subject to observation timeout).
+     */
+    read(ctx: AgentReadContext): TOut | Promise<TOut>;
+    /** Availability predicate, re-evaluated at snapshot and at invocation. */
+    when?: () => boolean;
+    unavailableReason?: string | (() => string);
+    policies?: AgentPolicy[];
+    meta?: Record<string, JsonValue>;
+    timeoutMs?: number;
+}
+interface AgentActionDefinition<TIn extends JsonValue, TOut extends JsonValue | void = void> {
+    description: string;
+    input: AgentSchema<TIn>;
+    output?: AgentSchema<Exclude<TOut, void>>;
+    /** View actions MUST be "local-state" | "navigation" (plane rule, docs/01). */
+    effect: "local-state" | "navigation";
+    idempotent?: boolean;
+    reversible?: boolean;
+    confirmation?: "never" | "optional" | "required";
+    audit?: "none" | "metadata" | "full";
+    when?: () => boolean;
+    unavailableReason?: string | (() => string);
+    /**
+     * Input-aware validation beyond the schema. Return void to pass; return
+     * (or throw) a PreconditionFailure to fail with PRECONDITION_FAILED.
+     */
+    precondition?(input: TIn, ctx: AgentReadContext): void | PreconditionFailure;
+    /**
+     * TOut is inferred from `output` only (NoInfer): the schema is the source
+     * of truth and the handler's return is checked against it.
+     */
+    execute(input: TIn, ctx: AgentActionContext): NoInfer<TOut> | Promise<NoInfer<TOut>>;
+    policies?: AgentPolicy[];
+    meta?: Record<string, JsonValue>;
+    timeoutMs?: number;
+    /** Concurrency group (D25). Default `{mode:"instance"}` — serialize with
+     *  every other action on this component instance. */
+    concurrency?: AgentConcurrency;
+}
+/** Identity helpers that fix generics for record-literal authoring. */
+declare function observation<TOut extends JsonValue>(def: AgentObservationDefinition<TOut>): AgentObservationDefinition<TOut>;
+declare function action<TIn extends JsonValue, TOut extends JsonValue | void = void>(def: AgentActionDefinition<TIn, TOut>): AgentActionDefinition<TIn, TOut>;
+declare function defineAgentComponent(def: AgentComponentDefinition): AgentComponentDefinition;
+interface ProcedureCallInfo {
+    invocationId: string;
+    consumer: AgentConsumer;
+    signal: AbortSignal;
+    confirmation?: {
+        id: string;
+        approvedAt: string;
+    };
+}
+interface AgentProcedureExecutor {
+    execute(req: {
+        path: string;
+        input: JsonValue;
+        info: ProcedureCallInfo;
+    }): Promise<JsonValue>;
+    /** Known exposed procedure paths (manifest), used for suffix-collision lint. */
+    paths?: ReadonlyArray<string>;
+}
+interface AgentProcedureRefDescriptor {
+    readonly id: string;
+    readonly path: string;
+    readonly description: string;
+    readonly inputSchema: JsonSchema;
+    readonly outputSchema?: JsonSchema;
+    readonly effect: AgentProcedureEffect;
+    /** Server-declared flag the client must respect (approval required). */
+    readonly requiresApproval?: boolean;
+}
+interface AgentProcedureBindingRuntimeConfig {
+    when?: () => boolean;
+    unavailableReason?: string | (() => string);
+    /** UI-derived inputs, evaluated at EXECUTION time (docs/05 rule 4). */
+    bind?: () => Record<string, JsonValue>;
+    overridableFields?: ReadonlyArray<string>;
+    /** Escalate (never lower) the manifest's confirmation requirement. */
+    confirmation?: "optional" | "required";
+    policies?: AgentPolicy[];
+    /** Contextual description appended to the manifest description. */
+    describe?: () => string;
+    meta?: Record<string, JsonValue>;
+    /** Concurrency group (D25). Default: one group per procedure identity per
+     *  referencing registration — conservative, and it never couples a domain
+     *  call to unrelated view actions. */
+    concurrency?: AgentConcurrency;
+}
+interface AgentProcedureBinding<TIn extends object = object, TOut = unknown> {
+    readonly kind: "procedure-binding";
+    readonly ref: AgentProcedureRefDescriptor;
+    readonly config: AgentProcedureBindingRuntimeConfig;
+    /** Keys produced by bind(), captured at binding creation. */
+    readonly boundKeys: ReadonlyArray<string>;
+    /** Bound keys the agent may NOT supply (bound minus overridable). */
+    readonly lockedKeys: ReadonlyArray<string>;
+    /** Agent-facing (reduced) input schema per D7 rule 1. */
+    readonly reducedInputSchema: JsonSchema;
+    /** Optional link to the owning view component. */
+    contextLink?: {
+        type: string;
+        instanceId: string;
+    };
+    /** Phantom fields carrying the generics (never read at runtime). */
+    readonly __types?: {
+        input: TIn;
+        output: TOut;
+    };
+}
+interface AgentComponentDefinition {
+    /** Component type, e.g. "devices.table". MUST match the id grammar. */
+    type: string;
+    /** Distinguishes simultaneous mounts. Defaults to "default". Data-derived. */
+    instanceId?: string;
+    /** Agent-visible description, ≤ 500 chars. Required, non-empty. */
+    description: string;
+    /** Optional containment link for hierarchy-aware consumers. */
+    parent?: {
+        type: string;
+        instanceId?: string;
+    };
+    /** Agent-visible metadata. JsonValue, ≤ 2 kB serialized. */
+    meta?: Record<string, JsonValue>;
+    /** Internal metadata for policies/audit sinks. NEVER serialized. */
+    internal?: Record<string, unknown>;
+    /** Policies applied to every capability of this component. */
+    policies?: AgentPolicy[];
+    /** Registrant trust label; default "first-party". */
+    origin?: string;
+    /** Snapshot ordering/budget priority; higher survives budgets longer. */
+    priority?: number;
+    /** Master switch; false ⇒ all capabilities visible-disabled. */
+    enabled?: boolean;
+    observations?: Record<string, AgentObservationDefinition<any>>;
+    actions?: Record<string, AgentActionDefinition<any, any>>;
+    /** Domain references; normally added via @agent-surface/orpc. */
+    procedures?: AgentProcedureBinding<any, any>[];
+}
+/**
+ * Validates a component definition structurally. Throws
+ * AgentSurfaceDefinitionError in every environment — structural defects are
+ * deterministic code bugs (docs/03 §registry).
+ */
+declare function validateComponentDefinition(def: AgentComponentDefinition, limits: AgentSurfaceLimits, opts: {
+    hasProcedureExecutor: boolean;
+}): void;
+
+type AgentSurfaceEvent = {
+    type: "surface-changed";
+    surfaceVersion: string;
+} | {
+    type: "component-registered";
+    registrationId: string;
+    componentType: string;
+    instanceId: string;
+} | {
+    type: "component-unregistered";
+    registrationId: string;
+    componentType: string;
+    instanceId: string;
+} | {
+    type: "component-rejected";
+    componentType: string;
+    instanceId: string;
+    reason: "duplicate" | "guard";
+} | {
+    type: "availability-changed";
+    registrationId: string;
+    capabilityId: string;
+    available: boolean;
+} | {
+    type: "collision-suspected";
+    viewCapabilityId: string;
+    domainProcedureId: string;
+} | {
+    type: "invocation-started";
+    invocationId: string;
+    capabilityId: string;
+    consumerId: string;
+} | {
+    type: "invocation-settled";
+    invocationId: string;
+    capabilityId: string;
+    status: "ok" | "error";
+    code?: AgentCapabilityErrorCode;
+    durationMs: number;
+} | {
+    type: "confirmation-requested";
+    confirmationId: string;
+    capabilityId: string;
+    expiresAt: string;
+} | {
+    type: "confirmation-resolved";
+    confirmationId: string;
+    outcome: "approved" | "denied" | "expired";
+};
+
+interface PendingConfirmation {
+    confirmationId: string;
+    capabilityId: string;
+    registrationId: string;
+    /** Normalized consumer identity `kind:id` (D22). */
+    consumerKey: string;
+    /** Effect of the operation being approved. */
+    effect: AgentEffect;
+    /** Human-readable summary composed from description + effective input. */
+    summary: string;
+    /** The exact effective input (bound + agent-supplied) being approved. */
+    input: JsonValue;
+    requestedAt: string;
+    expiresAt: string;
+}
+interface ConfirmationController {
+    /** Pending requests, for host UI rendering. */
+    pending(): PendingConfirmation[];
+    resolve(confirmationId: string, resolution: {
+        approved: boolean;
+        reason?: string;
+    }): void;
+    /** Resolves when the given confirmation settles (approved/denied/expired). */
+    waitFor(confirmationId: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<"approved" | "denied" | "expired">;
+    subscribe(listener: (pending: PendingConfirmation[]) => void): Unsubscribe;
+    /** Test hook: force-expire a record as if its TTL elapsed (docs/08). */
+    forceExpire(confirmationId: string): void;
+}
+
+type ConfirmationLevel = "never" | "optional" | "required";
+
+interface SnapshotContext {
+    consumer?: AgentConsumer;
+    /** Component-type prefixes to include, e.g. ["devices"]. Default: all. */
+    scope?: string[];
+    /** Include visible-disabled capabilities. Default true. */
+    includeUnavailable?: boolean;
+    /** [Experimental] Truncation budget. */
+    budget?: {
+        maxComponents?: number;
+        maxBytes?: number;
+    };
+}
+interface AgentSurfaceSnapshot {
+    surfaceId: string;
+    surfaceVersion: string;
+    capturedAt: string;
+    route?: AgentRouteInfo;
+    components: AgentComponentDescriptor[];
+    /** Domain references, top-level (planes are not nested into each other). */
+    procedures: AgentProcedureDescriptor[];
+    /** [Experimental] Present iff a budget truncated the snapshot. */
+    truncated?: {
+        droppedComponents: number;
+    };
+    /**
+     * [Experimental] Present iff a configured scope floor refused part of a
+     * requested scope (D27) — set by the adapter, never by `snapshot()`, which
+     * has no floor to intersect against. Empty `components` alongside this marker
+     * means the request fell outside the floor, not that the surface is empty.
+     */
+    scopeRejected?: {
+        prefixes: string[];
+    };
+}
+interface AgentComponentDescriptor {
+    type: string;
+    instanceId: string;
+    registrationId: string;
+    description: string;
+    parent?: {
+        type: string;
+        instanceId: string;
+    };
+    meta?: Record<string, JsonValue>;
+    observations: AgentObservationDescriptor[];
+    actions: AgentActionDescriptor[];
+}
+interface AgentObservationDescriptor {
+    capabilityId: string;
+    name: string;
+    description: string;
+    outputSchema: JsonSchema;
+    available: boolean;
+    unavailableReason?: string;
+    meta?: Record<string, JsonValue>;
+}
+interface AgentActionDescriptor {
+    capabilityId: string;
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    effect: "local-state" | "navigation";
+    idempotent: boolean;
+    reversible: boolean;
+    confirmation: "never" | "optional" | "required";
+    available: boolean;
+    unavailableReason?: string;
+    meta?: Record<string, JsonValue>;
+}
+interface AgentProcedureDescriptor {
+    procedureId: string;
+    /**
+     * The manifest description. Stable across snapshots — the contextual
+     * `describe()` output is `contextualNote` and is never folded in here (D28).
+     */
+    description: string;
+    /** Volatile: this snapshot's contextual `describe()` output, if any. */
+    contextualNote?: string;
+    /** Agent-facing (reduced) input schema per binding rule 1 (docs/05). */
+    inputSchema: JsonSchema;
+    outputSchema?: JsonSchema;
+    effect: AgentProcedureEffect;
+    confirmation: ConfirmationLevel;
+    available: boolean;
+    unavailableReason?: string;
+    boundFields: Array<{
+        path: string;
+        locked: boolean;
+        source: "ui-state";
+    }>;
+    /** The registration that contributed this reference (staleness token). */
+    registrationId: string;
+    /** Optional link to the owning view component. */
+    context?: {
+        type: string;
+        instanceId: string;
+    };
+    meta?: Record<string, JsonValue>;
+}
+type AgentCapabilityDescriptorUnion = AgentObservationDescriptor | AgentActionDescriptor | AgentProcedureDescriptor;
+
+interface RegistrationCandidate {
+    definition: AgentComponentDefinition;
+    stack?: string;
+}
+interface RegistryOptions {
+    /** "development" | "production" | "test". Default: "production". */
+    environment?: AgentEnvironment;
+    /** Host context provider. MUST be synchronous and cheap. */
+    context?: () => Record<string, unknown>;
+    /** Global policies, outermost layer of every chain. */
+    policies?: AgentPolicy[];
+    /** Audit sink; default: bounded in-memory sink (+ console in development). */
+    audit?: AuditSink;
+    /** Guard invoked before accepting a registration (trust filtering, docs/06). */
+    onRegister?: (candidate: RegistrationCandidate) => "accept" | "reject";
+    /** Collision handling for duplicate (type, instanceId). Default "reject". */
+    onDuplicateInstance?: "reject" | "replace";
+    /** Suffix-collision diagnostics vs known domain ids. Default "warn". */
+    duplicateSuffixPolicy?: "off" | "warn" | "error";
+    /** Route descriptor for snapshots (host wires its router here). */
+    route?: () => AgentRouteInfo | undefined;
+    limits?: Partial<AgentSurfaceLimits>;
+    /** Injectable clock (docs/08 determinism); default Date.now. */
+    now?: () => number;
+}
+interface AgentRegistrationHandle {
+    readonly registrationId: string;
+    readonly status: "active" | "rejected" | "unregistered";
+    /** Push dynamic updates; only these fields are updatable (D2). */
+    update(patch: {
+        enabled?: boolean;
+        availability?: Record<string, {
+            available: boolean;
+            reason?: string;
+        }>;
+    }): void;
+    /** Bumps the surface version without changing anything. */
+    invalidate(): void;
+    unregister(): void;
+}
+interface AgentSurfaceRegistry {
+    readonly surfaceId: string;
+    register(definition: AgentComponentDefinition): AgentRegistrationHandle;
+    snapshot(context?: SnapshotContext): AgentSurfaceSnapshot;
+    invoke(request: AgentInvocation, options?: InvokeOptions): Promise<AgentInvocationResult>;
+    subscribe(listener: (event: AgentSurfaceEvent) => void): Unsubscribe;
+    confirmations: ConfirmationController;
+    /** Register a domain-procedure executor (installed by @agent-surface/orpc). */
+    setProcedureExecutor(executor: AgentProcedureExecutor | undefined): void;
+    getVersion(): string;
+    /** Tears down: aborts in-flight invocations (CANCELLED), clears listeners. */
+    dispose(): void;
+}
+declare function createAgentSurfaceRegistry(options?: RegistryOptions): AgentSurfaceRegistry;
+
+export { type PendingConfirmation as $, type AgentRouteInfo as A, type AgentProcedureDescriptor as B, type AgentProcedureEffect as C, type DiscoveryDecision as D, type AgentProcedureExecutor as E, type AgentProcedureRefDescriptor as F, type AgentReadContext as G, type AgentRegistrationHandle as H, type AgentSchema as I, type JsonSchema as J, AgentSchemaError as K, type AgentSchemaIssue as L, AgentSurfaceDefinitionError as M, type AgentSurfaceDefinitionErrorCode as N, AgentSurfaceError as O, type AgentSurfaceEvent as P, type AgentSurfaceLimits as Q, type AgentSurfaceSnapshot as R, type SnapshotContext as S, type AuditEvent as T, type Unsubscribe as U, type AuditSink as V, CONFIRMATION_ESCALATION as W, type ConfirmationController as X, type ConfirmationEscalation as Y, DEFAULT_LIMITS as Z, type InvokeOptions as _, type AgentConsumer as a, type PreconditionFailure as a0, type ProcedureCallInfo as a1, type RegistrationCandidate as a2, type RegistryOptions as a3, type StandardSchemaV1 as a4, action as a5, audit as a6, authenticated as a7, composeInvokeChain as a8, consoleAuditSink as a9, createAgentSurfaceRegistry as aa, defineAgentComponent as ab, emptyObjectSchema as ac, environment as ad, evaluateDiscovery as ae, fromJsonSchema as af, fromStandardSchema as ag, hasPermission as ah, isAgentSurfaceError as ai, memoryAuditSink as aj, observation as ak, rateLimit as al, requireConfirmation as am, tenantBoundary as an, validateComponentDefinition as ao, validateJsonSchemaDocument as ap, validateValueAgainstSchema as aq, type AgentSurfaceRegistry as b, type JsonValue as c, type AgentInvocationResult as d, AGENT_CAPABILITY_ERROR_CODES as e, type AgentActionContext as f, type AgentActionDefinition as g, type AgentActionDescriptor as h, type AgentAuthorizationContext as i, type AgentCapabilityDescriptorUnion as j, type AgentCapabilityErrorCode as k, type AgentCapabilityErrorPayload as l, type AgentComponentDefinition as m, type AgentComponentDescriptor as n, type AgentConcurrency as o, type AgentEffect as p, type AgentEnvironment as q, type AgentErrorRetry as r, type AgentInvocation as s, type AgentInvocationPolicyContext as t, type AgentObservationDefinition as u, type AgentObservationDescriptor as v, type AgentPolicy as w, type AgentPolicyContext as x, type AgentProcedureBinding as y, type AgentProcedureBindingRuntimeConfig as z };