@steerable/agent-shell 0.6.17 → 0.6.19

package/dist/local-backend/router.js

@@ -898,7 +898,19 @@ export class LocalBackendRouter {
             }
         }
         if (method === 'DELETE' && pathname.startsWith('/api/v2/chat-agents/skills/delete/')) {
-            const skillName = pathname.slice('/api/v2/chat-agents/skills/delete/'.length).trim();
+            // URL.pathname 保留百分号编码——目录名/frontmatter 名含空格等字符时
+            // 客户端发来的是 fancy%20skill，不 decode 永远匹配不上 fancy skill
+            // （projects/mcp 路由段都 decode，这里对齐）。非法编码按 400 处理。
+            let skillName;
+            try {
+                skillName = decodeURIComponent(pathname.slice('/api/v2/chat-agents/skills/delete/'.length)).trim();
+            }
+            catch {
+                return {
+                    status: 400,
+                    data: { error: 'skillName is not valid percent-encoding' },
+                };
+            }
             if (!skillName) {
                 return {
                     status: 400,
@@ -1743,6 +1755,14 @@ export class LocalBackendRouter {
             // user+assistant pair onto history while the original (possibly bad)
             // assistant reply stayed in place — the model saw both and had no real
             // reason to answer differently.
+            //
+            // sidecar 门必须先于任何写操作：rerun 回合只能跑在 sidecar 上
+            // （handleCoreLoopTurn 无 sidecar 直接 503）。若先截断再 503，旧回复
+            // 已删、新回复不会产生、record 也不存在——非破坏性承诺破窗。
+            if (!getSidecarSupervisor()) {
+                emit(this.sse('error', { message: 'coreloop enabled but sidecar is not running' }));
+                return { status: 503 };
+            }
             const targetMessageId = regenerateMatch[2];
             // The user turn that prompted the target reply is whatever immediately
             // precedes it — re-derive its text so buildConversationMessages gets
@@ -2897,9 +2917,14 @@ export class LocalBackendRouter {
                 onNotice: (kind, notice) => {
                     if (kind === 'budget_exhausted') {
                         // 预算维度（rounds/tokens）在 notice.budget；notice.kind 是信封
-                        // 类型（loop 事件 data 里的 budget 键经 sidecar 透传）。
+                        // 类型（loop 事件 data 里的 budget 键经 sidecar 透传）。message
+                        // 是客户端读取的人类可读原因（chat-transport 的 reason 字段）。
                         const budgetKind = typeof notice?.budget === 'string' ? notice.budget : undefined;
-                        emit(this.sseData({ type: 'budget_exhausted', budget: { kind: budgetKind } }));
+                        emit(this.sseData({
+                            type: 'budget_exhausted',
+                            budget: { kind: budgetKind },
+                            message: budgetKind ? `budget_exhausted: ${budgetKind}` : 'budget_exhausted',
+                        }));
                     }
                 },
                 onChildEvent: (event) => {

package/dist/local-executor.d.ts

@@ -30,12 +30,22 @@ export interface LocalFileReadRequest {
     path: string;
     encoding?: BufferEncoding;
     maxSize?: number;
+    /** 1-based 起始行（CC Read 风格分页）。与 limit 配合做部分视图读取。 */
+    offset?: number;
+    /** 最多返回的行数（配合 offset 分页）；缺省返回到文件尾。 */
+    limit?: number;
 }
 export interface LocalFileReadResult {
     success: boolean;
     content?: string;
     /** 内容版本令牌（SHA-256）。读后写场景把它回传给 edit/write 做冲突检测。 */
     version?: string;
+    /**
+     * 本次返回的只是部分视图（offset/limit 分页或超长裁剪）——模型没看到完整
+     * 内容，本会话对该路径的整体覆写将被拒绝（框架 partial_reads / CC
+     * isPartialView 对齐）；定点修改走 local_edit_file 不受此限。
+     */
+    partial?: boolean;
     error?: string;
 }
 export interface LocalFileWriteRequest {
@@ -105,6 +115,18 @@ export interface LocalRunCodeResult extends LocalExecResult {
     /** 本次调用实际安装成功的依赖。 */
     installedPackages?: string[];
 }
+/**
+ * 部分视图裁剪（框架 `_clip` / CC Read 对齐）。version 永远基于完整内容计算，
+ * 部分视图的 CAS 令牌保持有效；返回的 partial 标记驱动整体覆写门。
+ *
+ * - 给了 offset/limit：按 1-based 行号切片，并在省略处打行数标记（含继续
+ *   分页的下一个 offset）；
+ * - 没给但内容超长：头尾裁剪，中间打省略字符数标记。
+ */
+export declare function slicePartialView(content: string, offset?: number, limit?: number): {
+    content: string;
+    partial: boolean;
+};
 /** 内容版本令牌：UTF-8 内容的 SHA-256。用于 read-before-write 冲突检测。 */
 /**
  * read-before-write 冲突令牌：内容的 SHA-256（UTF-8）十六进制。与框架
@@ -167,6 +189,13 @@ export declare class LocalExecutor {
      * 由 sidecar 的 `read_state.seed` 反向调用重灌（seedReadState）。
      */
     private readonly readFileState;
+    /**
+     * 部分视图门（框架 partial_reads / CC isPartialView 对齐）：本会话只读到
+     * 部分内容的分页/裁剪读取把路径登记在这里；writeLocalFile 拒绝整体覆写
+     * 未见全文的文件。完整读取或本会话自己的写/编辑成功后销记。会话恢复不
+     * 重灌此集合（与框架一致：resume 只重建 version 证据，门退化为 CAS）。
+     */
+    private readonly partialReadPaths;
     constructor(maxOutputBytes?: number, applyEditsFn?: ApplyEditsFn);
     updateSafetyConfig(config: CommandSafetyConfigPayload): void;
     /**

package/dist/local-executor.js

@@ -61,6 +61,55 @@ const NPM_PACKAGE_RE = /^(@[A-Za-z0-9._-]+\/)?[A-Za-z0-9._-]+(@[A-Za-z0-9._~^<>=
 const DEFAULT_TIMEOUT_MS = 30_000;
 const DEFAULT_MAX_OUTPUT_BYTES = 100 * 1024;
 const DEFAULT_MAX_READ_SIZE = 1024 * 1024;
+/**
+ * 单次读取返回给模型的字符上限（框架 workspace_tools `_MAX_OUTPUT` 对齐）。
+ * 超出部分头尾裁剪并打标记——保留尾部，日志/编译错误的关键行通常在末尾。
+ */
+const MAX_READ_OUTPUT_CHARS = 100_000;
+/**
+ * 部分视图裁剪（框架 `_clip` / CC Read 对齐）。version 永远基于完整内容计算，
+ * 部分视图的 CAS 令牌保持有效；返回的 partial 标记驱动整体覆写门。
+ *
+ * - 给了 offset/limit：按 1-based 行号切片，并在省略处打行数标记（含继续
+ *   分页的下一个 offset）；
+ * - 没给但内容超长：头尾裁剪，中间打省略字符数标记。
+ */
+export function slicePartialView(content, offset, limit) {
+    if (offset !== undefined || limit !== undefined) {
+        const start = offset ?? 1;
+        if (!Number.isInteger(start) || start < 1) {
+            throw new Error(`offset 必须是 >= 1 的整数（1-based 行号），收到 ${offset}`);
+        }
+        if (limit !== undefined && (!Number.isInteger(limit) || limit < 1)) {
+            throw new Error(`limit 必须是 >= 1 的整数，收到 ${limit}`);
+        }
+        const lines = content.split('\n');
+        if (start > lines.length) {
+            throw new Error(`offset ${start} 超出文件行数（共 ${lines.length} 行）。`);
+        }
+        const end = limit === undefined ? lines.length : Math.min(lines.length, start - 1 + limit);
+        let view = lines.slice(start - 1, end).join('\n');
+        const omittedAbove = start - 1;
+        const omittedBelow = lines.length - end;
+        if (omittedAbove > 0) {
+            view = `...[{上文省略 ${omittedAbove} 行}]...\n${view}`;
+        }
+        if (omittedBelow > 0) {
+            view = `${view}\n...[{下文省略 ${omittedBelow} 行；用 offset=${end + 1} 继续}]...`;
+        }
+        return { content: view, partial: omittedAbove > 0 || omittedBelow > 0 };
+    }
+    if (content.length <= MAX_READ_OUTPUT_CHARS) {
+        return { content, partial: false };
+    }
+    const head = Math.floor(MAX_READ_OUTPUT_CHARS / 5);
+    const tail = MAX_READ_OUTPUT_CHARS - head;
+    const omitted = content.length - head - tail;
+    return {
+        content: `${content.slice(0, head)}\n...[{省略 ${omitted} 字符；用 offset/limit 分段读取}]...\n${content.slice(-tail)}`,
+        partial: true,
+    };
+}
 /** 内容版本令牌：UTF-8 内容的 SHA-256。用于 read-before-write 冲突检测。 */
 /**
  * read-before-write 冲突令牌：内容的 SHA-256（UTF-8）十六进制。与框架
@@ -175,6 +224,13 @@ export class LocalExecutor {
      * 由 sidecar 的 `read_state.seed` 反向调用重灌（seedReadState）。
      */
     readFileState = new Map();
+    /**
+     * 部分视图门（框架 partial_reads / CC isPartialView 对齐）：本会话只读到
+     * 部分内容的分页/裁剪读取把路径登记在这里；writeLocalFile 拒绝整体覆写
+     * 未见全文的文件。完整读取或本会话自己的写/编辑成功后销记。会话恢复不
+     * 重灌此集合（与框架一致：resume 只重建 version 证据，门退化为 CAS）。
+     */
+    partialReadPaths = new Set();
     constructor(maxOutputBytes = DEFAULT_MAX_OUTPUT_BYTES, applyEditsFn = applyEdits) {
         this.maxOutputBytes = maxOutputBytes;
         this.applyEditsFn = applyEditsFn;
@@ -405,10 +461,19 @@ export class LocalExecutor {
                 return { success: false, error: `File too large (${fileStat.size} bytes), max=${maxSize}` };
             }
             const content = await readFile(filePath, { encoding });
+            // version 基于完整内容：部分视图的读证据 CAS 仍然有效（框架对齐）。
             const version = hashContent(content);
             // P2b: 记录读证据，后续 write/edit 缺省 expectedVersion 时自动 CAS。
             this.readFileState.set(filePath, version);
-            return { success: true, content, version };
+            const view = slicePartialView(content, request.offset, request.limit);
+            // 部分视图登记/销记：整体覆写门（writeLocalFile）据此拒绝未见全文的覆写。
+            if (view.partial) {
+                this.partialReadPaths.add(filePath);
+            }
+            else {
+                this.partialReadPaths.delete(filePath);
+            }
+            return { success: true, content: view.content, version, partial: view.partial };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -427,6 +492,17 @@ export class LocalExecutor {
         return this.serializeFileOp(filePath, async () => {
             try {
                 const encoding = request.encoding ?? 'utf-8';
+                // 部分视图门：本会话对该路径只读到分页/裁剪后的内容，整体覆写会销毁
+                // 未见内容（框架 partial_reads / CC isPartialView 对齐）。定点修改走
+                // local_edit_file；确需整体重写时先用 offset/limit 分段读完。
+                if (this.partialReadPaths.has(filePath)) {
+                    return {
+                        success: false,
+                        error: `拒绝整体覆写：${filePath} 本会话只读到部分内容（分页/裁剪），` +
+                            '覆写会销毁未见内容。请改用 local_edit_file 做定点修改；' +
+                            '确需整体重写时先用 offset/limit 分段读完。',
+                    };
+                }
                 // P2b 自动 CAS：调用方没给 expectedVersion 时回落到本会话的读证据
                 // （含 read_state.seed 重灌的）。隐式期望只对仍存在的文件生效——
                 // 读后被删除的文件重新写入是新建，没有可覆盖的他人改动。
@@ -453,6 +529,8 @@ export class LocalExecutor {
                 const version = hashContent(request.content);
                 // 写成功后回写读证据：本会话自己的连续写不互相冲突。
                 this.readFileState.set(filePath, version);
+                // 模型亲自写了全文，部分视图门不再适用（框架对齐）。
+                this.partialReadPaths.delete(filePath);
                 return { success: true, version };
             }
             catch (error) {
@@ -498,6 +576,8 @@ export class LocalExecutor {
                 await this.atomicWrite(filePath, result.content, encoding);
                 const version = hashContent(result.content);
                 this.readFileState.set(filePath, version);
+                // 注意：编辑不销记 partialReadPaths——定点编辑不代表模型见过全文，
+                // 后续盲写仍会销毁未见内容（框架「Cleared by a full read or a write」对齐）。
                 return {
                     success: true,
                     version,

package/dist/preload.cjs

@@ -122,14 +122,14 @@ function buildPreloadApi(packContributions = {}) {
     },
     /**
      * 4.6a 后台任务状态推送：任务到达终态（completed/failed）或 worktree
-     * 合并/丢弃完成时，主进程广播 `task-updated`。载荷只带 chatId/taskId/
-     * status——renderer 收到后重新拉任务列表（GET /chats/:id/tasks），
+     * 合并/丢弃完成时，主进程广播 `task-updated`。载荷只带 chatId/taskId
+     * ——renderer 收到后重新拉任务列表（GET /chats/:id/tasks），
      * 不把整条任务记录塞进 IPC（避免与 SQLite 双写漂移）。
      */
     onTaskUpdated: (callback) => {
       const handler = (_event, payload) => {
-        if (typeof payload?.chatId === "string" && typeof payload?.taskId === "string" && typeof payload?.status === "string") {
-          callback({ chatId: payload.chatId, taskId: payload.taskId, status: payload.status });
+        if (typeof payload?.chatId === "string" && typeof payload?.taskId === "string") {
+          callback({ chatId: payload.chatId, taskId: payload.taskId });
         }
       };
       import_electron.ipcRenderer.on("task-updated", handler);

package/dist/preload.js

@@ -138,16 +138,14 @@ export function buildPreloadApi(packContributions = {}) {
         },
         /**
          * 4.6a 后台任务状态推送：任务到达终态（completed/failed）或 worktree
-         * 合并/丢弃完成时，主进程广播 `task-updated`。载荷只带 chatId/taskId/
-         * status——renderer 收到后重新拉任务列表（GET /chats/:id/tasks），
+         * 合并/丢弃完成时，主进程广播 `task-updated`。载荷只带 chatId/taskId
+         * ——renderer 收到后重新拉任务列表（GET /chats/:id/tasks），
          * 不把整条任务记录塞进 IPC（避免与 SQLite 双写漂移）。
          */
         onTaskUpdated: (callback) => {
             const handler = (_event, payload) => {
-                if (typeof payload?.chatId === 'string' &&
-                    typeof payload?.taskId === 'string' &&
-                    typeof payload?.status === 'string') {
-                    callback({ chatId: payload.chatId, taskId: payload.taskId, status: payload.status });
+                if (typeof payload?.chatId === 'string' && typeof payload?.taskId === 'string') {
+                    callback({ chatId: payload.chatId, taskId: payload.taskId });
                 }
             };
             ipcRenderer.on('task-updated', handler);

package/dist/runtime.js

@@ -124,8 +124,12 @@ export function resolveProductWebDist(entryUrl) {
     const here = path.dirname(fileURLToPath(entryUrl));
     const productId = path.basename(here);
     for (const candidate of [
+        // 源码平面：入口在 products/<id>/（web dist 在同级 web/dist）。
         path.join(here, 'web', 'dist'),
-        path.resolve(here, '..', '..', '..', '..', 'products', productId, 'web', 'dist'),
+        // 编译平面 A：入口在仓根 dist/products/<id>/（上溯 3 级到仓根）。
+        path.resolve(here, '..', '..', '..', 'products', productId, 'web', 'dist'),
+        // 编译平面 B：入口在产品内 products/<id>/dist/products/<id>/（上溯 5 级到仓根）。
+        path.resolve(here, '..', '..', '..', '..', '..', 'products', productId, 'web', 'dist'),
     ]) {
         if (fs.existsSync(path.join(candidate, 'index.html')))
             return candidate;

package/dist/server/http-server.d.ts

@@ -12,9 +12,16 @@
  *                          （terminal / local / approval 为宿主自带；
  *                          场景包路由经 host/http-routes 注册表匹配）。
  *
- * 安全约定：默认绑定 127.0.0.1、无认证——本机自用定位（与 Electron 版相同
- * 的信任模型：能到端口 = 本机用户）。不要绑到非回环地址，那会把 shell /
- * 文件读写 / 场景包工具控制暴露给整个网络。
+ * 安全约定：默认绑定 127.0.0.1。仅绑回环挡不住 DNS rebinding（恶意网站
+ * 重绑定后受害者浏览器即同源驱动本服务），所以有两道门：
+ *   1. Host 白名单——所有请求（含静态）的 Host 必须是 127.0.0.1 /
+ *      localhost / [::1]，浏览器无法伪造 Host，rebinding 在此被拒；
+ *   2. Bearer token——每次启动随机生成，经 index.html 注入
+ *      `window.__DEEPPATH_BS__.token`；`/api/v2/*` 与 `/host/*` 全部要求
+ *      `Authorization: Bearer <token>`（EventSource 不能设头，SSE 走
+ *      `?token=` query）。静态资源不验 token（浏览器要靠它拿到 token）。
+ * 不要绑到非回环地址，那会把 shell / 文件读写 / 场景包工具控制暴露给整个
+ * 网络（token 只能挡没有 token 的人）。
  */
 import { type Server } from 'node:http';
 import type { LocalBackendRouter } from '../local-backend/router.js';
@@ -35,5 +42,7 @@ export interface BsServerDeps {
     bus: SseBus;
     /** apps/web/dist 的绝对路径。 */
     webDistDir: string;
+    /** Bearer token；缺省每次启动随机生成。测试注入固定值。 */
+    authToken?: string;
 }
 export declare function createBsServer(deps: BsServerDeps): Server;

package/dist/server/http-server.js

@@ -12,11 +12,19 @@
  *                          （terminal / local / approval 为宿主自带；
  *                          场景包路由经 host/http-routes 注册表匹配）。
  *
- * 安全约定：默认绑定 127.0.0.1、无认证——本机自用定位（与 Electron 版相同
- * 的信任模型：能到端口 = 本机用户）。不要绑到非回环地址，那会把 shell /
- * 文件读写 / 场景包工具控制暴露给整个网络。
+ * 安全约定：默认绑定 127.0.0.1。仅绑回环挡不住 DNS rebinding（恶意网站
+ * 重绑定后受害者浏览器即同源驱动本服务），所以有两道门：
+ *   1. Host 白名单——所有请求（含静态）的 Host 必须是 127.0.0.1 /
+ *      localhost / [::1]，浏览器无法伪造 Host，rebinding 在此被拒；
+ *   2. Bearer token——每次启动随机生成，经 index.html 注入
+ *      `window.__DEEPPATH_BS__.token`；`/api/v2/*` 与 `/host/*` 全部要求
+ *      `Authorization: Bearer <token>`（EventSource 不能设头，SSE 走
+ *      `?token=` query）。静态资源不验 token（浏览器要靠它拿到 token）。
+ * 不要绑到非回环地址，那会把 shell / 文件读写 / 场景包工具控制暴露给整个
+ * 网络（token 只能挡没有 token 的人）。
  */
 import { createServer } from 'node:http';
+import { randomBytes } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -52,6 +60,8 @@ const MIME = {
     '.ttf': 'font/ttf',
     '.txt': 'text/plain; charset=utf-8',
 };
+/** Host 白名单：仅回环（可带端口）。浏览器禁止伪造 Host，rebinding 到此为止。 */
+const LOOPBACK_HOST = /^(127\.0\.0\.1|localhost|\[::1\])(:\d+)?$/;
 function sendJson(res, status, data) {
     const body = JSON.stringify(data ?? null);
     res.writeHead(status, {
@@ -81,6 +91,13 @@ function asRecord(body) {
 }
 export function createBsServer(deps) {
     const { localBackendRouter, localExecutor, localScriptRegistry, terminalManager, approvalBridge, askUserBridge, maybeExecInTerminal, bus, webDistDir, } = deps;
+    const authToken = deps.authToken ?? randomBytes(24).toString('base64url');
+    /** `/api/v2/*` 与 `/host/*` 的 Bearer 门；EventSource 不能设头，收 query token。 */
+    function isAuthorized(req, url) {
+        if (req.headers.authorization === `Bearer ${authToken}`)
+            return true;
+        return url.searchParams.get('token') === authToken;
+    }
     async function handleApi(req, res, pathname) {
         const isStream = req.method === 'POST' && STREAM_PATH_PATTERNS.some((p) => p.test(pathname));
         const body = req.method === 'POST' || req.method === 'PATCH' || req.method === 'PUT'
@@ -315,6 +332,7 @@ export function createBsServer(deps) {
                     platform: process.platform,
                     flavor: brand.flavor,
                     brandName: brand.displayName,
+                    token: authToken,
                 })};</script>`;
                 content = content.toString('utf8').replace('<head>', `<head>${bootstrap}`);
             }
@@ -331,8 +349,21 @@ export function createBsServer(deps) {
     }
     return createServer((req, res) => {
         void (async () => {
+            // 门 1：Host 白名单（含静态——rebound 浏览器连 index.html 里的
+            // token 都不许拿到）。
+            if (!LOOPBACK_HOST.test(req.headers.host ?? '')) {
+                sendJson(res, 403, { detail: 'forbidden host' });
+                return;
+            }
             const url = new URL(req.url ?? '/', 'http://bs.local');
             const pathname = url.pathname;
+            // 门 2：API 与宿主能力要 Bearer token；静态资源不验（浏览器靠它
+            // 拿 token），静态面不暴露任何能力。
+            const needsAuth = pathname.startsWith('/api/v2/') || pathname.startsWith('/host/');
+            if (needsAuth && !isAuthorized(req, url)) {
+                sendJson(res, 401, { detail: 'unauthorized' });
+                return;
+            }
             if (pathname === '/api/v2/events' && req.method === 'GET') {
                 bus.attach(res);
                 return;

package/dist/tool-router.js

@@ -125,11 +125,24 @@ export class ToolRouter {
             },
             {
                 name: 'local_read_file',
-                description: 'Read a local text file',
+                description: 'Read a local text file. Large files can be paged with offset/limit (1-based line numbers); ' +
+                    'a paged or clipped result is marked `partial: true`, and a full-file overwrite of a path ' +
+                    'only partially read in this session is rejected — use local_edit_file for targeted changes, ' +
+                    'or finish reading all segments before rewriting.',
                 mode: 'read',
                 inputSchema: {
                     type: 'object',
-                    properties: { path: { type: 'string' } },
+                    properties: {
+                        path: { type: 'string' },
+                        offset: {
+                            type: 'number',
+                            description: 'Optional 1-based line number to start reading from (for paging large files).',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Optional maximum number of lines to return (for paging large files).',
+                        },
+                    },
                     required: ['path'],
                 },
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.17",
+  "version": "0.6.19",
   "description": "Steerable framework — product-neutral desktop/headless agent host (Tier 5). Electron main + preload + headless HTTP server (BS) sharing one storage/sidecar/tooling core; scenario packs extend it through the @steerable/pack-sdk contract and are composed at build time by the consuming product.",
   "license": "Apache-2.0",
   "homepage": "https://steerableframework.com/",
@@ -41,9 +41,9 @@
     "electron-store": "^8.1.0",
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
-    "@steerable/agent-harness": "0.6.17",
-    "@steerable/pack-sdk": "0.6.17",
-    "@steerable/agent-protocol": "0.6.17"
+    "@steerable/agent-harness": "0.6.19",
+    "@steerable/agent-protocol": "0.6.19",
+    "@steerable/pack-sdk": "0.6.19"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",