@arhen/pi-core-subagent 1.3.65 → 1.3.67

package/src/outcome.ts

@@ -0,0 +1,58 @@
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type { RunSnapshot, TaskSnapshot, UsageStats } from "./types.ts";
+
+export type Failure = { status: "failed" | "aborted"; message: string };
+
+export function emptyUsage(): UsageStats {
+	return { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, cost: 0, turns: 0 };
+}
+
+export function aggregateUsage(tasks: TaskSnapshot[]): UsageStats {
+	const total = emptyUsage();
+	for (const task of tasks) {
+		total.input += task.usage.input;
+		total.output += task.usage.output;
+		total.cacheRead += task.usage.cacheRead;
+		total.cacheWrite += task.usage.cacheWrite;
+		total.cost += task.usage.cost;
+		total.turns += task.usage.turns;
+	}
+	return total;
+}
+
+export function updateUsageFromMessage(task: TaskSnapshot, message: AssistantMessage): void {
+	if (message?.role !== "assistant") return;
+	task.usage.turns += 1;
+	const usage = message.usage;
+	if (!usage) return;
+	task.usage.input += usage.input ?? 0;
+	task.usage.output += usage.output ?? 0;
+	task.usage.cacheRead += usage.cacheRead ?? 0;
+	task.usage.cacheWrite += usage.cacheWrite ?? 0;
+	task.usage.cost += usage.cost?.total ?? 0;
+	if (message.model && !task.model) task.model = message.model;
+}
+
+export function classifyFailure(stopReason: string | undefined, errorMessage?: string): Failure | undefined {
+	if (!stopReason || stopReason === "stop" || stopReason === "end") return undefined;
+	if (stopReason === "aborted") return { status: "aborted", message: errorMessage || "Subagent was aborted." };
+	return { status: "failed", message: errorMessage || `Subagent ended with stopReason "${stopReason}".` };
+}
+
+export function lastAssistantFailure(messages: AssistantMessage[] | undefined): Failure | undefined {
+	for (const message of [...(messages ?? [])].reverse()) {
+		if (message?.role !== "assistant") continue;
+		return classifyFailure(message.stopReason, message.errorMessage);
+	}
+	return undefined;
+}
+
+export function failureError(failure: Failure): Error {
+	const error = new Error(failure.message);
+	(error as Error & { subagentStatus?: string }).subagentStatus = failure.status;
+	return error;
+}
+
+export function cloneRun(run: RunSnapshot): RunSnapshot {
+	return JSON.parse(JSON.stringify(run)) as RunSnapshot;
+}

package/src/presentation.ts

@@ -7,17 +7,18 @@ import type {
 	ToolLoadoutChanges,
 	ToolNamespace,
 } from "@earendil-works/pi-coding-agent";
-
-/**
- * Presentation preference for the subagent toolset.
- * - auto: native codemode presentation when the codemode tool is active, direct otherwise.
- * - direct (default): legacy native declarations and active-tool script callability.
- * - codemode: subagent tools are callable from codemode scripts but not declared or listed.
- */
-export type SubagentMode = "auto" | "direct" | "codemode";
+import {
+	DEFAULT_SUBAGENT_MODE,
+	isSubagentMode,
+	readStoredMode,
+	type SubagentMode,
+	writeSubagentConfig,
+} from "./config.ts";
+
+export { isSubagentMode, type SubagentMode } from "./config.ts";
 export type EffectiveMode = "direct" | "codemode";
 
-/** Branch-scoped custom entry holding the preference, so resume/tree keep it. */
+/** Branch-scoped custom entry holding the legacy preference; the global config file now wins. */
 export const MODE_ENTRY_TYPE = "subagent-mode";
 export const CODEMODE_TOOL_NAME = "codemode";
 
