pi-codebuddy-sdk 0.1.18 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Eli Dickinson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,107 +1,130 @@
 # pi-codebuddy-sdk
 
-回退到 `@tencent-ai/agent-sdk` 的 Pi provider 扩展。无反向代理，直接使用本地 CodeBuddy CLI，合规安全。
+Pi extension that registers **CodeBuddy** as a model provider. You keep using Pi for the TUI, tools, skills, and extensions; CodeBuddy Agent SDK runs inference locally via the `codebuddy` CLI. No HTTP proxy and no changes to how you work in Pi beyond picking a model.
 
-## 安装
+## What it does
 
-### 方式 1：全局安装（日常使用）
+- Exposes CodeBuddy models in Pi (`codebuddy/...` in `/model`)
+- Bridges Pi tools to the SDK (Pi still executes tools; CodeBuddy only plans and calls them)
+- Forwards Pi's system prompt, skills, and project `AGENTS.md` so the model acts as Pi—not as standalone CodeBuddy Code
+- Supports session resume, compaction, streaming, thinking levels, and images
+- Optional **AskCodebuddy** tool to delegate a focused sub-task to another CodeBuddy call
+
+## Install
 
 ```bash
-ln -s ~/Desktop/pi-codebuddy/src ~/.pi/agent/extensions/pi-codebuddy
-cd ~/Desktop/pi-codebuddy && npm install
+pi install npm:pi-codebuddy-sdk
 ```
 
-重启 Pi 即可自动发现。
+Restart `pi` if it was already running.
 
-### 方式 2：临时加载（测试）
+## Requirements
 
