@vanillagreen/pi-claude-bridge 1.0.0

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@vanillagreen/pi-claude-bridge",
+  "version": "1.0.0",
+  "description": "Pi provider bridge that runs Claude Code through the Claude Agent SDK, with opt-in forwarding for Pi prompt context.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "claude-code",
+    "claude-agent-sdk"
+  ],
+  "license": "MIT",
+  "pi": {
+    "extensions": [
+      "./bundle/index.js"
+    ],
+    "image": "https://raw.githubusercontent.com/vanillagreencom/vstack/main/pi-extensions/pi-claude-bridge/assets/claude-bridge1.png"
+  },
+  "vstack": {
+    "extensionManager": {
+      "displayName": "Claude Bridge",
+      "settings": [
+        {
+          "key": "enabled",
+          "label": "Enable Claude bridge provider",
+          "description": "Register claude-bridge models that route Pi turns through Claude Code via the Claude Agent SDK.",
+          "type": "boolean",
+          "default": true,
+          "category": "General",
+          "apply": "reload",
+          "requiresReload": true
+        },
+        {
+          "key": "appendSystemPrompt",
+          "label": "Forward AGENTS.md + skills",
+          "description": "Original bridge behavior: append AGENTS.md and Pi's skills block to Claude Code's claude_code preset prompt.",
+          "type": "boolean",
+          "default": true,
+          "category": "Base Prompt",
+          "apply": "live"
+        },
+        {
+          "key": "includeAppendSystemPromptMd",
+          "label": "Forward APPEND_SYSTEM.md",
+          "description": "Opt in to forwarding project/global APPEND_SYSTEM.md content to Claude Code. Off by default because these files can be Pi-specific.",
+          "type": "boolean",
+          "default": false,
+          "category": "Pi Prompt Context",
+          "apply": "live"
+        },
+        {
+          "key": "includeProjectAgentsHook",
+          "label": "Forward project agents hook",
+          "description": "Forward recognized pi-agents-tmux before_agent_start prompt additions such as the Project Agents/Subagents list. Off by default.",
+          "type": "boolean",
+          "default": false,
+          "category": "Pi Prompt Hooks",
+          "apply": "live"
+        },
+        {
+          "key": "includeTaskPanelHook",
+          "label": "Forward task panel hook",
+          "description": "Forward recognized pi-task-panel workflow reminders from before_agent_start. Off by default.",
+          "type": "boolean",
+          "default": false,
+          "category": "Pi Prompt Hooks",
+          "apply": "live"
+        },
+        {
+          "key": "includeCavemanHook",
+          "label": "Forward caveman hook",
+          "description": "Forward recognized pi-caveman response-style prompt additions from before_agent_start. Off by default.",
+          "type": "boolean",
+          "default": false,
+          "category": "Pi Prompt Hooks",
+          "apply": "live"
+        },
+        {
+          "key": "strictMcpConfig",
+          "label": "Strict MCP config",
+          "description": "When Claude Code filesystem settings are loaded, tell Claude Code to use only MCP servers passed by the bridge, avoiding token-heavy MCP auto-loads.",
+          "type": "boolean",
+          "default": true,
+          "category": "Claude Code",
+          "apply": "live"
+        },
+        {
+          "key": "pathToClaudeCodeExecutable",
+          "label": "Claude executable path",
+          "description": "Optional explicit path to the claude binary. If empty, the bridge auto-detects claude or claude-code on PATH.",
+          "type": "path",
+          "default": "",
+          "category": "Claude Code",
+          "apply": "live"
+        }
+      ]
+    }
+  },
+  "dependencies": {
+    "@anthropic-ai/claude-agent-sdk": "0.2.128",
+    "@anthropic-ai/sdk": "^0.73.0",
+    "cc-session-io": "^0.3.1",
+    "change-case": "^5.4.4"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": "*",
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@mariozechner/pi-ai": "^0.72.1",
+    "@mariozechner/pi-coding-agent": "^0.72.1",
+    "@types/node": "^24.3.0",
+    "esbuild": "^0.28.0",
+    "tsx": "^4.21.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts --bundle --platform=node --format=esm --target=node20 --outfile=bundle/index.js --external:@mariozechner/pi-ai --external:@mariozechner/pi-coding-agent",
+    "prepack": "npm run build",
+    "test:unit": "node --import tsx --test tests/unit-*.mjs",
+    "test": "set -a && [ -f .env.test ] && . .env.test; set +a && npm run test:unit && tests/int-smoke.sh && tests/int-multi-turn.sh && tests/int-cache.sh && node --import tsx --test tests/int-*.mjs",
+    "test:usage": "tests/usage-test.sh",
+    "typecheck": "tsc --noEmit"
+  },
+  "files": [
+    "bundle/",
+    "src/",
+    "assets/",
+    "CHANGELOG.md",
+    "LICENSE",
+    "README.md",
+    "package.json"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vanillagreencom/vstack.git",
+    "directory": "pi-extensions/pi-claude-bridge"
+  },
+  "homepage": "https://github.com/vanillagreencom/vstack/tree/main/pi-extensions/pi-claude-bridge",
+  "bugs": {
+    "url": "https://github.com/vanillagreencom/vstack/issues"
+  },
+  "author": "vanillagreen",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}

