pi-legion 5.0.1 → 5.2.0

package/src/supervisor/types.ts

@@ -90,19 +90,451 @@ export interface UsageSnapshot {
 	costUsd: number;
 }
 
+/**
+ * What a `steer` call actually achieved (#313).
+ *
+ * - `"queued"`: the text sits behind the child's in-flight work and is consumed
+ *   at its next turn boundary — the model has not seen it yet.
+ * - `"accepted"`: the call started a turn with the text (the child was idle, so
+ *   there was no queue to wait in). Still not proof the model read it.
+ * - `"intercepted"`: an input handler consumed the text before it was ever
+ *   queued — the child never saw it.
+ *
+ * There is deliberately no `"delivered"`: no seam observes the model reading the
+ * text, so any such claim would be invented.
+ */
+export type SteerDisposition = "queued" | "accepted" | "intercepted";
+
+/**
+ * Normalize the SDK's disposition vocabulary into {@link SteerDisposition}
+ * (#313 D2). The only place this mapping happens.
+ *
+ * `"handled"` is the SDK's *interception* signal, never delivery:
+ * `_queueUserInput` returns it **before** `_queueSteer` runs
+ * (`dist/core/agent-session.js:1694-1697`), so an input handler swallowed the
+ * text and the child never saw it. The RPC client says the same from the other
+ * side: `dist/modes/rpc/rpc-client.js:133` — "If the disposition is 'handled',
+ * no run started for this prompt".
+ *
+ * Everything else — `"queued"`, `undefined`, a backend that returns junk, an
+ * older SDK that returns nothing — means the text went in. `route` only decides
+ * what "went in" is called, and only for a child that was idle: a steer has
+ * nowhere to go but the queue (`"queued"`), while a `route` of `"prompt"` means
+ * `prompt()` returned without throwing, i.e. the session accepted a turn with
+ * this text (`"accepted"`) — `"handled"` is the only "no turn started" signal
+ * a prompt can produce.
+ */
+export function toSteerDisposition(
+	raw: unknown,
+	route: "steer" | "prompt",
+): SteerDisposition {
+	if (raw === "handled") return "intercepted";
+	return route === "prompt" ? "accepted" : "queued";
+}
+
+/**
+ * What an `abort` request actually achieved (#314 D1).
+ *
+ * Three honest states, not a boolean:
+ *
+ * - `"interrupted"`: a turn was running and the interrupt request went through.
+ * - `"no-turn"`: nothing was running, so nothing was done — the queue was not
+ *   touched either, and `cleared` is all zeros.
+ * - `"timeout"`: the request went out but the child did not settle within the
+ *   caller's bound. It kills nothing: no retire, no state rewrite.
+ *
+ * `cleared` is the count the preceding queue clear reported (`steering` /
+ * `followUp` message counts), not a claim about what the model read.
+ *
+ * `timeoutMs` is the bound this call applied — or, for `no-turn`, the bound it
+ * WOULD have applied: that status returns before either step arms a timer, so
+ * nothing was bounded at all (#325). The number itself is the caller's
+ * `timeoutMs` after the junk fallback and the timer-delay cap, or
+ * `DEFAULT_ABORT_TIMEOUT_MS` when the caller passed nothing. It travels in the
+ * outcome because the receipt has to name the wait it is talking about, and the
+ * tool surface never passes a bound of its own — a receipt reading a default of
+ * its own would report a number nobody used. It is reported for all three
+ * statuses (normalization happens before the `turnActive` check), so a reader
+ * never has to wonder whether the field is present, only whether a timer ran.
+ */
+export type AbortOutcome = {
+	status: "interrupted" | "no-turn" | "timeout";
+	cleared: { steering: number; followUp: number };
+	/** The bound this call applied, or would have applied on `no-turn` (see above). */
+	timeoutMs: number;
+};
+
+/**
+ * Bound for one `abort` (#314 D2), applied by both backends.
+ *
+ * The tool-surface receipt does NOT read it any more: it formats the bound the
+ * backend reported in `AbortOutcome.timeoutMs` (#325), so this constant stays the
+ * single source of the default bound.
+ *
+ * It bounds the pre-abort queue clear AND the interrupt that follows it
+ * (#314 D4), so a child that answers neither can delay the caller by at most
+ * about twice this — never by the RPC client's own request timeout.
+ */
+export const DEFAULT_ABORT_TIMEOUT_MS = 5_000;
+
+/**
+ * Largest delay `setTimeout` honours: 2^31 − 1 ms (~24.8 days).
+ *
+ * Node does not saturate an out-of-range delay, it **collapses it to 1 ms**
+ * (`TimeoutOverflowWarning: … does not fit into a 32-bit signed integer`), so an
+ * over-large `timeoutMs` would reproduce exactly the fake instant `"timeout"`
+ * the abort normalization exists to prevent (#314 D2). Both backends therefore
+ * clamp their bound to this value instead of trusting the caller's number.
+ */
+export const MAX_ABORT_TIMER_DELAY_MS = 2_147_483_647;
+
+/**
+ * Count what a queue clear dropped (#314 D2): read `{steering, followUp}` array
+ * lengths off whatever the backend's `clearQueue` returned. Anything else — a
+ * throw or a clear that never answers is handled by the caller — counts 0.
+ *
+ * Both backends call this so the two never disagree about the same payload, and
+ * every call allocates, so no caller can mutate another's counts.
+ */
+export function countClearedQueue(raw: unknown): {
+	steering: number;
+	followUp: number;
+} {
+	const record =
+		typeof raw === "object" && raw !== null
+			? (raw as { steering?: unknown; followUp?: unknown })
+			: undefined;
+	return {
+		steering: Array.isArray(record?.steering) ? record.steering.length : 0,
+		followUp: Array.isArray(record?.followUp) ? record.followUp.length : 0,
+	};
+}
+
+/**
+ * A tool call a child is inside right now (#315).
+ *
+ * `startedAt` is the HOST clock reading taken when the child's own
+ * `tool_execution_start` event arrived. Elapsed time is always
+ * `Date.now() - startedAt`, i.e. one clock family measuring an age — never two
+ * writers' timestamps arbitrated against each other (display-liveness D3).
+ */
+export interface ChildActivity {
+	/** Tool name exactly as the child's event stream reported it. */
+	readonly tool: string;
+	/** Host `Date.now()` when the start event arrived. */
+	readonly startedAt: number;
+	/**
+	 * Tool call id, when the child's event carried one. Used for exactly one
+	 * thing: matching the end event to the start it belongs to, so a parallel
+	 * call finishing cannot clear a different call still running.
+	 */
+	readonly toolCallId?: string;
+	/**
+	 * The call that made this one, when the child's event stream says so
+	 * (`codemode` → `bash` sets it). It is what tells a nested call apart from a
+	 * parallel sibling: without it, stack depth alone cannot say whether the
+	 * extra frames are *inside* the top call or merely *beside* it (#331).
+	 */
+	readonly parentToolCallId?: string;
+}
+
+/**
+ * The in-flight call stack for one child (#331).
+ *
+ * Oldest first, **innermost last**: `tool_execution_start` pushes, the matching
+ * `tool_execution_end` removes only its own frame, `agent_settled` empties the
+ * whole stack. The display reads the top (last) entry as "the tool it is inside
+ * right now"; every other frame is context (nesting / parallel siblings).
+ */
+export type InFlightToolStack = readonly ChildActivity[];
+
+/**
+ * A single tool call running at or past this bound gets a display-only marker
+ * (#315).
+ *
+ * Five minutes is chosen against the observable alternative: a child that stops
+ * making progress is currently invisible until its `collect` deadline (900s by
+ * default), because liveness calls any child holding a non-terminal handle
+ * alive. This bound fires well before that deadline, and it costs nothing but a
+ * string — it decides nothing and kills nothing.
+ */
+export const STALL_NOTICE_MS = 300_000;
+
+/**
+ * `451_000ms` → `00:07:31`. Hours are not capped, so an all-day call reads
+ * `30:00:00` instead of silently wrapping to `06:00:00`.
+ *
+ * A non-finite input is floored to the zero clock. `Math.max(0, Math.floor(NaN/1000))`
+ * is still `NaN`, which would render the readout as `NaN:NaN:NaN` — a defect that
+ * looks like data instead of a missing fact. Both clocks on this path are
+ * `Date.now()` readings, so this is belt-and-braces, not a live case.
+ */
+export function formatToolElapsed(elapsedMs: number): string {
+	const totalSecs = Number.isFinite(elapsedMs) ? Math.max(0, Math.floor(elapsedMs / 1000)) : 0;
+	const pad = (value: number): string => String(value).padStart(2, "0");
+	const hours = pad(Math.floor(totalSecs / 3600));
+	const minutes = pad(Math.floor((totalSecs % 3600) / 60));
+	return `${hours}:${minutes}:${pad(totalSecs % 60)}`;
+}
+
+/**
+ * The one-line activity readout for a child that is inside tool call(s) (#315,
+ * #331): `working · bash 00:07:31`, plus context hints and a marker once the
+ * top call has run for {@link STALL_NOTICE_MS}.
+ *
+ * The `working` prefix comes from the activity fact itself, not from the
+ * persisted child record: a start event with no matching end IS a child inside
+ * a tool call, while the record's `state` is only rewritten at turn boundaries
+ * and can lag (or read `retired` from a stale snapshot).
+ *
+ * The stack is LIFO (#331): the **last** element is the innermost call — the one
+ * the elapsed clock and the tool name come from. The remaining frames are
+ * context, reported only when the events name their parent:
+ *
+ * - frames that the top names (directly or transitively) through
+ *   `parentToolCallId` are nesting → ` (inside <outermost> ×<depth>)`;
+ * - frames that are NOT on that chain are parallel siblings → ` (+N more)`.
+ *
+ * With no `parentToolCallId` anywhere, a second frame cannot be told apart from
+ * a nested one, so it is reported as a sibling (` (+N more)`): that is the
+ * weaker, always-true claim. Inventing `inside` would be a false one.
+ *
+ * **Display only.** This builds a string. It does not decide `liveness()`, does
+ * not abort the call, and does not steer, retire or report anything — the
+ * marker names `abort` as the lever precisely because `steer` cannot reach a
+ * child that is already inside a tool call (#313).
+ *
+ * An empty stack renders the empty string: no fact, no line.
+ */
+export function formatInFlightToolLine(
+	stack: InFlightToolStack,
+	now: number,
+): string {
+	const activity = stack[stack.length - 1];
+	if (activity === undefined) return "";
+	// Same non-finite trap as `formatToolElapsed`, one step earlier: `Math.max(0,
+	// NaN)` is `NaN`, and `NaN < STALL_NOTICE_MS` is false, so an unusable clock
+	// would skip the short path and claim “no progress for NaNm”. Both clocks are
+	// `Date.now()` readings (belt-and-braces, not a live case) — but the marker is
+	// a claim, so an unusable clock must render as zero, never as a verdict.
+	const raw = now - activity.startedAt;
+	const elapsed = Number.isFinite(raw) ? Math.max(0, raw) : 0;
+	const chain = nestingChain(stack);
+	const hints: string[] = [];
+	if (chain.length > 1) {
+		// The outermost frame of the chain is the one that encloses everything the
+		// line is about; `×N` is the nesting depth it took to get to the top.
+		hints.push(` (inside ${chain[0]!.tool} ×${chain.length})`);
+	}
+	const siblings = stack.length - chain.length;
+	if (siblings > 0) hints.push(` (+${siblings} more)`);
+	const line = `working · ${activity.tool} ${formatToolElapsed(elapsed)}${hints.join("")}`;
+	if (elapsed < STALL_NOTICE_MS) return line;
+	const minutes = Math.floor(elapsed / 60_000);
+	return `${line} (long-running tool — no progress for ${minutes}m; \`steer\` cannot interrupt it, \`abort\` can)`;
+}
+
+/**
+ * The nesting chain that ends at the stack top (#331), outermost first.
+ *
+ * A frame is an ancestor when the current frame names it through
+ * `parentToolCallId`. The walk only looks *backwards* (a parent always started
+ * earlier) and visits each index at most once, so cyclic junk in an event
+ * stream cannot loop here. No parent links → `[top]`. The fallback exists
+ * because ids are optional on both sides of the event stream.
+ */
+function nestingChain(stack: InFlightToolStack): InFlightToolStack {
+	const chain: ChildActivity[] = [];
+	let index = stack.length - 1;
+	if (index < 0) return chain;
+	const seen = new Set<number>();
+	while (index >= 0 && !seen.has(index)) {
+		seen.add(index);
+		const current = stack[index]!;
+		chain.unshift(current);
+		const parentId = current.parentToolCallId;
+		if (parentId === undefined) break;
+		let parentIndex = -1;
+		for (let candidate = index - 1; candidate >= 0; candidate -= 1) {
+			if (stack[candidate]!.toolCallId === parentId) {
+				parentIndex = candidate;
+				break;
+			}
+		}
+		if (parentIndex < 0) break;
+		index = parentIndex;
+	}
+	return chain;
+}
+
+/**
+ * Fold one child lifecycle event into the in-flight-tool stack (#315, #331).
+ *
+ * Pure and total: an event that says nothing about tool boundaries returns
+ * `current` unchanged, so both backends can call this on every event without
+ * having to classify first.
+ *
+ * - `tool_execution_start` pushes a frame (a name-less start is ignored: no
+ *   invented tool);
+ * - `tool_execution_end` removes **only** the frame it names, by `toolCallId` —
+ *   never the whole stack. An inner `bash` ending inside `codemode` leaves the
+ *   outer frame running, and a parallel sibling finishing cannot erase the one
+ *   still in flight;
+ * - `agent_settled` empties the stack: a settled turn holds no tool, and an
+ *   aborted tool may never send its `end` at all.
+ *
+ * An end whose id matches no frame falls back to the topmost frame without an
+ * id (ids are optional on both sides), and otherwise changes nothing: trusting
+ * an unknown id would let a stranger's end erase a live call.
+ */
+export function nextInFlightTool(
+	current: InFlightToolStack,
+	event: {
+		readonly type?: unknown;
+		readonly toolName?: unknown;
+		readonly toolCallId?: unknown;
+		readonly parentToolCallId?: unknown;
+	},
+	now: number,
+): InFlightToolStack {
+	if (event.type === "agent_settled") return [];
+	if (event.type === "tool_execution_start") {
+		if (typeof event.toolName !== "string" || event.toolName === "") {
+			return current;
+		}
+		return [
+			...current,
+			{
+				tool: event.toolName,
+				startedAt: now,
+				...(typeof event.toolCallId === "string"
+					? { toolCallId: event.toolCallId }
+					: {}),
+				...(typeof event.parentToolCallId === "string"
+					? { parentToolCallId: event.parentToolCallId }
+					: {}),
+			},
+		];
+	}
+	if (event.type === "tool_execution_end") {
+		if (current.length === 0) return current;
+		const ended =
+			typeof event.toolCallId === "string" ? event.toolCallId : undefined;
+		// An end that cannot name its call is taken at face value: pop the top
+		// (innermost) frame, which is what a LIFO stream implies.
+		if (ended === undefined) return current.slice(0, -1);
+		for (let index = current.length - 1; index >= 0; index -= 1) {
+			if (current[index]!.toolCallId === ended) {
+				return [...current.slice(0, index), ...current.slice(index + 1)];
+			}
+		}
+		// No frame claims that id. The only frame it could still be is one that
+		// never got an id; an all-named stack is left untouched.
+		for (let index = current.length - 1; index >= 0; index -= 1) {
+			if (current[index]!.toolCallId === undefined) {
+				return [...current.slice(0, index), ...current.slice(index + 1)];
+			}
+		}
+		return current;
+	}
+	return current;
+}
+
 /** The orchestrator's frozen backend seam (legion-v2-contract.md §3.1). */
 export interface LegionSupervisor {
 	spawnChild(input: SpawnInput): Promise<ChildHandle>;
 	prompt(name: string, text: string): Promise<void>;
-	steer(name: string, text: string): Promise<void>;
+	/**
+	 * Steer a running child (#313): the returned disposition says what happened
+	 * to the text — `"queued"` behind its current tool batch, `"accepted"` as a
+	 * turn this call started, or `"intercepted"` by an input handler (the child
+	 * never saw it). Callers that build a receipt must report it.
+	 */
+	steer(name: string, text: string): Promise<SteerDisposition>;
 	followUp(name: string, text: string): Promise<void>;
-	abort(name: string): Promise<void>;
+	/**
+	 * Soft interrupt (#314): drop the child's queued steering/follow-up messages
+	 * FIRST, then interrupt the running turn, and wait a bounded time for it.
+	 *
+	 * Frozen defaults (#314 D2): `clearQueued` is **true** and `timeoutMs` is
+	 * `DEFAULT_ABORT_TIMEOUT_MS`. The bound covers the clear as well as the
+	 * interrupt, and a timeout never throws (#314 D4) — it returns
+	 * `status:"timeout"` and kills nothing.
+	 */
+	abort(
+		name: string,
+		opts?: { clearQueued?: boolean; timeoutMs?: number },
+	): Promise<AbortOutcome>;
 	waitSettled(name: string, timeoutMs?: number, signal?: AbortSignal): Promise<SettleResult>;
 	isAlive(name: string): boolean;
+	/**
+	 * The tool call this child is inside right now (#315), or `undefined`.
+	 *
+	 * Optional on purpose. It is a display-only read added after this seam was
+	 * frozen, and a supervisor that cannot answer it — a test double, a backend
+	 * predating #315 — must keep satisfying the contract. Absence means "no
+	 * activity fact", which renders no line at all: the same "no fact, no claim"
+	 * rule every other status source follows. Callers read it as
+	 * `supervisor.inFlightTool?.(name)`.
+	 *
+	 * A dead child never answers: holding no live handle, it can run no tool.
+	 */
+	inFlightTool?(name: string): ChildActivity | undefined;
+	/**
+	 * The whole in-flight stack (#331), innermost last, or `undefined`.
+	 *
+	 * Optional for the same reason as `inFlightTool`: a backend or test double
+	 * that cannot answer renders no line. {@link inFlightToolStackOf} is the one
+	 * place callers should read it, so a legacy double that only implements
+	 * `inFlightTool` still renders its single frame.
+	 *
+	 * A dead child never answers.
+	 */
+	inFlightToolStack?(name: string): InFlightToolStack | undefined;
+	/**
+	 * What this backend can actually observe (#323).
+	 *
+	 * `promptDisposition: false` means `prompt()` cannot tell "the session
+	 * accepted a turn" apart from "it did not throw": an input handler that
+	 * swallows the prompt is invisible. That is exactly the in-process backend —
+	 * the SDK's `AgentSession.prompt()` returns `void` — so its `accepted` is a
+	 * weaker claim than RPC's, where the reply carries the disposition.
+	 *
+	 * Frozen rule (#323 D1): a caller must never invent a `queued`/`intercepted`
+	 * distinction a backend cannot answer. The flag exists so that difference is
+	 * nameable instead of silently flattened. A facade-level read must never be
+	 * used to tell backends apart — the routing facade reports the intersection of
+	 * every backend it can reach; to distinguish, read the concrete backend
+	 * instance (`RoutingSupervisor.backendFor` resolves it, and `routing.rpc` /
+	 * `routing.inprocess` are the two capabilities it reaches). Contract:
+	 * `docs/legion-v2-contract.md` §3.1.
+	 *
+	 * Optional like `inFlightTool`: a supervisor that cannot answer must keep
+	 * satisfying the seam, and absence means "no capability claimed".
+	 */
+	capabilities?: { readonly promptDisposition: boolean };
 	stats(name: string): Promise<UsageSnapshot | null>;
 	retire(name: string, opts?: { graceful?: boolean }): Promise<void>;
 }
 
