@co0ontty/wand 4.83.1 → 4.84.0

package/dist/structured-content.d.ts

@@ -22,3 +22,26 @@ export declare function canonicalizeStructuredImagePart(value: unknown): Structu
 export declare function contentHasStructuredImage(content: unknown): boolean;
 /** Preserve both Responses content parts and arbitrary structured tool output. */
 export declare function normalizeStructuredToolResultContent(content: unknown): string | StructuredContentPart[];
+/**
+ * 将工具执行产生的原始结果（无论是纯文本、JSON、还是带图片的多模态数组）统一归一化为 Wand 内容块格式。
+ * - 纯文本结果（或仅包含 text part 的数组）：统一合并为格式规整的纯文本字符串，避免无谓的数组包装；
+ * - 包含图片/富媒体的结果：归一化为 `StructuredContentPart[]`，并将图片收敛为规范的 image part；
+ * - 针对 `{ content: [...] }` / `{ result: ... }` / `{ output: ... }` 等常见包装层自动解包。
+ */
+export declare function canonicalizeToolResultContent(value: unknown): string | StructuredContentPart[];
+export type AgentContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
+/**
+ * 将 Wand 历史存储或传输层中的 tool_result content 还原为 Agent/LLM SDK（如 @earendil-works/pi-ai）
+ * 可识别的 content parts 数组。
+ * - 文本转换为 `{ type: "text", text }`；
+ * - 包含 Base64 的图片转换为 `{ type: "image", data, mimeType }`；
+ * - 保证在多轮历史回放或断点恢复时，模型能够感知之前工具返回的多模态图片。
+ */
+export declare function toolResultContentToAgentParts(content: unknown): AgentContentPart[];

package/dist/structured-content.js

@@ -100,3 +100,75 @@ export function normalizeStructuredToolResultContent(content) {
     }
     return typeof content === "undefined" || content === null ? "" : String(content);
 }
+/**
+ * 将工具执行产生的原始结果（无论是纯文本、JSON、还是带图片的多模态数组）统一归一化为 Wand 内容块格式。
+ * - 纯文本结果（或仅包含 text part 的数组）：统一合并为格式规整的纯文本字符串，避免无谓的数组包装；
+ * - 包含图片/富媒体的结果：归一化为 `StructuredContentPart[]`，并将图片收敛为规范的 image part；
+ * - 针对 `{ content: [...] }` / `{ result: ... }` / `{ output: ... }` 等常见包装层自动解包。
+ */
+export function canonicalizeToolResultContent(value) {
+    const record = asRecord(value);
+    const raw = record && "content" in record
+        ? record.content
+        : record && "output" in record && typeof record.output === "string"
+            ? record.output
+            : value;
+    const normalized = normalizeStructuredToolResultContent(raw);
+    if (typeof normalized === "string")
+        return normalized;
+    if (normalized.length > 0 && normalized.every((part) => part.type === "text" && typeof part.text === "string")) {
+        return normalized
+            .map((part) => part.text)
+            .filter((text) => text.length > 0)
+            .join("\n");
+    }
+    return normalized;
+}
+/**
+ * 将 Wand 历史存储或传输层中的 tool_result content 还原为 Agent/LLM SDK（如 @earendil-works/pi-ai）
+ * 可识别的 content parts 数组。
+ * - 文本转换为 `{ type: "text", text }`；
+ * - 包含 Base64 的图片转换为 `{ type: "image", data, mimeType }`；
+ * - 保证在多轮历史回放或断点恢复时，模型能够感知之前工具返回的多模态图片。
+ */
+export function toolResultContentToAgentParts(content) {
+    if (typeof content === "string") {
+        return [{ type: "text", text: content }];
+    }
+    if (!Array.isArray(content)) {
+        const text = typeof content === "undefined" || content === null ? "" : String(content);
+        return [{ type: "text", text }];
+    }
+    const parts = [];
+    for (const part of content) {
+        if (!part || typeof part !== "object")
+            continue;
+        const record = part;
+        if (record.type === "text" && typeof record.text === "string") {
+            parts.push({ type: "text", text: record.text });
+            continue;
+        }
+        if (isStructuredImagePart(record)) {
+            const canonical = canonicalizeStructuredImagePart(record);
+            const source = asRecord(canonical?.source);
+            if (source && source.type === "base64" && typeof source.data === "string" && source.data) {
+                parts.push({
+                    type: "image",
+                    data: source.data,
+                    mimeType: typeof source.media_type === "string" && source.media_type ? source.media_type : "image/png",
+                });
+                continue;
+            }
+        }
+        try {
+            parts.push({ type: "text", text: JSON.stringify(record) });
+        }
+        catch {
+            parts.push({ type: "text", text: String(record) });
+        }
+    }
+    if (parts.length === 0) {
+        return [{ type: "text", text: "" }];
+    }
+    return parts;
+}

