c0de-agent 0.0.0 → 1.0.0

package/dist/session/compaction.d.ts

@@ -0,0 +1,27 @@
+import type { DB } from '../db/client.js';
+import type { Message } from '../shared/types/message.js';
+import type { CompactionConfig, CompactionResult, HotFile, Summarizer } from './types.js';
+/**
+ * Find a safe cut point: the index of the most recent 'user' message
+ * at or before `preferredCut`. Cutting at a user-turn boundary ensures
+ * we never split an assistant reply from its tool results.
+ */
+declare function findSafeCutPoint(messages: Message[], preferredCut: number): number;
+/** Extract frequently-accessed files (read ≥ 2 times) from message history. */
+declare function extractHotFiles(messages: Message[]): HotFile[];
+/** Build the LLM summarization prompt for a set of messages. */
+declare function buildCompactionPrompt(messages: Message[]): string;
+/**
+ * Compact a session: summarize old messages, archive them, keep recent ones.
+ *
+ * The keep window is driven by a token budget (`keepRecentTokens`), not a
+ * fixed message count — so compaction actually fires on a few long messages
+ * instead of silently no-op'ing when message count is small. The `summarizer`
+ * function is injected (the session layer never imports the LLM package).
+ *
+ * All destructive writes (archive + snapshot + delete + insert) run inside a
+ * single transaction so a mid-way failure cannot lose history: the originals
+ * are only deleted once the summary is durably stored.
+ */
+declare function compactSession(handle: DB, sessionId: string, summarizer: Summarizer, config?: Partial<CompactionConfig>): Promise<CompactionResult>;
+export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint };

package/dist/session/compaction.js

