@tuppence/agent-tools 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,65 @@
-# Temporary Holding Version
+# @tuppence/agent-tools
 
-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.
+Tuppence's tools for agent frameworks (the **OpenAI Agents SDK**, **LangChain** and the **Claude
+Agent SDK**), straight from Tuppence's MCP server.
+
+There is one definition of what an agent may do with Tuppence: the MCP server's. This package
+asks it for its tools, with your key, and hands your framework the same tools in its own shape,
+so they never drift, and a restricted key's agent is offered only what the key may do.
+
+```bash
+npm install @tuppence/agent-tools
+```
+
+Use a **restricted key** (`rk_…`) with only the scopes the agent needs, in `TUPPENCE_SECRET_KEY`
+(or pass `apiKey`).
+
+## OpenAI Agents SDK
+
+```ts
+import { Agent, run } from "@openai/agents";
+import { tuppenceTools } from "@tuppence/agent-tools/openai-agents";
+
+const { tools, close } = await tuppenceTools();
+const agent = new Agent({ name: "Billing", instructions: "Amounts are in pence.", tools });
+const result = await run(agent, "Make a £15 payment link for a research report");
+await close();
+```
+
+## LangChain
+
+```ts
+import { createAgent } from "langchain";
+import { tuppenceTools } from "@tuppence/agent-tools/langchain";
+
+const { tools, close } = await tuppenceTools();
+const agent = createAgent({ model: "openai:gpt-5", tools });
+await agent.invoke({ messages: [{ role: "user", content: "Make a £15 payment link" }] });
+await close();
+```
+
+## Claude Agent SDK
+
+It speaks MCP itself, so the pack is the connection:
+
+```ts
+import { query } from "@anthropic-ai/claude-agent-sdk";
+import { TUPPENCE_TOOLS, tuppenceMcpServer } from "@tuppence/agent-tools/claude-agent-sdk";
+
+for await (const message of query({
+  prompt: "Make a £15 payment link for a research report",
+  options: { mcpServers: { tuppence: tuppenceMcpServer() }, allowedTools: [TUPPENCE_TOOLS] },
+})) {
+  console.log(message);
+}
+```
+
+## Refusals are answers
+
+A tool the API refuses returns the error envelope (`code`, `message`, `param`) as its output,
+not an exception, so the agent can read "`amount` must be between 30 and 99999999" and try
+again. Money-moving tools need an `idempotency_key`: the same value when retrying, and the
+payment happens once.
+
+The examples in `examples/` run in Tuppence's CI against the real API, with a scripted model in
+place of the LLM.

package/dist/claude-agent-sdk.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Tuppence for the Claude Agent SDK — which speaks MCP itself, so the pack is the connection:
+ *
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   import { TUPPENCE_TOOLS, tuppenceMcpServer } from "@tuppence/agent-tools/claude-agent-sdk";
+ *
+ *   for await (const message of query({
+ *     prompt: "Make a £15 payment link for a research report",
+ *     options: {
+ *       mcpServers: { tuppence: tuppenceMcpServer() },   // TUPPENCE_SECRET_KEY
+ *       allowedTools: [TUPPENCE_TOOLS],                   // or name them: mcp__tuppence__create_payment_link
+ *     },
+ *   })) { … }
+ */
+import { type ConnectOptions } from "./index.js";
+/** Every Tuppence tool, as the Claude Agent SDK names them (`mcp__<server>__<tool>`). */
+export declare const TUPPENCE_TOOLS = "mcp__tuppence";
+/**
+ * The remote MCP server, as an `mcpServers` entry: streamable HTTP, your key as a bearer — and,
+ * with `account`, as one of your connected accounts (Tuppence Connect).
+ */
+export declare function tuppenceMcpServer(options?: ConnectOptions): {
+    type: "http";
+    url: string;
+    headers: Record<string, string>;
+};

package/dist/claude-agent-sdk.js

