apex-code 0.5.0 → 0.5.1

package/examples/extensions/custom-provider-anthropic/index.ts

@@ -27,9 +27,11 @@ import {
 	type Api,
 	type AssistantMessage,
 	type AssistantMessageEventStream,
-	type Context,
 	calculateCost,
+	collapseSystemMessages,
 	createAssistantMessageEventStream,
+	getCurrentSystemPrompt,
+	getCurrentTools,
 	type ImageContent,
 	type Message,
 	type Model,
@@ -42,6 +44,7 @@ import {
 	type Tool,
 	type ToolCall,
 	type ToolResultMessage,
+	type TranscriptContext,
 } from "@earendil-works/pi-ai";
 import type { ExtensionAPI } from "apex-code";
 
@@ -334,10 +337,15 @@ function mapStopReason(reason: string): StopReason {
 
 function streamCustomAnthropic(
 	model: Model<Api>,
-	context: Context,
+	context: TranscriptContext,
 	options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
 	const stream = createAssistantMessageEventStream();
+	// The transcript carries the prompt and tools in its system messages. This provider sends
+	// one top-level system prompt, so fold later system messages into the leading one first.
+	const transcript = collapseSystemMessages(context);
+	const systemPrompt = getCurrentSystemPrompt(transcript.messages);
+	const tools = getCurrentTools(transcript.messages);
 
 	(async () => {
 		const output: AssistantMessage = {
@@ -393,7 +401,7 @@ function streamCustomAnthropic(
 			// Build request params
 			const params: MessageCreateParamsStreaming = {
 				model: model.id,
-				messages: convertMessages(context.messages, isOAuth, context.tools),
+				messages: convertMessages(transcript.messages, isOAuth, tools),
 				max_tokens: options?.maxTokens || Math.floor(model.maxTokens / 3),
 				stream: true,
 			};
@@ -407,25 +415,25 @@ function streamCustomAnthropic(
 						cache_control: { type: "ephemeral" },
 					},
 				];
-				if (context.systemPrompt) {
+				if (systemPrompt) {
 					params.system.push({
 						type: "text",
-						text: sanitizeSurrogates(context.systemPrompt),
+						text: sanitizeSurrogates(systemPrompt),
 						cache_control: { type: "ephemeral" },
 					});
 				}
-			} else if (context.systemPrompt) {
+			} else if (systemPrompt) {
 				params.system = [
 					{
 						type: "text",
-						text: sanitizeSurrogates(context.systemPrompt),
+						text: sanitizeSurrogates(systemPrompt),
 						cache_control: { type: "ephemeral" },
 					},
 				];
 			}
 
-			if (context.tools) {
-				params.tools = convertTools(context.tools, isOAuth);
+			if (tools.length > 0) {
+				params.tools = convertTools(tools, isOAuth);
 			}
 
 			// Handle thinking/reasoning
@@ -474,9 +482,7 @@ function streamCustomAnthropic(
 						output.content.push({
 							type: "toolCall",
 							id: event.content_block.id,
-							name: isOAuth
-								? fromClaudeCodeName(event.content_block.name, context.tools)
-								: event.content_block.name,
+							name: isOAuth ? fromClaudeCodeName(event.content_block.name, tools) : event.content_block.name,
 							arguments: {},
 							partialJson: "",
 							index: event.index,

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

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.84.4",
+  "version": "0.87.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.84.4",
+      "version": "0.87.1",
       "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": "0.84.4",
+  "version": "0.87.1",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/index.ts

@@ -13,7 +13,6 @@ import {
 	type Api,
 	type AssistantMessageEventStream,
 	anthropicMessagesApi,
-	type Context,
 	createAssistantMessageEventStream,
 	type Model,
 	type OAuthCredentials,
@@ -21,6 +20,7 @@ import {
 	openAIResponsesApi,
 	type SimpleStreamOptions,
 	type ThinkingLevelMap,
+	type TranscriptContext,
 } from "@earendil-works/pi-ai/compat";
 import type { ExtensionAPI } from "apex-code";
 
@@ -306,7 +306,7 @@ async function refreshGitLabToken(credentials: OAuthCredentials, signal: AbortSi
 
 export function streamGitLabDuo(
 	model: Model<Api>,
-	context: Context,
+	context: TranscriptContext,
 	options?: SimpleStreamOptions,
 ): AssistantMessageEventStream {
 	const stream = createAssistantMessageEventStream();

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

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

package/examples/extensions/dynamic-resources/dynamic.json

@@ -30,6 +30,8 @@
 		"dim": "dimGray",
 		"text": "",
 		"thinkingText": "gray",
+		"scrollbarTrack": "darkGray",
+		"scrollbarThumb": "",
 		"selectedBg": "selectedBg",
 		"userMessageBg": "userMsgBg",
 		"userMessageText": "",

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

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-gondolin",
-	"version": "0.84.4",
+	"version": "0.87.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-gondolin",
-			"version": "0.84.4",
+			"version": "0.87.1",
 			"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.84.4",
+	"version": "0.87.1",
 	"type": "module",
 	"scripts": {
 		"clean": "echo 'nothing to clean'",

package/examples/extensions/prompt-customizer.ts

@@ -1,11 +1,8 @@
 /**
  * Prompt Customizer Extension
  *
- * Demonstrates using systemPromptOptions to make informed, context-aware
- * modifications to the system prompt without re-discovering resources.
- *
- * This extension adds tool-specific guidance based on what tools and skills
- * are currently active, respecting whatever the user has configured.
+ * Demonstrates using systemPromptOptions to add context-aware prompt sections
+ * without replacing or reparsing the complete rendered prompt.
  *
  * Usage:
  * 1. Copy this file to ~/.pi/agent/extensions/ or your project's .pi/extensions/
@@ -14,84 +11,39 @@
 
 import type { BuildSystemPromptOptions, ExtensionAPI } from "apex-code";
 
-/**
- * Adds tool-specific guidance that adapts to the active tool set.
- * Instead of appending one-size-fits-all instructions, this reads what's
- * actually loaded and tailors the guidance accordingly.
- */
-function addToolGuidance(options: BuildSystemPromptOptions, basePrompt: string): string {
+function buildToolGuidance(options: BuildSystemPromptOptions): string {
 	const hasTool = (name: string) => options.selectedTools?.includes(name) ?? false;
-
-	const parts: string[] = [];
+	const rules: string[] = [];
 
 	if (hasTool("read")) {
-		parts.push(
-			"• Use the `read` tool for file contents (supports text and images).",
-			"  - For large files, use `offset` and `limit` to read in chunks.",
+		rules.push(
+			"- Use `read` for file contents; it supports text and images.",
+			"- For large files, use `offset` and `limit` to read in chunks.",
 		);
 	}
-
 	if (hasTool("bash")) {
-		parts.push("• Execute commands with the `bash` tool. Use it for file operations like `ls`, `find`, `grep`.");
+		rules.push("- Use `bash` for file operations such as `ls`, `find`, and `grep`.");
 	}
-
 	if (hasTool("edit")) {
-		parts.push(
-			"• Use the `edit` tool for precise text replacements in files. Match exact content including whitespace.",
-		);
+		rules.push("- Use `edit` for precise text replacements that match existing content exactly.");
 	}
-
 	if (hasTool("write")) {
-		parts.push("• Use the `write` tool to create new files or overwrite existing ones completely.");
+		rules.push("- Use `write` to create new files or replace existing files completely.");
 	}
-
 	if (options.skills && options.skills.length > 0) {
-		const skillNames = options.skills.map((s) => s.name).join(", ");
-		parts.push(`\nAvailable skills: ${skillNames}`, "Use skill documentation for best practices on specific tools.");
+		rules.push(`- Available skills: ${options.skills.map((skill) => skill.name).join(", ")}.`);
 	}
 
-	if (parts.length === 0) {
-		return basePrompt;
-	}
-
-	return `${basePrompt}
-
-## Tool Guidance
-
-${parts.join("\n")}
-`;
-}
-
-/**
- * Merges extension instructions with user-provided append prompts.
- * This respects whatever the user configured via --append-system-prompt
- * flags or files, rather than duplicating that work.
- */
-function mergeWithUserAppend(options: BuildSystemPromptOptions): string {
-	const userAppend = options.appendSystemPrompt;
-	const extensionSpecific = `
-## Extension-Added Context
-
-This prompt includes tool guidance and skill information loaded dynamically.
-If you have additional requirements, configure them via --append-system-prompt or project context files.
-`;
-
-	if (userAppend) {
-		return `${userAppend}\n\n${extensionSpecific}`;
-	}
-
-	return extensionSpecific;
+	return rules.join("\n");
 }
 
 export default function promptCustomizer(pi: ExtensionAPI) {
-	pi.on("before_agent_start", async (event) => {
-		const { systemPrompt, systemPromptOptions } = event;
-
-		const customPrompt = addToolGuidance(systemPromptOptions, systemPrompt);
-		const appendSection = mergeWithUserAppend(systemPromptOptions);
-
-		return {
-			systemPrompt: `${customPrompt}${appendSection}`,
-		};
+	pi.on("before_agent_start", (event) => {
+		const guidance = buildToolGuidance(event.systemPromptOptions);
+		if (guidance) {
+			event.systemPromptOptions.sections.tool_guidance = guidance;
+		} else {
+			delete event.systemPromptOptions.sections.tool_guidance;
+		}
 	});
 }

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

@@ -1,12 +1,12 @@
 {
 	"name": "pi-extension-sandbox",
-	"version": "1.14.4",
+	"version": "1.17.1",
 	"lockfileVersion": 3,
 	"requires": true,
 	"packages": {
 		"": {
 			"name": "pi-extension-sandbox",
-			"version": "1.14.4",
+			"version": "1.17.1",
 			"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.14.4",
+	"version": "1.17.1",
 	"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.84.4",
+  "version": "0.87.1",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-with-deps",
-      "version": "0.84.4",
+      "version": "0.87.1",
       "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.84.4",
+  "version": "0.87.1",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/plugins/pi-example-plugin/README.md

@@ -0,0 +1,38 @@
+# `@earendil-works/pi-example-plugin`
+
+This package provides conventional `session` and `tui` Chord facets. The Session-worker facet provides a remote greeting service. The TUI facet contributes `/hello` and calls that service.
+
+The package needs no build script. Pi asks Chord to discover `src/session.ts` and `src/tui.ts`, builds both entries into its server-owned plugin cache, and sends the TUI artifact to clients.
+
+From the repository root:
+
+```bash
+PI_EXPERIMENTAL=1 ./pi-test.sh server \
+  -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
+```
+
+Alternatively, a client can select the plugin for the Session it creates or resumes on one local server:
+
+```bash
+PI_EXPERIMENTAL=1 ./pi-test.sh client \
+  -e "$PWD/packages/coding-agent/examples/plugins/pi-example-plugin"
+```
+
+Repeat `-e` to select multiple plugin packages. Client paths are resolved locally and sent only to a Unix server; Radius clients cannot select server filesystem paths. The Session and matching TUI facets are stored with that Session, so later server generations and clients can resume it without plugin arguments. Other Sessions and their workers are unaffected. An active Session rejects a different package selection instead of being restarted.
+
+`server -e` establishes the server profile's default Session and TUI facets. Starting an explicit foreground server without `-e` clears that default. Client selection never changes the server's root facet generation.
+
+Run `/hello Armin` in the TUI. After editing a facet, run `/reload`. The server atomically rebuilds the package, reloads the attached Session-worker generation, updates the current TUI generation, and serves the new artifact to future clients.
+
+Package metadata can override or disable conventional entries:
+
+```json
+{
+  "chord": {
+    "facets": {
+      "session": "./src/worker.ts",
+      "tui": false
+    }
+  }
+}
+```

package/examples/plugins/pi-example-plugin/package.json

@@ -0,0 +1,10 @@
+{
+	"name": "@earendil-works/pi-example-plugin",
+	"version": "1.0.0",
+	"private": true,
+	"type": "module",
+	"peerDependencies": {
+		"@earendil-works/chord": "^0.84.4",
+		"apex-code": "^0.5.0"
+	}
+}

package/examples/plugins/pi-example-plugin/src/contract.ts

@@ -0,0 +1,13 @@
+import { type Context, defineService, type ReplicatedState } from "@earendil-works/chord";
+
+export interface ExampleFacetReply {
+	readonly message: string;
+	readonly workerActivations: number;
+}
+
+export interface ExampleFacetService {
+	readonly workerActivations: ReplicatedState<{ count: number }>;
+	greet(input: { readonly name: string }, context: Context): Promise<ExampleFacetReply>;
+}
+
+export const ExampleFacetService = defineService<ExampleFacetService>("pi.example-plugin.greeting");

package/examples/plugins/pi-example-plugin/src/session.ts

@@ -0,0 +1,24 @@
+import { defineFacet } from "@earendil-works/chord";
+import { BACKGROUND_CONTEXT } from "@earendil-works/chord/context";
+import { ExampleFacetService } from "./contract.ts";
+
+export default defineFacet({
+	id: "@earendil-works/pi-example-plugin/session",
+	setup(env) {
+		const workerActivations = env.replicatedState({ count: 0 });
+		env.provide(ExampleFacetService, {
+			workerActivations,
+			async greet({ name }) {
+				return {
+					message: `Hello ${name} from the bundled Session worker facet!!!`,
+					workerActivations: workerActivations.value.count,
+				};
+			},
+		});
+		env.onActivate(() => {
+			workerActivations.change(BACKGROUND_CONTEXT, (draft) => {
+				draft.count += 1;
+			});
+		});
+	},
+});

package/examples/plugins/pi-example-plugin/src/tui.ts

@@ -0,0 +1,31 @@
+import { defineFacet } from "@earendil-works/chord";
+import { AgentController, PresentationUI, SlashCommands } from "apex-code/experimental/plugin";
+import { ExampleFacetService } from "./contract.ts";
+
+export default defineFacet({
+	id: "@earendil-works/pi-example-plugin/tui",
+	setup(env) {
+		const example = env.use(ExampleFacetService);
+		const commands = env.use(SlashCommands);
+		const controller = env.use(AgentController);
+		const ui = env.use(PresentationUI);
+		env.onActivate(() => {
+			env.own(
+				commands.replace({
+					name: "hello",
+					description: "Call the bundled Session worker facet",
+					argumentHint: "<name>",
+					async run(args, context) {
+						const message = args.length === 0 ? "from the TUI" : args;
+						const reply = await example.greet({ name: message }, context);
+						ui.showStatus(
+							`We got this: ${reply.message} Worker activations: ${reply.workerActivations}.`,
+							context,
+						);
+						return controller.prompt({ message: `pong: ${message}`, images: null }, context);
+					},
+				}),
+			);
+		});
+	},
+});

package/examples/rpc-client.ts

@@ -0,0 +1,35 @@
+/**
+ * Run one prompt through an Apex Code RPC child process.
+ *
+ * Build the coding-agent package first, then run:
+ * npx tsx examples/rpc-client.ts "Explain this repository"
+ */
+
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RpcClient } from "apex-code";
+
+const exampleDirectory = dirname(fileURLToPath(import.meta.url));
+const prompt = process.argv.slice(2).join(" ") || "Explain this repository in one paragraph.";
+
+const client = new RpcClient({
+	cliPath: join(exampleDirectory, "../dist/cli.js"),
+	args: ["--no-session"],
+});
+
+const unsubscribe = client.onEvent((event) => {
+	if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
+		process.stdout.write(event.assistantMessageEvent.delta);
+	} else if (event.type === "tool_execution_start") {
+		process.stderr.write(`\n[tool: ${event.toolName}]\n`);
+	}
+});
+
+try {
+	await client.start();
+	await client.promptAndWait(prompt);
+	process.stdout.write("\n");
+} finally {
+	unsubscribe();
+	await client.stop();
+}

package/examples/rpc-extension-ui.ts

@@ -16,7 +16,7 @@
 
 import { spawn } from "node:child_process";
 import { dirname, join } from "node:path";
-import * as readline from "node:readline";
+import { StringDecoder } from "node:string_decoder";
 import { fileURLToPath } from "node:url";
 import {
 	type Component,
@@ -258,7 +258,7 @@ async function main() {
 
 	const agent = spawn(
 		"node",
-		[cliPath, "--mode", "rpc", "--no-session", "--no-extension", "--extension", extensionPath],
+		[cliPath, "--mode", "rpc", "--no-session", "--no-extensions", "--extension", extensionPath],
 		{ stdio: ["pipe", "pipe", "pipe"] },
 	);
 
@@ -518,9 +518,7 @@ async function main() {
 
 	// -- Process agent stdout --
 
-	const stdoutRl = readline.createInterface({ input: agent.stdout!, terminal: false });
-
-	stdoutRl.on("line", (line) => {
+	function handleAgentLine(line: string): void {
 		let data: Record<string, unknown>;
 		try {
 			data = JSON.parse(line);
@@ -583,6 +581,28 @@ async function main() {
 			tui.requestRender();
 			return;
 		}
+	}
+
+	const stdoutDecoder = new StringDecoder("utf8");
+	let stdoutBuffer = "";
+
+	agent.stdout!.on("data", (chunk: Buffer) => {
+		stdoutBuffer += stdoutDecoder.write(chunk);
+		while (true) {
+			const newlineIndex = stdoutBuffer.indexOf("\n");
+			if (newlineIndex === -1) break;
+
+			const line = stdoutBuffer.slice(0, newlineIndex);
+			stdoutBuffer = stdoutBuffer.slice(newlineIndex + 1);
+			handleAgentLine(line.endsWith("\r") ? line.slice(0, -1) : line);
+		}
+	});
+
+	agent.stdout!.on("end", () => {
+		stdoutBuffer += stdoutDecoder.end();
+		if (stdoutBuffer.length > 0) {
+			handleAgentLine(stdoutBuffer.endsWith("\r") ? stdoutBuffer.slice(0, -1) : stdoutBuffer);
+		}
 	});
 
 	// -- User input --

package/examples/sdk/README.md

@@ -15,7 +15,7 @@ The runtime example shows how to build a recreate function that closes over proc
 | `05-tools.ts` | Built-in tool allowlists |
 | `06-extensions.ts` | Logging, blocking, result modification |
 | `07-context-files.ts` | AGENTS.md context files |
-| `08-slash-commands.ts` | File-based slash commands |
+| `08-prompt-templates.ts` | File-based prompt templates |
 | `09-api-keys-and-oauth.ts` | API key resolution, OAuth config |
 | `10-settings.ts` | Override compaction, retry, terminal settings |
 | `11-sessions.ts` | In-memory, persistent, continue, list sessions |