@autonome-research/thread-phase 3.0.0

package/dist/agent/runner.js

@@ -0,0 +1,270 @@
+/**
+ * Agent runner — the tool-use loop primitive.
+ *
+ * Given an agent config (system prompt, tools, model tier), a starting
+ * conversation, and an executor for the tools, runs an iterated tool-use
+ * loop against an OpenAI-compatible inference endpoint until the agent
+ * produces final text or hits its round budget.
+ *
+ * Composed from focused helpers in this directory:
+ *   - `./types.ts`           — public surface
+ *   - `./openai-adapter.ts`  — Message↔OpenAI wire-format translation
+ *   - `./stream-consumer.ts` — folds streaming chunks into one round's state
+ *   - `./retry.ts`           — error classification (retryable, abort)
+ *
+ * What the loop owns:
+ *   - Round budgeting and the compress / hard-stop transitions
+ *   - Streaming the request, dispatching tools, collecting results
+ *   - Cumulative usage / executedToolCalls accounting across rounds
+ *   - Cancellation observation (AbortSignal in options)
+ *   - The verifyResult hook, the parser-mismatch warning, the retry loop
+ */
+import { TokenBudgetTracker, BudgetStatus, } from '../context/token-budget.js';
+import { TruncateAndCacheResultCapper } from '../context/result-capper.js';
+import { DeterministicCompressor, AggressiveCompressor, sanitizeToolPairs, } from '../context/compressor.js';
+import { toOpenAIMessages, toOpenAITools } from './openai-adapter.js';
+import { consumeStream, looksLikeToolCallText } from './stream-consumer.js';
+import { isRetryableError, isAbortError } from './retry.js';
+export async function runAgentWithTools(config, initialMessages, options, agentLabel) {
+    const label = agentLabel ?? config.name;
+    const activity = [];
+    const executedToolCalls = [];
+    const cumulativeUsage = { promptTokens: 0, completionTokens: 0, totalTokens: 0 };
+    const cache = options.cache ?? null;
+    const maxRetries = options.maxRetries ?? 1;
+    const signal = options.signal;
+    const emit = options.onStreamEvent;
+    const budgetTracker = options.budgetTracker ?? new TokenBudgetTracker();
+    const cap = budgetTracker.getResultCap();
+    const protect = budgetTracker.getProtectCounts();
+    const resultCapper = options.resultCapper ?? new TruncateAndCacheResultCapper(cap.maxChars, cap.previewChars);
+    const compressor = options.compressor ?? new DeterministicCompressor();
+    const aggressiveCompressor = options.aggressiveCompressor ?? new AggressiveCompressor();
+    // Helper: compose the final result, run the verifyResult hook (if any),
+    // and surface a clean error result if the hook rejects.
+    const finalize = async (text, finishReason) => {
+        let result = {
+            text,
+            activity,
+            finishReason,
+            usage: cumulativeUsage,
+            executedToolCalls,
+        };
+        if (options.verifyResult) {
+            try {
+                const verified = await options.verifyResult(result);
+                if (verified)
+                    result = verified;
+            }
+            catch (err) {
+                const e = err;
+                activity.push({
+                    agent: label,
+                    action: 'verify_failed',
+                    detail: e.message?.slice(0, 200),
+                });
+                return {
+                    ...result,
+                    text: JSON.stringify({ _error: true, message: e.message ?? 'verifyResult threw' }),
+                    finishReason: 'error',
+                };
+            }
+        }
+        return result;
+    };
+    // Surface a clear cancellation result when the caller aborts before the
+    // first round.
+    if (signal?.aborted) {
+        activity.push({ agent: label, action: 'aborted', detail: 'signal aborted before first round' });
+        return finalize('', 'error');
+    }
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        try {
+            let localMessages = [...initialMessages];
+            let forceOutput = false;
+            for (let round = 0; round < config.maxToolRounds; round++) {
+                if (signal?.aborted) {
+                    activity.push({ agent: label, action: 'aborted', detail: `aborted before round ${round}` });
+                    return finalize([...localMessages]
+                        .reverse()
+                        .find((m) => m.role === 'assistant')?.content ?? '', 'error');
+                }
+                // --- Layer 2: budget check (compress / hard-stop) ---
+                const budget = budgetTracker.check(config.systemPrompt, localMessages, forceOutput ? [] : config.tools);
+                if (budget.status === BudgetStatus.HARD_STOP && !forceOutput) {
+                    activity.push({
+                        agent: label,
+                        action: 'budget_hard_stop',
+                        detail: `${budget.estimatedTokens} tokens (${(budget.budgetUsed * 100).toFixed(0)}%) — aggressive compression`,
+                    });
+                    localMessages = aggressiveCompressor.compress(localMessages, {
+                        protectFirst: protect.protectFirst,
+                        protectLast: protect.protectLastAggressive,
+                        activityLog: activity,
+                    });
+                    localMessages = sanitizeToolPairs(localMessages);
+                    forceOutput = true;
+                }
+                else if (budget.status === BudgetStatus.COMPRESS) {
+                    activity.push({
+                        agent: label,
+                        action: 'budget_compress',
+                        detail: `${budget.estimatedTokens} tokens (${(budget.budgetUsed * 100).toFixed(0)}%) — compressing old results`,
+                    });
+                    localMessages = compressor.compress(localMessages, {
+                        protectFirst: protect.protectFirst,
+                        protectLast: protect.protectLast,
+                        activityLog: activity,
+                    });
+                    localMessages = sanitizeToolPairs(localMessages);
+                }
+                const isLastRound = round === config.maxToolRounds - 1 || forceOutput;
+                // The nudge only makes sense when the agent has tools; injecting it
+                // for a no-tools agent confuses the model into returning empty content.
+                const shouldNudge = isLastRound && config.tools.length > 0;
+                const messagesForRequest = shouldNudge
+                    ? [
+                        ...localMessages,
+                        {
+                            role: 'user',
+                            content: 'You are running out of tool rounds. Please produce your final output now based on what you have found so far.',
+                        },
+                    ]
+                    : localMessages;
+                const openAiMessages = toOpenAIMessages(config.systemPrompt, messagesForRequest);
+                // The openai SDK serializes `tools: undefined` as `"tools": null` in
+                // the JSON body, which trips up vLLM/Qwen into a reasoning-only loop.
+                // Only set the field when we actually want tools available.
+                const sendTools = !isLastRound && config.tools.length > 0;
+                // extraBody first so anything the runner sets explicitly wins on key collision.
+                const requestBody = {
+                    ...config.extraBody,
+                    model: config.model,
+                    max_tokens: config.maxTokens,
+                    messages: openAiMessages,
+                    stream: true,
+                    // Ask backends that support it to include usage in the terminal
+                    // chunk. Backends that don't support it ignore the field.
+                    stream_options: { include_usage: true },
+                };
+                if (sendTools) {
+                    requestBody.tools = toOpenAITools(config.tools);
+                }
+                const stream = await options.client.chat.completions.create(requestBody, {
+                    signal,
+                });
+                const round_ = await consumeStream(stream, (delta) => {
+                    emit?.({ type: 'content_delta', agent: label, delta });
+                });
+                // Roll usage forward across rounds.
+                cumulativeUsage.promptTokens += round_.usage.promptTokens;
+                cumulativeUsage.completionTokens += round_.usage.completionTokens;
+                cumulativeUsage.totalTokens += round_.usage.totalTokens;
+                // Inference-provider parser-mismatch warning: tools[] was sent but
+                // the model returned plain content shaped like a tool call. Likely
+                // a missing or wrong --tool-call-parser on the backend.
+                if (sendTools &&
+                    round_.toolCalls.length === 0 &&
+                    looksLikeToolCallText(round_.content)) {
+                    const hint = 'tools[] was sent but model returned tool-call-shaped content as plain text. ' +
+                        'Likely a missing or wrong --tool-call-parser on the inference backend.';
+                    activity.push({ agent: label, action: 'parser_mismatch_warning', detail: hint });
+                    // eslint-disable-next-line no-console
+                    console.warn(`[${label}] ${hint} Preview: ${round_.content.slice(0, 160)}`);
+                }
+                const assistantMsg = {
+                    role: 'assistant',
+                    content: round_.content,
+                    toolCalls: round_.toolCalls,
+                };
+                localMessages.push(assistantMsg);
+                if (assistantMsg.content.trim() && assistantMsg.toolCalls.length > 0) {
+                    activity.push({
+                        agent: label,
+                        action: 'reasoning',
+                        detail: assistantMsg.content.trim().slice(0, 200),
+                    });
+                }
+                emit?.({
+                    type: 'round_complete',
+                    agent: label,
+                    round,
+                    finishReason: round_.finishReason,
+                });
+                // No tool calls → final output, return.
+                if (assistantMsg.toolCalls.length === 0) {
+                    return finalize(assistantMsg.content, round_.finishReason);
+                }
+                // Log tool calls + emit lifecycle events.
+                for (const tc of assistantMsg.toolCalls) {
+                    const summary = Object.entries(tc.input)
+                        .map(([k, v]) => `${k}=${JSON.stringify(v)}`.slice(0, 60))
+                        .join(', ');
+                    activity.push({
+                        agent: label,
+                        action: `tool:${tc.name}`,
+                        detail: summary.slice(0, 120),
+                    });
+                    emit?.({ type: 'tool_call_started', agent: label, toolCall: tc });
+                }
+                // Execute tools in parallel.
+                const results = await Promise.all(assistantMsg.toolCalls.map((tc) => options.toolExecutor.execute(tc.name, tc.id, tc.input)));
+                // --- Layer 1: cap each tool result ---
+                for (let i = 0; i < results.length; i++) {
+                    const r = results[i];
+                    const tc = assistantMsg.toolCalls[i];
+                    r.content = resultCapper.cap(r.content, tc.name, tc.id, cache);
+                    activity.push({
+                        agent: label,
+                        action: `result:${tc.name}`,
+                        detail: `${r.content.length} chars — ${r.content.slice(0, 80).replace(/\n/g, ' ')}`,
+                    });
+                    executedToolCalls.push(tc);
+                    emit?.({ type: 'tool_call_complete', agent: label, toolCall: tc, result: r });
+                }
+                // Append tool-result messages.
+                for (const r of results) {
+                    localMessages.push({
+                        role: 'tool',
+                        toolCallId: r.toolCallId,
+                        content: r.content,
+                    });
+                }
+            }
+            // Round budget exhausted with no final text output.
+            activity.push({ agent: label, action: 'max_rounds_reached' });
+            const lastAssistant = [...localMessages]
+                .reverse()
+                .find((m) => m.role === 'assistant');
+            // We ran out of rounds while the model still wanted to call tools.
+            // Surface that as 'length'-adjacent: incomplete from the model's
+            // perspective, even if the wire-level reason was 'tool_calls'.
+            return finalize(lastAssistant?.content ?? '{}', 'length');
+        }
+        catch (err) {
+            const e = err;
+            if (isAbortError(err)) {
+                activity.push({ agent: label, action: 'aborted', detail: e.message?.slice(0, 120) });
+                return finalize('', 'error');
+            }
+            activity.push({ agent: label, action: 'error', detail: e.message?.slice(0, 120) });
+            if (attempt < maxRetries && isRetryableError(err)) {
+                const delay = 2000 + Math.random() * 3000;
+                activity.push({
+                    agent: label,
+                    action: 'retry',
+                    detail: `Retrying after ${e.message?.slice(0, 60)}`,
+                });
+                // eslint-disable-next-line no-console
+                console.warn(`[${label}] retryable error, waiting ${Math.round(delay)}ms: ${e.message?.slice(0, 100)}`);
+                await new Promise((r) => setTimeout(r, delay));
+                continue;
+            }
+            // eslint-disable-next-line no-console
+            console.error(`[${label}] agent failed (attempt ${attempt + 1}):`, e.message);
+            return finalize(JSON.stringify({ _error: true, message: e.message }), 'error');
+        }
+    }
+    return finalize('{}', 'error');
+}
+//# sourceMappingURL=runner.js.map

