codecartographer-pi 0.1.4 → 0.6.0

package/.codecarto/workflow/config.yaml

@@ -0,0 +1,13 @@
+# CodeCartographer workspace-level orchestrator configuration. Optional.
+# Missing keys fall back to defaults defined in core/orchestrator-config.ts.
+
+orchestrator:
+  # When true, /codecarto-next runs the orchestrator's LLM as a one-shot
+  # rewriter: it reads the previous phase's closeout + the next phase's
+  # template and produces a customized seed prompt for the sub-agent.
+  # Adds orchestrator-side tokens; off by default.
+  #
+  # Per-invocation overrides:
+  #   /codecarto-next --llm-steer       -> force on for this run
+  #   /codecarto-next --no-llm-steer    -> force off for this run
+  llm_steer_next_phase: false

package/README.md

@@ -84,16 +84,19 @@ What the Pi extension adds:
 - tool interception that blocks `edit` and `write` outside `.codecarto/`
 - direct phase prompts that tell Pi exactly which `.codecarto/findings/<phase>/SKILL.md` file to read, without registering those internal files as global Pi skills
 
-### Orchestrator / phase sub-agent mode
+### Phase sub-agents (0.2.0+)
 
-When `/codecarto-init` runs from the Pi extension (0.1.3+), the current Pi session is recorded as the **orchestrator** for that workspace. Each subsequent `/codecarto-next`:
+`/codecarto-next` runs each phase as an isolated in-memory `AgentSession` while your TUI stays on the orchestrator session. The phase's tool calls, file reads, and reasoning live in the child's own context window — they never accumulate in the orchestrator. A persistent **Agents** widget appears above the editor while a phase is running, showing live tool count, token usage, elapsed time, and the current activity. The widget auto-clears once the phase finishes (and lingers a few seconds after for visibility).
 
-- **Run from the orchestrator** — spawns a child Pi session pre-seeded with the phase prompt. The TUI switches to the child; phase tool calls and reasoning land in the child's context window, leaving the orchestrator clean.
-- **Run from inside a phase child** — switches the TUI back to the orchestrator and chains the next phase as another child, atomically.
+```
+● CodeCartographer
+└─ ⠹ architecture phase  ⟳3 · 5 tool uses · 12.3k tokens · 1m32s
+   ⎿ reading…
+```
 
