pi-durable-subagents 1.0.23 → 1.0.25

package/dist/events/cli.js

@@ -0,0 +1,117 @@
+// `events --all [--since <cursor>] [--limit <n>] [--json] [--wait-ms <n>]` — read the cross-workflow event log.
+// Output is JSON lines (with or without --json). Without --since: `{"head","more":false}`. With --since: the events
+// after the cursor (at most --limit, default and max EVENTS_PAGE_MAX), then `{"head","more"}`: more:true → head is the
+// cursor of the last event printed; more:false → the log head. Exit 0; 4 cursor-expired (other epoch, seq below
+// `dropped`, or beyond the head); 1 malformed cursor or options (`{"error":"invalid-arguments","message"}`) or an
+// unreadable log (`{"error":"log-unreadable","message"}`: corrupt, or gone between reads twice); 75 no log yet within
+// --wait-ms (an orchestrator was started to create it). Read-only: never repairs the log, never starts the orchestrator when the log exists.
+import { setTimeout as delay } from "node:timers/promises";
+import { eventsLog } from "../paths.js";
+import { EPOCH, LogCorrupt, readHead, readPage } from "./log.js";
+import { EVENTS_PAGE_MAX, EXIT_CURSOR_EXPIRED } from "./types.js";
+export const EVENTS_EXIT = { ok: 0, invalid: 1, expired: EXIT_CURSOR_EXPIRED, pending: 75 };
+export const EVENTS_USAGE = "usage: events --all [--since <epoch>:<seq>] [--limit <n>] [--json] [--wait-ms <n>]";
+/** A cursor `<epoch>:<seq>`, or undefined when malformed. */
+export function parseCursor(text) {
+    const m = /^([0-9a-f]{16}):(0|[1-9]\d{0,15})$/.exec(text);
+    return m && EPOCH.test(m[1]) && Number.isSafeInteger(Number(m[2])) ? { epoch: m[1], seq: Number(m[2]) } : undefined;
+}
+/** Exit 1 with one JSON line `{"error":"invalid-arguments","message"}` (the output stays JSON lines). */
+function invalid(ctx, message) { ctx.write(JSON.stringify({ error: "invalid-arguments", message })); return EVENTS_EXIT.invalid; }
+/** Exit 1 with one JSON line `{"error":"log-unreadable","message"}`. */
+function unreadable(ctx, message) { ctx.write(JSON.stringify({ error: "log-unreadable", message })); return EVENTS_EXIT.invalid; }
+class Vanished extends Error {
+    constructor() { super("the event log disappeared while it was read"); }
+}
+class Expired extends Error {
+    head;
+    constructor(head) { super("cursor-expired"); this.head = head; }
+}
+export async function eventsAll(args, ctx) {
+    try {
+        return await read(args, ctx);
+    }
+    catch (error) {
+        if (error instanceof Vanished)
+            try {
+                return await read(args, ctx);
+            }
+            catch (again) {
+                error = again;
+            } // retried once
+        if (error instanceof LogCorrupt || error instanceof Vanished)
+            return unreadable(ctx, error.message);
+        throw error;
+    }
+}
+async function read(args, ctx) {
+    const values = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i], name = arg.startsWith("--") ? arg.slice(2) : undefined;
+        const kind = name === "all" || name === "json" ? "flag" : name === "since" || name === "limit" || name === "wait-ms" ? "value" : undefined;
+        if (!name || !kind || Object.hasOwn(values, name)) {
+            return invalid(ctx, `unknown, repeated or misplaced argument ${JSON.stringify(arg)}; ${EVENTS_USAGE}`);
+        }
+        if (kind === "flag") {
+            values[name] = true;
+            continue;
+        }
+        const value = args[++i];
+        if (value === undefined) {
+            return invalid(ctx, `--${name} needs a value; ${EVENTS_USAGE}`);
+        }
+        values[name] = value;
+    }
+    const number = (name, min, max) => {
+        const raw = values[name];
+        if (raw === undefined)
+            return undefined;
+        return typeof raw === "string" && /^\d+$/.test(raw) && Number(raw) >= min && Number(raw) <= max ? Number(raw) : null;
+    };
+    const limit = number("limit", 1, EVENTS_PAGE_MAX), wait = number("wait-ms", 0, 86_400_000);
+    if (limit === null)
+        return invalid(ctx, `--limit needs an integer 1-${EVENTS_PAGE_MAX}`);
+    if (wait === null)
+        return invalid(ctx, "--wait-ms needs a non-negative integer");
+    const since = typeof values.since === "string" ? parseCursor(values.since) : undefined;
+    if (values.since !== undefined && !since)
+        return invalid(ctx, `malformed cursor ${JSON.stringify(values.since)}; a cursor is <epoch>:<seq> as printed in "head" or "cursor"`);
+    const path = eventsLog(ctx.home);
+    // No log yet: the orchestrator creates it at start (deriving everything still on disk); start one and wait.
+    if (!readHead(path)) {
+        await ctx.starter(ctx.home, ctx.env);
+        const deadline = performance.now() + (wait ?? ctx.waitMs ?? 60_000);
+        while (!readHead(path) && performance.now() < deadline)
+            await delay(Math.min(100, Math.max(0, deadline - performance.now())));
+        if (!readHead(path)) {
+            ctx.write(JSON.stringify({ pending: true }));
+            return EVENTS_EXIT.pending;
+        }
+    }
+    const cursor = (h, seq) => `${h.epoch}:${seq}`;
+    if (!since) {
+        const h = readHead(path);
+        if (!h)
+            throw new Vanished();
+        ctx.write(JSON.stringify({ head: cursor(h, h.head), more: false }));
+        return EVENTS_EXIT.ok;
+    }
+    try {
+        const page = readPage(path, since.seq, limit ?? EVENTS_PAGE_MAX, h => {
+            if (h.epoch !== since.epoch || since.seq < h.dropped || since.seq > h.head)
+                throw new Expired(h);
+        });
+        if (!page)
+            throw new Vanished();
+        for (const e of page.events)
+            ctx.write(JSON.stringify(e));
+        ctx.write(JSON.stringify({ head: page.more ? page.events.at(-1).cursor : cursor(page, page.head), more: page.more }));
+        return EVENTS_EXIT.ok;
+    }
+    catch (error) {
+        if (!(error instanceof Expired))
+            throw error;
+        ctx.write(JSON.stringify({ error: "cursor-expired", head: cursor(error.head, error.head.head), oldest: cursor(error.head, error.head.dropped) }));
+        return EVENTS_EXIT.expired;
+    }
+}

