@aeondave/pi-persona 1.15.2

package/src/orchestration/parallel.ts

@@ -0,0 +1,107 @@
+/**
+ * Bounded-concurrency fan-out — the one place concurrency is implemented.
+ * Pure (no I/O): order-preserving, clamps the limit, and never runs more than
+ * `concurrency` callbacks at once. Used by `parallel()` in the Strategy SDK and
+ * by the delegate tool's parallel mode.
+ */
+
+export async function mapWithConcurrency<TIn, TOut>(
+	items: TIn[],
+	concurrency: number,
+	fn: (item: TIn, index: number) => Promise<TOut>,
+): Promise<TOut[]> {
+	if (items.length === 0) return [];
+	const requested = Number.isFinite(concurrency) ? Math.floor(concurrency) : 1;
+	const limit = Math.max(1, Math.min(requested, items.length));
+	const results = new Array<TOut>(items.length);
+	let next = 0;
+	// Contained rejection, two halves. CONTAINMENT: once a callback rejects no worker pulls another
+	// item, so a failed fan-out can't keep spawning siblings whose results are already destined for
+	// the bin. LATENCY: the batch rejects with the FIRST error the moment it lands. A callback
+	// already in flight cannot be cancelled from here, so awaiting it would not stop the work — it
+	// would only delay the report, and the rejections that reach this path are the run-fatal ones
+	// (`sdk.parallel`: a limit breach, a throwing host callback) that an operator must see now
+	// rather than after the slowest healthy leg, which for a delegated agent is minutes. The worker
+	// swallows into `failure`, so an abandoned one can never surface as an unhandled rejection.
+	let failure: { error: unknown } | undefined;
+	let onFailure = (): void => { /* replaced below */ };
+	const fatal = new Promise<void>((resolve) => {
+		onFailure = resolve;
+	});
+	const worker = async (): Promise<void> => {
+		while (!failure) {
+			const index = next++;
+			if (index >= items.length) return;
+			try {
+				results[index] = await fn(items[index]!, index);
+			} catch (error) {
+				failure ??= { error };
+				onFailure();
+			}
+		}
+	};
+	await Promise.race([Promise.all(Array.from({ length: limit }, () => worker())), fatal]);
+	if (failure) throw failure.error;
+	return results;
+}
+
+/**
+ * A counting semaphore for concurrency across INDEPENDENT launches (where
+ * `mapWithConcurrency` can't apply because the jobs don't arrive as one batch) —
+ * e.g. async delegate runs launched across several tool calls. FIFO, throw-safe:
+ * the slot is released even when the job rejects.
+ */
+export class Semaphore {
+	private available: number;
+	private readonly waiters: Array<() => void> = [];
+
+	constructor(slots: number) {
+		this.available = Math.max(1, Number.isFinite(slots) ? Math.floor(slots) : 1);
+	}
+
+	/** Run `fn` once a slot is free; the slot is released when it settles. A signal removes a
+	 * queued waiter immediately, so a stopped background leg can never start later. */
+	async with<T>(fn: () => Promise<T>, signal?: AbortSignal): Promise<T> {
+		await this.acquire(signal);
+		try {
+			if (signal?.aborted) throw this.abortError();
+			return await fn();
+		} finally {
+			this.release();
+		}
+	}
+
+	private acquire(signal?: AbortSignal): Promise<void> {
+		if (signal?.aborted) return Promise.reject(this.abortError());
+		if (this.available > 0) {
+			this.available -= 1;
+			return Promise.resolve();
+		}
+		return new Promise((resolve, reject) => {
+			const grant = (): void => {
+				signal?.removeEventListener("abort", onAbort);
+				resolve();
+			};
+			const onAbort = (): void => {
+				const index = this.waiters.indexOf(grant);
+				if (index >= 0) this.waiters.splice(index, 1);
+				signal?.removeEventListener("abort", onAbort);
+				reject(this.abortError());
+			};
+			this.waiters.push(grant);
+			signal?.addEventListener("abort", onAbort, { once: true });
+		});
+	}
+
+	private abortError(): Error {
+		const error = new Error("Semaphore wait aborted");
+		error.name = "AbortError";
+		return error;
+	}
+
+	private release(): void {
+		const next = this.waiters.shift();
+		if (next) next(); // hand the slot straight to the next waiter
+		else this.available += 1;
+	}
+}

