c0de-agent 1.11.0 → 1.13.0

package/dist/session/message.d.ts

@@ -9,6 +9,12 @@ declare function getMessages(handle: DB, sessionId: string, opts?: {
     limit?: number;
     offset?: number;
 }): Promise<Message[]>;
+/**
+ * 会话 steering 条目映射为 Message 形态（role='user'，内容为 steering part）。
+ * 时间线渲染与消息合并使用（P0：追加指令持久化后的展示路径）；
+ * 不并入 getMessages——compaction/shake/export 等仅处理真实消息的消费者不受影响。
+ */
+declare function getSteeringAsMessages(handle: DB, sessionId: string): 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). */
@@ -19,4 +25,4 @@ declare function getEntries(handle: DB, sessionId: string): Promise<SessionEntry
 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, };
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, };

package/dist/session/message.js

@@ -104,6 +104,26 @@ async function getMessages(handle, sessionId, opts) {
         .offset(opts?.offset ?? 0);
     return rows.map(rowToMessage);
 }
+/**
+ * 会话 steering 条目映射为 Message 形态（role='user'，内容为 steering part）。
+ * 时间线渲染与消息合并使用（P0：追加指令持久化后的展示路径）；
+ * 不并入 getMessages——compaction/shake/export 等仅处理真实消息的消费者不受影响。
+ */
+async function getSteeringAsMessages(handle, sessionId) {
+    const rows = await handle.db
+        .select()
+        .from(sessionEntries)
+        .where(and(eq(sessionEntries.sessionId, sessionId), eq(sessionEntries.tag, 'steering')))
+        .orderBy(asc(sessionEntries.createdAt));
+    return rows.map((row) => ({
+        id: row.id,
+        sessionId: row.sessionId,
+        role: 'user',
+        content: [{ _tag: 'steering', text: row.content.text ?? '' }],
+        tokenCount: row.tokenCount ?? 0,
+        createdAt: toEpochMs(row.createdAt),
+    }));
+}
 /** Count messages in a session. */
 async function getMessageCount(handle, sessionId) {
     const [result] = await handle.db
@@ -142,4 +162,4 @@ async function insertEntry(handle, values) {
         throw new Error('Failed to insert entry');
     return row;
 }
-export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, insertEntry, };
+export { appendMessage, deleteEntriesByIds, deleteMessagesAfter, getEntries, getMessageCount, getMessages, getSteeringAsMessages, insertEntry, };

package/dist/session/session.d.ts

@@ -2,39 +2,179 @@ 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';
+import type { LastRun, Session, SessionMetadata } 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, source?: 'web' | 'cli'): Promise<Session>;
+declare function createSession(handle: DB, title: string, projectId?: string, agentType?: string, source?: 'web' | 'cli', 
+/** P1 会话树治理：子 agent 会话挂到父会话（树内嵌套 + 删除级联）。 */
+parentId?: string, 
+/** 会话工作目录（CLI 会话必填：Web 打开时 agent 工具在该目录执行，而非 serve cwd）。 */
+worktreePath?: string, 
+/** 初始 metadata（如工作流运行会话记录 workflowName，供中断恢复指引展示）。 */
+metadata?: Record<string, unknown>): Promise<Session>;
+/**
+ * Web 会话树可见性条件：web 会话（source 为 null/web）或「持久的 CLI 会话」。
+ * 一次性 CLI print 会话与 CLI 来源的 workflow 会话是临时数据，隐藏；
+ * Web 来源的 workflow 会话（source=null）在树中可见（标题带时间戳）。
+ * 两类临时会话到期后统一**移入回收站**（purgeTemporarySessions），不再物理清除——
+ * 可见节点（含其子 agent 会话）享有 60 天可恢复承诺。
+ * --continue 续接后 agentType 已清除（upgradeTemporarySession），即对 Web 可见。
+ */
+export declare function webVisibleSessionCondition(): import("drizzle-orm").SQL<unknown> | undefined;
 /** Get a session by id, or null if not found. */
 declare function getSession(handle: DB, id: string): Promise<Session | null>;
-/** List all active sessions (未软删除、非 CLI 来源；source 为 NULL 的旧数据视为 web). */
+/** List all active sessions（未软删除、Web 树可见：web 会话 + 持久化 CLI 会话）。 */
 declare function listSessions(handle: DB): Promise<Session[]>;
 /** 列出所有未软删除会话（含 CLI 来源；供 ACP/CLI 等非 Web 消费者使用）。 */
 declare function listAllSessions(handle: DB): Promise<Session[]>;
