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

package/dist/engine/query.js

@@ -0,0 +1,107 @@
+/**
+ * High-level query API — async generator wrapping TurnLoop.
+ *
+ * Callers consume events via `for await (const event of query(params))`.
+ * This is the public entry point for running agentic queries; TurnLoop
+ * is the internal state machine.
+ *
+ * Adapted from restored-src/src/query.ts, simplified for Code Shell.
+ */
+import { TurnLoop } from "./turn-loop.js";
+import { logger } from "../logging/logger.js";
+// ─── Query generator ────────────────────────────────────────────────
+/**
+ * Run an agentic query and yield stream events as they occur.
+ *
+ * Usage:
+ *   const events: StreamEvent[] = [];
+ *   for await (const event of query(params)) {
+ *     events.push(event);
+ *   }
+ *   // last event contains the final result
+ */
+export async function* query(params) {
+    const { messages, systemPrompt, tools, maxTurns = 30, maxToolCallsPerTurn = 20, signal, deps, } = params;
+    // Collect events in a queue that the stream callback pushes to
+    const eventQueue = [];
+    let resolveWait = null;
+    const onStream = (event) => {
+        eventQueue.push(event);
+        if (resolveWait) {
+            resolveWait();
+            resolveWait = null;
+        }
+    };
+    const config = {
+        maxTurns,
+        maxToolCallsPerTurn,
+        onStream,
+        signal,
+    };
+    // Local overhead store — query() is a standalone entry point without a real
+    // session id, so per-call in-memory state is enough.
+    let localOverhead = 0;
+    const loopDeps = {
+        model: deps.model,
+        toolExecutor: deps.toolExecutor,
+        contextManager: deps.contextManager,
+        hooks: deps.hooks,
+        transcript: deps.transcript,
+        systemPrompt,
+        tools,
+        sessionId: "query",
+        ctxOverheadStore: {
+            get: () => localOverhead,
+            set: (_s, n) => {
+                localOverhead = n;
+            },
+        },
+    };
+    const loop = new TurnLoop(loopDeps, config);
+    // Start the turn loop in the background
+    let result;
+    let loopError;
+    let loopDone = false;
+    const loopPromise = loop
+        .run(messages)
+        .then((r) => {
+        result = r;
+        loopDone = true;
+        // Wake up the yield loop
+        if (resolveWait) {
+            resolveWait();
+            resolveWait = null;
+        }
+    })
+        .catch((err) => {
+        loopError = err;
+        loopDone = true;
+        if (resolveWait) {
+            resolveWait();
+            resolveWait = null;
+        }
+    });
+    // Yield events as they arrive
+    while (!loopDone || eventQueue.length > 0) {
+        if (eventQueue.length > 0) {
+            yield eventQueue.shift();
+        }
+        else if (!loopDone) {
+            // Wait for next event or loop completion
+            await new Promise((resolve) => {
+                resolveWait = resolve;
+            });
+        }
+    }
+    // Ensure the loop promise is settled
+    await loopPromise;
+    if (loopError) {
+        logger.error("query.error", { error: loopError.message });
+        throw loopError;
+    }
+    return {
+        text: result.text,
+        reason: result.reason,
+        turnCount: loop.currentTurn,
+    };
+}

package/dist/engine/runtime.d.ts

