attention-manifest-protocol 0.4.2 → 0.4.4

package/lib/boundary/refTable.d.ts

@@ -7,10 +7,13 @@
  * makes resolution explicit and gives the scope a name, so "unresolvable" is a
  * rejection rather than a silent dangling pointer.
  *
- * Canonicalisation rules:
- * - `tool` and `capability` share one namespace; the `mcp.` prefix is transport
- *   detail, not identity.
- * - `self` resolves to the agent id registered for the scope.
+ * Canonicalisation rules (one implementation, shared by `add`/`resolve`/`check`):
+ * - `tool` and `capability` share one namespace (`capability:<name>`); the
+ *   `mcp.` prefix is transport detail, not identity, and only one layer is
+ *   stripped. A name that is empty after stripping has no canonical key.
+ * - `self` and `agent` share one namespace (`agent:<id>`), which is also how a
+ *   constructor-bound agent is registered.
+ * - every other kind keeps its own namespace (`<kind>:<id>`).
  */
 import type { Id, Ref, RefKind } from "../types/common.js";
 /**
@@ -21,26 +24,33 @@ export declare class RefTable {
     readonly scope: RefScope;
     readonly opaqueKinds: ReadonlySet<RefKind>;
     private readonly entries;
+    /**
+     * @throws BoundaryRejection `invalid_ref` for a scope/opaque-kind outside
+     * the runtime sets, `invalid_id` for an agent id outside the AMP grammar.
+     */
     constructor(scope: RefScope, agentId?: string, opaqueKinds?: readonly RefKind[]);
     static forScope(scope: RefScope, agentId?: string, opaqueKinds?: readonly RefKind[]): RefTable;
     /**
-     * Register an object under its reference key.
+     * Register an object under its canonical reference key.
      *
-     * @throws BoundaryRejection `invalid_id` when the id cannot be referenced,
-     * `duplicate_ref` when the same key is registered twice.
+     * @throws BoundaryRejection `invalid_ref` for an unknown kind or an
+     * `undefined` value, `invalid_id` when the id cannot be referenced,
+     * `duplicate_ref` when the same canonical key is registered twice.
      */
     add(kind: RefKind, id: Id, value: unknown): this;
     resolve(ref: Ref): unknown | undefined;
     /**
      * Resolve or reject. The message names the scope so a host can tell a
-     * missing run object from a missing federated object.
+     * missing run object from a missing federated object. Opaque kinds are not
+     * special here: `require` always demands a registered object.
      */
     require(ref: Ref): unknown;
     has(ref: Ref): boolean;
     /**
      * Resolution verdict used by `frameFrom`.
      *
-     * Opaque kinds pass on shape alone; every other kind must be present in the
+     * Every ref must pass the id grammar and the runtime kind set first. Opaque
+     * kinds then pass on shape alone; every other kind must be present in the
      * scope. Returns a problem string instead of throwing so callers can report
      * every dangling reference at once.
      */

package/lib/boundary/refTable.js

@@ -1,18 +1,61 @@
 import { isId } from "./ids.js";
+import { isRefKind } from "./kinds.js";
 import { BoundaryRejection } from "../error/boundaryRejection.js";
+const RefScopes = ["run", "ledger", "bundle"];
 /**
  * Kinds that name something outside the ledger. They still need a valid id and
  * a kind, but they cannot be required to resolve here: a human, an org or an
  * external entity lives in a directory the host owns, not in the run.
  */
 const DefaultOpaqueKinds = ["human", "org", "entity", "other"];
+const isRefScope = (value) => typeof (value) === "string" && RefScopes.includes(value);
+const isRecord = (value) => typeof (value) === "object" && value !== null && !Array.isArray(value);
 const stripToolPrefix = (id) => (id.startsWith("mcp.") ? id.slice(4) : id);
