@agent-surface/core 0.15.0 → 0.16.0

package/dist/{registry-XD1QsGQ4.d.ts → registry-CWjIFWHV.d.ts}

@@ -719,6 +719,186 @@ interface AgentProcedureDescriptor {
 type AgentCapabilityDescriptorUnion = AgentObservationDescriptor | AgentActionDescriptor | AgentProcedureDescriptor;
 declare function matchesScope(type: string, scope: string[] | undefined): boolean;
 
+/** Contract format emitted by @agent-surface/compiler. */
+declare const CAPABILITY_CONTRACT_FORMAT_VERSION: 3;
+type CapabilityContractKind = "observation" | "action" | "procedure" | "external";
+interface CapabilityPolicyAttachment {
+    name: string;
+    phase?: "discovery" | "authorize" | "invoke";
+}
+interface CapabilityContractEntry {
+    declarationId: string;
+    capabilityId: string;
+    kind: CapabilityContractKind;
+    description: string;
+    effect: AgentEffect;
+    inputSchema?: JsonSchema;
+    outputSchema?: JsonSchema;
+    confirmation?: "never" | "optional" | "required";
+    policies?: CapabilityPolicyAttachment[];
+    tags?: string[];
+    contractHash: string;
+    targets: string[];
+    origin: string;
+}
+interface ExternalCapabilityContractDigest {
+    package?: string;
+    source: string;
+    digest: string;
+}
+interface CapabilityContractManifest {
+    formatVersion: typeof CAPABILITY_CONTRACT_FORMAT_VERSION;
+    compilerVersion: string;
+    targets: string[];
+    capabilities: CapabilityContractEntry[];
+    externalContracts: ExternalCapabilityContractDigest[];
+    completeness: {
+        status: "proven";
+    };
+    /** sha256 of the canonical manifest payload without this field. */
+    hash: string;
+}
+interface CompiledCapabilityToken {
+    manifestHash: string;
+    declarationId: string;
+    capabilityId: string;
+    contractHash: string;
+}
+interface CompiledComponentProvenance {
+    manifestHash: string;
+    declarationId: string;
+    capabilities: Record<string, CompiledCapabilityToken>;
+}
+/** Shared across duplicate copies of core in a bundle. Not enumerable/serializable. */
+declare const COMPILED_CAPABILITY_PROVENANCE: unique symbol;
+type ProvenanceCarrier = {
+    [COMPILED_CAPABILITY_PROVENANCE]?: CompiledComponentProvenance | CompiledCapabilityToken;
+};
+interface AgentObservationContract<TOut extends JsonValue> {
+    description: string;
+    output: AgentSchema<TOut>;
+    meta?: Record<string, JsonValue>;
+    timeoutMs?: number;
+    policies?: CapabilityPolicyAttachment[];
+    tags?: string[];
+}
+interface AgentActionContract<TIn extends JsonValue, TOut extends JsonValue | void = void> {
+    description: string;
+    input: AgentSchema<TIn>;
+    output?: AgentSchema<Exclude<TOut, void>>;
+    effect: "local-state" | "navigation";
+    idempotent?: boolean;
+    reversible?: boolean;
+    confirmation?: "never" | "optional" | "required";
+    audit?: "none" | "metadata" | "full";
+    meta?: Record<string, JsonValue>;
+    timeoutMs?: number;
+    concurrency?: AgentConcurrency;
+    policies?: CapabilityPolicyAttachment[];
+    tags?: string[];
+}
+declare function observationContract<TOut extends JsonValue>(contract: AgentObservationContract<TOut>): AgentObservationContract<TOut>;
+declare function actionContract<TIn extends JsonValue, TOut extends JsonValue | void = void>(contract: AgentActionContract<TIn, TOut>): AgentActionContract<TIn, TOut>;
+type ObservationBindings<C> = C extends AgentObservationContract<infer TOut> ? {
+    read(ctx: AgentReadContext): TOut | Promise<TOut>;
+    when?: () => boolean;
+    unavailableReason?: string | (() => string);
+    policies?: AgentPolicy[];
+} : never;
+type ActionBindings<C> = C extends AgentActionContract<infer TIn, infer TOut> ? {
+    execute(input: TIn, ctx: AgentActionContext): TOut | Promise<TOut>;
+    when?: () => boolean;
+    unavailableReason?: string | (() => string);
+    precondition?(input: TIn, ctx: AgentReadContext): void | PreconditionFailure;
+    policies?: AgentPolicy[];
+} : never;
+interface AgentComponentContractDefinition<TObservations extends Record<string, AgentObservationContract<any>> = Record<string, AgentObservationContract<any>>, TActions extends Record<string, AgentActionContract<any, any>> = Record<string, AgentActionContract<any, any>>> {
+    type: string;
+    description: string;
+    meta?: Record<string, JsonValue>;
+    origin?: string;
+    priority?: number;
+    policies?: CapabilityPolicyAttachment[];
+    tags?: string[];
+    observations?: TObservations;
+    actions?: TActions;
+}
+interface AgentComponentRuntimeBindings<TObservations extends Record<string, AgentObservationContract<any>>, TActions extends Record<string, AgentActionContract<any, any>>> {
+    instanceId?: string;
+    parent?: {
+        type: string;
+        instanceId?: string;
+    };
+    internal?: Record<string, unknown>;
+    enabled?: boolean;
+    policies?: AgentPolicy[];
+    observations?: {
+        [K in keyof TObservations]: ObservationBindings<TObservations[K]>;
+    };
+    actions?: {
+        [K in keyof TActions]: ActionBindings<TActions[K]>;
+    };
+    procedures?: AgentProcedureBinding<any, any>[];
+}
+interface AgentComponentContract<TObservations extends Record<string, AgentObservationContract<any>>, TActions extends Record<string, AgentActionContract<any, any>>> extends AgentComponentContractDefinition<TObservations, TActions> {
+    readonly kind: "agent-component-contract";
+    bind(bindings: AgentComponentRuntimeBindings<TObservations, TActions>): AgentComponentDefinition;
+}
+/**
+ * Compiler macro. The second argument is injected by @agent-surface/compiler;
+ * author code must never supply it.
+ */
+declare function defineAgentComponentContract<TObservations extends Record<string, AgentObservationContract<any>> = Record<never, never>, TActions extends Record<string, AgentActionContract<any, any>> = Record<never, never>>(definition: AgentComponentContractDefinition<TObservations, TActions>, compiled?: CompiledComponentProvenance): AgentComponentContract<TObservations, TActions>;
+interface ExternalAgentToolContractDefinition<TIn extends JsonValue, TOut extends JsonValue> {
+    id: string;
+    description: string;
+    input: AgentSchema<TIn>;
+    output?: AgentSchema<TOut>;
+    effect: AgentEffect;
+    confirmation?: "never" | "optional" | "required";
+    policies?: CapabilityPolicyAttachment[];
+    tags?: string[];
+}
+interface AgentProcedureContractDefinition<TIn extends JsonValue, TOut extends JsonValue> {
+    id: `domain:${string}`;
+    description: string;
+    input: AgentSchema<TIn>;
+    output?: AgentSchema<TOut>;
+    effect: "server-query" | "server-mutation" | "external-side-effect" | "destructive";
+    confirmation?: "never" | "optional" | "required";
+    policies?: CapabilityPolicyAttachment[];
+    tags?: string[];
+}
+interface AgentProcedureContract<TIn extends JsonValue, TOut extends JsonValue> extends ProvenanceCarrier {
+    readonly kind: "agent-procedure-contract";
+    readonly definition: AgentProcedureContractDefinition<TIn, TOut>;
+}
+declare function defineAgentProcedureContract<TIn extends JsonValue, TOut extends JsonValue = JsonValue>(definition: AgentProcedureContractDefinition<TIn, TOut>, compiled?: CompiledCapabilityToken): AgentProcedureContract<TIn, TOut>;
+interface CompiledExternalAgentTool<TIn extends JsonValue = JsonValue, TOut extends JsonValue = JsonValue> {
+    name: string;
+    description: string;
+    inputSchema: JsonSchema;
+    execute(input: TIn): TOut | Promise<TOut>;
+    [COMPILED_CAPABILITY_PROVENANCE]: CompiledCapabilityToken;
+}
+interface ExternalAgentToolContract<TIn extends JsonValue, TOut extends JsonValue> {
+    readonly kind: "external-agent-tool-contract";
+    readonly definition: ExternalAgentToolContractDefinition<TIn, TOut>;
+    bind(binding: {
+        execute(input: TIn): TOut | Promise<TOut>;
+    }): CompiledExternalAgentTool<TIn, TOut>;
+}
+declare function defineExternalAgentToolContract<TIn extends JsonValue, TOut extends JsonValue = JsonValue>(definition: ExternalAgentToolContractDefinition<TIn, TOut>, compiled?: CompiledCapabilityToken): ExternalAgentToolContract<TIn, TOut>;
+declare function compiledCapabilityToken(contract: AgentProcedureContract<any, any> | ExternalAgentToolContract<any, any>): CompiledCapabilityToken;
+declare function tryCompiledCapabilityToken(contract: AgentProcedureContract<any, any> | ExternalAgentToolContract<any, any>): CompiledCapabilityToken | undefined;
+/** Runtime exposure ceiling used by the registry. */
+declare function assertDefinitionInManifest(definition: AgentComponentDefinition, manifest: CapabilityContractManifest): void;
+interface AgentExposureGateway {
+    expose<T extends CompiledExternalAgentTool>(tools: readonly T[]): T[];
+}
+/** Final provider/MCP boundary: arbitrary tool objects cannot pass. */
+declare function createAgentExposureGateway(manifest: CapabilityContractManifest): AgentExposureGateway;
+
 interface RegistrationCandidate {
     definition: AgentComponentDefinition;
     stack?: string;
@@ -743,6 +923,8 @@ interface RegistryOptions {
     limits?: Partial<AgentSurfaceLimits>;
     /** Injectable clock (docs/08 determinism); default Date.now. */
     now?: () => number;
+    /** Compiler-generated runtime ceiling. When present, raw/stale bindings fail closed. */
+    manifest?: CapabilityContractManifest;
 }
 interface AgentRegistrationHandle {
     readonly registrationId: string;
@@ -774,4 +956,4 @@ interface AgentSurfaceRegistry {
 }
 declare function createAgentSurfaceRegistry(options?: RegistryOptions): AgentSurfaceRegistry;
 
-export { type InvokeOptions as $, type AgentRouteInfo as A, type AgentProcedureBindingRuntimeConfig as B, type AgentProcedureDescriptor as C, type DiscoveryDecision as D, type AgentProcedureEffect as E, type AgentProcedureExecutor as F, type AgentProcedureRefDescriptor as G, type AgentReadContext as H, type AgentRegistrationHandle as I, type JsonSchema as J, type AgentSchema as K, AgentSchemaError as L, type AgentSchemaIssue as M, AgentSurfaceDefinitionError as N, type AgentSurfaceDefinitionErrorCode as O, AgentSurfaceError as P, type AgentSurfaceEvent as Q, type AgentSurfaceLimits as R, type SnapshotContext as S, type AgentSurfaceSnapshot as T, type Unsubscribe as U, type AuditEvent as V, type AuditSink as W, CONFIRMATION_ESCALATION as X, type ConfirmationController as Y, type ConfirmationEscalation as Z, DEFAULT_LIMITS as _, type AgentConsumer as a, type PendingConfirmation as a0, type PreconditionFailure as a1, type ProcedureCallInfo as a2, type RegistrationCandidate as a3, type RegistryOptions as a4, type StandardSchemaV1 as a5, action as a6, audit as a7, authenticated as a8, composeInvokeChain as a9, consoleAuditSink as aa, createAgentSurfaceRegistry as ab, defineAgentComponent as ac, emptyObjectSchema as ad, environment as ae, evaluateDiscovery as af, fromJsonSchema as ag, fromStandardSchema as ah, hasPermission as ai, isAgentSurfaceError as aj, memoryAuditSink as ak, observation as al, rateLimit as am, requireConfirmation as an, tenantBoundary as ao, validateComponentDefinition as ap, validateJsonSchemaDocument as aq, validateValueAgainstSchema as ar, 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, matchesScope as m, type AgentComponentDefinition as n, type AgentComponentDescriptor as o, type AgentConcurrency as p, type AgentEffect as q, type AgentEnvironment as r, type AgentErrorRetry as s, type AgentInvocation as t, type AgentInvocationPolicyContext as u, type AgentObservationDefinition as v, type AgentObservationDescriptor as w, type AgentPolicy as x, type AgentPolicyContext as y, type AgentProcedureBinding as z };
+export { type AgentSurfaceLimits as $, type AgentRouteInfo as A, type AgentObservationContract as B, type AgentObservationDefinition as C, type DiscoveryDecision as D, type AgentObservationDescriptor as E, type AgentPolicy as F, type AgentPolicyContext as G, type AgentProcedureBinding as H, type AgentProcedureBindingRuntimeConfig as I, type JsonSchema as J, type AgentProcedureContract as K, type AgentProcedureContractDefinition as L, type AgentProcedureDescriptor as M, type AgentProcedureEffect as N, type AgentProcedureExecutor as O, type AgentProcedureRefDescriptor as P, type AgentReadContext as Q, type AgentRegistrationHandle as R, type SnapshotContext as S, type AgentSchema as T, type Unsubscribe as U, AgentSchemaError as V, type AgentSchemaIssue as W, AgentSurfaceDefinitionError as X, type AgentSurfaceDefinitionErrorCode as Y, AgentSurfaceError as Z, type AgentSurfaceEvent as _, type AgentConsumer as a, type AgentSurfaceSnapshot as a0, type AuditEvent as a1, type AuditSink as a2, CAPABILITY_CONTRACT_FORMAT_VERSION as a3, COMPILED_CAPABILITY_PROVENANCE as a4, CONFIRMATION_ESCALATION as a5, type CapabilityContractEntry as a6, type CapabilityContractKind as a7, type CapabilityContractManifest as a8, type CapabilityPolicyAttachment as a9, defineAgentComponent as aA, defineAgentComponentContract as aB, defineAgentProcedureContract as aC, defineExternalAgentToolContract as aD, emptyObjectSchema as aE, environment as aF, evaluateDiscovery as aG, fromJsonSchema as aH, fromStandardSchema as aI, hasPermission as aJ, isAgentSurfaceError as aK, memoryAuditSink as aL, observation as aM, observationContract as aN, rateLimit as aO, requireConfirmation as aP, tenantBoundary as aQ, tryCompiledCapabilityToken as aR, validateComponentDefinition as aS, validateJsonSchemaDocument as aT, validateValueAgainstSchema as aU, type CompiledCapabilityToken as aa, type CompiledComponentProvenance as ab, type CompiledExternalAgentTool as ac, type ConfirmationController as ad, type ConfirmationEscalation as ae, DEFAULT_LIMITS as af, type ExternalAgentToolContract as ag, type ExternalAgentToolContractDefinition as ah, type ExternalCapabilityContractDigest as ai, type InvokeOptions as aj, type PendingConfirmation as ak, type PreconditionFailure as al, type ProcedureCallInfo as am, type RegistrationCandidate as an, type RegistryOptions as ao, type StandardSchemaV1 as ap, action as aq, actionContract as ar, assertDefinitionInManifest as as, audit as at, authenticated as au, compiledCapabilityToken as av, composeInvokeChain as aw, consoleAuditSink as ax, createAgentExposureGateway as ay, createAgentSurfaceRegistry as az, type AgentSurfaceRegistry as b, type JsonValue as c, type AgentInvocationResult as d, AGENT_CAPABILITY_ERROR_CODES as e, type AgentActionContext as f, type AgentActionContract as g, type AgentActionDefinition as h, type AgentActionDescriptor as i, type AgentAuthorizationContext as j, type AgentCapabilityDescriptorUnion as k, type AgentCapabilityErrorCode as l, matchesScope as m, type AgentCapabilityErrorPayload as n, type AgentComponentContract as o, type AgentComponentContractDefinition as p, type AgentComponentDefinition as q, type AgentComponentDescriptor as r, type AgentComponentRuntimeBindings as s, type AgentConcurrency as t, type AgentEffect as u, type AgentEnvironment as v, type AgentErrorRetry as w, type AgentExposureGateway as x, type AgentInvocation as y, type AgentInvocationPolicyContext as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-surface/core",
-  "version": "0.15.0",
+  "version": "0.16.0",
   "description": "Framework-agnostic registry, types, policies, errors, snapshot, invocation for frontend agent surfaces",
   "license": "MIT",
   "type": "module",
@@ -58,7 +58,7 @@
   "size-limit": [
     {
       "path": "dist/index.js",
-      "limit": "19.5 kB"
+      "limit": "20.5 kB"
     },
     {
       "path": "dist/explain.js",