@@ -0,0 +1,50 @@
+import type { ModelPool } from "../llm/model-pool.js";
+import type { ToolRegistry } from "../tool-system/registry.js";
+import type { SettingsManager } from "../settings/manager.js";
+import type { MCPManager } from "../tool-system/mcp-manager.js";
+import type { CostTracker } from "../cost-tracker.js";
+import { type SandboxBackend, type SandboxConfig } from "../tool-system/sandbox/index.js";
+export interface EngineRuntimeOptions {
+    modelPool: ModelPool;
+    toolRegistry: ToolRegistry;
+    settings: SettingsManager;
+    mcpPool: MCPManager;
+    costTracker: CostTracker;
+}
+/**
+ * Shared read-only resources used by all Engine instances in a worker.
+ * Mutable per-session state stays on Engine itself.
+ */
+export declare class EngineRuntime {
+    readonly modelPool: ModelPool;
+    readonly toolRegistry: ToolRegistry;
+    readonly settings: SettingsManager;
+    readonly mcpPool: MCPManager;
+    readonly costTracker: CostTracker;
+    private sandboxCache;
+    constructor(opts: EngineRuntimeOptions);
+    /**
+     * Lazily resolve and cache a sandbox backend for `(mode, cwd)`.
+     *
+     * Explicit modes (`seatbelt`, `bwrap`) propagate the underlying
+     * `resolveSandboxBackend` throw — there is no silent downgrade. Only
+     * `auto` may degrade to `off` (handled inside the resolver itself).
+     * The Engine must not catch the throw at turn time; doing so would
+     * violate standard §S4 fail-closed rule.
+     */
+    resolveSandbox(config: SandboxConfig, cwd: string): Promise<SandboxBackend>;
+    /**
+     * Tear down runtime-owned resources. Safe to call multiple times; the
+     * MCPManager's `disconnectAll` clears its own connection map and the
+     * sandbox cache holds resolved-backend promises that don't need
+     * explicit cleanup (they're plain objects). Closes Gate 2 bullet
+     * "runtime close shuts down MCP connections, timers, and background
+     * work."
+     *
+     * Hosts that own a long-lived Runtime (the stdio worker, future
+     * Electron broker, codeshell-serve) should `await runtime.close()`
+     * before exiting the process — otherwise MCP child processes may be
+     * left running and bound ports may stay held until the OS cleans up.
+     */
+    close(): Promise<void>;
+}

package/dist/engine/runtime.js

@@ -0,0 +1,59 @@
+import { resolveSandboxBackend, } from "../tool-system/sandbox/index.js";
+/**
+ * Shared read-only resources used by all Engine instances in a worker.
+ * Mutable per-session state stays on Engine itself.
+ */
+export class EngineRuntime {
+    modelPool;
+    toolRegistry;
+    settings;
+    mcpPool;
+    costTracker;
+    // A2: cached sandbox backends, keyed by (mode + cwd). The capability
+    // probe (seatbelt availability, bwrap binary) and the per-turn
+    // downgrade-to-off warning fire at most once per (mode, cwd) pair
+    // per Runtime — not once per turn.
+    sandboxCache = new Map();
+    constructor(opts) {
+        this.modelPool = opts.modelPool;
+        this.toolRegistry = opts.toolRegistry;
+        this.settings = opts.settings;
+        this.mcpPool = opts.mcpPool;
+        this.costTracker = opts.costTracker;
+    }
+    /**
+     * Lazily resolve and cache a sandbox backend for `(mode, cwd)`.
+     *
+     * Explicit modes (`seatbelt`, `bwrap`) propagate the underlying
+     * `resolveSandboxBackend` throw — there is no silent downgrade. Only
+     * `auto` may degrade to `off` (handled inside the resolver itself).
+     * The Engine must not catch the throw at turn time; doing so would
+     * violate standard §S4 fail-closed rule.
+     */
+    resolveSandbox(config, cwd) {
+        const key = `${config.mode}:${cwd}`;
+        let cached = this.sandboxCache.get(key);
+        if (!cached) {
+            cached = resolveSandboxBackend(config, cwd);
+            this.sandboxCache.set(key, cached);
+        }
+        return cached;
+    }
+    /**
+     * Tear down runtime-owned resources. Safe to call multiple times; the
+     * MCPManager's `disconnectAll` clears its own connection map and the
+     * sandbox cache holds resolved-backend promises that don't need
+     * explicit cleanup (they're plain objects). Closes Gate 2 bullet
+     * "runtime close shuts down MCP connections, timers, and background
+     * work."
+     *
+     * Hosts that own a long-lived Runtime (the stdio worker, future
+     * Electron broker, codeshell-serve) should `await runtime.close()`
+     * before exiting the process — otherwise MCP child processes may be
+     * left running and bound ports may stay held until the OS cleans up.
+     */
+    async close() {
+        await this.mcpPool.disconnectAll();
+        this.sandboxCache.clear();
+    }
+}

