@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/engine/turn-loop.js

@@ -0,0 +1,602 @@
+/**
+ * Turn loop — state machine implementation.
+ *
+ * Following Claude Code's po_() pattern:
+ * pre_check → model_call → post_check → tool_exec → context_mgmt → hook_notify → next turn
+ */
+import { initialTurnState, newTurnId } from "./turn-state.js";
+import { wrapHookMessages } from "../hooks/inject.js";
+import { ContextLimitError } from "../exceptions.js";
+import { logger } from "../logging/logger.js";
+import { checkTokenBudget, createBudgetTracker } from "./token-budget.js";
+import { StreamingToolQueue } from "./streaming-tool-queue.js";
+import { estimateTokens } from "../context/compaction.js";
+export class TurnLoop {
+    deps;
+    config;
+    turnCount = 0;
+    /** Tool IDs already emitted as tool_use_start during streaming (to avoid duplicates). */
+    streamedToolIds = new Set();
+    /**
+     * Turn-scoped child logger set at the top of each loop iteration. Class
+     * methods invoked inside the iteration (callModelWithFallback,
+     * executeToolCall, ...) read it instead of using the root `logger`, so
+     * every line they write is tagged with the current turn/turnId.
+     */
+    currentTurnLog = logger;
+    /** Last emitted ctx token estimate; used to skip no-op usage_update events. */
+    lastCtxEmit = -1;
+    constructor(deps, config) {
+        this.deps = deps;
+        this.config = config;
+        // Wrap onStream so a single throwing handler can't silently break
+        // the channel for the rest of the run. A 2026-05-25 incident saw a
+        // sub-agent's events stop reaching the renderer ~23s into its run —
+        // the engine kept executing tools, but every subsequent stream emit
+        // was happening into a dead pipe. With this guard the failure shows
+        // up in ~/.code-shell/logs/engine-*.log with the offending event
+        // type, instead of presenting as a frozen UI.
+        //
+        // We replace `config.onStream` so the wrap covers BOTH direct calls
+        // (`this.config.onStream?.({...})` inside this class) AND places
+        // where the reference is passed onward (ModelFacade, StreamingToolQueue).
+        if (this.config.onStream) {
+            const inner = this.config.onStream;
+            this.config = {
+                ...this.config,
+                onStream: (event) => {
+                    try {
+                        inner(event);
+                    }
+                    catch (err) {
+                        // Use root logger, not currentTurnLog — this can fire from
+                        // outside a turn iteration (e.g. ModelFacade after run() resolves).
+                        logger.warn("stream.handler_threw", {
+                            eventType: event.type,
+                            error: err.message,
+                            stack: err.stack?.split("\n").slice(0, 4).join("\n"),
+                        });
+                    }
+                },
+            };
+        }
+    }
+    /**
+     * Emit a lifecycle hook with isSubAgent + sessionId auto-merged into data.
+     * Returns the aggregated HookResult so callers can consume `messages` /
+     * `decision` / `stop`. Use this instead of `deps.hooks.emit` directly so
+     * every emit carries the same context envelope.
+     */
+    async emitHook(event, data = {}) {
+        return this.deps.hooks.emit(event, {
+            ...data,
+            isSubAgent: this.deps.isSubAgent === true,
+            sessionId: this.deps.sessionId,
+        });
+    }
+    /**
+     * Emit a usage_update so the UI ctx bar reflects current message-array
+     * size. Called at every point where messages mutate: after a tool_result
+     * is appended, after context management (which may shrink), and after an
+     * LLM response (which we also feed through with the provider's authoritative
+     * promptTokens to override our estimate).
+     */
+    emitCtxFromMessages(messages) {
+        if (!this.config.onStream)
+            return;
+        // Messages-only estimate is missing system prompt + tool defs (typically
+        // ~16k tokens). Pull the cached overhead derived from the previous LLM
+        // response to keep the ctx bar in the same ballpark as the real prompt.
+        // Without this, the bar drops to ~1k every time tool results land.
+        const msgsEstimate = estimateTokens(messages);
+        const overhead = this.deps.ctxOverheadStore.get(this.deps.sessionId);
+        const ctx = msgsEstimate + overhead;
+        this.currentTurnLog.info("debug.ctx.emit", {
+            src: "messages",
+            value: ctx,
+            msgsEstimate,
+            overhead,
+            msgCount: messages.length,
+            prev: this.lastCtxEmit,
+        });
+        if (ctx === this.lastCtxEmit)
+            return;
+        this.lastCtxEmit = ctx;
+        this.config.onStream({ type: "usage_update", promptTokens: ctx });
+    }
+    emitCtxFromUsage(promptTokens, messages) {
+        if (!this.config.onStream)
+            return;
+        // Reverse-derive overhead from this authoritative reading so the next
+        // estimate-based emit (post-tool-result) is calibrated.
+        const msgsEstimate = estimateTokens(messages);
+        const overhead = Math.max(0, promptTokens - msgsEstimate);
+        this.deps.ctxOverheadStore.set(this.deps.sessionId, overhead);
+        this.currentTurnLog.info("debug.ctx.emit", {
+            src: "usage",
+            value: promptTokens,
+            msgsEstimate,
+            derivedOverhead: overhead,
+            prev: this.lastCtxEmit,
+        });
+        if (promptTokens === this.lastCtxEmit)
+            return;
+        this.lastCtxEmit = promptTokens;
+        this.config.onStream({ type: "usage_update", promptTokens });
+    }
+    /**
+     * Run the multi-turn agent loop until completion.
+     */
+    async run(initialMessages) {
+        let messages = [...initialMessages];
+        let finalText = "";
+        const budgetTracker = createBudgetTracker();
+        while (this.turnCount < this.config.maxTurns) {
+            this.turnCount++;
+            const state = initialTurnState(this.turnCount);
+            // Per-turn correlation ID. Every log written through `tlog` (or any
+            // child derived from it) is stamped with `turn` + `turnId`, so
+            // `jq 'select(.turnId == "...")'` reconstructs one turn's timeline.
+            // Span is *not* used for the loop itself because there are 6+ early
+            // returns; instead, each return-causing branch logs its own terminal
+            // event (model_error, completed, etc.).
+            const turnId = newTurnId();
+            const tlog = logger.child({ turn: this.turnCount, turnId });
+            this.currentTurnLog = tlog;
+            const turnStartedAt = Date.now();
+            tlog.info("turn.start", { cat: "turn", messageCount: messages.length });
+            // Tag downstream tool-exec / permission lines with this turn's IDs.
+            this.deps.toolExecutor.setLogger(tlog);
+            this.config.onStream?.({ type: "stream_request_start", turnNumber: this.turnCount });
+            const turnStartHook = await this.emitHook("on_turn_start", {
+                turnNumber: this.turnCount,
+            });
+            const turnStartInjection = wrapHookMessages(turnStartHook.messages);
+            if (turnStartInjection) {
+                messages.push(turnStartInjection);
+            }
+            // Approaching max turns: inject a warning so the model can wrap up
+            const turnsRemaining = this.config.maxTurns - this.turnCount;
+            if (turnsRemaining === 2) {
+                messages.push({
+                    role: "user",
+                    content: "<system-reminder>Warning: you have only 2 turns remaining before the turn limit is reached. " +
+                        "Start wrapping up your work and prepare a summary of what you've accomplished and what remains to be done.</system-reminder>",
+                });
+            }
+            else if (turnsRemaining === 0) {
+                messages.push({
+                    role: "user",
+                    content: "<system-reminder>This is your LAST turn. You MUST respond with a final text summary now. " +
+                        "Do NOT call any tools. Summarize what you have accomplished and list any remaining work.</system-reminder>",
+                });
+            }
+            // Pre-check: context management (async — may trigger LLM summarization)
+            messages = await this.deps.contextManager.manageAsync(messages);
+            // No pre-llm ctx emit here: the messages-only estimate would be ~16k
+            // smaller than the real prompt (system + tools not included), making
+            // the bar visibly drop on every submit. Post-llm/post-tool-result
+            // events carry an accurate value; if compaction shrank the array, the
+            // dedicated context_compact event has already informed the UI.
+            // post_compact hook: ContextManager just finished a manage() pass.
+            // If any non-micro tier fired, give handlers a chance to inject a
+            // <system-reminder> ("context was compacted — recall earlier
+            // decisions from the transcript") into THIS turn before the model
+            // call. Microcompact is lossless (just clearing redundant
+            // tool_results) so we suppress hook emits for it to keep token
+            // overhead down.
+            const pending = this.deps.consumePendingCompactInfo?.();
+            if (pending && pending.strategy !== "micro") {
+                const compactHook = await this.emitHook("post_compact", {
+                    strategy: pending.strategy,
+                    beforeTokens: pending.before,
+                    afterTokens: pending.after,
+                });
+                const compactInjection = wrapHookMessages(compactHook.messages);
+                if (compactInjection) {
+                    messages.push(compactInjection);
+                }
+            }
+            // Model call (with streaming fallback and max_output_tokens continuation)
+            // Track tool IDs streamed during this turn to avoid duplicate UI events
+            this.streamedToolIds.clear();
+            // Streaming tool queue: start concurrency-safe tools during streaming
+            const streamingQueue = new StreamingToolQueue(this.deps.toolExecutor);
+            let response;
+            try {
+                response = await this.callModelWithFallback(messages);
+            }
+            catch (err) {
+                if (err instanceof ContextLimitError) {
+                    // Progressive recovery: drop oldest API rounds, up to 3 retries
+                    const { dropOldestRounds } = await import("../context/compaction.js");
+                    let recovered = false;
+                    for (let retry = 1; retry <= 3; retry++) {
+                        tlog.warn("turn.ptl_recovery", { cat: "turn", retry, roundsToDrop: retry });
+                        messages = dropOldestRounds(messages, retry);
+                        try {
+                            response = await this.callModelWithFallback(messages);
+                            recovered = true;
+                            break;
+                        }
+                        catch (retryErr) {
+                            if (!(retryErr instanceof ContextLimitError)) {
+                                this.config.onStream?.({ type: "error", error: retryErr.message });
+                                return { text: finalText, reason: "model_error", messages };
+                            }
+                        }
+                    }
+                    if (!recovered) {
+                        this.patchOrphanedToolUses(messages);
+                        this.config.onStream?.({
+                            type: "error",
+                            error: "Context limit exceeded after 3 recovery attempts",
+                        });
+                        return { text: finalText, reason: "prompt_too_long", messages };
+                    }
+                }
+                else {
+                    this.patchOrphanedToolUses(messages);
+                    this.config.onStream?.({ type: "error", error: err.message });
+                    return { text: finalText, reason: "model_error", messages };
+                }
+            }
+            // UI ctx bar: prefer the provider's authoritative promptTokens.
+            if (response.usage?.promptTokens !== undefined) {
+                this.emitCtxFromUsage(response.usage.promptTokens, messages);
+            }
+            // Feed actual token usage back to the context manager so subsequent
+            // compaction decisions use hybrid (actual + delta) estimation rather than
+            // pure heuristics. Without this the manager falls back to char/4 estimates.
+            if (response.usage?.promptTokens !== undefined) {
+                this.deps.contextManager.recordActualUsage(response.usage.promptTokens, messages.length);
+            }
+            // Handle max_output_tokens: if response was truncated, do continuation (up to 3 times)
+            if (response.stopReason === "max_tokens" &&
+                response.toolCalls.length === 0 &&
+                response.text) {
+                let combinedText = response.text;
+                for (let retry = 0; retry < 3; retry++) {
+                    tlog.info("turn.max_tokens_continuation", { cat: "turn", retry: retry + 1 });
+                    const contMessages = [
+                        ...messages,
+                        { role: "assistant", content: combinedText },
+                        {
+                            role: "user",
+                            content: "<system-reminder>Your previous response was truncated due to length. Please continue from where you left off.</system-reminder>",
+                        },
+                    ];
+                    try {
+                        const contResponse = await this.deps.model.call(this.deps.systemPrompt, contMessages, this.deps.tools, this.config.onStream, this.config.signal);
+                        combinedText += contResponse.text;
+                        if (contResponse.stopReason !== "max_tokens" || contResponse.toolCalls.length > 0) {
+                            response = { ...contResponse, text: combinedText };
+                            break;
+                        }
+                    }
+                    catch {
+                        break;
+                    }
+                }
+                response = { ...response, text: combinedText };
+            }
+            // After any continuation, send latest usage so ctx bar reflects real context
+            if (response.usage?.promptTokens !== undefined) {
+                this.emitCtxFromUsage(response.usage.promptTokens, messages);
+            }
+            // Aborted?
+            if (this.config.signal?.aborted) {
+                return { text: finalText, reason: "aborted_streaming", messages };
+            }
+            // Accumulate text
+            if (response.text) {
+                finalText = response.text;
+            }
+            // Post-check: tool calls?
+            if (response.toolCalls.length === 0) {
+                // No tool use — final answer
+                this.config.onStream?.({
+                    type: "assistant_message",
+                    message: { role: "assistant", content: finalText },
+                });
+                await this.emitHook("on_turn_end", {
+                    turnNumber: this.turnCount,
+                    hasToolUse: false,
+                });
+                messages.push({ role: "assistant", content: finalText });
+                return { text: finalText, reason: "completed", messages };
+            }
+            // Tool execution phase
+            tlog.info("turn.tool_use", { cat: "turn", tools: response.toolCalls.map((t) => t.toolName) });
+            const toolCalls = response.toolCalls.slice(0, this.config.maxToolCallsPerTurn);
+            // Add assistant message with tool_use blocks to messages
+            const assistantBlocks = [];
+            if (response.text) {
+                assistantBlocks.push({ type: "text", text: response.text });
+            }
+            for (const tc of toolCalls) {
+                assistantBlocks.push({
+                    type: "tool_use",
+                    id: tc.id,
+                    name: tc.toolName,
+                    input: tc.args,
+                });
+                // Only emit tool_use_start if not already emitted during streaming
+                if (!this.streamedToolIds.has(tc.id)) {
+                    this.config.onStream?.({ type: "tool_use_start", toolCall: tc });
+                }
+                // Record in transcript
+                this.deps.transcript.appendToolUse(tc.toolName, tc.id, tc.args);
+            }
+            messages.push({ role: "assistant", content: assistantBlocks });
+            // Execute tools — enqueue concurrency-safe tools for early start,
+            // drain remaining (unsafe) tools sequentially.
+            for (const tc of toolCalls) {
+                streamingQueue.enqueue(tc);
+            }
+            const results = await streamingQueue.drain();
+            // Record results in transcript and stream
+            const resultBlocks = [];
+            for (const result of results) {
+                const content = result.error ? `Error: ${result.error}` : (result.result ?? "(no output)");
+                resultBlocks.push({
+                    type: "tool_result",
+                    tool_use_id: result.id,
+                    content,
+                });
+                this.deps.transcript.appendToolResult(result.id, result.toolName, result.result, result.error);
+                this.config.onStream?.({ type: "tool_result", result });
+            }
+            // Fire-and-forget tool use summary (non-blocking)
+            if (this.config.onStream) {
+                import("./tool-summary.js").then(({ generateToolUseSummary }) => {
+                    if (!this.deps.model.summarize)
+                        return;
+                    generateToolUseSummary(toolCalls, results, this.deps.model.summarize).then((summary) => {
+                        if (summary) {
+                            this.config.onStream?.({ type: "tool_summary", summary });
+                        }
+                    });
+                });
+            }
+            messages.push({ role: "user", content: resultBlocks });
+            // Tool results just pushed; recompute ctx so the bar updates *before*
+            // the next model round-trip — large tool outputs can move it sharply.
+            this.emitCtxFromMessages(messages);
+            // Token budget check
+            const totalOutputTokens = this.deps.model.getOutputTokens?.() ?? 0;
+            const budgetDecision = checkTokenBudget(totalOutputTokens, this.config.tokenBudget ?? Infinity, budgetTracker);
+            if (budgetDecision === "stop") {
+                tlog.info("turn.budget_stop", {
+                    cat: "turn",
+                    outputTokens: totalOutputTokens,
+                    budget: this.config.tokenBudget,
+                });
+                this.config.onStream?.({
+                    type: "assistant_message",
+                    message: { role: "assistant", content: finalText },
+                });
+                messages.push({ role: "assistant", content: finalText });
+                return { text: finalText, reason: "completed", messages };
+            }
+            if (budgetDecision === "nudge") {
+                messages.push({
+                    role: "user",
+                    content: "<system-reminder>You are approaching the token budget limit. Please start wrapping up your work and provide a summary.</system-reminder>",
+                });
+            }
+            // Investigation guard: end-of-turn check. If too many consecutive
+            // read-only turns went by without any user-visible text or side-effecting
+            // tool, inject a reminder that will land at the top of the next turn.
+            const guard = this.deps.toolExecutor.getInvestigationGuard();
+            if (guard) {
+                guard.noteText(response.text);
+                const turnReminder = guard.turnEnded(this.turnCount);
+                if (turnReminder) {
+                    messages.push({ role: "user", content: turnReminder });
+                    tlog.info("guard.silent_turn", { cat: "guard", turn: this.turnCount });
+                }
+            }
+            // Task guard: nudge the model if it has an in_progress task that
+            // hasn't moved in several turns. TaskCreate is sticky in working
+            // memory for the first few turns only; without this, the spinner
+            // runs forever on tasks the model has mentally finished.
+            const taskGuard = this.deps.toolExecutor.getTaskGuard();
+            if (taskGuard) {
+                const taskReminder = taskGuard.turnEnded(this.turnCount);
+                if (taskReminder) {
+                    messages.push({ role: "user", content: taskReminder });
+                    tlog.info("guard.stale_task", { cat: "guard", turn: this.turnCount });
+                }
+            }
+            // Hook: turn end
+            await this.emitHook("on_turn_end", {
+                turnNumber: this.turnCount,
+                hasToolUse: true,
+                toolCallCount: toolCalls.length,
+            });
+            // Record turn boundary
+            this.deps.transcript.appendTurnBoundary();
+            this.config.onTurnBoundary?.(this.turnCount);
+            tlog.info("turn.end", {
+                cat: "turn",
+                duration_ms: Date.now() - turnStartedAt,
+                outcome: "continue",
+            });
+        }
+        // Max turns reached — do one final summarization call (no tools)
+        logger.warn("turn.max_turns_reached", {
+            cat: "turn",
+            maxTurns: this.config.maxTurns,
+            turnCount: this.turnCount,
+        });
+        messages = this.deps.contextManager.manage(messages);
+        messages.push({
+            role: "user",
+            content: "<system-reminder>Turn limit reached. Provide a final summary of what you accomplished and what remains to be done. Do NOT call any tools.</system-reminder>",
+        });
+        this.emitCtxFromMessages(messages);
+        try {
+            const summaryResponse = await this.deps.model.call(this.deps.systemPrompt, messages, [], // No tools available for summary turn
+            this.config.onStream, this.config.signal);
+            if (summaryResponse.text) {
+                finalText = summaryResponse.text;
+            }
+        }
+        catch {
+            // If even summary fails, just return what we have
+            this.currentTurnLog.warn("turn.summary_failed", { cat: "turn" });
+        }
+        if (finalText) {
+            this.config.onStream?.({
+                type: "assistant_message",
+                message: { role: "assistant", content: finalText },
+            });
+            messages.push({ role: "assistant", content: finalText });
+        }
+        this.config.onStream?.({ type: "turn_complete", reason: "max_turns" });
+        return { text: finalText, reason: "max_turns", messages };
+    }
+    /**
+     * Call model with streaming fallback.
+     * If streaming fails, emit tombstone and retry non-streaming.
+     */
+    async callModelWithFallback(messages) {
+        // Wrap stream callback to track tool_use_start events and reactive compaction
+        let streamingResponseTokens = 0;
+        const wrappedStream = this.config.onStream
+            ? (event) => {
+                if (event.type === "tool_use_start" && event.toolCall?.id) {
+                    this.streamedToolIds.add(event.toolCall.id);
+                }
+                // Track accumulating response size for reactive compaction
+                if (event.type === "text_delta" && event.text) {
+                    streamingResponseTokens += Math.ceil(event.text.length / 4);
+                }
+                // Reactive compaction warning: if nearing context limit mid-stream,
+                // log a warning (actual compaction happens between turns)
+                if (streamingResponseTokens > 0 && streamingResponseTokens % 2000 === 0) {
+                    if (this.deps.contextManager.shouldReactiveCompact(messages, streamingResponseTokens)) {
+                        this.currentTurnLog.warn("turn.reactive_compact_warning", {
+                            cat: "turn",
+                            responseTokens: streamingResponseTokens,
+                            turn: this.turnCount,
+                        });
+                    }
+                }
+                return this.config.onStream(event);
+            }
+            : undefined;
+        try {
+            return await this.deps.model.call(this.deps.systemPrompt, messages, this.deps.tools, wrappedStream, this.config.signal);
+        }
+        catch (err) {
+            // If it's a context or rate limit error, don't fallback — propagate
+            if (err instanceof ContextLimitError)
+                throw err;
+            // Streaming might have partially emitted — send tombstone to revoke
+            this.config.onStream?.({ type: "tombstone", messageId: `turn_${this.turnCount}` });
+            this.currentTurnLog.warn("turn.streaming_fallback", {
+                cat: "turn",
+                error: err.message,
+            });
+            // Retry without streaming
+            return await this.deps.model.callWithoutStreaming(this.deps.systemPrompt, messages, this.deps.tools, this.config.signal);
+        }
+    }
+    /**
+     * Execute tools with overlap: start concurrent-safe (read-only) tools
+     * immediately in parallel while sequential (write) tools run one-by-one.
+     * Both groups run simultaneously — we don't wait for safe tools to finish
+     * before starting unsafe ones.
+     */
+    async executeToolsOverlapped(calls) {
+        if (calls.length <= 1) {
+            // Single tool — no overlap needed
+            return this.deps.toolExecutor.executeAll(calls);
+        }
+        const safe = [];
+        const unsafe = [];
+        for (const call of calls) {
+            if (this.deps.toolExecutor.isConcurrencySafe(call.toolName)) {
+                safe.push(call);
+            }
+            else {
+                unsafe.push(call);
+            }
+        }
+        // If all same type, delegate directly
+        if (safe.length === 0 || unsafe.length === 0) {
+            return this.deps.toolExecutor.executeAll(calls);
+        }
+        // Run both groups simultaneously:
+        // - safe tools all in parallel
+        // - unsafe tools sequentially (but started at the same time as safe group)
+        const resultMap = new Map();
+        const safePromise = Promise.all(safe.map((c) => this.deps.toolExecutor.executeSingle(c)));
+        const unsafePromise = (async () => {
+            const results = [];
+            for (const call of unsafe) {
+                results.push(await this.deps.toolExecutor.executeSingle(call));
+            }
+            return results;
+        })();
+        const [safeResults, unsafeResults] = await Promise.all([safePromise, unsafePromise]);
+        for (const r of safeResults)
+            resultMap.set(r.id, r);
+        for (const r of unsafeResults)
+            resultMap.set(r.id, r);
+        // Return results in original call order for deterministic transcript
+        return calls.map((c) => resultMap.get(c.id));
+    }
+    get currentTurn() {
+        return this.turnCount;
+    }
+    /**
+     * Generate synthetic error tool_results for any dangling tool_use blocks
+     * that never received results (e.g. because the API call failed).
+     * Prevents model confusion on the next turn.
+     */
+    patchOrphanedToolUses(messages) {
+        // Find the last assistant message with tool_use blocks
+        for (let i = messages.length - 1; i >= 0; i--) {
+            const msg = messages[i];
+            if (msg.role !== "assistant" || !Array.isArray(msg.content))
+                continue;
+            const toolUseIds = [];
+            for (const block of msg.content) {
+                if (block.type === "tool_use" && block.id)
+                    toolUseIds.push(block.id);
+            }
+            if (toolUseIds.length === 0)
+                continue;
+            // Check if all tool_use IDs have corresponding tool_results
+            const answeredIds = new Set();
+            for (let j = i + 1; j < messages.length; j++) {
+                const rm = messages[j];
+                if (!Array.isArray(rm.content))
+                    continue;
+                for (const block of rm.content) {
+                    if (block.type === "tool_result" && block.tool_use_id) {
+                        answeredIds.add(block.tool_use_id);
+                    }
+                }
+            }
+            const orphanedIds = toolUseIds.filter((id) => !answeredIds.has(id));
+            if (orphanedIds.length === 0)
+                return;
+            // Inject synthetic error results
+            const errorBlocks = orphanedIds.map((id) => ({
+                type: "tool_result",
+                tool_use_id: id,
+                content: "Error: Tool execution was cancelled because the previous API call failed.",
+            }));
+            messages.push({ role: "user", content: errorBlocks });
+            this.currentTurnLog.warn("turn.patched_orphaned_tool_uses", {
+                cat: "turn",
+                count: orphanedIds.length,
+            });
+            return; // Only patch the most recent orphaned set
+        }
+    }
+}