-```bash
-pi -e ~/Desktop/pi-codebuddy/src/index.ts --provider codebuddy --model <model>
-```
+- **`codebuddy` on your `PATH`** — the extension spawns the same CLI you use standalone. If `which codebuddy` fails, either add it to `PATH` or set `pathToCodebuddyCode` in `codebuddy-sdk.json` (see [Configuration](#configuration)).
+- **CodeBuddy auth already working** — if `codebuddy` works in your terminal, you do not need extra setup for this extension.
+
+## Quick start (already using CodeBuddy)
+
+No `codebuddy-sdk.json` and no plugin-specific env vars are required.
+
+1. `pi install npm:pi-codebuddy-sdk`
+2. Restart `pi`
+3. `/model` → pick `codebuddy/...`
 
-## 认证
+Optional: set `defaultProvider` / `defaultModel` in `~/.pi/agent/settings.json` so you skip `/model` each time.
 
-CodeBuddy SDK 从本地环境读取凭证，优先级：
+The first query after startup may take a few seconds while models are discovered from the SDK.
 
-### 1. 已通过 CLI 登录（自动，无需配置）
+## Auth
+
+The extension does not store credentials. The CodeBuddy CLI reads them from your machine. Use **one** of the following:
+
+### 1. CLI login (recommended)
 
 ```bash
-# 如果已登录 CodeBuddy CLI，SDK 自动复用凭证
 codebuddy login
 ```
 
-### 2. API Key（手动设置）
+Complete login in the browser. Credentials stay on your machine; Pi reuses them automatically.
+
+### 2. API key
 
 ```bash
-# 国际版
-export CODEBUDDY_API_KEY="your-key"
+export CODEBUDDY_API_KEY="your-api-key"
+```
+
+Obtain the key from your CodeBuddy account. Do not commit it or store it in repo files.
 
-# 中国版
-export CODEBUDDY_API_KEY="your-key"
-export CODEBUDDY_INTERNET_ENVIRONMENT=internal
+### 3. Tencent iOA (internal network)
 
-# iOA 版（企业内）
-export CODEBUDDY_API_KEY="your-key"
+```bash
 export CODEBUDDY_INTERNET_ENVIRONMENT=ioa
+codebuddy login
 ```
 
-**获取 API Key：**
+Use this when CodeBuddy must run on the iOA network. Add `CODEBUDDY_API_KEY` as well if your environment requires it.
 
-| 版本 | 地址 |
-|------|------|
-| 国际版 | https://www.codebuddy.ai/profile/keys |
-| 中国版 | https://copilot.tencent.com/profile/ |
-| iOA | https://tencent.sso.copilot.tencent.com/profile/keys |
+## Usage
 
-## 使用
+```text
+pi
+/model
+```
 
-```bash
-# 列出 codebuddy 所有模型
-pi --list-models
+Pick any entry prefixed with `codebuddy/` (for example `codebuddy/hy3-preview-agent-ioa`).
 
-# 使用指定模型
-pi --provider codebuddy --model claude-sonnet-4.6
+Tools, skills, extensions, `/compact`, and steer behave the same as with other Pi providers.
 
-# 或进入 Pi 后切换
-/model codebuddy/claude-sonnet-4.6
-```
+## Configuration
 
-### 推荐模型
+**Optional.** Defaults work for most users.
 
-| 模型 | 说明 |
-|------|------|
-| `claude-sonnet-4.6` | Claude Sonnet 4.6，支持 thinking |
-| `claude-opus-4.8` | Claude Opus 4.8，支持 thinking + image |
-| `gemini-3.1-pro` | Gemini 3.1 Pro，支持 thinking + image |
-| `gpt-5.5` | GPT-5.5，支持 thinking + image |
-| `hy3-preview-agent-ioa` | 混元 3 Preview，iOA 内免费无限额度 |
+File: `~/.pi/agent/codebuddy-sdk.json` or `.pi/codebuddy-sdk.json` in a project.
 
-## 特性
+```json
+{
+  "askCodebuddy": {
+    "enabled": true,
+    "allowFullMode": true
+  },
+  "provider": {
+    "appendSystemPrompt": true,
+    "strictMcpConfig": true,
+    "pathToCodebuddyCode": "/path/to/codebuddy"
+  }
+}
+```
+
+| Option | Default | Meaning |
+|--------|---------|---------|
+| `askCodebuddy.enabled` | `true` | Register the AskCodebuddy delegation tool |
+| `askCodebuddy.allowFullMode` | `true` | Allow write-capable delegation mode |
+| `provider.appendSystemPrompt` | `true` | Use Pi's system prompt instead of CodeBuddy's default identity |
+| `provider.strictMcpConfig` | `true` | Use only Pi-bridged MCP tools |
+| `provider.pathToCodebuddyCode` | auto | Path to `codebuddy` when it is **not** on `PATH` |
+
+## Privacy
 
-| 特性 | 说明 |
-|------|------|
-| **动态模型发现** | 启动时从 CodeBuddy SDK 拉取 29 个模型，自动标注 thinking/image 能力 |
-| **Session 池复用** | 多轮对话复用同一 CodeBuddy CLI 进程，首轮后每轮省 ~6s 启动 |
-| **Thinking 控制** | Pi 的 thinking level 映射到 CodeBuddy 的 thinking/effort 参数 |
-| **Image 输入** | 原生支持 Claude/Gemini/GPT 的多模态图片输入 |
-| **Abort 处理** | Esc 取消 → CodeBuddy `interrupt()`，干净终止 |
-| **Token 统计** | 包含 cache_read / cache_write / total_cost_usd |
-| **YOLO 模式** | `bypassPermissions`，所有工具自动批准（与 pi-cursor-sdk 一致） |
+- The extension does **not** send conversation data to this repository or any third-party telemetry endpoint.
+- Credentials are handled entirely by the CodeBuddy CLI on your machine.
+- Optional debug mode (`CODEBUDDY_SDK_DEBUG=1`) writes **local** logs under `~/.pi/agent/`; paths are redacted, prompts and tool payloads are not logged. Delete logs when finished.
 
-## FAQ
+## Troubleshooting
 
-**Q: 和 pi-cursor-sdk 有什么区别？**
+```bash
+export CODEBUDDY_SDK_DEBUG=1
+```
 
-pi-cursor-sdk 需要自建 MCP bridge 桥接 Cursor SDK 工具，pi-codebuddy SDK 原生处理工具执行，代码量减少 60%+。
+Default log: `~/.pi/agent/codebuddy-sdk.log`. See [CONTRIBUTING.md](CONTRIBUTING.md) for maintainer details.
 
-**Q: 怎么查看当前用了多少 tokens？**
+## Development
 
-每次回复后 Pi 会显示 usage，包含 input/output/cache/total 及费用。
+Maintainers: [CONTRIBUTING.md](CONTRIBUTING.md).
 
-**Q: maxTurns 限制？**
+## License
 
-100（安全上限）。CodeBuddy agent 完成任务会自动停止，不会循环满。
+MIT
 
-**Q: 支持哪些 CodeBuddy 版本？**
+## Inspiration
 
-CodeBuddy CLI ≥ 2.x（`@tencent-ai/agent-sdk` ≥ 0.3.0）。
+Early MCP bridge patterns were inspired by [pi-claude-bridge](https://github.com/elidickinson/pi-claude-bridge). This package is a separate codebase on [@tencent-ai/agent-sdk](https://www.npmjs.com/package/@tencent-ai/agent-sdk).

package/package.json

@@ -1,11 +1,17 @@
 {
   "name": "pi-codebuddy-sdk",
-  "version": "0.1.18",
-  "description": "CodeBuddy Agent SDK provider for Pi — native tool execution, 29+ models, thinking controls, session pool",
+  "version": "0.3.0",
+  "description": "Pi extension that uses CodeBuddy (via Agent SDK) as a model provider and adds an AskCodebuddy tool.",
   "author": "slahser",
   "license": "MIT",
   "type": "module",
-  "repository": "github:RealAlexandreAI/pi-codebuddy-sdk",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/RealAlexandreAI/pi-codebuddy-sdk.git"
+  },
+  "engines": {
+    "node": ">=20"
+  },
   "keywords": [
     "pi-package",
     "pi",
@@ -16,34 +22,36 @@
     "provider"
   ],
   "files": [
-    "src"
+    "src",
+    "README.md",
+    "LICENSE"
   ],
+  "scripts": {
+    "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",
+    "typecheck": "tsc --noEmit"
+  },
   "dependencies": {
-    "@tencent-ai/agent-sdk": "^0.3.0"
+    "@tencent-ai/agent-sdk": "^0.3.0",
+    "change-case": "^5.4.4",
+    "typebox": "^1.3.0"
   },
   "peerDependencies": {
-    "@earendil-works/pi-ai": "*",
-    "@earendil-works/pi-coding-agent": "*",
-    "typebox": "*"
+    "@earendil-works/pi-ai": ">=0.80.0",
+    "@earendil-works/pi-coding-agent": ">=0.80.0",
+    "@earendil-works/pi-tui": ">=0.80.0"
   },
-  "peerDependenciesMeta": {
-    "@earendil-works/pi-ai": {
-      "optional": true
-    },
-    "@earendil-works/pi-coding-agent": {
-      "optional": true
-    },
-    "typebox": {
-      "optional": true
-    }
+  "devDependencies": {
+    "@earendil-works/pi-ai": "^0.80.2",
+    "@earendil-works/pi-coding-agent": "^0.80.2",
+    "@earendil-works/pi-tui": "^0.80.2",
+    "@types/node": "^24.13.2",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
     ]
-  },
-  "devDependencies": {
-    "@earendil-works/pi-ai": "^0.80.2",
-    "@earendil-works/pi-coding-agent": "^0.80.2"
   }
 }

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/askcodebuddy-ui.ts

@@ -0,0 +1,90 @@
+// Status-line rendering helpers for the AskCodebuddy tool.
+//
+// While CodeBuddy runs inside an AskCodebuddy call, the pi TUI can't surface
+// each tool_use individually — there's only one status row for the whole
+// delegation. These helpers shape a tool_use record into a short, path-aware
+// label (e.g. "Read(src/foo.ts)", "Bash(git log --oneline…)") and collapse
+// runs of the same tool so the line doesn't flicker. Used only by
+// promptAndWait; the provider path exposes tools directly through pi's TUI
+// and doesn't need this.
+
+export interface ToolCallState {
+	name: string;
+	status: string;
+	rawInput?: unknown;
+}
+
+export function extractPath(rawInput: unknown): string | undefined {
+	if (!rawInput || typeof rawInput !== "object") return undefined;
+	const input = rawInput as Record<string, unknown>;
+	if (typeof input.file_path === "string") return input.file_path;
+	if (typeof input.path === "string") return input.path;
+	if (typeof input.command === "string") return input.command.substring(0, 80);
+	return undefined;
+}
+
+export function shortPath(p: string): string {
+	const cwd = process.cwd();
+	if (p.startsWith(cwd + "/")) return p.slice(cwd.length + 1);
+	if (p.startsWith("/")) {
+		const parts = p.split("/");
+		if (parts.length > 3) return parts.slice(-2).join("/");
+	}
+	return p;
+}
+
+export function formatToolAction(tc: ToolCallState): string | undefined {
+	const path = extractPath(tc.rawInput);
+	const verb = tc.name.toLowerCase().split(/\s/)[0];
+	if (verb === "read" || verb === "readfile") {
+		return path ? `Read(${shortPath(path)})` : "Read";
+	} else if (verb === "glob") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const pat = typeof input?.pattern === "string" ? input.pattern.slice(0, 40) : "";
+		return pat ? `Glob(${pat})` : "Glob";
+	} else if (verb === "edit" || verb === "write" || verb === "writefile" || verb === "multiedit") {
+		return path ? `Edit(${shortPath(path)})` : "Edit";
+	} else if (verb === "bashoutput") {
+		return undefined; // redundant with preceding Bash call
+	} else if (verb === "bash" || verb === "terminal") {
+		return path ? `Bash(${path})` : "Bash";
+	} else if (verb === "agent") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		return `Agent(${String(input?.description ?? "").slice(0, 40)})`;
+	} else if (verb === "grep") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const pat = typeof input?.pattern === "string" ? input.pattern.slice(0, 40) : "";
+		return pat ? `Grep(${pat})` : "Grep";
+	} else if (verb === "skill") {
+		const input = tc.rawInput as Record<string, unknown> | undefined;
+		const name = typeof input?.skill === "string" ? input.skill.slice(0, 40) : "";
+		return name ? `Skill(${name})` : "Skill";
+	} else if (verb === "todowrite" || verb === "taskcreate" || verb === "taskupdate") {
+		const todos = Array.isArray((tc.rawInput as any)?.todos) ? (tc.rawInput as any).todos : [];
+		const current = todos.find((t: any) => t.status === "in_progress") ?? todos.find((t: any) => t.status === "pending");
+		const label = current ? String(current.content ?? "").slice(0, 40) : "";
+		return label || undefined;
+	} else if (verb === "askclaude") {
+		// Recursive — don't show AskCodebuddy in its own action summary
+		return undefined;
+	}
+	return tc.name;
+}
+
+export function buildActionSummary(calls: Map<string, ToolCallState>): string {
+	const parts: string[] = [];
+	let prevVerb = "";
+	for (const [, tc] of calls) {
+		const action = formatToolAction(tc);
+		if (!action) continue;
+		const verb = tc.name.toLowerCase().split(/\s/)[0];
+		// Collapse consecutive calls to the same tool — keep only the latest
+		if (verb === prevVerb) {
+			parts[parts.length - 1] = action;
+		} else {
+			parts.push(action);
+		}
+		prevVerb = verb;
+	}
+	return parts.join("; ");
+}

