pi-onlyne 1.2.1 → 2.0.0

package/src/pi-surface.test.mjs

@@ -0,0 +1,232 @@
+// The pi-facing half of the surface: exactly what `wakeUser` hands
+// `pi.sendUserMessage`. Every shape asserted here is pi's own declaration —
+// `sendUserMessage(content: string | (TextContent | ImageContent)[])`, with
+// `ImageContent` the flat `{ type: "image", data, mimeType }` of
+// `@earendil-works/pi-ai` (measured against pi 0.87.1). pi normalizes each part
+// before it builds the message, so a part in any other shape — the nested
+// Anthropic `source: { type, media_type, data }` this plugin once sent — stops
+// the whole delivery inside pi, and pi reports that in its own pane without
+// handing anything back to the plugin.
+//
+// The role prose is the other half: it becomes one section of pi's system prompt
+// at `before_agent_start` (`event.systemPromptOptions.sections`, the mutable
+// prompt options pi hands the handler) and never a message. The section's value
+// is the client's own text, byte for byte.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+import { PROSE_SECTION, createSurface } from "./pi-surface.mjs";
+
+/**
+ * One delivery text in the shape the client renders and `agent.mjs` injects.
+ * The surface carries it verbatim; it composes no part of it.
+ */
+const TASK_TEXT = "From planner:\n\nbuild it";
+
+/** One inline image part in the shape the agent hands the surface. */
+const PNG_PART = { type: "image", mime: "image/png", data: "iVBORw0KGgoAAAANSUhEUg==", name: "shot.png" };
+
+/** pi's own `UserMessage.content` for that text and that part, key for key. */
+const PNG_CONTENT = [
+  { type: "text", text: TASK_TEXT },
+  { type: "image", data: "iVBORw0KGgoAAAANSUhEUg==", mimeType: "image/png" },
+];
+
+/**
+ * A surface over a hand-written fake pi: every `sendUserMessage` arrives with
+ * the arguments it was given, recorded whole, and every surface log line with
+ * it. `refuse` makes one call throw synchronously, the way a pi that does not
+ * know an option does.
+ * @param {{ refuse?: (content: unknown, options: unknown) => boolean }} [options]
+ */
+function fakeSurface({ refuse = null } = {}) {
+  const calls = [];
+  const messages = [];
+  const lines = [];
+  const surface = createSurface({
+    pi: {
+      sendUserMessage(content, options) {
+        calls.push({ content, options });
+        if (refuse?.(content, options)) throw new Error("this pi does not take that option");
+      },
+      // Recorded, never expected: no part of this plugin is a conversation
+      // message any more, and the prose is the one that could creep back.
+      sendMessage(message, options) {
+        messages.push({ message, options });
+      },
+    },
+    log: (line) => lines.push(line),
+    context: () => null,
+  });
+  return { calls, messages, lines, surface };
+}
+
+test("an image attachment reaches pi as one flat image content part beside the task text", () => {
+  const { calls, lines, surface } = fakeSurface();
+
+  assert.equal(surface.wakeUser(TASK_TEXT, [PNG_PART]), true);
+  assert.equal(calls.length, 1, "one message, not one call per part");
+  // The whole array, key for key: a nested `source` / `mediaType` part carries
+  // keys pi does not declare and lacks the two it does, so it cannot pass this.
+  assert.deepEqual(calls[0].content, PNG_CONTENT);
+  assert.deepEqual(lines, [], "a readable attachment is delivered, not reported");
+});
+
+test("task text with no attachments reaches pi as a bare string", () => {
+  const { calls, surface } = fakeSurface();
+
+  assert.equal(surface.wakeUser(TASK_TEXT, []), true);
+  assert.equal(calls.length, 1);
+  // pi takes the string path of `content`; a one-element array of text parts is
+  // a different message and a needless normalization round trip.
+  assert.equal(calls[0].content, TASK_TEXT);
+});
+
+test("an attachment pi cannot read is dropped, logged, and the task text still travels", () => {
+  const { calls, lines, surface } = fakeSurface();
+
+  // Each part below fails one clause of what pi needs: no base64 data, no media
+  // type, an empty media type. Sending any of them stops the whole delivery
+  // inside pi, so all three go and the text goes alone.
+  assert.equal(
+    surface.wakeUser(TASK_TEXT, [
+      { type: "image", mime: "image/png", name: "no-data.png" },
+      { type: "image", data: "iVBORw0KGgoAAAANSUhEUg==", name: "no-mime.png" },
+      { type: "image", data: "iVBORw0KGgoAAAANSUhEUg==", mime: "" },
+    ]),
+    true,
+  );
+  assert.equal(calls.length, 1);
+  assert.equal(calls[0].content, TASK_TEXT);
+  assert.equal(lines.length, 1);
+  assert.match(lines[0], /3 dropped/);
+  assert.match(lines[0], /the task text still went/);
+
+  // Dropping is per part: a usable image beside an unusable one still rides.
+  assert.equal(surface.wakeUser(TASK_TEXT, [{ type: "image", mime: "image/png" }, PNG_PART]), true);
+  assert.deepEqual(calls[1].content, PNG_CONTENT);
+  assert.equal(lines.length, 2);
+  assert.match(lines[1], /1 dropped/);
+});
+
+test("delivery asks for followUp and a refusal of that option retries with the same content", () => {
+  const asked = fakeSurface();
+
+  assert.equal(asked.surface.wakeUser(TASK_TEXT, [PNG_PART]), true);
+  assert.deepEqual(asked.calls, [{ content: PNG_CONTENT, options: { deliverAs: "followUp" } }]);
+
+  // An older pi throws on the option it does not know. The message itself is
+  // fine, so the retry drops the option and keeps the content.
+  const refusing = fakeSurface({ refuse: (_content, options) => Boolean(options) });
+
+  assert.equal(refusing.surface.wakeUser(TASK_TEXT, [PNG_PART]), true);
+  assert.equal(refusing.calls.length, 2);
+  assert.deepEqual(refusing.calls[0].options, { deliverAs: "followUp" });
+  assert.equal(refusing.calls[1].options, undefined);
+  assert.deepEqual(refusing.calls[1].content, PNG_CONTENT);
+  assert.deepEqual(refusing.lines, [], "a delivery that landed on the retry is not a failure");
+});
+
+/** One role prose, in the shape the client renders and `agent.mjs` hands over. */
+const PROSE_TEXT = "Read the incoming task.\n\nAnswer in the house style.\n";
+
+/** The shift `before_agent_start` hands a handler: the prompt options it is about to render. */
+const promptEvent = () => ({ systemPromptOptions: { sections: {} } });
+
+test("the role prose becomes one system-prompt section, byte for byte", () => {
+  const { surface, calls, messages } = fakeSurface();
+  assert.equal(surface.roleProse(PROSE_TEXT), true);
+
+  const event = promptEvent();
+  assert.equal(surface.applyRoleProse(event), true);
+  assert.deepEqual(event.systemPromptOptions.sections, { [PROSE_SECTION]: PROSE_TEXT });
+  // The client's bytes exactly: no prefix naming the role, no label, no newline
+  // of this plugin's own.
+  assert.equal(event.systemPromptOptions.sections[PROSE_SECTION], PROSE_TEXT);
+  // And it travelled as no message at all: the injection that used to put the
+  // prose in the transcript's message stream is gone.
+  assert.deepEqual(messages, [], "the role prose is not a conversation message");
+  assert.deepEqual(calls, [], "and not a user message either");
+});
+
+test("no prose arrived is no section written", () => {
+  const { surface } = fakeSurface();
+  const event = promptEvent();
+
+  assert.equal(surface.applyRoleProse(event), false);
+  assert.deepEqual(event.systemPromptOptions.sections, {});
+});
+
+test("every run writes the section again, because pi rebuilds the prompt options per run", () => {
+  const { surface } = fakeSurface();
+  surface.roleProse(PROSE_TEXT);
+
+  const first = promptEvent();
+  const second = promptEvent();
+  assert.equal(surface.applyRoleProse(first), true);
+  assert.equal(surface.applyRoleProse(second), true);
+  assert.deepEqual(second.systemPromptOptions.sections, first.systemPromptOptions.sections);
+
+  // A later prose — the spec edited between two runs of one session — takes the
+  // section over rather than being masked by the text that was written first.
+  surface.roleProse("Answer in the log style.");
+  const third = promptEvent();
+  surface.applyRoleProse(third);
+  assert.deepEqual(third.systemPromptOptions.sections, { [PROSE_SECTION]: "Answer in the log style." });
+});
+
+test("a pi whose prompt options carry no sections reports it once and carries no prose", () => {
+  const { surface, lines } = fakeSurface();
+  surface.roleProse(PROSE_TEXT);
+
+  assert.equal(surface.applyRoleProse({ systemPromptOptions: {} }), false);
+  assert.equal(surface.applyRoleProse({}), false);
+  assert.equal(lines.length, 1, "one line, not one per run");
+  assert.match(lines[0], /no instruction layer/);
+});
+
+/**
+ * A surface over a fake pi that answers the two questions the phase is read
+ * from, plus the cases where pi answers neither.
+ * @param {{ isIdle?: () => boolean, hasPendingMessages?: () => boolean, throwOn?: "idle" | "pending" }} [pi]
+ */
+function idleSurface(pi = {}) {
+  const lines = [];
+  return {
+    lines,
+    surface: createSurface({ pi, log: (line) => lines.push(line), context: () => pi }),
+  };
+}
+
+test("only a session waiting on its next message reads as idle", async () => {
+  const waiting = idleSurface({ isIdle: () => true, hasPendingMessages: () => false });
+  assert.equal(await waiting.surface.waitingForInput(), true);
+
+  // A queued continuation is input already on its way, so the session is not
+  // waiting for the user even though no turn is running.
+  const queued = idleSurface({ isIdle: () => true, hasPendingMessages: () => true });
+  assert.equal(await queued.surface.waitingForInput(), false);
+
+  // A turn in flight, a retry, and a compaction all read as not idle here.
+  const busy = idleSurface({ isIdle: () => false, hasPendingMessages: () => false });
+  assert.equal(await busy.surface.waitingForInput(), false);
+});
+
+test("a phase pi was never asked about reads as running, not idle", async () => {
+  // The probes are optional members of an older pi, and a session with no
+  // context yet has witnessed nothing: both answer `false` rather than guess.
+  const noProbes = idleSurface({});
+  assert.equal(await noProbes.surface.waitingForInput(), false);
+
+  const noContext = createSurface({ pi: { isIdle: () => true }, log: () => {}, context: () => null });
+  assert.equal(await noContext.waitingForInput(), false);
+
+  const throwing = idleSurface({
+    isIdle: () => true,
+    hasPendingMessages: () => {
+      throw new Error("pi is mid-replay");
+    },
+  });
+  assert.equal(await throwing.surface.waitingForInput(), false);
+});