@@ -0,0 +1,192 @@
+import { generateId } from '../shared/index.js';
+import { archiveOriginalEntries } from './archive.js';
+import { deleteEntriesByIds, getMessages, insertEntry } from './message.js';
+import { upsertFileSnapshot } from './snapshot.js';
+import { estimateMessageTokens, estimateTokens } from './token.js';
+/**
+ * Find a safe cut point: the index of the most recent 'user' message
+ * at or before `preferredCut`. Cutting at a user-turn boundary ensures
+ * we never split an assistant reply from its tool results.
+ */
+function findSafeCutPoint(messages, preferredCut) {
+    const upper = Math.min(preferredCut, messages.length);
+    for (let i = upper; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg && msg.role === 'user')
+            return i;
+    }
+    return 0;
+}
+/** Extract frequently-accessed files (read ≥ 2 times) from message history. */
+function extractHotFiles(messages) {
+    const accessCount = new Map();
+    const callPath = new Map();
+    const latestContent = new Map();
+    for (const msg of messages) {
+        for (const part of msg.content) {
+            if (part._tag === 'tool_call' && part.tool === 'read') {
+                const input = part.input;
+                if (input?.path) {
+                    accessCount.set(input.path, (accessCount.get(input.path) ?? 0) + 1);
+                    callPath.set(part.id, input.path);
+                }
+            }
+            if (part._tag === 'tool_result' && part.tool === 'read') {
+                if (part.output._tag === 'success') {
+                    const path = callPath.get(part.id);
+                    if (path)
+                        latestContent.set(path, part.output.output);
+                }
+            }
+        }
+    }
+    const hot = [];
+    for (const [path, count] of accessCount) {
+        if (count >= 2) {
+            const content = latestContent.get(path);
+            if (content) {
+                hot.push({ path, content, tokenCount: estimateTokens(content), accessCount: count });
+            }
+        }
+    }
+    return hot.sort((a, b) => b.accessCount - a.accessCount).slice(0, 10);
+}
+/** Build the LLM summarization prompt for a set of messages. */
+function buildCompactionPrompt(messages) {
+    const history = messages
+        .map((m) => `[${m.role}] ${m.content.map((p) => (p._tag === 'text' ? p.text : JSON.stringify(p))).join(' ')}`)
+        .join('\n');
+    return `将以下对话历史压缩为结构化摘要。保留关键信息，丢弃冗余细节。
+
+## Goal
+用户的目标是什么
+
+## Progress
+已完成的工作
+
+## Decisions
+做出的关键决策
+
+## Next Steps
+接下来要做什么
+
+## Critical Context
+必须记住的上下文（文件路径、变量名、错误信息等）
+
+## Modified Files
+修改过的文件列表及变更摘要
+
+---
+对话历史：
+${history}`;
+}
+/**
+ * Token cost of a single message, honoring a stored tokenCount when present.
+ * Mirrors core/context.ts rawMessageTokens without crossing the core→session
+ * layer boundary (core already imports session, so session must not import core).
+ */
+function messageTokens(m) {
+    if (m.tokenCount > 0)
+        return m.tokenCount;
+    return estimateMessageTokens(m.content);
+}
+/**
+ * Find the start index of the token-budgeted keep window by reverse-walking
+ * from the newest message. This is the session-layer analogue of
+ * core/context.ts fitToBudget's keep-window logic: accumulate tokens from the
+ * end until `keepRecentTokens` is exceeded, then everything older is eligible
+ * for compaction. At least the most recent message is always retained.
+ */
+function findKeepRecentStart(messages, keepRecentTokens) {
+    if (messages.length === 0)
+        return 0;
+    let used = 0;
+    let start = messages.length;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const m = messages[i];
+        if (!m)
+            continue;
+        const tc = messageTokens(m);
+        if (used + tc > keepRecentTokens)
+            break;
+        used += tc;
+        start = i;
+    }
+    // Always retain at least the most recent message.
+    return Math.min(start, messages.length - 1);
+}
+/**
+ * Compact a session: summarize old messages, archive them, keep recent ones.
+ *
+ * The keep window is driven by a token budget (`keepRecentTokens`), not a
+ * fixed message count — so compaction actually fires on a few long messages
+ * instead of silently no-op'ing when message count is small. The `summarizer`
+ * function is injected (the session layer never imports the LLM package).
+ *
+ * All destructive writes (archive + snapshot + delete + insert) run inside a
+ * single transaction so a mid-way failure cannot lose history: the originals
+ * are only deleted once the summary is durably stored.
+ */
+async function compactSession(handle, sessionId, summarizer, config) {
+    const messages = await getMessages(handle, sessionId);
+    const keepRecentTokens = config?.keepRecentTokens ?? 4000;
+    if (messages.length === 0) {
+        return { compacted: false, reason: 'too_few_messages' };
+    }
+    // Reverse-walk from the newest message to find the keep window boundary,
+    // driven by a token budget rather than a fixed message count.
+    const keepStart = findKeepRecentStart(messages, keepRecentTokens);
+    // Align the cut to a user-turn boundary so we never split an assistant
+    // reply from its tool results.
+    const cutPoint = findSafeCutPoint(messages, keepStart);
+    const compactMessages = messages.slice(0, cutPoint);
+    const keepMessages = messages.slice(cutPoint);
+    if (compactMessages.length === 0) {
+        return { compacted: false, reason: 'nothing_to_compact' };
+    }
+    const prompt = buildCompactionPrompt(compactMessages);
+    // Run the (slow, network) summarizer OUTSIDE the transaction so we don't
+    // hold a DB transaction open across an LLM call.
+    const summary = await summarizer(prompt);
+    const compactionEntryId = generateId();
+    // Atomic rewrite: archive originals → upsert snapshots → delete originals →
+    // insert summary. If any step throws, the whole transaction rolls back and
+    // the original message history is left intact.
+    const { archiveId, fileSnapshotIds } = await handle.db.transaction(async (tx) => {
+        const txHandle = { db: tx, close: handle.close };
+        const archiveId = await archiveOriginalEntries(txHandle, sessionId, compactMessages, 'compaction', summary, compactionEntryId);
+        const fileSnapshotIds = [];
+        if (config?.preserveSnapshots !== false) {
+            const hotFiles = extractHotFiles(compactMessages);
+            for (const file of hotFiles) {
+                const id = await upsertFileSnapshot(txHandle, sessionId, file.path, file.content);
+                fileSnapshotIds.push(id);
+            }
+        }
+        await deleteEntriesByIds(txHandle, compactMessages.map((m) => m.id));
+        await insertEntry(txHandle, {
+            id: compactionEntryId,
+            sessionId,
+            tag: 'compaction',
+            content: {
+                summary,
+                originalEntryIds: compactMessages.map((m) => m.id),
+                archiveId,
+            },
+            tokenCount: estimateTokens(summary),
+            // Position the summary at the first compacted message's timestamp so it
+            // sorts BEFORE the kept recent messages under createdAt-ascending order.
+            createdAt: compactMessages[0] ? new Date(compactMessages[0].createdAt) : new Date(),
+        });
+        return { archiveId, fileSnapshotIds };
+    });
+    return {
+        compacted: true,
+        summary,
+        archiveId,
+        fileSnapshots: fileSnapshotIds,
+        compactedCount: compactMessages.length,
+        keptCount: keepMessages.length,
+    };
+}
+export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint };

