@aeondave/pi-persona 1.17.3 → 1.17.4

package/src/engine/adapter.ts

@@ -10,6 +10,8 @@ import { randomUUID } from "node:crypto";
 import type { AgentConfig } from "../agents/agent.ts";
 import { type ContractDef, contractInstructions, parseAndValidate, pinContract, type PinnedContract } from "../core/contract.ts";
 import { sanitizeDisplayLabel } from "../core/display-label.ts";
+import { resolveLegThinking } from "../core/leg-thinking.ts";
+import type { ThinkingLevel } from "../core/types.ts";
 import { assignedIdentityPrompt } from "../core/naming.ts";
 import { roleHint } from "../orchestration/roster.ts";
 import { type AgentProgress, type AgentRunSpec, isPositiveFiniteMs, type SteerFn, type StrategyEngine } from "../orchestration/sdk.ts";
@@ -18,8 +20,13 @@ import { type ChildEngineOptions, type ChildRunSpec, runChildAgent } from "./chi
 import { looksLikeProviderError } from "./errors.ts";
 import { piHostModuleHint } from "./host-module.ts";
 import { nextChildHandle } from "./handles.ts";
+import { admitResultReadTool, referenceHandoffFailure } from "./result-grant.ts";
+import { makeScopedResultReader, type ResultArchiveView } from "../results/retrieval.ts";
+import type { PreparedResultReader, ScopedReader } from "../bus/result-reader.ts";
 import { combineSignals } from "./signals.ts";
+import { emptyUsage } from "./stream.ts";
 import { toolModifierFailure, unknownAgentFailure, unknownContractFailure } from "./spec-preflight.ts";
+import { mergeSessionToolAllowlist } from "./session-tools.ts";
 
 /** The engine-side face of the cross-process broker (spec B3/B4/B7) — a child-engine
  *  spawn's connection to the supervisor-hosted relay. The concrete implementation
@@ -40,6 +47,10 @@ export interface EngineAdapterBroker {
 	 *  parent-side idle/startup watchdogs consult this before killing a silent leg (R9): a leg
 	 *  blocked on the supervisor is re-armed, not killed. */
 	hasPendingAskFrom(handle: string): boolean;
