codecartographer-pi 0.1.1 → 0.1.3

package/README.md

@@ -44,14 +44,18 @@ That's it. The LLM reads the guide, checks `workflow/status.yaml` for progress,
 
 This branch also packages CodeCartographer for [Pi](https://github.com/badlogic/pi-mono/tree/main/packages/coding-agent) without changing `.codecarto/` itself. Pi is an **optional peer dependency** — if you only want the template or the MCP server, you don't need Pi installed.
 
-Install from a local checkout or git URL:
+Install from npm, a local checkout, or a git URL:
 
 ```bash
+pi install npm:codecartographer-pi
+# or, from a local checkout:
 pi install /absolute/path/to/CodeCartographer
-# or
+# or, from a git URL:
 pi install git:github.com/your-user/CodeCartographer
 ```
 
+> **Don't run `npm install codecartographer-pi` for the Pi use case.** Plain `npm install` puts the package on disk but doesn't register it with Pi, so it never appears in the TUI. Use `pi install npm:codecartographer-pi` instead — Pi handles the npm install internally and writes the package into its own `settings.json` (`~/.pi/agent/settings.json` by default). Plain `npm install` is the right command only for the MCP-server use case described below.
+
 For extension development, you can also point Pi directly at the extension entrypoint or place it in an auto-discovered extensions directory and use `/reload`:
 
 ```bash
@@ -73,17 +77,30 @@ If you install the whole repository as a Pi package, Pi may still run package in
 What the Pi extension adds:
 
 - `/codecarto-init` to copy `.codecarto/` into the current repository
-- `/codecarto-next` to queue the next eligible phase prompt
+- `/codecarto-next` to queue the next eligible phase prompt (or, in sub-agent mode, spawn the phase as a child session)
 - `/codecarto-status` to show current phase progress
 - `/codecarto-validate` and `/codecarto-complete` for validation-gated status updates
 - a footer/widget showing the active CodeCartographer phase
 - 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
+
+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`:
+
+- **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.
+
+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.
+
+The MCP-server path is unaffected — it has no session concept; the host (Claude Desktop / Claude Code / etc.) is the orchestrator.
+
 ## MCP Server
 
 The same framework is also packaged as a [Model Context Protocol](https://modelcontextprotocol.io) server, so any MCP-compatible host (Claude Code, Claude Desktop, etc.) can drive a CodeCartographer workflow without the Pi runtime. The server imports the same `core/` primitives the Pi extension uses, so phase prompts and validation are byte-identical across both surfaces.
 
+Implements MCP spec revision [`2025-11-25`](https://modelcontextprotocol.io/specification/2025-11-25) via `@modelcontextprotocol/sdk` ≥ 1.29.0. The negotiated `protocolVersion` reflects whatever the connecting client requests; the server accepts every revision the SDK supports (currently `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`).
+
 Install and wire it up:
 
 ```bash

package/dist/core/index.d.ts

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

package/dist/core/index.js

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

package/dist/core/orchestrator.d.ts

@@ -0,0 +1,6 @@
+export interface OrchestratorState {
+    sessionFile: string;
+    sessionId: string;
+}
+export declare function loadOrchestratorState(cwd: string): Promise<OrchestratorState | null>;
+export declare function writeOrchestratorState(cwd: string, state: OrchestratorState): Promise<void>;

package/dist/core/orchestrator.js

@@ -0,0 +1,36 @@
+// Per-machine pointer to the Pi session that runs as the CodeCartographer
+// orchestrator. Stored in `.codecarto/workflow/.orchestrator.local.yaml`
+// (gitignored) so committed `status.yaml` doesn't leak machine-specific
+// session file paths to collaborators.
+//
+// Only the Pi extension writes/reads this — the MCP path has no session
+// concept. When the file is missing or malformed, `/codecarto-next` falls
+// back to in-place phase prompts (legacy 0.1.0–0.1.2 behavior).
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { pathExists } from "./utils.js";
+import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
+const ORCHESTRATOR_STATE_RELATIVE = "workflow/.orchestrator.local.yaml";
+function orchestratorStatePath(cwd) {
+    return join(cwd, ".codecarto", ORCHESTRATOR_STATE_RELATIVE);
+}
+export async function loadOrchestratorState(cwd) {
+    const path = orchestratorStatePath(cwd);
+    if (!(await pathExists(path)))
+        return null;
+    let data;
+    try {
+        data = await loadYamlFile(path);
+    }
+    catch {
+        return null;
+    }
+    if (!data?.sessionFile || !data?.sessionId)
+        return null;
+    return { sessionFile: data.sessionFile, sessionId: data.sessionId };
+}
+export async function writeOrchestratorState(cwd, state) {
+    const path = orchestratorStatePath(cwd);
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, `${stringifySimpleYaml(state)}\n`, "utf8");
+}

package/dist/core/workspace.js

@@ -2,14 +2,31 @@
 // (so the MCP server and Pi can both copy from it on /codecarto-init), loads
 // + normalizes the per-project workspace state from disk, and provides the
 // atomic status-update primitive used by /codecarto-complete.
+import { existsSync } from "node:fs";
 import { appendFile, rename, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { acquireLock, normalizeStatus } from "./status.js";
 import { pathExists } from "./utils.js";
 import { loadYamlFile, stringifySimpleYaml } from "./yaml.js";
+// Walk up from the current file to find the package root. Needed because the
+// source lives at <root>/core/workspace.ts (one level below the package root)
+// but compiles to <root>/dist/core/workspace.js (two levels below). A fixed
+// `..` only works in one of those layouts, so resolve `package.json` instead.
+function findPackageRoot(start) {
+    let dir = start;
+    while (true) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir) {
+            throw new Error(`Could not locate package.json starting from ${start}`);
+        }
+        dir = parent;
+    }
+}
 const coreDir = dirname(fileURLToPath(import.meta.url));
-const packageRoot = resolve(coreDir, "..");
+const packageRoot = findPackageRoot(coreDir);
 // Path to the packaged framework template directory. Wrappers copy this on
 // /codecarto-init.
 export const packagedWorkspaceDir = join(packageRoot, ".codecarto");

package/dist/extensions/codecarto/index.d.ts

@@ -1,2 +1,2 @@
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 export default function codeCartographerExtension(pi: ExtensionAPI): void;

package/dist/extensions/codecarto/index.js

@@ -1,6 +1,6 @@
 import { cp, mkdir, rm, writeFile } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
-import { buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, } from "../../core/index.js";
+import { buildPhasePrompt, buildSkillPrompt, buildThreadLogEntry, buildValidationSummary, canonicalPath, closeoutFileName, createEmptyStatus, dateOnly, DEFAULT_PIPELINE_PATH, ensureCloseoutStub, getNextEligiblePhase, getPipelineLabel, getWorkspaceState, isWithinPath, listSkillNames, loadOrchestratorState, loadYamlFile, normalizeForComparison, normalizeStatus, packagedWorkspaceDir, pathExists, PIPELINE_ALIASES, resolvePhase, resolvePipelineChoice, stringifySimpleYaml, uniqueStrings, updateStatusAtomically, validatePhaseOutput, writeOrchestratorState, } from "../../core/index.js";
 const STATUS_WIDGET_ID = "codecarto-widget";
 const STATUS_LINE_ID = "codecarto-status";
 const SAFE_TOOL_NAMES = ["read", "grep", "find", "ls", "edit", "write"];
@@ -153,6 +153,21 @@ export default function codeCartographerExtension(pi) {
             normalizedStatus.last_updated = new Date().toISOString();
             await writeFile(rawStatusPath, `${stringifySimpleYaml(normalizedStatus)}\n`, "utf8");
             lastFeedbackLines = [`Initialized workspace with pipeline: ${getPipelineLabel(selectedPipelinePath)}`];
+            // Claim the current Pi session as the orchestrator for this workspace.
+            // /codecarto-next will then spawn each phase as a child session, keeping
+            // the orchestrator's context window clean. The pointer is gitignored
+            // (workflow/.orchestrator.local.yaml) so it's machine-local. If we have
+            // no session file (rare; Pi running headless), skip silently — handlers
+            // fall back to in-place phase prompts.
+            const orchestratorSessionFile = ctx.sessionManager.getSessionFile();
+            const orchestratorSessionId = ctx.sessionManager.getSessionId();
+            if (orchestratorSessionFile && orchestratorSessionId) {
+                await writeOrchestratorState(ctx.cwd, {
+                    sessionFile: orchestratorSessionFile,
+                    sessionId: orchestratorSessionId,
+                });
+                lastFeedbackLines.push(`Claimed this session as the orchestrator (${orchestratorSessionId.slice(0, 8)}…).`);
+            }
             ctx.ui.notify(`Initialized CodeCartographer (${getPipelineLabel(selectedPipelinePath)})`, "info");
             await ctx.reload();
             return;
@@ -184,15 +199,69 @@ export default function codeCartographerExtension(pi) {
                 return;
             }
             const prompt = await buildPhasePrompt(state, phase, false);
-            if (ctx.isIdle()) {
-                pi.sendUserMessage(prompt);
+            const orchestrator = await loadOrchestratorState(ctx.cwd);
+            const currentSessionFile = ctx.sessionManager.getSessionFile();
+            // Legacy path: workspace has no orchestrator pointer (created by 0.1.2
+            // or earlier, or Pi has no session file). Queue the prompt in-place
+            // exactly as we did before sub-agent mode existed.
+            if (!orchestrator || !currentSessionFile) {
+                if (ctx.isIdle())
+                    pi.sendUserMessage(prompt);
+                else
+                    pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+                lastFeedbackLines = [`Queued phase prompt for ${phase.id} (in-place; run /codecarto-init to enable sub-agent mode)`];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
+                return;
             }
-            else {
-                pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+            // Orchestrator path: we're the parent. Spawn a child session for the
+            // phase so its tool calls and reasoning land in an isolated context.
+            if (currentSessionFile === orchestrator.sessionFile) {
+                const result = await ctx.newSession({
+                    parentSession: orchestrator.sessionFile,
+                    withSession: async (childCtx) => {
+                        childCtx.sendUserMessage(prompt);
+                    },
+                });
+                if (result.cancelled) {
+                    ctx.ui.notify("Sub-agent spawn cancelled.", "warning");
+                    return;
+                }
+                lastFeedbackLines = [`Spawned ${phase.id} phase in a sub-agent`];
+                setUiState(ctx, state, lastFeedbackLines);
+                ctx.ui.notify(`CodeCartographer phase: ${phase.id} (sub-agent)`, "info");
+                return;
+            }
+            // Phase-child path: we're inside a phase sub-agent. Switch the TUI back
+            // to the orchestrator and chain the next phase atomically. The fresh
+            // state read inside withSession reflects any closeouts the child wrote.
+            const switchResult = await ctx.switchSession(orchestrator.sessionFile, {
+                withSession: async (orchestratorCtx) => {
+                    const freshState = await getWorkspaceState(orchestratorCtx.cwd);
+                    if (!freshState) {
+                        orchestratorCtx.ui.notify("Workspace state not found after switch.", "error");
+                        return;
+                    }
+                    const nextPhase = getNextEligiblePhase(freshState);
+                    if (!nextPhase) {
+                        orchestratorCtx.ui.notify("All CodeCartographer phases are complete.", "info");
+                        return;
+                    }
+                    const nextPrompt = await buildPhasePrompt(freshState, nextPhase, false);
+                    await orchestratorCtx.newSession({
+                        parentSession: orchestrator.sessionFile,
+                        withSession: async (nextChildCtx) => {
+                            nextChildCtx.sendUserMessage(nextPrompt);
+                        },
+                    });
+                },
+            });
+            if (switchResult.cancelled) {
+                ctx.ui.notify("Switch back to orchestrator cancelled.", "warning");
+                return;
             }
-            lastFeedbackLines = [`Queued phase prompt for ${phase.id}`];
+            lastFeedbackLines = ["Returned to orchestrator and queued next phase as a sub-agent"];
             setUiState(ctx, state, lastFeedbackLines);
-            ctx.ui.notify(`Queued CodeCartographer phase: ${phase.id}`, "info");
         },
     });
     pi.registerCommand("codecarto-phase", {

package/dist/mcp-server/server.js

@@ -367,7 +367,7 @@ const HANDLERS = {
 };
 // ---------- server bootstrap ----------
 export function buildServer() {
-    const server = new Server({ name: "codecartographer", version: "0.1.1" }, { capabilities: { tools: {} } });
+    const server = new Server({ name: "codecartographer", version: "0.1.3" }, { capabilities: { tools: {} } });
     server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }));
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const handler = HANDLERS[request.params.name];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codecartographer-pi",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "CodeCartographer packaged for Pi as an extension-driven workflow wrapper.",
   "type": "module",
   "keywords": [
@@ -39,10 +39,10 @@
     "smoke": "node scripts/smoke-mcp.mjs"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "*"
+    "@modelcontextprotocol/sdk": "^1.29.0"
   },
   "peerDependencies": {
-    "@mariozechner/pi-coding-agent": "*",
+    "@earendil-works/pi-coding-agent": "^0.74.0",
     "@sinclair/typebox": "*"
   },
   "pi": {