@orangecheck/agent-anthropic 0.2.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # @orangecheck/agent-anthropic
 
+> **Full reference:** [docs.ochk.io/sdk/agent-anthropic](https://docs.ochk.io/sdk/agent-anthropic) — auto-generated from the TypeScript source on every release.
+> Hand-written prose below is the high-level overview; the docs site is the source of truth for every export, type, and signature.
+
+
 Wrap [Anthropic Tool Use](https://docs.anthropic.com/en/docs/build-with-claude/tool-use) (Claude `tool_use` blocks) with [OC Agent](https://github.com/orangecheck/oc-agent-protocol) scope enforcement and emit a signed `agent-action` envelope per tool execution.
 
 ## Why

package/dist/index.js

@@ -30,13 +30,7 @@ function toolUseId(agentAddress, signedAt, delegationId, scopeExercised, t) {
 }
 async function stampToolUse(input) {
   const scopeExercised = input.scopeExercised ?? `anthropic:tool(name=${input.toolUse.name})`;
-  const granted = (input.delegation.scopes ?? []).map(agentCore.parseScope);
-  const exercisedParsed = agentCore.parseScope(scopeExercised);
-  if (!granted.some((g) => agentCore.isSubScope(exercisedParsed, g))) {
-    throw new Error(
-      `stampToolUse: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
-    );
-  }
+  agentCore.assertScopeGranted(input.delegation, scopeExercised, "stampToolUse");
   const bytes = canonicalizeToolUse(input.toolUse);
   return agentSigner.signAsAgent({
     agent: input.agent,

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["canonicalize","hexEncode","sha256","computeActionId","parseScope","isSubScope","signAsAgent","j"],"mappings":"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","file":"index.js","sourcesContent":["// @orangecheck/agent-anthropic — wrap Anthropic Tool Use invocations in\n// OC Agent action envelopes.\n//\n// Anthropic's Messages API surfaces tool calls as `tool_use` content\n// blocks: { type: 'tool_use', id, name, input }. This module canonicalizes\n// each tool_use, hashes it, and produces an agent-action envelope binding\n// the BIP-322-authenticated agent to the (tool_name, input) tuple — at a\n// scope of `anthropic:tool(name=<tool>)`.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    isSubScope,\n    parseScope,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization of an Anthropic tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AnthropicToolUse {\n    /** The `id` Anthropic assigns to this tool_use block (passed back as tool_use_id on result). */\n    id: string;\n    /** The tool name registered in your `tools` array on messages.create. */\n    name: string;\n    /** The model's structured input for this tool — JSON-serializable. */\n    input: Record<string, unknown>;\n}\n\n/**\n * Produce the canonical bytes for an Anthropic tool_use. The bytes are what\n * the agent-action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"id\":    <tool_use_id>,\n *     \"input\": <canonical JSON of input>,\n *     \"name\":  <tool name>\n *   }\n */\nexport function canonicalizeToolUse(t: AnthropicToolUse): Uint8Array {\n    const canon = {\n        id: t.id,\n        input: t.input,\n        name: t.name,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolUseHash(t: AnthropicToolUse): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolUse(t)));\n}\n\nexport function toolUseId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    t: AnthropicToolUse\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolUseHash(t),\n        content_length: canonicalizeToolUse(t).byteLength,\n        content_mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamped tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampToolUseInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    toolUse: AnthropicToolUse;\n    /** Defaults to `anthropic:tool(name=<tool>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\n/**\n * Stamp an Anthropic tool_use without executing it. Useful for pre-\n * authorization flows or batch stamping.\n */\nexport async function stampToolUse(input: StampToolUseInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? `anthropic:tool(name=${input.toolUse.name})`;\n\n    const granted = (input.delegation.scopes ?? []).map(parseScope);\n    const exercisedParsed = parseScope(scopeExercised);\n    if (!granted.some((g) => isSubScope(exercisedParsed, g))) {\n        throw new Error(\n            `stampToolUse: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`\n        );\n    }\n\n    const bytes = canonicalizeToolUse(input.toolUse);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolUseHash(input.toolUse), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// invokeWithStamp — call the tool AND produce the stamp around it\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface InvokeWithStampInput<T> extends StampToolUseInput {\n    /** Your handler that actually runs the tool. Returns whatever the tool returns. */\n    call: (toolUse: AnthropicToolUse) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n}\n\n/**\n * Stamp the tool_use first, then execute the handler. The stamped envelope\n * is returned alongside the result so the caller can ship them together —\n * e.g. as a side-channel to an audit log, or as the `_oc_agent` metadata on\n * the tool_result content block back to Claude.\n */\nexport async function invokeWithStamp<T>(\n    input: InvokeWithStampInput<T>\n): Promise<InvokeWithStampResult<T>> {\n    const action = await stampToolUse(input);\n    const result = await input.call(input.toolUse);\n    return { result, action };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Fleet integration: POST stamped actions to fleet.ochk.io/api/actions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface FleetClient {\n    /** Defaults to https://fleet.ochk.io. */\n    baseUrl?: string;\n    /** Bearer token from /settings § 03 (`ock_<hex>`). */\n    apiToken: string;\n    /** Project the action belongs to (proj_*). */\n    projectId: string;\n    /** Optional fetch override for runtimes that need it (Node 18 LTS w/o global fetch, etc). */\n    fetch?: typeof fetch;\n}\n\nexport interface PostActionResult {\n    id: string;\n    project_id: string;\n    delegation_id: string;\n}\n\n/**\n * POST a stamped action envelope to fleet.ochk.io's /api/actions\n * registry. The fleet:\n *   - re-derives the action id from canonical inputs and rejects on\n *     mismatch (tamper defense)\n *   - validates that the agent address matches the parent delegation's\n *     agent (forgery defense)\n *   - persists, fans out to Nostr (kind 30084), submits to OC Stamp,\n *     and triggers any subscribed webhooks (action.registered)\n *\n * Returns the registered action's id + project_id + delegation_id.\n * Throws on non-2xx with the server's reason string.\n */\nexport async function postActionToFleet(\n    action: ActionEnvelope,\n    client: FleetClient\n): Promise<PostActionResult> {\n    const baseUrl = client.baseUrl ?? 'https://fleet.ochk.io';\n    const f = client.fetch ?? fetch;\n    const body = {\n        project_id: client.projectId,\n        delegation_id: action.delegation_id,\n        agent_address: action.signer.address,\n        scope_exercised: action.scope_exercised,\n        content_hash: action.content.hash,\n        content_length: action.content.length,\n        content_mime: action.content.mime,\n        signed_at: action.signed_at,\n        signature: action.sig.value,\n        id: action.id,\n    };\n    const r = await f(`${baseUrl}/api/actions`, {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${client.apiToken}`,\n        },\n        body: JSON.stringify(body),\n    });\n    if (!r.ok) {\n        let reason = `http_${r.status}`;\n        try {\n            const j = (await r.json()) as { reason?: string };\n            if (j.reason) reason = j.reason;\n        } catch {\n            // body wasn't json; keep the http_<n> reason\n        }\n        throw new Error(`postActionToFleet failed: ${reason}`);\n    }\n    const j = (await r.json()) as { ok: true; action: PostActionResult };\n    return j.action;\n}\n\nexport interface InvokeWithStampAndPostInput<T> extends InvokeWithStampInput<T> {\n    /** Fleet credentials. If absent, behaves like invokeWithStamp (no posting). */\n    fleet?: FleetClient;\n}\n\nexport interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {\n    /** Set when fleet is configured AND the POST succeeded. null otherwise. */\n    posted: PostActionResult | null;\n}\n\n/**\n * Convenience: stamp the tool_use, execute the handler, AND post the\n * stamped envelope to fleet. Three roundtrips → one call. If `fleet`\n * is omitted, this is identical to invokeWithStamp + posted=null.\n *\n * The post happens AFTER the call so a failing post doesn't prevent the\n * tool from running. If you need pre-authorization (the post must\n * succeed before the call runs), use stampToolUse + postActionToFleet\n * + your call() in that order.\n */\nexport async function invokeWithStampAndPost<T>(\n    input: InvokeWithStampAndPostInput<T>\n): Promise<InvokeWithStampAndPostResult<T>> {\n    const { result, action } = await invokeWithStamp(input);\n    let posted: PostActionResult | null = null;\n    if (input.fleet) {\n        try {\n            posted = await postActionToFleet(action, input.fleet);\n        } catch (err) {\n            // Best-effort post — surfacing the error here would force\n            // every caller to handle \"tool ran fine but post failed\",\n            // which is rarely what they want. Log and continue.\n            // eslint-disable-next-line no-console\n            console.error('[oc-agent-anthropic] postActionToFleet failed:', err);\n        }\n    }\n    return { result, action, posted };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["canonicalize","hexEncode","sha256","computeActionId","assertScopeGranted","signAsAgent","j"],"mappings":"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","file":"index.js","sourcesContent":["// @orangecheck/agent-anthropic — wrap Anthropic Tool Use invocations in\n// OC Agent action envelopes.\n//\n// Anthropic's Messages API surfaces tool calls as `tool_use` content\n// blocks: { type: 'tool_use', id, name, input }. This module canonicalizes\n// each tool_use, hashes it, and produces an agent-action envelope binding\n// the BIP-322-authenticated agent to the (tool_name, input) tuple — at a\n// scope of `anthropic:tool(name=<tool>)`.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    assertScopeGranted,\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization of an Anthropic tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AnthropicToolUse {\n    /** The `id` Anthropic assigns to this tool_use block (passed back as tool_use_id on result). */\n    id: string;\n    /** The tool name registered in your `tools` array on messages.create. */\n    name: string;\n    /** The model's structured input for this tool — JSON-serializable. */\n    input: Record<string, unknown>;\n}\n\n/**\n * Produce the canonical bytes for an Anthropic tool_use. The bytes are what\n * the agent-action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"id\":    <tool_use_id>,\n *     \"input\": <canonical JSON of input>,\n *     \"name\":  <tool name>\n *   }\n */\nexport function canonicalizeToolUse(t: AnthropicToolUse): Uint8Array {\n    const canon = {\n        id: t.id,\n        input: t.input,\n        name: t.name,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolUseHash(t: AnthropicToolUse): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolUse(t)));\n}\n\nexport function toolUseId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    t: AnthropicToolUse\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolUseHash(t),\n        content_length: canonicalizeToolUse(t).byteLength,\n        content_mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamped tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampToolUseInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    toolUse: AnthropicToolUse;\n    /** Defaults to `anthropic:tool(name=<tool>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\n/**\n * Stamp an Anthropic tool_use without executing it. Useful for pre-\n * authorization flows or batch stamping.\n */\nexport async function stampToolUse(input: StampToolUseInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? `anthropic:tool(name=${input.toolUse.name})`;\n\n    assertScopeGranted(input.delegation, scopeExercised, 'stampToolUse');\n\n    const bytes = canonicalizeToolUse(input.toolUse);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolUseHash(input.toolUse), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// invokeWithStamp — call the tool AND produce the stamp around it\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface InvokeWithStampInput<T> extends StampToolUseInput {\n    /** Your handler that actually runs the tool. Returns whatever the tool returns. */\n    call: (toolUse: AnthropicToolUse) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n}\n\n/**\n * Stamp the tool_use first, then execute the handler. The stamped envelope\n * is returned alongside the result so the caller can ship them together —\n * e.g. as a side-channel to an audit log, or as the `_oc_agent` metadata on\n * the tool_result content block back to Claude.\n */\nexport async function invokeWithStamp<T>(\n    input: InvokeWithStampInput<T>\n): Promise<InvokeWithStampResult<T>> {\n    const action = await stampToolUse(input);\n    const result = await input.call(input.toolUse);\n    return { result, action };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Fleet integration: POST stamped actions to fleet.ochk.io/api/actions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface FleetClient {\n    /** Defaults to https://fleet.ochk.io. */\n    baseUrl?: string;\n    /** Bearer token from /settings § 03 (`ock_<hex>`). */\n    apiToken: string;\n    /** Project the action belongs to (proj_*). */\n    projectId: string;\n    /** Optional fetch override for runtimes that need it (Node 18 LTS w/o global fetch, etc). */\n    fetch?: typeof fetch;\n}\n\nexport interface PostActionResult {\n    id: string;\n    project_id: string;\n    delegation_id: string;\n}\n\n/**\n * POST a stamped action envelope to fleet.ochk.io's /api/actions\n * registry. The fleet:\n *   - re-derives the action id from canonical inputs and rejects on\n *     mismatch (tamper defense)\n *   - validates that the agent address matches the parent delegation's\n *     agent (forgery defense)\n *   - persists, fans out to Nostr (kind 30084), submits to OC Stamp,\n *     and triggers any subscribed webhooks (action.registered)\n *\n * Returns the registered action's id + project_id + delegation_id.\n * Throws on non-2xx with the server's reason string.\n */\nexport async function postActionToFleet(\n    action: ActionEnvelope,\n    client: FleetClient\n): Promise<PostActionResult> {\n    const baseUrl = client.baseUrl ?? 'https://fleet.ochk.io';\n    const f = client.fetch ?? fetch;\n    const body = {\n        project_id: client.projectId,\n        delegation_id: action.delegation_id,\n        agent_address: action.signer.address,\n        scope_exercised: action.scope_exercised,\n        content_hash: action.content.hash,\n        content_length: action.content.length,\n        content_mime: action.content.mime,\n        signed_at: action.signed_at,\n        signature: action.sig.value,\n        id: action.id,\n    };\n    const r = await f(`${baseUrl}/api/actions`, {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${client.apiToken}`,\n        },\n        body: JSON.stringify(body),\n    });\n    if (!r.ok) {\n        let reason = `http_${r.status}`;\n        try {\n            const j = (await r.json()) as { reason?: string };\n            if (j.reason) reason = j.reason;\n        } catch {\n            // body wasn't json; keep the http_<n> reason\n        }\n        throw new Error(`postActionToFleet failed: ${reason}`);\n    }\n    const j = (await r.json()) as { ok: true; action: PostActionResult };\n    return j.action;\n}\n\nexport interface InvokeWithStampAndPostInput<T> extends InvokeWithStampInput<T> {\n    /** Fleet credentials. If absent, behaves like invokeWithStamp (no posting). */\n    fleet?: FleetClient;\n}\n\nexport interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {\n    /** Set when fleet is configured AND the POST succeeded. null otherwise. */\n    posted: PostActionResult | null;\n}\n\n/**\n * Convenience: stamp the tool_use, execute the handler, AND post the\n * stamped envelope to fleet. Three roundtrips → one call. If `fleet`\n * is omitted, this is identical to invokeWithStamp + posted=null.\n *\n * The post happens AFTER the call so a failing post doesn't prevent the\n * tool from running. If you need pre-authorization (the post must\n * succeed before the call runs), use stampToolUse + postActionToFleet\n * + your call() in that order.\n */\nexport async function invokeWithStampAndPost<T>(\n    input: InvokeWithStampAndPostInput<T>\n): Promise<InvokeWithStampAndPostResult<T>> {\n    const { result, action } = await invokeWithStamp(input);\n    let posted: PostActionResult | null = null;\n    if (input.fleet) {\n        try {\n            posted = await postActionToFleet(action, input.fleet);\n        } catch (err) {\n            // Best-effort post — surfacing the error here would force\n            // every caller to handle \"tool ran fine but post failed\",\n            // which is rarely what they want. Log and continue.\n            // eslint-disable-next-line no-console\n            console.error('[oc-agent-anthropic] postActionToFleet failed:', err);\n        }\n    }\n    return { result, action, posted };\n}\n"]}

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { sha256 } from '@noble/hashes/sha256';
-import { canonicalize, hexEncode, computeActionId, parseScope, isSubScope } from '@orangecheck/agent-core';
+import { canonicalize, hexEncode, computeActionId, assertScopeGranted } from '@orangecheck/agent-core';
 import { signAsAgent } from '@orangecheck/agent-signer';
 
 // src/index.ts
@@ -28,13 +28,7 @@ function toolUseId(agentAddress, signedAt, delegationId, scopeExercised, t) {
 }
 async function stampToolUse(input) {
   const scopeExercised = input.scopeExercised ?? `anthropic:tool(name=${input.toolUse.name})`;
-  const granted = (input.delegation.scopes ?? []).map(parseScope);
-  const exercisedParsed = parseScope(scopeExercised);
-  if (!granted.some((g) => isSubScope(exercisedParsed, g))) {
-    throw new Error(
-      `stampToolUse: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
-    );
-  }
+  assertScopeGranted(input.delegation, scopeExercised, "stampToolUse");
   const bytes = canonicalizeToolUse(input.toolUse);
   return signAsAgent({
     agent: input.agent,

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts"],"names":["j"],"mappings":"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","file":"index.mjs","sourcesContent":["// @orangecheck/agent-anthropic — wrap Anthropic Tool Use invocations in\n// OC Agent action envelopes.\n//\n// Anthropic's Messages API surfaces tool calls as `tool_use` content\n// blocks: { type: 'tool_use', id, name, input }. This module canonicalizes\n// each tool_use, hashes it, and produces an agent-action envelope binding\n// the BIP-322-authenticated agent to the (tool_name, input) tuple — at a\n// scope of `anthropic:tool(name=<tool>)`.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    isSubScope,\n    parseScope,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization of an Anthropic tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AnthropicToolUse {\n    /** The `id` Anthropic assigns to this tool_use block (passed back as tool_use_id on result). */\n    id: string;\n    /** The tool name registered in your `tools` array on messages.create. */\n    name: string;\n    /** The model's structured input for this tool — JSON-serializable. */\n    input: Record<string, unknown>;\n}\n\n/**\n * Produce the canonical bytes for an Anthropic tool_use. The bytes are what\n * the agent-action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"id\":    <tool_use_id>,\n *     \"input\": <canonical JSON of input>,\n *     \"name\":  <tool name>\n *   }\n */\nexport function canonicalizeToolUse(t: AnthropicToolUse): Uint8Array {\n    const canon = {\n        id: t.id,\n        input: t.input,\n        name: t.name,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolUseHash(t: AnthropicToolUse): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolUse(t)));\n}\n\nexport function toolUseId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    t: AnthropicToolUse\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolUseHash(t),\n        content_length: canonicalizeToolUse(t).byteLength,\n        content_mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamped tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampToolUseInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    toolUse: AnthropicToolUse;\n    /** Defaults to `anthropic:tool(name=<tool>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\n/**\n * Stamp an Anthropic tool_use without executing it. Useful for pre-\n * authorization flows or batch stamping.\n */\nexport async function stampToolUse(input: StampToolUseInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? `anthropic:tool(name=${input.toolUse.name})`;\n\n    const granted = (input.delegation.scopes ?? []).map(parseScope);\n    const exercisedParsed = parseScope(scopeExercised);\n    if (!granted.some((g) => isSubScope(exercisedParsed, g))) {\n        throw new Error(\n            `stampToolUse: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`\n        );\n    }\n\n    const bytes = canonicalizeToolUse(input.toolUse);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolUseHash(input.toolUse), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// invokeWithStamp — call the tool AND produce the stamp around it\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface InvokeWithStampInput<T> extends StampToolUseInput {\n    /** Your handler that actually runs the tool. Returns whatever the tool returns. */\n    call: (toolUse: AnthropicToolUse) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n}\n\n/**\n * Stamp the tool_use first, then execute the handler. The stamped envelope\n * is returned alongside the result so the caller can ship them together —\n * e.g. as a side-channel to an audit log, or as the `_oc_agent` metadata on\n * the tool_result content block back to Claude.\n */\nexport async function invokeWithStamp<T>(\n    input: InvokeWithStampInput<T>\n): Promise<InvokeWithStampResult<T>> {\n    const action = await stampToolUse(input);\n    const result = await input.call(input.toolUse);\n    return { result, action };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Fleet integration: POST stamped actions to fleet.ochk.io/api/actions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface FleetClient {\n    /** Defaults to https://fleet.ochk.io. */\n    baseUrl?: string;\n    /** Bearer token from /settings § 03 (`ock_<hex>`). */\n    apiToken: string;\n    /** Project the action belongs to (proj_*). */\n    projectId: string;\n    /** Optional fetch override for runtimes that need it (Node 18 LTS w/o global fetch, etc). */\n    fetch?: typeof fetch;\n}\n\nexport interface PostActionResult {\n    id: string;\n    project_id: string;\n    delegation_id: string;\n}\n\n/**\n * POST a stamped action envelope to fleet.ochk.io's /api/actions\n * registry. The fleet:\n *   - re-derives the action id from canonical inputs and rejects on\n *     mismatch (tamper defense)\n *   - validates that the agent address matches the parent delegation's\n *     agent (forgery defense)\n *   - persists, fans out to Nostr (kind 30084), submits to OC Stamp,\n *     and triggers any subscribed webhooks (action.registered)\n *\n * Returns the registered action's id + project_id + delegation_id.\n * Throws on non-2xx with the server's reason string.\n */\nexport async function postActionToFleet(\n    action: ActionEnvelope,\n    client: FleetClient\n): Promise<PostActionResult> {\n    const baseUrl = client.baseUrl ?? 'https://fleet.ochk.io';\n    const f = client.fetch ?? fetch;\n    const body = {\n        project_id: client.projectId,\n        delegation_id: action.delegation_id,\n        agent_address: action.signer.address,\n        scope_exercised: action.scope_exercised,\n        content_hash: action.content.hash,\n        content_length: action.content.length,\n        content_mime: action.content.mime,\n        signed_at: action.signed_at,\n        signature: action.sig.value,\n        id: action.id,\n    };\n    const r = await f(`${baseUrl}/api/actions`, {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${client.apiToken}`,\n        },\n        body: JSON.stringify(body),\n    });\n    if (!r.ok) {\n        let reason = `http_${r.status}`;\n        try {\n            const j = (await r.json()) as { reason?: string };\n            if (j.reason) reason = j.reason;\n        } catch {\n            // body wasn't json; keep the http_<n> reason\n        }\n        throw new Error(`postActionToFleet failed: ${reason}`);\n    }\n    const j = (await r.json()) as { ok: true; action: PostActionResult };\n    return j.action;\n}\n\nexport interface InvokeWithStampAndPostInput<T> extends InvokeWithStampInput<T> {\n    /** Fleet credentials. If absent, behaves like invokeWithStamp (no posting). */\n    fleet?: FleetClient;\n}\n\nexport interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {\n    /** Set when fleet is configured AND the POST succeeded. null otherwise. */\n    posted: PostActionResult | null;\n}\n\n/**\n * Convenience: stamp the tool_use, execute the handler, AND post the\n * stamped envelope to fleet. Three roundtrips → one call. If `fleet`\n * is omitted, this is identical to invokeWithStamp + posted=null.\n *\n * The post happens AFTER the call so a failing post doesn't prevent the\n * tool from running. If you need pre-authorization (the post must\n * succeed before the call runs), use stampToolUse + postActionToFleet\n * + your call() in that order.\n */\nexport async function invokeWithStampAndPost<T>(\n    input: InvokeWithStampAndPostInput<T>\n): Promise<InvokeWithStampAndPostResult<T>> {\n    const { result, action } = await invokeWithStamp(input);\n    let posted: PostActionResult | null = null;\n    if (input.fleet) {\n        try {\n            posted = await postActionToFleet(action, input.fleet);\n        } catch (err) {\n            // Best-effort post — surfacing the error here would force\n            // every caller to handle \"tool ran fine but post failed\",\n            // which is rarely what they want. Log and continue.\n            // eslint-disable-next-line no-console\n            console.error('[oc-agent-anthropic] postActionToFleet failed:', err);\n        }\n    }\n    return { result, action, posted };\n}\n"]}
+{"version":3,"sources":["../src/index.ts"],"names":["j"],"mappings":"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","file":"index.mjs","sourcesContent":["// @orangecheck/agent-anthropic — wrap Anthropic Tool Use invocations in\n// OC Agent action envelopes.\n//\n// Anthropic's Messages API surfaces tool calls as `tool_use` content\n// blocks: { type: 'tool_use', id, name, input }. This module canonicalizes\n// each tool_use, hashes it, and produces an agent-action envelope binding\n// the BIP-322-authenticated agent to the (tool_name, input) tuple — at a\n// scope of `anthropic:tool(name=<tool>)`.\n\nimport { sha256 } from '@noble/hashes/sha256';\nimport {\n    assertScopeGranted,\n    canonicalize,\n    computeActionId,\n    hexEncode,\n    type DelegationEnvelope,\n} from '@orangecheck/agent-core';\nimport {\n    signAsAgent,\n    type ActionEnvelope,\n    type SignerRef,\n} from '@orangecheck/agent-signer';\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization of an Anthropic tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface AnthropicToolUse {\n    /** The `id` Anthropic assigns to this tool_use block (passed back as tool_use_id on result). */\n    id: string;\n    /** The tool name registered in your `tools` array on messages.create. */\n    name: string;\n    /** The model's structured input for this tool — JSON-serializable. */\n    input: Record<string, unknown>;\n}\n\n/**\n * Produce the canonical bytes for an Anthropic tool_use. The bytes are what\n * the agent-action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"id\":    <tool_use_id>,\n *     \"input\": <canonical JSON of input>,\n *     \"name\":  <tool name>\n *   }\n */\nexport function canonicalizeToolUse(t: AnthropicToolUse): Uint8Array {\n    const canon = {\n        id: t.id,\n        input: t.input,\n        name: t.name,\n    };\n    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);\n    return new TextEncoder().encode(str + '\\n');\n}\n\nexport function toolUseHash(t: AnthropicToolUse): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeToolUse(t)));\n}\n\nexport function toolUseId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    t: AnthropicToolUse\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: toolUseHash(t),\n        content_length: canonicalizeToolUse(t).byteLength,\n        content_mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamped tool_use\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampToolUseInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    toolUse: AnthropicToolUse;\n    /** Defaults to `anthropic:tool(name=<tool>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\n/**\n * Stamp an Anthropic tool_use without executing it. Useful for pre-\n * authorization flows or batch stamping.\n */\nexport async function stampToolUse(input: StampToolUseInput): Promise<ActionEnvelope> {\n    const scopeExercised =\n        input.scopeExercised ?? `anthropic:tool(name=${input.toolUse.name})`;\n\n    assertScopeGranted(input.delegation, scopeExercised, 'stampToolUse');\n\n    const bytes = canonicalizeToolUse(input.toolUse);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: toolUseHash(input.toolUse), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.anthropic-tool-use+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// invokeWithStamp — call the tool AND produce the stamp around it\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface InvokeWithStampInput<T> extends StampToolUseInput {\n    /** Your handler that actually runs the tool. Returns whatever the tool returns. */\n    call: (toolUse: AnthropicToolUse) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n}\n\n/**\n * Stamp the tool_use first, then execute the handler. The stamped envelope\n * is returned alongside the result so the caller can ship them together —\n * e.g. as a side-channel to an audit log, or as the `_oc_agent` metadata on\n * the tool_result content block back to Claude.\n */\nexport async function invokeWithStamp<T>(\n    input: InvokeWithStampInput<T>\n): Promise<InvokeWithStampResult<T>> {\n    const action = await stampToolUse(input);\n    const result = await input.call(input.toolUse);\n    return { result, action };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Fleet integration: POST stamped actions to fleet.ochk.io/api/actions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface FleetClient {\n    /** Defaults to https://fleet.ochk.io. */\n    baseUrl?: string;\n    /** Bearer token from /settings § 03 (`ock_<hex>`). */\n    apiToken: string;\n    /** Project the action belongs to (proj_*). */\n    projectId: string;\n    /** Optional fetch override for runtimes that need it (Node 18 LTS w/o global fetch, etc). */\n    fetch?: typeof fetch;\n}\n\nexport interface PostActionResult {\n    id: string;\n    project_id: string;\n    delegation_id: string;\n}\n\n/**\n * POST a stamped action envelope to fleet.ochk.io's /api/actions\n * registry. The fleet:\n *   - re-derives the action id from canonical inputs and rejects on\n *     mismatch (tamper defense)\n *   - validates that the agent address matches the parent delegation's\n *     agent (forgery defense)\n *   - persists, fans out to Nostr (kind 30084), submits to OC Stamp,\n *     and triggers any subscribed webhooks (action.registered)\n *\n * Returns the registered action's id + project_id + delegation_id.\n * Throws on non-2xx with the server's reason string.\n */\nexport async function postActionToFleet(\n    action: ActionEnvelope,\n    client: FleetClient\n): Promise<PostActionResult> {\n    const baseUrl = client.baseUrl ?? 'https://fleet.ochk.io';\n    const f = client.fetch ?? fetch;\n    const body = {\n        project_id: client.projectId,\n        delegation_id: action.delegation_id,\n        agent_address: action.signer.address,\n        scope_exercised: action.scope_exercised,\n        content_hash: action.content.hash,\n        content_length: action.content.length,\n        content_mime: action.content.mime,\n        signed_at: action.signed_at,\n        signature: action.sig.value,\n        id: action.id,\n    };\n    const r = await f(`${baseUrl}/api/actions`, {\n        method: 'POST',\n        headers: {\n            'Content-Type': 'application/json',\n            Authorization: `Bearer ${client.apiToken}`,\n        },\n        body: JSON.stringify(body),\n    });\n    if (!r.ok) {\n        let reason = `http_${r.status}`;\n        try {\n            const j = (await r.json()) as { reason?: string };\n            if (j.reason) reason = j.reason;\n        } catch {\n            // body wasn't json; keep the http_<n> reason\n        }\n        throw new Error(`postActionToFleet failed: ${reason}`);\n    }\n    const j = (await r.json()) as { ok: true; action: PostActionResult };\n    return j.action;\n}\n\nexport interface InvokeWithStampAndPostInput<T> extends InvokeWithStampInput<T> {\n    /** Fleet credentials. If absent, behaves like invokeWithStamp (no posting). */\n    fleet?: FleetClient;\n}\n\nexport interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {\n    /** Set when fleet is configured AND the POST succeeded. null otherwise. */\n    posted: PostActionResult | null;\n}\n\n/**\n * Convenience: stamp the tool_use, execute the handler, AND post the\n * stamped envelope to fleet. Three roundtrips → one call. If `fleet`\n * is omitted, this is identical to invokeWithStamp + posted=null.\n *\n * The post happens AFTER the call so a failing post doesn't prevent the\n * tool from running. If you need pre-authorization (the post must\n * succeed before the call runs), use stampToolUse + postActionToFleet\n * + your call() in that order.\n */\nexport async function invokeWithStampAndPost<T>(\n    input: InvokeWithStampAndPostInput<T>\n): Promise<InvokeWithStampAndPostResult<T>> {\n    const { result, action } = await invokeWithStamp(input);\n    let posted: PostActionResult | null = null;\n    if (input.fleet) {\n        try {\n            posted = await postActionToFleet(action, input.fleet);\n        } catch (err) {\n            // Best-effort post — surfacing the error here would force\n            // every caller to handle \"tool ran fine but post failed\",\n            // which is rarely what they want. Log and continue.\n            // eslint-disable-next-line no-console\n            console.error('[oc-agent-anthropic] postActionToFleet failed:', err);\n        }\n    }\n    return { result, action, posted };\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orangecheck/agent-anthropic",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Wrap Anthropic Tool Use (Claude tool_use blocks) with OC Agent scope enforcement and emit a signed agent-action envelope per tool execution.",
   "keywords": [
     "bitcoin",
@@ -51,8 +51,8 @@
   },
   "dependencies": {
     "@noble/hashes": "^1.5.0",
-    "@orangecheck/agent-core": "^0.3.0",
-    "@orangecheck/agent-signer": "^0.1.0"
+    "@orangecheck/agent-core": "^1.2.0",
+    "@orangecheck/agent-signer": "^0.3.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.2",

package/src/index.ts

@@ -9,11 +9,10 @@
 
 import { sha256 } from '@noble/hashes/sha256';
 import {
+    assertScopeGranted,
     canonicalize,
     computeActionId,
     hexEncode,
-    isSubScope,
-    parseScope,
     type DelegationEnvelope,
 } from '@orangecheck/agent-core';
 import {
@@ -99,13 +98,7 @@ export async function stampToolUse(input: StampToolUseInput): Promise<ActionEnve
     const scopeExercised =
         input.scopeExercised ?? `anthropic:tool(name=${input.toolUse.name})`;
 
-    const granted = (input.delegation.scopes ?? []).map(parseScope);
-    const exercisedParsed = parseScope(scopeExercised);
-    if (!granted.some((g) => isSubScope(exercisedParsed, g))) {
-        throw new Error(
-            `stampToolUse: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
-        );
-    }
+    assertScopeGranted(input.delegation, scopeExercised, 'stampToolUse');
 
     const bytes = canonicalizeToolUse(input.toolUse);
     return signAsAgent({

package/src/scope-preflight.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it } from 'vitest';
+
+import { ScopeNotGrantedError } from '@orangecheck/agent-core';
+
+import { stampToolUse } from './index.js';
+
+const AGENT = 'bc1qagent0000000000000000000000000000000000';
+const sign = () => async (msg: string) => Buffer.from(msg, 'utf8').toString('base64');
+
+const SEALED = {
+    v: 1,
+    alg: 'x25519-xchacha20poly1305',
+    recipients: [{ device_id: 'dev1', ct: 'AA' }],
+    ct: 'BB',
+    nonce: 'CC',
+} as never;
+
+/**
+ * This adapter used to open-code the pre-flight scope check. It now routes to
+ * agent-core's `assertScopeGranted`, and these assert the routing rather than
+ * the check — agent-core owns testing the check itself.
+ *
+ * The case that matters is the encrypted one: a v1.2 private delegation has no
+ * readable `scopes`, and the old `?? []` reported that as "not a sub-scope of
+ * any granted scope" — pointing the integrator at a scope string that was
+ * probably fine, when the actual need was to decrypt the grant.
+ */
+describe('stampToolUse scope pre-flight', () => {
+    const base = {
+        agent: { address: AGENT, sign: sign() },
+        toolUse: { type: 'tool_use', id: 't1', name: 'search', input: { q: 'x' } },
+    } as never;
+
+    it('names encrypted scopes rather than blaming the scope string', async () => {
+        const err = await stampToolUse({
+            ...(base as object),
+            delegation: { scopes_encrypted: SEALED },
+            scopeExercised: 'anthropic:tool(name=search)',
+        } as never).catch((e: unknown) => e);
+
+        expect(err).toBeInstanceOf(ScopeNotGrantedError);
+        expect((err as ScopeNotGrantedError).reason).toBe('scopes_encrypted');
+        expect((err as Error).message).toMatch(/decryptPrivateScopes/);
+    });
+
+    it('treats an absent grant as granting nothing', async () => {
+        const err = await stampToolUse({
+            ...(base as object),
+            delegation: {},
+            scopeExercised: 'anthropic:tool(name=search)',
+        } as never).catch((e: unknown) => e);
+
+        expect((err as ScopeNotGrantedError).reason).toBe('no_scopes');
+    });
+});