@theoremjs/agents 0.3.0 → 0.3.1

package/esm/src/kernel/system-parts.js

@@ -4,17 +4,17 @@ function partProblem(part) {
     if (typeof part === 'string')
         return undefined;
     if (typeof part !== 'object' || part === null || Array.isArray(part)) {
-        return 'must be a string or { private: string }'; // lexicon-exempt: developer contract error
+        return 'must be a string or { private: string }'; // labels-exempt: developer contract error
     }
     const keys = Object.keys(part);
     if (keys.length !== 1 || keys[0] !== 'private') {
-        return 'must have exactly one key, private'; // lexicon-exempt: developer contract error
+        return 'must have exactly one key, private'; // labels-exempt: developer contract error
     }
     const text = part.private;
     if (typeof text !== 'string')
-        return 'must be a string'; // lexicon-exempt: developer contract error
+        return 'must be a string'; // labels-exempt: developer contract error
     if (text === '')
-        return 'must not be empty'; // lexicon-exempt: developer contract error
+        return 'must not be empty'; // labels-exempt: developer contract error
     return undefined;
 }
 /** What is wrong with `prompt` as a system prompt, `where` naming it, or undefined. */
@@ -22,9 +22,9 @@ function systemPromptProblem(prompt, where) {
     if (typeof prompt === 'string')
         return undefined;
     if (!Array.isArray(prompt))
-        return `${where} must be a string or an array of parts`; // lexicon-exempt: developer contract error
+        return `${where} must be a string or an array of parts`; // labels-exempt: developer contract error
     if (prompt.length === 0)
-        return `${where} must not be an empty array`; // lexicon-exempt: developer contract error
+        return `${where} must not be an empty array`; // labels-exempt: developer contract error
     for (const [at, part] of prompt.entries()) {
         const problem = partProblem(part);
         if (!problem)

package/esm/src/kernel/tools/activity-label.d.ts

@@ -1,16 +1,22 @@
+/** One line of wording, or a list of lines read top to bottom: the first that fits is shown. */
+export type LabelTemplate = string | readonly string[];
+/** A tool's name as a label shows it: `manage_alert` reads "manage alert". */
+export declare function toolNameInWords(name: string): string;
 /**
- * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a placeholder
- * with no value and no fallback leaves the whole label `undefined`, and the transcript names the tool.
+ * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a line fits
+ * when every placeholder has a value or a fallback and its `when` holds. A list shows its first
+ * line that fits, and a run of `+` lines shows every member that fits, joined in words. When no
+ * line fits the label is `undefined`, and the transcript names the tool.
  */
-export declare function fillActivityLabel(template: string | undefined, values: {
+export declare function fillActivityLabel(template: LabelTemplate | undefined, values: {
     input: unknown;
     output?: unknown;
 }): string | undefined;
 /**
- * Why a label can't fill from these JSON schemas, as a sentence for its author, or `undefined`
- * when every placeholder can. Pass `output` for a Done label.
+ * Why a label can't be used with these JSON schemas, as a sentence for its author, or `undefined`
+ * when it can. Pass `output` for a Done label. A list must end on a line that always fits.
  */
-export declare function activityLabelProblem(template: string, schemas: {
+export declare function activityLabelProblem(template: LabelTemplate, schemas: {
     input: unknown;
     output?: unknown;
 }): string | undefined;

package/esm/src/kernel/tools/activity-label.js

@@ -1,18 +1,21 @@
 import { isRecord } from '../util/record.js';
-const MAX_VALUE_CHARS = 40;
 const PLACEHOLDER = /\{\{?([^{}]*)\}\}?/g;
-// Control and bidi-override characters would let a tool's output restyle or reorder the label.
+// why: Control and bidi-override characters would let a tool's output restyle or reorder the label.
 const UNPRINTABLE = /[\p{Cc}\p{Cf}]/gu;
 const INDEX = /^-?\d+$/;
 const ISO_DATE = /^(\d{4})-(\d{2})-(\d{2})(?:[T ](\d{2}):(\d{2})(?::\d{2}(?:\.\d+)?)?(?:Z|[+-]\d{2}:?\d{2})?)?$/;
 const NUMBER = new Intl.NumberFormat(undefined, { maximumFractionDigits: 2 });
-// Dates show the wall-clock time as the tool wrote it, not converted to the server's zone.
+// why: Dates show the wall-clock time as the tool wrote it, not converted to the server's zone.
 const DAY = new Intl.DateTimeFormat(undefined, { dateStyle: 'medium', timeZone: 'UTC' });
 const DAY_TIME = new Intl.DateTimeFormat(undefined, {
     dateStyle: 'medium',
     timeStyle: 'short',
     timeZone: 'UTC',
 });
+const JOINED = /^\+\s+/;
+/** The colon that ends a line's condition: the first one followed by a space or the line's end. */
+const WHEN_ENDS = /:(?:\s|$)/;
+const CHECK = /^(\S+) is (?:(not) )?(\S.*)$/;
 function parsePlaceholder(raw) {
     const bar = raw.indexOf('|');
     if (bar < 0)
@@ -64,22 +67,75 @@ function labelValue(value) {
     if (typeof value !== 'string')
         return undefined;
     const text = value.replace(UNPRINTABLE, ' ').replace(/\s+/g, ' ').trim();
-    const chars = [...(dateText(text) ?? text)];
-    if (chars.length === 0)
-        return undefined;
-    if (chars.length <= MAX_VALUE_CHARS)
-        return chars.join('');
-    const head = chars.slice(0, MAX_VALUE_CHARS - 1).join('');
-    return `${head.trimEnd()}…`;
+    return (dateText(text) ?? text) || undefined;
 }
-/**
- * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a placeholder
- * with no value and no fallback leaves the whole label `undefined`, and the transcript names the tool.
- */
-export function fillActivityLabel(template, values) {
-    if (!template?.trim())
-        return undefined;
-    const sides = 'output' in values ? ['input', 'output'] : ['input'];
+function parseChecks(raw) {
+    const checks = [];
+    // why: one space between words first, so no pattern below can try a run of spaces two ways.
+    for (const part of raw.replace(/\s+/g, ' ').split(' and ')) {
+        const match = CHECK.exec(part.trim());
+        const [, path, not, expected] = match ?? [];
+        if (!path || !expected)
+            return 'unreadable';
+        const literal = expected.trim();
+        checks.push({ path, negated: Boolean(not), expected: literal === 'null' ? null : literal });
+    }
+    return checks;
+}
+/** `+ when status is archived: archiving {name}` is a joined line, with one check, then its text. */
+function parseLine(raw) {
+    const joined = JOINED.test(raw);
+    const rest = raw.replace(JOINED, '').trim();
+    if (!/^when(\s|$)/.test(rest))
+        return { joined, when: [], text: rest };
+    const end = rest.search(WHEN_ENDS);
+    if (end < 0)
+        return { joined, when: 'unreadable', text: '' };
+    return { joined, when: parseChecks(rest.slice(4, end)), text: rest.slice(end + 1).trim() };
+}
+function entriesOf(template) {
+    const raw = typeof template === 'string' ? [template] : template;
+    const entries = [];
+    raw.forEach((text, index) => {
+        const line = parseLine(text);
+        const last = entries.at(-1);
+        if (line.joined && last?.joined)
+            last.lines.push({ line, number: index + 1 });
+        else
+            entries.push({ joined: line.joined, lines: [{ line, number: index + 1 }] });
+    });
+    return entries;
+}
+/** The input keys a check reads, or `undefined` when it names the output. */
+function checkKeys(path) {
+    const [route] = routes(path, ['input']);
+    return route?.side === 'input' ? route.keys : undefined;
+}
+// why: "is not" is the plain opposite of "is", so a field the model left out is not any value.
+function checkHolds(check, input) {
+    const keys = checkKeys(check.path);
+    if (!keys)
+        return false;
+    const value = valueAt(input, keys);
+    const comparable = typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean';
+    const is = check.expected === null ? value === null : comparable && `${value}` === check.expected;
+    return is !== check.negated;
+}
+/** "a", "a and b", "a, b, and c". */
+function joinedInWords(parts) {
+    if (parts.length <= 1)
+        return parts[0] ?? '';
+    return `${parts.slice(0, -1).join(', ')}${parts.length > 2 ? ',' : ''} and ${parts.at(-1)}`;
+}
+/** A tool's name as a label shows it: `manage_alert` reads "manage alert". */
+export function toolNameInWords(name) {
+    return name
+        .replace(/([a-z\d])([A-Z])/g, '$1 $2')
+        .replace(/[_-]+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+function fillText(template, values, sides) {
     let missing = false;
     const filled = template.replace(PLACEHOLDER, (_, raw) => {
         const { path, fallback } = parsePlaceholder(raw);
@@ -95,6 +151,30 @@ export function fillActivityLabel(template, values) {
     const text = filled.replace(/\s+/g, ' ').trim();
     return missing || !text ? undefined : text;
 }
+/**
+ * Fills each `{path}` or `{path|fallback}` from the call. Only text and numbers fill; a line fits
+ * when every placeholder has a value or a fallback and its `when` holds. A list shows its first
+ * line that fits, and a run of `+` lines shows every member that fits, joined in words. When no
+ * line fits the label is `undefined`, and the transcript names the tool.
+ */
+export function fillActivityLabel(template, values) {
+    if (template === undefined)
+        return undefined;
+    const sides = 'output' in values ? ['input', 'output'] : ['input'];
+    for (const entry of entriesOf(template)) {
+        const fitting = entry.lines.flatMap(({ line }) => {
+            if (line.when === 'unreadable')
+                return [];
+            if (!line.when.every((check) => checkHolds(check, values.input)))
+                return [];
+            const text = fillText(line.text, values, sides);
+            return text === undefined ? [] : [text];
+        });
+        if (fitting.length)
+            return joinedInWords(fitting);
+    }
+    return undefined;
+}
 const HOLDS_RANK = ['value', 'group', 'flag', 'missing'];
 function schemaTypes(node) {
     const types = Array.isArray(node.type) ? node.type : [node.type];
@@ -128,10 +208,18 @@ function leavesAt(node, path) {
     const types = schemaTypes(node);
     if (types.length && types.every((type) => type === 'boolean'))
         return [];
-    const group = types.includes('array') || types.includes('object') || schemaBranches(node).length;
+    const branches = schemaBranches(node);
+    // why: A branch of text or null (a nullable field) is still one value a label can show.
+    const nested = branches.some((branch) => schemaTypes(branch).some((type) => type === 'array' || type === 'object'));
+    const group = types.includes('array') || types.includes('object') || nested;
+    if (!group && branches.length) {
+        return branches.every((branch) => schemaTypes(branch).every((type) => type === 'boolean'))
+            ? []
+            : [path];
+    }
     return group ? placeholdersAt(node, path) : [path];
 }
-// A schema that doesn't say what's there ($ref, no properties, no items) is taken on trust.
+// why: A schema that doesn't say what's there ($ref, no properties, no items) is taken on trust.
 function schemaPathHolds(node, keys, walked) {
     if (!isRecord(node) || '$ref' in node)
         return { holds: 'value' };
@@ -169,27 +257,24 @@ function tryInstead(paths) {
     const shown = [...new Set(paths)].slice(0, 4).map((path) => `{${path}}`);
     if (shown.length === 0)
         return '';
-    const list = shown.length === 1 ? shown[0] : `${shown.slice(0, -1).join(', ')} or ${shown.at(-1)}`;
+    const list = shown.length === 1
+        ? shown[0]
+        : `${shown.slice(0, -1).join(', ')}${shown.length > 2 ? ',' : ''} or ${shown.at(-1)}`;
     return ` Try ${list}.`;
 }
-/**
- * Why a label can't fill from these JSON schemas, as a sentence for its author, or `undefined`
- * when every placeholder can. Pass `output` for a Done label.
- */
-export function activityLabelProblem(template, schemas) {
-    const sides = 'output' in schemas ? ['input', 'output'] : ['input'];
+function placeholderProblem(template, schemas, sides) {
     for (const match of template.matchAll(PLACEHOLDER)) {
         const { path } = parsePlaceholder(match[1] ?? '');
         if (!path) {
             const example = placeholdersAt(schemas.input, '')[0] ?? 'name';
-            return `Put a field name between the braces, like {${example}}.`; // lexicon-exempt: builder diagnostic
+            return `Put a field name between the braces, like {${example}}.`; // labels-exempt: builder diagnostic
         }
         const paths = routes(path, sides);
         const [route] = paths;
         if (!route)
             continue;
         if (route.prefixed && !sides.includes(route.side)) {
-            return `{${path}} is only there once the call is done; use it in the Done label.`; // lexicon-exempt: builder diagnostic
+            return `{${path}} is only there once the call is done; use it in the Done label.`; // labels-exempt: builder diagnostic
         }
         const found = mergeHolds(paths.map(({ side, keys, prefixed }) => schemaPathHolds(schemas[side], keys, prefixed ? side : '')));
         if (found.holds === 'value')
@@ -199,11 +284,152 @@ export function activityLabelProblem(template, schemas) {
         const near = all.filter((candidate) => candidate.split('.')[depth] === route.keys[0]);
         const from = route.prefixed ? route.side : sides.join(' or ');
         const reason = {
-            missing: `is not a field of this tool's ${from}.`, // lexicon-exempt: builder diagnostic
-            group: 'is a list or group; a label shows text or a number.', // lexicon-exempt: builder diagnostic
-            flag: 'is true or false; a label shows text or a number.', // lexicon-exempt: builder diagnostic
+            missing: `is not a field of this tool's ${from}.`, // labels-exempt: builder diagnostic
+            group: 'is a list or group; a label shows text or a number.', // labels-exempt: builder diagnostic
+            flag: 'is true or false; a label shows text or a number.', // labels-exempt: builder diagnostic
         }[found.holds];
         return `{${path}} ${reason}${tryInstead(near.length ? near : all)}`;
     }
     return undefined;
 }
+const OPEN_LEAF = { texts: 'any', nullable: true };
+function rawTypes(node) {
+    const types = Array.isArray(node.type) ? node.type : [node.type];
+    return types.filter((type) => typeof type === 'string');
+}
+function leafOf(node) {
+    const listed = Array.isArray(node.enum) ? node.enum : 'const' in node ? [node.const] : undefined;
+    if (listed) {
+        return {
+            texts: listed.filter((value) => value !== null).map((value) => `${value}`),
+            nullable: listed.includes(null),
+        };
+    }
+    const types = rawTypes(node);
+    if (types.length === 0)
+        return OPEN_LEAF;
+    const shown = types.filter((type) => type !== 'null');
+    const flag = shown.every((type) => type === 'boolean');
+    return {
+        texts: flag ? (shown.length ? ['true', 'false'] : []) : 'any',
+        nullable: types.includes('null'),
+    };
+}
+// why: A schema that doesn't say what's there ($ref, no properties, no items) is taken on trust.
+function schemaLeavesAt(node, keys) {
+    if (!isRecord(node) || '$ref' in node)
+        return [OPEN_LEAF];
+    const branches = schemaBranches(node);
+    if (branches.length)
+        return branches.flatMap((branch) => schemaLeavesAt(branch, keys));
+    const [key, ...rest] = keys;
+    if (key === undefined)
+        return [leafOf(node)];
+    const types = schemaTypes(node);
+    if (types.includes('array')) {
+        if (key === 'length')
+            return rest.length ? [] : [{ texts: 'any', nullable: false }];
+        if (INDEX.test(key))
+            return schemaLeavesAt(node.items, rest);
+    }
+    if (isRecord(node.properties)) {
+        return Object.hasOwn(node.properties, key) ? schemaLeavesAt(node.properties[key], rest) : [];
+    }
+    return types.length === 0 && rawTypes(node).length === 0 ? [OPEN_LEAF] : [];
+}
+/** The input's own field names, flags included: what a `when` can compare. */
+function inputFields(node) {
+    if (!isRecord(node))
+        return [];
+    const branches = schemaBranches(node).flatMap(inputFields);
+    const own = isRecord(node.properties) ? Object.keys(node.properties) : [];
+    return [...new Set([...own, ...branches])];
+}
+function oneOf(values) {
+    const shown = [...new Set(values)].map((value) => `"${value}"`);
+    return shown.length <= 1
+        ? (shown[0] ?? '')
+        : `${shown.slice(0, -1).join(', ')}${shown.length > 2 ? ',' : ''} or ${shown.at(-1)}`;
+}
+function checkProblem(check, input) {
+    const keys = checkKeys(check.path);
+    if (!keys) {
+        return `A "when" reads what the model sent; "${check.path}" is only there once the call is done.`; // labels-exempt: builder diagnostic
+    }
+    const found = schemaPathHolds(input, keys, '');
+    if (found.holds === 'missing') {
+        const fields = inputFields(input).slice(0, 4);
+        const tryThese = fields.length ? ` Try ${oneOf(fields)}.` : ''; // labels-exempt: builder diagnostic
+        return `"${check.path}" in the "when" is not a field of this tool's input.${tryThese}`; // labels-exempt: builder diagnostic
+    }
+    if (found.holds === 'group') {
+        return `"${check.path}" in the "when" is a list or group; a "when" compares text, a number, or true or false.`; // labels-exempt: builder diagnostic
+    }
+    const leaves = schemaLeavesAt(input, keys);
+    if (check.expected === null) {
+        return leaves.some((leaf) => leaf.nullable) ? undefined : `"${check.path}" is never null.`; // labels-exempt: builder diagnostic
+    }
+    const texts = [];
+    for (const leaf of leaves) {
+        if (leaf.texts === 'any')
+            return undefined;
+        texts.push(...leaf.texts);
+    }
+    if (texts.includes(check.expected))
+        return undefined;
+    const itIs = texts.length ? ` It is ${oneOf(texts)}.` : ''; // labels-exempt: builder diagnostic
+    return `"${check.path}" is never "${check.expected}".${itIs}`; // labels-exempt: builder diagnostic
+}
+function lineProblem(line, schemas, sides, mustShow) {
+    if (line.when === 'unreadable') {
+        return 'A line that opens with "when" needs a condition and a colon, like "when status is archived: archiving {name}". A condition uses "is", "is not", "is null", and "and".'; // labels-exempt: builder diagnostic
+    }
+    for (const check of line.when) {
+        const problem = checkProblem(check, schemas.input);
+        if (problem)
+            return problem;
+    }
+    if (!line.text && (mustShow || line.when.length)) {
+        return 'It has no wording to show.'; // labels-exempt: builder diagnostic
+    }
+    return placeholderProblem(line.text, schemas, sides);
+}
+/** Whether a line shows for every call: no `when`, and a fallback on every placeholder. */
+function alwaysFits(line) {
+    if (line.when === 'unreadable' || line.when.length)
+        return false;
+    let open = false;
+    const settled = line.text.replace(PLACEHOLDER, (_, raw) => {
+        const { fallback } = parsePlaceholder(raw);
+        if (fallback === undefined)
+            open = true;
+        return fallback ?? '';
+    });
+    return !open && settled.trim().length > 0;
+}
+function listProblem(entries) {
+    const fits = entries.map((entry) => entry.lines.some(({ line }) => alwaysFits(line)));
+    const early = fits.slice(0, -1).indexOf(true);
+    if (early >= 0) {
+        const number = entries[early]?.lines.find(({ line }) => alwaysFits(line))?.number;
+        return `Line ${number} always fits, so the lines below it are never read. Move it to the end.`; // labels-exempt: builder diagnostic
+    }
+    if (fits.at(-1))
+        return undefined;
+    return 'The last line must always fit, so every call gets a label: no "when", and a fallback on every {value}, like "saving the item".'; // labels-exempt: builder diagnostic
+}
+/**
+ * Why a label can't be used with these JSON schemas, as a sentence for its author, or `undefined`
+ * when it can. Pass `output` for a Done label. A list must end on a line that always fits.
+ */
+export function activityLabelProblem(template, schemas) {
+    const sides = 'output' in schemas ? ['input', 'output'] : ['input'];
+    const listed = typeof template !== 'string';
+    const entries = entriesOf(template);
+    for (const { line, number } of entries.flatMap((entry) => entry.lines)) {
+        const problem = lineProblem(line, schemas, sides, listed);
+        if (problem)
+            return listed ? `Line ${number}: ${problem}` : problem; // labels-exempt: builder diagnostic
+    }
+    return listed ? listProblem(entries) : undefined;
+}

package/esm/src/kernel/tools/agent.d.ts

@@ -0,0 +1,66 @@
+import { z } from 'zod';
+import type { ToolOrigin } from '../../guardrails/types.js';
+import type { SpanHandle } from '../../observability/trace-span.js';
+import type { Profile, ProfileId, ProfileInputsSpec, TurnEvent, TurnTokens } from '../types.js';
+import type { AgentToolDef, AgentToolInput, AgentToolOutput, RegisteredAgentTool, RegisteredTool, ToolFailure } from './types.js';
+/** How one agent tool call settled, with what the called agent used. */
+type AgentRun = {
+    output: AgentToolOutput;
+    tokens?: TurnTokens;
+} | {
+    failure: ToolFailure;
+    tokens?: TurnTokens;
+};
+/** Runs agent tool calls for one turn, which supplies the scope, provider, and hook. */
+interface AgentCaller {
+    run(call: {
+        tool: RegisteredAgentTool;
+        callId: string;
+        input: AgentToolInput;
+        caller: Profile;
+        /** The call's `execute_tool` span; the agent's turn opens under it. */
+        span?: SpanHandle;
+        signal?: AbortSignal;
+    }): AsyncGenerator<TurnEvent, AgentRun>;
+}
+/** A call that settled without a reply; the model reads `failure`. */
+declare class AgentCallFailed extends Error {
+    readonly failure: ToolFailure;
+    constructor(failure: ToolFailure);
+}
+/**
+ * What the model sent, split into what goes to the called agent and what only the host reads.
+ *
+ * why: A host field is the host's own word for something (an id it resolves); the called profile does not take it, so it never reaches the agent's turn.
+ */
+declare function splitHostInput(tool: Pick<AgentToolDef, 'hostFields'>, input: AgentToolInput): {
+    sent: AgentToolInput;
+    hostInput?: Record<string, unknown>;
+};
+/**
+ * The input of an agent tool that runs `agent`: text, and each channel the
+ * profile's `inputs` declares. Anything else is refused, never dropped. The
+ * called turn's own ingress checks MIME types and sizes.
+ */
+declare function agentToolInputFor(agent: Pick<Profile, 'type'> & {
+    inputs?: Pick<ProfileInputsSpec, 'attachments' | 'voice' | 'slots'>;
+}, tool?: Pick<AgentToolDef, 'name' | 'fieldText' | 'hostFields' | 'hostOnly'>): z.ZodType<AgentToolInput>;
+declare const agentToolOutput: z.ZodType<AgentToolOutput>;
+/** Why `profile` can't be run by an agent tool, or `undefined` when it can. */
+declare function agentProfileProblem(profile: Profile, find: (name: string) => RegisteredTool | undefined): string | undefined;
+/** The profile an agent tool runs; throws `config` when the tool can't run it. */
+declare function agentToolProfile(def: AgentToolDef, findProfile: (id: ProfileId) => Profile | undefined, findTool: (name: string) => RegisteredTool | undefined): Profile;
+/** An agent with no tools of its own read only what it was sent; one with tools may have read outside content. */
+declare function agentToolOrigin(profile: Profile | undefined): ToolOrigin;
+/**
+ * The called agent's reply: its text or its last structured reply, its media as parts, and what it cited.
+ *
+ * why: A structured reply's text is the same JSON as a string, so returning both would have the caller's model read the answer twice.
+ */
+declare function agentToolOutputOf(turn: readonly TurnEvent[]): AgentToolOutput;
+declare function normalizeAgent(def: AgentToolDef, input: z.ZodType<AgentToolInput>, schemas: {
+    inputSchema: Record<string, unknown>;
+    outputSchema: Record<string, unknown>;
+}): RegisteredAgentTool;
+export type { AgentCaller, AgentRun };
+export { AgentCallFailed, agentProfileProblem, agentToolInputFor, agentToolOrigin, agentToolOutput, agentToolOutputOf, agentToolProfile, normalizeAgent, splitHostInput, };