package/src/agents-md.ts

@@ -0,0 +1,54 @@
+// AGENTS.md discovery and sanitization for forwarding to Claude Code.
+//
+// Pi uses AGENTS.md for long-lived instructions; Claude Code reads the same
+// content under "# CLAUDE.md". We walk up from cwd looking for AGENTS.md,
+// fall back to ~/.pi/agent/AGENTS.md, and rewrite pi-specific references
+// (~/.pi, .pi/, .pi, pi) to their Claude Code equivalents so any paths or
+// references in the file still resolve inside the CC subprocess.
+
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+
+const GLOBAL_AGENTS_PATH = join(homedir(), ".pi", "agent", "AGENTS.md");
+
+export function resolveAgentsMdPath(): string | undefined {
+	const fromCwd = findAgentsMdInParents(process.cwd());
+	if (fromCwd) return fromCwd;
+	if (existsSync(GLOBAL_AGENTS_PATH)) return GLOBAL_AGENTS_PATH;
+	return undefined;
+}
+
+export function findAgentsMdInParents(startDir: string): string | undefined {
+	let current = resolve(startDir);
+	while (true) {
+		const candidate = join(current, "AGENTS.md");
+		if (existsSync(candidate)) return candidate;
+		const parent = dirname(current);
+		if (parent === current) break;
+		current = parent;
+	}
+	return undefined;
+}
+
+export function extractAgentsAppend(): string | undefined {
+	const agentsPath = resolveAgentsMdPath();
+	if (!agentsPath) return undefined;
+	try {
+		const content = readFileSync(agentsPath, "utf-8").trim();
+		if (!content) return undefined;
+		const sanitized = sanitizeAgentsContent(content);
+		return sanitized.length > 0 ? `# CLAUDE.md\n\n${sanitized}` : undefined;
+	} catch {
+		return undefined;
+	}
+}
+
+export function sanitizeAgentsContent(content: string): string {
+	let sanitized = content;
+	sanitized = sanitized.replace(/~\/\.pi\b/gi, "~/.claude");
+	sanitized = sanitized.replace(/(^|[\s'"`])\.pi\//g, "$1.claude/");
+	sanitized = sanitized.replace(/\b\.pi\b/gi, ".claude");
+	sanitized = sanitized.replace(/\bpi\b/gi, "environment");
+	return sanitized;
+}

package/src/config.ts

@@ -0,0 +1,144 @@
+// User-facing extension config. Legacy config is loaded from
+// ~/.pi/agent/claude-bridge.json and .pi/claude-bridge.json. vstack extension
+// manager config is loaded from settings.json and overrides legacy files.
+
+import type { SettingSource } from "@anthropic-ai/claude-agent-sdk";
+import { existsSync, readFileSync } from "fs";
+import { homedir } from "os";
+import { dirname, join, resolve } from "path";
+
+export const PACKAGE_ID = "pi-claude-bridge";
+export const SCOPED_PACKAGE_ID = "@vanillagreen/pi-claude-bridge";
+
+export interface Config {
+	enabled?: boolean;
+	/** Low-level Claude Agent SDK plumbing. Most users won't need these. */
+	provider?: {
+		appendSystemPrompt?: boolean;
+		settingSources?: SettingSource[];
+		strictMcpConfig?: boolean;
+		pathToClaudeCodeExecutable?: string;
+	};
+	/** Extra Pi context forwarded to Claude Code on top of AGENTS.md + skills. */
+	promptContext?: {
+		includeAppendSystemPromptMd?: boolean;
+		includeProjectAgentsHook?: boolean;
+		includeTaskPanelHook?: boolean;
+		includeCavemanHook?: boolean;
+	};
+}
+
+type SettingsRecord = Record<string, unknown>;
+
+function expandHome(input: string): string {
+	if (input === "~") return homedir();
+	if (input.startsWith("~/")) return join(homedir(), input.slice(2));
+	return input;
+}
+
+function piUserDir(): string {
+	return resolve(expandHome(process.env.PI_CODING_AGENT_DIR?.trim() || "~/.pi/agent"));
+}
+
+function asRecord(value: unknown): SettingsRecord | undefined {
+	return value && typeof value === "object" && !Array.isArray(value) ? value as SettingsRecord : undefined;
+}
+
+function mergeDeep<T extends SettingsRecord>(target: T, source: SettingsRecord): T {
+	for (const [key, value] of Object.entries(source)) {
+		const current = asRecord(target[key]);
+		const incoming = asRecord(value);
+		if (current && incoming) target[key as keyof T] = mergeDeep({ ...current }, incoming) as T[keyof T];
+		else target[key as keyof T] = value as T[keyof T];
+	}
+	return target;
+}
+
+function projectSettingsPath(cwd: string): string {
+	let current = resolve(cwd);
+	while (true) {
+		const candidate = join(current, ".pi", "settings.json");
+		if (existsSync(candidate)) return candidate;
+		if (existsSync(join(current, ".pi")) || existsSync(join(current, ".git")) || existsSync(join(current, ".vstack-lock.json"))) return candidate;
+		const parent = dirname(current);
+		if (parent === current) return join(resolve(cwd), ".pi", "settings.json");
+		current = parent;
+	}
+}
+
+function settingsPaths(cwd: string): string[] {
+	return [join(piUserDir(), "settings.json"), projectSettingsPath(cwd)];
+}
+
+export function tryParseJson(path: string): Partial<Config> {
+	if (!existsSync(path)) return {};
+	try {
+		return JSON.parse(readFileSync(path, "utf-8"));
+	} catch (e) {
+		console.error(`claude-bridge: failed to parse ${path}: ${e}`);
+		return {};
+	}
+}
+
+function readManagerConfig(cwd: string): SettingsRecord {
+	const merged: SettingsRecord = {};
+	for (const path of settingsPaths(cwd)) {
+		if (!existsSync(path)) continue;
+		try {
+			const parsed = JSON.parse(readFileSync(path, "utf8"));
+			const configRoot = asRecord(asRecord(asRecord(parsed?.vstack)?.extensionManager)?.config);
+			const config = asRecord(configRoot?.[PACKAGE_ID]) ?? asRecord(configRoot?.[SCOPED_PACKAGE_ID]);
+			if (config) mergeDeep(merged, config);
+		} catch {
+			// Ignore malformed optional manager config; Pi will surface settings issues elsewhere.
+		}
+	}
+	return merged;
+}
+
+function boolFrom(raw: SettingsRecord, key: string): boolean | undefined {
+	return typeof raw[key] === "boolean" ? raw[key] as boolean : undefined;
+}
+
+function stringFrom(raw: SettingsRecord, key: string): string | undefined {
+	const value = raw[key];
+	return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function managerToConfig(raw: SettingsRecord): Partial<Config> {
+	const provider: Config["provider"] = {};
+	const promptContext: Config["promptContext"] = {};
+
+	const appendSystemPrompt = boolFrom(raw, "appendSystemPrompt");
+	if (appendSystemPrompt !== undefined) provider.appendSystemPrompt = appendSystemPrompt;
+	const strictMcpConfig = boolFrom(raw, "strictMcpConfig");
+	if (strictMcpConfig !== undefined) provider.strictMcpConfig = strictMcpConfig;
+	const claudePath = stringFrom(raw, "pathToClaudeCodeExecutable");
+	if (claudePath) provider.pathToClaudeCodeExecutable = claudePath;
+
+	const includeAppendSystemPromptMd = boolFrom(raw, "includeAppendSystemPromptMd");
+	if (includeAppendSystemPromptMd !== undefined) promptContext.includeAppendSystemPromptMd = includeAppendSystemPromptMd;
+	const includeProjectAgentsHook = boolFrom(raw, "includeProjectAgentsHook");
+	if (includeProjectAgentsHook !== undefined) promptContext.includeProjectAgentsHook = includeProjectAgentsHook;
+	const includeTaskPanelHook = boolFrom(raw, "includeTaskPanelHook");
+	if (includeTaskPanelHook !== undefined) promptContext.includeTaskPanelHook = includeTaskPanelHook;
+	const includeCavemanHook = boolFrom(raw, "includeCavemanHook");
+	if (includeCavemanHook !== undefined) promptContext.includeCavemanHook = includeCavemanHook;
+
+	return {
+		...(boolFrom(raw, "enabled") !== undefined ? { enabled: boolFrom(raw, "enabled") } : {}),
+		...(Object.keys(provider).length ? { provider } : {}),
+		...(Object.keys(promptContext).length ? { promptContext } : {}),
+	};
+}
+
+export function loadConfig(cwd: string): Config {
+	const global = tryParseJson(join(piUserDir(), "claude-bridge.json"));
+	const project = tryParseJson(join(cwd, ".pi", "claude-bridge.json"));
+	const manager = managerToConfig(readManagerConfig(cwd));
+	return {
+		enabled: manager.enabled ?? project.enabled ?? global.enabled ?? true,
+		provider: { ...global.provider, ...project.provider, ...manager.provider },
+		promptContext: { ...global.promptContext, ...project.promptContext, ...manager.promptContext },
+	};
+}

package/src/convert.ts

@@ -0,0 +1,100 @@
+// Pure pi→Anthropic message conversion helpers.
+// Extracted so they can be tested without pulling in the full extension runtime.
+
+import type { Message as PiMessage } from "@mariozechner/pi-ai";
+import type { Message as SessionMessage } from "cc-session-io";
+import { pascalCase } from "change-case";
+
+export const PROVIDER_ID = "claude-bridge";
+
+export const PI_TO_SDK_TOOL_NAME: Record<string, string> = {
+	read: "Read", write: "Write", edit: "Edit", bash: "Bash",
+};
+
+export function sanitizeToolId(id: string, cache: Map<string, string>): string {
+	const existing = cache.get(id);
+	if (existing) return existing;
+	const clean = id.replace(/[^a-zA-Z0-9_-]/g, "_");
+	cache.set(id, clean);
+	return clean;
+}
+
+export function mapPiToolNameToSdk(name: string, customToolNameToSdk?: Map<string, string>): string {
+	if (!name) return "";
+	const normalized = name.toLowerCase();
+	if (customToolNameToSdk) {
+		const mapped = customToolNameToSdk.get(name) ?? customToolNameToSdk.get(normalized);
+		if (mapped) return mapped;
+	}
+	if (PI_TO_SDK_TOOL_NAME[normalized]) return PI_TO_SDK_TOOL_NAME[normalized];
+	return pascalCase(name);
+}
+
+export function messageContentToText(
+	content: string | Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts = [];
+	let hasText = false;
+	for (const block of content) {
+		if (block.type === "text" && block.text) { parts.push(block.text); hasText = true; }
+		else if (block.type !== "text" && block.type !== "image") { parts.push(`[${block.type}]`); }
+	}
+	return hasText ? parts.join("\n") : "";
+}
+
+/** Convert pi message array to Anthropic API format. */
+export function convertPiMessages(
+	messages: PiMessage[],
+	customToolNameToSdk?: Map<string, string>,
+): { anthropicMessages: SessionMessage[]; sanitizedIds: Map<string, string> } {
+	const anthropicMessages = [];
+	const sanitizedIds = new Map();
+
+	for (const msg of messages) {
+		if (msg.role === "user") {
+			if (typeof msg.content === "string") {
+				anthropicMessages.push({ role: "user", content: msg.content || "[empty]" });
+			} else if (Array.isArray(msg.content)) {
+				const parts = [];
+				for (const block of msg.content) {
+					if (block.type === "text" && block.text) parts.push({ type: "text", text: block.text });
+					else if (block.type === "image" && block.data && block.mimeType) {
+						parts.push({ type: "image", source: { type: "base64", media_type: block.mimeType, data: block.data } });
+					}
+				}
+				anthropicMessages.push({ role: "user", content: parts.length ? parts : "[image]" });
+			} else {
+				anthropicMessages.push({ role: "user", content: "[empty]" });
+			}
+		} else if (msg.role === "assistant") {
+			const content = Array.isArray(msg.content) ? msg.content : [];
+			const blocks = [];
+			for (const block of content) {
+				if (block.type === "text" && block.text) {
+					blocks.push({ type: "text", text: block.text });
+				} else if (block.type === "thinking") {
+					const sig = block.thinkingSignature;
+					const isAnthropicProvider = msg.provider === PROVIDER_ID || msg.api === "anthropic";
+					if (isAnthropicProvider && sig) {
+						blocks.push({ type: "thinking", thinking: block.thinking ?? "", signature: sig });
+					}
+				} else if (block.type === "toolCall") {
+					const toolName = mapPiToolNameToSdk(block.name, customToolNameToSdk);
+					blocks.push({ type: "tool_use", id: sanitizeToolId(block.id, sanitizedIds), name: toolName, input: block.arguments ?? {} });
+				}
+			}
+			if (!blocks.length) blocks.push({ type: "text", text: "[incompatible content omitted]" });
+			anthropicMessages.push({ role: "assistant", content: blocks });
+		} else if (msg.role === "toolResult") {
+			const text = typeof msg.content === "string" ? msg.content : messageContentToText(msg.content);
+			anthropicMessages.push({
+				role: "user",
+				content: [{ type: "tool_result", tool_use_id: sanitizeToolId(msg.toolCallId, sanitizedIds), content: text || "", is_error: msg.isError }],
+			});
+		}
+	}
+
+	return { anthropicMessages, sanitizedIds };
+}

package/src/extract-tool-results.ts

@@ -0,0 +1,47 @@
+// Tool-result extraction: walks the context tail to collect this turn's
+// tool results. Pi appends results to context and calls the provider again;
+// this scrapes them back out. Walks past user messages (steer/followUp) that
+// pi may inject between toolResults. Stops at the nearest assistant message
+// (turn boundary).
+// Extracted from index.ts so tests can import without activating the extension.
+
+export type McpContent = Array<
+	| { type: "text"; text: string }
+	| { type: "image"; data: string; mimeType: string }
+>;
+
+export interface McpResult {
+	content: McpContent;
+	isError?: boolean;
+	toolCallId?: string;
+	[key: string]: unknown;
+}
+
+export function toolResultToMcpContent(
+	content: string | Array<{ type: string; text?: string; data?: string; mimeType?: string }>,
+): McpContent {
+	if (typeof content === "string") return [{ type: "text", text: content || "" }];
+	if (!Array.isArray(content)) return [{ type: "text", text: "" }];
+	const blocks: McpContent = [];
+	for (const block of content) {
+		if (block.type === "text" && block.text) blocks.push({ type: "text", text: block.text });
+		else if (block.type === "image" && block.data && block.mimeType) blocks.push({ type: "image", data: block.data, mimeType: block.mimeType });
+	}
+	return blocks.length ? blocks : [{ type: "text", text: "" }];
+}
+
+// Returns { results, stopIdx } so callers can log the walk boundary.
+export function extractAllToolResults(
+	messages: Array<{ role: string; content?: unknown; toolCallId?: string; isError?: boolean; [key: string]: unknown }>,
+): { results: McpResult[]; stopIdx: number } {
+	const results: McpResult[] = [];
+	let stopIdx = -1;
+	for (let i = messages.length - 1; i >= 0; i--) {
+		const msg = messages[i];
+		if (msg.role === "toolResult") {
+			results.unshift({ content: toolResultToMcpContent(msg.content as string | Array<{ type: string; text?: string; data?: string; mimeType?: string }>), isError: msg.isError, toolCallId: msg.toolCallId });
+		} else if (msg.role === "assistant") { stopIdx = i; break; }
+		// user messages: skip (steer/followUp injected mid-tool-execution)
+	}
+	return { results, stopIdx };
+}