lsagent-sdk 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 LSAgent Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,316 @@
+# lsagent-sdk — 让你的网页使用用户本机的 AI
+
+> 浏览器 JS SDK。你的网页通过它连接跑在用户自己电脑上的 AI 运行时
+> [lsagent](https://www.npmjs.com/package/lsagent)：用户在页面上传提单 / 发票 / 客户消息，
+> AI 在用户本机解析成结构化字段回填表单；也能让 AI 读用户的邮箱。
+> 业务系统**零后端改造**——文件不用传到服务器，模型密钥不用你代管。
+
+```text
+你的网页 ── lsagent-sdk（WebSocket，首次系统确认一次）──> 用户电脑上的 lsagent ──> 模型 API / 本机文件 / 邮箱
+                                                        │
+                                            只监听 ws://127.0.0.1:37700/ws
+```
+
+典型场景：补料 / 单证 AI 导入、客户消息抽取建单、发票识别、邮件内容提取等——
+一切"AI 处理用户自己电脑上的东西"的需求。
+
+## 与 lsagent 配合使用
+
+[lsagent](https://www.npmjs.com/package/lsagent)（npm 包）与 lsagent-sdk 是一对，各装一端：
+
+| 端 | 安装 | 角色 |
+| --- | --- | --- |
+| **用户的电脑** | `npm i -g lsagent`，运行 `lsagent` | AI 运行时：连模型 API、读本机文件、收发邮件、执行任务；只监听 `ws://127.0.0.1:37700/ws` |
+| **你的网页** | `npm i lsagent-sdk` | 遥控器：WebSocket 连接 + 认证 + 任务/事件 API |
+
+**用户侧一次性准备**（你的页面可以引导完成）：
+
+1. 安装 [Node.js](https://nodejs.org) ≥ 20 → `npm i -g lsagent` → 终端运行 `lsagent`（前台常驻；开机自启自行加系统启动项）。
+2. **无需配对码、无需配白名单**：网页不带配对码连接时，用户电脑上会弹一次系统确认框，
+   点"是"后你的网站即持久授权、以后无感直连（用户可用 `lsagent --disallow-origin` 撤销）。
+   localhost 开发环境同样只弹一次。
+3. 模型配置（API key + provider）：用户手改两个 JSON 文件（格式见 lsagent README），
+   **或完全由你的网页引导完成**（见下方「第 1 层」的 `saveProvider()`，推荐）。
+
+**连接握手时序**（免码模式）：
+
+```text
+connect() ──> connecting ──> pending（用户电脑弹系统确认框，onState 可感知）
+   ──用户点「是」──> authed（此后刷新页面 / 重启浏览器无感直连）
+```
+
+**lsagent 没在运行的判别**：`waitForAuthed()` 超时返回 `false` 且 `getLastError()` 含
+`code=1006`（连不上）——此时页面应出安装引导（指到
+[lsagent README](https://www.npmjs.com/package/lsagent)），用户装好后再 `connect()` 重试。
+
+**兼容性**：免码确认制需 lsagent ≥ 0.1.2（更早版本会按配对码错误拒绝免码连接）；
+配对码模式任意版本可用。`npm i -g lsagent` 默认装最新版，一般无需关心。
+
+**授权管理命令**（在用户电脑执行，可写进你的用户帮助文档）：
+
+```bash
+lsagent --show-code                                 # 查看 6 位配对码（配对码模式用）
+lsagent --list-origins                              # 查看白名单与确认授权
+lsagent --allow-origin https://crm.example.com      # 手动放行你的网站（免弹窗）
+lsagent --disallow-origin https://crm.example.com   # 撤销授权（下次连接重新弹窗确认）
+```
+
+## 安装
+
+**方式一：script 标签**（零构建；从本包拷 `dist/lsagent-sdk.js` 到你的 public/，或用 CDN）
+
+```html
+<script src="lsagent-sdk.js"></script>
+<!-- CDN：<script src="https://unpkg.com/lsagent-sdk/dist/lsagent-sdk.js"></script> -->
+<script>
+  const client = new LsagentSDK.LsagentClient(); // 免码模式：首次弹系统确认，一次点击永久授权
+</script>
+```
+
+**方式二：npm / ESM**
+
+```bash
+npm i lsagent-sdk
+```
+
+```ts
+import { LsagentClient } from "lsagent-sdk";
+```
+
+## 快速上手
+
+```ts
+const client = new LsagentClient(); // 免码模式（推荐）：首次连接弹系统确认框，用户点一次"是"即永久授权
+
+client.onState((s) => {
+  console.log("连接状态:", s);        // disconnected|connecting|connected|pending|authed
+  if (s === "pending") showHint("请在弹出的系统确认框上点【是】");
+});
+client.connect();
+await client.waitForAuthed(120_000);                          // 首次要留时间等用户点确认；false = lsagent 未运行
+
+// 创建并执行一个任务（firstMessage 立即开始；模型建议显式指定，见「第 1 层」）
+const task = await client.createTask({
+  title: "整理今日邮件摘要",
+  provider: "deepseek", modelId: "deepseek-chat",              // 用户已配置的模型
+  firstMessage: "把今天收到的邮件整理成摘要表格发给我",
+  systemPromptAppend: "输出使用简体中文。",                      // 可选：业务背景/输出约定
+  mcpServers: ["crm-tools"],                                  // 可选：只接入业务系统自己的 MCP 工具
+});
+
+// 实时进度（事件全量广播，按 taskId 过滤）
+client.onEvent((event, payload) => {
+  if (payload.taskId !== task.id) return;
+  if (event === "task.delta") appendStream(payload.text);     // 流式文本
+  if (event === "task.status") onDone(payload.status);        // idle|running|error
+});
+
+// 追问 / 控制
+await client.prompt(task.id, "再按发件人分组");
+await client.steer(task.id, "改成按主题分组");                  // 执行中插入转向
+await client.abort(task.id);                                  // 中止
+
+// 文件：先落到用户本机，AI 才能读（≤20MB）
+const buf = await file.arrayBuffer();
+const { path } = await client.request("fs.saveUpload", {
+  name: file.name,
+  bytesBase64: arrayBufferToBase64(buf),                      // FileReader.readAsDataURL 后取逗号后一段也行
+});
+
+// 查询
+const models = await client.listModels();
+const messages = await client.getMessages(task.id);
+```
+
+完整可跑示例见 `demo/`（`npm run demo` 后开 http://127.0.0.1:4567）。
+
+## API
+
+| 成员 | 说明 |
+| --- | --- |
+| `new LsagentClient({ url?, pairingCode? })` | `url` 缺省 `ws://127.0.0.1:37700/ws`，远程模式填 `ws://IP:37700/ws`；**不传 `pairingCode` = 免码模式**（推荐，首次系统弹窗确认一次），传则走配对码模式（要求页面是 localhost 或在白名单） |
+| `connect()` / `disconnect()` | 连接（幂等，断线自动指数退避重连）/ 主动断开 |
+| `getState()` / `onState(cb)` | 状态机：`disconnected → connecting → connected → (pending) → authed`；`pending` = 等用户在本机点确认框 |
+| `getLastError()` | 最近一次失败原因（如"等待用户在本机确认接入…"、"接入被拒绝（denied）"），UI 提示用 |
+| `waitForAuthed(timeoutMs?)` | 等待配对完成；超时返回 `false`。免码模式首次等待用户点击，建议给足超时（如 120_000） |
+| `onEvent(cb)` | 订阅事件（见下表），返回取消函数 |
+| `request(type, payload?, timeoutMs?)` | 通用透传：lsagent WS 协议全开放（`fs.*`、`email.*` 等） |
+| `createTask(opts?)` | 建任务；`firstMessage` 非空则立即执行 |
+| `prompt(taskId, text)` | 追加消息（任务空闲时触发执行；执行中会被拒，改用 `steer` 或等待） |
+| `steer(taskId, text)` / `abort(taskId)` | 执行中转向 / 中止 |
+| `listModels()` / `listTasks()` / `getMessages(taskId)` | 查询模型 / 任务列表 / 任务消息 |
+| `listProviders()` / `saveProvider(spec)` | 探测本机模型服务配置状态（`hasKey`）/ 新增更新模型服务（见「第 1 层」） |
+
+`createTask` 选项：`title`、`provider`+`modelId`（缺省用全局默认模型）、`cwd`（本机工作目录）、
+`firstMessage`、`systemPromptAppend`、`skills`、`mcpServers`（详见下节）。
+
+## 模型、提示词与能力配置（集成方必读）
+
+配置分三层，**全部经 SDK 同一条连接传输**（`createTask` 参数 + `request()` 透传），无需额外通道。
+
+### 第 1 层：模型——密钥在用户侧，选择在任务级
+
+| 关注点 | 谁负责 | 怎么做 |
+| --- | --- | --- |
+| 模型服务与 API 密钥 | **用户侧** | 配置存用户本机 `~/.lsagent/pi/`（`models.json` + `auth.json`）；业务系统可探测、可代填，但不该后端囤 key |
+| 用哪个模型跑任务 | **业务系统**（任务级指定） | `createTask({ provider, modelId })`；建议**总是显式指定**（见下方「默认模型」注意） |
+
+```ts
+const models = await client.listModels();          // available=true 的才可指定（已配凭据）
+const task = await client.createTask({
+  provider: models[0].provider, modelId: models[0].id,
+  firstMessage: "...",
+});
+```
+
+指定了用户未配置的模型会报错「模型不存在或已删除」。
+
+**首次配置引导**（用户刚装 lsagent、还没配 key 时，全部经 SDK 同一条连接完成）：
+
+```ts
+// 1. 探测：没有任何已配 key 的服务 → 页面出引导表单
+const providers = await client.listProviders();
+const unconfigured = providers.length === 0 || providers.every((p) => !p.hasKey);
+
+// 2. 用户在表单里选常见服务商预设或自填，提交时落到用户本机，保存即生效：
+await client.saveProvider({
+  name: "deepseek",                       // provider 标识（自填时自定义，如 "my-company"）
+  displayName: "DeepSeek",
+  baseUrl: "https://api.deepseek.com/v1",
+  apiType: "openai-completions",          // OpenAI 兼容端点用这个；Anthropic 兼容用 "anthropic-messages"
+  apiKey: userEnteredKey,                 // 写入用户本机 auth.json；留空 = 保留原 key
+  models: [
+    { id: "deepseek-chat", name: "DeepSeek-V3", contextWindow: 131072, maxTokens: 8192 },
+  ],
+});
+
+// 3. 复查可用性，然后显式指定模型建任务
+const models = await client.listModels();
+```
+
+常见预设速查（baseUrl + apiType）：DeepSeek `https://api.deepseek.com/v1` / `openai-completions`；
+Kimi `https://api.moonshot.cn/v1` / `openai-completions`；智谱 GLM `https://open.bigmodel.cn/api/anthropic` /
+`anthropic-messages`。模型 `contextWindow`/`maxTokens` 填服务商标称值即可，影响上下文管理。
+
+**企业统一密钥（可选）**：业务后端托管一份公司级 provider 配置，用户配对完成后页面从业务后端
+拉取并 `saveProvider` 推到用户本机——用户零配置。key 会落到用户本机明文文件（与用户自己配等价），
+是否采用由业务方自行评估。
+
+**「默认模型」注意**：全局默认模型存在用户本机 `settings.json`，新装用户大概率没设——
+所以 **SDK 建任务时总是显式传 `provider` + `modelId`**，不要依赖缺省。
+
+### 第 2 层：提示词——systemPromptAppend 是业务注入的唯一正道
+
+`createTask({ systemPromptAppend })` 把文本**追加**到系统提示之后（不替换内置工具指引），适合放：
+业务背景（"这是货代公司的订单审核系统"）、角色约定、输出格式（"结果以 JSON 返回，字段…"）、
+红线（"不要执行删除类操作"）。
+
+```ts
+const task = await client.createTask({
+  systemPromptAppend: [
+    "你是订单审核助手，操作对象是本公司的 ERP。",
+    "输出固定 JSON：{approved: boolean, reason: string}。",
+  ].join("\n"),
+  firstMessage: orderText,
+});
+```
+
+单次业务数据（订单内容等）放 `firstMessage` / `prompt()`，不要塞进系统提示。
+
+### 第 3 层：能力——Skills 与 MCP 工具
+
+任务通过参数引用能力，能力本体落在用户本机配置文件里（用户可见、可删，透明可控）：
+
+**Skills（给 AI 的操作手册/站点策略）**
+
+```ts
+// 探测用户已有的
+const local = await client.request("skills.local.list");
+
+// 推送业务系统自己的 skill（首次集成时一次即可；内容 = markdown 手册）
+await client.request("skills.local.save", {
+  name: "erp-order-guide",
+  content: "# ERP 订单审核指南\n1. 先查 ...\n2. ...",
+  origin: "业务系统名",          // 可选，标记来源方便用户辨认
+});
+
+// 任务引用（按名内联全文进系统提示）
+const task = await client.createTask({ skills: ["erp-order-guide"], firstMessage: "..." });
+```
+
+**MCP（业务系统提供给 AI 的工具，如查订单/改状态）**
+
+```ts
+// 注册业务系统自己的 MCP Server（http 型最简单：一个 URL + 鉴权头）
+await client.request("mcp.local.save", {
+  server: {
+    name: "crm-tools",
+    type: "http",
+    url: "https://crm.example.com/mcp",
+    headers: { Authorization: "Bearer <用户级token>" },
+    enabled: true,
+  },
+  origin: "业务系统名",
+});
+
+// 任务只接入指定 MCP（缺省接入用户已启用的全部）
+const task = await client.createTask({ mcpServers: ["crm-tools"], firstMessage: "..." });
+```
+
+stdio 型（`command`/`args`/`env`）也支持，但会启动用户本机进程，优先用 http 型。
+
+### 推荐的首次集成初始化流程
+
+```
+用户打开业务页面 → SDK 免码连接（onState 出现 pending 时提示用户点系统确认框，waitForAuthed 等待）
+  → request("skills.local.list") / request("mcp.local.list") 探测本系统已注册的能力
+  → 缺则推送（skills.local.save + mcp.local.save；失败不阻塞，降级为纯 systemPromptAppend）
+  → 之后每次 createTask({ systemPromptAppend, skills, mcpServers, ... })
+```
+
+能力推送是**写用户本机配置**的操作，请在页面里明示，不要静默反复写入；
+版本更新时先比对内容再决定是否覆盖。
+
+## 事件（`onEvent`）
+
+| 事件 | 载荷（均含 `taskId`） |
+| --- | --- |
+| `task.status` | `status: idle\|running\|error`，`error?` 错误描述 |
+| `task.delta` | `text` 流式增量文本 |
+| `task.message` | `message` 完整消息（role/text/usage…） |
+| `task.tool` | `phase: start\|end`、`name` 工具名 |
+| `task.usage` | `input`/`output`/`cost` 本轮用量 |
+| `task.deleted` | 任务被删除 |
+| `mail.new` | 新邮件（无 taskId） |
+
+事件为全量广播（与本机其它已配对客户端一致），业务方按 `taskId`/事件名自行过滤。
+
+## 安全模型
+
+- **免码模式 = 系统弹窗确认制**：首次连接时用户电脑弹原生确认框，点一次"是"授权即持久
+  （存 `~/.lsagent/web-grants.json`，用户可 `lsagent --disallow-origin <url>` 撤销）。
+  授权绑定来源 origin，浏览器无法伪造；点"否"只拒当次，同一网站连拒 3 次转静默拦截，
+  恶意网站无法靠反复请求轰炸用户（10 分钟内最多弹 5 次确认框）。
+- **配对码 = 完全授权**：持有配对码的页面可读本机文件、发邮件、执行任务，且要求页面
+  来源是 localhost 或用户白名单（防钓鱼页骗码直连）。只在用户明确信任的系统中使用，
+  建议用户输入而非硬编码进代码。
+- lsagent 有防爆破：同 IP 连续错 5 次锁 10 分钟；配对码 6 位、服务只监听本机回环（远程模式除外）。
+
+## 限制
+
+- 需用户电脑开机且 lsagent 在线（`onState` 可感知断线，SDK 自动重连）。
+- 来源白名单为精确匹配，暂不支持 `*.example.com` 通配。
+- 本机模式面向「用户在场」的场景；无人值守/服务端集中模式不在本 SDK 范围。
+
+## 本地开发
+
+```bash
+npm install          # 在仓库根目录（workspace）
+npm run build -w sdk     # 构建 dist（esbuild 产物 + tsc 类型声明）
+npm run demo -w sdk      # 演示页 http://127.0.0.1:4567
+npm run typecheck -w sdk
+```
+
+## 许可证
+
+[MIT](./LICENSE)

package/dist/index.d.ts

@@ -0,0 +1,130 @@
+export type LsagentState = "disconnected" | "connecting" | "connected" | "pending" | "authed";
+export interface LsagentOptions {
+    /** 伴侣应用 WS 地址，默认 ws://127.0.0.1:37700/ws（远程模式填 ws://IP:37700/ws） */
+    url?: string;
+    /** 6 位配对码（用户 `lsagent --show-code` 查看）。推荐不传——免码模式首次弹系统确认，一次点击永久授权 */
+    pairingCode?: string;
+}
+/** 公开类型自带（不依赖 @lsagent/shared）：SDK 产物零依赖，d.ts 可独立分发 */
+export interface LsagentModel {
+    provider: string;
+    id: string;
+    name: string;
+    available: boolean;
+}
+/** 本机模型服务（models.json + auth.json 合并视图；hasKey=false 表示未配密钥不可用） */
+export interface LsagentProvider {
+    name: string;
+    displayName: string;
+    baseUrl: string;
+    /** "openai-completions" | "anthropic-messages" | ... */
+    apiType: string;
+    hasKey: boolean;
+    models: {
+        id: string;
+        name: string;
+        contextWindow: number;
+        maxTokens: number;
+    }[];
+}
+/** providers.save 入参（apiKey 省略/为空 = 保留本机已有 key） */
+export interface LsagentProviderSpec {
+    name: string;
+    displayName: string;
+    baseUrl: string;
+    apiType: string;
+    apiKey?: string;
+    models: {
+        id: string;
+        name: string;
+        reasoning?: boolean;
+        contextWindow?: number;
+        maxTokens?: number;
+    }[];
+}
+export interface LsagentTask {
+    id: string;
+    title: string;
+    status: "idle" | "running" | "error";
+    model: string | null;
+    cwd: string;
+    createdAt: string;
+    messageCount: number;
+}
+export interface LsagentMessage {
+    role: "user" | "assistant" | "toolResult";
+    text: string;
+    model?: string;
+    errorMessage?: string;
+    usage?: {
+        input: number;
+        output: number;
+        cost: number;
+    };
+    timestamp: number;
+}
+export interface LsagentCreateTaskOptions {
+    title?: string;
+    /** 模型提供方 + 模型 id（缺省用伴侣应用全局默认模型；也可只建任务后用 prompt 前指定） */
+    provider?: string;
+    modelId?: string;
+    /** 工作目录（本机绝对路径，缺省为伴侣应用 workspace） */
+    cwd?: string;
+    /** 建任务后立即发送的首条消息 */
+    firstMessage?: string;
+    /** 追加到系统提示末尾（业务背景、输出格式约定等） */
+    systemPromptAppend?: string;
+    /** 按名启用的本地 skill */
+    skills?: string[];
+    /** 仅接入指定 MCP server（缺省接入全部启用的；业务系统自己的工具走这里） */
+    mcpServers?: string[];
+}
+export type LsagentEventHandler = (event: string, payload: Record<string, unknown>) => void;
+export type LsagentStateHandler = (state: LsagentState) => void;
+export declare class LsagentClient {
+    private readonly inner;
+    private stateHandler;
+    private eventHandler;
+    constructor(opts: LsagentOptions);
+    /** 建立连接（自动认证 + 断线指数退避重连；重复调用幂等） */
+    connect(): void;
+    /** 主动断开（停止重连） */
+    disconnect(): void;
+    getState(): LsagentState;
+    /** 最近一次连接/认证失败原因（诊断用）：如"等待用户在本机确认接入…"、"接入被拒绝（denied）" */
+    getLastError(): string | null;
+    /** 连接状态变化（authed = 配对成功可用；pending = 等用户在本机点系统确认框）。返回取消订阅函数 */
+    onState(cb: LsagentStateHandler): () => void;
+    /** 伴侣应用事件（全量广播，业务方按 event 名过滤）。返回取消订阅函数
+     *
+     * 常用事件（均带 taskId）：task.status（idle|running|error）、task.delta（流式文本）、
+     * task.message（完整消息）、task.tool（工具调用 start|end）、task.usage（用量）、
+     * task.deleted；另有 mail.new（新邮件） */
+    onEvent(cb: LsagentEventHandler): () => void;
+    /** 等待配对完成（connect + 轮询，超时返回 false）——页面初始化或用户点「测试连接」时用。
+     * 免码模式下用户点系统确认框可能超过默认 6s：建议先 onState 监听 pending 提示用户，
+     * 并把超时放大（如 120_000） */
+    waitForAuthed(timeoutMs?: number): Promise<boolean>;
+    /** 通用请求（伴侣应用 WS 协议全开放，如 fs.readFile / email.send / flows.list） */
+    request<T = unknown>(type: string, payload?: unknown, timeoutMs?: number): Promise<T>;
+    listModels(): Promise<LsagentModel[]>;
+    /** 本机模型服务列表（探测配置状态：全部 hasKey=false = 用户还没配过 key） */
+    listProviders(): Promise<LsagentProvider[]>;
+    /** 新增/更新模型服务（写本机 models.json + auth.json，保存即生效；apiKey 为空 = 保留原 key） */
+    saveProvider(spec: LsagentProviderSpec): Promise<{
+        name: string;
+    }>;
+    listTasks(): Promise<LsagentTask[]>;
+    getMessages(taskId: string): Promise<LsagentMessage[]>;
+    /** 建任务（firstMessage 非空则立即开始执行，进度走 task.* 事件） */
+    createTask(opts?: LsagentCreateTaskOptions): Promise<LsagentTask>;
+    /** 向任务追加消息（任务空闲时触发执行；执行中提交会被拒绝，改用 steer 或等空闲） */
+    prompt(taskId: string, text: string): Promise<{
+        queued?: boolean;
+    }>;
+    /** 任务执行中插入转向指令（不排队，下一轮生效） */
+    steer(taskId: string, text: string): Promise<unknown>;
+    /** 中止执行中的任务 */
+    abort(taskId: string): Promise<unknown>;
+}
+export default LsagentClient;

package/dist/lsagent-sdk.esm.js

@@ -0,0 +1,328 @@
+var __defProp = Object.defineProperty;
+var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+// ../shared/src/companion-client.ts
+var CompanionClient = class {
+  constructor(handlers, pairingCode, url = "ws://127.0.0.1:37700/ws", client) {
+    this.handlers = handlers;
+    this.client = client;
+    __publicField(this, "ws", null);
+    __publicField(this, "pending", /* @__PURE__ */ new Map());
+    __publicField(this, "nextId", 1);
+    __publicField(this, "reconnectTimer", null);
+    __publicField(this, "pendingRetryTimer", null);
+    __publicField(this, "backoffMs", 1e3);
+    __publicField(this, "stopped", false);
+    __publicField(this, "state", "disconnected");
+    __publicField(this, "version", null);
+    /** 最近一次连接/认证失败的原因（诊断用） */
+    __publicField(this, "lastError", null);
+    __publicField(this, "pairingCode");
+    __publicField(this, "url");
+    this.pairingCode = pairingCode;
+    this.url = url;
+  }
+  setState(state) {
+    var _a, _b;
+    this.state = state;
+    (_b = (_a = this.handlers).onStateChange) == null ? void 0 : _b.call(_a, state, this.version, this.lastError);
+  }
+  connect() {
+    this.stopped = false;
+    if (this.reconnectTimer !== null) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)) {
+      return;
+    }
+    this.setState("connecting");
+    const ws = new WebSocket(this.url);
+    this.ws = ws;
+    const isCurrent = () => this.ws === ws;
+    ws.onopen = () => {
+      if (!isCurrent()) return;
+      this.lastError = null;
+      this.setState("connected");
+      this.authenticate(ws, isCurrent);
+    };
+    ws.onmessage = (ev) => {
+      var _a, _b, _c;
+      if (!isCurrent()) return;
+      let msg;
+      try {
+        msg = JSON.parse(String(ev.data));
+      } catch (e) {
+        return;
+      }
+      if (msg.type === "event") {
+        (_c = (_b = this.handlers).onEvent) == null ? void 0 : _c.call(_b, (_a = msg.event) != null ? _a : "", msg.payload);
+        return;
+      }
+      if (msg.type === "creq") {
+        this.handleServerRequest(msg);
+        return;
+      }
+      if (msg.type !== "res") return;
+      const entry = this.pending.get(msg.id);
+      if (!entry) return;
+      this.pending.delete(msg.id);
+      clearTimeout(entry.timer);
+      if (msg.ok) entry.resolve(msg.data);
+      else entry.reject(new Error(msg.error || "\u672A\u77E5\u9519\u8BEF"));
+    };
+    ws.onclose = (ev) => {
+      if (!isCurrent()) return;
+      if (this.pendingRetryTimer !== null) {
+        clearTimeout(this.pendingRetryTimer);
+        this.pendingRetryTimer = null;
+      }
+      this.version = null;
+      this.rejectAll("\u8FDE\u63A5\u5DF2\u65AD\u5F00");
+      if (ev.code === 4003 && /denied/i.test(ev.reason)) {
+        this.stopped = true;
+        this.lastError = `\u63A5\u5165\u88AB\u62D2\u7EDD\uFF08${ev.reason}\uFF09`;
+        console.warn("[companion] \u63A5\u5165\u88AB\u62D2\u7EDD:", ev.reason);
+        this.setState("disconnected");
+        return;
+      }
+      if (!this.stopped) {
+        this.lastError = `\u8FDE\u63A5\u65AD\u5F00 (code=${ev.code}${ev.reason ? `, ${ev.reason}` : ""})\uFF0C${Math.round(this.backoffMs / 1e3)}s \u540E\u91CD\u8BD5`;
+        console.warn("[companion] onclose:", ev.code, ev.reason);
+      }
+      this.setState("disconnected");
+      if (!this.stopped) {
+        this.reconnectTimer = setTimeout(() => this.connect(), this.backoffMs);
+        this.backoffMs = Math.min(this.backoffMs * 2, 15e3);
+      }
+    };
+    ws.onerror = () => {
+      if (!isCurrent()) return;
+      this.lastError = "WebSocket \u8FDE\u63A5\u5931\u8D25\uFF08\u4F34\u4FA3\u5E94\u7528\u672A\u542F\u52A8\u6216\u7AEF\u53E3\u88AB\u5360\u7528\uFF1F\uFF09";
+      console.warn("[companion] onerror");
+    };
+  }
+  /** 发送 auth：配对码为空 = 确认制免码接入（首次由用户在服务端弹的系统确认框放行）。
+   * 服务端回 pending-confirm 表示正在等用户点击，3s 后重发 auth 探测结果——
+   * 授权落地 → authed；用户点否 → 服务端 4003 denied 断开走 onclose 致停 */
+  authenticate(ws, isCurrent) {
+    this.request(
+      "auth",
+      { ...this.pairingCode ? { code: this.pairingCode } : {}, ...this.client ? { client: this.client } : {} },
+      5e3
+    ).then((data) => {
+      var _a;
+      if (!isCurrent() || this.state === "authed") return;
+      this.version = (_a = data == null ? void 0 : data.version) != null ? _a : null;
+      this.backoffMs = 1e3;
+      this.setState("authed");
+    }).catch((err) => {
+      if (!isCurrent()) return;
+      if (err.message === "pending-confirm") {
+        this.lastError = "\u7B49\u5F85\u7528\u6237\u5728\u672C\u673A\u786E\u8BA4\u63A5\u5165\u2026";
+        this.setState("pending");
+        if (this.pendingRetryTimer !== null) clearTimeout(this.pendingRetryTimer);
+        this.pendingRetryTimer = setTimeout(() => {
+          this.pendingRetryTimer = null;
+          if (!isCurrent() || this.stopped || this.state === "authed") return;
+          this.authenticate(ws, isCurrent);
+        }, 3e3);
+        return;
+      }
+      this.lastError = `\u8BA4\u8BC1\u5931\u8D25: ${err.message}`;
+      console.warn("[companion] \u8BA4\u8BC1\u5931\u8D25:", err.message);
+      this.setState("connected");
+    });
+  }
+  disconnect() {
+    var _a;
+    this.stopped = true;
+    if (this.reconnectTimer !== null) clearTimeout(this.reconnectTimer);
+    if (this.pendingRetryTimer !== null) {
+      clearTimeout(this.pendingRetryTimer);
+      this.pendingRetryTimer = null;
+    }
+    (_a = this.ws) == null ? void 0 : _a.close();
+    this.ws = null;
+    this.rejectAll("\u5DF2\u4E3B\u52A8\u65AD\u5F00");
+    this.setState("disconnected");
+  }
+  setPairingCode(code) {
+    this.update(this.url, code);
+  }
+  /** 更新连接参数（URL/配对码未变则绝不断开现有连接——连接中反复调用只是幂等 no-op；
+   * 否则重连。配对码为空 = 免码确认制接入，与有码行为一致（并非断开）。
+   * 此前的 disconnect+connect 会让 SW 冷启动时的并发请求产生重连风暴，
+   * 旧 socket 迟到的 onclose 把状态打脏） */
+  update(url, code) {
+    const changed = url !== this.url || code !== this.pairingCode;
+    this.url = url;
+    this.pairingCode = code;
+    if (!changed) {
+      this.connect();
+      return;
+    }
+    this.disconnect();
+    this.connect();
+  }
+  /** 等待进入 authed 状态（用于点击测试/保存时确保连接完成）。
+   * 进入等待时先立即 connect()：不等退避计时——否则一次失败后 backoff 最长 15s，
+   * 6s 的等待会在退避期间白白超时（用户看到的正是"伴侣应用未连接"） */
+  async waitForAuthed(timeoutMs = 6e3) {
+    if (this.state !== "authed" && !this.stopped) this.connect();
+    const deadline = Date.now() + timeoutMs;
+    while (this.state !== "authed" && Date.now() < deadline) {
+      await new Promise((r) => setTimeout(r, 200));
+    }
+    return this.state === "authed";
+  }
+  request(type, payload, timeoutMs = 1e4) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      return Promise.reject(new Error("\u4F34\u4FA3\u5E94\u7528\u672A\u8FDE\u63A5"));
+    }
+    const id = `r${this.nextId++}`;
+    const msg = { id, type, payload };
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error("\u8BF7\u6C42\u8D85\u65F6"));
+      }, timeoutMs);
+      this.pending.set(id, { resolve, reject, timer });
+      this.ws.send(JSON.stringify(msg));
+    });
+  }
+  /** 反向请求（creq）：调 onRequest 处理并回 cres。handler 缺失/抛错都回错误，不让伴侣应用侧挂等超时 */
+  handleServerRequest(msg) {
+    const send = (ok, data, error) => {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+      try {
+        this.ws.send(JSON.stringify({ type: "cres", id: msg.id, ok, ...ok ? { data } : { error } }));
+      } catch (e) {
+      }
+    };
+    const handler = this.handlers.onRequest;
+    if (!handler) {
+      send(false, void 0, "\u8BE5\u5BA2\u6237\u7AEF\u4E0D\u652F\u6301\u6B64\u8BF7\u6C42");
+      return;
+    }
+    Promise.resolve().then(() => handler(msg.tool, msg.payload)).then((data) => send(true, data)).catch((err) => send(false, void 0, err instanceof Error ? err.message : String(err)));
+  }
+  rejectAll(reason) {
+    for (const entry of this.pending.values()) {
+      clearTimeout(entry.timer);
+      entry.reject(new Error(reason));
+    }
+    this.pending.clear();
+  }
+};
+
+// src/index.ts
+var LsagentClient = class {
+  constructor(opts) {
+    this.stateHandler = null;
+    this.eventHandler = null;
+    var _a, _b;
+    this.inner = new CompanionClient(
+      {
+        onStateChange: (state) => {
+          var _a2;
+          return (_a2 = this.stateHandler) == null ? void 0 : _a2.call(this, state);
+        },
+        onEvent: (event, payload) => {
+          var _a2;
+          return (_a2 = this.eventHandler) == null ? void 0 : _a2.call(this, event, payload != null ? payload : {});
+        }
+      },
+      (_a = opts.pairingCode) != null ? _a : "",
+      (_b = opts.url) != null ? _b : "ws://127.0.0.1:37700/ws",
+      // 身份 "sdk"：不会被伴侣应用登记为浏览器能力宿主（那是插件专用槽位）
+      "sdk"
+    );
+  }
+  /** 建立连接（自动认证 + 断线指数退避重连；重复调用幂等） */
+  connect() {
+    this.inner.connect();
+  }
+  /** 主动断开（停止重连） */
+  disconnect() {
+    this.inner.disconnect();
+  }
+  getState() {
+    return this.inner.state;
+  }
+  /** 最近一次连接/认证失败原因（诊断用）：如"等待用户在本机确认接入…"、"接入被拒绝（denied）" */
+  getLastError() {
+    return this.inner.lastError;
+  }
+  /** 连接状态变化（authed = 配对成功可用；pending = 等用户在本机点系统确认框）。返回取消订阅函数 */
+  onState(cb) {
+    this.stateHandler = cb;
+    return () => {
+      if (this.stateHandler === cb) this.stateHandler = null;
+    };
+  }
+  /** 伴侣应用事件（全量广播，业务方按 event 名过滤）。返回取消订阅函数
+   *
+   * 常用事件（均带 taskId）：task.status（idle|running|error）、task.delta（流式文本）、
+   * task.message（完整消息）、task.tool（工具调用 start|end）、task.usage（用量）、
+   * task.deleted；另有 mail.new（新邮件） */
+  onEvent(cb) {
+    this.eventHandler = cb;
+    return () => {
+      if (this.eventHandler === cb) this.eventHandler = null;
+    };
+  }
+  /** 等待配对完成（connect + 轮询，超时返回 false）——页面初始化或用户点「测试连接」时用。
+   * 免码模式下用户点系统确认框可能超过默认 6s：建议先 onState 监听 pending 提示用户，
+   * 并把超时放大（如 120_000） */
+  async waitForAuthed(timeoutMs = 6e3) {
+    return this.inner.waitForAuthed(timeoutMs);
+  }
+  /** 通用请求（伴侣应用 WS 协议全开放，如 fs.readFile / email.send / flows.list） */
+  request(type, payload, timeoutMs) {
+    return this.inner.request(type, payload, timeoutMs);
+  }
+  async listModels() {
+    const data = await this.request("models.list");
+    return data.models;
+  }
+  /** 本机模型服务列表（探测配置状态：全部 hasKey=false = 用户还没配过 key） */
+  async listProviders() {
+    const data = await this.request("providers.list");
+    return data.providers;
+  }
+  /** 新增/更新模型服务（写本机 models.json + auth.json，保存即生效；apiKey 为空 = 保留原 key） */
+  async saveProvider(spec) {
+    return this.request("providers.save", { provider: spec });
+  }
+  async listTasks() {
+    const data = await this.request("task.list");
+    return data.tasks;
+  }
+  async getMessages(taskId) {
+    const data = await this.request("task.messages", { taskId });
+    return data.messages;
+  }
+  /** 建任务（firstMessage 非空则立即开始执行，进度走 task.* 事件） */
+  async createTask(opts = {}) {
+    return this.request("task.create", opts);
+  }
+  /** 向任务追加消息（任务空闲时触发执行；执行中提交会被拒绝，改用 steer 或等空闲） */
+  async prompt(taskId, text) {
+    return this.request("task.prompt", { taskId, text });
+  }
+  /** 任务执行中插入转向指令（不排队，下一轮生效） */
+  async steer(taskId, text) {
+    return this.request("task.steer", { taskId, text });
+  }
+  /** 中止执行中的任务 */
+  async abort(taskId) {
+    return this.request("task.abort", { taskId });
+  }
+};
+var index_default = LsagentClient;
+export {
+  LsagentClient,
+  index_default as default
+};

