@tangleai/agents 0.21.1

package/src/schemas/program.js

@@ -0,0 +1,205 @@
+//@ts-check
+/**
+ * The action language: what a model may say about the environment.
+ *
+ * The RLM paper's root model writes Python and an interpreter runs it.
+ * This package has no interpreter and will never have one — `eval` and
+ * `new Function` are forbidden by the house rules and a browser tab is
+ * the wrong place for a sandbox — so the model authors a **document**
+ * instead, and the document is put through the same two gates every
+ * generated Jaren program goes through: a schema that constrains
+ * decoding (the shape) and a compiler that runs before anything else
+ * does (the semantics).
+ *
+ * Read the two rules that shaped every line of this file:
+ *
+ *  - **A step names slots; it never carries content** (D2). Every member
+ *    below is an operation name, a binding name, a slot reference, a
+ *    bounded instruction or a query document. There is no member a
+ *    corpus can be poured into, and none can be added later without
+ *    failing `test/ai/program.test.js` — the schema is walked and every
+ *    string member must declare a `maxLength`. That is what makes "the
+ *    program is constant-size whatever the corpus" a property of the
+ *    grammar rather than a promise about how it will be used.
+ *  - **`map` is the only step that calls a model.** One construct, one
+ *    concurrency bound, one place to count spend. A grammar with
+ *    sub-calls sprinkled through it cannot be bounded, and a runner over
+ *    such a grammar cannot state what a program will cost before it runs
+ *    it.
+ *
+ * Three shape decisions exist for the weak tier specifically (D8), and
+ * each one trades expressiveness for a decision the model does not have
+ * to make:
+ *
+ *  - **Every step reads `from` and writes `as`.** Not `slot`/`in`/`over`
+ *    per operation: one input member and one output member across the
+ *    whole language, so the model picks the *operation* and never the
+ *    spelling of its argument.
+ *  - **Bindings are program-local names, not addresses.** The program
+ *    says `as: "pieces"`; the runner resolves that to whatever the
+ *    environment's derived addressing produced (HORIZON_06 owns
+ *    addresses; a model that could write one could name a slot that
+ *    cannot exist).
+ *  - **`query` is left open unless a grammar is injected.** The seam is
+ *    D3: with `@jarenjs/json`'s query grammar passed as a `ref` the
+ *    shape is constrained too; without it the schema accepts any JSON
+ *    value here and the compile gate is what refuses a bad one. A schema
+ *    that hard-`$ref`'d a grammar this package may not import would make
+ *    the whole language unusable with the seam empty.
+ */
+
+/** Steps one program may have. A plan longer than this is a program
+ * that should have been two runs; it is also past the length a small
+ * model keeps coherent. */
+export const MAX_STEPS = 12;
+
+/** The whole document's character cap, enforced by the compiler. This
+ * is the constant in "constant-size root request": the program is one
+ * more thing the root carries, and it must not grow with the corpus. */
+export const MAX_PROGRAM_CHARS = 4000;
+
+/** A binding name: short, lowercase, unmistakable in an error message. */
+export const NAME_PATTERN = '^[a-z][a-z0-9_]{0,31}$';
+
+/** How long a slot reference may be — an address, never a payload. */
+const SLOT_REF_MAX = 200;
+
+/** How long a sub-call instruction may be. An instruction, not content:
+ * the content is the slot the sub-call is run over. */
+const PROMPT_MAX = 1000;
+
+/** How long a grep pattern may be. */
+const PATTERN_MAX = 200;
+
+/** The operations a program may name, in the order a plan uses them. */
+export const PROGRAM_OPS = ['chunk', 'grep', 'select', 'stat', 'peek', 'map', 'reduce', 'answer'];
+
+/** The one input member. See the file header for why it is not per-op. */
+const FROM = {
+  type: 'string',
+  minLength: 1,
+  maxLength: SLOT_REF_MAX,
+  description: 'What this step reads: a name from an earlier step\'s "as", or a slot from the digest.',
+};
+
+/** The one output member: the name later steps use to read this one.
+ * `maxLength` as well as the pattern, which already bounds it: the D2
+ * walk in `test/ai/program.test.js` checks that every string member
+ * declares a cap, and a check that has to interpret a regex to decide
+ * whether one is bounded is a weaker check than one that reads a
+ * number. */
+const AS = {
+  type: 'string',
+  pattern: NAME_PATTERN,
+  maxLength: 32,
+  description: 'A short name for this step\'s result, used as "from" by a later step.',
+};
+
+/**
+ * One step's schema.
+ * @param {string} op
+ * @param {string} description
+ * @param {Record<string, any>} extra - members beyond `from`/`as`
+ * @param {string[]} [required] - beyond `from`, `as`
+ */
+function step(op, description, extra = {}, required = []) {
+  return {
+    title: op,
+    description,
+    type: 'object',
+    properties: {
+      op: { const: op },
+      from: FROM,
+      as: AS,
+      ...extra,
+    },
+    required: ['op', 'from', 'as', ...required],
+    additionalProperties: false,
+  };
+}
+
+/**
+ * The program schema.
+ *
+ * `queryRef` is the `$id` of an injected query grammar
+ * (`@jarenjs/json/schemas/jaren-query.schema.json`, or its LLM-profile
+ * twin — the twin is the better choice for constrained decoding, which
+ * is what it was derived for). Given one, `select` and `reduce` are
+ * shape-constrained as well as compile-gated, and the caller must pass
+ * the same grammar to `createStructuredOutput` as a `ref` so the
+ * validator can resolve it. Given none, `query` accepts any JSON value
+ * and the compile gate carries the whole weight.
+ *
+ * @param {{ queryRef?: string, maxSteps?: number }} [options]
+ * @returns {any} a JSON Schema document
+ */
+export function programSchema(options = {}) {
+  const query = options.queryRef === undefined
+    ? { description: 'A jaren-query document.' }
+    : { $ref: options.queryRef, description: 'A jaren-query document.' };
+  const maxSteps = options.maxSteps ?? MAX_STEPS;
+
+  return {
+    $id: 'https://jarenjs.github.io/schemas/ai/program.json',
+    title: 'Environment program',
+    description: 'A plan over slots in the agent\'s environment. Steps name slots and never'
+      + ' carry their content; the last step is always "answer".',
+    type: 'object',
+    properties: {
+      steps: {
+        type: 'array',
+        minItems: 1,
+        maxItems: maxSteps,
+        items: {
+          // anyOf, not oneOf: the branches are disjoint by their `op`
+          // const, and oneOf is the keyword provider implementations
+          // most often refuse (the same reason schemas/patch.js gives).
+          anyOf: [
+            step('chunk', 'Split a slot into addressable pieces.', {
+              strategy: { enum: ['size', 'line', 'separator'], description: 'How to cut. Default size.' },
+              size: { type: 'integer', minimum: 200, maximum: 100000, description: 'Piece size in characters.' },
+            }),
+            step('grep', 'Scan for a pattern and record which slots matched.', {
+              pattern: { type: 'string', minLength: 1, maxLength: PATTERN_MAX, description: 'A regular expression.' },
+              flags: { enum: ['i', 'm', 'im', ''], description: 'Regex flags. Default i.' },
+              limit: { type: 'integer', minimum: 1, maximum: 200, description: 'Maximum matches recorded.' },
+            }, ['pattern']),
+            step('select', 'Run a query over a JSON slot and store the result.', { query }, ['query']),
+            step('stat', 'Counts, sizes and shape of a slot or a family.'),
+            step('peek', 'Metadata and a head excerpt of one slot.'),
+            step('map', 'Ask the model once per piece. The ONLY step that calls a model.', {
+              prompt: {
+                type: 'string',
+                minLength: 1,
+                maxLength: PROMPT_MAX,
+                description: 'What to ask about each piece. Ask for a JSON value; the piece is'
+                  + ' supplied automatically, so do not paste any content here.',
+              },
+            }, ['prompt']),
+            step('reduce', 'Combine a map\'s results with a query, into one slot.', {
+              query, outputSchema: { type: 'object', description: 'Declared JSON Schema for an inference-unknown result; validated before storage.' },
+            }, ['query']),
+            {
+              title: 'answer',
+              description: 'The last step: the slot the answer is read from.',
+              type: 'object',
+              properties: {
+                op: { const: 'answer' },
+                from: FROM,
+                chars: { type: 'integer', minimum: 1, maximum: 8000, description: 'How much of it to read.' },
+              },
+              required: ['op', 'from'],
+              additionalProperties: false,
+            },
+          ],
+        },
+      },
+    },
+    required: ['steps'],
+    additionalProperties: false,
+  };
+}
+
+/** The program schema with the query seam empty — what a caller with no
+ * grammar injected authors against. */
+export const PROGRAM_SCHEMA = programSchema();

