pi-ultracode 0.1.0

package/src/mode.ts

@@ -0,0 +1,196 @@
+/**
+ * Ultracode mode controller.
+ *
+ * Ultracode is a session-scoped effort mode. While on, it:
+ *   - raises the thinking level to xhigh (remembering the previous level),
+ *   - keeps the `workflow` tool active,
+ *   - injects a standing "author and run a workflow by default" system block on
+ *     every turn, plus an optional token budget,
+ *   - persists its on/off + budget state in session custom entries so it survives
+ *     reload, resume, fork, and compaction.
+ */
+
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { ULTRACODE_ACTIVE_REMINDER, ULTRACODE_TAGLINE, ultracodeSystemBlock } from "./prompts.ts";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+export const MODE_ENTRY_TYPE = "ultracode-mode";
+
+interface PersistedModeState {
+  enabled: boolean;
+  budgetTotal: number | null;
+  previousThinking?: ThinkingLevel;
+}
+
+export class UltracodeMode {
+  private enabled = false;
+  private budgetTotal: number | null = null;
+  private previousThinking: ThinkingLevel | undefined;
+  /** The level pi actually applied after clamping "xhigh" to the model's capability. */
+  private appliedThinking: ThinkingLevel | undefined;
+  private readonly workflowToolName: string;
+
+  constructor(workflowToolName: string) {
+    this.workflowToolName = workflowToolName;
+  }
+
+  /** Enable if off, disable if on. Returns the new enabled state. */
+  toggle(pi: ExtensionAPI, opts: { budget?: number | null } = {}): boolean {
+    if (this.enabled) {
+      this.disable(pi);
+      return false;
+    }
+    this.enable(pi, opts);
+    return true;
+  }
+
+  /** The thinking level pi actually applied (xhigh, or clamped down for models that lack it). */
+  getAppliedThinking(): ThinkingLevel | undefined {
+    return this.appliedThinking;
+  }
+
+  /** The effort level to forward to workflow subagents: xhigh when ultracode is
+   *  on, so each subagent's own session clamps it to THAT subagent model's max
+   *  (mirroring the parent's "request xhigh, clamp per model" contract). This
+   *  keeps subagents at their respective model's max even when they run a
+   *  different model than the parent. Undefined when off, so subagents fall back
+   *  to the session default. */
+  getSubagentThinkingLevel(): ThinkingLevel | undefined {
+    return this.enabled ? "xhigh" : undefined;
+  }
+
+  isEnabled(): boolean {
+    return this.enabled;
+  }
+
+  getBudget(): number | null {
+    return this.budgetTotal;
+  }
+
+  tagline(): string {
+    return ULTRACODE_TAGLINE;
+  }
+
+  /** Turn ultracode on. Idempotent. */
+  enable(pi: ExtensionAPI, opts: { budget?: number | null } = {}): void {
+    if (opts.budget !== undefined) this.budgetTotal = opts.budget;
+    if (!this.enabled) {
+      this.previousThinking = safeGetThinking(pi);
+      this.enabled = true;
+    }
+    this.applyThinking(pi, "xhigh");
+    this.activateWorkflowTool(pi);
+    this.persist(pi);
+  }
+
+  /** Turn ultracode off, restoring the previous thinking level. */
+  disable(pi: ExtensionAPI): void {
+    if (this.enabled && this.previousThinking) this.applyThinking(pi, this.previousThinking);
+    this.enabled = false;
+    this.persist(pi);
+  }
+
+  setBudget(pi: ExtensionAPI, budget: number | null): void {
+    this.budgetTotal = budget;
+    this.persist(pi);
+  }
+
+  /** Restore mode state from session entries (called on session_start). */
+  restore(pi: ExtensionAPI, entries: Array<{ type?: string; customType?: string; data?: unknown }>): void {
+    let latest: PersistedModeState | undefined;
+    for (const entry of entries) {
+      if (entry.type === "custom" && entry.customType === MODE_ENTRY_TYPE && entry.data) {
+        latest = entry.data as PersistedModeState;
+      }
+    }
+    if (!latest) return;
+    this.budgetTotal = latest.budgetTotal ?? null;
+    this.previousThinking = latest.previousThinking;
+    if (latest.enabled) {
+      this.enabled = true;
+      this.applyThinking(pi, "xhigh");
+      this.activateWorkflowTool(pi);
+    }
+  }
+
+  /**
+   * Build the before_agent_start result: appends the ultracode system block to the
+   * turn's system prompt when enabled.
+   */
+  beforeAgentStart(event: { systemPrompt: string }): { systemPrompt: string } | undefined {
+    if (!this.enabled) return undefined;
+    const block = ultracodeSystemBlock({ budgetTotal: this.budgetTotal });
+    return { systemPrompt: `${event.systemPrompt}\n\n${block}\n\n${ULTRACODE_ACTIVE_REMINDER}` };
+  }
+
+  statusLine(): string {
+    if (!this.enabled) return `ultracode: off`;
+    const parts = ["ultracode: on"];
+    // Show the level that actually applied (xhigh, or whatever the model clamped to).
+    if (this.appliedThinking) parts.push(`thinking ${this.appliedThinking}`);
+    if (this.budgetTotal) parts.push(`budget ~${formatTokens(this.budgetTotal)}`);
+    return parts.join(" · ");
+  }
+
+  private applyThinking(pi: ExtensionAPI, level: ThinkingLevel): void {
+    try {
+      // pi clamps the requested level down to the model's capability (e.g. "high",
+      // or "off" for non-reasoning models); it never throws. Read back what stuck.
+      pi.setThinkingLevel(level);
+      this.appliedThinking = safeGetThinking(pi) ?? level;
+    } catch {
+      this.appliedThinking = safeGetThinking(pi);
+    }
+  }
+
+  private activateWorkflowTool(pi: ExtensionAPI): void {
+    try {
+      const active = pi.getActiveTools();
+      if (!active.includes(this.workflowToolName)) {
+        pi.setActiveTools([...active, this.workflowToolName]);
+      }
+    } catch {
+      // ignore
+    }
+  }
+
+  private persist(pi: ExtensionAPI): void {
+    const state: PersistedModeState = {
+      enabled: this.enabled,
+      budgetTotal: this.budgetTotal,
+      previousThinking: this.previousThinking,
+    };
+    try {
+      pi.appendEntry(MODE_ENTRY_TYPE, state);
+    } catch {
+      // ignore persistence failures
+    }
+  }
+}
+
+function safeGetThinking(pi: ExtensionAPI): ThinkingLevel | undefined {
+  try {
+    return pi.getThinkingLevel() as ThinkingLevel;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`;
+  if (n >= 1_000) return `${Math.round(n / 1_000)}k`;
+  return String(n);
+}
+
+/** Parse a budget token like "500k", "1m", "250000", "+500k". */
+export function parseBudget(input: string): number | null {
+  const match = input.trim().match(/^\+?\s*([0-9][0-9_.]*)\s*([kmKM])?$/);
+  if (!match) return null;
+  const value = Number(match[1].replace(/_/g, ""));
+  if (!Number.isFinite(value)) return null;
+  const unit = match[2]?.toLowerCase();
+  if (unit === "k") return Math.round(value * 1_000);
+  if (unit === "m") return Math.round(value * 1_000_000);
+  return Math.round(value);
+}

package/src/prompts.ts

@@ -0,0 +1,83 @@
+/**
+ * Prompt text for ultracode mode.
+ *
+ * These strings reproduce the behavioural contract of Claude Code's "ultracode"
+ * effort level: a standing opt-in to deterministic multi-agent workflow
+ * orchestration, biased toward the most exhaustive, correct answer.
+ */
+
+/** One-line description shown by `/ultracode status` and the footer. */
+export const ULTRACODE_TAGLINE = "xhigh thinking + dynamic workflow orchestration";
+
+/**
+ * The standing system-prompt block injected on every turn while ultracode is on.
+ * Mirrors the "Ultracode" section of the Workflow tool contract.
+ */
+export function ultracodeSystemBlock(opts: { budgetTotal: number | null }): string {
+  const budgetLine =
+    opts.budgetTotal != null
+      ? `\n- Token budget for this session: ~${formatTokens(opts.budgetTotal)} output tokens. Treat it as a hard ceiling — scale workflow depth (fleet size, verification rounds) to fit it, and stop spawning agents as it runs out.`
+      : "";
+
+  return [
+    "<ultracode>",
+    "Ultracode is ON. This opt-in is standing: author and run a workflow for every substantive task by default.",
+    "",
+    "The goal is the most exhaustive, correct answer you can produce — token cost is not a constraint.",
+    "For multi-phase work (understand → design → implement → review), run several workflows in sequence — one per phase — so you stay in the loop between them, reading each result before deciding the next phase.",
+    "",
+    "Lean toward orchestrating with the workflow tool and adversarially verifying your findings, unless the work is trivial or already verified. Solo (no workflow) only on conversational turns or trivial mechanical edits.",
+    "",
+    "Quality patterns to compose as the task calls for it:",
+    "- Adversarial verify: spawn N independent skeptics per finding, each prompted to REFUTE it; kill the finding if a majority refute. Stops plausible-but-wrong findings from surviving.",
+    "- Perspective-diverse verify: when a finding can fail in more than one way, give each verifier a distinct lens (correctness, security, performance, does-it-reproduce) instead of N identical refuters.",
+    "- Multi-modal sweep: parallel agents each searching a different way (by-container, by-content, by-entity, by-time); each is blind to what the others surface.",
+    "- Loop-until-dry: for unknown-size discovery (bugs, edge cases), keep spawning finders until K consecutive rounds return nothing new.",
+    "- Completeness critic: a final agent that asks \"what's missing — a modality not run, a claim unverified, a source unread?\" What it finds becomes the next round of work.",
+    "- No silent caps: if a workflow bounds coverage (top-N, no-retry, sampling), log() what was dropped.",
+    "",
+    "Scale to the task: \"find any bugs\" → a few finders, single-vote verify; \"thoroughly audit\" / \"be comprehensive\" → larger finder pool, 3–5 vote adversarial pass, a synthesis stage." +
+      budgetLine,
+    "</ultracode>",
+  ].join("\n");
+}
+
+/** Short reminder appended to confirm the mode is active (system-reminder style). */
+export const ULTRACODE_ACTIVE_REMINDER =
+  "Reminder: ultracode is on — default to authoring and running a workflow for substantive tasks, and adversarially verify your findings.";
+
+/** Tool description for the `workflow` tool. */
+export const WORKFLOW_TOOL_DESCRIPTION = [
+  "Execute a deterministic JavaScript workflow that orchestrates multiple subagents to be comprehensive (decompose and cover in parallel), confident (independent perspectives and adversarial checks before committing), or to take on scale one context can't hold (migrations, audits, broad sweeps).",
+  "`script` is required raw JavaScript. It must begin with `export const meta = { name, description }` (a pure literal) and must call agent() at least once.",
+  "Available globals: agent(prompt, opts), parallel(thunks), pipeline(items, ...stages), phase(title), log(message), workflow(nameOrRef, args), args, cwd, budget.",
+].join(" ");
+
+/** One-line snippet for the Available tools section. */
+export const WORKFLOW_PROMPT_SNIPPET =
+  "Run a deterministic JS workflow that fans out subagents. Header: export const meta = { name: 'snake_case', description: '...' }. Globals: agent/parallel/pipeline/phase/log/workflow/args/budget.";
+
+/** Guideline bullets appended to the Guidelines section when the tool is active. */
+export const WORKFLOW_GUIDELINES: string[] = [
+  "Use the workflow tool to decompose-and-cover in parallel, to gather independent perspectives that adversarially verify each other, or to take on scale a single context can't hold. Outside ultracode mode, reserve it for explicit fan-out / multi-agent requests.",
+  "For the workflow tool, pass one raw JavaScript string in the required `script` parameter; no Markdown fences, no prose around the script.",
+  "For the workflow tool, the script's first statement must be `export const meta = { name: 'short_snake_case', description: 'non-empty human description' }`. meta must be a pure literal: no variables, function calls, spreads, or template interpolation. meta.phases is optional and should mirror your phase() titles.",
+  "For the workflow tool, write plain JavaScript after the meta export. No TypeScript syntax, imports, require(), fs, network, Date.now(), Math.random(), or new Date() (they break determinism and resume). Stamp timestamps after the workflow returns; vary randomness by agent index.",
+  "For the workflow tool, every workflow must call agent() at least once. Each agent() call should pass a short unique label (2-5 words) so live status and error reporting stay readable.",
+  "For the workflow tool, DEFAULT TO pipeline(items, ...stages): items flow through stages independently with no barrier, so item A can be in stage 3 while item B is still in stage 1. Only use parallel() (a barrier that awaits all thunks) when a later stage genuinely needs ALL prior results together (dedup/merge across the full set, early-exit on zero, cross-item comparison).",
+  "For the workflow tool, parallel() takes functions, not promises: `await parallel(items.map(item => () => agent('...', { label: '...' })))`, never `await parallel(items.map(item => agent(...)))`. Results are returned in input order; a thunk that throws resolves to null, so .filter(Boolean) before using results.",
+  "For the workflow tool, pipeline(items, ...stages) passes each stage (previousValue, originalItem, index). A stage that throws drops that item to null and skips its remaining stages.",
+  "For the workflow tool, if agent() needs machine-readable output pass a plain JSON Schema via opts.schema; agent() then returns the validated object. Use JSON Schema, not TypeScript or TypeBox constructors.",
+  "For the workflow tool, when agent() is called WITHOUT a schema, its return value is the subagent's final assistant text (the last text the subagent produced). With a schema it returns the validated structured_output object. Prefer a schema for machine-readable results; use the text form only for prose summaries.",
+  "For the workflow tool, agent opts also accept: model (override the subagent model by pattern), agentType (use a custom subagent role/system-prompt), isolation:'worktree' (run the agent in an isolated git worktree — use ONLY when agents mutate files in parallel and would conflict), and phase (assign the agent to a progress group explicitly inside parallel()/pipeline()).",
+  "For the workflow tool, use budget for dynamic depth: `while (budget.total && budget.remaining() > 50000) { ... }`. Guard the loop on budget.total — with no budget set, remaining() is Infinity and the loop runs to the agent cap.",
+  "For the workflow tool, workflow(nameOrRef, args) runs a saved workflow (by name) or a scriptPath inline as a sub-step, sharing this run's concurrency cap, agent counter, and token budget. Nesting is one level only.",
+  "For the workflow tool, failed agent()/parallel()/pipeline() branches return null and log the failure (unless the whole run is aborted). Check for nulls before synthesizing conclusions, and prefer a final synthesis/assertion agent that returns a compact JSON-serializable verdict.",
+  "For the workflow tool, do not assume subagents share the parent's repository context; include enough task context and relevant file paths in each agent prompt.",
+];
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(n % 1_000_000 === 0 ? 0 : 1)}M`;
+  if (n >= 1_000) return `${Math.round(n / 1_000)}k`;
+  return String(n);
+}

package/src/workflow/agent-runner.ts

@@ -0,0 +1,329 @@
+/**
+ * In-memory subagent runner.
+ *
+ * Each agent() call in a workflow spins up a fresh in-memory Pi session with the
+ * standard coding tools (and a terminating structured_output tool when a schema
+ * is given), runs one prompt to completion, and returns the result plus token usage.
+ *
+ * Supports per-call model overrides, custom agent types (role system-prompt + tool
+ * allowlist), and an alternate cwd for git-worktree isolation.
+ */
+
+import {
+  createAgentSession,
+  createCodingTools,
+  getAgentDir,
+  SessionManager,
+  SettingsManager,
+  type ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import type { AssistantMessage, TextContent } from "@earendil-works/pi-ai";
+import type { Static, TSchema } from "typebox";
+import { createStructuredOutputTool, type StructuredOutputCapture } from "./structured-output.ts";
+import { jsonSchemaToTypeBox } from "./json-schema.ts";
+import type { AgentTypeDef } from "./agent-types.ts";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+
+/** A minimal structural view of a Pi model (avoids importing the heavy generic type). */
+export interface ModelLike {
+  provider: string;
+  id: string;
+  name?: string;
+}
+
+export interface ModelRegistryLike {
+  getAvailable(): ModelLike[];
+  getAll?(): ModelLike[];
+}
+
+export interface AgentUsage {
+  outputTokens: number;
+  totalTokens: number;
+  cost: number;
+}
+
+export interface AgentRunResult {
+  value: unknown;
+  usage: AgentUsage;
+  /** cwd the agent actually ran in (differs from the shared cwd under worktree isolation). */
+  cwd: string;
+}
+
+export interface WorkflowAgentRunnerOptions {
+  cwd: string;
+  modelRegistry?: ModelRegistryLike;
+  /** Default model used when an agent() call does not override it. */
+  model?: ModelLike;
+  /** Default thinking level for subagents. */
+  thinkingLevel?: ThinkingLevel;
+}
+
+/** Normalized activity signal forwarded from inside a running subagent. */
+export interface AgentActivityInput {
+  kind: "text" | "thinking" | "tool";
+  detail?: string;
+}
+
+export interface AgentRunCall {
+  prompt: string;
+  label: string;
+  schema?: unknown;
+  instructions?: string;
+  signal?: AbortSignal;
+  /** Resolved model pattern (e.g. "sonnet" or "anthropic/...:high"). */
+  modelPattern?: string;
+  agentTypeDef?: AgentTypeDef;
+  /** Override cwd (worktree). */
+  cwd?: string;
+  /** Live activity stream from the subagent (text deltas / tool calls). */
+  onActivity?: (event: AgentActivityInput) => void;
+}
+
+export class WorkflowAgentRunner {
+  private readonly baseCwd: string;
+  private readonly modelRegistry?: ModelRegistryLike;
+  private readonly defaultModel?: ModelLike;
+  private readonly defaultThinking?: ThinkingLevel;
+
+  constructor(options: WorkflowAgentRunnerOptions) {
+    this.baseCwd = options.cwd;
+    this.modelRegistry = options.modelRegistry;
+    this.defaultModel = options.model;
+    this.defaultThinking = options.thinkingLevel;
+  }
+
+  async run(call: AgentRunCall): Promise<AgentRunResult> {
+    if (call.signal?.aborted) throw new Error("Subagent was aborted");
+
+    const cwd = call.cwd ?? this.baseCwd;
+    const capture: StructuredOutputCapture<any> = { called: false, value: undefined };
+
+    const customTools: ToolDefinition[] = [...createCodingTools(cwd)];
+    let toolAllowlist: string[] | undefined = call.agentTypeDef?.tools
+      ? [...call.agentTypeDef.tools]
+      : undefined;
+
+    let schemaTSchema: TSchema | undefined;
+    if (call.schema) {
+      schemaTSchema = jsonSchemaToTypeBox(call.schema);
+      customTools.push(
+        createStructuredOutputTool({ schema: schemaTSchema, capture }) as unknown as ToolDefinition,
+      );
+      if (toolAllowlist) toolAllowlist.push("structured_output");
+    }
+
+    const { model, thinkingLevel } = this.resolveModel(call.modelPattern, call.agentTypeDef);
+
+    const agentDir = getAgentDir();
+    const { session } = await createAgentSession({
+      cwd,
+      agentDir,
+      sessionManager: SessionManager.inMemory(cwd),
+      settingsManager: SettingsManager.create(cwd, agentDir),
+      customTools,
+      ...(model ? { model: model as any } : {}),
+      ...(thinkingLevel ? { thinkingLevel } : {}),
+      ...(toolAllowlist ? { tools: toolAllowlist } : {}),
+      ...(this.modelRegistry ? { modelRegistry: this.modelRegistry as any } : {}),
+    });
+
+    let removeAbort: (() => void) | undefined;
+    let unsubscribe: (() => void) | undefined;
+    try {
+      if (call.signal) {
+        const onAbort = () => void session.abort();
+        call.signal.addEventListener("abort", onAbort, { once: true });
+        removeAbort = () => call.signal?.removeEventListener("abort", onAbort);
+      }
+
+      // Forward live activity (text deltas / tool calls) so the workflow
+      // snapshot can show per-agent progress and detect stuck subagents.
+      if (call.onActivity) {
+        const onActivity = call.onActivity;
+        unsubscribe = session.subscribe((event) => forwardActivity(event, onActivity));
+      }
+
+      await session.prompt(this.buildPrompt(call, Boolean(call.schema)));
+      if (call.signal?.aborted) throw new Error("Subagent was aborted");
+
+      let value: unknown;
+      if (call.schema) {
+        if (!capture.called) throw new Error("Subagent finished without calling structured_output");
+        value = capture.value;
+      } else {
+        value = lastAssistantText(session.messages as unknown[]);
+      }
+
+      return { value, usage: readUsage(session), cwd };
+    } finally {
+      removeAbort?.();
+      unsubscribe?.();
+      session.dispose();
+    }
+  }
+
+  private buildPrompt(call: AgentRunCall, structured: boolean): string {
+    const role = call.agentTypeDef;
+    const parts: Array<string | undefined> = [];
+    if (role?.systemPrompt) {
+      const header = role.systemPromptMode === "replace" ? `Role (operate strictly as):` : `Role:`;
+      parts.push(`${header}\n${role.systemPrompt}`);
+    }
+    parts.push(call.instructions);
+    parts.push(call.label ? `Task label: ${call.label}` : undefined);
+    parts.push(call.prompt);
+    if (structured) {
+      parts.push(
+        [
+          "Final output contract:",
+          "- Your final action MUST be a structured_output tool call.",
+          "- The structured_output arguments are the return value of this subagent.",
+          "- Do not emit a prose final answer instead of structured_output.",
+        ].join("\n"),
+      );
+    }
+    return parts.filter(Boolean).join("\n\n");
+  }
+
+  private resolveModel(
+    pattern: string | undefined,
+    role: AgentTypeDef | undefined,
+  ): { model?: ModelLike; thinkingLevel?: ThinkingLevel } {
+    return resolveModelSelection({
+      pattern,
+      roleModel: role?.model,
+      roleThinking: role?.thinking,
+      defaultModel: this.defaultModel,
+      defaultThinking: this.defaultThinking,
+      models: this.modelRegistry?.getAvailable(),
+    });
+  }
+}
+
+const THINKING_LEVELS = new Set<ThinkingLevel>(["off", "minimal", "low", "medium", "high", "xhigh"]);
+
+export function splitThinkingSuffix(pattern: string): { base: string; thinking?: ThinkingLevel } {
+  const idx = pattern.lastIndexOf(":");
+  if (idx === -1) return { base: pattern };
+  const raw = pattern.slice(idx + 1).trim();
+  const suffix = raw as ThinkingLevel;
+  if (THINKING_LEVELS.has(suffix)) return { base: pattern.slice(0, idx).trim(), thinking: suffix };
+  // Trailing colon with no/invalid suffix (e.g. "sonnet:"): strip it so the base
+  // is still matchable instead of silently falling back to the default model.
+  if (raw === "") return { base: pattern.slice(0, idx).trim() };
+  return { base: pattern };
+}
+
+/** Match a model pattern against a registry list: exact provider/id, then exact id, then substring. */
+export function matchModelIn(models: ModelLike[] | undefined, pattern: string): ModelLike | undefined {
+  if (!models) return undefined;
+  // An empty pattern must never match: "any-id".includes("") === true would
+  // otherwise silently return the FIRST registered model.
+  if (!pattern.trim()) return undefined;
+  const lower = pattern.trim().toLowerCase();
+  const slash = lower.includes("/");
+  // 1. exact provider/id, 2. exact id, 3. substring on id / provider/id / name.
+  return (
+    models.find((m) => `${m.provider}/${m.id}`.toLowerCase() === lower) ??
+    models.find((m) => m.id.toLowerCase() === lower) ??
+    models.find((m) =>
+      slash
+        ? `${m.provider}/${m.id}`.toLowerCase().includes(lower)
+        : m.id.toLowerCase().includes(lower) || (m.name?.toLowerCase().includes(lower) ?? false),
+    )
+  );
+}
+
+/**
+ * Resolve the model + thinking level for an agent() call.
+ *
+ * `pattern` may carry a thinking suffix like "anthropic/claude:high". A bare
+ * ":high" (empty base) means "keep the default model, only override thinking" —
+ * it must NOT fall through to matching an empty string, which would silently
+ * pick the first registered model (`id.includes("") === true`).
+ */
+export function resolveModelSelection(args: {
+  pattern?: string;
+  roleModel?: string;
+  roleThinking?: ThinkingLevel;
+  defaultModel?: ModelLike;
+  defaultThinking?: ThinkingLevel;
+  models?: ModelLike[];
+}): { model?: ModelLike; thinkingLevel?: ThinkingLevel } {
+  const { pattern, roleModel, roleThinking, defaultModel, defaultThinking, models } = args;
+  const effectivePattern = pattern ?? roleModel;
+  if (!effectivePattern) {
+    return { model: defaultModel, thinkingLevel: roleThinking ?? defaultThinking };
+  }
+  const { base, thinking } = splitThinkingSuffix(effectivePattern);
+  const model = base ? matchModelIn(models, base) ?? defaultModel : defaultModel;
+  return { model, thinkingLevel: thinking ?? roleThinking ?? defaultThinking };
+}
+
+function readUsage(session: any): AgentUsage {
+  try {
+    const stats = session.getSessionStats?.();
+    if (stats?.tokens) {
+      return {
+        outputTokens: stats.tokens.output ?? 0,
+        totalTokens: stats.tokens.total ?? 0,
+        cost: stats.cost ?? 0,
+      };
+    }
+  } catch {
+    // fall through to message-based estimate
+  }
+  // Fallback: sum assistant usage from messages.
+  let output = 0;
+  let total = 0;
+  let cost = 0;
+  for (const message of (session.messages ?? []) as Array<Partial<AssistantMessage>>) {
+    if (message?.role === "assistant" && message.usage) {
+      output += message.usage.output ?? 0;
+      total += message.usage.totalTokens ?? 0;
+      cost += message.usage.cost?.total ?? 0;
+    }
+  }
+  return { outputTokens: output, totalTokens: total, cost };
+}
+
+function lastAssistantText(messages: unknown[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i] as Partial<AssistantMessage> | undefined;
+    if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
+    const text = message.content
+      .filter((part): part is TextContent => (part as TextContent).type === "text")
+      .map((part) => part.text)
+      .join("");
+    if (text.trim()) return text;
+  }
+  return "";
+}
+
+/**
+ * Map a raw AgentSessionEvent into a normalized activity signal and forward it.
+ * Defensive: activity forwarding must never break the subagent run.
+ */
+export function forwardActivity(event: unknown, onActivity: (e: AgentActivityInput) => void): void {
+  try {
+    const e = event as any;
+    if (e?.type === "message_update") {
+      const ame = e.assistantMessageEvent;
+      if (!ame) return;
+      if (ame.type === "text_delta" && typeof ame.delta === "string") {
+        onActivity({ kind: "text", detail: ame.delta });
+      } else if (ame.type === "thinking_delta") {
+        onActivity({ kind: "thinking" });
+      } else if (ame.type === "toolcall_start" && ame.toolName) {
+        onActivity({ kind: "tool", detail: String(ame.toolName) });
+      }
+      return;
+    }
+    if (e?.type === "tool_execution_start" && e.toolName) {
+      onActivity({ kind: "tool", detail: String(e.toolName) });
+    }
+  } catch {
+    // best-effort: never let observability break the run
+  }
+}