@ancha-labs/tools 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @ancha-labs/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.
+Test your agent against the production run that went wrong. Wrap your agent's own tools once: in production nothing
+changes, and in an [Ancha](https://ancha.io) test made from a production trace each call answers as production did.
+
+```sh
+npm install @ancha-labs/tools
+```
+
+```ts
+import { wrapTools, entry } from '@ancha-labs/tools';
+
+const tools = wrapTools({ lookup_order, refund_order }); // functions, or the AI SDK's tool() objects
+
+await entry(async input => runAgent(input.task, tools)); // the command an Ancha test runs
+```
+
+- **Outside a test** (no `ANCHA_TOOLS_URL`), a wrapped tool is your function: same arguments, same result, no network.
+- **In a test**, `ancha run` answers each call: production's answer (`replayed`), a model's answer in production's shape
+  for a read production never made (`simulated`), or an error for a write production never made (`failed`).
+- **A tool the trace recorded but your agent does not wrap** stops the test before your agent runs, so a test never
+  reaches production.
+
+Docs: [Tool wrappers](https://docs.ancha.io/reference/tool-wrappers) and
+[From a production trace to a failing test](https://docs.ancha.io/guides/rebuild-from-traces). MIT licensed.

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "@ancha-labs/tools",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Test your agent's own tools against production's recorded calls: wrap them once, and in an Ancha test each call answers as production did. Nothing changes in production.",
+  "type": "module",
+  "engines": {
+    "node": ">=18"
+  },
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    }
+  },
+  "files": [
+    "src"
+  ],
+  "license": "MIT",
+  "homepage": "https://docs.ancha.io",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.d.ts

@@ -0,0 +1,25 @@
+/** Ancha answered a tool call with the error production's tool raised, or with no recorded answer. */
+export declare class AnchaToolError extends Error {
+  /** Where the answer came from: `replayed` (production's error) or `failed` (no recorded answer). */
+  source?: 'replayed' | 'twin' | 'simulated' | 'failed';
+}
+
+/** What a test hands the agent: the invocation's task, the conversation so far, and the user it served. */
+export interface AgentInput {
+  task: string;
+  messages?: { role: 'user' | 'assistant' | 'tool'; content: string | null; tool_calls?: { id?: string; name: string; arguments: unknown }[]; tool_call_id?: string }[];
+  user?: string;
+  [key: string]: unknown;
+}
+
+/** One function as a tool named `name`, the name the model sees and the trace records. */
+export declare function wrapTool<F extends (...args: any[]) => any>(name: string, fn: F): (...args: Parameters<F>) => Promise<Awaited<ReturnType<F>>>;
+
+/** Every tool in `tools`, wrapped: functions, and tool objects with `execute` (the AI SDK's `tool()`). */
+export declare function wrapTools<T extends Record<string, unknown> | unknown[]>(tools: T, options?: { names?: Record<string, string> }): T;
+
+/** One call to a tool as Ancha answers it in a test. */
+export declare function callTool(name: string, args: unknown): Promise<unknown>;
+
+/** The command a test runs: checks every tool is wrapped, calls `run` with the invocation's input, returns its answer to Ancha. */
+export declare function entry<T>(run: (input: AgentInput) => T | Promise<T>): Promise<T>;

package/src/index.mjs

@@ -0,0 +1,111 @@
+// @ancha-labs/tools: test an agent's own tools against production's recorded calls (TRACE_PLAN_V2 §3).
+//
+//   import { wrapTools, entry } from '@ancha-labs/tools';
+//   const tools = wrapTools({ lookupOrder, refundOrder });     // or AI SDK tools: wrapTools({ weather: tool({ … }) })
+//   entry(input => runAgent(input.messages, input.user));       // in the command ancha.yaml runs
+//
+// In production nothing changes: without ANCHA_TOOLS_URL every wrapped tool is the original function. In a test,
+// `ancha run` sets ANCHA_TOOLS_URL and ANCHA_TOOLS_TOKEN, and each call goes to Ancha, which answers as production did.
+
+/** Ancha answered a tool call with the error production's tool raised, or with no recorded answer. */
+export class AnchaToolError extends Error {
+  constructor(message, source) { super(message); this.name = 'AnchaToolError'; this.source = source; }
+}
+
+const wrapped = new Set();
+let registered = Promise.resolve();
+const service = () => (process.env.ANCHA_TOOLS_URL ? { url: process.env.ANCHA_TOOLS_URL.replace(/\/+$/, ''), token: process.env.ANCHA_TOOLS_TOKEN ?? '' } : undefined);
+
+async function post(url, token, body) {
+  const res = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', authorization: `Bearer ${token}` }, body: JSON.stringify(body) });
+  const answer = await res.json().catch(() => ({}));
+  return { status: res.status, body: answer };
+}
+
+/** Tells Ancha which tools this process wraps, so a test stops before the agent calls an unwrapped one for real. */
+function register(names) {
+  for (const name of names) wrapped.add(name);
+  const s = service();
+  if (!s) return;
+  const previous = registered;
+  registered = previous.then(() => post(`${s.url}/register`, s.token, { tools: names }), () => {}).then(() => {}, () => {});
+}
+
+/** Ancha's answer to one call: production's result, its error thrown as the tool would have, or `passthrough`. */
+async function ask(name, args) {
+  const s = service();
+  if (!s) throw new Error('callTool runs inside an Ancha test: ANCHA_TOOLS_URL is not set');
+  await registered;
+  const { status, body } = await post(`${s.url}/tools/${encodeURIComponent(name)}`, s.token, { args: args ?? {} });
+  if (status === 401) throw new Error('Ancha refused the tool call: ANCHA_TOOLS_TOKEN does not match this test');
+  if (body?.stop) { process.stderr.write(`ancha: ${body.error}\n`); process.exit(2); }
+  if (status >= 400) throw new Error(`Ancha's tool service answered ${status}${body?.error ? `: ${body.error}` : ''}`);
+  if (body.error !== undefined) throw new AnchaToolError(body.error, body.source);
+  return body;
+}
+
+/** One call to a tool, answered by Ancha: the recorded result, or the recorded error thrown as the tool would have. */
+export async function callTool(name, args) {
+  const answer = await ask(name, args);
+  if (answer.passthrough) throw new AnchaToolError(`production never made this call to ${name}; the tool itself runs against the ${answer.source} in a test`, answer.source);
+  return answer.result;
+}
+
+/** A call through Ancha, or, when production never made it and the tool is linked to a twin, the tool itself. */
+async function route(name, args, original) {
+  const answer = await ask(name, args);
+  return answer.passthrough ? original() : answer.result;
+}
+
+/** The arguments as the model sent them: a tool's one object argument, otherwise the list of arguments. */
+const argsOf = list => (list.length === 1 && list[0] !== null && typeof list[0] === 'object' && !Array.isArray(list[0]) ? list[0] : list.length === 0 ? {} : { args: list });
+
+/** One function as a tool named `name` (the name the model sees, as the trace records it). */
+export function wrapTool(name, fn) {
+  if (typeof fn !== 'function') throw new TypeError(`wrapTool(${JSON.stringify(name)}): expected a function`);
+  register([name]);
+  const tool = async function (...args) {
+    return service() ? route(name, argsOf(args), () => fn.apply(this, args)) : fn.apply(this, args);
+  };
+  Object.defineProperty(tool, 'name', { value: fn.name || name });
+  return tool;
+}
+
+/**
+ * Every tool in `tools`, wrapped: functions, and tool objects with an `execute` function (the AI SDK's `tool()`),
+ * whose `execute(input, options)` is called with the model's input. The keys are the names the model sees;
+ * `names` maps a key to another name when the trace knows the tool by one.
+ */
+export function wrapTools(tools, { names = {} } = {}) {
+  const out = Array.isArray(tools) ? [] : {};
+  const list = [];
+  for (const [key, value] of Object.entries(tools)) {
+    const toolName = names[key] ?? (Array.isArray(tools) ? value?.name || key : key);
+    if (typeof value === 'function') out[key] = wrapTool(toolName, value);
+    else if (value && typeof value.execute === 'function') {
+      const execute = value.execute;
+      out[key] = { ...value, execute: async (input, options) => (service() ? route(toolName, input, () => execute.call(value, input, options)) : execute.call(value, input, options)) };
+      list.push(toolName);
+    } else throw new TypeError(`wrapTools: ${key} is neither a function nor a tool with execute()`);
+  }
+  register(list);
+  return out;
+}
+
+/**
+ * The command a test runs: tells Ancha every wrapped tool (a test stops here if the trace holds one the agent does
+ * not wrap), calls `run` with the invocation's input (ANCHA_INPUT_JSON: the conversation so far and the user, plus
+ * `task`), and hands the answer back to Ancha. Outside a test it runs `run` with ANCHA_TASK, or with nothing.
+ */
+export async function entry(run) {
+  const s = service();
+  if (s) {
+    await registered;
+    const { status, body } = await post(`${s.url}/register`, s.token, { tools: [...wrapped], complete: true });
+    if (status === 409) { process.stderr.write(`ancha: ${body.error}\n`); process.exit(2); }
+  }
+  const input = { task: process.env.ANCHA_TASK ?? '', ...JSON.parse(process.env.ANCHA_INPUT_JSON || '{}') };
+  const output = await run(input);
+  if (process.env.ANCHA_DONE_URL) await post(process.env.ANCHA_DONE_URL, process.env.ANCHA_TRIAL_TOKEN ?? '', { output: output ?? null });
+  return output;
+}