package/dist/session/context.d.ts

@@ -0,0 +1,16 @@
+import type { DB } from '../db/client.js';
+import type { ChatMessage } from '../shared/types/llm.js';
+import type { Message } from '../shared/types/message.js';
+import type { FileSnapshot, SessionEntry } from './types.js';
+/** Convert a stored Message to a protocol-level ChatMessage for the LLM. */
+declare function messageToChatMessage(msg: Message): ChatMessage;
+/** Convert all session entries (messages + special) to ChatMessage[] for the LLM. */
+declare function entriesToChatMessages(entries: SessionEntry[], snapshots: FileSnapshot[]): ChatMessage[];
+/** Inject file snapshot block after the first message (preserves cache prefix). */
+declare function injectSnapshots(messages: ChatMessage[], snapshots: FileSnapshot[]): ChatMessage[];
+/** Get the full session context: all entries + file snapshots. */
+declare function getSessionContext(handle: DB, sessionId: string): Promise<{
+    entries: SessionEntry[];
+    snapshots: FileSnapshot[];
+}>;
+export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage };

package/dist/session/context.js

@@ -0,0 +1,173 @@
+import { getEntries } from './message.js';
+import { getFileSnapshots } from './snapshot.js';
+/**
+ * Drop tool messages whose id cannot be paired with an assistant tool_call,
+ * and inject synthetic tool results for orphan tool_calls (assistant 发出了
+ * tool_call 但无对应 tool result——服务重启中断场景）。
+ *
+ * OpenAI Chat 协议要求每个 role=tool 消息必须有 tool_call_id，且必须匹配
+ * 前面某条 assistant 消息的 tool_calls[].id。部分输出不规范的 provider
+ * 会产生空 id 的 tool_call/tool_result 碎片；这些碎片发回 provider 会触发
+ * "invalid tool_call_id"。这里在重建上下文时丢弃：
+ *   - assistant.toolCalls 里 id 为空的项（连带丢弃其后无法配对的 tool result）
+ *   - role=tool 但 toolCallId 为空、或找不到对应 assistant tool_call 的消息
+ * 正常（完整配对）的数据不受影响。
+ *
+ * 新增：assistant 有有效 tool_call 但后续无匹配 tool result（服务重启中断）时，
+ * 注入合成 tool result 告知模型工具被中断，而非丢弃 tool_call 让模型
+ * 盲目重试可能已产生副作用的非幂等工具。
+ */
+function sanitizeToolPairs(messages) {
+    // 收集所有有效的 assistant tool_call id（非空）
+    const validCallIds = new Set();
+    for (const m of messages) {
+        if (m.role === 'assistant' && m.toolCalls) {
+            for (const tc of m.toolCalls) {
+                if (tc.id)
+                    validCallIds.add(tc.id);
+            }
+        }
+    }
+    // 收集已有 tool result 配对的 tool_call id（用于检测孤儿 tool_call）
+    const answeredCallIds = new Set();
+    for (const m of messages) {
+        if (m.role === 'tool' && m.toolCallId && validCallIds.has(m.toolCallId)) {
+            answeredCallIds.add(m.toolCallId);
+        }
+    }
+    const result = [];
+    for (const m of messages) {
+        if (m.role === 'assistant' && m.toolCalls) {
+            // 丢弃 id 为空的 tool_call 项；若删空了则整个 toolCalls 移除
+            const filtered = m.toolCalls.filter((tc) => tc.id);
+            if (filtered.length === 0) {
+                result.push({ role: 'assistant', content: m.content });
+            }
+            else {
+                result.push({ ...m, toolCalls: filtered });
+                // 为无 result 配对的 tool_call 注入合成 result（服务中断场景）
+                for (const tc of filtered) {
+                    if (!answeredCallIds.has(tc.id)) {
+                        result.push({
+                            role: 'tool',
+                            toolCallId: tc.id,
+                            content: JSON.stringify({
+                                error: 'Tool execution was interrupted by server restart',
+                            }),
+                        });
+                    }
+                }
+            }
+            continue;
+        }
+        if (m.role === 'tool') {
+            // toolCallId 为空、或找不到对应 assistant tool_call：丢弃整条 tool 消息
+            if (!m.toolCallId || !validCallIds.has(m.toolCallId)) {
+                continue;
+            }
+        }
+        result.push(m);
+    }
+    return result;
+}
+/** Convert a stored Message to a protocol-level ChatMessage for the LLM. */
+function messageToChatMessage(msg) {
+    const textParts = msg.content
+        .filter((p) => p._tag === 'text' || p._tag === 'thinking')
+        .map((p) => (p._tag === 'thinking' ? `<think>${p.text}</think>` : p.text))
+        .join('');
+    const toolCalls = msg.content
+        .filter((p) => p._tag === 'tool_call')
+        .map((p) => ({
+        id: p.id,
+        name: p.tool,
+        arguments: JSON.stringify(p.input),
+    }));
+    const toolResultPart = msg.content.find((p) => p._tag === 'tool_result');
+    const imageParts = msg.content.filter((p) => p._tag === 'image');
+    // 含图片：构建多模态 content 数组（text 在前，image 在后）
+    if (imageParts.length > 0) {
+        const parts = [];
+        if (textParts)
+            parts.push({ type: 'text', text: textParts });
+        for (const img of imageParts) {
+            if (img._tag !== 'image')
+                continue;
+            parts.push({ type: 'image', mediaType: img.mediaType, data: img.data });
+        }
+        const multimodal = { role: msg.role, content: parts };
+        if (toolCalls.length > 0)
+            multimodal.toolCalls = toolCalls;
+        return multimodal;
+    }
+    // 无图片：保持原纯字符串逻辑（零回归）
+    const chat = {
+        role: msg.role,
+        content: textParts || (toolResultPart ? JSON.stringify(toolResultPart.output) : ''),
+    };
+    if (toolCalls.length > 0) {
+        chat.toolCalls = toolCalls;
+    }
+    if (toolResultPart && toolResultPart._tag === 'tool_result') {
+        chat.toolCallId = toolResultPart.id;
+        chat.content = JSON.stringify(toolResultPart.output);
+    }
+    return chat;
+}
+/** Convert all session entries (messages + special) to ChatMessage[] for the LLM. */
+function entriesToChatMessages(entries, snapshots) {
+    const messages = [];
+    for (const entry of entries) {
+        if (!('_tag' in entry)) {
+            messages.push(messageToChatMessage(entry));
+            continue;
+        }
+        switch (entry._tag) {
+            case 'compaction':
+            case 'squash':
+                messages.push({ role: 'system', content: `[Compacted History]\n${entry.summary}` });
+                break;
+            case 'branch_summary':
+                messages.push({ role: 'system', content: `[Branch Context]\n${entry.summary}` });
+                break;
+            case 'steering':
+                messages.push({ role: 'system', content: entry.content });
+                break;
+        }
+    }
+    return injectSnapshots(sanitizeToolPairs(messages), snapshots);
+}
+/** Inject file snapshot block after the first message (preserves cache prefix). */
+function injectSnapshots(messages, snapshots) {
+    if (snapshots.length === 0)
+        return messages;
+    // Keep only the highest-version snapshot per filePath (avoid stale duplicates).
+    const latestByPath = new Map();
+    for (const s of snapshots) {
+        const prev = latestByPath.get(s.filePath);
+        if (!prev || s.version > prev.version)
+            latestByPath.set(s.filePath, s);
+    }
+    const block = [...latestByPath.values()]
+        .map((s) => `[Cached File: ${s.filePath}]\n\`\`\`\n${s.content}\n\`\`\``)
+        .join('\n\n');
+    const snapshotMessage = {
+        role: 'system',
+        content: `[Active File Snapshots — DO NOT re-read these files]\n${block}`,
+    };
+    if (messages.length === 0)
+        return [snapshotMessage];
+    const first = messages[0];
+    if (!first)
+        return [snapshotMessage];
+    return [first, snapshotMessage, ...messages.slice(1)];
+}
+/** Get the full session context: all entries + file snapshots. */
+async function getSessionContext(handle, sessionId) {
+    const [entries, snapshots] = await Promise.all([
+        getEntries(handle, sessionId),
+        getFileSnapshots(handle, sessionId),
+    ]);
+    return { entries, snapshots };
+}
+export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage };

