@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/results/retrieval.ts

@@ -0,0 +1,142 @@
+/** Supervisor-facing terminal receipts and the shared fenced page projection. No lifecycle effects. */
+import { fenceUntrusted } from "../core/fence.ts";
+import { readFailure, type ReadReply, type ScopedReader } from "../bus/result-reader.ts";
+import { RESULT_MAX_BODY_CHARS, RESULT_READ_DEFAULT, RESULT_READ_MAX, type ArchiveFailure, type ResultPage, type ResultReadRequest,
+	type ResultStorage, type SaveOutcome, type TerminalStatus } from "./types.ts";
+import type { StoredBodyPage } from "./record.ts";
+
+export interface ResultReceipt {
+	ref?: string;
+	storage?: ResultStorage;
+	truncated?: boolean;
+	warning?: string;
+}
+
+export function resultReceipt(outcome: SaveOutcome): ResultReceipt {
+	if (!outcome.ok) return { warning: `Terminal report not archived (${outcome.reason}).` };
+	return {
+		ref: outcome.ref, storage: outcome.storage, truncated: outcome.summary.truncated,
+		...(outcome.warnings.length > 0 ? { warning: `Terminal storage: ${outcome.warnings.join(", ")}.` } : {}),
+	};
+}
+
+export function resultReceiptHint(receipt: ResultReceipt | undefined): string {
+	if (!receipt) return "";
+	const reference = receipt.ref
+		? `${receipt.ref} · ${receipt.storage === "session-entry" ? "native session entry accepted (not an fsync guarantee)" : "memory-only; runtime-only, not durable"}. Read with intercom { action:"result", ref:"${receipt.ref}" }.`
+		: "";
+	return [reference, receipt.truncated ? "Saved report truncated by archive limits." : "", receipt.warning ?? ""].filter(Boolean).join(" ");
+}
+
+/** Live reports are not restricted to archive body retention; paging still obeys the same UTF-16 contract. */
+export function pageLiveResult(body: string, offset = 0, limit = RESULT_READ_DEFAULT): StoredBodyPage | undefined {
+	const splitsPair = (at: number): boolean => at > 0 && at < body.length
+		&& /[\uD800-\uDBFF]/.test(body[at - 1]!) && /[\uDC00-\uDFFF]/.test(body[at]!);
+	if (!Number.isSafeInteger(offset) || offset < 0 || offset > body.length || splitsPair(offset)
+		|| !Number.isInteger(limit) || limit < 2 || limit > RESULT_READ_MAX) return undefined;
+	let end = Math.min(body.length, offset + limit);
+	if (splitsPair(end)) end--;
+	return { body: body.slice(offset, end), offset, endOfStoredBody: end === body.length, ...(end < body.length ? { nextOffset: end } : {}) };
+}
+
+/** Metadata is caller-owned; report and diagnostic text are always independently fenced. */
+export function projectResultPage(page: StoredBodyPage, error?: string): string {
+	const cause = error ? `\nFailure detail:\n${fenceUntrusted(error.slice(0, 2048))}` : "";
+	const next = page.nextOffset === undefined ? "end of stored body" : `next offset: ${page.nextOffset}`;
+	return `Page offset ${page.offset}; ${page.body.length} UTF-16 units; ${next}.${cause}\n${page.body === "(no output)" ? page.body : fenceUntrusted(page.body)}`;
+}
+
+// ── reference handoff (flow reference mode): scoped reads over the terminal archive ──
+
+/** The narrow archive face a leg's reader needs — `TerminalResultArchive` satisfies it
+ *  structurally. Readers never own, hydrate or mutate archive state; they page through it. */
+export interface ResultArchiveView {
+	read(request: ResultReadRequest): ResultPage;
+}
+
+/** An archive failure reason mapped onto the reader wire's closed error vocabulary. */
+function readFailureFor(reason: ArchiveFailure["reason"]): ReadReply {
+	switch (reason) {
+		case "invalid":
+			return readFailure("invalid");
+		case "busy":
+			return readFailure("busy");
+		default:
+			// missing / ambiguous / corrupt / conflict / quota — every identity or durability
+			// problem reads to the child as "the ref is not readable here".
+			return readFailure("unavailable");
+	}
+}
+
+/** A scoped reader over the owning session's archive, granted an EXPLICIT ref set (the
+ *  direct upstream phase needs of THIS leg — nothing else). Owner/capability rechecks at
+ *  call time are the root's job (the adapter closure); revocation is one-way and final.
+ *  Reads page the archive's already-stored body; they never rebill, collect live runs, or
+ *  wake anything. Projection/fencing stays the tool's job (`tools/read-result.ts`). */
+export interface ScopedResultReader extends ScopedReader {
+	/** Refs that are not durably readable (missing, unreadable, or memory-only). Empty = healthy. */
+	preflight(): { missing: string[] };
+}
+
+export function makeScopedResultReader(view: ResultArchiveView, granted: readonly string[]): ScopedResultReader {
+	const refs = new Set(granted);
+	let revoked = false;
+	const page = (request: ResultReadRequest): ReadReply => {
+		const result = view.read(request);
+		if (!result.ok) return readFailureFor(result.reason);
+		const s = result.summary;
+		const end = result.offset + result.body.length;
+		return {
+			ok: true, ref: s.ref, body: result.body, offset: result.offset,
+			...(end < s.storedChars ? { nextOffset: end } : {}),
+			storedChars: s.storedChars, originalChars: s.originalChars, truncated: s.truncated,
+			endOfStoredBody: result.endOfStoredBody, status: s.status, provenance: s.provenance,
+		};
+	};
+	return {
+		async read(request, signal): Promise<ReadReply> {
+			if (revoked) return readFailure("revoked");
+			if (signal?.aborted) return readFailure("cancelled");
+			if (!refs.has(request.ref)) return readFailure("denied");
+			return page(request);
+		},
+		revoke(): void {
+			revoked = true;
+		},
+		preflight(): { missing: string[] } {
+			// Reference handoff is a DURABILITY contract: a memory-only record is not a receipt
+			// a later process (or a resumed run) could read back, so it does not pass preflight.
+			const missing: string[] = [];
+			for (const ref of refs) {
+				const result = view.read({ ref, offset: 0, limit: 2 });
+				if (!result.ok || result.summary.storage !== "session-entry") missing.push(ref);
+			}
+			return { missing };
+		},
+	};
+}
+
+/** The full stored body of an archived result, paged out to the archive's own ceiling. Used
+ *  by a reference-mode RESUME to rebuild a done phase's output from the archive (contract 2). */
+export function readArchivedBody(view: ResultArchiveView, ref: string):
+	| { ok: true; body: string; status: TerminalStatus; truncated: boolean }
+	| { ok: false; error: string } {
+	let offset = 0;
+	let body = "";
+	let status: TerminalStatus | undefined;
+	let truncated = false;
+	while (true) {
+		const page = view.read({ ref, offset, limit: RESULT_READ_MAX });
+		if (!page.ok) return { ok: false, error: `${page.reason}: ${page.message}` };
+		status = page.summary.status;
+		truncated = page.summary.truncated;
+		body += page.body;
+		if (page.endOfStoredBody || page.nextOffset === undefined) break;
+		if (page.nextOffset <= offset || body.length >= RESULT_MAX_BODY_CHARS) {
+			return { ok: false, error: `archive paging did not advance past offset ${page.nextOffset}` };
+		}
+		offset = page.nextOffset;
+	}
+	if (status === undefined) return { ok: false, error: "archive returned no status" };
+	return { ok: true, body, status, truncated };
+}

