@steerable/agent-shell-web 0.6.55 → 0.6.57

package/src/lib/host-bridge.ts

@@ -1,7 +1,379 @@
 /**
- * Canonical renderer host contract.
+ * Host-neutral bridge used by the renderer in desktop and browser modes.
  *
- * The legacy `electron-bridge` module remains available so existing product
- * sources can migrate without a synchronized breaking release.
+ * Implementations are `tauri-bridge.ts` (desktop) and `http-bridge.ts`
+ * (browser server); both must satisfy {@link HostBridge}.
+ * Callers use `window.steerableHost` and `getHostBridge()`.
  */
-export * from './electron-bridge';
+
+import type { SSEEvent } from '@steerable/agent-protocol';
+import { getHttpBridge } from './http-bridge';
+import { getTauriBridge } from './tauri-bridge';
+
+export type LocalBackendRequestInput = {
+  method: string;
+  path: string;
+  body?: unknown;
+};
+
+export type LocalBackendStreamEvent =
+  | { type: 'data'; chunk: string; parsed?: SSEEvent }
+  | { type: 'end'; status: number }
+  | { type: 'error'; error: string };
+
+/**
+ * W4-1: mirror of the approval algebra's decision variants
+ * (`steerable_agent_runtime.approval.APPROVAL_KINDS` minus `timed_out`,
+ * which the sidecar synthesizes itself on timeout).
+ */
+export type ApprovalDecisionKind =
+  | 'allow_once'
+  | 'allow_for_session'
+  | 'allow_always'
+  | 'deny_once'
+  | 'deny_for_session'
+  | 'deny_always'
+  | 'abort';
+
+export interface ApprovalPromptRequest {
+  requestId: string;
+  toolName: string;
+  arguments: Record<string, unknown>;
+  mode: string;
+  category: string;
+  round: number;
+  /** 发起审批的对话。缺省时卡片不绑定会话（旧请求）。 */
+  chatId?: string;
+}
+
+/**
+ * W8: mirror of the sidecar's `ask_user.request` reverse-call payload
+ * (`HostAskUserHandler` in steerable_sidecar.host_tools). `questions`
+ * entries match `AskUserQuestionsPayload['questions'][number]` from
+ * `@steerable/agent-protocol`; kept structurally typed here so the
+ * renderer's compile graph stays free of main-process imports.
+ */
+export interface AskUserPromptRequest {
+  requestId: string;
+  intro: string;
+  questions: Array<Record<string, unknown>>;
+  /** 发起提问的对话。缺省时卡片不绑定会话（旧请求）。 */
+  chatId?: string;
+}
+
+/**
+ * Mirror of `TerminalSession` / `TerminalSpawnOptions` in
+ * `src/terminal-manager.ts`. Kept inline (rather than cross-imported)
+ * for the same reason as the rest of this file — we don't want the
+ * renderer's compile graph to pull in main-process modules.
+ */
+export interface TerminalSession {
+  id: string;
+  shell: string;
+  pid: number;
+  cwd: string;
+  cols: number;
+  rows: number;
+}
+
+export interface TerminalSpawnOptions {
+  shell?: string;
+  cwd?: string;
+  env?: Record<string, string>;
+  cols?: number;
+  rows?: number;
+}
+
+export type AppReleasePhase =
+  | 'disabled'
+  | 'idle'
+  | 'checking'
+  | 'downloading'
+  | 'ready'
+  | 'installing'
+  | 'error';
+
+/**
+ * 桌面版本与更新。`version` 是当前安装版本，`availableVersion` 是待安装版本。
+ * 与主进程 `AppReleaseSnapshot` 对齐。
+ */
+export interface AppReleaseSnapshot {
+  version: string;
+  enabled: boolean;
+  phase: AppReleasePhase;
+  availableVersion?: string;
+  percent?: number;
+  message?: string;
+}
+
+export type PythonRunnerPhase =
+  | 'idle'
+  | 'downloading'
+  | 'verifying'
+  | 'extracting'
+  | 'ready'
+  | 'error';
+
+export interface PythonRunnerSnapshot {
+  supported: boolean;
+  source: 'default' | 'url' | 'local';
+  phase: PythonRunnerPhase;
+  percent?: number;
+  downloadedBytes?: number;
+  totalBytes?: number;
+  message?: string;
+  defaultUrl?: string;
+  configuredUrl?: string;
+  activeRunner?: string;
+  configuredRunner?: string;
+  restartRequired: boolean;
+}
+
+export interface HostBridge {
+  runtime: 'local';
+  platform: NodeJS.Platform;
+  local?: {
+    selectDirectory: (options?: {
+      title?: string;
+    }) => Promise<{ canceled: boolean; filePaths: string[] }>;
+    saveTextFile?: (options: {
+      title?: string;
+      defaultPath?: string;
+      content: string;
+    }) => Promise<{ canceled: boolean; filePath?: string }>;
+    /** 截取窗口（或指定 DIP 区域）并写入系统剪贴板。 */
+    captureScreenshot: (rect?: {
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+    }) => Promise<
+      | { success: true; width: number; height: number }
+      | { success: false; error: string }
+    >;
+  };
+  localBackend: {
+    request: <T>(input: LocalBackendRequestInput) => Promise<T>;
+    startStream: (
+      input: LocalBackendRequestInput,
+      onEvent: (payload: LocalBackendStreamEvent) => void,
+    ) => Promise<string | null>;
+    cancelStream: (streamId: string) => void;
+    /** 轮中转向：注入一条用户消息到运行中的 CoreLoop 回合；false = 无可转向回合。 */
+    steerChat?: (chatId: string, content: string) => Promise<boolean>;
+  };
+  /** 会话附件：把源文件路径 / base64 字节拷贝进会话空间（`attachments:save`）。 */
+  attachments?: {
+    save: (input: {
+      chatId: string;
+      files: Array<{ path?: string; name?: string; data?: string }>;
+    }) => Promise<{
+      files: Array<{ name: string; path: string; size: number; error?: string }>;
+    }>;
+  };
+  /**
+   * Desktop menu — `Cmd+N` fires `menu:new-chat`. Renderer subscribes via
+   * `onMenuNewChat(cb)` and must call `offMenuNewChat()` on unmount
+   * so a remounted AgentSidebar does not keep the previous callback.
+   */
+  /** 把当前界面语言告诉桌面壳，以便重建应用菜单。浏览器预览里没有。 */
+  setLocale?: (locale: string) => void;
+  onMenuNewChat?: (callback: () => void) => void;
+  offMenuNewChat?: () => void;
+  /**
+   * App menu IPC — `Cmd+T` / 视图 → 打开终端 fires `menu:open-terminal`.
+   * The terminal is a toggleable panel inside AgentLayout (not a separate
+   * window, not a route), so the renderer just flips layout state. Same
+   * subscribe/off pairing as `onMenuNewChat`.
+   */
+  onMenuOpenTerminal?: (callback: () => void) => void;
+  offMenuOpenTerminal?: () => void;
+  /**
+   * App menu IPC — `Cmd+V` / 编辑 → 粘贴 fires `menu:paste`.
+   * WKWebView does not expose that pasteboard to the page, so the renderer
+   * reads it through `readClipboard`.
+   */
+  onMenuPaste?: (callback: () => void) => void;
+  offMenuPaste?: () => void;
+  /**
+   * OS pasteboard. `files` are copied paths or a screenshot PNG.
+   * Text is empty when the pasteboard holds files, so the path is not
+   * inserted into the composer as well.
+   */
+  readClipboard?: () => Promise<{
+    text: string;
+    files: Array<{
+      name: string;
+      path?: string;
+      dataBase64?: string;
+      mime?: string;
+    }>;
+  }>;
+  /** Plain text from the OS pasteboard. Empty when the clipboard has no text. */
+  readClipboardText?: () => Promise<string>;
+  /**
+   * 异步 AI 标题就绪通知。Backend 在每条 chat 首条助手回复完成后 fire-and-forget
+   * 跑 LLM 生成标题；完成时通过这个通道把 `{chatId, title}` 推过来。返回的函数
+   * 解除订阅（preload 用 add/remove 配对，不是 removeAllListeners——可以多处订阅）。
+   */
+  onChatTitleUpdated?: (
+    callback: (payload: { chatId: string; title: string }) => void,
+  ) => () => void;
+  /**
+   * 回合追问建议就绪。Backend 在助手回复完成后推 `{chatId, messageId, suggestions}`
+   * （先启发式、后 LLM 替换）。返回解除订阅函数。
+   */
+  onSuggestedReplies?: (
+    callback: (payload: {
+      chatId: string;
+      messageId: string;
+      suggestions: string[];
+    }) => void,
+  ) => () => void;
+  /**
+   * 会话补建通知。Backend 在「向一个本地不存在的 chatId 首次发送」时按 URL
+   * 里的 id 现场补建会话（见 router.handleStream），随后广播 `chat-created`
+   * （{chatId, agentId}）；渲染端据此 refresh 一次侧栏，避免"URL 能聊、列表
+   * 里却找不到这条会话"。返回解除订阅函数。
+   */
+  onChatCreated?: (
+    callback: (payload: { chatId: string; agentId?: string | null }) => void,
+  ) => () => void;
+  /**
+   * 另一个进程提交了宿主库。侧栏据此重新拉会话列表。
+   * 载荷为空；渲染端不依赖里面的字段。
+   */
+  onStoreChanged?: (callback: () => void) => () => void;
+  /**
+   * 4.6a 后台任务状态推送。任务到达终态或 worktree 合并/丢弃完成时主进程
+   * 广播；载荷只有 chatId/taskId，面板收到后重新拉列表。
+   */
+  onTaskUpdated?: (
+    callback: (payload: { chatId: string; taskId: string }) => void,
+  ) => () => void;
+  /**
+   * 场景包广播事件订阅（3.1 通用化）：按通道名订阅主进程/BS 后端的
+   * 广播事件，载荷由订阅方（包）自行收窄校验。shell 不知道包的事件
+   * 语义——包的通道名约定带包前缀（如 `<pack>:updated`）。返回解除
+   * 订阅函数。
+   */
+  onPackEvent?: (
+    channel: string,
+    callback: (payload: unknown) => void,
+  ) => () => void;
+  /**
+   * 后台任务推理时间线推送。任务流的 reasoning / 工具 / 文本增量经主进程
+   * 广播；右侧过程栏订阅后不用轮询。
+   */
+  onTaskProcess?: (
+    callback: (payload: {
+      chatId: string;
+      taskId: string;
+      timeline: unknown;
+      live: boolean;
+    }) => void,
+  ) => () => void;
+  /**
+   * W4-1 审批代数：sidecar ApprovalExecutor 的请示经主进程广播到 renderer。
+   * onRequest 订阅返回 unsubscribe；decide 把用户的 7 变体决定送回主进程。
+   */
+  approval?: {
+    onRequest: (callback: (request: ApprovalPromptRequest) => void) => () => void;
+    decide: (decision: {
+      requestId: string;
+      kind: ApprovalDecisionKind;
+      reason?: string;
+    }) => Promise<void>;
+    pending: () => Promise<ApprovalPromptRequest[]>;
+  };
+  /**
+   * W8 结构化提问：sidecar ask_user 工具的请示经主进程/BS 服务器广播到
+   * renderer。onRequest 订阅返回 unsubscribe；answer 把答案映射送回
+   * （空映射 = 用户未作答，模型自行推进）。
+   */
+  askUser?: {
+    onRequest: (callback: (request: AskUserPromptRequest) => void) => () => void;
+    answer: (reply: {
+      requestId: string;
+      answers: Record<string, string | string[]>;
+    }) => Promise<void>;
+    pending: () => Promise<AskUserPromptRequest[]>;
+  };
+  terminal?: {
+    /** Ensures a session exists (reuses last one if alive). */
+    ensure: (options?: TerminalSpawnOptions) => Promise<TerminalSession>;
+    write: (id: string, data: string) => Promise<boolean>;
+    resize: (id: string, cols: number, rows: number) => Promise<boolean>;
+    onData: (
+      callback: (payload: { sessionId: string; chunk: string }) => void,
+    ) => () => void;
+    onExit: (
+      callback: (payload: {
+        sessionId: string;
+        code: number;
+        signal: string | null;
+      }) => void,
+    ) => () => void;
+  };
+  /**
+   * 桌面版本与更新。Tauri 提供；浏览器预览没有这一段。
+   */
+  app?: {
+    snapshot: () => Promise<AppReleaseSnapshot>;
+    check: () => Promise<AppReleaseSnapshot>;
+    install: () => Promise<AppReleaseSnapshot>;
+    onState: (callback: (snapshot: AppReleaseSnapshot) => void) => () => void;
+  };
+  /** Desktop-only Python child interpreter management for run_code. */
+  pythonRunner?: {
+    snapshot: () => Promise<PythonRunnerSnapshot>;
+    download: (url?: string) => Promise<PythonRunnerSnapshot>;
+    cancel: () => Promise<PythonRunnerSnapshot>;
+    pickLocal: () => Promise<string | null>;
+    useLocal: (path: string) => Promise<PythonRunnerSnapshot>;
+    useDefault: () => Promise<PythonRunnerSnapshot>;
+    restart: () => Promise<void>;
+    onState: (callback: (snapshot: PythonRunnerSnapshot) => void) => () => void;
+  };
+  // 场景包的 invoke 命名空间（如包 preload 贡献的 `<pack>` / `<pack>Mock`）
+  // 不进本接口——包用自己的结构化收窄访问器（见各包 web/bridge.ts），
+  // shell 桥接口保持产品中立（3.1）。
+}
+
+declare global {
+  interface Window {
+    steerableHost?: HostBridge;
+    __TAURI_INTERNALS__?: object;
+    /**
+     * BS server 托管 index.html 时注入的引导信息。存在且没有 Tauri
+     * 内部对象时，`getHostBridge()` 返回 HTTP 实现。
+     */
+    __DEEPPATH_BS__?: {
+      platform: NodeJS.Platform;
+      flavor: string;
+      brandName: string;
+    };
+  }
+}
+
+export function getHostBridge(): HostBridge | null {
+  if (typeof window === 'undefined') return null;
+  if (window.steerableHost) return window.steerableHost;
+  if (window.__TAURI_INTERNALS__ && window.__DEEPPATH_BS__) {
+    return getTauriBridge();
+  }
+  if (window.__DEEPPATH_BS__) return getHttpBridge();
+  return null;
+}
+
+/** True when the page can call the Node host, including browser mode. */
+export function hasHostBridge(): boolean {
+  return getHostBridge() !== null;
+}
+
+export function isDesktopHost(): boolean {
+  if (typeof window === 'undefined') return false;
+  return Boolean(
+    window.steerableHost || (window.__TAURI_INTERNALS__ && window.__DEEPPATH_BS__),
+  );
+}

