@agent-surface/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,796 @@
+/** 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>;
+}
+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;
+
+/** 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);
+}
+
+/**
+ * Canonical ID grammar (docs/01 §identity):
+ *
+ *   capability-id   = plane ":" component-type "." capability-name
+ *   plane           = "view" | "domain"
+ *   component-type  = segment *( "." segment )
+ *   segment         = lowercase-letter *( lowercase-letter / digit / "-" )
+ *   capability-name = lowercase-letter *( letter / digit )   ; camelCase, no dots
+ *   instance-id     = 1*( letter / digit / "-" / "_" )
+ *
+ * Underscores are reserved for the wire-name encoding (docs/09).
+ */
+declare const MAX_ID_LENGTH = 128;
+type AgentPlane = "view" | "domain";
+declare function isValidComponentType(type: string): boolean;
+declare function isValidCapabilityName(name: string): boolean;
+declare function isValidInstanceId(id: string): boolean;
+declare function formatViewCapabilityId(componentType: string, name: string): string;
+declare function formatDomainCapabilityId(path: string): string;
+interface ParsedViewCapabilityId {
+    plane: "view";
+    componentType: string;
+    name: string;
+}
+interface ParsedDomainCapabilityId {
+    plane: "domain";
+    /** Canonical oRPC procedure path — treated as opaque (docs/01). */
+    path: string;
+}
+type ParsedCapabilityId = ParsedViewCapabilityId | ParsedDomainCapabilityId;
+/** Parses a capability id; returns undefined when the grammar is violated. */
+declare function parseCapabilityId(id: string): ParsedCapabilityId | undefined;
+declare const MAX_WIRE_NAME_LENGTH = 64;
+declare function encodeWireName(id: string): string;
+/**
+ * Wire name disambiguated per instance: providers require UNIQUE tool names,
+ * so when several live instances expose the same capability the adapter
+ * appends `_at_<instanceId>` (docs/09 rule 7 — the id↔name map stays
+ * authoritative; instance ids never contain "." so decoding stays possible
+ * by stripping the suffix).
+ */
+declare function encodeWireNameForInstance(id: string, instanceId?: string): string;
+/**
+ * Reverses `encodeWireName` for non-truncated names. Truncated names cannot
+ * be decoded — the adapter's id↔name map is authoritative (docs/09 rule 7).
+ */
+declare function decodeWireName(name: string): string | undefined;
+
+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[];
+
+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;
+}
+/** 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>;
+}
+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;
+    };
+}
+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;
+    description: 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;
+
+interface AgentToolsetOptions {
+    consumer: AgentConsumer;
+    /** "direct": one tool per capability. "meta": 3 generic tools. [meta: Experimental] */
+    mode?: "direct" | "meta";
+    /**
+     * Loop topology (D26). Sets the confirmation-mode default: "embedded" →
+     * "wait", "remote" → "two-phase". One of `topology` or `confirmations`
+     * MUST be provided — there is no ambiguous global default.
+     */
+    topology?: "embedded" | "remote";
+    /**
+     * "wait": on CONFIRMATION_REQUIRED, await user resolution (up to TTL) and
+     * auto-retry, so the model sees one tool call → one final result.
+     * "two-phase": surface CONFIRMATION_REQUIRED to the model, which retries.
+     * Overrides the topology default (a remote loop opting into "wait" owns
+     * its transport-timeout story, docs/09 §confirmation-topology).
+     */
+    confirmations?: "wait" | "two-phase";
+    scope?: string[];
+}
+interface AgentTool {
+    /** Wire-safe name (docs/09 §wire-names), ≤ 64 chars. */
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    execute(input: JsonValue, call: {
+        toolCallId?: string;
+    }): Promise<AgentInvocationResult>;
+}
+interface AgentToolset {
+    tools(): AgentTool[];
+    /** Fires when tools() would return a different catalog. */
+    subscribe(listener: (tools: AgentTool[]) => void): Unsubscribe;
+    dispose(): void;
+}
+declare function createAgentToolset(registry: AgentSurfaceRegistry, options: AgentToolsetOptions): AgentToolset;
+
+/** Deep equality over JsonValue (order-sensitive for arrays, docs/06 rule 2). */
+declare function jsonDeepEqual(a: JsonValue | undefined, b: JsonValue | undefined): boolean;
+
+export { AGENT_CAPABILITY_ERROR_CODES, type AgentActionContext, type AgentActionDefinition, type AgentActionDescriptor, type AgentAuthorizationContext, type AgentCapabilityDescriptorUnion, type AgentCapabilityErrorCode, type AgentCapabilityErrorPayload, type AgentComponentDefinition, type AgentComponentDescriptor, type AgentConsumer, type AgentEffect, type AgentEnvironment, type AgentErrorRetry, type AgentInvocation, type AgentInvocationPolicyContext, type AgentInvocationResult, type AgentObservationDefinition, type AgentObservationDescriptor, type AgentPlane, type AgentPolicy, type AgentPolicyContext, type AgentProcedureBinding, type AgentProcedureBindingRuntimeConfig, type AgentProcedureDescriptor, type AgentProcedureEffect, type AgentProcedureExecutor, type AgentProcedureRefDescriptor, type AgentReadContext, type AgentRegistrationHandle, type AgentRouteInfo, type AgentSchema, AgentSchemaError, type AgentSchemaIssue, AgentSurfaceDefinitionError, type AgentSurfaceDefinitionErrorCode, AgentSurfaceError, type AgentSurfaceEvent, type AgentSurfaceLimits, type AgentSurfaceRegistry, type AgentSurfaceSnapshot, type AgentTool, type AgentToolset, type AgentToolsetOptions, type AuditEvent, type AuditSink, CONFIRMATION_ESCALATION, type ConfirmationController, type ConfirmationEscalation, DEFAULT_LIMITS, type DiscoveryDecision, type InvokeOptions, type JsonSchema, type JsonValue, MAX_ID_LENGTH, MAX_WIRE_NAME_LENGTH, type ParsedCapabilityId, type PendingConfirmation, type PreconditionFailure, type ProcedureCallInfo, type RegistrationCandidate, type RegistryOptions, type SnapshotContext, type StandardSchemaV1, type Unsubscribe, action, audit, authenticated, composeInvokeChain, consoleAuditSink, createAgentSurfaceRegistry, createAgentToolset, decodeWireName, defineAgentComponent, emptyObjectSchema, encodeWireName, encodeWireNameForInstance, environment, evaluateDiscovery, formatDomainCapabilityId, formatViewCapabilityId, fromJsonSchema, fromStandardSchema, hasPermission, isAgentSurfaceError, isValidCapabilityName, isValidComponentType, isValidInstanceId, jsonDeepEqual, memoryAuditSink, observation, parseCapabilityId, rateLimit, requireConfirmation, tenantBoundary, validateComponentDefinition, validateJsonSchemaDocument, validateValueAgainstSchema };