package/dist/structured-failure.d.ts

@@ -0,0 +1,16 @@
+import type { StructuredRunnerResult, StructuredRunnerTurnState } from "./structured-runner.js";
+export type ProviderRejectionKind = "quota" | "authentication" | "rate-limit" | "model-unavailable";
+export interface StructuredFailure {
+    kind: ProviderRejectionKind | "spawn" | "preflight" | "runtime" | "cancelled";
+    delivery: "rejected" | "accepted" | "unknown";
+    retryable: boolean;
+}
+/** Only call for a provider protocol error, never assistant text, stderr or a caught transport error. */
+export declare function classifyProviderRejection(message: string | null | undefined): ProviderRejectionKind | null;
+/** Monotonic observations matter: a final error can replace earlier usage or content. */
+export declare function hasStructuredExecutionProgress(state: StructuredRunnerTurnState): boolean;
+/** Shared by model groups, employee fallback and team startup facts. Missing facts never authorize replay. */
+export declare function classifyStructuredFailure(result: StructuredRunnerResult, observed?: {
+    output?: boolean;
+    progress?: boolean;
+}): StructuredFailure | null;

package/dist/structured-failure.js

@@ -0,0 +1,36 @@
+/** Only call for a provider protocol error, never assistant text, stderr or a caught transport error. */
+export function classifyProviderRejection(message) {
+    const text = message?.trim() ?? "";
+    if (!text || /\b(?:408|409|5\d\d)\b|fetch failed|timed?\s*out|ECONN\w*|socket|network error/i.test(text))
+        return null;
+    if (/insufficient[_ -](?:quota|credits|balance)|quota[_ -](?:exceeded|exhausted)|credit balance is too low|(?:usage|spending) limit (?:has been )?(?:reached|exceeded)|you have hit your usage limit/i.test(text)
+        || /^(?:错误[：:]\s*)?(?:积分|额度|余额)(?:已)?(?:耗尽|用尽|不足)(?:[，,：:。.!！\s].*)?$/.test(text))
+        return "quota";
+    if (/\b(?:invalid_api_key|authentication_error|invalid api key|incorrect api key|unauthorized)\b/i.test(text))
+        return "authentication";
+    if (/\b(?:rate_limit_exceeded|rate_limit_error|rate limit exceeded|too many requests)\b/i.test(text))
+        return "rate-limit";
+    if (/\b(?:model_not_found|model not found|unknown model)\b/i.test(text))
+        return "model-unavailable";
+    return null;
+}
+/** Monotonic observations matter: a final error can replace earlier usage or content. */
+export function hasStructuredExecutionProgress(state) {
+    return !!state.result.trim() || state.blocks.some((block) => block.type === "text" ? !!block.text.trim()
+        : block.type === "thinking" ? !!block.thinking.trim() : true)
+        || Object.values(state.usage ?? {}).some((value) => typeof value === "number" && value > 0);
+}
+/** Shared by model groups, employee fallback and team startup facts. Missing facts never authorize replay. */
+export function classifyStructuredFailure(result, observed = {}) {
+    if (!result.spawnError && !result.primaryError && !result.signal && (result.exitCode === null || result.exitCode === 0))
+        return null;
+    const progressed = observed.progress || hasStructuredExecutionProgress(result.state) || result.inputAccepted === true;
+    // A verified provider rejection may include a native session ID and protocol/selection metadata.
+    // Legacy adapters without this fact retain their stricter no-output/no-session retry boundary.
+    const uncertainOutput = !result.rejection && (observed.output || (!result.spawnError && !!result.state.sessionId));
+    const rejected = !progressed && !uncertainOutput && (result.inputAccepted === false || !!result.spawnError);
+    const kind = result.signal || result.stopReason ? "cancelled" : result.rejection
+        ?? (result.spawnError ? "spawn" : result.inputAccepted === false ? "preflight" : "runtime");
+    return { kind, delivery: progressed ? "accepted" : rejected ? "rejected" : "unknown",
+        retryable: rejected && kind !== "cancelled" && !result.retryForbidden };
+}

