@theoremjs/agents 0.0.0-stage → 0.3.1

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

@@ -0,0 +1,134 @@
+import { errorCopyText, isAbortError, TheoremError, throwIfAborted, toErrorEvent, } from '../../../guardrails/error.js';
+import { labelText } from '../../../guardrails/labels.js';
+import { nestedTurnModel, resolveRegisteredTurnModel } from '../../provider-dispatch.js';
+import { agentProfileProblem, agentToolOutputOf, splitHostInput, } from '../../tools/agent.js';
+import { findLast } from '../../util/find-last.js';
+import { sumEventTokens } from '../usage.js';
+/** Errors only the host can fix: a nested turn throws them rather than failing quietly every call. */
+const NESTED_THROWS = new Set(['config', 'request', 'auth', 'internal']);
+function turnError(events) {
+    return events.find((e) => e.type === 'error');
+}
+/**
+ * Agent tool calls for one turn. `own` is the turn's model binding: its
+ * provider runs a called agent on the same provider and protocol, and the
+ * host's hook supplies any other. Without `own` (an invoke) the provider is
+ * the host's own choice and runs as given.
+ */
+function createAgentCaller(args) {
+    const calls = new Map();
+    const { registry, req } = args;
+    return {
+        async *run({ tool, callId, input, caller, span, signal }) {
+            const labels = caller.labels;
+            const settled = (code, kind, message) => ({
+                failure: { code, kind, message },
+            });
+            const made = calls.get(tool.name) ?? 0;
+            if (tool.maxCallsPerTurn !== undefined && made >= tool.maxCallsPerTurn) {
+                return settled('call_limit', 'declined', labelText('tool.agent_call_limit', { tool: tool.name }, labels));
+            }
+            calls.set(tool.name, made + 1);
+            const profile = registry.profiles.get(tool.profile);
+            const problem = agentProfileProblem(profile, (name) => registry.tools.get(name));
+            if (problem) {
+                throw new TheoremError('config', `Agent tool "${tool.name}" can't run '${tool.profile}': ${problem}`);
+            }
+            const { sent: modelInput, hostInput } = splitHostInput(tool, input);
+            if (hostInput && !req.onAgentCall) {
+                throw new TheoremError('config', `Agent tool "${tool.name}" declares host fields, which need the request's onAgentCall`);
+            }
+            const shaped = await req.onAgentCall?.({
+                tool: tool.name,
+                callId,
+                profile: tool.profile,
+                input: modelInput,
+                ...(hostInput ? { hostInput } : {}),
+                caller: caller.id,
+                depth: args.depth + 1,
+                ...(req.metadata ? { metadata: req.metadata } : {}),
+                ...(signal ? { signal } : {}),
+            });
+            if (shaped && 'refuse' in shaped) {
+                return settled('refused_by_host', 'declined', shaped.refuse);
+            }
+            const { provider: hostProvider, ...fields } = shaped ?? {};
+            const provider = agentProvider(args, profile.id, fields.model, hostProvider);
+            if (!span) {
+                throw new TheoremError('internal', `Agent tool "${tool.name}" ran without a span`); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+            }
+            const { speech, ...sent } = modelInput;
+            const events = [];
+            try {
+                for await (const event of args.runNested({
+                    req: {
+                        ...(speech ? { speech } : {}),
+                        ...fields,
+                        profile: tool.profile,
+                        execution: req.execution,
+                        pageExecution: req.pageExecution,
+                        input: fields.input ?? sent,
+                        ...(signal ? { signal } : {}),
+                        ...(req.onAgentCall ? { onAgentCall: req.onAgentCall } : {}),
+                    },
+                    provider,
+                    parent: span,
+                    agentDepth: args.depth + 1,
+                })) {
+                    events.push(event);
+                    yield event;
+                }
+            }
+            catch (err) {
+                // why: A turn refused before it starts (a file the agent does not take) throws; the caller's model reads it like any other failed call.
+                if (!(err instanceof TheoremError) || NESTED_THROWS.has(err.kind) || isAbortError(err)) {
+                    throw err;
+                }
+                events.push(toErrorEvent(err));
+            }
+            throwIfAborted(signal);
+            return agentRunOf(events, tool.name, tool.profile, labels);
+        },
+    };
+}
+/** The provider an agent's turn runs on: the host's for this call, else the caller's, else the registry's. */
+function agentProvider(from, profileId, model, hostProvider) {
+    if (hostProvider)
+        return resolveRegisteredTurnModel(from.registry, profileId, model, hostProvider);
+    if (from.provider)
+        return nestedTurnModel(from.provider, profileId, model);
+    return resolveRegisteredTurnModel(from.registry, profileId, model, {});
+}
+/** The agent's reply, or why there is none. Errors only the host can fix are thrown. */
+function agentRunOf(events, toolName, profileId, labels) {
+    const done = findLast(events, (e) => e.type === 'done');
+    const tokens = done?.tokens ?? sumEventTokens(events);
+    const usage = tokens ? { tokens } : {};
+    const reported = turnError(events);
+    if (reported && NESTED_THROWS.has(reported.errorKind)) {
+        throw new TheoremError(reported.errorKind, `Agent '${profileId}' failed: ${reported.errorInternal ?? reported.error}`);
+    }
+    const stop = done?.stop.kind;
+    if (stop !== 'completed' || reported) {
+        const failed = labelText('tool.agent_failed', { tool: toolName }, labels);
+        // why: Reasons the agent's turn named (a file it does not take, a model that is busy) let the caller's model correct the call or say why.
+        const reason = reported?.errorCopy
+            ? errorCopyText(reported.errorCopy, labels)
+            : reported?.error;
+        return {
+            failure: {
+                code: 'agent_failed',
+                kind: reported?.errorKind ?? 'failed',
+                message: reason ? `${failed}\n${reason}` : failed,
+                details: {
+                    agent: profileId,
+                    ...(stop ? { stop } : {}),
+                    ...(reported?.errorCopy ? { reasons: reported.errorCopy } : {}),
+                },
+            },
+            ...usage,
+        };
+    }
+    return { output: agentToolOutputOf(events), ...usage };
+}
+export { createAgentCaller, NESTED_THROWS, turnError };

