@cjhyy/code-shell-core 0.7.0 → 0.8.0

package/dist/engine/subagent-spawner.d.ts

@@ -0,0 +1,32 @@
+import type { LLMConfig, StreamCallback } from "../types.js";
+import type { AgentPresetName } from "../preset/index.js";
+import type { ModelPool } from "../llm/model-pool.js";
+import type { SubAgentSpawner } from "../tool-system/context.js";
+import type { EngineConfig } from "./types.js";
+import type { ChildEngineRunner } from "./run-types.js";
+import { type SandboxConfig, type SandboxMode } from "../tool-system/sandbox/index.js";
+import type { MCPServerConfig } from "../types.js";
+export declare const NESTED_AGENT_TOOLS: string[];
+export declare function resolveChildLlm(modelKey: string | undefined, pool: ModelPool | undefined, parentLlm: LLMConfig): LLMConfig;
+export declare function resolveChildToolScope(allowlist: string[] | undefined, parentDisabled: string[] | undefined, parentEnabled: string[] | undefined): {
+    enabled?: string[];
+    disabled: string[];
+};
+export declare function resolveChildSandbox(mode: SandboxMode | undefined, parent: SandboxConfig): SandboxConfig;
+export declare function resolveChildMcpServers(allowlist: string[] | undefined, parent: Record<string, MCPServerConfig> | undefined): Record<string, MCPServerConfig> | undefined;
+export declare function wrapChildStream(destination: StreamCallback | undefined, agentId: string): StreamCallback | undefined;
+export interface CreateSubAgentSpawnerDeps {
+    parentConfig: EngineConfig;
+    /** Fully resolved sandbox for this parent run, including settings layers. */
+    parentSandbox: SandboxConfig;
+    presetName: AgentPresetName;
+    cwd: string;
+    permissionMode: NonNullable<EngineConfig["permissionMode"]>;
+    modelPool?: ModelPool;
+    appendParentSubagent: (agentId: string, description: string) => void;
+    sessionExists: (sessionId: string) => boolean;
+    getSessionParentId?: (sessionId: string) => string | null | undefined;
+    childRunner: ChildEngineRunner;
+    parentStream?: StreamCallback;
+}
+export declare function createSubAgentSpawner(deps: CreateSubAgentSpawnerDeps): SubAgentSpawner;

package/dist/engine/subagent-spawner.js

