c0de-agent 0.0.0 → 1.0.0

package/dist/server/routes/tool.js

@@ -0,0 +1,28 @@
+import { Hono } from 'hono';
+import { listTools } from '../../tools/registry.js';
+import { apiError } from '../middleware/error.js';
+function createToolRoute(ctx) {
+    const app = new Hono();
+    // 列出可用工具（不含 execute 函数）
+    app.get('/', (c) => {
+        const tools = listTools(ctx.toolRegistry, { config: {}, cwd: ctx.cwd });
+        const serializable = tools.map((t) => ({
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+            permission: t.permission,
+        }));
+        return c.json(serializable);
+    });
+    // 确认工具执行权限
+    app.post('/confirm', async (c) => {
+        const body = await c.req.json();
+        const ok = ctx.permissionStore.resolve(body.toolCallId, body.approved);
+        if (!ok) {
+            return apiError(c, 404, 'NOT_FOUND', 'No pending permission for this tool call');
+        }
+        return c.json({ confirmed: true });
+    });
+    return app;
+}
+export { createToolRoute };

package/dist/server/routes/update.d.ts

@@ -0,0 +1,14 @@
+import { Hono } from 'hono';
+import type { ServerContext } from '../types.js';
+/**
+ * GET /api/update — 返回后台调度器缓存的版本检查结果（spec §18.1）。
+ * 路由本身不触发 npm registry 请求；调度器周期性 checkNow 写入缓存，
+ * 路由读缓存（避免每个前端轮询都打外网）。
+ *
+ * POST /api/update/apply — 手动触发热更新（spec §18.2）：
+ *   序列化当前会话 → performHotUpdate（npm install -g + spawn 新实例 + handoffPort）。
+ *   旧实例通过 handoff 端点优雅退出，新实例 restore 快照并接管端口。
+ *   响应立即返回（不阻塞 spawn），实际接管由 handoff IPC 异步完成。
+ */
+declare function createUpdateRoute(ctx: ServerContext): Hono;
+export { createUpdateRoute };

package/dist/server/routes/update.js

@@ -0,0 +1,49 @@
+import { Hono } from 'hono';
+import { performHotUpdate, serializeSessions } from '../../update/index.js';
+import { apiError } from '../middleware/error.js';
+/**
+ * GET /api/update — 返回后台调度器缓存的版本检查结果（spec §18.1）。
+ * 路由本身不触发 npm registry 请求；调度器周期性 checkNow 写入缓存，
+ * 路由读缓存（避免每个前端轮询都打外网）。
+ *
+ * POST /api/update/apply — 手动触发热更新（spec §18.2）：
+ *   序列化当前会话 → performHotUpdate（npm install -g + spawn 新实例 + handoffPort）。
+ *   旧实例通过 handoff 端点优雅退出，新实例 restore 快照并接管端口。
+ *   响应立即返回（不阻塞 spawn），实际接管由 handoff IPC 异步完成。
+ */
+function createUpdateRoute(ctx) {
+    const app = new Hono();
+    app.get('/', (c) => {
+        const cached = ctx.updateScheduler.getLastResult();
+        if (cached)
+            return c.json(cached);
+        // 无缓存（首次启动延迟未到）：同步触发一次，避免前端首屏空。
+        // 不 await——保持 GET 语义非阻塞；前端下次轮询拿到结果。
+        void ctx.updateScheduler.checkNow();
+        return c.json({
+            hasUpdate: false,
+            currentVersion: '0.0.0',
+            latestVersion: '0.0.0',
+        });
+    });
+    app.post('/apply', async (c) => {
+        const result = await ctx.updateScheduler.checkNow();
+        if (!result.hasUpdate) {
+            return apiError(c, 409, 'NO_UPDATE', '已是最新版本，无需热更新');
+        }
+        const snapshot = await serializeSessions(ctx.db, ctx.config);
+        const r = await performHotUpdate(snapshot, {
+            handoffPort: ctx.handoff?.port,
+        });
+        if (r._tag === 'success') {
+            return c.json({
+                ok: true,
+                snapshotPath: r.snapshotPath,
+                latestVersion: result.latestVersion,
+            });
+        }
+        return apiError(c, 500, 'HOT_UPDATE_FAILED', `${r._tag}: ${'error' in r ? r.error : 'unknown'}`);
+    });
+    return app;
+}
+export { createUpdateRoute };