package/dist/engine/streaming-tool-queue.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Streaming tool queue — enqueues tools for execution during streaming,
+ * starts concurrency-safe tools immediately, queues unsafe tools for
+ * sequential execution.
+ *
+ * Usage:
+ *   const queue = new StreamingToolQueue(executor);
+ *   // During streaming, as tool_use blocks arrive:
+ *   queue.enqueue(toolCall);
+ *   // After streaming completes:
+ *   const results = await queue.drain();
+ */
+import type { ToolCall, ToolResult } from "../types.js";
+import type { ToolExecutor } from "../tool-system/executor.js";
+export declare class StreamingToolQueue {
+    private readonly executor;
+    private readonly pending;
+    private readonly unsafeQueue;
+    private readonly callOrder;
+    private draining;
+    constructor(executor: ToolExecutor);
+    /**
+     * Enqueue a tool for execution. Concurrency-safe tools start immediately;
+     * unsafe tools are queued for sequential execution during drain().
+     */
+    enqueue(call: ToolCall): void;
+    /**
+     * Execute all remaining unsafe tools sequentially, then await all results.
+     * Returns results in original enqueue order.
+     */
+    drain(): Promise<ToolResult[]>;
+    /** Number of tools currently enqueued or executing. */
+    get size(): number;
+}

package/dist/engine/streaming-tool-queue.js

@@ -0,0 +1,61 @@
+/**
+ * Streaming tool queue — enqueues tools for execution during streaming,
+ * starts concurrency-safe tools immediately, queues unsafe tools for
+ * sequential execution.
+ *
+ * Usage:
+ *   const queue = new StreamingToolQueue(executor);
+ *   // During streaming, as tool_use blocks arrive:
+ *   queue.enqueue(toolCall);
+ *   // After streaming completes:
+ *   const results = await queue.drain();
+ */
+export class StreamingToolQueue {
+    executor;
+    pending = new Map();
+    unsafeQueue = [];
+    callOrder = [];
+    draining = false;
+    constructor(executor) {
+        this.executor = executor;
+    }
+    /**
+     * Enqueue a tool for execution. Concurrency-safe tools start immediately;
+     * unsafe tools are queued for sequential execution during drain().
+     */
+    enqueue(call) {
+        this.callOrder.push(call.id);
+        if (this.executor.isConcurrencySafe(call.toolName)) {
+            // Start immediately
+            this.pending.set(call.id, this.executor.executeSingle(call));
+        }
+        else {
+            this.unsafeQueue.push(call);
+        }
+    }
+    /**
+     * Execute all remaining unsafe tools sequentially, then await all results.
+     * Returns results in original enqueue order.
+     */
+    async drain() {
+        if (this.draining)
+            throw new Error("StreamingToolQueue already draining");
+        this.draining = true;
+        // Execute unsafe tools sequentially
+        for (const call of this.unsafeQueue) {
+            this.pending.set(call.id, this.executor.executeSingle(call));
+            await this.pending.get(call.id);
+        }
+        // Await all results
+        const resultMap = new Map();
+        for (const [id, promise] of this.pending) {
+            resultMap.set(id, await promise);
+        }
+        // Return in original order
+        return this.callOrder.map((id) => resultMap.get(id));
+    }
+    /** Number of tools currently enqueued or executing. */
+    get size() {
+        return this.callOrder.length;
+    }
+}

package/dist/engine/token-budget.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Token budget — decides whether the agent loop should continue, nudge, or stop.
+ *
+ * - "continue": keep going normally
+ * - "nudge": inject a "please wrap up" message, but continue
+ * - "stop": terminate the loop gracefully
+ */
+export interface BudgetTracker {
+    continuationCount: number;
+    lastDeltaTokens: number;
+    prevTurnTokens: number;
+}
+export declare function createBudgetTracker(): BudgetTracker;
+export type BudgetDecision = "continue" | "nudge" | "stop";
+/**
+ * Check if the turn loop should continue based on token output budget.
+ *
+ * @param turnOutputTokens - tokens output so far this turn
+ * @param budget - max tokens allowed for this turn (Infinity = no limit)
+ * @param tracker - mutable tracker state (updated in place)
+ */
+export declare function checkTokenBudget(turnOutputTokens: number, budget: number, tracker: BudgetTracker): BudgetDecision;

