@staal/node 0.24.1 → 0.26.0

package/README.md

@@ -31,6 +31,49 @@ in `index.d.ts`: `done` with a `result`, `failed` with a `failure`, `stopped` (a
 action in doubt: `resolve` it, then `resume`), `invalid` with located check errors,
 or `error`. Pass `{ engine: 'native' }` to run pure code as machine code.
 
+**As a tool.** `staal.Tool.open` makes a program a tool an agent can call many times,
+with quotas across calls, `once` (the same operation called again is the same run),
+and recovery of a run a crash interrupted when the journal directory is next opened.
+Grants are fixed, or computed by your app for each call from a context it passes:
+
+```js
+const refund = await staal.Tool.open('refund.staal', {
+  name: 'refund_order',
+  description: 'Refund part of an order.',
+  grants: (customer) => ({ pay: { cap: 'payments.refund', uses: 1, each: { amount: LIMITS[customer.tier], currency: 'USD' } } }),
+  journals: 'runs',
+  quota: { window: '1h', money: { amount: '1000.00', currency: 'USD' } },
+});
+const r = await refund.call({ order: '4417', amount: { amount: '35.00', currency: 'USD' } }, { context: customer });
+// r.status: 'done', 'failed', 'stopped', 'in_progress' or 'not_run'; r.text, r.value, r.run
+```
+
+A grant is never an argument, and the model never sees one. An app serving several
+tenants or users from one directory also gives `scope: (customer) => customer.tenantId`,
+from its own records: `once` keys are then held per scope, and a run's status is given
+only in its scope (`refund.status(run, { context: customer })`). Inputs that only the
+app may give, such as the customer a call is for, are `appInputs: { customer: (customer)
+=> customer.id }`: they are left out of the schema a model sees, and a call whose
+arguments name one is refused. One process uses a
+journal directory at a time, so give each worker its own directory (whose quotas are
+then its own), or send the calls through one process.
+
+**Agent frameworks.** `functionTool` from `@staal/node/openai-agents` gives an OpenAI
+Agents SDK tool (grants from the run's `context`), and `structuredTool` from
+`@staal/node/langgraph` a LangChain tool for LangGraph (context from
+`config.configurable.staal_context`). `aiTools` from `@staal/node/vercel-ai` gives
+Vercel AI SDK tools, an ES module for `ai` 7 (Node 22 or newer), whose context is each
+tool's entry in `toolsContext`; a refusal reaches the model as an error with Staal's
+message. `mcpServer` from `@staal/node/claude-agent-sdk` serves tools to the Claude Agent SDK as
+an in-process MCP server, with the session's context bound when the server is made
+(one per query), and `allowedTools` gives their names for `allowedTools`. The
+frameworks are optional peer dependencies. Each is tested through the framework's own
+agent loop (@openai/agents 0.20.0, @langchain/langgraph 1.5.1, ai 7.0.145,
+@anthropic-ai/claude-agent-sdk 0.3.304, whose loop runs in the CLI it ships, against a
+local stand-in for the Messages API), and once a week against each framework's latest
+release; the examples are in
+[examples/frameworks](https://github.com/laurells/staal/tree/main/examples/frameworks).
+
 **Platforms.** Node 18 or newer, on Linux (x86_64 and arm64, glibc 2.28 or newer) and
 macOS (Apple Silicon, macOS 11 or newer; Intel, macOS 10.12 or newer). Elsewhere,
 build `node/` from the repository.

package/claude-agent-sdk.d.mts

@@ -0,0 +1,5 @@
+import type { Tool } from './index.js';
+/** staal Tools as an in-process MCP server config for the Claude Agent SDK's `mcpServers`. */
+export function mcpServer(tools: Tool<any>[], options?: { name?: string; context?: unknown }): { type: 'sdk'; name: string; instance: any };
+/** The names the Agent SDK gives `tools` served under `name`, for `allowedTools`. */
+export function allowedTools(name: string, tools: Tool<any>[]): string[];

package/claude-agent-sdk.mjs

@@ -0,0 +1,77 @@
+// staal Tools as an in-process MCP server for the Claude Agent SDK
+// (@anthropic-ai/claude-agent-sdk, with @modelcontextprotocol/sdk 1.x, which the app
+// installs; @staal/node depends on neither). The Agent SDK is published as ES modules
+// only, so this adapter is one too.
+//
+//   import { query } from '@anthropic-ai/claude-agent-sdk';
+//   import { allowedTools, mcpServer } from '@staal/node/claude-agent-sdk';
+//   for await (const message of query({ prompt, options: {
+//     mcpServers: { staal: mcpServer([refund], { context: customer }) },   // one per query
+//     allowedTools: allowedTools('staal', [refund]),
+//     tools: [],
+//   } })) { ... }
+//
+// The Agent SDK gives a tool only its arguments, so the app's context for the session
+// (the signed-in customer, the tenant) is bound when the server is made: make one per
+// query, from the app's own records, never from anything the model wrote. Each call
+// runs the Staal program with the grants the app's policy gives for that context.
+//
+// The server is a plain MCP server (the MCP SDK's low-level Server), so the program's
+// argument schema reaches the model as JSON Schema, unconverted, and Staal's own check
+// of the arguments is the one that decides. A refusal, a failure or an unknown tool is
+// a tool result with isError, with Staal's message, so the model can correct itself;
+// nothing is retried. The model sees each tool as `mcp__<name>__<tool name>`.
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+const HINTS = ['title', 'readOnlyHint', 'destructiveHint', 'idempotentHint', 'openWorldHint'];
+
+function checked(tools) {
+  if (!Array.isArray(tools) || tools.length === 0) throw new TypeError('staal: mcpServer takes a list of Tools from Tool.open');
+  const byName = new Map();
+  for (const t of tools) {
+    if (!t || typeof t.call !== 'function' || typeof t.name !== 'string') throw new TypeError('staal: mcpServer takes a list of Tools from Tool.open');
+    if (byName.has(t.name)) throw new TypeError(`staal: mcpServer: two tools are named '${t.name}'`);
+    byName.set(t.name, t);
+  }
+  return byName;
+}
+
+/**
+ * `tools` as an in-process MCP server for the Agent SDK's `mcpServers` option.
+ * `options.context` is what each tool's grants (and scope) function receives, for
+ * every call made through this server; `options.name` (default "staal") must be the
+ * key the server is given in `mcpServers`.
+ */
+export function mcpServer(tools, options = {}) {
+  const byName = checked(tools);
+  const name = options.name ?? 'staal';
+  if (typeof name !== 'string' || !/^[A-Za-z0-9_-]+$/.test(name)) throw new TypeError('staal: mcpServer: name is letters, digits, _ and -');
+  const context = options.context;
+  const server = new Server({ name, version: '1.0.0' }, { capabilities: { tools: {} } });
+  const listed = [...byName.values()].map((t) => {
+    const annotations = {};
+    for (const k of HINTS) if (t.annotations && k in t.annotations) annotations[k] = t.annotations[k];
+    return { name: t.name, description: t.description, inputSchema: t.schema, annotations };
+  });
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: listed }));
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const t = byName.get(request.params.name);
+    if (!t) return { content: [{ type: 'text', text: `there is no tool '${request.params.name}'` }], isError: true };
+    try {
+      const result = await t.call(request.params.arguments ?? {}, { context });
+      return { content: [{ type: 'text', text: result.text }], isError: result.isError };
+    } catch (e) {
+      // The call did not reach an answer (the host is closed, the grants function
+      // threw): the model is told so, as an MCP tool error, not a protocol error.
+      return { content: [{ type: 'text', text: `the tool could not be called: ${e && e.message ? e.message : String(e)}` }], isError: true };
+    }
+  });
+  return { type: 'sdk', name, instance: server };
+}
+
+/** The names the Agent SDK gives `tools` served under `name`, for `allowedTools`. */
+export function allowedTools(name, tools) {
+  return [...checked(tools).keys()].map((n) => `mcp__${name}__${n}`);
+}

