@cjhyy/code-shell-core 0.7.1 → 0.8.1

package/dist/engine/run-finalize.d.ts

@@ -0,0 +1,58 @@
+import { type SessionBundle, type SessionStateFieldPatch } from "../session/session-manager.js";
+import { type CumulativeUsageCounters } from "../session/usage.js";
+import type { GoalTerminationReason } from "../goal/lifecycle.js";
+import type { Message, TokenUsage } from "../types.js";
+import type { LLMUsageTracker } from "../llm/types.js";
+import type { LLMClientBase } from "../llm/client-base.js";
+import type { HookEventName, HookResult } from "../hooks/events.js";
+import type { TurnLoop } from "./turn-loop.js";
+import type { EngineResult } from "./types.js";
+import type { EngineRunOptions, RunBehaviorProfile } from "./run-types.js";
+type TurnLoopRunResult = Awaited<ReturnType<TurnLoop["run"]>>;
+/** engine.ts:headless 一次性 run 的后台子代理排水循环。 */
+export declare function drainHeadlessBackgroundAgents(args: {
+    sid: string;
+    session: SessionBundle;
+    signal: AbortSignal | undefined;
+    initialResult: TurnLoopRunResult;
+    runTurnLoop: (messages: Message[]) => Promise<TurnLoopRunResult>;
+    applyGoalTermination: (termination: GoalTerminationReason | undefined, round: number | undefined) => void;
+    waitForBackgroundAgentChange: (sid: string, signal?: AbortSignal) => Promise<boolean>;
+    waitForBackgroundAgentChangeOrTimeout: (sid: string, ms: number) => Promise<boolean>;
+    getFirstGoalTermination: () => GoalTerminationReason | undefined;
+    setFirstGoalTermination: (t: GoalTerminationReason | undefined) => void;
+}): Promise<TurnLoopRunResult>;
+/** engine.ts:成功路径收尾(缓存/日志/钩子/记忆/标题/终态/结果)。 */
+export declare function finalizeRunSuccess(args: {
+    session: SessionBundle;
+    result: TurnLoopRunResult;
+    firstGoalTermination: GoalTerminationReason | undefined;
+    turnCount: number;
+    getRunUsage: () => LLMUsageTracker;
+    usageBaseline: TokenUsage;
+    userContextMsg: Message | null;
+    dynamicContextMsg: Message | null;
+    setCompactedMessages: (sid: string, messages: Message[]) => void;
+    setLastMessages: (messages: Message[]) => void;
+    options: EngineRunOptions | undefined;
+    emitHook: (event: HookEventName, payload: Record<string, unknown>, signal?: AbortSignal) => Promise<HookResult>;
+    cwd: string;
+    llmClient: LLMClientBase;
+    auxSummaryClient: LLMClientBase;
+    recordExternalBilledUsage: (usage: TokenUsage) => CumulativeUsageCounters;
+    runMemoryPipeline: (transcript: SessionBundle["transcript"], sessionId: string, cwd: string, llmClient: LLMClientBase, recordExternalBilledUsage: (usage: TokenUsage) => CumulativeUsageCounters) => Promise<void> | void;
+    updatePersistedSessionState: (sid: string, patch: SessionStateFieldPatch) => void;
+    persistFinalRunState: (state: SessionBundle["state"]) => void;
+    markRunAccountingFinalized: () => void;
+    costStoreSerialize: (() => Record<string, unknown>) | undefined;
+    profile: RunBehaviorProfile | undefined;
+    getProfileReportedResults: () => Record<string, unknown> | undefined;
+}): Promise<EngineResult>;
+/** engine.ts catch 体:初始化失败 → model_error 终态 + 错误结果。 */
+export declare function buildRunFailureResult(args: {
+    err: unknown;
+    session: SessionBundle;
+    options: EngineRunOptions | undefined;
+    persistFinalRunState: (state: SessionBundle["state"]) => void;
+}): EngineResult;
+export {};

package/dist/engine/run-finalize.js