@@ -0,0 +1,25 @@
+/**
+ * Tuppence for the Claude Agent SDK — which speaks MCP itself, so the pack is the connection:
+ *
+ *   import { query } from "@anthropic-ai/claude-agent-sdk";
+ *   import { TUPPENCE_TOOLS, tuppenceMcpServer } from "@tuppence/agent-tools/claude-agent-sdk";
+ *
+ *   for await (const message of query({
+ *     prompt: "Make a £15 payment link for a research report",
+ *     options: {
+ *       mcpServers: { tuppence: tuppenceMcpServer() },   // TUPPENCE_SECRET_KEY
+ *       allowedTools: [TUPPENCE_TOOLS],                   // or name them: mcp__tuppence__create_payment_link
+ *     },
+ *   })) { … }
+ */
+import { resolveOptions } from "./index.js";
+/** Every Tuppence tool, as the Claude Agent SDK names them (`mcp__<server>__<tool>`). */
+export const TUPPENCE_TOOLS = "mcp__tuppence";
+/**
+ * The remote MCP server, as an `mcpServers` entry: streamable HTTP, your key as a bearer — and,
+ * with `account`, as one of your connected accounts (Tuppence Connect).
+ */
+export function tuppenceMcpServer(options = {}) {
+    const { apiUrl, headers } = resolveOptions(options);
+    return { type: "http", url: `${apiUrl}/mcp`, headers };
+}

package/dist/index.d.ts

@@ -0,0 +1,49 @@
+export declare const VERSION = "0.1.1";
+export type ConnectOptions = {
+    /** Default: `TUPPENCE_SECRET_KEY` (or `TUPPENCE_API_KEY`). Prefer a restricted key (`rk_…`). */
+    apiKey?: string;
+    /** Default: `TUPPENCE_API_URL`, else `https://api.tuppence.ai`. */
+    apiUrl?: string;
+    /**
+     * Tuppence Connect: every tool acts as this one of your connected accounts (`acct_…`) — the
+     * `Tuppence-Account` header on the connection, as `tuppence.as()` is in `@tuppence/node`. The
+     * platform's own Connect tools are then not offered. Without it, a tool call's own `account`
+     * argument acts as one account for that call.
+     */
+    account?: string;
+};
+export type ToolSpec = {
+    name: string;
+    title?: string;
+    description: string;
+    /** JSON Schema for the arguments — exactly what the MCP server declares. */
+    inputSchema: Record<string, unknown>;
+    annotations?: {
+        readOnlyHint?: boolean;
+        destructiveHint?: boolean;
+        idempotentHint?: boolean;
+    };
+};
+/** What a tool call returned: the API's JSON — on failure, its error envelope, with `isError`. */
+export type ToolResult = {
+    isError: boolean;
+    body: unknown;
+};
+export declare function resolveOptions(options?: ConnectOptions): {
+    apiKey: string;
+    apiUrl: string;
+    headers: Record<string, string>;
+};
+export declare class TuppenceToolkit {
+    private readonly client;
+    /** The tools this key may use, as the server describes them. */
+    readonly tools: ToolSpec[];
+    private constructor();
+    static connect(options?: ConnectOptions): Promise<TuppenceToolkit>;
+    /**
+     * Calls a tool. A refusal is an ANSWER, not an exception: the agent gets the error envelope
+     * (`code`, `message`, `param`) as the tool's output, and can correct itself and try again.
+     */
+    call(name: string, args: Record<string, unknown>): Promise<ToolResult>;
+    close(): Promise<void>;
+}

package/dist/index.js