package/src/protocol.mjs

@@ -36,8 +36,12 @@ export const SEQ_BASE = 1000;
 /** Heartbeat cadence while a task is active (`heartbeat_timeout_ms` is 30s). */
 export const DEFAULT_HEARTBEAT_MS = 10_000;
 
-/** Outcomes the wire accepts for one completion. */
-export const OUTCOMES = ["done", "failed", "cancelled"];
+/**
+ * Outcomes the wire accepts for one completion. The proto's own `Outcome`
+ * (`crates/onlyne-proto/src/envelope.rs`), so the two drives that mount these
+ * tools refuse the same spellings rather than each keeping a list.
+ */
+export const OUTCOMES = ["done", "failed", "cancelled", "blocked"];
 
 /** Mime types `ImagePart` accepts, in the core's stable order. */
 export const IMAGE_MIMES = ["image/png", "image/jpeg", "image/gif", "image/webp"];
@@ -102,6 +106,11 @@ export function welcomeFrom(data) {
     prose: typeof args.prose === "string" ? args.prose : "",
     server: args.server ?? null,
     hostCapabilities: Array.isArray(args.host_capabilities) ? args.host_capabilities : [],
+    // The tasks whose delivery the host already handed this session: a plugin
+    // that restarts under a live client seeds its injection guard from it, so
+    // the work its predecessor read is not injected a second time. Null when the
+    // host says nothing.
+    deliveredTasks: Array.isArray(args.delivered_tasks) ? args.delivered_tasks : null,
   };
 }
 