@@ -0,0 +1,287 @@
+import { buildAgentDirectionMessage, notificationQueue, } from "../tool-system/builtin/agent-notifications.js";
+import { nanoid } from "nanoid";
+import { defaultSandboxConfig, } from "../tool-system/sandbox/index.js";
+export const NESTED_AGENT_TOOLS = ["Agent", "AgentStatus", "AgentCancel", "AgentSendInput"];
+export function resolveChildLlm(modelKey, pool, parentLlm) {
+    if (modelKey && pool?.has(modelKey)) {
+        const resolved = pool.resolveLLMConfig(modelKey);
+        if (resolved)
+            return resolved;
+    }
+    return parentLlm;
+}
+export function resolveChildToolScope(allowlist, parentDisabled, parentEnabled) {
+    if (allowlist) {
+        return {
+            enabled: allowlist.filter((tool) => !NESTED_AGENT_TOOLS.includes(tool)),
+            disabled: [...NESTED_AGENT_TOOLS],
+        };
+    }
+    return {
+        enabled: parentEnabled?.filter((tool) => !NESTED_AGENT_TOOLS.includes(tool)),
+        disabled: Array.from(new Set([...(parentDisabled ?? []), ...NESTED_AGENT_TOOLS])),
+    };
+}
+export function resolveChildSandbox(mode, parent) {
+    if (mode === undefined)
+        return parent;
+    // Role definitions are project/plugin-authored capability constraints, not
+    // an authority to weaken the user's effective run sandbox. Explicit native
+    // backends are already fail-closed; keep them unchanged. `auto` may resolve
+    // to an isolated backend, so it likewise cannot be downgraded to off/auto.
+    if (parent.mode === "seatbelt" || parent.mode === "bwrap")
+        return parent;
+    if (parent.mode === "auto" && (mode === "off" || mode === "auto"))
+        return parent;
+    return { ...defaultSandboxConfig(mode), ...parent, mode };
+}
+export function resolveChildMcpServers(allowlist, parent) {
+    if (allowlist === undefined)
+        return parent;
+    const allowed = new Set(allowlist);
+    return Object.fromEntries(Object.entries(parent ?? {}).filter(([name]) => allowed.has(name)));
+}
+export function wrapChildStream(destination, agentId) {
+    if (!destination)
+        return undefined;
+    return (event) => {
+        if (event.type === "usage_update" ||
+            event.type === "session_started" ||
+            event.type === "context_compact") {
+            return;
+        }
+        destination({ ...event, agentId });
+    };
+}
+function wrapChildRuntimeStream(destination, agentId, onProgressEvent) {
+    const uiStream = wrapChildStream(destination, agentId);
+    if (!uiStream && !onProgressEvent)
+        return undefined;
+    return (event) => {
+        onProgressEvent?.(event);
+        return uiStream?.(event);
+    };
+}
+class ChildRunSupervisor {
+    runtime;
+    childSessionId;
+    runtimeGeneration;
+    state = "starting";
+    activeController;
+    interruptPending = false;
+    running = false;
+    intakeClosed = false;
+    pendingDelivered = new Map();
+    closeIntake;
+    constructor(runtime, childSessionId, runtimeGeneration) {
+        this.runtime = runtime;
+        this.childSessionId = childSessionId;
+        this.runtimeGeneration = runtimeGeneration;
+        runtime.setAgentControlStateListener((state) => {
+            this.state = state;
+        });
+        runtime.setAgentDirectionsDeliveredListener?.((envelopeIds) => {
+            for (const id of envelopeIds) {
+                const pending = this.pendingDelivered.get(id);
+                if (!pending)
+                    continue;
+                this.pendingDelivered.delete(id);
+                pending.resolve({ status: "delivered", ...pending.receipt });
+            }
+        });
+    }
+    setCloseIntake(closeIntake) {
+        this.closeIntake = closeIntake;
+    }
+    getState() {
+        return this.state;
+    }
+    routeDirection(draft) {
+        if (!this.running ||
+            this.intakeClosed ||
+            this.state === "closing" ||
+            this.state === "terminal") {
+            return { status: "rejected", reason: "intake-closed", rejectedAt: Date.now() };
+        }
+        const envelope = notificationQueue.enqueue(draft);
+        if (!envelope || envelope.kind !== "direction") {
+            return { status: "rejected", reason: "invalid-request", rejectedAt: Date.now() };
+        }
+        const receipt = {
+            envelopeId: envelope.id,
+            sequence: envelope.sequence,
+            correlationId: envelope.correlationId,
+            target: envelope.to,
+            acceptedAt: envelope.createdAt,
+        };
+        if (this.state === "safe-point") {
+            return new Promise((resolve) => {
+                this.pendingDelivered.set(envelope.id, { receipt, resolve });
+            });
+        }
+        if (draft.delivery === "interrupt-and-redrive" &&
+            !this.interruptPending &&
+            this.activeController &&
+            !this.activeController.signal.aborted) {
+            this.interruptPending = true;
+            this.state = "interrupting";
+            this.activeController.abort();
+            return { status: "interrupted", ...receipt };
+        }
+        return { status: "queued", ...receipt };
+    }
+    closeDirectionIntake() {
+        if (this.intakeClosed)
+            return;
+        this.intakeClosed = true;
+        this.state = "closing";
+        this.closeIntake?.();
+    }
+    drainDirections() {
+        return notificationQueue.drain(this.childSessionId, (envelope) => envelope.kind === "direction" && envelope.runtimeGeneration === this.runtimeGeneration);
+    }
+    async run(task, options) {
+        this.running = true;
+        let nextTask = task;
+        let agentDirection;
+        try {
+            for (;;) {
+                const controller = new AbortController();
+                this.activeController = controller;
+                const lifecycleSignal = options.signal;
+                const cascadeAbort = () => controller.abort();
+                if (lifecycleSignal?.aborted)
+                    cascadeAbort();
+                else
+                    lifecycleSignal?.addEventListener("abort", cascadeAbort, { once: true });
+                this.state = agentDirection ? "redriving" : "starting";
+                let result;
+                try {
+                    result = await this.runtime.run(nextTask, {
+                        ...options,
+                        signal: controller.signal,
+                        runtimeGeneration: this.runtimeGeneration,
+                        ...(agentDirection ? { injected: true, agentDirection } : {}),
+                    });
+                }
+                finally {
+                    lifecycleSignal?.removeEventListener("abort", cascadeAbort);
+                    this.activeController = undefined;
+                }
+                if (lifecycleSignal?.aborted) {
+                    this.closeDirectionIntake();
+                    return result;
+                }
+                // Engine.run has fully settled here, including all accepted tool results.
+                // For a normal completion, atomically close registry intake first. A
+                // sender that won before this boundary is now in the fenced queue and
+                // must be consumed/redriven; a sender after it is rejected.
+                if (!this.interruptPending)
+                    this.closeDirectionIntake();
+                const directions = this.drainDirections();
+                this.interruptPending = false;
+                if (directions.length === 0) {
+                    return result;
+                }
+                directions.sort((left, right) => left.sequence - right.sequence);
+                nextTask = buildAgentDirectionMessage(directions);
+                agentDirection = {
+                    envelopeIds: directions.map((item) => item.id),
+                    correlationIds: directions
+                        .map((item) => item.correlationId)
+                        .filter((value) => value !== undefined),
+                };
+            }
+        }
+        finally {
+            this.closeDirectionIntake();
+            this.running = false;
+            this.state = "terminal";
+            for (const { receipt, resolve } of this.pendingDelivered.values()) {
+                resolve({ status: "queued", ...receipt });
+            }
+            this.pendingDelivered.clear();
+            this.runtime.setAgentControlStateListener(undefined);
+            this.runtime.setAgentDirectionsDeliveredListener?.(undefined);
+        }
+    }
+}
+export function createSubAgentSpawner(deps) {
+    return {
+        parentStream: deps.parentStream,
+        describe: () => ({
+            cwd: deps.cwd,
+            preset: deps.presetName,
+            permissionMode: deps.permissionMode,
+        }),
+        sessionExists: deps.sessionExists,
+        getSessionParentId: deps.getSessionParentId,
+        spawn: async (request) => {
+            if (!request.resumeSessionId) {
+                try {
+                    deps.appendParentSubagent(request.agentId, request.description);
+                }
+                catch {
+                    // Parent anchors are best-effort and must never block a child run.
+                }
+            }
+            const scope = resolveChildToolScope(request.toolAllowlist, deps.parentConfig.disabledBuiltinTools, deps.parentConfig.enabledBuiltinTools);
+            const childConfig = {
+                llm: resolveChildLlm(request.model, deps.modelPool, deps.parentConfig.llm),
+                clientDefaults: {
+                    ...(deps.parentConfig.clientDefaults ?? {}),
+                    retryMaxAttempts: 2,
+                },
+                cwd: deps.cwd,
+                permissionMode: deps.permissionMode,
+                preset: deps.presetName,
+                enabledBuiltinTools: scope.enabled,
+                disabledBuiltinTools: scope.disabled,
+                capabilities: deps.parentConfig.capabilities,
+                extensionModules: deps.parentConfig.extensionModules,
+                builtinToolHost: deps.parentConfig.builtinToolHost,
+                customSystemPrompt: deps.parentConfig.customSystemPrompt,
+                appendSystemPrompt: [deps.parentConfig.appendSystemPrompt, request.appendSystemPrompt]
+                    .filter(Boolean)
+                    .join("\n\n") || undefined,
+                responseLanguage: deps.parentConfig.responseLanguage,
+                userProfile: deps.parentConfig.userProfile,
+                instructions: deps.parentConfig.instructions,
+                maxTurns: request.maxTurns,
+                maxContextTokens: deps.parentConfig.maxContextTokens ?? 200_000,
+                sessionStorageDir: deps.parentConfig.sessionStorageDir,
+                headless: deps.parentConfig.headless,
+                readOnlySession: request.readOnlySession,
+                skillAllowlist: request.skillAllowlist,
+                sandbox: resolveChildSandbox(request.sandboxMode, deps.parentSandbox),
+                mcpServers: resolveChildMcpServers(request.mcpAllowlist, deps.parentConfig.mcpServers),
+                settingsScope: deps.parentConfig.settingsScope ?? "project",
+                isSubAgent: true,
+            };
+            const destination = request.streamOverride ?? deps.parentStream;
+            const childSessionId = request.resumeSessionId ?? request.agentId;
+            if (deps.childRunner.createChild && request.runtimeGeneration !== undefined) {
+                const runtime = deps.childRunner.createChild(childConfig);
+                const supervisor = new ChildRunSupervisor(runtime, childSessionId, request.runtimeGeneration);
+                const ownerToken = nanoid();
+                const bound = request.bindLiveControl?.(supervisor, ownerToken);
+                supervisor.setCloseIntake(() => request.closeLiveControl?.(supervisor, bound && bound !== true ? bound : undefined));
+                if (bound === false) {
+                    throw new Error(`child session ${childSessionId} already has a live transcript writer`);
+                }
+                return await supervisor.run(request.prompt, {
+                    signal: request.signal,
+                    onStream: wrapChildRuntimeStream(destination, request.agentId, request.onProgressEvent),
+                    sessionId: childSessionId,
+                    onAgentProgress: request.onAgentProgress,
+                });
+            }
+            const result = await deps.childRunner.runChild(childConfig, request.prompt, {
+                signal: request.signal,
+                onStream: wrapChildRuntimeStream(destination, request.agentId, request.onProgressEvent),
+                sessionId: childSessionId,
+            });
+            return result;
+        },
+    };
+}

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