package/src/orchestration/params.ts

@@ -0,0 +1,23 @@
+/**
+ * Shared param normalisation for strategies. Unknown/junk values fall back rather than
+ * silently changing semantics (I2 is lenient on unknown KEYS; a declared number that is
+ * NaN/negative still has to mean something honest).
+ */
+
+/** A finite integer ≥ 1, else `fallback`. Fractional values floor. */
+export function positiveInteger(value: unknown, fallback: number): number {
+	if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) return fallback;
+	return Math.max(1, Math.floor(value));
+}
+
+/**
+ * A best-of-N threshold: positive integer, then clamped to the roster size.
+ * An unclamped `bestOf: 10` on a 3-member panel can never be reached, so every round
+ * would fall through to best-by-confidence while the header still claimed "best-of-10".
+ */
+export function clampBestOf(value: unknown, rosterSize: number): { bestOf: number; clamped: boolean } {
+	const majority = Math.floor(rosterSize / 2) + 1;
+	const requested = positiveInteger(value, majority);
+	const bestOf = Math.min(requested, Math.max(1, rosterSize));
+	return { bestOf, clamped: bestOf !== requested };
+}

package/src/orchestration/reducers.ts

@@ -0,0 +1,123 @@
+/**
+ * Reducers fold many `AgentResult`s into one. This module holds the two non-voting
+ * reducers — usage summation and labeled aggregation (for fanout); the voting
+ * reducer with the richer status union (winner|tie|no_consensus|invalid_outputs)
+ * lives in `voting.ts`.
+ */
+
+import { type ChildUsage, emptyUsage } from "../engine/stream.ts";
+import type { AgentResult, FailureKind } from "./types.ts";
+
+export interface FailedResultCause {
+	error: string;
+	failureKind: FailureKind;
+}
+
+/** Preserve the most actionable cause when a whole panel yields no usable result.
+ * User cancellation wins even in a mixed panel. Otherwise a homogeneous technical
+ * failure survives; mixed failures or successful-but-protocol-invalid outputs are
+ * classified at the enclosing strategy's contract boundary. */
+export function summarizeFailedResults(
+	results: AgentResult[],
+	fallbackError: string,
+	fallbackKind: FailureKind = "contract",
+): FailedResultCause {
+	const aborted = results.find((result) => !result.ok && result.failureKind === "abort");
+	if (aborted) return { error: aborted.error ?? "the run was aborted", failureKind: "abort" };
+
+	const failed = results.filter((result) => !result.ok);
+	if (failed.length > 0 && failed.length === results.length) {
+		const kinds = new Set(failed.map((result) => result.failureKind ?? "agent"));
+		if (kinds.size === 1) {
+			const failureKind = kinds.values().next().value as FailureKind;
+			const error = failed.find((result) => result.error)?.error ?? fallbackError;
+			return { error, failureKind };
+		}
+	}
+
+	return { error: fallbackError, failureKind: fallbackKind };
+}
+
+export function sumUsage(usages: ChildUsage[]): ChildUsage {
+	const total = emptyUsage();
+	for (const u of usages) {
+		total.input += u.input;
+		total.output += u.output;
+		total.cacheRead += u.cacheRead;
+		total.cacheWrite += u.cacheWrite;
+		total.cost += u.cost;
+		total.turns += u.turns;
+	}
+	return total;
+}
+
+export type ItemStatus = "completed" | "failed" | "not-run";
+
+/** One status entry per `map` sub-item — the batch's audit trail, independent of `ownership`. */
+export interface ItemLedgerEntry {
+	index: number;
+	item: string;
+	status: ItemStatus;
+	agent?: string;
+	failureKind?: FailureKind;
+	error?: string;
+	writeSet?: string[];
+}
+
+/** One ledger entry per item the splitter produced: `completed`/`failed` for an item a worker
+ *  actually ran (from `results`, in item order), `not-run` for the `dropped` tail that never got
+ *  a worker slot. Pure; carries the item's declared `writeSet` through when the caller kept it. */
+export function itemLedger(
+	allItems: readonly { item: string; writeSet?: string[] }[],
+	results: readonly AgentResult[],
+	dropped: number,
+): ItemLedgerEntry[] {
+	const ranCount = Math.max(0, allItems.length - dropped);
+	return allItems.map((it, index) => {
+		const writeSet = it.writeSet ? { writeSet: it.writeSet } : {};
+		const result = index < ranCount ? results[index] : undefined;
+		if (!result) return { index, item: it.item, status: "not-run", ...writeSet };
+		return {
+			index,
+			item: it.item,
+			status: result.ok ? "completed" : "failed",
+			agent: result.agent,
+			...(result.failureKind ? { failureKind: result.failureKind } : {}),
+			...(!result.ok && result.error ? { error: result.error } : {}),
+			...writeSet,
+		};
+	});
+}
+
+/** Combine fan-out results into one labeled-section result; ok iff all ok. */
+export function aggregateResults(results: AgentResult[]): AgentResult {
+	const sections = results.map((r) => {
+		const status = r.ok ? "ok" : `failed${r.failureKind ? ` (${r.failureKind})` : ""}`;
+		const body = r.output || r.error || "(no output)";
+		const cause = !r.ok && r.error && r.output && r.error !== r.output ? `\n\nError: ${r.error}` : "";
+		return `### [${r.agent}] ${status}\n\n${body}${cause}`;
+	});
+	const aggregate: AgentResult = {
+		agent: "aggregate",
+		output: sections.join("\n\n---\n\n"),
+		structured: {
+			count: results.length,
+			results: results.map((r) => ({
+				agent: r.agent,
+				ok: r.ok,
+				output: r.output,
+				error: r.error ?? null,
+				failureKind: r.failureKind ?? null,
+				structured: r.structured ?? null,
+			})),
+		},
+		usage: sumUsage(results.map((r) => r.usage)),
+		ok: results.every((r) => r.ok),
+	};
+	if (!aggregate.ok) {
+		const cause = summarizeFailedResults(results, "one or more agents failed", "agent");
+		aggregate.error = cause.error;
+		aggregate.failureKind = cause.failureKind;
+	}
+	return aggregate;
+}

