@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/core/timer.ts

@@ -1,13 +1,12 @@
 /**
  * `TimerScheduler` — the pure kernel behind the supervisor-armable `timer` tool.
  *
- * Problem it solves: a supervisor that must WAIT for a fixed wall-clock moment (a scheduled event,
- * a service window, a scheduled re-check) has no cheap way to "sleep and resume". The
- * MCP/transport layer caps a blocking tool call at ~20-60s, so a 50-minute wait degenerates into
- * dozens of token-burning polls. The fix is an ALARM, not a sleep: arm a timer that, when it
- * expires, WAKES the session by injecting a follow-up (the extension routes the fire through the
- * same idle-delivery notifier that surfaces async-run completions — an idle delivery always starts
- * a fresh turn, so the supervisor resumes on its own).
+ * Problem it solves: a supervisor needs a wake at a fixed wall-clock moment the world decides (a
+ * scheduled event, a service window, a reminder). The MCP/transport layer caps a blocking tool
+ * call at ~20-60s, so a blocking sleep is not an option. The fix is an ALARM: arm a timer that,
+ * when it expires, WAKES the session by injecting a follow-up (the extension routes the fire
+ * through the same idle-delivery notifier that surfaces async-run completions — an idle delivery
+ * always starts a fresh turn, so the supervisor resumes on its own).
  *
  * This module is pure (injected clock + setTimer/clearTimer + an onFire sink), so scheduling,
  * validation, cancellation and listing are unit-tested without a live model or real wall clock.
@@ -65,6 +64,11 @@ export interface TimerSchedulerDeps {
 	clearTimer: (handle: unknown) => void;
 	/** Called exactly once when a timer expires (never for a cancelled one). */
 	onFire: (entry: TimerEntry) => void;
+	/** Called once per admitted alarm, right after `arm` accepts it (never for a rejected request).
+	 *  Every announced alarm later reaches exactly one of `onFire` / `onCancelled`. */
+	onArmed?: (entry: TimerEntry) => void;
+	/** Called once per alarm dropped by `cancel` or `cancelAll` (never for one that fired). */
+	onCancelled?: (entry: TimerEntry) => void;
 	/** Minimum accepted delay (ms). Default 1000 — sub-second alarms are pointless here. */
 	minDelayMs?: number;
 	/** Maximum accepted delay (ms). Default 24h — guards against a runaway/typo alarm. */
@@ -75,12 +79,26 @@ export interface TimerSchedulerDeps {
 	/** Maximum follow-up message length (chars). Default 4000 — the stored message is
 	 *  re-injected into context at fire time, so it is a budget, not a document. */
 	maxMessageChars?: number;
+	/** Longest accepted label (code units). Default 120 — the label lands in the tree row, `timer list`
+	 *  and the fire message, so it is a caption, not a document. A longer label is CLIPPED (ending in
+	 *  "…"), not rejected: a verbose label must never cost the alarm. */
+	maxLabelChars?: number;
 }
 
 const DEFAULT_MIN_DELAY_MS = 1_000;
 const DEFAULT_MAX_DELAY_MS = 24 * 60 * 60 * 1_000;
 const DEFAULT_MAX_ARMED = 32;
 const DEFAULT_MAX_MESSAGE_CHARS = 4_000;
