dsh-foreman-node 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,39 @@
+# Changelog
+
+本包是 [`dsh-foreman`](https://www.npmjs.com/package/dsh-foreman) 的设备侧，单独发版，
+但**协议与 hub 版本绑定**：两侧协议版本不一致时，握手就拒绝并给出可读原因。
+
+## 0.1.0 — 2026-11-07
+
+首个公开发布。
+
+### 新增：连出去
+
+- `NodeClient`：主动 wss 连到主 loop 的稳定域名，断线指数退避重连（1 s 起，封顶 60 s）。
+  方向是出站，所以公司 NAT 后面也能用。
+- 每 15 s 一次心跳，报「我在跑几件」；`hello` 报完整的在跑 assignment id 列表，
+  让主 loop 对齐而不是猜测。
+
+### 新增：接单
+
+- `JobSessions`：收到 `assign` 就在帧里给的**设备侧目录**建（或复用）会话
+  `job-<assignmentId>`，把渲染好的任务文本投进去。会话出现在你自己的侧栏里，你能看、能插话。
+- 会话权限固定为 **`workspace-write`**，不是 `danger-full-access`：笔记本前没人，
+  弹审批等于卡死。需要越界时不弹窗，而是报 `blocked` 让人决定。
+- 投递按 `requestId` 幂等：重投不会产生第二条消息。
+
+### 新增：回报
+
+- 每个 job 会话自动挂上 `foreman_report` 工具：`progress` / `ready` / `blocked` / `failed`，
+  可选一句提问。工具调用直接转成 `report` 帧。
+- **不向模型提供 `dropped`**：那是判断，设备没有判断权。想表达同样意思只能 `blocked`。
+- 投递成功回一帧 `accepted`，主 loop 才把这张 assignment 记为 started。
+
+### 协议
+
+- 帧定义在 `src/protocol.ts`，**这是协议的唯一定义**，hub 依赖本包并从这里导入。
+- 单帧上限 256 KiB，超限拒绝而不是截断；带副作用的帧带去重 id；帧里不传凭据。
+
+### 依赖
+
+- 运行时零第三方依赖。`@deepseek-ai/*` 是 `peerDependencies`，由装了本插件的 DSH 实例提供。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek Harness Team
+
+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

@@ -1,3 +1,79 @@
-# Temporary Holding Version
+# dsh-foreman-node
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **Not an official DeepSeek product.** 第三方项目，与 DeepSeek 官方无关。
+
+**设备侧。** 装在每台要被主 loop 派活的机器上：公司笔记本、宿舍电脑、任何一台你愿意接单的机器。
+
+它只做三件事：
+
+1. **连出去**——主动 wss 连到主 loop 的稳定域名，断线指数退避重连。方向是出站，所以公司 NAT 后面也能用。
+2. **接单**——收到 `assign` 就在指定目录建（或复用）一个 `job-<assignmentId>` 会话，把渲染好的任务文本投进去。这个会话出现在你自己的侧栏里，你能看、能插话。
+3. **回报**——在 job 会话上注册 `foreman_report` 工具，`progress` / `ready` / `blocked` / `failed` 加可选提问，直接转成 `report` 帧发回去。
+
+**它没有的**：工单、评估、决策、策略、数据库、SQLite。判断这件事该不该做，是主 loop 的事，不是设备的。
+
+```
+┌──────────── 主 loop（另一台机器）────────────┐
+│  dsh-foreman：唯一账本、选设备、下发、收回报     │
+└────────────────────┬─────────────────────────┘
+                     │  设备主动外连（wss）
+                     ▼
+     ┌───────────────────────────────┐
+     │  dsh-foreman-node（本机）      │
+     │  job-<id> 会话，权限受限       │
+     │  你自己的 DSH 一切照常         │
+     └───────────────────────────────┘
+```
+
+## 状态
+
+**早期开发中。** 协议、连接、接单与回报工具都已落地并有测试（14 项）。
+
+## 装上去
+
+```yaml
+# 本机 profile 的 cordis.patch.yml
+- id: dsh-foreman-node
+  config:
+    url: wss://foreman.example.com     # 主 loop 的稳定域名（隧道后面）
+    deviceId: laptop                   # 主 loop 上 scripts/add-device.mjs 登记的那个 id
+    token: <登记时打印的那一枚>
+    roots:
+      - project: shop
+        path: 'D:\工作\shop'            # 本机自己的绝对路径，原样写
+```
+
+重启本机的 DSH 即可。主 loop 不用重启——设备表在主 loop 的数据库里，不在它的插件配置里。
+
+## 接单时发生什么
+
+1. 收到 `assign` → 在帧里给的目录建（或复用）会话 `job-<assignmentId>`。
+2. 任务文本作为一条用户消息投进去，`requestId` 幂等：重投不会产生第二条。
+3. 会话挂上 `foreman_report` 工具，模型用它报 `progress` / `ready` / `blocked` / `failed`。
+4. 每次投递成功回一帧 `accepted`，主 loop 才把这张 assignment 记为 started。
+
+**权限是 `workspace-write`**，不是主 loop 自己用的 `danger-full-access`：笔记本前没人，弹审批等于卡死。
+需要越界时设备不弹窗，而是报 `blocked`，由人决定放宽 root 还是换设备。
+
+## 协议
+
+帧定义在 [`src/protocol.ts`](src/protocol.ts)。**这个文件是该协议的唯一权威定义**：
+主 loop 那个包 `dsh-foreman` 依赖本包并从 `dsh-foreman-node/protocol` 导入它，所以两侧
+不可能漂移——这也是为什么协议放在设备侧而不是主 loop 侧：反过来会把整个领域内核装进每台笔记本。
+
+约定：
+- 一条 WebSocket 文本消息一个 JSON 帧，`v` 是协议版本，不同版本在握手时就拒绝。
+- 单帧上限 256 KiB，超限拒绝而不是截断。
+- 带副作用的帧带 `frameId`，接收方去重。
+- `report` 的 `state` **不含 `dropped`**：那是判断，设备没有判断权。
+
+## 由来
+
+代码结构参考了 [dsh-superagent-local](https://github.com/mengzhongjie/dsh-superagent-local)
+与 [dsh-superagent-prototype](https://github.com/deepseek-ai/dsh-superagent-prototype)（均为 MIT，
+Copyright (c) 2026 DeepSeek Harness Team）。架构思想来自 DeepSeek Harness 团队的
+《Super-agent 设计探索》，本包对应其中「计算与执行环境分离」那一层。
+
+## 许可
+
+MIT，见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,5 @@
+# dsh-foreman-node bundle patch: the device side only. It carries no stateDir,
+# locks no database and opens no listener; it dials out to the hub.
+- insert:
+    - id: dsh-foreman-node
+      name: 'dsh-foreman-node'

package/lib/index.d.ts

@@ -0,0 +1,219 @@
+import { Frame, FrameAttachment, FrameDedupe, Root } from "./protocol.js";
+import { Context } from "@deepseek-ai/cordis";
+import { Agent } from "@deepseek-ai/dsh-agent";
+/** What a socket has to offer; the global `WebSocket` satisfies it, and tests supply an object that does too. */
+interface SocketLike {
+  readyState: number;
+  send(data: string): void;
+  close(): void;
+  addEventListener(type: 'open' | 'close' | 'error', listener: () => void): void;
+  addEventListener(type: 'message', listener: (event: {
+    data: unknown;
+  }) => void): void;
+}
+/** Opens a socket; injectable so tests never touch the network. */
+type Connect = (url: string) => SocketLike;
+interface NodeClientInput {
+  /** The hub's stable address, such as `wss://foreman.example.com`. */
+  url: string;
+  deviceId: string;
+  /** The device token; sent in the hello and nowhere else. */
+  token: string;
+  version: string;
+  /** The projects this device can work on, as its own absolute paths. Declared once and re-declared on every hello. */
+  roots: () => Root[];
+  /** The assignments this device currently holds. Reported on every hello so the hub aligns instead of guessing. */
+  running: () => string[];
+  /** Handles frames the hub sends. */
+  onFrame: (frame: Frame) => void;
+  /** Milliseconds before the first reconnect; doubles up to `maxReconnectMs`. */
+  reconnectMs?: number;
+  maxReconnectMs?: number;
+  connect?: Connect;
+  /** The heartbeat interval; a device that says nothing looks offline to the hub, which turns its work blocked. */
+  heartbeatMs?: number;
+  log?: (text: string) => void;
+  /** Frame ids the device has already acted on, so a redelivered frame does nothing twice. */
+  dedupe?: FrameDedupe;
+}
+/**
+ * Keeps one connection to the hub open, reconnecting with backoff.
+ *
+ * The class owns the socket's lifecycle and nothing else: what a frame means is the plugin's business, and what
+ * happens when the connection is refused is the hub's. `start` and `stop` are idempotent.
+ */
+declare class NodeClient {
+  private readonly input;
+  private socket?;
+  private stopped;
+  private reconnectTimer?;
+  private heartbeatTimer?;
+  private delay;
+  private readonly dedupe;
+  private readonly connect;
+  private readonly log;
+  constructor(input: NodeClientInput);
+  /** Open the connection, or do nothing if it is already open or opening. */
+  start(): void;
+  /** Close the connection and stop reconnecting; a late socket event does nothing. */
+  stop(): void;
+  /** Send a frame now if the connection is open. Returns whether it went out, so a caller can retry later. */
+  send(frame: Frame): boolean;
+  /** Report an outcome on an assignment, which is the only way a hub learns what a job did. */
+  report(assignmentId: string, report: {
+    state: 'progress' | 'ready' | 'blocked' | 'failed';
+    summary: string;
+    question?: string;
+  }): void;
+  /** Whether the connection is open right now. */
+  connected(): boolean;
+  private open;
+  private hello;
+  private startHeartbeat;
+  private receive;
+  /** Acknowledge a frame once its side effect is done, so the hub can stop resending it. */
+  ack(frame: Frame): void;
+  /** Tell the hub a frame's work reached its Session, which is what lets it mark the assignment started. */
+  accepted(assignmentId: string): void;
+  private scheduleReconnect;
+}
+/**
+ * The `foreman_report` tool a device registers on a job Session.
+ *
+ * Reporting is a hard requirement rather than a convenience: in the domain, "waiting for a person" is a structured
+ * fact that a report carries, and inferring it from a turn ending is an explicitly rejected approach. So a device
+ * states outcomes through this tool and nothing else.
+ *
+ * `dropped` is not in its enum. Deciding that work should not be done is a judgement, a device has no judgement, and
+ * the hub's ledger already refuses that state from a device (see the protocol). A device that believes the same thing
+ * must report `blocked` and let a person decide.
+ *
+ * The schema is written as JSON Schema and validated here rather than through `zod`, so this package stays free of
+ * runtime dependencies beyond the DSH services it is a peer plugin of.
+ */
+/** What a device may report; the same set the protocol's `NodeReportState` names. */
+declare const REPORT_STATES: readonly ["progress", "ready", "blocked", "failed"];
+type ReportState = typeof REPORT_STATES[number];
+/** A report as the tool's caller gives it. */
+interface DeviceReport {
+  state: ReportState;
+  summary: string;
+  /** One question a person must answer; paired with `state: 'blocked'` in practice. */
+  question?: string;
+}
+/** The host a tool reports through: the client that owns the connection, or a test. */
+interface ReportHost {
+  report(assignmentId: string, report: DeviceReport): void;
+}
+/** The parts of a tool definition DSH registers: name, description, JSON Schema, and the executor. */
+interface DeviceTool {
+  name: string;
+  description: string;
+  parameters: Record<string, unknown>;
+  execute(args: Record<string, unknown>, execution: {
+    signal: AbortSignal;
+  }): Promise<unknown>;
+}
+/**
+ * Build the `foreman_report` tool for one assignment.
+ *
+ * The assignment id is bound here rather than passed by the model: a job Session reports on the assignment it was
+ * started for, and a model should not be able to name a different one.
+ */
+declare function foremanReportTool(host: ReportHost, assignmentId: string): DeviceTool;
+declare module '@deepseek-ai/dsh-llm' {
+  interface MessageSourceMap {
+    'dsh-foreman-node': {
+      kind: 'dsh-foreman-node';
+      form: 'relay';
+    };
+  }
+}
+interface EnsureInput {
+  assignmentId: string;
+  /** The absolute directory on this device; the hub mapped it through the device's declared roots. */
+  directory: string;
+  title: string;
+}
+/**
+ * Keeps the device's job Sessions and delivers work into them.
+ *
+ * A Session is created only when it does not exist yet, so a redelivered `assign` reuses the Session and the work
+ * already in it instead of starting a second one. Delivery is idempotent by request id: the hub retrying a frame
+ * that it never saw acknowledged cannot append the task twice.
+ */
+declare class JobSessions {
+  private readonly ctx;
+  /** Jobs by assignment id, so `running()` reports what this device actually holds rather than what it was told. */
+  private readonly jobs;
+  /** Assignments whose Session already carries the report tool, so a redelivered assign registers it only once. */
+  private readonly reported;
+  constructor(ctx: Context);
+  /**
+   * Resolve or create the `job-<assignmentId>` Session in the given directory, attach its `foreman_report` tool, and
+   * register it so a heartbeat counts it.
+   *
+   * The tool is attached here rather than left to the caller because it is the only way a device can say what
+   * happened: without it a job Session's model has no `progress`/`ready`/`blocked`/`failed` channel, the hub waits
+   * forever, and the whole design's "never infer state from session events" requirement is moot. Registration is
+   * idempotent per assignment, so a redelivered `assign` does not stack a second tool on the same Session.
+   *
+   * @returns the Session id.
+   */
+  ensure(input: EnsureInput, onReport?: (assignmentId: string, report: DeviceReport) => void): Promise<string>;
+  /**
+   * Deliver a task into its job Session, once per request id.
+   *
+   * `queue` rather than `steer` on the first delivery: the job's task should start a turn, not interrupt one that is
+   * already running. A redelivery finds the message already recorded and adds nothing.
+   */
+  deliver(sessionId: string, text: string, requestId: string): Promise<void>;
+  /** Whether the Session already holds the delivery for `requestId`, in its live inbox or its stored history. */
+  holds(agent: Agent, requestId: string): Promise<boolean>;
+  /** The assignment ids this device currently holds a job for: what a heartbeat and a reconnected hello report. */
+  running(): string[];
+  /** Forget a job whose assignment the hub stopped, so this device stops reporting it as running. */
+  forget(assignmentId: string): void;
+  /** Attach the `foreman_report` tool to a job Session, disposed with it. */
+  reportTools(agent: Agent, assignmentId: string, onReport: (assignmentId: string, report: DeviceReport) => void): void;
+}
+/** Version reported in the hello, so the hub can tell which device build is talking. */
+declare const VERSION = "0.1.0";
+/** One project this device can work on: the hub's logical name and this machine's own absolute path. */
+interface NodeRoot {
+  project: string;
+  path: string;
+}
+/** What the `dsh-foreman-node` entry in a profile's patch configures. */
+interface NodeConfig {
+  /** The hub's stable address; the device dials out to it. */
+  url: string;
+  /** This device's id, as registered on the hub with `Devices.add`. */
+  deviceId: string;
+  /** This device's token; sent in the hello and nowhere else. */
+  token: string;
+  /** The projects this device can work on. */
+  roots: NodeRoot[];
+  /** How often to tell the hub this device is alive, in milliseconds. */
+  heartbeatMs: number;
+  /** Delay before the first reconnect attempt, in milliseconds. */
+  reconnectMs: number;
+}
+/**
+ * Configuration of one device, from the `dsh-foreman-node` entry in the profile's patch.
+ *
+ * The annotation names the schema type through the global `Schemastery` namespace rather than letting it be inferred:
+ * an inferred type here names a `cosmokit` symbol the emitted declaration cannot reference portably.
+ */
+declare const Config: Schemastery<NodeConfig>;
+declare const name = "dsh-foreman-node";
+/** DSH services a job needs; all are the host's own, and none is a foreman one. */
+declare const inject: string[];
+/**
+ * Start the device.
+ *
+ * The plugin returns once the connection is attempted, not once it succeeds: a device must boot and stay usable
+ * while its hub is unreachable, and the client keeps retrying in the background.
+ */
+declare function apply(ctx: Context, config: NodeConfig): Promise<void>;
+export { Config, type Frame, type FrameAttachment, JobSessions, NodeClient, NodeConfig, NodeRoot, REPORT_STATES, type Root, VERSION, apply, foremanReportTool, inject, name };