@steerable/agent-shell-web 0.6.15

package/src/lib/chat-transport.ts

@@ -0,0 +1,346 @@
+/**
+ * Local chat transport — bridges Electron IPC SSE -> `@steerable/agent-ui`'s
+ * `ChatStreamTransport` contract.
+ *
+ * Pipeline:
+ *
+ *   user types in ChatPanel
+ *     -> useChatStream.sendUserMessage()
+ *     -> transport.stream(input, onEvent)
+ *     -> window.electron.localBackend.startStream({ POST /api/v2/chats/:id/run })
+ *     -> main process forwards each raw SSE chunk via webContents.send
+ *     -> preload re-emits as `{ type: 'data'; chunk: string }`
+ *     -> we parse the SSE frames with the framework's `SSEParser`, normalise
+ *        the payload via `bridgeLegacySSE`, and call `onEvent` for each
+ *        normalised event
+ *     -> useChatStream's reducer renders messages
+ *
+ * Local-backend's wire format (see src/local-backend/router.ts handleStream):
+ *
+ *   - Standard content tokens:    `data: {"content":"..."}\n\n`
+ *   - User message echo:          `data: {"type":"user_message", "message":{...}}\n\n`
+ *   - Tool execution summary:     `data: {"type":"executed_actions", "actions":[...]}\n\n`
+ *   - Per-round completion:       `data: {"type":"completion", "status":"...", "reason":"..."}\n\n`
+ *   - Budget exhausted:           `data: {"type":"budget_exhausted", "budget":{...}}\n\n`
+ *   - Persisted message id:       `data: {"type":"message_id", "messageId":"..."}\n\n`
+ *   - Named error event:          `event: error\ndata: {"message":"..."}\n\n`
+ *   - Stream terminator:          `data: [DONE]\n\n`
+ *
+ * Framework `SSEEvent` (packages/agent-protocol/ts/src/generated/SSEEvent.ts)
+ * is the canonical normalisation target. The legacy-envelope mapping lives in
+ * `@steerable/agent-ui/state`'s `bridgeLegacySSE` — this file used to keep its
+ * own copy; wave 1 of the steerable-framework refactor consolidated them.
+ *
+ * We do still keep one app-specific guard: if any content has already
+ * streamed and the backend ends with `budget_exhausted`, we downgrade that
+ * event to a generic `agent/round_end` + `done` so the framework hook
+ * doesn't blow away the already-rendered text via patch-last-assistant.
+ *
+ * Open issue (upstream): framework `useChatStream`'s cancel pathway stores
+ * the cancel handle only AFTER `await transport.stream(...)` resolves, by
+ * which point the stream has already ended. So the framework's Stop button
+ * is effectively a no-op today. We still return a cancel function from the
+ * resolved promise per the contract; full cancel UX needs an upstream fix.
+ */
+
+import type {
+  ChatStreamTransport,
+  ChatStreamSendInput,
+} from '@steerable/agent-ui';
+import {
+  SSEParser,
+  bridgeLegacySSE,
+  parseSSEData,
+} from '@steerable/agent-ui/state';
+import type { SSEEvent } from '@steerable/agent-protocol';
+import { getElectronBridge } from './electron-bridge';
+import { appendDelta, syncTools, type TurnBlock } from '@/components/chat/turn-timeline';
+import type { ExecutedAction } from '@/components/chat/ExecutedActionsCard';
+
+// ---------------------------------------------------------------------------
+// Local-backend SSE adapter — feeds opaque IPC chunks into the framework's
+// `SSEParser`, then runs every frame through `bridgeLegacySSE` and applies a
+// small app-specific guard around `budget_exhausted` (see file header).
+// ---------------------------------------------------------------------------
+
+class LocalBackendSseAdapter {
+  /** True once any content delta has been forwarded for this stream. */
+  private hasStreamedContent = false;
+  private completed = false;
+  private readonly parser: SSEParser;
+  private timeline: TurnBlock[] = [];
+
+  constructor(private readonly onEvent: (event: SSEEvent) => void) {
+    this.parser = new SSEParser({
+      onFrame: (frame) => {
+        if (!frame.data) return;
+        const parsed = parseSSEData(frame.data);
+        const ev = bridgeLegacySSE(parsed, frame.event);
+        if (ev) this.handleNormalised(ev);
+      },
+      onComplete: () => {
+        if (!this.completed) {
+          this.completed = true;
+          this.onEvent({ type: 'done' });
+        }
+      },
+    });
+  }
+
+  feed(chunk: string): void {
+    this.parser.feed(chunk);
+  }
+
+  end(): void {
+    this.parser.end();
+    if (!this.completed) {
+      this.completed = true;
+      this.onEvent({ type: 'done' });
+    }
+  }
+
+  private handleNormalised(event: SSEEvent): void {
+    if (event.type === 'content' && typeof event.content === 'string' && event.content.length > 0) {
+      this.hasStreamedContent = true;
+    }
+    if (event.type === 'budget_exhausted' && this.hasStreamedContent) {
+      this.onEvent({
+        type: 'agent',
+        event: 'budget_exhausted_suppressed',
+        payload: { reason: event.message ?? 'budget_exhausted' },
+      } as any);
+      if (!this.completed) {
+        this.completed = true;
+        this.onEvent({ type: 'done' });
+      }
+      return;
+    }
+    const timelineChanged = this.applyToTimeline(event);
+    this.onEvent(event);
+    if (timelineChanged) {
+      this.onEvent({
+        type: 'agent',
+        event: 'turn_timeline',
+        payload: { blocks: this.timeline },
+      });
+    }
+  }
+
+  private applyToTimeline(event: SSEEvent): boolean {
+    if (event.type === 'content' && typeof event.content === 'string' && event.content.length > 0) {
+      this.timeline = appendDelta(this.timeline, 'text', event.content);
+      return true;
+    }
+    if (event.type !== 'agent') return false;
+    if (event.event === 'reasoning') {
+      const delta =
+        typeof event.payload?.content === 'string'
+          ? event.payload.content
+          : typeof event.payload?.delta === 'string'
+            ? event.payload.delta
+            : '';
+      if (!delta) return false;
+      this.timeline = appendDelta(this.timeline, 'reasoning', delta);
+      return true;
+    }
+    if (event.event === 'executed_actions') {
+      const actions = event.payload?.actions as ExecutedAction[] | undefined;
+      if (!Array.isArray(actions)) return false;
+      this.timeline = syncTools(this.timeline, actions);
+      return true;
+    }
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Transport factory — bind to a specific chatId. Each `stream()` invocation
+// starts a fresh SSE pipe against /api/v2/chats/:id/run.
+// ---------------------------------------------------------------------------
+
+export interface ElectronChatTransport extends ChatStreamTransport {
+  /**
+   * 立即取消当前进行中的流（如果有）。
+   *
+   * 框架的 `useChatStream` 只在 `transport.stream()` resolve 之后才保存
+   * cancel 句柄——那时流已经结束，Stop 按钮等于空操作。这个方法绕过该缺陷：
+   * transport 自己记住 in-flight streamId，UI 层（Stop 按钮 / 组件卸载）
+   * 直接调它把主进程里的 agent 循环真正停下来。
+   */
+  cancelActive: () => void;
+}
+
+export function createElectronChatTransport(chatId: string): ElectronChatTransport {
+  // 当前 in-flight 流的 id。startStream resolve 后写入，流结束（end/error）
+  // 或被取消后清空。同一 transport 一次只会有一条流（useChatStream 在
+  // isStreaming 时拒绝重入）。
+  const active: { streamId: string | null } = { streamId: null };
+
+  return {
+    cancelActive: () => {
+      const bridge = getElectronBridge();
+      if (active.streamId) {
+        bridge?.localBackend.cancelStream(active.streamId);
+        active.streamId = null;
+        return;
+      }
+      // 切走再切回后：当前 mount 没有原 streamId（它属于上一个已卸载的
+      // mount），改用 chatId 取消后端仍在跑的回合。fire-and-forget。
+      if (bridge) {
+        void bridge.localBackend
+          .request({
+            method: 'POST',
+            path: `/api/v2/chats/${encodeURIComponent(chatId)}/cancel`,
+            body: {},
+          })
+          .catch(() => {});
+      }
+    },
+    // 轮中转向：仅在 CoreLoop 路径（STEERABLE_USE_CORELOOP=1）且回合仍
+    // 运行时生效；否则主进程软失败，useChatStream 保留草稿。
+    steer: async (content: string) => {
+      const bridge = getElectronBridge();
+      if (!bridge?.localBackend.steerChat) return false;
+      return await bridge.localBackend.steerChat(chatId, content);
+    },
+    stream: async (input: ChatStreamSendInput, onEvent) => {
+      const bridge = getElectronBridge();
+      if (!bridge) {
+        throw new Error(
+          'Electron bridge unavailable — chat transport requires the desktop shell.',
+        );
+      }
+
+      const adapter = new LocalBackendSseAdapter(onEvent);
+
+      // We mutate this from inside the IPC callback (settle) and read it from
+      // the cancel handle returned at the end. Declaring it up-front sidesteps
+      // any temporal-dead-zone surprises.
+      const ref: { streamId: string | null } = { streamId: null };
+
+      await new Promise<void>((resolve, reject) => {
+        let settled = false;
+        const settle = (err?: Error) => {
+          if (settled) return;
+          settled = true;
+          if (err) reject(err);
+          else resolve();
+        };
+
+        bridge.localBackend
+          .startStream(
+            {
+              method: 'POST',
+              path: `/api/v2/chats/${encodeURIComponent(chatId)}/run`,
+              body: {
+                message: input.content,
+                ...(input.metadata ?? {}),
+              },
+            },
+            (payload) => {
+              if (payload.type === 'data') {
+                adapter.feed(payload.chunk);
+                return;
+              }
+              if (payload.type === 'end') {
+                active.streamId = null;
+                adapter.end();
+                settle();
+                return;
+              }
+              // payload.type === 'error'
+              active.streamId = null;
+              adapter.end();
+              onEvent({ type: 'error', message: payload.error });
+              settle(new Error(payload.error));
+            },
+          )
+          .then((streamId) => {
+            ref.streamId = streamId;
+            active.streamId = streamId;
+          })
+          .catch((err: unknown) => {
+            const msg = err instanceof Error ? err.message : String(err);
+            onEvent({ type: 'error', message: msg });
+            settle(new Error(msg));
+          });
+      });
+
+      // Return cancel handle per the transport contract. Note: framework's
+      // hook stores this AFTER stream completion, so it's a no-op in practice.
+      // Real cancel-while-streaming goes through `cancelActive()` above.
+      return () => {
+        if (ref.streamId) bridge.localBackend.cancelStream(ref.streamId);
+      };
+    },
+  };
+}
+
+// Exported for unit testing the SSE adapter separately from the IPC bridge.
+export const __test__ = {
+  LocalBackendSseAdapter,
+};
+
+/**
+ * W1.2.1: regenerate an assistant turn via the backend's regenerate route
+ * (fork-preserving truncate-and-rerun). The stream's events are not fed to
+ * `useChatStream` — the hook's message state is thrown away on the
+ * re-hydrate that follows anyway, so this just runs the turn to completion
+ * and lets the caller remount the message list from the store.
+ */
+export async function regenerateChatMessage(
+  chatId: string,
+  messageId: string,
+): Promise<void> {
+  const bridge = getElectronBridge();
+  if (!bridge) {
+    throw new Error(
+      'Electron bridge unavailable — regenerate requires the desktop shell.',
+    );
+  }
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    const settle = (err?: Error) => {
+      if (settled) return;
+      settled = true;
+      if (err) reject(err);
+      else resolve();
+    };
+    // The route can refuse before running anything — it declines to regenerate
+    // when the old reply could not be forked into a branch. A refusal arrives
+    // as a named `error` frame plus a non-2xx `end`; the main process only
+    // sends `type: 'error'` when the handler throws, so without reading the
+    // frame the caller would see an ordinary completion.
+    let refusal: string | null = null;
+    const parser = new SSEParser({
+      onFrame: (frame) => {
+        if (frame.event !== 'error' || !frame.data) return;
+        const parsed = parseSSEData(frame.data);
+        const message = (parsed as { message?: unknown } | null)?.message;
+        refusal = typeof message === 'string' && message ? message : '重新生成失败';
+      },
+    });
+    bridge.localBackend
+      .startStream(
+        {
+          method: 'POST',
+          path: `/api/v2/chats/${encodeURIComponent(chatId)}/messages/${encodeURIComponent(messageId)}/regenerate`,
+          body: {},
+        },
+        (payload) => {
+          if (payload.type === 'data') parser.feed(payload.chunk);
+          else if (payload.type === 'end') {
+            parser.end();
+            settle(
+              payload.status >= 400
+                ? new Error(refusal ?? `重新生成失败（HTTP ${payload.status}）`)
+                : undefined,
+            );
+          } else if (payload.type === 'error') settle(new Error(payload.error));
+        },
+      )
+      .catch((err: unknown) => {
+        settle(err instanceof Error ? err : new Error(String(err)));
+      });
+  });
+}