package/dist/session/index.d.ts

@@ -0,0 +1,10 @@
+export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, } from './archive.js';
+export { forkSession, getBranches, getTree } from './branch.js';
+export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint, } from './compaction.js';
+export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage, } from './context.js';
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, } from './message.js';
+export { createSession, deleteSession, getLLMSegments, getSession, listSessions, migrateLegacyDetails, saveLLMSegments, segmentFingerprint, touchSession, updateSessionTitle, } from './session.js';
+export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, } from './snapshot.js';
+export { squashRecent } from './squash.js';
+export { estimateMessageTokens, estimateTokens } from './token.js';
+export type { ArchiveRef, BranchSummaryEntry, CompactionArchive, CompactionConfig, CompactionEntry, CompactionResult, FileSnapshot, HotFile, MessageInput, SessionEntry, SessionTreeNode, SquashConfig, SquashEntry, SteeringEntry, Summarizer, } from './types.js';

package/dist/session/index.js

@@ -0,0 +1,10 @@
+// Session layer: conversation persistence, branching, compaction, and context reconstruction.
+export { archiveOriginalEntries, getArchive, getArchiveOriginalEntries, parseArchiveReference, resolveArchiveReference, searchArchives, } from './archive.js';
+export { forkSession, getBranches, getTree } from './branch.js';
+export { buildCompactionPrompt, compactSession, extractHotFiles, findSafeCutPoint, } from './compaction.js';
+export { entriesToChatMessages, getSessionContext, injectSnapshots, messageToChatMessage, } from './context.js';
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, } from './message.js';
+export { createSession, deleteSession, getLLMSegments, getSession, listSessions, migrateLegacyDetails, saveLLMSegments, segmentFingerprint, touchSession, updateSessionTitle, } from './session.js';
+export { checkFileSnapshot, getFileSnapshots, getLatestFileSnapshot, upsertFileSnapshot, } from './snapshot.js';
+export { squashRecent } from './squash.js';
+export { estimateMessageTokens, estimateTokens } from './token.js';