package/index.d.ts

@@ -30,6 +30,7 @@ export type FailureKind =
   | 'provider'
   | 'step_limit'
   | 'depth_limit'
+  | 'deadline'
   | 'internal'
   | 'journal'
   | 'in_doubt';
@@ -39,8 +40,17 @@ export interface Failure {
   message: string;
 }
 
+/** What one granted capability used over a run (RUNTIME.md section 6). */
+export interface GrantUsage {
+  capability: string;
+  uses: number;
+  charged: { amount: string; currency: string }[];
+}
+
 interface Ran {
   log: LogEvent[];
+  /** For each capability parameter of the entry function, by name. */
+  usage: { [parameter: string]: GrantUsage };
   /** Present when the run loaded C code, which Staal cannot check (RUNTIME.md section 19). */
   unchecked?: Json[];
 }
@@ -75,3 +85,99 @@ export function check(program: string): Promise<CheckResult>;
 export function run(program: string, config: RunConfig, options?: RunOptions): Promise<RunResult>;
 export function resume(program: string, config: RunConfig, journal: string, options?: Pick<RunOptions, 'engine'>): Promise<RunResult>;
 export function resolve(journal: string, resolution: Resolution): Promise<ResolveResult>;
+
+/** A host or tool could not be opened, or a call was malformed: nothing ran. */
+export class StaalError extends Error {}
+
+export interface HostOptions {
+  /** Days a settled run's files are kept (default 90), or "forever". */
+  keep?: number | 'forever';
+  max_concurrent_runs?: number;
+  notify?: string[];
+  notify_env?: string[];
+}
+
+/** Where tools keep their runs: one journal directory, its ledger and its quotas. */
+export class Host {
+  static open(journals: string, options?: HostOptions): Promise<Host>;
+  readonly journals: string;
+  /** What happened to a run, by its id. Changes nothing. */
+  /** A run made in a scope is described only when the same scope is given. */
+  status(run: string, options?: { scope?: string }): Promise<RunStatus>;
+  close(): Promise<void>;
+}
+
+export type RunStatus = {
+  run: string;
+  status: 'running' | 'waiting_for_operator' | 'done' | 'failed' | 'not_started' | 'expired' | 'unknown';
+  observed_at: string;
+  result?: Json;
+  failure?: { kind: string; message: string };
+  reason?: string;
+};
+
+export interface ToolOptions<Context = unknown> {
+  name: string;
+  description: string;
+  /** The same grants for every call, or a function of the call's context giving that call's. */
+  grants?: { [name: string]: Json } | ((context: Context) => { [name: string]: Json } | Promise<{ [name: string]: Json }>);
+  /**
+   * The call's trusted scope (a tenant's or a user's id, from the app's own records,
+   * never from the arguments), from its context: `once` keys are held within a scope,
+   * and a run's status is given only in its scope.
+   */
+  scope?: (context: Context) => string | Promise<string>;
+  /**
+   * Inputs only the app supplies, such as the customer a call is for: each name, an
+   * input of the entry function, maps to a function of the call's context giving its
+   * value. They are not in the schema a model sees, and a call whose arguments name
+   * one is refused.
+   */
+  appInputs?: { [name: string]: (context: Context) => Json | Promise<Json> };
+  /** A journal directory, or an open host: one is required. */
+  journals?: string;
+  host?: Host;
+  title?: string;
+  entry?: string;
+  quota?: { window: string; calls?: number; money?: { amount: string; currency: string } };
+  once?: { by: string[]; keep?: string };
+  deadline?: string;
+  max_concurrent_runs?: number;
+  engine?: 'interpreter' | 'native';
+  model?: Json;
+  secrets?: Json;
+  net?: Json;
+  fs?: Json;
+  adapters?: Json;
+  limits?: Json;
+}
+
+export interface ToolResult {
+  status: 'done' | 'failed' | 'stopped' | 'in_progress' | 'not_run';
+  isError: boolean;
+  /** What to show a model. */
+  text: string;
+  structured?: { result: Json } | { status: 'waiting_for_operator'; run: string };
+  run?: string;
+  /** The program's result, when done. */
+  value?: Json;
+}
+
+/** A program's entry function as a tool, with quotas, once and recovery across calls. */
+export class Tool<Context = unknown> {
+  static open<Context = unknown>(program: string, options: ToolOptions<Context>): Promise<Tool<Context>>;
+  readonly name: string;
+  readonly title?: string;
+  readonly description: string;
+  /** The JSON Schema of its arguments. */
+  readonly schema: Json;
+  readonly outputSchema: Json;
+  readonly annotations: { readOnlyHint: boolean; destructiveHint: boolean; idempotentHint: boolean; openWorldHint: boolean; title?: string };
+  readonly warnings: string[];
+  readonly perCallGrants: boolean;
+  readonly host: Host;
+  call(args?: { [name: string]: Json }, options?: { context?: Context }): Promise<ToolResult>;
+  /** A run's status, in the scope the tool's scope function gives for the context. */
+  status(run: string, options?: { context?: Context }): Promise<RunStatus>;
+  close(): Promise<void>;
+}

