@steerable/agent-shell-web 0.6.15

package/src/components/settings/preset-choice-model.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, it } from 'vitest';
+import {
+  choiceFromPresetMode,
+  descriptorLabel,
+  overrideFromDescriptor,
+  overridesEqual,
+  presetModeFromChoice,
+  summarizePreset,
+} from './preset-choice-model';
+import type { ProviderPresetDescriptor } from '@/lib/local-api';
+
+// 与框架 llm/presets.py `describe_provider_presets` 同形的注册表行夹具。
+const ROWS: ProviderPresetDescriptor[] = [
+  {
+    host: 'api.deepseek.com',
+    modelPrefix: 'deepseek',
+    temperature: 0.0,
+    topP: null,
+    maxTokens: null,
+    reasoningEffort: null,
+    extraBody: null,
+  },
+  {
+    host: null,
+    modelPrefix: 'qwen3',
+    temperature: 0.6,
+    topP: 0.95,
+    maxTokens: null,
+    reasoningEffort: null,
+    extraBody: { top_k: 20 },
+  },
+];
+
+describe('overrideFromDescriptor', () => {
+  it('drops null fields so they are not sent on the wire', () => {
+    expect(overrideFromDescriptor(ROWS[0])).toEqual({ temperature: 0.0 });
+    expect(overrideFromDescriptor(ROWS[1])).toEqual({
+      temperature: 0.6,
+      topP: 0.95,
+      extraBody: { top_k: 20 },
+    });
+  });
+});
+
+describe('descriptorLabel', () => {
+  it('joins host and model prefix, tolerating single-key rows', () => {
+    expect(descriptorLabel(ROWS[0])).toBe('api.deepseek.com + deepseek*');
+    expect(descriptorLabel(ROWS[1])).toBe('qwen3*');
+  });
+});
+
+describe('summarizePreset', () => {
+  it('renders a one-line parameter summary', () => {
+    expect(summarizePreset(overrideFromDescriptor(ROWS[1]))).toBe(
+      'temperature 0.6 · top_p 0.95 · top_k 20',
+    );
+  });
+
+  it('describes the empty preset honestly (Moonshot case)', () => {
+    expect(summarizePreset(null)).toBe('不下发额外采样参数');
+    expect(summarizePreset({})).toContain('不带采样字段');
+  });
+});
+
+describe('presetModeFromChoice / choiceFromPresetMode', () => {
+  it('round-trips the three modes', () => {
+    expect(presetModeFromChoice(undefined)).toBe('auto');
+    expect(presetModeFromChoice({ enabled: true })).toBe('auto');
+    expect(presetModeFromChoice({ enabled: false })).toBe('off');
+    expect(presetModeFromChoice({ override: { temperature: 0.6 } })).toBe('pinned');
+
+    expect(choiceFromPresetMode('auto', -1, ROWS)).toBeUndefined();
+    expect(choiceFromPresetMode('off', -1, ROWS)).toEqual({ enabled: false });
+    expect(choiceFromPresetMode('pinned', 1, ROWS)).toEqual({
+      override: { temperature: 0.6, topP: 0.95, extraBody: { top_k: 20 } },
+    });
+  });
+
+  it('keeps a saved custom override when the registry is unavailable', () => {
+    const existing = { override: { temperature: 0.42 } };
+    expect(choiceFromPresetMode('pinned', -1, [], existing)).toEqual(existing);
+    // 无注册表也无已保存覆盖：钉死无从谈起，回落为不持久化（自动）。
+    expect(choiceFromPresetMode('pinned', -1, [])).toBeUndefined();
+  });
+});
+
+describe('overridesEqual', () => {
+  it('matches a saved override back to its registry row', () => {
+    expect(overridesEqual(overrideFromDescriptor(ROWS[1]), {
+      temperature: 0.6,
+      topP: 0.95,
+      extraBody: { top_k: 20 },
+    })).toBe(true);
+    expect(overridesEqual(overrideFromDescriptor(ROWS[0]), { temperature: 0.1 })).toBe(false);
+  });
+});

package/src/components/settings/preset-choice-model.ts

