pi-onlyne 1.1.0 → 1.1.1

package/README.md

@@ -79,10 +79,10 @@ printf '{"packages":["../.onlyne/agent/onlyne-agent-pi"]}\n' > <ws>/.pi/settings
 ### From npm
 
 ```bash
-pi install pi-onlyne              # user-level: every pi process on this box loads it
+pi install npm:pi-onlyne          # user-level: every pi process on this box loads it
 ```
 
-The published package is `pi-onlyne` on npm; `pi install pi-onlyne@<version>` pins
+The published package is `pi-onlyne` on npm; `pi install npm:pi-onlyne@<version>` pins
 one. This route reaches ordinary interactive sessions too, and there the extension
 stays inert (no `ONLYNE_ROLE`, so no adapter). A role workspace needs no global
 install to get a panel: the file-level copy above, or `onlyne server generate`,
@@ -298,10 +298,12 @@ the shipped client.
   written, and a framing fault closes the connection and reconnects. Framing cannot
   resynchronise after a corrupt body, which is the same conclusion
   `crates/onlyne-frame/src/lib.rs` reaches.
-- **Task ids here are single-use.** The plugin acks duplicate `assign` deliveries for the
-  same task (`reason: "duplicate"`) without a second injection, and remembers the id for
-  the life of the connection. The client today mints a fresh uuid per task, so this only
-  ever fires on a genuine redelivery.
+- **Deliveries are idempotent; tasks are not.** The dedup key is the envelope id. The
+  same delivery twice gets one injection and an ack with `reason: "duplicate"`, and a
+  new envelope for a task that is already running reaches that session as another
+  message — the work record keeps its counters and its relay ledger, and only its
+  "turns since this instruction" watchdog restarts. The client mints a fresh uuid per
+  envelope, so `duplicate` fires on a genuine re-offer and on nothing else.
 
 - **Pane binding (Orca tabs).** Inside an Orca pane the plugin reports the pane it runs in on every
   heartbeat, as `observed.host.orca.pane_key` in the report's `Observation`

package/README.zh.md

@@ -73,10 +73,10 @@ printf '{"packages":["../.onlyne/agent/onlyne-agent-pi"]}\n' > <ws>/.pi/settings
 ### 从 npm 装
 
 ```bash
-pi install pi-onlyne              # 用户级：这台机器上每个 pi 进程都会加载
+pi install npm:pi-onlyne          # 用户级：这台机器上每个 pi 进程都会加载
 ```
 
-发布名是 npm 上的 `pi-onlyne`，`pi install pi-onlyne@<version>` 钉住某一版。这条路径会覆盖
+发布名是 npm 上的 `pi-onlyne`，`pi install npm:pi-onlyne@<version>` 钉住某一版。这条路径会覆盖
 普通交互会话，那里没有 `ONLYNE_ROLE`，扩展保持静默（见 §1 的身份门）。role workspace 想要面
 板，不必装到全局：上面那份文件级复制、或者 `onlyne server generate`，都把插件限定在服务这个
 role 的 workspace 里。
@@ -259,9 +259,10 @@ stderr 告警并忽略，把机会让回文件。
   `inject` 插件记录的重载。其他键记日志后忽略，绝不误读。
 - **`frame_too_large` / `bad_frame`**：超限正文在写出任何字节之前就被拒；帧错误关闭连接并重
   连。帧一旦损坏无法重新同步，这与 `crates/onlyne-frame/src/lib.rs` 的结论一致。
-- **任务 id 在连接生命周期内一次性使用**：同一任务的重复 `assign` 插件只回
-  `reason: "duplicate"` 的 ack，不重复注入，并记住这个 id 直到连接结束。当今 client 每个任务
-  都是新 uuid，所以这条只在真正的重投上生效。
+- **投递按 envelope id 幂等，任务不按 id 一次性使用**：去重键是 envelope id。同一条投递重复
+  到达只注入一次，ack 带 `reason: "duplicate"`；正在运行的任务收到新 envelope，会作为新消息
+  注入同一个会话，工作记录保留自己的计数与转发账本，只把"自这条指令以来的轮数"看门狗归零。
+  client 每条 envelope 都发新 uuid，所以 `duplicate` 只在真正的重投上生效。
 
 - **pane 绑定（Orca tab）。** 在 Orca pane 里，插件在每个 heartbeat 上报自己跑在哪：报告
   `Observation` 里的 `observed.host.orca.pane_key`（`crates/onlyne-session/src/host.rs`），环境

