@agent-surface/core 0.15.0 → 0.16.0

package/README.md

@@ -1,49 +1,22 @@
-# @agent-surface/core
+# `@agent-surface/core`
 
-Framework-agnostic core of [agent-surface](https://github.com/Wiseair-srl/agent-surface): a registry for declaring an explicit, semantic, typed, policy-governed *agent surface* over a frontend — and nothing more. If a component or capability is not explicitly annotated, it does not exist for the agent.
-
-Zero runtime dependencies. Provides: canonical capability ids, the `AgentSchema` layer (Standard Schema + built-in JSON Schema subset validator), component/capability definitions, the registry (registration lifecycle, availability, versioning, staleness), synchronous snapshots, the 10-phase invocation pipeline, composable policies, single-use confirmation evidence, audit sinks, and a provider-neutral toolset projection for embedded agent loops.
-
-Docs: https://agent-surface-docs.vercel.app
-
-## Install
-
-```bash
-pnpm add @agent-surface/core
-```
-
-## Use
+Framework-neutral contracts, registry, policy, confirmation, invocation and exposure gateway.
 
 ```ts
-import {
-  createAgentSurfaceRegistry,
-  defineAgentComponent,
-  observation,
-  action,
-  fromStandardSchema,
-  createAgentToolset,
-} from "@agent-surface/core";
-
-const registry = createAgentSurfaceRegistry({
-  environment: import.meta.env.DEV ? "development" : "production",
-  context: () => ({ user: authStore.user }),
+const contract = defineAgentComponentContract({
+  type: "devices.table",
+  description: "Device table",
+  observations: { readState: observationContract({ description: "State", output }) },
+  actions: { selectRows: actionContract({ description: "Select", input, effect: "local-state" }) },
 });
 
-registry.register(
-  defineAgentComponent({
-    type: "devices.table",
-    description: "Table of the devices visible on the current page",
-    observations: { readState: observation({ /* … */ }) },
-    actions: { selectRows: action({ /* … */ }) },
-  }),
-);
-
-const toolset = createAgentToolset(registry, {
-  consumer: { id: "copilot", kind: "embedded" },
-  topology: "embedded",   // required (D26): embedded → confirmations "wait",
-});                       // remote → "two-phase". No global default.
+const registry = createAgentSurfaceRegistry({ manifest });
+registry.register(contract.bind({
+  observations: { readState: { read } },
+  actions: { selectRows: { execute } },
+}));
 ```
 
-React apps should use [`@agent-surface/react`](https://www.npmjs.com/package/@agent-surface/react) instead of calling `register` directly. Full specification: [docs](https://github.com/Wiseair-srl/agent-surface/tree/main/docs).
+With a compiler manifest installed, raw/unknown/stale/mismatched registrations fail closed. Use `createAgentExposureGateway()` at final provider/MCP assembly.
 
-MIT © Wiseair S.r.l.
+See [Core API](../../docs/03-core-api.md).

package/dist/explain.d.ts

@@ -1,5 +1,5 @@
-import { D as DiscoveryDecision, A as AgentRouteInfo, a as AgentConsumer, b as AgentSurfaceRegistry, S as SnapshotContext } from './registry-XD1QsGQ4.js';
-export { m as matchesScope } from './registry-XD1QsGQ4.js';
+import { D as DiscoveryDecision, A as AgentRouteInfo, a as AgentConsumer, b as AgentSurfaceRegistry, S as SnapshotContext } from './registry-CWjIFWHV.js';
+export { m as matchesScope } from './registry-CWjIFWHV.js';
 
 /**
  * `explainSurface()` — the developer projection.

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { J as JsonSchema, c as JsonValue, d as AgentInvocationResult, U as Unsubscribe, a as AgentConsumer, b as AgentSurfaceRegistry } from './registry-XD1QsGQ4.js';
-export { e as AGENT_CAPABILITY_ERROR_CODES, f as AgentActionContext, g as AgentActionDefinition, h as AgentActionDescriptor, i as AgentAuthorizationContext, j as AgentCapabilityDescriptorUnion, k as AgentCapabilityErrorCode, l as AgentCapabilityErrorPayload, n as AgentComponentDefinition, o as AgentComponentDescriptor, p as AgentConcurrency, q as AgentEffect, r as AgentEnvironment, s as AgentErrorRetry, t as AgentInvocation, u as AgentInvocationPolicyContext, v as AgentObservationDefinition, w as AgentObservationDescriptor, x as AgentPolicy, y as AgentPolicyContext, z as AgentProcedureBinding, B as AgentProcedureBindingRuntimeConfig, C as AgentProcedureDescriptor, E as AgentProcedureEffect, F as AgentProcedureExecutor, G as AgentProcedureRefDescriptor, H as AgentReadContext, I as AgentRegistrationHandle, A as AgentRouteInfo, K as AgentSchema, L as AgentSchemaError, M as AgentSchemaIssue, N as AgentSurfaceDefinitionError, O as AgentSurfaceDefinitionErrorCode, P as AgentSurfaceError, Q as AgentSurfaceEvent, R as AgentSurfaceLimits, T as AgentSurfaceSnapshot, V as AuditEvent, W as AuditSink, X as CONFIRMATION_ESCALATION, Y as ConfirmationController, Z as ConfirmationEscalation, _ as DEFAULT_LIMITS, D as DiscoveryDecision, $ as InvokeOptions, a0 as PendingConfirmation, a1 as PreconditionFailure, a2 as ProcedureCallInfo, a3 as RegistrationCandidate, a4 as RegistryOptions, S as SnapshotContext, a5 as StandardSchemaV1, a6 as action, a7 as audit, a8 as authenticated, a9 as composeInvokeChain, aa as consoleAuditSink, ab as createAgentSurfaceRegistry, ac as defineAgentComponent, ad as emptyObjectSchema, ae as environment, af as evaluateDiscovery, ag as fromJsonSchema, ah as fromStandardSchema, ai as hasPermission, aj as isAgentSurfaceError, ak as memoryAuditSink, al as observation, am as rateLimit, an as requireConfirmation, ao as tenantBoundary, ap as validateComponentDefinition, aq as validateJsonSchemaDocument, ar as validateValueAgainstSchema } from './registry-XD1QsGQ4.js';
+import { J as JsonSchema, c as JsonValue, d as AgentInvocationResult, U as Unsubscribe, a as AgentConsumer, b as AgentSurfaceRegistry } from './registry-CWjIFWHV.js';
+export { e as AGENT_CAPABILITY_ERROR_CODES, f as AgentActionContext, g as AgentActionContract, h as AgentActionDefinition, i as AgentActionDescriptor, j as AgentAuthorizationContext, k as AgentCapabilityDescriptorUnion, l as AgentCapabilityErrorCode, n as AgentCapabilityErrorPayload, o as AgentComponentContract, p as AgentComponentContractDefinition, q as AgentComponentDefinition, r as AgentComponentDescriptor, s as AgentComponentRuntimeBindings, t as AgentConcurrency, u as AgentEffect, v as AgentEnvironment, w as AgentErrorRetry, x as AgentExposureGateway, y as AgentInvocation, z as AgentInvocationPolicyContext, B as AgentObservationContract, C as AgentObservationDefinition, E as AgentObservationDescriptor, F as AgentPolicy, G as AgentPolicyContext, H as AgentProcedureBinding, I as AgentProcedureBindingRuntimeConfig, K as AgentProcedureContract, L as AgentProcedureContractDefinition, M as AgentProcedureDescriptor, N as AgentProcedureEffect, O as AgentProcedureExecutor, P as AgentProcedureRefDescriptor, Q as AgentReadContext, R as AgentRegistrationHandle, A as AgentRouteInfo, T as AgentSchema, V as AgentSchemaError, W as AgentSchemaIssue, X as AgentSurfaceDefinitionError, Y as AgentSurfaceDefinitionErrorCode, Z as AgentSurfaceError, _ as AgentSurfaceEvent, $ as AgentSurfaceLimits, a0 as AgentSurfaceSnapshot, a1 as AuditEvent, a2 as AuditSink, a3 as CAPABILITY_CONTRACT_FORMAT_VERSION, a4 as COMPILED_CAPABILITY_PROVENANCE, a5 as CONFIRMATION_ESCALATION, a6 as CapabilityContractEntry, a7 as CapabilityContractKind, a8 as CapabilityContractManifest, a9 as CapabilityPolicyAttachment, aa as CompiledCapabilityToken, ab as CompiledComponentProvenance, ac as CompiledExternalAgentTool, ad as ConfirmationController, ae as ConfirmationEscalation, af as DEFAULT_LIMITS, D as DiscoveryDecision, ag as ExternalAgentToolContract, ah as ExternalAgentToolContractDefinition, ai as ExternalCapabilityContractDigest, aj as InvokeOptions, ak as PendingConfirmation, al as PreconditionFailure, am as ProcedureCallInfo, an as RegistrationCandidate, ao as RegistryOptions, S as SnapshotContext, ap as StandardSchemaV1, aq as action, ar as actionContract, as as assertDefinitionInManifest, at as audit, au as authenticated, av as compiledCapabilityToken, aw as composeInvokeChain, ax as consoleAuditSink, ay as createAgentExposureGateway, az as createAgentSurfaceRegistry, aA as defineAgentComponent, aB as defineAgentComponentContract, aC as defineAgentProcedureContract, aD as defineExternalAgentToolContract, aE as emptyObjectSchema, aF as environment, aG as evaluateDiscovery, aH as fromJsonSchema, aI as fromStandardSchema, aJ as hasPermission, aK as isAgentSurfaceError, aL as memoryAuditSink, aM as observation, aN as observationContract, aO as rateLimit, aP as requireConfirmation, aQ as tenantBoundary, aR as tryCompiledCapabilityToken, aS as validateComponentDefinition, aT as validateJsonSchemaDocument, aU as validateValueAgainstSchema } from './registry-CWjIFWHV.js';
 
 /**
  * Canonical ID grammar (docs/01 §identity):

package/dist/index.js

@@ -1945,6 +1945,251 @@ function drainObservationQueues(internals) {
   for (const waiter of waiting) waiter.admit(false);
 }
 
+// src/contract.ts
+var CAPABILITY_CONTRACT_FORMAT_VERSION = 3;
+var COMPILED_CAPABILITY_PROVENANCE = /* @__PURE__ */ Symbol.for(
+  "@agent-surface/core.compiled-capability-provenance"
+);
+function observationContract(contract) {
+  return contract;
+}
+function actionContract(contract) {
+  return contract;
+}
+function defineAgentComponentContract(definition, compiled) {
+  const contract = {
+    ...definition,
+    kind: "agent-component-contract",
+    bind(bindings) {
+      const observations = {};
+      for (const [name, authored] of Object.entries(definition.observations ?? {})) {
+        const runtime = bindings.observations?.[name];
+        if (!runtime?.read) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `contract "${definition.type}" observation "${name}" has no runtime binding`
+          );
+        }
+        observations[name] = {
+          description: authored.description,
+          output: authored.output,
+          read: runtime.read,
+          ...authored.meta ? { meta: authored.meta } : {},
+          ...authored.timeoutMs !== void 0 ? { timeoutMs: authored.timeoutMs } : {},
+          ...runtime.when ? { when: runtime.when } : {},
+          ...runtime.unavailableReason ? { unavailableReason: runtime.unavailableReason } : {},
+          ...runtime.policies ? { policies: runtime.policies } : {}
+        };
+      }
+      const actions = {};
+      for (const [name, authored] of Object.entries(definition.actions ?? {})) {
+        const runtime = bindings.actions?.[name];
+        if (!runtime?.execute) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `contract "${definition.type}" action "${name}" has no runtime binding`
+          );
+        }
+        actions[name] = {
+          description: authored.description,
+          input: authored.input,
+          ...authored.output ? { output: authored.output } : {},
+          effect: authored.effect,
+          execute: runtime.execute,
+          ...authored.idempotent !== void 0 ? { idempotent: authored.idempotent } : {},
+          ...authored.reversible !== void 0 ? { reversible: authored.reversible } : {},
+          ...authored.confirmation !== void 0 ? { confirmation: authored.confirmation } : {},
+          ...authored.audit !== void 0 ? { audit: authored.audit } : {},
+          ...authored.meta ? { meta: authored.meta } : {},
+          ...authored.timeoutMs !== void 0 ? { timeoutMs: authored.timeoutMs } : {},
+          ...authored.concurrency ? { concurrency: authored.concurrency } : {},
+          ...runtime.when ? { when: runtime.when } : {},
+          ...runtime.unavailableReason ? { unavailableReason: runtime.unavailableReason } : {},
+          ...runtime.precondition ? { precondition: runtime.precondition } : {},
+          ...runtime.policies ? { policies: runtime.policies } : {}
+        };
+      }
+      const bound = {
+        type: definition.type,
+        description: definition.description,
+        ...bindings.instanceId !== void 0 ? { instanceId: bindings.instanceId } : {},
+        ...bindings.parent ? { parent: bindings.parent } : {},
+        ...definition.meta ? { meta: definition.meta } : {},
+        ...bindings.internal ? { internal: bindings.internal } : {},
+        ...bindings.policies ? { policies: bindings.policies } : {},
+        ...definition.origin ? { origin: definition.origin } : {},
+        ...definition.priority !== void 0 ? { priority: definition.priority } : {},
+        ...bindings.enabled !== void 0 ? { enabled: bindings.enabled } : {},
+        ...Object.keys(observations).length > 0 ? { observations } : {},
+        ...Object.keys(actions).length > 0 ? { actions } : {},
+        ...bindings.procedures ? { procedures: bindings.procedures } : {}
+      };
+      if (compiled) {
+        Object.defineProperty(bound, COMPILED_CAPABILITY_PROVENANCE, {
+          value: compiled,
+          enumerable: false
+        });
+      }
+      return bound;
+    }
+  };
+  return contract;
+}
+function defineAgentProcedureContract(definition, compiled) {
+  const contract = {
+    kind: "agent-procedure-contract",
+    definition
+  };
+  if (compiled) {
+    Object.defineProperty(contract, COMPILED_CAPABILITY_PROVENANCE, {
+      value: compiled,
+      enumerable: false
+    });
+  }
+  return contract;
+}
+function defineExternalAgentToolContract(definition, compiled) {
+  const contract = {
+    kind: "external-agent-tool-contract",
+    definition,
+    bind(binding) {
+      if (!compiled) {
+        throw new AgentSurfaceDefinitionError(
+          "INVALID_DEFINITION",
+          `external contract "${definition.id}" has no compiler provenance`
+        );
+      }
+      const tool = {
+        name: definition.id,
+        description: definition.description,
+        inputSchema: definition.input.jsonSchema,
+        execute: binding.execute
+      };
+      Object.defineProperty(tool, COMPILED_CAPABILITY_PROVENANCE, {
+        value: compiled,
+        enumerable: false
+      });
+      return tool;
+    }
+  };
+  if (compiled) {
+    Object.defineProperty(contract, COMPILED_CAPABILITY_PROVENANCE, {
+      value: compiled,
+      enumerable: false
+    });
+  }
+  return contract;
+}
+function compiledCapabilityToken(contract) {
+  const token = contract[COMPILED_CAPABILITY_PROVENANCE];
+  if (!token || "capabilities" in token) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `contract "${contract.definition.id}" has no compiler provenance`
+    );
+  }
+  return token;
+}
+function tryCompiledCapabilityToken(contract) {
+  const token = contract[COMPILED_CAPABILITY_PROVENANCE];
+  return token && !("capabilities" in token) ? token : void 0;
+}
+function manifestIndex(manifest) {
+  if (manifest.formatVersion !== CAPABILITY_CONTRACT_FORMAT_VERSION || manifest.completeness?.status !== "proven" || typeof manifest.hash !== "string" || manifest.hash.length === 0) {
+    throw new AgentSurfaceDefinitionError("INVALID_DEFINITION", "invalid compiled capability manifest");
+  }
+  const index = /* @__PURE__ */ new Map();
+  for (const entry of manifest.capabilities) {
+    const key = `${entry.declarationId}\0${entry.capabilityId}`;
+    if (index.has(key)) {
+      throw new AgentSurfaceDefinitionError(
+        "DUPLICATE_CAPABILITY",
+        `duplicate compiled declaration "${entry.declarationId}" for "${entry.capabilityId}"`
+      );
+    }
+    index.set(key, entry);
+  }
+  return index;
+}
+function assertToken(token, manifest, index) {
+  if (token.manifestHash !== manifest.hash) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `stale compiler token for "${token.capabilityId}": manifest hash mismatch`
+    );
+  }
+  const declared = index.get(`${token.declarationId}\0${token.capabilityId}`);
+  if (!declared) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `unknown compiled declaration "${token.declarationId}" for "${token.capabilityId}"`
+    );
+  }
+  if (declared.contractHash !== token.contractHash) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `compiled contract hash mismatch for "${token.capabilityId}"`
+    );
+  }
+}
+function assertDefinitionInManifest(definition, manifest) {
+  const provenance = definition[COMPILED_CAPABILITY_PROVENANCE];
+  if (!provenance || !("capabilities" in provenance)) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `raw registration "${definition.type}" rejected: bind a compiler-generated contract`
+    );
+  }
+  if (provenance.manifestHash !== manifest.hash) {
+    throw new AgentSurfaceDefinitionError(
+      "INVALID_DEFINITION",
+      `stale contract "${provenance.declarationId}": manifest hash mismatch`
+    );
+  }
+  const index = manifestIndex(manifest);
+  const expected = [
+    ...Object.keys(definition.observations ?? {}).map((name) => `view:${definition.type}.${name}`),
+    ...Object.keys(definition.actions ?? {}).map((name) => `view:${definition.type}.${name}`),
+    ...(definition.procedures ?? []).map((binding) => binding.ref.id)
+  ];
+  for (const capabilityId of expected) {
+    const token = provenance.capabilities[capabilityId];
+    if (!token) {
+      throw new AgentSurfaceDefinitionError(
+        "INVALID_DEFINITION",
+        `capability "${capabilityId}" is absent from compiled contract "${provenance.declarationId}"`
+      );
+    }
+    assertToken(token, manifest, index);
+  }
+  for (const capabilityId of Object.keys(provenance.capabilities)) {
+    if (!expected.includes(capabilityId)) {
+      throw new AgentSurfaceDefinitionError(
+        "INVALID_DEFINITION",
+        `binding for "${provenance.declarationId}" omits compiled capability "${capabilityId}"`
+      );
+    }
+  }
+}
+function createAgentExposureGateway(manifest) {
+  const index = manifestIndex(manifest);
+  return {
+    expose(tools) {
+      return tools.map((tool) => {
+        const token = tool[COMPILED_CAPABILITY_PROVENANCE];
+        if (!token) {
+          throw new AgentSurfaceDefinitionError(
+            "INVALID_DEFINITION",
+            `raw provider tool "${tool.name}" rejected by compiled exposure gateway`
+          );
+        }
+        assertToken(token, manifest, index);
+        return tool;
+      });
+    }
+  };
+}
+
 // src/registry.ts
 function createAgentSurfaceRegistry(options) {
   const environment2 = options?.environment ?? "production";
@@ -2093,6 +2338,7 @@ function createAgentSurfaceRegistry(options) {
     surfaceId: internals.surfaceId,
     register(definition) {
       if (internals.disposed) throw new Error("register() called on a disposed registry");
+      if (options?.manifest) assertDefinitionInManifest(definition, options.manifest);
       validateComponentDefinition(definition, limits, {
         hasProcedureExecutor: internals.executor !== void 0
       });
@@ -2781,20 +3027,29 @@ export {
   AgentSchemaError,
   AgentSurfaceDefinitionError,
   AgentSurfaceError,
+  CAPABILITY_CONTRACT_FORMAT_VERSION,
+  COMPILED_CAPABILITY_PROVENANCE,
   CONFIRMATION_ESCALATION,
   DEFAULT_LIMITS,
   MAX_ID_LENGTH,
   MAX_WIRE_NAME_LENGTH,
   action,
+  actionContract,
+  assertDefinitionInManifest,
   assignWireNames,
   audit,
   authenticated,
+  compiledCapabilityToken,
   composeInvokeChain,
   consoleAuditSink,
+  createAgentExposureGateway,
   createAgentSurfaceRegistry,
   createAgentToolset,
   decodeWireName,
   defineAgentComponent,
+  defineAgentComponentContract,
+  defineAgentProcedureContract,
+  defineExternalAgentToolContract,
   emptyObjectSchema,
   encodeWireName,
   encodeWireNameForInstance,
@@ -2812,10 +3067,12 @@ export {
   jsonDeepEqual,
   memoryAuditSink,
   observation,
+  observationContract,
   parseCapabilityId,
   rateLimit,
   requireConfirmation,
   tenantBoundary,
+  tryCompiledCapabilityToken,
   validateComponentDefinition,
   validateJsonSchemaDocument,
   validateValueAgainstSchema