package/src/orchestration/render.ts

@@ -0,0 +1,127 @@
+/**
+ * Shared rendering of a deliberation result — turn a member's structured fields into
+ * readable prose, NOT the raw JSON envelope. Used by every vote-style strategy (`magi`,
+ * `council-rounds`) so a ruling/dissent reads as text, never as tool JSON.
+ */
+
+import { compactInlineText } from "../ui/presentation.ts";
+import type { AgentResult } from "./types.ts";
+
+/** Child-authored chrome: strip terminal control sequences and bound the display width. */
+function safeChrome(value: string, max: number): string {
+	return compactInlineText(value, { maxChars: max });
+}
+
+function field(s: Record<string, unknown> | undefined, key: string): string | undefined {
+	const value = s?.[key];
+	return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+
+function oneLine(value: string, max = 220): string {
+	const compact = value.replace(/\s+/g, " ").trim();
+	return compact.length > max ? `${compact.slice(0, max - 1)}…` : compact;
+}
+
+function memberMeta(s: Record<string, unknown> | undefined): string[] {
+	const meta: string[] = [];
+	const vote = field(s, "vote");
+	if (vote) meta.push(`vote ${vote}`);
+	const confidence = s?.confidence;
+	if (typeof confidence === "number" && Number.isFinite(confidence)) {
+		meta.push(`confidence ${Math.round(Math.max(0, Math.min(1, confidence)) * 100)}%`);
+	}
+	return meta;
+}
+
+/** A member's human-readable position from its structured fields (result + output). */
+export function readableRuling(r: AgentResult): string {
+	const s = r.structured;
+	if (s) {
+		const parts: string[] = [];
+		const result = field(s, "result");
+		const output = field(s, "output");
+		if (result) parts.push(result);
+		if (output && output !== result) parts.push(output);
+		if (parts.length > 0) return parts.join("\n\n");
+	}
+	return r.output.trim();
+}
+
+/** A bounded one-line headline for collapsed strategy/tool presentations. */
+export function rulingHeadline(r: AgentResult): string | undefined {
+	const headline = oneLine(readableRuling(r), 120);
+	return headline || undefined;
+}
+
+/** Compact UI-only view of one child result. Structured fields win so JSON envelopes
+ *  never leak into the agent overlay; unstructured agents retain a prose fallback. */
+export function compactMemberResult(r: AgentResult): string {
+	const s = r.structured;
+	if (!s) return oneLine(r.output) || "(no output)";
+	const meta = memberMeta(s);
+	const summary = (field(s, "result") ?? field(s, "output") ?? r.output.trim()) || "(no output)";
+	return `${meta.length > 0 ? `${meta.join(" · ")}\n` : ""}${oneLine(summary)}`;
+}
+
+/** Human UI rendering for aggregate/fanout results. The aggregate contract itself is
+ *  untouched; this consumes its retained member envelopes only for presentation. */
+export function humanizeAggregateResult(r: AgentResult): string | undefined {
+	const members = r.structured?.results;
+	if (!Array.isArray(members)) return undefined;
+	const lines: string[] = [];
+	for (const value of members) {
+		if (!value || typeof value !== "object" || Array.isArray(value)) continue;
+		const member = value as Record<string, unknown>;
+		const agent = typeof member.agent === "string" && member.agent.trim() ? member.agent.trim() : "member";
+		const ok = member.ok === true;
+		const output = typeof member.output === "string" ? member.output : "";
+		const structured = member.structured && typeof member.structured === "object" && !Array.isArray(member.structured)
+			? (member.structured as Record<string, unknown>)
+			: undefined;
+		const view: AgentResult = { agent, output, usage: r.usage, ok };
+		if (structured) view.structured = structured;
+		const error = typeof member.error === "string" && member.error.trim() ? oneLine(member.error) : undefined;
+		const failureKind = typeof member.failureKind === "string" && member.failureKind.trim() ? member.failureKind.trim() : undefined;
+		const failure = !ok
+			? `${failureKind ? ` (${failureKind})` : ""}${error ? `: ${error}` : ""}`
+			: "";
+		lines.push(`${ok ? "✓" : "✗"} ${agent}${failure}\n${compactMemberResult(view)}`);
+	}
+	return lines.length > 0 ? lines.join("\n\n") : undefined;
+}
+
+export interface CouncilResultPresentation {
+	headline: string | undefined;
+	status: string | undefined;
+	tally: Record<string, number> | undefined;
+	usedFallback: boolean | undefined;
+	body: string;
+}
+
+/** Plain Pi result text; the call renderer owns the single `council …` title. */
+export function formatCouncilResult(input: CouncilResultPresentation, expanded: boolean, expandHint = "ctrl+o"): string {
+	const body = input.body.trim();
+	if (expanded) return body || "(the council returned no ruling)";
+	const firstBodyLine = body.split("\n").find((line) => line.trim())?.trim();
+	// headline/status/tally carry the winning member's own words (its `result`/`vote`), and
+	// only `body` is sanitized upstream — so bound and strip them here. The tally keys in
+	// particular are whole prose answers whenever a member omits its `vote` field.
+	const status = safeChrome(input.status?.replace(/_/g, " ") ?? "", 48);
+	const verdict = safeChrome(input.headline?.trim() || firstBodyLine || status || "(ruling)", 96);
+	const meta: string[] = [];
+	if (status && status.toLowerCase() !== verdict.toLowerCase()) meta.push(status);
+	if (input.usedFallback) meta.push("confidence fallback");
+	const tally = input.tally
+		? safeChrome(Object.entries(input.tally).map(([key, count]) => `${key}=${count}`).join(", "), 120)
+		: "";
+	if (tally) meta.push(`tally ${tally}`);
+	return `${verdict}${meta.length > 0 ? ` · ${meta.join(" · ")}` : ""} · ${expandHint}`;
+}
+
+/** A one-line dissent entry: who, how they voted, and their one-line position. */
+export function dissentLine(r: AgentResult): string {
+	const s = r.structured;
+	const vote = field(s, "vote") ?? "?";
+	const summary = field(s, "result") ?? field(s, "output") ?? r.output.trim();
+	return `[${r.agent} · ${vote}] ${oneLine(summary || "(no output)")}`;
+}

package/src/orchestration/roster.ts

@@ -0,0 +1,133 @@
+/**
+ * Roster loading — `teams.yaml` maps a team name to an ordered list of members.
+ * Referenced by a persona's `orchestration.roster` or `council.roster`.
+ *
+ * A member is either a bare agent name (`- scout`) OR a map that specialises ONE
+ * agent inline — `{ agent, role?, model?, skills? }` — so an ensemble of distinct
+ * perspectives can be built from a SINGLE agent (e.g. one `reviewer` run three times
+ * with different `role`s and models) instead of one .md file per perspective. That is
+ * the "skills + role provide specialisation, not files" principle applied to rosters.
+ *
+ * Pure: reuses the core YAML-subset parser. `rosterSpec` normalises a member into the
+ * run-spec fields the SDK's `agent()` accepts; `makeRoster` adapts a team map to the
+ * SDK's `Roster` interface (unknown team → empty list).
+ */
+
+import { asBoolean, asStringArray, parseYamlSubset } from "../core/frontmatter.ts";
+import type { Roster } from "./sdk.ts";
+
+/** A roster member: a bare agent name, or an inline specialisation of one agent. `tools`/
+ *  `isolation`/`mcp` bring a roster member to parity with an ad-hoc `delegate` task's own
+ *  knobs (see `tools/delegate.ts`'s `DelegateTask`). */
+export type RosterMember =
+	| string
+	| { agent: string; role?: string; model?: string; skills?: string[]; tools?: string[]; isolation?: "none" | "worktree"; mcp?: boolean };
+
+/** The normalised run-spec fields a member contributes (agent + any specialisation). */
+export interface RosterSpec {
+	agent: string;
+	role?: string;
+	model?: string;
+	skills?: string[];
+	tools?: string[];
+	isolation?: "none" | "worktree";
+	mcp?: boolean;
+}
+
+/** Normalise a member into the fields `sdk.agent()` accepts (a bare name → just `agent`).
+ *  `tools`/`isolation`/`mcp` map onto the SAME `AgentRunSpec` fields the `delegate` path's
+ *  `specOf()` uses for these three concepts — including explicit `none`/`false` overrides —
+ *  so a roster member and an ad-hoc task behave identically once specialised. */
+export function rosterSpec(member: RosterMember): RosterSpec {
+	if (typeof member === "string") return { agent: member };
+	const spec: RosterSpec = { agent: member.agent };
+	if (member.role?.trim()) spec.role = member.role.trim();
+	if (member.model?.trim()) spec.model = member.model.trim();
+	if (member.skills && member.skills.length > 0) spec.skills = member.skills;
+	if (member.tools !== undefined) spec.tools = member.tools;
+	if (member.isolation !== undefined) spec.isolation = member.isolation;
+	if (member.mcp !== undefined) spec.mcp = member.mcp;
+	return spec;
+}
+
+// Emphasised keywords in a role are the lens; small connective words are not — drop
+// them so "Focus ONLY on the SECURITY lens…" hints "SECURITY", not "ONLY".
+const ROLE_STOPWORDS = new Set([
+	"ONLY", "THE", "AND", "OR", "NOT", "FOR", "YOU", "YOUR", "ALL", "ANY", "USE", "VIA", "ONE",
+	"ON", "IN", "OF", "TO", "IS", "IT", "BE", "DO", "AS", "AT", "BY", "AN", "A",
+]);
+
+/** A short emphasis hint from a member's role text — the first salient ALL-CAPS keyword
+ *  (e.g. "SECURITY" from "Focus ONLY on the SECURITY lens…"), else the first few words.
+ *  Used to disambiguate same-agent roster-role members in the UI tree. Pure. */
+export function roleHint(role: string): string {
+	const words = role.split(/\s+/);
+	for (const w of words) {
+		const clean = w.replace(/[^A-Za-z0-9]/g, "");
+		if (clean.length >= 3 && /[A-Z]/.test(clean) && clean === clean.toUpperCase() && !ROLE_STOPWORDS.has(clean)) {
+			return clean;
+		}
+	}
+	const brief = words.slice(0, 4).join(" ").replace(/[:.,;].*$/, "").trim();
+	return brief.length > 20 ? `${brief.slice(0, 20)}…` : brief || "role";
+}
+
+/** The base UI label for a member: `agent`, or `agent · HINT` when it carries a role —
+ *  so an ensemble of one agent under several roles shows as distinct nodes. Pure. */
+export function memberBaseLabel(member: RosterMember): string {
+	const s = rosterSpec(member);
+	return s.role ? `${s.agent} · ${roleHint(s.role)}` : s.agent;
+}
+
+/** Disambiguated node keys for a roster, aligned to input order: the base label, with a
+ *  `#N` suffix only when the same base repeats. This is the SAME derivation the SDK applies
+ *  per `agent()` call (base from role, occurrence-suffixed), so the tree's seeded "queued"
+ *  nodes line up with the live ones instead of collapsing three same-name members into one.
+ *  Pure. */
+export function rosterNodeKeys(members: RosterMember[]): string[] {
+	const seen = new Map<string, number>();
+	return members.map((m) => {
+		const base = memberBaseLabel(m);
+		const n = (seen.get(base) ?? 0) + 1;
+		seen.set(base, n);
+		return n === 1 ? base : `${base}#${n}`;
+	});
+}
+
+/** Coerce one raw YAML value into a roster member (string name, or `{ agent, … }` map). */
+function toMember(raw: unknown): RosterMember | undefined {
+	if (typeof raw === "string") return raw.trim() ? raw.trim() : undefined;
+	if (raw && typeof raw === "object" && !Array.isArray(raw)) {
+		const o = raw as Record<string, unknown>;
+		if (typeof o.agent !== "string" || !o.agent.trim()) return undefined;
+		const m: { agent: string; role?: string; model?: string; skills?: string[]; tools?: string[]; isolation?: "none" | "worktree"; mcp?: boolean } = {
+			agent: o.agent.trim(),
+		};
+		if (typeof o.role === "string" && o.role.trim()) m.role = o.role.trim();
+		if (typeof o.model === "string" && o.model.trim()) m.model = o.model.trim();
+		const skills = asStringArray(o.skills);
+		if (skills) m.skills = skills;
+		const tools = asStringArray(o.tools);
+		if (tools) m.tools = tools;
+		if (o.isolation === "worktree" || o.isolation === "none") m.isolation = o.isolation;
+		const mcp = asBoolean(o.mcp);
+		if (mcp !== undefined) m.mcp = mcp;
+		return m;
+	}
+	return undefined;
+}
+
+export function parseTeams(yaml: string): Record<string, RosterMember[]> {
+	const raw = parseYamlSubset(yaml);
+	const teams: Record<string, RosterMember[]> = {};
+	for (const [name, value] of Object.entries(raw)) {
+		const items: unknown[] = Array.isArray(value) ? value : typeof value === "string" ? value.split(",") : [];
+		const members = items.map(toMember).filter((m): m is RosterMember => m !== undefined);
+		if (members.length > 0) teams[name] = members;
+	}
+	return teams;
+}
+
+export function makeRoster(teams: Record<string, RosterMember[]>): Roster {
+	return { team: (name: string) => teams[name] ?? [] };
+}