-/** List soft-deleted sessions (回收站). */
-declare function listDeletedSessions(handle: DB): Promise<Session[]>;
+/** List soft-deleted sessions (回收站)；projectId 提供时仅列出归属该项目的会话
+ *  （P1-7：回收站此前全库共享，项目 A 的界面能清空项目 B 的删除会话）。 */
+declare function listDeletedSessions(handle: DB, projectId?: string): Promise<Session[]>;
+/** 列出未归属任何项目的已软删除会话（孤儿）。删除项目时 FK set null 使会话失去 projectId，
+ *  在任何项目的回收站视图都不可见（F1），需专门的全局视图暴露以便恢复/归巢。 */
+declare function listOrphanDeletedSessions(handle: DB): Promise<Session[]>;
+/**
+ * 标记回收站条目「已被用户看到」，记录 metadata.trashSeenAt = now（仅首次，不重置）。
+ * 回收站保留期自首次看到起算（见 purgeDeletedSessions）。语义为分组粒度（M1）：
+ * 一次调用标记 scope 内全部条目——「首次看到」指用户打开该回收站分组，而非逐条
+ * 浏览到某个条目；分组内条目同时起算，列表按到期先后置顶展示以补偿该粒度。
+ * 软删除时会清除旧标记，恢复后再次删除须重新看到回收站才重新起算——
+ * 避免「未重新看到就被过早清空」。
+ * scope.orphan=true 时仅标记未归属项目的孤儿会话（与 listOrphanDeletedSessions 对齐）；
+ * 孤儿标记仅在用户展开「未归属项目」分组时由前端显式调用（POST /deleted/orphans/seen），
+ * 避免打开任意项目回收站连带启动无关孤儿条目的倒计时。
+ */
+declare function touchTrashSeen(handle: DB, scope?: {
+    projectId?: string;
+    orphan?: boolean;
+}): Promise<number>;
 /**
  * 软删除会话（级联其所有 fork 后代）。设置 deletedAt = now；
- * 30 天后由 purgeDeletedSessions 物理清除。
+ * 60 天后由 purgeDeletedSessions 物理清除（到期先标记、宽限 7 天）。
+ * A3：同时清除 trashSeenAt/purgePendingAt——恢复后重删的会话必须重新被
+ * 用户看到才重新起算，宽限期标记不跨删除周期生效。
  * 会话不存在或已在回收站 → 返回 false（调用方按 404 处理）。
  */
 declare function softDeleteSession(handle: DB, id: string): Promise<boolean>;
+/**
+ * A3：清除回收站倒计时/宽限期标记（软删除与项目删除共用）。
+ * 恢复后重删的会话须重新被看到才重新起算；宽限期标记不跨删除周期生效。
+ * 无标记时原样返回，避免无谓的 jsonb 覆写。
+ */
+declare function clearTrashMarks(meta: SessionMetadata): SessionMetadata;
+/**
+ * 把会话归属到指定项目（P1-2 孤儿会话补救）：设置 projectId 与 worktreePath。
+ * 会话不存在返回 false。
+ */
+declare function rebindSession(handle: DB, id: string, project: {
+    id: string;
+    worktree: string;
+}): Promise<boolean>;
 /**
  * 从回收站恢复会话：默认连带恢复其已软删除的祖先链——
  * 否则恢复的会话因父仍在回收站而游离于会话树之外（P2-1：UI 不可达）。
  * 祖先中未删除的（活跃）节点不需要也不应该被改动。
+ *
+ * P2 修复：删除级联后代入回收站，恢复同样级联还原目标会话的整棵后代子树——
+ * 否则「删除根会话 → 恢复根会话」后分支仍滞留回收站且无任何提示，保留期后被清。
+ * 兄弟分支（祖先的其他后代）不受影响。
+ */
+export type RestoreResult = {
+    restored: boolean;
+    /** 为可达性连带还原的祖先会话数量（不含目标会话与其同批次后代）。 */
+    restoredAncestorCount: number;
+    /** 是否连带还原了与目标非同一次删除批次的祖先（用户早先单独删除的会话）。 */
+    crossedBatchAncestor: boolean;
+    /**
+     * A2：已删除但未随本次恢复的后代数量（删除批次不同——典型场景是项目删除时
+     * 各会话批次断裂）。这些 fork 分支滞留在回收站，必须显式告知用户单独恢复，
+     * 否则会被静默物理清除。
+     */
+    leftBehindDescendantCount: number;
+};
+declare function restoreSessionCore(handle: DB, id: string, opts?: {
+    includeDescendants?: boolean;
+}): Promise<RestoreResult>;
+declare function restoreSession(handle: DB, id: string, opts?: {
+    includeDescendants?: boolean;
+}): Promise<boolean>;
+/**
+ * P2-4：回收站保留期 60 天（原 30 天），自「用户首次在回收站看到该条目」
+ * （metadata.trashSeenAt）起算，而非删除时间（墙钟）——否则用户删除后长期不开服务、
+ * 重启即被静默物理清除，从未见过任何倒计时。临时会话（CLI print / workflow）保留期
+ * 仍为 30 天，见 purgeTemporarySessions。
+ */
+export declare const TRASH_RETENTION_MS: number;
+/**
+ * 绝对上限（365 天）：自删除起超过此时长的条目，无论是否被看到都进入宽限期清理。
+ * 兜底「用户从不开回收站 → trashSeenAt 永不写入 → 条目永不清理」的无界增长死角。
+ * 到期仍走先标记（宽限 7 天、UI 显示「即将清除」可恢复）再物理清除的两阶段流程。
+ */
+export declare const TRASH_ABSOLUTE_MAX_MS: number;
+/**
+ * A3：到期标记 → 物理清除的宽限期（默认 7 天）。
+ * 条目到期后先写 metadata.purgePendingAt，UI 显示「即将清除」并可恢复；
+ * 宽限期满才物理清除——杜绝「到期即静默物理清空」的数据丢失死角。
+ */
+export declare const TRASH_PURGE_GRACE_MS: number;
+/** 清除结果：marked = 本次新标记进入宽限期的条目数；deleted = 本次物理清除数。 */
+export type TrashPurgeResult = {
+    marked: number;
+    deleted: number;
+};
+/**
+ * 回收站两阶段清理（启动时与每日定时调用）：
+ * 阶段一：进入保留期截止（首次看到 + 60 天）或绝对上限（删除 + 365 天，无论是否
+ *   被看到）且未标记 → 标记 purgePendingAt（进入宽限期，可恢复）。
+ * 阶段二：purgePendingAt 早于宽限截止 → 物理清除（子会话先于父，自引用 FK 要求）。
+ * 恢复后重删、尚未重新看到的会话按「首次看到 + 60 天」计（绝对上限兜底仍生效）。
  */