package/src/lib/host-paste.ts

@@ -15,7 +15,7 @@ export interface HostClipboard {
   text: string;
   files: HostClipboardFile[];
 }
-import { getHostBridge } from './electron-bridge';
+import { getHostBridge } from './host-bridge';
 
 let pending = false;
 let lastEditable: HTMLElement | null = null;

package/src/lib/http-bridge.ts

@@ -1,6 +1,6 @@
 /**
  * BS 模式的宿主 bridge：与 Electron preload（src/preload.ts）暴露的
- * `window.electron` 同一接口（ElectronBridge），但传输换成 HTTP + SSE：
+ * `window.steerableHost` 同一接口（HostBridge），但传输换成 HTTP + SSE：
  *
  *   localBackend.request   → fetch /api/v2/*
  *   localBackend.startStream → fetch（ReadableStream 逐 chunk 喂 onEvent）
@@ -12,17 +12,17 @@
  * onPackEvent（= subscribeChannel）订阅。
  *
  * server 在 index.html 里注入 `window.__DEEPPATH_BS__`（platform/brand），
- * getElectronBridge() 据此在浏览器里选中本实现。
+ * getHostBridge() 据此在浏览器里选中本实现。
  */
 import type {
   ApprovalPromptRequest,
   AskUserPromptRequest,
-  ElectronBridge,
+  HostBridge,
   LocalBackendRequestInput,
   LocalBackendStreamEvent,
   TerminalSession,
   TerminalSpawnOptions,
-} from './electron-bridge';
+} from './host-bridge';
 import { t } from '@/i18n';
 
 interface BsBootstrap {
@@ -198,9 +198,9 @@ async function terminalEnsure(options?: TerminalSpawnOptions): Promise<TerminalS
   return session;
 }
 
