localsnake-sdk-web 2026.8.7-v1

package/README.md

@@ -0,0 +1,262 @@
+# LocalSnake SDK Web
+
+`localsnake-sdk-web` is the JavaScript SDK for LocalSnake main-interface apps. It exposes two top-level objects:
+
+- `LocalSnake`: app lifecycle, Agent chat, realtime events, workspace files, and low-level host requests.
+- `LocalHub`: LocalHub agent, LLM, proxy, and WebSocket proxy APIs.
+
+Docs: English | [简体中文](README.zh-CN.md) | [Architecture](Architecture.md)
+
+## Install
+
+```bash
+npm install localsnake-sdk-web
+```
+
+Browser bundle:
+
+```html
+<script src="https://cdn.example.com/localsnake-sdk-web.min.js"></script>
+```
+
+## Quick Start
+
+```ts
+import { LocalSnake } from 'localsnake-sdk-web';
+
+const context = await LocalSnake.init();
+console.log(context.agentId, context.sessionKey);
+
+LocalSnake.onEvent((event) => {
+  if (event.type === 'runtime_status') {
+    console.log(event.payload.status, event.payload.activityType);
+  }
+});
+
+await LocalSnake.sendMessage('帮我查一下今天的安排');
+```
+
+## Browser Usage
+
+```html
+<script src="https://cdn.example.com/localsnake-sdk-web.min.js"></script>
+<script>
+  const { LocalSnake, LocalHub } = window;
+
+  LocalSnake.onEvent((event) => {
+    if (event.type === 'runtime_status') {
+      console.log(event.payload.status, event.payload.activityType);
+    }
+  });
+
+  LocalSnake.init((context) => {
+    console.log('LocalSnake app context', context);
+  });
+
+  async function ask(text) {
+    await LocalSnake.sendMessage(text);
+  }
+
+  async function listModels() {
+    return LocalHub.llm.request('/v1/models');
+  }
+</script>
+```
+
+## Module Usage
+
+```ts
+import { LocalSnake, LocalHub } from 'localsnake-sdk-web';
+
+LocalSnake.onEvent((event) => {
+  console.log(event.type, event.payload);
+});
+
+await LocalSnake.init();
+await LocalSnake.sendMessage('帮我查一下今天的安排');
+
+const metadata = await LocalSnake.workspace.readJson('works/montage/knowledge/metadata.json');
+const models = await LocalHub.llm.request('/v1/models');
+```
+
+Default import returns `LocalSnake`:
+
+```ts
+import LocalSnake from 'localsnake-sdk-web';
+```
+
+## Lifecycle
+
+| API | Trigger | Callback argument | Typical use |
+| --- | --- | --- | --- |
+| `LocalSnake.init(handler?)` | After page load and the host `app.init` handshake. If the WebView is visible, `onShow()` is replayed after init. | `LocalSnakeAppContext` | Read agent/session/workspace state and initialize the app. |
+| `LocalSnake.onShow(handler)` | WebView first shown or restored from hidden state. | none | Resume animation, rendering, polling, or visible-state sync. |
+| `LocalSnake.onHide(handler)` | WebView hidden. | none | Pause animation, rendering, or expensive recalculation. |
+| `LocalSnake.onDestroy(handler)` | WebView is unloading, detached, or switching app / agent / page. | none | Cleanup timers, WebGL, audio, and subscriptions. |
+
+Lifecycle callbacks are not delivered through public `LocalSnake.onEvent()`.
+
+## Common APIs
+
+| API | Return value | Notes |
+| --- | --- | --- |
+| `LocalSnake.onEvent(handler)` | `() => void` | Subscribes to realtime non-lifecycle host events. The SDK may replay the latest `runtime_status` so apps do not miss the initial state. |
+| `LocalSnake.sendMessage(text, options?)` | `Promise<unknown>` | Sends a user message to the current open session. Pass `options.sessionKey` to target a specific session. |
+| `LocalSnake.getHistory()` | currently unsupported | Reserved for a future explicit history API. |
+| `LocalSnake.workspace.readText(path)` | `Promise<string \| null>` | Reads a UTF-8 text file under the current agent workspace. Missing files return `null`. |
+| `LocalSnake.workspace.readJson<T>(path)` | `Promise<T \| null>` | Reads and parses a JSON file under the current agent workspace. Missing files return `null`; invalid JSON rejects. |
+| `LocalSnake.workspace.writeText(path, content)` | `Promise<{ path: string, success: boolean, error?: string }>` | Writes a UTF-8 text file under the current agent workspace. Parent directories are created by the host. |
+| `LocalSnake.workspace.writeJson(path, value)` | `Promise<{ path: string, success: boolean, error?: string }>` | Serializes JSON with two-space indentation and writes it under the current agent workspace. |
+| `LocalSnake.request(method, payload?)` | `Promise<T>` | Low-level request entry. Prefer wrapped APIs for normal use. |
+| `LocalHub.request(pathOrRequest, init?)` | `Promise<LocalSnakeLocalHubResponse>` | Low-level LocalHub proxy entry. Prefer the typed `LocalHub.agent`, `LocalHub.llm`, and `LocalHub.proxy` helpers. |
+
+## Send Message
+
+```ts
+await LocalSnake.sendMessage('Summarize this workspace');
+
+await LocalSnake.sendMessage('Send this to a child session', {
+  sessionKey: 'session-key',
+});
+```
+
+If `sessionKey` is omitted, LocalSnake sends the message to the currently active session.
+
+## Workspace Files
+
+`LocalSnake.workspace` is scoped to the current agent workspace reported by `init()`. Paths must be relative workspace paths such as `works/montage/knowledge/metadata.json`; absolute paths, empty paths, null bytes, and `..` escapes are rejected by the host.
+
+```ts
+const index = await LocalSnake.workspace.readJson('works/montage/knowledge/metadata.json');
+await LocalSnake.workspace.writeJson('works/montage/knowledge/metadata.json', {
+  schema_version: 1,
+  kind: 'dreamer.knowledge.index',
+  updated_at: new Date().toISOString(),
+  projects: index?.projects ?? [],
+});
+```
+
+## LocalHub
+
+`LocalHub` is split into the same three public LocalHub route domains:
+
+| API | Route prefix | Use |
+| --- | --- | --- |
+| `LocalHub.agent.request(pathOrRequest, init?)` | `/agent/*` | LocalHub management, search bridge, and evolution APIs. |
+| `LocalHub.llm.request(pathOrRequest, init?)` | `/llm/*` | LLM proxy calls, including OpenAI-compatible and Anthropic-compatible routes. |
+| `LocalHub.proxy.request(pathOrRequest, init?)` | `/proxy/*` | HTTP request-proxy calls configured in LocalHub. |
+| `LocalHub.proxy.route(routes)` | `/agent/proxies` | Overwrite request-proxy route configuration for the system LocalHub key. Pass `[]` to clear. |
+| `LocalHub.proxy.websocket(pathOrRequest, options?)` | `/proxy/*` | WebSocket request-proxy calls configured in LocalHub. |
+
+LocalSnake supplies the LocalHub base URL and injects the configured `localHubApiKey` as `Authorization: Bearer <key>` in the background. Apps should not read, store, or pass `localHubApiKey`.
+
+```ts
+await LocalHub.agent.request('/initialized');
+await LocalHub.llm.request('/v1/models');
+
+const res = await LocalHub.proxy.request('/orders/42', {
+  method: 'POST',
+  body: { status: 'paid' },
+});
+```
+
+Request-proxy routes can be replaced for the system LocalHub key with a semantic helper. The LocalHub management endpoint is `/agent/proxies`, but the SDK exposes it under `LocalHub.proxy.route()` because it configures runtime `/proxy/*` routes.
+
+```ts
+await LocalHub.proxy.route([
+  {
+    name: 'orders',
+    protocol: 'http',
+    path: '/proxy/orders/*',
+    targetUrl: 'https://api.example.com/orders',
+    headers: { Authorization: 'Bearer upstream-token' },
+  },
+]);
+
+await LocalHub.proxy.route([]);
+```
+
+WebSocket request proxies are exposed through a small browser-like object. It is backed by the host bridge so LocalSnake can attach the required Authorization header during the LocalHub handshake.
+
+```ts
+const socket = LocalHub.proxy.websocket('/events');
+
+socket.onopen = () => socket.send('hello');
+socket.onmessage = (event) => {
+  console.log(event.data);
+};
+socket.onclose = (event) => {
+  console.log(event.code, event.reason);
+};
+```
+
+## Realtime Event Contract
+
+`LocalSnake.onEvent()` receives a single event object:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `type` | `string` | Event type. |
+| `timestamp` | `number` | Host-side timestamp in milliseconds. |
+| `payload` | `object` | Event payload. Shape depends on `type`. |
+
+`LocalSnake.onEvent()` events are self-contained and do not include `LocalSnakeAppContext`; read agent / session / workspace from `init()`.
+
+| Event type | Source | Payload shape | Description |
+| --- | --- | --- | --- |
+| `user_message` | OpenClaw session | `{ message: LocalSnakeMessage }` | A realtime user message entered the current open session. |
+| `assistant_delta` | OpenClaw stream | `{ text: string, message?: LocalSnakeMessage, runId?: string \| null }` | Realtime assistant text delta. Append it to the current message / run only. |
+| `assistant_message` | OpenClaw session | `{ message: LocalSnakeMessage }` | Realtime final assistant message. |
+| `tool_call` | OpenClaw tool call | `{ toolCallId?: string, toolName?: string, input?: unknown, status?: "running" \| "completed" \| "error" }` | Realtime tool call event. Do not append it into assistant text. |
+| `tool_result` | OpenClaw tool result | `{ toolCallId?: string, toolName?: string, result?: unknown, text?: string, isError?: boolean }` | Realtime tool response / result. Hosts may emit more than one result event for streamed tool output. |
+| `send_message` | SDK / AppManager | `{ text: string, sessionKey?: string \| null }` | The embedded app submitted a user message through `LocalSnake.sendMessage()`. |
+| `runtime_status` | AppManager | `LocalSnakeRuntimeStatus` | Current-session runtime status. Prefer this event for scene / state mapping. |
+
+## Payload Types
+
+### `LocalSnakeAppContext`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `app` | `"LocalSnake"` | Host app name. |
+| `platform` | `"desktop" \| "mobile" \| "unknown"` | Host platform. |
+| `bridge` | `"electron-webview" \| "ios-webkit" \| "android-webview" \| "react-native-webview" \| "webview2" \| "post-message" \| "unknown"` | JS bridge type. |
+| `agentId` | `string \| null` | Current agent id. |
+| `sessionKey` | `string \| null` | Current open session key. |
+| `workspacePath` | `string \| null` | Current agent workspace path. |
+| `visibilityState` | `"visible" \| "hidden"` | WebView visibility at init time. |
+| `capabilities.chat` | `boolean` | Whether `sendMessage` is supported. |
+| `capabilities.history` | `boolean` | Currently `false`; history is not exposed through SDK Web. |
+| `capabilities.localHub` | `boolean` | Whether LocalHub proxy APIs are supported. |
+| `capabilities.workspace` | `boolean` | Whether current-agent workspace file APIs are supported. |
+| `capabilities.events` | `string[]` | Non-lifecycle event types the host may emit through `onEvent()`. |
+
+### `LocalSnakeRuntimeStatus`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `status` | `"idle" \| "working" \| "subagent"` | Coarse runtime state. Ordinary main-process tool calls remain `working`; `subagent` means subagent coordination is active. |
+| `activityType` | `"idle" \| "message" \| "tool" \| "subagent" \| "queued" \| "thinking"` | More specific current activity. Prefer this for UI mapping when possible. |
+| `sessionKey` | `string \| null \| undefined` | Current session key. |
+| `activeRunId` | `string \| null \| undefined` | Active runtime run id when known. |
+| `sending` | `boolean` | Whether the current session is considered actively running. |
+| `pendingFinal` | `boolean` | Whether the host is waiting for the final assistant response. |
+| `queuedCount` | `number` | Count of queued steer / follow-up messages. |
+| `runningTools` | `Array<{ toolCallId?: string, toolName?: string, status?: "running" \| "completed" \| "error" }>` | Running tools currently known to the host. |
+| `subagentCount` | `number?` | Count of running tools identified as subagent / delegate / spawn activity. |
+| `reason` | `string` | Diagnostic reason, such as `idle`, `main-session-active`, `session-run-active`, or `subagent-tools-running`. |
+
+### `LocalSnakeMessage`
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string?` | Message id when known. |
+| `role` | `"user" \| "assistant" \| "system" \| "toolResult" \| "tool"` | Normalized message role. |
+| `content` | `unknown` | Message content as provided by the host / runtime. |
+| `timestamp` | `number?` | Message timestamp when known. |
+| `model` | `string?` | Model id when known. |
+| `provider` | `string?` | Provider name when known. |
+| `toolCallId` | `string?` | Tool call id when known. |
+| `toolName` | `string?` | Tool name when known. |
+| `isError` | `boolean?` | Whether the message is an error result. |
+| `usage` | `unknown` | Token usage or other runtime metadata when known. |

package/README.zh-CN.md

@@ -0,0 +1,262 @@
+# LocalSnake SDK Web
+
+`localsnake-sdk-web` 是 LocalSnake 主界面应用的 JavaScript SDK。它向浏览器应用和前端框架应用暴露两个顶层对象：
+
+- `LocalSnake`：应用生命周期、Agent 对话、实时事件、工作区文件和底层 Host 请求。
+- `LocalHub`：LocalHub agent、LLM、proxy 和 WebSocket proxy API。
+
+文档：[English](README.md) | 简体中文 | [Architecture](Architecture.md)
+
+## 安装
+
+```bash
+npm install localsnake-sdk-web
+```
+
+浏览器 bundle：
+
+```html
+<script src="https://cdn.example.com/localsnake-sdk-web.min.js"></script>
+```
+
+## 快速开始
+
+```ts
+import { LocalSnake } from 'localsnake-sdk-web';
+
+const context = await LocalSnake.init();
+console.log(context.agentId, context.sessionKey);
+
+LocalSnake.onEvent((event) => {
+  if (event.type === 'runtime_status') {
+    console.log(event.payload.status, event.payload.activityType);
+  }
+});
+
+await LocalSnake.sendMessage('帮我查一下今天的安排');
+```
+
+## 浏览器使用
+
+```html
+<script src="https://cdn.example.com/localsnake-sdk-web.min.js"></script>
+<script>
+  const { LocalSnake, LocalHub } = window;
+
+  LocalSnake.onEvent((event) => {
+    if (event.type === 'runtime_status') {
+      console.log(event.payload.status, event.payload.activityType);
+    }
+  });
+
+  LocalSnake.init((context) => {
+    console.log('LocalSnake app context', context);
+  });
+
+  async function ask(text) {
+    await LocalSnake.sendMessage(text);
+  }
+
+  async function listModels() {
+    return LocalHub.llm.request('/v1/models');
+  }
+</script>
+```
+
+## 模块化使用
+
+```ts
+import { LocalSnake, LocalHub } from 'localsnake-sdk-web';
+
+LocalSnake.onEvent((event) => {
+  console.log(event.type, event.payload);
+});
+
+await LocalSnake.init();
+await LocalSnake.sendMessage('帮我查一下今天的安排');
+
+const metadata = await LocalSnake.workspace.readJson('works/montage/knowledge/metadata.json');
+const models = await LocalHub.llm.request('/v1/models');
+```
+
+默认导入返回 `LocalSnake`：
+
+```ts
+import LocalSnake from 'localsnake-sdk-web';
+```
+
+## 生命周期
+
+| API | 触发时机 | 回调参数 | 典型用途 |
+| --- | --- | --- | --- |
+| `LocalSnake.init(handler?)` | 页面 load 后完成 Host `app.init` 握手。若 WebView 已可见，初始化后会回放 `onShow()`。 | `LocalSnakeAppContext` | 读取当前 Agent、会话、工作区并初始化应用。 |
+| `LocalSnake.onShow(handler)` | WebView 首次显示或从隐藏状态恢复。 | 无 | 恢复动画、渲染、轮询或可见状态同步。 |
+| `LocalSnake.onHide(handler)` | WebView 隐藏。 | 无 | 暂停动画、渲染或高成本计算。 |
+| `LocalSnake.onDestroy(handler)` | WebView 卸载、分离或切换应用 / Agent / 页面。 | 无 | 清理定时器、WebGL、音频和订阅。 |
+
+生命周期回调不会通过公开的 `LocalSnake.onEvent()` 投递。
+
+## 常用 API
+
+| API | 返回值 | 说明 |
+| --- | --- | --- |
+| `LocalSnake.onEvent(handler)` | `() => void` | 订阅非生命周期实时 Host 事件。SDK 可能回放最新 `runtime_status`，避免应用错过初始状态。 |
+| `LocalSnake.sendMessage(text, options?)` | `Promise<unknown>` | 向当前打开会话发送用户消息。传入 `options.sessionKey` 可指定目标会话。 |
+| `LocalSnake.getHistory()` | 暂不支持 | 预留给未来显式历史 API。 |
+| `LocalSnake.workspace.readText(path)` | `Promise<string \| null>` | 读取当前 Agent 工作区下的 UTF-8 文本文件。文件不存在返回 `null`。 |
+| `LocalSnake.workspace.readJson<T>(path)` | `Promise<T \| null>` | 读取并解析当前 Agent 工作区下的 JSON 文件。文件不存在返回 `null`，JSON 非法则 reject。 |
+| `LocalSnake.workspace.writeText(path, content)` | `Promise<{ path: string, success: boolean, error?: string }>` | 写入当前 Agent 工作区下的 UTF-8 文本文件。父目录由 Host 创建。 |
+| `LocalSnake.workspace.writeJson(path, value)` | `Promise<{ path: string, success: boolean, error?: string }>` | 使用两个空格格式化 JSON 后写入当前 Agent 工作区。 |
+| `LocalSnake.request(method, payload?)` | `Promise<T>` | 底层请求入口。常规场景优先使用封装 API。 |
+| `LocalHub.request(pathOrRequest, init?)` | `Promise<LocalSnakeLocalHubResponse>` | 底层 LocalHub 代理入口。优先使用 `LocalHub.agent`、`LocalHub.llm`、`LocalHub.proxy`。 |
+
+## 发送消息
+
+```ts
+await LocalSnake.sendMessage('Summarize this workspace');
+
+await LocalSnake.sendMessage('Send this to a child session', {
+  sessionKey: 'session-key',
+});
+```
+
+如果不传 `sessionKey`，LocalSnake 会把消息发送到当前激活会话。
+
+## 工作区文件
+
+`LocalSnake.workspace` 的访问范围由 `init()` 返回的当前 Agent 工作区决定。路径必须是相对工作区路径，例如 `works/montage/knowledge/metadata.json`；Host 会拒绝绝对路径、空路径、空字节和 `..` 越界路径。
+
+```ts
+const index = await LocalSnake.workspace.readJson('works/montage/knowledge/metadata.json');
+await LocalSnake.workspace.writeJson('works/montage/knowledge/metadata.json', {
+  schema_version: 1,
+  kind: 'dreamer.knowledge.index',
+  updated_at: new Date().toISOString(),
+  projects: index?.projects ?? [],
+});
+```
+
+## LocalHub
+
+`LocalHub` 按 LocalHub 的三个公开路由域拆分：
+
+| API | 路由前缀 | 用途 |
+| --- | --- | --- |
+| `LocalHub.agent.request(pathOrRequest, init?)` | `/agent/*` | LocalHub 管理、搜索桥接和 evolution API。 |
+| `LocalHub.llm.request(pathOrRequest, init?)` | `/llm/*` | LLM 代理调用，包括 OpenAI 兼容和 Anthropic 兼容路由。 |
+| `LocalHub.proxy.request(pathOrRequest, init?)` | `/proxy/*` | 调用 LocalHub 中配置的 HTTP 请求代理。 |
+| `LocalHub.proxy.route(routes)` | `/agent/proxies` | 覆盖系统 LocalHub Key 的请求代理路由配置。传 `[]` 可清空。 |
+| `LocalHub.proxy.websocket(pathOrRequest, options?)` | `/proxy/*` | 调用 LocalHub 中配置的 WebSocket 请求代理。 |
+
+LocalSnake 会在后台提供 LocalHub base URL，并把已配置的 `localHubApiKey` 注入为 `Authorization: Bearer <key>`。应用不应该读取、保存或传递 `localHubApiKey`。
+
+```ts
+await LocalHub.agent.request('/initialized');
+await LocalHub.llm.request('/v1/models');
+
+const res = await LocalHub.proxy.request('/orders/42', {
+  method: 'POST',
+  body: { status: 'paid' },
+});
+```
+
+请求代理路由可以通过语义化 helper 替换。LocalHub 管理端点是 `/agent/proxies`，但 SDK 暴露在 `LocalHub.proxy.route()` 下，因为它配置的是运行时 `/proxy/*` 路由。
+
+```ts
+await LocalHub.proxy.route([
+  {
+    name: 'orders',
+    protocol: 'http',
+    path: '/proxy/orders/*',
+    targetUrl: 'https://api.example.com/orders',
+    headers: { Authorization: 'Bearer upstream-token' },
+  },
+]);
+
+await LocalHub.proxy.route([]);
+```
+
+WebSocket 请求代理通过一个轻量的类浏览器对象暴露。它由 Host bridge 承载，因此 LocalSnake 可以在 LocalHub 握手阶段附加所需的 Authorization 头。
+
+```ts
+const socket = LocalHub.proxy.websocket('/events');
+
+socket.onopen = () => socket.send('hello');
+socket.onmessage = (event) => {
+  console.log(event.data);
+};
+socket.onclose = (event) => {
+  console.log(event.code, event.reason);
+};
+```
+
+## 实时事件契约
+
+`LocalSnake.onEvent()` 接收单个事件对象：
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `type` | `string` | 事件类型。 |
+| `timestamp` | `number` | Host 侧毫秒时间戳。 |
+| `payload` | `object` | 事件载荷，结构取决于 `type`。 |
+
+`LocalSnake.onEvent()` 事件是自包含的，不包含 `LocalSnakeAppContext`；Agent、会话和工作区信息请从 `init()` 读取。
+
+| 事件类型 | 来源 | Payload | 说明 |
+| --- | --- | --- | --- |
+| `user_message` | OpenClaw session | `{ message: LocalSnakeMessage }` | 当前打开会话收到实时用户消息。 |
+| `assistant_delta` | OpenClaw stream | `{ text: string, message?: LocalSnakeMessage, runId?: string \| null }` | 实时 assistant 文本增量。只追加到当前 message / run。 |
+| `assistant_message` | OpenClaw session | `{ message: LocalSnakeMessage }` | assistant 最终消息。 |
+| `tool_call` | OpenClaw tool call | `{ toolCallId?: string, toolName?: string, input?: unknown, status?: "running" \| "completed" \| "error" }` | 工具调用事件，不应拼进 assistant 文本。 |
+| `tool_result` | OpenClaw tool result | `{ toolCallId?: string, toolName?: string, result?: unknown, text?: string, isError?: boolean }` | 工具响应 / 结果事件。流式工具输出可能产生多个结果事件。 |
+| `send_message` | SDK / AppManager | `{ text: string, sessionKey?: string \| null }` | 嵌入应用通过 `LocalSnake.sendMessage()` 提交用户消息。 |
+| `runtime_status` | AppManager | `LocalSnakeRuntimeStatus` | 当前会话运行状态。建议优先用它做场景 / 状态映射。 |
+
+## 类型说明
+
+### `LocalSnakeAppContext`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `app` | `"LocalSnake"` | Host 应用名。 |
+| `platform` | `"desktop" \| "mobile" \| "unknown"` | Host 平台。 |
+| `bridge` | `"electron-webview" \| "ios-webkit" \| "android-webview" \| "react-native-webview" \| "webview2" \| "post-message" \| "unknown"` | JS bridge 类型。 |
+| `agentId` | `string \| null` | 当前 Agent id。 |
+| `sessionKey` | `string \| null` | 当前打开会话 key。 |
+| `workspacePath` | `string \| null` | 当前 Agent 工作区路径。 |
+| `visibilityState` | `"visible" \| "hidden"` | init 时 WebView 可见状态。 |
+| `capabilities.chat` | `boolean` | 是否支持 `sendMessage`。 |
+| `capabilities.history` | `boolean` | 当前为 `false`；SDK Web 暂不暴露历史。 |
+| `capabilities.localHub` | `boolean` | 是否支持 LocalHub 代理 API。 |
+| `capabilities.workspace` | `boolean` | 是否支持当前 Agent 工作区文件 API。 |
+| `capabilities.events` | `string[]` | Host 可能通过 `onEvent()` 发出的非生命周期事件类型。 |
+
+### `LocalSnakeRuntimeStatus`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `status` | `"idle" \| "working" \| "subagent"` | 粗粒度运行状态。普通主进程工具调用保持 `working`；`subagent` 表示子 Agent 协调中。 |
+| `activityType` | `"idle" \| "message" \| "tool" \| "subagent" \| "queued" \| "thinking"` | 更具体的活动类型，适合 UI 状态映射。 |
+| `sessionKey` | `string \| null \| undefined` | 当前会话 key。 |
+| `activeRunId` | `string \| null \| undefined` | 已知的当前 runtime run id。 |
+| `sending` | `boolean` | 当前会话是否被认为正在运行。 |
+| `pendingFinal` | `boolean` | Host 是否正在等待最终 assistant 响应。 |
+| `queuedCount` | `number` | 排队中的 steer / follow-up 消息数量。 |
+| `runningTools` | `Array<{ toolCallId?: string, toolName?: string, status?: "running" \| "completed" \| "error" }>` | Host 已知的运行中工具。 |
+| `subagentCount` | `number?` | 被识别为 subagent / delegate / spawn 的运行中工具数量。 |
+| `reason` | `string` | 诊断原因，例如 `idle`、`main-session-active`、`session-run-active` 或 `subagent-tools-running`。 |
+
+### `LocalSnakeMessage`
+
+| 字段 | 类型 | 说明 |
+| --- | --- | --- |
+| `id` | `string?` | 已知的消息 id。 |
+| `role` | `"user" \| "assistant" \| "system" \| "toolResult" \| "tool"` | 标准化消息角色。 |
+| `content` | `unknown` | Host / runtime 提供的消息内容。 |
+| `timestamp` | `number?` | 已知的消息时间戳。 |
+| `model` | `string?` | 已知的模型 id。 |
+| `provider` | `string?` | 已知的 Provider 名称。 |
+| `toolCallId` | `string?` | 已知的工具调用 id。 |
+| `toolName` | `string?` | 已知的工具名称。 |
+| `isError` | `boolean?` | 是否为错误结果。 |
+| `usage` | `unknown` | 已知的 token usage 或其它 runtime 元数据。 |

package/dist/index.cjs

@@ -0,0 +1,2 @@
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const k="localsnake.sdk-web",M=1,U=2e3;function B(){return typeof window>"u"?null:window}function j(){const n=typeof crypto<"u"&&"randomUUID"in crypto?crypto.randomUUID():Math.random().toString(36).slice(2);return`sdkweb_${Date.now().toString(36)}_${n}`}function V(n){return!!(n&&typeof n=="object"&&n.channel===k&&n.protocol===M)}function q(n){if(typeof n=="string")try{return q(JSON.parse(n))}catch{return null}return V(n)?n:null}function J(n){return n?n.LocalSnakeAppManager?.postMessage?n.LocalSnakeAppManager.platform==="electron-webview"?"electron-webview":"android-webview":n.webkit?.messageHandlers?.LocalSnakeAppManager?.postMessage?"ios-webkit":n.ReactNativeWebView?.postMessage?"react-native-webview":n.chrome?.webview?.postMessage?"webview2":n.parent&&n.parent!==n?"post-message":"unknown":"unknown"}class m{constructor(){this.pending=new Map,this.eventHandlers=new Set,this.recentEventKeys=new Map,this.handleWindowMessage=e=>{this.handleIncoming(e.data)},this.handleCustomMessage=e=>{this.handleIncoming(e.detail)},this.handleWebView2Message=e=>{this.handleIncoming(e.data)},this.win=B(),this.platform=J(this.win),this.attachListeners()}dispose(){if(this.win){this.win.removeEventListener("message",this.handleWindowMessage),this.win.removeEventListener("localsnake-app-manager-message",this.handleCustomMessage),this.win.chrome?.webview?.removeEventListener?.("message",this.handleWebView2Message);for(const e of this.pending.values())clearTimeout(e.timeout),e.retry&&clearInterval(e.retry),e.reject(new Error("LocalSnake transport disposed"));this.pending.clear(),this.eventHandlers.clear(),this.recentEventKeys.clear()}}onEvent(e){return this.eventHandlers.add(e),()=>this.eventHandlers.delete(e)}request(e,t,r=3e4){const o=j(),a={channel:k,protocol:M,id:o,type:"request",method:e,payload:t};return new Promise((u,h)=>{const c=setTimeout(()=>{const l=this.pending.get(o);l?.retry&&clearInterval(l.retry),this.pending.delete(o),h(new Error(`LocalSnake AppManager request timed out: ${e}`))},r),d=e==="app.init"?setInterval(()=>{if(this.pending.has(o))try{this.post(a)}catch{}},800):void 0;this.pending.set(o,{resolve:l=>u(l),reject:h,timeout:c,retry:d});try{this.post(a)}catch(l){clearTimeout(c),d&&clearInterval(d),this.pending.delete(o),h(l)}})}attachListeners(){this.win&&(this.win.addEventListener("message",this.handleWindowMessage),this.win.addEventListener("localsnake-app-manager-message",this.handleCustomMessage),this.win.chrome?.webview?.addEventListener?.("message",this.handleWebView2Message))}post(e){const t=this.win;if(!t)throw new Error("LocalSnake SDK Web requires a browser window");if(t.LocalSnakeAppManager?.postMessage){t.LocalSnakeAppManager.postMessage(e);return}if(t.webkit?.messageHandlers?.LocalSnakeAppManager?.postMessage){t.webkit.messageHandlers.LocalSnakeAppManager.postMessage(e);return}if(t.ReactNativeWebView?.postMessage){t.ReactNativeWebView.postMessage(JSON.stringify(e));return}if(t.chrome?.webview?.postMessage){t.chrome.webview.postMessage(e);return}if(t.parent&&t.parent!==t){t.parent.postMessage(e,"*");return}throw new Error("LocalSnake AppManager bridge is not available")}handleIncoming(e){const t=q(e);if(t){if(t.type==="response"){this.handleResponse(t);return}t.type==="event"&&(t.event.type==="localhub.websocket"||!this.isDuplicateEvent(t))&&this.handleEvent(t)}}isDuplicateEvent(e){const t=Date.now();for(const[o,a]of this.recentEventKeys)t-a>U&&this.recentEventKeys.delete(o);const r=JSON.stringify(e.event);return this.recentEventKeys.has(r)?!0:(this.recentEventKeys.set(r,t),!1)}handleResponse(e){const t=this.pending.get(e.id);if(!t)return;if(clearTimeout(t.timeout),t.retry&&clearInterval(t.retry),this.pending.delete(e.id),e.ok){t.resolve(e.result);return}const r=e.error?.message||"LocalSnake AppManager request failed",o=new Error(r);e.error?.code&&Object.defineProperty(o,"code",{value:e.error.code,enumerable:!0}),t.reject(o)}handleEvent(e){for(const t of[...this.eventHandlers])try{t(e.event)}catch{}}}const x=0,E=1,L=2,y=3;function A(n,e){return typeof n=="string"?{path:n,...e}:{...n,...e,path:n.path}}function z(n,e){const t=`/${n}`,r=e.trim();return r?r===t||r.startsWith(`${t}/`)?r:`${t}${r.startsWith("/")?r:`/${r}`}`:t}function O(n,e,t){const r=A(e,t);return{...r,path:z(n,r.path)}}function f(n){return typeof n=="string"&&n.trim()?n.trim():void 0}function G(n){if(!n||typeof n!="object"||Array.isArray(n))return;const e={};for(const[t,r]of Object.entries(n)){if(typeof r!="string")continue;const o=t.trim();o&&(e[o]=r.trim())}return Object.keys(e).length>0?e:void 0}function T(n,e){if(!n||typeof n!="object"||Array.isArray(n))throw new Error(`LocalHub proxy route at index ${e} must be an object`);const t=n,r=f(t.name),o=f(t.path),a=f(t.targetUrl);if(!r)throw new Error(`LocalHub proxy route at index ${e} requires name`);if(!o)throw new Error(`LocalHub proxy route at index ${e} requires path`);if(!a)throw new Error(`LocalHub proxy route at index ${e} requires targetUrl`);const u=f(t.protocol);if(u&&u!=="http"&&u!=="websocket")throw new Error(`LocalHub proxy route at index ${e} protocol must be http or websocket`);const h=u,c=f(t.id),d=f(t.targetPath),l=G(t.headers);return{...c?{id:c}:{},...h?{protocol:h}:{},name:r,path:o,targetUrl:a,...d?{targetPath:d}:{},...l?{headers:l}:{}}}function F(n){if(!Array.isArray(n))throw new Error("LocalHub.proxy.route expects a routes array");return n.map((e,t)=>T(e,t))}function N(n){return n.json&&typeof n.json=="object"?n.json:{}}function Q(n){const e=N(n).data;if(!e||typeof e!="object"||Array.isArray(e))return[];const t=e.proxies;return Array.isArray(t)?t.map((r,o)=>T(r,o)):[]}function X(n){const e=N(n),t=typeof e.msg=="string"?e.msg:void 0,r=n.ok&&(e.code===void 0||e.code===0);return{ok:r,status:n.status,routes:r?Q(n):[],...t?{message:t}:{},...r?{}:{error:n.error||t||`HTTP ${n.status}`}}}function Y(){const n=typeof crypto<"u"&&"randomUUID"in crypto?crypto.randomUUID():Math.random().toString(36).slice(2);return`localhub_ws_${Date.now().toString(36)}_${n}`}function Z(n){if(typeof n=="string")return{data:n,binary:!1,encoding:"text"};const e=n instanceof Uint8Array?n:new Uint8Array(n);let t="";for(let r=0;r<e.length;r+=1)t+=String.fromCharCode(e[r]);return{data:btoa(t),binary:!0,encoding:"base64"}}function ee(n){if(!n.binary)return n.data;const e=atob(n.data),t=new Uint8Array(e.length);for(let r=0;r<e.length;r+=1)t[r]=e.charCodeAt(r);return t.buffer}class te{constructor(e,t,r){this.transport=e,this.socketId=Y(),this.CONNECTING=x,this.OPEN=E,this.CLOSING=L,this.CLOSED=y,this.listeners={open:new Set,message:new Set,error:new Set,close:new Set},this.unsubscribe=null,this.state=x,this.activeProtocol="",this.onopen=null,this.onmessage=null,this.onerror=null,this.onclose=null,this.unsubscribe=this.transport.onEvent(o=>{o.type==="localhub.websocket"&&o.payload.socketId===this.socketId&&this.handleBridgeEvent(o.payload)}),this.transport.request("localhub.websocket.open",{socketId:this.socketId,request:t,options:r}).catch(o=>{const a=o instanceof Error?o.message:String(o);this.emit("error",{type:"error",error:a}),this.finishClose(1006,a,!1)})}get readyState(){return this.state}get protocol(){return this.activeProtocol}addEventListener(e,t){this.listeners[e].add(t)}removeEventListener(e,t){this.listeners[e].delete(t)}async send(e){if(this.state!==E)throw new Error("LocalHub WebSocket is not open");await this.transport.request("localhub.websocket.send",{socketId:this.socketId,...Z(e)})}async close(e=1e3,t=""){this.state===L||this.state===y||(this.state=L,await this.transport.request("localhub.websocket.close",{socketId:this.socketId,code:e,reason:t}))}handleBridgeEvent(e){if(e.event==="open"){this.state=E,this.activeProtocol=e.protocol??"",this.emit("open",{type:"open",protocol:this.activeProtocol});return}if(e.event==="message"){this.emit("message",{type:"message",data:ee(e)});return}if(e.event==="error"){this.emit("error",{type:"error",error:e.error});return}this.finishClose(e.code,e.reason,e.wasClean)}finishClose(e,t,r){this.state!==y&&(this.state=y,this.unsubscribe?.(),this.unsubscribe=null,this.emit("close",{type:"close",code:e,reason:t,wasClean:r}))}emit(e,t){e==="open"&&this.onopen?.(t),e==="message"&&this.onmessage?.(t),e==="error"&&this.onerror?.(t),e==="close"&&this.onclose?.(t);for(const r of[...this.listeners[e]])r(t)}}class C{constructor(e,t){this.transport=e,this.domain=t}request(e,t){return this.transport.request("localhub.request",O(this.domain,e,t))}}class ne extends C{constructor(e){super(e,"agent")}}class re extends C{constructor(e){super(e,"proxy")}async route(e){const t=await this.transport.request("localhub.request",{path:"/agent/proxies",method:"PUT",body:{proxies:F(e)}});return X(t)}websocket(e,t){const r=O("proxy",e);return new te(this.transport,r,t)}}class b{constructor(e){this.transport=e,this.agent=new ne(e),this.llm=new C(e,"llm"),this.proxy=new re(e)}request(e,t){return this.transport.request("localhub.request",A(e,t))}}function se(n=new m){return new b(n)}const oe=100;function P(){return typeof document>"u"||document.readyState==="complete"?Promise.resolve():new Promise(n=>{if(typeof window<"u"){window.addEventListener("load",()=>n(),{once:!0});return}const e=()=>{document.readyState==="complete"&&(document.removeEventListener("readystatechange",e),n())};document.addEventListener("readystatechange",e)})}function p(n){Promise.resolve(n()).catch(()=>{})}function ie(n){const{context:e,...t}=n;return t}function W(n={}){const e=n.transport??new m,t=n.LocalHub??new b(e),r=new Set,o={show:new Set,hide:new Set,destroy:new Set},a=[];let u=null,h=null,c=null,d=!1,l=null;const D=()=>{a.length=0,u=null,h=null,c=null,d=!1},R=s=>{a.push(s),a.length>oe&&a.shift()},S=s=>{if(s.phase==="show"){if(c===!0)return;c=!0;for(const i of[...o.show])p(i);return}if(s.phase==="hide"){if(c===!1)return;c=!1;for(const i of[...o.hide])p(i);return}if(s.phase==="destroy"){if(l)return;l=s;for(const i of[...o.destroy])p(i);D();return}},$=s=>{if(!(d||!(s.visibilityState==="visible"||s.visibilityState==null&&c!==!1))){d=!0,c=!0;for(const g of[...o.show])p(g)}};e.onEvent(s=>{if(s.type==="lifecycle"){S(s.payload);return}if(s.type==="localhub.websocket")return;const i=ie(s);R(i);for(const g of[...r])try{g(i)}catch{}});const K=()=>(u||(u=P().then(()=>e.request("app.init",{sdkPlatform:e.platform})).then(s=>(h=s,s))),u),v=(s,i)=>(o[s].add(i),(s==="show"&&c===!0||s==="hide"&&c===!1||s==="destroy"&&l)&&p(i),()=>o[s].delete(i));return typeof window<"u"&&(window.addEventListener("pagehide",()=>{S({phase:"destroy",reason:"pagehide"})}),window.addEventListener("beforeunload",()=>{S({phase:"destroy",reason:"beforeunload"})})),{LocalHub:t,workspace:{readText:async s=>{const i=await e.request("workspace.readText",{path:s});return typeof i.content=="string"?i.content:null},readJson:async s=>{const i=await e.request("workspace.readText",{path:s});return typeof i.content!="string"?null:JSON.parse(i.content)},writeText:(s,i)=>e.request("workspace.writeText",{path:s,content:i}),writeJson:(s,i)=>e.request("workspace.writeText",{path:s,content:`${JSON.stringify(i,null,2)}
+`})},init:async s=>{await P();const i=h??await K();return s&&await s(i),$(i),i},onShow:s=>v("show",s),onHide:s=>v("hide",s),onDestroy:s=>v("destroy",s),onEvent:s=>{r.add(s);for(const i of a)try{s(i)}catch{}return()=>r.delete(s)},sendMessage:(s,i)=>e.request("chat.sendMessage",{text:s,options:i}),getHistory:()=>e.request("chat.getHistory"),request:(s,i)=>e.request(s,i)}}const _=new m,H=new b(_),I=W({transport:_,LocalHub:H}),w=typeof window<"u"?window:void 0;w&&(w.LocalSnake||(w.LocalSnake=I),w.LocalHub||(w.LocalHub=H));exports.LocalHub=H;exports.LocalSnake=I;exports.LocalSnakeLocalHubClient=b;exports.LocalSnakeTransport=m;exports.SDK_WEB_CHANNEL=k;exports.SDK_WEB_PROTOCOL_VERSION=M;exports.createLocalHubClient=se;exports.createLocalSnakeClient=W;exports.default=I;