@aeondave/pi-persona 1.17.1 → 1.17.3

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/engine/adapter.ts

@@ -12,14 +12,14 @@ import { type ContractDef, contractInstructions, parseAndValidate, pinContract,
 import { sanitizeDisplayLabel } from "../core/display-label.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 { combineSignals } from "./signals.ts";
 import { toolModifierFailure, unknownAgentFailure, unknownContractFailure } from "./spec-preflight.ts";
-import type { ToolEvent } from "./stream.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
@@ -106,7 +106,7 @@ 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,
@@ -153,7 +153,7 @@ 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);
@@ -215,6 +215,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 +224,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 +241,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