@andorra-labs/code 0.0.0-stage → 0.1.5

package/dist/src/runtime.d.ts

@@ -0,0 +1,418 @@
+import { TodoStore, type TodoItem } from './todos.js';
+import type { WidgetStore, WidgetSnapshot } from './widgets.js';
+import type { Graph, CompletionPolicy } from './graphs.js';
+import type { JsonSchema } from './handoffs.js';
+import type { ArtifactRef, ArtifactStore } from './artifacts.js';
+import type { ResolvedAttachments, UserAttachmentRef } from './attachments.js';
+import type { Message, ModelAdapter, RuntimeEvent, Tool, ToolContext, Usage } from './types.js';
+import { type Limits } from './limits.js';
+import type { DecisionManager } from './decision/DecisionManager.js';
+import type { DecisionBatch } from './decision/types.js';
+export declare const DEFAULT_GRAPH: Readonly<{
+    id: "default";
+    name: "Software Engineer";
+    revision: "1";
+    nodes: readonly (Readonly<{
+        id: "engineer";
+        type: "agent";
+        executor: "react-basic";
+    }> | Readonly<{
+        id: "done";
+        type: "end";
+    }>)[];
+    edges: readonly Readonly<{
+        from: "engineer";
+        to: "done";
+        on: "succeeded";
+    }>[];
+}>;
+export { DEFAULT_LIMITS, LIMIT_KEYS, isUnlimited, isUnlimitedAlias, resolveLimits } from './limits.js';
+export type { Limits, LimitKey } from './limits.js';
+export interface Completion {
+    summary: string;
+    tests: string[];
+    outcome?: string;
+    output?: Record<string, unknown>;
+    artifacts?: ArtifactRef[];
+    /**
+     * How an attempt ended, carried on the summary a stopped attempt leaves behind.
+     *
+     * Absent on a normal completion: clients render a stopped attempt differently — a cancelled or
+     * crashed turn keeps its activity visible rather than folding it into a finished turn's summary
+     * card — and they branch on this field rather than re-reading the summary's wording. `running` is
+     * what the session record carries while the attempt is in flight, and `interrupted` is what
+     * startup recovery writes when the engine that owned it is gone.
+     */
+    status?: 'running' | 'cancelled' | 'interrupted' | 'infrastructure_error' | 'exhausted' | 'needs_clarification';
+}
+/** A shared tool-call allowance; `maxToolCalls` absent means the allowance is unbounded. */
+export interface InvocationBudget {
+    usage: Usage;
+    toolCalls: number;
+    maxToolCalls?: number;
+}
+export interface RunResult {
+    /** Request-local retries have already handled this error; never replay the agent. */
+    providerRequestFailed?: boolean;
+    /** Set when the request was the classified context-overflow condition, which is a limit, not a fault. */
+    providerOverflow?: boolean;
+    /** Local telemetry counters and buckets; never persisted as event content until the emitter reads it. */
+    telemetry?: import('./telemetry/capture.js').RunTelemetry;
+    id: string;
+    graph: typeof DEFAULT_GRAPH | Graph;
+    provider: string;
+    model: string;
+    status: 'succeeded' | 'exhausted' | 'cancelled' | 'infrastructure_error' | 'needs_clarification';
+    reason?: string;
+    completion?: Completion;
+    usage: Usage;
+    toolCalls: number;
+    nodeResults?: Record<string, Completion>;
+    todos?: TodoItem[];
+    /** Final widget values, carried when the run's graph defines widgets. */
+    widgets?: WidgetSnapshot[];
+    /**
+     * Workspace-relative paths this attempt wrote or edited, bounded to 64. A re-attempt on another
+     * model is told about them so it inspects the work already done instead of repeating it.
+     */
+    mutations?: string[];
+    /** Effective limits for this attempt, so stop reasons can be reported concretely. */
+    limits?: Limits;
+}
+/** Private, in-memory transcript transfer between compatible graph Agent activations. */
+export interface AgentConversation {
+    provider: string;
+    model: string;
+    messages: Message[];
+    /** Archived originals the messages name, by run artifact; the successor re-admits them (see `AgentContinuationState.toolOutputArchive`). */
+    toolOutputArchive?: Record<string, string>;
+}
+export interface AgentContinuationState {
+    engineState?: {
+        stopHookContinuationCount: number;
+        outputTokenContinuationCount: number;
+    };
+    /** @deprecated Legacy resume state from older checkpoints. */
+    zcodeState?: {
+        stopHookContinuationCount: number;
+        outputTokenContinuationCount: number;
+    };
+    outputPartials?: string[];
+    iterations: number;
+    repairs: number;
+    todoCalls: number;
+    preparedPlanCalls?: number;
+    restorationCalls?: number;
+    widgetCalls?: number;
+    directionRevision: number;
+    todos?: TodoItem[];
+    failures: import('./tool-failure-tracker.js').ToolFailureTracker;
+    remainingToolCalls?: number;
+    remainingWallTimeMs?: number;
+    copies?: {
+        messages: Message[];
+        state: AgentContinuationState;
+    }[];
+    /** Successful siblings retained only while recovering an interrupted iteration. */
+    completedCopies?: (Completion | undefined)[];
+    modifierIteration?: number;
+    /** Prior completed loop iteration, needed by copies that have not started yet. */
+    previousIterationCompletion?: Completion;
+    /**
+     * Complete originals of the filtered tool results this conversation names, by their
+     * `tool-output://` reference and the run artifact holding each. A resumed attempt re-admits them so
+     * `expand_tool_output` keeps serving the references in the restored messages.
+     */
+    toolOutputArchive?: Record<string, string>;
+    orchestratorIntake?: {
+        nodeId: string;
+        clarified: boolean;
+        publishedPlan: boolean;
+        observedResearch: boolean;
+        confirmedClarifications: {
+            question: string;
+            answer: string;
+            proposedDesign: string[];
+        }[];
+    };
+}
+/**
+ * The text a retained history turn puts in front of the model: its task, plus the direction
+ * the attempt was continued with — a continued turn's task is the stopped attempt's own, so
+ * without this the user's words after a stop would never reach the model.
+ *
+ * This is the one renderer of retained turns: the engine's runs, the CLI's retained history, and
+ * the optional-context estimators all flow through it, and the stored turn keeps task and
+ * direction apart. Baking the note into a stored task instead would make every later request
+ * expand a turn that already carries it, repeating the stale instruction until the turn ages out
+ * of the window. The turn's attachments are re-referenced the same way: a replayed turn carries
+ * the reference text alone (the pixels were sent with the turn that owned them and are not
+ * re-attached), so the block must not claim an image input.
+ */
+export declare function turnModelTask(turn: {
+    task: string;
+    direction?: string;
+    attachments?: readonly UserAttachmentRef[];
+    steers?: {
+        text: string;
+        attachments?: readonly UserAttachmentRef[];
+    }[];
+}): string;
+export interface RunOptions {
+    /** Opt-in, tool-free goal verification using this run's model and metered adapter. */
+    goalCompletionVerification?: import('./goal-completion-verification.js').GoalCompletionVerificationOptions;
+    decisionManager?: DecisionManager;
+    decisionHints?: DecisionBatch;
+    /** Original task before private retrieval or skill bodies are appended to model context. */
+    decisionTask?: string;
+    /** Independent efficiency switches (`src/efficiency.ts`); absent means every one is off. */
+    efficiency?: import('./efficiency.js').EfficiencyConfig;
+    /**
+     * User-authored attachments for this turn. The executor appends the reference block to the
+     * opening user message and attaches `images` to it; graph plumbing carries the field through
+     * untouched so every entry path (CLI, app-server, resume) shares one implementation.
+     */
+    attachments?: ResolvedAttachments;
+    /** Original capability-filtered catalog, for recovering a prematurely pruned schema. */
+    recoverTools?: Tool[];
+    /** Interactive model selection, sampled at model-turn boundaries; in-flight requests keep their adapter. */
+    getLiveModel?: (nodeId: string | undefined, provider: string, model: string, signal: AbortSignal) => Promise<(ResolvedGraphModel & {
+        provider: string;
+    }) | undefined>;
+    task: string;
+    model: string;
+    provider: string;
+    adapter: ModelAdapter;
+    tools: Tool[];
+    /** Selected model context window in tokens, supplied by the provider registry. */
+    contextWindow?: number;
+    context: ToolContext;
+    limits?: Partial<Limits>;
+    /** Unclamped node character ceiling; live window changes recompute the model-specific bound. */
+    contextCharCeiling?: number;
+    /**
+     * Retained turns seeded into the run. A continued turn's `direction` is rendered by
+     * `turnModelTask`; a turn's attachments are re-referenced as text, never re-sent as pixels.
+     */
+    history?: {
+        task: string;
+        completion: Completion;
+        runId?: string;
+        direction?: string;
+        attachments?: UserAttachmentRef[];
+    }[];
+    /** In-memory continuation only; never persist provider protocol state in run results. */
+    resumeMessages?: Message[];
+    resumeDirectionRevision?: number;
+    resumeState?: AgentContinuationState;
+    previousConversation?: AgentConversation;
+    /** Activated workflow skills passed separately from conversation reuse and model identity. */
+    inheritedSkills?: readonly string[];
+    /** Called after a skill resource was successfully loaded by this node. */
+    onSkillActivated?: (skillId: string) => void | Promise<void>;
+    onConversationCheckpoint?: (messages: Message[], state: AgentContinuationState, conversation?: AgentConversation) => void | Promise<void>;
+    instructions?: string;
+    systemPrompt?: string;
+    /** Configured graph node instruction, separate from the expanded model system prompt. */
+    nodeInstruction?: string;
+    runId?: string;
+    nodeId?: string;
+    graph?: Graph;
+    completionPolicy?: CompletionPolicy;
+    canonicalTask?: string;
+    completionGuard?: (completion: Completion) => string | undefined;
+    outputSchema?: JsonSchema;
+    mappedInputs?: Record<string, unknown>;
+    predecessorOutputs?: Record<string, Completion>;
+    runInput?: Record<string, unknown>;
+    runState?: Record<string, unknown>;
+    artifactStore?: ArtifactStore;
+    todoStore?: TodoStore;
+    onTodosUpdated?: () => void;
+    /**
+     * The run's widget values. Present only when the executing graph defines widgets; the
+     * definitions themselves are read from `graph.widgets`, and the store is shared by every
+     * node of the run the way the todo store is.
+     */
+    widgetStore?: WidgetStore;
+    budget?: InvocationBudget;
+    /**
+     * Per-request usage deltas, as each attempt and each completion is recorded.
+     * `origin` carries the request's `invocationId` when the executor knows one, so a
+     * consumer can pair a completion with the request that produced it. The delta that
+     * closes a request — the response accounting, as opposed to the per-attempt transport
+     * bookkeeping — is flagged `final`, so a consumer that holds a display value can tell
+     * an unmeasured completion from a retry attempt that reports no tokens by design.
+     */
+    onUsage?: (usage: Usage, origin?: {
+        invocationId?: string;
+        final?: boolean;
+    }) => void;
+    subagentId?: string;
+    /**
+     * Which provider class, endpoint and workflow role a request belongs to, for local telemetry.
+     * Only bucket labels ever leave the machine; the base URL is reduced to hosted/local/other.
+     */
+    telemetryIdentity?: {
+        providerType?: string;
+        baseUrl?: string;
+        role: 'agent' | 'orchestrator' | 'subagent' | 'jev' | 'other';
+    };
+    /**
+     * Pull messages typed by the user while this attempt is running.
+     *
+     * Polled by the hardened executor at turn boundaries, so a returned message is
+     * injected into the live conversation as a steer instruction rather than starting a
+     * new run. Returning an empty array means nothing is queued. Only an interactive
+     * caller supplies this; headless runs leave it unset and behave exactly as before.
+     */
+    getSteeringMessages?: (signal: AbortSignal) => Promise<Message[]>;
+    onEvent?: (event: RuntimeEvent) => void | Promise<void>;
+}
+/** Account transport attempts immediately, even if generation later fails or is cancelled. */
+export declare function generateWithUsage(options: RunOptions, result: RunResult, request: Parameters<ModelAdapter['generate']>[0]): Promise<import("./types.js").ModelResponse>;
+export declare class ClarificationRequiredError extends Error {
+    constructor(message: string);
+}
+/**
+ * Whether a tool-call count still fits its allowance.
+ *
+ * `maxToolCalls` is optional, and an absent value means unlimited: the caller is
+ * always within budget. Stating that rule once keeps every enforcement site from
+ * re-deriving it, where a bare `< undefined` comparison would silently read as
+ * "out of budget" and stop a run that has no ceiling at all.
+ * @param used - tool calls already consumed, or about to be consumed.
+ * @param maxToolCalls - configured ceiling, or undefined for unlimited.
+ * @returns whether the count is within the allowance.
+ */
+export declare function withinToolBudget(used: number, maxToolCalls: number | undefined): boolean;
+/**
+ * Whether another tool call can still be made.
+ *
+ * Distinct from {@link withinToolBudget} on purpose: executing one more call needs
+ * strictly more headroom, so a run already at its ceiling has none. Advertising a
+ * tool while at the ceiling would invite a call the runtime must refuse.
+ * @param used - tool calls already consumed.
+ * @param maxToolCalls - configured ceiling, or undefined for unlimited.
+ * @returns whether one more tool call fits.
+ */
+export declare function hasToolBudget(used: number, maxToolCalls: number | undefined): boolean;
+/**
+ * The phrase that completes a sentence about a stop whose subject is "it".
+ *
+ * A classified reason reads as a verb phrase and takes the "it". A failure message is prose with
+ * a subject of its own, so it is used whole — "it Provider request failed" would be a mistake.
+ * @param reason - the internal stop code, or a failure message.
+ * @param limits - the run's limits, so a reason that names a budget can name its size.
+ * @returns the phrase to write after the sentence's colon.
+ */
+export declare function stopReasonPhrase(reason: string | undefined, limits?: Partial<Limits>): string;
+/**
+ * The whole sentence a client shows for a stopped run.
+ *
+ * The command line and the app server phrase a stop as a clause inside a sentence of their own,
+ * so a client that sees only the journal event has to finish the sentence itself. The engine
+ * publishes the finished sentence, so every surface shows the same words and no surface leaks an
+ * internal code such as `maxNodeVisits:engineer`.
+ * @param reason - the internal stop code, or a failure message.
+ * @param limits - the run's limits, so a reason that names a budget can name its size.
+ * @returns the sentence that describes how the run stopped.
+ */
+export declare function stopReasonSentence(reason: string | undefined, limits?: Partial<Limits>): string;
+/** A fresh attempt owns its messages; graph routing is outside the model/tool loop. */
+/** Compatibility facade: standalone and graph execution share the same engine. */
+export declare class BasicReActAgentExecutor {
+    execute(options: RunOptions): Promise<RunResult>;
+}
+/** Legacy single-Agent execution helper; the CLI uses the current saved default harness. */
+export declare function runDefaultGraph(options: RunOptions): Promise<RunResult>;
+export interface ResolvedGraphModel {
+    model: string;
+    adapter: ModelAdapter;
+    contextWindow?: number;
+    /** The provider class and endpoint, carried for local telemetry aggregation only. */
+    providerType?: string;
+    baseUrl?: string;
+}
+export interface GraphRunOptions extends RunOptions {
+    decisionManager?: import('./decision/DecisionManager.js').DecisionManager;
+    /**
+     * Set by the run policy: an Agent node uses `decisionManager` only when it sets `jevEnabled: true`,
+     * and every other node runs with decisions off. Node JSON cannot grant an account entitlement; the
+     * manager the policy built already reflects sign-in and the installation-wide switch.
+     */
+    decisionNodeOptIn?: boolean;
+    /** Task, memory availability and retrieval eligibility captured before retrieval. */
+    decisionPreflight?: {
+        task: string;
+        memory: boolean;
+        memoryAvailable: boolean;
+    };
+    /**
+     * The run's provider and model were chosen explicitly by the user (a `--model` flag, a desktop
+     * override). Adaptive routing never replaces an explicit choice; without this flag the pair is
+     * the configured default and an opted-in router may re-tier a node that pins nothing itself.
+     */
+    modelPinned?: boolean;
+    /** The configured providers' ids and model lists, for validating adaptive-routing tiers. */
+    configuredModels?: {
+        id: string;
+        model?: string;
+        models?: readonly string[];
+    }[];
+    /** Facts the runner collected once for the run, so nodes do not walk the workspace again. */
+    workspaceFacts?: import('./workspace-facts.js').WorkspaceFacts;
+    /** Explicit slash invocation guidance only for nodes that inherit active skills. */
+    skillInvocationInstruction?: string;
+    /** Internal modifier clock suspension for baseline automatic memory retrieval. Never suspends the graph/run clock. */
+    suspendMemoryBudget?: () => () => void;
+    /** One-based modifier iteration, scoped to this invocation's root agent. */
+    modifierIteration?: number;
+    /** Validated preceding loop result; grants artifact scope only to this iteration's root. */
+    previousIterationCompletion?: Completion;
+    /** Scheduler reservation for nested copy workers; never exceeds graph concurrency. */
+    concurrencyBudget?: number;
+    /** Resolve the actual model, including same-provider overrides, for each invocation. */
+    resolveModel?: (id: string, model: string | undefined, signal: AbortSignal) => Promise<ResolvedGraphModel>;
+    resolveProvider?: (id: string) => ResolvedGraphModel;
+    /** Persistent project memory; absent means memory is unavailable this run. */
+    memory?: import('./memory/MemoryManager.js').MemoryManager;
+    /** Local, deterministic command lessons; the CLI enables this without Graphiti. */
+    commandMemory?: import('./memory/LocalToolMemory.js').LocalToolMemory;
+    /**
+     * The furthest accepted conversation of each node, on every checkpoint.
+     *
+     * Unlike `onConversationCheckpoint`, which only fires for the invocation the caller passed it
+     * to, this fires for every node in the graph so a caller can persist resume state that outlives
+     * the process. `meta.generation` is the visit's generation: a cyclic node's next visit is always
+     * a new generation, so the stamp identifies which visit the conversation belongs to, and a
+     * resume only re-enters a checkpoint whose stamp matches the frontier activation's generation.
+     * `meta.provider`/`meta.model` name the model that conversation ran on when it was handed to a
+     * predecessor: the runtime accepts a continued conversation only from the same provider and
+     * model, so a resume needs the stamp to rebuild a predecessor-conversation handoff.
+     * `meta.routedFrom` names the model identity this run had CONFIGURED for the node — the baseline
+     * adaptive routing started from. A checkpoint whose own pair differs from that baseline was
+     * routed; a resume whose recomputed baseline still matches `routedFrom` knows the routing
+     * decision was its own configuration's, and continues the conversation on the pair that ran
+     * instead of restarting the visit.
+     */
+    onNodeCheckpoint?: (nodeId: string, messages: Message[], state: AgentContinuationState, meta?: {
+        generation?: number;
+        provider?: string;
+        model?: string;
+        routedFrom?: {
+            provider: string;
+            model?: string;
+        };
+    }) => void | Promise<void>;
+    /**
+     * Rehydrate the scheduler from a stopped attempt: completed nodes, visit counts, the frontier
+     * of activations the journal proved pending, and the captured conversations of the unfinished
+     * nodes — one checkpoint per branch that had one, since parallel branches each hold their own.
+     */
+    resumeFrom?: {
+        progress: import('./run-progress.js').RunProgress;
+        checkpoints?: import('./run-progress.js').RunCheckpoint[];
+    };
+}
+export { runGraph } from './graph-runner.js';