@@ -5,9 +5,9 @@
  * 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>;
+export type SummarizeFn = (systemPrompt: string, userMessage: string, signal?: AbortSignal) => 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>;
+export declare function generateToolUseSummary(toolCalls: ToolCall[], results: ToolResult[], summarize: SummarizeFn, signal?: AbortSignal): Promise<string | null>;

package/dist/engine/tool-summary.js

@@ -13,7 +13,7 @@ const SUMMARY_SYSTEM_PROMPT = "Generate a very brief (under 40 chars) summary of
  * Generate a 1-line summary of completed tool executions.
  * Returns null on failure (non-critical).
  */
-export async function generateToolUseSummary(toolCalls, results, summarize) {
+export async function generateToolUseSummary(toolCalls, results, summarize, signal) {
     if (toolCalls.length === 0)
         return null;
     try {
@@ -25,7 +25,7 @@ export async function generateToolUseSummary(toolCalls, results, summarize) {
             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"));
+        const summary = await summarize(SUMMARY_SYSTEM_PROMPT, parts.join("\n"), signal);
         return summary?.trim() || null;
     }
     catch (err) {

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

@@ -4,16 +4,19 @@
  * 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, ContentBlock, ToolResult, TokenUsage, ContextUsageAnchor } from "../types.js";
+import type { Message, StreamCallback, TerminalReason, ContentBlock, ToolResult, TokenUsage, ContextUsageAnchor, TurnCompletionKind } from "../types.js";
 import type { SteerItem } from "./steer-queue.js";
+import type { DirectionEnvelope } from "../tool-system/builtin/agent-notifications.js";
+import type { LiveChildState } from "../tool-system/builtin/agent-registry.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 { type GoalJudgeRuntimeContext } from "../hooks/goal-stop-hook.js";
+import type { GoalJudgeRuntimeContext } from "../hooks/goal-stop-hook.js";
+import type { PromptCacheDiagnosticSample } from "./prompt-cache-diagnostics.js";
 import { Transcript } from "../session/transcript.js";
-import { type CumulativeUsageCounters } from "./session-usage.js";
-import { type GoalConfig, type GoalExtension, type GoalTerminationReason } from "./goal.js";
+import { type CumulativeUsageCounters } from "../session/usage.js";
+import { type GoalConfig, type GoalExtension, type GoalTerminationReason } from "../goal/lifecycle.js";
 export interface TurnLoopConfig {
     maxTurns: number;
     maxToolCallsPerTurn: number;
@@ -94,11 +97,13 @@ export interface TurnLoopDeps {
      * Returns the updated counters so usage_update can carry both metric scopes.
      */
     recordCumulativeUsage?: (usage: TokenUsage) => CumulativeUsageCounters;
+    /** Child-only billed usage delta for structured progress accounting. */
+    onAgentUsage?: (usage: TokenUsage) => void;
     /**
      * Lightweight per-session prompt-cache diagnostic, owned by Engine because it
      * needs memory across TurnLoop instances.
      */
-    recordCacheReadDiagnostics?: (usage: TokenUsage) => void;
+    recordCacheReadDiagnostics?: (sample: PromptCacheDiagnosticSample) => void;
     /** Persist the latest context-estimation anchor derived from provider usage. */
     recordContextUsageAnchor?: (anchor: ContextUsageAnchor) => void;
     /**
@@ -110,6 +115,12 @@ export interface TurnLoopDeps {
      * tests (turn loop tolerates undefined).
      */
     consumeSteer?: (source?: "normal_step" | "finalize_backfill") => SteerItem[];
+    /** Child-only mailbox drain; separate from user steering for provenance/consent. */
+    consumeAgentDirections?: () => DirectionEnvelope[];
+    /** Exposes semantic model/tool boundaries to the bound live child supervisor. */
+    onAgentControlState?: (state: LiveChildState) => void;
+    /** Confirms that specific envelopes reached messages + persisted provenance. */
+    onAgentDirectionsDelivered?: (envelopeIds: string[]) => void;
     /** Restore steer items whose model-facing content could not be prepared. */
     restoreSteer?: (items: SteerItem[]) => void;
     /** Build model-facing content for a queued steer item, including attachments. */
@@ -125,19 +136,24 @@ export interface TurnLoopDeps {
     /** Make tools launched after an injected steer attribute side effects to that steer. */
     setOriginClientMessageId?: (clientMessageId: string | undefined) => void;
     /**
-     * Clear this session's PERSISTED goal (state.activeGoal) and drop the
-     * in-flight goal-stop hook, so a user-initiated cancel_goal both stops the
-     * current run AND prevents the goal from re-inheriting on the next bare send.
+     * Terminally clear this session's persisted goalLifecycle and drop
+     * the in-flight goal-stop hook, so complete_goal/cancel_goal both stop the
+     * current run AND prevent the goal from re-inheriting on the next bare send.
      * Wired by Engine (delegates to Engine.clearGoal for the running session);
      * absent in standalone tests (turn loop tolerates undefined — the local
      * goalTracker short-circuit still stops the run).
      */
-    clearPersistedGoal?: () => void;
+    /** Return false when the durable transition failed; the loop must keep driving. */
+    clearPersistedGoal?: (reason: "completed" | "cancelled") => boolean | void;
     /**
      * Private Goal-judge evidence seam. Engine stores this snapshot in the
      * built-in judge closure; it is never added to the public on_stop context.
      */
-    updateGoalJudgeContext?: (context: GoalJudgeRuntimeContext) => void;
+    publishGoalJudgeContext?: (context: GoalJudgeRuntimeContext) => void;
+    /** Inspect a trusted tool's pending run yield without clearing it. */
+    peekToolRunYield?: () => import("../tool-system/context.js").ToolRunYieldReason | undefined;
+    /** Consume a trusted tool's request to yield until an async notification. */
+    consumeToolRunYield?: () => import("../tool-system/context.js").ToolRunYieldReason | undefined;
 }
 export interface TurnLoopResult {
     text: string;
@@ -145,6 +161,10 @@ export interface TurnLoopResult {
     messages: Message[];
     /** Goal-specific forced terminal outcome; public TerminalReason stays stable. */
     goalTermination?: GoalTerminationReason;
+    /** Stop-block round captured before the loop resets its per-approach counter. */
+    goalTerminationRound?: number;
+    /** Exceptional completed-run boundary; absent means an ordinary final answer. */
+    completionKind?: TurnCompletionKind;
 }
 /**
  * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
@@ -172,6 +192,10 @@ export declare class TurnLoop {
     private readonly sensitiveToolResultRedactions;
     private readonly pendingImageMessages;
     private readonly volatileContextMessages;
+    /** Last outer-loop turn for which the model returned a complete response. */
+    private lastCompletedModelTurn;
+    /** Last model turn whose transcript/persistence boundary was finalized. */
+    private lastFinalizedTurn;
     /**
      * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
      * on any unblocked completion. When it reaches config.maxStopBlocks the
@@ -191,6 +215,24 @@ export declare class TurnLoop {
      * being re-emitted every turn while still within the approach threshold.
      */
     private approachAnnounced;
+    /** Latest coalesced Goal edit/resume reminder, consumed at a safe point. */
+    private pendingGoalControlMessage;
+    /** Pause/delete requested while a Goal run is in flight. The current
+     * model/tool step is allowed to settle, then the loop stops before starting
+     * another model request. */
+    private goalControlStopRequested;
+    /** Auxiliary tool-summary calls started by this loop and revoked by Goal pause/delete. */
+    private readonly activeToolSummaryControllers;
+    /**
+     * Apply a user goal edit/pause/resume to the live loop. Passing undefined
+     * pauses goal-driving at the next step boundary; a goal value resumes it.
+     * Usage accumulated before an edit is retained, while a pause/resume starts
+     * a fresh run-scoped budget window (matching a later persisted resume).
+     */
+    updateGoal(goal: GoalConfig | undefined, controlMessage?: string, limits?: {
+        maxTurns?: number;
+        maxStopBlocks?: number;
+    }): void;
     /**
      * Extend the in-flight run's limits (TODO 3.1 — 运行中续轮/加预算). Mutates
      * the maxTurns ceiling, the maxStopBlocks cap, and/or the live goal budgets;
@@ -204,6 +246,13 @@ export declare class TurnLoop {
         timeBudgetMs?: number;
         maxStopBlocks: number;
     };
+    /**
+     * Private Goal-judge accounting seam. Judge calls bypass ModelFacade, so the
+     * Engine forwards their provider usage here while the run-scoped tracker is
+     * live. The returned reason lets the hook suppress verdict side effects when
+     * this very request crossed a hard token/time budget.
+     */
+    recordGoalJudgeUsage(usage: TokenUsage | undefined): Extract<GoalTerminationReason, "token_budget_exhausted" | "time_budget_exhausted"> | undefined;
     /**
      * Goal mode only: if the run is nearing EITHER stop ceiling (maxTurns or
      * maxStopBlocks) and we haven't announced it yet, emit one approaching_limit
@@ -229,6 +278,13 @@ export declare class TurnLoop {
      * for one Stop still writes a single marker.
      */
     private markStopped;
+    /**
+     * Close one completed model turn exactly once. The transcript boundary must
+     * be durable before the Engine flushes usage, heartbeat, and turnCount via
+     * onTurnBoundary, so crash recovery never folds two assistant responses into
+     * the same transcript turn or observes state ahead of the transcript.
+     */
+    private finalizeModelTurn;
     private prepareMessagesForModel;
     private stripVolatileContextMessages;
     private appendVolatileContextMessages;
@@ -259,6 +315,7 @@ export declare class TurnLoop {
     private callModelWithFallback;
     get currentTurn(): number;
     private consumeQueuedSteer;
+    private consumeQueuedAgentDirections;
     /**
      * Generate synthetic error tool_results for any dangling tool_use blocks
      * that never received results (e.g. because the API call failed).