package/dist/server/server.d.ts

@@ -0,0 +1,43 @@
+import type { Hono } from 'hono';
+import type { DB } from '../db/client.js';
+import type { Registry } from '../llm/registry.js';
+import type { Config } from '../shared/types/config.js';
+import { checkForUpdate, createHandoffServer } from '../update/index.js';
+import type { ServerContext } from './types.js';
+type StartServerOptions = {
+    port?: number;
+    cwd?: string;
+    /** 注入已有 DB（测试用）。 */
+    db?: DB;
+    /** 热更新新实例启动时从此快照文件恢复会话状态。 */
+    restoreFrom?: string;
+    /** 新实例启动时提供：请求旧实例 handoff 后再绑端口（spec §18.3）。 */
+    handoffPort?: number;
+    /** 测试注入：跳过 handoff 请求与重试绑端口。 */
+    skipHandoff?: boolean;
+    /** 测试注入：覆盖 checkForUpdate（默认走真实 npm registry）。 */
+    checkForUpdateFn?: typeof checkForUpdate;
+    /** 测试注入：覆盖 createHandoffServer。 */
+    createHandoffFn?: typeof createHandoffServer;
+};
+type RunningServer = {
+    app: Hono;
+    port: number;
+    close(): Promise<void>;
+};
+type BootstrappedServer = {
+    ctx: ServerContext;
+    close(): Promise<void>;
+};
+/** 把 config.providers 注册到新建的 LLM registry（修复此前空 registry 的遗漏）。 */
+declare function buildRegistryFromConfig(config: Config): Registry;
+/**
+ * config 变更后原地同步 registry（清空旧路由 + 重新注册），
+ * 使运行中的 ServerContext 立即生效，无需重启。
+ */
+declare function syncRegistryFromConfig(registry: Registry, config: Config): void;
+/** 初始化 DB + 配置 + 注册表，返回 ServerContext + 清理函数（dev 与独立后端共用）。 */
+declare function bootstrapServerContext(opts?: StartServerOptions): Promise<BootstrappedServer>;
+declare function startServer(opts?: StartServerOptions): Promise<RunningServer>;
+export type { BootstrappedServer, RunningServer, StartServerOptions };
+export { bootstrapServerContext, buildRegistryFromConfig, startServer, syncRegistryFromConfig };

package/dist/server/server.js