package/dist/engine/token-budget.js

@@ -0,0 +1,40 @@
+/**
+ * Token budget — decides whether the agent loop should continue, nudge, or stop.
+ *
+ * - "continue": keep going normally
+ * - "nudge": inject a "please wrap up" message, but continue
+ * - "stop": terminate the loop gracefully
+ */
+export function createBudgetTracker() {
+    return { continuationCount: 0, lastDeltaTokens: Infinity, prevTurnTokens: 0 };
+}
+/**
+ * Check if the turn loop should continue based on token output budget.
+ *
+ * @param turnOutputTokens - tokens output so far this turn
+ * @param budget - max tokens allowed for this turn (Infinity = no limit)
+ * @param tracker - mutable tracker state (updated in place)
+ */
+export function checkTokenBudget(turnOutputTokens, budget, tracker) {
+    if (!isFinite(budget) || budget <= 0)
+        return "continue";
+    const pct = turnOutputTokens / budget;
+    const delta = turnOutputTokens - tracker.prevTurnTokens;
+    // Diminishing returns: 3+ continuations and last two deltas both < 500
+    const isDiminishing = tracker.continuationCount >= 3 &&
+        delta < 500 &&
+        tracker.lastDeltaTokens < 500;
+    // Update tracker
+    tracker.lastDeltaTokens = delta;
+    tracker.prevTurnTokens = turnOutputTokens;
+    // Stop: at/above threshold with prior nudge, or diminishing returns
+    if (tracker.continuationCount > 0 && (isDiminishing || pct >= 0.9)) {
+        return "stop";
+    }
+    // Nudge: approaching budget threshold
+    if (pct >= 0.9) {
+        tracker.continuationCount++;
+        return "nudge";
+    }
+    return "continue";
+}

package/dist/engine/tool-summary.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Tool use summary — generates a 1-line progress label after tool batch execution.
+ *
+ * Runs async (fire-and-forget) so it doesn't block the next model call.
+ * Returns a short commit-subject-style string like "Read 3 files, fixed NPE in auth.ts"
+ */
+import type { ToolCall, ToolResult } from "../types.js";
+export type SummarizeFn = (systemPrompt: string, userMessage: string) => Promise<string>;
+/**
+ * Generate a 1-line summary of completed tool executions.
+ * Returns null on failure (non-critical).
+ */
+export declare function generateToolUseSummary(toolCalls: ToolCall[], results: ToolResult[], summarize: SummarizeFn): Promise<string | null>;

package/dist/engine/tool-summary.js

@@ -0,0 +1,35 @@
+/**
+ * Tool use summary — generates a 1-line progress label after tool batch execution.
+ *
+ * Runs async (fire-and-forget) so it doesn't block the next model call.
+ * Returns a short commit-subject-style string like "Read 3 files, fixed NPE in auth.ts"
+ */
+import { logger } from "../logging/logger.js";
+const SUMMARY_SYSTEM_PROMPT = "Generate a very brief (under 40 chars) summary of what these tools did. " +
+    "Use past tense, commit-subject style. Examples: " +
+    '"Read 3 config files", "Fixed import in auth.ts", "Searched for API endpoints". ' +
+    "Respond with ONLY the summary text, nothing else.";
+/**
+ * Generate a 1-line summary of completed tool executions.
+ * Returns null on failure (non-critical).
+ */
+export async function generateToolUseSummary(toolCalls, results, summarize) {
+    if (toolCalls.length === 0)
+        return null;
+    try {
+        const parts = [];
+        for (let i = 0; i < toolCalls.length; i++) {
+            const tc = toolCalls[i];
+            const result = results[i];
+            const input = JSON.stringify(tc.args).slice(0, 200);
+            const output = (result?.result ?? result?.error ?? "").slice(0, 300);
+            parts.push(`Tool: ${tc.toolName}(${input}) → ${output}`);
+        }
+        const summary = await summarize(SUMMARY_SYSTEM_PROMPT, parts.join("\n"));
+        return summary?.trim() || null;
+    }
+    catch (err) {
+        logger.warn("tool_summary.failed", { error: err.message });
+        return null;
+    }
+}

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