@@ -0,0 +1,78 @@
+/**
+ * Tuppence's tools, for agent frameworks (plan 11-10).
+ *
+ * There is ONE definition of what an agent may do with Tuppence: the MCP server's (the API's
+ * `mcp.tools.ts` — the same services as the REST API, the same scopes, the same idempotency).
+ * This package does not copy it: it asks the server for its tools (`tools/list`), with your key,
+ * and hands each framework the same tools in its own shape. So the packs cannot drift from the
+ * server, or from each other — and a restricted key's agent is offered only what the key may do.
+ *
+ *   import { tuppenceTools } from "@tuppence/agent-tools/openai-agents";   // OpenAI Agents SDK
+ *   import { tuppenceTools } from "@tuppence/agent-tools/langchain";       // LangChain
+ *   import { tuppenceMcpServer } from "@tuppence/agent-tools/claude-agent-sdk";
+ */
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+export const VERSION = "0.1.1";
+export function resolveOptions(options = {}) {
+    const env = globalThis.process?.env ?? {};
+    const apiKey = options.apiKey ?? env.TUPPENCE_SECRET_KEY ?? env.TUPPENCE_API_KEY ?? "";
+    if (!/^(sk|rk)_(test|live)_/.test(apiKey)) {
+        throw new TypeError("A Tuppence secret or restricted key is needed (sk_… / rk_…): pass apiKey, or set TUPPENCE_SECRET_KEY.");
+    }
+    const apiUrl = (options.apiUrl ?? env.TUPPENCE_API_URL ?? "https://api.tuppence.ai").replace(/\/+$/, "");
+    const account = options.account?.trim();
+    if (account !== undefined && !/^acct_\w+$/.test(account)) {
+        throw new TypeError('`account` is a connected account id: "acct_…".');
+    }
+    return {
+        apiKey,
+        apiUrl,
+        headers: {
+            Authorization: `Bearer ${apiKey}`,
+            ...(account ? { "Tuppence-Account": account } : {}),
+        },
+    };
+}
+export class TuppenceToolkit {
+    client;
+    tools;
+    constructor(client, 
+    /** The tools this key may use, as the server describes them. */
+    tools) {
+        this.client = client;
+        this.tools = tools;
+    }
+    static async connect(options = {}) {
+        const { apiUrl, headers } = resolveOptions(options);
+        const client = new Client({ name: "tuppence-agent-tools", version: VERSION });
+        await client.connect(new StreamableHTTPClientTransport(new URL(`${apiUrl}/mcp`), { requestInit: { headers } }));
+        const { tools } = await client.listTools();
+        return new TuppenceToolkit(client, tools.map((t) => ({
+            name: t.name,
+            ...(t.title ? { title: t.title } : {}),
+            description: t.description ?? t.title ?? t.name,
+            inputSchema: t.inputSchema,
+            ...(t.annotations ? { annotations: t.annotations } : {}),
+        })));
+    }
+    /**
+     * Calls a tool. A refusal is an ANSWER, not an exception: the agent gets the error envelope
+     * (`code`, `message`, `param`) as the tool's output, and can correct itself and try again.
+     */
+    async call(name, args) {
+        const result = await this.client.callTool({ name, arguments: args });
+        const text = result.content?.find((c) => c.type === "text")?.text ?? "null";
+        let body = text;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // Not JSON: hand the text over as it is.
+        }
+        return { isError: result.isError === true, body };
+    }
+    close() {
+        return this.client.close();
+    }
+}

package/dist/langchain.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tuppence's tools for LangChain (JS).
+ *
+ *   import { createAgent } from "langchain";
+ *   import { tuppenceTools } from "@tuppence/agent-tools/langchain";
+ *
+ *   const { tools, close } = await tuppenceTools();          // TUPPENCE_SECRET_KEY
+ *   const agent = createAgent({ model: "openai:gpt-5", tools });
+ *   await agent.invoke({ messages: [{ role: "user", content: "Make a £15 link" }] });
+ *   await close();
+ */
+import { type StructuredToolInterface } from "@langchain/core/tools";
+import { type ConnectOptions, TuppenceToolkit } from "./index.js";
+export declare function tuppenceTools(options?: ConnectOptions): Promise<{
+    tools: StructuredToolInterface[];
+    toolkit: TuppenceToolkit;
+    close: () => Promise<void>;
+}>;

package/dist/langchain.js

@@ -0,0 +1,23 @@
+/**
+ * Tuppence's tools for LangChain (JS).
+ *
+ *   import { createAgent } from "langchain";
+ *   import { tuppenceTools } from "@tuppence/agent-tools/langchain";
+ *
+ *   const { tools, close } = await tuppenceTools();          // TUPPENCE_SECRET_KEY
+ *   const agent = createAgent({ model: "openai:gpt-5", tools });
+ *   await agent.invoke({ messages: [{ role: "user", content: "Make a £15 link" }] });
+ *   await close();
+ */
+import { tool } from "@langchain/core/tools";
+import { TuppenceToolkit } from "./index.js";
+export async function tuppenceTools(options = {}) {
+    const toolkit = await TuppenceToolkit.connect(options);
+    const tools = toolkit.tools.map((spec) => tool(async (args) => JSON.stringify((await toolkit.call(spec.name, args)).body), {
+        name: spec.name,
+        description: spec.description,
+        // LangChain takes the server's JSON Schema as is.
+        schema: spec.inputSchema,
+    }));
+    return { tools, toolkit, close: () => toolkit.close() };
+}