@@ -0,0 +1,245 @@
+/**
+ * Run finalize — the headless background-agent drain loop, the success-path
+ * epilogue (persistence, hooks, memory pipeline trigger, session title,
+ * result assembly) and the initialization-failure terminal result.
+ */
+import { asyncAgentRegistry } from "../tool-system/builtin/agent-registry.js";
+import { buildNotificationMessage, notificationQueue, } from "../tool-system/builtin/agent-notifications.js";
+import { logger } from "../logging/logger.js";
+import { recordSessionEnd } from "../logging/session-recorder.js";
+import { isEphemeralSessionState, } from "../session/session-manager.js";
+import { foldRunUsage } from "../session/usage.js";
+import { buildSessionTitle } from "./session-title.js";
+import { formatFriendlyError } from "./friendly-error.js";
+import { stripInjectedContextMessages } from "./injected-context-cache.js";
+/** engine.ts:headless 一次性 run 的后台子代理排水循环。 */
+export async function drainHeadlessBackgroundAgents(args) {
+    const { sid, session } = args;
+    let result = args.initialResult;
+    let aborted = args.signal?.aborted === true;
+    // Loop: a summarize turn can spawn a NEW background sub-agent; keep
+    // draining + summarizing until none remain. turnCount accumulates, so
+    // the turn-loop's maxTurns still bounds runaway re-summarization.
+    for (;;) {
+        while (!aborted && asyncAgentRegistry.hasRunningForSession(sid)) {
+            aborted = await args.waitForBackgroundAgentChange(sid, args.signal);
+        }
+        let pending = notificationQueue.drainAll(sid);
+        if (aborted && pending.length === 0) {
+            // Abort race: an agent calls markCompleted (registry notify) and only
+            // THEN enqueue (queue notify) as two separate statements. If the abort
+            // fired before that agent's completion `.then` ran, the while above
+            // exited on `aborted`, this drainAll caught nothing, and a naive
+            // `break` here would drop the agent's output. Give still-settling
+            // agents a bounded window to finish enqueuing, then drain once more.
+            // Each wait is timeout-bounded so a genuinely stuck (never-completing)
+            // agent can't hang abort cleanup forever — we'd rather lose nothing in
+            // the common case and not hang in the pathological one.
+            for (let i = 0; i < 20 && asyncAgentRegistry.hasRunningForSession(sid); i++) {
+                const changed = await args.waitForBackgroundAgentChangeOrTimeout(sid, 25);
+                if (!changed)
+                    break; // timed out with no state change → stop waiting
+            }
+            pending = notificationQueue.drainAll(sid);
+            if (pending.length === 0)
+                break;
+        }
+        else if (pending.length === 0) {
+            break;
+        }
+        const injected = {
+            role: "user",
+            content: `<system-reminder>\n${buildNotificationMessage(pending)}\n</system-reminder>`,
+        };
+        if (aborted || args.getFirstGoalTermination()) {
+            // Mark injected: a synthetic notification, not the user's own input —
+            // the disk reader drops it on replay so no phantom user bubble.
+            // A goal termination is also a hard boundary: retain the notification
+            // for recovery, but never re-enter TurnLoop (which would reset its
+            // run-scoped goal budget tracker and could overwrite the first reason).
+            session.transcript.appendMessage(injected.role, injected.content, { injected: true });
+            result = { ...result, messages: [...result.messages, injected] };
+            break;
+        }
+        result = await args.runTurnLoop([...result.messages, injected]);
+        args.setFirstGoalTermination(args.getFirstGoalTermination() ?? result.goalTermination);
+        args.applyGoalTermination(result.goalTermination, result.goalTerminationRound);
+    }
+    return result;
+}
+/** engine.ts:成功路径收尾(缓存/日志/钩子/记忆/标题/终态/结果)。 */
+export async function finalizeRunSuccess(args) {
+    const { session, result, firstGoalTermination, turnCount, getRunUsage, usageBaseline, userContextMsg, dynamicContextMsg, options, cwd, llmClient, auxSummaryClient, recordExternalBilledUsage, profile, } = args;
+    args.setLastMessages(result.messages);
+    const cachedMessages = stripInjectedContextMessages(result.messages, userContextMsg, dynamicContextMsg);
+    args.setCompactedMessages(session.state.sessionId, cachedMessages);
+    logger.info("engine.done", {
+        sessionId: session.state.sessionId,
+        reason: result.reason,
+        turns: turnCount,
+        tokens: getRunUsage().totalTokens,
+    });
+    recordSessionEnd(session.state.sessionId, {
+        reason: result.reason,
+        turns: turnCount,
+        cost: getRunUsage(),
+    });
+    // Session-level hook: fired symmetrically with on_session_start once
+    // the turn loop has resolved (completion, error, or abort). Handlers
+    // are notify-only — any returned messages are dropped because the run
+    // is already over and there's no next turn to inject into.
+    await args.emitHook("on_session_end", {
+        sessionId: session.state.sessionId,
+        reason: result.reason,
+        turnCount,
+    }, options?.signal);
+    // Ephemeral side chats must never leak into durable memory, even after
+    // the user explicitly elevates tool permissions for a turn. Lifecycle
+    // isolation is independent of the run-scoped behavior/permission mode.
+    if (!isEphemeralSessionState(session.state)) {
+        // Fire-and-forget memory pipeline: extract durable memories from the
+        // transcript, save a session summary, and conditionally trigger
+        // auto-dream consolidation. Doesn't block the Engine result.
+        void args.runMemoryPipeline(session.transcript, session.state.sessionId, cwd, llmClient, recordExternalBilledUsage);
+    }
+    // Fire-and-forget session title generation — only after the FIRST turn.
+    // Reuses the already-resolved auxSummaryClient (aux model, cheap). Best-
+    // effort: failures never touch the run result. The renderer writes the
+    // title into the sidebar on receipt of the session_title stream event.
+    {
+        const messageEvents = session.transcript.getEvents("message");
+        const userMsgEvents = messageEvents.filter((e) => e.data.role === "user");
+        const userMsgCount = userMsgEvents.length;
+        const onStream = options?.onStream;
+        if (userMsgCount === 1 && onStream && result.text) {
+            const sessionId = session.state.sessionId;
+            const rawContent = userMsgEvents[0]?.data?.content;
+            const firstUserText = typeof rawContent === "string" ? rawContent : JSON.stringify(rawContent ?? "");
+            void buildSessionTitle(auxSummaryClient, firstUserText, result.text, recordExternalBilledUsage)
+                .then((title) => {
+                if (title) {
+                    // Persist the title so it survives a localStorage wipe / disk
+                    // rebuild — it used to live only in the renderer's localStorage
+                    // index. Read the latest persisted state at callback time and
+                    // merge only title; the completed run's session.state snapshot
+                    // may already be stale after later serial session updates.
+                    args.updatePersistedSessionState(sessionId, { title });
+                    onStream({
+                        type: "session_title",
+                        sessionId,
+                        title,
+                    });
+                }
+            })
+                .catch(() => { });
+        }
+    }
+    // Update session state. Persist the raw terminal reason as the status so
+    // callers can distinguish user-cancelled (aborted_streaming) from real
+    // failures (model_error, prompt_too_long, ...) — previously every
+    // non-completed outcome collapsed to "errored", which threw away the
+    // distinction and misled anyone reading state.json.
+    const transcriptFlushFailed = session.transcript.flushFailed();
+    if (transcriptFlushFailed) {
+        const failure = session.transcript.getFlushFailure();
+        logger.error("engine.transcript_persistence_failed", {
+            sessionId: session.state.sessionId,
+            terminalReason: result.reason,
+            degraded: true,
+            ...failure,
+        });
+    }
+    options?.onAgentProgress?.({ type: "phase", phase: "finalizing" });
+    session.state.turnCount = turnCount;
+    session.state.status = result.reason;
+    if (result.reason === "completed" && result.completionKind) {
+        session.state.lastCompletionKind = result.completionKind;
+    }
+    else {
+        delete session.state.lastCompletionKind;
+    }
+    if (result.reason === "completed") {
+        session.state.completedSnapshotVersion = 1;
+        if (!transcriptFlushFailed) {
+            session.state.completedThroughEventId = session.transcript.getEvents().at(-1)?.id;
+        }
+    }
+    // Session-cumulative (baseline + this run) for persistence...
+    const usage = getRunUsage();
+    session.state.tokenUsage = foldRunUsage(usageBaseline, usage);
+    if (args.costStoreSerialize) {
+        session.state.costState = args.costStoreSerialize();
+    }
+    args.persistFinalRunState(session.state);
+    args.markRunAccountingFinalized();
+    // Hook: agent end
+    await args.emitHook("on_agent_end", {
+        sessionId: session.state.sessionId,
+        reason: result.reason,
+        turnCount,
+    }, options?.signal);
+    // Emit completion
+    options?.onStream?.({
+        type: "turn_complete",
+        reason: result.reason,
+        ...(result.completionKind ? { completionKind: result.completionKind } : {}),
+    });
+    // Structured results the active profile's run services reported, keyed
+    // by profile id. petWorkDelegation stays as a compat mirror of
+    // extensions.pet?.workDelegation until pet-aware hosts migrate.
+    const profileReportedResults = args.getProfileReportedResults();
+    const runExtensions = profile && profileReportedResults ? { [profile.id]: profileReportedResults } : undefined;
+    const petWorkDelegationMirror = runExtensions?.pet?.workDelegation;
+    return {
+        text: result.text,
+        reason: result.reason,
+        goalTermination: firstGoalTermination,
+        sessionId: session.state.sessionId,
+        turnCount,
+        usage: {
+            promptTokens: usage.totalPromptTokens,
+            completionTokens: usage.totalCompletionTokens,
+            totalTokens: usage.totalTokens,
+            cacheReadTokens: usage.totalCacheReadTokens,
+            cacheCreationTokens: usage.totalCacheCreationTokens,
+        },
+        ...(runExtensions ? { extensions: runExtensions } : {}),
+        ...(petWorkDelegationMirror ? { petWorkDelegation: petWorkDelegationMirror } : {}),
+    };
+}
+/** engine.ts catch 体:初始化失败 → model_error 终态 + 错误结果。 */
+export function buildRunFailureResult(args) {
+    const { err, session, options } = args;
+    // The session is already persisted as active before runWithSid starts.
+    // Initialization failures (client creation, MCP connection, prompt/hooks)
+    // therefore need the same terminal lifecycle treatment as turn-loop errors.
+    const error = formatFriendlyError(err);
+    session.state.status = "model_error";
+    delete session.state.lastCompletionKind;
+    args.persistFinalRunState(session.state);
+    session.transcript.appendError(error, { phase: "initialization" });
+    logger.error("engine.run_lifecycle_failed", {
+        sessionId: session.state.sessionId,
+        error: err instanceof Error ? err.message : String(err),
+    });
+    recordSessionEnd(session.state.sessionId, {
+        reason: "model_error",
+        turns: session.state.turnCount,
+    });
+    options?.onStream?.({ type: "error", error });
+    options?.onStream?.({ type: "turn_complete", reason: "model_error" });
+    const usage = session.state.tokenUsage;
+    return {
+        text: `ERROR: ${error}`,
+        reason: "model_error",
+        sessionId: session.state.sessionId,
+        turnCount: session.state.turnCount,
+        usage: {
+            promptTokens: usage.promptTokens ?? 0,
+            completionTokens: usage.completionTokens ?? 0,
+            totalTokens: usage.totalTokens ?? 0,
+            cacheReadTokens: usage.cacheReadTokens ?? 0,
+            cacheCreationTokens: usage.cacheCreationTokens ?? 0,
+        },
+    };
+}