package/dist/structured-pi-adapter.d.ts

@@ -1,4 +1,5 @@
 import { spawn } from "node:child_process";
+import { type OpenRouterFreeCliDependencies } from "./openrouter-free-cli.js";
 import type { StructuredExecHost } from "./structured-exec-host.js";
 import type { StructuredRunnerAdapter, StructuredRunnerContext, StructuredRunnerExecution, StructuredRunnerObserver, StructuredRunnerTurnState } from "./structured-runner.js";
 import type { SessionSnapshot } from "./types.js";
@@ -6,13 +7,17 @@ type PiTurnState = StructuredRunnerTurnState & {
     pendingSessionId?: string;
 };
 export declare function isMissingPiSession(error: string | null | undefined, sessionId: string | null | undefined): boolean;
-export declare function buildPiArgs(session: SessionSnapshot, prompt: string): string[];
+export declare function piToolsArgs(session: Pick<SessionSnapshot, "piSettings">): string[];
+export declare function buildPiArgs(session: SessionSnapshot, prompt: string, resourceArgs?: string[]): string[];
 export declare function piToolName(name: string): string;
-export declare function applyPiEvent(state: PiTurnState, event: Record<string, unknown>): string | null;
+export declare function applyPiEvent(state: PiTurnState, event: Record<string, unknown>, observedAt?: string): string | null;
 export declare class PiRunner implements StructuredRunnerAdapter {
     private readonly spawnProcess;
     private readonly execHost?;
-    constructor(spawnProcess?: typeof spawn, execHost?: StructuredExecHost | undefined);
+    private readonly agentDir?;
+    private readonly freeModels?;
+    constructor(spawnProcess?: typeof spawn, execHost?: StructuredExecHost | undefined, agentDir?: string | undefined, freeModels?: OpenRouterFreeCliDependencies | undefined);
     start(context: StructuredRunnerContext, observer: StructuredRunnerObserver): StructuredRunnerExecution;
+    private startCli;
 }
 export {};

package/dist/structured-pi-adapter.js

@@ -1,7 +1,16 @@
 import { spawn } from "node:child_process";
+import { capturePiExecutionEvent } from "./pi-execution.js";
+import { defaultCoreHarnessAgentDir } from "./harness-engine.js";
+import { preparePiResources } from "./pi-resource-run.js";
+import { prepareOpenRouterFreeCli } from "./openrouter-free-cli.js";
+import { isOpenRouterFreeSelector } from "./openrouter-free-selection.js";
+import { getErrorMessage } from "./error-utils.js";
+import { classifyProviderRejection, hasStructuredExecutionProgress } from "./structured-failure.js";
+import { settleThinkingRound, updateThinkingActivity } from "./structured-thinking.js";
 import { startStructuredCli } from "./structured-exec-pump.js";
-import { asRecord, normalizeStructuredToolResultContent } from "./structured-content.js";
+import { asRecord, canonicalizeToolResultContent } from "./structured-content.js";
 import { systemPromptArgs, thinkingEffortToPiLevel } from "./structured-provider-common.js";
+import { defaultPiCliSessionSettings, PI_BUILTIN_TOOLS, piToolSelection } from "./pi-session-settings.js";
 export function isMissingPiSession(error, sessionId) {
     return !!sessionId && !!error?.includes(`No session found matching '${sessionId}'`);
 }
@@ -17,24 +26,22 @@ function textContent(value) {
         return item.text;
     return textContent(item.content);
 }