@@ -0,0 +1,197 @@
+// src/server/server.ts
+import { existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { connect as tcpConnect } from 'node:net';
+import { join } from 'node:path';
+import { serve } from '@hono/node-server';
+import { BUILTIN_AGENTS, createAgentRegistry } from '../core/agents/index.js';
+import { loadConfig } from '../core/config.js';
+import { decryptSecret } from '../core/secret.js';
+import { createDB, migrateDB } from '../db/index.js';
+import { createRegistry, registerProvider } from '../llm/registry.js';
+import { initPlugins } from '../plugins/index.js';
+import { createDefaultRegistry, createDefaultURLRegistry } from '../tools/index.js';
+import { checkForUpdate, createHandoffServer, createUpdateScheduler, requestHandoff, restoreSessions, } from '../update/index.js';
+import { createAgentManager } from './agent-manager.js';
+import { createApp } from './app.js';
+import { createPermissionStore } from './permission/store.js';
+/** 把 config.providers 注册到新建的 LLM registry（修复此前空 registry 的遗漏）。 */
+function buildRegistryFromConfig(config) {
+    const registry = createRegistry();
+    for (const p of config.providers) {
+        registerProviderFromConfig(registry, p);
+    }
+    return registry;
+}
+function registerProviderFromConfig(registry, p) {
+    // 兼容 config.json 中以 _tag 标识 provider 的格式（name 缺失时回退到 _tag）
+    const name = p.name || p._tag;
+    if (!name || !p.baseURL)
+        return;
+    // baseURL 已含 /v1 时用 /chat/completions，避免 /v1/v1 双重前缀
+    const path = p.baseURL.replace(/\/+$/, '').endsWith('/v1') ? '/chat/completions' : undefined;
+    registerProvider(registry, {
+        name,
+        baseURL: p.baseURL,
+        apiKey: p.apiKey ? decryptSecret(p.apiKey) : p.apiKey,
+        ...(path ? { path } : {}),
+    });
+}
+/**
+ * config 变更后原地同步 registry（清空旧路由 + 重新注册），
+ * 使运行中的 ServerContext 立即生效，无需重启。
+ */
+function syncRegistryFromConfig(registry, config) {
+    registry.routes.clear();
+    registry.roles.clear();
+    for (const p of config.providers) {
+        registerProviderFromConfig(registry, p);
+    }
+}
+/** 解析 PGLite 持久化数据目录：优先 C0DE_DB_DIR，否则 <cwd>/.c0de/pglite。 */
+function resolveDbDir(cwd) {
+    const envDir = process.env.C0DE_DB_DIR;
+    if (envDir && envDir.trim() !== '')
+        return envDir;
+    return join(cwd, '.c0de', 'pglite');
+}
+/** 初始化 DB + 配置 + 注册表，返回 ServerContext + 清理函数（dev 与独立后端共用）。 */
+async function bootstrapServerContext(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const ownsDb = !opts.db;
+    // 持久化 PGLite 数据：默认 <cwd>/.c0de/pglite（与 .c0de/cache、.c0de/config.json 同约定），
+    // 可用 C0DE_DB_DIR 覆盖。此前默认 in-memory，进程重启即丢全部会话/消息/调用详情。
+    // 测试注入 opts.db 时跳过（保持 in-memory 隔离）。
+    let db;
+    if (opts.db) {
+        db = opts.db;
+    }
+    else {
+        const dataDir = resolveDbDir(cwd);
+        if (!existsSync(dataDir))
+            mkdirSync(dataDir, { recursive: true });
+        db = await createDB({ driver: 'pglite', dataDir });
+    }
+    // migrateDB 失败时必须 close db，否则 PGLite WASM 实例泄漏并锁住 dataDir，
+    // 导致后续重试全部 abort（RuntimeError: Aborted()）。
+    try {
+        await migrateDB(db);
+    }
+    catch (err) {
+        if (ownsDb)
+            await db.close().catch(() => { });
+        throw err;
+    }
+    if (opts.restoreFrom) {
+        const snapshot = JSON.parse(readFileSync(opts.restoreFrom, 'utf8'));
+        await restoreSessions(db, snapshot);
+    }
+    const config = await loadConfig(cwd);
+    const toolRegistry = createDefaultRegistry(config);
+    const llmRegistry = buildRegistryFromConfig(config);
+    const urlRegistry = createDefaultURLRegistry();
+    const { pluginRegistry, hookRunner } = await initPlugins({
+        cwd,
+        config,
+        toolRegistry,
+        llmRegistry,
+    });
+    const ctx = {
+        db,
+        config,
+        toolRegistry,
+        llmRegistry,
+        urlRegistry,
+        hookRunner,
+        pluginRegistry,
+        agentManager: createAgentManager(),
+        permissionStore: createPermissionStore(),
+        permissionMode: config.permission.defaultMode,
+        // Agent 注册表：内置 4 个默认 agent；项目/用户自定义 agent 可在启动后补充加载。
+        agentRegistry: (() => {
+            const reg = createAgentRegistry();
+            for (const def of BUILTIN_AGENTS)
+                reg.register(def);
+            return reg;
+        })(),
+        // spec §18.1 后台版本检查调度器；config.update.enabled 控制是否启动。
+        updateScheduler: createUpdateScheduler({
+            checkFn: opts.checkForUpdateFn ?? checkForUpdate,
+            intervalMs: config.update.intervalMs,
+            initialDelayMs: config.update.initialDelayMs,
+        }),
+        cwd,
+    };
+    // spec §18.3 handoff server：旧实例监听随机端口，收到 POST /handoff 时
+    // 序列化当前会话状态 + 优雅关闭，让新实例接管。config.update.enabled=false
+    // 或测试 skipHandoff 时跳过（减少后台资源占用）。
+    let handoffServer;
+    if (config.update.enabled && !opts.skipHandoff) {
+        const createHandoff = opts.createHandoffFn ?? createHandoffServer;
+        handoffServer = await createHandoff(async () => {
+            // 序列化在热更新主链路（performHotUpdate）已完成；handoff 回调只需释放资源。
+            // 这里提前停 scheduler 以避免 close 期间还在跑检查。
+            ctx.updateScheduler.stop();
+        });
+        ctx.handoff = { port: handoffServer.port, server: handoffServer };
+    }
+    return {
+        ctx,
+        close: async () => {
+            ctx.updateScheduler.stop();
+            if (handoffServer)
+                await handoffServer.close();
+            if (ownsDb)
+                await db.close();
+        },
+    };
+}
+/**
+ * 请求旧实例 handoff 后轮询端口释放（spec §18.3）。旧实例收到 /handoff 后
+ * 优雅退出释放端口；新实例轮询 TCP 连接直到被拒（端口已释放）或超时报错。
+ */
+async function requestHandoffWithRetry(port, maxAttempts = 30, delayMs = 100) {
+    try {
+        await requestHandoff(port);
+    }
+    catch {
+        // 旧实例未启 handoff 端点（update 未启用）；直接尝试绑端口。
+        return;
+    }
+    for (let i = 0; i < maxAttempts; i++) {
+        const released = await new Promise((resolve) => {
+            const sock = tcpConnect({ host: '127.0.0.1', port });
+            sock.once('connect', () => {
+                sock.destroy();
+                resolve(false); // 连上 → 旧实例还在
+            });
+            sock.once('error', () => resolve(true)); // 连接拒绝 → 端口已释放
+        });
+        if (released)
+            return;
+        await new Promise((r) => setTimeout(r, delayMs));
+    }
+    throw new Error(`handoff: old instance on port ${port} did not release after ${maxAttempts} attempts`);
+}
+async function startServer(opts = {}) {
+    const port = opts.port ?? 3000;
+    // spec §18.3：新实例从 --handoff-port 拿到旧实例端口，请求优雅退出后绑端口。
+    if (opts.handoffPort && !opts.skipHandoff) {
+        await requestHandoffWithRetry(opts.handoffPort);
+    }
+    const { ctx, close: closeCtx } = await bootstrapServerContext(opts);
+    const app = createApp(ctx);
+    // config.update.enabled 时启动后台调度器。
+    if (ctx.config.update.enabled)
+        ctx.updateScheduler.start();
+    const server = serve({ fetch: app.fetch, port });
+    let closed = false;
+    const close = async () => {
+        if (closed)
+            return;
+        closed = true;
+        server.close();
+        await closeCtx();
+    };
+    return { app, port, close };
+}
+export { bootstrapServerContext, buildRegistryFromConfig, startServer, syncRegistryFromConfig };

package/dist/server/types.d.ts

@@ -0,0 +1,73 @@
+import type { AgentRegistry } from '../core/agents/types.js';
+import type { Config } from '../core/config.js';
+import type { DB } from '../db/client.js';
+import type { chatStream as chatStreamFn } from '../llm/provider.js';
+import type { Registry } from '../llm/registry.js';
+import type { HookRunner, PluginRegistry } from '../plugins/types.js';
+import type { Config as SharedConfig } from '../shared/types/config.js';
+import type { URLRegistry } from '../shared/types/tool.js';
+import type { ToolRegistry } from '../tools/types.js';
+import type { HandoffServer, UpdateScheduler } from '../update/index.js';
+import type { AgentManager } from './agent-manager.js';
+import type { PermissionStore } from './permission/store.js';
+/** 持有所有服务依赖的不可变上下文（config 字段可变用于 PATCH 更新）。 */
+type ServerContext = {
+    db: DB;
+    config: Config;
+    toolRegistry: ToolRegistry;
+    llmRegistry: Registry;
+    /** 内置 URL 解析器注册表（file://, skill://）；注入 agent loop 的 ToolContext。 */
+    urlRegistry: URLRegistry;
+    /** 插件 hook runner；接入 agent loop 的 tool/provider/message hook。 */
+    hookRunner: HookRunner;
+    /** 插件注册表（builtin + 已加载外部插件）；供插件管理 API 查询。 */
+    pluginRegistry: PluginRegistry;
+    agentManager: AgentManager;
+    /** 全局权限确认 store（单例），独立于 agent run 生命周期。 */
+    permissionStore: PermissionStore;
+    /** 全局授权模式（运行时可临时切换）：'default' 逐个确认；'auto' 自动放行 ask 工具（YOLO）。启动时取 config.permission.defaultMode，PUT /api/permissions 临时切换不回写 config。 */
+    permissionMode: 'default' | 'auto';
+    /** Agent 类型注册表（spec: multi-agent-design）。注入 agent loop 的 runSubAgent。 */
+    agentRegistry: AgentRegistry;
+    /** 后台版本检查调度器（spec §18.1）；/api/update 读取其缓存结果。 */
+    updateScheduler: UpdateScheduler;
+    /** Handoff HTTP 端点（spec §18.3）；热更新时新实例 POST /handoff 触发优雅退出。 undefined 表示未启用。 */
+    handoff?: {
+        port: number;
+        server: HandoffServer;
+    };
+    cwd: string;
+    /** 测试注入：覆盖 LLM chat stream。生产环境为 undefined。 */
+    chatStream?: typeof chatStreamFn;
+};
+/** POST /api/chat 请求体。 */
+type ChatRequest = {
+    sessionId: string;
+    message: string;
+    provider?: string;
+    model?: string;
+    tools?: string[];
+};
+/** Agent 控制请求（abort/pause/resume）。 */
+type ControlRequest = {
+    sessionId: string;
+};
+/** POST /api/chat/steer 请求体。 */
+type SteerRequest = {
+    sessionId: string;
+    message: string;
+};
+/** POST /api/tools/confirm 请求体。 */
+type ConfirmRequest = {
+    toolCallId: string;
+    approved: boolean;
+};
+/** 统一错误响应体。 */
+type APIErrorBody = {
+    error: {
+        code: string;
+        message: string;
+        details?: Record<string, unknown>;
+    };
+};
+export type { APIErrorBody, ChatRequest, Config, ConfirmRequest, ControlRequest, HandoffServer, ServerContext, SharedConfig, SteerRequest, };

package/dist/server/types.js

@@ -0,0 +1,2 @@
+// src/server/types.ts
+export {};

package/dist/server/util/safe-path.d.ts

@@ -0,0 +1,7 @@
+/**
+ * safeResolve 已下沉到共享层（src/shared/utils/path.ts），供 tools / server 等
+ * 所有层统一引用，避免 tools 层反向依赖 server 层。
+ *
+ * 本文件仅做 re-export，保持 server 层调用方（chat/files 路由）的对外 API 不变。
+ */
+export { safeResolve } from '../../shared/utils/path.js';

package/dist/server/util/safe-path.js

@@ -0,0 +1,7 @@
+/**
+ * safeResolve 已下沉到共享层（src/shared/utils/path.ts），供 tools / server 等
+ * 所有层统一引用，避免 tools 层反向依赖 server 层。
+ *
+ * 本文件仅做 re-export，保持 server 层调用方（chat/files 路由）的对外 API 不变。
+ */
+export { safeResolve } from '../../shared/utils/path.js';

package/dist/session/archive.d.ts

@@ -0,0 +1,15 @@
+import type { DB } from '../db/client.js';
+import type { ArchiveRef, CompactionArchive, SessionEntry } from './types.js';
+/** Archive original entries before compaction/squash. Returns the archive id. */
+declare function archiveOriginalEntries(handle: DB, sessionId: string, entries: SessionEntry[], archiveType: 'compaction' | 'squash', summary: string, compactionId: string): Promise<string>;
+/** Get an archive by id. Returns null for invalid or non-existent ids. */
+declare function getArchive(handle: DB, id: string): Promise<CompactionArchive | null>;
+/** Get the original entries stored in an archive. */
+declare function getArchiveOriginalEntries(handle: DB, archiveId: string): Promise<SessionEntry[]>;
+/** Search archives by keyword (case-insensitive substring on searchable text). */
+declare function searchArchives(handle: DB, sessionId: string, query: string): Promise<CompactionArchive[]>;
+/** Parse a `@[archive:<id>]` or `@[squash:<n>]` reference from text. Returns null if none. */
+declare function parseArchiveReference(text: string): ArchiveRef | null;
+/** Resolve an archive reference to displayable text. */
+declare function resolveArchiveReference(handle: DB, sessionId: string, ref: ArchiveRef): Promise<string | null>;
+export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, };