package/esm/src/kernel/engine/runner/schema-validation.d.ts

@@ -0,0 +1,35 @@
+import type { ItemCheckTurn, ProfileItemRule, ProfileValidator } from '../../types.js';
+interface ValidationFailure {
+    path: string;
+    error: string;
+}
+declare function isAbsent(value: unknown): boolean;
+/**
+ * Required vs optional comes only from the JSON Schema; host field validators run for required
+ * paths and for optional paths that are present. Throws when the root is not an object schema.
+ */
+declare function collectValidationFailures(jsonSchema: Record<string, unknown>, structured: unknown, fields: Record<string, ProfileValidator> | undefined, slots?: Record<string, string>): Promise<ValidationFailure[]>;
+/**
+ * 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.
+ */
+declare function schemaReaches(jsonSchema: Record<string, unknown>, path: string): boolean;
+declare function formatValidationFailures(failures: ValidationFailure[]): string;
+/** One list item an item rule refused: where it sat, the item, and why. */
+interface ItemFailure {
+    path: string;
+    index: number;
+    item: unknown;
+    reason: string;
+    onFail: ProfileItemRule['onFail'];
+}
+/** The value at a dotted path, reached through object properties only. */
+declare function valueAt(structured: unknown, path: string): unknown;
+/** `structured` with the list at `path` replaced; every object on the way is copied. */
+declare function withListAt(structured: unknown, path: string, list: unknown[]): unknown;
+/** Each item an item rule refuses, in the reply's own order. A path with no list has no items. */
+declare function collectItemFailures(structured: unknown, items: Record<string, ProfileItemRule> | undefined, turn: ItemCheckTurn): Promise<ItemFailure[]>;
+/** The schema of one item of the list at `path`, or `undefined` when the path reaches no list with one. */
+declare function itemSchemaAt(jsonSchema: Record<string, unknown>, path: string): Record<string, unknown> | undefined;
+export type { ItemFailure, ValidationFailure };
+export { collectItemFailures, collectValidationFailures, formatValidationFailures, isAbsent, itemSchemaAt, schemaReaches, valueAt, withListAt, };

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

