@atlasauth/pca-anthropic 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @atlasauth/pca-anthropic
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Anthropic (Claude) adapter for Proof-Carrying Authority: turn a tool_use block into a PCActn and build the tool_result with the proof attached.
+
+## Install
+
+```sh
+npm i @atlasauth/pca-anthropic
+# peer dependency, install alongside:
+npm i @anthropic-ai/sdk
+```
+
+`@anthropic-ai/sdk` is an optional peer dependency.
+
+## Usage
+
+```ts
+import { handleToolUse, extractToolUses } from '@atlasauth/pca-anthropic';
+
+// For each tool_use block in the assistant message:
+for (const block of extractToolUses(message.content)) {
+  const toolResult = await handleToolUse(
+    agent,                                 // core @atlasauth/pca Agent
+    block,                                 // { type: 'tool_use', id, name, input }
+    ({ name, input }) =>                   // map tool → catalog { verb, resource }; null declines
+      name === 'refund' ? { verb: 'stripe.refund', resource: `ch_${input.chargeId}` } : null,
+    {
+      refund: async (input, pca) => {      // pca carries the signed proof to forward downstream
+        return doRefund(input);
+      },
+    },
+  );
+  // → { type: 'tool_result', tool_use_id, content } (is_error:true on a declined/failed tool)
+}
+```
+
+`handleToolUse` builds a PCActn and attaches the proof; it does not authorize on its own — the resource server's verifier decides.
+
+Part of Proof-Carrying Authority — see `@atlasauth/pca`.

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Anthropic (Claude) adapter for Proof-Carrying Authority.
+ *
+ * Claude's tool use is a conversation: an assistant message carries content blocks, and a
+ * `tool_use` block (`{ type, id, name, input }`) asks your app to run a tool. Your app runs it and
+ * replies with a user message containing a matching `tool_result` block (`{ tool_use_id, content }`).
+ * This adapter sits in that gap: it turns a `tool_use` block into a PCActn (via the core
+ * `bridgeToolCall`), runs your handler with the proof in hand, and hands back the `tool_result` to
+ * append to the next message — including the error-shaped result Claude expects when a tool refuses.
+ *
+ * Structurally compatible with the `@anthropic-ai/sdk` package (declared as an OPTIONAL peer
+ * dependency). We model only the block shapes we touch, so this works across SDK minor versions
+ * without importing its runtime — nothing here requires the SDK to be installed.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's
+ * verifier decides. A handler that forgets to forward the proof just means the downstream action
+ * lacks a valid PCActn and fails server-side.
+ */
+import { type Agent, type PcaCall, pcaHeaders } from '@atlasauth/pca';
+/** A Claude `tool_use` content block (what the model emits to call a tool). */
+export interface ToolUseBlock {
+    type: 'tool_use';
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+/** A Claude `tool_result` content block (what your app replies with). */
+export interface ToolResultBlock {
+    type: 'tool_result';
+    tool_use_id: string;
+    content: string;
+    is_error?: boolean;
+}
+/** How a Claude tool name + input maps onto a PCA (verb, resource). Return null to decline the tool. */
+export type ToolMapping = (block: {
+    name: string;
+    input: Record<string, unknown>;
+}) => {
+    verb: string;
+    resource: string;
+} | null;
+/** Your tool implementation: gets the model's input and the PCActn so it can carry the proof downstream. */
+export type ToolHandler = (input: Record<string, unknown>, pca: import('@atlasauth/pca').PcaCall) => Promise<unknown> | unknown;
+/**
+ * Handle one `tool_use` block: build its PCActn, run the mapped handler, and return the `tool_result`.
+ *
+ * If the mapping declines the tool (returns null), we never run the handler — we return a
+ * `tool_result` with `is_error: true` so Claude sees the refusal. If the handler throws, we likewise
+ * return an error-shaped `tool_result`. On success, `content` is `JSON.stringify(result)`, falling
+ * back to `{ pca: <encoded> }` when the handler returns nothing.
+ */
+export declare function handleToolUse(agent: Agent, block: ToolUseBlock, map: ToolMapping, handlers: Record<string, ToolHandler>, opts?: {
+    aud?: string;
+    counter?: number;
+    now?: number;
+}): Promise<ToolResultBlock>;
+/** Handle many `tool_use` blocks (e.g. all of them from one assistant turn), preserving order. */
+export declare function handleToolUses(agent: Agent, blocks: ToolUseBlock[], map: ToolMapping, handlers: Record<string, ToolHandler>, opts?: {
+    aud?: string;
+    counter?: number;
+    now?: number;
+}): Promise<ToolResultBlock[]>;
+/** Pull the `tool_use` blocks out of an assistant message's `content` array (ignoring text/other blocks). */
+export declare function extractToolUses(content: Array<{
+    type: string;
+    [k: string]: unknown;
+}>): ToolUseBlock[];
+export { pcaHeaders, type PcaCall };

package/dist/index.js

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * Anthropic (Claude) adapter for Proof-Carrying Authority.
+ *
+ * Claude's tool use is a conversation: an assistant message carries content blocks, and a
+ * `tool_use` block (`{ type, id, name, input }`) asks your app to run a tool. Your app runs it and
+ * replies with a user message containing a matching `tool_result` block (`{ tool_use_id, content }`).
+ * This adapter sits in that gap: it turns a `tool_use` block into a PCActn (via the core
+ * `bridgeToolCall`), runs your handler with the proof in hand, and hands back the `tool_result` to
+ * append to the next message — including the error-shaped result Claude expects when a tool refuses.
+ *
+ * Structurally compatible with the `@anthropic-ai/sdk` package (declared as an OPTIONAL peer
+ * dependency). We model only the block shapes we touch, so this works across SDK minor versions
+ * without importing its runtime — nothing here requires the SDK to be installed.
+ *
+ * HONEST: this does not authorize — it attaches a proof-carrying action; the resource server's
+ * verifier decides. A handler that forgets to forward the proof just means the downstream action
+ * lacks a valid PCActn and fails server-side.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pcaHeaders = void 0;
+exports.handleToolUse = handleToolUse;
+exports.handleToolUses = handleToolUses;
+exports.extractToolUses = extractToolUses;
+const pca_1 = require("@atlasauth/pca");
+Object.defineProperty(exports, "pcaHeaders", { enumerable: true, get: function () { return pca_1.pcaHeaders; } });
+/**
+ * Handle one `tool_use` block: build its PCActn, run the mapped handler, and return the `tool_result`.
+ *
+ * If the mapping declines the tool (returns null), we never run the handler — we return a
+ * `tool_result` with `is_error: true` so Claude sees the refusal. If the handler throws, we likewise
+ * return an error-shaped `tool_result`. On success, `content` is `JSON.stringify(result)`, falling
+ * back to `{ pca: <encoded> }` when the handler returns nothing.
+ */
+async function handleToolUse(agent, block, map, handlers, opts) {
+    const pca = (0, pca_1.bridgeToolCall)(agent, { name: block.name, arguments: block.input }, (b) => map({ name: b.name, input: b.arguments }), opts);
+    if (!pca) {
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: `No proof-carrying authority is mapped for tool "${block.name}".`,
+            is_error: true,
+        };
+    }
+    const handler = handlers[block.name];
+    if (!handler) {
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: `No handler registered for tool "${block.name}".`,
+            is_error: true,
+        };
+    }
+    try {
+        const result = await handler(block.input, pca);
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: JSON.stringify(result ?? { pca: pca.encoded }),
+        };
+    }
+    catch (err) {
+        return {
+            type: 'tool_result',
+            tool_use_id: block.id,
+            content: err instanceof Error ? err.message : String(err),
+            is_error: true,
+        };
+    }
+}
+/** Handle many `tool_use` blocks (e.g. all of them from one assistant turn), preserving order. */
+async function handleToolUses(agent, blocks, map, handlers, opts) {
+    const uses = blocks.filter((b) => b.type === 'tool_use');
+    return Promise.all(uses.map((b) => handleToolUse(agent, b, map, handlers, opts)));
+}
+/** Pull the `tool_use` blocks out of an assistant message's `content` array (ignoring text/other blocks). */
+function extractToolUses(content) {
+    return content.filter((b) => b.type === 'tool_use');
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;GAiBG;;;AAwCH,sCA6CC;AAGD,wCASC;AAGD,0CAEC;AApGD,wCAAsF;AAsG7E,2FAtG0C,gBAAU,OAsG1C;AAxEnB;;;;;;;GAOG;AACI,KAAK,UAAU,aAAa,CACjC,KAAY,EACZ,KAAmB,EACnB,GAAgB,EAChB,QAAqC,EACrC,IAAuD;IAEvD,MAAM,GAAG,GAAG,IAAA,oBAAc,EACxB,KAAK,EACL,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,KAAK,EAAE,EAC5C,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC,SAAS,EAAE,CAAC,EAChD,IAAI,CACL,CAAC;IACF,IAAI,CAAC,GAAG,EAAE,CAAC;QACT,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,mDAAmD,KAAK,CAAC,IAAI,IAAI;YAC1E,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAG,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACrC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,mCAAmC,KAAK,CAAC,IAAI,IAAI;YAC1D,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;IACD,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC/C,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,IAAI,CAAC,SAAS,CAAC,MAAM,IAAI,EAAE,GAAG,EAAE,GAAG,CAAC,OAAO,EAAE,CAAC;SACxD,CAAC;IACJ,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,OAAO;YACL,IAAI,EAAE,aAAa;YACnB,WAAW,EAAE,KAAK,CAAC,EAAE;YACrB,OAAO,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;YACzD,QAAQ,EAAE,IAAI;SACf,CAAC;IACJ,CAAC;AACH,CAAC;AAED,kGAAkG;AAC3F,KAAK,UAAU,cAAc,CAClC,KAAY,EACZ,MAAsB,EACtB,GAAgB,EAChB,QAAqC,EACrC,IAAuD;IAEvD,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAqB,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;IAC5E,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,aAAa,CAAC,KAAK,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AACpF,CAAC;AAED,6GAA6G;AAC7G,SAAgB,eAAe,CAAC,OAAsD;IACpF,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAA+C,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,UAAU,CAAC,CAAC;AACnG,CAAC"}

package/package.json

@@ -1,6 +1,41 @@
 {
   "name": "@atlasauth/pca-anthropic",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Anthropic (Claude) adapter for Proof-Carrying Authority: turn a tool_use block into a PCActn and build the tool_result with the proof attached.",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dependencies": {
+    "@atlasauth/pca": "0.1.0"
+  },
+  "peerDependencies": {
+    "@anthropic-ai/sdk": "^0.30 || ^0.40 || ^0.50"
+  },
+  "peerDependenciesMeta": {
+    "@anthropic-ai/sdk": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.6.3",
+    "vitest": "^2.1.4"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
 }