@steerable/agent-shell 0.7.4 → 0.8.1

package/dist/local-backend/coreloop-stream.d.ts

@@ -40,6 +40,23 @@ export interface CoreLoopToolAction {
         auto?: boolean;
     };
 }
+/**
+ * What the sidecar knew about a failed model request, beyond its text.
+ *
+ * The host renders user-facing copy per `errorKind` and never parses
+ * `message` for it: the provider taxonomy is structured data, and message
+ * text is for the diagnostics panel.
+ */
+export interface TurnFailureInfo {
+    /** Provider classification; `undefined` when the sidecar did not send one. */
+    errorKind?: string;
+    /** Proxy the request used, credentials stripped; `undefined` means direct. */
+    proxy?: string;
+    /** Provider attempts spent on the failing request, including the last. */
+    attempts?: number;
+    /** HTTP status when the provider answered with one. */
+    statusCode?: number;
+}
 export interface CoreLoopTurnOutcome {
     status: string;
     reason?: string;
@@ -204,6 +221,13 @@ export interface StreamCoreLoopTurnOptions {
     }) => void;
     /** Fired when a tool finishes on the host (for tool-card rendering). */
     onToolAction?: (action: CoreLoopToolAction) => void;
+    /**
+     * Fired when the sidecar abandons the attempt it was streaming and starts
+     * the request again (a retry after partial output). Everything emitted via
+     * `onText` / `onReasoning` since the last restart belongs to a reply the
+     * user will never see in full and must be withdrawn from the display.
+     */
+    onRestart?: () => void;
     /** soft_timeout / budget_exhausted notices from the loop. */
     onNotice?: (kind: string, notice?: {
         kind: string;

package/dist/local-backend/coreloop-stream.js

@@ -307,6 +307,9 @@ export async function streamCoreLoopTurn(options) {
                 // for the sidecar's cancelled done.
                 if (cancelling)
                     return;
+                if (chunk.restart) {
+                    options.onRestart?.();
+                }
                 if (chunk.delta) {
                     options.onText(chunk.delta);
                 }
@@ -373,8 +376,15 @@ export async function streamCoreLoopTurn(options) {
                 // persist the partial trace — failed turns are the ones dogfooding
                 // most needs to inspect.
                 const failure = new Error(`coreloop stream failed: ${err.kind}: ${err.message}`);
+                const annotated = failure;
                 if (err.traceId)
-                    failure.traceId = err.traceId;
+                    annotated.traceId = err.traceId;
+                annotated.failureInfo = {
+                    errorKind: err.errorKind,
+                    proxy: err.proxy,
+                    attempts: err.attempts,
+                    statusCode: err.statusCode,
+                };
                 reject(failure);
             },
         })

package/dist/local-backend/resumable-turn.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Which turns the `resume` channel may continue.
+ *
+ * `resume` replays the durable record's projection as the loop seed, so it can
+ * only continue a turn the record still ends mid-way through. Three settled
+ * states reach this decision, and they are not the same question:
+ *
+ * - **Interrupted** (W7-1): the process died, so the turn_active marker
+ *   survived and no terminal assistant message was written. The user message
+ *   is the record's tail; continuing finishes the request that never got an
+ *   answer.
+ * - **Failed**: the turn's last model request exhausted its retries. The
+ *   process is alive and settled the turn, so the marker is gone and the
+ *   assistant message carries `completionStatus: 'failed'`. Everything
+ *   completed before the failure is in the record — tools included — so
+ *   continuing asks the model for the next step without repeating side
+ *   effects.
+ * - **Cancelled**: the user stopped it. Continuing is allowed for the same
+ *   reason as a failure, and deliberately: the usual cause is impatience with
+ *   a retry, not a decision to abandon the task.
+ *
+ * A turn that completed normally is none of these. Resuming it would append a
+ * reply the user never asked for, which is why this is a whitelist: an
+ * unrecognised state refuses.
+ */
+/** Why a turn can be continued, as far as the store can tell. */
+export type ResumableReason = 'interrupted' | 'failed' | 'cancelled';
+export interface ResumableTurnInput {
+    /** The `turn_active` marker survived: a turn began and never settled. */
+    turnActive: boolean;
+    /** A stream for this chat is live in THIS process right now. */
+    streamActive: boolean;
+    /** Role of the chat's newest persisted message, or null on an empty chat. */
+    lastMessageRole: string | null;
+    /**
+     * `completionStatus` of the last assistant message when the store ends on
+     * one. Absent when the newest message is not an assistant reply, or when the
+     * metadata predates the field.
+     */
+    lastAssistantStatus?: string | null;
+}
+/**
+ * Returns why the chat's last turn may be continued, or null when it may not.
+ *
+ * A live stream always refuses: the turn is running, and a second writer on
+ * the same record would interleave two tails.
+ */
+export declare function resumableTurn(input: ResumableTurnInput): ResumableReason | null;

package/dist/local-backend/resumable-turn.js

@@ -0,0 +1,53 @@
+/**
+ * Which turns the `resume` channel may continue.
+ *
+ * `resume` replays the durable record's projection as the loop seed, so it can
+ * only continue a turn the record still ends mid-way through. Three settled
+ * states reach this decision, and they are not the same question:
+ *
+ * - **Interrupted** (W7-1): the process died, so the turn_active marker
+ *   survived and no terminal assistant message was written. The user message
+ *   is the record's tail; continuing finishes the request that never got an
+ *   answer.
+ * - **Failed**: the turn's last model request exhausted its retries. The
+ *   process is alive and settled the turn, so the marker is gone and the
+ *   assistant message carries `completionStatus: 'failed'`. Everything
+ *   completed before the failure is in the record — tools included — so
+ *   continuing asks the model for the next step without repeating side
+ *   effects.
+ * - **Cancelled**: the user stopped it. Continuing is allowed for the same
+ *   reason as a failure, and deliberately: the usual cause is impatience with
+ *   a retry, not a decision to abandon the task.
+ *
+ * A turn that completed normally is none of these. Resuming it would append a
+ * reply the user never asked for, which is why this is a whitelist: an
+ * unrecognised state refuses.
+ */
+/**
+ * Returns why the chat's last turn may be continued, or null when it may not.
+ *
+ * A live stream always refuses: the turn is running, and a second writer on
+ * the same record would interleave two tails.
+ */
+export function resumableTurn(input) {
+    if (input.streamActive)
+        return null;
+    if (input.turnActive) {
+        // A surviving marker with an assistant tail is the crash-between-write-
+        // and-clear window; the reply proves the turn settled, so it is not
+        // interrupted — but a failed reply may still be worth continuing.
+        return input.lastMessageRole === 'assistant'
+            ? statusReason(input.lastAssistantStatus)
+            : 'interrupted';
+    }
+    if (input.lastMessageRole !== 'assistant')
+        return null;
+    return statusReason(input.lastAssistantStatus);
+}
+function statusReason(status) {
+    if (status === 'failed')
+        return 'failed';
+    if (status === 'cancelled')
+        return 'cancelled';
+    return null;
+}

package/dist/local-backend/router.d.ts

@@ -1,3 +1,4 @@
+import { type TurnFailureInfo } from './coreloop-stream.js';
 import type { ScopedStore } from '../storage/scoped-store.js';
 import { ToolRouter } from '../tool-router.js';
 import { type ResolvedAsk } from '../sidecar/reverse-ask-user.js';
@@ -35,10 +36,14 @@ export interface WakeResult {
     status?: number;
 }
 /**
- * 把 CoreLoop/LLM 的底层错误翻译成适合直接显示在助手消息里的中文提示。
- * 原始错误仍保存在 messageMetadata.completionReason 里，便于排查。
+ * Reads the structured failure detail off a rejected stream.
+ *
+ * `streamCoreLoopTurn` annotates its rejection; anything else (an abort, a
+ * router-level error) carries none, which the renderer shows as its generic
+ * card. Returns undefined rather than an empty object so the persisted
+ * metadata omits the field entirely.
  */
-export declare function userFacingCoreLoopFailure(reason: string): string;
+export declare function readTurnFailureInfo(err: unknown): TurnFailureInfo | undefined;
 export interface StreamOptions {
     /**
      * 取消信号。renderer 主动 Stop、窗口被销毁、应用退出时由 main 进程 abort。
@@ -47,6 +52,37 @@ export interface StreamOptions {
      */
     signal?: AbortSignal;
 }
+/**
+ * Extracts the fields a "reconnecting" indicator needs from a retry notice.
+ *
+ * The loop announces every retry as a `hook_action`; only attempts on the
+ * same model request are a wait the user notices, so the round and delay are
+ * carried through. Returns null for any other hook action so the caller can
+ * keep its round-boundary handling unchanged.
+ */
+/**
+ * `completionStatus` of a persisted assistant message, or null.
+ *
+ * Only the terminal assistant message's status decides whether Continue is
+ * offered, so this reads the field and leaves the meaning to
+ * `resumableTurn`. A message without metadata (older builds) yields null,
+ * which refuses — resuming a turn whose end state is unknown could append a
+ * reply to a conversation that already finished.
+ */
+export declare function readCompletionStatus(message: {
+    messageMetadata?: string | null;
+} | undefined): string | null;
+export declare function readRetryNotice(notice: {
+    kind?: string;
+    action?: unknown;
+    delayMs?: unknown;
+    round?: unknown;
+    reason?: unknown;
+} | undefined): {
+    round?: number;
+    delayMs?: number;
+    reason?: string;
+} | null;
 /**
  * Out-of-band 事件推送回调。用于把"在请求生命周期之外"才出结果的事件（例如
  * 后台 AI 标题生成）异步广播到所有 renderer。main.ts 注入 `webContents.send`

package/dist/local-backend/router.js

@@ -16,7 +16,7 @@ import { buildAmbientDelegateRoster, buildDelegateDispatchInstruction, buildDele
 import { resolveMentionedAgentIds } from './mention-targets.js';
 import { presentToolCall } from '../tool-presentation.js';
 import { readSidecarHistoryEntries, timelineFromHistoryEntries, } from './task-process.js';
-import { appendTimelineDelta, freezeTimelineReasoning, sealLastTimelineBlock, syncTimelineTools, } from './turn-timeline.js';
+import { appendTimelineDelta, dropAttemptBlocks, freezeTimelineReasoning, sealLastTimelineBlock, syncTimelineTools, } from './turn-timeline.js';
 import { turnDurationMs } from './turn-duration.js';
 import { DEFAULT_SYSTEM_PROMPT, telemetryEnabled } from '../storage/index.js';
 import { isSkillPinned, isToolAllowed, mergeAgentCapabilities, normalizeToolPolicy, resolveSkillExcludes, } from './agent-capability.js';
@@ -44,8 +44,9 @@ import { formatHistoryForSummary, truncateMiddle, } from './context-compactor.js
 import { planRegenerateTruncate, resolveRegenerateContext, resolveRegenerateForkOrdinal, } from './regenerate-helper.js';
 import { resolveBranchActivation } from './branch-helper.js';
 import { detectInterruptedTurn } from './interrupted-helper.js';
+import { resumableTurn } from './resumable-turn.js';
 import { handlePortableRequest } from './portable-service.js';
-import { getProductConfig, isPortableProduct } from '../product-config.js';
+import { getProductConfig, isPortableProduct, productConfigDirectConnection, } from '../product-config.js';
 import { dropCurrentUserMessage } from './history-helper.js';
 import { parseImageAttachments, processImageAttachments } from '../image-attachment.js';
 import { chatAttachmentsDirPath, isValidChatAttachmentsKey } from '../attachments.js';
@@ -152,23 +153,27 @@ function downloadMimeForPath(filePath) {
     return DOWNLOAD_MIME_BY_EXT[path.extname(filePath).toLowerCase()] ?? 'application/octet-stream';
 }
 /**
- * 把 CoreLoop/LLM 的底层错误翻译成适合直接显示在助手消息里的中文提示。
- * 原始错误仍保存在 messageMetadata.completionReason 里，便于排查。
+ * Reads the structured failure detail off a rejected stream.
+ *
+ * `streamCoreLoopTurn` annotates its rejection; anything else (an abort, a
+ * router-level error) carries none, which the renderer shows as its generic
+ * card. Returns undefined rather than an empty object so the persisted
+ * metadata omits the field entirely.
  */
-export function userFacingCoreLoopFailure(reason) {
-    if (reason.includes('HTTP 401') || reason.includes('HTTP 403')) {
-        return '[回复失败] 模型服务认证失败，请检查 API Key 配置。';
-    }
-    if (reason.includes('HTTP 404')) {
-        return '[回复失败] 模型服务或模型名不存在（HTTP 404），请检查 baseUrl 与 model 配置。';
-    }
-    if (reason.includes('ECONNREFUSED') ||
-        reason.includes('ENOTFOUND') ||
-        reason.includes('ETIMEDOUT') ||
-        reason.includes('fetch failed')) {
-        return '[回复失败] 无法连接模型服务，请检查网络或 baseUrl 配置。';
-    }
-    return `[回复失败] ${reason}`;
+export function readTurnFailureInfo(err) {
+    const info = err?.failureInfo;
+    if (!info || typeof info !== 'object')
+        return undefined;
+    const record = info;
+    const pick = (key) => typeof record[key] === 'string' && record[key] ? record[key] : undefined;
+    const pickNumber = (key) => typeof record[key] === 'number' ? record[key] : undefined;
+    const out = {
+        errorKind: pick('errorKind'),
+        proxy: pick('proxy'),
+        attempts: pickNumber('attempts'),
+        statusCode: pickNumber('statusCode'),
+    };
+    return Object.values(out).some((value) => value !== undefined) ? out : undefined;
 }
 /**
  * Parses a pagination-style query param (`?page=`, `?limit=`) into a finite
@@ -251,6 +256,44 @@ function isRoundBoundaryHook(notice) {
         return false;
     return notice.action === 'retry' || notice.action === 'narrate';
 }
+/**
+ * Extracts the fields a "reconnecting" indicator needs from a retry notice.
+ *
+ * The loop announces every retry as a `hook_action`; only attempts on the
+ * same model request are a wait the user notices, so the round and delay are
+ * carried through. Returns null for any other hook action so the caller can
+ * keep its round-boundary handling unchanged.
+ */
+/**
+ * `completionStatus` of a persisted assistant message, or null.
+ *
+ * Only the terminal assistant message's status decides whether Continue is
+ * offered, so this reads the field and leaves the meaning to
+ * `resumableTurn`. A message without metadata (older builds) yields null,
+ * which refuses — resuming a turn whose end state is unknown could append a
+ * reply to a conversation that already finished.
+ */
+export function readCompletionStatus(message) {
+    const raw = message?.messageMetadata;
+    if (typeof raw !== 'string' || !raw)
+        return null;
+    try {
+        const status = JSON.parse(raw).completionStatus;
+        return typeof status === 'string' && status ? status : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function readRetryNotice(notice) {
+    if (notice?.kind !== 'hook_action' || notice.action !== 'retry')
+        return null;
+    return {
+        ...(typeof notice.round === 'number' ? { round: notice.round } : {}),
+        ...(typeof notice.delayMs === 'number' ? { delayMs: notice.delayMs } : {}),
+        ...(typeof notice.reason === 'string' && notice.reason ? { reason: notice.reason } : {}),
+    };
+}
 function buildLocalAgent() {
     const now = new Date().toISOString();
     return {
@@ -2040,6 +2083,14 @@ export class LocalBackendRouter {
                 data: await this.store.getUsageSummary(days),
             };
         }
+        // 二期 R4：网络失败统计。窗口默认 7 天（设置页「最近 7 天」那一块）。
+        if (method === 'GET' && pathname === '/api/v2/usage/reliability') {
+            const days = parsePositiveIntParam(url.searchParams.get('days'), 7);
+            return {
+                status: 200,
+                data: await this.store.getReliabilitySummary(days),
+            };
+        }
         if (method === 'POST' && pathname.match(/^\/api\/v2\/chats\/[^/]+\/suggest-replies$/)) {
             return {
                 status: 200,
@@ -2454,25 +2505,42 @@ export class LocalBackendRouter {
                 });
             }
             else if (isResume) {
-                // W7-1: 继续被中断的 turn —— 不追加新用户消息（记录里已有），而是让
-                // sidecar 回放 durable record 的投影作为循环种子。只在检测确为
-                // interrupted 时接受：对一个已正常完结的 turn 续跑只会给完整对话
-                // 凭空多接一段回复。
+                // 继续上一轮 —— 不追加新用户消息（记录里已有），而是让 sidecar 回放
+                // durable record 的投影作为循环种子。允许续跑的三种终态见
+                // `resumable-turn.ts`：崩溃中断、失败、用户停止。正常完成的回合拒绝，
+                // 否则会给完整对话凭空多接一段回复。
                 const prior = await this.store.listMessages(chatId, 200);
-                const interrupted = detectInterruptedTurn({
-                    turnActive: await this.store.getTurnActive(chatId) !== null,
+                const lastAssistant = prior.find((m) => m.role === 'assistant');
+                const reason = resumableTurn({
+                    turnActive: (await this.store.getTurnActive(chatId)) !== null,
                     streamActive: getActiveCoreLoopStreamId(chatId) !== undefined,
                     lastMessageRole: prior[0]?.role ?? null,
+                    lastAssistantStatus: readCompletionStatus(lastAssistant),
                 });
                 const lastUser = prior.find(m => m.role === 'user');
-                if (!interrupted || !lastUser) {
-                    emit(this.sse('error', { message: '没有可继续的中断回复' }));
+                if (!reason || !lastUser) {
+                    emit(this.sse('error', { message: '没有可继续的回复' }));
                     return { status: 409 };
                 }
                 // 触发轮的用户消息仍在库里（崩溃只丢了回复）——取其原文喂给
                 // buildConversationMessages，让 mode  preamble / deferred-exec 检测
                 // 仍然基于真实诉求。发给 sidecar 的 messages 为空（见下方调用点）。
                 userMessageText = lastUser.content;
+                // 在原先失败/停止的那条回复上记下「已从这里继续」：界面据此把整张
+                // 失败卡片收成一行历史记录，重启后仍然是这一行，而不是又一次失败。
+                if (lastAssistant && reason !== 'interrupted') {
+                    // 记不下来只会让卡片多留一张，不值得让续跑失败——所以吞掉异常，
+                    // 但用 try/catch 而不是 `.catch()`：store 实现可以是同步的。
+                    try {
+                        await this.store.patchMessageMetadata(chatId, lastAssistant.id, {
+                            continuedAt: new Date().toISOString(),
+                            continuedReason: reason,
+                        });
+                    }
+                    catch (patchErr) {
+                        console.warn('[local-backend] continue: metadata patch failed', patchErr);
+                    }
+                }
             }
             else {
                 userMessageText = String(payload.message || '').trim();
@@ -3660,12 +3728,33 @@ export class LocalBackendRouter {
         // approval:"off" 或 STEERABLE_APPROVAL=0 本轮不挂审批。
         const approval = resolveTurnApproval();
         let assistantText = '';
+        // Text this attempt streamed (reset on restart) and the timeline length
+        // when the attempt began, so a retry can withdraw exactly its own output.
+        let streamedText = '';
+        let attemptBlockStart = 0;
+        // A retry notice arrived and no output followed yet: the turn is waiting
+        // on the network, not on the model. `stream_restart` clears it because the
+        // retry has begun producing again.
+        let retrying = false;
+        // Reliability accounting for this turn (R4). A model request is either a
+        // pass (a fresh loop run) or a retry inside one (the sidecar re-issuing
+        // the same request), so attempts = passes + retries. The retry and direct
+        // flags are sticky: one retry anywhere in the turn is what the statistic
+        // asks about.
+        let turnPasses = 0;
+        let turnRetries = 0;
+        let retriedThisTurn = false;
+        let directThisTurn = false;
         const executedActions = [];
         const timeline = [];
         // 编排子代理生命周期事件累积（切回后用于重建 currentTurnChildren）。
         const children = [];
         let completionStatus = 'completed';
         let completionReason = '';
+        // Provider classification of the failing request (see TurnFailureInfo).
+        // Stays empty for a clean sidecar-reported failure, which carries its own
+        // `completionReason` but no per-request detail.
+        let failureInfo;
         let outcomeTraceId;
         // Every pass records its own sidecar trace; all of them are persisted
         // against the one assistant message this turn produces.
@@ -3735,6 +3824,9 @@ export class LocalBackendRouter {
                 provider: sidecarWireProvider(settings.provider),
                 model: overrideModel || settings.model,
                 reasoningEffort,
+                // 产品声明模型服务是否直连（跳过系统代理）。只在产品显式打开时下发，
+                // 未声明的产品线上字节与旧版完全一致。
+                ...(productConfigDirectConnection() ? { directConnection: true } : {}),
                 // W2.2.2 凭证代理：broker 活跃且命中 provider 主机时，baseUrl 改写
                 // 为 http（代理解析绝对 URI 后注入凭证转发 https），apiKey 不再下
                 // 发——sidecar 进程（沙箱内、可被 agent 行为影响）永远拿不到真实
@@ -3801,8 +3893,32 @@ export class LocalBackendRouter {
                     assistantText += delta;
                     appendTimelineDelta(timeline, 'text', delta);
                     live.content = assistantText;
+                    // Track what this attempt emitted so a retry can take exactly it
+                    // back: the host has already handed these bytes to the renderer.
+                    streamedText += delta;
                     emit(this.sseData({ content: delta }));
                 },
+                onRestart: () => {
+                    // The sidecar is re-issuing this request. Withdraw the attempt's
+                    // text and reasoning — persisted, live, and renderer views — so the
+                    // retry's reply does not arrive after a half sentence the model
+                    // never finished. Tool blocks stay: those calls ran.
+                    if (streamedText) {
+                        assistantText = assistantText.slice(0, assistantText.length - streamedText.length);
+                        streamedText = '';
+                    }
+                    // The retry is producing again; a Stop from here on is not a stop
+                    // "during reconnection".
+                    retrying = false;
+                    live.content = assistantText;
+                    dropAttemptBlocks(timeline, attemptBlockStart);
+                    attemptBlockStart = timeline.length;
+                    emit(this.sseData({
+                        type: 'stream_restart',
+                        content: assistantText,
+                        blocks: timeline,
+                    }));
+                },
                 onReasoning: (delta) => {
                     appendTimelineDelta(timeline, 'reasoning', delta);
                     emit(this.sseData({ type: 'reasoning', content: delta }));
@@ -3856,6 +3972,17 @@ export class LocalBackendRouter {
                     }
                 },
                 onNotice: (kind, notice) => {
+                    // A retry is a wait the user can feel: connection backoff runs for
+                    // seconds. Announce it so the turn can show "reconnecting" instead
+                    // of looking stuck, and so the wait itself is visible before the
+                    // next attempt starts. Not persisted — history keeps outcomes only.
+                    const retry = readRetryNotice(notice);
+                    if (retry) {
+                        retrying = true;
+                        retriedThisTurn = true;
+                        turnRetries += 1;
+                        emit(this.sseData({ type: 'turn_retry', ...retry }));
+                    }
                     if (kind === 'budget_exhausted') {
                         // 预算维度（rounds/tokens）在 notice.budget；notice.kind 是信封
                         // 类型（loop 事件 data 里的 budget 键经 sidecar 透传）。message
@@ -3920,6 +4047,7 @@ export class LocalBackendRouter {
                 afterPass: async (outcome) => {
                     if (outcome.traceId)
                         passTraceIds.push(outcome.traceId);
+                    turnPasses += 1;
                     // W6-9 用量归因:落一条 chat 用量事件(含成本估算,无单价模型 costUsd=null)。
                     // 每趟各落一条——续跑的花费是真实发生的，不该被合并掉。
                     if (outcome.usage) {
@@ -3965,11 +4093,16 @@ export class LocalBackendRouter {
         catch (err) {
             if (err instanceof DOMException && err.name === 'AbortError') {
                 completionStatus = 'cancelled';
-                completionReason = 'aborted_by_user';
+                // Stop lands for two very different reasons, and the card says which:
+                // while waiting out a retry (almost always impatience with a slow
+                // reconnect) or while the model was writing (a deliberate stop).
+                // Recorded here because only the host saw whether a retry was pending.
+                completionReason = retrying ? 'aborted_during_retry' : 'aborted_by_user';
             }
             else {
                 completionStatus = 'failed';
                 completionReason = err instanceof Error ? err.message : String(err);
+                failureInfo = readTurnFailureInfo(err);
                 emit(this.sse('error', { message: completionReason }));
             }
             // streamCoreLoopTurn attaches the sidecar trace id to failures — the
@@ -3980,6 +4113,72 @@ export class LocalBackendRouter {
                 passTraceIds.push(failureTraceId);
             }
         }
+        // 可靠性统计（R4）：一回合一条终态记录，与 token 用量分开记——用量
+        // 是每趟各一条（自动续跑的花费是真实发生的），终态只有一个。
+        // `usedDirect` 取产品当前配置：直连是产品级开关，不是每回合的决定。
+        try {
+            await this.store.recordUsageEvent({
+                chatId,
+                kind: 'turn',
+                provider: settings.provider,
+                model: overrideModel || settings.model,
+                promptTokens: 0,
+                completionTokens: 0,
+                totalTokens: 0,
+                outcome: completionStatus === 'failed'
+                    ? 'failed'
+                    : completionStatus === 'cancelled'
+                        ? 'cancelled'
+                        : 'completed',
+                failureKind: completionStatus === 'failed' ? (failureInfo?.errorKind ?? 'unknown') : null,
+                attempts: turnPasses + turnRetries || null,
+                retried: retriedThisTurn,
+                usedDirect: directThisTurn || productConfigDirectConnection(),
+            });
+        }
+        catch (reliabilityErr) {
+            // 统计写不进去不该影响回合收尾——消息已经落库，用户看到的是结果。
+            console.warn('[local-backend] record turn outcome failed', reliabilityErr);
+        }
+        // 配了遥测就把这一回合的终态作为计数上报（R4）。指标只有类别与次数，
+        // 没有对话内容，所以 `metadata` 档位也可以发；没配 endpoint 就一条不发。
+        // 失败不阻断：回合已经完成，投递不了是收集端的事。
+        // 取遥测设置：读不到只意味着这一回合不上报，不该影响回合收尾。用
+        // try/catch 而不是 `.catch()`——store 实现是同步返回时没有 thenable，
+        // 链式 `.catch` 会直接抛。
+        let telemetryForTurn = null;
+        try {
+            telemetryForTurn = await this.store.getTelemetrySettings();
+        }
+        catch (telemetryReadErr) {
+            console.warn('[local-backend] read telemetry settings failed', telemetryReadErr);
+        }
+        if (telemetryEnabled(telemetryForTurn) && telemetryForTurn?.endpoint) {
+            void supervisor
+                ?.call('metrics.export', {
+                // 一个端点同时收 trace 与 metric 时，把 /v1/traces 换成 /v1/metrics。
+                endpoint: telemetryForTurn.endpoint.replace(/\/v1\/traces$/, '/v1/metrics'),
+                serviceName: telemetryForTurn.serviceName,
+                samples: [
+                    {
+                        outcome: completionStatus === 'failed'
+                            ? 'failed'
+                            : completionStatus === 'cancelled'
+                                ? 'cancelled'
+                                : 'completed',
+                        ...(completionStatus === 'failed'
+                            ? { failureKind: failureInfo?.errorKind ?? 'unknown' }
+                            : {}),
+                        attempts: turnPasses + turnRetries,
+                        retried: retriedThisTurn,
+                        usedDirect: directThisTurn || productConfigDirectConnection(),
+                    },
+                ],
+            }, { timeoutMs: 10_000 })
+                .catch((err) => {
+                console.warn('[local-backend] telemetry metrics export failed', err);
+            });
+        }
         const durationMs = turnDurationMs((await this.store.getTurnActive(chatId))?.startedAt, Date.now());
         // 回合产物文件列表（成功/失败/取消都收集——半截回合写出的文件同样是
         // 产物）。收集失败只记日志，永远不该拖垮回合收尾。
@@ -4010,6 +4209,7 @@ export class LocalBackendRouter {
             ...(durationMs != null ? { durationMs } : {}),
             ...(autoContinuations > 0 ? { autoContinuations } : {}),
             ...(turnFiles.length > 0 ? { turnFiles } : {}),
+            ...(failureInfo ? { failure: failureInfo } : {}),
         }));
         try {
             await recordInsightTurn(this.store, {

package/dist/local-backend/turn-timeline.d.ts

@@ -17,6 +17,20 @@ export type PersistedTurnBlock = {
     actions: Array<Record<string, unknown>>;
 };
 export declare function appendTimelineDelta(blocks: PersistedTurnBlock[], type: 'text' | 'reasoning', delta: string, now?: number): void;
+/**
+ * Withdraw a discarded attempt's streamed text and reasoning.
+ *
+ * A retry after partial output restarts the reply from nothing, so the blocks
+ * this attempt produced must not survive into the persisted turn: the retry's
+ * own text would otherwise be appended after text the model never finished
+ * saying. Tool blocks are kept — a tool call that already ran is a fact, and
+ * the retry does not repeat it.
+ *
+ * @param blocks Timeline to prune in place.
+ * @param sinceLength `blocks.length` recorded when the attempt started; only
+ *   entries at or after that index are candidates.
+ */
+export declare function dropAttemptBlocks(blocks: PersistedTurnBlock[], sinceLength: number): void;
 /**
  * Close the current reasoning/text segment so the next same-kind delta
  * starts a new block. Mirrors apps/web `sealLastBlock`.

package/dist/local-backend/turn-timeline.js

@@ -25,6 +25,27 @@ export function appendTimelineDelta(blocks, type, delta, now = Date.now()) {
     }
     blocks.push({ type, content: delta });
 }
+/**
+ * Withdraw a discarded attempt's streamed text and reasoning.
+ *
+ * A retry after partial output restarts the reply from nothing, so the blocks
+ * this attempt produced must not survive into the persisted turn: the retry's
+ * own text would otherwise be appended after text the model never finished
+ * saying. Tool blocks are kept — a tool call that already ran is a fact, and
+ * the retry does not repeat it.
+ *
+ * @param blocks Timeline to prune in place.
+ * @param sinceLength `blocks.length` recorded when the attempt started; only
+ *   entries at or after that index are candidates.
+ */
+export function dropAttemptBlocks(blocks, sinceLength) {
+    for (let index = blocks.length - 1; index >= sinceLength; index -= 1) {
+        const block = blocks[index];
+        if (block && (block.type === 'text' || block.type === 'reasoning')) {
+            blocks.splice(index, 1);
+        }
+    }
+}
 /**
  * Close the current reasoning/text segment so the next same-kind delta
  * starts a new block. Mirrors apps/web `sealLastBlock`.

package/dist/local-executor.d.ts

@@ -239,8 +239,14 @@ export declare class LocalExecutor {
     /**
      * P2b：会话恢复时重灌 read-before-write 证据。sidecar 扫描持久记录里的
      * 文件工具结果，把 path → version 经 `read_state.seed` 推到这里——进程
-     * 重启后自动 CAS 仍然成立（CC `seed_read_state` 语义）。键是 sidecar 侧
-     * 已解析的绝对路径，原样存储；resolvePath 对绝对路径是恒等，查询能命中。
+     * 重启后自动 CAS 仍然成立（CC `seed_read_state` 语义）。
+     *
+     * 键必须过一遍 `resolvePath`：读证据的每一次读写都用规范化后的路径做键，
+     * 而 seed 来的路径是 sidecar 记录的原文。两者不一致时自动 CAS 永远查不
+     * 中，write/edit 会退回「未读先写已拒绝」。macOS 上 `/var/folders/…` 与
+     * `/private/var/folders/…` 就是这种情形（`os.tmpdir()` 返回未解析的
+     * 形式），Linux 的 `/tmp` 符号链接同理。
+     *
      * 返回实际收录的条目数（畸形条目跳过）。
      */
     seedReadState(state: Record<string, unknown>): number;

package/dist/local-executor.js

@@ -329,15 +329,21 @@ export class LocalExecutor {
     /**
      * P2b：会话恢复时重灌 read-before-write 证据。sidecar 扫描持久记录里的
      * 文件工具结果，把 path → version 经 `read_state.seed` 推到这里——进程
-     * 重启后自动 CAS 仍然成立（CC `seed_read_state` 语义）。键是 sidecar 侧
-     * 已解析的绝对路径，原样存储；resolvePath 对绝对路径是恒等，查询能命中。
+     * 重启后自动 CAS 仍然成立（CC `seed_read_state` 语义）。
+     *
+     * 键必须过一遍 `resolvePath`：读证据的每一次读写都用规范化后的路径做键，
+     * 而 seed 来的路径是 sidecar 记录的原文。两者不一致时自动 CAS 永远查不
+     * 中，write/edit 会退回「未读先写已拒绝」。macOS 上 `/var/folders/…` 与
+     * `/private/var/folders/…` 就是这种情形（`os.tmpdir()` 返回未解析的
+     * 形式），Linux 的 `/tmp` 符号链接同理。
+     *
      * 返回实际收录的条目数（畸形条目跳过）。
      */
     seedReadState(state) {
         let seeded = 0;
         for (const [p, version] of Object.entries(state)) {
             if (typeof p === 'string' && p.length > 0 && typeof version === 'string') {
-                this.readFileState.set(p, version);
+                this.readFileState.set(this.resolvePath(p), version);
                 seeded += 1;
             }
         }

package/dist/product-config.d.ts

@@ -132,9 +132,26 @@ export interface ProductConfig {
      * 超过则接口返回 413，不创建新会话。
      */
     forkWorkspaceMaxBytes?: number;
+    /**
+     * 模型请求是否跳过系统代理直连。缺省关（跟随系统代理）。
+     *
+     * 打开后这一端点的请求不经过用户在系统里配置的代理。用于国内常见
+     * 「开着 Clash，但模型服务本来就在直连规则里」的情形：代理多转一手
+     * 只会用更短的超时把本来能连上的请求断掉。
+     *
+     * 要求流量必须经过公司代理的环境（例如企业产品）应保持关闭。
+     */
+    directModelConnection?: boolean;
 }
 /** shell 内置智能体：只有产品显式 `true` 才开。 */
 export declare function isShellBuiltinAgentEnabled(id: 'local-assistant' | 'all-round-assistant', config?: ProductConfig): boolean;
+/**
+ * 模型请求是否直连（不经过系统代理）。只有产品显式 `true` 才开。
+ *
+ * 企业产品可能要求所有出网流量经过公司代理，所以缺省是关：产品不声明
+ * 就保持跟随系统代理的旧行为。
+ */
+export declare function productConfigDirectConnection(config?: ProductConfig): boolean;
 /** 对话与配置能否导出/导入。缺省关，产品必须显式打开。 */
 export declare function isPortableProduct(config?: ProductConfig): boolean;
 /** shell 内置技能：`true` 全开；否则只有对象里显式 `true` 的目录开。 */

package/dist/product-config.js

@@ -13,6 +13,15 @@
 export function isShellBuiltinAgentEnabled(id, config = getProductConfig()) {
     return config.builtinAgents?.[id] === true;
 }
+/**
+ * 模型请求是否直连（不经过系统代理）。只有产品显式 `true` 才开。
+ *
+ * 企业产品可能要求所有出网流量经过公司代理，所以缺省是关：产品不声明
+ * 就保持跟随系统代理的旧行为。
+ */
+export function productConfigDirectConnection(config = getProductConfig()) {
+    return config.directModelConnection === true;
+}
 /** 对话与配置能否导出/导入。缺省关，产品必须显式打开。 */
 export function isPortableProduct(config = getProductConfig()) {
     return config.portable === true;

package/dist/sidecar/types.d.ts

@@ -545,6 +545,17 @@ export interface SidecarStreamChunk {
         kind: string;
         [key: string]: unknown;
     };
+    /**
+     * The sidecar abandoned the attempt it was streaming and re-issued the
+     * request. Deltas received before this point belong to a reply that will
+     * never be completed, so the host withdraws them from the display rather
+     * than appending the retry's text after them.
+     */
+    restart?: {
+        reason: string;
+        round?: number;
+        attempt?: number;
+    };
     finishReason?: string;
     usage?: {
         promptTokens: number;
@@ -580,6 +591,22 @@ export interface SidecarStreamError {
     traceId?: string;
     kind: string;
     message: string;
+    /**
+     * Provider classification (`transport` / `auth` / `rate_limit` / `server` /
+     * `context_overflow` / `invalid_request` / `unknown`). Absent from older
+     * sidecars and from non-provider failures; treat missing as `unknown` rather
+     * than parsing the message.
+     */
+    errorKind?: string;
+    /**
+     * Proxy the model request went through, credentials stripped. Absent means
+     * the request went direct or the sidecar predates this field.
+     */
+    proxy?: string;
+    /** Provider attempts spent on the failing request, including the last. */
+    attempts?: number;
+    /** HTTP status when the provider answered with one. */
+    statusCode?: number;
 }
 /**
  * `agent.child` notification payload (child-agent lifecycle), demuxed by

package/dist/storage/index.d.ts

@@ -4,6 +4,7 @@ import { type TelemetrySettings } from './telemetry-settings.js';
 import { type WebSearchSettings } from './web-search-settings.js';
 import { type InsightKind, type InsightsProfile, type InsightsSettings, type InsightsSettingsPatch } from './insights-settings.js';
 import { type UsageSummary } from './usage-summary.js';
+import type { ReliabilitySummary } from './reliability-summary.js';
 import type { TenantScope } from './driver.js';
 import type { ScopedStore } from './scoped-store.js';
 export type { UsageModelBucket, UsageSummary } from './usage-summary.js';
@@ -326,7 +327,32 @@ export declare class SqliteScopedStore implements ScopedStore {
         totalTokens: number;
         cachedPromptTokens?: number;
         costUsd?: number | null;
+        /** How the turn ended; omitted keeps the historical 'completed' default. */
+        outcome?: 'completed' | 'failed' | 'cancelled';
+        /** Provider classification, recorded only for `failed`. */
+        failureKind?: string | null;
+        /** Model requests spent on the turn, retries included. */
+        attempts?: number | null;
+        /** Whether any request in the turn was retried. */
+        retried?: boolean;
+        /** Whether any request went direct instead of through the proxy. */
+        usedDirect?: boolean;
     }): Promise<void>;
+    /**
+     * Reliability summary for the last `sinceDays` days.
+     *
+     * Splits the three terminal states apart because they answer different
+     * questions: a failed turn is something to fix, a cancelled one is the user's
+     * decision and must not inflate the failure rate, and a retried turn that
+     * completed is the measure of whether retrying is doing its job. Turns
+     * recorded before these columns existed default to `completed`, which is the
+     * only honest reading — their outcome was not observed.
+     *
+     * @param sinceDays Window length in days, ending now.
+     * @returns Counts per outcome, failures broken down by provider
+     *   classification, and how many completed turns had retried.
+     */
+    getReliabilitySummary(sinceDays?: number): Promise<ReliabilitySummary>;
     /**
      * 聚合最近 `sinceDays` 天的用量:按 model 分桶( token 合计 + 成本合计),
      * 外加总计。成本只统计有单价的模型(cost_usd 非 NULL);无单价模型的

package/dist/storage/index.js

@@ -335,6 +335,20 @@ export class SqliteScopedStore {
         this.ensureColumn('tasks', 'owner_instance_id', 'TEXT');
         this.ensureColumn('insights_outbox', 'claimed_by', 'TEXT');
         this.ensureColumn('insights_outbox', 'claimed_at', 'TEXT');
+        // 网络失败统计（二期 R4）。一次回合一行，与 token 用量共用一张表：
+        // 两者都是「这一回合发生了什么」的事实，分成两张表只会让复盘时
+        // 要 join。
+        //
+        // outcome 取值 completed / failed / cancelled。cancelled 是用户主动
+        // 停止，不算失败——界面与统计都不该把它和网络故障混为一谈。
+        this.ensureColumn('usage_events', 'outcome', `TEXT NOT NULL DEFAULT 'completed'`);
+        // 失败类别（provider 分类：transport / auth / rate_limit / …）。
+        this.ensureColumn('usage_events', 'failure_kind', 'TEXT');
+        // 本回合一共发出了几次模型请求（含重试）。
+        this.ensureColumn('usage_events', 'attempts', 'INTEGER');
+        // 是否发生过重试，以及是否改走过直连。
+        this.ensureColumn('usage_events', 'retried', 'INTEGER NOT NULL DEFAULT 0');
+        this.ensureColumn('usage_events', 'used_direct', 'INTEGER NOT NULL DEFAULT 0');
         // 智能体技能面（增量迁移）：load_all_skills = 无视触发条件全量加载。
         // 此前这个行为是 router 里 `chatAgentId === 'all-round-assistant'` 的
         // 硬编码，自建智能体拿不到；建列时一次性回填给内置「智能助手」，之后
@@ -1124,9 +1138,59 @@ export class SqliteScopedStore {
     async recordUsageEvent(input) {
         this.db.prepare(`
       INSERT INTO usage_events
-        (tenant_id, user_id, id, chat_id, kind, provider, model, prompt_tokens, completion_tokens, total_tokens, cached_prompt_tokens, cost_usd, created_at)
-      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-    `).run(this.scope.tenantId, this.scope.userId, randomUUID(), input.chatId ?? null, input.kind, input.provider ?? null, input.model ?? null, Math.max(0, Math.floor(input.promptTokens)), Math.max(0, Math.floor(input.completionTokens)), Math.max(0, Math.floor(input.totalTokens)), Math.max(0, Math.floor(input.cachedPromptTokens ?? 0)), input.costUsd ?? null, new Date().toISOString());
+        (tenant_id, user_id, id, chat_id, kind, provider, model, prompt_tokens, completion_tokens, total_tokens, cached_prompt_tokens, cost_usd, created_at, outcome, failure_kind, attempts, retried, used_direct)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(this.scope.tenantId, this.scope.userId, randomUUID(), input.chatId ?? null, input.kind, input.provider ?? null, input.model ?? null, Math.max(0, Math.floor(input.promptTokens)), Math.max(0, Math.floor(input.completionTokens)), Math.max(0, Math.floor(input.totalTokens)), Math.max(0, Math.floor(input.cachedPromptTokens ?? 0)), input.costUsd ?? null, new Date().toISOString(), input.outcome ?? 'completed', input.failureKind ?? null, input.attempts ?? null, input.retried ? 1 : 0, input.usedDirect ? 1 : 0);
+    }
+    /**
+     * Reliability summary for the last `sinceDays` days.
+     *
+     * Splits the three terminal states apart because they answer different
+     * questions: a failed turn is something to fix, a cancelled one is the user's
+     * decision and must not inflate the failure rate, and a retried turn that
+     * completed is the measure of whether retrying is doing its job. Turns
+     * recorded before these columns existed default to `completed`, which is the
+     * only honest reading — their outcome was not observed.
+     *
+     * @param sinceDays Window length in days, ending now.
+     * @returns Counts per outcome, failures broken down by provider
+     *   classification, and how many completed turns had retried.
+     */
+    async getReliabilitySummary(sinceDays = 7) {
+        const since = new Date(Date.now() - sinceDays * 24 * 60 * 60 * 1000).toISOString();
+        const totals = this.db
+            .prepare(`SELECT
+           COUNT(*) AS total,
+           SUM(CASE WHEN outcome = 'failed' THEN 1 ELSE 0 END) AS failed,
+           SUM(CASE WHEN outcome = 'cancelled' THEN 1 ELSE 0 END) AS cancelled,
+           SUM(CASE WHEN outcome = 'completed' AND retried = 1 THEN 1 ELSE 0 END) AS recovered,
+           SUM(CASE WHEN used_direct = 1 THEN 1 ELSE 0 END) AS used_direct
+         FROM usage_events
+         WHERE tenant_id = ? AND user_id = ? AND created_at >= ?`)
+            .get(this.scope.tenantId, this.scope.userId, since);
+        const byKind = this.db
+            .prepare(
+        // Group by the expression, not the output alias: a bare `GROUP BY kind`
+        // resolves to a source column when one exists, which silently merges
+        // every row into the wrong bucket.
+        `SELECT COALESCE(failure_kind, 'unknown') AS kind, COUNT(*) AS count
+         FROM usage_events
+         WHERE tenant_id = ? AND user_id = ? AND created_at >= ?
+           AND outcome = 'failed'
+         GROUP BY COALESCE(failure_kind, 'unknown')
+         ORDER BY count DESC, kind`)
+            .all(this.scope.tenantId, this.scope.userId, since);
+        return {
+            sinceDays,
+            total: totals.total ?? 0,
+            failed: totals.failed ?? 0,
+            cancelled: totals.cancelled ?? 0,
+            /** Completed turns that had retried at least once. */
+            recoveredByRetry: totals.recovered ?? 0,
+            /** Turns where the model request went direct instead of via a proxy. */
+            usedDirect: totals.used_direct ?? 0,
+            failuresByKind: byKind.map((row) => ({ kind: row.kind, count: row.count })),
+        };
     }
     /**
      * 聚合最近 `sinceDays` 天的用量:按 model 分桶( token 合计 + 成本合计),

package/dist/storage/reliability-summary.d.ts

@@ -0,0 +1,55 @@
+/**
+ * 二期 R4 —— 网络失败的统计口径（纯逻辑）。
+ *
+ * 与 `usage-summary.ts` 同样的拆分理由：`LocalStore` 顶层加载的
+ * better-sqlite3 native 模块与 vitest 运行时二进制不兼容，SQL 留在
+ * store 里，口径与派生量放这里，可以直接单测。
+ *
+ * 三个终态分开数，因为它们回答不同的问题：
+ *
+ * - `failed` 是要修的东西。失败率的分母用它。
+ * - `cancelled` 是用户自己的决定，**不算失败**。把停止算成失败，会让
+ *   「网络在变差」和「用户等得不耐烦」看起来一样。
+ * - `recoveredByRetry` 是重试有没有用的直接度量：重试过、最终成功了
+ *   的回合数。它低不代表重试没价值（可能是网络好），但配合失败数看就
+ *   能判断 R3 的策略是否合适。
+ *
+ * 早于这三列存在之前写入的行，`outcome` 取默认值 `completed`——那时候
+ * 也没观测过终态，按完成计是唯一诚实的读法。
+ */
+/** Provider failure classification, as `LLMError.kind` names them. */
+export type FailureKind = 'transport' | 'rate_limit' | 'server' | 'auth' | 'invalid_request' | 'context_overflow' | 'unknown';
+/** One failure category with its count. */
+export interface FailureKindCount {
+    kind: string;
+    count: number;
+}
+/** Reliability numbers for one window. */
+export interface ReliabilitySummary {
+    sinceDays: number;
+    /** Every recorded turn in the window, whatever its outcome. */
+    total: number;
+    failed: number;
+    cancelled: number;
+    /** Completed turns in which at least one model request was retried. */
+    recoveredByRetry: number;
+    /** Turns whose model request went direct instead of through a proxy. */
+    usedDirect: number;
+    /** Failure counts per provider classification, largest first. */
+    failuresByKind: FailureKindCount[];
+}
+/**
+ * Share of turns that failed, as a number in [0, 1].
+ *
+ * Cancelled turns are excluded from the denominator: the user stopping is not
+ * evidence about the network. Returns null when nothing was observed, so a
+ * reader can tell "no failures" from "no data" — a dashboard that shows 0%
+ * on an empty window invites the wrong conclusion.
+ */
+export declare function failureRate(summary: ReliabilitySummary): number | null;
+/**
+ * The network-attributable share of failures, in [0, 1], or null when there
+ * were none. `transport` is the kind this phase's work targets; the rest are
+ * configuration (`auth`), throttling, or the provider's own errors.
+ */
+export declare function networkFailureShare(summary: ReliabilitySummary): number | null;

package/dist/storage/reliability-summary.js

@@ -0,0 +1,44 @@
+/**
+ * 二期 R4 —— 网络失败的统计口径（纯逻辑）。
+ *
+ * 与 `usage-summary.ts` 同样的拆分理由：`LocalStore` 顶层加载的
+ * better-sqlite3 native 模块与 vitest 运行时二进制不兼容，SQL 留在
+ * store 里，口径与派生量放这里，可以直接单测。
+ *
+ * 三个终态分开数，因为它们回答不同的问题：
+ *
+ * - `failed` 是要修的东西。失败率的分母用它。
+ * - `cancelled` 是用户自己的决定，**不算失败**。把停止算成失败，会让
+ *   「网络在变差」和「用户等得不耐烦」看起来一样。
+ * - `recoveredByRetry` 是重试有没有用的直接度量：重试过、最终成功了
+ *   的回合数。它低不代表重试没价值（可能是网络好），但配合失败数看就
+ *   能判断 R3 的策略是否合适。
+ *
+ * 早于这三列存在之前写入的行，`outcome` 取默认值 `completed`——那时候
+ * 也没观测过终态，按完成计是唯一诚实的读法。
+ */
+/**
+ * Share of turns that failed, as a number in [0, 1].
+ *
+ * Cancelled turns are excluded from the denominator: the user stopping is not
+ * evidence about the network. Returns null when nothing was observed, so a
+ * reader can tell "no failures" from "no data" — a dashboard that shows 0%
+ * on an empty window invites the wrong conclusion.
+ */
+export function failureRate(summary) {
+    const observed = summary.total - summary.cancelled;
+    if (observed <= 0)
+        return null;
+    return summary.failed / observed;
+}
+/**
+ * The network-attributable share of failures, in [0, 1], or null when there
+ * were none. `transport` is the kind this phase's work targets; the rest are
+ * configuration (`auth`), throttling, or the provider's own errors.
+ */
+export function networkFailureShare(summary) {
+    if (summary.failed <= 0)
+        return null;
+    const transport = summary.failuresByKind.find((row) => row.kind === 'transport');
+    return (transport?.count ?? 0) / summary.failed;
+}

package/dist/storage/scoped-store.d.ts

@@ -3,6 +3,7 @@ import type { InsightKind, InsightsSettings, InsightsSettingsPatch } from './ins
 import type { LlmSettings } from './llm-settings.js';
 import type { TelemetrySettings } from './telemetry-settings.js';
 import type { UsageSummary } from './usage-summary.js';
+import type { ReliabilitySummary } from './reliability-summary.js';
 import type { WebSearchSettings } from './web-search-settings.js';
 import type { TenantScope } from './driver.js';
 /** Explicit asynchronous storage API bound to one tenant and user. */
@@ -79,8 +80,14 @@ export interface ScopedStore {
         totalTokens: number;
         cachedPromptTokens?: number;
         costUsd?: number | null;
+        outcome?: 'completed' | 'failed' | 'cancelled';
+        failureKind?: string | null;
+        attempts?: number | null;
+        retried?: boolean;
+        usedDirect?: boolean;
     }): Promise<void>;
     getUsageSummary(sinceDays?: number): Promise<UsageSummary>;
+    getReliabilitySummary(sinceDays?: number): Promise<ReliabilitySummary>;
     getLlmSettings(): Promise<LlmSettings | null>;
     setLlmSettings(settings: LlmSettings): Promise<LlmSettings>;
     getTelemetrySettings(): Promise<TelemetrySettings | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.7.4",
+  "version": "0.8.1",
   "description": "Steerable framework — product-neutral Node HostRuntime and headless HTTP server shared by Tauri desktop and browser deployments; scenario packs extend it through @steerable/pack-sdk.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -53,9 +53,9 @@
     "jpeg-js": "^0.4.4",
     "node-pty": "^1.1.0",
     "pngjs": "^7.0.0",
-    "@steerable/agent-harness": "0.7.4",
-    "@steerable/agent-protocol": "0.7.4",
-    "@steerable/pack-sdk": "0.7.4"
+    "@steerable/agent-harness": "0.8.1",
+    "@steerable/agent-protocol": "0.8.1",
+    "@steerable/pack-sdk": "0.8.1"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",