package/index.js

@@ -77,4 +77,174 @@ async function resolve(journal, resolution) {
   return parse(await addon.resolve(str(journal, 'journal'), JSON.stringify(resolution)));
 }
 
-module.exports = { version, check, run, resume, resolve };
+class StaalError extends Error {}
+
+function ok(out) {
+  if (out.status === 'error') throw new StaalError(out.error);
+  return out;
+}
+
+/**
+ * Where tools keep their runs: one journal directory, its ledger and its quotas.
+ * Opening it resumes or settles whatever an earlier process left there. One process
+ * uses a directory at a time; opening it again in this process gives the same host.
+ */
+class Host {
+  constructor(handle, journals) {
+    this._handle = handle;
+    this.journals = journals;
+  }
+
+  static async open(journals, options = {}) {
+    const settings = { journals: str(journals, 'journals'), keep: 90, max_concurrent_runs: 8, ...options };
+    const out = ok(parse(await addon.hostOpen(JSON.stringify(settings))));
+    return new Host(out.host, journals);
+  }
+
+  /**
+   * What happened to a run, by its id. Changes nothing. A run made in a scope is
+   * described only when `options.scope` is that scope; otherwise it is unknown.
+   */
+  async status(run, options = {}) {
+    return ok(parse(await addon.runStatus(this._handle, str(run, 'run'), scopeOf(options.scope))));
+  }
+
+  async close() {
+    if (this._handle !== null) {
+      const h = this._handle;
+      this._handle = null;
+      ok(parse(await addon.hostClose(h)));
+    }
+  }
+}
+
+function scopeOf(scope) {
+  if (scope === undefined || scope === null) return undefined;
+  if (typeof scope !== 'string') throw new TypeError("staal: a scope must be a string (a tenant's or a user's id, from the app's own records)");
+  return scope;
+}
+
+const SPEC_KEYS = ['title', 'entry', 'quota', 'once', 'deadline', 'max_concurrent_runs', 'engine',
+  'model', 'secrets', 'net', 'fs', 'adapters', 'limits'];
+
+/**
+ * A program's entry function as a tool. `grants` is an object, the same for every
+ * call, or a function of the call's context that returns that call's grants, so the
+ * app's policy decides each call's limits. `scope`, if given, is a function of the
+ * same context returning the call's trusted scope as a string (a tenant's or a user's
+ * id, from the app's own records, never from the arguments): a `once` key is held
+ * within its scope, and a run's status is given only in its scope. An app serving more
+ * than one tenant or user from one journal directory gives a scope. `appInputs`, if
+ * given, maps names of the entry function's inputs to functions of the same context
+ * that give their values: inputs only the app supplies, such as the customer a call
+ * is for. They are not in the schema a model sees, and a call whose arguments name
+ * one is refused. Give `journals` (a directory) or `host`.
+ */
+class Tool {
+  static async open(program, options) {
+    const { name, description, grants, scope, appInputs, journals, host, ...spec } = options || {};
+    if (scope !== undefined && typeof scope !== 'function') throw new TypeError("staal: Tool: scope is a function of the call's context");
+    if (appInputs !== undefined) {
+      const entries = appInputs !== null && typeof appInputs === 'object' && !Array.isArray(appInputs) ? Object.entries(appInputs) : [];
+      if (entries.length === 0 || !entries.every(([, f]) => typeof f === 'function')) {
+        throw new TypeError("staal: Tool: appInputs maps input names to functions of the call's context");
+      }
+    }
+    for (const k of Object.keys(spec)) {
+      if (!SPEC_KEYS.includes(k)) throw new TypeError(`staal: Tool: unknown option '${k}'`);
+    }
+    if ((journals === undefined) === (host === undefined)) {
+      throw new TypeError('staal: Tool: give journals (a directory) or host, not both and not neither');
+    }
+    const ownHost = host === undefined;
+    const h = ownHost ? await Host.open(journals) : host;
+    const body = { name, description, program: str(program, 'program') };
+    if (grants !== undefined && typeof grants !== 'function') body.grants = grants;
+    if (appInputs !== undefined) body.app_inputs = Object.keys(appInputs);
+    for (const [k, v] of Object.entries(spec)) if (v !== undefined && v !== null) body[k] = v;
+    let out;
+    try {
+      out = ok(parse(await addon.toolOpen(h._handle, JSON.stringify(body))));
+    } catch (e) {
+      if (ownHost) await h.close();
+      throw e;
+    }
+    const t = new Tool(out, h, ownHost, typeof grants === 'function' ? grants : null, scope || null, appInputs ? { ...appInputs } : null);
+    if (t.perCallGrants && t._grants === null) {
+      await t.close();
+      throw new TypeError('staal: Tool: the program needs grants; give grants (an object or a function of the context)');
+    }
+    if (!t.perCallGrants && t._grants !== null) {
+      await t.close();
+      throw new TypeError("staal: Tool: the program's entry function takes no capabilities, so it takes no grants");
+    }
+    return t;
+  }
+
+  constructor(out, host, ownHost, grants, scope, appInputs) {
+    this._handle = out.tool;
+    this._scope = scope;
+    this._appInputs = appInputs;
+    this.host = host;
+    this._ownHost = ownHost;
+    this._grants = grants;
+    this.name = out.name;
+    this.title = out.title;
+    this.description = out.description;
+    this.schema = out.input_schema;
+    this.outputSchema = out.output_schema;
+    this.annotations = out.annotations;
+    this.warnings = out.warnings;
+    this.perCallGrants = out.grants === 'per_call';
+  }
+
+  /**
+   * One call. Resolves to { status, isError, text, structured, run, value }: status is
+   * "done", "failed", "stopped" (waiting for an operator), "in_progress" or "not_run";
+   * a refusal is a result too, so a model can be told why.
+   */
+  async call(args = {}, options = {}) {
+    if (args === null || typeof args !== 'object' || Array.isArray(args)) {
+      throw new TypeError(`staal: the arguments are an object (a JSON object), not ${args === null ? 'null' : Array.isArray(args) ? 'an array' : typeof args}`);
+    }
+    let grants;
+    if (this.perCallGrants) {
+      const g = await this._grants(options.context);
+      if (g === null || typeof g !== 'object' || Array.isArray(g)) throw new TypeError('staal: the grants function must return an object');
+      grants = JSON.stringify(g);
+    }
+    const scope = this._scope ? scopeOf(await this._scope(options.context)) : undefined;
+    let inputs;
+    if (this._appInputs) {
+      const values = {};
+      for (const [k, f] of Object.entries(this._appInputs)) values[k] = await f(options.context);
+      inputs = JSON.stringify(values);
+    }
+    const out = ok(parse(await addon.toolCall(this._handle, JSON.stringify(args), inputs, grants, scope)));
+    return {
+      status: out.status,
+      isError: out.is_error,
+      text: out.text,
+      structured: out.structured,
+      run: out.run,
+      value: out.status === 'done' && out.structured ? out.structured.result : undefined,
+    };
+  }
+
+  /** A run's status, in the scope the tool's scope function gives for `options.context`. */
+  async status(run, options = {}) {
+    const scope = this._scope ? scopeOf(await this._scope(options.context)) : undefined;
+    return this.host.status(run, { scope });
+  }
+
+  async close() {
+    if (this._handle !== null) {
+      const t = this._handle;
+      this._handle = null;
+      ok(parse(await addon.toolClose(t)));
+    }
+    if (this._ownHost) await this.host.close();
+  }
+}
+
+module.exports = { version, check, run, resume, resolve, Host, Tool, StaalError };