-const canonicalId = (kind, id) => `${kind}:${kind === "tool" ? stripToolPrefix(id) : id}`;
+/**
+ * The only canonical-key rule. Returns `undefined` when `kind` and `id` do not
+ * name a registerable object (a tool/capability id that is empty after the
+ * single `mcp.` strip).
+ */
+const canonicalKey = (kind, id) => {
+    if (kind === "tool" || kind === "capability") {
+        const name = stripToolPrefix(id);
+        if (name.length === 0) {
+            return (void 0);
+        }
+        return `capability:${name}`;
+    }
+    if (kind === "self" || kind === "agent") {
+        return `agent:${id}`;
+    }
+    return `${kind}:${id}`;
+};
 export class RefTable {
     scope;
     opaqueKinds;
     entries;
+    /**
+     * @throws BoundaryRejection `invalid_ref` for a scope/opaque-kind outside
+     * the runtime sets, `invalid_id` for an agent id outside the AMP grammar.
+     */
     constructor(scope, agentId, opaqueKinds = DefaultOpaqueKinds) {
+        if (!isRefScope(scope)) {
+            throw new BoundaryRejection("invalid_ref", [`scope ${String(scope)} is not a ref scope`]);
+        }
+        if (agentId !== (void 0) && !isId(agentId)) {
+            throw new BoundaryRejection("invalid_id", [`agentId ${String(agentId)} is not a valid AMP id`]);
+        }
+        if (!Array.isArray(opaqueKinds)) {
+            throw new BoundaryRejection("invalid_ref", ["opaqueKinds must be an array of ref kinds"]);
+        }
+        const problems = [];
+        opaqueKinds.forEach((kind) => {
+            if (!isRefKind(kind)) {
+                problems.push(`${String(kind)} is not a ref kind`);
+            }
+        });
+        if (problems.length > 0) {
+            throw new BoundaryRejection("invalid_ref", problems);
+        }
         this.scope = scope;
         this.opaqueKinds = new Set(opaqueKinds);
         this.entries = new Map();
@@ -24,16 +67,23 @@ export class RefTable {
         return new RefTable(scope, agentId, opaqueKinds);
     }
     /**
-     * Register an object under its reference key.
+     * Register an object under its canonical reference key.
      *
-     * @throws BoundaryRejection `invalid_id` when the id cannot be referenced,
-     * `duplicate_ref` when the same key is registered twice.
+     * @throws BoundaryRejection `invalid_ref` for an unknown kind or an
+     * `undefined` value, `invalid_id` when the id cannot be referenced,
+     * `duplicate_ref` when the same canonical key is registered twice.
      */
     add(kind, id, value) {
-        if (!isId(id)) {
-            throw new BoundaryRejection("invalid_id", [`${kind}:${id} is not a valid AMP id`]);
+        if (!isRefKind(kind)) {
+            throw new BoundaryRejection("invalid_ref", [`${String(kind)} is not a ref kind`]);
+        }
+        const key = isId(id) ? canonicalKey(kind, id) : (void 0);
+        if (key === (void 0)) {
+            throw new BoundaryRejection("invalid_id", [`${kind}:${String(id)} is not a valid AMP id`]);
+        }
+        if (value === (void 0)) {
+            throw new BoundaryRejection("invalid_ref", [`${key} cannot be registered with an undefined value`]);
         }
-        const key = canonicalId(kind, id);
         if (this.entries.has(key)) {
             throw new BoundaryRejection("duplicate_ref", [`${key} is already registered in scope ${this.scope}`]);
         }
@@ -41,31 +91,58 @@ export class RefTable {
         return this;
     }
     resolve(ref) {
-        if (!isId(ref.id)) {
-            return (void 0);
-        }
-        const direct = this.entries.get(canonicalId(ref.kind, ref.id));
-        if (direct !== (void 0)) {
-            return direct;
+        try {
+            if (!isRecord(ref)) {
+                return (void 0);
+            }
+            const kind = ref.kind;
+            const id = ref.id;
+            if (!isRefKind(kind) || !isId(id)) {
+                return (void 0);
+            }
+            const key = canonicalKey(kind, id);
+            if (key === (void 0)) {
+                return (void 0);
+            }
+            return this.entries.has(key) ? this.entries.get(key) : (void 0);
         }
-        if (ref.kind === "tool") {
-            return this.entries.get(`capability:${stripToolPrefix(ref.id)}`);
-        }
-        if (ref.kind === "self") {
-            return this.entries.get(`agent:${ref.id}`);
+        catch {
+            return (void 0);
         }
-        return (void 0);
     }
     /**
      * Resolve or reject. The message names the scope so a host can tell a
-     * missing run object from a missing federated object.
+     * missing run object from a missing federated object. Opaque kinds are not
+     * special here: `require` always demands a registered object.
      */
     require(ref) {
-        const hit = this.resolve(ref);
-        if (hit === (void 0)) {
-            throw new BoundaryRejection("unresolvable_ref", [`${ref.kind}:${ref.id} is not present in scope ${this.scope}`]);
+        try {
+            if (!isRecord(ref)) {
+                throw new BoundaryRejection("invalid_ref", ["value is not a Ref object"]);
+            }
+            const kind = ref.kind;
+            const id = ref.id;
+            if (!isRefKind(kind)) {
+                throw new BoundaryRejection("invalid_ref", [`${String(kind)} is not a ref kind`]);
+            }
+            if (!isId(id)) {
+                throw new BoundaryRejection("invalid_id", [`${kind}:${String(id)} is not a valid AMP id`]);
+            }
+            const key = canonicalKey(kind, id);
+            if (key === (void 0)) {
+                throw new BoundaryRejection("invalid_id", [`${kind}:${id} is not a valid AMP id`]);
+            }
+            if (!this.entries.has(key)) {
+                throw new BoundaryRejection("unresolvable_ref", [`${kind}:${id} is not present in scope ${this.scope}`]);
+            }
+            return this.entries.get(key);
+        }
+        catch (error) {
+            if (error instanceof BoundaryRejection) {
+                throw error;
+            }
+            throw new BoundaryRejection("invalid_ref", [`ref could not be inspected (${error instanceof Error ? error.name : typeof (error)})`]);
         }
-        return hit;
     }
     has(ref) {
         return this.resolve(ref) !== (void 0);
@@ -73,18 +150,39 @@ export class RefTable {
     /**
      * Resolution verdict used by `frameFrom`.
      *
-     * Opaque kinds pass on shape alone; every other kind must be present in the
+     * Every ref must pass the id grammar and the runtime kind set first. Opaque
+     * kinds then pass on shape alone; every other kind must be present in the
      * scope. Returns a problem string instead of throwing so callers can report
      * every dangling reference at once.
      */
     check(ref) {
-        if (this.opaqueKinds.has(ref.kind)) {
-            return (void 0);
+        try {
+            if (!isRecord(ref)) {
+                return "value is not a Ref object";
+            }
+            const kind = ref.kind;
+            const id = ref.id;
+            if (!isId(id)) {
+                return `${String(kind)}:${String(id)} is not a valid AMP id`;
+            }
+            if (!isRefKind(kind)) {
+                return `${String(kind)} is not a ref kind`;
+            }
+            const key = canonicalKey(kind, id);
+            if (key === (void 0)) {
+                return `${kind}:${id} is not a valid AMP id`;
+            }
+            if (this.opaqueKinds.has(kind)) {
+                return (void 0);
+            }
+            if (this.entries.has(key)) {
+                return (void 0);
+            }
+            return `${kind}:${id} is not present in scope ${this.scope}`;
         }
-        if (this.resolve(ref) !== (void 0)) {
-            return (void 0);
+        catch (error) {
+            return `ref could not be inspected (${error instanceof Error ? error.name : typeof (error)})`;
         }
-        return `${ref.kind}:${ref.id} is not present in scope ${this.scope}`;
     }
     get size() {
         return this.entries.size;

package/lib/boundary/toolCall.d.ts

@@ -3,14 +3,26 @@
  *
  * The reference executor passes `Record<string, unknown>` straight to a server.
  * This module checks the arguments against the tool's `inputSchema` and returns
- * a digest of exactly what was accepted, so an approval can bind to the parsed
- * call instead of to a mutable object.
+ * a frozen copy plus a digest of exactly what was accepted, so an approval can
+ * bind to the parsed call instead of to a mutable object.
  *
- * The validator implements the subset of JSON Schema that MCP tool definitions
- * actually use: `type`, `properties`, `required`, `additionalProperties`,
- * `items`, `enum`, `const`, `anyOf`/`oneOf`/`allOf`, length and numeric bounds,
- * and `pattern`. Keywords outside that subset are ignored rather than guessed
- * at; a schema that needs more should be narrowed before it reaches this layer.
+ * Contract:
+ *  - `raw` must be a plain object whose values are strict JSON
+ *    (`jsonValueProblem`); `undefined`, `NaN`, ±`Infinity`, functions,
+ *    `symbol`/`BigInt`, `Date`/`Map`/`Set`, sparse arrays, cycles and accessors
+ *    are rejected at the boundary instead of being silently rewritten by
+ *    `JSON.stringify` (which would make the digest disagree with the wire).
+ *  - the accepted arguments are a deep clone, frozen at every level, so the
+ *    caller cannot mutate the call or its digest after approval.
+ *  - the schema is JSON Schema restricted to `SupportedKeywords`. Local `$ref`
+ *    targets (`#`, `#/$defs/<name>`, `#/definitions/<name>`) are resolved;
+ *    every other applicator, and every malformed keyword form, is a schema
+ *    problem rather than an ignored hint.
+ *  - `not`/`contains`/`if`/`then`/`else`/`patternProperties`/`dependentSchemas`
+ *    are intentionally not implemented: a schema that needs them is rejected
+ *    (fail-closed) instead of being applied partially.
+ *  - schema nesting is capped at 128 levels, far above the deepest schema MCP
+ *    tools use, so legal deep schemas pass while `$ref` cycles terminate.
  */
 import type { Digest } from "../types/common.js";
 export interface ToolSchema {
@@ -26,8 +38,8 @@ export interface ParsedToolCall {
     digest: Digest;
 }
 /**
- * Parse a tool call's arguments against its declared schema.
- *
- * @throws BoundaryRejection `invalid_tool_args` with every problem found.
+ * Public entry point. The inner checks catch the common inspection failures;
+ * this outer guard covers a revoked `Proxy` whose very prototype lookup throws
+ * before the inner `try` blocks run.
  */
 export declare const parseToolCall: (tool: ToolSchema, raw: unknown) => ParsedToolCall;