package/dist/engine/run-goal.d.ts

@@ -0,0 +1,58 @@
+import type { StreamCallback, TokenUsage } from "../types.js";
+import { type GoalConfig, type GoalTerminationReason, type PersistedGoalTerminationReason } from "../goal/lifecycle.js";
+import { createGoalStopHook, type GoalJudgeRuntimeContext } from "../hooks/goal-stop-hook.js";
+import type { HookRegistry } from "../hooks/registry.js";
+import type { LLMClientBase } from "../llm/client-base.js";
+import type { GoalTerminalSaveOutcome, SessionBundle, SessionManager } from "../session/session-manager.js";
+import type { TurnLoop } from "./turn-loop.js";
+import type { EngineConfig } from "./types.js";
+import type { EngineRunOptions } from "./run-types.js";
+export type GoalStopHookHandler = ReturnType<typeof createGoalStopHook>;
+export interface GoalRunSlots {
+    getActiveRuntimeGoal(): GoalConfig | null;
+    setActiveRuntimeGoal(goal: GoalConfig | null): void;
+    getActivePersistedRunGoal(): GoalConfig | null;
+    setActivePersistedRunGoal(goal: GoalConfig | null): void;
+    getActiveGoalHook(): GoalStopHookHandler | null;
+    setActiveGoalHook(hook: GoalStopHookHandler | null): void;
+    setActiveGoalHookAttached(attached: boolean): void;
+}
+/** engine.ts:explicit/stored/fallback 归一化 + 持久化 + goal_set 事件。 */
+export declare function resolveRunGoal(args: {
+    options: EngineRunOptions | undefined;
+    session: SessionBundle;
+    sessionManager: Pick<SessionManager, "saveActiveGoal">;
+    configGoal: EngineConfig["goal"];
+    isSubAgent: boolean;
+    sid: string;
+    onStream: StreamCallback | undefined;
+}): {
+    normalizedGoal: GoalConfig | undefined;
+    persistedRunGoal: GoalConfig | undefined;
+};
+/** engine.ts:GoalStopHook 创建 + 注册 + 槽位登记。 */
+export declare function armRunGoalHook(args: {
+    slots: GoalRunSlots;
+    hooks: HookRegistry;
+    llmClient: LLMClientBase;
+    isSubAgent: boolean;
+    normalizedGoal: GoalConfig | undefined;
+    persistedRunGoal: GoalConfig | undefined;
+    session: SessionBundle;
+    sessionManager: Pick<SessionManager, "markGoalWaiting" | "readActiveGoal">;
+    persistGoalTerminal: (state: SessionBundle["state"], goal: GoalConfig, reason: PersistedGoalTerminationReason) => boolean;
+    getJudgeContext: () => GoalJudgeRuntimeContext | undefined;
+    recordCumulativeUsage: (usage: TokenUsage) => unknown;
+    recordGoalJudgeUsage: (usage: TokenUsage | undefined) => ReturnType<TurnLoop["recordGoalJudgeUsage"]>;
+}): GoalStopHookHandler | null;
+/** engine.ts:goal 终态落盘 + 事件 + 钩子摘除(闭包工厂)。 */
+export declare function createGoalTerminationApplier(args: {
+    slots: GoalRunSlots;
+    hooks: HookRegistry;
+    session: SessionBundle;
+    persistedRunGoal: GoalConfig | undefined;
+    goalHookHandler: GoalStopHookHandler | null;
+    persistGoalTerminalOutcome: (state: SessionBundle["state"], goal: GoalConfig, termination: PersistedGoalTerminationReason) => GoalTerminalSaveOutcome;
+    readActiveGoal: (sid: string) => GoalConfig | undefined | null;
+    onStream: StreamCallback | undefined;
+}): (termination: GoalTerminationReason | undefined, round: number | undefined) => void;