package/dist/session/message.d.ts

@@ -0,0 +1,22 @@
+import type { DB } from '../db/client.js';
+import { sessionEntries } from '../db/schema.js';
+import type { Message } from '../shared/types/message.js';
+import type { MessageInput, SessionEntry } from './types.js';
+/** Append a message to a session. Returns the stored Message with generated id/timestamp. */
+declare function appendMessage(handle: DB, sessionId: string, input: MessageInput): Promise<Message>;
+/** Get messages for a session (tag='message' only), ordered chronologically. */
+declare function getMessages(handle: DB, sessionId: string, opts?: {
+    limit?: number;
+    offset?: number;
+}): Promise<Message[]>;
+/** Count messages in a session. */
+declare function getMessageCount(handle: DB, sessionId: string): Promise<number>;
+/** Delete all messages after the given 0-based index (keeps 0..index inclusive). */
+declare function deleteMessagesAfter(handle: DB, sessionId: string, messageIndex: number): Promise<void>;
+/** Low-level: get ALL entries (messages + special) in chronological order. */
+declare function getEntries(handle: DB, sessionId: string): Promise<SessionEntry[]>;
+/** Low-level: delete entries by id. */
+declare function deleteEntriesByIds(handle: DB, ids: string[]): Promise<void>;
+/** Low-level: insert a raw entry row (for compaction/squash/branch_summary/steering). */
+declare function insertEntry(handle: DB, values: typeof sessionEntries.$inferInsert): Promise<typeof sessionEntries.$inferSelect>;
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, };