@@ -0,0 +1,122 @@
+/**
+ * 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 type { Message, StreamCallback, TerminalReason } from "../types.js";
+import { ModelFacade } from "./model-facade.js";
+import { ToolExecutor } from "../tool-system/executor.js";
+import { ContextManager } from "../context/manager.js";
+import { HookRegistry } from "../hooks/registry.js";
+import { Transcript } from "../session/transcript.js";
+export interface TurnLoopConfig {
+    maxTurns: number;
+    maxToolCallsPerTurn: number;
+    tokenBudget?: number;
+    onStream?: StreamCallback;
+    signal?: AbortSignal;
+    /**
+     * Fired after each turn boundary is recorded. Lets the engine flush an
+     * up-to-date snapshot to state.json mid-run, so a long run doesn't leave
+     * the on-disk turnCount/status frozen at the last completion.
+     */
+    onTurnBoundary?: (turnCount: number) => void;
+}
+export interface CtxOverheadStore {
+    /** Tokens for system prompt + tool defs, derived from provider's promptTokens. */
+    get(sid: string): number;
+    set(sid: string, tokens: number): void;
+}
+export interface TurnLoopDeps {
+    model: ModelFacade;
+    toolExecutor: ToolExecutor;
+    contextManager: ContextManager;
+    hooks: HookRegistry;
+    transcript: Transcript;
+    systemPrompt: string;
+    tools: import("../types.js").ToolDefinition[];
+    /** Per-sid overhead cache so the ctx bar doesn't drop between turns. */
+    ctxOverheadStore: CtxOverheadStore;
+    /** Current session id, used to key the overhead store. */
+    sessionId: string;
+    /**
+     * Carried into every hook emit's `ctx.data.isSubAgent` so handlers can
+     * skip noisy injections for spawned children. Set by Engine from
+     * EngineConfig.isSubAgent (engine.ts:119).
+     */
+    isSubAgent?: boolean;
+    /**
+     * Reads/clears the most recent compaction event emitted by
+     * ContextManager since the last call. Returns `null` if no compaction
+     * fired since the previous check. The Engine wires this up so the
+     * turn loop can `post_compact` emit + inject hook messages without
+     * the ContextManager itself depending on HookRegistry.
+     */
+    consumePendingCompactInfo?: () => {
+        strategy: string;
+        before: number;
+        after: number;
+    } | null;
+}
+export interface TurnLoopResult {
+    text: string;
+    reason: TerminalReason;
+    messages: Message[];
+}
+export declare class TurnLoop {
+    private readonly deps;
+    private readonly config;
+    private turnCount;
+    /** Tool IDs already emitted as tool_use_start during streaming (to avoid duplicates). */
+    private streamedToolIds;
+    /**
+     * 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.
+     */
+    private currentTurnLog;
+    /** Last emitted ctx token estimate; used to skip no-op usage_update events. */
+    private lastCtxEmit;
+    constructor(deps: TurnLoopDeps, config: TurnLoopConfig);
+    /**
+     * 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.
+     */
+    private emitHook;
+    /**
+     * 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).
+     */
+    private emitCtxFromMessages;
+    private emitCtxFromUsage;
+    /**
+     * Run the multi-turn agent loop until completion.
+     */
+    run(initialMessages: Message[]): Promise<TurnLoopResult>;
+    /**
+     * Call model with streaming fallback.
+     * If streaming fails, emit tombstone and retry non-streaming.
+     */
+    private callModelWithFallback;
+    /**
+     * 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.
+     */
+    private executeToolsOverlapped;
+    get currentTurn(): number;
+    /**
+     * 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.
+     */
+    private patchOrphanedToolUses;
+}