package/dist/src/runtime.js

@@ -0,0 +1,247 @@
+import { attachmentReferenceBlock } from './attachments.js';
+import { createRunTelemetry, recordModelUse } from './telemetry/capture.js';
+import { pricingFor } from './model-tiers.js';
+export const DEFAULT_GRAPH = Object.freeze({
+    id: 'default', name: 'Software Engineer', revision: '1',
+    nodes: Object.freeze([
+        Object.freeze({ id: 'engineer', type: 'agent', executor: 'react-basic' }),
+        Object.freeze({ id: 'done', type: 'end' }),
+    ]),
+    edges: Object.freeze([Object.freeze({ from: 'engineer', to: 'done', on: 'succeeded' })]),
+});
+// Bounds live in a dependency-free leaf module so configuration can name them without
+// importing this runtime; re-exported here because this is where callers already look for them.
+export { DEFAULT_LIMITS, LIMIT_KEYS, isUnlimited, isUnlimitedAlias, resolveLimits } from './limits.js';
+/**
+ * The text a retained history turn puts in front of the model: its task, plus the direction
+ * the attempt was continued with — a continued turn's task is the stopped attempt's own, so
+ * without this the user's words after a stop would never reach the model.
+ *
+ * This is the one renderer of retained turns: the engine's runs, the CLI's retained history, and
+ * the optional-context estimators all flow through it, and the stored turn keeps task and
+ * direction apart. Baking the note into a stored task instead would make every later request
+ * expand a turn that already carries it, repeating the stale instruction until the turn ages out
+ * of the window. The turn's attachments are re-referenced the same way: a replayed turn carries
+ * the reference text alone (the pixels were sent with the turn that owned them and are not
+ * re-attached), so the block must not claim an image input.
+ */
+export function turnModelTask(turn) {
+    const text = turn.direction === undefined ? turn.task : `${turn.task}\n\nDirection given when the attempt continued: ${turn.direction}`;
+    // A steer was read inside the turn that was running, so it renders as part of that turn rather
+    // than as a turn of its own — the model sees the instruction that redirected the work it is
+    // reading about. Files a steer carried are named without claiming image inputs, exactly as the
+    // turn's own attachments are.
+    const withSteers = (turn.steers ?? []).reduce((text, steer) => {
+        const line = `\n\nSteering message the user sent while this attempt ran: ${steer.text}`;
+        const refs = steer.attachments?.length ? `\n\n${attachmentReferenceBlock(steer.attachments, { imagesIncluded: false })}` : '';
+        return `${text}${line}${refs}`;
+    }, text);
+    return turn.attachments?.length ? `${withSteers}\n\n${attachmentReferenceBlock(turn.attachments, { imagesIncluded: false })}` : withSteers;
+}
+/** Account transport attempts immediately, even if generation later fails or is cancelled. */
+export async function generateWithUsage(options, result, request) {
+    let recordedRequests = 0;
+    // Every delta from this one request carries the request's identity, so a consumer that
+    // pairs completions with the window they opened (the footer's token-speed meter) can do
+    // so without guessing across concurrent requests.
+    const origin = request.context?.invocationId ? { invocationId: request.context.invocationId } : undefined;
+    const add = (delta, final = false) => {
+        for (const target of [result.usage, ...(options.budget ? [options.budget.usage] : [])]) {
+            target.requests += delta.requests;
+            target.inputTokens += delta.inputTokens;
+            target.outputTokens += delta.outputTokens;
+            // inputTokens stays inclusive of cache traffic; the split is carried alongside, and stays sparse
+            // only while nothing has reported it. Once a delta carries a counter, the total carries it too —
+            // including as a zero — because a provider that measured "nothing cached" said something, and a
+            // run record that dropped that field would let the completion refresh hide the reading.
+            if (delta.cacheRead !== undefined || target.cacheRead !== undefined)
+                target.cacheRead = (target.cacheRead ?? 0) + (delta.cacheRead ?? 0);
+            if (delta.cacheWrite !== undefined || target.cacheWrite !== undefined)
+                target.cacheWrite = (target.cacheWrite ?? 0) + (delta.cacheWrite ?? 0);
+        }
+        options.onUsage?.(delta, final ? { ...origin, final: true } : origin);
+    };
+    const identity = {
+        providerType: options.telemetryIdentity?.providerType,
+        baseUrl: options.telemetryIdentity?.baseUrl,
+        model: request.model,
+        role: options.telemetryIdentity?.role ?? (options.subagentId ? 'subagent' : 'other'),
+    };
+    const response = await options.adapter.generate({ ...request, onRequest: () => {
+            recordedRequests++;
+            add({ inputTokens: 0, outputTokens: 0, requests: 1 });
+        } }).catch(error => {
+        // The attempt reached the provider and was billed even though it failed. It is recorded with
+        // requests only: nothing measured its tokens, so they stay absent rather than becoming zero.
+        if (recordedRequests > 0) {
+            result.telemetry ??= createRunTelemetry();
+            recordModelUse(result.telemetry, { ...identity, usage: { requests: recordedRequests } });
+        }
+        // A request that rejects still ends: the final flag lets the meter retire the held
+        // reading (a failed request's predecessor must not keep its speed beside the fallback
+        // provider or model the retry switches to) and consume the window its start opened, so
+        // the retry's own completion pairs with its own start. The zeros mean "nothing was
+        // measured", so a consumer that tracks the conversation size keeps its previous value.
+        add({ inputTokens: 0, outputTokens: 0, requests: 0 }, true);
+        throw error;
+    });
+    // Adapters without transport callbacks retain their response-based accounting.
+    // The HTTP adapter reports the same total in its response; do not count it twice.
+    //
+    // The cache fields travel only when the provider reported them: normalizing an absent counter to
+    // zero here would tell every consumer — the run record, the window's figures — that a provider
+    // which says nothing about caching had measured "nothing cached", and a surface cannot tell those
+    // apart afterwards. A reported zero is carried as the measurement it is.
+    add({ inputTokens: response.usage?.inputTokens ?? 0, outputTokens: response.usage?.outputTokens ?? 0,
+        ...(response.usage?.cacheRead === undefined ? {} : { cacheRead: response.usage.cacheRead }),
+        ...(response.usage?.cacheWrite === undefined ? {} : { cacheWrite: response.usage.cacheWrite }),
+        // The decode window is a measurement, not a billing figure: it rides the delta so surfaces
+        // that divide tokens by decode time (the node chips, the composer stats line) can see it.
+        // It stays absent when the response was not streamed or the adapter measures no window.
+        ...(response.usage?.decodeMs === undefined ? {} : { decodeMs: response.usage.decodeMs }),
+        requests: Math.max(0, (response.usage?.requests ?? 1) - recordedRequests) }, true);
+    // A response is the unit the ADR measures: this request counts toward its tuple, and a
+    // measurement is reported only when every request in that tuple reported it. The capture
+    // applies that rule and stores no prompt, response, or argument. The user's routing prices
+    // turn the usage into a cost when they name this provider/model; a request the pricing table
+    // does not cover reports no cost, and the tuple's cost stays absent until every request in it
+    // was priced (the capture's completeness rule).
+    result.telemetry ??= createRunTelemetry();
+    recordModelUse(result.telemetry, { ...identity, usage: response.usage ?? {},
+        ...(options.efficiency?.adaptiveRouting?.pricing ? { pricing: pricingFor(options.efficiency.adaptiveRouting, request.context?.providerId ?? '', request.model) } : {}) });
+    return response;
+}
+export class ClarificationRequiredError extends Error {
+    constructor(message) { super(message); this.name = 'ClarificationRequiredError'; }
+}
+/**
+ * Whether a tool-call count still fits its allowance.
+ *
+ * `maxToolCalls` is optional, and an absent value means unlimited: the caller is
+ * always within budget. Stating that rule once keeps every enforcement site from
+ * re-deriving it, where a bare `< undefined` comparison would silently read as
+ * "out of budget" and stop a run that has no ceiling at all.
+ * @param used - tool calls already consumed, or about to be consumed.
+ * @param maxToolCalls - configured ceiling, or undefined for unlimited.
+ * @returns whether the count is within the allowance.
+ */
+export function withinToolBudget(used, maxToolCalls) {
+    return maxToolCalls === undefined || used <= maxToolCalls;
+}
+/**
+ * Whether another tool call can still be made.
+ *
+ * Distinct from {@link withinToolBudget} on purpose: executing one more call needs
+ * strictly more headroom, so a run already at its ceiling has none. Advertising a
+ * tool while at the ceiling would invite a call the runtime must refuse.
+ * @param used - tool calls already consumed.
+ * @param maxToolCalls - configured ceiling, or undefined for unlimited.
+ * @returns whether one more tool call fits.
+ */
+export function hasToolBudget(used, maxToolCalls) {
+    return maxToolCalls === undefined || used < maxToolCalls;
+}
+/**
+ * Classify an internal exhaustion code into the words a person can act on.
+ *
+ * Users should never be shown a bare identifier such as `exhausted: maxTokens`.
+ * @param reason - the internal stop code, or a failure message.
+ * @param limits - the run's limits, so a reason that names a budget can name its size.
+ * @returns the clause the engine writes for the reason, or the message as it was reported.
+ */
+function classifyStopReason(reason, limits) {
+    if (!reason)
+        return { clause: 'stopped before completing its work' };
+    // Millisecond wall limits are valid in graph and node configuration, so a sub-minute bound
+    // must be reported in seconds. Forcing a one-minute floor would overstate a short deadline
+    // by up to 60x and mislead anyone investigating an early stop.
+    const duration = !limits?.wallTimeMs ? undefined
+        : limits.wallTimeMs < 60_000
+            ? `${Math.max(1, Math.round(limits.wallTimeMs / 1000))} second${Math.round(limits.wallTimeMs / 1000) === 1 ? '' : 's'}`
+            : `${Math.max(1, Math.round(limits.wallTimeMs / 60_000))} minute${Math.round(limits.wallTimeMs / 60_000) === 1 ? '' : 's'}`;
+    if (reason === 'wallTimeMs')
+        return { clause: `ran out of time${duration ? ` after about ${duration}` : ''} and stopped before finishing` };
+    if (reason === 'maxIterations')
+        return { clause: `used all ${limits?.maxIterations ?? 'its'} reasoning steps without reaching a result` };
+    if (reason === 'maxToolCalls')
+        return { clause: `used all ${limits?.maxToolCalls ?? 'its'} tool calls without reaching a result` };
+    if (reason === 'maxContextChars')
+        return { clause: 'needed more context than the node allows; the conversation could not be compacted further' };
+    // These clauses complete a sentence whose subject is "it" — the run — so they must not carry
+    // a subject of their own: "it the model repeatedly exceeded..." reads as a mistake. The clause
+    // says what the run did, and the sentence around it names the run.
+    if (reason === 'stopHookContinuation')
+        return { clause: 'used its three stop-hook continuations without a valid handoff' };
+    if (reason === 'outputTokenLimit')
+        return { clause: 'repeatedly exceeded its output token limit after three continuations' };
+    if (reason === 'maxCompletionRepairs')
+        return { clause: 'kept returning responses that did not satisfy the completion contract' };
+    if (reason === 'repeatedToolFailure')
+        return { clause: 'stopped after the same tool call failed repeatedly without a successful file repair' };
+    if (reason === 'maxTodoCalls')
+        return { clause: 'exhausted its plan-update allowance before finishing' };
+    if (reason === 'cancelled')
+        return { clause: 'was cancelled' };
+    if (reason.startsWith('maxNodeVisits:'))
+        return { clause: `tried to run node ${reason.slice('maxNodeVisits:'.length)} more times than the graph allows` };
+    if (reason.startsWith('loop.maxIterations:'))
+        return { clause: `repeated the loop at node ${reason.slice('loop.maxIterations:'.length)} until its attempt limit` };
+    // Prefer a plain sentence over a raw code; messages from errors are already readable. The
+    // caller supplies the sentence's final period, so a reason that already ends in one must not
+    // produce "availability..".
+    return reason.includes(' ') ? { message: reason.replace(/\.$/, '') } : { clause: `stopped: ${reason}` };
+}
+/**
+ * The phrase that completes a sentence about a stop whose subject is "it".
+ *
+ * A classified reason reads as a verb phrase and takes the "it". A failure message is prose with
+ * a subject of its own, so it is used whole — "it Provider request failed" would be a mistake.
+ * @param reason - the internal stop code, or a failure message.
+ * @param limits - the run's limits, so a reason that names a budget can name its size.
+ * @returns the phrase to write after the sentence's colon.
+ */
+export function stopReasonPhrase(reason, limits) {
+    const classified = classifyStopReason(reason, limits);
+    return 'clause' in classified ? `it ${classified.clause}` : classified.message;
+}
+/**
+ * The whole sentence a client shows for a stopped run.
+ *
+ * The command line and the app server phrase a stop as a clause inside a sentence of their own,
+ * so a client that sees only the journal event has to finish the sentence itself. The engine
+ * publishes the finished sentence, so every surface shows the same words and no surface leaks an
+ * internal code such as `maxNodeVisits:engineer`.
+ * @param reason - the internal stop code, or a failure message.
+ * @param limits - the run's limits, so a reason that names a budget can name its size.
+ * @returns the sentence that describes how the run stopped.
+ */
+export function stopReasonSentence(reason, limits) {
+    if (!reason)
+        return 'The run stopped before completing its work.';
+    if (reason === 'cancelled')
+        return 'The run was cancelled.';
+    const classified = classifyStopReason(reason, limits);
+    if ('message' in classified)
+        return `The run stopped: ${classified.message}.`;
+    // A code the engine does not classify reads as the code itself; a classified one reads as a clause.
+    const code = classified.clause.startsWith('stopped: ') ? classified.clause.slice('stopped: '.length) : undefined;
+    return code ? `The run stopped: ${code}.` : `The run stopped: it ${classified.clause}.`;
+}
+/** A fresh attempt owns its messages; graph routing is outside the model/tool loop. */
+/** Compatibility facade: standalone and graph execution share the same engine. */
+export class BasicReActAgentExecutor {
+    async execute(options) {
+        const { createAgentEngine } = await import('./hardened-runtime.js');
+        return createAgentEngine().execute(options);
+    }
+}
+/** Legacy single-Agent execution helper; the CLI uses the current saved default harness. */
+export async function runDefaultGraph(options) {
+    const result = await new BasicReActAgentExecutor().execute(options);
+    // The only bundled edge is success -> End. Failures remain explicit terminal outcomes.
+    if (result.status === 'succeeded') {
+        await options.onEvent?.({ type: 'graph.completed', time: new Date().toISOString(), data: { runId: result.id, node: 'done' } });
+    }
+    return result;
+}
+export { runGraph } from './graph-runner.js';

package/dist/src/sandbox-child.d.ts

@@ -0,0 +1 @@
+export {};