package/langgraph.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from './index';
+/** A staal Tool as a @langchain/core tool; `context` maps the call's config to the tool's context. */
+export function structuredTool(staalTool: Tool<any>, options?: { context?: (config: any) => unknown }): any;

package/langgraph.js

@@ -0,0 +1,31 @@
+'use strict';
+// A staal Tool as a LangChain tool, for LangGraph's ToolNode and agents (@langchain/core
+// and @langchain/langgraph, which the app installs; @staal/node does not depend on them).
+//
+//   const { ToolNode } = require('@langchain/langgraph/prebuilt');
+//   const { structuredTool } = require('@staal/node/langgraph');
+//   const tools = new ToolNode([structuredTool(refund)]);
+//   await graph.invoke(state, { configurable: { staal_context: customer } });
+//
+// Each call runs the Staal program with the grants the app's policy gives for the call's
+// context: by default `config.configurable.staal_context`, or whatever `context` returns
+// for the call's config. A refusal or a failure is given to the model as the tool's
+// output, the broker's message included, so the model can correct itself.
+
+const { tool } = require('@langchain/core/tools');
+
+/** `staalTool` (from Tool.open) as a @langchain/core tool. */
+function structuredTool(staalTool, options = {}) {
+  const pick = options.context || ((config) => (config && config.configurable ? config.configurable.staal_context : undefined));
+  const schema = { ...staalTool.schema };
+  delete schema.$schema;
+  return tool(
+    async (input, config) => {
+      const result = await staalTool.call(input || {}, { context: pick(config) });
+      return result.text;
+    },
+    { name: staalTool.name, description: staalTool.description, schema },
+  );
+}
+
+module.exports = { structuredTool };

