SessionStore

会话存储接口(五方法为承诺面,其余成员纯加法可选)。实现纪律:

• commit 的 rewritten=true 须整卷轮换(语义见 SessionStoreCommitMeta);
• 存储损坏恒结构化报错(throw),恒不静默返回残缺历史(改坏存储文件须报错不静默);
• list 恒不携消息内容(枚举是元数据面);
• create 幂等(同 sessionId 重复登记返回既有记录,platformSessionId 以新值对账更新——resume 后的 AgentSession 沿用记录已存 平台 ULID,本对账写只在旧记录无键时补录新铸值)。

属性

checkpoints?

readonly optional checkpoints?: CheckpointStore;

可选(同居缺省):store 自带的、与会话同生命周期的快照存储。 createSession 在 checkpoints.store / checkpoints.dir 皆缺席时取之作为快照 落点(createFileSessionStore 提供:<sessionDir>/checkpoints,随 delete 一并 消失);自建 store 不提供即 = 快照未接线(相关方法结构化拒绝,恒不静默)。 五方法承诺不变(本成员为纯加法)。

方法

commit()

commit(
   sessionId,
   history,
   meta
): Promise<void>;

轮末提交(对接 onHistoryCommit;rewritten=true 须整卷轮换)

参数

sessionId

string

history

readonly IRMessage[]

meta

SessionStoreCommitMeta

返回

Promise<void>

---

create()

create(init): Promise<SessionRecordMeta>;

建会话(登记 meta;id 由 store 铸造或调用方供给;幂等)

参数

init

SessionStoreCreateInit

返回

Promise<SessionRecordMeta>

---

delete()

delete(sessionId): Promise<void>;

删除/归档(FileSessionStore = 目录删除;平台实现 = 归档语义)

参数

sessionId

string

返回

Promise<void>

---

flush()?

optional flush(options?): Promise<boolean>;

可选(server 份 ServeAgentSessionStore.flush 同笔):等待在飞提交 settle 与冷层上传 队列排空(进程退出前调用可保证封存段已上传 / 冷清单已提交)。无冷层 = 等在飞 settle 后即 true;超时 / 中止 false(热层已耐久,只是冷层积压未清)。createFileSessionStore 提供；自建 store 不实现仅表示无全局 flush 能力， 不表示其 commit 同步。AgentSession.drain 缺省只等本会话真实提交；flushStore:true 才调用借用 store 的全局 flush，调用可能同时等待其他会话。SDK 观察预算包住整个 Promise，不把观察者的取消传给共享 flush。

参数

options?

signal?

any

timeoutMs?

number

返回

Promise<boolean>

---

fork()?

optional fork(input): Promise<{
  sessionId: string;
}>;

可选:自快照 fork 出新会话记录——源会话恒不改;新会话历史 = 快照 messages(实现方须配对治理,kernel 原语内置);新会话不被打开(调用方随后 resume)。 createFileSessionStore 经 kernel forkSessionFromCheckpoint 落地(新卷首记录 kind=‘fork’ + meta.forkedFrom + 附件按 sha 复制);自建 store 不实现即由 AgentSession.fork 回落五方法 (create + commit 全量历史)——功能同在,只无血缘记录(五方法承诺不变,本成员纯加法)。

参数

input

SessionStoreForkInput

返回

Promise<{ sessionId: string; }>

---

get()

get(sessionId): Promise<SessionRecord | null>;

取单会话(meta + 完整历史;不存在返回 null;损坏结构化 throw)

参数

sessionId

string

返回

Promise<SessionRecord | null>

---

getHistoryPage()?

optional getHistoryPage(sessionId, page): Promise<
  | {
  messages: IRMessage[];
  nextOffset: number;
  offset: number;
  total: number;
}
| null>;

可选:历史分页读——消息索引口径(offset = IRMessage[] 下标,limit = 至少返回的消息数),不暴露段/游标。实现纪律:

• 返回切片恒配对完整:start 向前对齐到 ≤ offset 的干净边界(结果 offset 如实回填对齐后的起点),end 向后对齐到 ≥ offset+limit 的干净边界(limit 是 下限,为凑齐工具轮可多返回);total 为该会话全量消息数;
• 会话不存在返回 null;存储损坏结构化 throw(与 get 同律);
• limit: 0 合法 = 只取 total(实现应避免为此全量装载);
• createFileSessionStore 以段清单跳读实现(readTail,只装尾部所需段);自建 store 不实现即由 readHistoryPage() 回落 get 全量切片(五方法承诺不变,本成员纯加法)。 与 server v2 store 同构双份(server 份多 endUserId 首参)。

参数

sessionId

string

page

limit

number

offset

number

返回

Promise< | { messages: IRMessage[]; nextOffset: number; offset: number; total: number; } | null>

---

list()

list(filter?): Promise<SessionRecordMeta[]>;

列会话(按 updatedAt 倒序;恒无内容)

参数

filter?

limit?

number

返回

Promise<SessionRecordMeta[]>

---

readiness()?

optional readiness(): {
  ready: boolean;
  reason?: string;
};

可选(server 份同笔):就绪探针——分层存储热盘触顶(policy.hotRetention.maxBytes,已提交 段逐出后仍越帽)→ { ready:false, reason:'store_hot_full' },否则 { ready:true }。宿主据此拒新建 / 摘流。 缺席 = 恒就绪(本成员纯加法)。

返回

{
  ready: boolean;
  reason?: string;
}

ready

ready: boolean;

reason?

optional reason?: string;

---

recordCwdChange()?

optional recordCwdChange(sessionId, change): Promise<void>;

可选:登记一次 cwd 中途切换——实现须把 meta.cwd 改写为 change.to 并把 change 追加到 meta.cwdHistory(切换即刻、与历史提交无关;不改 updatedAt)。会话不存在结构化 throw(session_not_found)。createFileSessionStore 以 meta.json 原文读-改-写实现;自建 store 不实现即 = 切换不落盘(AgentSession.setCwd 照常成功,仅无持久化记录——五方法承诺不变,本成员纯加法)。 与 server v2 store 同构双份(server 份多 endUserId 首参)。

参数

sessionId

string

change

SessionCwdChange

返回

Promise<void>

本文是否有帮助?

有帮助没帮助