pi-onlyne 0.8.0 → 0.9.1

package/dist/swarm.js

@@ -1,6 +1,47 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+/** Frame header for versioned lifecycle evidence consumed by the scheduler
+ * reducer. A distinct prefix from `---swarm` / `---swarm-ctl`, so a report
+ * never enters the task delivery paths on either side. */
+export const SWARM_REPORT_PREFIX = "---swarm-report\n";
+/** Report kinds accepted by the scheduler's report parser. */
+export const SWARM_REPORT_KINDS = ["heartbeat", "ready", "turn_started", "snapshot", "complete", "fault"];
+/** Whether a value carries scheduler task identity: a UUID. The session's own
+ * composite keys (`session:<handle>`) name no scheduler row, so a report built
+ * from one would land as unknown-session noise on that side. */
+export function isSwarmTaskId(value) {
+    return UUID_RE.test(value.trim());
+}
+/** Whether a loopback text is a lifecycle report frame. Reports live in the
+ * same loopback history and event stream as task wires, so every task scan
+ * skips them ahead of its malformed-header check. */
+export function isSwarmReportFrame(text) {
+    return text.startsWith(SWARM_REPORT_PREFIX);
+}
+/** u64 ceiling the scheduler validates for generation and seq. */
+const MAX_REPORT_COUNTER = 9_007_199_254_740_991;
+/** Render one lifecycle report frame:
+ * `---swarm-report\nprotocol: 2\nop: <kind>\ntask_id: <uuid>\ngeneration: <n>\nseq: <n>\n---\n`
+ * Field order, labels, values, and the closing delimiter match the scheduler
+ * parser byte for byte; its `fields()` rejects missing, unknown, and duplicate
+ * keys, so the frame carries exactly those five fields. The trailing `---\n`
+ * closes the header region the parser reads.
+ * Invalid input fails here with a diagnostic: a synthetic task id and an
+ * out-of-range counter never reach the wire. */
+export function renderSwarmReport(kind, taskId, generation, seq) {
+    if (!SWARM_REPORT_KINDS.includes(kind))
+        throw new Error(`unknown swarm report kind: ${String(kind)}`);
+    const id = taskId.trim();
+    if (!isSwarmTaskId(id))
+        throw new Error(`swarm report needs a uuid task_id, got ${taskId || "<empty>"}`);
+    for (const [name, value] of [["generation", generation], ["seq", seq]]) {
+        if (!Number.isSafeInteger(value) || value < 0 || value > MAX_REPORT_COUNTER) {
+            throw new Error(`swarm report ${name} must be a u64 counter within ${MAX_REPORT_COUNTER}, got ${value}`);
+        }
+    }
+    return `${SWARM_REPORT_PREFIX}protocol: 2\nop: ${kind}\ntask_id: ${id}\ngeneration: ${generation}\nseq: ${seq}\n---\n`;
+}
 /** Parse a `---swarm` body header. Returns null for non-swarm messages. */
 export function parseSwarmHeader(text) {
     const rest = text.startsWith("---swarm\n") ? text.slice("---swarm\n".length) : null;
@@ -24,38 +65,56 @@ export function parseSwarmHeader(text) {
         headRaw = rest.slice(0, alt);
         payload = rest.slice(alt + "\n---".length).replace(/^\n/, "");
     }
+    let protocol;
     let task_id;
-    let from = ".";
+    let from;
     let transfer_send_to = "";
     let attempt = 1;
-    let sawTransfer = false;
+    let delivery = "";
+    const seen = new Set();
+    const allowed = new Set(["protocol", "task_id", "from", "transfer_send_to", "attempt", "delivery"]);
     for (const line of headRaw.split("\n")) {
         const t = line.trim();
         if (!t || t.startsWith("#"))
             continue;
         const i = t.indexOf(":");
         if (i < 0)
-            continue;
+            return null;
         const k = t.slice(0, i).trim();
         const v = t.slice(i + 1).trim().replace(/^["']|["']$/g, "");
-        if (k === "task_id")
+        if (!allowed.has(k) || seen.has(k) || !v)
+            return null;
+        seen.add(k);
+        if (k === "protocol") {
+            if (!/^\d+$/.test(v) || Number(v) !== 2)
+                return null;
+            protocol = 2;
+        }
+        else if (k === "task_id")
             task_id = v;
         else if (k === "from")
-            from = v || ".";
+            from = v;
         else if (k === "transfer_send_to") {
+            if (!UUID_RE.test(v))
+                return null;
             transfer_send_to = v;
-            sawTransfer = true;
         }
-        else if (k === "reply_to")
-            return null;
-        else if (k === "attempt")
-            attempt = Number.parseInt(v, 10) || 1;
+        else if (k === "attempt") {
+            if (!/^\d+$/.test(v))
+                return null;
+            attempt = Number(v);
+            if (!Number.isSafeInteger(attempt) || attempt < 1)
+                return null;
+        }
+        else if (k === "delivery") {
+            if (v !== "scheduler")
+                return null;
+            delivery = v;
+        }
     }
-    if (!sawTransfer)
+    if (protocol !== 2 || !task_id || !from || !UUID_RE.test(task_id.trim()))
         return null;
-    if (!task_id || !UUID_RE.test(task_id.trim()))
-        return null;
-    return { header: { task_id: task_id.trim(), from, transfer_send_to, attempt }, payload };
+    return { header: { task_id: task_id.trim(), from, transfer_send_to, attempt }, delivery, payload };
 }
 export function parseSwarmCtl(text) {
     if (!text.startsWith("---swarm-ctl\n"))
@@ -89,9 +148,17 @@ export function parseSwarmCtl(text) {
 }
 /** Render a swarm body header in front of a Markdown payload. */
 export function renderSwarmHeader(header, role, payloadMarkdown) {
-    let s = `---swarm\ntask_id: ${header.task_id}\nfrom: ${header.from}\ntransfer_send_to: ${header.transfer_send_to}\nattempt: ${header.attempt}\n---\n`;
-    if (role)
-        s += `## role: ${role}\n\n${role}\n`;
+    // Raw relay and out wires intentionally omit `delivery`. Scheduler owns the
+    // second delivery step and adds `delivery: scheduler` there.
+    let s = `---swarm\nprotocol: 2\ntask_id: ${header.task_id}\nfrom: ${header.from}\n`;
+    const transfer = header.transfer_send_to.trim();
+    if (transfer)
+        s += `transfer_send_to: ${transfer}\n`;
+    s += `attempt: ${header.attempt}\n---\n`;
+    // Flat role text follows the delimiter once, with no duplicate echo.
+    if (role) {
+        s += role.endsWith("\n") ? role + "\n" : role + "\n\n";
+    }
     s += payloadMarkdown;
     if (!s.endsWith("\n"))
         s += "\n";
@@ -184,7 +251,46 @@ export function treePathForWorkspace(workspaceRoot) {
 export function terminalHandle() {
     return process.env.ORCA_TERMINAL_HANDLE || process.env.ONLYNE_TERMINAL_HANDLE || "";
 }
+/** Choose a scheduler-delivered history wire for a fresh swarm session.
+ *
+ * A terminal with ONLYNE_SWARM_TASK has one assigned task. History may still
+ * contain arbitrary old unclosed wires for the same workspace, so it may
+ * replay only that exact id. If the assigned delivery has not reached history
+ * yet, return undefined and let the live inbound event deliver it. Sessions
+ * without an env assignment (manual ready pool) retain newest-unclosed
+ * fallback behavior. This is pure so the replay race is regression-tested.
+ */
+export function selectHistoryDelivery(expectedTaskId, inbounds, outs) {
+    if (expectedTaskId) {
+        return inbounds.find((text) => parseSwarmHeader(text)?.header.task_id === expectedTaskId);
+    }
+    for (let i = inbounds.length - 1; i >= 0; i--) {
+        const text = inbounds[i];
+        const taskId = parseSwarmHeader(text)?.header.task_id;
+        if (taskId && !outs.has(taskId))
+            return text;
+    }
+    return undefined;
+}
 /** Task id injected by the scheduler via env (fallback before swarm_ready handshake). */
 export function envTaskId() {
     return process.env.ONLYNE_SWARM_TASK || "";
 }
+/** R4 hop-activity decision, pure so the guard and the pending_exit bit are
+ * unit-tested without a live daemon. Returns the daemon op body, or null when
+ * nothing should be reported: busy/idle only make sense for a swarm session
+ * that has a workspace and a live claimed task. An idle report always carries
+ * pending_exit=true — the plugin never sends idle after swarm_complete cleared
+ * the task (that path writes no event; the scheduler owns the recycle). */
+export function hopActivityBody(kind, opts) {
+    if (!opts.swarm || !opts.workspaceRoot || !opts.taskId)
+        return null;
+    const body = {
+        workspace: opts.workspaceRoot,
+        terminal_handle: opts.terminal,
+        task_id: opts.taskId,
+    };
+    if (kind === "idle")
+        body.pending_exit = true;
+    return body;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-onlyne",
-  "version": "0.8.0",
+  "version": "0.9.1",
   "description": "Pi extension tools for sending messages through Onlyne.",
   "type": "module",
   "main": "./dist/index.js",