package/openai-agents.d.ts

@@ -0,0 +1,3 @@
+import type { Tool } from './index';
+/** A staal Tool as an @openai/agents function tool; `context` maps the run context to the tool's context. */
+export function functionTool(staalTool: Tool<any>, options?: { context?: (runContext: any) => unknown }): any;

package/openai-agents.js

@@ -0,0 +1,35 @@
+'use strict';
+// A staal Tool as a tool of the OpenAI Agents SDK for JavaScript (@openai/agents, which
+// the app installs; @staal/node does not depend on it).
+//
+//   const { Agent } = require('@openai/agents');
+//   const { functionTool } = require('@staal/node/openai-agents');
+//   const agent = new Agent({ name: 'Support', tools: [functionTool(refund)] });
+//
+// Each call runs the Staal program with the grants the app's policy gives for the run's
+// context (the `context` passed to run(), unless `context` says otherwise). A refusal
+// or a failure is given to the model as the tool's output, the broker's message
+// included, so the model can correct itself.
+
+const { tool } = require('@openai/agents');
+
+/** `staalTool` (from Tool.open) as an @openai/agents function tool. */
+function functionTool(staalTool, options = {}) {
+  const pick = options.context || ((runContext) => (runContext ? runContext.context : undefined));
+  const parameters = { ...staalTool.schema };
+  delete parameters.$schema;
+  return tool({
+    name: staalTool.name,
+    description: staalTool.description,
+    parameters,
+    // Staal's own check of the arguments is the one that decides; the schema is given
+    // as it is rather than rewritten into the API's strict subset.
+    strict: false,
+    execute: async (input, runContext) => {
+      const result = await staalTool.call(input || {}, { context: pick(runContext) });
+      return result.text;
+    },
+  });
+}
+
+module.exports = { functionTool };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staal/node",
-  "version": "0.24.1",
+  "version": "0.26.0",
   "description": "Staal, the programming language for agents, for Node.js: the staalc compiler and runtime, through its C interface",
   "keywords": [
     "staal",
@@ -27,7 +27,15 @@
     "README.md",
     "LICENSE",
     "NOTICE",
-    "LICENSE-THIRD-PARTY.txt"
+    "LICENSE-THIRD-PARTY.txt",
+    "openai-agents.js",
+    "openai-agents.d.ts",
+    "langgraph.js",
+    "langgraph.d.ts",
+    "vercel-ai.mjs",
+    "vercel-ai.d.mts",
+    "claude-agent-sdk.mjs",
+    "claude-agent-sdk.d.mts"
   ],
   "publishConfig": {
     "access": "public"
@@ -45,10 +53,57 @@
   ],
   "scripts": {
     "test": "node --test test/staal.test.mjs",
-    "types": "tsc --noEmit -p test/tsconfig.json"
+    "types": "tsc --noEmit -p test/tsconfig.json && tsc --noEmit -p test/tsconfig.esm.json"
   },
   "devDependencies": {
     "@types/node": "22.10.2",
     "typescript": "5.7.2"
+  },
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
+    "./openai-agents": {
+      "types": "./openai-agents.d.ts",
+      "default": "./openai-agents.js"
+    },
+    "./langgraph": {
+      "types": "./langgraph.d.ts",
+      "default": "./langgraph.js"
+    },
+    "./vercel-ai": {
+      "types": "./vercel-ai.d.mts",
+      "import": "./vercel-ai.mjs"
+    },
+    "./claude-agent-sdk": {
+      "types": "./claude-agent-sdk.d.mts",
+      "import": "./claude-agent-sdk.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@openai/agents": ">=0.20.0",
+    "@langchain/core": ">=1.2.18",
+    "ai": ">=7.0.145",
+    "@anthropic-ai/claude-agent-sdk": ">=0.3.304",
+    "@modelcontextprotocol/sdk": ">=1.29.0"
+  },
+  "peerDependenciesMeta": {
+    "@openai/agents": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "@anthropic-ai/claude-agent-sdk": {
+      "optional": true
+    },
+    "@modelcontextprotocol/sdk": {
+      "optional": true
+    }
   }
 }