@@ -0,0 +1,75 @@
+/**
+ * 厂商参数预制（框架 llm.presets）设置区的纯表单模型，从
+ * LocalLlmSettingsModal 抽出以便单测。注册表与匹配规则都在框架侧
+ * （presets.describe / presets.resolve RPC），这里只做表单态与 wire
+ * 载荷之间的转换，不硬编码任何厂商参数。
+ */
+
+import type {
+  ProviderPresetDescriptor,
+  ProviderPresetOverride,
+  ProviderPresetsChoice,
+} from '@/lib/local-api';
+
+/** 三态：自动（框架按 baseUrl+model 匹配）/ 关闭 / 钉死一条注册表行。 */
+export type PresetMode = 'auto' | 'off' | 'pinned';
+
+/** 注册表行 → 钉死时随流下发的 override 载荷（null 字段不下发）。 */
+export function overrideFromDescriptor(d: ProviderPresetDescriptor): ProviderPresetOverride {
+  return {
+    ...(d.temperature != null && { temperature: d.temperature }),
+    ...(d.topP != null && { topP: d.topP }),
+    ...(d.maxTokens != null && { maxTokens: d.maxTokens }),
+    ...(d.reasoningEffort != null && { reasoningEffort: d.reasoningEffort }),
+    ...(d.extraBody != null && { extraBody: d.extraBody }),
+  };
+}
+
+/** 选择器选项标签：`host + 前缀*`，缺省键名退化为「未命名」。 */
+export function descriptorLabel(d: ProviderPresetDescriptor): string {
+  const parts = [d.host, d.modelPrefix ? `${d.modelPrefix}*` : null].filter(Boolean);
+  return parts.join(' + ') || '（未命名预制）';
+}
+
+/** 预制参数的一行摘要，用于生效预览。 */
+export function summarizePreset(p: ProviderPresetOverride | null): string {
+  if (!p) return '不下发额外采样参数';
+  const parts: string[] = [];
+  if (p.temperature != null) parts.push(`temperature ${p.temperature}`);
+  if (p.topP != null) parts.push(`top_p ${p.topP}`);
+  if (p.maxTokens != null) parts.push(`max_tokens ${p.maxTokens}`);
+  if (p.reasoningEffort) parts.push(`reasoning_effort ${p.reasoningEffort}`);
+  if (p.extraBody) {
+    for (const [k, v] of Object.entries(p.extraBody)) parts.push(`${k} ${JSON.stringify(v)}`);
+  }
+  return parts.length > 0 ? parts.join(' · ') : '不下发额外采样参数（该厂商最优请求即不带采样字段）';
+}
+
+export function overridesEqual(a: ProviderPresetOverride, b: ProviderPresetOverride): boolean {
+  return (
+    JSON.stringify({ ...a, extraBody: a.extraBody ?? null }) ===
+    JSON.stringify({ ...b, extraBody: b.extraBody ?? null })
+  );
+}
+
+/** 已持久化的选择 → 表单三态。 */
+export function presetModeFromChoice(choice: ProviderPresetsChoice | undefined): PresetMode {
+  if (!choice) return 'auto';
+  if (choice.override) return 'pinned';
+  return choice.enabled === false ? 'off' : 'auto';
+}
+
+/** 表单三态 → 待持久化的选择（自动 = 不持久化，框架自动匹配兜底）。 */
+export function choiceFromPresetMode(
+  mode: PresetMode,
+  pinnedIdx: number,
+  list: ProviderPresetDescriptor[],
+  existing?: ProviderPresetsChoice,
+): ProviderPresetsChoice | undefined {
+  if (mode === 'auto') return undefined;
+  if (mode === 'off') return { enabled: false };
+  const pinned = pinnedIdx >= 0 ? list[pinnedIdx] : undefined;
+  if (pinned) return { override: overrideFromDescriptor(pinned) };
+  // 钉死但注册表不可用（sidecar 未就绪）：保留已保存的自定义覆盖。
+  return existing?.override ? { override: existing.override } : undefined;
+}

package/src/fixtures/browser-dev-data.json