package/dist/events/derive.js

@@ -0,0 +1,128 @@
+// Journal → event drafts. Pure functions of durable sources: the entry at journal index i (seq i+1) is derived from
+// that journal's entries up to it and from orchestrator-ledger entries durable before it, so a re-derivation after a
+// crash gives the same events with the same ids (`<wid>:<journal seq>:<type>`, `<wid>:submitted`).
+import { createHash } from "node:crypto";
+import { requestId } from "../requests.js";
+import { JT, isEntry } from "../types.js";
+import { fenceReason, interruptingFence } from "./fence.js";
+import { EVENT_DATA_INLINE_MAX } from "./types.js";
+/** `<wid>@<rev>/<key>@<gen>` → key and gen (a key may itself contain '/' or '@'). */
+export function callParts(call) {
+    const m = /^[^@/]+@\d+\/(.*)@(\d+)$/s.exec(call);
+    return m ? { key: m[1], gen: Number(m[2]) } : undefined;
+}
+const echo = (id) => ({ ...(id.request !== undefined ? { request: id.request } : {}), ...(id.labels ? { labels: id.labels } : {}) });
+const onCall = (call) => { const p = callParts(call); return p ? { key: p.key, gen: p.gen, call } : { call }; };
+/** The labels of a run body: a non-empty plain object of strings (anything else, and `{}`, is not echoed — as describe
+ *  and the wait collector treat them). */
+export function labelsOf(body) {
+    const labels = body?.labels;
+    if (!labels || typeof labels !== "object" || Array.isArray(labels))
+        return undefined;
+    const entries = Object.entries(labels);
+    return entries.length && entries.every(([, v]) => typeof v === "string") ? Object.fromEntries(entries) : undefined;
+}
+/** `answered.by` from the answer request's sender: a pi session `main:<id>` → `session:<id>` (+ via "ui" when the
+ *  subagent list sent it, SendBody.by "user"); the CLI sender `cli:<user>@<host>` as is; anything else `unknown`. */
+export function answeredBy(req) {
+    const from = req?.from ?? "";
+    if (from.startsWith("main:"))
+        return { by: `session:${from.slice(5)}`, ...(req.body?.by === "user" ? { via: "ui" } : {}) };
+    if (/^cli:[^@]+@.+$/.test(from))
+        return { by: from };
+    return { by: "unknown" };
+}
+/** `submitted` from the orchestrator ledger's `created {rid, wid}` at index `i` (name from its create-intent). */
+export function deriveCreated(orch, i, id) {
+    const e = orch[i], wid = String(e.wid), rid = String(e.rid);
+    let name;
+    for (let j = i - 1; j >= 0; j--) {
+        const c = orch[j];
+        if (c.type === "create-intent" && c.rid === rid) {
+            name = c.name;
+            break;
+        }
+    }
+    return { id: `${wid}:submitted`, ts: e.ts, type: "submitted", wid, ...echo({ ...id, request: requestId(rid) ?? id.request }), ...(typeof name === "string" ? { name } : {}) };
+}
+/** The request the answer to question (call, qid, rev) came with: an `answer-bound` (a hibernated asker) or a `forward`
+ *  of kind answer (a live one) before index `limit` names its rid; the orchestrator ledger keeps the admitted envelope. */
+function answerOf(entries, limit, orch, call, qid, rev) {
+    let rid, forwarded;
+    for (let j = limit - 1; j >= 0 && rid === undefined; j--) {
+        const e = entries[j];
+        if (e.type === "answer-bound" && e.call === call && e.qid === qid && e.rev === rev)
+            rid = String(e.rid);
+        else if (e.type === "forward" && e.dest === call) {
+            const env = e.envelope;
+            if (env?.kind === "answer" && env.cond?.qid === qid && env.cond?.rev === rev) {
+                rid = String(e.rid);
+                forwarded = typeof env.body?.message === "string" ? env.body.message : undefined;
+            }
+        }
+    }
+    const request = rid === undefined ? undefined : orch.findLast(e => e.type === "request" && e.request?.rid === rid)?.request;
+    const message = request?.body?.message;
+    return { request, text: typeof message === "string" ? message : forwarded ?? "" };
+}
+/** The ledger entries durable before journal entry `e` (by time: the ledger and the journal are separate files). A wall
+ *  clock step back can change which ledger entries a re-derivation sees, and so `by`/`reason` of its event (ids stay). */
+function before(orch, e) {
+    let n = orch.length;
+    while (n > 0 && Number(orch[n - 1].ts) > e.ts)
+        n--;
+    return n === orch.length ? orch : orch.slice(0, n);
+}
+/** The events of journal entry `i` of workflow `wid` (usually none). Reads only that journal's entries up to `i` and
+ *  the ledger entries durable before it, so a re-derivation gives the same events. */
+export function deriveEntry(wid, entries, i, orch, id) {
+    const e = entries[i], base = (type) => ({ id: `${wid}:${e.seq}:${type}`, ts: e.ts, wid, ...echo(id) });
+    if (isEntry(e, JT.exec)) {
+        // `started` once per call (generation): its first execution. A later execution follows a fence; `fenced` when
+        // that fence interrupted work (the classification `describe` uses for lastFence).
+        let previous;
+        for (let j = i - 1; j >= 0 && !previous; j--) {
+            const p = entries[j];
+            if (p.type === JT.exec && p.call === e.call)
+                previous = p;
+        }
+        if (!previous)
+            return [{ ...base("started"), type: "started", ...onCall(e.call), exec: e.exec }];
+        const fence = interruptingFence(entries, String(previous.exec), i);
+        if (!fence)
+            return [];
+        return [{ ...base("fenced"), type: "fenced", ...onCall(e.call), exec: String(previous.exec), reason: fenceReason(entries.slice(0, i), before(orch, e), fence), at: fence.ts }];
+    }
+    if (isEntry(e, JT.attention)) {
+        const item = e.item;
+        if (item?.kind !== "question" || !item.call || item.qid === undefined)
+            return [];
+        const parts = callParts(item.call);
+        return [{ ...base("asking"), type: "asking", ...onCall(item.call), qid: item.qid, rev: item.rev, question: item.text, to: `${wid}/${parts?.key ?? ""}` }];
+    }
+    if (isEntry(e, JT.attentionResolved)) {
+        if (e.resolution !== "answered")
+            return [];
+        let item;
+        for (let j = i - 1; j >= 0 && !item; j--) {
+            const a = entries[j];
+            if (isEntry(a, JT.attention) && a.item.id === e.id && a.item.rev === e.rev)
+                item = a;
+        }
+        const q = item?.item;
+        if (!q || q.kind !== "question" || !q.call || q.qid === undefined)
+            return [];
+        const answer = answerOf(entries, i, before(orch, e), q.call, q.qid, q.rev);
+        return [{ ...base("answered"), type: "answered", ...onCall(q.call), qid: q.qid, rev: q.rev, ...answeredBy(answer.request),
+                digest: createHash("sha256").update(answer.text, "utf8").digest("hex"), length: answer.text.length }];
+    }
+    if (isEntry(e, JT.sealed)) {
+        const r = (e.result ?? {}), data = Object.hasOwn(r, "data") && r.data !== undefined ? JSON.stringify(r.data) : undefined;
+        const bytes = data === undefined ? 0 : Buffer.byteLength(data);
+        return [{ ...base("sealed"), type: "sealed", ...onCall(e.call), status: String(r.status ?? "unknown"), ...(r.error ? { error: String(r.error) } : {}),
+                ...(data === undefined ? {} : bytes <= EVENT_DATA_INLINE_MAX ? { data: r.data } : { data_omitted: bytes }) }];
+    }
+    if (e.type === JT.done)
+        return [{ ...base("workflow-done"), type: "workflow-done", status: String(e.status), ...(e.error !== undefined ? { error: String(e.error) } : {}) }];
+    return [];
+}

