@steerable/agent-shell 0.7.2 → 0.8.0

package/dist/sidecar/reverse-ask-user.js

@@ -11,25 +11,59 @@
  */
 import { randomUUID } from 'node:crypto';
 const EMPTY_REPLY = { answers: {} };
+function rememberAsk(resolved, chatId, intro, questions, answers, unattended) {
+    if (questions.length === 0)
+        return;
+    const key = chatId ?? '';
+    const queue = resolved.get(key) ?? [];
+    queue.push({
+        intro,
+        questions,
+        answers,
+        ...(unattended ? { unattended: true } : {}),
+    });
+    resolved.set(key, queue);
+}
+function shiftAsk(resolved, key) {
+    const queue = resolved.get(key);
+    if (!queue || queue.length === 0)
+        return undefined;
+    const next = queue.shift();
+    if (queue.length === 0)
+        resolved.delete(key);
+    return next;
+}
+/** The tool-row result stored in place of the truncated preview. */
+export function storedAskResult(ask) {
+    return {
+        intro: ask.intro,
+        questions: ask.questions,
+        answers: ask.answers,
+        ...(ask.unattended ? { unattended: true } : {}),
+    };
+}
 export function createAskUserBridge(deps) {
     const pending = new Map();
+    const resolved = new Map();
     return {
         handler: (params) => {
             const p = (params ?? {});
             const questions = Array.isArray(p.questions) ? p.questions : [];
             const chatId = typeof p.chatId === 'string' && p.chatId ? p.chatId : undefined;
+            const intro = typeof p.intro === 'string' ? p.intro : '';
             if (questions.length === 0) {
                 deps.onLog?.('ask_user: malformed request (no questions); answering empty');
                 return Promise.resolve({ ...EMPTY_REPLY });
             }
             if (!deps.hasWindow()) {
                 deps.onLog?.('ask_user: no renderer window; answering empty');
+                rememberAsk(resolved, chatId, intro, questions, {}, false);
                 return Promise.resolve({ ...EMPTY_REPLY });
             }
             const requestId = randomUUID();
             const prompt = {
                 requestId,
-                intro: typeof p.intro === 'string' ? p.intro : '',
+                intro,
                 questions: questions,
                 ...(chatId ? { chatId } : {}),
             };
@@ -41,6 +75,7 @@ export function createAskUserBridge(deps) {
                 catch (err) {
                     pending.delete(requestId);
                     deps.onLog?.(`ask_user: broadcast failed: ${String(err)}`);
+                    rememberAsk(resolved, chatId, intro, prompt.questions, {}, false);
                     resolve({ ...EMPTY_REPLY });
                 }
             });
@@ -55,8 +90,10 @@ export function createAskUserBridge(deps) {
             const answers = p.answers && typeof p.answers === 'object' && !Array.isArray(p.answers)
                 ? p.answers
                 : {};
+            rememberAsk(resolved, entry.prompt.chatId, entry.prompt.intro, entry.prompt.questions, answers, p.unattended === true);
             entry.resolve({ answers });
             return { ok: true };
         },
+        takeResolved: (chatId) => shiftAsk(resolved, chatId) ?? (chatId ? shiftAsk(resolved, '') : undefined),
     };
 }

package/dist/sidecar/types.d.ts

@@ -531,12 +531,13 @@ export interface SidecarStreamChunk {
             backend?: string;
             enforcement: string;
         };
-        /** Session-allow reuse. `cached` means this call did not show a card. */
+        /** Session-allow reuse. `cached` means this call did not show a card. `auto` is an unattended allow. */
         approval?: {
             kind?: string;
             category?: string;
             cached?: boolean;
             waitMs?: number;
+            auto?: boolean;
         };
     };
     /** CoreLoop notices: soft_timeout / budget_exhausted / round_end / hook_action. */
@@ -544,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;
@@ -579,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/dist/tool-presentation.js

@@ -38,6 +38,24 @@ function dataOf(result) {
 function failed(result) {
     return Boolean(result && typeof result === 'object' && result.success === false);
 }
+function askTitle(args, result) {
+    return clip(firstQuestion(args) || firstQuestion(result) || str(args, 'intro') || str(args, 'question')) || '提问';
+}
+function firstQuestion(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return '';
+    const questions = value.questions;
+    if (!Array.isArray(questions))
+        return '';
+    for (const question of questions) {
+        if (!question || typeof question !== 'object' || Array.isArray(question))
+            continue;
+        const text = str(question, 'text').trim();
+        if (text)
+            return text;
+    }
+    return '';
+}
 function commandTitle(args) {
     return clip(str(args, 'command')) || 'shell';
 }
@@ -230,7 +248,7 @@ const PRESENTERS = {
     ask_user: {
         card: 'generic',
         kind: 'other',
-        title: (args) => clip(str(args, 'intro') || str(args, 'question')) || '提问',
+        title: (args, result) => askTitle(args, result),
     },
     skill: { card: 'generic', kind: 'read', title: (args) => str(args, 'name') || 'skill' },
     delegate_subagent: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "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.2",
-    "@steerable/agent-protocol": "0.7.2",
-    "@steerable/pack-sdk": "0.7.2"
+    "@steerable/agent-harness": "0.8.0",
+    "@steerable/agent-protocol": "0.8.0",
+    "@steerable/pack-sdk": "0.8.0"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",