@@ -0,0 +1,315 @@
+{
+  "version": 1,
+  "exportedAt": null,
+  "source": "hand-curated neutral fixtures",
+  "agents": [
+    {
+      "id": "local-assistant",
+      "slug": "local-assistant",
+      "name": "电脑操作员",
+      "icon": "Cpu",
+      "color": "#4f46e5",
+      "description": "默认本地助手，可调用 shell、文件与 MCP 工具。",
+      "rolePrompt": "你是本地离线助手，回答时清晰、可执行。",
+      "forbiddenPrompt": null,
+      "skillIds": [],
+      "toolPolicy": {
+        "mode": "all",
+        "tools": []
+      },
+      "allowExternalSkills": true,
+      "isBuiltin": true,
+      "isArchived": false,
+      "sortOrder": 0,
+      "createdAt": "2026-06-22T03:32:30.256Z",
+      "updatedAt": "2026-06-22T03:32:30.256Z"
+    },
+    {
+      "id": "data-analyst",
+      "slug": "data-analyst",
+      "name": "数据分析助手",
+      "icon": "Activity",
+      "color": "#0ea5e9",
+      "description": "处理本地 CSV 与日志文件：清洗、统计、出图与汇总报告。",
+      "rolePrompt": "你是 **数据分析助手**，专注本地数据文件的清洗、统计与可视化。\n工作语言：中文。回答简洁、结论先行。\n\n工作纪律：\n1) 先探查文件结构再动手；\n2) 每一步都说明做了什么；\n3) 结果用表格或要点呈现。",
+      "forbiddenPrompt": null,
+      "skillIds": [],
+      "toolPolicy": {
+        "mode": "all",
+        "tools": []
+      },
+      "allowExternalSkills": true,
+      "isBuiltin": true,
+      "isArchived": false,
+      "sortOrder": 1,
+      "createdAt": "2026-06-22T03:32:30.256Z",
+      "updatedAt": "2026-06-22T03:32:30.256Z"
+    },
+    {
+      "id": "all-round-assistant",
+      "slug": "all-round-assistant",
+      "name": "智能助手",
+      "icon": "🔮",
+      "color": "#a855f7",
+      "description": "全能智能体，自动加载全部已安装本地技能和工具，无需限定条件。",
+      "rolePrompt": "你是 **智能助手**，一个具备高权限且集成了全部本地技能（Skills）的行动体。\n你具备完整的本地命令执行（local_exec_shell）、文件读写与数据分析能力。\n你的系统提示词中已经无条件加载了所有已安装的本地技能与工具。\n请根据用户的需求，直接、高效地调用最合适的本地工具或执行脚本来解决任务。",
+      "forbiddenPrompt": null,
+      "skillIds": [],
+      "toolPolicy": {
+        "mode": "all",
+        "tools": []
+      },
+      "allowExternalSkills": true,
+      "isBuiltin": true,
+      "isArchived": false,
+      "sortOrder": 2,
+      "createdAt": "2026-06-22T03:32:30.256Z",
+      "updatedAt": "2026-06-22T03:32:30.256Z"
+    }
+  ],
+  "chats": [
+    {
+      "id": "8286e3c8-2d83-409e-930a-3e99b2004d41",
+      "projectId": null,
+      "userId": "local",
+      "title": "你好",
+      "agentId": "local-assistant",
+      "createdAt": "2026-07-01T10:05:58.604Z",
+      "updatedAt": "2026-07-01T10:06:06.736Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    },
+    {
+      "id": "8b13a92e-4b3e-4bac-885f-879ddd9e4835",
+      "projectId": null,
+      "userId": "local",
+      "title": "启用 csv-data-tools 技能",
+      "agentId": "all-round-assistant",
+      "createdAt": "2026-06-22T04:30:54.662Z",
+      "updatedAt": "2026-06-22T04:32:12.657Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    },
+    {
+      "id": "d536659c-6492-424d-97e8-2f701a9ce5d8",
+      "projectId": null,
+      "userId": "local",
+      "title": "新对话",
+      "agentId": "all-round-assistant",
+      "createdAt": "2026-06-22T04:19:52.607Z",
+      "updatedAt": "2026-06-22T04:20:00.151Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    },
+    {
+      "id": "4845b527-c9c9-467c-9d72-5fc5f8763aa5",
+      "projectId": null,
+      "userId": "local",
+      "title": "新对话",
+      "agentId": "all-round-assistant",
+      "createdAt": "2026-06-22T04:12:17.151Z",
+      "updatedAt": "2026-06-22T04:12:22.038Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    },
+    {
+      "id": "405f5964-f01c-4ece-9c8f-02a73d539469",
+      "projectId": null,
+      "userId": "local",
+      "title": "启用 csv-data-tools 技能",
+      "agentId": "all-round-assistant",
+      "createdAt": "2026-06-22T04:06:21.745Z",
+      "updatedAt": "2026-06-22T04:11:42.782Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    },
+    {
+      "id": "19a1d8e7-7e9c-425b-8509-0fe9dd292971",
+      "projectId": null,
+      "userId": "local",
+      "title": "启用 csv-data-tools 技能",
+      "agentId": "all-round-assistant",
+      "createdAt": "2026-06-22T04:01:21.158Z",
+      "updatedAt": "2026-06-22T04:05:08.801Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    },
+    {
+      "id": "492c1a80-85b2-486a-b365-3d668c9ad7e6",
+      "projectId": null,
+      "userId": "local",
+      "title": "新对话",
+      "agentId": "all-round-assistant",
+      "createdAt": "2026-06-22T03:44:47.381Z",
+      "updatedAt": "2026-06-22T03:44:54.479Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    },
+    {
+      "id": "4e997d62-20ef-4937-a866-27778dee3a17",
+      "projectId": null,
+      "userId": "local",
+      "title": "hi",
+      "agentId": "all-round-assistant",
+      "createdAt": "2026-06-22T03:34:36.892Z",
+      "updatedAt": "2026-06-22T03:37:37.601Z",
+      "isPinned": false,
+      "systemPrompt": null,
+      "pinnedRefs": null
+    }
+  ],
+  "messagesByChatId": {
+    "8286e3c8-2d83-409e-930a-3e99b2004d41": [
+      {
+        "id": "ea36a5de-e2e0-428b-b882-f5e67ca326b0",
+        "chatId": "8286e3c8-2d83-409e-930a-3e99b2004d41",
+        "role": "assistant",
+        "content": "你好！我是**本地智能助手**，运行在你的本地机器上。\n\n我可以帮你做这些事情：\n\n**💻 本地终端操作**\n- 执行 shell 命令、读写文件\n- 搜索代码库、批量替换\n\n**📊 数据处理**\n- 清洗 CSV / 日志文件\n- 生成统计汇总\n\n直接输入需求即可开始。",
+        "createdAt": "2026-07-01T10:06:06.733Z",
+        "messageMetadata": "{\"traceId\":\"tr_269aa1b0f5244962b3279304d6f26323\",\"completionStatus\":\"completed\",\"trace\":{\"traceId\":\"tr_269aa1b0f5244962b3279304d6f26323\",\"sessionId\":\"8286e3c8-2d83-409e-930a-3e99b2004d41\",\"chatId\":\"8286e3c8-2d83-409e-930a-3e99b2004d41\",\"startedAtMs\":1782900364396,\"eventCount\":3,\"spanCount\":1,\"events\":[{\"name\":\"stream_start\",\"timestampMs\":1782900364396,\"data\":{\"path\":\"/api/v2/chats/8286e3c8-2d83-409e-930a-3e99b2004d41/run\",\"method\":\"POST\"}},{\"name\":\"completion_decision\",\"timestampMs\":1782900366733,\"data\":{\"status\":\"completed\",\"reason\":\"assistant produced final response with no pending tools\",\"confidence\":0.85,\"evidence\":[{\"textLength\":218,\"toolCalls\":[],\"toolErrorCount\":0}]}},{\"name\":\"stream_complete\",\"timestampMs\":1782900366733,\"data\":{\"usedTool\":false,\"completionStatus\":\"completed\",\"assistantLength\":218}}],\"spans\":[{\"name\":\"llm_call\",\"stepId\":\"step_1\",\"startMs\":1782900364396,\"endMs\":1782900366733,\"status\":\"ok\",\"data\":{\"turn\":0,\"model\":\"default\",\"tokensUsed\":{\"prompt\":8596,\"completion\":130,\"total\":8726},\"toolCalls\":0},\"durationMs\":2337}]},\"executedActions\":[]}"
+      },
+      {
+        "id": "ab1387a6-5c43-4d4b-986d-073d98b3f5e2",
+        "chatId": "8286e3c8-2d83-409e-930a-3e99b2004d41",
+        "role": "user",
+        "content": "你好",
+        "createdAt": "2026-07-01T10:06:04.392Z",
+        "messageMetadata": null
+      }
+    ],
+    "8b13a92e-4b3e-4bac-885f-879ddd9e4835": [
+      {
+        "id": "6599eb84-515c-4f58-bec8-0f37fcfbb234",
+        "chatId": "8b13a92e-4b3e-4bac-885f-879ddd9e4835",
+        "role": "assistant",
+        "content": "好的，我先查看 `csv-data-tools` 技能的可用模块。\n\n**`csv-data-tools`** 技能已就绪。以下是它的能力概览：\n\n---\n\n## 📦 csv-data-tools\n\n- `csv_stats` — 列级统计（行数、缺失、分布）\n- `csv_filter` — 条件过滤与导出\n- `csv_plot` — 快速出图\n\n告诉我文件路径即可开始。",
+        "createdAt": "2026-06-22T04:32:11.576Z",
+        "messageMetadata": null
+      },
+      {
+        "id": "a6d5f510-e26c-4fd5-878b-74ea98a977f9",
+        "chatId": "8b13a92e-4b3e-4bac-885f-879ddd9e4835",
+        "role": "user",
+        "content": "/csv-data-tools",
+        "createdAt": "2026-06-22T04:31:01.151Z",
+        "messageMetadata": null
+      }
+    ],
+    "d536659c-6492-424d-97e8-2f701a9ce5d8": [
+      {
+        "id": "9b04bf0c-2d90-4e27-b891-9871207d177e",
+        "chatId": "d536659c-6492-424d-97e8-2f701a9ce5d8",
+        "role": "user",
+        "content": "/csv-data-tools",
+        "createdAt": "2026-06-22T04:20:00.151Z",
+        "messageMetadata": null
+      }
+    ],
+    "4845b527-c9c9-467c-9d72-5fc5f8763aa5": [
+      {
+        "id": "abb7c501-67d1-4ca4-8d94-708bbd55646f",
+        "chatId": "4845b527-c9c9-467c-9d72-5fc5f8763aa5",
+        "role": "user",
+        "content": "/csv-data-tools",
+        "createdAt": "2026-06-22T04:12:22.038Z",
+        "messageMetadata": null
+      }
+    ],
+    "405f5964-f01c-4ece-9c8f-02a73d539469": [
+      {
+        "id": "c8dc9e96-642b-4232-8c3c-c8abc32a615c",
+        "chatId": "405f5964-f01c-4ece-9c8f-02a73d539469",
+        "role": "assistant",
+        "content": "我来查看当前可用的 MCP 工具，找到 `csv-data-tools` 的相关信息。\n\n看起来 `csv-data-tools` 没有作为独立的 MCP 服务器注册。换个方式，先扫描本地脚本和可执行工具。\n\n结论：该技能当前未安装，可通过技能设置页导入。",
+        "createdAt": "2026-06-22T04:11:42.077Z",
+        "messageMetadata": null
+      },
+      {
+        "id": "d4c21f8f-b4ab-4dc0-bc48-611bc66847a4",
+        "chatId": "405f5964-f01c-4ece-9c8f-02a73d539469",
+        "role": "user",
+        "content": "/csv-data-tools",
+        "createdAt": "2026-06-22T04:06:27.797Z",
+        "messageMetadata": null
+      }
+    ],
+    "19a1d8e7-7e9c-425b-8509-0fe9dd292971": [
+      {
+        "id": "cfb0f03c-7faa-4594-b29f-f4c11fb09105",
+        "chatId": "19a1d8e7-7e9c-425b-8509-0fe9dd292971",
+        "role": "assistant",
+        "content": "本地模型调用失败：无法连接 OpenAI 兼容网关 (https://api.deepseek.com)，请检查 baseUrl / 网络。原始错误: fetch failed",
+        "createdAt": "2026-06-22T04:05:06.751Z",
+        "messageMetadata": null
+      },
+      {
+        "id": "2d7469fc-1a58-488b-beb8-c372e54e3def",
+        "chatId": "19a1d8e7-7e9c-425b-8509-0fe9dd292971",
+        "role": "user",
+        "content": "/csv-data-tools",
+        "createdAt": "2026-06-22T04:01:55.866Z",
+        "messageMetadata": null
+      }
+    ],
+    "492c1a80-85b2-486a-b365-3d668c9ad7e6": [
+      {
+        "id": "6ca59f0c-6df7-4747-9c96-80812d459a96",
+        "chatId": "492c1a80-85b2-486a-b365-3d668c9ad7e6",
+        "role": "user",
+        "content": "/csv-data-tools",
+        "createdAt": "2026-06-22T03:44:54.479Z",
+        "messageMetadata": null
+      }
+    ],
+    "4e997d62-20ef-4937-a866-27778dee3a17": [
+      {
+        "id": "c5d6136b-eaa4-4cc7-878b-450099b7d226",
+        "chatId": "4e997d62-20ef-4937-a866-27778dee3a17",
+        "role": "assistant",
+        "content": "我来查看当前可用的 MCP 工具，找到 `csv-data-tools` 的相关信息。\n\n看起来 `csv-data-tools` 没有作为独立的 MCP 服务器注册。换个方式，先扫描本地脚本和可执行工具。\n\n结论：该技能当前未安装，可通过技能设置页导入。",
+        "createdAt": "2026-06-22T03:37:37.601Z",
+        "messageMetadata": null
+      },
+      {
+        "id": "68f12c35-7de5-49f3-af14-ca5deae13dee",
+        "chatId": "4e997d62-20ef-4937-a866-27778dee3a17",
+        "role": "user",
+        "content": "/csv-data-tools",
+        "createdAt": "2026-06-22T03:36:49.529Z",
+        "messageMetadata": null
+      },
+      {
+        "id": "fa89030e-5db1-4d04-9320-e796baeb89e2",
+        "chatId": "4e997d62-20ef-4937-a866-27778dee3a17",
+        "role": "assistant",
+        "content": "你好！我是**本地智能助手**，运行在你的本地机器上。\n\n我可以帮你做这些事情：\n\n**💻 本地终端操作**\n- 执行 shell 命令、读写文件\n- 搜索代码库、批量替换\n\n**📊 数据处理**\n- 清洗 CSV / 日志文件\n- 生成统计汇总\n\n直接输入需求即可开始。",
+        "createdAt": "2026-06-22T03:34:48.778Z",
+        "messageMetadata": "{\"traceId\":\"tr_f53c2142bbd347b5888f9d50c5444478\",\"completionStatus\":\"completed\",\"trace\":{\"traceId\":\"tr_f53c2142bbd347b5888f9d50c5444478\",\"sessionId\":\"4e997d62-20ef-4937-a866-27778dee3a17\",\"chatId\":\"4e997d62-20ef-4937-a866-27778dee3a17\",\"startedAtMs\":1782099286405,\"eventCount\":3,\"spanCount\":1,\"events\":[{\"name\":\"stream_start\",\"timestampMs\":1782099286405,\"data\":{\"path\":\"/api/v2/chats/4e997d62-20ef-4937-a866-27778dee3a17/run\",\"method\":\"POST\"}},{\"name\":\"completion_decision\",\"timestampMs\":1782099288778,\"data\":{\"status\":\"completed\",\"reason\":\"assistant produced final response with no pending tools\",\"confidence\":0.85,\"evidence\":[{\"textLength\":224,\"toolCalls\":[],\"toolErrorCount\":0}]}},{\"name\":\"stream_complete\",\"timestampMs\":1782099288778,\"data\":{\"usedTool\":false,\"completionStatus\":\"completed\",\"assistantLength\":224}}],\"spans\":[{\"name\":\"llm_call\",\"stepId\":\"step_1\",\"startMs\":1782099286405,\"endMs\":1782099288777,\"status\":\"ok\",\"data\":{\"turn\":0,\"model\":\"default\",\"tokensUsed\":{\"prompt\":2234,\"completion\":130,\"total\":2364},\"toolCalls\":0},\"durationMs\":2372}]},\"executedActions\":[]}"
+      },
+      {
+        "id": "82c95340-1d74-49fe-abe7-2184aeab9f8c",
+        "chatId": "4e997d62-20ef-4937-a866-27778dee3a17",
+        "role": "user",
+        "content": "hi",
+        "createdAt": "2026-06-22T03:34:46.403Z",
+        "messageMetadata": null
+      }
+    ]
+  },
+  "llmSettings": {
+    "provider": "openai-compat",
+    "model": "deepseek-chat",
+    "baseUrl": "https://api.deepseek.com",
+    "apiKey": "",
+    "temperature": 0.3,
+    "systemPrompt": "你是一款本地行动助手，优先给出可执行建议并在需要时调用本地工具。"
+  },
+  "skills": []
+}

package/src/hooks/useChatsAndAgents.ts

@@ -0,0 +1,182 @@
+/**
+ * `useChatsAndAgents` — sidebar state (paginated chats + agent catalog + the
+ * "agent picked for next new chat" selection) for the Agent shell.
+ *
+ * Wave 1 of the steerable-framework refactor moved the generic pagination /
+ * agent-selection / title-patching machinery into `@steerable/agent-ui/state`
+ * as `useChatList<TChat, TAgent>`. This file is now an Electron-flavoured
+ * adapter:
+ *   - It wires the framework hook to the local-backend transport
+ *     (`@/lib/local-api`).
+ *   - It gates everything behind `isElectron()` so a renderer running in a
+ *     plain browser doesn't fire requests.
+ *   - It keeps the legacy `UseChatsAndAgentsResult` shape so callers
+ *     (`AgentLayout`, `useChatsAndAgents()` consumers) don't change.
+ *
+ * Pagination contract (mirrors `deeppath/apps/web` `useChatUI`):
+ *   - First mount loads page 1 (50 items).
+ *   - AgentSidebar scrolls within its own container and calls `loadMoreChats`
+ *     when the user nears the bottom. `isLoadingMoreChats` gates re-entry.
+ *   - After a `refreshChats` (e.g. post create/delete), we reset to page 1
+ *     and drop any already-loaded pages — keeping the list consistent is
+ *     simpler than trying to splice individual pages.
+ */
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import {
+  useChatList,
+  type ChatListTransport,
+} from '@steerable/agent-ui/state';
+import {
+  createChat as apiCreateChat,
+  deleteChat as apiDeleteChat,
+  listChatAgents,
+  listChats,
+  type LocalChat,
+  type LocalChatAgent,
+} from '@/lib/local-api';
+import { isElectron } from '@/lib/electron-bridge';
+import { pickDefaultAgentId } from '@/brand';
+
+const CHAT_PAGE_SIZE = 50;
+
+export interface UseChatsAndAgentsResult {
+  chats: LocalChat[];
+  agents: LocalChatAgent[];
+  isLoading: boolean;
+  error: string | null;
+  selectedAgentId: string | null;
+  setSelectedAgentId: (id: string | null) => void;
+  refreshChats: () => Promise<void>;
+  refreshAgents: () => Promise<void>;
+  createChat: (input?: { agentId?: string; projectId?: string }) => Promise<string | null>;
+  deleteChat: (chatId: string) => Promise<boolean>;
+  /**
+   * 就地把某个 chat 的 title 改掉（不打后端、不重新拉列表）。
+   * 用于 SSE `chat_title_updated` 事件——后端已经写好库了，前端只要
+   * 同步内存里的 sidebar 视图就行，免得 refreshChats() 把翻页状态打回 page 1。
+   * 找不到 id 时静默忽略。
+   */
+  patchChatTitle: (chatId: string, title: string) => void;
+  /** True while a `loadMoreChats` call is in flight. */
+  isLoadingMoreChats: boolean;
+  /** True iff the last list-chats response reported more pages available. */
+  hasMoreChats: boolean;
+  loadMoreChats: () => Promise<void>;
+}
+
+export function useChatsAndAgents(): UseChatsAndAgentsResult {
+  const isElectronRef = useRef(isElectron());
+
+  const transport = useMemo<ChatListTransport<LocalChat, LocalChatAgent>>(
+    () => ({
+      listChats: async ({ page, pageSize }) => {
+        if (!isElectronRef.current) return { chats: [], hasMore: false };
+        const data = await listChats({ page, limit: pageSize });
+        return {
+          chats: data.chats,
+          hasMore: Boolean(data.pagination?.hasMore),
+        };
+      },
+      listAgents: async () => {
+        if (!isElectronRef.current) return [];
+        const data = await listChatAgents(false);
+        return data.agents;
+      },
+      createChat: async ({ agentId, projectId }) => {
+        if (!isElectronRef.current) {
+          throw new Error('not in electron');
+        }
+        const res = await apiCreateChat({
+          ...(agentId ? { agentId } : {}),
+          ...(projectId ? { projectId } : {}),
+        });
+        return res.chatId;
+      },
+      deleteChat: async (chatId) => {
+        if (!isElectronRef.current) return false;
+        await apiDeleteChat(chatId);
+        return true;
+      },
+      getChatId: (c) => c.id,
+      setChatTitle: (c, title) => (c.title === title ? c : { ...c, title }),
+      getAgentId: (a) => a.id,
+    }),
+    [],
+  );
+
+  const list = useChatList<LocalChat, LocalChatAgent>({
+    transport,
+    pageSize: CHAT_PAGE_SIZE,
+    // The renderer mounts before electron decides whether the bridge is live;
+    // skip the auto-fetch and trigger it manually after the SSR no-op check.
+    skipInitialLoad: !isElectronRef.current,
+  });
+
+  // Default-select this flavor's builtin expert once the catalog loads.
+  // 场景产品默认包的主打专家；无包产品默认 shell 内置智能体。
+  useEffect(() => {
+    if (list.agents.length === 0) return;
+    const current = list.selectedAgentId;
+    if (current && list.agents.some((a) => a.id === current)) return;
+    const next = pickDefaultAgentId(list.agents);
+    if (next) list.setSelectedAgentId(next);
+    // We only want this to fire when the catalog identity changes.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [list.agents]);
+
+  // Translate the framework's `Error | null` into the legacy `string | null`.
+  const errorStr = useMemo(
+    () => (list.error ? list.error.message : null),
+    [list.error],
+  );
+  // Some app-side flows (createChat/deleteChat below) also need to surface a
+  // string error without round-tripping through the framework hook. We keep a
+  // local override that takes precedence.
+  const [localError, setLocalError] = useState<string | null>(null);
+  const mergedError = localError ?? errorStr;
+
+  const createChat = useCallback(
+    async (input?: { agentId?: string; projectId?: string }) => {
+      try {
+        const id = await list.createChat(input);
+        return id;
+      } catch (err) {
+        setLocalError(err instanceof Error ? err.message : String(err));
+        return null;
+      }
+    },
+    [list],
+  );
+
+  const deleteChat = useCallback(
+    async (chatId: string) => {
+      try {
+        const ok = await list.deleteChat(chatId);
+        if (ok) await list.refreshChats();
+        return ok;
+      } catch (err) {
+        setLocalError(err instanceof Error ? err.message : String(err));
+        return false;
+      }
+    },
+    [list],
+  );
+
+  return {
+    chats: list.chats,
+    agents: list.agents,
+    isLoading: list.isLoading,
+    error: mergedError,
+    selectedAgentId: list.selectedAgentId,
+    setSelectedAgentId: list.setSelectedAgentId,
+    refreshChats: list.refreshChats,
+    refreshAgents: list.refreshAgents,
+    createChat,
+    deleteChat,
+    patchChatTitle: list.patchChatTitle,
+    isLoadingMoreChats: list.isLoadingMoreChats,
+    hasMoreChats: list.hasMoreChats,
+    loadMoreChats: list.loadMoreChats,
+  };
+}