package/src/toolbox.d.ts

@@ -0,0 +1,55 @@
+/**
+ * @typedef {Object} ToolDef
+ * @property {string} name
+ * @property {string} description
+ * @property {any} inputSchema - JSON Schema for the arguments object
+ * @property {(input: any) => any} execute - may return a value or a promise
+ */
+/**
+ * @param {{ validator?: any }} [options] - a shared JarenValidator, if
+ *   the host already has one
+ * @returns {{
+ *   add: (def: ToolDef) => void,
+ *   list: () => { name: string, description: string, inputSchema: any }[],
+ *   toFunctionTools: () => any[],
+ *   execute: (name: string, args: any) => any,
+ * }}
+ */
+export function createToolbox(options?: {
+    validator?: any;
+}): {
+    add: (def: ToolDef) => void;
+    list: () => {
+        name: string;
+        description: string;
+        inputSchema: any;
+    }[];
+    toFunctionTools: () => any[];
+    execute: (name: string, args: any) => any;
+};
+/**
+ * Publish validated tools through the shared browser adapter. Await `ready`
+ * for completion and call `dispose` when the host leaves. The optional context
+ * remains the second argument; undefined requests automatic discovery.
+ * @param {ReturnType<typeof createToolbox>} toolbox
+ * @param {unknown} [modelContext]
+ * @param {(error: unknown) => void} [onError]
+ * @param {Omit<import('@jarenjs/contract/webmcp').WebMcpOptions, 'context'|'onError'>} [options]
+ */
+export function registerModelContext(toolbox: ReturnType<typeof createToolbox>, modelContext?: unknown, onError?: (error: unknown) => void, options?: Omit<import("@jarenjs/contract/webmcp").WebMcpOptions, "context" | "onError">): {
+    ready: Promise<import("@jarenjs/contract/webmcp").WebMcpResult>;
+    dispose: () => Promise<import("@jarenjs/contract/webmcp").WebMcpResult>;
+    readonly status: "disposed" | "failed" | "pending" | "registered" | "unavailable";
+};
+export type ToolDef = {
+    name: string;
+    description: string;
+    /**
+     * - JSON Schema for the arguments object
+     */
+    inputSchema: any;
+    /**
+     * - may return a value or a promise
+     */
+    execute: (input: any) => any;
+};

