@aeondave/pi-persona 1.17.0 → 1.17.3

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 };
+}

package/src/tools/council.ts

@@ -2,8 +2,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { fenceUntrusted } from "../core/fence.ts";
-import { expandDetailHint, failureDetails, formatCouncilCallLabel } from "../extension/shared.ts";
-import { knownParams, strategyNames } from "../orchestration/strategy.ts";
+import { expandDetailHint, failureDetails, formatCouncilCallLabel, isInline } from "../extension/shared.ts";
+import { knownParams, missingRequiredParams, strategyCatalog } from "../orchestration/strategy.ts";
 import { memberBaseLabel, type RosterMember } from "../orchestration/roster.ts";
 import { formatCouncilResult, humanizeAggregateResult } from "../orchestration/render.ts";
 import type { FailureKind } from "../orchestration/types.ts";
@@ -12,10 +12,11 @@ import { resolveCouncilInvocation } from "../persona/persona.ts";
 import type { OrchestrationGrammar, Persona } from "../persona/persona.ts";
 import type { PersonaController } from "../persona/controller.ts";
 import { Text } from "@earendil-works/pi-tui";
-import { compactInlineText, sanitizeTerminalText } from "../ui/presentation.ts";
-import { compactVisibleText } from "../ui/presentation.ts";
-import { toolUsageField, type ChildUsageLedger } from "../ui/usage.ts";
+import { createReportBody } from "../ui/report-body.ts";
+import { compactInlineText, compactVisibleText, sanitizeTerminalText } from "../ui/presentation.ts";
+import { toolUsageField } from "../ui/usage.ts";
 import { emptyUsage } from "../engine/stream.ts";