package/dist/events/fence.js

@@ -0,0 +1,61 @@
+// Which fences interrupted work, shared by `describe` (lastFence) and the event deriver (`fenced`). Read-only over
+// committed journal entries; `limit` restricts the view to the first `limit` entries (the deriver may read only entries
+// before the one it derives, so a re-derivation after a crash sees the same history).
+import { JT } from "../types.js";
+/** Executions whose fence did NOT interrupt work: every execution ends with a fence; one interrupted work only when
+ *  the execution neither settled (its turn ended) before it nor hibernated (it waits for an answer), and was not sealed
+ *  on purpose: a seal ends an execution on purpose unless its outcome is `unknown` (a `once` call cut off in a tool) or
+ *  the execution was recorded as lost (the loss bound sealed it), which are interruptions themselves. A seal for an
+ *  execution that never ran (a launch failure) or that the call's stop, timeout or budget ended is on purpose. */
+export function endedExecs(journal, limit = journal.length) {
+    const lost = new Set(), fencedAt = new Map(), ended = new Set();
+    for (let i = 0; i < limit; i++) {
+        const e = journal[i];
+        if (e.type === "loss")
+            lost.add(String(e.exec));
+        else if (e.type === JT.fenced)
+            fencedAt.set(String(e.exec), e.seq);
+    }
+    for (let i = 0; i < limit; i++) {
+        const e = journal[i], exec = String(e.exec);
+        // Recovery records `hibernated` after the fence for an execution cut off while only its question's ask ran (P28):
+        // it was waiting, not working, so that is no interruption either.
+        if (e.type === "hibernated")
+            ended.add(exec);
+        else if (e.type === "settled") {
+            if (e.seq < (fencedAt.get(exec) ?? Infinity))
+                ended.add(exec);
+        }
+        else if (e.type === JT.sealed && e.result?.status !== "unknown" && !lost.has(exec))
+            ended.add(exec);
+    }
+    return ended;
+}
+/** Best effort: why `fence` (a `fenced` entry that interrupted work) happened. restart-force: a forced restart listed
+ *  the execution as live; orchestrator-crash: the execution was launched before an orchestrator start that is not
+ *  preceded by a clean exit and fenced after it (startup recovery); otherwise process-died (the child or its host went
+ *  away, or a drain fenced it). */
+export function fenceReason(journal, orch, fence) {
+    const exec = String(fence.exec), at = Number(fence.ts);
+    if (orch.some(e => e.type === "restart" && e.force === true && Array.isArray(e.live) && e.live.includes(exec)))
+        return "restart-force";
+    const launched = journal.find(e => e.type === JT.exec && e.exec === exec), starts = orch.filter(e => e.type === "orchestrator");
+    const recovery = starts.findLast(s => Number(s.ts) <= at);
+    if (launched && recovery && Number(launched.ts) < Number(recovery.ts)) {
+        const prior = orch.filter(e => Number(e.seq) < Number(recovery.seq));
+        const lastStart = prior.findLast(e => e.type === "orchestrator"), cleanExit = lastStart && prior.some(e => e.type === "orchestrator-exit" && Number(e.seq) > Number(lastStart.seq));
+        if (!cleanExit)
+            return "orchestrator-crash";
+    }
+    return "process-died";
+}
+/** The fence of `exec` among the first `limit` entries when it interrupted work, else undefined. */
+export function interruptingFence(journal, exec, limit = journal.length) {
+    let fence;
+    for (let i = limit - 1; i >= 0 && !fence; i--) {
+        const e = journal[i];
+        if (e.type === JT.fenced && e.exec === exec)
+            fence = e;
+    }
+    return fence && !endedExecs(journal, limit).has(exec) ? fence : undefined;
+}