package/src/results/types.ts

@@ -0,0 +1,128 @@
+import type { ThinkingLevel } from "../core/types.ts";
+
+export const TERMINAL_RESULT_ENTRY = "pi-persona-terminal-result";
+export const RESULT_MAX_ENTRIES = 128;
+/** UTF-8 JSON custom-entry DATA only; the host's JSONL envelope is excluded. */
+export const RESULT_MAX_PAYLOAD_BYTES = 8 * 1024 * 1024;
+export const RESULT_MAX_RECORD_BYTES = 512 * 1024;
+export const RESULT_MAX_BODY_CHARS = 262_144;
+export const RESULT_READ_DEFAULT = 8_000;
+export const RESULT_READ_MAX = 16_000;
+export const RESULT_LIST_DEFAULT = 20;
+export const RESULT_LIST_MAX = 50;
+
+export type TerminalStatus = "done" | "failed" | "stopped";
+export type ResultProvenance = "result-output" | "partial-output" | "error";
+export type ResultStorage = "session-entry" | "memory-only";
+export type ResultWarning = "no-session-storage" | "accounting-unavailable" | "invalid-history"
+	| "duplicate-history" | "ambiguous-history" | "append-failed" | "body-truncated";
+
+/** Cumulative usage only, never a context-window claim or per-token stream. */
+export interface TerminalUsage {
+	input: number;
+	output: number;
+	cacheRead?: number;
+	cacheWrite?: number;
+	cost?: number;
+	turns?: number;
+}
+
+/** Trusted caller projection, NOT an arbitrary AgentResult. Unknown fields are rejected.
+ * Metadata ceilings (UTF-16): originKey 1024, originRunId/agent 128, label 256,
+ * model 512, error 2048. Invalid metadata rejects the save rather than silently changing it. */
+export interface TerminalResultInput {
+	/** Immutable activation + run/phase identity. Routing labels are not identities. */
+	originKey: string;
+	originRunId?: string;
+	status: TerminalStatus;
+	agent: string;
+	label?: string;
+	model?: string;
+	thinkingRequested?: ThinkingLevel;
+	thinkingEffective?: ThinkingLevel;
+	usage?: TerminalUsage;
+	/** Epoch milliseconds. Omit to stamp a NEW record with the injected clock. */
+	createdAt?: number;
+	body: string;
+	provenance: ResultProvenance;
+	error?: string;
+}
+
+export interface TerminalResultRecord extends Omit<TerminalResultInput, "createdAt"> {
+	version: 1;
+	ref: string;
+	createdAt: number;
+	/** SHA-256 content identity includes the original body, even its discarded suffix.
+	 * This is collision detection, not authentication of host history. */
+	payloadHash: string;
+	originalChars: number;
+	storedChars: number;
+	truncated: boolean;
+}
+
+export interface ResultSummary extends Omit<TerminalResultRecord, "body" | "payloadHash"> {
+	storage: ResultStorage;
+}
+
+export interface ResultAccounting {
+	/** Includes unknown/malformed/duplicate history and reserved append attempts. */
+	chargedEntries: number;
+	/** null means the lifetime baseline is unaccountable; persistence is disabled. */
+	chargedPayloadBytes: number | null;
+	persistenceDisabled: boolean;
+}
+
+export interface ArchiveEvidence {
+	accounting: ResultAccounting;
+	warnings: ResultWarning[];
+}
+
+export interface ArchiveFailure extends ArchiveEvidence {
+	ok: false;
+	reason: "invalid" | "unavailable" | "conflict" | "ambiguous" | "corrupt" | "quota" | "busy";
+	message: string;
+}
+
+export type SaveOutcome = ArchiveFailure | (ArchiveEvidence & {
+	ok: true;
+	ref: string;
+	/** session-entry means append returned normally or data came from native history.
+	 * It is NOT an fsync/crash-survival guarantee. memory-only is never a durable receipt. */
+	storage: ResultStorage;
+	summary: ResultSummary;
+	idempotent: boolean;
+	storageError?: string;
+});
+
+export interface ResultReadRequest { ref: string; offset?: number; limit?: number }
+export type ResultPage = ArchiveFailure | (ArchiveEvidence & {
+	ok: true;
+	summary: ResultSummary;
+	/** Untrusted text; the integration must apply its shared fence on model delivery. */
+	body: string;
+	offset: number;
+	nextOffset?: number;
+	/** Reached the end of the STORED body, not necessarily the original report. */
+	endOfStoredBody: boolean;
+});
+
+export interface ResultListRequest { cursor?: number; limit?: number }
+export type ResultSummaryPage = ArchiveFailure | (ArchiveEvidence & {
+	ok: true;
+	results: ResultSummary[];
+	/** Opaque-in-practice append ordinal, not a run id or a branch-local index. */
+	nextCursor?: number;
+});
+
+export interface TerminalResultArchiveDeps {
+	/** All branches in ONE owning session file. Never read parent/foreign files.
+	 * History entries are immutable host data. Hydration is read-only and runs once.
+	 * Recreate the archive on owner change; adapters must reject stale-owner writes. */
+	entries: () => readonly unknown[];
+	/** Native custom ENTRY, not a model message. May throw after partially committing. */
+	append: (customType: string, data: unknown) => void;
+	persistent: boolean;
+	/** Must return result:<UUID>. The default uses node:crypto.randomUUID(). */
+	makeRef?: () => string;
+	clock?: () => number;
+}

