@steerable/agent-shell 0.6.41 → 0.6.42

package/README.md

@@ -1,6 +1,21 @@
 # @steerable/agent-shell
 
-Product-neutral Electron and headless HTTP host for Steerable Framework.
+Product-neutral Node HostRuntime and headless HTTP host for Steerable Framework.
+
+## Desktop composition
+
+Tauri desktop products supervise the same BS executable used by browser mode,
+bind it to an ephemeral loopback port, and load its web UI in a WebView. The
+renderer uses `HostBridge`: HTTP/SSE carries agent, storage, PTY, approval,
+attachment, and pack traffic; narrow Tauri commands provide native dialogs,
+menus, screenshots, and updates. `STEERABLE_HOST_READY` on stdout is the
+machine-readable startup record. `STEERABLE_HOST_PARENT_PID` makes the Node
+host shut down if its desktop supervisor disappears.
+
+The reusable Rust host source is published as
+`@steerable/agent-shell-tauri`. Product `src-tauri` crates depend on its
+installed npm path and only supply product configuration plus
+`tauri::generate_context!()`.
 
 ## BS composition
 

package/contracts/tool-contract.json

@@ -280,6 +280,24 @@
         "version"
       ]
     },
+    "view_image": {
+      "desktopName": "view_image",
+      "optionalInput": [
+        "region",
+        "maxEdge",
+        "format"
+      ],
+      "requiredInput": [
+        "path"
+      ],
+      "requiredResult": [
+        "width",
+        "height",
+        "sourcePath",
+        "mediaType",
+        "_image"
+      ]
+    },
     "write_file": {
       "desktopName": "local_write_file",
       "optionalInput": [
@@ -294,7 +312,7 @@
       ]
     }
   },
