@astralyn/pi 0.87.6 → 1.0.0

package/examples/extensions/gondolin/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "0.87.1",
+	"version": "1.0.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "0.87.1",
+			"version": "1.0.0",
 			"dependencies": {
 				"@earendil-works/gondolin": "0.12.0"
 			}

package/examples/extensions/gondolin/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-gondolin",
 	"private": true,
-	"version": "0.87.1",
+	"version": "1.0.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/jev-router.ts

@@ -0,0 +1,113 @@
+/**
+ * Jev router - a virtual model that plans on a strong model and implements on a cheap one.
+ *
+ * Registers `jev/auto`, which routes between three OpenAI Codex models:
+ *
+ * - Planning: GPT-5.6 Sol for complex work, GPT-5.6 Terra otherwise. The Jev classifier rates the
+ *   first user message; planning stays on the chosen model.
+ * - Implementation: GPT-5.6 Luna.
+ *
+ * The planning model explores, plans, and makes the first edit. After the first successful `edit`
+ * or `write` tool call, the next request of the same turn goes to Luna, and the session stays
+ * there. A session therefore switches models once and accepts a single prompt-cache miss.
+ *
+ * The phase is router state: Pi stores it on the session branch, so it follows the session tree
+ * and survives compaction. The selected thinking level passes through as the reasoning effort of
+ * the chosen model. Requests outside the agent loop, such as compaction summaries, go to Luna.
+ *
+ * Requires TypeSafe credentials (TYPESAFE_API_KEY) and an OpenAI Codex login.
+ * Usage: pi -e ./jev-router.ts --model jev/auto
+ */
+
+import type { Message } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext, ModelRoute, ModelRouteRequest } from "@earendil-works/pi-coding-agent";
+
+const PROVIDER = "openai-codex";
+const SOL = "gpt-5.6-sol";
+const TERRA = "gpt-5.6-terra";
+const LUNA = "gpt-5.6-luna";
+
+/** Tools whose successful result means implementation has started. */
+const EDIT_TOOLS = new Set(["edit", "write"]);
+
+interface JevState {
+	phase: "planning" | "implementation";
+	/** OpenAI Codex model for this phase. */
+	model: string;
+}
+
+type JevRequest = ModelRouteRequest<JevState>;
+
+function routeTo(request: JevRequest, ctx: ExtensionContext, id: string, state?: JevState): ModelRoute<JevState> {
+	const model = ctx.modelRegistry.find(PROVIDER, id);
+	if (!model) throw new Error(`Model ${PROVIDER}/${id} is not in the catalog`);
+	return { model, thinkingLevel: request.thinkingLevel, state };
+}
+
+function lastUserText(messages: readonly Message[]): string {
+	const content = messages.filter((message) => message.role === "user").at(-1)?.content ?? "";
+	if (typeof content === "string") return content;
+	return content.flatMap((block) => (block.type === "text" ? [block.text] : [])).join("\n");
+}
+
+/** Whether a tool call since the last user message edited a file successfully. */
+function editedThisTurn(messages: readonly Message[]): boolean {
+	const lastUser = messages.findLastIndex((message) => message.role === "user");
+	return messages
+		.slice(lastUser + 1)
+		.some((message) => message.role === "toolResult" && EDIT_TOOLS.has(message.toolName) && !message.isError);
+}
+
+/** Planning model for a new session: Sol for complex work, Terra otherwise or when Jev is unavailable. */
+async function choosePlanningModel(request: JevRequest, ctx: ExtensionContext): Promise<string> {
+	// Keep a planning model the session already uses, so switching to jev/auto costs no cache miss.
+	const previous = request.previous?.model;
+	if (previous?.provider === PROVIDER && (previous.id === SOL || previous.id === TERRA)) return previous.id;
+
+	const jev = ctx.modelRegistry.findOfType("classifier", "typesafe", "jev-latest");
+	if (!jev) return TERRA;
+	const result = await ctx.modelRegistry.classify(
+		jev,
+		{
+			state: { prompt: lastUserText(request.messages).slice(0, 16_000) },
+			questions: {
+				complexity: {
+					type: "choice",
+					instructions: "How demanding is the software engineering work requested in `prompt`?",
+					criteria: {
+						standard: "Ordinary features, fixes, reviews, or questions",
+						complex: "Subtle design, cross-cutting changes, or hard debugging",
+					},
+				},
+			},
+		},
+		{ signal: request.signal },
+	);
+	const answer = result.stopReason === "stop" ? result.answers.complexity : undefined;
+	return answer?.type === "choice" && (answer.probabilities.complex ?? 0) >= 0.5 ? SOL : TERRA;
+}
+
+export default function (pi: ExtensionAPI) {
+	pi.registerVirtualModel<JevState>({
+		provider: "jev",
+		id: "auto",
+		name: "Auto (Jev)",
+		thinkingLevels: ["low", "medium", "high", "xhigh"],
+		// Shared by all three models; shown before the first response.
+		contextWindow: 272_000,
+		maxTokens: 128_000,
+		async route(request, ctx) {
+			if (request.reason === "direct") return routeTo(request, ctx, LUNA);
+			const state = request.state;
+			if (!state) {
+				const model = await choosePlanningModel(request, ctx);
+				return routeTo(request, ctx, model, { phase: "planning", model });
+			}
+			// The planning model made the first edit: hand the rest of the work to Luna.
+			if (state.phase === "planning" && editedThisTurn(request.messages)) {
+				return routeTo(request, ctx, LUNA, { phase: "implementation", model: LUNA });
+			}
+			return routeTo(request, ctx, state.model);
+		},
+	});
+}