@@ -0,0 +1,179 @@
+import { TheoremError } from '../../../guardrails/error.js';
+function isAbsent(value) {
+    return value === undefined || value === null;
+}
+function asRecord(value) {
+    if (isAbsent(value) || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function asObjectSchema(schema) {
+    const rec = asRecord(schema);
+    if (!rec) {
+        return null;
+    }
+    if (rec.type !== undefined && rec.type !== 'object') {
+        return null;
+    }
+    return rec;
+}
+function requiredKeys(schema) {
+    const raw = schema.required;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    return raw.filter((k) => typeof k === 'string');
+}
+function propertySchemas(schema) {
+    const props = schema.properties;
+    return asRecord(props) ?? {};
+}
+function joinPath(prefix, key) {
+    return prefix ? `${prefix}.${key}` : key;
+}
+function pushMissing(path, failures) {
+    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) {
+        return;
+    }
+    const check = await validator(value, slots);
+    if (check.isValid) {
+        return;
+    }
+    failures.push({
+        path,
+        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) {
+    const { path, propSchema, child, isRequired, fields, slots, failures } = args;
+    if (isAbsent(child)) {
+        if (isRequired) {
+            pushMissing(path, failures);
+        }
+        return;
+    }
+    await runFieldValidator(path, child, fields?.[path], slots, failures);
+    const nested = asObjectSchema(propSchema);
+    const nestedValue = nested ? asRecord(child) : null;
+    if (nested && nestedValue) {
+        await walkObject(nested, nestedValue, path, fields, slots, failures);
+    }
+}
+async function walkObject(schema, value, pathPrefix, fields, slots, failures) {
+    const props = propertySchemas(schema);
+    const required = new Set(requiredKeys(schema));
+    const keys = new Set([...Object.keys(props), ...required]);
+    const record = asRecord(value);
+    for (const key of keys) {
+        await visitProperty({
+            path: joinPath(pathPrefix, key),
+            propSchema: props[key],
+            child: record?.[key],
+            isRequired: required.has(key),
+            fields,
+            slots,
+            failures,
+        });
+    }
+}
+/**
+ * Required vs optional comes only from the JSON Schema; host field validators run for required
+ * paths and for optional paths that are present. Throws when the root is not an object schema.
+ */
+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'); // labels-exempt: developer contract / internal diagnostic — not end-user or model copy (P2)
+    }
+    const failures = [];
+    if (!asRecord(structured)) {
+        for (const key of requiredKeys(root)) {
+            pushMissing(key, failures);
+        }
+        return failures;
+    }
+    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('; ');
+}
+/** 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

@@ -0,0 +1,28 @@
+import { type InjectUnit, type StageApplyWarning, type StageCallBag, type StageContext, type StageHandler } from '../../stages.js';
+import type { Profile, ResolvedGeneration, TurnEvent, TurnStage } from '../../types.js';
+import type { StepExecutionState } from './state.js';
+export interface ApplyTurnStageArgs extends StageCallBag {
+    profile: Profile;
+    generation: ResolvedGeneration;
+    state: StepExecutionState;
+    stage: StageContext['stage'];
+    step: number;
+    onStage?: StageHandler;
+    signal?: AbortSignal;
+    /** Another provider step would exceed maxSteps — reject inject. */
+    injectWouldExceedMaxSteps?: boolean;
+    host?: unknown;
+}
+export interface ApplyTurnStageResult {
+    abort?: boolean | {
+        reason?: string;
+    };
+    injectCount: number;
+    warnings: StageApplyWarning[];
+}
+/** Sanitized stage injects extend portable history. */
+export declare function applyStageInjects(state: StepExecutionState, stage: TurnStage, units: readonly InjectUnit[], extra?: {
+    callId?: string;
+    toolName?: string;
+}): Generator<TurnEvent, number>;
+export declare function applyTurnStage(args: ApplyTurnStageArgs): AsyncGenerator<TurnEvent, ApplyTurnStageResult>;

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

