pi-onlyne 0.9.1 → 1.0.0

package/src/relay.test.mjs

@@ -0,0 +1,210 @@
+// The relay guard's policy reader and its verdict.
+//
+// The reader is the half that decides whether a workspace guards anything at
+// all: a missing file, a malformed line or an unknown key must leave the guard
+// off (or leave only the sound half of it on) instead of refusing completions
+// on a policy nobody wrote. The client's injected policy outranks the file, and
+// the file is the fallback a manual installation still has.
+
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { afterEach, test } from "node:test";
+
+import {
+  DEFAULT_RELAY,
+  RELAY_ENV_COUNT,
+  RELAY_ENV_REQUIRED,
+  RELAY_FILE,
+  envRelay,
+  loadRelay,
+  parseRelay,
+  relayEnabled,
+  relayPath,
+  relayRefusal,
+} from "./relay.mjs";
+
+const cleanups = [];
+afterEach(() => {
+  while (cleanups.length > 0) cleanups.pop()();
+});
+
+/** One temp directory holding a `relay.toml` body, when given one. */
+function workspace(body) {
+  const dir = mkdtempSync(join(tmpdir(), "pi-onlyne-relay-"));
+  cleanups.push(() => rmSync(dir, { recursive: true, force: true }));
+  if (body !== undefined) {
+    writeFileSync(join(dir, RELAY_FILE), body);
+  }
+  return dir;
+}
+
+test("a missing policy file leaves the guard off", () => {
+  const dir = workspace();
+  const relay = loadRelay({ path: join(dir, RELAY_FILE), env: {} });
+  assert.deepEqual(
+    { required: relay.required, count: relay.count },
+    { required: DEFAULT_RELAY.required, count: DEFAULT_RELAY.count },
+  );
+  assert.equal(relay.present, false);
+  assert.equal(relay.source, "none");
+  assert.equal(relay.warning, null);
+  assert.equal(relayEnabled(relay), false);
+  assert.equal(relay.path, join(dir, RELAY_FILE));
+});
+
+test("the default policy path is the one beside the plugin's package.json", () => {
+  const path = relayPath();
+  assert.ok(path.endsWith(`/${RELAY_FILE}`), path);
+  // A generated workspace loads the vendored copy of this package, so the
+  // policy has to travel inside it (`crates/onlyne-server/src/generate.rs`).
+  assert.ok(existsSync(join(dirname(path), "package.json")), dirname(path));
+});
+
+test("both policy keys are honoured, comments and blank lines included", () => {
+  const list = parseRelay('# which handoffs this session owes\nrelay_required = ["writer", "auditor"]\n');
+  assert.deepEqual(list.required, ["writer", "auditor"]);
+  assert.equal(list.count, null);
+  assert.equal(list.warning, null);
+
+  const counted = parseRelay("relay_required_count = 2 # distinct downstream roles\n");
+  assert.deepEqual(counted.required, []);
+  assert.equal(counted.count, 2);
+  assert.equal(counted.warning, null);
+
+  const both = parseRelay('relay_required = []\nrelay_required_count = 3\n');
+  assert.deepEqual(both.required, []);
+  assert.equal(both.count, 3);
+});
+
+test("a body outside the closed subset warns and keeps the default", () => {
+  const unsupported = parseRelay(
+    ["[relay]", 'relay_required = [', '  "writer",', "]", "relay_required_count = 0", "write = true"].join("\n"),
+    "relay.toml",
+  );
+  assert.deepEqual(unsupported.required, []);
+  assert.equal(unsupported.count, null);
+  assert.match(unsupported.warning, /relay\.toml:1: not a `key = value` line/);
+  assert.match(unsupported.warning, /relay\.toml:2: relay_required must be one line/);
+  assert.match(unsupported.warning, /relay\.toml:4: not a `key = value` line/);
+  assert.match(unsupported.warning, /relay\.toml:5: relay_required_count must be a positive integer/);
+  assert.match(unsupported.warning, /relay\.toml:6: unknown key "write"/);
+
+  // One bad line does not take the sound one with it.
+  const partial = parseRelay('relay_required = ["writer"]\nrelay_required_count = two\n');
+  assert.deepEqual(partial.required, ["writer"]);
+  assert.equal(partial.count, null);
+  assert.match(partial.warning, /relay_required_count must be a positive integer/);
+});
+
+test("a policy file on disk reaches the caller with its warnings", () => {
+  const dir = workspace('relay_required = ["writer"]\nnonsense\n');
+  const relay = loadRelay({ path: join(dir, RELAY_FILE), env: {} });
+  assert.equal(relay.present, true);
+  assert.equal(relay.source, "file");
+  assert.deepEqual(relay.required, ["writer"]);
+  assert.equal(relayEnabled(relay), true);
+  assert.match(relay.warning, /relay\.toml:2:/);
+});
+
+test("an injected policy is the one in force, and the file is not consulted", () => {
+  const dir = workspace('relay_required = ["legacy"]\n');
+  const relay = loadRelay({
+    path: join(dir, RELAY_FILE),
+    env: { [RELAY_ENV_REQUIRED]: "writer, auditor", [RELAY_ENV_COUNT]: "2" },
+  });
+  assert.deepEqual(relay.required, ["writer", "auditor"]);
+  assert.equal(relay.count, 2);
+  assert.equal(relay.source, "env");
+  assert.equal(relay.present, false, "the file is not where this policy came from");
+  assert.equal(relay.path, join(dir, RELAY_FILE));
+  assert.equal(relay.warning, null);
+  assert.equal(relayEnabled(relay), true);
+  // Both forms travel when the spec names both, and the list still decides.
+  assert.match(relayRefusal(relay, ["builder", "auditor"]), /missing handoff to: writer/);
+});
+
+test("the environment spells the spec's two keys", () => {
+  const listed = envRelay({ [RELAY_ENV_REQUIRED]: "writer,, auditor ," });
+  assert.deepEqual(listed.required, ["writer", "auditor"]);
+  assert.equal(listed.count, null);
+  assert.equal(listed.specified, true);
+  assert.equal(listed.warning, null);
+
+  const counted = envRelay({ [RELAY_ENV_COUNT]: "2" });
+  assert.deepEqual(counted.required, []);
+  assert.equal(counted.count, 2);
+  assert.equal(counted.specified, true);
+
+  const nothing = envRelay({});
+  assert.deepEqual(nothing.required, []);
+  assert.equal(nothing.count, null);
+  assert.equal(nothing.specified, false, "an absent pair is not a policy");
+  assert.equal(nothing.warning, null);
+});
+
+test("an unparsable variable is reported and the file keeps its turn", () => {
+  const dir = workspace('relay_required = ["legacy"]\n');
+  const relay = loadRelay({
+    path: join(dir, RELAY_FILE),
+    env: { [RELAY_ENV_COUNT]: "two" },
+  });
+  assert.equal(relay.source, "file");
+  assert.equal(relay.present, true);
+  assert.deepEqual(relay.required, ["legacy"]);
+  assert.equal(relay.count, null);
+  assert.equal(relayEnabled(relay), true);
+  assert.match(relay.warning, /ONLYNE_RELAY_COUNT must be a positive integer, got "two"/);
+
+  // A variable that names no role is not a policy either; with no file behind
+  // it the guard stays off, and the reason it is off is reported.
+  const off = loadRelay({ path: join(workspace(), RELAY_FILE), env: { [RELAY_ENV_REQUIRED]: ", ," } });
+  assert.deepEqual(off.required, []);
+  assert.equal(off.count, null);
+  assert.equal(off.source, "none");
+  assert.equal(off.present, false);
+  assert.equal(relayEnabled(off), false);
+  assert.match(off.warning, /ONLYNE_RELAY_REQUIRED: no role names in ", ,"/);
+});
+
+test("the verdict names every missing edge, and the way out", () => {
+  const refusal = relayRefusal({ required: ["writer", "auditor"] }, ["auditor"]);
+  assert.match(refusal, /^relay guard: missing handoff to: writer \(/);
+  assert.match(refusal, /force:true and a non-empty reason/);
+  assert.match(refusal, /"relay-guard-forced: <reason>"/);
+  assert.equal(relayRefusal({ required: ["writer"] }, ["writer"]), null);
+  // The list wins when both keys are present, however many roles were reached.
+  assert.match(
+    relayRefusal({ required: ["writer"], count: 2 }, ["builder", "auditor"]),
+    /missing handoff to: writer/,
+  );
+});
+
+test("count mode wants distinct downstream roles, not echoes", () => {
+  const policy = { required: [], count: 2 };
+  const self = "planner";
+  const upstream = "supervisor";
+  // A send back to the role that assigned this task, and a note to itself, are
+  // not handoffs further down the cluster.
+  const echoed = relayRefusal(policy, [upstream, self], { role: self, upstream });
+  assert.match(echoed, /missing handoff: 2 of 2 required distinct downstream roles/);
+  assert.match(echoed, /delivered downstream: none/);
+
+  const one = relayRefusal(policy, [upstream, self, "builder"], { role: self, upstream });
+  assert.match(one, /missing handoff: 1 of 2 required distinct downstream roles/);
+  assert.match(one, /delivered downstream: builder/);
+
+  const enough = relayRefusal(policy, [upstream, self, "builder", "writer"], { role: self, upstream });
+  assert.equal(enough, null);
+  // Two handoffs to the same role are one edge, not two.
+  const repeated = relayRefusal(policy, ["builder", "builder"], { role: self, upstream });
+  assert.match(repeated, /missing handoff: 1 of 2/);
+});
+
+test("no policy, or a policy that guards nothing, never refuses", () => {
+  assert.equal(relayRefusal(DEFAULT_RELAY, []), null);
+  assert.equal(relayRefusal({ required: [], count: 0 }, []), null);
+  assert.equal(relayRefusal(undefined, []), null);
+  assert.equal(relayEnabled({ required: [], count: null }), false);
+});

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 dbydd
-
-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/SPEC.md

@@ -1,124 +0,0 @@
-# pi-onlyne SPEC
-
-## Scope
-
-Pi extension for Onlyne. Onlyne remains a workspace-local IM broker; this extension owns Pi session lifecycle, watch behavior, message injection, send tools, and a small config surface.
-
-## v1 Decisions
-
-- Watch is configurable; default manual.
-- `/onlyne` provides argument completions for its supported subcommands, including daemon lifecycle commands.
-- `watch on` connects to the workspace-local `.onlyne/run/s`; if unavailable, it starts a Pi-owned workspace daemon.
-- `/onlyne daemon start|stop|restart` is the preferred lifecycle surface. Agents must not use ad-hoc `nohup onlyne run`, `pkill -f 'onlyne run'`, or global launchd/systemd jobs when pi-onlyne owns the daemon.
-- Inbound events come from Onlyne `subscribe_events`; no polling.
-- Inbound mode is rule-based: `auto-handle`, `queue-only`, or `muted`.
-- Outbound defaults to `guarded-explicit`: prefer tool reply, fallback to final text, else send configured error text.
-- Send tools default to Markdown and may pass `raw_text: true` to Onlyne for literal text.
-- Broadcast sends concurrently with per-target retry and per-target results.
-- Loopback inbound messages wake Pi without creating a reply obligation.
-- `/handshake` inbound messages are Onlyne control messages and must not be surfaced to Pi as agent work.
-- After pi surfaces an inbound follow-up, it calls `mark_io_consumed` so Onlyne FIFO `out_cursor = "consume"` stays synchronized with pi notifications.
-- FIFO IO itself remains owned by the Onlyne daemon; pi-onlyne does not open `.onlyne/channels/*/in|out` directly.
-
-## Config
-
-Stored in project `.pi/onlyne.json`:
-
-```json
-{
-  "watch": { "autoStart": false },
-  "inbound": { "defaultMode": "auto-handle", "rules": [] },
-  "outbound": {
-    "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):
-
-- `onlyne_reply({ text })`
-- `onlyne_send({ channelId, text, rawText? })`
-- `onlyne_broadcast({ targets, text, rawText? })`
-- `onlyne_loopback({ text, rawText? })`
-- `onlyne_mark_no_reply({ reason? })`
-- `onlyne_daemon_start/stop/restart`
-
-Swarm mode (`[swarm] enabled`, see below):
-
-- `swarm_complete({ text })`
-- `swarm_quit({ reason? })`
-- `swarm_send({ to, text })`
-- `swarm_status()`
-- `onlyne_daemon_start/stop/restart`
-
-One session sees one toolset. The surface is chosen at `session_start` from
-`[swarm]` and applied with `setActiveTools` when the Pi API exists.
-
-## Deferred
-
-- Attachments.
-- Auth QR/secret editing TUI.
-- Schedules.
-- Target groups.
-
-## Swarm mode (v2, amendment-1)
-
-- Switch: `/onlyne swarm on|off|status`. On/off persists to the workspace
-  `.onlyne/config.toml` `[swarm] enabled` flag and restarts watch. Status line
-  and `session_start` banner report `swarm` vs `ready`.
-- When swarm is on, generic in/out auto-handling is disabled: the scheduler owns
-  input/output. Only loopback messages carrying a `---swarm` body header enter
-  the session, via the `followUp` task queue.
-- Session model: one session carries exactly one scheduler-delivered hop. A
-  `delivery: scheduler` header field claims the slot; raw `swarm_send` relay
-  wires and out wires omit it and never claim. Any further delivered header
-  while claimed is ignored (the scheduler always opens a new session, so this
-  guard never fires on the normal path). No waiting, no callbacks, no parent
-  bookkeeping.
-- Startup handshake: swarm watch sends the `swarm_ready` op
-  (`{workspace, terminal_handle}`) so the scheduler can match a pending task.
-  `ONLYNE_SWARM_TASK` env and `ORCA_TERMINAL_HANDLE`/`ONLYNE_TERMINAL_HANDLE`
-  provide fallback correlation. **`ONLYNE_SWARM_TASK` is a hard binding:** a
-  newly created terminal may replay history only for that exact task id. If
-  its FIFO delivery has not reached history yet, the session waits for the
-  live inbound event; it never claims a newest/old workspace-local task.
-  Sessions with no env task (manual ready pool) retain newest-unclosed
-  fallback replay.
-- Hop activity (v0.9.1, R4): `agent_start` with a live claimed task sends
-  `swarm_busy` (`{workspace, terminal_handle, task_id}`); `agent_end` with
-  the turn ended and no out sends `swarm_idle` (same fields plus
-  `pending_exit`, mirroring whether the hop still awaits `swarm_complete`).
-  Both are fire-and-forget over the existing swarm event channel; the
-  scheduler treats missing rows as race residue and drives its own TTLs.
-- Tools: `swarm_complete({text})` writes the out message carrying this hop's
-  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`).
-- 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/config.d.ts