package/dist/engine/run-goal.js

@@ -0,0 +1,188 @@
+/**
+ * Run goal — persistent-goal resolution (explicit > stored > config default),
+ * arming the GoalStopHook for the run, and the terminal-outcome applier.
+ * Engine keeps ownership of its active-goal slots via GoalRunSlots.
+ */
+import { randomUUID } from "node:crypto";
+import { normalizeGoal, resolveGoalSetAt, goalConfigFromLifecycle, isGoalLifecycleCurrent, isSameGoalVersion, } from "../goal/lifecycle.js";
+import { createGoalStopHook } from "../hooks/goal-stop-hook.js";
+import { logger } from "../logging/logger.js";
+/** engine.ts:explicit/stored/fallback 归一化 + 持久化 + goal_set 事件。 */
+export function resolveRunGoal(args) {
+    const { options, session, sessionManager, configGoal, isSubAgent, sid, onStream } = args;
+    const explicitGoal = normalizeGoal(options?.goal);
+    const storedLifecycle = session.state.goalLifecycle;
+    const storedGoal = isSubAgent !== true && storedLifecycle && isGoalLifecycleCurrent(storedLifecycle)
+        ? goalConfigFromLifecycle(storedLifecycle)
+        : undefined;
+    if (storedGoal &&
+        !explicitGoal &&
+        session.state.goalLifecycle?.phase === "waiting" &&
+        !sessionManager.saveActiveGoal(session.state, storedGoal)) {
+        throw new Error(`Failed to arm waiting goal for session ${sid}`);
+    }
+    if (explicitGoal && isSubAgent !== true) {
+        // Supplying a goal on a run is an explicit arm/resume operation.
+        delete explicitGoal.paused;
+        const replaced = !!storedGoal && storedGoal.objective !== explicitGoal.objective;
+        // Stamp WHEN this goal was set so the judge can anchor relative deadlines
+        // ("做到3点") to the set time, not "now" — else once the clock passes the
+        // deadline the judge could read "3点" as tomorrow's and never stop. A new
+        // or changed objective gets a fresh stamp; re-sending the SAME objective
+        // keeps the original anchor (the goal continues, the user didn't restate a
+        // new deadline). User input never carries setAtMs, so we set it here.
+        const resolvedSetAt = resolveGoalSetAt(explicitGoal.objective, storedGoal, Date.now());
+        explicitGoal.setAtMs = resolvedSetAt;
+        explicitGoal.goalId = randomUUID();
+        explicitGoal.revision = 1;
+        if (!sessionManager.saveActiveGoal(session.state, explicitGoal, {
+            replaceCurrent: storedGoal !== undefined,
+        })) {
+            throw new Error(`Failed to persist active goal for session ${sid}`);
+        }
+        onStream?.({
+            type: "goal_set",
+            goalId: explicitGoal.goalId,
+            revision: explicitGoal.revision,
+            objective: explicitGoal.objective,
+            replaced,
+        });
+    }
+    const fallbackGoal = normalizeGoal(configGoal);
+    if (fallbackGoal && !fallbackGoal.goalId)
+        fallbackGoal.goalId = randomUUID();
+    if (fallbackGoal && !fallbackGoal.revision)
+        fallbackGoal.revision = 1;
+    const normalizedGoal = explicitGoal ??
+        (storedGoal?.paused === true ? undefined : storedGoal) ??
+        (fallbackGoal?.paused === true ? undefined : fallbackGoal);
+    // Snapshot the persisted goal identity owned by THIS run. Terminal
+    // cleanup compares against this immutable copy so an old run cannot
+    // delete a replacement goal installed while it was finishing.
+    const persistedRunGoal = normalizedGoal &&
+        session.state.goalLifecycle &&
+        isGoalLifecycleCurrent(session.state.goalLifecycle) &&
+        isSameGoalVersion(goalConfigFromLifecycle(session.state.goalLifecycle), normalizedGoal)
+        ? { ...normalizedGoal }
+        : undefined;
+    return { normalizedGoal, persistedRunGoal };
+}
+/** engine.ts:GoalStopHook 创建 + 注册 + 槽位登记。 */
+export function armRunGoalHook(args) {
+    const { slots, hooks, llmClient, isSubAgent, normalizedGoal, persistedRunGoal, session, sessionManager, persistGoalTerminal, getJudgeContext, recordCumulativeUsage, recordGoalJudgeUsage, } = args;
+    let goalHookHandler = null;
+    if (isSubAgent !== true) {
+        // Keep a dormant hook even when this ordinary run inherited a paused
+        // persisted goal. A mid-run Resume can then arm Goal mode at the same
+        // safe step boundary as Steer instead of waiting for another submit.
+        slots.setActiveRuntimeGoal(normalizedGoal ?? null);
+        slots.setActivePersistedRunGoal(persistedRunGoal ?? null);
+        goalHookHandler = createGoalStopHook({
+            goal: normalizedGoal,
+            getGoal: () => slots.getActiveRuntimeGoal() ?? undefined,
+            llm: llmClient,
+            log: logger,
+            getJudgeContext: () => getJudgeContext(),
+            onJudgeUsage: (usage) => {
+                // The provider records this request into llmClient.getUsage() and the
+                // process-wide CostTracker. This separate callback feeds the session
+                // cumulative cache counters and the live Goal hard-budget tracker.
+                if (usage)
+                    recordCumulativeUsage(usage);
+                // Charge the request even if an edit landed while the judge was
+                // awaiting its response. Revision fencing suppresses the old
+                // verdict, not the provider cost; otherwise repeated edits can
+                // bypass the Goal hard budget.
+                return recordGoalJudgeUsage(usage);
+            },
+            // Clear the persisted active goal the moment the judge says it's met,
+            // so a later bare send doesn't re-inherit a satisfied goal. The hook
+            // calls this from inside its met branch (single source of truth for
+            // "goal achieved"); engine owns the persistence side-effect.
+            onMet: () => {
+                const runGoal = slots.getActivePersistedRunGoal() ?? persistedRunGoal;
+                return runGoal ? persistGoalTerminal(session.state, runGoal, "completed") : true;
+            },
+            onWaiting: () => {
+                const runGoal = slots.getActivePersistedRunGoal() ?? persistedRunGoal;
+                return runGoal ? sessionManager.markGoalWaiting(session.state, runGoal) : true;
+            },
+            // Re-read the persisted goal each turn so a mid-run 清除 (clearGoal
+            // wrote state.json but this hook's frozen goal copy + the closure's
+            // in-RAM session are untouched) actually stops the judge. Reads disk
+            // via readActiveGoal — authoritative and independent of which session
+            // instance the run closure holds.
+            isGoalActive: (sid) => {
+                const runtimeGoal = slots.getActiveRuntimeGoal();
+                if (!runtimeGoal)
+                    return false;
+                // A config-only Goal has no disk record to re-check.
+                if (!slots.getActivePersistedRunGoal())
+                    return true;
+                const liveGoal = sessionManager.readActiveGoal(sid);
+                return liveGoal?.paused !== true && isSameGoalVersion(liveGoal, runtimeGoal);
+            },
+        });
+        if (normalizedGoal) {
+            hooks.register("on_stop", goalHookHandler, 0, "goal-stop");
+            slots.setActiveGoalHookAttached(true);
+        }
+        else {
+            slots.setActiveGoalHookAttached(false);
+        }
+        // Expose for edit/pause/resume/delete mid-run. Already guarded by
+        // isSubAgent above.
+        slots.setActiveGoalHook(goalHookHandler);
+    }
+    return goalHookHandler;
+}
+/** engine.ts:goal 终态落盘 + 事件 + 钩子摘除(闭包工厂)。 */
+export function createGoalTerminationApplier(args) {
+    const { slots, hooks, session, persistedRunGoal, goalHookHandler, persistGoalTerminalOutcome, readActiveGoal, onStream, } = args;
+    return (termination, round) => {
+        const runGoal = slots.getActivePersistedRunGoal() ?? persistedRunGoal;
+        if (!termination || !runGoal)
+            return;
+        // Judge prompt overflow ends only this run. The objective is unfinished
+        // and may be resumed after the user reduces fixed judge context, so it
+        // must not get a terminal tombstone or be cleared from activeGoal.
+        if (termination === "judge_prompt_too_large")
+            return;
+        const outcome = persistGoalTerminalOutcome(session.state, runGoal, termination);
+        if (outcome === "failed") {
+            // No terminal event has been published. Re-assert the authoritative
+            // active Goal in case another optimistic control changed the client.
+            const authoritative = readActiveGoal(session.state.sessionId);
+            if (authoritative) {
+                onStream?.({
+                    type: "goal_updated",
+                    goalId: authoritative.goalId,
+                    revision: authoritative.revision,
+                    objective: authoritative.objective,
+                    paused: authoritative.paused === true,
+                });
+            }
+            return;
+        }
+        if (outcome === "persisted") {
+            // The durable terminal transition is the publication barrier: clients
+            // must never observe an exhausted Goal that does not exist on disk.
+            onStream?.({
+                type: "goal_progress",
+                goalId: runGoal.goalId,
+                revision: runGoal.revision,
+                status: "exhausted",
+                round: round ?? 0,
+            });
+        }
+        if (goalHookHandler) {
+            hooks.unregister("on_stop", goalHookHandler);
+            if (slots.getActiveGoalHook() === goalHookHandler) {
+                slots.setActiveGoalHook(null);
+                slots.setActiveGoalHookAttached(false);
+                slots.setActiveRuntimeGoal(null);
+                slots.setActivePersistedRunGoal(null);
+            }
+        }
+    };
+}

