@staal/node 0.24.1 → 0.25.0

package/README.md

@@ -31,6 +31,38 @@ 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 })`). 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
+[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/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,92 @@ 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>;
+  /** 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,154 @@ 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. Give `journals`
+ * (a directory) or `host`.
+ */
+class Tool {
+  static async open(program, options) {
+    const { name, description, grants, scope, journals, host, ...spec } = options || {};
+    if (scope !== undefined && typeof scope !== 'function') throw new TypeError("staal: Tool: scope is a function 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;
+    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);
+    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) {
+    this._handle = out.tool;
+    this._scope = scope;
+    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 = {}) {
+    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;
+    const out = ok(parse(await addon.toolCall(this._handle, JSON.stringify(args), 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.25.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,11 @@
     "README.md",
     "LICENSE",
     "NOTICE",
-    "LICENSE-THIRD-PARTY.txt"
+    "LICENSE-THIRD-PARTY.txt",
+    "openai-agents.js",
+    "openai-agents.d.ts",
+    "langgraph.js",
+    "langgraph.d.ts"
   ],
   "publishConfig": {
     "access": "public"
@@ -50,5 +54,32 @@
   "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"
+    },
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "@openai/agents": ">=0.20.0",
+    "@langchain/core": ">=1.2.18"
+  },
+  "peerDependenciesMeta": {
+    "@openai/agents": {
+      "optional": true
+    },
+    "@langchain/core": {
+      "optional": true
+    }
   }
 }