package/examples/extensions/minimal-mode.ts

@@ -18,13 +18,13 @@
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import {
-	createBashTool,
-	createEditTool,
-	createFindTool,
-	createGrepTool,
-	createLsTool,
-	createReadTool,
-	createWriteTool,
+	createBashToolDefinition,
+	createEditToolDefinition,
+	createFindToolDefinition,
+	createGrepToolDefinition,
+	createLsToolDefinition,
+	createReadToolDefinition,
+	createWriteToolDefinition,
 } from "@earendil-works/pi-coding-agent";
 import { Text } from "@earendil-works/pi-tui";
 import { homedir } from "os";
@@ -40,45 +40,26 @@ function shortenPath(path: string): string {
 	return path;
 }
 
-// Cache for built-in tools by cwd
-const toolCache = new Map<string, ReturnType<typeof createBuiltInTools>>();
-
 function createBuiltInTools(cwd: string) {
 	return {
-		read: createReadTool(cwd),
-		bash: createBashTool(cwd),
-		edit: createEditTool(cwd),
-		write: createWriteTool(cwd),
-		find: createFindTool(cwd),
-		grep: createGrepTool(cwd),
-		ls: createLsTool(cwd),
+		read: createReadToolDefinition(cwd),
+		bash: createBashToolDefinition(cwd),
+		edit: createEditToolDefinition(cwd),
+		write: createWriteToolDefinition(cwd),
+		find: createFindToolDefinition(cwd),
+		grep: createGrepToolDefinition(cwd),
+		ls: createLsToolDefinition(cwd),
 	};
 }
 