+	/** Strict, AWAITED result-reader preflight for a reference-handoff leg (the broker host binds
+	 *  a single-use token to this handle). Must complete BEFORE `register` and the spawn — a
+	 *  missing broker/binding fails the leg closed with zero usage instead of degrading bus-less. */
+	prepareResultReader(handle: string, reader: ScopedReader, signal?: AbortSignal): Promise<PreparedResultReader>;
 }
 
 export interface EngineAdapterDeps {
@@ -55,8 +66,7 @@ export interface EngineAdapterDeps {
 	 *  the on-the-fly role this run carries, when it has one, so a member's own assignment key
 	 *  (`agent#hash`) resolves ahead of the bare agent's. */
 	modelFor?: (agent: string, role?: string) => string | undefined;
-	/** Explicit thinking level appended to the child model (`model:level`) so it can't
-	 *  fall into a model's default "adaptive" mode, which some models reject. */
+	/** Configured/inherited child effort, below explicit leg and agent selections. */
 	childThinking?: string;
 	/** The shared behavioral layer (docs/SPINE.md), prepended to every leg's prompt. This is the
 	 *  WORKER variant (`prompts/spine.worker.md`), not the supervisor text — a leg runs headless
@@ -80,6 +90,11 @@ export interface EngineAdapterDeps {
 	 *  blocking would deadlock: default false, mirroring `inproc.ts`'s `allowBlocking`
 	 *  default. Forwarded to the child as `PI_PERSONA_ALLOW_BLOCKING` (bridge.ts). */
 	allowBlocking?: boolean;
+	/** The owning session's terminal archive (a GETTER — the owner can change across sessions).
+	 *  Required by any leg carrying `resultRefs` (flow reference handoff): the scoped reader
+	 *  handed to the broker pages THIS archive, after a zero-usage preflight verified every
+	 *  granted ref is durably stored. Absent ⇒ such legs fail closed before any spawn. */
+	resultArchive?: () => ResultArchiveView | undefined;
 }
 
 export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
@@ -113,10 +128,38 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 		): Promise<AgentResult> {
 			const cfg = deps.resolveAgent(spec.agent);
 			if (!cfg) return unknownAgentFailure(spec.agent, deps.listAgents?.() ?? []);
+			let thinkingRequested: ThinkingLevel | undefined;
+			try {
+				thinkingRequested = resolveLegThinking(spec, cfg, deps.childThinking);
+			} catch (error) {
+				return { agent: spec.agent, output: "", usage: emptyUsage(), ok: false, failureKind: "contract", error: `[${spec.agent}] ${error instanceof Error ? error.message : String(error)}` };
+			}
 			const tools = spec.tools ?? cfg.tools;
 			const invalidTools = toolModifierFailure(spec.agent, tools);
 			if (invalidTools) return invalidTools;
 
+			// ── reference handoff preflight (contract 3/4) — BEFORE any broker work or spawn ──
+			// Admission uses the SAME shared rule as the in-process engine; storage is verified
+			// durable (session-entry); the broker binding is AWAITED before registration/spawn.
+			// Any miss is a zero-usage contract failure and the child is never invoked.
+			let admittedTools = tools;
+			let resultReader: ScopedReader | undefined;
+			if (spec.resultRefs !== undefined && spec.resultRefs.length > 0) {
+				const grant = admitResultReadTool({
+					specTools: spec.tools, cfgTools: cfg.tools, excludeTools: cfg.excludeTools,
+					canUseBus: deps.canUseBus ?? true,
+				});
+				if (!grant.ok) return referenceHandoffFailure(spec.agent, grant.error);
+				const archive = deps.resultArchive?.();
+				if (archive === undefined) return referenceHandoffFailure(spec.agent, "terminal result archive unavailable for reference handoff");
+				const scoped = makeScopedResultReader(archive, spec.resultRefs);
+				const { missing } = scoped.preflight();
+				if (missing.length > 0) return referenceHandoffFailure(spec.agent, `archived results unavailable: ${missing.join(", ")}`);
+				if (deps.broker === undefined) return referenceHandoffFailure(spec.agent, "cross-process broker reader unavailable for reference handoff");
+				resultReader = scoped;
+				admittedTools = grant.tools;
+			}
+
 			// Resolved (and pinned) up front: the SAME def both instructs the member and
 			// validates its output — an instruction/validation drift is impossible. A named
 			// contract that cannot be resolved is a hard configuration error: running the leg
@@ -130,12 +173,10 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 					: spec.task;
 			const task = contractDef ? `${withSkills}\n\n${contractInstructions(contractDef)}` : withSkills;
 			const childSpec: ChildRunSpec = { task };
-			let model = spec.model ?? deps.modelFor?.(spec.agent, spec.role) ?? cfg.model;
-			// Append an explicit thinking level (model:level) unless one is already present —
-			// a child without it defaults to "adaptive", which some models reject.
-			if (model && deps.childThinking && !model.includes(":")) model = `${model}:${deps.childThinking}`;
+			const model = spec.model ?? deps.modelFor?.(spec.agent, spec.role) ?? cfg.model;
 			if (model) childSpec.model = model;
-			if (tools !== undefined) childSpec.tools = tools;
+			if (thinkingRequested !== undefined) childSpec.thinking = thinkingRequested;
+			if (admittedTools !== undefined) childSpec.tools = admittedTools;
 			if (cfg.excludeTools && cfg.excludeTools.length > 0) childSpec.excludeTools = cfg.excludeTools;
 			// The shared behavioral layer (docs/SPINE.md) + the agent's own persona + any
 			// on-the-fly `role` specialisation from the spec. All three go out as
@@ -160,27 +201,46 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 
 			// Cross-process comm plane (spec B1-B7): absent broker ⇒ none of this runs, so
 			// the spawn env + behaviour stay byte-identical to pre-broker pi-persona.
-			// Present ⇒ mint a handle, register it with the host BEFORE
-			// spawn, wire the child's env, and give the caller a steer function.
+			// Present ⇒ mint a handle, (for a reference-handoff leg) AWAIT the strict reader
+			// binding BEFORE registration, register the handle with the host BEFORE spawn, wire
+			// the child's env, and give the caller a steer function.
 			let handle: string | undefined;
+			let preparedReader: PreparedResultReader | undefined;
 			if (deps.broker) {
-				handle = nextChildHandle(spec.agent);
+				const broker = deps.broker;
+			handle = nextChildHandle(spec.agent);
 				const wantsPeers = spec.peers === true && (deps.canUseBus ?? true);
-				const label = spec.name?.trim()
+				const busTools = (deps.canUseBus ?? true) ? ["contact_supervisor", ...(wantsPeers ? ["contact_peer"] : [])] : [];
+				const mergedTools = mergeSessionToolAllowlist(admittedTools, busTools);
+				if (mergedTools !== undefined) childSpec.tools = mergedTools;
+			const label = spec.name?.trim()
 					? sanitizeDisplayLabel(spec.name, handle)
 					: spec.role ? `${handle} (${roleHint(spec.role)})` : handle;
-				deps.broker.register({ handle, label, group: peerGroup, ...(wantsPeers ? { peers: true } : {}) });
+				if (resultReader !== undefined) {
+					try {
+						preparedReader = await broker.prepareResultReader(handle, resultReader, signal);
+					} catch (error) {
+						return referenceHandoffFailure(spec.agent, `broker result reader preparation failed: ${error instanceof Error ? error.message : String(error)}`);
+					}
+					childOptions.env = {
+						...childOptions.env,
+						// Private spawn credential for the child's bridge (bridge.ts installs read_result
+						// only when this is set); scrubbed from the inherited env inside child.ts.
+						PI_PERSONA_RESULT_READER_TOKEN: preparedReader.token,
+					};
+				}
+				broker.register({ handle, label, group: peerGroup, ...(wantsPeers ? { peers: true } : {}) });
 				childOptions.env = {
 					...childOptions.env,
-					PI_PERSONA_BUS: deps.broker.endpoint,
+					PI_PERSONA_BUS: broker.endpoint,
 					PI_PERSONA_HANDLE: handle,
+					PI_PERSONA_BUS_TOOLS: (deps.canUseBus ?? true) ? "on" : "off",
 					...(wantsPeers ? { PI_PERSONA_PEERS: "1" } : {}),
 					...(deps.allowBlocking ? { PI_PERSONA_ALLOW_BLOCKING: "1" } : {}),
 				};
 				// The parent-side watchdogs must not kill a leg that is genuinely waiting on the
 				// supervisor's answer (R9, inproc parity) — ask the bus, don't guess from a static flag.
-				childOptions.isBlocked = () => deps.broker!.hasPendingAskFrom(handle!);
-				const broker = deps.broker;
+				childOptions.isBlocked = () => broker.hasPendingAskFrom(handle!);
 				const h = handle;
 				const steer: SteerFn = Object.assign((text: string) => broker.steerFrame(h, text), {
 					isWaitingForSupervisor: () => broker.hasPendingAskFrom(h),
@@ -192,17 +252,21 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			try {
 				child = await runChildAgent(childSpec, signal, childOptions);
 			} finally {
-				// Unregister on EVERY settle path (success, failure, or an unexpected throw) —
-				// a leaked handle would otherwise linger in the host's registries forever.
+				// Revoke the reader grant and unregister on EVERY settle path (success, failure, or
+				// an unexpected throw) — a leaked grant would outlive its leg; a leaked handle would
+				// otherwise linger in the host's registries forever.
+				preparedReader?.revoke();
 				if (deps.broker && handle) deps.broker.unregister(handle);
 			}
 
 			const result: AgentResult = { agent: spec.agent, output: child.output, usage: child.usage, ok: child.ok };
-			// The provider/id the child ran on (drop any `:thinking` suffix) — for the UI and
+			if (thinkingRequested !== undefined) result.thinkingRequested = thinkingRequested;
+			if (child.thinkingEffective !== undefined) result.thinkingEffective = child.thinkingEffective;
+			// The opaque provider/id the child ran on — for the UI and
 			// as the seed of the provider-fallback chain on a provider failure. The child's
 			// STREAM-REPORTED model wins over the requested spec: a resolved alias or a
 			// provider-side redirect must seed the fallback chain with what actually ran.
-			const modelUsed = (child.model ?? childSpec.model ?? spec.model ?? cfg.model)?.split(":")[0];
+			const modelUsed = child.model ?? childSpec.model ?? spec.model ?? cfg.model;
 			if (modelUsed) result.modelUsed = modelUsed;
 			// Diagnostic tag: agent · model ref · dynamic overrides. Same shape as inproc engine,
 			// so failed follow-ups always say WHICH agent+model died and WHY.

package/src/engine/async.ts

@@ -11,13 +11,13 @@
 
 import type { ProgressSnapshot, ToolEvent } from "./stream.ts";
 import type { AgentResult } from "../orchestration/types.ts";
+import { resultReceiptHint, type ResultReceipt } from "../results/retrieval.ts";
 import { DEFAULT_ASYNC_RETAIN } from "../core/config.ts";
 import { MAX_DISPLAY_LABEL_CHARS, sanitizeDisplayLabel, sanitizeStatusLabel } from "../core/display-label.ts";
 import { compactTokens } from "../core/format.ts";
+import { isThinkingLevel } from "../core/types.ts";
 import { formatDuration } from "../core/time.ts";
 
-export { MAX_DISPLAY_LABEL_CHARS } from "../core/display-label.ts";
-
 /** "possibly stuck" — the soft stall signal shared by the operator card, the peek digest and the UI
  *  badge. It is deliberately patient: a long scan, a big generation, or a blocking command shows no
  *  visible progress yet is perfectly healthy, so every surface flags a leg only after a genuinely long quiet
@@ -33,6 +33,7 @@ export interface AsyncRun {
 	status: "running" | "done" | "failed" | "stopped";
 	progress: ProgressSnapshot;
 	result?: AgentResult;
+	resultReceipt?: ResultReceipt;
 	error?: string;
 	/** The codename the launcher gave this run (e.g. "atlas-static") — the SAME name shown on the
 	 *  agent-tree node for this run. When set, it's the canonical display name (over the bare
@@ -115,6 +116,7 @@ export class AsyncRunTracker {
 	/** Ids whose payload was evicted while STILL UNCOLLECTED, oldest first (insertion-ordered Set). */
 	private readonly droppedIds = new Set<string>();
 	private readonly completeListeners: Array<(run: AsyncRun) => void> = [];
+	private readonly createListeners: Array<(run: AsyncRun) => void> = [];
 	private seq = 0;
 	private readonly maxRetained: number;
 	private readonly now: () => number;
@@ -159,6 +161,9 @@ export class AsyncRunTracker {
 		if (meta.label !== undefined) entry.label = sanitizeDisplayLabel(meta.label);
 		if (meta.model !== undefined) entry.model = sanitizeDisplayLabel(meta.model, "model");
 		this.runs.set(id, entry);
+		for (const cb of [...this.createListeners]) {
+			try { cb(entry); } catch { /* archival observation cannot prevent launch */ }
+		}
 
 		const settle = (): void => this.settleOnce(entry);
 		// `Promise.resolve(run(...))` routes BOTH a returned rejection AND a SYNCHRONOUS throw from
@@ -176,7 +181,9 @@ export class AsyncRunTracker {
 				.then((result) => {
 					if (entry.settled) return; // force-settled by the supervisor — drop the late natural result
 					entry.status = result.ok ? "done" : result.failureKind === "abort" ? "stopped" : "failed";
-					entry.result = result;
+					// Retain scalar metadata by value: an engine reusing/mutating its result object
+					// after settlement must not rewrite this run's requested/observed effort.
+					entry.result = { ...result, usage: { ...result.usage }, ...(result.resultReceipt ? { resultReceipt: { ...result.resultReceipt } } : {}) };
 					if (!result.ok && result.error) entry.error = result.error;
 				})
 				.catch((err: unknown) => {
@@ -347,6 +354,14 @@ export class AsyncRunTracker {
 		return batch === undefined || !this.running().some((r) => r.batch === batch);
 	}
 
+	onCreate(cb: (run: AsyncRun) => void): () => void {
+		this.createListeners.push(cb);
+		return () => {
+			const i = this.createListeners.indexOf(cb);
+			if (i >= 0) this.createListeners.splice(i, 1);
+		};
+	}
+
 	onComplete(cb: (run: AsyncRun) => void): () => void {
 		this.completeListeners.push(cb);
 		return () => {
@@ -363,10 +378,18 @@ export function dedupeRunsById(runs: AsyncRun[]): AsyncRun[] {
 	return [...byId.values()];
 }
 
+/** A terminal engine observation supersedes the launch choice; running/launch rows retain their snapshot. */
+export function observedRunModel(run: Partial<Pick<AsyncRun, "status" | "result">>): string | undefined {
+	const model = run.status !== undefined && run.status !== "running" ? run.result?.modelUsed : undefined;
+	return model?.trim() ? model.split("/").map((part) => sanitizeDisplayLabel(part, "model", 256)).join("/").slice(0, 256) : undefined;
+}
+
 /** One identity everywhere a tracked run is rendered: the launcher's codename when present,
- *  otherwise the agent type, with the already-shortened model appended once. */
-export function runDisplayName(run: Pick<AsyncRun, "agent" | "label" | "model">): string {
-	const model = run.model === undefined ? undefined : sanitizeDisplayLabel(run.model, "model", 24);
+ *  otherwise the agent type, with the observed terminal model or launch model appended once. */
+export function runDisplayName(run: Pick<AsyncRun, "agent" | "label" | "model"> & Partial<Pick<AsyncRun, "status" | "result">>): string {
+	const observed = observedRunModel(run);
+	const selected = observed ? (observed.split("/").pop() ?? observed).replace(/^claude-/, "") : run.model;
+	const model = selected === undefined ? undefined : sanitizeDisplayLabel(selected, "model", 24);
 	if (model === undefined) return sanitizeDisplayLabel(run.label ?? run.agent);
 	const suffix = ` · ${model}`;
 	const nameLimit = Math.max(1, MAX_DISPLAY_LABEL_CHARS - suffix.length);
@@ -618,6 +641,25 @@ export function buildCompletionReport(runs: AsyncRun[], fence: (text: string) =>
 	const stoppedCount = stopped.length > 0 ? `, ${stopped.length} stopped` : "";
 	const head = `[pi-persona] ${runs.length} async run${runs.length === 1 ? "" : "s"} settled — ${done.length} done, ${failed.length} failed${stoppedCount}`;
 	const blocks: string[] = [head];
+	const models = runs.flatMap((run) => {
+		const model = observedRunModel(run);
+		return model ? [`${run.id}: Observed model: ${model}`] : [];
+	});
+	if (models.length > 0) blocks.push(`\n${models.join("\n")}`);
+	const receipts = runs.slice(0, MAX_ASYNC_STATUS_ROWS).flatMap((run) => {
+		const hint = resultReceiptHint(run.resultReceipt);
+		return hint ? [`${run.id}: ${hint}`] : [];
+	});
+	if (receipts.length > 0) blocks.push(`\nTerminal reports (intercom results lists all retained references):\n${receipts.join("\n")}`);
+	// Common result metadata, outside untrusted worker prose, on inline and background paths.
+	// A host effort observation is a Pi request setting, not a measure of provider cognition.
+	const efforts = runs.flatMap((r) => {
+		const requested = r.result?.thinkingRequested;
+		const observed = r.result?.thinkingEffective;
+		if (!isThinkingLevel(requested) && !isThinkingLevel(observed)) return [];
+		return [`${r.id}: requested ${isThinkingLevel(requested) ? requested : "unknown"}; observed Pi effort ${isThinkingLevel(observed) ? observed : "unknown"}`];
+	});
+	if (efforts.length > 0) blocks.push(`\nThinking (not provider cognition):\n${efforts.join("\n")}`);
 	for (const r of done) {
 		// Only fence REAL output — an empty/whitespace result gets a plain "(no output)", never an
 		// empty <fence></fence> shell (there's nothing untrusted to guard, and the empty block reads
@@ -660,7 +702,7 @@ export function buildCompletionReport(runs: AsyncRun[], fence: (text: string) =>
 	// The cap cuts whole legs from the middle of a wide fan-out. Name every run in the tail, which the
 	// cut keeps, so a cut leg is still fetchable by id instead of silently missing.
 	const named = report.length > MAX_COMPLETION_REPORT_CHARS
-		? `${report}\n\nRun ids in this report: ${runs.slice(0, MAX_ASYNC_STATUS_ROWS).map((r) => r.id).join(", ")}`
+		? `${report}\n\nRun ids in this report: ${runs.slice(0, MAX_ASYNC_STATUS_ROWS).map((r) => r.id).join(", ")}. Saved reports: intercom { action:"results" }; use result { ref, offset, limit } even if live handles were dropped.`
 		: report;
 	return boundCompletionSurface(named);
 }
@@ -697,9 +739,6 @@ export const MAX_EMPTY_RENDER_RETRIES = 3;
 export interface IdleNotifierDeps<T> {
 	/** Whether the supervisor is idle (not streaming a turn). */
 	isIdle: () => boolean;
-	/** Legacy host-queue probe. Retained for source compatibility, but deliberately ignored: when
-	 *  the supervisor is idle, starting a turn is what drains any orphaned host follow-ups. */
-	hasPending?: () => boolean;
 	/** Deliver the coalesced message. Async rejection is treated exactly like a synchronous throw:
 	 *  the batch is restored at the front of the queue and retried. */
 	deliver: (message: string) => void | Promise<void>;

package/src/engine/child.ts

@@ -10,11 +10,13 @@ import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
 
+import type { ThinkingLevel } from "../core/types.ts";
 import { applyEvent, type ChildUsage, createStreamState, feedLines, type ProgressSnapshot, snapshot } from "./stream.ts";
 
 export interface ChildRunSpec {
 	task: string;
 	model?: string;
+	thinking?: ThinkingLevel;
 	tools?: string[];
 	excludeTools?: string[];
 	systemPrompt?: string;
@@ -32,6 +34,7 @@ export interface ChildRunResult {
 	/** True when the idle watchdog OR the hard wall-clock cap fired. Disjoint from `aborted`. */
 	timedOut: boolean;
 	model?: string;
+	thinkingEffective?: ThinkingLevel;
 	stopReason?: string;
 	errorMessage?: string;
 }
@@ -166,6 +169,7 @@ export async function runChildAgent(
 
 	const args: string[] = ["--mode", "json", "-p", "--no-session"];
 	if (spec.model) args.push("--model", spec.model);
+	if (spec.thinking !== undefined) args.push("--thinking", spec.thinking);
 	if (spec.tools !== undefined) {
 		if (spec.tools.length > 0) args.push("--tools", spec.tools.join(","));
 		else args.push("--no-tools");
@@ -201,13 +205,16 @@ export async function runChildAgent(
 			const inv = resolveInvocation(args);
 			// A stale broker wiring in the SUPERVISOR's own environment must not leak into a
 			// plain child: PI_PERSONA_BUS would boot the child's bridge against a dead (or
-			// foreign) endpoint. The adapter re-adds these deliberately via opts.env when a
-			// broker is actually live for THIS run.
+			// foreign) endpoint, and a stale reader token would arm a read_result tool nobody
+			// granted. The adapter re-adds these deliberately via opts.env when a broker (and a
+			// result-reader grant) is actually live for THIS run.
 			const inherited = { ...process.env };
 			delete inherited.PI_PERSONA_BUS;
 			delete inherited.PI_PERSONA_HANDLE;
 			delete inherited.PI_PERSONA_PEERS;
 			delete inherited.PI_PERSONA_ALLOW_BLOCKING;
+			delete inherited.PI_PERSONA_BUS_TOOLS;
+			delete inherited.PI_PERSONA_RESULT_READER_TOKEN;
 			const proc = spawn(inv.command, inv.args, {
 				cwd: spec.cwd ?? process.cwd(),
 				shell: false,
@@ -496,6 +503,7 @@ export async function runChildAgent(
 			timedOut: timedOut || hardTimedOut || startupTimedOut,
 		};
 		if (state.model !== undefined) result.model = state.model;
+		if (state.thinkingEffective !== undefined) result.thinkingEffective = state.thinkingEffective;
 		if (state.stopReason !== undefined) result.stopReason = state.stopReason;
 		// errorMessage precedence: a timeout/abort is the *cause of death*, so label
 		// it explicitly and fold in any stream-level error rather than letting the