package/src/lib/date-groups.ts

@@ -0,0 +1,34 @@
+/**
+ * Date-group helpers used by AgentSidebar to label chat groups
+ * ("今天" / "昨天" / "N天前" / "M月D日" / "YYYY年M月D日"). Lifted verbatim
+ * from `deeppath/apps/web/src/app/agent/AgentSidebar.tsx` so the visual
+ * grouping stays in lockstep.
+ *
+ * priority is used for ordering groups: smaller = newer = listed first.
+ */
+
+export function getDateGroupLabel(date: Date): string {
+  const today = new Date();
+  today.setHours(0, 0, 0, 0);
+  const target = new Date(date);
+  target.setHours(0, 0, 0, 0);
+  const diffDays =
+    (today.getTime() - target.getTime()) / (1000 * 60 * 60 * 24);
+  if (diffDays === 0) return '今天';
+  if (diffDays === 1) return '昨天';
+  if (diffDays < 4) return `${Math.floor(diffDays)}天前`;
+  const m = target.getMonth() + 1;
+  const d = target.getDate();
+  if (target.getFullYear() !== today.getFullYear()) {
+    return `${target.getFullYear()}年${m}月${d}日`;
+  }
+  return `${m}月${d}日`;
+}
+
+export function getDateGroupPriority(label: string): number {
+  if (label === '今天') return 1;
+  if (label === '昨天') return 2;
+  if (label.endsWith('天前')) return 2 + parseInt(label, 10);
+  if (label.includes('年')) return 1000;
+  return 100;
+}

