@agent-surface/core 0.5.0 → 0.7.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;
 
@@ -838,6 +846,11 @@ interface AgentToolsetOptions {
      * "direct": one tool per capability — provider-native input typing, catalog
      * size linear in the surface. "meta": three fixed tools with lazy discovery —
      * constant tool-block size, one extra round trip before the first act.
+     *
+     * [Experimental] applies to "meta" only (D29): the three verbs' envelope may
+     * change in any release — 0.6 typed `surface_act.input` and started enforcing
+     * the verb schemas (D32). "direct" is Draft, like the rest of the API.
+     *
      * Default "direct"; see the selection guide in docs/09 §choosing-a-mode.
      */
     mode?: "direct" | "meta";

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);
@@ -3034,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) {
@@ -3050,6 +3058,75 @@ 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");
@@ -3075,6 +3152,8 @@ function createAgentToolset(registry, options) {
     );
   }
   const confirmationsMode = options.confirmations ?? (options.topology === "remote" ? "two-phase" : "wait");
+  const devWarn = registry[DEV_WARN] ?? (() => {
+  });
   const listeners = /* @__PURE__ */ new Set();
   const pendingWaits = /* @__PURE__ */ new Set();
   let disposed = false;
@@ -3204,6 +3283,15 @@ function createAgentToolset(registry, options) {
     }));
     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,
@@ -3213,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({
@@ -3255,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,
@@ -3291,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,
@@ -3331,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 } : {},
@@ -3425,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;
@@ -3433,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,