@agent-surface/core 0.4.1 → 0.6.0

package/dist/index.d.ts

@@ -171,6 +171,14 @@ declare function assignWireNames(entries: readonly WireNameEntry[]): WireNameAss
  * names among them (`AS-WIRE-007`: consult `toolset.wireNameMap()` instead).
  * Returning a plausible-but-wrong canonical id would take the audit identity
  * with it, so this refuses anything it cannot re-encode byte-identically.
+ *
+ * Refusal is decided by what a name *is*, never by a substring it happens to
+ * contain. `view:at.a.a` encodes to `view_at__a__a`, where `_at_` is the plane
+ * separator meeting a segment named "at" — screening for the marker text cost
+ * every id with an `at` or `0` segment its own faithful encoding (`AS-ID-004`).
+ * Marker-bearing names are still refused, by the two checks that can tell:
+ * every underscore run must be exactly two (one "."), and the id must re-encode
+ * byte-identically.
  */
 declare function decodeWireName(name: string): string | undefined;
 
@@ -749,17 +757,10 @@ interface AgentProcedureDescriptor {
     procedureId: string;
     /**
      * The manifest description. Stable across snapshots — the contextual
-     * `describe()` output is `contextualNote`, not part of this string, unless
-     * the registry was created with `snapshotMergesContextualNote: true`
-     * (the 0.2 default, removed in a later minor — D28).
+     * `describe()` output is `contextualNote` and is never folded in here (D28).
      */
     description: string;
-    /**
-     * Volatile: this snapshot's contextual `describe()` output, if any. Always
-     * populated, in both merge modes, so a host can migrate before the default
-     * moves. Use {@link stableDescriptionOf} to recover the note-free
-     * description without parsing.
-     */
+    /** Volatile: this snapshot's contextual `describe()` output, if any. */
     contextualNote?: string;
     /** Agent-facing (reduced) input schema per binding rule 1 (docs/05). */
     inputSchema: JsonSchema;
@@ -783,15 +784,6 @@ interface AgentProcedureDescriptor {
     meta?: Record<string, JsonValue>;
 }
 type AgentCapabilityDescriptorUnion = AgentObservationDescriptor | AgentActionDescriptor | AgentProcedureDescriptor;
-/**
- * The note-free description of a descriptor, whichever way the registry was
- * configured to compose it (D28). The merge rule is `${description} ${note}`,
- * so the split is exact — no host ever has to parse a prefix it did not write.
- */
-declare function stableDescriptionOf(descriptor: {
-    description: string;
-    contextualNote?: string;
-}): string;
 
 interface RegistrationCandidate {
     definition: AgentComponentDefinition;
@@ -815,15 +807,6 @@ interface RegistryOptions {
     /** Route descriptor for snapshots (host wires its router here). */
     route?: () => AgentRouteInfo | undefined;
     limits?: Partial<AgentSurfaceLimits>;
-    /**
-     * D28 compatibility flag. `true` (default through 0.4; flips in 0.5) folds a procedure
-     * reference's contextual `describe()` output into
-     * `AgentProcedureDescriptor.description`, as 0.1 did. `false` keeps the two
-     * apart, so `description` is stable across snapshots and the live text is
-     * read from `contextualNote`. Populated either way; the default flips in a
-     * later minor and the flag is then removed.
-     */
-    snapshotMergesContextualNote?: boolean;
     /** Injectable clock (docs/08 determinism); default Date.now. */
     now?: () => number;
 }
@@ -897,23 +880,14 @@ interface AgentToolsetOptions {
         maxComponents?: number;
         maxBytes?: number;
     };
-    /**
-     * D28 compatibility flag. `true` (default through 0.4; flips in 0.5) composes
-     * availability and the contextual note into `description`, as 0.1 did.
-     * `false` keeps `description` free of live state, so the provider tool block
-     * is byte-stable across steps and prompt-prefix caching survives; the host
-     * renders `AgentTool.state` outside the tool definitions (docs/09
-     * §rendering-capability-state). `state` is populated either way.
-     */
-    descriptionIncludesState?: boolean;
 }
 interface AgentTool {
     /** Wire-safe name (docs/09 §wire-names), ≤ 64 chars, unique in this catalog. */
     name: string;
     /**
      * Plane + effect + confirmation prefix, then the authored description.
-     * With `descriptionIncludesState: false` this contains NO live state — it is
-     * safe in a provider tool block with prompt-prefix caching across steps.
+     * Contains NO live state (D28), so it is safe in a provider tool block with
+     * prompt-prefix caching across steps.
      */
     description: string;
     inputSchema: JsonSchema;
@@ -950,4 +924,4 @@ declare function createAgentToolset(registry: AgentSurfaceRegistry, options: Age
 /** 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 AgentConcurrency, 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, type WireNameAssignment, type WireNameEntry, action, assignWireNames, 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, stableDescriptionOf, tenantBoundary, validateComponentDefinition, validateJsonSchemaDocument, validateValueAgainstSchema };
+export { AGENT_CAPABILITY_ERROR_CODES, type AgentActionContext, type AgentActionDefinition, type AgentActionDescriptor, type AgentAuthorizationContext, type AgentCapabilityDescriptorUnion, type AgentCapabilityErrorCode, type AgentCapabilityErrorPayload, type AgentComponentDefinition, type AgentComponentDescriptor, type AgentConcurrency, 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, type WireNameAssignment, type WireNameEntry, action, assignWireNames, 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 };

package/dist/index.js

@@ -82,7 +82,7 @@ function formatDomainCapabilityId(path) {
   return `domain:${path}`;
 }
 function parseCapabilityId(id) {
-  if (id.length > MAX_ID_LENGTH) return void 0;
+  if (typeof id !== "string" || id.length > MAX_ID_LENGTH) return void 0;
   if (id.startsWith("view:")) {
     const rest = id.slice("view:".length);
     const lastDot = rest.lastIndexOf(".");
@@ -125,7 +125,7 @@ function encodeWireName(id) {
 }
 function encodeWireNameForInstance(id, instanceId, level = 0) {
   const raw = rawWireName(id, instanceId);
-  if (level === 0 && raw.length <= MAX_WIRE_NAME_LENGTH) return raw;
+  if (level === 0 && raw.length <= MAX_WIRE_NAME_LENGTH && !id.includes("_")) return raw;
   const hashLength = 7 + level * 2;
   const keep = MAX_WIRE_NAME_LENGTH - SHORTENED_MARKER.length - hashLength;
   const hash = hash36(`${id}#${instanceId ?? ""}#${level}`, hashLength);
@@ -169,12 +169,15 @@ function assignWireNames(entries) {
   return { names, byName };
 }
 function decodeWireName(name) {
-  if (name.includes(SHORTENED_MARKER) || name.includes(INSTANCE_MARKER)) return void 0;
   const planeEnd = name.indexOf("_");
   if (planeEnd <= 0) return void 0;
   const plane = name.slice(0, planeEnd);
   if (plane !== "view" && plane !== "domain") return void 0;
-  const id = `${plane}:${name.slice(planeEnd + 1).replaceAll("__", ".")}`;
+  const rest = name.slice(planeEnd + 1);
+  if (/_{3,}/.test(rest)) return void 0;
+  const path = rest.replaceAll("__", ".");
+  if (path.split(".").some((segment) => segment === "")) return void 0;
+  const id = `${plane}:${path}`;
   if (id.includes("_") || !parseCapabilityId(id) || encodeWireName(id) !== name) return void 0;
   return id;
 }
@@ -1361,6 +1364,7 @@ var ConfirmationStore = class {
 };
 
 // src/internal.ts
+var DEV_WARN = /* @__PURE__ */ Symbol("agent-surface.dev-warn");
 var DevDefectError = class extends Error {
   constructor(message) {
     super(message);
@@ -2572,12 +2576,6 @@ function drainObservationQueues(internals) {
 
 // src/snapshot.ts
 var DEFAULT_CONSUMER2 = { id: "anonymous", kind: "embedded" };
-function stableDescriptionOf(descriptor) {
-  const note = descriptor.contextualNote;
-  if (!note) return descriptor.description;
-  if (descriptor.description === note) return "";
-  return descriptor.description.endsWith(` ${note}`) ? descriptor.description.slice(0, -(note.length + 1)) : descriptor.description;
-}
 function matchesScope(type, scope) {
   if (!scope || scope.length === 0) return true;
   return scope.some((prefix) => type === prefix || type.startsWith(`${prefix}.`));
@@ -2692,10 +2690,12 @@ function createSnapshot(internals, ctx) {
         } catch {
         }
       }
-      const description = contextualNote && internals.mergesContextualNote ? `${proc.baseDescription} ${contextualNote}`.trim() : proc.baseDescription;
       procedures.push({
         procedureId: proc.capabilityId,
-        description,
+        // Never merged with `contextualNote` (D28): the manifest text is the
+        // stable half, and folding volatile text in is what churned the
+        // provider's cached prompt prefix.
+        description: proc.baseDescription,
         ...contextualNote !== void 0 ? { contextualNote } : {},
         inputSchema: proc.reducedInputSchema,
         ...proc.outputJsonSchema ? { outputSchema: proc.outputJsonSchema } : {},
@@ -2763,7 +2763,6 @@ function createAgentSurfaceRegistry(options) {
   const internals = {
     environment: environment2,
     limits,
-    mergesContextualNote: options?.snapshotMergesContextualNote ?? true,
     surfaceId: `srf_${randomBase62(22)}`,
     version: 0,
     registrations: /* @__PURE__ */ new Map(),
@@ -3039,6 +3038,10 @@ function createAgentSurfaceRegistry(options) {
       dispatcher.clear();
     }
   };
+  Object.defineProperty(registry, DEV_WARN, {
+    value: (...args) => internals.devWarn(...args),
+    enumerable: false
+  });
   return registry;
 }
 function combineSinks(...sinks) {
@@ -3055,16 +3058,80 @@ var EMPTY_INPUT_SCHEMA = {
   properties: {},
   additionalProperties: false
 };
+var META_DISCOVER_SCHEMA = {
+  type: "object",
+  properties: {
+    scope: {
+      type: "array",
+      items: { type: "string" },
+      // No enum: valid tokens are live component types, and inlining them
+      // would make this tool block churn on every mount — the churn
+      // AS-META-005 and D28 exist to prevent.
+      description: 'Component-type prefixes to narrow the result, e.g. ["devices.table"], taken from `components[].type` of an earlier call \u2014 omit on the first. Narrows only: prefixes outside this host\'s configured scope match nothing and come back in `scopeRejected`.'
+    }
+  },
+  additionalProperties: false
+};
+var META_READ_SCHEMA = {
+  type: "object",
+  properties: {
+    capabilityId: {
+      type: "string",
+      description: "Observation id, verbatim from `observations[].capabilityId` in a discover result."
+    },
+    instanceId: {
+      type: "string",
+      description: "Only when several components share a type: `components[].instanceId` picks one."
+    }
+  },
+  required: ["capabilityId"],
+  additionalProperties: false
+};
+var META_ACT_SCHEMA = {
+  type: "object",
+  properties: {
+    capabilityId: {
+      type: "string",
+      description: "Action `capabilityId` or `procedureId`, verbatim from a discover result."
+    },
+    instanceId: {
+      type: "string",
+      description: "Only when several components share a type: `components[].instanceId` picks one."
+    },
+    // Typed, and not merely described: an untyped property is the one position
+    // a provider's constrained decoder cannot constrain, so the model falls
+    // back to its prior — a JSON-encoded string, the shape
+    // `function_call.arguments` carries — and sorts the rest of the capability's
+    // arguments into the sibling modifiers below. `type: "object"` costs
+    // nothing in practice: direct mode already passes `act.inputSchema`
+    // straight through as the tool schema, and providers require that to be an
+    // object schema at the top level. No `additionalProperties` here — the
+    // capability's own schema governs what goes inside.
+    input: {
+      type: "object",
+      description: "Arguments matching that capability's `inputSchema`, as a JSON object \u2014 not a JSON-encoded string. Everything the capability declares goes in here, never beside it."
+    },
+    invocationId: {
+      type: "string",
+      description: "Reuse a previous call's id to retry without executing twice; required when resuming after CONFIRMATION_REQUIRED."
+    },
+    confirmationId: {
+      type: "string",
+      description: "The id returned with CONFIRMATION_REQUIRED, sent back after the user approves."
+    },
+    surfaceVersion: {
+      type: "string",
+      description: "The `surfaceVersion` you planned against. Send it for destructive or externally-visible calls: a surface that moved underneath the plan then fails instead of executing. Omitted, the call binds to what is live now."
+    }
+  },
+  required: ["capabilityId"],
+  additionalProperties: false
+};
 function describePrefix(plane, effect, confirmation) {
   const parts = [plane, effect];
   if (confirmation === "required") parts.push("requires confirmation");
   return `[${parts.join(" \xB7 ")}]`;
 }
-function legacyDescription(prefix, description, state) {
-  const unavailable = state.available ? "" : ` [currently unavailable${state.unavailableReason ? `: ${state.unavailableReason}` : ""}]`;
-  const note = state.note ? ` ${state.note}` : "";
-  return `${prefix}${unavailable} ${description}${note}`;
-}
 function availabilityState(descriptor) {
   return {
     available: descriptor.available,
@@ -3085,7 +3152,8 @@ function createAgentToolset(registry, options) {
     );
   }
   const confirmationsMode = options.confirmations ?? (options.topology === "remote" ? "two-phase" : "wait");
-  const descriptionIncludesState = options.descriptionIncludesState ?? true;
+  const devWarn = registry[DEV_WARN] ?? (() => {
+  });
   const listeners = /* @__PURE__ */ new Set();
   const pendingWaits = /* @__PURE__ */ new Set();
   let disposed = false;
@@ -3199,7 +3267,7 @@ function createAgentToolset(registry, options) {
         void 0,
         describePrefix("domain", proc.effect, proc.confirmation),
         // The stable half only: a contextual note travels in `state.note`.
-        stableDescriptionOf(proc),
+        proc.description,
         proc.inputSchema,
         availabilityState(proc),
         needsSuffix ? proc.context?.instanceId ?? proc.registrationId.replace(/[^A-Za-z0-9_-]/g, "") : void 0
@@ -3208,13 +3276,22 @@ function createAgentToolset(registry, options) {
     const assignment = assignWireNames(pending.map((p) => p.wire));
     const tools = pending.map((p, i) => ({
       name: assignment.names[i],
-      description: descriptionIncludesState ? legacyDescription(p.prefix, p.description, p.state) : `${p.prefix} ${p.description}`,
+      description: `${p.prefix} ${p.description}`,
       inputSchema: p.inputSchema,
       state: p.state,
       execute: (input, call) => invokeThroughSurface(p.entry, input, call.toolCallId)
     }));
     return { tools, wireNames: assignment.byName };
   }
+  function envelopeFailure(metaCapabilityId, capabilityId, error, toolCallId) {
+    return {
+      status: "error",
+      invocationId: toolCallId ?? `inv_${randomBase62(12)}`,
+      capabilityId: typeof capabilityId === "string" && capabilityId.length > 0 ? capabilityId : metaCapabilityId,
+      error,
+      surfaceVersion: registry.getVersion()
+    };
+  }
   function buildMetaTools() {
     const snapshotFor = () => registry.snapshot({
       consumer: options.consumer,
@@ -3224,21 +3301,12 @@ function createAgentToolset(registry, options) {
       {
         name: "surface_discover",
         description: "[meta] Discover the current agent surface: components, capabilities, procedures, availability, schemas.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            scope: {
-              type: "array",
-              items: { type: "string" },
-              // No enum: valid tokens are live component types, and inlining
-              // them would make this tool block churn on every mount —
-              // the churn AS-META-005 and D28 exist to prevent.
-              description: 'Component-type prefixes to narrow the result, e.g. ["devices.table"], taken from `components[].type` of an earlier call \u2014 omit on the first. Narrows only: prefixes outside this host\'s configured scope match nothing and come back in `scopeRejected`.'
-            }
-          },
-          additionalProperties: false
-        },
-        async execute(input) {
+        inputSchema: META_DISCOVER_SCHEMA,
+        async execute(input, call) {
+          const invalid = validateEnvelope("surface_discover", META_DISCOVER_SCHEMA, input);
+          if (invalid) {
+            return envelopeFailure("meta:surface.discover", void 0, invalid, call.toolCallId);
+          }
           const requested = input?.scope;
           const effective = intersectScope(options.scope, requested);
           const snapshot = registry.snapshot({
@@ -3266,25 +3334,15 @@ function createAgentToolset(registry, options) {
       {
         name: "surface_read",
         description: "[meta] Invoke an observation by capabilityId and return its output.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            capabilityId: {
-              type: "string",
-              description: "Observation id, verbatim from `observations[].capabilityId` in a discover result."
-            },
-            instanceId: {
-              type: "string",
-              description: "Only when several components share a type: `components[].instanceId` picks one."
-            }
-          },
-          required: ["capabilityId"],
-          additionalProperties: false
-        },
+        inputSchema: META_READ_SCHEMA,
         async execute(input, call) {
-          const req = input;
+          const req = input ?? {};
+          const invalid = validateEnvelope("surface_read", META_READ_SCHEMA, input);
+          if (invalid) {
+            return envelopeFailure("meta:surface.read", req.capabilityId, invalid, call.toolCallId);
+          }
           const snapshot = snapshotFor();
-          const registrationId = findRegistrationId(snapshot, req.capabilityId, req.instanceId);
+          const { registrationId } = findTarget(snapshot, req.capabilityId, req.instanceId);
           return invokeThroughSurface(
             {
               capabilityId: req.capabilityId,
@@ -3302,38 +3360,27 @@ function createAgentToolset(registry, options) {
       {
         name: "surface_act",
         description: "[meta] Invoke an action or procedure by capabilityId. Echo the surfaceVersion you discovered so a surface that changed underneath a destructive plan is rejected rather than executed.",
-        inputSchema: {
-          type: "object",
-          properties: {
-            capabilityId: {
-              type: "string",
-              description: "Action `capabilityId` or `procedureId`, verbatim from a discover result."
-            },
-            instanceId: {
-              type: "string",
-              description: "Only when several components share a type: `components[].instanceId` picks one."
-            },
-            input: { description: "Arguments matching that capability's `inputSchema`." },
-            invocationId: {
-              type: "string",
-              description: "Reuse a previous call's id to retry without executing twice; required when resuming after CONFIRMATION_REQUIRED."
-            },
-            confirmationId: {
-              type: "string",
-              description: "The id returned with CONFIRMATION_REQUIRED, sent back after the user approves."
-            },
-            surfaceVersion: {
-              type: "string",
-              description: "The `surfaceVersion` you planned against. Send it for destructive or externally-visible calls: a surface that moved underneath the plan then fails instead of executing. Omitted, the call binds to what is live now."
-            }
-          },
-          required: ["capabilityId"],
-          additionalProperties: false
-        },
+        inputSchema: META_ACT_SCHEMA,
         async execute(input, call) {
-          const req = input;
+          const req = input ?? {};
+          const invalid = validateEnvelope("surface_act", META_ACT_SCHEMA, input, ["input"]);
+          if (invalid) {
+            return envelopeFailure("meta:surface.act", req.capabilityId, invalid, call.toolCallId);
+          }
           const snapshot = snapshotFor();
-          const registrationId = findRegistrationId(snapshot, req.capabilityId, req.instanceId);
+          const { registrationId, inputSchema } = findTarget(
+            snapshot,
+            req.capabilityId,
+            req.instanceId
+          );
+          let actInput = req.input;
+          const parsed = parseStringifiedObject(actInput, inputSchema);
+          if (parsed !== void 0) {
+            actInput = parsed;
+            devWarn(
+              `[agent-surface] surface_act got \`input\` as a JSON-encoded string for "${req.capabilityId}" and parsed it; the provider is not honoring the tool schema.`
+            );
+          }
           return invokeThroughSurface(
             {
               capabilityId: req.capabilityId,
@@ -3342,7 +3389,7 @@ function createAgentToolset(registry, options) {
               surfaceVersion: req.surfaceVersion ?? snapshot.surfaceVersion,
               kind: "action"
             },
-            req.input,
+            actInput,
             call.toolCallId,
             {
               ...req.invocationId !== void 0 ? { invocationId: req.invocationId } : {},
@@ -3436,7 +3483,7 @@ function intersectScope(floor, requested) {
   }
   return out.size > 0 ? { scope: [...out], empty: false, rejected } : { empty: true, rejected };
 }
-function findRegistrationId(snapshot, capabilityId, instanceId) {
+function findTarget(snapshot, capabilityId, instanceId) {
   const matches = [];
   for (const component of snapshot.components) {
     if (instanceId !== void 0 && component.instanceId !== instanceId) continue;
@@ -3444,12 +3491,89 @@ function findRegistrationId(snapshot, capabilityId, instanceId) {
       ...component.observations,
       ...component.actions
     ];
-    if (all.some((c) => c.capabilityId === capabilityId)) matches.push(component.registrationId);
+    const hit = all.find((c) => c.capabilityId === capabilityId);
+    if (hit) {
+      matches.push({
+        registrationId: component.registrationId,
+        ..."inputSchema" in hit ? { inputSchema: hit.inputSchema } : {}
+      });
+    }
   }
   for (const proc of snapshot.procedures) {
-    if (proc.procedureId === capabilityId) matches.push(proc.registrationId);
+    if (proc.procedureId === capabilityId) {
+      matches.push({ registrationId: proc.registrationId, inputSchema: proc.inputSchema });
+    }
+  }
+  return matches.length === 1 ? matches[0] : {};
+}
+function validateEnvelope(verb, schema, raw, exempt = []) {
+  if (raw !== void 0 && raw !== null && (typeof raw !== "object" || Array.isArray(raw))) {
+    return envelopeError(verb, [
+      { path: "", message: `\`${verb}\` takes a JSON object of arguments.` }
+    ]);
+  }
+  const properties = schema.properties ?? {};
+  const known = Object.keys(properties);
+  const required = schema.required ?? [];
+  const req = raw ?? {};
+  const issues = [];
+  for (const key of required) {
+    if (req[key] === void 0) issues.push({ path: key, message: `\`${key}\` is required.` });
+  }
+  for (const [key, value] of Object.entries(req)) {
+    if (value === void 0) continue;
+    if (!known.includes(key)) {
+      if (schema.additionalProperties === false) {
+        issues.push({
+          path: key,
+          // The high-value half is the pointer back at `input`: it turns the
+          // dead end of a hoisted capability argument into a one-retry
+          // recovery. A verb without an `input` has nowhere to point.
+          message: `Unknown top-level property. \`${verb}\` accepts only ${known.join(", ")}.${known.includes("input") ? " An argument the capability declares belongs inside `input`." : ""}`
+        });
+      }
+      continue;
+    }
+    if (exempt.includes(key)) continue;
+    const issue = checkDeclaredType(key, properties[key], value);
+    if (issue) issues.push(issue);
+  }
+  return issues.length > 0 ? envelopeError(verb, issues) : void 0;
+}
+function checkDeclaredType(key, property, value) {
+  if (property.type === "string" && (typeof value !== "string" || value.length === 0)) {
+    return { path: key, message: `\`${key}\` must be a non-empty string.` };
+  }
+  if (property.type === "array") {
+    if (!Array.isArray(value)) return { path: key, message: `\`${key}\` must be an array.` };
+    const items = property.items;
+    if (items?.type === "string" && !value.every((item) => typeof item === "string")) {
+      return { path: key, message: `\`${key}\` must be an array of strings.` };
+    }
+  }
+  return void 0;
+}
+function envelopeError(verb, issues) {
+  return {
+    code: "INVALID_INPUT",
+    // Names the envelope, not the capability: pointing the model at the
+    // capability's schema when the wrapper is what is wrong sends it to fix
+    // something that is already correct.
+    message: `The \`${verb}\` call is malformed \u2014 the fault is in the tool's own arguments, not the capability's input. Fix the listed issues and retry.`,
+    retry: "with-changes",
+    details: { issues }
+  };
+}
+function parseStringifiedObject(value, targetSchema) {
+  if (typeof value !== "string" || targetSchema?.type !== "object") return void 0;
+  let parsed;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    return void 0;
   }
-  return matches.length === 1 ? matches[0] : void 0;
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return void 0;
+  return parsed;
 }
 export {
   AGENT_CAPABILITY_ERROR_CODES,
@@ -3490,7 +3614,6 @@ export {
   parseCapabilityId,
   rateLimit,
   requireConfirmation,
-  stableDescriptionOf,
   tenantBoundary,
   validateComponentDefinition,
   validateJsonSchemaDocument,