@@ -30,7 +31,7 @@ export const SUBAGENT_NAMESPACE: ToolNamespace = {
 - direct (default): legacy native tool declarations and active-tool script callability; activating codemode alone does not switch profiles.
 - auto (opt-in): codemode presentation while the \`codemode\` tool is active, direct otherwise.
 - codemode: active tools are callable from scripts but not declared; inactive tools stay model-only and are not callable at all.
-Switch with \`/subagents mode auto|direct|codemode\`. The preference is stored on the session branch and restored on reload, resume and tree navigation.
+Switch with \`/subagents mode auto|direct|codemode\`. The preference is stored in the global \`subagents-config.json\` and applies to every session — reload, resume and tree navigation included.
 
 ## Operations
 Object arguments, exactly as validated when issued by the model:
@@ -67,10 +68,6 @@ export const CODEMODE_DISCOVERY_GUIDELINE =
 /** The full-reference pointer only resolves while codemode scripts can reach `describeNamespace`. */
 const NAMESPACE_REFERENCE = / Full reference: `describeNamespace\('subagents'\)`\./;
 
-export function isSubagentMode(value: unknown): value is SubagentMode {
-	return value === "auto" || value === "direct" || value === "codemode";
-}
-
 export type AnyToolDefinition = ToolDefinition<any, any, any>;
 
 export interface Presentation {
@@ -82,7 +79,7 @@ export interface Presentation {
 	/** Report preference, effective mode and codemode availability. */
 	describe(): string;
 	setPreference(mode: SubagentMode): void;
-	/** Restore the latest preference stored on the session branch. */
+	/** Restore the globally stored preference, with the session branch as the legacy fallback. */
 	restore(ctx: ExtensionContext): void;
 	/** Register the tools for the current effective mode; no-op when already applied. */
 	sync(): boolean;
@@ -90,6 +87,17 @@ export interface Presentation {
 	registerInitial(): void;
 }
 
+/** Latest mode stored by an older package version on this session branch, if any. */
+function branchPreference(ctx: ExtensionContext): SubagentMode | undefined {
+	let restored: SubagentMode | undefined;
+	for (const entry of ctx.sessionManager.getBranch()) {
+		const candidate = entry as { type?: string; customType?: string; data?: { mode?: unknown } };
+		if (candidate.type === "custom" && candidate.customType === MODE_ENTRY_TYPE && isSubagentMode(candidate.data?.mode))
+			restored = candidate.data.mode;
+	}
+	return restored;
+}
+
 /**
  * Owns the subagent exposure profile. Tools stay registered while only their exposure changes, so
  * the active selection (and the running manager) is preserved across mode switches.
@@ -169,25 +177,19 @@ export function createPresentation(pi: ExtensionAPI, definitions: readonly AnyTo
 			const availability = available ? "codemode is active" : "codemode is not active";
 			const fallback = !available && preference === "codemode" ? "; using direct fallback" : "";
 			const pending = target !== shown ? `; pending ${target} at the next request boundary` : "";
-			return `Subagent exposure: mode ${preference} → effective ${shown} (${availability}${fallback}${pending}). Use /subagents mode auto|direct|codemode.`;
+			return `Subagent exposure: mode ${preference} → effective ${shown} (${availability}${fallback}${pending}). Saved for all sessions. Use /subagents mode auto|direct|codemode.`;
 		},
 		setPreference(mode) {
 			preference = mode;
+			// The global config file is authoritative for every session; the branch entry stays as a
+			// fallback for sessions that predate it and for readers of older package versions.
+			void writeSubagentConfig({ mode }).catch(() => {});
 			pi.appendEntry(MODE_ENTRY_TYPE, { mode });
 		},
 		restore(ctx) {
-			let restored: SubagentMode | undefined;
-			for (const entry of ctx.sessionManager.getBranch()) {
-				const candidate = entry as { type?: string; customType?: string; data?: { mode?: unknown } };
-				if (
-					candidate.type === "custom" &&
-					candidate.customType === MODE_ENTRY_TYPE &&
-					isSubagentMode(candidate.data?.mode)
-				)
-					restored = candidate.data.mode;
-			}
-			// Branch-sensitive state: a branch without an entry uses the package default again.
-			preference = restored ?? "direct";
+			// Global preference wins over the branch; the branch entry is the legacy fallback for
+			// sessions that chose a mode before the preference moved into the config file.
+			preference = readStoredMode() ?? branchPreference(ctx) ?? DEFAULT_SUBAGENT_MODE;
 		},
 		sync() {
 			const own = new Set(ownNames());

package/src/run-widget.ts

@@ -0,0 +1,122 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { TUI } from "@earendil-works/pi-tui";
+import { isTalking, SubagentsWidget } from "./format.ts";
+import { type RunSnapshot, TERMINAL } from "./types.ts";
+
+const THROTTLE_MS = 150;
+const PULSE_MS = 700;
+
+/**
+ * The live-runs widget above the editor: throttled redraws per run, a pulse while a child is
+ * talking, and settled runs pruned (subagent_status/result still reach them — this shows live work).
+ */
+export class RunWidget {
+	runs: RunSnapshot[] = [];
+	private tui: TUI | null = null;
+	private timers = new Map<string, ReturnType<typeof setTimeout>>();
+	private pulseTimer: ReturnType<typeof setTimeout> | null = null;
+
+	/** Remove the widget from the UI; pending timers keep running and re-create it on demand. */
+	clear(ctx?: ExtensionContext): void {
+		this.runs = [];
+		this.tui = null;
+		if (ctx?.hasUI) {
+			try {
+				ctx.ui.setWidget("subagents", undefined);
+			} catch {}
+		}
+	}
+
+	/** Session end: drop every timer and run without touching the UI. */
+	dispose(): void {
+		this.tui = null;
+		if (this.pulseTimer) {
+			clearTimeout(this.pulseTimer);
+			this.pulseTimer = null;
+		}
+		for (const timer of this.timers.values()) clearTimeout(timer);
+		this.timers.clear();
+		this.runs = [];
+	}
+
+	upsert(run: RunSnapshot | undefined): void {
+		this.prune();
+		if (!run || TERMINAL.includes(run.status)) return;
+		const idx = this.runs.findIndex((r) => r.id === run.id);
+		if (idx >= 0) this.runs[idx] = run;
+		else this.runs.push(run);
+	}
+
+	schedule(run: RunSnapshot | undefined, ctx?: ExtensionContext): void {
+		this.upsert(run);
+		if (!run || this.timers.has(run.id)) return;
+		this.timers.set(
+			run.id,
+			setTimeout(() => {
+				this.timers.delete(run.id);
+				if (ctx?.hasUI) {
+					this.ensure(ctx);
+					this.tui?.requestRender();
+				}
+				this.maybePulse(ctx);
+			}, THROTTLE_MS),
+		);
+	}
+
+	flush(run: RunSnapshot | undefined, ctx?: ExtensionContext, onUpdate?: (partial: any) => void): void {
+		if (run) {
+			const timer = this.timers.get(run.id);
+			if (timer) {
+				clearTimeout(timer);
+				this.timers.delete(run.id);
+			}
+		}
+		this.prune();
+		if (this.runs.length === 0) {
+			if (this.tui) this.clear(ctx);
+		} else {
+			if (ctx?.hasUI) {
+				this.ensure(ctx);
+				this.tui?.requestRender();
+			}
+			this.maybePulse(ctx);
+		}
+		if (!run) return;
+
+		onUpdate?.({
+			content: [
+				{
+					type: "text",
+					text: `${run.tasks.filter((t) => TERMINAL.includes(t.status)).length}/${run.tasks.length} done · ${run.status}`,
+				},
+			],
+		});
+	}
+
+	private prune(): void {
+		this.runs = this.runs.filter((r) => !TERMINAL.includes(r.status));
+	}
+
+	private maybePulse(ctx?: ExtensionContext): void {
+		if (this.pulseTimer || !this.tui) return;
+		const talking = this.runs.some((r) => r.tasks.some(isTalking));
+		if (!talking) return;
+		this.pulseTimer = setTimeout(() => {
+			this.pulseTimer = null;
+			this.tui?.requestRender();
+			this.maybePulse(ctx);
+		}, PULSE_MS);
+	}
+
+	private ensure(ctx: ExtensionContext): void {
+		if (this.tui !== null || !ctx.hasUI) return;
+		ctx.ui.setWidget(
+			"subagents",
+			(tui, theme) => {
+				this.tui = tui;
+				return new SubagentsWidget(() => [...this.runs], theme);
+			},
+			{ placement: "aboveEditor" },
+		);
+	}
+}

package/src/runtime.ts

@@ -0,0 +1,136 @@
+import { join } from "node:path";
+import type { ThinkingLevel } from "@earendil-works/pi-agent-core";
+import { type Api, clampThinkingLevel, getSupportedThinkingLevels, type Model } from "@earendil-works/pi-ai";
+import {
+	type DefaultResourceLoader,
+	type ExtensionContext,
+	getAgentDir,
+	ModelRuntime,
+} from "@earendil-works/pi-coding-agent";
+
+type ChildExtensionFactories = ConstructorParameters<typeof DefaultResourceLoader>[0]["extensionFactories"];
+
+/**
+ * Children run with `noExtensions`, so they get none of the configured extensions — codemode is the
+ * one exception, because it is how a child batches tool calls. `createCodemodeExtension()` is the
+ * supported factory (pi >= 1.0); hosts that do not export it simply give children no codemode.
+ */
+export async function codemodeFactories(): Promise<ChildExtensionFactories> {
+	try {
+		const host = (await import("@earendil-works/pi-coding-agent")) as unknown as {
+			createCodemodeExtension?: () => unknown;
+		};
+		const factory = host.createCodemodeExtension?.();
+		return factory ? ([factory] as ChildExtensionFactories) : [];
+	} catch {
+		return [];
+	}
+}
+
+/**
+ * A resumed task keeps its stored thinking level, clamped to what the target model accepts — a
+ * resume that swaps model must not fail on an effort the new model does not define.
+ */
+export function clampResumeThinking(
+	model: Model<Api> | undefined,
+	thinking: ThinkingLevel | undefined,
+): ThinkingLevel | undefined {
+	if (!thinking || !model) return thinking;
+	return clampThinkingLevel(model, thinking) as ThinkingLevel;
+}
+
+const PROBE_THINKING_LEVELS: ThinkingLevel[] = ["low", "minimal", "medium", "high", "xhigh", "max"];
+
+/**
+ * Thinking level for the usability probe: exactly what the child session will send — the clamped
+ * requested level, or the cheapest the model accepts when none was requested. Probing without a
+ * level makes adaptive-thinking providers reject the request (9router claude models answer
+ * "thinking.type.disabled is not supported"), which used to make every preflight fail and fall
+ * back to the session model.
+ */
+function probeThinking(model: Model<Api>, thinking?: string): ThinkingLevel | undefined {
+	if (!model.reasoning) return undefined;
+	const supported = getSupportedThinkingLevels(model);
+	if (thinking && thinking !== "off") return clampThinkingLevel(model, thinking as ThinkingLevel);
+	// the child clamps an unsupported "off" up to its cheapest level, so probe that instead
+	if (thinking === "off") return supported.includes("off") ? undefined : supported[0];
+	return PROBE_THINKING_LEVELS.find((level) => supported.includes(level));
+}
+
+async function probeModel(
+	ctx: ExtensionContext,
+	model: Model<Api>,
+	signal: AbortSignal | undefined,
+	thinking?: string,
+): Promise<string | undefined> {
+	try {
+		const reasoningEffort = probeThinking(model, thinking);
+		const reply = await ctx.modelRegistry.complete(
+			model,
+			{ messages: [{ role: "user", content: "ping", timestamp: Date.now() }] },
+			{ maxTokens: 16, signal, ...(reasoningEffort ? { reasoningEffort } : {}) },
+		);
+		return reply.stopReason === "error" ? (reply.errorMessage ?? "provider returned an error") : undefined;
+	} catch (err) {
+		return err instanceof Error ? err.message : String(err);
+	}
+}
+
+export async function ensureUsableModel(
+	ctx: ExtensionContext,
+	model: Model<Api> | undefined,
+	signal: AbortSignal | undefined,
+	thinking?: string,
+): Promise<{ model: Model<Api> | undefined; note?: string }> {
+	const session = ctx.model;
+	if (!model || !ctx.modelRegistry) return { model };
+	if (session && model.provider === session.provider && model.id === session.id) return { model };
+	const error = await probeModel(ctx, model, signal, thinking);
+	if (!error) return { model };
+	if (model.provider === "opencode-go" && /MissingSessionID|x-opencode-session/i.test(error)) {
+		// ponytail: opencode-go rejects stateless probes but accepts AgentSession requests, which add the session header.
+		// Upgrade path: remove this exception when modelRegistry.complete can carry AgentSession request transforms.
+		return { model, note: `preflight unavailable (${error}); child session will validate the model` };
+	}
+	if (!session) throw new Error(`Model ${model.provider}/${model.id} is unusable: ${error}`);
+	return {
+		model: session,
+		note: `${model.provider}/${model.id} failed preflight (${error}); using session model ${session.provider}/${session.id}`,
+	};
+}
+
+export async function createChildModelRuntime(ctx: ExtensionContext) {
+	const ids = ctx.modelRegistry.getRegisteredProviderIds?.() ?? [];
+	if (ids.length === 0) return undefined;
+	const agentDir = getAgentDir();
+	const runtime = await ModelRuntime.create({
+		authPath: join(agentDir, "auth.json"),
+		modelsPath: join(agentDir, "models.json"),
+	});
+	for (const id of ids) {
+		const native = ctx.modelRegistry.getRegisteredNativeProvider?.(id);
+		if (native) {
+			runtime.registerNativeProvider(native);
+			continue;
+		}
+		const config = ctx.modelRegistry.getRegisteredProviderConfig?.(id);
+		if (config) runtime.registerProvider(id, config);
+	}
+	await runtime.refresh({ allowNetwork: false });
+	return runtime;
+}
+
+export function validateThinking(model: Model<Api> | undefined, level: string | undefined): void {
+	if (!level || level === "off") return;
+	if (!model) return;
+	const map = model.thinkingLevelMap;
+	if (map && level in map && map[level as keyof typeof map] === null) {
+		const supported = Object.keys(map).filter((k) => map[k as keyof typeof map] !== null);
+		throw new Error(
+			`Thinking level "${level}" is not supported by ${model.provider}/${model.id}. Supported: ${supported.length ? supported.join(" | ") : 'none — use thinking: "off"'}.`,
+		);
+	}
+	if (!model.reasoning) {
+		throw new Error(`Model ${model.provider}/${model.id} does not support thinking. Use thinking: "off".`);
+	}
+}

package/src/types.ts

@@ -133,3 +133,12 @@ export interface ModelCatalog {
 	/** Set when the catalog is empty, so the caller knows it is not looking at a legitimate empty list. */
 	unavailable?: string;
 }
+
+/** A child message collected by a parked `await` instead of being sent to the leader. */
+export interface ParkedMsg {
+	kind: "ask" | "notify" | "done";
+	taskId: string;
+	agent: string;
+	text: string;
+	final?: boolean;
+}