package/dist/openai-agents.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Tuppence's tools for the OpenAI Agents SDK.
+ *
+ *   import { Agent, run } from "@openai/agents";
+ *   import { tuppenceTools } from "@tuppence/agent-tools/openai-agents";
+ *
+ *   const { tools, close } = await tuppenceTools();          // TUPPENCE_SECRET_KEY
+ *   const agent = new Agent({ name: "Billing", instructions: "…", tools });
+ *   const result = await run(agent, "Make a £15 link for a research report");
+ *   await close();
+ */
+import { type FunctionTool } from "@openai/agents";
+import { type ConnectOptions, TuppenceToolkit } from "./index.js";
+export declare function tuppenceTools(options?: ConnectOptions): Promise<{
+    tools: FunctionTool[];
+    toolkit: TuppenceToolkit;
+    close: () => Promise<void>;
+}>;

package/dist/openai-agents.js

@@ -0,0 +1,31 @@
+/**
+ * Tuppence's tools for the OpenAI Agents SDK.
+ *
+ *   import { Agent, run } from "@openai/agents";
+ *   import { tuppenceTools } from "@tuppence/agent-tools/openai-agents";
+ *
+ *   const { tools, close } = await tuppenceTools();          // TUPPENCE_SECRET_KEY
+ *   const agent = new Agent({ name: "Billing", instructions: "…", tools });
+ *   const result = await run(agent, "Make a £15 link for a research report");
+ *   await close();
+ */
+import { tool } from "@openai/agents";
+import { TuppenceToolkit } from "./index.js";
+export async function tuppenceTools(options = {}) {
+    const toolkit = await TuppenceToolkit.connect(options);
+    const tools = toolkit.tools.map((spec) => tool({
+        name: spec.name,
+        description: spec.description,
+        // The server's JSON Schema, as is. Not "strict": some arguments are optional.
+        parameters: {
+            type: "object",
+            properties: {},
+            required: [],
+            additionalProperties: true,
+            ...spec.inputSchema,
+        },
+        strict: false,
+        execute: async (args) => JSON.stringify((await toolkit.call(spec.name, args)).body),
+    }));
+    return { tools, toolkit, close: () => toolkit.close() };
+}

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@tuppence/agent-tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.1",
+  "description": "Tuppence's tools for agent frameworks — the OpenAI Agents SDK, LangChain and the Claude Agent SDK — straight from its MCP server.",
+  "license": "MIT",
+  "homepage": "https://docs.tuppence.ai",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ZenningAI/tuppence.git",
+    "directory": "packages/agent-tools"
+  },
+  "bugs": "https://github.com/ZenningAI/tuppence/issues",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./openai-agents": {
+      "types": "./dist/openai-agents.d.ts",
+      "import": "./dist/openai-agents.js"
+    },
+    "./langchain": {
+      "types": "./dist/langchain.d.ts",
+      "import": "./dist/langchain.js"
+    },
+    "./claude-agent-sdk": {
+      "types": "./dist/claude-agent-sdk.d.ts",
+      "import": "./dist/claude-agent-sdk.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.32.1"
+  },
+  "peerDependencies": {
+    "@langchain/core": ">=1.2.0",
+    "@openai/agents": ">=0.18.0"
+  },
+  "peerDependenciesMeta": {
+    "@langchain/core": {
+      "optional": true
+    },
+    "@openai/agents": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@langchain/core": "1.2.12",
+    "@openai/agents": "0.18.0",
+    "@types/node": "^22.20.4",
+    "langchain": "1.5.11",
+    "typescript": "^5.9.3",
+    "zod": "^4.6.6"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.examples.json --noEmit"
+  }
 }