package/dist/events/labels.js

@@ -0,0 +1,53 @@
+// Caller labels of a run — `run --labels <json>`, the tool's `labels`, and the
+// orchestrator's admission all validate with this one function. Labels are part of RunBody, so they are part of the
+// request's spec_digest (the same request id with other labels is a request-conflict) and are echoed by `describe` and
+// on every event of the workflow.
+/** At most this many keys. */
+export const LABELS_MAX_KEYS = 32;
+/** A key: 1-64 characters of [A-Za-z0-9_.:-]. */
+export const LABEL_KEY = /^[A-Za-z0-9_.:-]{1,64}$/;
+/** A value: a string of at most this many UTF-16 units. */
+export const LABEL_VALUE_MAX = 256;
+/** The labels' JSON is at most this many UTF-8 bytes. */
+export const LABELS_JSON_MAX = 4096;
+/** What is wrong with `value` as run labels (naming the offending key), or undefined when they are valid. */
+export function labelsProblem(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return "labels must be a JSON object of string values";
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return "labels must be a plain JSON object of string values";
+    const entries = Object.entries(value);
+    if (entries.length > LABELS_MAX_KEYS)
+        return `labels have ${entries.length} keys; at most ${LABELS_MAX_KEYS}`;
+    for (const [key, v] of entries) {
+        if (!LABEL_KEY.test(key))
+            return `label key ${JSON.stringify(key)} must be 1-64 characters [A-Za-z0-9_.:-]`;
+        if (typeof v !== "string")
+            return `label ${JSON.stringify(key)} must have a string value`;
+        if (v.length > LABEL_VALUE_MAX)
+            return `label ${JSON.stringify(key)} is ${v.length} characters long; at most ${LABEL_VALUE_MAX}`;
+    }
+    const bytes = Buffer.byteLength(JSON.stringify(value), "utf8");
+    if (bytes > LABELS_JSON_MAX)
+        return `labels are ${bytes} bytes of JSON; at most ${LABELS_JSON_MAX}`;
+    return undefined;
+}
+/** Valid labels as given (throws the problem otherwise). */
+export function checkLabels(value) {
+    const problem = labelsProblem(value);
+    if (problem)
+        throw new Error(problem);
+    return value;
+}
+/** `--labels <json>`: parse and validate. */
+export function parseLabels(json) {
+    let value;
+    try {
+        value = JSON.parse(json);
+    }
+    catch (error) {
+        throw new Error(`--labels is not JSON: ${error.message}`);
+    }
+    return checkLabels(value);
+}