package/dist/engine/turn-state.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Turn loop state definitions.
+ */
+import type { TurnPhase, ToolCall, LLMResponse, TerminalReason } from "../types.js";
+export interface TurnState {
+    phase: TurnPhase;
+    turnNumber: number;
+    modelResponse?: LLMResponse;
+    toolCalls?: ToolCall[];
+    finalText?: string;
+    error?: Error;
+    terminalReason?: TerminalReason;
+}
+export declare function initialTurnState(turnNumber: number): TurnState;
+/**
+ * Short, human-readable turn correlation ID. Stamped on every log entry
+ * written for the duration of one turn so `jq 'select(.turnId == "abc123")'`
+ * pulls a single turn's whole timeline out of the daily log file.
+ */
+export declare function newTurnId(): string;

package/dist/engine/turn-state.js

@@ -0,0 +1,17 @@
+/**
+ * Turn loop state definitions.
+ */
+export function initialTurnState(turnNumber) {
+    return {
+        phase: "pre_check",
+        turnNumber,
+    };
+}
+/**
+ * Short, human-readable turn correlation ID. Stamped on every log entry
+ * written for the duration of one turn so `jq 'select(.turnId == "abc123")'`
+ * pulls a single turn's whole timeline out of the daily log file.
+ */
+export function newTurnId() {
+    return `t${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}