package/dist/agent/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/agent/runner.ts"],"names":[],"mappings":"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"}

package/dist/agent/stream-consumer.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Stream consumer — folds an OpenAI streaming chat-completion response into
+ * a single round's accumulated state (content, tool_calls, finish_reason,
+ * usage). Tool calls arrive as per-index deltas; we buffer by index and
+ * JSON-parse the args at the end.
+ *
+ * Pure data transform: takes an AsyncIterable of chunks, calls the supplied
+ * callback for each content delta, returns the assembled AccumulatedRound.
+ * No I/O, no logging, no agent state — keeps the consumer testable in
+ * isolation.
+ */
+import type { ChatCompletionChunk } from 'openai/resources/chat/completions.js';
+import type { ToolCall } from '../messages.js';
+import type { FinishReason, UsageInfo } from './types.js';
+/**
+ * @internal
+ *
+ * Internal accumulator shape — not part of the public API. May change
+ * between minor versions.
+ */
+export interface AccumulatedRound {
+    content: string;
+    toolCalls: ToolCall[];
+    finishReason: FinishReason;
+    usage: UsageInfo;
+}
+/**
+ * @internal
+ *
+ * Normalize OpenAI's finish_reason string into a `FinishReason` union.
+ * Exported for advanced callers (e.g. building a custom streaming consumer)
+ * but not part of the v1 stable surface.
+ */
+export declare function normalizeFinishReason(raw: string | null | undefined): FinishReason;
+/**
+ * @internal
+ *
+ * Heuristic: does this content look like a tool call that leaked through
+ * as plain text? Used by the agent loop to flag a missing/wrong
+ * inference-side `--tool-call-parser` configuration. Exported for callers
+ * that want to apply the same heuristic; not part of the v1 stable surface.
+ */
+export declare function looksLikeToolCallText(text: string): boolean;
+/**
+ * @internal
+ *
+ * Consume one streaming chat-completion response.
+ *
+ * Calls `onContentDelta` synchronously for each chunk's content fragment so
+ * the caller can surface them upstream as they arrive. Returns the assembled
+ * round once the stream ends.
+ *
+ * Exported for advanced callers (e.g. building a non-loop agent that just
+ * streams once and returns); not part of the v1 stable surface.
+ */
+export declare function consumeStream(stream: AsyncIterable<ChatCompletionChunk>, onContentDelta: (delta: string) => void): Promise<AccumulatedRound>;
+//# sourceMappingURL=stream-consumer.d.ts.map

