pi-onlyne 0.7.3 → 0.8.0

package/README.md

@@ -151,6 +151,12 @@ One session sees one toolset, chosen at session start. Generic send/reply
 tools stay out of the swarm surface so unheaded writes cannot pollute the
 protocol.
 
+Reclaim uses a control wire on the same loopback path: the scheduler writes a
+header-only `---swarm-ctl` message (`op: recycle`), pi-onlyne intercepts it
+before delivery, acks `swarm_recycled { task_id, reason }`, stops watching,
+clears the slot, and exits its own process. The scheduler then closes the
+Orca tab. Missing acks are logged and the tab still closes.
+
 Messages use Markdown by default. `rawText: true` preserves literal text for scripts and protocol payloads.
 
 ### Send one message
@@ -190,7 +196,7 @@ Swarm mode lets `onlyne-swarm` own task routing for a generated agent workspace.
 enabled = true
 ```
 
-A swarm Pi session subscribes to loopback events, reports `swarm_ready`, accepts one hop atomically, spawns continuations with `swarm_send` (fire-and-forget), and exits with `swarm_complete` (done signal) or `swarm_quit` (silent, scheduler records failed). Downstream results travel through files and the ledger; nothing waits.
+A swarm Pi session subscribes to loopback events, reports `swarm_ready`, accepts one hop atomically, spawns continuations with `swarm_send` (fire-and-forget), and writes `swarm_complete` (done signal). Scheduler then sends a header-only recycle control wire; pi-onlyne intercepts it before model delivery, sends `swarm_recycled`, stops the watch, clears the slot, and self-exits. `swarm_quit` sends the same ack with `quit:<reason>` then self-exits, so the scheduler records failed immediately. Downstream results travel through files and the ledger; nothing waits.
 
 For automatic startup in a generated workspace, add `.pi/onlyne.json`:
 
@@ -212,7 +218,9 @@ Pi-side settings live at `.pi/onlyne.json`. Onlyne stores credentials, history,
 
 ## Release notes
 
-This checkout is version 0.6.0 with swarm support already merged into the `dev` branch. npm currently publishes 0.4.0 as the latest tag. Run `npm run check` before any release so the build and tests regenerate `dist/`. Publish with `npm publish` after reviewing the generated tarball.
+The checkout in this repository tracks the published version in `package.json`.
+Run `npm run check` before any release so the build and tests regenerate
+`dist/`. Publish with `npm publish` after reviewing the generated tarball.
 
 ## Development
 

package/SPEC.md

@@ -32,10 +32,21 @@ Stored in project `.pi/onlyne.json`:
     "defaultReplyMode": "guarded-explicit",
     "guardedExplicit": { "reminders": 2, "noOutputFallbackText": "Onlyne/Pi error: no valid reply was produced." },
     "retry": { "attempts": 2, "concurrency": 8 }
-  }
+  },
+  "swarm_prompt": { "template": "prompts/swarm-task.md" }
 }
 ```
 
+- `swarm_prompt` externalizes the swarm task injection wrapper
+  (`src/swarm-prompt.ts`). `template` is a workspace-relative path whose
+  content is injected as the followUp message; placeholders `{task_id}`,
+  `{from}`, `{transfer_send_to}`, `{attempt}`, `{payload}` are substituted.
+  `false` disables the wrapper (raw payload injected). Omitting the key
+  keeps the built-in default text. Operators with relay-only nodes
+  (no history worth restoring) should ship a template that names the role
+  as the complete instruction set and warns that `onlyne_in/` and
+  `.onlyne/` are OS pipes (opening one freezes the session).
+
 ## Tools
 
 Normal mode (default):
@@ -82,17 +93,19 @@ One session sees one toolset. The surface is chosen at `session_start` from
   `ONLYNE_SWARM_TASK` env and `ORCA_TERMINAL_HANDLE`/`ONLYNE_TERMINAL_HANDLE`
   provide fallback correlation.
 - Tools: `swarm_complete({text})` writes the out message carrying this hop's