-  "version": 2,
+  "version": 3,
   "dualImplementations": {
     "todo_write": ["python", "rust"],
     "web_fetch": ["python", "rust"],

package/dist/host-tools.d.ts

@@ -34,7 +34,7 @@ export type ResolvedSettingsChrome = Record<SettingsItemId, boolean>;
  */
 export declare function resolveSettingsChrome(value?: unknown, tools?: ResolvedHostTools): ResolvedSettingsChrome;
 export declare function hasGeneralSettingsChrome(chrome?: ResolvedSettingsChrome): boolean;
-export declare const LOCAL_FS_TOOL_NAMES: readonly ["local_exec_shell", "local_read_file", "local_write_file", "local_edit_file", "local_open_path", "local_run_snippet", "local_list_scripts", "local_run_script"];
+export declare const LOCAL_FS_TOOL_NAMES: readonly ["local_exec_shell", "local_read_file", "view_image", "local_write_file", "local_edit_file", "local_open_path", "local_run_snippet", "local_list_scripts", "local_run_script"];
 export declare function resolveHostToolSurface(value: boolean | {
     capability?: boolean;
     chrome?: boolean;
@@ -68,6 +68,6 @@ export declare function buildHostApproval(input: {
     timeoutMs?: number;
 }): {
     mode: 'host';
-    timeoutMs: number;
+    timeoutMs?: number;
     storePath: string;
 } | undefined;

package/dist/host-tools.js

@@ -76,6 +76,7 @@ export function hasGeneralSettingsChrome(chrome = resolveSettingsChrome()) {
 export const LOCAL_FS_TOOL_NAMES = [
     'local_exec_shell',
     'local_read_file',
+    'view_image',
     'local_write_file',
     'local_edit_file',
     'local_open_path',
@@ -190,9 +191,11 @@ export function isHostIpcAllowed(channel, tools = resolveHostTools()) {
 export function buildHostApproval(input) {
     if (!isApprovalEnabled(input))
         return undefined;
+    // No default timer: the card stays until the user allows or denies.
+    // An explicit timeoutMs still fails closed as timed_out.
     return {
         mode: 'host',
-        timeoutMs: input.timeoutMs ?? 120_000,
+        ...(input.timeoutMs != null ? { timeoutMs: input.timeoutMs } : {}),
         storePath: input.storePath,
     };
 }

package/dist/image-attachment.d.ts

@@ -1,3 +1,4 @@
+import type { NativeImageLike } from './runtime.js';
 import type { LlmImage } from './llm/types.js';
 /** Refuse to read source files larger than this (10 MB). */
 export declare const IMAGE_MAX_SOURCE_BYTES: number;
@@ -14,6 +15,33 @@ export interface ProcessedImageAttachments {
     /** One line per input describing the outcome, for the model-visible note. */
     notes: string[];
 }
+export interface ImageRegion {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}
+export interface ViewImageInput {
+    path: string;
+    region?: ImageRegion;
+    maxEdge?: number;
+    format?: 'png' | 'jpeg';
+}
+export interface ViewImageResult {
+    success: boolean;
+    data?: {
+        width: number;
+        height: number;
+        sourcePath: string;
+        mediaType: 'image/png' | 'image/jpeg';
+        _image: {
+            b64: string;
+            media_type: 'image/png' | 'image/jpeg';
+        };
+    };
+    error?: string;
+    needsFollowup?: boolean;
+}
 export declare function isImagePath(path: string): boolean;
 /**
  * Validate the wire value (`metadata.images` from the renderer) into a clean
@@ -32,6 +60,12 @@ export declare function computeTargetSize(width: number, height: number, maxDime
     height: number;
     resized: boolean;
 };
+/**
+ * Decode, optionally crop, resize, and encode one image for a model-visible
+ * tool result. `_image` is consumed by the CoreLoop as an image content part;
+ * it is not a path or model-visible base64 string.
+ */
+export declare function processViewImage(input: ViewImageInput, nativeImage?: NativeImageLike | null): ViewImageResult;
 /**
  * Process a batch of image attachments. Synchronous: `nativeImage` decode /
  * resize / encode are all synchronous, and the byte check uses `statSync`.

package/dist/image-attachment.js

@@ -69,6 +69,117 @@ export function computeTargetSize(width, height, maxDimension = IMAGE_MAX_DIMENS
         resized: true,
     };
 }
+/**
+ * Decode, optionally crop, resize, and encode one image for a model-visible
+ * tool result. `_image` is consumed by the CoreLoop as an image content part;
+ * it is not a path or model-visible base64 string.
+ */
+export function processViewImage(input, nativeImage = getNativeImage()) {
+    if (!isImagePath(input.path)) {
+        return {
+            success: false,
+            error: 'view_image supports PNG, JPEG, and WebP files',
+            needsFollowup: true,
+        };
+    }
+    if (!nativeImage) {
+        return {
+            success: false,
+            error: '当前运行环境不支持图片解码',
+            needsFollowup: true,
+        };
+    }
+    let sourceBytes;
+    try {
+        sourceBytes = statSync(input.path).size;
+    }
+    catch {
+        return { success: false, error: '图片不存在或不可读', needsFollowup: true };
+    }
+    if (sourceBytes > IMAGE_MAX_SOURCE_BYTES) {
+        return {
+            success: false,
+            error: `源文件 ${formatMb(sourceBytes)}MB 超过 ${formatMb(IMAGE_MAX_SOURCE_BYTES)}MB 上限`,
+            needsFollowup: true,
+        };
+    }
+    const maxEdge = input.maxEdge ?? IMAGE_MAX_DIMENSION;
+    if (!Number.isInteger(maxEdge) || maxEdge < 1 || maxEdge > 4096) {
+        return {
+            success: false,
+            error: 'maxEdge 必须是 1–4096 的整数',
+            needsFollowup: true,
+        };
+    }
+    let rendered = nativeImage.createFromPath(input.path);
+    if (rendered.isEmpty()) {
+        return { success: false, error: '不是可识别的图片', needsFollowup: true };
+    }
+    if (input.region) {
+        const crop = resolveCrop(input.region, rendered.getSize());
+        if ('error' in crop) {
+            return { success: false, error: crop.error, needsFollowup: true };
+        }
+        rendered = rendered.crop(crop);
+    }
+    const croppedSize = rendered.getSize();
+    const target = computeTargetSize(croppedSize.width, croppedSize.height, maxEdge);
+    if (target.resized) {
+        rendered = rendered.resize({
+            width: target.width,
+            height: target.height,
+            quality: 'good',
+        });
+    }
+    const sourceExt = extname(input.path).toLowerCase();
+    const outputFormat = input.format ?? (['.jpg', '.jpeg'].includes(sourceExt) ? 'jpeg' : 'png');
+    let mediaType = outputFormat === 'jpeg' ? 'image/jpeg' : 'image/png';
+    let buffer = outputFormat === 'jpeg' ? rendered.toJPEG(85) : rendered.toPNG();
+    if (buffer.length > IMAGE_MAX_ENCODED_BYTES && input.format == null && outputFormat === 'png') {
+        mediaType = 'image/jpeg';
+        buffer = rendered.toJPEG(80);
+    }
+    if (buffer.length > IMAGE_MAX_ENCODED_BYTES) {
+        return {
+            success: false,
+            error: `图片编码后 ${formatMb(buffer.length)}MB 超过 ${formatMb(IMAGE_MAX_ENCODED_BYTES)}MB 上限；请减小 maxEdge 或使用 jpeg`,
+            needsFollowup: true,
+        };
+    }
+    const { width, height } = rendered.getSize();
+    const b64 = buffer.toString('base64');
+    return {
+        success: true,
+        data: {
+            width,
+            height,
+            sourcePath: input.path,
+            mediaType,
+            _image: { b64, media_type: mediaType },
+        },
+    };
+}
+function resolveCrop(region, size) {
+    const values = [region.x, region.y, region.w, region.h];
+    if (!values.every(Number.isFinite))
+        return { error: 'region 的 x/y/w/h 必须是有限数字' };
+    const normalized = values.every((value) => value >= 0 && value <= 1);
+    const x = normalized ? Math.floor(region.x * size.width) : Math.round(region.x);
+    const y = normalized ? Math.floor(region.y * size.height) : Math.round(region.y);
+    const width = normalized ? Math.ceil(region.w * size.width) : Math.round(region.w);
+    const height = normalized ? Math.ceil(region.h * size.height) : Math.round(region.h);
+    if (x < 0 ||
+        y < 0 ||
+        width < 1 ||
+        height < 1 ||
+        x + width > size.width ||
+        y + height > size.height) {
+        return {
+            error: `region 超出图片范围 ${size.width}×${size.height}`,
+        };
+    }
+    return { x, y, width, height };
+}
 function formatMb(bytes) {
     return (bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, '');
 }

package/dist/mcp-executor.js

@@ -56,7 +56,7 @@ function tryResolveBundled(config) {
         return {
             command: process.execPath,
             args: [entryPath, ...extraArgs],
-            env: { ...config.env, ELECTRON_RUN_AS_NODE: '1' },
+            env: { ...config.env },
             cwd: config.cwd,
         };
     }

package/dist/runtime.d.ts

@@ -43,12 +43,18 @@ export declare function shellOpenExternal(url: string): Promise<void>;
  */
 export declare function onAppWillQuit(listener: () => void): void;
 export declare function offAppWillQuit(listener: () => void): void;
-interface NativeImageInstance {
+export interface NativeImageInstance {
     isEmpty(): boolean;
     getSize(): {
         width: number;
         height: number;
     };
+    crop(rect: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    }): NativeImageInstance;
     resize(o: {
         width?: number;
         height?: number;
@@ -57,7 +63,7 @@ interface NativeImageInstance {
     toPNG(): Buffer;
     toJPEG(quality: number): Buffer;
 }
-interface NativeImageLike {
+export interface NativeImageLike {
     createFromPath(p: string): NativeImageInstance;
 }
 /**
@@ -65,4 +71,3 @@ interface NativeImageLike {
  * null——调用方按"不支持图片解码"降级（image-attachment 已有该分支）。
  */
 export declare function getNativeImage(): NativeImageLike | null;
-export {};

package/dist/server/index.js

@@ -1,12 +1,17 @@
 /** Executable BS entry; reusable assembly lives in `start.ts`. */
 import { startBsHost } from './start.js';
+import { formatHostReady } from './ready.js';
 async function main() {
     const handle = await startBsHost();
+    console.log(formatHostReady({ host: handle.host, port: handle.port }));
     let shuttingDown = false;
+    let parentWatch;
     const shutdown = () => {
         if (shuttingDown)
             return;
         shuttingDown = true;
+        if (parentWatch)
+            clearInterval(parentWatch);
         console.log('[bs] shutting down…');
         void handle.shutdown().finally(() => process.exit(0));
         // 兜底：sidecar 卡住也不拖住退出。
@@ -14,6 +19,27 @@ async function main() {
     };
     process.on('SIGINT', shutdown);
     process.on('SIGTERM', shutdown);
+    const parentPidValue = process.env.STEERABLE_HOST_PARENT_PID?.trim();
+    if (parentPidValue) {
+        const parentPid = Number(parentPidValue);
+        if (!Number.isSafeInteger(parentPid) || parentPid <= 0 || parentPid === process.pid) {
+            throw new Error(`invalid STEERABLE_HOST_PARENT_PID: ${parentPidValue}`);
+        }
+        parentWatch = setInterval(() => {
+            try {
+                process.kill(parentPid, 0);
+            }
+            catch (error) {
+                if (error &&
+                    typeof error === 'object' &&
+                    'code' in error &&
+                    error.code === 'ESRCH') {
+                    shutdown();
+                }
+            }
+        }, 1_000);
+        parentWatch.unref();
+    }
 }
 main().catch((err) => {
     console.error('[bs] failed to start:', err);

package/dist/server/ready.d.ts

@@ -0,0 +1,12 @@
+/** Prefix for the machine-readable host startup record on stdout. */
+export declare const HOST_READY_PREFIX = "STEERABLE_HOST_READY ";
+export interface HostReadyRecord {
+    host: string;
+    port: number;
+}
+/**
+ * Formats the startup record consumed by desktop host supervisors.
+ *
+ * Human-readable log lines are not part of this protocol.
+ */
+export declare function formatHostReady(record: HostReadyRecord): string;

package/dist/server/ready.js

@@ -0,0 +1,10 @@
+/** Prefix for the machine-readable host startup record on stdout. */
+export const HOST_READY_PREFIX = 'STEERABLE_HOST_READY ';
+/**
+ * Formats the startup record consumed by desktop host supervisors.
+ *
+ * Human-readable log lines are not part of this protocol.
+ */
+export function formatHostReady(record) {
+    return `${HOST_READY_PREFIX}${JSON.stringify(record)}`;
+}

package/dist/sidecar/boot.js

@@ -304,14 +304,11 @@ export async function startHostSidecar(deps) {
                     // tool-router forwards the call back over the reverse channel.
                     STEERABLE_RUN_CODE: '1',
                     // P3: conversational JS PTC (run_js/wait_js). The sidecar spawns a
-                    // long-lived Node worker; in the desktop that worker is the bundled
-                    // runtime — process.execPath is the Electron binary, which runs as
-                    // plain Node under ELECTRON_RUN_AS_NODE (and already *is* plain
-                    // Node in headless/BS mode, where the variable is ignored). The
-                    // sidecar's env scrub passes both through to the worker child.
+                    // long-lived Node worker. Browser and Tauri desktop hosts both run
+                    // under the pinned Node runtime, so process.execPath is directly
+                    // executable by the sidecar.
                     STEERABLE_PTC_JS: '1',
                     STEERABLE_PTC_NODE: process.execPath,
-                    ELECTRON_RUN_AS_NODE: '1',
                 },
                 onLogLine: (line) => (deps.onLogLine ?? ((l) => log.info('[sidecar]', l)))(line),
             });

package/dist/sidecar/reverse-approval.d.ts

@@ -5,8 +5,9 @@
  *
  * Fail-closed by construction: no window, no listener, a renderer error,
  * or an invalid reply all become `deny_once` — never a hang, never an
- * auto-allow. The sidecar additionally bounds the wait (`timeoutMs` on the
- * approval config), so a wedged renderer degrades to `timed_out` there.
+ * auto-allow. An explicit `timeoutMs` on the approval config still fails
+ * closed as `timed_out`; the desktop omits it, so the prompt waits until
+ * the user decides.
  *
  * The renderer answers via the `approval:decide` invoke with the requestId
  * echoed back; decisions are validated against the algebra's kind set

package/dist/sidecar/reverse-approval.js

@@ -5,8 +5,9 @@
  *
  * Fail-closed by construction: no window, no listener, a renderer error,
  * or an invalid reply all become `deny_once` — never a hang, never an
- * auto-allow. The sidecar additionally bounds the wait (`timeoutMs` on the
- * approval config), so a wedged renderer degrades to `timed_out` there.
+ * auto-allow. An explicit `timeoutMs` on the approval config still fails
+ * closed as `timed_out`; the desktop omits it, so the prompt waits until
+ * the user decides.
  *
  * The renderer answers via the `approval:decide` invoke with the requestId
  * echoed back; decisions are validated against the algebra's kind set

package/dist/sidecar/reverse-ask-user.d.ts

@@ -16,6 +16,8 @@ export interface AskUserPromptRequest {
     requestId: string;
     intro: string;
     questions: Array<Record<string, unknown>>;
+    /** 发起提问的对话。renderer 只在这条会话的输入框展示卡片。 */
+    chatId?: string;
 }
 export interface AskUserBridgeDeps {
     broadcast: (channel: 'ask-user:request', payload: AskUserPromptRequest) => void;

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

@@ -17,6 +17,7 @@ export function createAskUserBridge(deps) {
         handler: (params) => {
             const p = (params ?? {});
             const questions = Array.isArray(p.questions) ? p.questions : [];
+            const chatId = typeof p.chatId === 'string' && p.chatId ? p.chatId : undefined;
             if (questions.length === 0) {
                 deps.onLog?.('ask_user: malformed request (no questions); answering empty');
                 return Promise.resolve({ ...EMPTY_REPLY });
@@ -30,6 +31,7 @@ export function createAskUserBridge(deps) {
                 requestId,
                 intro: typeof p.intro === 'string' ? p.intro : '',
                 questions: questions,
+                ...(chatId ? { chatId } : {}),
             };
             return new Promise((resolve) => {
                 pending.set(requestId, { prompt, resolve });

package/dist/sidecar/reverse-spawn.d.ts

@@ -1,7 +1,7 @@
 /**
  * W4.1.1 reverse channel: serve the sidecar's `host.process.spawn` by
  * spawning the command confined on Windows via the win-spawn-helper Rust
- * binary (restricted token + Job Object; contract: OpenSteerable
+ * binary (restricted token + Job Object; contract: Steerable
  * docs/spec/safety.md "Host capability surface").
  *
  * Fail closed by construction: on non-Windows platforms (which have local

package/dist/sidecar/reverse-spawn.js

@@ -1,7 +1,7 @@
 /**
  * W4.1.1 reverse channel: serve the sidecar's `host.process.spawn` by
  * spawning the command confined on Windows via the win-spawn-helper Rust
- * binary (restricted token + Job Object; contract: OpenSteerable
+ * binary (restricted token + Job Object; contract: Steerable
  * docs/spec/safety.md "Host capability surface").
  *
  * Fail closed by construction: on non-Windows platforms (which have local

package/dist/sidecar/reverse-tools.js

@@ -18,6 +18,22 @@ import { normalizeToolPolicy } from '../local-backend/agent-capability.js';
  * 2000 单字段，最坏情况纯 CJK 约 4.8k token）。
  */
 function capResultForModelContext(out) {
+    if (out && typeof out === 'object') {
+        const record = out;
+        const data = record.data && typeof record.data === 'object'
+            ? record.data
+            : null;
+        const image = data?._image;
+        if (image && typeof image === 'object') {
+            const textOnly = { ...record, data: { ...data } };
+            delete textOnly.data._image;
+            const capped = capResultForModelContext(textOnly);
+            const cappedData = capped.data && typeof capped.data === 'object'
+                ? capped.data
+                : {};
+            return { ...capped, data: { ...cappedData, _image: image } };
+        }
+    }
     const json = JSON.stringify(out);
     if (json.length <= 8000)
         return out;

package/dist/sidecar/types.d.ts

@@ -445,8 +445,9 @@ export interface SidecarChatStreamRequest {
      * `mode: 'host'` asks the host UI over the reverse channel
      * (`approval.request`); `storePath` enables the durable scope
      * (`allow_always` / `deny_always` persisted per category);
-     * `timeoutMs` fails closed as `timed_out` (a denial) when the UI does
-     * not answer in time. Absent → no approval layer (legacy behavior).
+     * `timeoutMs`, when set, fails closed as `timed_out` (a denial) when the
+     * UI does not answer in time. Omitted, the prompt waits until the user
+     * decides. Absent `approval` → no approval layer (legacy behavior).
      */
     approval?: {
         mode: 'host' | 'auto';

package/dist/tool-router.d.ts

@@ -10,7 +10,7 @@ import { type AgentToolPolicy } from './local-backend/agent-capability.js';
 /** 已注册 MCP 服务的动态工具名前缀：`mcp__<serverKey>__<toolName>`。 */
 export declare const MCP_DYNAMIC_TOOL_PREFIX = "mcp__";
 /**
- * 工具曝光分层（OpenSteerable Wave 2 同构）：`direct` 进模型可见列表；
+ * 工具曝光分层（Steerable Wave 2 同构）：`direct` 进模型可见列表；
  * `deferred` 可分发、可经 `tool_search` 发现，但不占每轮工具列表的 token；
  * `hidden` 仅可分发。缺省 `direct`。
  *
@@ -205,11 +205,12 @@ export declare class ToolRouter {
      */
     private applyProjectCwdSandbox;
     private executeShell;
+    private resolveReadablePath;
     private resolveMcpConfig;
     /**
      * `tool_search` 处理器：BM25 排序 deferred 名录（name 分词计两次），返回
      * 完整 schema，结果有界（默认 8，封顶 20）。算法、常量、默认上限与返回
-     * 文案都与 OpenSteerable `tool_search.py` 对齐——同名工具在两侧给
+     * 文案都与 Steerable `tool_search.py` 对齐——同名工具在两侧给
      * 出同样的名次；hidden 层不进搜索。
      *
      * 智能体工具策略在这里同样生效：否则每轮列表藏起来的工具会从这条发现缝

package/dist/tool-router.js

@@ -5,12 +5,13 @@ import { mcpExecutor } from './mcp-executor.js';
 import { rankTools, resolveMaxResults, TOOL_SEARCH_DEFAULT_MAX_RESULTS, } from './tool-search-rank.js';
 import { maybeAutoInstallWrittenSkill } from './local-backend/skill-install.js';
 import { filterToolsByPolicy, isToolAllowed, } from './local-backend/agent-capability.js';
+import { processViewImage } from './image-attachment.js';
 import { isHostToolCapabilityEnabled } from './host-tools.js';
 import { getResolvedHostTools } from './host-tools-runtime.js';
 /** 已注册 MCP 服务的动态工具名前缀：`mcp__<serverKey>__<toolName>`。 */
 export const MCP_DYNAMIC_TOOL_PREFIX = 'mcp__';
 /**
- * 工具曝光分层（OpenSteerable Wave 2 同构）：`direct` 进模型可见列表；
+ * 工具曝光分层（Steerable Wave 2 同构）：`direct` 进模型可见列表；
  * `deferred` 可分发、可经 `tool_search` 发现，但不占每轮工具列表的 token；
  * `hidden` 仅可分发。缺省 `direct`。
  *
@@ -148,6 +149,43 @@ export class ToolRouter {
                     required: ['path'],
                 },
             },
+            {
+                name: 'view_image',
+                description: 'Look at a local PNG, JPEG, or WebP image. The result includes an actual image content part the model can see, not merely a path or base64 text. ' +
+                    'Use region for a pixel or normalized 0–1 crop, maxEdge to bound the longest output edge, and jpeg to reduce payload size.',
+                mode: 'read',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: { type: 'string', description: 'Local PNG, JPEG, or WebP path.' },
+                        region: {
+                            type: 'object',
+                            description: 'Optional crop {x,y,w,h}; use either pixel values or all-normalized 0–1 values.',
+                            properties: {
+                                x: { type: 'number' },
+                                y: { type: 'number' },
+                                w: { type: 'number' },
+                                h: { type: 'number' },
+                            },
+                            required: ['x', 'y', 'w', 'h'],
+                            additionalProperties: false,
+                        },
+                        maxEdge: {
+                            type: 'integer',
+                            minimum: 1,
+                            maximum: 4096,
+                            description: 'Resize the longest output edge to at most this many pixels (default 1568).',
+                        },
+                        format: {
+                            type: 'string',
+                            enum: ['png', 'jpeg'],
+                            description: 'Output encoding. JPEG usually uses fewer bytes/tokens.',
+                        },
+                    },
+                    required: ['path'],
+                    additionalProperties: false,
+                },
+            },
             {
                 name: 'local_write_file',
                 description: 'Write content to local file path',
@@ -655,6 +693,33 @@ export class ToolRouter {
                 return await this.localExecutor.readLocalFile({
                     path: String(args.path || ''),
                 }, projectRoot, context?.additionalReadRoots ?? null);
+            case 'view_image': {
+                if (args.format !== undefined && args.format !== 'png' && args.format !== 'jpeg') {
+                    return {
+                        success: false,
+                        error: 'format 必须是 png 或 jpeg',
+                        needsFollowup: true,
+                    };
+                }
+                const sourcePath = this.resolveReadablePath(String(args.path || ''), projectRoot, context?.additionalReadRoots ?? null);
+                if ('error' in sourcePath) {
+                    return { success: false, error: sourcePath.error, needsFollowup: true };
+                }
+                const region = args.region && typeof args.region === 'object'
+                    ? {
+                        x: Number(args.region.x),
+                        y: Number(args.region.y),
+                        w: Number(args.region.w),
+                        h: Number(args.region.h),
+                    }
+                    : undefined;
+                return processViewImage({
+                    path: sourcePath.path,
+                    region,
+                    maxEdge: typeof args.maxEdge === 'number' ? args.maxEdge : undefined,
+                    format: args.format === 'png' || args.format === 'jpeg' ? args.format : undefined,
+                });
+            }
             case 'local_write_file': {
                 const written = await this.localExecutor.writeLocalFile({
                     path: String(args.path || ''),
@@ -871,6 +936,29 @@ export class ToolRouter {
         }
         return this.localExecutor.executeShell(sandboxed.request);
     }
+    resolveReadablePath(inputPath, projectRoot, additionalReadRoots) {
+        if (!inputPath.trim())
+            return { error: 'path 不能为空' };
+        const expanded = inputPath.startsWith('~')
+            ? path.join(os.homedir(), inputPath.slice(1))
+            : inputPath;
+        const resolved = path.resolve(expanded);
+        if (!projectRoot)
+            return { path: resolved };
+        const root = path.resolve(projectRoot.startsWith('~')
+            ? path.join(os.homedir(), projectRoot.slice(1))
+            : projectRoot);
+        const inAdditionalRoot = (additionalReadRoots ?? []).some((candidate) => {
+            const expandedCandidate = candidate.startsWith('~')
+                ? path.join(os.homedir(), candidate.slice(1))
+                : candidate;
+            return isPathWithinRoot(resolved, path.resolve(expandedCandidate));
+        });
+        if (!isPathWithinRoot(resolved, root) && !inAdditionalRoot) {
+            return { error: buildProjectRootViolation(resolved, root) };
+        }
+        return { path: resolved };
+    }
     resolveMcpConfig(args) {
         return {
             command: String(args.command || ''),
@@ -881,7 +969,7 @@ export class ToolRouter {
     /**
      * `tool_search` 处理器：BM25 排序 deferred 名录（name 分词计两次），返回
      * 完整 schema，结果有界（默认 8，封顶 20）。算法、常量、默认上限与返回
-     * 文案都与 OpenSteerable `tool_search.py` 对齐——同名工具在两侧给
+     * 文案都与 Steerable `tool_search.py` 对齐——同名工具在两侧给
      * 出同样的名次；hidden 层不进搜索。
      *
      * 智能体工具策略在这里同样生效：否则每轮列表藏起来的工具会从这条发现缝

package/dist/tool-search-rank.d.ts

@@ -1,5 +1,5 @@
 /**
- * `tool_search` 的 BM25 排序，与 OpenSteerable
+ * `tool_search` 的 BM25 排序，与 Steerable
  * `packages/agent-runtime/py/src/steerable_agent_runtime/tool_search.py`
  * 同一算法与同一常量：同名工具在两侧必须给出同样的名次与同样的默认上限，
  * 否则「桌面的 tool_search」和「框架的 tool_search」是两个契约不同的工具。

package/dist/tool-search-rank.js

@@ -1,5 +1,5 @@
 /**
- * `tool_search` 的 BM25 排序，与 OpenSteerable
+ * `tool_search` 的 BM25 排序，与 Steerable
  * `packages/agent-runtime/py/src/steerable_agent_runtime/tool_search.py`
  * 同一算法与同一常量：同名工具在两侧必须给出同样的名次与同样的默认上限，
  * 否则「桌面的 tool_search」和「框架的 tool_search」是两个契约不同的工具。

package/package.json

@@ -1,16 +1,16 @@
 {
   "name": "@steerable/agent-shell",
-  "version": "0.6.41",
-  "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.",
+  "version": "0.6.42",
+  "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/",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pathlyapp/opensteerable.git",
+    "url": "git+https://github.com/pathlyapp/steerable.git",
     "directory": "packages/agent-shell/ts"
   },
   "bugs": {
-    "url": "https://github.com/pathlyapp/opensteerable/issues"
+    "url": "https://github.com/pathlyapp/steerable/issues"
   },
   "type": "module",
   "main": "dist/runtime.js",
@@ -55,9 +55,9 @@
     "he": "^1.2.0",
     "node-pty": "^1.1.0",
     "semver": "^7.8.0",
-    "@steerable/agent-harness": "0.6.41",
-    "@steerable/agent-protocol": "0.6.41",
-    "@steerable/pack-sdk": "0.6.41"
+    "@steerable/agent-protocol": "0.6.42",
+    "@steerable/pack-sdk": "0.6.42",
+    "@steerable/agent-harness": "0.6.42"
   },
   "devDependencies": {
     "@types/better-sqlite3": "^7.6.13",
@@ -77,7 +77,7 @@
     "check:drift": "echo ok",
     "shell:neutral": "node scripts/check-shell-neutral.mjs",
     "storage:boundaries": "node scripts/check-storage-boundaries.mjs",
-    "web": "ELECTRON_RUN_AS_NODE=1 DEEPPATH_WEB_DIST=${DEEPPATH_WEB_DIST:-../web/app/dist} node node_modules/electron/cli.js dist/server/index.js",
+    "web": "DEEPPATH_WEB_DIST=${DEEPPATH_WEB_DIST:-../web/app/dist} node dist/server/index.js",
     "client": "DEEPPATH_FORCE_BUNDLED_WEB=1 DEEPPATH_WEB_DIST=${DEEPPATH_WEB_DIST:-../web/app/dist} node node_modules/electron/cli.js dist/main.js"
   }
 }