package/package.json

@@ -1,9 +1,8 @@
 {
   "name": "pi-onlyne",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Onlyne agent adapter for pi: the session lifecycle an onlyne role client expects from a pi host.",
   "type": "module",
-  "main": "./src/index.ts",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -32,12 +31,10 @@
     ]
   },
   "scripts": {
-    "test": "node --test src/*.test.mjs",
-    "test:live": "node --test src/agent.live.test.mjs"
+    "test": "node --test src/*.test.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": "*",
     "typebox": "*"
-  },
-  "peerDevDependencies": {}
+  }
 }

package/relay.toml.example

@@ -1,13 +1,18 @@
-# Onlyne relay guard policy — copy to `relay.toml` next to this package's `package.json`.
+# Manual-installation escape hatch for the relay guard.
 #
-# Manual installations only. A generated workspace states the same policy in the
-# server spec's `[[client]]` entry (`relay_required` / `relay_count`), which the
-# client injects as `ONLYNE_RELAY_REQUIRED` / `ONLYNE_RELAY_COUNT`. Those
-# environment variables win, and a file they shadow is ignored outright.
+# A generated workspace gets its guard policy from spec.toml ([[client]] rows
+# `relay_required = ["writer"]`, `relay_count = 2` — `relay_required_count` is
+# accepted as the guard file's own spelling), which the client injects into
+# every session it spawns. This file is for installations that manage their
+# own workspace: drop it beside package.json and the guard reads it when the
+# environment carries no policy. Environment wins over this file; no policy in
+# either place leaves the guard off.
 #
-# Closed subset: flat `key = value` lines, the two keys below, one-line arrays of
-# double-quoted strings, `#` comments. Anything outside that warns on stderr and
-# is ignored. `relay_required` wins when both keys are present.
+# relay_required wins over relay_count when both are present.
 
-relay_required = ["writer"]        # these roles must have received a handoff
-relay_required_count = 2           # ... or this many distinct downstream roles
+# Downstream roles one of this role's sessions must have handed work to before
+# it may report a terminal outcome:
+#   relay_required = ["writer", "auditor"]
+
+# ... or this many distinct downstream roles:
+#   relay_required_count = 2

package/src/agent.mjs