@@ -131,11 +140,21 @@ export function heartbeatReport({ taskId, generation, seq, agent, host = null })
   };
 }
 
-/** `report.complete` — the terminal fact the ledger keeps. */
-export function completeReport({ taskId, outcome, head }) {
+/**
+ * `report.complete` — the terminal fact the ledger keeps.
+ *
+ * `head` is the display line the ledger holds; `details` is the full result,
+ * carried verbatim for the next hop and the originator, and `files` are the
+ * absolute paths that result names. The client owns the `details` ceiling and
+ * refuses an oversize body, so this builds the frame and adds no rule of its
+ * own (`docs/v2-CONTRACT.md` §3c).
+ */
+export function completeReport({ taskId, outcome, head, details = null, files = [] }) {
   const report = { kind: "complete", data: { task_id: taskId, outcome: normalizeOutcome(outcome) } };
   const text = headOf(head);
   if (text) report.data.head = text;
+  if (typeof details === "string" && details.length > 0) report.data.details = details;
+  if (Array.isArray(files) && files.length > 0) report.data.files = files;
   return report;
 }
 
@@ -277,7 +296,7 @@ export function sendEnvelope({ from, to, kind = "note", text = "", image = null,
   return envelope;
 }
 
-/** A human-readable principal, for injection headers. */
+/** A human-readable principal, for the plugin's own operator log line. */
 export function describePrincipal(principal) {
   if (!principal || typeof principal !== "object") return "unknown";
   if (principal.role) {
@@ -305,48 +324,10 @@ export function normalizeOutcome(value) {
 }
 
 /**
- * The user message one `assign` becomes.
- *
- * The task text is quoted verbatim under a header naming its origin, so a
- * session transcript shows where the instruction came from; the role prose
- * (identical in `welcome` and `assign`) is folded in only when it has not
- * already been delivered.
- *
- * The header also carries the family's own figures — the hop this assignment
- * sits at and the hops the family may spend — so a role reads its position off
- * the instruction. Both appear only when the causality names a hop budget: the
- * budget is what marks a payload as a member of a bounded family, and a payload
- * that names none injects exactly the bytes it produced before this header
- * carried them.
- * @param {{ assign: any, proseIsNew: boolean, attachmentPaths?: string[] }} options
- */
-export function injectionText({ assign, proseIsNew, attachmentPaths = [] }) {
-  const envelope = assign.envelope ?? {};
-  const causality = envelope.causality ?? {};
-  const taskId = assign.task_id ?? envelope.causality?.task ?? "unknown";
-  const position =
-    typeof causality.hop_budget === "number"
-      ? `, hop ${causality.hop ?? 0}, hop budget ${causality.hop_budget}`
-      : "";
-  const lines = [
-    `[onlyne] task ${taskId} from ${describePrincipal(envelope.from)} (kind ${envelope.kind ?? "task"}${position})`,
-  ];
-  const prose = typeof assign.prose === "string" ? assign.prose.trim() : "";
-  if (prose && proseIsNew) {
-    lines.push("", "[onlyne] role prose from the spec:", prose);
-  }
-  const text = typeof envelope.body?.text === "string" ? envelope.body.text.trim() : "";
-  lines.push("", text || "(the task carried no text; the image attachment is the payload)");
-  if (attachmentPaths.length > 0) {
-    lines.push("", `[onlyne] attachment saved to: ${attachmentPaths.join(", ")}`);
-  }
-  return lines.join("\n");
-}
-
-/**
- * Task body for the `config_get` route: when a plugin does not declare `inject`
- * the host hands the payload over as `config_get{key:"stdin:<task text>"}`
- * (PROTOCOL.md, "Mounts and capabilities").
+ * Delivery text for the `config_get` route: when a plugin does not declare
+ * `inject` the host hands the payload over as
+ * `config_get{key:"stdin:<delivery text>"}`, the same bytes an `assign` carries
+ * in its `text` (PROTOCOL.md, "Mounts and capabilities").
  * @returns {{ text: string } | null}
  */
 export function stdinTaskText(args) {

package/src/protocol.test.mjs

@@ -18,7 +18,6 @@ import {
   helloArgs,
   hostBinding,
   imagePart,
-  injectionText,
   normalizeOutcome,
   observationFor,
   readPluginVersion,
@@ -31,7 +30,6 @@ import {
 const VECTOR_DIR = fileURLToPath(new URL("../../../crates/onlyne-proto/tests/wire_vectors/", import.meta.url));
 const hasVectors = existsSync(VECTOR_DIR);
 const vectorFrame = (name) => JSON.parse(JSON.parse(readFileSync(`${VECTOR_DIR}${name}`, "utf8")).frame);
-const ASSIGN = () => vectorFrame("adapter_host_assign.json");
 const packageJson = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
 
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/;
@@ -89,6 +87,7 @@ test("welcome parses the host's response body and rejects junk", () => {
     prose: "Read the incoming task",
     server: { connected: true, cluster: "local", name: "server" },
     hostCapabilities: ["probe", "recycle"],
+    deliveredTasks: null,
   });
   assert.deepEqual(welcomeFrom(args)?.role, "planner");
   assert.equal(welcomeFrom(null), null);
@@ -101,7 +100,14 @@ test("welcome parses the host's response body and rejects junk", () => {
     prose: "",
     server: null,
     hostCapabilities: [],
+    deliveredTasks: null,
   });
+  // The host's restart-recovery list travels under its own wire name.
+  assert.deepEqual(
+    welcomeFrom({ op: "welcome", args: { ...args, delivered_tasks: ["task-1"] } }).deliveredTasks,
+    ["task-1"],
+  );
+  assert.equal(welcomeFrom({ op: "welcome", args: { ...args, delivered_tasks: "task-1" } }).deliveredTasks, null);
 });
 
 test("ready matches the host's ready vector, which relays a cluster this plugin never speaks for", { skip: !hasVectors }, () => {
@@ -219,16 +225,6 @@ test("observationFor attaches the host only when there is one", () => {
   assert.deepEqual(dimensions, bare);
 });
 
-test("heartbeatReport carries the host inside observed", () => {
-  const report = heartbeatReport({ taskId: "t1", generation: 1, seq: SEQ_BASE + 1, agent: "idle", host: hostBinding(PANE_ENV) });
-  assert.equal(report.data.observed.host.orca.pane_key, PANE_KEY);
-  assert.equal(report.data.observed.agent, "idle");
-  assert.equal(
-    "host" in heartbeatReport({ taskId: "t1", generation: 1, seq: SEQ_BASE + 2, agent: "idle" }).data.observed,
-    false
-  );
-});
-
 test("a completion names an outcome and a single-line head", () => {
   assert.deepEqual(completeReport({ taskId: "t1", outcome: "failed", head: "broke\non line two" }), {
     kind: "complete",
@@ -239,9 +235,24 @@ test("a completion names an outcome and a single-line head", () => {
     kind: "complete",
     data: { task_id: "t1", outcome: "done" },
   });
+  // The full result and the paths it names ride the same report, and only when
+  // there is something to carry: an empty body adds no key at all.
+  assert.deepEqual(
+    completeReport({ taskId: "t1", outcome: "done", head: "done", details: "all of it", files: ["/ws/a.md"] }),
+    {
+      kind: "complete",
+      data: { task_id: "t1", outcome: "done", head: "done", details: "all of it", files: ["/ws/a.md"] },
+    },
+  );
+  assert.deepEqual(completeReport({ taskId: "t1", outcome: "done", details: "", files: [] }), {
+    kind: "complete",
+    data: { task_id: "t1", outcome: "done" },
+  });
   assert.equal(completeReport({ taskId: "t1", outcome: "weird" }).data.outcome, "done");
   assert.equal(normalizeOutcome(undefined), "done");
   assert.equal(normalizeOutcome("cancelled"), "cancelled");
+  // `blocked` is the proto's own outcome (slice 1), so it travels as itself.
+  assert.equal(normalizeOutcome("blocked"), "blocked");
 });
 
 test("the ledger head is capped at the plan's 200 characters", () => {
@@ -251,63 +262,6 @@ test("the ledger head is capped at the plan's 200 characters", () => {
   assert.equal(headOf(undefined), "");
 });
 
-test("an assignment becomes one message naming its origin and payload", { skip: !hasVectors }, () => {
-  const assign = ASSIGN().args;
-  const text = injectionText({ assign, proseIsNew: true });
-  // The vector's causality names no hop budget, and the header is byte for byte
-  // the line this plugin has always injected.
-  assert.equal(
-    text.split("\n")[0],
-    "[onlyne] task 11111111-1111-4111-8111-111111111111 from role:planner (kind task)",
-  );
-  assert.match(text, /\[onlyne\] role prose from the spec:\nRead the incoming task/);
-  assert.match(text, /\nbuild it\n?$/);
-
-  const repeat = injectionText({ assign, proseIsNew: false });
-  assert.doesNotMatch(repeat, /role prose from the spec/);
-  assert.match(repeat, /build it/);
-});
-
-test("the header names the hop and the budget once the family names a budget", () => {
-  const header = (causality) =>
-    injectionText({
-      assign: {
-        task_id: "t9",
-        envelope: {
-          id: "e9",
-          kind: "task",
-          from: { role: { role: "planner" } },
-          causality,
-          body: { text: "pass it on" },
-        },
-      },
-      proseIsNew: false,
-    }).split("\n")[0];
-
-  assert.equal(
-    header({ task: "t9", hop: 2, attempt: 0, family: "t1", hop_budget: 5 }),
-    "[onlyne] task t9 from role:planner (kind task, hop 2, hop budget 5)",
-  );
-  // A family may spend no further hop: zero is a figure the header carries.
-  assert.equal(
-    header({ task: "t9", hop: 0, attempt: 0, family: "t1", hop_budget: 0 }),
-    "[onlyne] task t9 from role:planner (kind task, hop 0, hop budget 0)",
-  );
-  // No budget named: the compat rule holds, hop or no hop.
-  assert.equal(header({ task: "t9", hop: 2, attempt: 0 }), "[onlyne] task t9 from role:planner (kind task)");
-});
-
-test("an empty-bodied assignment still produces an instruction", () => {
-  const text = injectionText({
-    assign: { task_id: "t9", envelope: { id: "e9", kind: "note", from: { gateway: { gateway: "fg1", channel: "fake", conversation: "c1" } }, body: {} } },
-    proseIsNew: false,
-    attachmentPaths: ["/ws/.onlyne/tmp/attachments/a.png"],
-  });
-  assert.match(text, /from gateway:fg1:fake:c1/);
-  assert.match(text, /the task carried no text/);
-  assert.match(text, /\/ws\/\.onlyne\/tmp\/attachments\/a\.png/);
-});
-
 test("a note carries no idempotency key and a task carries both", { skip: !hasVectors }, () => {
   const note = sendEnvelope({ from: "planner", to: "builder", kind: "note", text: "ping" });
   assert.deepEqual(Object.keys(note).sort(), ["admin", "body", "from", "id", "kind", "protocol", "to", "ts"].sort());