package/src/telemetry/contract.ts

@@ -4,7 +4,7 @@ export const TELEMETRY_EVENT_NAME = "pi:telemetry" as const;
 export const LEGACY_TELEMETRY_EVENT_NAME = "pi-persona:telemetry" as const;
 export const LEGACY_TELEMETRY_VERSION = 1 as const;
 export const TELEMETRY_PRODUCER_ID = "pi-persona" as const;
-export const TELEMETRY_PRODUCER_VERSION = "1.17.1" as const;
+export const TELEMETRY_PRODUCER_VERSION = "1.17.4" as const;
 
 export type InstanceStatus = "active" | "idle" | "stopped" | "stale" | (string & {});
 export type AgentKind = "subagent" | "delegate" | "council" | "flow" | "phase" | (string & {});

package/src/tools/background-run.ts

@@ -0,0 +1,151 @@
+/**
+ * `council` and `flow` as ONE tracked run (the same machinery `delegate` uses): a visible strategy or
+ * flow is launched into the {@link AsyncRunTracker}, rooted in the agent tree at `async:<runId>`, and
+ * reachable through the stop key `async:<runId>`: `intercom stop`, stop all, and `x` on the run's root row
+ * in the f9 overlay all end the whole run. Interactive sessions get a receipt at once and ONE completion
+ * follow-up (`renderCompletion`); headless sessions join the same run before the tool returns, so the
+ * single turn carries the result.
+ *
+ * Which semaphore gates what:
+ *  - `slots` is the launch pool `delegate` already uses (`maxConcurrency`). A council or flow takes ONE
+ *    slot for the whole run, exactly like one delegate leg, and shows `queued` until it has it.
+ *  - The strategy SDK's own per-run semaphore (`orchestration/sdk.ts`) gates the legs INSIDE the run, so
+ *    a council's members never compete with delegate legs for these slots and cannot deadlock on them.
+ *    A flow parked at a human checkpoint keeps its slot for the wait: the operator owns that wait, and
+ *    stopping the run releases it.
+ *  - Token budgets, the child limit and the fork-bomb guard live in that SDK and the engine, untouched.
+ */
+import { END_TURN_NOTE } from "../core/brief.ts";
+import type { ChildUsage } from "../engine/stream.ts";
+import { emptyUsage } from "../engine/stream.ts";
+import type { AgentResult } from "../orchestration/types.ts";
+import type { Semaphore } from "../orchestration/parallel.ts";
+import { madeHeadway, type AsyncRun, type AsyncRunTracker, type IdleCoalescingNotifier, type ProgressReading } from "../engine/async.ts";
+import type { AgentTree } from "../ui/agent-tree.ts";
+import type { ChildUsageLedger } from "../ui/usage.ts";
+
+/** What a visible runner is handed when it works for a tracked run (absent ⇒ it roots and stops itself). */
+export interface TrackedRun {
+	/** The tree root of this run: `async:<runId>`. Its nodes hang under it. */
+	rootId: string;
+	/** Fires when the run is stopped — by key, by `intercom stop`, or by the headless tool call's abort. */
+	signal: AbortSignal;
+	/** Interactive: the launching turn has ended and the supervisor is idle, so a coached leg may block on an
+	 *  ask (the run's engines are built `async`). Headless: the call is parked in the turn and could not answer. */
+	background: boolean;
+	/** One leg progressed: feeds the run's cumulative tokens, and its stall clock when the leg made headway. */
+	onProgress(leg: string, progress: ProgressReading): void;
+	/** The run is blocked on the operator (a flow checkpoint) — or released again (`undefined`). */
+	onAwaiting(label: string | undefined): void;
+}
+
+export interface BackgroundRunDeps {
+	tracker: AsyncRunTracker;
+	agentTree: AgentTree;
+	stopRegistry: Map<string, () => void>;
+	/** The launch pool shared with `delegate` (see the module comment). */
+	slots: Semaphore;
+	completionNotifier: Pick<IdleCoalescingNotifier<AsyncRun>, "discard">;
+	startPeek(): void;
+	childUsage: ChildUsageLedger;
+	publishPersonaCost(): void;
+}
+
+/** `inline` (headless) skips the status monitor: the launching call joins the run and nobody reads a status card. */
+export interface LaunchMeta { kind: "council" | "flow"; label: string; task: string; inline: boolean }
+
+type RunWork = (run: TrackedRun) => Promise<AgentResult>;
+
+/** The receipt an interactive `council`/`flow` launch returns. `wake` finishes "you will be woken ONCE ...". */
+export function launchReceipt(kind: LaunchMeta["kind"], id: string, subject: string, wake: string): string {
+	return `Launched ${kind} ${id} (${subject}) in the background — you will be woken ONCE ${wake} (${END_TURN_NOTE}).`;
+}
+
+export interface BackgroundRuns {
+	/** Launch `work` as one tracked run and return its id. */
+	launch(meta: LaunchMeta, work: RunWork): string;
+	/** Join launched runs (headless): wait for all of them, stop them if `signal` aborts, drop the follow-ups
+	 *  this return replaces, and bill their usage once. `onSettled` sees each settle as (done, total). */
+	settle(ids: readonly string[], signal: AbortSignal | undefined, onSettled?: (done: number, total: number) => void): Promise<{ runs: AsyncRun[]; usage: ChildUsage }>;
+}
+
+export function createBackgroundRuns(d: BackgroundRunDeps): BackgroundRuns {
+	function launch(meta: LaunchMeta, work: RunWork): string {
+		// `mutates`: a strategy's legs and their tool grants are decided leg by leg inside the run, so the run
+		// is classed as a potential writer — the fail-closed answer for a persona's fresh-verification policy
+		// (whose refusal says "may mutate", which is all this classification knows).
+		const id = d.tracker.launch({ agent: meta.label, task: meta.task, label: meta.label, mutates: true, queued: true }, (onProgress, runId) => {
+			const rootId = `async:${runId}`;
+			const ac = new AbortController();
+			d.stopRegistry.set(rootId, () => ac.abort());
+			const legSeen = new Map<string, ProgressReading>();
+			const legTokens = new Map<string, number>();
+			const snapshot = (output = ""): { output: string; turns: number; tokens: number } => ({ output, turns: 0, tokens: [...legTokens.values()].reduce((a, b) => a + b, 0) });
+			const run: TrackedRun = {
+				rootId,
+				signal: ac.signal,
+				background: !meta.inline,
+				onProgress: (leg, progress) => {
+					// Headway is judged per leg - the run's own snapshot is only their token sum - by the same rule a
+					// delegate leg is held to, so one chatty tool in one leg cannot keep the whole run looking alive.
+					if (madeHeadway(legSeen.get(leg), progress)) d.tracker.advance(runId);
+					legSeen.set(leg, progress);
+					legTokens.set(leg, progress.tokens ?? legTokens.get(leg) ?? 0);
+					onProgress(snapshot());
+				},
+				onAwaiting: (label) => {
+					d.tracker.setAwaiting(runId, label);
+				},
+			};
+			return d.slots
+				.with(async () => {
+					d.tracker.markAdmitted(runId);
+					const result = await work(run);
+					// A ruling or plan that did not complete lives in `result.output`, but a failed or stopped run's
+					// report salvages the tracker's `progress.output` — hand it over so that work is not lost.
+					if (!result.ok && result.output) onProgress(snapshot(result.output));
+					return result;
+				}, ac.signal)
+				.catch((error: unknown): AgentResult => {
+					if (!ac.signal.aborted) throw error;
+					return { agent: meta.label, output: "", usage: emptyUsage(), ok: false, error: "run aborted", failureKind: "abort" };
+				});
+		});
+		// Visible while queued, so `x` and the tree's stop work before the pool grants a slot; the visible runner
+		// upserts this same row when it starts.
+		d.agentTree.add({ id: `async:${id}`, label: meta.label, kind: meta.kind, status: "running", detail: "queued" });
+		if (!meta.inline) d.startPeek();
+		return id;
+	}
+
+	async function settle(ids: readonly string[], signal: AbortSignal | undefined, onSettled?: (done: number, total: number) => void): Promise<{ runs: AsyncRun[]; usage: ChildUsage }> {
+		const runs = ids.flatMap((id) => d.tracker.peek(id) ?? []); // launch() registers each, and a running entry is never evicted
+		const stopAll = (): void => {
+			for (const id of ids) d.stopRegistry.get(`async:${id}`)?.();
+		};
+		if (signal?.aborted) stopAll();
+		else signal?.addEventListener("abort", stopAll, { once: true });
+		try {
+			if (runs.some((run) => !run.settled)) {
+				await new Promise<void>((resolve) => {
+					const off = d.tracker.onComplete(() => {
+						const done = runs.filter((run) => run.settled).length;
+						onSettled?.(done, runs.length);
+						if (done === runs.length) {
+							off();
+							resolve();
+						}
+					});
+				});
+			}
+		} finally {
+			signal?.removeEventListener("abort", stopAll);
+		}
+		d.completionNotifier.discard((pending) => ids.includes(pending.id)); // this return IS the delivery
+		const usage = d.childUsage.accountMany(runs.map((run) => ({ key: run.id, usage: run.result?.usage ?? emptyUsage() })));
+		d.publishPersonaCost();
+		return { runs, usage };
+	}
+
+	return { launch, settle };
+}