-The orchestrator pointer is stored in `.codecarto/workflow/.orchestrator.local.yaml` (gitignored — the file holds an absolute path into the user's Pi session storage, which is machine-local). Workspaces created by 0.1.0 – 0.1.2 don't have this file; the extension falls back to in-place phase prompts (the legacy behavior). Re-run `/codecarto-init` to opt in.
+Versions 0.1.3 – 0.1.4 used a different design — a session-switching pattern via `ctx.newSession()` that flipped the TUI to the child. That delivered context isolation but the switch was visually invisible during normal flow, so 0.2.0 replaced it with the parallel-widget approach. 0.1.x workspaces don't need migration; existing `.codecarto/` directories work with 0.2.0 unchanged.
 
-The MCP-server path is unaffected — it has no session concept; the host (Claude Desktop / Claude Code / etc.) is the orchestrator.
+The MCP-server path is unaffected — it has no session concept; the host (Claude Desktop / Claude Code / etc.) is always the orchestrator.
 
 ## MCP Server
 

package/dist/core/index.d.ts

@@ -5,4 +5,5 @@ export * from "./status.ts";
 export * from "./pipeline.ts";
 export * from "./prompts.ts";
 export * from "./workspace.ts";
-export * from "./orchestrator.ts";
+export * from "./orchestrator-config.ts";
+export * from "./usage.ts";

package/dist/core/index.js

@@ -8,4 +8,5 @@ export * from "./status.js";
 export * from "./pipeline.js";
 export * from "./prompts.js";
 export * from "./workspace.js";
-export * from "./orchestrator.js";
+export * from "./orchestrator-config.js";
+export * from "./usage.js";

package/dist/core/orchestrator-config.d.ts

@@ -0,0 +1,20 @@
+import type { PathLike } from "node:fs";
+export interface OrchestratorConfig {
+    /** When true, /codecarto-next runs an LLM rewriter to produce a seed prompt
+     *  customized to the previous phase's closeout + the next phase's template
+     *  before spawning the sub-agent. Off by default — extra orchestrator-side
+     *  tokens, opt-in. */
+    llm_steer_next_phase: boolean;
+}
+export interface CodecartoConfig {
+    orchestrator: OrchestratorConfig;
+}
+export declare const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
+type RawConfig = {
+    orchestrator?: Partial<{
+        llm_steer_next_phase: unknown;
+    }>;
+};
+export declare function loadCodecartoConfig(workspaceDir: PathLike): Promise<CodecartoConfig>;
+export declare function mergeConfig(raw: RawConfig | null | undefined): CodecartoConfig;
+export {};

package/dist/core/orchestrator-config.js

@@ -0,0 +1,45 @@
+// Workspace-level orchestrator configuration. Lives at
+// `.codecarto/workflow/config.yaml`. Missing file or missing keys fall back
+// to defaults, so existing workspaces created before this file existed
+// keep working unchanged. Schema is intentionally narrow — one surface
+// per feature, easy to grow.
+import { join } from "node:path";
+import { pathExists } from "./utils.js";
+import { loadYamlFile } from "./yaml.js";
+export const CONFIG_RELATIVE_PATH = "workflow/config.yaml";
+const DEFAULT_CONFIG = {
+    orchestrator: {
+        llm_steer_next_phase: false,
+    },
+};
+export async function loadCodecartoConfig(workspaceDir) {
+    const configPath = join(workspaceDir, CONFIG_RELATIVE_PATH);
+    if (!(await pathExists(configPath)))
+        return cloneDefault();
+    try {
+        const raw = await loadYamlFile(configPath);
+        return mergeConfig(raw);
+    }
+    catch {
+        // Malformed YAML: fall back to defaults rather than failing the
+        // command. The user can fix it; a broken config shouldn't block work.
+        return cloneDefault();
+    }
+}
+export function mergeConfig(raw) {
+    const merged = cloneDefault();
+    if (!raw || typeof raw !== "object")
+        return merged;
+    const o = raw.orchestrator;
+    if (o && typeof o === "object") {
+        if (typeof o.llm_steer_next_phase === "boolean") {
+            merged.orchestrator.llm_steer_next_phase = o.llm_steer_next_phase;
+        }
+    }
+    return merged;
+}
+function cloneDefault() {
+    return {
+        orchestrator: { ...DEFAULT_CONFIG.orchestrator },
+    };
+}

package/dist/core/usage.d.ts

@@ -0,0 +1,31 @@
+export declare const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
+export type UsageRunStatus = "completed" | "aborted" | "error";
+export interface UsageTokens {
+    input: number;
+    output: number;
+    cache_write: number;
+}
+export interface UsageRun {
+    timestamp: string;
+    phase: string;
+    status: UsageRunStatus;
+    turn_count: number;
+    tool_uses: number;
+    duration_ms: number;
+    tokens: UsageTokens;
+    session_file?: string;
+}
+export interface UsageFile {
+    version: number;
+    runs: UsageRun[];
+}
+export interface UsageTotals {
+    runs: number;
+    tokens: UsageTokens;
+    tool_uses: number;
+    duration_ms: number;
+}
+export declare function loadUsage(workspaceDir: string): Promise<UsageFile>;
+export declare function appendUsageRun(workspaceDir: string, run: UsageRun): Promise<void>;
+export declare function computeTotals(file: UsageFile): UsageTotals;
+export declare function computePerPhaseTotals(file: UsageFile): Map<string, UsageTotals>;

package/dist/core/usage.js

@@ -0,0 +1,94 @@
+// Local-only phase usage log. Lives at
+// `.codecarto/workflow/.usage.local.yaml` (gitignored). Append-only —
+// each finished phase sub-agent contributes one entry. Totals are computed
+// on read so the file never holds a number that contradicts the runs.
+//
+// Concurrency: /codecarto-next rejects re-entry on a phase that's already
+// running, and phases run sequentially against this file, so a plain
+// read-modify-write is safe enough. If parallel-phase dispatch ever ships,
+// switch this to atomic-rename (see core/workspace.ts for the pattern).
+import { readFile, rename, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { pathExists } from "./utils.js";
+import { parseSimpleYaml, stringifySimpleYaml } from "./yaml.js";
+export const USAGE_RELATIVE_PATH = "workflow/.usage.local.yaml";
+const SCHEMA_VERSION = 1;
+export async function loadUsage(workspaceDir) {
+    const path = join(workspaceDir, USAGE_RELATIVE_PATH);
+    if (!(await pathExists(path)))
+        return emptyUsage();
+    try {
+        const raw = await readFile(path, "utf8");
+        const parsed = parseSimpleYaml(raw);
+        return normalize(parsed);
+    }
+    catch {
+        // Malformed file: treat as empty rather than blocking the user. They
+        // can fix or delete the file; corrupt local state shouldn't stop work.
+        return emptyUsage();
+    }
+}
+export async function appendUsageRun(workspaceDir, run) {
+    const current = await loadUsage(workspaceDir);
+    current.runs.push(run);
+    const path = join(workspaceDir, USAGE_RELATIVE_PATH);
+    const tempPath = `${path}.${process.pid}.${Date.now()}.tmp`;
+    const serialized = `${stringifySimpleYaml(current)}\n`;
+    await writeFile(tempPath, serialized, "utf8");
+    await rename(tempPath, path);
+}
+export function computeTotals(file) {
+    const totals = {
+        runs: file.runs.length,
+        tokens: { input: 0, output: 0, cache_write: 0 },
+        tool_uses: 0,
+        duration_ms: 0,
+    };
+    for (const r of file.runs) {
+        totals.tokens.input += r.tokens?.input ?? 0;
+        totals.tokens.output += r.tokens?.output ?? 0;
+        totals.tokens.cache_write += r.tokens?.cache_write ?? 0;
+        totals.tool_uses += r.tool_uses ?? 0;
+        totals.duration_ms += r.duration_ms ?? 0;
+    }
+    return totals;
+}
+export function computePerPhaseTotals(file) {
+    const byPhase = new Map();
+    for (const r of file.runs) {
+        const t = byPhase.get(r.phase) ?? {
+            runs: 0,
+            tokens: { input: 0, output: 0, cache_write: 0 },
+            tool_uses: 0,
+            duration_ms: 0,
+        };
+        t.runs += 1;
+        t.tokens.input += r.tokens?.input ?? 0;
+        t.tokens.output += r.tokens?.output ?? 0;
+        t.tokens.cache_write += r.tokens?.cache_write ?? 0;
+        t.tool_uses += r.tool_uses ?? 0;
+        t.duration_ms += r.duration_ms ?? 0;
+        byPhase.set(r.phase, t);
+    }
+    return byPhase;
+}
+function emptyUsage() {
+    return { version: SCHEMA_VERSION, runs: [] };
+}
+function normalize(raw) {
+    if (!raw || typeof raw !== "object")
+        return emptyUsage();
+    const runs = Array.isArray(raw.runs) ? raw.runs.filter(isUsageRun) : [];
+    return {
+        version: typeof raw.version === "number" ? raw.version : SCHEMA_VERSION,
+        runs,
+    };
+}
+function isUsageRun(x) {
+    if (!x || typeof x !== "object")
+        return false;
+    const r = x;
+    return (typeof r.timestamp === "string" &&
+        typeof r.phase === "string" &&
+        typeof r.status === "string");
+}

package/dist/extensions/codecarto/agent-rewriter.d.ts

@@ -0,0 +1,20 @@
+import { type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { type WorkspaceState } from "../../core/index.ts";
+export interface RewritePhasePromptInput {
+    ctx: ExtensionContext;
+    state: WorkspaceState;
+    originalPrompt: string;
+    nextPhaseId: string;
+}
+export interface RewritePhasePromptResult {
+    prompt: string;
+    used: boolean;
+    skipReason?: string;
+}
+/**
+ * Run the rewriter and return the customized seed prompt. On any failure
+ * (no prior phase, missing closeout, rewriter session error, empty output)
+ * returns the original prompt with `used: false` and a skip reason — never
+ * throws. The caller decides what to surface to the user.
+ */
+export declare function rewritePhasePrompt(input: RewritePhasePromptInput): Promise<RewritePhasePromptResult>;

package/dist/extensions/codecarto/agent-rewriter.js

@@ -0,0 +1,149 @@
+// Optional LLM-steered prompt rewriter for /codecarto-next.
+//
+// When enabled (workspace config `orchestrator.llm_steer_next_phase: true`,
+// or per-invocation `--llm-steer`), this runs a one-shot in-memory
+// AgentSession on the orchestrator's model with no tools. It receives the
+// stock phase prompt + the previous phase's closeout (if any) and returns
+// a customized seed prompt that acknowledges the prior findings.
+//
+// Off by default. The orchestrator's tokens stay yours unless you opt in.
+import { readFile, readdir } from "node:fs/promises";
+import { join } from "node:path";
+import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { closeoutFileName, pathExists } from "../../core/index.js";
+/** Closeout content over this many bytes is truncated before being passed to
+ *  the rewriter. Keeps the orchestrator-side cost predictable. */
+const CLOSEOUT_BYTE_BUDGET = 8000;
+/**
+ * Run the rewriter and return the customized seed prompt. On any failure
+ * (no prior phase, missing closeout, rewriter session error, empty output)
+ * returns the original prompt with `used: false` and a skip reason — never
+ * throws. The caller decides what to surface to the user.
+ */
+export async function rewritePhasePrompt(input) {
+    const { ctx, state, originalPrompt, nextPhaseId } = input;
+    const prevPhaseId = findPreviousPhaseId(state, nextPhaseId);
+    if (!prevPhaseId) {
+        return { prompt: originalPrompt, used: false, skipReason: "no previous phase to steer from" };
+    }
+    const closeout = await readLatestCloseout(state.workspaceDir, prevPhaseId);
+    if (!closeout) {
+        return { prompt: originalPrompt, used: false, skipReason: `no closeout found for ${prevPhaseId}` };
+    }
+    const rewriterPrompt = buildRewriterPrompt({
+        nextPhaseId,
+        prevPhaseId,
+        originalPrompt,
+        prevCloseout: closeout,
+    });
+    let customized;
+    try {
+        customized = await runRewriterOnce(ctx, rewriterPrompt);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { prompt: originalPrompt, used: false, skipReason: `rewriter session failed: ${message}` };
+    }
+    const trimmed = customized.trim();
+    if (!trimmed) {
+        return { prompt: originalPrompt, used: false, skipReason: "rewriter returned empty output" };
+    }
+    return { prompt: trimmed, used: true };
+}
+function findPreviousPhaseId(state, nextPhaseId) {
+    const order = state.pipeline.phase_order;
+    const idx = order.indexOf(nextPhaseId);
+    if (idx <= 0)
+        return undefined;
+    for (let i = idx - 1; i >= 0; i--) {
+        if (state.status.phases[order[i]]?.status === "complete")
+            return order[i];
+    }
+    return undefined;
+}
+async function readLatestCloseout(workspaceDir, phaseId) {
+    const closeoutsDir = join(workspaceDir, "closeouts");
+    if (!(await pathExists(closeoutsDir)))
+        return undefined;
+    let entries;
+    try {
+        entries = await readdir(closeoutsDir);
+    }
+    catch {
+        return undefined;
+    }
+    const suffix = closeoutFileName("", phaseId).replace(/^-/, ""); // "<phaseId>.md"
+    const matches = entries.filter((name) => name.endsWith(`-${suffix}`)).sort();
+    const latest = matches.at(-1);
+    if (!latest)
+        return undefined;
+    const raw = await readFile(join(closeoutsDir, latest), "utf8");
+    if (raw.length <= CLOSEOUT_BYTE_BUDGET)
+        return raw;
+    return `${raw.slice(0, CLOSEOUT_BYTE_BUDGET)}\n\n[…closeout truncated for rewriter input…]`;
+}
+function buildRewriterPrompt(input) {
+    return [
+        `You are seeding a sub-agent for the \`${input.nextPhaseId}\` phase of a CodeCartographer pipeline.`,
+        `The previous phase \`${input.prevPhaseId}\` just completed. Read its closeout below and produce a CUSTOMIZED seed prompt for the next phase's sub-agent.`,
+        "",
+        "Constraints for the customized prompt:",
+        `- Stay faithful to the original ${input.nextPhaseId} phase template; do not change its structure, required outputs, or completion criteria.`,
+        `- Add a short \"context from ${input.prevPhaseId}\" preamble that names the specific findings, open questions, or carry-forward items from the closeout that the ${input.nextPhaseId} phase should pay attention to.`,
+        "- Do not invent findings the closeout does not state.",
+        "- Do not add commentary directed at the user; the output is the sub-agent's seed prompt.",
+        "",
+        "Output ONLY the customized seed prompt as plain Markdown. No preface, no fenced code blocks, no commentary.",
+        "",
+        "=== ORIGINAL NEXT-PHASE PROMPT ===",
+        input.originalPrompt,
+        "=== END ORIGINAL NEXT-PHASE PROMPT ===",
+        "",
+        `=== PREVIOUS PHASE (${input.prevPhaseId}) CLOSEOUT ===`,
+        input.prevCloseout,
+        `=== END PREVIOUS PHASE (${input.prevPhaseId}) CLOSEOUT ===`,
+    ].join("\n");
+}
+async function runRewriterOnce(ctx, prompt) {
+    const cwd = ctx.cwd;
+    const agentDir = getAgentDir();
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir,
+        // Even more stripped than the phase runner: no extensions either,
+        // since the rewriter has no tools and shouldn't pick up codecarto's
+        // tool-interception (it has no tools to intercept).
+        noExtensions: true,
+        noSkills: true,
+        noPromptTemplates: true,
+        noThemes: true,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    const { session } = await createAgentSession({
+        cwd,
+        agentDir,
+        sessionManager: SessionManager.inMemory(cwd),
+        settingsManager: SettingsManager.create(cwd, agentDir),
+        modelRegistry: ctx.modelRegistry,
+        model: ctx.model,
+        tools: [],
+        resourceLoader: loader,
+    });
+    await session.prompt(prompt);
+    for (let i = session.messages.length - 1; i >= 0; i--) {
+        const msg = session.messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        const blocks = msg.content;
+        const parts = [];
+        for (const c of blocks) {
+            if (c.type === "text" && c.text)
+                parts.push(c.text);
+        }
+        const joined = parts.join("\n").trim();
+        if (joined)
+            return joined;
+    }
+    return "";
+}

package/dist/extensions/codecarto/agent-runner.d.ts

@@ -0,0 +1,44 @@
+import { type AgentSession, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+export interface PhaseRunCallbacks {
+    onSessionCreated?: (session: AgentSession) => void;
+    onToolStart?: (toolCallId: string, toolName: string) => void;
+    onToolEnd?: (toolCallId: string, toolName: string) => void;
+    onTextDelta?: (delta: string, fullText: string) => void;
+    onTurnEnd?: (turnCount: number) => void;
+    onMessageEnd?: (usage: {
+        input: number;
+        output: number;
+        cacheWrite: number;
+    }) => void;
+}
+export interface PhaseRunOptions {
+    /** Display name written via appendSessionInfo so the session shows up in
+     *  /resume's picker as e.g. "CodeCartographer phase: blueprint". Pi reads
+     *  it via SessionManager.getSessionName(). */
+    sessionName?: string;
+}
+export interface PhaseRunResult {
+    session: AgentSession;
+    responseText: string;
+    toolUses: number;
+    turnCount: number;
+    aborted: boolean;
+    /** Path to the on-disk session file (under ~/.pi/agent/sessions/<encoded-cwd>/).
+     *  Stable across the run; useful for /codecarto-usage and any future tooling
+     *  that wants to point at the phase's transcript. */
+    sessionFile: string | undefined;
+}
+/**
+ * Run one CodeCartographer phase as an isolated AgentSession. Awaiting this
+ * function blocks until the phase completes (or aborts via signal). The
+ * orchestrator's TUI stays active throughout — only the phase's own context
+ * window holds the tool calls and reasoning.
+ *
+ * The phase session is **persisted** to the default Pi session directory
+ * (`~/.pi/agent/sessions/<encoded-cwd>/`), the same directory the orchestrator
+ * uses, so Pi's `/resume`, `/tree`, and `/export` see phase transcripts as
+ * first-class sessions. They're tagged via `appendSessionInfo` (display name)
+ * and `parentSession` (the orchestrator's session file path) so the picker
+ * shows lineage.
+ */
+export declare function runPhase(ctx: ExtensionContext, prompt: string, callbacks?: PhaseRunCallbacks, options?: PhaseRunOptions, signal?: AbortSignal): Promise<PhaseRunResult>;

package/dist/extensions/codecarto/agent-runner.js

@@ -0,0 +1,169 @@
+// Sub-agent runner for codecarto phases. Spawns an in-memory AgentSession
+// using the SDK's createAgentSession() (NOT ctx.newSession() — that replaces
+// the active TUI session, which is not what we want). Subscribes to the
+// session's event stream and forwards events to caller-provided callbacks
+// so a parent UI (the agents widget; M2) can render live progress while the
+// phase runs in parallel with the orchestrator.
+//
+// The runner is intentionally minimal: no memory tools, no append-mode
+// system prompt, no parent-context inheritance, no turn-limit grace logic.
+// Codecarto phases are bounded by their phase prompt and validation gate;
+// they don't need the full subagent-framework machinery.
+import { createAgentSession, DefaultResourceLoader, getAgentDir, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+// Tools available to the phase sub-agent. Matches the codecarto interception
+// allowlist (SAFE_TOOL_NAMES in extensions/codecarto/index.ts), minus bash.
+// Phases analyze source code and write findings; they don't need a shell.
+const PHASE_TOOL_NAMES = ["read", "edit", "write", "grep", "find", "ls"];
+/**
+ * Run one CodeCartographer phase as an isolated AgentSession. Awaiting this
+ * function blocks until the phase completes (or aborts via signal). The
+ * orchestrator's TUI stays active throughout — only the phase's own context
+ * window holds the tool calls and reasoning.
+ *
+ * The phase session is **persisted** to the default Pi session directory
+ * (`~/.pi/agent/sessions/<encoded-cwd>/`), the same directory the orchestrator
+ * uses, so Pi's `/resume`, `/tree`, and `/export` see phase transcripts as
+ * first-class sessions. They're tagged via `appendSessionInfo` (display name)
+ * and `parentSession` (the orchestrator's session file path) so the picker
+ * shows lineage.
+ */
+export async function runPhase(ctx, prompt, callbacks = {}, options = {}, signal) {
+    const cwd = ctx.cwd;
+    const agentDir = getAgentDir();
+    // Resource loader: load Pi extensions and skills (so codecarto's own tool
+    // interception applies to the child) but skip prompt templates, themes,
+    // and project context files — they'd just bloat the system prompt.
+    const loader = new DefaultResourceLoader({
+        cwd,
+        agentDir,
+        noExtensions: false,
+        noSkills: false,
+        noPromptTemplates: true,
+        noThemes: true,
+        noContextFiles: true,
+    });
+    await loader.reload();
+    // File-backed session in the same directory the orchestrator's TUI uses.
+    // Pi's /resume, /tree, and /export read this directory, so phase
+    // transcripts become first-class browsable artifacts. Tag with
+    // parentSession (orchestrator's file) for lineage and a session_info
+    // display name so the picker can identify them at a glance.
+    const sessionManager = SessionManager.create(cwd);
+    const orchestratorSessionFile = ctx.sessionManager.getSessionFile();
+    if (orchestratorSessionFile) {
+        // SessionManager.create() calls newSession() with no options in its
+        // constructor; rewrite the header to attach the parent before the
+        // session ever flushes to disk.
+        sessionManager.newSession({ parentSession: orchestratorSessionFile });
+    }
+    if (options.sessionName) {
+        sessionManager.appendSessionInfo(options.sessionName);
+    }
+    const { session } = await createAgentSession({
+        cwd,
+        agentDir,
+        sessionManager,
+        settingsManager: SettingsManager.create(cwd, agentDir),
+        modelRegistry: ctx.modelRegistry,
+        model: ctx.model,
+        tools: PHASE_TOOL_NAMES,
+        resourceLoader: loader,
+    });
+    await session.bindExtensions({});
+    callbacks.onSessionCreated?.(session);
+    let toolUses = 0;
+    let turnCount = 0;
+    let currentMessageText = "";
+    let aborted = false;
+    const unsubscribe = session.subscribe((event) => {
+        switch (event.type) {
+            case "tool_execution_start": {
+                toolUses++;
+                const id = event.toolCallId ?? `${event.toolName}-${toolUses}`;
+                callbacks.onToolStart?.(id, event.toolName);
+                break;
+            }
+            case "tool_execution_end": {
+                const id = event.toolCallId ?? `${event.toolName}-${toolUses}`;
+                callbacks.onToolEnd?.(id, event.toolName);
+                break;
+            }
+            case "turn_end": {
+                turnCount++;
+                callbacks.onTurnEnd?.(turnCount);
+                break;
+            }
+            case "message_start": {
+                currentMessageText = "";
+                break;
+            }
+            case "message_update": {
+                if (event.assistantMessageEvent?.type === "text_delta") {
+                    currentMessageText += event.assistantMessageEvent.delta;
+                    callbacks.onTextDelta?.(event.assistantMessageEvent.delta, currentMessageText);
+                }
+                break;
+            }
+            case "message_end": {
+                if (event.message.role === "assistant") {
+                    const u = event.message.usage;
+                    if (u) {
+                        callbacks.onMessageEnd?.({
+                            input: u.input ?? 0,
+                            output: u.output ?? 0,
+                            cacheWrite: u.cacheWrite ?? 0,
+                        });
+                    }
+                }
+                break;
+            }
+        }
+    });
+    let abortCleanup = () => { };
+    if (signal) {
+        const onAbort = () => {
+            aborted = true;
+            session.abort();
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        abortCleanup = () => signal.removeEventListener("abort", onAbort);
+    }
+    try {
+        await session.prompt(prompt);
+    }
+    finally {
+        unsubscribe();
+        abortCleanup();
+    }
+    return {
+        session,
+        responseText: getLastAssistantText(session) || currentMessageText,
+        toolUses,
+        turnCount,
+        aborted,
+        sessionFile: sessionManager.getSessionFile(),
+    };
+}
+/**
+ * Walk session.messages backward to find the last non-empty assistant text.
+ * Used as a fallback when text_delta streaming missed something or the final
+ * message arrived in a single chunk.
+ */
+function getLastAssistantText(session) {
+    for (let i = session.messages.length - 1; i >= 0; i--) {
+        const msg = session.messages[i];
+        if (msg.role !== "assistant")
+            continue;
+        // Assistant content is always a content-block array per SDK types.
+        const blocks = msg.content;
+        const parts = [];
+        for (const c of blocks) {
+            if (c.type === "text" && c.text)
+                parts.push(c.text);
+        }
+        const joined = parts.join("\n").trim();
+        if (joined)
+            return joined;
+    }
+    return "";
+}