-export function createHttpBridge(): ElectronBridge {
+export function createHttpBridge(): HostBridge {
   const boot = bootstrap();
-  const bridge: ElectronBridge = {
+  const bridge: HostBridge = {
     runtime: 'local',
     platform: boot.platform,
 
@@ -266,6 +266,8 @@ export function createHttpBridge(): ElectronBridge {
     onChatCreated: (callback) =>
       subscribeChannel<{ chatId: string; agentId?: string | null }>('chat-created', callback),
 
+    onStoreChanged: (callback) => subscribeChannel('store:changed', () => callback()),
+
     onTaskUpdated: (callback) =>
       subscribeChannel<{ chatId: string; taskId: string }>(
         'task-updated',
@@ -321,9 +323,9 @@ export function createHttpBridge(): ElectronBridge {
   return bridge;
 }
 
-let singleton: ElectronBridge | null = null;
+let singleton: HostBridge | null = null;
 
-export function getHttpBridge(): ElectronBridge {
+export function getHttpBridge(): HostBridge {
   if (!singleton) singleton = createHttpBridge();
   return singleton;
 }

package/src/lib/insights.ts

@@ -1,11 +1,11 @@
-import { getElectronBridge } from './electron-bridge';
+import { getHostBridge } from './host-bridge';
 
 /** Fire-and-forget local enqueue. Never throws into UI. */
 export function trackBehavior(
   eventName: string,
   properties: Record<string, unknown> = {},
 ): void {
-  const bridge = getElectronBridge();
+  const bridge = getHostBridge();
   if (!bridge) return;
   void bridge.localBackend
     .request({

package/src/lib/local-api.ts

@@ -1,18 +1,18 @@
 /**
- * Typed wrappers around `window.electron.localBackend.request` for the
+ * Typed wrappers around `window.steerableHost.localBackend.request` for the
  * endpoints that apps/web actually consumes today. Shapes follow what
  * `src/local-backend/router.ts` returns — see the corresponding route
  * handlers there if you need to add fields.
  *
  * Conventions:
- *   - Every helper throws if the bridge is missing (caller should `isElectron()`
+ *   - Every helper throws if the bridge is missing (caller should `hasHostBridge()`
  *     check first if a graceful degradation is needed).
  *   - We deliberately keep the local return shapes (not Pydantic / protocol
  *     types) — they're the contract between local-backend and renderer, and
  *     may drift from any public cloud API. Aligning the two is out of scope.
  */
 
-import { getElectronBridge } from './electron-bridge';
+import { getHostBridge } from './host-bridge';
 
 export interface LocalChat {
   id: string;
@@ -100,10 +100,10 @@ interface CreateChatResponse {
 }
 
 function bridge() {
-  const b = getElectronBridge();
+  const b = getHostBridge();
   if (!b) {
     throw new Error(
-      'Electron bridge unavailable — local API can only be used inside the desktop shell.',
+      'Host bridge unavailable — local API can only be used inside the desktop shell.',
     );
   }
   return b;
@@ -767,6 +767,14 @@ export interface DiagnoseResult {
   hint: string | null;
 }
 
+export async function installCommandLineTool(name: string) {
+  return bridge().localBackend.request<{ path: string; onPath: boolean }>({
+    method: 'POST',
+    path: '/api/v2/cli/install',
+    body: { name },
+  });
+}
+
 export async function diagnoseLlmConnection(input: {
   baseUrl?: string;
   apiKey?: string;

package/src/lib/portable.ts

@@ -4,7 +4,7 @@
  */
 
 import { t } from '@/i18n';
-import { getElectronBridge } from '@/lib/electron-bridge';
+import { getHostBridge } from '@/lib/host-bridge';
 import { listChats } from '@/lib/local-api';
 import { persistExecPolicy, readStoredExecPolicy, type ExecPolicy } from '@/lib/exec-policy';
 import {
@@ -139,7 +139,7 @@ export function isClientSection(id: string): boolean {
 }
 
 async function request<T>(method: string, path: string, body?: unknown): Promise<T> {
-  const bridge = getElectronBridge();
+  const bridge = getHostBridge();
   if (!bridge) throw new Error(t('No local backend in this environment'));
   return bridge.localBackend.request<T>(body === undefined ? { method, path } : { method, path, body });
 }
@@ -189,7 +189,7 @@ export async function importChatDocument(document: unknown): Promise<PortableCha
 
 export async function saveJsonFile(filename: string, data: unknown): Promise<string | null> {
   const content = `${JSON.stringify(data, null, 2)}\n`;
-  const save = getElectronBridge()?.local?.saveTextFile;
+  const save = getHostBridge()?.local?.saveTextFile;
   if (save) {
     const saved = await save({ title: t('Export'), defaultPath: filename, content });
     if (saved.canceled || !saved.filePath) return null;

package/src/lib/slash-sources.ts

@@ -14,7 +14,7 @@
 
 import { useCallback, useEffect, useState } from 'react';
 import { getPackHiddenSlashSkills } from '../packs/registry';
-import { getElectronBridge, isElectron } from './electron-bridge';
+import { getHostBridge, hasHostBridge } from './host-bridge';
 
 export type SkillItem = {
   /** Skill directory name (e.g. `70-plan-mode`); absent on hand-built items. */
@@ -125,7 +125,7 @@ let inflight: Promise<SlashSources> | null = null;
 const listeners = new Set<(sources: SlashSources) => void>();
 
 async function load(): Promise<SlashSources> {
-  const bridge = getElectronBridge();
+  const bridge = getHostBridge();
   if (!bridge) return cached;
 
   let skills = cached.skills;
@@ -159,7 +159,7 @@ async function load(): Promise<SlashSources> {
 
 /** Re-read the catalog. Concurrent callers share one in-flight request. */
 export function refreshSlashSources(): Promise<SlashSources> {
-  if (!isElectron()) return Promise.resolve(cached);
+  if (!hasHostBridge()) return Promise.resolve(cached);
   if (!inflight) {
     inflight = load().finally(() => {
       inflight = null;

package/src/lib/tauri-bridge.ts

@@ -12,7 +12,7 @@ import type {
   AppReleaseSnapshot,
   HostBridge,
   PythonRunnerSnapshot,
-} from './electron-bridge';
+} from './host-bridge';
 import { createHttpBridge } from './http-bridge';
 
 type VoidCallback = () => void;

package/src/main.tsx

@@ -94,8 +94,8 @@ export async function bootstrap(): Promise<void> {
   if (import.meta.env.DEV) {
     // 动态 import：prod 构建里 Rollup 把 DEV 分支连同 mock（含其 fixtures）
     // 整体树摇掉，浏览器 dev mock 数据不进产物。
-    const { installBrowserDevElectronMock } = await import('./lib/browser-dev-electron-mock');
-    installBrowserDevElectronMock();
+    const { installBrowserDevHostMock } = await import('./lib/browser-dev-host-mock');
+    installBrowserDevHostMock();
   }
 
   // 标题与 favicon 在 bootstrap 时设置——此刻产品入口已完成包注册
@@ -105,7 +105,7 @@ export async function bootstrap(): Promise<void> {
     defaultLocale: import.meta.env.VITE_DEFAULT_LOCALE || 'en',
   });
   document.documentElement.lang = getLocale() === 'zh' ? 'zh-CN' : getLocale();
-  window.electron?.setLocale?.(getLocale());
+  window.steerableHost?.setLocale?.(getLocale());
   document.title = BRAND_NAME;
   document.querySelector<HTMLLinkElement>('link[rel="icon"]')?.setAttribute('href', getBrandLogoUrl());
   installHostPaste();