package/dist/session/message.js

@@ -0,0 +1,145 @@
+import { and, asc, count, eq, inArray } from 'drizzle-orm';
+import { sessionEntries } from '../db/schema.js';
+import { generateId } from '../shared/index.js';
+import { touchSession } from './session.js';
+import { estimateMessageTokens } from './token.js';
+/** Convert a Date-like DB value to epoch milliseconds. */
+function toEpochMs(value) {
+    if (value instanceof Date)
+        return value.getTime();
+    if (typeof value === 'number')
+        return value;
+    return new Date(value).getTime();
+}
+/** Convert a message-tagged row to a Message. */
+function rowToMessage(row) {
+    return {
+        id: row.id,
+        sessionId: row.sessionId,
+        role: row.role,
+        content: row.content,
+        tokenCount: row.tokenCount ?? 0,
+        createdAt: toEpochMs(row.createdAt),
+    };
+}
+/** Convert any row to a SessionEntry (dispatch on tag). */
+function rowToEntry(row) {
+    if (row.tag === 'message') {
+        return rowToMessage(row);
+    }
+    const content = row.content;
+    const createdAt = toEpochMs(row.createdAt);
+    switch (row.tag) {
+        case 'compaction':
+            return {
+                _tag: 'compaction',
+                id: row.id,
+                sessionId: row.sessionId,
+                summary: content.summary,
+                originalEntryIds: content.originalEntryIds,
+                archiveId: content.archiveId,
+                tokenCount: row.tokenCount ?? 0,
+                createdAt,
+            };
+        case 'squash':
+            return {
+                _tag: 'squash',
+                id: row.id,
+                sessionId: row.sessionId,
+                summary: content.summary,
+                squashedEntryIds: content.squashedEntryIds,
+                archiveId: content.archiveId,
+                tokenCount: row.tokenCount ?? 0,
+                createdAt,
+            };
+        case 'branch_summary':
+            return {
+                _tag: 'branch_summary',
+                id: row.id,
+                sessionId: row.sessionId,
+                summary: content.summary,
+                sourceSessionId: content.sourceSessionId,
+                createdAt,
+            };
+        case 'steering':
+            return {
+                _tag: 'steering',
+                id: row.id,
+                sessionId: row.sessionId,
+                content: content.text,
+                createdAt,
+            };
+        default:
+            // Fallback: treat unknown tags as messages
+            return rowToMessage(row);
+    }
+}
+/** Append a message to a session. Returns the stored Message with generated id/timestamp. */
+async function appendMessage(handle, sessionId, input) {
+    const tokenCount = input.tokenCount ?? estimateMessageTokens(input.content);
+    const [row] = await handle.db
+        .insert(sessionEntries)
+        .values({
+        id: generateId(),
+        sessionId,
+        tag: 'message',
+        role: input.role,
+        content: input.content,
+        tokenCount,
+    })
+        .returning();
+    await touchSession(handle, sessionId);
+    if (!row)
+        throw new Error('Failed to insert message');
+    return rowToMessage(row);
+}
+/** Get messages for a session (tag='message' only), ordered chronologically. */
+async function getMessages(handle, sessionId, opts) {
+    const rows = await handle.db
+        .select()
+        .from(sessionEntries)
+        .where(and(eq(sessionEntries.sessionId, sessionId), eq(sessionEntries.tag, 'message')))
+        .orderBy(asc(sessionEntries.createdAt))
+        .limit(opts?.limit ?? 100_000)
+        .offset(opts?.offset ?? 0);
+    return rows.map(rowToMessage);
+}
+/** Count messages in a session. */
+async function getMessageCount(handle, sessionId) {
+    const [result] = await handle.db
+        .select({ value: count() })
+        .from(sessionEntries)
+        .where(and(eq(sessionEntries.sessionId, sessionId), eq(sessionEntries.tag, 'message')));
+    return result?.value ?? 0;
+}
+/** Delete all messages after the given 0-based index (keeps 0..index inclusive). */
+async function deleteMessagesAfter(handle, sessionId, messageIndex) {
+    const messages = await getMessages(handle, sessionId);
+    const toDelete = messages.slice(messageIndex + 1);
+    if (toDelete.length > 0) {
+        await handle.db.delete(sessionEntries).where(inArray(sessionEntries.id, toDelete.map((m) => m.id)));
+    }
+}
+/** Low-level: get ALL entries (messages + special) in chronological order. */
+async function getEntries(handle, sessionId) {
+    const rows = await handle.db
+        .select()
+        .from(sessionEntries)
+        .where(eq(sessionEntries.sessionId, sessionId))
+        .orderBy(asc(sessionEntries.createdAt));
+    return rows.map(rowToEntry);
+}
+/** Low-level: delete entries by id. */
+async function deleteEntriesByIds(handle, ids) {
+    if (ids.length === 0)
+        return;
+    await handle.db.delete(sessionEntries).where(inArray(sessionEntries.id, ids));
+}
+/** Low-level: insert a raw entry row (for compaction/squash/branch_summary/steering). */
+async function insertEntry(handle, values) {
+    const [row] = await handle.db.insert(sessionEntries).values(values).returning();
+    if (!row)
+        throw new Error('Failed to insert entry');
+    return row;
+}
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, };