package/dist/lsagent-sdk.js

@@ -0,0 +1,351 @@
+"use strict";
+var LsagentSDK = (() => {
+  var __defProp = Object.defineProperty;
+  var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+  var __getOwnPropNames = Object.getOwnPropertyNames;
+  var __hasOwnProp = Object.prototype.hasOwnProperty;
+  var __defNormalProp = (obj, key, value) => key in obj ? __defProp(obj, key, { enumerable: true, configurable: true, writable: true, value }) : obj[key] = value;
+  var __export = (target, all) => {
+    for (var name in all)
+      __defProp(target, name, { get: all[name], enumerable: true });
+  };
+  var __copyProps = (to, from, except, desc) => {
+    if (from && typeof from === "object" || typeof from === "function") {
+      for (let key of __getOwnPropNames(from))
+        if (!__hasOwnProp.call(to, key) && key !== except)
+          __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+    }
+    return to;
+  };
+  var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+  var __publicField = (obj, key, value) => __defNormalProp(obj, typeof key !== "symbol" ? key + "" : key, value);
+
+  // src/index.ts
+  var index_exports = {};
+  __export(index_exports, {
+    LsagentClient: () => LsagentClient,
+    default: () => index_default
+  });
+
+  // ../shared/src/companion-client.ts
+  var CompanionClient = class {
+    constructor(handlers, pairingCode, url = "ws://127.0.0.1:37700/ws", client) {
+      this.handlers = handlers;
+      this.client = client;
+      __publicField(this, "ws", null);
+      __publicField(this, "pending", /* @__PURE__ */ new Map());
+      __publicField(this, "nextId", 1);
+      __publicField(this, "reconnectTimer", null);
+      __publicField(this, "pendingRetryTimer", null);
+      __publicField(this, "backoffMs", 1e3);
+      __publicField(this, "stopped", false);
+      __publicField(this, "state", "disconnected");
+      __publicField(this, "version", null);
+      /** 最近一次连接/认证失败的原因（诊断用） */
+      __publicField(this, "lastError", null);
+      __publicField(this, "pairingCode");
+      __publicField(this, "url");
+      this.pairingCode = pairingCode;
+      this.url = url;
+    }
+    setState(state) {
+      var _a, _b;
+      this.state = state;
+      (_b = (_a = this.handlers).onStateChange) == null ? void 0 : _b.call(_a, state, this.version, this.lastError);
+    }
+    connect() {
+      this.stopped = false;
+      if (this.reconnectTimer !== null) {
+        clearTimeout(this.reconnectTimer);
+        this.reconnectTimer = null;
+      }
+      if (this.ws && (this.ws.readyState === WebSocket.OPEN || this.ws.readyState === WebSocket.CONNECTING)) {
+        return;
+      }
+      this.setState("connecting");
+      const ws = new WebSocket(this.url);
+      this.ws = ws;
+      const isCurrent = () => this.ws === ws;
+      ws.onopen = () => {
+        if (!isCurrent()) return;
+        this.lastError = null;
+        this.setState("connected");
+        this.authenticate(ws, isCurrent);
+      };
+      ws.onmessage = (ev) => {
+        var _a, _b, _c;
+        if (!isCurrent()) return;
+        let msg;
+        try {
+          msg = JSON.parse(String(ev.data));
+        } catch (e) {
+          return;
+        }
+        if (msg.type === "event") {
+          (_c = (_b = this.handlers).onEvent) == null ? void 0 : _c.call(_b, (_a = msg.event) != null ? _a : "", msg.payload);
+          return;
+        }
+        if (msg.type === "creq") {
+          this.handleServerRequest(msg);
+          return;
+        }
+        if (msg.type !== "res") return;
+        const entry = this.pending.get(msg.id);
+        if (!entry) return;
+        this.pending.delete(msg.id);
+        clearTimeout(entry.timer);
+        if (msg.ok) entry.resolve(msg.data);
+        else entry.reject(new Error(msg.error || "\u672A\u77E5\u9519\u8BEF"));
+      };
+      ws.onclose = (ev) => {
+        if (!isCurrent()) return;
+        if (this.pendingRetryTimer !== null) {
+          clearTimeout(this.pendingRetryTimer);
+          this.pendingRetryTimer = null;
+        }
+        this.version = null;
+        this.rejectAll("\u8FDE\u63A5\u5DF2\u65AD\u5F00");
+        if (ev.code === 4003 && /denied/i.test(ev.reason)) {
+          this.stopped = true;
+          this.lastError = `\u63A5\u5165\u88AB\u62D2\u7EDD\uFF08${ev.reason}\uFF09`;
+          console.warn("[companion] \u63A5\u5165\u88AB\u62D2\u7EDD:", ev.reason);
+          this.setState("disconnected");
+          return;
+        }
+        if (!this.stopped) {
+          this.lastError = `\u8FDE\u63A5\u65AD\u5F00 (code=${ev.code}${ev.reason ? `, ${ev.reason}` : ""})\uFF0C${Math.round(this.backoffMs / 1e3)}s \u540E\u91CD\u8BD5`;
+          console.warn("[companion] onclose:", ev.code, ev.reason);
+        }
+        this.setState("disconnected");
+        if (!this.stopped) {
+          this.reconnectTimer = setTimeout(() => this.connect(), this.backoffMs);
+          this.backoffMs = Math.min(this.backoffMs * 2, 15e3);
+        }
+      };
+      ws.onerror = () => {
+        if (!isCurrent()) return;
+        this.lastError = "WebSocket \u8FDE\u63A5\u5931\u8D25\uFF08\u4F34\u4FA3\u5E94\u7528\u672A\u542F\u52A8\u6216\u7AEF\u53E3\u88AB\u5360\u7528\uFF1F\uFF09";
+        console.warn("[companion] onerror");
+      };
+    }
+    /** 发送 auth：配对码为空 = 确认制免码接入（首次由用户在服务端弹的系统确认框放行）。
+     * 服务端回 pending-confirm 表示正在等用户点击，3s 后重发 auth 探测结果——
+     * 授权落地 → authed；用户点否 → 服务端 4003 denied 断开走 onclose 致停 */
+    authenticate(ws, isCurrent) {
+      this.request(
+        "auth",
+        { ...this.pairingCode ? { code: this.pairingCode } : {}, ...this.client ? { client: this.client } : {} },
+        5e3
+      ).then((data) => {
+        var _a;
+        if (!isCurrent() || this.state === "authed") return;
+        this.version = (_a = data == null ? void 0 : data.version) != null ? _a : null;
+        this.backoffMs = 1e3;
+        this.setState("authed");
+      }).catch((err) => {
+        if (!isCurrent()) return;
+        if (err.message === "pending-confirm") {
+          this.lastError = "\u7B49\u5F85\u7528\u6237\u5728\u672C\u673A\u786E\u8BA4\u63A5\u5165\u2026";
+          this.setState("pending");
+          if (this.pendingRetryTimer !== null) clearTimeout(this.pendingRetryTimer);
+          this.pendingRetryTimer = setTimeout(() => {
+            this.pendingRetryTimer = null;
+            if (!isCurrent() || this.stopped || this.state === "authed") return;
+            this.authenticate(ws, isCurrent);
+          }, 3e3);
+          return;
+        }
+        this.lastError = `\u8BA4\u8BC1\u5931\u8D25: ${err.message}`;
+        console.warn("[companion] \u8BA4\u8BC1\u5931\u8D25:", err.message);
+        this.setState("connected");
+      });
+    }
+    disconnect() {
+      var _a;
+      this.stopped = true;
+      if (this.reconnectTimer !== null) clearTimeout(this.reconnectTimer);
+      if (this.pendingRetryTimer !== null) {
+        clearTimeout(this.pendingRetryTimer);
+        this.pendingRetryTimer = null;
+      }
+      (_a = this.ws) == null ? void 0 : _a.close();
+      this.ws = null;
+      this.rejectAll("\u5DF2\u4E3B\u52A8\u65AD\u5F00");
+      this.setState("disconnected");
+    }
+    setPairingCode(code) {
+      this.update(this.url, code);
+    }
+    /** 更新连接参数（URL/配对码未变则绝不断开现有连接——连接中反复调用只是幂等 no-op；
+     * 否则重连。配对码为空 = 免码确认制接入，与有码行为一致（并非断开）。
+     * 此前的 disconnect+connect 会让 SW 冷启动时的并发请求产生重连风暴，
+     * 旧 socket 迟到的 onclose 把状态打脏） */
+    update(url, code) {
+      const changed = url !== this.url || code !== this.pairingCode;
+      this.url = url;
+      this.pairingCode = code;
+      if (!changed) {
+        this.connect();
+        return;
+      }
+      this.disconnect();
+      this.connect();
+    }
+    /** 等待进入 authed 状态（用于点击测试/保存时确保连接完成）。
+     * 进入等待时先立即 connect()：不等退避计时——否则一次失败后 backoff 最长 15s，
+     * 6s 的等待会在退避期间白白超时（用户看到的正是"伴侣应用未连接"） */
+    async waitForAuthed(timeoutMs = 6e3) {
+      if (this.state !== "authed" && !this.stopped) this.connect();
+      const deadline = Date.now() + timeoutMs;
+      while (this.state !== "authed" && Date.now() < deadline) {
+        await new Promise((r) => setTimeout(r, 200));
+      }
+      return this.state === "authed";
+    }
+    request(type, payload, timeoutMs = 1e4) {
+      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+        return Promise.reject(new Error("\u4F34\u4FA3\u5E94\u7528\u672A\u8FDE\u63A5"));
+      }
+      const id = `r${this.nextId++}`;
+      const msg = { id, type, payload };
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(new Error("\u8BF7\u6C42\u8D85\u65F6"));
+        }, timeoutMs);
+        this.pending.set(id, { resolve, reject, timer });
+        this.ws.send(JSON.stringify(msg));
+      });
+    }
+    /** 反向请求（creq）：调 onRequest 处理并回 cres。handler 缺失/抛错都回错误，不让伴侣应用侧挂等超时 */
+    handleServerRequest(msg) {
+      const send = (ok, data, error) => {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
+        try {
+          this.ws.send(JSON.stringify({ type: "cres", id: msg.id, ok, ...ok ? { data } : { error } }));
+        } catch (e) {
+        }
+      };
+      const handler = this.handlers.onRequest;
+      if (!handler) {
+        send(false, void 0, "\u8BE5\u5BA2\u6237\u7AEF\u4E0D\u652F\u6301\u6B64\u8BF7\u6C42");
+        return;
+      }
+      Promise.resolve().then(() => handler(msg.tool, msg.payload)).then((data) => send(true, data)).catch((err) => send(false, void 0, err instanceof Error ? err.message : String(err)));
+    }
+    rejectAll(reason) {
+      for (const entry of this.pending.values()) {
+        clearTimeout(entry.timer);
+        entry.reject(new Error(reason));
+      }
+      this.pending.clear();
+    }
+  };
+
+  // src/index.ts
+  var LsagentClient = class {
+    constructor(opts) {
+      this.stateHandler = null;
+      this.eventHandler = null;
+      var _a, _b;
+      this.inner = new CompanionClient(
+        {
+          onStateChange: (state) => {
+            var _a2;
+            return (_a2 = this.stateHandler) == null ? void 0 : _a2.call(this, state);
+          },
+          onEvent: (event, payload) => {
+            var _a2;
+            return (_a2 = this.eventHandler) == null ? void 0 : _a2.call(this, event, payload != null ? payload : {});
+          }
+        },
+        (_a = opts.pairingCode) != null ? _a : "",
+        (_b = opts.url) != null ? _b : "ws://127.0.0.1:37700/ws",
+        // 身份 "sdk"：不会被伴侣应用登记为浏览器能力宿主（那是插件专用槽位）
+        "sdk"
+      );
+    }
+    /** 建立连接（自动认证 + 断线指数退避重连；重复调用幂等） */
+    connect() {
+      this.inner.connect();
+    }
+    /** 主动断开（停止重连） */
+    disconnect() {
+      this.inner.disconnect();
+    }
+    getState() {
+      return this.inner.state;
+    }
+    /** 最近一次连接/认证失败原因（诊断用）：如"等待用户在本机确认接入…"、"接入被拒绝（denied）" */
+    getLastError() {
+      return this.inner.lastError;
+    }
+    /** 连接状态变化（authed = 配对成功可用；pending = 等用户在本机点系统确认框）。返回取消订阅函数 */
+    onState(cb) {
+      this.stateHandler = cb;
+      return () => {
+        if (this.stateHandler === cb) this.stateHandler = null;
+      };
+    }
+    /** 伴侣应用事件（全量广播，业务方按 event 名过滤）。返回取消订阅函数
+     *
+     * 常用事件（均带 taskId）：task.status（idle|running|error）、task.delta（流式文本）、
+     * task.message（完整消息）、task.tool（工具调用 start|end）、task.usage（用量）、
+     * task.deleted；另有 mail.new（新邮件） */
+    onEvent(cb) {
+      this.eventHandler = cb;
+      return () => {
+        if (this.eventHandler === cb) this.eventHandler = null;
+      };
+    }
+    /** 等待配对完成（connect + 轮询，超时返回 false）——页面初始化或用户点「测试连接」时用。
+     * 免码模式下用户点系统确认框可能超过默认 6s：建议先 onState 监听 pending 提示用户，
+     * 并把超时放大（如 120_000） */
+    async waitForAuthed(timeoutMs = 6e3) {
+      return this.inner.waitForAuthed(timeoutMs);
+    }
+    /** 通用请求（伴侣应用 WS 协议全开放，如 fs.readFile / email.send / flows.list） */
+    request(type, payload, timeoutMs) {
+      return this.inner.request(type, payload, timeoutMs);
+    }
+    async listModels() {
+      const data = await this.request("models.list");
+      return data.models;
+    }
+    /** 本机模型服务列表（探测配置状态：全部 hasKey=false = 用户还没配过 key） */
+    async listProviders() {
+      const data = await this.request("providers.list");
+      return data.providers;
+    }
+    /** 新增/更新模型服务（写本机 models.json + auth.json，保存即生效；apiKey 为空 = 保留原 key） */
+    async saveProvider(spec) {
+      return this.request("providers.save", { provider: spec });
+    }
+    async listTasks() {
+      const data = await this.request("task.list");
+      return data.tasks;
+    }
+    async getMessages(taskId) {
+      const data = await this.request("task.messages", { taskId });
+      return data.messages;
+    }
+    /** 建任务（firstMessage 非空则立即开始执行，进度走 task.* 事件） */
+    async createTask(opts = {}) {
+      return this.request("task.create", opts);
+    }
+    /** 向任务追加消息（任务空闲时触发执行；执行中提交会被拒绝，改用 steer 或等空闲） */
+    async prompt(taskId, text) {
+      return this.request("task.prompt", { taskId, text });
+    }
+    /** 任务执行中插入转向指令（不排队，下一轮生效） */
+    async steer(taskId, text) {
+      return this.request("task.steer", { taskId, text });
+    }
+    /** 中止执行中的任务 */
+    async abort(taskId) {
+      return this.request("task.abort", { taskId });
+    }
+  };
+  var index_default = LsagentClient;
+  return __toCommonJS(index_exports);
+})();

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "lsagent-sdk",
+  "version": "0.1.1",
+  "type": "module",
+  "description": "浏览器 JS SDK——网页连接用户本机的 lsagent AI 运行时（ws://127.0.0.1:37700/ws）：建任务、流式事件、文件上传、模型配置引导",
+  "license": "MIT",
+  "main": "./dist/lsagent-sdk.esm.js",
+  "module": "./dist/lsagent-sdk.esm.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/lsagent-sdk.esm.js",
+      "default": "./dist/lsagent-sdk.js"
+    },
+    "./dist/*": "./dist/*"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "typecheck": "tsc --noEmit",
+    "demo": "node demo/server.mjs"
+  },
+  "devDependencies": {
+    "@lsagent/shared": "*",
+    "esbuild": "^0.25.0",
+    "typescript": "^5.7.2"
+  }
+}