@orangecheck/agent-openai 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OrangeCheck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @orangecheck/agent-openai
+
+Wrap [OpenAI function calls](https://platform.openai.com/docs/guides/function-calling) with [OC Agent](https://github.com/orangecheck/oc-agent-protocol) scope enforcement and emit a signed `agent-action` envelope per invocation. Covers both the new **Responses API** (`function_call` items) and the legacy **Chat Completions** tool path (`tool_calls`).
+
+## Why
+
+Function calling is the OpenAI-shaped way agents reach out to the world. Without scope enforcement and a cryptographic action receipt, "the model called this function" is the entire audit trail. With this adapter, every call carries: the agent address (BIP-322 signed), the active delegation, the exercised scope, the content hash of the inputs, and the OC Stamp anchor — replayable offline forever.
+
+## Status
+
+**v0.0.1 · in design.** API shape is stable; canonicalization is locked. Production wiring (per-event streaming integration with the OpenAI SDK's `responses.stream()` / `chat.completions.create()`) lands when the first design partner names the integration.
+
+## Install
+
+```bash
+npm i @orangecheck/agent-openai
+# peer deps:
+npm i @orangecheck/agent-core @orangecheck/agent-signer
+```
+
+## Quickstart
+
+```ts
+import { invokeWithStamp } from '@orangecheck/agent-openai';
+
+// Pull a tool_call out of a Chat Completions response …
+const toolCall = response.choices[0].message.tool_calls[0];
+
+const { result, action, call } = await invokeWithStamp({
+    agent,
+    delegation,
+    call: toolCall, // raw OpenAI shape — we normalize
+    execute: async (c) => myInvoiceCreateImpl(c.arguments),
+});
+
+// `result` becomes the tool result you feed back to the model.
+// `call` is the normalized OpenAiFunctionCall (id, name, arguments).
+// `action` is the signed envelope; ship to your audit bundle / Nostr.
+```
+
+The same `invokeWithStamp` works on Responses-API `function_call` items — `parseFunctionCall` handles the `call_id` / `id` and string-vs-object `arguments` differences automatically.
+
+## What gets stamped
+
+The stamp's `content.hash` is a SHA-256 of the RFC-8785-canonicalized JSON:
+
+```json
+{
+  "arguments": <canonical JSON of arguments>,
+  "id":        "<call id>",
+  "name":      "<function name>"
+}
+```
+
+The action's `scope_exercised` defaults to `openai:function(name=<name>)`. Override via `scopeExercised`.
+
+## API
+
+- `parseFunctionCall(raw)` — normalizes a Chat Completions `tool_call` or Responses `function_call` into `{id, name, arguments}`.
+- `canonicalizeFunctionCall(call)` — RFC 8785 canonical bytes.
+- `functionCallHash(call)` — `sha256:<64-hex>` for `content.hash`.
+- `stampFunctionCall(input)` — sign without executing.
+- `invokeWithStamp(input)` — sign + execute + return both.
+
+## License
+
+MIT.
+
+## Related
+
+- [oc-agent-protocol](https://github.com/orangecheck/oc-agent-protocol) — normative wire format.
+- [@orangecheck/agent-core](https://www.npmjs.com/package/@orangecheck/agent-core) — verifier library.
+- [@orangecheck/agent-mcp](https://www.npmjs.com/package/@orangecheck/agent-mcp) — same pattern, for MCP.
+- [@orangecheck/agent-anthropic](https://www.npmjs.com/package/@orangecheck/agent-anthropic) — same pattern, for Claude Tool Use.
+- [console.ochk.io/integrations/openai](https://console.ochk.io/integrations/openai) — managed-tier story.

package/dist/index.d.mts

@@ -0,0 +1,50 @@
+import { DelegationEnvelope } from '@orangecheck/agent-core';
+import { SignerRef, ActionEnvelope } from '@orangecheck/agent-signer';
+
+interface OpenAiFunctionCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+declare function parseFunctionCall(raw: unknown): OpenAiFunctionCall;
+declare function canonicalizeFunctionCall(c: OpenAiFunctionCall): Uint8Array;
+declare function functionCallHash(c: OpenAiFunctionCall): string;
+declare function functionCallActionId(agentAddress: string, signedAt: string, delegationId: string, scopeExercised: string, c: OpenAiFunctionCall): string;
+interface StampFunctionCallInput {
+    agent: SignerRef;
+    delegation: DelegationEnvelope;
+    call: OpenAiFunctionCall | unknown;
+    scopeExercised?: string;
+    signedAt?: Date;
+}
+declare function stampFunctionCall(input: StampFunctionCallInput): Promise<ActionEnvelope>;
+interface InvokeWithStampInput<T> extends StampFunctionCallInput {
+    execute: (call: OpenAiFunctionCall) => Promise<T>;
+}
+interface InvokeWithStampResult<T> {
+    result: T;
+    action: ActionEnvelope;
+    call: OpenAiFunctionCall;
+}
+declare function invokeWithStamp<T>(input: InvokeWithStampInput<T>): Promise<InvokeWithStampResult<T>>;
+interface ConsoleClient {
+    baseUrl?: string;
+    apiToken: string;
+    projectId: string;
+    fetch?: typeof fetch;
+}
+interface PostActionResult {
+    id: string;
+    project_id: string;
+    delegation_id: string;
+}
+declare function postActionToConsole(action: ActionEnvelope, client: ConsoleClient): Promise<PostActionResult>;
+interface InvokeWithStampAndPostInput<T> extends InvokeWithStampInput<T> {
+    console?: ConsoleClient;
+}
+interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {
+    posted: PostActionResult | null;
+}
+declare function invokeWithStampAndPost<T>(input: InvokeWithStampAndPostInput<T>): Promise<InvokeWithStampAndPostResult<T>>;
+
+export { type ConsoleClient, type InvokeWithStampAndPostInput, type InvokeWithStampAndPostResult, type InvokeWithStampInput, type InvokeWithStampResult, type OpenAiFunctionCall, type PostActionResult, type StampFunctionCallInput, canonicalizeFunctionCall, functionCallActionId, functionCallHash, invokeWithStamp, invokeWithStampAndPost, parseFunctionCall, postActionToConsole, stampFunctionCall };

package/dist/index.d.ts

@@ -0,0 +1,50 @@
+import { DelegationEnvelope } from '@orangecheck/agent-core';
+import { SignerRef, ActionEnvelope } from '@orangecheck/agent-signer';
+
+interface OpenAiFunctionCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+declare function parseFunctionCall(raw: unknown): OpenAiFunctionCall;
+declare function canonicalizeFunctionCall(c: OpenAiFunctionCall): Uint8Array;
+declare function functionCallHash(c: OpenAiFunctionCall): string;
+declare function functionCallActionId(agentAddress: string, signedAt: string, delegationId: string, scopeExercised: string, c: OpenAiFunctionCall): string;
+interface StampFunctionCallInput {
+    agent: SignerRef;
+    delegation: DelegationEnvelope;
+    call: OpenAiFunctionCall | unknown;
+    scopeExercised?: string;
+    signedAt?: Date;
+}
+declare function stampFunctionCall(input: StampFunctionCallInput): Promise<ActionEnvelope>;
+interface InvokeWithStampInput<T> extends StampFunctionCallInput {
+    execute: (call: OpenAiFunctionCall) => Promise<T>;
+}
+interface InvokeWithStampResult<T> {
+    result: T;
+    action: ActionEnvelope;
+    call: OpenAiFunctionCall;
+}
+declare function invokeWithStamp<T>(input: InvokeWithStampInput<T>): Promise<InvokeWithStampResult<T>>;
+interface ConsoleClient {
+    baseUrl?: string;
+    apiToken: string;
+    projectId: string;
+    fetch?: typeof fetch;
+}
+interface PostActionResult {
+    id: string;
+    project_id: string;
+    delegation_id: string;
+}
+declare function postActionToConsole(action: ActionEnvelope, client: ConsoleClient): Promise<PostActionResult>;
+interface InvokeWithStampAndPostInput<T> extends InvokeWithStampInput<T> {
+    console?: ConsoleClient;
+}
+interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {
+    posted: PostActionResult | null;
+}
+declare function invokeWithStampAndPost<T>(input: InvokeWithStampAndPostInput<T>): Promise<InvokeWithStampAndPostResult<T>>;
+
+export { type ConsoleClient, type InvokeWithStampAndPostInput, type InvokeWithStampAndPostResult, type InvokeWithStampInput, type InvokeWithStampResult, type OpenAiFunctionCall, type PostActionResult, type StampFunctionCallInput, canonicalizeFunctionCall, functionCallActionId, functionCallHash, invokeWithStamp, invokeWithStampAndPost, parseFunctionCall, postActionToConsole, stampFunctionCall };

package/dist/index.js

@@ -0,0 +1,147 @@
+'use strict';
+
+var sha256 = require('@noble/hashes/sha256');
+var agentCore = require('@orangecheck/agent-core');
+var agentSigner = require('@orangecheck/agent-signer');
+
+// src/index.ts
+function parseFunctionCall(raw) {
+  if (raw == null || typeof raw !== "object") {
+    throw new TypeError("parseFunctionCall: input is not an object");
+  }
+  const r = raw;
+  if (r.function && typeof r.function === "object") {
+    const f = r.function;
+    return {
+      id: String(r.id ?? ""),
+      name: String(f.name ?? ""),
+      arguments: parseArgs(f.arguments)
+    };
+  }
+  return {
+    id: String(r.id ?? r.call_id ?? ""),
+    name: String(r.name ?? ""),
+    arguments: parseArgs(r.arguments)
+  };
+}
+function parseArgs(args) {
+  if (args == null) return {};
+  if (typeof args === "object") return args;
+  if (typeof args === "string") {
+    try {
+      const v = JSON.parse(args);
+      if (v && typeof v === "object") return v;
+      return { _raw: args };
+    } catch {
+      return { _raw: args };
+    }
+  }
+  return { _raw: String(args) };
+}
+function canonicalizeFunctionCall(c) {
+  const canon = {
+    arguments: c.arguments,
+    id: c.id,
+    name: c.name
+  };
+  const str = agentCore.canonicalize(canon);
+  return new TextEncoder().encode(str + "\n");
+}
+function functionCallHash(c) {
+  return "sha256:" + agentCore.hexEncode(sha256.sha256(canonicalizeFunctionCall(c)));
+}
+function functionCallActionId(agentAddress, signedAt, delegationId, scopeExercised, c) {
+  return agentCore.computeActionId({
+    address: agentAddress,
+    content_hash: functionCallHash(c),
+    content_length: canonicalizeFunctionCall(c).byteLength,
+    content_mime: "application/vnd.oc-agent.openai-function-call+json",
+    signed_at: signedAt,
+    delegation_id: delegationId,
+    scope_exercised: scopeExercised
+  });
+}
+async function stampFunctionCall(input) {
+  const fc = typeof input.call === "object" && input.call !== null && "arguments" in input.call && typeof input.call.arguments !== "string" ? input.call : parseFunctionCall(input.call);
+  const scopeExercised = input.scopeExercised ?? `openai:function(name=${fc.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(
+      `stampFunctionCall: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
+    );
+  }
+  const bytes = canonicalizeFunctionCall(fc);
+  return agentSigner.signAsAgent({
+    agent: input.agent,
+    delegation: input.delegation,
+    content: { hash: functionCallHash(fc), length: bytes.byteLength },
+    mime: "application/vnd.oc-agent.openai-function-call+json",
+    scopeExercised,
+    signedAt: input.signedAt
+  });
+}
+async function invokeWithStamp(input) {
+  const action = await stampFunctionCall(input);
+  const fc = parseFunctionCall(input.call);
+  const result = await input.execute(fc);
+  return { result, action, call: fc };
+}
+async function postActionToConsole(action, client) {
+  const baseUrl = client.baseUrl ?? "https://console.ochk.io";
+  const f = client.fetch ?? fetch;
+  const body = {
+    project_id: client.projectId,
+    delegation_id: action.delegation_id,
+    agent_address: action.signer.address,
+    scope_exercised: action.scope_exercised,
+    content_hash: action.content.hash,
+    content_length: action.content.length,
+    content_mime: action.content.mime,
+    signed_at: action.signed_at,
+    signature: action.sig.value,
+    id: action.id
+  };
+  const r = await f(`${baseUrl}/api/actions`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${client.apiToken}`
+    },
+    body: JSON.stringify(body)
+  });
+  if (!r.ok) {
+    let reason = `http_${r.status}`;
+    try {
+      const j2 = await r.json();
+      if (j2.reason) reason = j2.reason;
+    } catch {
+    }
+    throw new Error(`postActionToConsole failed: ${reason}`);
+  }
+  const j = await r.json();
+  return j.action;
+}
+async function invokeWithStampAndPost(input) {
+  const { result, action, call } = await invokeWithStamp(input);
+  let posted = null;
+  if (input.console) {
+    try {
+      posted = await postActionToConsole(action, input.console);
+    } catch (err) {
+      console.error("[oc-agent-openai] postActionToConsole failed:", err);
+    }
+  }
+  return { result, action, call, posted };
+}
+
+exports.canonicalizeFunctionCall = canonicalizeFunctionCall;
+exports.functionCallActionId = functionCallActionId;
+exports.functionCallHash = functionCallHash;
+exports.invokeWithStamp = invokeWithStamp;
+exports.invokeWithStampAndPost = invokeWithStampAndPost;
+exports.parseFunctionCall = parseFunctionCall;
+exports.postActionToConsole = postActionToConsole;
+exports.stampFunctionCall = stampFunctionCall;
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +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-openai — wrap OpenAI function calls in OC Agent\n// action envelopes.\n//\n// Covers both surfaces:\n//   - Responses API:        response.output → tool_call items with\n//                            { type: 'function_call', name, arguments, call_id }\n//                            (`arguments` is a JSON string)\n//   - Chat Completions:     message.tool_calls[i] = { id, function: { name, arguments } }\n//                            (`arguments` is also a JSON string)\n//\n// Both shapes normalize through `parseFunctionCall()` to the canonical\n// {id, name, arguments} form before hashing.\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// Shape normalization\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface OpenAiFunctionCall {\n    /** OpenAI's `id` for this call (Chat Completions: `tool_call.id`; Responses: `call_id`). */\n    id: string;\n    /** The function name. */\n    name: string;\n    /** The (already-parsed) function arguments. */\n    arguments: Record<string, unknown>;\n}\n\n/**\n * Normalize either a Chat Completions `tool_call` or a Responses\n * `function_call` item into our canonical {id, name, arguments} shape.\n *\n * Accepts:\n *   - { id, function: { name, arguments } }                      (Chat Completions)\n *   - { call_id, name, arguments }                               (Responses, function_call)\n *   - { id, name, arguments }                                    (already normalized)\n *\n * `arguments` may be either a JSON string (OpenAI's wire shape) or an\n * already-parsed object (your post-processing). Both work.\n */\nexport function parseFunctionCall(raw: unknown): OpenAiFunctionCall {\n    if (raw == null || typeof raw !== 'object') {\n        throw new TypeError('parseFunctionCall: input is not an object');\n    }\n    const r = raw as Record<string, unknown>;\n\n    // Chat Completions shape\n    if (r.function && typeof r.function === 'object') {\n        const f = r.function as Record<string, unknown>;\n        return {\n            id: String(r.id ?? ''),\n            name: String(f.name ?? ''),\n            arguments: parseArgs(f.arguments),\n        };\n    }\n\n    // Responses API or already-normalized\n    return {\n        id: String(r.id ?? r.call_id ?? ''),\n        name: String(r.name ?? ''),\n        arguments: parseArgs(r.arguments),\n    };\n}\n\nfunction parseArgs(args: unknown): Record<string, unknown> {\n    if (args == null) return {};\n    if (typeof args === 'object') return args as Record<string, unknown>;\n    if (typeof args === 'string') {\n        try {\n            const v = JSON.parse(args);\n            if (v && typeof v === 'object') return v as Record<string, unknown>;\n            return { _raw: args };\n        } catch {\n            return { _raw: args };\n        }\n    }\n    return { _raw: String(args) };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Produce the canonical bytes for an OpenAI function call. The bytes are\n * what the agent-action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"arguments\": <canonical JSON of arguments>,\n *     \"id\":        <call id>,\n *     \"name\":      <function name>\n *   }\n */\nexport function canonicalizeFunctionCall(c: OpenAiFunctionCall): Uint8Array {\n    const canon = {\n        arguments: c.arguments,\n        id: c.id,\n        name: c.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 functionCallHash(c: OpenAiFunctionCall): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeFunctionCall(c)));\n}\n\nexport function functionCallActionId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    c: OpenAiFunctionCall\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: functionCallHash(c),\n        content_length: canonicalizeFunctionCall(c).byteLength,\n        content_mime: 'application/vnd.oc-agent.openai-function-call+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamping + invocation\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampFunctionCallInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    /** Either a normalized `OpenAiFunctionCall` or a raw OpenAI tool_call / function_call object. */\n    call: OpenAiFunctionCall | unknown;\n    /** Defaults to `openai:function(name=<name>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\nexport async function stampFunctionCall(\n    input: StampFunctionCallInput\n): Promise<ActionEnvelope> {\n    const fc =\n        typeof input.call === 'object' &&\n        input.call !== null &&\n        'arguments' in (input.call as Record<string, unknown>) &&\n        typeof (input.call as Record<string, unknown>).arguments !== 'string'\n            ? (input.call as OpenAiFunctionCall)\n            : parseFunctionCall(input.call);\n\n    const scopeExercised =\n        input.scopeExercised ?? `openai:function(name=${fc.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            `stampFunctionCall: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`\n        );\n    }\n\n    const bytes = canonicalizeFunctionCall(fc);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: functionCallHash(fc), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.openai-function-call+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\nexport interface InvokeWithStampInput<T> extends StampFunctionCallInput {\n    /** Your handler. Receives the normalized OpenAiFunctionCall. */\n    execute: (call: OpenAiFunctionCall) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n    call: OpenAiFunctionCall;\n}\n\nexport async function invokeWithStamp<T>(\n    input: InvokeWithStampInput<T>\n): Promise<InvokeWithStampResult<T>> {\n    const action = await stampFunctionCall(input);\n    const fc = parseFunctionCall(input.call);\n    const result = await input.execute(fc);\n    return { result, action, call: fc };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Console integration: POST stamped actions to console.ochk.io/api/actions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ConsoleClient {\n    /** Defaults to https://console.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. */\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 console.ochk.io/api/actions. The\n * console re-derives the action id, validates agent-must-match-\n * delegation, persists, fans out to Nostr (kind 30084), submits to\n * OC Stamp, and triggers any subscribed webhooks. Throws on non-2xx\n * with the server's reason string.\n */\nexport async function postActionToConsole(\n    action: ActionEnvelope,\n    client: ConsoleClient\n): Promise<PostActionResult> {\n    const baseUrl = client.baseUrl ?? 'https://console.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\n        }\n        throw new Error(`postActionToConsole 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    /** Console credentials. If absent, behaves like invokeWithStamp. */\n    console?: ConsoleClient;\n}\n\nexport interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {\n    /** Set when console is configured AND the POST succeeded. */\n    posted: PostActionResult | null;\n}\n\nexport async function invokeWithStampAndPost<T>(\n    input: InvokeWithStampAndPostInput<T>\n): Promise<InvokeWithStampAndPostResult<T>> {\n    const { result, action, call } = await invokeWithStamp(input);\n    let posted: PostActionResult | null = null;\n    if (input.console) {\n        try {\n            posted = await postActionToConsole(action, input.console);\n        } catch (err) {\n            // eslint-disable-next-line no-console\n            console.error('[oc-agent-openai] postActionToConsole failed:', err);\n        }\n    }\n    return { result, action, call, posted };\n}\n"]}

package/dist/index.mjs

@@ -0,0 +1,138 @@
+import { sha256 } from '@noble/hashes/sha256';
+import { canonicalize, hexEncode, computeActionId, parseScope, isSubScope } from '@orangecheck/agent-core';
+import { signAsAgent } from '@orangecheck/agent-signer';
+
+// src/index.ts
+function parseFunctionCall(raw) {
+  if (raw == null || typeof raw !== "object") {
+    throw new TypeError("parseFunctionCall: input is not an object");
+  }
+  const r = raw;
+  if (r.function && typeof r.function === "object") {
+    const f = r.function;
+    return {
+      id: String(r.id ?? ""),
+      name: String(f.name ?? ""),
+      arguments: parseArgs(f.arguments)
+    };
+  }
+  return {
+    id: String(r.id ?? r.call_id ?? ""),
+    name: String(r.name ?? ""),
+    arguments: parseArgs(r.arguments)
+  };
+}
+function parseArgs(args) {
+  if (args == null) return {};
+  if (typeof args === "object") return args;
+  if (typeof args === "string") {
+    try {
+      const v = JSON.parse(args);
+      if (v && typeof v === "object") return v;
+      return { _raw: args };
+    } catch {
+      return { _raw: args };
+    }
+  }
+  return { _raw: String(args) };
+}
+function canonicalizeFunctionCall(c) {
+  const canon = {
+    arguments: c.arguments,
+    id: c.id,
+    name: c.name
+  };
+  const str = canonicalize(canon);
+  return new TextEncoder().encode(str + "\n");
+}
+function functionCallHash(c) {
+  return "sha256:" + hexEncode(sha256(canonicalizeFunctionCall(c)));
+}
+function functionCallActionId(agentAddress, signedAt, delegationId, scopeExercised, c) {
+  return computeActionId({
+    address: agentAddress,
+    content_hash: functionCallHash(c),
+    content_length: canonicalizeFunctionCall(c).byteLength,
+    content_mime: "application/vnd.oc-agent.openai-function-call+json",
+    signed_at: signedAt,
+    delegation_id: delegationId,
+    scope_exercised: scopeExercised
+  });
+}
+async function stampFunctionCall(input) {
+  const fc = typeof input.call === "object" && input.call !== null && "arguments" in input.call && typeof input.call.arguments !== "string" ? input.call : parseFunctionCall(input.call);
+  const scopeExercised = input.scopeExercised ?? `openai:function(name=${fc.name})`;
+  const granted = (input.delegation.scopes ?? []).map(parseScope);
+  const exercisedParsed = parseScope(scopeExercised);
+  if (!granted.some((g) => isSubScope(exercisedParsed, g))) {
+    throw new Error(
+      `stampFunctionCall: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
+    );
+  }
+  const bytes = canonicalizeFunctionCall(fc);
+  return signAsAgent({
+    agent: input.agent,
+    delegation: input.delegation,
+    content: { hash: functionCallHash(fc), length: bytes.byteLength },
+    mime: "application/vnd.oc-agent.openai-function-call+json",
+    scopeExercised,
+    signedAt: input.signedAt
+  });
+}
+async function invokeWithStamp(input) {
+  const action = await stampFunctionCall(input);
+  const fc = parseFunctionCall(input.call);
+  const result = await input.execute(fc);
+  return { result, action, call: fc };
+}
+async function postActionToConsole(action, client) {
+  const baseUrl = client.baseUrl ?? "https://console.ochk.io";
+  const f = client.fetch ?? fetch;
+  const body = {
+    project_id: client.projectId,
+    delegation_id: action.delegation_id,
+    agent_address: action.signer.address,
+    scope_exercised: action.scope_exercised,
+    content_hash: action.content.hash,
+    content_length: action.content.length,
+    content_mime: action.content.mime,
+    signed_at: action.signed_at,
+    signature: action.sig.value,
+    id: action.id
+  };
+  const r = await f(`${baseUrl}/api/actions`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json",
+      Authorization: `Bearer ${client.apiToken}`
+    },
+    body: JSON.stringify(body)
+  });
+  if (!r.ok) {
+    let reason = `http_${r.status}`;
+    try {
+      const j2 = await r.json();
+      if (j2.reason) reason = j2.reason;
+    } catch {
+    }
+    throw new Error(`postActionToConsole failed: ${reason}`);
+  }
+  const j = await r.json();
+  return j.action;
+}
+async function invokeWithStampAndPost(input) {
+  const { result, action, call } = await invokeWithStamp(input);
+  let posted = null;
+  if (input.console) {
+    try {
+      posted = await postActionToConsole(action, input.console);
+    } catch (err) {
+      console.error("[oc-agent-openai] postActionToConsole failed:", err);
+    }
+  }
+  return { result, action, call, posted };
+}
+
+export { canonicalizeFunctionCall, functionCallActionId, functionCallHash, invokeWithStamp, invokeWithStampAndPost, parseFunctionCall, postActionToConsole, stampFunctionCall };
+//# sourceMappingURL=index.mjs.map
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"names":["j"],"mappings":"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","file":"index.mjs","sourcesContent":["// @orangecheck/agent-openai — wrap OpenAI function calls in OC Agent\n// action envelopes.\n//\n// Covers both surfaces:\n//   - Responses API:        response.output → tool_call items with\n//                            { type: 'function_call', name, arguments, call_id }\n//                            (`arguments` is a JSON string)\n//   - Chat Completions:     message.tool_calls[i] = { id, function: { name, arguments } }\n//                            (`arguments` is also a JSON string)\n//\n// Both shapes normalize through `parseFunctionCall()` to the canonical\n// {id, name, arguments} form before hashing.\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// Shape normalization\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface OpenAiFunctionCall {\n    /** OpenAI's `id` for this call (Chat Completions: `tool_call.id`; Responses: `call_id`). */\n    id: string;\n    /** The function name. */\n    name: string;\n    /** The (already-parsed) function arguments. */\n    arguments: Record<string, unknown>;\n}\n\n/**\n * Normalize either a Chat Completions `tool_call` or a Responses\n * `function_call` item into our canonical {id, name, arguments} shape.\n *\n * Accepts:\n *   - { id, function: { name, arguments } }                      (Chat Completions)\n *   - { call_id, name, arguments }                               (Responses, function_call)\n *   - { id, name, arguments }                                    (already normalized)\n *\n * `arguments` may be either a JSON string (OpenAI's wire shape) or an\n * already-parsed object (your post-processing). Both work.\n */\nexport function parseFunctionCall(raw: unknown): OpenAiFunctionCall {\n    if (raw == null || typeof raw !== 'object') {\n        throw new TypeError('parseFunctionCall: input is not an object');\n    }\n    const r = raw as Record<string, unknown>;\n\n    // Chat Completions shape\n    if (r.function && typeof r.function === 'object') {\n        const f = r.function as Record<string, unknown>;\n        return {\n            id: String(r.id ?? ''),\n            name: String(f.name ?? ''),\n            arguments: parseArgs(f.arguments),\n        };\n    }\n\n    // Responses API or already-normalized\n    return {\n        id: String(r.id ?? r.call_id ?? ''),\n        name: String(r.name ?? ''),\n        arguments: parseArgs(r.arguments),\n    };\n}\n\nfunction parseArgs(args: unknown): Record<string, unknown> {\n    if (args == null) return {};\n    if (typeof args === 'object') return args as Record<string, unknown>;\n    if (typeof args === 'string') {\n        try {\n            const v = JSON.parse(args);\n            if (v && typeof v === 'object') return v as Record<string, unknown>;\n            return { _raw: args };\n        } catch {\n            return { _raw: args };\n        }\n    }\n    return { _raw: String(args) };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Canonicalization\n// ─────────────────────────────────────────────────────────────────────────────\n\n/**\n * Produce the canonical bytes for an OpenAI function call. The bytes are\n * what the agent-action envelope's `content.hash` is a SHA-256 of.\n *\n * Shape (RFC 8785 canonical JSON, then trailing LF):\n *   {\n *     \"arguments\": <canonical JSON of arguments>,\n *     \"id\":        <call id>,\n *     \"name\":      <function name>\n *   }\n */\nexport function canonicalizeFunctionCall(c: OpenAiFunctionCall): Uint8Array {\n    const canon = {\n        arguments: c.arguments,\n        id: c.id,\n        name: c.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 functionCallHash(c: OpenAiFunctionCall): string {\n    return 'sha256:' + hexEncode(sha256(canonicalizeFunctionCall(c)));\n}\n\nexport function functionCallActionId(\n    agentAddress: string,\n    signedAt: string,\n    delegationId: string,\n    scopeExercised: string,\n    c: OpenAiFunctionCall\n): string {\n    return computeActionId({\n        address: agentAddress,\n        content_hash: functionCallHash(c),\n        content_length: canonicalizeFunctionCall(c).byteLength,\n        content_mime: 'application/vnd.oc-agent.openai-function-call+json',\n        signed_at: signedAt,\n        delegation_id: delegationId,\n        scope_exercised: scopeExercised,\n    });\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Stamping + invocation\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface StampFunctionCallInput {\n    agent: SignerRef;\n    delegation: DelegationEnvelope;\n    /** Either a normalized `OpenAiFunctionCall` or a raw OpenAI tool_call / function_call object. */\n    call: OpenAiFunctionCall | unknown;\n    /** Defaults to `openai:function(name=<name>)` — the tightest admissible sub-scope. */\n    scopeExercised?: string;\n    signedAt?: Date;\n}\n\nexport async function stampFunctionCall(\n    input: StampFunctionCallInput\n): Promise<ActionEnvelope> {\n    const fc =\n        typeof input.call === 'object' &&\n        input.call !== null &&\n        'arguments' in (input.call as Record<string, unknown>) &&\n        typeof (input.call as Record<string, unknown>).arguments !== 'string'\n            ? (input.call as OpenAiFunctionCall)\n            : parseFunctionCall(input.call);\n\n    const scopeExercised =\n        input.scopeExercised ?? `openai:function(name=${fc.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            `stampFunctionCall: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`\n        );\n    }\n\n    const bytes = canonicalizeFunctionCall(fc);\n    return signAsAgent({\n        agent: input.agent,\n        delegation: input.delegation as never,\n        content: { hash: functionCallHash(fc), length: bytes.byteLength },\n        mime: 'application/vnd.oc-agent.openai-function-call+json',\n        scopeExercised,\n        signedAt: input.signedAt,\n    });\n}\n\nexport interface InvokeWithStampInput<T> extends StampFunctionCallInput {\n    /** Your handler. Receives the normalized OpenAiFunctionCall. */\n    execute: (call: OpenAiFunctionCall) => Promise<T>;\n}\n\nexport interface InvokeWithStampResult<T> {\n    result: T;\n    action: ActionEnvelope;\n    call: OpenAiFunctionCall;\n}\n\nexport async function invokeWithStamp<T>(\n    input: InvokeWithStampInput<T>\n): Promise<InvokeWithStampResult<T>> {\n    const action = await stampFunctionCall(input);\n    const fc = parseFunctionCall(input.call);\n    const result = await input.execute(fc);\n    return { result, action, call: fc };\n}\n\n// ─────────────────────────────────────────────────────────────────────────────\n// Console integration: POST stamped actions to console.ochk.io/api/actions\n// ─────────────────────────────────────────────────────────────────────────────\n\nexport interface ConsoleClient {\n    /** Defaults to https://console.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. */\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 console.ochk.io/api/actions. The\n * console re-derives the action id, validates agent-must-match-\n * delegation, persists, fans out to Nostr (kind 30084), submits to\n * OC Stamp, and triggers any subscribed webhooks. Throws on non-2xx\n * with the server's reason string.\n */\nexport async function postActionToConsole(\n    action: ActionEnvelope,\n    client: ConsoleClient\n): Promise<PostActionResult> {\n    const baseUrl = client.baseUrl ?? 'https://console.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\n        }\n        throw new Error(`postActionToConsole 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    /** Console credentials. If absent, behaves like invokeWithStamp. */\n    console?: ConsoleClient;\n}\n\nexport interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {\n    /** Set when console is configured AND the POST succeeded. */\n    posted: PostActionResult | null;\n}\n\nexport async function invokeWithStampAndPost<T>(\n    input: InvokeWithStampAndPostInput<T>\n): Promise<InvokeWithStampAndPostResult<T>> {\n    const { result, action, call } = await invokeWithStamp(input);\n    let posted: PostActionResult | null = null;\n    if (input.console) {\n        try {\n            posted = await postActionToConsole(action, input.console);\n        } catch (err) {\n            // eslint-disable-next-line no-console\n            console.error('[oc-agent-openai] postActionToConsole failed:', err);\n        }\n    }\n    return { result, action, call, posted };\n}\n"]}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@orangecheck/agent-openai",
+  "version": "0.1.0",
+  "description": "Wrap OpenAI function-calling (Responses API + Chat Completions tool path) with OC Agent scope enforcement and emit a signed agent-action envelope per function invocation.",
+  "keywords": [
+    "bitcoin",
+    "agent",
+    "authority",
+    "openai",
+    "responses",
+    "function-calling",
+    "tool-use",
+    "bip322",
+    "oc-agent",
+    "orangecheck"
+  ],
+  "author": "OrangeCheck",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/orangecheck/oc-packages.git",
+    "directory": "agent-openai"
+  },
+  "homepage": "https://github.com/orangecheck/oc-agent-protocol",
+  "bugs": {
+    "url": "https://github.com/orangecheck/oc-agent-protocol/issues"
+  },
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.5.0",
+    "@orangecheck/agent-core": "^0.3.0",
+    "@orangecheck/agent-signer": "^0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^3.2.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,91 @@
+import { describe, expect, it } from 'vitest';
+
+import {
+    canonicalizeFunctionCall,
+    functionCallHash,
+    parseFunctionCall,
+} from './index.js';
+
+describe('parseFunctionCall', () => {
+    it('parses a Chat Completions tool_call', () => {
+        const c = parseFunctionCall({
+            id: 'call_abc',
+            type: 'function',
+            function: {
+                name: 'invoice.create',
+                arguments: '{"customer":"acme","amount":14.2}',
+            },
+        });
+        expect(c.id).toBe('call_abc');
+        expect(c.name).toBe('invoice.create');
+        expect(c.arguments).toEqual({ customer: 'acme', amount: 14.2 });
+    });
+
+    it('parses a Responses function_call item', () => {
+        const c = parseFunctionCall({
+            type: 'function_call',
+            call_id: 'call_xyz',
+            name: 'invoice.refund',
+            arguments: '{"order":"o_99","amount":22.5}',
+        });
+        expect(c.id).toBe('call_xyz');
+        expect(c.name).toBe('invoice.refund');
+        expect(c.arguments).toEqual({ order: 'o_99', amount: 22.5 });
+    });
+
+    it('handles already-parsed arguments', () => {
+        const c = parseFunctionCall({
+            id: 'call_abc',
+            name: 'invoice.create',
+            arguments: { customer: 'acme', amount: 14.2 },
+        });
+        expect(c.arguments).toEqual({ customer: 'acme', amount: 14.2 });
+    });
+
+    it('handles malformed argument strings without throwing', () => {
+        const c = parseFunctionCall({
+            id: 'call_abc',
+            name: 'invoice.create',
+            arguments: 'not-json',
+        });
+        expect(c.arguments).toEqual({ _raw: 'not-json' });
+    });
+});
+
+describe('canonicalizeFunctionCall', () => {
+    it('produces byte-identical output across Chat Completions vs Responses shapes', () => {
+        const cc = parseFunctionCall({
+            id: 'call_abc',
+            type: 'function',
+            function: {
+                name: 'invoice.create',
+                arguments: '{"customer":"acme","amount":14.2}',
+            },
+        });
+        const rsp = parseFunctionCall({
+            type: 'function_call',
+            call_id: 'call_abc',
+            name: 'invoice.create',
+            arguments: '{"amount":14.2,"customer":"acme"}',
+        });
+        expect(canonicalizeFunctionCall(cc)).toEqual(canonicalizeFunctionCall(rsp));
+    });
+
+    it('differs when arguments differ', () => {
+        const a = functionCallHash(
+            parseFunctionCall({
+                id: 'c',
+                name: 'x',
+                arguments: '{"a":1}',
+            })
+        );
+        const b = functionCallHash(
+            parseFunctionCall({
+                id: 'c',
+                name: 'x',
+                arguments: '{"a":2}',
+            })
+        );
+        expect(a).not.toBe(b);
+    });
+});

package/src/index.ts

@@ -0,0 +1,299 @@
+// @orangecheck/agent-openai — wrap OpenAI function calls in OC Agent
+// action envelopes.
+//
+// Covers both surfaces:
+//   - Responses API:        response.output → tool_call items with
+//                            { type: 'function_call', name, arguments, call_id }
+//                            (`arguments` is a JSON string)
+//   - Chat Completions:     message.tool_calls[i] = { id, function: { name, arguments } }
+//                            (`arguments` is also a JSON string)
+//
+// Both shapes normalize through `parseFunctionCall()` to the canonical
+// {id, name, arguments} form before hashing.
+
+import { sha256 } from '@noble/hashes/sha256';
+import {
+    canonicalize,
+    computeActionId,
+    hexEncode,
+    isSubScope,
+    parseScope,
+    type DelegationEnvelope,
+} from '@orangecheck/agent-core';
+import {
+    signAsAgent,
+    type ActionEnvelope,
+    type SignerRef,
+} from '@orangecheck/agent-signer';
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Shape normalization
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface OpenAiFunctionCall {
+    /** OpenAI's `id` for this call (Chat Completions: `tool_call.id`; Responses: `call_id`). */
+    id: string;
+    /** The function name. */
+    name: string;
+    /** The (already-parsed) function arguments. */
+    arguments: Record<string, unknown>;
+}
+
+/**
+ * Normalize either a Chat Completions `tool_call` or a Responses
+ * `function_call` item into our canonical {id, name, arguments} shape.
+ *
+ * Accepts:
+ *   - { id, function: { name, arguments } }                      (Chat Completions)
+ *   - { call_id, name, arguments }                               (Responses, function_call)
+ *   - { id, name, arguments }                                    (already normalized)
+ *
+ * `arguments` may be either a JSON string (OpenAI's wire shape) or an
+ * already-parsed object (your post-processing). Both work.
+ */
+export function parseFunctionCall(raw: unknown): OpenAiFunctionCall {
+    if (raw == null || typeof raw !== 'object') {
+        throw new TypeError('parseFunctionCall: input is not an object');
+    }
+    const r = raw as Record<string, unknown>;
+
+    // Chat Completions shape
+    if (r.function && typeof r.function === 'object') {
+        const f = r.function as Record<string, unknown>;
+        return {
+            id: String(r.id ?? ''),
+            name: String(f.name ?? ''),
+            arguments: parseArgs(f.arguments),
+        };
+    }
+
+    // Responses API or already-normalized
+    return {
+        id: String(r.id ?? r.call_id ?? ''),
+        name: String(r.name ?? ''),
+        arguments: parseArgs(r.arguments),
+    };
+}
+
+function parseArgs(args: unknown): Record<string, unknown> {
+    if (args == null) return {};
+    if (typeof args === 'object') return args as Record<string, unknown>;
+    if (typeof args === 'string') {
+        try {
+            const v = JSON.parse(args);
+            if (v && typeof v === 'object') return v as Record<string, unknown>;
+            return { _raw: args };
+        } catch {
+            return { _raw: args };
+        }
+    }
+    return { _raw: String(args) };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Canonicalization
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Produce the canonical bytes for an OpenAI function call. The bytes are
+ * what the agent-action envelope's `content.hash` is a SHA-256 of.
+ *
+ * Shape (RFC 8785 canonical JSON, then trailing LF):
+ *   {
+ *     "arguments": <canonical JSON of arguments>,
+ *     "id":        <call id>,
+ *     "name":      <function name>
+ *   }
+ */
+export function canonicalizeFunctionCall(c: OpenAiFunctionCall): Uint8Array {
+    const canon = {
+        arguments: c.arguments,
+        id: c.id,
+        name: c.name,
+    };
+    const str = canonicalize(canon as unknown as Parameters<typeof canonicalize>[0]);
+    return new TextEncoder().encode(str + '\n');
+}
+
+export function functionCallHash(c: OpenAiFunctionCall): string {
+    return 'sha256:' + hexEncode(sha256(canonicalizeFunctionCall(c)));
+}
+
+export function functionCallActionId(
+    agentAddress: string,
+    signedAt: string,
+    delegationId: string,
+    scopeExercised: string,
+    c: OpenAiFunctionCall
+): string {
+    return computeActionId({
+        address: agentAddress,
+        content_hash: functionCallHash(c),
+        content_length: canonicalizeFunctionCall(c).byteLength,
+        content_mime: 'application/vnd.oc-agent.openai-function-call+json',
+        signed_at: signedAt,
+        delegation_id: delegationId,
+        scope_exercised: scopeExercised,
+    });
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Stamping + invocation
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface StampFunctionCallInput {
+    agent: SignerRef;
+    delegation: DelegationEnvelope;
+    /** Either a normalized `OpenAiFunctionCall` or a raw OpenAI tool_call / function_call object. */
+    call: OpenAiFunctionCall | unknown;
+    /** Defaults to `openai:function(name=<name>)` — the tightest admissible sub-scope. */
+    scopeExercised?: string;
+    signedAt?: Date;
+}
+
+export async function stampFunctionCall(
+    input: StampFunctionCallInput
+): Promise<ActionEnvelope> {
+    const fc =
+        typeof input.call === 'object' &&
+        input.call !== null &&
+        'arguments' in (input.call as Record<string, unknown>) &&
+        typeof (input.call as Record<string, unknown>).arguments !== 'string'
+            ? (input.call as OpenAiFunctionCall)
+            : parseFunctionCall(input.call);
+
+    const scopeExercised =
+        input.scopeExercised ?? `openai:function(name=${fc.name})`;
+
+    const granted = (input.delegation.scopes ?? []).map(parseScope);
+    const exercisedParsed = parseScope(scopeExercised);
+    if (!granted.some((g) => isSubScope(exercisedParsed, g))) {
+        throw new Error(
+            `stampFunctionCall: scope_exercised (${scopeExercised}) is not a sub-scope of any granted scope`
+        );
+    }
+
+    const bytes = canonicalizeFunctionCall(fc);
+    return signAsAgent({
+        agent: input.agent,
+        delegation: input.delegation as never,
+        content: { hash: functionCallHash(fc), length: bytes.byteLength },
+        mime: 'application/vnd.oc-agent.openai-function-call+json',
+        scopeExercised,
+        signedAt: input.signedAt,
+    });
+}
+
+export interface InvokeWithStampInput<T> extends StampFunctionCallInput {
+    /** Your handler. Receives the normalized OpenAiFunctionCall. */
+    execute: (call: OpenAiFunctionCall) => Promise<T>;
+}
+
+export interface InvokeWithStampResult<T> {
+    result: T;
+    action: ActionEnvelope;
+    call: OpenAiFunctionCall;
+}
+
+export async function invokeWithStamp<T>(
+    input: InvokeWithStampInput<T>
+): Promise<InvokeWithStampResult<T>> {
+    const action = await stampFunctionCall(input);
+    const fc = parseFunctionCall(input.call);
+    const result = await input.execute(fc);
+    return { result, action, call: fc };
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Console integration: POST stamped actions to console.ochk.io/api/actions
+// ─────────────────────────────────────────────────────────────────────────────
+
+export interface ConsoleClient {
+    /** Defaults to https://console.ochk.io. */
+    baseUrl?: string;
+    /** Bearer token from /settings § 03 (`ock_<hex>`). */
+    apiToken: string;
+    /** Project the action belongs to (proj_*). */
+    projectId: string;
+    /** Optional fetch override for runtimes that need it. */
+    fetch?: typeof fetch;
+}
+
+export interface PostActionResult {
+    id: string;
+    project_id: string;
+    delegation_id: string;
+}
+
+/**
+ * POST a stamped action envelope to console.ochk.io/api/actions. The
+ * console re-derives the action id, validates agent-must-match-
+ * delegation, persists, fans out to Nostr (kind 30084), submits to
+ * OC Stamp, and triggers any subscribed webhooks. Throws on non-2xx
+ * with the server's reason string.
+ */
+export async function postActionToConsole(
+    action: ActionEnvelope,
+    client: ConsoleClient
+): Promise<PostActionResult> {
+    const baseUrl = client.baseUrl ?? 'https://console.ochk.io';
+    const f = client.fetch ?? fetch;
+    const body = {
+        project_id: client.projectId,
+        delegation_id: action.delegation_id,
+        agent_address: action.signer.address,
+        scope_exercised: action.scope_exercised,
+        content_hash: action.content.hash,
+        content_length: action.content.length,
+        content_mime: action.content.mime,
+        signed_at: action.signed_at,
+        signature: action.sig.value,
+        id: action.id,
+    };
+    const r = await f(`${baseUrl}/api/actions`, {
+        method: 'POST',
+        headers: {
+            'Content-Type': 'application/json',
+            Authorization: `Bearer ${client.apiToken}`,
+        },
+        body: JSON.stringify(body),
+    });
+    if (!r.ok) {
+        let reason = `http_${r.status}`;
+        try {
+            const j = (await r.json()) as { reason?: string };
+            if (j.reason) reason = j.reason;
+        } catch {
+            // body wasn't json
+        }
+        throw new Error(`postActionToConsole failed: ${reason}`);
+    }
+    const j = (await r.json()) as { ok: true; action: PostActionResult };
+    return j.action;
+}
+
+export interface InvokeWithStampAndPostInput<T> extends InvokeWithStampInput<T> {
+    /** Console credentials. If absent, behaves like invokeWithStamp. */
+    console?: ConsoleClient;
+}
+
+export interface InvokeWithStampAndPostResult<T> extends InvokeWithStampResult<T> {
+    /** Set when console is configured AND the POST succeeded. */
+    posted: PostActionResult | null;
+}
+
+export async function invokeWithStampAndPost<T>(
+    input: InvokeWithStampAndPostInput<T>
+): Promise<InvokeWithStampAndPostResult<T>> {
+    const { result, action, call } = await invokeWithStamp(input);
+    let posted: PostActionResult | null = null;
+    if (input.console) {
+        try {
+            posted = await postActionToConsole(action, input.console);
+        } catch (err) {
+            // eslint-disable-next-line no-console
+            console.error('[oc-agent-openai] postActionToConsole failed:', err);
+        }
+    }
+    return { result, action, call, posted };
+}