package/dist/session/session.d.ts

@@ -0,0 +1,37 @@
+import type { DB } from '../db/client.js';
+import { sessions } from '../db/schema.js';
+import type { LLMSegment } from '../shared/types/agent.js';
+import type { ChatTool } from '../shared/types/llm.js';
+import type { LastRun, Session } from '../shared/types/message.js';
+/** Convert a DB row (with Date timestamps) to the shared Session type (with number timestamps). */
+export declare function rowToSession(row: typeof sessions.$inferSelect): Session;
+/** Create a new root session. */
+declare function createSession(handle: DB, title: string, projectId?: string, agentType?: string): Promise<Session>;
+/** Get a session by id, or null if not found. */
+declare function getSession(handle: DB, id: string): Promise<Session | null>;
+/** List all sessions. */
+declare function listSessions(handle: DB): Promise<Session[]>;
+/** Delete a session (cascades to entries, archives, snapshots via FK). */
+declare function deleteSession(handle: DB, id: string): Promise<void>;
+/** Update a session's title. */
+declare function updateSessionTitle(handle: DB, id: string, title: string): Promise<void>;
+/** Bump updatedAt to now (used after appending messages). */
+declare function touchSession(handle: DB, id: string): Promise<void>;
+/** 规格化工具集并计算前缀指纹。tools 顺序不影响指纹（按 name 排序）。 */
+export declare function segmentFingerprint(systemPrompt: string, tools: ChatTool[]): string;
+/**
+ * 将旧 metadata.llmDetails 迁移为单个 legacy segment。
+ * - 无 llmDetails 或已有 segments → 原样返回。
+ * - 否则取首条的 systemPrompt/tools 作为段首快照，所有旧 detail 转为 calls，
+ *   responseText 从 responseChunks 的 text 块拼接提取。
+ * 幂等：迁移后 llmDetails 字段被移除，不会重复迁移。
+ */
+export declare function migrateLegacyDetails(meta: Record<string, unknown>): Record<string, unknown>;
+/** 读取会话 metadata.segments（读取时顺带迁移旧 llmDetails）。 */
+export declare function getLLMSegments(handle: DB, id: string): Promise<LLMSegment[]>;
+/** 全量替换会话 metadata.segments（每轮 loop 结束写入；段数据轻量）。 */
+export declare function saveLLMSegments(handle: DB, id: string, segments: LLMSegment[]): Promise<void>;
+/** 更新会话 metadata.lastRun（agent run 开始/结束时写入；重启后检测中断用）。 */
+declare function updateSessionLastRun(handle: DB, id: string, lastRun: LastRun): Promise<void>;
+declare function listSessionsByProject(handle: DB, projectId: string): Promise<Session[]>;
+export { createSession, deleteSession, getSession, listSessions, listSessionsByProject, touchSession, updateSessionLastRun, updateSessionTitle, };