@hyperspaceng/neural-coding-agent 0.63.0 → 0.63.2

package/dist/modes/print-mode.d.ts

@@ -24,5 +24,5 @@ export interface PrintModeOptions {
  * Run in print (single-shot) mode.
  * Sends prompts to the agent and outputs the result.
  */
-export declare function runPrintMode(session: AgentSession, options: PrintModeOptions): Promise<void>;
+export declare function runPrintMode(session: AgentSession, options: PrintModeOptions): Promise<number>;
 //# sourceMappingURL=print-mode.d.ts.map

package/dist/modes/print-mode.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"print-mode.d.ts","sourceRoot":"","sources":["../../src/modes/print-mode.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAyFlG","sourcesContent":["/**\n * Print mode (single-shot): Send prompts, output result, exit.\n *\n * Used for:\n * - `pi -p \"prompt\"` - text output\n * - `pi --mode json \"prompt\"` - JSON event stream\n */\n\nimport type { AssistantMessage, ImageContent } from \"@hyperspaceng/neural-ai\";\nimport type { AgentSession } from \"../core/agent-session.js\";\nimport { flushRawStdout, writeRawStdout } from \"../core/output-guard.js\";\n\n/**\n * Options for print mode.\n */\nexport interface PrintModeOptions {\n\t/** Output mode: \"text\" for final response only, \"json\" for all events */\n\tmode: \"text\" | \"json\";\n\t/** Array of additional prompts to send after initialMessage */\n\tmessages?: string[];\n\t/** First message to send (may contain @file content) */\n\tinitialMessage?: string;\n\t/** Images to attach to the initial message */\n\tinitialImages?: ImageContent[];\n}\n\n/**\n * Run in print (single-shot) mode.\n * Sends prompts to the agent and outputs the result.\n */\nexport async function runPrintMode(session: AgentSession, options: PrintModeOptions): Promise<void> {\n\tconst { mode, messages = [], initialMessage, initialImages } = options;\n\tif (mode === \"json\") {\n\t\tconst header = session.sessionManager.getHeader();\n\t\tif (header) {\n\t\t\twriteRawStdout(`${JSON.stringify(header)}\\n`);\n\t\t}\n\t}\n\t// Set up extensions for print mode (no UI)\n\tawait session.bindExtensions({\n\t\tcommandContextActions: {\n\t\t\twaitForIdle: () => session.agent.waitForIdle(),\n\t\t\tnewSession: async (options) => {\n\t\t\t\tconst success = await session.newSession({ parentSession: options?.parentSession });\n\t\t\t\tif (success && options?.setup) {\n\t\t\t\t\tawait options.setup(session.sessionManager);\n\t\t\t\t}\n\t\t\t\treturn { cancelled: !success };\n\t\t\t},\n\t\t\tfork: async (entryId) => {\n\t\t\t\tconst result = await session.fork(entryId);\n\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t},\n\t\t\tnavigateTree: async (targetId, options) => {\n\t\t\t\tconst result = await session.navigateTree(targetId, {\n\t\t\t\t\tsummarize: options?.summarize,\n\t\t\t\t\tcustomInstructions: options?.customInstructions,\n\t\t\t\t\treplaceInstructions: options?.replaceInstructions,\n\t\t\t\t\tlabel: options?.label,\n\t\t\t\t});\n\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t},\n\t\t\tswitchSession: async (sessionPath) => {\n\t\t\t\tconst success = await session.switchSession(sessionPath);\n\t\t\t\treturn { cancelled: !success };\n\t\t\t},\n\t\t\treload: async () => {\n\t\t\t\tawait session.reload();\n\t\t\t},\n\t\t},\n\t\tonError: (err) => {\n\t\t\tconsole.error(`Extension error (${err.extensionPath}): ${err.error}`);\n\t\t},\n\t});\n\n\t// Always subscribe to enable session persistence via _handleAgentEvent\n\tsession.subscribe((event) => {\n\t\t// In JSON mode, output all events\n\t\tif (mode === \"json\") {\n\t\t\twriteRawStdout(`${JSON.stringify(event)}\\n`);\n\t\t}\n\t});\n\n\t// Send initial message with attachments\n\tif (initialMessage) {\n\t\tawait session.prompt(initialMessage, { images: initialImages });\n\t}\n\n\t// Send remaining messages\n\tfor (const message of messages) {\n\t\tawait session.prompt(message);\n\t}\n\n\t// In text mode, output final response\n\tif (mode === \"text\") {\n\t\tconst state = session.state;\n\t\tconst lastMessage = state.messages[state.messages.length - 1];\n\n\t\tif (lastMessage?.role === \"assistant\") {\n\t\t\tconst assistantMsg = lastMessage as AssistantMessage;\n\n\t\t\t// Check for error/aborted\n\t\t\tif (assistantMsg.stopReason === \"error\" || assistantMsg.stopReason === \"aborted\") {\n\t\t\t\tconsole.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);\n\t\t\t\tprocess.exit(1);\n\t\t\t}\n\n\t\t\t// Output text content\n\t\t\tfor (const content of assistantMsg.content) {\n\t\t\t\tif (content.type === \"text\") {\n\t\t\t\t\twriteRawStdout(`${content.text}\\n`);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t// Ensure stdout is fully flushed before returning\n\t// This prevents race conditions where the process exits before all output is written\n\tawait flushRawStdout();\n}\n"]}
+{"version":3,"file":"print-mode.d.ts","sourceRoot":"","sources":["../../src/modes/print-mode.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAoB,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,yEAAyE;IACzE,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IACtB,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,wDAAwD;IACxD,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,8CAA8C;IAC9C,aAAa,CAAC,EAAE,YAAY,EAAE,CAAC;CAC/B;AAED;;;GAGG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,MAAM,CAAC,CAoGpG","sourcesContent":["/**\n * Print mode (single-shot): Send prompts, output result, exit.\n *\n * Used for:\n * - `pi -p \"prompt\"` - text output\n * - `pi --mode json \"prompt\"` - JSON event stream\n */\n\nimport type { AssistantMessage, ImageContent } from \"@hyperspaceng/neural-ai\";\nimport type { AgentSession } from \"../core/agent-session.js\";\nimport { flushRawStdout, writeRawStdout } from \"../core/output-guard.js\";\n\n/**\n * Options for print mode.\n */\nexport interface PrintModeOptions {\n\t/** Output mode: \"text\" for final response only, \"json\" for all events */\n\tmode: \"text\" | \"json\";\n\t/** Array of additional prompts to send after initialMessage */\n\tmessages?: string[];\n\t/** First message to send (may contain @file content) */\n\tinitialMessage?: string;\n\t/** Images to attach to the initial message */\n\tinitialImages?: ImageContent[];\n}\n\n/**\n * Run in print (single-shot) mode.\n * Sends prompts to the agent and outputs the result.\n */\nexport async function runPrintMode(session: AgentSession, options: PrintModeOptions): Promise<number> {\n\tconst { mode, messages = [], initialMessage, initialImages } = options;\n\tlet exitCode = 0;\n\n\ttry {\n\t\tif (mode === \"json\") {\n\t\t\tconst header = session.sessionManager.getHeader();\n\t\t\tif (header) {\n\t\t\t\twriteRawStdout(`${JSON.stringify(header)}\\n`);\n\t\t\t}\n\t\t}\n\t\t// Set up extensions for print mode (no UI)\n\t\tawait session.bindExtensions({\n\t\t\tcommandContextActions: {\n\t\t\t\twaitForIdle: () => session.agent.waitForIdle(),\n\t\t\t\tnewSession: async (options) => {\n\t\t\t\t\tconst success = await session.newSession({ parentSession: options?.parentSession });\n\t\t\t\t\tif (success && options?.setup) {\n\t\t\t\t\t\tawait options.setup(session.sessionManager);\n\t\t\t\t\t}\n\t\t\t\t\treturn { cancelled: !success };\n\t\t\t\t},\n\t\t\t\tfork: async (entryId) => {\n\t\t\t\t\tconst result = await session.fork(entryId);\n\t\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t\t},\n\t\t\t\tnavigateTree: async (targetId, options) => {\n\t\t\t\t\tconst result = await session.navigateTree(targetId, {\n\t\t\t\t\t\tsummarize: options?.summarize,\n\t\t\t\t\t\tcustomInstructions: options?.customInstructions,\n\t\t\t\t\t\treplaceInstructions: options?.replaceInstructions,\n\t\t\t\t\t\tlabel: options?.label,\n\t\t\t\t\t});\n\t\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t\t},\n\t\t\t\tswitchSession: async (sessionPath) => {\n\t\t\t\t\tconst success = await session.switchSession(sessionPath);\n\t\t\t\t\treturn { cancelled: !success };\n\t\t\t\t},\n\t\t\t\treload: async () => {\n\t\t\t\t\tawait session.reload();\n\t\t\t\t},\n\t\t\t},\n\t\t\tonError: (err) => {\n\t\t\t\tconsole.error(`Extension error (${err.extensionPath}): ${err.error}`);\n\t\t\t},\n\t\t});\n\n\t\t// Always subscribe to enable session persistence via _handleAgentEvent\n\t\tsession.subscribe((event) => {\n\t\t\t// In JSON mode, output all events\n\t\t\tif (mode === \"json\") {\n\t\t\t\twriteRawStdout(`${JSON.stringify(event)}\\n`);\n\t\t\t}\n\t\t});\n\n\t\t// Send initial message with attachments\n\t\tif (initialMessage) {\n\t\t\tawait session.prompt(initialMessage, { images: initialImages });\n\t\t}\n\n\t\t// Send remaining messages\n\t\tfor (const message of messages) {\n\t\t\tawait session.prompt(message);\n\t\t}\n\n\t\t// In text mode, output final response\n\t\tif (mode === \"text\") {\n\t\t\tconst state = session.state;\n\t\t\tconst lastMessage = state.messages[state.messages.length - 1];\n\n\t\t\tif (lastMessage?.role === \"assistant\") {\n\t\t\t\tconst assistantMsg = lastMessage as AssistantMessage;\n\n\t\t\t\t// Check for error/aborted\n\t\t\t\tif (assistantMsg.stopReason === \"error\" || assistantMsg.stopReason === \"aborted\") {\n\t\t\t\t\tconsole.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);\n\t\t\t\t\texitCode = 1;\n\t\t\t\t} else {\n\t\t\t\t\t// Output text content\n\t\t\t\t\tfor (const content of assistantMsg.content) {\n\t\t\t\t\t\tif (content.type === \"text\") {\n\t\t\t\t\t\t\twriteRawStdout(`${content.text}\\n`);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn exitCode;\n\t} finally {\n\t\tconst extensionRunner = session.extensionRunner;\n\t\tif (extensionRunner?.hasHandlers(\"session_shutdown\")) {\n\t\t\tawait extensionRunner.emit({ type: \"session_shutdown\" });\n\t\t}\n\n\t\t// Ensure stdout is fully flushed before returning\n\t\t// This prevents race conditions where the process exits before all output is written\n\t\tawait flushRawStdout();\n\t}\n}\n"]}

package/dist/modes/print-mode.js

@@ -12,84 +12,96 @@ import { flushRawStdout, writeRawStdout } from "../core/output-guard.js";
  */
 export async function runPrintMode(session, options) {
     const { mode, messages = [], initialMessage, initialImages } = options;
-    if (mode === "json") {
-        const header = session.sessionManager.getHeader();
-        if (header) {
-            writeRawStdout(`${JSON.stringify(header)}\n`);
+    let exitCode = 0;
+    try {
+        if (mode === "json") {
+            const header = session.sessionManager.getHeader();
+            if (header) {
+                writeRawStdout(`${JSON.stringify(header)}\n`);
+            }
         }
-    }
-    // Set up extensions for print mode (no UI)
-    await session.bindExtensions({
-        commandContextActions: {
-            waitForIdle: () => session.agent.waitForIdle(),
-            newSession: async (options) => {
-                const success = await session.newSession({ parentSession: options?.parentSession });
-                if (success && options?.setup) {
-                    await options.setup(session.sessionManager);
-                }
-                return { cancelled: !success };
+        // Set up extensions for print mode (no UI)
+        await session.bindExtensions({
+            commandContextActions: {
+                waitForIdle: () => session.agent.waitForIdle(),
+                newSession: async (options) => {
+                    const success = await session.newSession({ parentSession: options?.parentSession });
+                    if (success && options?.setup) {
+                        await options.setup(session.sessionManager);
+                    }
+                    return { cancelled: !success };
+                },
+                fork: async (entryId) => {
+                    const result = await session.fork(entryId);
+                    return { cancelled: result.cancelled };
+                },
+                navigateTree: async (targetId, options) => {
+                    const result = await session.navigateTree(targetId, {
+                        summarize: options?.summarize,
+                        customInstructions: options?.customInstructions,
+                        replaceInstructions: options?.replaceInstructions,
+                        label: options?.label,
+                    });
+                    return { cancelled: result.cancelled };
+                },
+                switchSession: async (sessionPath) => {
+                    const success = await session.switchSession(sessionPath);
+                    return { cancelled: !success };
+                },
+                reload: async () => {
+                    await session.reload();
+                },
             },
-            fork: async (entryId) => {
-                const result = await session.fork(entryId);
-                return { cancelled: result.cancelled };
+            onError: (err) => {
+                console.error(`Extension error (${err.extensionPath}): ${err.error}`);
             },
-            navigateTree: async (targetId, options) => {
-                const result = await session.navigateTree(targetId, {
-                    summarize: options?.summarize,
-                    customInstructions: options?.customInstructions,
-                    replaceInstructions: options?.replaceInstructions,
-                    label: options?.label,
-                });
-                return { cancelled: result.cancelled };
-            },
-            switchSession: async (sessionPath) => {
-                const success = await session.switchSession(sessionPath);
-                return { cancelled: !success };
-            },
-            reload: async () => {
-                await session.reload();
-            },
-        },
-        onError: (err) => {
-            console.error(`Extension error (${err.extensionPath}): ${err.error}`);
-        },
-    });
-    // Always subscribe to enable session persistence via _handleAgentEvent
-    session.subscribe((event) => {
-        // In JSON mode, output all events
-        if (mode === "json") {
-            writeRawStdout(`${JSON.stringify(event)}\n`);
-        }
-    });
-    // Send initial message with attachments
-    if (initialMessage) {
-        await session.prompt(initialMessage, { images: initialImages });
-    }
-    // Send remaining messages
-    for (const message of messages) {
-        await session.prompt(message);
-    }
-    // In text mode, output final response
-    if (mode === "text") {
-        const state = session.state;
-        const lastMessage = state.messages[state.messages.length - 1];
-        if (lastMessage?.role === "assistant") {
-            const assistantMsg = lastMessage;
-            // Check for error/aborted
-            if (assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted") {
-                console.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);
-                process.exit(1);
+        });
+        // Always subscribe to enable session persistence via _handleAgentEvent
+        session.subscribe((event) => {
+            // In JSON mode, output all events
+            if (mode === "json") {
+                writeRawStdout(`${JSON.stringify(event)}\n`);
             }
-            // Output text content
-            for (const content of assistantMsg.content) {
-                if (content.type === "text") {
-                    writeRawStdout(`${content.text}\n`);
+        });
+        // Send initial message with attachments
+        if (initialMessage) {
+            await session.prompt(initialMessage, { images: initialImages });
+        }
+        // Send remaining messages
+        for (const message of messages) {
+            await session.prompt(message);
+        }
+        // In text mode, output final response
+        if (mode === "text") {
+            const state = session.state;
+            const lastMessage = state.messages[state.messages.length - 1];
+            if (lastMessage?.role === "assistant") {
+                const assistantMsg = lastMessage;
+                // Check for error/aborted
+                if (assistantMsg.stopReason === "error" || assistantMsg.stopReason === "aborted") {
+                    console.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);
+                    exitCode = 1;
+                }
+                else {
+                    // Output text content
+                    for (const content of assistantMsg.content) {
+                        if (content.type === "text") {
+                            writeRawStdout(`${content.text}\n`);
+                        }
+                    }
                 }
             }
         }
+        return exitCode;
+    }
+    finally {
+        const extensionRunner = session.extensionRunner;
+        if (extensionRunner?.hasHandlers("session_shutdown")) {
+            await extensionRunner.emit({ type: "session_shutdown" });
+        }
+        // Ensure stdout is fully flushed before returning
+        // This prevents race conditions where the process exits before all output is written
+        await flushRawStdout();
     }
-    // Ensure stdout is fully flushed before returning
-    // This prevents race conditions where the process exits before all output is written
-    await flushRawStdout();
 }
 //# sourceMappingURL=print-mode.js.map

package/dist/modes/print-mode.js.map

@@ -1 +1 @@
-{"version":3,"file":"print-mode.js","sourceRoot":"","sources":["../../src/modes/print-mode.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Print mode (single-shot): Send prompts, output result, exit.\n *\n * Used for:\n * - `pi -p \"prompt\"` - text output\n * - `pi --mode json \"prompt\"` - JSON event stream\n */\n\nimport type { AssistantMessage, ImageContent } from \"@hyperspaceng/neural-ai\";\nimport type { AgentSession } from \"../core/agent-session.js\";\nimport { flushRawStdout, writeRawStdout } from \"../core/output-guard.js\";\n\n/**\n * Options for print mode.\n */\nexport interface PrintModeOptions {\n\t/** Output mode: \"text\" for final response only, \"json\" for all events */\n\tmode: \"text\" | \"json\";\n\t/** Array of additional prompts to send after initialMessage */\n\tmessages?: string[];\n\t/** First message to send (may contain @file content) */\n\tinitialMessage?: string;\n\t/** Images to attach to the initial message */\n\tinitialImages?: ImageContent[];\n}\n\n/**\n * Run in print (single-shot) mode.\n * Sends prompts to the agent and outputs the result.\n */\nexport async function runPrintMode(session: AgentSession, options: PrintModeOptions): Promise<void> {\n\tconst { mode, messages = [], initialMessage, initialImages } = options;\n\tif (mode === \"json\") {\n\t\tconst header = session.sessionManager.getHeader();\n\t\tif (header) {\n\t\t\twriteRawStdout(`${JSON.stringify(header)}\\n`);\n\t\t}\n\t}\n\t// Set up extensions for print mode (no UI)\n\tawait session.bindExtensions({\n\t\tcommandContextActions: {\n\t\t\twaitForIdle: () => session.agent.waitForIdle(),\n\t\t\tnewSession: async (options) => {\n\t\t\t\tconst success = await session.newSession({ parentSession: options?.parentSession });\n\t\t\t\tif (success && options?.setup) {\n\t\t\t\t\tawait options.setup(session.sessionManager);\n\t\t\t\t}\n\t\t\t\treturn { cancelled: !success };\n\t\t\t},\n\t\t\tfork: async (entryId) => {\n\t\t\t\tconst result = await session.fork(entryId);\n\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t},\n\t\t\tnavigateTree: async (targetId, options) => {\n\t\t\t\tconst result = await session.navigateTree(targetId, {\n\t\t\t\t\tsummarize: options?.summarize,\n\t\t\t\t\tcustomInstructions: options?.customInstructions,\n\t\t\t\t\treplaceInstructions: options?.replaceInstructions,\n\t\t\t\t\tlabel: options?.label,\n\t\t\t\t});\n\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t},\n\t\t\tswitchSession: async (sessionPath) => {\n\t\t\t\tconst success = await session.switchSession(sessionPath);\n\t\t\t\treturn { cancelled: !success };\n\t\t\t},\n\t\t\treload: async () => {\n\t\t\t\tawait session.reload();\n\t\t\t},\n\t\t},\n\t\tonError: (err) => {\n\t\t\tconsole.error(`Extension error (${err.extensionPath}): ${err.error}`);\n\t\t},\n\t});\n\n\t// Always subscribe to enable session persistence via _handleAgentEvent\n\tsession.subscribe((event) => {\n\t\t// In JSON mode, output all events\n\t\tif (mode === \"json\") {\n\t\t\twriteRawStdout(`${JSON.stringify(event)}\\n`);\n\t\t}\n\t});\n\n\t// Send initial message with attachments\n\tif (initialMessage) {\n\t\tawait session.prompt(initialMessage, { images: initialImages });\n\t}\n\n\t// Send remaining messages\n\tfor (const message of messages) {\n\t\tawait session.prompt(message);\n\t}\n\n\t// In text mode, output final response\n\tif (mode === \"text\") {\n\t\tconst state = session.state;\n\t\tconst lastMessage = state.messages[state.messages.length - 1];\n\n\t\tif (lastMessage?.role === \"assistant\") {\n\t\t\tconst assistantMsg = lastMessage as AssistantMessage;\n\n\t\t\t// Check for error/aborted\n\t\t\tif (assistantMsg.stopReason === \"error\" || assistantMsg.stopReason === \"aborted\") {\n\t\t\t\tconsole.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);\n\t\t\t\tprocess.exit(1);\n\t\t\t}\n\n\t\t\t// Output text content\n\t\t\tfor (const content of assistantMsg.content) {\n\t\t\t\tif (content.type === \"text\") {\n\t\t\t\t\twriteRawStdout(`${content.text}\\n`);\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\t// Ensure stdout is fully flushed before returning\n\t// This prevents race conditions where the process exits before all output is written\n\tawait flushRawStdout();\n}\n"]}
+{"version":3,"file":"print-mode.js","sourceRoot":"","sources":["../../src/modes/print-mode.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Print mode (single-shot): Send prompts, output result, exit.\n *\n * Used for:\n * - `pi -p \"prompt\"` - text output\n * - `pi --mode json \"prompt\"` - JSON event stream\n */\n\nimport type { AssistantMessage, ImageContent } from \"@hyperspaceng/neural-ai\";\nimport type { AgentSession } from \"../core/agent-session.js\";\nimport { flushRawStdout, writeRawStdout } from \"../core/output-guard.js\";\n\n/**\n * Options for print mode.\n */\nexport interface PrintModeOptions {\n\t/** Output mode: \"text\" for final response only, \"json\" for all events */\n\tmode: \"text\" | \"json\";\n\t/** Array of additional prompts to send after initialMessage */\n\tmessages?: string[];\n\t/** First message to send (may contain @file content) */\n\tinitialMessage?: string;\n\t/** Images to attach to the initial message */\n\tinitialImages?: ImageContent[];\n}\n\n/**\n * Run in print (single-shot) mode.\n * Sends prompts to the agent and outputs the result.\n */\nexport async function runPrintMode(session: AgentSession, options: PrintModeOptions): Promise<number> {\n\tconst { mode, messages = [], initialMessage, initialImages } = options;\n\tlet exitCode = 0;\n\n\ttry {\n\t\tif (mode === \"json\") {\n\t\t\tconst header = session.sessionManager.getHeader();\n\t\t\tif (header) {\n\t\t\t\twriteRawStdout(`${JSON.stringify(header)}\\n`);\n\t\t\t}\n\t\t}\n\t\t// Set up extensions for print mode (no UI)\n\t\tawait session.bindExtensions({\n\t\t\tcommandContextActions: {\n\t\t\t\twaitForIdle: () => session.agent.waitForIdle(),\n\t\t\t\tnewSession: async (options) => {\n\t\t\t\t\tconst success = await session.newSession({ parentSession: options?.parentSession });\n\t\t\t\t\tif (success && options?.setup) {\n\t\t\t\t\t\tawait options.setup(session.sessionManager);\n\t\t\t\t\t}\n\t\t\t\t\treturn { cancelled: !success };\n\t\t\t\t},\n\t\t\t\tfork: async (entryId) => {\n\t\t\t\t\tconst result = await session.fork(entryId);\n\t\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t\t},\n\t\t\t\tnavigateTree: async (targetId, options) => {\n\t\t\t\t\tconst result = await session.navigateTree(targetId, {\n\t\t\t\t\t\tsummarize: options?.summarize,\n\t\t\t\t\t\tcustomInstructions: options?.customInstructions,\n\t\t\t\t\t\treplaceInstructions: options?.replaceInstructions,\n\t\t\t\t\t\tlabel: options?.label,\n\t\t\t\t\t});\n\t\t\t\t\treturn { cancelled: result.cancelled };\n\t\t\t\t},\n\t\t\t\tswitchSession: async (sessionPath) => {\n\t\t\t\t\tconst success = await session.switchSession(sessionPath);\n\t\t\t\t\treturn { cancelled: !success };\n\t\t\t\t},\n\t\t\t\treload: async () => {\n\t\t\t\t\tawait session.reload();\n\t\t\t\t},\n\t\t\t},\n\t\t\tonError: (err) => {\n\t\t\t\tconsole.error(`Extension error (${err.extensionPath}): ${err.error}`);\n\t\t\t},\n\t\t});\n\n\t\t// Always subscribe to enable session persistence via _handleAgentEvent\n\t\tsession.subscribe((event) => {\n\t\t\t// In JSON mode, output all events\n\t\t\tif (mode === \"json\") {\n\t\t\t\twriteRawStdout(`${JSON.stringify(event)}\\n`);\n\t\t\t}\n\t\t});\n\n\t\t// Send initial message with attachments\n\t\tif (initialMessage) {\n\t\t\tawait session.prompt(initialMessage, { images: initialImages });\n\t\t}\n\n\t\t// Send remaining messages\n\t\tfor (const message of messages) {\n\t\t\tawait session.prompt(message);\n\t\t}\n\n\t\t// In text mode, output final response\n\t\tif (mode === \"text\") {\n\t\t\tconst state = session.state;\n\t\t\tconst lastMessage = state.messages[state.messages.length - 1];\n\n\t\t\tif (lastMessage?.role === \"assistant\") {\n\t\t\t\tconst assistantMsg = lastMessage as AssistantMessage;\n\n\t\t\t\t// Check for error/aborted\n\t\t\t\tif (assistantMsg.stopReason === \"error\" || assistantMsg.stopReason === \"aborted\") {\n\t\t\t\t\tconsole.error(assistantMsg.errorMessage || `Request ${assistantMsg.stopReason}`);\n\t\t\t\t\texitCode = 1;\n\t\t\t\t} else {\n\t\t\t\t\t// Output text content\n\t\t\t\t\tfor (const content of assistantMsg.content) {\n\t\t\t\t\t\tif (content.type === \"text\") {\n\t\t\t\t\t\t\twriteRawStdout(`${content.text}\\n`);\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\n\t\treturn exitCode;\n\t} finally {\n\t\tconst extensionRunner = session.extensionRunner;\n\t\tif (extensionRunner?.hasHandlers(\"session_shutdown\")) {\n\t\t\tawait extensionRunner.emit({ type: \"session_shutdown\" });\n\t\t}\n\n\t\t// Ensure stdout is fully flushed before returning\n\t\t// This prevents race conditions where the process exits before all output is written\n\t\tawait flushRawStdout();\n\t}\n}\n"]}

package/docs/development.md

@@ -14,9 +14,11 @@ npm run build
 Run from source:
 
 ```bash
-./pi-test.sh
+/path/to/pi-mono/pi-test.sh
 ```
 
+The script can be run from any directory. Pi keeps the caller's current working directory.
+
 ## Forking / Rebranding
 
 Configure via `package.json`:

package/docs/extensions.md

@@ -293,10 +293,11 @@ Fired by the `pi` CLI during startup session resolution, before the initial sess
 This event is:
 - CLI-only. It is not emitted in SDK mode.
 - Startup-only. It is not emitted for later interactive `/new` or `/resume` actions.
-- Bypassed when `--session-dir` is provided.
+- Lower priority than `--session-dir` and `sessionDir` in `settings.json`.
 - Special-cased to receive no `ctx` argument.
 
 If multiple extensions return `sessionDir`, the last one wins.
+Combined precedence is: `--session-dir` CLI flag, then `sessionDir` in settings, then extension `session_directory` hooks.
 
 ```typescript
 pi.on("session_directory", async (event) => {
@@ -564,17 +565,27 @@ Before `tool_call` runs, pi waits for previously emitted Agent events to finish
 
 In the default parallel tool execution mode, sibling tool calls from the same assistant message are preflighted sequentially, then executed concurrently. `tool_call` is not guaranteed to see sibling tool results from that same assistant message in `ctx.sessionManager`.
 
+`event.input` is mutable. Mutate it in place to patch tool arguments before execution.
+
+Behavior guarantees:
+- Mutations to `event.input` affect the actual tool execution
+- Later `tool_call` handlers see mutations made by earlier handlers
+- No re-validation is performed after your mutation
+- Return values from `tool_call` only control blocking via `{ block: true, reason?: string }`
+
 ```typescript
 import { isToolCallEventType } from "@mariozechner/pi-coding-agent";
 
 pi.on("tool_call", async (event, ctx) => {
   // event.toolName - "bash", "read", "write", "edit", etc.
   // event.toolCallId
-  // event.input - tool parameters
+  // event.input - tool parameters (mutable)
 
   // Built-in tools: no type params needed
   if (isToolCallEventType("bash", event)) {
     // event.input is { command: string; timeout?: number }
+    event.input.command = `source ~/.profile\n${event.input.command}`;
+
     if (event.input.command.includes("rm -rf")) {
       return { block: true, reason: "Dangerous command" };
     }

package/docs/models.md

@@ -131,6 +131,12 @@ The `apiKey` and `headers` fields support three formats:
   "apiKey": "sk-..."
   ```
 
+For `models.json`, shell commands are resolved at request time. pi intentionally does not apply built-in TTL, stale reuse, or recovery logic for arbitrary commands. Different commands need different caching and failure strategies, and pi cannot infer the right one.
+
+If your command is slow, expensive, rate-limited, or should keep using a previous value on transient failures, wrap it in your own script or command that implements the caching or TTL behavior you want.
+
+`/model` availability checks use configured auth presence and do not execute shell commands.
+
 ### Custom Headers
 
 ```json

package/docs/rpc.md

@@ -494,7 +494,7 @@ Response:
 
 #### get_session_stats
 
-Get token usage and cost statistics.
+Get token usage, cost statistics, and current context window usage.
 
 ```json
 {"type": "get_session_stats"}
@@ -521,11 +521,20 @@ Response:
       "cacheWrite": 5000,
       "total": 105000
     },
-    "cost": 0.45
+    "cost": 0.45,
+    "contextUsage": {
+      "tokens": 60000,
+      "contextWindow": 200000,
+      "percent": 30
+    }
   }
 }
 ```
 
+`tokens` contains assistant usage totals for the current session state. `contextUsage` contains the actual current context-window estimate used for compaction and footer display.
+
+`contextUsage` is omitted when no model or context window is available. `contextUsage.tokens` and `contextUsage.percent` are `null` immediately after compaction until a fresh post-compaction assistant response provides valid usage data.
+
 #### export_html
 
 Export session to an HTML file.

package/docs/settings.md

@@ -127,6 +127,18 @@ When a provider requests a retry delay longer than `maxDelayMs` (e.g., Google's
 
 `npmCommand` is used for all npm package-manager operations, including `npm root -g`, installs, uninstalls, and `npm install` inside git packages. Use argv-style entries exactly as the process should be launched.
 
+### Sessions
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `sessionDir` | string | - | Directory where session files are stored. Accepts absolute or relative paths. |
+
+```json
+{ "sessionDir": ".pi/sessions" }
+```
+
+When multiple sources specify a session directory, `--session-dir` CLI flag takes precedence, then `sessionDir` in settings.json, then extension hooks.
+
 ### Model Cycling
 
 | Setting | Type | Default | Description |

package/docs/skills.md

@@ -34,8 +34,9 @@ Pi loads skills from:
 - CLI: `--skill <path>` (repeatable, additive even with `--no-skills`)
 
 Discovery rules:
-- Direct `.md` files in the skills directory root
-- Recursive `SKILL.md` files under subdirectories
+- In `~/.pi/agent/skills/` and `.pi/skills/`, direct root `.md` files are discovered as individual skills
+- In all skill locations, directories containing `SKILL.md` are discovered recursively
+- In `~/.agents/skills/` and project `.agents/skills/`, root `.md` files are ignored
 
 Disable discovery with `--no-skills` (explicit `--skill` paths still load).
 

package/examples/extensions/custom-compaction.ts

@@ -31,9 +31,13 @@ export default function (pi: ExtensionAPI) {
 			return;
 		}
 
-		// Resolve API key for the summarization model
-		const apiKey = await ctx.modelRegistry.getApiKey(model);
-		if (!apiKey) {
+		// Resolve request auth for the summarization model
+		const auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+		if (!auth.ok) {
+			ctx.ui.notify(`Compaction auth failed: ${auth.error}`, "warning");
+			return;
+		}
+		if (!auth.apiKey) {
 			ctx.ui.notify(`No API key for ${model.provider}, using default compaction`, "warning");
 			return;
 		}
@@ -83,7 +87,16 @@ ${conversationText}
 
 		try {
 			// Pass signal to honor abort requests (e.g., user cancels compaction)
-			const response = await complete(model, { messages: summaryMessages }, { apiKey, maxTokens: 8192, signal });
+			const response = await complete(
+				model,
+				{ messages: summaryMessages },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					maxTokens: 8192,
+					signal,
+				},
+			);
 
 			const summary = response.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "1.14.0",
+  "version": "1.14.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "1.14.0",
+      "version": "1.14.2",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-anthropic",
 	"private": true,
-	"version": "1.14.0",
+	"version": "1.14.2",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-gitlab-duo",
 	"private": true,
-	"version": "1.14.0",
+	"version": "1.14.2",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-qwen-cli/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "pi-extension-custom-provider-qwen-cli",
 	"private": true,
-	"version": "1.13.0",
+	"version": "1.13.2",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/handoff.ts

@@ -80,7 +80,10 @@ export default function (pi: ExtensionAPI) {
 				loader.onAbort = () => done(null);
 
 				const doGenerate = async () => {
-					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+					if (!auth.ok || !auth.apiKey) {
+						throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+					}
 
 					const userMessage: Message = {
 						role: "user",
@@ -96,7 +99,7 @@ export default function (pi: ExtensionAPI) {
 					const response = await complete(
 						ctx.model!,
 						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
-						{ apiKey, signal: loader.signal },
+						{ apiKey: auth.apiKey, headers: auth.headers, signal: loader.signal },
 					);
 
 					if (response.stopReason === "aborted") {

package/examples/extensions/qna.ts

@@ -77,7 +77,10 @@ export default function (pi: ExtensionAPI) {
 
 				// Do the work
 				const doExtract = async () => {
-					const apiKey = await ctx.modelRegistry.getApiKey(ctx.model!);
+					const auth = await ctx.modelRegistry.getApiKeyAndHeaders(ctx.model!);
+					if (!auth.ok || !auth.apiKey) {
+						throw new Error(auth.ok ? `No API key for ${ctx.model!.provider}` : auth.error);
+					}
 					const userMessage: UserMessage = {
 						role: "user",
 						content: [{ type: "text", text: lastAssistantText! }],
@@ -87,7 +90,7 @@ export default function (pi: ExtensionAPI) {
 					const response = await complete(
 						ctx.model!,
 						{ systemPrompt: SYSTEM_PROMPT, messages: [userMessage] },
-						{ apiKey, signal: loader.signal },
+						{ apiKey: auth.apiKey, headers: auth.headers, signal: loader.signal },
 					);
 
 					if (response.stopReason === "aborted") {

package/examples/extensions/summarize.ts

@@ -165,12 +165,15 @@ export default function (pi: ExtensionAPI) {
 				ctx.ui.notify("Model openai/gpt-5.2 not found", "warning");
 			}
 
-			const apiKey = model ? await ctx.modelRegistry.getApiKey(model) : undefined;
-			if (!apiKey && ctx.hasUI) {
+			const auth = model ? await ctx.modelRegistry.getApiKeyAndHeaders(model) : undefined;
+			if (auth && !auth.ok && ctx.hasUI) {
+				ctx.ui.notify(auth.error, "warning");
+			}
+			if (auth?.ok && !auth.apiKey && ctx.hasUI) {
 				ctx.ui.notify("No API key for openai/gpt-5.2", "warning");
 			}
 
-			if (!model || !apiKey) {
+			if (!model || !auth?.ok || !auth.apiKey) {
 				return;
 			}
 
@@ -182,7 +185,15 @@ export default function (pi: ExtensionAPI) {
 				},
 			];
 
-			const response = await complete(model, { messages: summaryMessages }, { apiKey, reasoningEffort: "high" });
+			const response = await complete(
+				model,
+				{ messages: summaryMessages },
+				{
+					apiKey: auth.apiKey,
+					headers: auth.headers,
+					reasoningEffort: "high",
+				},
+			);
 
 			const summary = response.content
 				.filter((c): c is { type: "text"; text: string } => c.type === "text")

package/examples/extensions/trigger-compact.ts

@@ -3,6 +3,8 @@ import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-age
 const COMPACT_THRESHOLD_TOKENS = 100_000;
 
 export default function (pi: ExtensionAPI) {
+	let previousTokens: number | null | undefined;
+
 	const triggerCompaction = (ctx: ExtensionContext, customInstructions?: string) => {
 		if (ctx.hasUI) {
 			ctx.ui.notify("Compaction started", "info");
@@ -24,7 +26,15 @@ export default function (pi: ExtensionAPI) {
 
 	pi.on("turn_end", (_event, ctx) => {
 		const usage = ctx.getContextUsage();
-		if (!usage || usage.tokens === null || usage.tokens <= COMPACT_THRESHOLD_TOKENS) {
+		const currentTokens = usage?.tokens ?? null;
+		if (currentTokens === null) {
+			return;
+		}
+
+		const crossedThreshold =
+			previousTokens !== undefined && previousTokens !== null && previousTokens <= COMPACT_THRESHOLD_TOKENS;
+		previousTokens = currentTokens;
+		if (!crossedThreshold || currentTokens <= COMPACT_THRESHOLD_TOKENS) {
 			return;
 		}
 		triggerCompaction(ctx);

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

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

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

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

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@hyperspaceng/neural-coding-agent",
-	"version": "0.63.0",
+	"version": "0.63.2",
 	"description": "Coding agent CLI with read, bash, edit, write tools and session management",
 	"type": "module",
 	"piConfig": {
@@ -40,10 +40,11 @@
 	},
 	"dependencies": {
 		"@mariozechner/jiti": "^2.6.2",
-		"@hyperspaceng/neural-agent-core": "^0.63.0",
-		"@hyperspaceng/neural-ai": "^0.63.0",
-		"@hyperspaceng/neural-tui": "^0.63.0",
+		"@hyperspaceng/neural-agent-core": "^0.63.2",
+		"@hyperspaceng/neural-ai": "^0.63.2",
+		"@hyperspaceng/neural-tui": "^0.63.2",
 		"@silvia-odwyer/photon-node": "^0.3.4",
+		"ajv": "^8.17.1",
 		"chalk": "^5.5.0",
 		"cli-highlight": "^2.1.11",
 		"diff": "^8.0.2",