pi-durable-subagents 1.0.22 → 1.0.24

package/dist/events/derive.js

@@ -0,0 +1,128 @@
+// R2: 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 R7 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 @@
+// R2/R3: 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";
+/** R3: 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;
+}
+/** R3, 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";
+}
+/** R2: 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 @@
+// R6 (owed requirements §20.2): 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);
+}