@@ -0,0 +1,41 @@
+import { throwIfAborted } from '../../../guardrails/error.js';
+import { injectedStageEvent, injectMessages, runStage, } from '../../stages.js';
+import { profileAllowsInject } from '../../stop.js';
+/** 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);
+    const landed = injectedStageEvent(stage, units, extra);
+    if (landed) {
+        state.allEmittedEvents.push(landed);
+        yield landed;
+    }
+    return inject.length;
+}
+export async function* applyTurnStage(args) {
+    const { profile, generation, state, onStage, host, ...call } = args;
+    throwIfAborted(call.signal);
+    const run = runStage({
+        ...call,
+        history: state.currentHistory,
+        handlers: onStage ? [onStage] : [],
+        guardrails: profile.guardrails,
+        injectAllowed: profileAllowsInject(profile),
+        host: host ?? generation.host,
+        span: state.trace.root,
+    });
+    let next = await run.next();
+    while (!next.done) {
+        state.allEmittedEvents.push(next.value);
+        yield next.value;
+        next = await run.next();
+    }
+    const out = next.value;
+    return {
+        abort: out.abort,
+        injectCount: yield* applyStageInjects(state, call.stage, out.inject),
+        warnings: out.warnings,
+    };
+}

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

@@ -0,0 +1,97 @@
+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, 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. */
+    root: SpanHandle;
+    /** Validation / egress attempt the next model call belongs to (0-based). */
+    attempt: number;
+    calls: number;
+    binding: ModelBinding | undefined;
+}
+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;
+    /** Model calls sent again this turn under the profile's resumption (`executeResumedStep`). */
+    resumes: number;
+    allEmittedEvents: TurnEvent[];
+    attemptEvents: TurnEvent[];
+    /**
+     * If the mid-stream window tripped but the final verdict on the whole text passes, nothing was
+     * 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. */
+    thoughtCarry?: string;
+    /** System-prompt leaks withheld under a host policy; they pin the end-of-attempt verdict to block. */
+    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;
+    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). */
+declare function appendUserInput(state: StepExecutionState, parts: readonly InteractionPart[]): void;
+/**
+ * Step state for one turn. A text turn's history grows inside the turn (tool
+ * steps, stage injects, repair retries), so its opening input moves into turn
+ * history here and everything later lands after it; `generation.input` is then
+ * empty. Image and speech turns are one call that reads only the input, so
+ * theirs stays put.
+ */
+declare function openTurnState(args: {
+    tools: ToolRegistry;
+    profile: Profile;
+    generation: ResolvedGeneration;
+    trace: TurnTraceState;
+    allEmittedEvents?: TurnEvent[];
+    agents?: AgentCaller;
+}): StepExecutionState;
+export type { AttemptFlowState, PendingItemFix, StepExecutionState, TurnTraceState };
+export { appendUserInput, openTurnState, recordStepEvent };

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

@@ -0,0 +1,50 @@
+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);
+}
+/** Append user parts to turn history as one user message (plain text stays a string). */
+function appendUserInput(state, parts) {
+    if (parts.length === 0)
+        return;
+    const textOnly = parts.every((p) => p.type === 'text');
+    state.currentHistory.push(textOnly
+        ? { role: 'user', content: parts.map((p) => (p.type === 'text' ? p.text : '')).join('') }
+        : { role: 'user', parts: [...parts] });
+}
+/**
+ * Step state for one turn. A text turn's history grows inside the turn (tool
+ * steps, stage injects, repair retries), so its opening input moves into turn
+ * history here and everything later lands after it; `generation.input` is then
+ * empty. Image and speech turns are one call that reads only the input, so
+ * theirs stays put.
+ */
+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,
+        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);
+        generation.input = [];
+    }
+    return state;
+}
+export { appendUserInput, openTurnState, recordStepEvent };

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)[]>;