+const DEFAULT_MAX_LABEL_CHARS = 120;
+
+/** At most `max` code units, ending in "…" when clipped; never cuts an astral character in half. */
+function clipLabel(text: string, max: number): string {
+	if (text.length <= max) return text;
+	let end = Math.max(0, max - 1);
+	const last = text.charCodeAt(end - 1);
+	if (last >= 0xd800 && last <= 0xdbff) end -= 1;
+	return `${text.slice(0, end)}…`;
+}
 
 interface Scheduled {
 	entry: TimerEntry;
@@ -93,6 +111,7 @@ export class TimerScheduler {
 	private readonly maxDelayMs: number;
 	private readonly maxArmed: number;
 	private readonly maxMessageChars: number;
+	private readonly maxLabelChars: number;
 	private readonly timers = new Map<string, Scheduled>();
 	private seq = 0;
 
@@ -102,6 +121,7 @@ export class TimerScheduler {
 		this.maxDelayMs = deps.maxDelayMs ?? DEFAULT_MAX_DELAY_MS;
 		this.maxArmed = deps.maxArmed ?? DEFAULT_MAX_ARMED;
 		this.maxMessageChars = deps.maxMessageChars ?? DEFAULT_MAX_MESSAGE_CHARS;
+		this.maxLabelChars = deps.maxLabelChars ?? DEFAULT_MAX_LABEL_CHARS;
 	}
 
 	/** Arm a new alarm. Returns the entry on success, or a reason on rejection. */
@@ -137,13 +157,14 @@ export class TimerScheduler {
 		const id = `timer-${++this.seq}`;
 		const entry: TimerEntry = {
 			id,
-			label: (req.label ?? "").trim() || id,
+			label: clipLabel((req.label ?? "").trim(), this.maxLabelChars) || id,
 			fireAtEpochMs: fireAt,
 			armedAtEpochMs: now,
 			message,
 		};
 		const handle = this.deps.setTimer(() => this.fire(id), delay);
 		this.timers.set(id, { entry, handle });
+		this.deps.onArmed?.(entry);
 		return { ok: true, entry, remainingMs: delay };
 	}
 
@@ -153,13 +174,17 @@ export class TimerScheduler {
 		if (!scheduled) return false;
 		this.deps.clearTimer(scheduled.handle);
 		this.timers.delete(id);
+		this.deps.onCancelled?.(scheduled.entry);
 		return true;
 	}
 
 	/** Cancel every armed alarm (reload/dispose hygiene — never leak a timer across sessions). */
 	cancelAll(): void {
-		for (const scheduled of this.timers.values()) this.deps.clearTimer(scheduled.handle);
+		const dropped = [...this.timers.values()];
+		for (const scheduled of dropped) this.deps.clearTimer(scheduled.handle);
 		this.timers.clear();
+		// Announced after the map is empty, so a listener that re-enters (list/cancel) sees the truth.
+		for (const scheduled of dropped) this.deps.onCancelled?.(scheduled.entry);
 	}
 
 	/** Snapshot of all armed alarms, soonest first, with live remaining time. */

package/src/core/types.ts

@@ -14,7 +14,7 @@ export type { Permission };
  *  new level here too — `pi.getThinkingLevel()` returns the upstream union, so a missing member here
  *  is a hard compile error where the host reads it (see `PersonaHost.getThinkingLevel`). */
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
-const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
+export const THINKING_LEVELS = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 
 export function isThinkingLevel(x: unknown): x is ThinkingLevel {
 	return typeof x === "string" && (THINKING_LEVELS as readonly string[]).includes(x);

package/src/engine/adapter.ts

@@ -10,16 +10,23 @@ 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 AgentRunSpec, isPositiveFiniteMs, type SteerFn, type StrategyEngine } from "../orchestration/sdk.ts";
+import { type AgentProgress, type AgentRunSpec, isPositiveFiniteMs, type SteerFn, type StrategyEngine } from "../orchestration/sdk.ts";
 import type { AgentResult } from "../orchestration/types.ts";
 import { type ChildEngineOptions, type ChildRunSpec, runChildAgent } from "./child.ts";
 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 type { ToolEvent } from "./stream.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 {
@@ -106,17 +121,45 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 	return {
 		async run(
 			spec: AgentRunSpec,
-			onProgress?: (p: { output: string; tokens?: number; activity?: string; toolEvent?: ToolEvent }) => void,
+			onProgress?: (p: AgentProgress) => void,
 			callSignal?: AbortSignal,
 			/** Called once with a steer handle when the broker is on (in-process parity). */
 			onSteerable?: (steer: SteerFn) => void,
 		): 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
@@ -153,34 +194,53 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			if (isPositiveFiniteMs(spec.timeoutMs)) childOptions.timeoutMs = spec.timeoutMs;
 			if (onProgress) {
 				childOptions.onProgress = (snap) =>
-					onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolOutputAt !== undefined ? { toolOutputAt: snap.toolOutputAt } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
+					onProgress({ output: snap.output, tokens: snap.tokens, ...(snap.usage ? { usage: snap.usage } : {}), ...(snap.activity ? { activity: snap.activity } : {}), ...(snap.toolEvent ? { toolEvent: snap.toolEvent } : {}) });
 			}
 			// The run aborts if EITHER the whole-run signal or this agent's own (UI stop) fires.
 			const signal = combineSignals(deps.signal, callSignal);
 
 			// 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.
@@ -215,6 +279,8 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			const tag = `[${spec.agent} · ${modelRef}${dyn}]`;
 			if (child.errorMessage) result.error = `${tag} ${child.errorMessage}`;
 			else if (!child.ok) result.error = `${tag} ${child.stderr.trim() || `agent failed (exit ${child.exitCode})`}`;
+			const hostModuleHint = !child.ok ? piHostModuleHint(`${child.errorMessage ?? ""}\n${child.stderr}`) : undefined;
+			if (hostModuleHint && result.error) result.error += ` — ${hostModuleHint}`;
 			// MCP-leg diagnosis: an `mcp: true` leg is routed here (the child engine) precisely so
 			// `pi-mcp-adapter` initializes in a fresh headless `pi -p`. When such a leg fails without
 			// completing a single turn, the near-certain cause is the MCP adapter hanging in init —
@@ -222,7 +288,7 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			// Keyed on turns===0 (never really started), not empty output, so an early tool/log line
 			// can't mask it. Name the cause + the fix so the operator never has to guess (a real prod
 			// report: a dead `mcp: true` async delegation with an opaque timeout).
-			if (!child.ok && spec.mcp === true && child.usage.turns === 0) {
+			if (!child.ok && !hostModuleHint && spec.mcp === true && child.usage.turns === 0) {
 				result.error =
 					`${result.error ?? `${tag} agent failed`} — mcp:true leg never completed a turn: the MCP adapter likely hung initializing in the headless child ` +
 					`(a server needing interactive OAuth can't authenticate without a UI). Fix: authenticate the MCP server once in a normal \`pi\` session (\`/mcp auth\`) so its token is cached — the headless child reuses it; ` +
@@ -239,9 +305,11 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 					? "timeout"
 					: child.aborted
 						? "abort"
-						: child.stopReason === "error" || looksLikeProviderError(`${child.errorMessage ?? ""}\n${child.stderr}`)
-							? "provider"
-							: "agent";
+						: hostModuleHint
+							? "agent"
+							: child.stopReason === "error" || looksLikeProviderError(`${child.errorMessage ?? ""}\n${child.stderr}`)
+								? "provider"
+								: "agent";
 
 			if (contractDef) {
 				// Shared parse+validate (unwraps ```json fences / prose first) — a member's