@agent-surface/core 0.15.0 → 0.17.0

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

@@ -719,6 +719,178 @@ 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: 4;
+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;
+}
+declare const CAPABILITY_AUTHORITY_TYPE: unique symbol;
+/** Immutable runtime source of truth. Only objects minted here are accepted. */
+interface CapabilityAuthority {
+    readonly manifest: CapabilityContractManifest;
+    readonly [CAPABILITY_AUTHORITY_TYPE]: true;
+}
+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>): 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> {
+    readonly kind: "agent-procedure-contract";
+    readonly definition: AgentProcedureContractDefinition<TIn, TOut>;
+}
+declare function defineAgentProcedureContract<TIn extends JsonValue, TOut extends JsonValue = JsonValue>(definition: AgentProcedureContractDefinition<TIn, TOut>): 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>;
+}
+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>): ExternalAgentToolContract<TIn, TOut>;
+/** Preserve compiler proof while an adapter replaces handlers with latest-ref delegates. */
+declare function deriveAgentComponentBinding(source: AgentComponentDefinition, derived: AgentComponentDefinition): AgentComponentDefinition;
+/** Bind a compiled procedure contract to its contextual runtime definition. */
+declare function authorizeAgentProcedureBinding(contract: AgentProcedureContract<any, any>, definition: AgentComponentDefinition): AgentComponentDefinition;
+declare function createCapabilityAuthority(manifest: CapabilityContractManifest): CapabilityAuthority;
+/** Mandatory runtime authority check used by every registry registration. */
+declare function assertDefinitionAuthorized(definition: AgentComponentDefinition, authority: CapabilityAuthority): void;
+interface AgentExposureGateway {
+    expose<T extends CompiledExternalAgentTool>(tools: readonly T[]): T[];
+}
+/** Final provider/MCP boundary: arbitrary tool objects cannot pass. */
+declare function createAgentExposureGateway(authority: CapabilityAuthority): AgentExposureGateway;
+
 interface RegistrationCandidate {
     definition: AgentComponentDefinition;
     stack?: string;
@@ -743,6 +915,8 @@ interface RegistryOptions {
     limits?: Partial<AgentSurfaceLimits>;
     /** Injectable clock (docs/08 determinism); default Date.now. */
     now?: () => number;
+    /** Compiler-generated runtime source of truth. Required outside repository tests. */
+    authority?: CapabilityAuthority;
 }
 interface AgentRegistrationHandle {
     readonly registrationId: string;
@@ -774,4 +948,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, CONFIRMATION_ESCALATION as a4, type CapabilityAuthority as a5, type CapabilityContractEntry as a6, type CapabilityContractKind as a7, type CapabilityContractManifest as a8, type CapabilityPolicyAttachment as a9, defineAgentComponentContract as aA, defineAgentProcedureContract as aB, defineExternalAgentToolContract as aC, deriveAgentComponentBinding 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, validateComponentDefinition as aR, validateJsonSchemaDocument as aS, validateValueAgainstSchema as aT, type CompiledExternalAgentTool as aa, type ConfirmationController as ab, type ConfirmationEscalation as ac, DEFAULT_LIMITS as ad, type ExternalAgentToolContract as ae, type ExternalAgentToolContractDefinition as af, type ExternalCapabilityContractDigest as ag, type InvokeOptions as ah, type PendingConfirmation as ai, type PreconditionFailure as aj, type ProcedureCallInfo as ak, type RegistrationCandidate as al, type RegistryOptions as am, type StandardSchemaV1 as an, action as ao, actionContract as ap, assertDefinitionAuthorized as aq, audit as ar, authenticated as as, authorizeAgentProcedureBinding as at, composeInvokeChain as au, consoleAuditSink as av, createAgentExposureGateway as aw, createAgentSurfaceRegistry as ax, createCapabilityAuthority as ay, defineAgentComponent 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.17.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": "22 kB"
     },
     {
       "path": "dist/explain.js",