@staal/node 0.25.0 → 0.26.0

package/README.md

@@ -51,16 +51,27 @@ const r = await refund.call({ order: '4417', amount: { amount: '35.00', currency
 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 })`). One process uses a
+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`). The frameworks are optional peer dependencies.
-Both are tested through the framework's own agent loop (@openai/agents 0.20.0,
-@langchain/langgraph 1.5.1); the examples are in
+`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

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

@@ -127,6 +127,13 @@ export interface ToolOptions<Context = unknown> {
    * 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;

package/index.js

@@ -134,13 +134,22 @@ const SPEC_KEYS = ['title', 'entry', 'quota', 'once', 'deadline', 'max_concurren
  * 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. Give `journals`
- * (a directory) or `host`.
+ * 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, journals, host, ...spec } = 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}'`);
     }
@@ -151,6 +160,7 @@ class Tool {
     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 {
@@ -159,7 +169,7 @@ class Tool {
       if (ownHost) await h.close();
       throw e;
     }
-    const t = new Tool(out, h, ownHost, typeof grants === 'function' ? grants : null, scope || null);
+    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)');
@@ -171,9 +181,10 @@ class Tool {
     return t;
   }
 
-  constructor(out, host, ownHost, grants, scope) {
+  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;
@@ -193,6 +204,9 @@ class Tool {
    * 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);
@@ -200,7 +214,13 @@ class Tool {
       grants = JSON.stringify(g);
     }
     const scope = this._scope ? scopeOf(await this._scope(options.context)) : undefined;
-    const out = ok(parse(await addon.toolCall(this._handle, JSON.stringify(args), grants, scope)));
+    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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@staal/node",
-  "version": "0.25.0",
+  "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",
@@ -31,7 +31,11 @@
     "openai-agents.js",
     "openai-agents.d.ts",
     "langgraph.js",
-    "langgraph.d.ts"
+    "langgraph.d.ts",
+    "vercel-ai.mjs",
+    "vercel-ai.d.mts",
+    "claude-agent-sdk.mjs",
+    "claude-agent-sdk.d.mts"
   ],
   "publishConfig": {
     "access": "public"
@@ -49,7 +53,7 @@
   ],
   "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",
@@ -68,11 +72,22 @@
       "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"
+    "@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": {
@@ -80,6 +95,15 @@
     },
     "@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;
+}