package/vercel-ai.d.mts

@@ -0,0 +1,5 @@
+import type { Tool } from './index.js';
+/** A staal Tool as a Vercel AI SDK tool; `context` maps the tool's `toolsContext` entry to the staal Tool's context. */
+export function aiTool(staalTool: Tool<any>, options?: { context?: (toolContext: any) => unknown }): any;
+/** Several staal Tools as an AI SDK tool set, keyed by each tool's name. */
+export function aiTools(staalTools: Tool<any>[], options?: { context?: (toolContext: any) => unknown }): Record<string, any>;

package/vercel-ai.mjs

@@ -0,0 +1,58 @@
+// A staal Tool as a tool of the Vercel AI SDK (`ai`, version 7, which the app installs;
+// @staal/node does not depend on it). The AI SDK is published as ES modules only, so
+// this adapter is one too.
+//
+//   import { generateText, stepCountIs } from 'ai';
+//   import { aiTools } from '@staal/node/vercel-ai';
+//   const result = await generateText({
+//     model, prompt, stopWhen: stepCountIs(5),
+//     tools: aiTools([refund]),
+//     toolsContext: { refund_order: customer },   // the app's context for that tool
+//   });
+//
+// Each call runs the Staal program with the grants the app's policy gives for the
+// tool's context: the AI SDK hands each tool its own entry of `toolsContext`, keyed by
+// the tool's name, and that entry is what the Staal tool's grants (and scope) function
+// receives, unless `options.context` maps it to something else. Context never reaches
+// the model.
+//
+// The model is shown the program's argument schema as it is, without validation by
+// the AI SDK: Staal's own check of the arguments is the one that decides, and a call it
+// refuses comes back to the model as an error with Staal's message, as a refusal by the
+// broker does, so the model can correct itself. Nothing is retried. An abort of the
+// generation does not stop a Staal run that has started: its outcome is in its journal
+// and in the tool's status, as with any call.
+
+import { tool, jsonSchema } from 'ai';
+
+/** `staalTool` (from Tool.open) as an AI SDK tool. Give it to `tools` under `staalTool.name`. */
+export function aiTool(staalTool, options = {}) {
+  if (!staalTool || typeof staalTool.call !== 'function' || typeof staalTool.name !== 'string') {
+    throw new TypeError('staal: aiTool takes a Tool from Tool.open');
+  }
+  const pick = options.context || ((context) => context);
+  if (typeof pick !== 'function') throw new TypeError('staal: aiTool: options.context is a function of the tool context');
+  const schema = { ...staalTool.schema };
+  delete schema.$schema;
+  return tool({
+    description: staalTool.description,
+    // No `validate`: the AI SDK passes the model's input on as it is, and Staal checks it.
+    inputSchema: jsonSchema(schema),
+    execute: async (input, { context }) => staalTool.call(input ?? {}, { context: await pick(context) }),
+    // What the model reads: the answer's text, as an MCP client would get it, marked
+    // as an error when Staal refused or the run failed.
+    toModelOutput: ({ output }) => (output.isError ? { type: 'error-text', value: output.text } : { type: 'text', value: output.text }),
+  });
+}
+
+/** Several staal Tools as an AI SDK tool set, each under its own name. */
+export function aiTools(staalTools, options = {}) {
+  if (!Array.isArray(staalTools)) throw new TypeError('staal: aiTools takes a list of Tools');
+  const set = {};
+  for (const t of staalTools) {
+    const made = aiTool(t, options);
+    if (Object.prototype.hasOwnProperty.call(set, t.name)) throw new TypeError(`staal: aiTools: two tools are named '${t.name}'`);
+    set[t.name] = made;
+  }
+  return set;
+}