package/dist/engine/run-image-input.d.ts

@@ -1,4 +1,4 @@
-import type { InputAttachmentMeta } from "../protocol/types.js";
+import type { InputAttachmentMeta } from "../types.js";
 import type { ContentBlock, LLMConfig } from "../types.js";
 import { type ParsedTask } from "./parse-task.js";
 import type { EngineResult } from "./types.js";

package/dist/engine/run-image-input.js

@@ -76,9 +76,11 @@ export async function prepareRunImageInput(args) {
         parsedTask = {
             text: [parsedTask.text, attachmentContext.text].filter(Boolean).join("\n\n"),
             images: [...parsedTask.images, ...attachmentContext.images],
-            hasImages: parsedTask.hasImages ||
-                attachmentContext.images.length > 0 ||
-                attachmentContext.hasStructuredImageAttachments,
+            // A structured image attachment can intentionally degrade to textual
+            // metadata when the selected model has no vision support. Only actual
+            // image bytes require the vision gate below; the on-disk path remains
+            // useful to file-oriented tools and delegated Work Sessions.
+            hasImages: parsedTask.hasImages || attachmentContext.images.length > 0,
         };
     }
     if (parsedTask.hasImages) {

package/dist/engine/run-session-open.d.ts

@@ -0,0 +1,41 @@
+import type { Message, SessionKind } from "../types.js";
+import type { SessionBundle, SessionManager } from "../session/session-manager.js";
+import type { ParsedTask } from "./parse-task.js";
+import type { buildRunUserMessageContent } from "./run-image-input.js";
+import type { EngineConfig, EngineResult } from "./types.js";
+import type { EngineRunOptions } from "./run-types.js";
+export interface OpenRunSessionArgs {
+    sessionManager: SessionManager;
+    options: EngineRunOptions | undefined;
+    parsedTask: ParsedTask;
+    taskText: string;
+    userMessageContent: ReturnType<typeof buildRunUserMessageContent>;
+    cwd: string;
+    sessionKind: SessionKind;
+    sessionWorkspaceProfile: string | undefined;
+    /** Standing brief resent by the host each turn until the Session persists it. */
+    sessionBrief?: string;
+    llmModel: string;
+    llmProvider: string;
+    isSubAgent: boolean;
+    origin: EngineConfig["origin"];
+    costStore: EngineConfig["costStore"];
+    cachedCompactedMessages: Message[] | undefined;
+    onAgentDirectionsDelivered: ((envelopeIds: NonNullable<EngineRunOptions["agentDirection"]>["envelopeIds"]) => void) | undefined;
+}
+export interface OpenedRunSession {
+    session: SessionBundle;
+    messages: Message[];
+    freshImageMessage: Message | undefined;
+    resumedFromDisk: boolean;
+    claimClientMessageId: (bundle: SessionBundle, clientMessageId: string | undefined, source: "submit" | "steer") => boolean;
+    releaseClientMessageId: (clientMessageId: string) => void;
+}
+export type OpenRunSessionResult = {
+    ok: true;
+    opened: OpenedRunSession;
+} | {
+    ok: false;
+    result: EngineResult;
+};
+export declare function openRunSession(args: OpenRunSessionArgs): OpenRunSessionResult;