-declare function restoreSession(handle: DB, id: string): Promise<boolean>;
+declare function purgeDeletedSessions(handle: DB, retentionMs?: number, graceMs?: number): Promise<TrashPurgeResult>;
 /**
- * 物理清除回收站中超过保留期（默认 30 天）的会话。
- * 子会话先于父会话删除（自引用 FK 要求）。
- * 返回清除数量。启动时与每日定时调用。
+ * C4：清理长期空置的 web 会话（无任何条目、无子会话、未删除、创建早于保留期）。
+ * 覆盖「新建会话后未发言」的残留：首条消息失败清理依赖前端 JS 执行，
+ * 崩溃/断电/离线时必然残留空「New Session」行。CLI 临时会话由 purgeTemporarySessions 负责。
  */
-declare function purgeDeletedSessions(handle: DB, retentionMs?: number): Promise<number>;
+declare function purgeEmptySessions(handle: DB, retentionMs?: number): Promise<number>;
 /** Update a session's title. */
 declare function updateSessionTitle(handle: DB, id: string, title: string): Promise<void>;
+/**
+ * P3-9：物理删除一个「真空会话」——无任何条目且无子会话（首条消息发送失败后
+ * 的前端清理路径使用）。非空会话绝不触碰（返回 false），防误删走错回收站语义。
+ * 软删除会话（回收站条目）不在本路径处理。
+ */
+declare function purgeEmptySession(handle: DB, id: string): Promise<boolean>;
+/**
+ * 彻底删除某个回收站会话及其全部后代（含未软删除的 fork 后代，防御数据异常）。
+ * 子会话先于父会话删除（自引用 FK RESTRICT 要求）；entries/archives 经 FK cascade 清理。
+ * 返回删除数量。会话不存在或不在回收站 → 返回 0。
+ */
+declare function permanentlyDeleteSession(handle: DB, id: string): Promise<number>;
+/** 清空回收站：物理删除所有已软删除会话（子先于父）。返回删除数量。
+ *  projectId 提供时仅清空该项目（P1-7）。 */
+declare function emptyTrash(handle: DB, projectId?: string): Promise<number>;
+/**
+ * 清理过期临时会话（P2 → P1 收紧：仅处理显式标记的临时会话）。
+ * - agentType='print'：CLI 一次性问答（c0de chat，非 --continue）创建的会话。
+ * - agentType='workflow'：工作流运行产生的会话。
+ * 普通 CLI 会话（ACP）与 --continue 续接的会话（续接时已升级）永不清理——
+ * 此前按 source='cli' 全删会把用户显式续接的历史静默物理删除。
+ * 保留期默认 30 天。
+ *
+ * P1（本轮）：清理方式从物理删除改为**移入回收站**（softDeleteSession）——
+ * 工作流/print 会话的子 agent 会话在 Web 树中可见，此前「30 天到点即物理清除」
+ * 让可见节点无回收站保护地凭空消失，与「60 天可恢复」的产品承诺冲突。
+ * 软删除级联同批次后代；随后由 purgeDeletedSessions 的两阶段回收站机制
+ * （trashSeenAt 60 天 / 绝对上限 365 天 + 7 天宽限）统一兜底。
+ * 返回本次移入回收站的会话数。
+ */
+declare function purgeTemporarySessions(handle: DB, retentionMs?: number): Promise<number>;
+/**
+ * 把临时会话升级为持久会话（--continue 续接时调用）：
+ * 清除 print 标记，30 天临时清理不再触及。
+ */
+declare function upgradeTemporarySession(handle: DB, id: string): Promise<void>;
 /** Bump updatedAt to now (used after appending messages). */
 declare function touchSession(handle: DB, id: string): Promise<void>;
 /** 记录会话上次打开时间（用于会话列表按最近打开排序）。 */
