@cjhyy/code-shell-core 0.7.0-beta.1 → 0.7.0

package/dist/engine/input-attachments.js

@@ -1,6 +1,7 @@
 import { createHash } from "node:crypto";
 import { readdir, readFile, realpath, stat } from "node:fs/promises";
 import { extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { logger } from "../logging/logger.js";
 import { classifyPath } from "../tool-system/path-policy.js";
 import { enforceImageBytePolicy } from "./image-policy.js";
 const IMAGE_MIME_BY_EXT = {
@@ -23,8 +24,18 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
     const images = [];
     const errors = [];
     const pendingImages = [];
+    const diagnostics = [];
     let hasStructuredImageAttachments = false;
+    logger.info("engine.run.input_attachments.start", {
+        attachmentCount: attachments.length,
+        expectedSessionId: expectedSessionId ?? null,
+        includeImageBytes,
+    });
     if (!expectedSessionId) {
+        logger.warn("engine.run.input_attachments.invalid_session", {
+            attachmentCount: attachments.length,
+            reason: "missing_expected_session_id",
+        });
         return {
             text: "",
             images: [],
@@ -33,6 +44,10 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
         };
     }
     if (!isSafeSessionPathSegment(expectedSessionId)) {
+        logger.warn("engine.run.input_attachments.invalid_session", {
+            attachmentCount: attachments.length,
+            reason: "unsafe_expected_session_id",
+        });
         return {
             text: "",
             images: [],
@@ -40,36 +55,89 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
             hasStructuredImageAttachments: false,
         };
     }
-    for (const attachment of attachments) {
-        if (!attachment || typeof attachment !== "object")
+    for (const [index, attachment] of attachments.entries()) {
+        if (!attachment || typeof attachment !== "object") {
+            errors.push(`attachment at index ${index} is not an object`);
+            diagnostics.push({
+                index,
+                id: "(unknown)",
+                kind: typeof attachment,
+                path: null,
+                mime: null,
+                stage: "invalid_metadata",
+            });
             continue;
-        const displayPath = attachment.path || attachment.relPath || attachment.absPath;
+        }
+        const id = stringField(attachment.id) ?? "(unknown)";
+        const kind = stringField(attachment.kind) ?? "(unknown)";
+        const declaredMime = stringField(attachment.mime);
+        const displayPath = firstString(attachment.path, attachment.relPath, attachment.absPath);
         if (!displayPath) {
-            errors.push(`attachment ${attachment.id || "(unknown)"} has no path`);
+            errors.push(`attachment ${id} has no valid path`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: null,
+                mime: declaredMime ?? null,
+                stage: "invalid_path_metadata",
+            });
             continue;
         }
         if (attachment.sessionId !== expectedSessionId) {
-            errors.push(`attachment ${attachment.id || displayPath} session mismatch: expected ${expectedSessionId}, got ${attachment.sessionId}`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} session mismatch: expected ${expectedSessionId}, got ${attachment.sessionId}`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "session_mismatch",
+            });
             continue;
         }
-        const resolved = resolveAttachmentPath(attachment, cwd);
+        const resolved = resolveAttachmentPath(attachment, cwd, displayPath);
         let info;
         try {
             info = await stat(resolved);
         }
         catch (err) {
-            errors.push(`attachment ${attachment.id || displayPath} stat failed: ${err.message}`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} stat failed: ${err.message}`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "stat_failed",
+            });
             continue;
         }
         const policy = classifyPath(resolved, { workspaceRoot: cwdReal, operation: "read" });
         if (policy.decision !== "allow") {
-            errors.push(`attachment ${attachment.id || displayPath} blocked by path policy: ${policy.reason}`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} blocked by path policy: ${policy.reason}`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "path_policy_blocked",
+            });
             continue;
         }
         const realPath = policy.resolvedPath;
         const stagedPathError = await validateStagedAttachmentPath(attachment, realPath, cwdReal, expectedSessionId, displayPath);
         if (stagedPathError) {
             errors.push(stagedPathError);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "staged_path_blocked",
+            });
             continue;
         }
         if (attachment.kind === "directory" || info.isDirectory()) {
@@ -83,35 +151,85 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
                 ...tree.lines,
                 `</attached-directory>`,
             ].join("\n"));
+            diagnostics.push({
+                index,
+                id,
+                kind: "directory",
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: tree.truncated ? "directory_metadata_truncated" : "directory_metadata",
+            });
             continue;
         }
         if (!info.isFile()) {
-            errors.push(`attachment ${attachment.id || displayPath} is not a regular file or directory`);
+            errors.push(`attachment ${id === "(unknown)" ? displayPath : id} is not a regular file or directory`);
+            diagnostics.push({
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime: declaredMime ?? null,
+                stage: "unsupported_filesystem_entry",
+            });
             continue;
         }
-        const mime = attachment.mime || IMAGE_MIME_BY_EXT[extname(realPath).toLowerCase()];
+        const mime = declaredMime || IMAGE_MIME_BY_EXT[extname(realPath).toLowerCase()];
         if (attachment.kind === "image") {
             hasStructuredImageAttachments = true;
             if (!includeImageBytes || attachment.vision?.include === false) {
                 textBlocks.push(formatFileMetadata(attachment, displayPath, realPath, info.size, mime));
+                diagnostics.push({
+                    index,
+                    id,
+                    kind,
+                    path: displayPath,
+                    mime: mime ?? null,
+                    stage: "image_metadata_only",
+                });
                 continue;
             }
             if (!mime ||
                 !mime.startsWith("image/") ||
                 !IMAGE_MIME_BY_EXT[extname(realPath).toLowerCase()]) {
-                errors.push(`image attachment ${attachment.id || displayPath} has unsupported image type`);
+                errors.push(`image attachment ${id === "(unknown)" ? displayPath : id} has unsupported image type`);
+                diagnostics.push({
+                    index,
+                    id,
+                    kind,
+                    path: displayPath,
+                    mime: mime ?? null,
+                    stage: "unsupported_image_type",
+                });
                 continue;
             }
+            const diagnostic = {
+                index,
+                id,
+                kind,
+                path: displayPath,
+                mime,
+                stage: "image_pending_bytes",
+            };
             pendingImages.push({
                 attachment,
                 displayPath,
                 realPath,
                 mime,
                 size: info.size,
+                diagnostic,
             });
+            diagnostics.push(diagnostic);
             continue;
         }
         textBlocks.push(formatFileMetadata(attachment, displayPath, realPath, info.size, mime));
+        diagnostics.push({
+            index,
+            id,
+            kind,
+            path: displayPath,
+            mime: mime ?? null,
+            stage: "file_metadata",
+        });
     }
     if (errors.length === 0 && includeImageBytes && pendingImages.length > 0) {
         const verdict = enforceImageBytePolicy(pendingImages.map((image) => ({
@@ -121,6 +239,11 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
         })));
         if (!verdict.ok) {
             errors.push(`image attachment size policy failed: ${verdict.message}`);
+            for (const diagnostic of diagnostics) {
+                if (diagnostic.stage === "image_pending_bytes") {
+                    diagnostic.stage = "image_size_policy_failed";
+                }
+            }
         }
         else {
             for (const image of pendingImages) {
@@ -130,6 +253,7 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
                 }
                 catch (err) {
                     errors.push(`image attachment ${image.attachment.id || image.displayPath} read failed: ${err.message}`);
+                    image.diagnostic.stage = "image_read_failed";
                     continue;
                 }
                 const sha256 = createHash("sha256").update(bytes).digest("hex");
@@ -145,17 +269,36 @@ export async function buildInputAttachmentContext(attachments, cwd, options = {}
                     origin: image.attachment.origin,
                     sessionId: image.attachment.sessionId,
                 });
+                image.diagnostic.stage = "image_bytes_loaded";
             }
         }
     }
+    logger.info("engine.run.input_attachments.complete", {
+        attachmentCount: attachments.length,
+        textBlockCount: textBlocks.length,
+        imageCount: images.length,
+        errorCount: errors.length,
+        attachments: diagnostics,
+    });
     return { text: textBlocks.join("\n\n"), images, errors, hasStructuredImageAttachments };
 }
-function resolveAttachmentPath(attachment, cwd) {
-    const candidate = attachment.vision?.mediaPath || attachment.absPath || attachment.relPath || attachment.path;
+function resolveAttachmentPath(attachment, cwd, displayPath) {
+    const visionPath = attachment.vision && typeof attachment.vision === "object"
+        ? stringField(attachment.vision.mediaPath)
+        : undefined;
+    const candidate = visionPath ??
+        firstString(attachment.absPath, attachment.relPath, attachment.path) ??
+        displayPath;
     if (isAbsolute(candidate))
         return candidate;
     return resolve(cwd, candidate);
 }
+function firstString(...values) {
+    return values.find((value) => typeof value === "string" && value.length > 0);
+}
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
 async function validateStagedAttachmentPath(attachment, realPath, cwdReal, expectedSessionId, displayPath) {
     if (!isStagedAttachmentReference(attachment, realPath, cwdReal))
         return undefined;

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

@@ -0,0 +1,22 @@
+import type { InputAttachmentMeta } from "../protocol/types.js";
+import type { ContentBlock, LLMConfig } from "../types.js";
+import { type ParsedTask } from "./parse-task.js";
+import type { EngineResult } from "./types.js";
+export interface PreparedRunImageInput {
+    parsedTask: ParsedTask;
+    taskText: string;
+}
+export type PrepareRunImageInputResult = ({
+    ok: true;
+} & PreparedRunImageInput) | {
+    ok: false;
+    result: EngineResult;
+};
+export declare function prepareRunImageInput(args: {
+    task: string;
+    cwd: string;
+    llm: Pick<LLMConfig, "provider" | "providerKind" | "model">;
+    sessionId?: string;
+    attachments?: readonly InputAttachmentMeta[];
+}): Promise<PrepareRunImageInputResult>;
+export declare function buildRunUserMessageContent(parsedTask: ParsedTask, cwd: string, taskText: string): string | ContentBlock[];

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

@@ -0,0 +1,195 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { capabilitiesFor } from "../llm/capabilities/index.js";
+import { logger } from "../logging/logger.js";
+import { tryCompressImages } from "./image-compression.js";
+import { byteLengthFromBase64, collectAttachedImagePaths, dropOversizedImages, enforceImagePolicy, } from "./image-policy.js";
+import { buildInputAttachmentContext } from "./input-attachments.js";
+import { parseTaskWithImages } from "./parse-task.js";
+export async function prepareRunImageInput(args) {
+    const { task, cwd, llm, sessionId } = args;
+    // Parse `<codeshell-image>` blocks out of the raw task string before
+    // any other gate looks at it. Two concerns:
+    //   1. The noise detector sees raw base64 as gibberish and would reject the
+    //      whole turn — split images out first so it only inspects prose.
+    //   2. Models that don't accept vision must be refused immediately, with the
+    //      image bytes intact for the user to retry on another model.
+    let parsedTask;
+    try {
+        parsedTask = parseTaskWithImages(task);
+    }
+    catch (err) {
+        const msg = err.message;
+        logger.warn("engine.run.image_parse_failed", { error: msg });
+        return {
+            ok: false,
+            result: {
+                text: `ERROR: image attachment is malformed (${msg}). Drop the image and try again, or re-attach it.`,
+                reason: "image_error",
+                sessionId: sessionId ?? "image-parse-failed",
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    const cap = capabilitiesFor((llm.providerKind ?? llm.provider), llm.model);
+    let attachmentContext;
+    try {
+        attachmentContext = await buildInputAttachmentContext(args.attachments, cwd, {
+            includeImageBytes: cap.supportsVision,
+            expectedSessionId: sessionId,
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error("engine.run.input_attachment_exception", {
+            stage: "build_input_attachment_context",
+            attachmentCount: args.attachments?.length ?? 0,
+            error: message,
+        });
+        return {
+            ok: false,
+            result: {
+                text: `ERROR: input attachment could not be prepared (${message}). Re-attach it or choose a path inside the workspace.`,
+                reason: "image_error",
+                sessionId: sessionId ?? "input-attachment-exception",
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    if (attachmentContext.errors.length > 0) {
+        const detail = attachmentContext.errors.join("; ");
+        logger.warn("engine.run.input_attachment_failed", { error: detail });
+        return {
+            ok: false,
+            result: {
+                text: `ERROR: input attachment could not be read (${detail}). Re-attach it or choose a path inside the workspace.`,
+                reason: "image_error",
+                sessionId: sessionId ?? "input-attachment-failed",
+                turnCount: 0,
+                usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+            },
+        };
+    }
+    if (attachmentContext.text || attachmentContext.hasStructuredImageAttachments) {
+        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,
+        };
+    }
+    if (parsedTask.hasImages) {
+        if (!cap.supportsVision) {
+            logger.warn("engine.run.vision_not_supported", {
+                provider: llm.provider,
+                model: llm.model,
+                imageCount: parsedTask.images.length,
+            });
+            return {
+                ok: false,
+                result: {
+                    text: `ERROR: model "${llm.model}" does not accept image input. ` +
+                        `Switch to a vision-capable model (e.g. gpt-4o, claude-sonnet, gemini-1.5-pro) and resend.`,
+                    reason: "image_error",
+                    sessionId: sessionId ?? "vision-not-supported",
+                    turnCount: 0,
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                },
+            };
+        }
+        // Size gate. Hosts are expected to pre-compress to IMAGE_TARGETS; this is
+        // the last cheap refusal point before a provider request carries the bytes.
+        let verdict = enforceImagePolicy(parsedTask.images);
+        if (!verdict.ok && verdict.code === "image_too_large") {
+            const compressed = await tryCompressImages(parsedTask.images);
+            if (compressed.anyCompressed) {
+                parsedTask.images = compressed.images;
+                logger.info("engine.run.image_compressed", {
+                    before: verdict.offender?.bytes,
+                    after: compressed.images.reduce((s, i) => s + byteLengthFromBase64(i.base64), 0),
+                });
+                verdict = enforceImagePolicy(parsedTask.images);
+            }
+        }
+        // After compression, anything still over the per-image cap is dropped with
+        // a textual placeholder so oversized bytes do not poison conversation history.
+        if (!verdict.ok && verdict.code === "image_too_large") {
+            const drop = dropOversizedImages(parsedTask.images);
+            if (drop.droppedCount > 0) {
+                parsedTask.images = drop.kept;
+                parsedTask.hasImages = drop.kept.length > 0;
+                parsedTask.text = drop.placeholder + "\n\n" + parsedTask.text;
+                logger.warn("engine.run.image_dropped", {
+                    droppedCount: drop.droppedCount,
+                    keptCount: drop.kept.length,
+                });
+                verdict = enforceImagePolicy(parsedTask.images);
+            }
+        }
+        if (!verdict.ok) {
+            logger.warn("engine.run.image_policy_failed", {
+                code: verdict.code,
+                imageCount: verdict.totals.imageCount,
+                totalBytes: verdict.totals.totalBytes,
+                offender: verdict.offender,
+            });
+            return {
+                ok: false,
+                result: {
+                    text: `ERROR: ${verdict.message}`,
+                    reason: "image_error",
+                    sessionId: sessionId ?? `image-policy-${verdict.code}`,
+                    turnCount: 0,
+                    usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                },
+            };
+        }
+    }
+    // For downstream noise-detection + transcript persistence we want the text
+    // portion only. Image bytes ride in parsedTask.images and re-enter the message
+    // tree below.
+    const taskText = parsedTask.text;
+    return { ok: true, parsedTask, taskText };
+}
+export function buildRunUserMessageContent(parsedTask, cwd, taskText) {
+    // Compose the user-turn payload once so resume + cold paths agree on shape.
+    // When an attached image came from a workspace file, surface that path to the
+    // model as text so file-oriented tools can use the real on-disk path.
+    const attachedPaths = collectAttachedImagePaths(parsedTask.images, (name) => (isAbsolute(name) ? name : join(cwd, name)), existsSync);
+    const pathHint = attachedPaths.length > 0
+        ? `\n\n<attached-image-paths>\n${attachedPaths.join("\n")}\n</attached-image-paths>\n` +
+            `(上面附带的图片在工作区的真实路径，如需把它们作为工具输入（例如 GenerateImage 的 referenceImages、图生图参考图），直接使用这些路径。)`
+        : "";
+    const userMessageContent = parsedTask.hasImages
+        ? [
+            ...(parsedTask.text || pathHint
+                ? [{ type: "text", text: `${parsedTask.text}${pathHint}` }]
+                : []),
+            ...parsedTask.images.map((img) => ({
+                type: "image",
+                source: {
+                    type: "base64",
+                    media_type: img.mime,
+                    data: img.base64,
+                },
+            })),
+        ]
+        : taskText;
+    logger.info("engine.run.user_message_content_built", {
+        contentShape: Array.isArray(userMessageContent) ? "content_blocks" : "text",
+        textBlockCount: Array.isArray(userMessageContent)
+            ? userMessageContent.filter((block) => block.type === "text").length
+            : userMessageContent
+                ? 1
+                : 0,
+        imageBlockCount: Array.isArray(userMessageContent)
+            ? userMessageContent.filter((block) => block.type === "image").length
+            : 0,
+        attachedPathCount: attachedPaths.length,
+        textLength: taskText.length,
+    });
+    return userMessageContent;
+}

package/dist/engine/steer-queue.d.ts

@@ -6,13 +6,15 @@
  * it. Pure + side-effect-free so it unit-tests without the Engine/TurnLoop
  * harness (same rationale as the renderer's queuedInput.ts).
  */
+import type { InputAttachmentMeta } from "../protocol/types.js";
 export interface SteerItem {
     id: string;
     text: string;
     clientMessageId?: string;
+    attachments?: InputAttachmentMeta[];
 }
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string, clientMessageId?: string): SteerItem[];
+export declare function enqueueSteerItem(list: SteerItem[], id: string, text: string, clientMessageId?: string, attachments?: InputAttachmentMeta[]): SteerItem[];
 /**
  * Take everything currently queued and clear the list. Returns the drained
  * entries (in order) and the now-empty remainder. The turn loop calls this at

package/dist/engine/steer-queue.js

@@ -1,9 +1,17 @@
 /** Append a steer entry. Blank text is dropped (returns the list unchanged). */
-export function enqueueSteerItem(list, id, text, clientMessageId) {
+export function enqueueSteerItem(list, id, text, clientMessageId, attachments) {
     const t = text?.trim();
     if (!id || !t)
         return list;
-    return [...list, { id, text: t, ...(clientMessageId ? { clientMessageId } : {}) }];
+    return [
+        ...list,
+        {
+            id,
+            text: t,
+            ...(clientMessageId ? { clientMessageId } : {}),
+            ...(attachments && attachments.length > 0 ? { attachments: [...attachments] } : {}),
+        },
+    ];
 }
 /**
  * Take everything currently queued and clear the list. Returns the drained

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

@@ -10,9 +10,10 @@ 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 { Transcript } from "../session/transcript.js";
 import { type CumulativeUsageCounters } from "./session-usage.js";
-import { type GoalConfig, type GoalExtension } from "./goal.js";
+import { type GoalConfig, type GoalExtension, type GoalTerminationReason } from "./goal.js";
 export interface TurnLoopConfig {
     maxTurns: number;
     maxToolCallsPerTurn: number;
@@ -25,6 +26,11 @@ export interface TurnLoopConfig {
      * response, then downgrades them to placeholders in the working history.
      */
     freshImageMessages?: Iterable<Message>;
+    /**
+     * Per-run injected context that must be visible to the model but must not be
+     * summarized into durable history. Engine uses this for dynamicContext.
+     */
+    volatileContextMessages?: Iterable<Message>;
     /**
      * 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
@@ -88,6 +94,11 @@ export interface TurnLoopDeps {
      * Returns the updated counters so usage_update can carry both metric scopes.
      */
     recordCumulativeUsage?: (usage: TokenUsage) => CumulativeUsageCounters;
+    /**
+     * Lightweight per-session prompt-cache diagnostic, owned by Engine because it
+     * needs memory across TurnLoop instances.
+     */
+    recordCacheReadDiagnostics?: (usage: TokenUsage) => void;
     /** Persist the latest context-estimation anchor derived from provider usage. */
     recordContextUsageAnchor?: (anchor: ContextUsageAnchor) => void;
     /**
@@ -99,12 +110,20 @@ export interface TurnLoopDeps {
      * tests (turn loop tolerates undefined).
      */
     consumeSteer?: (source?: "normal_step" | "finalize_backfill") => SteerItem[];
+    /** 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. */
+    buildSteerUserMessageContent?: (item: SteerItem) => string | ContentBlock[] | Promise<string | ContentBlock[]>;
     /**
      * Execution-level idempotency guard for host-supplied user/steer intents.
      * Returns false only when a present clientMessageId has already entered this
      * run or the persisted transcript. Messages without an id bypass this guard.
      */
     claimClientMessageId?: (clientMessageId: string, source: "steer") => boolean;
+    /** Release a steer id reservation when preparation fails before persistence. */
+    releaseClientMessageId?: (clientMessageId: string) => void;
+    /** 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
@@ -114,11 +133,18 @@ export interface TurnLoopDeps {
      * goalTracker short-circuit still stops the run).
      */
     clearPersistedGoal?: () => 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;
 }
 export interface TurnLoopResult {
     text: string;
     reason: TerminalReason;
     messages: Message[];
+    /** Goal-specific forced terminal outcome; public TerminalReason stays stable. */
+    goalTermination?: GoalTerminationReason;
 }
 /**
  * 把一个 ToolResult 映射成发给 LLM 的 tool_result ContentBlock。
@@ -145,6 +171,7 @@ export declare class TurnLoop {
     private currentCumulativeUsage;
     private readonly sensitiveToolResultRedactions;
     private readonly pendingImageMessages;
+    private readonly volatileContextMessages;
     /**
      * Consecutive on_stop blocks (Goal mode kept the agent going). Reset to 0
      * on any unblocked completion. When it reaches config.maxStopBlocks the
@@ -203,6 +230,8 @@ export declare class TurnLoop {
      */
     private markStopped;
     private prepareMessagesForModel;
+    private stripVolatileContextMessages;
+    private appendVolatileContextMessages;
     private markPendingImagesConsumed;
     private redactConsumedSensitiveToolResults;
     private modelCallRecordingOptions;