+/**
+ * Read the display fact as a stack (#331), with a one-frame fallback.
+ *
+ * `inFlightToolStack` is the precise read. A supervisor that predates #331 (a
+ * test double, an older backend) only implements `inFlightTool`, so its single
+ * call is wrapped as a one-frame stack — same line as before, no invented
+ * context. Absent everywhere → `undefined`, which renders no line at all.
+ */
+export function inFlightToolStackOf(
+	supervisor: Pick<LegionSupervisor, "inFlightTool" | "inFlightToolStack">,
+	name: string,
+): InFlightToolStack | undefined {
+	const stack = supervisor.inFlightToolStack?.(name);
+	if (stack !== undefined && stack.length > 0) return stack;
+	const top = supervisor.inFlightTool?.(name);
+	return top === undefined ? undefined : [top];
+}
+
 /**
  * RpcClient's public constructor options. Kept as an alias so the adapter tracks
  * the installed Pi SDK without widening the supervisor contract.
@@ -145,6 +577,11 @@ export interface RpcClientLike {
 	steer(message: string): Promise<unknown>;
 	followUp(message: string): Promise<unknown>;
 	abort(): Promise<void>;
+	/**
+	 * Optional so existing fakes keep satisfying this seam: drop the queued
+	 * steering/follow-up messages and answer their counts (#314 D2).
+	 */
+	clearQueue?(): Promise<unknown>;
 	getSessionStats(): Promise<unknown>;
 }
 

package/src/tui/status.ts

@@ -678,7 +678,8 @@ export interface StatusUi {
 	};
 }
 
-function isStaleUiError(error: unknown): boolean {
+/** Exported (#377): the same test the board uses, reused by the extension entry points. */
+export function isStaleUiError(error: unknown): boolean {
 	return (
 		error instanceof Error &&
 		(error.message.includes("This extension ctx is stale") ||