@theoremjs/agents 0.3.0 → 0.3.2

package/esm/src/kernel/engine/runner/schema-validation.js

@@ -33,7 +33,7 @@ function joinPath(prefix, key) {
     return prefix ? `${prefix}.${key}` : key;
 }
 function pushMissing(path, failures) {
-    failures.push({ path, error: `required field '${path}' is missing` }); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    failures.push({ path, error: `required field '${path}' is missing` }); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
 }
 async function runFieldValidator(path, value, validator, slots, failures) {
     if (!validator) {
@@ -45,7 +45,7 @@ async function runFieldValidator(path, value, validator, slots, failures) {
     }
     failures.push({
         path,
-        error: check.error || check.finding || `Validation failed for '${path}'`, // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        error: check.error || check.finding || `Validation failed for '${path}'`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     });
 }
 async function visitProperty(args) {
@@ -87,7 +87,7 @@ async function walkObject(schema, value, pathPrefix, fields, slots, failures) {
 async function collectValidationFailures(jsonSchema, structured, fields, slots) {
     const root = asObjectSchema(jsonSchema);
     if (!root) {
-        throw new TheoremError('config', 'structured validation requires a JSON Schema object root'); // lexicon-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+        throw new TheoremError('config', 'structured validation requires a JSON Schema object root'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
     }
     const failures = [];
     if (!asRecord(structured)) {
@@ -99,7 +99,81 @@ async function collectValidationFailures(jsonSchema, structured, fields, slots)
     await walkObject(root, structured, '', fields, slots, failures);
     return failures;
 }
+/**
+ * Whether a validator keyed by `path` can run against `jsonSchema`: each segment is a
+ * property or required key of an object schema, as `collectValidationFailures` walks it.
+ */
+function schemaReaches(jsonSchema, path) {
+    let schema = jsonSchema;
+    for (const key of path.split('.')) {
+        const object = asObjectSchema(schema);
+        if (!object) {
+            return false;
+        }
+        const props = propertySchemas(object);
+        if (!Object.hasOwn(props, key) && !requiredKeys(object).includes(key)) {
+            return false;
+        }
+        schema = props[key];
+    }
+    return true;
+}
 function formatValidationFailures(failures) {
     return failures.map((f) => f.error).join('; ');
 }
-export { collectValidationFailures, formatValidationFailures, isAbsent };
+/** The value at a dotted path, reached through object properties only. */
+function valueAt(structured, path) {
+    let value = structured;
+    for (const key of path.split('.')) {
+        value = asRecord(value)?.[key];
+    }
+    return value;
+}
+/** `structured` with the list at `path` replaced; every object on the way is copied. */
+function withListAt(structured, path, list) {
+    const [key, ...rest] = path.split('.');
+    const record = asRecord(structured) ?? {};
+    if (key === undefined)
+        return structured;
+    return {
+        ...record,
+        [key]: rest.length ? withListAt(record[key], rest.join('.'), list) : list,
+    };
+}
+/** Each item an item rule refuses, in the reply's own order. A path with no list has no items. */
+async function collectItemFailures(structured, items, turn) {
+    const failures = [];
+    for (const [path, rule] of Object.entries(items ?? {})) {
+        const list = valueAt(structured, path);
+        if (!Array.isArray(list))
+            continue;
+        for (const [index, item] of list.entries()) {
+            const check = await rule.check(item, turn);
+            if (check.isValid)
+                continue;
+            failures.push({
+                path,
+                index,
+                item,
+                reason: check.error || check.finding || `Validation failed for '${path}'`, // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+                onFail: rule.onFail,
+            });
+        }
+    }
+    return failures;
+}
+/** The schema of one item of the list at `path`, or `undefined` when the path reaches no list with one. */
+function itemSchemaAt(jsonSchema, path) {
+    let schema = jsonSchema;
+    for (const key of path.split('.')) {
+        const object = asObjectSchema(schema);
+        if (!object)
+            return undefined;
+        schema = propertySchemas(object)[key];
+    }
+    const list = asRecord(schema);
+    if (list?.type !== 'array')
+        return undefined;
+    return asRecord(list.items) ?? undefined;
+}
+export { collectItemFailures, collectValidationFailures, formatValidationFailures, isAbsent, itemSchemaAt, schemaReaches, valueAt, withListAt, };

package/esm/src/kernel/engine/runner/stages.d.ts

@@ -20,7 +20,7 @@ export interface ApplyTurnStageResult {
     injectCount: number;
     warnings: StageApplyWarning[];
 }
-/** Injects must arrive sanitized; they are mirrored into an active Interactions continuation too. */
+/** Sanitized stage injects extend portable history. */
 export declare function applyStageInjects(state: StepExecutionState, stage: TurnStage, units: readonly InjectUnit[], extra?: {
     callId?: string;
     toolName?: string;

package/esm/src/kernel/engine/runner/stages.js

@@ -1,19 +1,12 @@
 import { throwIfAborted } from '../../../guardrails/error.js';
 import { injectedStageEvent, injectMessages, runStage, } from '../../stages.js';
 import { profileAllowsInject } from '../../stop.js';
-/** Injects must arrive sanitized; they are mirrored into an active Interactions continuation too. */
+/** Sanitized stage injects extend portable history. */
 export function* applyStageInjects(state, stage, units, extra) {
     const inject = injectMessages(units);
     if (inject.length === 0)
         return 0;
     state.currentHistory.push(...inject);
-    if (state.interactionsContinuation) {
-        for (const msg of inject) {
-            if (msg.role === 'tool')
-                continue;
-            state.interactionsContinuation.messages.push(msg);
-        }
-    }
     const landed = injectedStageEvent(stage, units, extra);
     if (landed) {
         state.allEmittedEvents.push(landed);

package/esm/src/kernel/engine/runner/state.d.ts

@@ -1,9 +1,12 @@
+import { type TurnDestinations } from '../../../guardrails/destinations.js';
 import { type GivenUrlSets } from '../../../guardrails/egress-urls.js';
+import type { OwnTools } from '../../../guardrails/tool-leak.js';
 import type { GuardrailHit, TurnTaint } from '../../../guardrails/types.js';
 import type { SpanHandle } from '../../../observability/trace-span.js';
+import type { AgentCaller } from '../../tools/agent.js';
 import type { ToolRegistry } from '../../tools/registry.js';
-import type { InteractionPart, ModelBinding, Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnRequest, TurnStop } from '../../types.js';
-import type { MediaTokenFamily } from '../token-estimate.js';
+import type { InteractionPart, ModelBinding, Profile, ResolvedGeneration, TurnEvent, TurnHistoryMessage, TurnRequest, TurnStop, TurnToolResult } from '../../types.js';
+import type { ItemFailure } from './schema-validation.js';
 import type { CallUsage } from './usage.js';
 interface TurnTraceState {
     /** The turn's `invoke_agent` span; model calls and tools open under it. */
@@ -16,11 +19,13 @@ interface TurnTraceState {
 interface StepExecutionState {
     /** The turn's scope's tools: calls and provider builtins are looked up here. */
     tools: ToolRegistry;
+    /** Runs the turn's agent tools; absent where none can run (a compactor's own turn). */
+    agents?: AgentCaller;
     trace: TurnTraceState;
     currentHistory: TurnHistoryMessage[];
     stepCount: number;
-    /** Media family of the turn's model binding, for estimating unreported usage. */
-    mediaFamily: MediaTokenFamily | undefined;
+    /** Model calls sent again this turn under the profile's resumption (`executeResumedStep`). */
+    resumes: number;
     allEmittedEvents: TurnEvent[];
     attemptEvents: TurnEvent[];
     /**
@@ -28,6 +33,8 @@ interface StepExecutionState {
      * streamed, so the attempt gate must release the buffered text rather than drop it.
      */
     withheldVisible?: boolean;
+    /** The reply text the stream's gate released this attempt, as it released it. */
+    released: string;
     /** The canary opening the last provider call ended on, read in front of the next call's reply. */
     canaryCarry?: string;
     /** What the last provider call's thoughts ended on, read in front of the next call's thoughts. */
@@ -36,23 +43,37 @@ interface StepExecutionState {
     promptLeaks?: GuardrailHit[];
     /** Untrusted content read so far, so a later tool call is judged against all the turn ingested. */
     taint?: TurnTaint;
+    /** The destinations the turn has read, by who wrote them, so a tool call's own are judged against them. */
+    destinations: TurnDestinations;
     /** Every URL the model has been given this turn (`GuardrailContext.givenUrls`). */
     givenUrls: GivenUrlSets;
+    /** The names of the profile's tools and of their parameters (`GuardrailContext.ownTools`). */
+    ownTools?: OwnTools;
+    /** Set once the model is given the canary this turn (`GuardrailContext.canaryGiven`). */
+    canaryGiven: boolean;
+    /** What the canary scan already read this turn (`requestGivesCanary`). */
+    canaryScanned: WeakSet<object>;
+    /** Every tool call the turn completed, for the checks on a reply's items (`ItemCheckTurn`). */
+    toolResults: TurnToolResult[];
     /** Last provider stop from a discarded provider `done` event. */
     lastStop?: TurnStop;
-    lastInteractionId?: string;
-    /** Tool results and stage injects pending for the next step's Interactions `continuation`. */
-    interactionsContinuation?: {
-        previousInteractionId: string;
-        messages: TurnHistoryMessage[];
-    };
+    providerState?: import('../../checkpoint.js').ProviderCheckpoint;
     /** Usage of the last model call; a continuation's prompt estimate extends it. */
     lastCall?: CallUsage;
 }
+/** A reply waiting on its refused items: the attempt under way is rewriting only those. */
+interface PendingItemFix {
+    /** The reply the items were refused in; the rewritten ones go back into it. */
+    reply: unknown;
+    refused: ItemFailure[];
+    /** The profile's own structured schema, put back once the rewrite returns. */
+    structured: ResolvedGeneration['structured'];
+}
 interface AttemptFlowState {
     currentAttempt: number;
     currentReq: TurnRequest;
     currentGen: ResolvedGeneration;
+    pendingItemFix?: PendingItemFix;
 }
 declare function recordStepEvent(event: TurnEvent, state: StepExecutionState): void;
 /** Append user parts to turn history as one user message (plain text stays a string). */
@@ -69,8 +90,8 @@ declare function openTurnState(args: {
     profile: Profile;
     generation: ResolvedGeneration;
     trace: TurnTraceState;
-    mediaFamily: MediaTokenFamily | undefined;
     allEmittedEvents?: TurnEvent[];
+    agents?: AgentCaller;
 }): StepExecutionState;
-export type { AttemptFlowState, StepExecutionState, TurnTraceState };
+export type { AttemptFlowState, PendingItemFix, StepExecutionState, TurnTraceState };
 export { appendUserInput, openTurnState, recordStepEvent };

package/esm/src/kernel/engine/runner/state.js

@@ -1,4 +1,6 @@
+import { turnDestinations } from '../../../guardrails/destinations.js';
 import { givenUrlSets } from '../../../guardrails/egress-urls.js';
+import { ownToolsOf } from '../../tools/project.js';
 function recordStepEvent(event, state) {
     state.allEmittedEvents.push(event);
     state.attemptEvents.push(event);
@@ -21,15 +23,23 @@ function appendUserInput(state, parts) {
  */
 function openTurnState(args) {
     const { profile, generation } = args;
+    const ownTools = ownToolsOf(args.tools, profile);
     const state = {
         tools: args.tools,
         trace: args.trace,
         currentHistory: [...(generation.history ?? [])],
         stepCount: 0,
-        mediaFamily: args.mediaFamily,
+        resumes: 0,
+        toolResults: [],
         allEmittedEvents: args.allEmittedEvents ?? [],
         attemptEvents: [],
+        released: '',
         givenUrls: givenUrlSets(),
+        destinations: turnDestinations(),
+        canaryGiven: false,
+        canaryScanned: new WeakSet(),
+        ...(ownTools ? { ownTools } : {}),
+        ...(args.agents ? { agents: args.agents } : {}),
     };
     if (profile.type === 'text') {
         appendUserInput(state, generation.input);

package/esm/src/kernel/engine/runner/step-order.d.ts

@@ -0,0 +1,27 @@
+import type { StepWait } from '../../tools/stage-run.js';
+import type { TurnEvent } from '../../types.js';
+/** One step's calls: when each may start, and who waits for whom. */
+export interface StepOrder {
+    /** Resolves when the call may start: at once side by side, once every call before it settles one at a time. */
+    start(callId: string): Promise<void>;
+    /** Marks the call settled; what waits for it goes on. */
+    settle(callId: string): void;
+    wait: StepWait;
+}
+/**
+ * The order of a step's calls. Side by side, every call starts at once. One at a time,
+ * each starts when every call before it has settled. A call whose `pre_tool` answers `waitFor`
+ * is held until those calls settle. A wait on a call outside the step fails; so does a wait
+ * that can never end, because the call waited for waits for this one or runs after it. Every
+ * call whose own wait closes such a loop fails.
+ */
+export declare function stepOrder(callIds: readonly string[], parallel: boolean, signal?: AbortSignal): StepOrder;
+/** Runs a call's body once the step lets it start, and settles it however the body ends. */
+export declare function inStep<T>(order: StepOrder, callId: string, body: () => AsyncGenerator<TurnEvent, T>): AsyncGenerator<TurnEvent, T>;
+/**
+ * Runs tools side by side and passes on each event as it comes. Returns each run's
+ * settlement by its place in `runs`, `undefined` where there was no run.
+ *
+ * why: One run that throws ends them all; the rest are closed so none keeps running unseen.
+ */
+export declare function runSideBySide<T>(runs: (AsyncGenerator<TurnEvent, T | undefined> | undefined)[]): AsyncGenerator<TurnEvent, (T | undefined)[]>;

package/esm/src/kernel/engine/runner/step-order.js

@@ -0,0 +1,165 @@
+import { throwIfAborted } from '../../../guardrails/error.js';
+/**
+ * A promise and the function that settles it. `Promise.withResolvers` would do, but the React
+ * package compiles the kernel against ES2023, which lacks it.
+ */
+function settleable() {
+    let resolve = () => undefined;
+    const promise = new Promise((settle) => {
+        resolve = settle;
+    });
+    return { promise, resolve };
+}
+/**
+ * The order of a step's calls. Side by side, every call starts at once. One at a time,
+ * each starts when every call before it has settled. A call whose `pre_tool` answers `waitFor`
+ * is held until those calls settle. A wait on a call outside the step fails; so does a wait
+ * that can never end, because the call waited for waits for this one or runs after it. Every
+ * call whose own wait closes such a loop fails.
+ */
+export function stepOrder(callIds, parallel, signal) {
+    const settled = new Set();
+    const done = new Map(callIds.map((id) => [id, settleable()]));
+    const waits = new Map();
+    const held = new Map();
+    const unhook = new Map();
+    const earlier = (callId) => (parallel ? [] : callIds.slice(0, callIds.indexOf(callId)));
+    for (const id of callIds) {
+        const before = earlier(id);
+        if (before.length > 0)
+            waits.set(id, new Map(before.map((target) => [target, 'after'])));
+    }
+    /** The calls from `from` to `to` along unsettled waits, or `undefined` when none leads there. */
+    const pathTo = (from, to, seen = new Set()) => {
+        if (from === to)
+            return [to];
+        if (seen.has(from) || settled.has(from))
+            return undefined;
+        seen.add(from);
+        for (const next of waits.get(from)?.keys() ?? []) {
+            const rest = pathTo(next, to, seen);
+            if (rest)
+                return [from, ...rest];
+        }
+        return undefined;
+    };
+    const release = (id, outcome) => {
+        held.get(id)?.(outcome);
+        held.delete(id);
+        unhook.get(id)?.();
+        unhook.delete(id);
+        for (const [target, kind] of waits.get(id) ?? []) {
+            if (kind === 'asked')
+                waits.get(id)?.delete(target);
+        }
+    };
+    const doneOf = (id) => done.get(id)?.promise ?? Promise.resolve();
+    return {
+        start: async (callId) => {
+            await Promise.all(earlier(callId).map(doneOf));
+            throwIfAborted(signal);
+        },
+        settle: (callId) => {
+            settled.add(callId);
+            waits.delete(callId);
+            done.get(callId)?.resolve();
+        },
+        wait: (callId, waitFor) => {
+            const unknown = waitFor.filter((id) => !done.has(id));
+            if (unknown.length > 0) {
+                return Promise.resolve({ ok: false, reason: 'unknown', callIds: unknown });
+            }
+            const pending = waitFor.filter((id) => !settled.has(id));
+            if (pending.length === 0)
+                return Promise.resolve({ ok: true });
+            const own = waits.get(callId) ?? new Map();
+            waits.set(callId, own);
+            for (const id of pending)
+                own.set(id, 'asked');
+            const loops = pending.flatMap((id) => {
+                const path = pathTo(id, callId);
+                return path ? [{ id, path }] : [];
+            });
+            if (loops.length > 0) {
+                // why: Every call whose own wait is part of the loop is held for nothing that can come; each fails.
+                for (const { path } of loops) {
+                    for (const [index, id] of path.entries()) {
+                        const next = path[index + 1];
+                        if (next !== undefined && id !== callId && waits.get(id)?.get(next) === 'asked') {
+                            release(id, { ok: false, reason: 'cycle', callIds: [next] });
+                        }
+                    }
+                }
+                release(callId, { ok: false, reason: 'cycle', callIds: loops.map(({ id }) => id) });
+                return Promise.resolve({
+                    ok: false,
+                    reason: 'cycle',
+                    callIds: loops.map(({ id }) => id),
+                });
+            }
+            const outcome = settleable();
+            held.set(callId, outcome.resolve);
+            Promise.all(pending.map(doneOf)).then(() => release(callId, { ok: true }));
+            const aborted = new Promise((_, reject) => {
+                if (!signal)
+                    return;
+                const onAbort = () => reject(signal.reason);
+                signal.addEventListener('abort', onAbort, { once: true });
+                unhook.set(callId, () => signal.removeEventListener('abort', onAbort));
+            });
+            // why: An aborted turn ends the wait with the abort; the call settles as aborted.
+            aborted.catch(() => { });
+            return Promise.race([outcome.promise, aborted]);
+        },
+    };
+}
+/** Runs a call's body once the step lets it start, and settles it however the body ends. */
+export async function* inStep(order, callId, body) {
+    try {
+        await order.start(callId);
+        return yield* body();
+    }
+    finally {
+        order.settle(callId);
+    }
+}
+/**
+ * Runs tools side by side and passes on each event as it comes. Returns each run's
+ * settlement by its place in `runs`, `undefined` where there was no run.
+ *
+ * why: One run that throws ends them all; the rest are closed so none keeps running unseen.
+ */
+export async function* runSideBySide(runs) {
+    const settled = runs.map(() => undefined);
+    const waiting = new Map();
+    const pull = (index, run) => {
+        const next = run.next().then((result) => ({ index, next: result }));
+        // why: A run that fails after another already threw is closed below; its failure has nowhere to go.
+        next.catch(() => { });
+        waiting.set(index, next);
+    };
+    runs.forEach((run, index) => {
+        if (run)
+            pull(index, run);
+    });
+    try {
+        while (waiting.size > 0) {
+            const { index, next } = await Promise.race(waiting.values());
+            waiting.delete(index);
+            const run = runs[index];
+            if (next.done || !run) {
+                if (next.done)
+                    settled[index] = next.value;
+                continue;
+            }
+            yield next.value;
+            pull(index, run);
+        }
+    }
+    finally {
+        for (const index of waiting.keys()) {
+            runs[index]?.return(undefined).catch(() => { });
+        }
+    }
+    return settled;
+}

package/esm/src/kernel/engine/runner/steps.d.ts

@@ -1,12 +1,12 @@
 import type { BoundSystem } from '../../system-parts.js';
-import type { ModelProvider, Profile, ResolvedGeneration, TurnEvent, TurnRequest } from '../../types.js';
+import type { Profile, ResolvedGeneration, TurnEvent, TurnModel, TurnRequest } from '../../types.js';
 import { type StepExecutionState } from './state.js';
 declare function executeAttempt(args: {
     safe: TurnRequest;
     profile: Profile;
     generation: ResolvedGeneration;
     system: BoundSystem;
-    provider: ModelProvider;
+    provider: TurnModel;
     state: StepExecutionState;
 }): AsyncGenerator<TurnEvent, {
     latestStructured?: unknown;