-/**
- * Pi 的工具结果是 `{ content: [ text…, image… ] }`。图片 part 不能像以前那样只抽文本
- * 丢掉——读图 / 截图全靠它，统一交给 normalizeStructuredToolResultContent 归一化。
- * 纯文本结果仍压成字符串，保持既有形态。
- */
-function piToolResultContent(value) {
-    const record = asRecord(value);
-    const raw = record && "content" in record ? record.content : value;
-    const normalized = normalizeStructuredToolResultContent(raw);
-    if (typeof normalized === "string")
-        return normalized;
-    if (normalized.length > 0 && normalized.every((part) => part.type === "text" && typeof part.text === "string")) {
-        return normalized.map((part) => part.text).filter(Boolean).join("\n");
-    }
-    return normalized;
+export function piToolsArgs(session) {
+    // 没有会话设置（旧快照）时按 CLI 出厂默认：跟随 Pi 自身配置，不传任何工具参数。
+    const settings = session.piSettings ?? defaultPiCliSessionSettings();
+    // 旧快照可能带未校验的名字：只保留合法的基础工具，再交给策略附加 CodeMode / 目标工具。
+    const selection = piToolSelection({
+        ...settings,
+        tools: settings.tools.filter((tool) => PI_BUILTIN_TOOLS.includes(tool)),
+    });
+    // `globalTools` 打开：既不传 --tools 也不传 --exclude-tools，完全跟随 Pi 自身配置。
+    if (selection.mode === "config")
+        return [];
+    return selection.names.length ? ["--tools", selection.names.join(",")] : ["--no-tools"];
 }
-export function buildPiArgs(session, prompt) {
+export function buildPiArgs(session, prompt, resourceArgs = []) {
     const args = ["--mode", "json", "--print"];
+    args.push(...piToolsArgs(session), ...resourceArgs);
     const model = session.selectedModel?.trim();
     if (model && model !== "default")
         args.push("--model", model);
@@ -86,8 +93,21 @@ function applyPiAssistantMessage(state, message) {
         }
     }
     const thinking = thinkings.join("");
-    if (thinking && !state.blocks.some((block) => block.type === "thinking")) {
-        state.blocks.push({ type: "thinking", thinking });
+    // 流式事件只给出边界时，最后一轮会停在空占位上。这里用完整正文补齐，
+    // 而不是因为「已经有思考块」就把真实内容整段丢掉；单轮时更长的正文为准。
+    const thinkingBlocks = state.blocks.filter((block) => block.type === "thinking");
+    const lastThinking = thinkingBlocks.at(-1);
+    if (thinking) {
+        if (!lastThinking)
+            state.blocks.push({ type: "thinking", thinking });
+        else if (!lastThinking.thinking.trim())
+            lastThinking.thinking = thinking;
+        else if (thinkingBlocks.length === 1 && thinking.length > lastThinking.thinking.length) {
+            lastThinking.thinking = thinking;
+        }
+    }
+    else {
+        settleThinkingRound(state.blocks, thinking);
     }
     const text = texts.join("");
     if (text) {
@@ -107,7 +127,8 @@ function applyPiAssistantMessage(state, message) {
     }
     return null;
 }
-export function applyPiEvent(state, event) {
+export function applyPiEvent(state, event, observedAt) {
+    capturePiExecutionEvent(state.blocks, event);
     // Pi announces the ID before it writes a session file. The file is only
     // created when an assistant message is saved, so this ID is not resumable yet.
     if (event.type === "session" && typeof event.id === "string")
@@ -119,6 +140,7 @@ export function applyPiEvent(state, event) {
         state.phase = "responding";
         const update = asRecord(event.assistantMessageEvent);
         const delta = typeof update?.delta === "string" ? update.delta : "";
+        updateThinkingActivity(state.blocks, update, observedAt);
         if (update?.type === "text_delta" && delta) {
             const last = state.blocks.at(-1);
             if (last?.type === "text")
@@ -158,7 +180,7 @@ export function applyPiEvent(state, event) {
     }
     if (event.type === "tool_execution_end") {
         const id = typeof event.toolCallId === "string" ? event.toolCallId : "unknown";
-        state.blocks.push({ type: "tool_result", tool_use_id: id, content: piToolResultContent(event.result), is_error: event.isError === true });
+        state.blocks.push({ type: "tool_result", tool_use_id: id, content: canonicalizeToolResultContent(event.result), is_error: event.isError === true });
     }
     if (event.type === "message_end" || event.type === "turn_end") {
         const message = asRecord(event.message);
@@ -176,28 +198,85 @@ export function applyPiEvent(state, event) {
         }
     }
     if (event.type === "agent_end" && Array.isArray(event.messages)) {
+        let error = null;
         for (const raw of event.messages) {
             const message = asRecord(raw);
             if (message?.role === "assistant") {
                 if (state.pendingSessionId)
                     state.sessionId = state.pendingSessionId;
-                const error = applyPiAssistantMessage(state, message);
-                if (error)
-                    return error;
+                error = applyPiAssistantMessage(state, message);
             }
         }
+        return error;
     }
     return null;
 }
 export class PiRunner {
     spawnProcess;
     execHost;
-    constructor(spawnProcess = spawn, execHost) {
+    agentDir;
+    freeModels;
+    constructor(spawnProcess = spawn, execHost, agentDir, freeModels) {
         this.spawnProcess = spawnProcess;
         this.execHost = execHost;
+        this.agentDir = agentDir;
+        this.freeModels = freeModels;
     }
     start(context, observer) {
-        const args = buildPiArgs(context.session, context.prompt);
+        const selection = context.session.piSettings?.resources;
+        const codemodeOverride = context.session.piSettings?.codemodeOverride;
+        const freeSelection = isOpenRouterFreeSelector(context.session.selectedModel);
+        const env = { ...context.env };
+        delete env.WAND_PI_RESOURCE_POLICY;
+        delete env.WAND_PI_FREE_POLICY;
+        delete env.WAND_PI_FREE_TOKEN;
+        context = { ...context, env };
+        if (!selection && !codemodeOverride && !freeSelection)
+            return this.startCli(context, observer);
+        // Return synchronously so the manager registers ownership in this tick. Preparation belongs to
+        // this execution; stop/delete during preparation prevents the process from being started.
+        let execution = null;
+        let interrupted = false;
+        const spawnedAt = new Date().toISOString();
+        const completion = (async () => {
+            const prepared = [];
+            try {
+                let preparedEnv = context.env;
+                if (selection || codemodeOverride) {
+                    const resources = await preparePiResources(this.agentDir ?? defaultCoreHarnessAgentDir(), context.session.cwd, selection, preparedEnv, codemodeOverride);
+                    prepared.push(resources);
+                    preparedEnv = resources.env;
+                }
+                if (interrupted || !observer.isActive())
+                    throw new Error("资源准备已取消，尚未启动 Pi。");
+                if (freeSelection) {
+                    if (!this.freeModels)
+                        throw new Error("免费模型 CLI 接入未就绪，请更新 Wand 服务后重试。");
+                    const free = prepareOpenRouterFreeCli(this.freeModels, { ...context, env: preparedEnv });
+                    prepared.push(free);
+                    preparedEnv = free.env;
+                }
+                execution = this.startCli({ ...context, env: preparedEnv }, observer, prepared.flatMap((item) => item.args));
+                const result = await execution.completion;
+                // A configured fallback tool uses its own capabilities. Only the free-price boundary
+                // forbids switching after execution; resource preparation failures still fail closed below.
+                return freeSelection ? { ...result, retryForbidden: true } : result;
+            }
+            finally {
+                for (const item of prepared.reverse())
+                    item.close();
+            }
+        })().catch((error) => ({
+            state: { blocks: [], result: "", sessionId: context.session.claudeSessionId },
+            exitCode: 1, signal: null, stderr: "", primaryError: getErrorMessage(error),
+            inputAccepted: false, retryForbidden: true,
+        }));
+        return { get args() { return execution?.args ?? buildPiArgs(context.session, context.prompt, ["--no-skills"]); },
+            get pid() { return execution?.pid ?? null; }, spawnedAt, completion,
+            interrupt: () => { interrupted = true; execution?.interrupt(); } };
+    }
+    startCli(context, observer, resourceArgs = []) {
+        const args = buildPiArgs(context.session, context.prompt, resourceArgs);
         const state = {
             blocks: [],
             result: "",
@@ -206,12 +285,14 @@ export class PiRunner {
             phase: "responding",
         };
         let primaryError = null;
+        let progressed = false;
+        let unparsedOutput = false;
         return startStructuredCli({
             sessionId: context.session.id,
             file: "pi",
             args,
             cwd: context.session.cwd,
-            env: context.env,
+            env: this.agentDir ? { ...context.env, PI_CODING_AGENT_DIR: this.agentDir } : context.env,
             observer,
             execHost: this.execHost,
             spawnProcess: this.spawnProcess,
@@ -222,12 +303,32 @@ export class PiRunner {
                 try {
                     const event = JSON.parse(line);
                     observer.onEvent?.(event);
-                    primaryError = applyPiEvent(state, event) ?? primaryError;
+                    primaryError = applyPiEvent(state, event, new Date().toISOString()) ?? primaryError;
+                    progressed ||= hasStructuredExecutionProgress(state);
+                    const messages = event.type === "agent_end" && Array.isArray(event.messages) ? event.messages
+                        : event.type === "message_end" || event.type === "turn_end" ? [event.message] : [];
+                    progressed ||= messages.some((raw) => {
+                        const message = asRecord(raw);
+                        return message?.role === "assistant" && (message.stopReason !== "error"
+                            || (Array.isArray(message.content) && message.content.length > 0));
+                    });
+                    const lastAssistant = asRecord([...messages].reverse().find((raw) => asRecord(raw)?.role === "assistant"));
+                    // Pi can recover internally. A later completed answer supersedes an earlier error;
+                    // the opposite order remains a failure and the monotonic progress fact forbids replay.
+                    if (lastAssistant && lastAssistant.stopReason !== "error")
+                        primaryError = null;
                     observer.onUpdate(state);
                 }
-                catch { /* Pi stdout is NDJSON; ignore non-protocol noise. */ }
+                catch {
+                    unparsedOutput = true; /* Unknown stdout is not evidence of a safe refusal. */
+                }
+            },
+            finalize: (ctx, exitCode, signal, spawnError) => {
+                const rejection = !progressed && !unparsedOutput && !signal && !spawnError
+                    ? classifyProviderRejection(primaryError) : null;
+                return { state, exitCode, signal, stderr: ctx.stderr, primaryError, ...(spawnError ? { spawnError } : {}),
+                    ...(rejection ? { rejection, inputAccepted: false } : progressed ? { inputAccepted: true } : {}) };
             },
-            finalize: (ctx, exitCode, signal, spawnError) => ({ state, exitCode, signal, stderr: ctx.stderr, primaryError, ...(spawnError ? { spawnError } : {}) }),
         });
     }
 }

package/dist/structured-provider-common.d.ts

@@ -30,6 +30,12 @@ export declare function defaultStructuredRunner(provider: SessionProvider): Sess
 export declare function normalizeStructuredRunner(runner: unknown): unknown;
 export declare function resolveStructuredRunner(provider: SessionProvider, requestedRunner: unknown): SessionRunner;
 export declare function defaultStructuredState(provider: SessionProvider, runner?: SessionRunner): StructuredSessionState;
+/**
+ * 回合锚点的收敛兜底：`inFlight !== true` 时 turnStartedAt / lastActivityAt 一律读成
+ * null。写入点已经逐条走 settleTurn()，这里再挡一层历史库残值和重启降级窗口——
+ * 否则客户端会在一条早就结束的会话上算出「已运行 N 分钟」。
+ */
+export declare function normalizeTurnAnchors(state: StructuredSessionState | undefined): StructuredSessionState | undefined;
 export declare function normalizeThinkingEffort(value: unknown): SessionSnapshot["thinkingEffort"];
 export declare function thinkingEffortToClaudeCliEffort(effort: SessionSnapshot["thinkingEffort"]): string | null;
 export declare function thinkingEffortToClaudeSlashEffort(effort: SessionSnapshot["thinkingEffort"]): string;

package/dist/structured-provider-common.js

@@ -119,7 +119,29 @@ export function resolveStructuredRunner(provider, requestedRunner) {
     return runner === "claude-sdk" ? "claude-cli-print" : runner;
 }
 export function defaultStructuredState(provider, runner = defaultStructuredRunner(provider)) {
-    return { provider, runner, lastError: null, inFlight: false, activeRequestId: null };
+    return {
+        provider,
+        runner,
+        lastError: null,
+        inFlight: false,
+        activeRequestId: null,
+        // 锚点是 inFlight 的派生读数：不在飞的默认态必须显式为 null，而不是 undefined，
+        // 这样任何 {...defaultStructuredState(...)} 展开都不会把上一轮的旧锚点带出来。
+        turnStartedAt: null,
+        lastActivityAt: null,
+    };
+}
+/**
+ * 回合锚点的收敛兜底：`inFlight !== true` 时 turnStartedAt / lastActivityAt 一律读成
+ * null。写入点已经逐条走 settleTurn()，这里再挡一层历史库残值和重启降级窗口——
+ * 否则客户端会在一条早就结束的会话上算出「已运行 N 分钟」。
+ */
+export function normalizeTurnAnchors(state) {
+    if (!state || state.inFlight)
+        return state;
+    if (state.turnStartedAt === null && state.lastActivityAt === null)
+        return state;
+    return { ...state, turnStartedAt: null, lastActivityAt: null };
 }
 export function normalizeThinkingEffort(value) {
     if (typeof value !== "string")

package/dist/structured-runner.d.ts

@@ -1,4 +1,31 @@
 import type { ContentBlock, ConversationTurn, SessionSnapshot } from "./types.js";
+/** core 引擎回报的上下文占用；CLI runner 无此能力时省略。 */
+export interface StructuredContextUsage {
+    /** 本轮请求实际占用的上下文 token。 */
+    usedTokens: number;
+    /** 当前模型上下文窗口 token。 */
+    windowTokens: number;
+    /** used / window，0-100，保留 1 位。 */
+    percent: number;
+    /** 本会话累计压缩次数。 */
+    compactions?: number;
+}
+/** core 引擎本轮发生的一次上下文压缩，由会话管理器落成压缩状态。 */
+export interface StructuredCompactionNotice {
+    reason: "threshold" | "manual" | "overflow";
+    tokensBefore: number;
+    /** 压缩后重估的 token；估算值，不作为计费依据。 */
+    tokensAfter?: number;
+    summary: string;
+    /** 摘要覆盖到第几条会话消息之前（即从这一条开始保留原样）。 */
+    fromTurnIndex: number;
+    /** 被摘要覆盖的消息条数。 */
+    droppedMessages: number;
+    /** 本会话累计压缩次数。 */
+    compactions: number;
+    /** 摘要调用本身的用量。 */
+    usage?: ConversationTurn["usage"];
+}
 export interface StructuredRunnerTurnState {
     blocks: ContentBlock[];
     result: string;
@@ -7,11 +34,21 @@ export interface StructuredRunnerTurnState {
     usage?: ConversationTurn["usage"];
     /** Provider turn phase when the CLI stays alive after its visible reply. */
     phase?: "responding" | "background";
+    /** Actual server-owned resource choice for this submitted round; presentation metadata only. */
+    resourceSelection?: import("./pi-session-settings.js").PiResourceSelectionNotice;
+    /** 本轮结束后的上下文占用（core 引擎）。 */
+    contextUsage?: StructuredContextUsage;
+    /** 本轮发生的上下文压缩（core 引擎）；每个回合最多一条。 */
+    compaction?: StructuredCompactionNotice;
+    /** Native Pi extension metadata to checkpoint, never part of the wire DTO. */
+    harnessExtensionState?: SessionSnapshot["harnessExtensionState"];
 }
 export interface StructuredRunnerContext {
     session: SessionSnapshot;
     prompt: string;
     env: NodeJS.ProcessEnv;
+    /** Execution-only group boundary; never persisted/projected to session DTOs. */
+    modelGroupModels?: readonly string[];
 }
 export interface StructuredRunnerObserver {
     isActive(): boolean;
@@ -30,6 +67,14 @@ export interface StructuredRunnerResult {
     stdoutTail?: string;
     stopReason?: "ask-user-question";
     spawnError?: NodeJS.ErrnoException;
+    /** Explicit pre-execution fact only; absent means unknown, not permission to replay. */
+    inputAccepted?: boolean;
+    /** A resource preparation failure or explicit price boundary must not be bypassed by fallback. */
+    retryForbidden?: boolean;
+    /** Adapter-verified initial provider refusal, with no prior model output or tool execution. */
+    rejection?: import("./structured-failure.js").ProviderRejectionKind;
+    /** Normalized once at the runner boundary; consumers do not re-guess delivery from error text. */
+    failure?: import("./structured-failure.js").StructuredFailure | null;
 }
 export interface StructuredRunnerExecution {
     args: string[];