package/dist/agent/stream-consumer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-consumer.d.ts","sourceRoot":"","sources":["../../src/agent/stream-consumer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,sCAAsC,CAAC;AAChF,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE1D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,YAAY,EAAE,YAAY,CAAC;IAC3B,KAAK,EAAE,SAAS,CAAC;CAClB;AAQD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,YAAY,CAWlF;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAS3D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,aAAa,CACjC,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,EAC1C,cAAc,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GACtC,OAAO,CAAC,gBAAgB,CAAC,CA6E3B"}

package/dist/agent/stream-consumer.js

@@ -0,0 +1,126 @@
+/**
+ * Stream consumer — folds an OpenAI streaming chat-completion response into
+ * a single round's accumulated state (content, tool_calls, finish_reason,
+ * usage). Tool calls arrive as per-index deltas; we buffer by index and
+ * JSON-parse the args at the end.
+ *
+ * Pure data transform: takes an AsyncIterable of chunks, calls the supplied
+ * callback for each content delta, returns the assembled AccumulatedRound.
+ * No I/O, no logging, no agent state — keeps the consumer testable in
+ * isolation.
+ */
+/**
+ * @internal
+ *
+ * Normalize OpenAI's finish_reason string into a `FinishReason` union.
+ * Exported for advanced callers (e.g. building a custom streaming consumer)
+ * but not part of the v1 stable surface.
+ */
+export function normalizeFinishReason(raw) {
+    switch (raw) {
+        case 'stop':
+        case 'length':
+        case 'tool_calls':
+        case 'content_filter':
+        case 'function_call':
+            return raw;
+        default:
+            return 'unknown';
+    }
+}
+/**
+ * @internal
+ *
+ * Heuristic: does this content look like a tool call that leaked through
+ * as plain text? Used by the agent loop to flag a missing/wrong
+ * inference-side `--tool-call-parser` configuration. Exported for callers
+ * that want to apply the same heuristic; not part of the v1 stable surface.
+ */
+export function looksLikeToolCallText(text) {
+    const trimmed = text.trim();
+    if (!trimmed)
+        return false;
+    return (/^<tool_call\b/i.test(trimmed) ||
+        /^<function_call\b/i.test(trimmed) ||
+        /^\{\s*"name"\s*:/i.test(trimmed) ||
+        /^\{\s*"function"\s*:/i.test(trimmed));
+}
+/**
+ * @internal
+ *
+ * Consume one streaming chat-completion response.
+ *
+ * Calls `onContentDelta` synchronously for each chunk's content fragment so
+ * the caller can surface them upstream as they arrive. Returns the assembled
+ * round once the stream ends.
+ *
+ * Exported for advanced callers (e.g. building a non-loop agent that just
+ * streams once and returns); not part of the v1 stable surface.
+ */
+export async function consumeStream(stream, onContentDelta) {
+    const out = {
+        content: '',
+        toolCalls: [],
+        finishReason: 'unknown',
+        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+    };
+    // Tool calls stream as deltas keyed by index. Build them up by index, then
+    // flatten to ToolCall[] at the end.
+    const toolBuffers = new Map();
+    for await (const chunk of stream) {
+        // Some backends emit an extra terminal chunk with usage and no choices.
+        if (chunk.usage) {
+            out.usage = {
+                promptTokens: chunk.usage.prompt_tokens ?? 0,
+                completionTokens: chunk.usage.completion_tokens ?? 0,
+                totalTokens: chunk.usage.total_tokens ?? 0,
+            };
+        }
+        const choice = chunk.choices?.[0];
+        if (!choice)
+            continue;
+        const delta = choice.delta;
+        if (delta?.content) {
+            out.content += delta.content;
+            onContentDelta(delta.content);
+        }
+        if (delta?.tool_calls) {
+            for (const tcDelta of delta.tool_calls) {
+                const idx = tcDelta.index;
+                let buf = toolBuffers.get(idx);
+                if (!buf) {
+                    buf = { id: '', name: '', argsBuffer: '' };
+                    toolBuffers.set(idx, buf);
+                }
+                if (tcDelta.id)
+                    buf.id = tcDelta.id;
+                if (tcDelta.function?.name)
+                    buf.name = tcDelta.function.name;
+                if (tcDelta.function?.arguments)
+                    buf.argsBuffer += tcDelta.function.arguments;
+            }
+        }
+        if (choice.finish_reason) {
+            out.finishReason = normalizeFinishReason(choice.finish_reason);
+        }
+    }
+    // Flatten tool buffers in index order.
+    const indices = [...toolBuffers.keys()].sort((a, b) => a - b);
+    for (const idx of indices) {
+        const buf = toolBuffers.get(idx);
+        if (!buf.id || !buf.name) {
+            // Malformed tool call delta — skip rather than corrupt the loop.
+            continue;
+        }
+        let input = {};
+        try {
+            input = buf.argsBuffer ? JSON.parse(buf.argsBuffer) : {};
+        }
+        catch {
+            input = { _raw: buf.argsBuffer };
+        }
+        out.toolCalls.push({ id: buf.id, name: buf.name, input });
+    }
+    return out;
+}
+//# sourceMappingURL=stream-consumer.js.map

package/dist/agent/stream-consumer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stream-consumer.js","sourceRoot":"","sources":["../../src/agent/stream-consumer.ts"],"names":[],"mappings":"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"}

package/dist/agent/types.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Public types for the agent runner.
+ *
+ * Kept separate from the loop so callers can import the surface without
+ * pulling in the streaming machinery, and so the type surface is easy to
+ * audit at a glance.
+ */
+import type OpenAI from 'openai';
+import type { ToolCall, ToolDefinition, ToolExecutor, ToolResult } from '../messages.js';
+import type { TokenBudgetTracker } from '../context/token-budget.js';
+import type { ResultCapper } from '../context/result-capper.js';
+import type { CompressorStrategy } from '../context/compressor.js';
+import type { PipelineCache } from '../cache.js';
+export interface AgentConfig {
+    /** Identifier surfaced in activity logs. */
+    name: string;
+    systemPrompt: string;
+    /** Model name passed to the inference endpoint. Empty string → caller-default. */
+    model: string;
+    tools: ToolDefinition[];
+    /** Max rounds of tool use before forcing a final response. */
+    maxToolRounds: number;
+    /** Max tokens for the model's response. */
+    maxTokens: number;
+    /**
+     * Extra fields merged into the chat-completions request body. Use for
+     * provider-specific extensions that aren't in the OpenAI spec — e.g. vLLM's
+     * `chat_template_kwargs: { enable_thinking: false }` to disable Qwen3 reasoning,
+     * or `top_k`, `repetition_penalty`, etc.
+     *
+     * Merged via spread; if a key collides with one the runner sets explicitly
+     * (model, max_tokens, messages, tools, stream), the runner's value wins.
+     */
+    extraBody?: Record<string, unknown>;
+}
+export interface ActivityEntry {
+    agent: string;
+    action: string;
+    detail?: string;
+}
+/**
+ * `finishReason` mirrors OpenAI's `choices[0].finish_reason`. Callers that
+ * need to detect truncation should branch on `'length'` (= max_tokens hit,
+ * output cut off mid-stream). `'unknown'` is used when the backend never
+ * surfaced a reason (e.g. a stream that errored mid-flight).
+ */
+export type FinishReason = 'stop' | 'length' | 'tool_calls' | 'content_filter' | 'function_call' | 'error' | 'unknown';
+export interface UsageInfo {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+export interface AgentRunResult {
+    /** Final text output from the agent. May be JSON; caller can parseJSON it. */
+    text: string;
+    activity: ActivityEntry[];
+    /**
+     * Reason the agent stopped. `'stop'` = clean finish, `'length'` = truncated
+     * (max_tokens hit), `'tool_calls'` = stopped to call tools (rare at the top
+     * level since the loop continues), `'error'` = surfaced from a thrown error
+     * inside the loop, `'unknown'` = backend never reported one.
+     */
+    finishReason: FinishReason;
+    /** Token usage summed across every inference round in this run. */
+    usage: UsageInfo;
+    /**
+     * Every tool call the agent actually executed during this run, in order.
+     * Use this rather than parsing `activity[]` to verify what the agent did
+     * vs. what it claimed in its text/JSON output.
+     */
+    executedToolCalls: ToolCall[];
+}
+/**
+ * Streaming events fed to `AgentRunnerOptions.onStreamEvent`.
+ *
+ * - `content_delta`: chunk of model content as it streams.
+ * - `tool_call_started`: assistant emitted a tool call (post-decode).
+ * - `tool_call_complete`: tool executed, result capped, content available.
+ * - `round_complete`: one tool-use round just finished.
+ */
+export type AgentStreamEvent = {
+    type: 'content_delta';
+    agent: string;
+    delta: string;
+} | {
+    type: 'tool_call_started';
+    agent: string;
+    toolCall: ToolCall;
+} | {
+    type: 'tool_call_complete';
+    agent: string;
+    toolCall: ToolCall;
+    result: ToolResult;
+} | {
+    type: 'round_complete';
+    agent: string;
+    round: number;
+    finishReason: FinishReason;
+};
+export interface AgentRunnerOptions {
+    client: OpenAI;
+    toolExecutor: ToolExecutor;
+    /** Per-pipeline cache shared with the result capper for full-result retrieval. */
+    cache?: PipelineCache | null;
+    budgetTracker?: TokenBudgetTracker;
+    resultCapper?: ResultCapper;
+    compressor?: CompressorStrategy;
+    aggressiveCompressor?: CompressorStrategy;
+    /** Number of full retry attempts on retryable errors (default 1 = retry once). */
+    maxRetries?: number;
+    /**
+     * Cancellation signal. When aborted: the in-flight stream is cancelled
+     * (passed through to `client.chat.completions.create({ signal })`), the
+     * loop stops between rounds, and the runner returns whatever it has so far
+     * with `finishReason: 'error'`.
+     */
+    signal?: AbortSignal;
+    /**
+     * Optional streaming sink. Receives content deltas as they arrive plus
+     * tool-call lifecycle events. Synchronous callbacks only — don't await
+     * inside; if you need async work, schedule it.
+     */
+    onStreamEvent?: (event: AgentStreamEvent) => void;
+    /**
+     * Defensive validation hook called once per run, just before returning.
+     * Receives the assembled `AgentRunResult` (with `executedToolCalls` already
+     * populated) and may either return a transformed result or throw to mark
+     * the run as failed. Use this to verify the agent's claimed output against
+     * what was actually executed — the canonical way to catch silent
+     * confabulation where a small model says "I created file X" without ever
+     * calling the write tool.
+     */
+    verifyResult?: (result: AgentRunResult) => Promise<AgentRunResult> | AgentRunResult;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"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"}

package/dist/agent/types.js

@@ -0,0 +1,9 @@
+/**
+ * Public types for the agent runner.
+ *
+ * Kept separate from the loop so callers can import the surface without
+ * pulling in the streaming machinery, and so the type surface is easy to
+ * audit at a glance.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/agent/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/agent/types.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/agent-runner.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Backward-compat shim — the agent runner was split into focused modules
+ * under `./agent/`. This file re-exports the same public surface so existing
+ * imports continue to work.
+ *
+ * For new code, import from `thread-phase` (or directly from `./agent/*`)
+ * rather than this path.
+ */
+export { runAgentWithTools, parseJSON, type AgentConfig, type ActivityEntry, type AgentRunResult, type AgentRunnerOptions, type AgentStreamEvent, type FinishReason, type UsageInfo, } from './agent/index.js';
+//# sourceMappingURL=agent-runner.d.ts.map

package/dist/agent-runner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-runner.d.ts","sourceRoot":"","sources":["../src/agent-runner.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,iBAAiB,EACjB,SAAS,EACT,KAAK,WAAW,EAChB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,SAAS,GACf,MAAM,kBAAkB,CAAC"}