package/src/cb-session-io.ts

@@ -0,0 +1,205 @@
+// CodeBuddy session JSONL read/write for pi session sync (replaces cc-session-io).
+// CodeBuddy stores sessions at ~/.codebuddy/projects/<sanitized-path>/<sessionId>.jsonl
+
+import { randomUUID } from "crypto";
+import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import type { Message as PiMessage } from "@earendil-works/pi-ai";
+import { convertPiMessages, messageContentToText } from "./convert.js";
+
+export interface CbMessage {
+	role: "user" | "assistant";
+	content: string;
+}
+
+export function getCodebuddyDir(codebuddyDir?: string): string {
+	return codebuddyDir ?? process.env.CODEBUDDY_CONFIG_DIR ?? join(homedir(), ".codebuddy");
+}
+
+export function normalizeProjectPath(projectPath: string): string {
+	return projectPath.replace(/\/+$/, "") || projectPath;
+}
+
+export function projectPathToHash(projectPath: string): string {
+	return normalizeProjectPath(projectPath).replace(/^\//, "").replace(/\//g, "-");
+}
+
+export function getProjectDir(projectPath: string, codebuddyDir?: string): string {
+	return join(getCodebuddyDir(codebuddyDir), "projects", projectPathToHash(projectPath));
+}
+
+export function getSessionPath(sessionId: string, projectPath: string, codebuddyDir?: string): string {
+	return join(getProjectDir(projectPath, codebuddyDir), `${sessionId}.jsonl`);
+}
+
+export function deleteSession(sessionId: string, projectPath: string, codebuddyDir?: string): void {
+	const jsonlPath = getSessionPath(sessionId, projectPath, codebuddyDir);
+	const dir = join(getProjectDir(projectPath, codebuddyDir), sessionId);
+	try { rmSync(jsonlPath, { force: true }); } catch { /* ignore */ }
+	try { rmSync(dir, { recursive: true, force: true }); } catch { /* ignore */ }
+}
+
+function piToCbMessages(messages: PiMessage[]): CbMessage[] {
+	const { anthropicMessages } = convertPiMessages(messages);
+	const out: CbMessage[] = [];
+	for (const msg of anthropicMessages) {
+		if (msg.role === "user") {
+			const text = typeof msg.content === "string"
+				? msg.content
+				: msg.content.map((b: any) => b.type === "text" ? b.text : b.type === "tool_result" ? `[tool_result:${b.tool_use_id}]` : `[${b.type}]`).join("\n");
+			out.push({ role: "user", content: text });
+		} else if (msg.role === "assistant") {
+			const text = typeof msg.content === "string"
+				? msg.content
+				: msg.content.map((b: any) => b.type === "text" ? b.text : b.type === "tool_use" ? `[tool:${b.name}]` : `[${b.type}]`).join("\n");
+			out.push({ role: "assistant", content: text });
+		}
+	}
+	return out;
+}
+
+function writeCbJsonl(sessionId: string, cwd: string, messages: CbMessage[]): string {
+	const jsonlPath = getSessionPath(sessionId, cwd);
+	mkdirSync(join(jsonlPath, ".."), { recursive: true });
+	const lines: string[] = [];
+	let parentId: string | undefined;
+	const ts = Date.now();
+	for (const msg of messages) {
+		const id = randomUUID();
+		if (msg.role === "user") {
+			lines.push(JSON.stringify({
+				id, timestamp: ts, type: "message", role: "user",
+				content: [{ type: "input_text", text: msg.content }],
+				providerData: { agent: "sdk" }, sessionId, cwd,
+			}));
+			parentId = id;
+		} else {
+			lines.push(JSON.stringify({
+				id, parentId, timestamp: ts, type: "message", role: "assistant",
+				status: "completed",
+				content: [{ type: "output_text", text: msg.content }],
+				providerData: { agent: "sdk" }, sessionId, cwd,
+			}));
+			parentId = id;
+		}
+	}
+	writeFileSync(jsonlPath, lines.join("\n") + (lines.length ? "\n" : ""));
+	return jsonlPath;
+}
+
+export class Session {
+	readonly sessionId: string;
+	readonly projectPath: string;
+	readonly codebuddyDir?: string;
+	readonly jsonlPath: string;
+	messages: CbMessage[] = [];
+
+	constructor(sessionId: string, projectPath: string, codebuddyDir?: string) {
+		this.sessionId = sessionId;
+		this.projectPath = projectPath;
+		this.codebuddyDir = codebuddyDir;
+		this.jsonlPath = getSessionPath(sessionId, projectPath, codebuddyDir);
+	}
+
+	importPiMessages(messages: PiMessage[]): void {
+		this.messages = piToCbMessages(messages);
+	}
+
+	save(): void {
+		writeCbJsonl(this.sessionId, this.projectPath, this.messages);
+	}
+}
+
+export interface CreateSessionOptions {
+	projectPath: string;
+	sessionId?: string;
+	model?: string;
+	codebuddyDir?: string;
+}
+
+export function createSession(opts: CreateSessionOptions): Session {
+	const sessionId = opts.sessionId ?? randomUUID();
+	return new Session(sessionId, opts.projectPath, opts.codebuddyDir);
+}
+
+export function repairToolPairing(messages: Array<{ role: string; content: unknown }>): Array<{ role: string; content: unknown }> {
+	const result: Array<{ role: string; content: unknown }> = [];
+	let pending: Set<string> | null = null;
+	const synthetic = (id: string) => ({
+		type: "tool_result",
+		tool_use_id: id,
+		content: "[no tool result recorded]",
+		is_error: true,
+	});
+	const flushPending = () => {
+		if (pending && pending.size > 0) {
+			result.push({ role: "user", content: [...pending].map(synthetic) });
+		}
+		pending = null;
+	};
+	for (const msg of messages) {
+		if (msg.role === "assistant") {
+			flushPending();
+			const ids = new Set<string>();
+			if (Array.isArray(msg.content)) {
+				for (const b of msg.content as Array<{ type?: string; id?: string }>) {
+					if (b.type === "tool_use" && typeof b.id === "string") ids.add(b.id);
+				}
+			}
+			result.push(msg);
+			pending = ids.size > 0 ? ids : null;
+			continue;
+		}
+		const blocks = Array.isArray(msg.content) ? msg.content as Array<{ type?: string; tool_use_id?: string }> : null;
+		const hasToolResults = blocks?.some((b) => b.type === "tool_result") ?? false;
+		if (!pending && !hasToolResults) {
+			result.push(msg);
+			continue;
+		}
+		const input = blocks ?? (typeof msg.content === "string" && msg.content ? [{ type: "text", text: msg.content }] : []);
+		const provided = new Set<string>();
+		const kept = input.filter((b: { type?: string; tool_use_id?: string }) => {
+			if (b.type !== "tool_result") return true;
+			if (b.tool_use_id && pending?.has(b.tool_use_id)) {
+				provided.add(b.tool_use_id);
+				return true;
+			}
+			return false;
+		});
+		if (pending) {
+			const missing = [...pending].filter((id) => !provided.has(id)).map(synthetic);
+			kept.unshift(...missing);
+			pending = null;
+		}
+		if (kept.length === 0) {
+			if (result.length === 0) {
+				result.push({ role: "user", content: [{ type: "text", text: "[orphaned tool result removed]" }] });
+			}
+			continue;
+		}
+		result.push({ ...msg, content: kept });
+	}
+	flushPending();
+	return result;
+}
+
+export function readSession(sessionId: string, projectPath: string, codebuddyDir?: string): Session | null {
+	const jsonlPath = getSessionPath(sessionId, projectPath, codebuddyDir);
+	if (!existsSync(jsonlPath)) return null;
+	const session = new Session(sessionId, projectPath, codebuddyDir);
+	const lines = readFileSync(jsonlPath, "utf-8").split("\n").filter(Boolean);
+	for (const line of lines) {
+		try {
+			const rec = JSON.parse(line);
+			if (rec.type === "message" && rec.role === "user") {
+				const text = rec.content?.find((b: any) => b.type === "input_text")?.text ?? messageContentToText(rec.content);
+				session.messages.push({ role: "user", content: text });
+			} else if (rec.type === "message" && rec.role === "assistant") {
+				const text = rec.content?.find((b: any) => b.type === "output_text")?.text ?? messageContentToText(rec.content);
+				session.messages.push({ role: "assistant", content: text });
+			}
+		} catch { /* skip malformed */ }
+	}
+	return session;
+}