-function getBuiltInTools(cwd: string) {
-	let tools = toolCache.get(cwd);
-	if (!tools) {
-		tools = createBuiltInTools(cwd);
-		toolCache.set(cwd, tools);
-	}
-	return tools;
-}
-
 export default function (pi: ExtensionAPI) {
+	const tools = createBuiltInTools(process.cwd());
+
 	// =========================================================================
 	// Read Tool
 	// =========================================================================
 	pi.registerTool({
-		name: "read",
-		label: "read",
-		description:
-			"Read the contents of a file. Supports text files and images (jpg, png, gif, webp). Images are sent as attachments. For text files, output is truncated to 2000 lines or 50KB (whichever is hit first). Use offset/limit for large files.",
-		parameters: getBuiltInTools(process.cwd()).read.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const tools = getBuiltInTools(ctx.cwd);
-			return tools.read.execute(toolCallId, params, signal, onUpdate);
-		},
+		...tools.read,
 
 		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
@@ -116,16 +97,7 @@ export default function (pi: ExtensionAPI) {
 	// Bash Tool
 	// =========================================================================
 	pi.registerTool({
-		name: "bash",
-		label: "bash",
-		description:
-			"Execute a bash command in the current working directory. Returns stdout and stderr. Output is truncated to last 2000 lines or 50KB (whichever is hit first).",
-		parameters: getBuiltInTools(process.cwd()).bash.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const tools = getBuiltInTools(ctx.cwd);
-			return tools.bash.execute(toolCallId, params, signal, onUpdate);
-		},
+		...tools.bash,
 
 		renderCall(args, theme, _context) {
 			const command = args.command || "...";
@@ -165,16 +137,7 @@ export default function (pi: ExtensionAPI) {
 	// Write Tool
 	// =========================================================================
 	pi.registerTool({
-		name: "write",
-		label: "write",
-		description:
-			"Write content to a file. Creates the file if it doesn't exist, overwrites if it does. Automatically creates parent directories.",
-		parameters: getBuiltInTools(process.cwd()).write.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const tools = getBuiltInTools(ctx.cwd);
-			return tools.write.execute(toolCallId, params, signal, onUpdate);
-		},
+		...tools.write,
 
 		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
@@ -207,16 +170,8 @@ export default function (pi: ExtensionAPI) {
 	// Edit Tool
 	// =========================================================================
 	pi.registerTool({
-		name: "edit",
-		label: "edit",
-		description:
-			"Edit a file by replacing exact text. The oldText must match exactly (including whitespace). Use this for precise, surgical edits.",
-		parameters: getBuiltInTools(process.cwd()).edit.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const tools = getBuiltInTools(ctx.cwd);
-			return tools.edit.execute(toolCallId, params, signal, onUpdate);
-		},
+		...tools.edit,
+		renderShell: "default",
 
 		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || "");
@@ -252,16 +207,7 @@ export default function (pi: ExtensionAPI) {
 	// Find Tool
 	// =========================================================================
 	pi.registerTool({
-		name: "find",
-		label: "find",
-		description:
-			"Find files by name pattern (glob). Searches recursively from the specified path. Output limited to 200 results.",
-		parameters: getBuiltInTools(process.cwd()).find.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const tools = getBuiltInTools(ctx.cwd);
-			return tools.find.execute(toolCallId, params, signal, onUpdate);
-		},
+		...tools.find,
 
 		renderCall(args, theme, _context) {
 			const pattern = args.pattern || "";
@@ -310,16 +256,7 @@ export default function (pi: ExtensionAPI) {
 	// Grep Tool
 	// =========================================================================
 	pi.registerTool({
-		name: "grep",
-		label: "grep",
-		description:
-			"Search file contents by regex pattern. Uses ripgrep for fast searching. Output limited to 200 matches.",
-		parameters: getBuiltInTools(process.cwd()).grep.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const tools = getBuiltInTools(ctx.cwd);
-			return tools.grep.execute(toolCallId, params, signal, onUpdate);
-		},
+		...tools.grep,
 
 		renderCall(args, theme, _context) {
 			const pattern = args.pattern || "";
@@ -372,16 +309,7 @@ export default function (pi: ExtensionAPI) {
 	// Ls Tool
 	// =========================================================================
 	pi.registerTool({
-		name: "ls",
-		label: "ls",
-		description:
-			"List directory contents with file sizes. Shows files and directories with their sizes. Output limited to 500 entries.",
-		parameters: getBuiltInTools(process.cwd()).ls.parameters,
-
-		async execute(toolCallId, params, signal, onUpdate, ctx) {
-			const tools = getBuiltInTools(ctx.cwd);
-			return tools.ls.execute(toolCallId, params, signal, onUpdate);
-		},
+		...tools.ls,
 
 		renderCall(args, theme, _context) {
 			const path = shortenPath(args.path || ".");

package/examples/extensions/sandbox/package-lock.json

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.17.1",
+	"version": "1.0.0",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.17.1",
+			"version": "1.0.0",
 			"dependencies": {
 				"@anthropic-ai/sandbox-runtime": "^0.0.26"
 			}

package/examples/extensions/sandbox/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-sandbox",
 	"private": true,
-	"version": "1.17.1",
+	"version": "1.0.0",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/with-deps/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-with-deps",
-  "version": "0.87.1",
+  "version": "1.0.0",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.87.1",
+      "version": "1.0.0",
       "dependencies": {
         "ms": "^2.1.3"
       },

package/examples/extensions/with-deps/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-with-deps",
   "private": true,
-  "version": "0.87.1",
+  "version": "1.0.0",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/rpc-client.ts

@@ -2,7 +2,7 @@
  * Run one prompt through a Pi RPC child process.
  *
  * Build the coding-agent package first, then run:
- * npx tsx examples/rpc-client.ts "Explain this repository"
+ * node examples/rpc-client.ts "Explain this repository"
  */
 
 import { dirname, join } from "node:path";

package/examples/rpc-extension-ui.ts

@@ -5,7 +5,7 @@
  * Demonstrates how to build a custom UI on top of the RPC protocol,
  * including handling extension UI requests (select, confirm, input, editor).
  *
- * Usage: npx tsx examples/rpc-extension-ui.ts
+ * Usage: node examples/rpc-extension-ui.ts
  *
  * Slash commands:
  *   /select  - demo select dialog

package/examples/sdk/14-codemode-mcp.ts

@@ -0,0 +1,61 @@
+/**
+ * Codemode, Tool Search, and MCP
+ *
+ * The CLI loads `codemode`, `tool_search`, and MCP as built-in extensions. SDK sessions add
+ * them to the resource loader's extension factories.
+ *
+ * `codemode` and `tool_search` are registered inactive. Enable them through the `defaultTools` setting
+ * (`tools` would also restrict the session to the named tools, which hides MCP tools), or let the
+ * MCP extension activate them: `codemode` for servers with `codemode` exposure, `tool_search` for
+ * servers with `deferred` exposure.
+ */
+
+import {
+	createAgentSession,
+	createCodemodeExtension,
+	createMcpExtension,
+	createToolSearchExtension,
+	DefaultResourceLoader,
+	getAgentDir,
+	SessionManager,
+	SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+
+const cwd = process.cwd();
+
+const resourceLoader = new DefaultResourceLoader({
+	cwd,
+	agentDir: getAgentDir(),
+	extensionFactories: [
+		createCodemodeExtension({ mode: "on" }),
+		createToolSearchExtension(),
+		// Reads mcp.json from the agent directory and the trusted project, like the CLI.
+		createMcpExtension(),
+	],
+});
+await resourceLoader.reload();
+
+const settingsManager = SettingsManager.create(cwd);
+// `+name` adds to the configured default tools instead of replacing them.
+settingsManager.applyOverrides({ defaultTools: ["+codemode", "+tool_search"] });
+
+const { session } = await createAgentSession({
+	resourceLoader,
+	settingsManager,
+	sessionManager: SessionManager.inMemory(),
+});
+
+try {
+	// Emits session_start, which connects the MCP servers in the background.
+	await session.bindExtensions({});
+	console.log("Active tools:", session.getActiveToolNames().join(", "));
+	session.subscribe((event) => {
+		if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+			process.stdout.write(event.assistantMessageEvent.delta);
+		}
+	});
+	await session.prompt("Use codemode to count the TypeScript files in src/ and list the three largest.");
+	console.log();
+} finally {
+	session.dispose();
+}

package/examples/sdk/README.md

@@ -21,6 +21,7 @@ The runtime example shows how to build a recreate function that closes over proc
 | `11-sessions.ts` | In-memory, persistent, continue, list sessions |
 | `12-full-control.ts` | Replace everything, no discovery |
 | `13-session-runtime.ts` | Manage runtime-backed session replacement |
+| `14-codemode-mcp.ts` | Add the `codemode`, `tool_search`, and MCP extensions |
 
 ## Running