-  header (the scheduler's done signal). `swarm_quit({reason?})` exits silently
-  (scheduler records failed). `swarm_send({to, text})` spawns a downstream
-  task with `transfer_send_to` set to the current task and returns the child
-  id without waiting. `swarm_status()` reports the current task and spawned
-  ids. Daemon lifecycle tools stay available in both modes.
+  header (the scheduler's done signal). Scheduler sends a `---swarm-ctl`
+  recycle wire; pi-onlyne intercepts it, sends `swarm_recycled`, stops the
+  watch, clears the slot, and exits its own process. `swarm_quit({reason?})`
+  sends `swarm_recycled` with `quit:<reason>` then self-exits; scheduler marks
+  the hop failed with no retry. The second empty-exit guard runs this same path.
+- `swarm_send({to, text})` spawns a downstream task with
+  `transfer_send_to` set to the current task and returns the child id without
+  waiting. `swarm_status()` reports the current task and spawned ids. Daemon
+  lifecycle tools stay available in both modes.
 - Generic send/reply tools are not registered in the swarm surface: unheaded
   or misheaded writes would pollute the protocol. All swarm IO goes through
   the `swarm_*` tools, whose headers are constructed inside the plugin
   (`renderSwarmHeader`).
-- Exit guard: at `agent_end` with an unfinished hop, one followUp reminder
-  fires; a second quiet window auto-runs `swarm_quit` (failed ledger row).
 - Body protocol lives in `src/swarm.ts` (`parseSwarmHeader`,
   `renderSwarmHeader`, `readSwarmEnabled`); covered by `test/swarm.test.mjs`.
   Old `reply_to` headers parse as ordinary (non-swarm) messages.

package/dist/index.js

@@ -3,10 +3,10 @@ import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join, resolve } from "node:path";
 import { Type } from "typebox";
-import { broadcast, connectDaemon, consumeEvent, loopback, markConsumed, sendWithRetry, shutdownDaemon, stopProcess, subscribe, swarmReady } from "./onlyne.js";
+import { broadcast, connectDaemon, consumeEvent, loopback, markConsumed, sendWithRetry, shutdownDaemon, stopProcess, subscribe, swarmReady, swarmRecycled } from "./onlyne.js";
 import { inboundModeFor, loadConfig, saveConfig } from "./config.js";
 import { findWorkspace } from "./workspace.js";
-import { envTaskId, parseSwarmHeader, readSwarmEnabled, readSwarmModel, terminalHandle, treePathForWorkspace } from "./swarm.js";
+import { envTaskId, parseSwarmCtl, parseSwarmHeader, readSwarmEnabled, readSwarmModel, terminalHandle, treePathForWorkspace } from "./swarm.js";
 import { SwarmSlot } from "./swarm-slot.js";
 const swarmSlot = new SwarmSlot();
 const state = { cwd: process.cwd(), workspace: null, watching: false, owner: "stopped", swarm: false };
@@ -72,6 +72,8 @@ async function historyTaskDone(taskId) {
             const text = m?.text ?? "";
             if (typeof text !== "string" || !text.startsWith("---swarm"))
                 continue;
+            if (text.startsWith("---swarm-ctl"))
+                continue;
             if (m?.direction === "outbound") {
                 const p = parseSwarmHeader(text);
                 if (p)
@@ -111,6 +113,8 @@ async function catchUpSwarmHistory(pi, ctx) {
             const text = m?.text ?? m?.content ?? "";
             if (typeof text !== "string" || !text.startsWith("---swarm"))
                 continue;
+            if (text.startsWith("---swarm-ctl"))
+                continue;
             const p = parseSwarmHeader(text);
             if (!p)
                 continue;
@@ -163,7 +167,7 @@ function handleSwarmInbound(pi, text, eventSeq, ctx) {
     // Slot transitions live in SwarmSlot (unit-tested); here we only mirror
     // the claimed task into session state. A claimed session never accepts
     // another task; downstream work spawns new tasks via swarm_send.
-    const outcome = swarmSlot.handle(pi, text, envTaskId() || undefined);
+    const outcome = swarmSlot.handle(pi, text, envTaskId() || undefined, state.workspace?.root);
     if (outcome === "claimed" || outcome === "yielded") {
         const cur = swarmSlot.task();
         state.swarmTask = { taskId: cur.taskId, from: cur.from, transferSendTo: cur.transferSendTo, attempt: cur.attempt };
@@ -206,6 +210,11 @@ async function startWatch(pi) {
             // task was already delivered (scheduler writes in before the
             // session finishes starting). History replay is idempotent via
             // the slot guard + scheduler task_id dedup.
+            if (parseSwarmCtl(inbound.text)) {
+                const ctl = parseSwarmCtl(inbound.text);
+                void handleSwarmRecycle(ctl.task_id, ctl.reason);
+                return;
+            }
             void catchUpSwarmHistory(pi);
             handleSwarmInbound(pi, inbound.text, line.event_seq);
         }, () => { if (state.socket === socket)
@@ -279,12 +288,54 @@ async function swarmComplete(text) {
     }
     return { ...res, taskId: task.taskId };
 }
-/** swarm_quit: silent exit. No out written; the scheduler records failed. */
+/** swarm_quit: speak, then die by our own hand. Sends the exit notice
+ * (same op the recycle path uses, reason quit:<reason>) so the scheduler
+ * records failed immediately instead of leaving the task pinned running;
+ * then releases the watch and exits this process. The scheduler only ever
+ * closes the tab. */
 async function swarmQuit(reason) {
     const task = state.swarmTask;
+    const taskId = task?.taskId ?? "";
+    const why = `quit:${reason ?? ""}`;
+    try {
+        if (state.workspace && taskId) {
+            await swarmRecycled(state.workspace.socketPath, taskId, terminalHandle(), why);
+        }
+    }
+    catch { /* daemon may be gone; exit anyway */ }
+    clearReminder();
+    try {
+        stopWatch();
+    }
+    catch { /* already stopped */ }
+    state.swarmTask = undefined;
+    swarmSlot.clear();
+    setTimeout(() => process.exit(0), 300);
+    return { quit: true, taskId, reason: reason ?? "" };
+}
+/** Handle a downlink recycle signal: accept, ack, release, self-terminate.
+ * No out is written (the scheduler already recorded the terminal state). */
+async function handleSwarmRecycle(ctlTaskId, reason) {
+    const claimed = swarmSlot.task().taskId;
+    const taskId = ctlTaskId === "*" ? (claimed ?? "") : ctlTaskId;
+    if (claimed && ctlTaskId !== "*" && claimed !== ctlTaskId)
+        return false;
+    const why = `recycle:${reason}`;
+    try {
+        if (state.workspace && taskId) {
+            await swarmRecycled(state.workspace.socketPath, taskId, terminalHandle(), why);
+        }
+    }
+    catch { /* daemon may be gone; exit anyway */ }
+    clearReminder();
+    try {
+        stopWatch();
+    }
+    catch { /* already stopped */ }
     state.swarmTask = undefined;
     swarmSlot.clear();
-    return { quit: true, taskId: task?.taskId, reason: reason ?? "" };
+    setTimeout(() => process.exit(0), 300);
+    return true;
 }
 /** swarm_send: spawn downstream. New UUID, transfer_send_to = current task, fire-and-forget. */
 async function swarmSend(to, text) {

package/dist/onlyne.d.ts

@@ -34,6 +34,7 @@ export declare function connectDaemon(ws: Workspace, startIfMissing?: boolean):
 export declare function shutdownDaemon(ws: Workspace, child?: ChildProcess): Promise<void>;
 export declare function stopProcess(child?: ChildProcess): void;
 export declare function swarmReady(socketPath: string, workspace: string, terminalHandle: string): Promise<any>;
+export declare function swarmRecycled(socketPath: string, taskId: string, terminalHandle: string, reason: string): Promise<any>;
 export declare function consumeEvent(socket: Socket, eventSeq: number): Promise<void>;
 export declare function loopback(socketPath: string, text: string, rawText?: boolean): Promise<any>;
 export declare function markConsumed(socketPath: string, messageId: string): Promise<any>;

package/dist/onlyne.js

@@ -112,6 +112,9 @@ catch { /* ignore */ } }
 export async function swarmReady(socketPath, workspace, terminalHandle) {
     return request(socketPath, { id: `swarm-ready-${Date.now()}`, op: "swarm_ready", text: JSON.stringify({ workspace, terminal_handle: terminalHandle }) });
 }
+export async function swarmRecycled(socketPath, taskId, terminalHandle, reason) {
+    return request(socketPath, { id: `swarm-recycled-${Date.now()}`, op: "swarm_recycled", text: JSON.stringify({ task_id: taskId, terminal_handle: terminalHandle, reason }) });
+}
 export async function consumeEvent(socket, eventSeq) {
     return new Promise((resolve) => { try {
         socket.write(`${JSON.stringify({ id: `consume-${Date.now()}`, op: "consume", event_seq: eventSeq })}\n`, () => resolve());

package/dist/swarm-prompt.d.ts

@@ -0,0 +1,12 @@
+export interface SwarmPromptConfig {
+    enabled: boolean;
+    template?: string;
+    fallback?: string;
+}
+export declare function readSwarmPromptConfig(workspaceRoot: string): SwarmPromptConfig;
+export declare function resolveSwarmPrompt(workspaceRoot: string, header: {
+    task_id: string;
+    from: string;
+    transfer_send_to: string;
+    attempt: number;
+}, payload: string): string | null;

package/dist/swarm-prompt.js

@@ -0,0 +1,45 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+const DEFAULT_PROMPT = `Onlyne swarm task {task_id} (from {from}):
+
+{payload}
+
+This session carries this one task only. Restore context from files, work, spawn continuations with swarm_send when another unit must continue, then exit with swarm_complete. Downstream results travel through files and the ledger; nothing waits here.`;
+export function readSwarmPromptConfig(workspaceRoot) {
+    const cfgPath = join(workspaceRoot, ".pi", "onlyne.json");
+    if (!existsSync(cfgPath)) {
+        return { enabled: true, fallback: DEFAULT_PROMPT };
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(cfgPath, "utf8"));
+        const sw = parsed?.swarm_prompt;
+        if (sw === false || (sw && sw.enabled === false))
+            return { enabled: false, fallback: DEFAULT_PROMPT };
+        return {
+            enabled: sw?.enabled !== false,
+            template: sw?.template,
+            fallback: sw?.fallback ?? DEFAULT_PROMPT,
+        };
+    }
+    catch {
+        return { enabled: true, fallback: DEFAULT_PROMPT };
+    }
+}
+export function resolveSwarmPrompt(workspaceRoot, header, payload) {
+    const cfg = readSwarmPromptConfig(workspaceRoot);
+    if (!cfg.enabled)
+        return null;
+    let tmpl = cfg.fallback ?? DEFAULT_PROMPT;
+    if (cfg.template) {
+        const abs = join(workspaceRoot, cfg.template);
+        if (existsSync(abs)) {
+            tmpl = readFileSync(abs, "utf8");
+        }
+    }
+    return tmpl
+        .replace(/{task_id}/g, header.task_id)
+        .replace(/{from}/g, header.from)
+        .replace(/{transfer_send_to}/g, header.transfer_send_to)
+        .replace(/{attempt}/g, String(header.attempt))
+        .replace(/{payload}/g, payload);
+}

package/dist/swarm-slot.d.ts

@@ -21,7 +21,7 @@ export declare class SwarmSlot {
     private transfer;
     private attempt;
     private sentChildIds;
-    handle(pi: SwarmPi, text: string, preferredTaskId?: string): SwarmHandleResult;
+    handle(pi: SwarmPi, text: string, preferredTaskId?: string, workspaceRoot?: string): SwarmHandleResult;
     task(): {
         taskId?: string;
         from: string;
@@ -35,7 +35,7 @@ export declare class SwarmSlot {
 }
 /** Test seam: fresh slot without touching module-global pi-onlyne state. */
 export declare function __swarmSlotForTest(): {
-    handle: (pi: SwarmPi, text: string, preferredTaskId?: string) => SwarmHandleResult;
+    handle: (pi: SwarmPi, text: string, preferredTaskId?: string, workspaceRoot?: string) => SwarmHandleResult;
     task: () => {
         taskId?: string;
         from: string;

package/dist/swarm-slot.js

@@ -1,4 +1,5 @@
 import { parseSwarmHeader } from "./swarm.js";
+import { resolveSwarmPrompt } from "./swarm-prompt.js";
 /**
  * Single atomic task slot for swarm mode, extracted for unit testing.
  * index.ts delegates its state transitions here; the only coupling is the
@@ -10,7 +11,7 @@ export class SwarmSlot {
     transfer = "";
     attempt = 1;
     sentChildIds = [];
-    handle(pi, text, preferredTaskId) {
+    handle(pi, text, preferredTaskId, workspaceRoot) {
         const parsed = parseSwarmHeader(text);
         if (!parsed)
             return "not-swarm";
@@ -24,7 +25,7 @@ export class SwarmSlot {
             // Cold start needs triggerTurn: followUp alone only queues behind an
             // active turn, and a fresh session has none. sendMessage with
             // triggerTurn starts the model turn immediately.
-            pi.sendMessage({ customType: "onlyne-swarm-task", content: `Onlyne swarm task ${header.task_id} (from ${header.from}):\n\n${payload}\n\nThis session carries this one task only. Restore context from files, work, spawn continuations with swarm_send when another unit must continue, then exit with swarm_complete. Downstream results travel through files and the ledger; nothing waits here.`, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+            pi.sendMessage({ customType: "onlyne-swarm-task", content: resolveSwarmPrompt(workspaceRoot ?? process.cwd(), header, payload) ?? payload, display: true }, { triggerTurn: true, deliverAs: "followUp" });
             return "claimed";
         }
         // Env-task preemption: the scheduler injected ONLYNE_SWARM_TASK for
@@ -37,7 +38,7 @@ export class SwarmSlot {
             this.transfer = header.transfer_send_to;
             this.attempt = header.attempt;
             this.sentChildIds = [];
-            pi.sendMessage({ customType: "onlyne-swarm-task", content: `Onlyne swarm task ${header.task_id} (from ${header.from}):\n\n${payload}\n\nThis session carries this one task only. Restore context from files, work, spawn continuations with swarm_send when another unit must continue, then exit with swarm_complete. Downstream results travel through files and the ledger; nothing waits here.`, display: true }, { triggerTurn: true, deliverAs: "followUp" });
+            pi.sendMessage({ customType: "onlyne-swarm-task", content: resolveSwarmPrompt(workspaceRoot ?? process.cwd(), header, payload) ?? payload, display: true }, { triggerTurn: true, deliverAs: "followUp" });
             return "yielded";
         }
         return "not-swarm";
@@ -63,7 +64,7 @@ export class SwarmSlot {
 export function __swarmSlotForTest() {
     const slot = new SwarmSlot();
     return {
-        handle: (pi, text, preferredTaskId) => slot.handle(pi, text, preferredTaskId),
+        handle: (pi, text, preferredTaskId, workspaceRoot) => slot.handle(pi, text, preferredTaskId, workspaceRoot),
         task: () => slot.task(),
         taskId: () => slot.taskIdOf(),
         noteSpawned: (childId) => slot.noteSpawned(childId),

package/dist/swarm.d.ts

@@ -11,6 +11,15 @@ export interface SwarmMessage {
 }
 /** Parse a `---swarm` body header. Returns null for non-swarm messages. */
 export declare function parseSwarmHeader(text: string): SwarmMessage | null;
+/** Downlink control wire (scheduler -> session). Header-only marker the
+ * session intercepts before the model sees anything. `task_id` is "*" for
+ * "whatever this session holds". */
+export interface SwarmCtl {
+    op: string;
+    task_id: string;
+    reason: string;
+}
+export declare function parseSwarmCtl(text: string): SwarmCtl | null;
 /** Render a swarm body header in front of a Markdown payload. */
 export declare function renderSwarmHeader(header: SwarmHeader, role: string, payloadMarkdown: string): string;
 /** Read the `[swarm] enabled` flag from the workspace .onlyne/config.toml. */

package/dist/swarm.js

@@ -57,6 +57,36 @@ export function parseSwarmHeader(text) {
         return null;
     return { header: { task_id: task_id.trim(), from, transfer_send_to, attempt }, payload };
 }
+export function parseSwarmCtl(text) {
+    if (!text.startsWith("---swarm-ctl\n"))
+        return null;
+    const rest = text.slice("---swarm-ctl\n".length);
+    const end = rest.indexOf("\n---");
+    if (end < 0)
+        return null;
+    let op;
+    let task_id = "*";
+    let reason = "";
+    for (const line of rest.slice(0, end).split("\n")) {
+        const t = line.trim();
+        if (!t || t.startsWith("#"))
+            continue;
+        const i = t.indexOf(":");
+        if (i < 0)
+            continue;
+        const k = t.slice(0, i).trim();
+        const v = t.slice(i + 1).trim().replace(/^["']|["']$/g, "");
+        if (k === "op")
+            op = v;
+        else if (k === "task_id")
+            task_id = v || "*";
+        else if (k === "reason")
+            reason = v;
+    }
+    if (op !== "recycle")
+        return null;
+    return { op, task_id, reason };
+}
 /** 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`;

package/package.json

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