package/src/lib/demo-flag.ts

@@ -0,0 +1,15 @@
+/**
+ * Demo-mode flag for the static website build (steerableframework.com/demo/).
+ * The app-demo entry calls markDemoMode() before bootstrap; AppShell reads it
+ * for the demo banner and the browser mock reads it to allow installation
+ * outside DEV builds. Normal app builds never call markDemoMode().
+ */
+let demoMode = false;
+
+export function markDemoMode(): void {
+  demoMode = true;
+}
+
+export function isDemoMode(): boolean {
+  return demoMode;
+}

package/src/lib/electron-bridge.ts

@@ -0,0 +1,270 @@
+/**
+ * Typed view of `window.electron`, the bridge that Electron's preload script
+ * (src/preload.ts in the main project) exposes via `contextBridge`.
+ *
+ * This file MUST stay a subset / aligned shape with `ElectronAPI` in
+ * `../../../src/preload.ts`. We intentionally don't TypeScript-reference that
+ * file across workspaces — it would drag the whole main-process source tree
+ * into the renderer's compile graph. Treat this as a contract surface and
+ * extend it lazily as apps/web starts using new bridge methods.
+ *
+ * Outside Electron (e.g. plain `vite dev` in a browser tab without preload),
+ * `window.electron` is undefined. Always read it via `getElectronBridge()`
+ * and handle the `null` case so the SPA stays demoable in a normal browser.
+ */
+
+import type { SSEEvent } from '@steerable/agent-protocol';
+import { getHttpBridge } from './http-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;
+}
+
+/**
+ * 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>>;
+}
+
+/**
+ * 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 interface ElectronBridge {
+  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 }>;
+    }>;
+  };
+  /**
+   * App menu IPC — `Cmd+N` / 文件 → 新建对话 fires `menu:new-chat`
+   * (see src/main.ts:createMenu). Renderer subscribes via
+   * `onMenuNewChat(cb)` and *must* call `offMenuNewChat()` on unmount
+   * to clear the listener (otherwise multiple AgentSidebar mounts
+   * during HMR would queue up duplicate callbacks).
+   */
+  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;
+  /**
+   * 异步 AI 标题就绪通知。Backend 在每条 chat 首条助手回复完成后 fire-and-forget
+   * 跑 LLM 生成标题；完成时通过这个通道把 `{chatId, title}` 推过来。返回的函数
+   * 解除订阅（preload 用 add/remove 配对，不是 removeAllListeners——可以多处订阅）。
+   */
+  onChatTitleUpdated?: (
+    callback: (payload: { chatId: string; title: 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;
+  /**
+   * 4.6a 后台任务状态推送。任务到达终态或 worktree 合并/丢弃完成时主进程
+   * 广播；载荷只有 chatId/taskId/status，面板收到后重新拉列表。
+   */
+  onTaskUpdated?: (
+    callback: (payload: { chatId: string; taskId: string; status: 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>;
+  };
+  /**
+   * 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>;
+  };
+  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;
+    /**
+     * agent 命令进入可见 PTY 时由 main 广播（`terminal:reveal`）——渲染端
+     * 据此自动展开内嵌终端面板（Codex 式 auto-reveal）。已打开时是 no-op。
+     */
+    onReveal: (
+      callback: (payload: { sessionId: string }) => void,
+    ) => () => void;
+  };
+  // 场景包的 invoke 命名空间（如包 preload 贡献的 `<pack>` / `<pack>Mock`）
+  // 不进本接口——包用自己的结构化收窄访问器（见各包 web/bridge.ts），
+  // shell 桥接口保持产品中立（3.1）。
+}
+
+declare global {
+  interface Window {
+    electron?: ElectronBridge;
+    /**
+     * BS server（src/server/）托管 index.html 时注入的引导信息；存在即代表
+     * 当前跑在浏览器-服务器模式，getElectronBridge() 会返回 HTTP 实现。
+     */
+    __DEEPPATH_BS__?: {
+      platform: NodeJS.Platform;
+      flavor: string;
+      brandName: string;
+    };
+  }
+}
+
+export function getElectronBridge(): ElectronBridge | null {
+  if (typeof window === 'undefined') return null;
+  if (window.electron) return window.electron;
+  if (window.__DEEPPATH_BS__) return getHttpBridge();
+  return null;
+}
+
+export function isElectron(): boolean {
+  return getElectronBridge() !== null;
+}

package/src/lib/exec-policy.ts

@@ -0,0 +1,25 @@
+/**
+ * 会话级命令执行沙箱（类 Codex 的 sandbox_mode）。
+ *
+ * 作用于下一轮 `chat.stream` 的 `execSandbox`，不是 sidecar 进程沙箱
+ * （设置页那一层）。工作区 = 只能写入当前项目；完整权限 = 关闭逐条命令
+ * 沙箱。工具审批（允许/拒绝）仍按原策略生效。
+ */
+
+export type ExecPolicy = 'workspace' | 'full';
+
+export const EXEC_POLICY_STORAGE_KEY = 'agent-exec-policy';
+
+export function parseExecPolicy(value: unknown): ExecPolicy {
+  return value === 'full' ? 'full' : 'workspace';
+}
+
+export function readStoredExecPolicy(): ExecPolicy {
+  if (typeof localStorage === 'undefined') return 'workspace';
+  return parseExecPolicy(localStorage.getItem(EXEC_POLICY_STORAGE_KEY));
+}
+
+export function persistExecPolicy(policy: ExecPolicy): void {
+  if (typeof localStorage === 'undefined') return;
+  localStorage.setItem(EXEC_POLICY_STORAGE_KEY, policy);
+}