package/dist/session/archive.js

@@ -0,0 +1,129 @@
+import { and, desc, eq, ilike } from 'drizzle-orm';
+import { compactionArchives } from '../db/schema.js';
+import { generateId } from '../shared/index.js';
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function toEpochMs(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'number')
+        return value;
+    return new Date(value).getTime();
+}
+function rowToArchive(row) {
+    return {
+        id: row.id,
+        sessionId: row.sessionId,
+        compactionId: row.compactionId,
+        archiveType: row.archiveType,
+        originalEntries: row.originalEntries,
+        summary: row.summary,
+        tokenCount: row.tokenCount ?? 0,
+        searchableText: row.searchableText ?? '',
+        createdAt: toEpochMs(row.createdAt),
+    };
+}
+/** Convert an entry to searchable plain text. */
+function entryToSearchableText(entry) {
+    if ('_tag' in entry) {
+        switch (entry._tag) {
+            case 'compaction':
+            case 'squash':
+            case 'branch_summary':
+                return entry.summary;
+            case 'steering':
+                return entry.content;
+        }
+    }
+    return entry.content
+        .map((part) => {
+        switch (part._tag) {
+            case 'text':
+            case 'thinking':
+            case 'steering':
+                return part.text;
+            case 'tool_call':
+                return `${part.tool}: ${JSON.stringify(part.input)}`;
+            case 'tool_result':
+                return JSON.stringify(part.output);
+            default:
+                return '';
+        }
+    })
+        .join(' ');
+}
+/** Archive original entries before compaction/squash. Returns the archive id. */
+async function archiveOriginalEntries(handle, sessionId, entries, archiveType, summary, compactionId) {
+    const id = generateId();
+    const searchableText = entries.map(entryToSearchableText).join('\n');
+    const tokenCount = entries.reduce((sum, e) => sum + ('tokenCount' in e ? e.tokenCount : 0), 0);
+    await handle.db.insert(compactionArchives).values({
+        id,
+        sessionId,
+        compactionId,
+        archiveType,
+        originalEntries: entries,
+        summary,
+        tokenCount,
+        searchableText,
+    });
+    return id;
+}
+/** Get an archive by id. Returns null for invalid or non-existent ids. */
+async function getArchive(handle, id) {
+    // PGLite rejects non-UUID strings at query time; validate first.
+    if (!UUID_RE.test(id))
+        return null;
+    const [row] = await handle.db
+        .select()
+        .from(compactionArchives)
+        .where(eq(compactionArchives.id, id));
+    return row ? rowToArchive(row) : null;
+}
+/** Get the original entries stored in an archive. */
+async function getArchiveOriginalEntries(handle, archiveId) {
+    const archive = await getArchive(handle, archiveId);
+    return archive?.originalEntries ?? [];
+}
+/** Escape LIKE/ILIKE metacharacters so the query is treated as a literal substring. */
+function escapeLikePattern(text) {
+    return text.replace(/[%_\\]/g, '\\$&');
+}
+/** Search archives by keyword (case-insensitive substring on searchable text). */
+async function searchArchives(handle, sessionId, query) {
+    const pattern = `%${escapeLikePattern(query)}%`;
+    const rows = await handle.db
+        .select()
+        .from(compactionArchives)
+        .where(and(eq(compactionArchives.sessionId, sessionId), ilike(compactionArchives.searchableText, pattern)))
+        .orderBy(desc(compactionArchives.createdAt));
+    return rows.map(rowToArchive);
+}
+/** Parse a `@[archive:<id>]` or `@[squash:<n>]` reference from text. Returns null if none. */
+function parseArchiveReference(text) {
+    const archiveId = text.match(/@\[archive:([^\]]+)\]/)?.[1];
+    if (archiveId)
+        return { type: 'archive', id: archiveId };
+    const squashId = text.match(/@\[squash:(\d+|last)\]/)?.[1];
+    if (squashId)
+        return { type: 'squash', id: squashId };
+    return null;
+}
+/** Resolve an archive reference to displayable text. */
+async function resolveArchiveReference(handle, sessionId, ref) {
+    if (ref.type === 'archive') {
+        const archive = await getArchive(handle, ref.id);
+        return archive ? `[Referenced Archive]\n${archive.summary}` : null;
+    }
+    // squash reference: nth most recent squash archive
+    const archives = await handle.db
+        .select()
+        .from(compactionArchives)
+        .where(and(eq(compactionArchives.sessionId, sessionId), eq(compactionArchives.archiveType, 'squash')))
+        .orderBy(desc(compactionArchives.createdAt));
+    const index = ref.id === 'last' ? 0 : Number.parseInt(ref.id, 10) - 1;
+    const row = archives[index];
+    if (!row)
+        return null;
+    return `[Referenced Squash #${index + 1}]\n${row.summary}`;
+}
+export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, };