@@ -152,7 +152,13 @@ export class OnlyneAgent {
      * sent — the guard judges this session's own deliveries, not history.
      */
     this.deliveredTo = new Set();
-    this.injectedTasks = new Set();
+    /**
+     * The deliveries this process has already handed to the model, keyed by
+     * envelope id (a delivery's own identity). Keying it by task id would swallow
+     * every later envelope for a live task — the follow-up that never arrives —
+     * and the guard below answers a true re-delivery with `duplicate`.
+     */
+    this.injectedDeliveries = new Set();
     this.deliveredProse = new Set();
     /** Pushes that arrived before the handshake finished; see `onFrame`. */
     this.handshaking = false;
@@ -564,13 +570,16 @@ export class OnlyneAgent {
       this.log("assign carried no task id; ignored");
       return;
     }
-    if (this.injectedTasks.has(taskId)) {
+    // The delivery's own identity, so a re-offer of the same message is caught
+    // and a genuinely new message for a running task gets through.
+    const deliveryId = envelope.id ?? `task:${taskId}`;
+    if (this.injectedDeliveries.has(deliveryId)) {
       this.stats.duplicates += 1;
-      this.notice("dup", `task ${taskId.slice(0, 8)} already injected`);
+      this.notice("dup", `~~ task ${taskId.slice(0, 8)} re-delivered, already injected`);
       await this.ack(taskId, true, "duplicate");
       return;
     }
-    this.injectedTasks.add(taskId);
+    this.injectedDeliveries.add(deliveryId);
     this.stats.assigns += 1;
     if (typeof args.generation === "number") this.generation = args.generation;
 
@@ -580,18 +589,32 @@ export class OnlyneAgent {
     if (proseIsNew) this.deliveredProse.add(prose);
     const text = injectionText({ assign: { ...args, task_id: taskId }, proseIsNew, attachmentPaths: attachments.map((item) => item.path) });
 
-    this.tasks.set(taskId, {
-      taskId,
-      envelopeId: envelope.id ?? null,
-      // Who handed this task over: the relay guard's count mode does not count
-      // a send straight back to it (`relay.mjs`).
-      upstream: envelope.from?.role?.role ?? null,
-      turnsSinceAssign: 0,
-      turns: 0,
-      errored: false,
-      head: "",
-      failed: false,
-    });
+    const held = this.tasks.get(taskId);
+    // A completed record is not a live one: a new envelope for a task that
+    // already settled is fresh work under an old id, so it gets a fresh record.
+    if (held && !held.completed) {
+      // A new envelope for a task this session already holds — a follow-up, a
+      // redirect, a bounce back through a relay. The work record stays where it
+      // is: its delivered set keeps the relay guard's count, and its completion
+      // state still settles the task. Only the "since this instruction" counter
+      // moves, so the settled-without-completing watchdog measures the newest one.
+      held.turnsSinceAssign = 0;
+      held.envelopeId = envelope.id ?? held.envelopeId;
+      if (held.failed) held.failed = false;
+    } else {
+      this.tasks.set(taskId, {
+        taskId,
+        envelopeId: envelope.id ?? null,
+        // Who handed this task over: the relay guard's count mode does not count
+        // a send straight back to it (`relay.mjs`).
+        upstream: envelope.from?.role?.role ?? null,
+        turnsSinceAssign: 0,
+        turns: 0,
+        errored: false,
+        head: "",
+        failed: false,
+      });
+    }
     this.agentState = "running";
     this.surface.wakeUser?.(text, attachments.map((item) => item.part));
     this.surface.customEntry?.("onlyne-assign", {

package/src/agent.test.mjs

@@ -458,6 +458,50 @@ test("an assign is injected once, acked, and a redelivery changes nothing", asyn
   assert.deepEqual(second[1], { task_id: TASK_ID, accepted: true, reason: "duplicate" });
 });
 
+// A follow-up arrives as its own envelope under the task id the session is
+// already running. Keying the injection guard on the task swallowed it: the
+// panel said `already injected`, nothing reached the model, and the row the
+// server kept re-offering never settled.
+test("a new envelope for a running task reaches the model and keeps its record", async () => {
+  const { agent, host, surface } = await startAgent();
+  agent.start();
+  await waitFor(() => host.of("report").length >= 1);
+
+  host.notify("assign", assignArgs());
+  await waitFor(() => (surface.calls.wakeUser.length === 1 ? true : null));
+  const record = agent.tasks.get(TASK_ID);
+  // Turns already run under this task, without driving the turn hooks: a real
+  // turn end also arms the settle fallback, which would complete the task.
+  record.turns = 3;
+  record.turnsSinceAssign = 2;
+
+  const base = assignArgs();
+  const follow = {
+    ...base,
+    envelope: {
+      ...base.envelope,
+      id: "4a3b2c1d-6e7f-4a90-8b1c-2d3e4f506172",
+      body: { text: "actually, use the q8 variant" },
+    },
+  };
+  host.notify("assign", follow);
+  await waitFor(() => (surface.calls.wakeUser.length === 2 ? true : null));
+  assert.match(surface.calls.wakeUser[1].text, /q8 variant/);
+  const acks = await waitFor(() => (host.of("assign_ack").length === 2 ? host.of("assign_ack") : null));
+  assert.deepEqual(acks[1], { task_id: TASK_ID, accepted: true });
+
+  assert.equal(agent.tasks.get(TASK_ID), record, "the running work record survives");
+  assert.equal(record.turns, 3, "what the session already did under this task is not erased");
+  assert.equal(record.turnsSinceAssign, 0, "the watchdog counts from the newest instruction");
+  assert.equal(record.envelopeId, "4a3b2c1d-6e7f-4a90-8b1c-2d3e4f506172");
+
+  // The same envelope again is the true duplicate, and it changes nothing.
+  host.notify("assign", follow);
+  const third = await waitFor(() => (host.of("assign_ack").length === 3 ? host.of("assign_ack") : null));
+  assert.equal(surface.calls.wakeUser.length, 2);
+  assert.deepEqual(third[2], { task_id: TASK_ID, accepted: true, reason: "duplicate" });
+});
+
 // The live case in crates/onlyne-testkit/e2e/pi-live.sh found this: the client
 // hands over a staged session by writing the hello reply and the first assign
 // together, so both frames arrive in one read. The assignment must not be