@@ -55,5 +195,39 @@ export declare function getLLMSegments(handle: DB, id: string): Promise<LLMSegme
 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>;
+/**
+ * P2-3：预算超支暂停时把原因写入 metadata.budgetPauseReason。
+ * 热更新/重启后 run 重建时由 consumeBudgetPauseMarker 消费——恢复内存
+ * budgetPauseTriggered 标记，避免同一超支原因二次暂停。
+ */
+declare function markBudgetPause(handle: DB, id: string, reason: string): Promise<void>;
+/**
+ * P2-3：消费预算暂停标记（新 run 启动时调用一次）。返回上次暂停原因并删除字段；
+ * 无标记返回 null。消费即删除——单次语义，之后 run 恢复常规预算检查。
+ */
+declare function consumeBudgetPauseMarker(handle: DB, id: string): Promise<string | null>;
 declare function listSessionsByProject(handle: DB, projectId: string): Promise<Session[]>;
-export { createSession, getSession, listAllSessions, listDeletedSessions, listSessions, listSessionsByProject, purgeDeletedSessions, restoreSession, softDeleteSession, touchLastOpened, touchSession, updateSessionLastRun, updateSessionTitle, };
+/**
+ * 跨会话搜索（P2-6）：标题 + 消息内容子串匹配。
+ * 默认仅搜索未软删除的非 CLI 会话（与 Web 会话树一致）；projectId 提供时限定项目。
+ * opts.includeDeleted=true 时搜索回收站（P3：回收站无搜索，删后找内容只能逐行翻）。
+ * 返回 { session, matchedBy: 'title' | 'content' }。
+ */
+declare function searchSessions(handle: DB, query: string, projectId?: string, opts?: {
+    includeDeleted?: boolean;
+}): Promise<Array<{
+    session: Session;
+    matchedBy: 'title' | 'content';
+}>>;
+/**
+ * M3：把中断 run 的半截轮次标记为「未完成」——写入 metadata 的
+ * (unfinishedSinceEntryId, unfinishedUntilEntryId] 区间。
+ * 检测条件：lastRun.status 仍为 running/paused（进程崩溃/重启或热更新交接
+ * 未能写入 completed；deliberate abort 由 SSE finally 正常写 completed，不误标）。
+ * 边界 = 最后一条含文本的 user 消息；其后的条目全部属中断轮次——
+ * 上下文构建剔除（context.ts），前端时间线置灰。
+ * 边界已是最后一条 → 无半截内容，跳过标记。
+ * 重复中断：区间起点不变（重发不追加 user 消息），终点推进到最新末尾，天然合并。
+ */
+declare function markUnfinishedTurn(handle: DB, sessionId: string): Promise<void>;
+export { clearTrashMarks, consumeBudgetPauseMarker, createSession, emptyTrash, getSession, listAllSessions, listDeletedSessions, listOrphanDeletedSessions, listSessions, listSessionsByProject, markBudgetPause, markUnfinishedTurn, permanentlyDeleteSession, purgeDeletedSessions, purgeEmptySession, purgeEmptySessions, purgeTemporarySessions, rebindSession, restoreSession, restoreSessionCore, searchSessions, softDeleteSession, touchLastOpened, touchSession, touchTrashSeen, updateSessionLastRun, updateSessionTitle, upgradeTemporarySession, };