@@ -1,32 +0,0 @@
-export type InboundMode = "auto-handle" | "queue-only" | "muted";
-export type ReplyMode = "guarded-explicit" | "explicit-only" | "implicit-final";
-export interface OnlyneRule {
-    channel: string;
-    conversation?: string;
-    mode: InboundMode;
-}
-export interface OnlyneConfig {
-    watch: {
-        autoStart: boolean;
-    };
-    inbound: {
-        defaultMode: InboundMode;
-        rules: OnlyneRule[];
-    };
-    outbound: {
-        defaultReplyMode: ReplyMode;
-        guardedExplicit: {
-            reminders: number;
-            noOutputFallbackText: string;
-        };
-        retry: {
-            attempts: number;
-            concurrency: number;
-        };
-    };
-}
-export declare const defaultConfig: OnlyneConfig;
-export declare function configPath(cwd: string): string;
-export declare function loadConfig(cwd: string): OnlyneConfig;
-export declare function saveConfig(cwd: string, config: OnlyneConfig): void;
-export declare function inboundModeFor(config: OnlyneConfig, channel: string, conversation?: string): InboundMode;

package/dist/config.js

@@ -1,19 +0,0 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
-export const defaultConfig = {
-    watch: { autoStart: false },
-    inbound: { defaultMode: "auto-handle", rules: [] },
-    outbound: { defaultReplyMode: "guarded-explicit", guardedExplicit: { reminders: 2, noOutputFallbackText: "Onlyne/Pi error: no valid reply was produced." }, retry: { attempts: 2, concurrency: 8 } },
-};
-export function configPath(cwd) { return join(cwd, ".pi", "onlyne.json"); }
-export function loadConfig(cwd) {
-    const path = configPath(cwd);
-    if (!existsSync(path))
-        return structuredClone(defaultConfig);
-    const parsed = JSON.parse(readFileSync(path, "utf8"));
-    return { ...structuredClone(defaultConfig), ...parsed, watch: { ...defaultConfig.watch, ...parsed.watch }, inbound: { ...defaultConfig.inbound, ...parsed.inbound, rules: parsed.inbound?.rules ?? [] }, outbound: { ...defaultConfig.outbound, ...parsed.outbound, guardedExplicit: { ...defaultConfig.outbound.guardedExplicit, ...parsed.outbound?.guardedExplicit }, retry: { ...defaultConfig.outbound.retry, ...parsed.outbound?.retry } } };
-}
-export function saveConfig(cwd, config) { const path = configPath(cwd); mkdirSync(dirname(path), { recursive: true }); writeFileSync(path, `${JSON.stringify(config, null, 2)}\n`); }
-export function inboundModeFor(config, channel, conversation) {
-    return config.inbound.rules.find((r) => r.channel === channel && r.conversation === conversation)?.mode ?? config.inbound.rules.find((r) => r.channel === channel && !r.conversation)?.mode ?? config.inbound.defaultMode;
-}

package/dist/index.d.ts

@@ -1,27 +0,0 @@
-import { type ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { type Workspace } from "./workspace.js";
-import { type SwarmReportKind } from "./swarm.js";
-import { type StateContext } from "./session.js";
-/** Swarm task slot: one session carries exactly one hop. No waiting, no callbacks. */
-interface SwarmTask {
-    taskId: string;
-    from: string;
-    transferSendTo: string;
-    attempt: number;
-}
-export default function onlyne(pi: ExtensionAPI): void;
-/** Test seam: drive the lifecycle-report wiring against a stub daemon socket.
- * No live pi session and no real daemon are involved; the seam exposes the
- * same closures the hooks call. Mirrors `__swarmSlotForTest`. */
-export declare function __swarmReportForTest(): {
-    setWorkspace: (ws: Workspace | null) => void;
-    beginSession: (appendEntry: StateContext["appendEntry"], taskId: string) => {
-        generation: number;
-        seq: number;
-    };
-    setTask: (task?: SwarmTask) => void;
-    reportTaskId: () => string | null;
-    emit: (kind: SwarmReportKind) => Promise<boolean>;
-    beat: () => void;
-};
-export {};