+import { launchReceipt, type BackgroundRuns, type TrackedRun } from "./background-run.ts";
 
 
 export interface CouncilToolDeps {
@@ -28,11 +29,11 @@ export interface CouncilToolDeps {
 		orch: OrchestrationGrammar,
 		task: string,
 		label: string,
-		signal?: AbortSignal,
+		tracked?: TrackedRun,
 	): Promise<AgentResult | undefined>;
+	/** Launch/join: a council is one tracked run, like a delegate leg (see background-run.ts). */
+	runs: BackgroundRuns;
 	drainBusBlock(): string;
-	childUsage: ChildUsageLedger;
-	publishPersonaCost(): void;
 }
 
 /** What the card names as the panel: the team, or the ad-hoc members themselves — an
@@ -55,7 +56,7 @@ export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void
 		strategy: Type.Optional(
 			Type.String({ description: 'Per-call strategy override (default: the selected or active council profile\'s strategy, or built-in "magi")' }),
 		),
-		roster: Type.Optional(Type.String({ description: 'Per-call roster override (default: the selected or active profile\'s roster, then its orchestration roster, or built-in "magi")' })),
+		roster: Type.Optional(Type.String({ description: 'Per-call roster override (default: the method\'s own team when you switch method; else the selected or active profile\'s roster, then its orchestration roster, or built-in "magi")' })),
 		members: Type.Optional(
 			Type.Array(Type.Unknown(), {
 				description:
@@ -72,30 +73,24 @@ export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void
 	pi.registerTool({
 		name: "council",
 		label: "Council",
-		description: [
+		// The method catalog is generated from the strategy registry (`when`/`roster`/`required`), never hand-written.
+		description: `${[
 			"Convene a council of specialists with controlled, complementary biases to deliberate a",
-			"decision — returns the selected strategy's result, preserving vote tally and dissent when produced.",
-			"Scale it to the decision: convene for a genuine fork, a contested or high-stakes call, or a",
-			"pick between rival answers — NOT before every decision, and a routine task does not",
-			"deserve a whole panel. Then EXECUTE the ruling yourself and re-convene only when execution",
-			"surfaces a NEW decision. Do NOT use it to get work done: `delegate` (and your own tools)",
-			"produce the work; the council decides, the executor acts.",
-			"Patterns: adversarial vote with dissent (magi, council-rounds); a reasoned pick between rival",
-			"COMPLETE answers by an impartial arbiter (judge); adversarial critique then revise",
-			"(critic-loop); head-to-head argument (debate); many findings merged into ONE deliverable",
-			"(synthesize, map); rival implementations judged blind (compete); a single pair (pair).",
+			"decision or run a coordinated method over a task — returns the selected strategy's result,",
+			"preserving vote tally and dissent when produced.",
+			"Scale it to the task: convene when the method adds value — NOT before every decision, and a",
+			"routine task does not deserve a whole panel. Then act on the result yourself and re-convene only",
+			"when acting surfaces a NEW decision. Do NOT use it for plain independent parallel work: that is",
+			"`delegate`. Interactive sessions run a council in the background: you get a run id at once and ONE",
+			"follow-up carries the ruling, so end your turn and never poll it; headless sessions return the",
+			"ruling inline.",
 			'Use `persona: "magi"` to invoke an installed persona\'s declared council without switching away',
 			"from the active caller; its prompt, model, tools, and permissions are never inherited.",
-			`Strategies: ${strategyNames()
-				.map((n) => {
-					const p = knownParams(n);
-					const keys = p ? Object.keys(p) : [];
-					return keys.length > 0 ? `${n}(${keys.join(", ")})` : n;
-				})
-				.join(" · ")}.`,
 			"Pass `members` to seat an ad-hoc panel for one call, or `params` to vary the profile's default",
 			'council — e.g. { "reflect": false }.',
-		].join(" "),
+			"Pick the strategy by problem class (`*` = required param):",
+		].join(" ")}
+${strategyCatalog()}`,
 		parameters: CouncilParams,
 		async execute(_id, params, signal, _onUpdate, ctx) {
 			d.lastCtx = ctx;
@@ -106,10 +101,13 @@ export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void
 				members: params.members,
 				params: params.params as Record<string, unknown> | undefined,
 			});
-			if (!resolved.ok) {
+			// A call that cannot run (no such persona, a missing `required` param) is refused HERE, as an
+			// immediate tool error — before a run, a tree row or the model picker exists.
+			const error = resolved.ok ? missingRequiredParams(resolved.value.strategy, resolved.value.params) : resolved.error;
+			if (!resolved.ok || error) {
 				return {
-					content: [{ type: "text", text: `council failed: ${resolved.error}` }],
-					details: failureDetails({ error: resolved.error, persona: params.persona }),
+					content: [{ type: "text", text: `council failed: ${error}` }],
+					details: failureDetails({ error: error ?? "", persona: params.persona }),
 					isError: true,
 				};
 			}
@@ -137,8 +135,29 @@ export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void
 				// Ephemeral members ride the SAME grammar path as a named team (see
 				// `resolveOrchestrationMembers`) — nothing about the profile is inherited.
 				if (members) orch.members = members;
-				const result = await d.runStrategyVisible(ctx, orch, params.question, `council:${_id}`, signal);
-				const s = (result?.structured ?? {}) as {
+				// The same launch `delegate` uses: ONE tracked run. Interactive sessions get a receipt now and
+				// the ruling as ONE completion follow-up (the idle-gated wake, fenced and bounded); headless
+				// sessions join the run before returning, since nothing would deliver a follow-up there.
+				const inline = isInline(ctx);
+				const id = d.runs.launch({ kind: "council", label: `council ${strategy}`, task: params.question, inline }, async (run) =>
+					(await d.runStrategyVisible(ctx, orch, params.question, "council", run)) ??
+					{ agent: strategy, output: "(the council returned no ruling)", usage: emptyUsage(), ok: false, error: "no ruling" });
+				if (!inline) {
+					const names = compactInlineText(`${strategy} · ${panel}`, { maxChars: 120 });
+					return {
+						content: [{ type: "text", text: `${launchReceipt("council", id, names, "with the ruling")}${paramNote}` }],
+						details: { runId: id, strategy, roster: panel, persona },
+						isError: false,
+					};
+				}
+				const { runs, usage } = await d.runs.settle([id], signal);
+				const run = runs[0];
+				const result = run?.result;
+				if (!result) {
+					const message = run?.error ?? run?.status ?? "the run record is gone";
+					return { content: [{ type: "text", text: `council failed: ${message}` }], details: failureDetails({ error: message, strategy, roster: panel }), isError: true };
+				}
+				const s = (result.structured ?? {}) as {
 					headline?: string;
 					status?: string;
 					tally?: Record<string, number>;
@@ -146,33 +165,28 @@ export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void
 					count?: number;
 					items?: unknown;
 				};
-				const ruling = result?.output ?? "(the council returned no ruling)";
-				const uiBody = result ? (humanizeAggregateResult(result) ?? result.output) : "";
 				const headline = s.headline ?? (typeof s.count === "number" ? `${s.count} member results` : s.status ?? "");
-				const ok = result?.ok ?? false;
 				const details = {
-					ok,
+					ok: result.ok,
 					headline,
 					status: s.status,
 					tally: s.tally,
 					usedFallback: s.usedFallback,
 					items: s.items,
-					body: uiBody,
+					body: humanizeAggregateResult(result) ?? result.output,
 					strategy,
 					roster: panel,
 					persona,
-					...(result?.error ? { error: result.error } : {}),
-					...(result?.failureKind ? { failureKind: result.failureKind } : {}),
+					...(result.error ? { error: result.error } : {}),
+					...(result.failureKind ? { failureKind: result.failureKind } : {}),
 				};
-				const usage = result?.usage ?? emptyUsage();
-				d.childUsage.account(usage);
-				d.publishPersonaCost();
 				return {
 					// The ruling is sub-agent (council member) text — fence it like every other
 					// path that hands sub-agent output to the supervisor.
-					content: [{ type: "text", text: `${fenceUntrusted(ruling)}${paramNote}${d.drainBusBlock()}` }],
-					details: ok ? details : failureDetails(details),
-					isError: !ok,
+					// A run stopped before it convened has no ruling, only its cause: show that, not an empty fence.
+					content: [{ type: "text", text: `${fenceUntrusted(result.output || result.error || "")}${paramNote}${d.drainBusBlock()}` }],
+					details: result.ok ? details : failureDetails(details),
+					isError: !result.ok,
 					...toolUsageField(usage),
 				};
 			} catch (err) {
@@ -193,7 +207,7 @@ export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void
 			const roster = resolved.ok ? panelLabel(resolved.value) : (args.roster ?? args.persona ?? "?");
 			return new Text(theme.fg("toolTitle", theme.bold(formatCouncilCallLabel(strategy, roster))), 0, 0);
 		},
-		renderResult(result, { expanded }, theme) {
+		renderResult(result, { expanded }, theme, context) {
 			const d = (result.details ?? {}) as {
 				ok?: boolean;
 				headline?: string;
@@ -205,24 +219,35 @@ export function registerCouncilTool(pi: ExtensionAPI, d: CouncilToolDeps): void
 				roster?: string;
 				error?: string;
 				failureKind?: FailureKind;
+				runId?: string;
 			};
 			const first = result.content[0];
+			const failed = (context?.isError ?? result.isError) || d.ok === false || !!d.error;
+			if (d.runId) {
+				// Interactive launch receipt: the ruling arrives later as the completion follow-up.
+				const launched = failed ? theme.fg("error", theme.bold("council failed"))
+					: `${theme.fg("toolTitle", theme.bold("council "))}${theme.fg("accent", compactInlineText(`launched ${d.runId} · ${d.strategy ?? "?"} · ${d.roster ?? "?"}`, { maxChars: 120 }))}`;
+				return new Text(expanded && first?.type === "text" ? `${launched}\n${theme.fg("toolOutput", sanitizeTerminalText(first.text))}` : launched, 0, 0);
+			}
 			const body = sanitizeTerminalText(d.body || (first && first.type === "text" ? first.text : ""));
-			const failed = d.ok === false || !!d.error;
 			if (failed) {
 				const cause = compactInlineText([d.failureKind, d.error].filter((part): part is string => !!part).join(" · "), { maxChars: 160 });
-				const title = theme.fg("error", theme.bold(`council failed${cause ? ` · ${cause}` : ""}`));
-				if (expanded) return new Text(`${title}\n${theme.fg("toolOutput", body || "(no ruling)")}`, 0, 0);
+				const title = () => theme.fg("error", theme.bold(`council failed${cause ? ` · ${cause}` : ""}`));
+				if (expanded) {
+					// Only a completed council retains a ruling body; preflight/host errors are literal.
+					if (typeof d.body === "string") return createReportBody(body || "(no ruling)", theme, { header: title }, context?.lastComponent);
+					return new Text(`${title()}\n${theme.fg("toolOutput", body || "(no ruling)")}`, 0, 0);
+				}
 				const preview = compactVisibleText(body || "(no ruling)", { maxLines: 3, maxLineChars: 100 });
 				const hint = preview.truncated ? `\n${theme.fg("dim", expandDetailHint())}` : "";
-				return new Text(`${title}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
+				return new Text(`${title()}\n${theme.fg("toolOutput", preview.text)}${hint}`, 0, 0);
 			}
 			const text = formatCouncilResult(
 				{ headline: d.headline, status: d.status, tally: d.tally, usedFallback: d.usedFallback, body },
 				expanded,
 				expandDetailHint(),
 			);
-			return new Text(theme.fg(expanded ? "toolOutput" : "accent", text), 0, 0);
+			return expanded ? createReportBody(text, theme, {}, context?.lastComponent) : new Text(theme.fg("accent", text), 0, 0);
 		},
 	});
 }