package/dist/session/branch.d.ts

@@ -0,0 +1,9 @@
+import type { DB } from '../db/client.js';
+import type { Session, SessionTreeNode } from './types.js';
+/** Fork a session at a message index — copies messages 0..index into a new child session. */
+declare function forkSession(handle: DB, sessionId: string, messageIndex: number): Promise<Session>;
+/** Get direct child sessions (branches) of a session. */
+declare function getBranches(handle: DB, sessionId: string): Promise<Session[]>;
+/** Build a full session tree from root sessions down. */
+declare function getTree(handle: DB): Promise<SessionTreeNode[]>;
+export { forkSession, getBranches, getTree };

package/dist/session/branch.js

@@ -0,0 +1,63 @@
+import { eq } from 'drizzle-orm';
+import { sessions } from '../db/schema.js';
+import { generateId } from '../shared/index.js';
+import { getMessages, insertEntry } from './message.js';
+import { createSession, getSession, rowToSession } from './session.js';
+/** Fork a session at a message index — copies messages 0..index into a new child session. */
+async function forkSession(handle, sessionId, messageIndex) {
+    const source = await getSession(handle, sessionId);
+    if (!source)
+        throw new Error(`Session not found: ${sessionId}`);
+    const messages = await getMessages(handle, sessionId);
+    const toCopy = messages.slice(0, messageIndex + 1);
+    const forked = await createSession(handle, `Branch of ${source.title}`, source.projectId ?? undefined);
+    await handle.db
+        .update(sessions)
+        .set({ parentId: sessionId, branchPoint: messageIndex })
+        .where(eq(sessions.id, forked.id));
+    for (const msg of toCopy) {
+        await insertEntry(handle, {
+            id: generateId(),
+            sessionId: forked.id,
+            tag: 'message',
+            role: msg.role,
+            content: msg.content,
+            tokenCount: msg.tokenCount,
+        });
+    }
+    await insertEntry(handle, {
+        id: generateId(),
+        sessionId: forked.id,
+        tag: 'branch_summary',
+        content: {
+            summary: `Branched from session ${sessionId} at message ${messageIndex}`,
+            sourceSessionId: sessionId,
+        },
+    });
+    const updated = await getSession(handle, forked.id);
+    if (!updated)
+        throw new Error('Forked session not found after creation');
+    return updated;
+}
+/** Get direct child sessions (branches) of a session. */
+async function getBranches(handle, sessionId) {
+    const rows = await handle.db.select().from(sessions).where(eq(sessions.parentId, sessionId));
+    return rows.map(rowToSession);
+}
+/** Build a full session tree from root sessions down. */
+async function getTree(handle) {
+    const rows = await handle.db.select().from(sessions);
+    const byParent = new Map();
+    for (const row of rows) {
+        const session = rowToSession(row);
+        const list = byParent.get(session.parentId) ?? [];
+        list.push(session);
+        byParent.set(session.parentId, list);
+    }
+    const build = (parentId) => (byParent.get(parentId) ?? []).map((session) => ({
+        session,
+        children: build(session.id),
+    }));
+    return build(null);
+}
+export { forkSession, getBranches, getTree };