package/src/toolbox.js

@@ -0,0 +1,178 @@
+//@ts-check
+/**
+ * The toolbox: a registry of tools an AI may call, each declared with
+ * a JSON Schema `inputSchema` that Jaren itself compiles and enforces
+ * before the tool runs — the suite guarding its own tools. One
+ * registry serves every surface that wants to drive the host app:
+ *
+ *  - an embedded agent loop (`toFunctionTools()` produces the OpenAI
+ *    function-calling definitions, `execute()` dispatches a call);
+ *  - a browser-hosted agent over WebMCP (`registerModelContext()`
+ *    publishes the same tools on either browser model-context root).
+ *
+ * `execute` never throws for content-level problems: an unknown tool
+ * or a throwing tool comes back as `{ error }`, invalid input as
+ * `{ error, errors, inputSchema }` plus a `hint` where the model sent
+ * JSON-encoded text for a structured property — results the calling
+ * model can read and recover from.
+ */
+
+import { JarenValidator } from '@jarenjs/validate';
+import { registerWebMcp } from '@jarenjs/contract/webmcp';
+
+import { checkOutcome } from '@jarenjs/core/check';
+import { invalidInput } from '@tangleai/models/check';
+
+/** Whether a property schema asks for structure (object or array). */
+function wantsStructure(schema) {
+  const type = schema?.type;
+  return type === 'object' || type === 'array'
+    || (Array.isArray(type) && (type.includes('object') || type.includes('array')));
+}
+
+/**
+ * The top-level properties that wanted structure but arrived as
+ * strings — after coercion failed, these are what went wrong.
+ * @param {any} inputSchema
+ * @param {any} input
+ * @returns {string[]}
+ */
+function stringStructureKeys(inputSchema, input) {
+  const properties = inputSchema?.properties;
+  if (properties == null || input === null || typeof input !== 'object') return [];
+  return Object.entries(properties)
+    .filter(([key, schema]) => wantsStructure(schema) && typeof input[key] === 'string')
+    .map(([key]) => key);
+}
+
+/**
+ * A copy of `input` with string-valued top-level properties parsed as
+ * JSON wherever the schema wants an object or array — or `null` when
+ * nothing was coercible.
+ * @param {any} inputSchema
+ * @param {any} input
+ * @returns {any | null}
+ */
+function coerceStringArguments(inputSchema, input) {
+  const properties = inputSchema?.properties;
+  if (properties == null || input === null || typeof input !== 'object') return null;
+  let coerced = null;
+  for (const [key, schema] of Object.entries(properties)) {
+    if (!wantsStructure(schema) || typeof input[key] !== 'string') continue;
+    try {
+      const parsed = JSON.parse(input[key]);
+      if (parsed !== null && typeof parsed === 'object') {
+        if (coerced === null) coerced = { ...input };
+        coerced[key] = parsed;
+      }
+    }
+    catch {
+      // not JSON text: keep the original so validation reports it
+    }
+  }
+  return coerced;
+}
+
+/**
+ * @typedef {Object} ToolDef
+ * @property {string} name
+ * @property {string} description
+ * @property {any} inputSchema - JSON Schema for the arguments object
+ * @property {(input: any) => any} execute - may return a value or a promise
+ */
+
+/**
+ * @param {{ validator?: any }} [options] - a shared JarenValidator, if
+ *   the host already has one
+ * @returns {{
+ *   add: (def: ToolDef) => void,
+ *   list: () => { name: string, description: string, inputSchema: any }[],
+ *   toFunctionTools: () => any[],
+ *   execute: (name: string, args: any) => any,
+ * }}
+ */
+export function createToolbox(options = {}) {
+  const jaren = options.validator ?? new JarenValidator({ skipErrors: false, collectErrors: true });
+  /** @type {Map<string, ToolDef & { check: (input: any) => any }>} */
+  const tools = new Map();
+
+  /** @param {ToolDef} def */
+  function add(def) {
+    tools.set(def.name, { ...def, check: jaren.compile(def.inputSchema) });
+  }
+
+  function list() {
+    return [...tools.values()].map(({ name, description, inputSchema }) =>
+      ({ name, description, inputSchema }));
+  }
+
+  function toFunctionTools() {
+    return [...tools.values()].map(({ name, description, inputSchema }) => ({
+      type: 'function',
+      function: { name, description, parameters: inputSchema },
+    }));
+  }
+
+  /**
+   * Dispatch one call. Synchronous tools answer synchronously (WebMCP
+   * hosts call `execute` directly); a promise-returning tool resolves
+   * to its value with rejections folded into `{ error }`. A rejected
+   * call answers `{ error, errors, inputSchema }` — the first
+   * `MAX_INPUT_ERRORS` validation errors plus the schema to re-read —
+   * with a `hint` added when a property wanting structure arrived as
+   * unparseable JSON text.
+   * @param {string} name
+   * @param {any} args
+   */
+  function execute(name, args) {
+    const tool = tools.get(name);
+    if (tool === undefined) return { error: `unknown tool '${name}'` };
+    let input = args ?? {};
+    let outcome = checkOutcome(tool.check(input));
+    if (!outcome.valid) {
+      // models routinely JSON-encode nested arguments; when a property
+      // wanted structure but arrived as parseable JSON text, validate
+      // the parsed value instead — valid or not, its errors point into
+      // the structure the model meant to send
+      const coerced = coerceStringArguments(tool.inputSchema, input);
+      if (coerced !== null) {
+        input = coerced;
+        outcome = checkOutcome(tool.check(coerced));
+      }
+    }
+    if (!outcome.valid) {
+      const stringly = stringStructureKeys(tool.inputSchema, input);
+      return invalidInput(name, outcome, tool.inputSchema,
+        stringly.length === 0 ? {} : {
+          hint: `${stringly.map((k) => `'${k}'`).join(', ')} arrived as a JSON-encoded string that does not parse — pass a real JSON value, not quoted JSON text`,
+        });
+    }
+    try {
+      const value = tool.execute(input);
+      return typeof value?.then === 'function'
+        ? value.then((resolved) => resolved, (/** @type {any} */ err) =>
+          ({ error: err?.message ?? String(err) }))
+        : value;
+    }
+    catch (err) {
+      return { error: /** @type {any} */ (err)?.message ?? String(err) };
+    }
+  }
+
+  return { add, list, toFunctionTools, execute };
+}
+
+/**
+ * Publish validated tools through the shared browser adapter. Await `ready`
+ * for completion and call `dispose` when the host leaves. The optional context
+ * remains the second argument; undefined requests automatic discovery.
+ * @param {ReturnType<typeof createToolbox>} toolbox
+ * @param {unknown} [modelContext]
+ * @param {(error: unknown) => void} [onError]
+ * @param {Omit<import('@jarenjs/contract/webmcp').WebMcpOptions, 'context'|'onError'>} [options]
+ */
+export function registerModelContext(toolbox, modelContext, onError, options = {}) {
+  return registerWebMcp(toolbox.list().map(def => ({ ...def,
+    execute: (args) => toolbox.execute(def.name, args),
+  })), { ...options, ...(modelContext === undefined ? {} : { context: modelContext }), onError });
+}