c0de-agent 0.0.0 → 1.1.0

package/dist/tools/websearch/providers/duckduckgo.js

@@ -0,0 +1,75 @@
+const DUCKDUCKGO_SEARCH_URL = 'https://api.duckduckgo.com/';
+const AGENT_TOKEN = 'c0de-agent';
+function cleanText(value) {
+    const cleaned = value
+        ?.replace(/<[^>]*>/g, ' ')
+        .replace(/&nbsp;/gi, ' ')
+        .replace(/&amp;/gi, '&')
+        .replace(/&lt;/gi, '<')
+        .replace(/&gt;/gi, '>')
+        .replace(/&quot;/gi, '"')
+        .replace(/&#39;/gi, "'")
+        .replace(/\s+/g, ' ')
+        .trim();
+    return cleaned ? cleaned : undefined;
+}
+function addSource(sources, source) {
+    if (!source.url || sources.some((s) => s.url === source.url))
+        return;
+    sources.push(source);
+}
+function addTopicSource(sources, topic) {
+    const url = topic.FirstURL?.trim();
+    if (!url)
+        return;
+    const text = cleanText(topic.Text);
+    addSource(sources, { title: text ?? url, url, snippet: text });
+}
+function collectTopicSources(sources, topics) {
+    if (!topics)
+        return;
+    for (const topic of topics) {
+        addTopicSource(sources, topic);
+        collectTopicSources(sources, topic.Topics);
+    }
+}
+async function callDuckDuckGoSearch(params) {
+    const fetchImpl = params.fetchImpl ?? fetch;
+    const query = new URLSearchParams({
+        q: params.query,
+        format: 'json',
+        no_redirect: '1',
+        no_html: '1',
+        skip_disambig: '1',
+        t: AGENT_TOKEN,
+    });
+    const response = await fetchImpl(`${DUCKDUCKGO_SEARCH_URL}?${query.toString()}`, {
+        method: 'GET',
+        signal: params.signal,
+    });
+    if (!response.ok) {
+        const text = await response.text().catch(() => response.statusText);
+        throw new Error(`DuckDuckGo API error (${response.status}): ${text}`);
+    }
+    return (await response.json());
+}
+/** DuckDuckGo Instant Answer 后端（零 key，恒可用）。recency 不支持，忽略。 */
+export const duckduckgoProvider = {
+    id: 'duckduckgo',
+    isAvailable: () => true,
+    search: async (params) => {
+        const data = await callDuckDuckGoSearch(params);
+        const answer = cleanText(data.AbstractText) ?? cleanText(data.Answer) ?? cleanText(data.Definition);
+        const sources = [];
+        // AbstractURL 作为首个来源（若无 RelatedTopics 填充）
+        if (data.AbstractURL) {
+            addSource(sources, {
+                title: cleanText(data.Heading) ?? data.AbstractURL,
+                url: data.AbstractURL,
+            });
+        }
+        collectTopicSources(sources, data.Results);
+        collectTopicSources(sources, data.RelatedTopics);
+        return { provider: 'duckduckgo', answer, sources };
+    },
+};

package/dist/tools/websearch/providers/tavily.d.ts

@@ -0,0 +1,11 @@
+import type { Recency, WebSearchProvider } from '../types.js';
+interface TavilySearchParams {
+    query: string;
+    numResults?: number;
+    recency?: Recency;
+}
+/** 导出供测试：构造 Tavily 请求 body。始终用 general topic（避免技术查询窄化为新闻）。 */
+export declare function buildRequestBody(params: TavilySearchParams): Record<string, unknown>;
+/** Tavily 后端（AI 优化搜索，需 key，返回合成 answer）。 */
+export declare const tavilyProvider: WebSearchProvider;
+export {};

package/dist/tools/websearch/providers/tavily.js

@@ -0,0 +1,89 @@
+import { DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS } from '../types.js';
+const TAVILY_SEARCH_URL = 'https://api.tavily.com/search';
+function clamp(n) {
+    if (n === undefined || Number.isNaN(n))
+        return DEFAULT_NUM_RESULTS;
+    return Math.min(MAX_NUM_RESULTS, Math.max(MIN_NUM_RESULTS, Math.trunc(n)));
+}
+/** 导出供测试：构造 Tavily 请求 body。始终用 general topic（避免技术查询窄化为新闻）。 */
+export function buildRequestBody(params) {
+    const body = {
+        query: params.query,
+        search_depth: 'basic',
+        max_results: clamp(params.numResults),
+        include_answer: 'advanced',
+        include_raw_content: false,
+    };
+    if (params.recency)
+        body.time_range = params.recency;
+    return body;
+}
+function safeParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function asRecord(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+function getErrorMessage(value) {
+    if (typeof value === 'string') {
+        const t = value.trim();
+        return t.length > 0 ? t : null;
+    }
+    const rec = asRecord(value);
+    if (!rec)
+        return null;
+    for (const key of ['detail', 'error', 'message']) {
+        const m = getErrorMessage(rec[key]);
+        if (m)
+            return m;
+    }
+    return null;
+}
+async function callTavilySearch(apiKey, params) {
+    const fetchImpl = params.fetchImpl ?? fetch;
+    const response = await fetchImpl(TAVILY_SEARCH_URL, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${apiKey}`,
+        },
+        body: JSON.stringify(buildRequestBody({
+            query: params.query,
+            numResults: params.limit,
+            recency: params.recency,
+        })),
+        signal: params.signal,
+    });
+    if (!response.ok) {
+        const raw = await response.text().catch(() => response.statusText);
+        const msg = getErrorMessage(safeParse(raw)) ?? (raw.trim() || response.statusText);
+        throw new Error(`Tavily API error (${response.status}): ${msg}`);
+    }
+    return (await response.json());
+}
+/** Tavily 后端（AI 优化搜索，需 key，返回合成 answer）。 */
+export const tavilyProvider = {
+    id: 'tavily',
+    isAvailable: (apiKey) => Boolean(apiKey && apiKey.length > 0),
+    search: async (params) => {
+        if (!params.apiKey)
+            throw new Error('Tavily requires an API key (TAVILY_API_KEY or config).');
+        const data = await callTavilySearch(params.apiKey, params);
+        const sources = [];
+        for (const r of data.results ?? []) {
+            if (!r.url)
+                continue;
+            sources.push({ title: r.title ?? r.url, url: r.url, snippet: r.content ?? undefined });
+        }
+        return {
+            provider: 'tavily',
+            answer: data.answer?.trim() || undefined,
+            sources: sources.slice(0, clamp(params.limit)),
+        };
+    },
+};

package/dist/tools/websearch/types.d.ts

@@ -0,0 +1,51 @@
+/**
+ * websearch 工具的统一类型、常量与工具函数。
+ *
+ * 来源：oh-my-pi（packages/coding-agent/src/web/search/）多后端 strategy 架构，
+ * 裁剪适配 c0de-agent 的 data+functions 范式（无 class）。
+ * 详见 docs/superpowers/specs/2026-06-30-websearch-tool-design.md §2-3。
+ */
+/** 后端标识。strategy 接口预留，未来可加 'exa' | 'searxng' | … */
+type WebSearchProviderId = 'duckduckgo' | 'tavily' | 'brave';
+/** 时效过滤窗口。各后端映射为各自 API 参数。 */
+type Recency = 'day' | 'week' | 'month' | 'year';
+/** 单条搜索来源（所有后端统一）。 */
+type WebSearchSource = {
+    title: string;
+    url: string;
+    snippet?: string;
+};
+/** 统一搜索参数。 */
+type WebSearchParams = {
+    query: string;
+    limit?: number;
+    recency?: Recency;
+    signal?: AbortSignal;
+    /** Tavily/Brave 的 key（DuckDuckGo 不用）。 */
+    apiKey?: string;
+    /** 测试注入；默认用 createFetch()。 */
+    fetchImpl?: typeof fetch;
+};
+/** 统一响应（所有后端统一）。 */
+type WebSearchResponse = {
+    provider: WebSearchProviderId;
+    /** Tavily 返回合成答案；DuckDuckGo/Brave 通常无。 */
+    answer?: string;
+    sources: WebSearchSource[];
+};
+/** 后端 strategy 接口（data + functions，非 class）。 */
+type WebSearchProvider = {
+    id: WebSearchProviderId;
+    /** 是否当前可用（DuckDuckGo 恒真；Tavily/Brave 需 key）。驱动 'auto' 选择。 */
+    isAvailable: (apiKey?: string) => boolean;
+    /** 执行搜索。 */
+    search: (params: WebSearchParams) => Promise<WebSearchResponse>;
+};
+/** 工具参数校验常量。 */
+declare const DEFAULT_NUM_RESULTS = 8;
+declare const MAX_NUM_RESULTS = 20;
+declare const MIN_NUM_RESULTS = 1;
+/** clamp 结果数到 [MIN, MAX]；undefined/NaN 回退到 fallback。 */
+declare function clampNumResults(n: number | undefined, fallback?: number): number;
+export type { Recency, WebSearchParams, WebSearchProvider, WebSearchProviderId, WebSearchResponse, WebSearchSource, };
+export { clampNumResults, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS };

package/dist/tools/websearch/types.js

@@ -0,0 +1,18 @@
+/**
+ * websearch 工具的统一类型、常量与工具函数。
+ *
+ * 来源：oh-my-pi（packages/coding-agent/src/web/search/）多后端 strategy 架构，
+ * 裁剪适配 c0de-agent 的 data+functions 范式（无 class）。
+ * 详见 docs/superpowers/specs/2026-06-30-websearch-tool-design.md §2-3。
+ */
+/** 工具参数校验常量。 */
+const DEFAULT_NUM_RESULTS = 8;
+const MAX_NUM_RESULTS = 20;
+const MIN_NUM_RESULTS = 1;
+/** clamp 结果数到 [MIN, MAX]；undefined/NaN 回退到 fallback。 */
+function clampNumResults(n, fallback = DEFAULT_NUM_RESULTS) {
+    if (n === undefined || Number.isNaN(n))
+        return fallback;
+    return Math.min(MAX_NUM_RESULTS, Math.max(MIN_NUM_RESULTS, Math.trunc(n)));
+}
+export { clampNumResults, DEFAULT_NUM_RESULTS, MAX_NUM_RESULTS, MIN_NUM_RESULTS };

package/dist/tools/websearch/websearch.d.ts

@@ -0,0 +1,10 @@
+import type { WebSearchConfig } from '../../shared/types/config.js';
+import type { ToolDef } from '../../shared/types/tool.js';
+import { setFetchOverride } from './index.js';
+export { setFetchOverride };
+/**
+ * websearch 工具工厂。config 由工厂闭包捕获（对齐 runSubAgent/debugSpawn 依赖反转模式）。
+ * permission: auto（只读网络搜索，不改本地状态）。timeout 30s。
+ * 详见 docs/superpowers/specs/2026-06-30-websearch-tool-design.md §5。
+ */
+export declare function createWebSearchTool(config: WebSearchConfig): ToolDef;

package/dist/tools/websearch/websearch.js

@@ -0,0 +1,48 @@
+import { formatForLLM, runWebSearch, setFetchOverride } from './index.js';
+export { setFetchOverride };
+const NO_RESULTS = 'No search results found. Try a different query.';
+/**
+ * websearch 工具工厂。config 由工厂闭包捕获（对齐 runSubAgent/debugSpawn 依赖反转模式）。
+ * permission: auto（只读网络搜索，不改本地状态）。timeout 30s。
+ * 详见 docs/superpowers/specs/2026-06-30-websearch-tool-design.md §5。
+ */
+export function createWebSearchTool(config) {
+    return {
+        name: 'websearch',
+        description: 'Search the web for up-to-date information beyond knowledge cutoff. ' +
+            'Returns titled sources with snippets (and a synthesized answer when the ' +
+            'backend supports it). Use for current events, recent releases, and docs. ' +
+            `The current year is ${new Date().getFullYear()}.`,
+        parameters: {
+            type: 'object',
+            properties: {
+                query: { type: 'string', description: 'Search query' },
+                numResults: {
+                    type: 'number',
+                    description: 'Number of results (default 8, max 20)',
+                },
+                recency: {
+                    type: 'string',
+                    enum: ['day', 'week', 'month', 'year'],
+                    description: 'Time filter for results',
+                },
+            },
+            required: ['query'],
+        },
+        permission: 'auto',
+        timeout: 30_000,
+        execute: async (input, ctx) => {
+            const { query, numResults, recency } = input;
+            try {
+                const response = await runWebSearch({ query, numResults, recency }, config, ctx.abort);
+                if (!response.answer && response.sources.length === 0) {
+                    return { _tag: 'success', output: NO_RESULTS };
+                }
+                return { _tag: 'success', output: formatForLLM(response) };
+            }
+            catch (err) {
+                return { _tag: 'error', error: err instanceof Error ? err.message : String(err) };
+            }
+        },
+    };
+}

package/dist/update/index.d.ts

@@ -0,0 +1,10 @@
+export type { HandoffServer } from './ipc.js';
+export { createHandoffServer, requestHandoff } from './ipc.js';
+export type { UpdateScheduler, UpdateSchedulerOptions } from './scheduler.js';
+export { createUpdateScheduler } from './scheduler.js';
+export type { SerializedEntry, SerializedSession, SessionSnapshot } from './snapshot.js';
+export { orderSessionsByParent, restoreSessions, serializeSessions } from './snapshot.js';
+export type { HotUpdateOptions, HotUpdateResult, SpawnFn } from './updater.js';
+export { cleanupSnapshot, performHotUpdate } from './updater.js';
+export type { UpdateCheckResult } from './version.js';
+export { checkForUpdate, compareSemver } from './version.js';

package/dist/update/index.js

@@ -0,0 +1,6 @@
+// 热更新 + 会话迁移包（spec §18）。
+export { createHandoffServer, requestHandoff } from './ipc.js';
+export { createUpdateScheduler } from './scheduler.js';
+export { orderSessionsByParent, restoreSessions, serializeSessions } from './snapshot.js';
+export { cleanupSnapshot, performHotUpdate } from './updater.js';
+export { checkForUpdate, compareSemver } from './version.js';

package/dist/update/ipc.d.ts

@@ -0,0 +1,15 @@
+/**
+ * 端口接管 IPC（spec §18.3）：新实例检测到端口被旧实例占用时，通过 HTTP
+ * `/handoff` 端点请求旧实例 graceful shutdown（序列化状态后退出），从而
+ * 接管端口。用普通 HTTP 而非 unix socket，便于跨平台。
+ */
+type HandoffServer = {
+    port: number;
+    close: () => Promise<void>;
+};
+/** 旧实例启动时创建 handoff 端点。收到 POST /handoff 即触发 onHandoff（序列化 + 退出）。 */
+declare function createHandoffServer(onHandoff: () => Promise<void>): Promise<HandoffServer>;
+/** 新实例请求旧实例让出端口（graceful shutdown）。失败抛错。 */
+declare function requestHandoff(port: number, host?: string): Promise<void>;
+export type { HandoffServer };
+export { createHandoffServer, requestHandoff };

package/dist/update/ipc.js

@@ -0,0 +1,41 @@
+import { createServer } from 'node:http';
+/** 旧实例启动时创建 handoff 端点。收到 POST /handoff 即触发 onHandoff（序列化 + 退出）。 */
+function createHandoffServer(onHandoff) {
+    return new Promise((resolve, reject) => {
+        const handler = async (req, res) => {
+            if (req.method === 'POST' && req.url === '/handoff') {
+                try {
+                    await onHandoff();
+                    res.writeHead(200, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: true }));
+                }
+                catch (error) {
+                    res.writeHead(500, { 'content-type': 'application/json' });
+                    res.end(JSON.stringify({ ok: false, error: String(error) }));
+                }
+                return;
+            }
+            res.writeHead(404);
+            res.end();
+        };
+        const server = createServer(handler);
+        server.on('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const addr = server.address();
+            const port = typeof addr === 'object' && addr ? addr.port : 0;
+            resolve({
+                port,
+                close: () => new Promise((res) => {
+                    server.close(() => res());
+                }),
+            });
+        });
+    });
+}
+/** 新实例请求旧实例让出端口（graceful shutdown）。失败抛错。 */
+async function requestHandoff(port, host = '127.0.0.1') {
+    const res = await fetch(`http://${host}:${port}/handoff`, { method: 'POST' });
+    if (!res.ok)
+        throw new Error(`handoff failed: HTTP ${res.status}`);
+}
+export { createHandoffServer, requestHandoff };

package/dist/update/scheduler.d.ts

@@ -0,0 +1,34 @@
+import type { UpdateCheckResult } from './version.js';
+/**
+ * 后台版本检查调度器（spec §18.1 步骤 1）。
+ *
+ * 启动时延迟 initialDelayMs 后执行首次 checkForUpdate，之后按 intervalMs
+ * 周期性检查。结果缓存到内存，供 /api/update 路由读取（避免每次请求都打
+ * npm registry）。发现新版本通过 onUpdate 回调通知上层（server.ts 转发到
+ * 前端 SSE 或前端轮询读取）。
+ *
+ * checkFn 抛错时不传播，缓存降级为 hasUpdate:false（与 checkForUpdate 自身
+ * 的容错语义一致）。
+ */
+type UpdateSchedulerOptions = {
+    checkFn: () => Promise<UpdateCheckResult>;
+    /** 周期检查间隔（毫秒），默认 1 小时。 */
+    intervalMs?: number;
+    /** 首次检查延迟（毫秒），默认 10 秒。 */
+    initialDelayMs?: number;
+    /** 每次成功检查后回调（含 hasUpdate:false）；异常路径不调用。 */
+    onUpdate?: (result: UpdateCheckResult) => void;
+};
+type UpdateScheduler = {
+    /** 启动调度（首次延迟 + 周期检查）。重复 start 是 no-op。 */
+    start(): void;
+    /** 停止调度；已缓存的 lastResult 保留。 */
+    stop(): void;
+    /** 立即触发一次检查并更新缓存；异常降级为 hasUpdate:false。 */
+    checkNow(): Promise<UpdateCheckResult>;
+    /** 当前缓存结果；未检查过返回 null。 */
+    getLastResult(): UpdateCheckResult | null;
+};
+declare function createUpdateScheduler(opts: UpdateSchedulerOptions): UpdateScheduler;
+export type { UpdateScheduler, UpdateSchedulerOptions };
+export { createUpdateScheduler };

package/dist/update/scheduler.js

@@ -0,0 +1,57 @@
+const DEFAULT_INTERVAL_MS = 60 * 60 * 1000;
+const DEFAULT_INITIAL_DELAY_MS = 10_000;
+function createUpdateScheduler(opts) {
+    const intervalMs = opts.intervalMs ?? DEFAULT_INTERVAL_MS;
+    const initialDelayMs = opts.initialDelayMs ?? DEFAULT_INITIAL_DELAY_MS;
+    // 直接引用全局 timer；vitest useFakeTimers() 会替换全局，start() 时读取即拿到 mock。
+    let intervalId = null;
+    let initialId = null;
+    let lastResult = null;
+    let started = false;
+    async function runOnce() {
+        let r;
+        try {
+            r = await opts.checkFn();
+        }
+        catch {
+            // 异常降级：缓存 hasUpdate:false，但不触发 onUpdate（避免误报）。
+            lastResult = { hasUpdate: false, currentVersion: '0.0.0', latestVersion: '0.0.0' };
+            return lastResult;
+        }
+        lastResult = r;
+        if (opts.onUpdate)
+            opts.onUpdate(r);
+        return r;
+    }
+    return {
+        start() {
+            if (started)
+                return;
+            started = true;
+            // 首次延迟：到达后执行 runOnce，再挂周期 interval。
+            // 不能直接 setInterval——initialDelayMs 与 intervalMs 通常不同。
+            initialId = setTimeout(() => {
+                void runOnce();
+                intervalId = setInterval(() => void runOnce(), intervalMs);
+            }, initialDelayMs);
+        },
+        stop() {
+            if (initialId !== null) {
+                clearTimeout(initialId);
+                initialId = null;
+            }
+            if (intervalId !== null) {
+                clearInterval(intervalId);
+                intervalId = null;
+            }
+            started = false;
+        },
+        checkNow() {
+            return runOnce();
+        },
+        getLastResult() {
+            return lastResult;
+        },
+    };
+}
+export { createUpdateScheduler };

package/dist/update/snapshot.d.ts

@@ -0,0 +1,39 @@
+import type { DB } from '../db/client.js';
+/** 序列化后的会话行（Date → epoch ms，纯 JSON 安全）。 */
+type SerializedSession = {
+    id: string;
+    title: string;
+    parentId: string | null;
+    projectId: string | null;
+    branchPoint: number | null;
+    metadata: unknown;
+    createdAt: number;
+    updatedAt: number;
+};
+/** 序列化后的会话条目行（Date → epoch ms）。 */
+type SerializedEntry = {
+    id: string;
+    sessionId: string;
+    tag: string;
+    role: string | null;
+    content: unknown;
+    toolName: string | null;
+    tokenCount: number;
+    createdAt: number;
+};
+/** 热更新迁移快照（spec §18.2）。 */
+type SessionSnapshot = {
+    version: string;
+    sessions: SerializedSession[];
+    entries: SerializedEntry[];
+    config: unknown;
+    timestamp: number;
+};
+/** 按 parentId 拓扑序排列 sessions，使父会话先于子会话插入（满足自引用 FK）。 */
+declare function orderSessionsByParent(list: SerializedSession[]): SerializedSession[];
+/** 从 DB 导出所有会话与条目为可序列化快照。 */
+declare function serializeSessions(handle: DB, config?: unknown): Promise<SessionSnapshot>;
+/** 把快照导入 DB（保留原始 id 与时间戳；父会话先插入以满足 FK）。 */
+declare function restoreSessions(handle: DB, snapshot: SessionSnapshot): Promise<void>;
+export type { SerializedEntry, SerializedSession, SessionSnapshot };
+export { orderSessionsByParent, restoreSessions, serializeSessions };

package/dist/update/snapshot.js

@@ -0,0 +1,99 @@
+import { sessionEntries, sessions } from '../db/schema.js';
+const CURRENT_SNAPSHOT_VERSION = '0.1.0';
+function toDateMs(v) {
+    if (v instanceof Date)
+        return v.getTime();
+    if (typeof v === 'string' || typeof v === 'number')
+        return new Date(v).getTime();
+    return Date.now();
+}
+function toSerializedSession(row) {
+    return {
+        id: row.id,
+        title: row.title,
+        parentId: row.parentId,
+        projectId: row.projectId,
+        branchPoint: row.branchPoint,
+        metadata: row.metadata,
+        createdAt: toDateMs(row.createdAt),
+        updatedAt: toDateMs(row.updatedAt),
+    };
+}
+function toSerializedEntry(row) {
+    return {
+        id: row.id,
+        sessionId: row.sessionId,
+        tag: row.tag,
+        role: row.role,
+        content: row.content,
+        toolName: row.toolName,
+        tokenCount: row.tokenCount ?? 0,
+        createdAt: toDateMs(row.createdAt),
+    };
+}
+/** 按 parentId 拓扑序排列 sessions，使父会话先于子会话插入（满足自引用 FK）。 */
+function orderSessionsByParent(list) {
+    const byId = new Map(list.map((s) => [s.id, s]));
+    const ordered = [];
+    const seen = new Set();
+    const visit = (s) => {
+        if (seen.has(s.id))
+            return;
+        const parent = s.parentId ? byId.get(s.parentId) : undefined;
+        if (parent && !seen.has(parent.id))
+            visit(parent);
+        seen.add(s.id);
+        ordered.push(s);
+    };
+    for (const s of list)
+        visit(s);
+    return ordered;
+}
+/** 从 DB 导出所有会话与条目为可序列化快照。 */
+async function serializeSessions(handle, config) {
+    const [sRows, eRows] = await Promise.all([
+        handle.db.select().from(sessions),
+        handle.db.select().from(sessionEntries),
+    ]);
+    return {
+        version: CURRENT_SNAPSHOT_VERSION,
+        sessions: sRows.map(toSerializedSession),
+        entries: eRows.map(toSerializedEntry),
+        config: config ?? null,
+        timestamp: Date.now(),
+    };
+}
+/** 把快照导入 DB（保留原始 id 与时间戳；父会话先插入以满足 FK）。 */
+async function restoreSessions(handle, snapshot) {
+    for (const s of orderSessionsByParent(snapshot.sessions)) {
+        await handle.db
+            .insert(sessions)
+            .values({
+            id: s.id,
+            title: s.title,
+            parentId: s.parentId,
+            projectId: s.projectId,
+            branchPoint: s.branchPoint,
+            metadata: s.metadata,
+            createdAt: new Date(s.createdAt),
+            updatedAt: new Date(s.updatedAt),
+        })
+            .onConflictDoNothing();
+    }
+    for (const e of snapshot.entries) {
+        await handle.db
+            .insert(sessionEntries)
+            .values({
+            id: e.id,
+            sessionId: e.sessionId,
+            tag: e.tag,
+            role: e.role,
+            content: e.content,
+            toolName: e.toolName,
+            tokenCount: e.tokenCount,
+            createdAt: new Date(e.createdAt),
+        })
+            .onConflictDoNothing();
+    }
+}
+export { orderSessionsByParent, restoreSessions, serializeSessions };

package/dist/update/updater.d.ts

@@ -0,0 +1,48 @@
+import type { SessionSnapshot } from './snapshot.js';
+/** 热更新执行结果（spec §18）。 */
+type HotUpdateResult = {
+    _tag: 'success';
+    snapshotPath: string;
+} | {
+    _tag: 'install_failed';
+    error: string;
+    snapshotPath: string;
+} | {
+    _tag: 'spawn_failed';
+    error: string;
+    snapshotPath: string;
+};
+/**
+ * 启动新实例的函数签名。
+ * @param snapshotPath 快照文件路径（旧实例已写入）
+ * @param argv          传给新进程的完整参数（含 restore flag + 可选 handoff flag）
+ */
+type SpawnFn = (snapshotPath: string, argv: string[]) => Promise<void>;
+type HotUpdateOptions = {
+    /** 自更新安装函数；默认 `npm install -g <pkg>`。 */
+    installFn?: (pkg: string) => Promise<void>;
+    /** 启动新实例的函数；默认 detached spawn 当前进程入口。 */
+    spawnNewInstanceFn?: SpawnFn;
+    packageName?: string;
+    /** 快照写入路径；默认临时目录。 */
+    snapshotPath?: string;
+    /** 新实例接收快照的参数前缀（默认 --restore）。 */
+    restoreFlag?: string;
+    /** 旧实例 handoff 端口；提供时新实例启动后请求旧实例 graceful shutdown。 */
+    handoffPort?: number;
+};
+/**
+ * 执行热更新（spec §18.1-18.2 流程）：
+ *   1. 序列化当前会话状态到快照文件
+ *   2. 全局自更新（npm install -g）
+ *   3. detached 启动新版本实例，传入快照路径（新实例 restore + 端口接管）
+ *
+ * 注：旧实例的 graceful shutdown / 端口让渡由新实例启动后通过 IPC 协调
+ * （见 ipc.ts），本函数只负责"序列化 + 安装 + 接力"。若提供 handoffPort，
+ * argv 会带上 --handoff-port，新实例据此 requestHandoff 通知旧实例退出。
+ */
+declare function performHotUpdate(snapshot: SessionSnapshot, opts?: HotUpdateOptions): Promise<HotUpdateResult>;
+/** 清理快照临时目录（热更新完成或放弃后调用）。 */
+declare function cleanupSnapshot(snapshotPath: string): Promise<void>;
+export type { HotUpdateOptions, HotUpdateResult, SpawnFn };
+export { cleanupSnapshot, performHotUpdate };