mirror of
https://github.com/deepseek-ai/deepseek-harness
synced 2026-08-15 21:04:50 +00:00
refactor(session): drop the unused predicate helper and tighten the docs
`isInheritedSeq` had no production caller — only its own tests — so it was a public core export shaped by nothing. A bracket owner reads the boundary positionally; the helper belongs with the compaction seam, where a real consumer decides its signature. Also condense the `session/inherited` and `lastActivityTime` docs.
This commit is contained in:
Hypatia May
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-30-session-inherited-log-boundary.md
|
||||
2026-07-30-session-inherited-log-boundary.md: 027281a7555214122b4e2d1f8457d3554a751921
|
||||
2026-07-30-session-inherited-log-boundary.zh.md: 3c169e16f0b409f125ccc29226412f239a58c6aa
|
||||
2026-07-30-session-inherited-log-boundary.md: 3b9cb09d1d1a16d30fd212b439a97e3d9296bd6d
|
||||
2026-07-30-session-inherited-log-boundary.zh.md: de048bc994ca97f937f74783b9055fbeb171314a
|
||||
|
||||
@@ -16,9 +16,9 @@ Crash repair does not close the gap and must not: `interruptedTurnClosers` synth
|
||||
|
||||
`Session`'s constructor appends the log-only `session/inherited` event as the seeded session's first live write, at the seq `firstLiveSeq` names. The event is the durable projection of that field: `firstLiveSeq` answers "which prefix did I inherit" for a consumer holding the object, the event answers it for one holding only stored bytes. Its payload is empty — position and `time` carry the whole meaning — and it is not a `SurfaceEventType`, so it produces no message and cannot perturb derived history.
|
||||
|
||||
`isInheritedSeq(events, seq)` (exported from `dsh-session`) is the predicate a bracket owner calls on an unmatched opening marker. True means the marker belongs to a lifecycle that has ended and cannot still be running. Core writes the boundary and reads nothing from it; each bracket's vocabulary stays with its owning plugin.
|
||||
A bracket owner reads it positionally: an unmatched opening marker below the boundary belongs to a lifecycle that has ended and cannot still be running. Core writes the boundary and reads nothing from it; each bracket's vocabulary stays with its owning plugin, so no core predicate helper ships without a consumer to shape it.
|
||||
|
||||
The constructor is the placement because it is the single waist every seeded session passes through. All six entry points reach it: `agents.resume()`, config-driven startup on a persisted id (`restoreOrCreateConfigured`), `sessions.fork()`, a subagent fork child, `coordinator.adopt()`'s live-prefix path, and a bare `sessions.create(id, {seed})`. A boundary written at persistence load would miss both fork paths — and a forked child inheriting a still-running parent's open `compact/start` is precisely the case the predicate must classify. A boundary written at loop start would miss `fork()` and `adopt()`, and would have to fire on `SessionStartSource: 'startup'`, which is what a fork child publishes, so that field would stop discriminating.
|
||||
The constructor is the placement because it is the single waist every seeded session passes through. All six entry points reach it: `agents.resume()`, config-driven startup on a persisted id (`restoreOrCreateConfigured`), `sessions.fork()`, a subagent fork child, `coordinator.adopt()`'s live-prefix path, and a bare `sessions.create(id, {seed})`. A boundary written at persistence load would miss both fork paths — and a forked child inheriting a still-running parent's open `compact/start` is precisely the case that must be classifiable. A boundary written at loop start would miss `fork()` and `adopt()`, and would have to fire on `SessionStartSource: 'startup'`, which is what a fork child publishes, so that field would stop discriminating.
|
||||
|
||||
Two guards keep the marker from becoming noise. An empty seed writes nothing: a boundary with nothing below it marks nothing. A seed already ending in one is not re-marked, which makes the write idempotent. Idempotence is load-bearing rather than tidiness — `agentFor()` resumes a cold session on first touch, so merely opening one in a client is a pickup, and without the guard browsing would grow a log by one event per visit.
|
||||
|
||||
@@ -44,10 +44,10 @@ The predicate holds for a bracket *this* session inherited, not as a liveness si
|
||||
|
||||
## Consequences
|
||||
|
||||
Bought: one predicate, in one place, correct for all six seeded-start paths — including the fork gap the persistence-layer version could not reach. The persistence packages keep a pure read path. `firstLiveSeq` gains a durable twin rather than a second, competing notion of the same boundary.
|
||||
Bought: one boundary, written in one place, correct for all six seeded-start paths — including the fork gap the persistence-layer version could not reach. The persistence packages keep a pure read path. `firstLiveSeq` gains a durable twin rather than a second, competing notion of the same boundary.
|
||||
|
||||
Cost: a seeded session's log is one event longer, which moved seq expectations in tests across nine packages (session, agent-loop, persistence contract, jsonl, session-query, session-title, subagent-inprocess, telemetry, token-meter). Two of those updates are load-bearing rather than mechanical: telemetry's adoption tests now assert the boundary IS exported, because it is this lifecycle's own write, and the property suite's replay invariant is restated as "seed reproduced verbatim, plus one log-only boundary" with idempotence added as its own property.
|
||||
|
||||
`session/inherited` joins the on-disk vocabulary. Under the pre-release stance (`SESSION_FORMAT_VERSION` pinned at `0`, no compatibility promise) older logs simply lack it, and a log without a boundary correctly reports nothing as inherited.
|
||||
|
||||
Not built here: no plugin consumes `isInheritedSeq` yet. Wiring the compaction seam's staleness check to it is the follow-up that motivated this boundary, and it belongs with that seam's own tests.
|
||||
Not built here: no plugin reads the boundary yet. Wiring the compaction seam's staleness check to it is the follow-up that motivated this boundary; the predicate helper belongs with that seam, where a real consumer decides its shape, rather than shipping into core untested against one.
|
||||
|
||||
@@ -16,9 +16,9 @@ Status: implemented
|
||||
|
||||
`Session` 的构造函数把仅日志事件 `session/inherited` 作为带种子会话的第一次实时写入追加，位置正是 `firstLiveSeq` 指出的 seq。该事件是那个字段的持久投影：`firstLiveSeq` 为持有对象的消费方回答"我继承了哪一段前缀"，该事件则为只持有存储字节的消费方回答同一问题。它的 payload 为空——位置与 `time` 承载全部含义——并且不是 `SurfaceEventType`，因此不产生消息，也无法扰动派生历史。
|
||||
|
||||
`isInheritedSeq(events, seq)`（由 `dsh-session` 导出）是括号所有方在一个未配对开启标记上调用的谓词。为真意味着该标记属于一个已结束的生命周期，不可能仍在运行。核心写入该边界但不从中读取任何内容；每个括号的词汇表仍归其所属插件。
|
||||
括号所有方按位置读取它：位于边界之下的未配对开启标记属于一个已结束的生命周期，不可能仍在运行。核心写入该边界但不从中读取任何内容；每个括号的词汇表仍归其所属插件，因此在没有消费方来塑形之前，核心不会先发布谓词辅助函数。
|
||||
|
||||
选择构造函数，是因为它是每一个带种子会话都必经的唯一收窄处。全部六个入口都会到达它：`agents.resume()`、在已持久化 id 上的配置驱动启动（`restoreOrCreateConfigured`）、`sessions.fork()`、子代理 fork 子会话、`coordinator.adopt()` 的实时前缀路径，以及裸的 `sessions.create(id, {seed})`。在持久化加载时写入的边界会漏掉两条 fork 路径——而一个继承了仍在运行的父会话开放 `compact/start` 的 fork 子会话，恰恰是该谓词必须判定的场景。在 loop 启动时写入的边界会漏掉 `fork()` 与 `adopt()`，并且不得不在 `SessionStartSource: 'startup'` 上触发——那正是 fork 子会话发布的取值，于是该字段将不再具有区分力。
|
||||
选择构造函数，是因为它是每一个带种子会话都必经的唯一收窄处。全部六个入口都会到达它：`agents.resume()`、在已持久化 id 上的配置驱动启动（`restoreOrCreateConfigured`）、`sessions.fork()`、子代理 fork 子会话、`coordinator.adopt()` 的实时前缀路径，以及裸的 `sessions.create(id, {seed})`。在持久化加载时写入的边界会漏掉两条 fork 路径——而一个继承了仍在运行的父会话开放 `compact/start` 的 fork 子会话，恰恰是必须可判定的场景。在 loop 启动时写入的边界会漏掉 `fork()` 与 `adopt()`，并且不得不在 `SessionStartSource: 'startup'` 上触发——那正是 fork 子会话发布的取值，于是该字段将不再具有区分力。
|
||||
|
||||
两条守卫让这个标记不至于变成噪声。空种子不写入任何内容：下方什么都没有的边界标记不了任何东西。种子本身已以该事件结尾时不会重复标记，这让写入具备幂等性。幂等性是承重的，而不是为了整洁——`agentFor()` 会在首次触碰时恢复一个冷会话，因此在客户端里仅仅打开一个会话就是一次接手；没有这条守卫，浏览会让日志每访问一次就增长一个事件。
|
||||
|
||||
@@ -44,10 +44,10 @@ Status: implemented
|
||||
|
||||
## Consequences
|
||||
|
||||
买到的：一个谓词，位于一处，对全部六条带种子启动路径都正确——包括持久化层方案触及不到的 fork 缺口。持久化各包保留纯读取路径。`firstLiveSeq` 获得一个持久孪生体，而不是关于同一边界的第二套彼此竞争的概念。
|
||||
买到的：一条边界，在一处写入，对全部六条带种子启动路径都正确——包括持久化层方案触及不到的 fork 缺口。持久化各包保留纯读取路径。`firstLiveSeq` 获得一个持久孪生体，而不是关于同一边界的第二套彼此竞争的概念。
|
||||
|
||||
代价：带种子会话的日志长了一个事件，这在九个包（session、agent-loop、持久化契约、jsonl、session-query、session-title、subagent-inprocess、telemetry、token-meter）里挪动了 seq 期望。其中两处更新是承重的而非机械的：telemetry 的收养测试现在断言该边界*会*被导出，因为它是本生命周期的自有写入；而属性测试套件的重放不变式被重述为"种子逐字节复现，外加一个仅日志边界"，并把幂等性补成一条独立属性。
|
||||
|
||||
`session/inherited` 加入了落盘词汇表。在预发布立场下（`SESSION_FORMAT_VERSION` 固定为 `0`，不作兼容承诺），更旧的日志只是没有它，而没有边界的日志会正确地报告没有任何内容被继承。
|
||||
|
||||
此处未做：还没有任何插件消费 `isInheritedSeq`。把压缩 seam 的陈旧性检查接到它上面，是催生这条边界的后续工作，应当与那个 seam 自己的测试一起完成。
|
||||
此处未做：还没有任何插件读取该边界。把压缩 seam 的陈旧性检查接到它上面，是催生这条边界的后续工作；谓词辅助函数应当归属那个 seam——在那里由真实消费方决定它的形状——而不是未经真实消费方检验就先落进核心。
|
||||
|
||||
@@ -2,5 +2,5 @@
|
||||
# side as of the last confirmed-consistent state. Both languages carry equal authority;
|
||||
# after editing either side, bring the other along and re-record with:
|
||||
# pnpm run verify-translation-pairing --write docs/core-data-structures/session.md
|
||||
session.md: 20942722c2c1f86bf9a2b6007ad42c9e97d43b91
|
||||
session.zh.md: 87ca7dc44ad4ac19456679ecbffd08cfd3023296
|
||||
session.md: 25fb5471e600541a3a2d5d2b67083f5b443dcd52
|
||||
session.zh.md: 9cf8c61d3c2ca27c4cdc6adf5804e59dd73b5f5e
|
||||
|
||||
@@ -92,23 +92,17 @@ interface SessionEventMap {
|
||||
*/
|
||||
'request/header': { header: EpochHeader; reason: RequestHeaderReason }
|
||||
/**
|
||||
* The log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* BELOW it was inherited through a constructor seed — resume, fork, or replay
|
||||
* — and no writer in this session's lifecycle produced it. Appended as the
|
||||
* first live event of every seeded session.
|
||||
* Log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* below it was inherited through a constructor seed (resume, fork, or replay)
|
||||
* and no writer in this lifecycle produced it. Payload is empty — position
|
||||
* and `time` carry the meaning.
|
||||
*
|
||||
* A plugin owning a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) needs it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below this boundary
|
||||
* belongs to an ended lifecycle, so it is dead whether the writer crashed,
|
||||
* the process succeeded it, or the events were forked out of a parent that is
|
||||
* still running. Read it through `isInheritedSeq`.
|
||||
*
|
||||
* NOT a liveness signal about other writers: a concurrently live session may
|
||||
* hold an open bracket over the same stored history with its own boundary
|
||||
* An owner of a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) reads it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below the boundary
|
||||
* belongs to an ended lifecycle, whatever ended it. NOT a liveness signal
|
||||
* about other writers — a concurrently live session holds its own boundary
|
||||
* elsewhere, so tolerating concurrent writers needs a signal beyond the log.
|
||||
*
|
||||
* The payload is empty by design — position and `time` carry the meaning.
|
||||
*/
|
||||
'session/inherited': Record<string, never>
|
||||
}
|
||||
@@ -535,7 +529,7 @@ The optional `dsh-session/invariant` companion enforces the relations owned by c
|
||||
|
||||
A seeded session — resume, fork, or replay — appends this log-only event as its first live write, at the seq its `firstLiveSeq` names. It is the durable projection of that field: `firstLiveSeq` answers "which prefix did I inherit" for a consumer holding the object, this event for one holding only stored bytes. The payload is empty, so position and `time` carry the whole meaning, and it produces no message. An empty seed writes nothing, and a seed already ending in one is not re-marked, so reopening an untouched session does not grow its log per open.
|
||||
|
||||
It exists because inherited history and live work are otherwise byte-identical, which defeats any plugin owning a standalone open/close bracket: an unmatched `compact/start` reads the same whether the writer crashed mid-compaction or is compacting right now. `isInheritedSeq(events, seq)` is the predicate a bracket owner calls — true means the opening marker belongs to an ended lifecycle, whatever ended it (a crash, a succeeding process, or a fork out of a still-running parent). It classifies only brackets *this* session inherited: a concurrently live session holding an open bracket over the same history has its own boundary elsewhere, so tolerating concurrent writers needs a liveness signal beyond the log. Core writes the boundary and reads nothing from it — a bracket's vocabulary stays with its owning plugin, which is why crash repair closes turn/step/tool boundaries and never `compact/*`.
|
||||
It exists because inherited history and live work are otherwise byte-identical, which defeats any plugin owning a standalone open/close bracket: an unmatched `compact/start` reads the same whether the writer crashed mid-compaction or is compacting right now. An opening marker below the boundary belongs to an ended lifecycle, whatever ended it (a crash, a succeeding process, or a fork out of a still-running parent), so its owner may treat it as dead. That covers only brackets *this* session inherited: a concurrently live session holding an open bracket over the same history has its own boundary elsewhere, so tolerating concurrent writers needs a liveness signal beyond the log. Core writes the boundary and reads nothing from it — a bracket's vocabulary stays with its owning plugin, which is why crash repair closes turn/step/tool boundaries and never `compact/*`.
|
||||
|
||||
Activity ordering excludes the boundary through `lastActivityTime(events)`: picking a session up is not work, and lazy resume means browsing writes one, so a resume picker or session list ordering by log tail would float every opened session to the top.
|
||||
|
||||
|
||||
@@ -92,23 +92,17 @@ interface SessionEventMap {
|
||||
*/
|
||||
'request/header': { header: EpochHeader; reason: RequestHeaderReason }
|
||||
/**
|
||||
* The log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* BELOW it was inherited through a constructor seed — resume, fork, or replay
|
||||
* — and no writer in this session's lifecycle produced it. Appended as the
|
||||
* first live event of every seeded session.
|
||||
* Log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* below it was inherited through a constructor seed (resume, fork, or replay)
|
||||
* and no writer in this lifecycle produced it. Payload is empty — position
|
||||
* and `time` carry the meaning.
|
||||
*
|
||||
* A plugin owning a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) needs it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below this boundary
|
||||
* belongs to an ended lifecycle, so it is dead whether the writer crashed,
|
||||
* the process succeeded it, or the events were forked out of a parent that is
|
||||
* still running. Read it through `isInheritedSeq`.
|
||||
*
|
||||
* NOT a liveness signal about other writers: a concurrently live session may
|
||||
* hold an open bracket over the same stored history with its own boundary
|
||||
* An owner of a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) reads it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below the boundary
|
||||
* belongs to an ended lifecycle, whatever ended it. NOT a liveness signal
|
||||
* about other writers — a concurrently live session holds its own boundary
|
||||
* elsewhere, so tolerating concurrent writers needs a signal beyond the log.
|
||||
*
|
||||
* The payload is empty by design — position and `time` carry the meaning.
|
||||
*/
|
||||
'session/inherited': Record<string, never>
|
||||
}
|
||||
@@ -539,7 +533,7 @@ interface TurnEndReasonMap {
|
||||
|
||||
带种子的会话（恢复、fork 或重放）把这个仅日志事件作为自己的第一次实时写入追加，位置正是 `firstLiveSeq` 指出的 seq。它是该字段的持久投影：`firstLiveSeq` 为持有对象的消费方回答"我继承了哪一段前缀"，这个事件则为只持有存储字节的消费方回答同一问题。payload 为空，因此位置与 `time` 承载全部含义，且不产生任何消息。空种子不写入任何内容；种子本身已以该事件结尾时不会重复标记，因此重新打开一个未被改动的会话不会每次打开都增长日志。
|
||||
|
||||
它之所以必要，是因为继承历史与实时工作在字节层面完全相同，这会让任何拥有独立开／闭括号的插件失效：一个未配对的 `compact/start`，无论写入方是在压缩中途崩溃、还是此刻正在压缩，读起来都一样。`isInheritedSeq(events, seq)` 就是括号所有方调用的谓词——为真意味着该开启标记属于一个已结束的生命周期，无论结束原因为何（崩溃、进程接替，或从仍在运行的父会话 fork 出来）。它只判定*本*会话继承的括号：另一个并发存活的会话可能在同一段历史上持有开放括号，而它自己的边界在别处，因此容忍并发写入方还需要日志之外的存活信号。核心写入该边界但不从中读取任何内容——括号的词汇表仍归其所属插件，这也正是崩溃修复只关闭轮次／步骤／工具边界而从不处理 `compact/*` 的原因。
|
||||
它之所以必要，是因为继承历史与实时工作在字节层面完全相同，这会让任何拥有独立开／闭括号的插件失效：一个未配对的 `compact/start`，无论写入方是在压缩中途崩溃、还是此刻正在压缩，读起来都一样。边界之下的开启标记属于一个已结束的生命周期，无论结束原因为何（崩溃、进程接替，或从仍在运行的父会话 fork 出来），因此其所有方可以视之为已死。这只覆盖*本*会话继承的括号：另一个并发存活的会话可能在同一段历史上持有开放括号，而它自己的边界在别处，因此容忍并发写入方还需要日志之外的存活信号。核心写入该边界但不从中读取任何内容——括号的词汇表仍归其所属插件，这也正是崩溃修复只关闭轮次／步骤／工具边界而从不处理 `compact/*` 的原因。
|
||||
|
||||
活动排序通过 `lastActivityTime(events)` 排除该边界：接手会话不算工作，而惰性恢复意味着浏览就会写入一个，因此按日志尾部排序的恢复选择器或会话列表会把每个打开过的会话顶到最前。
|
||||
|
||||
|
||||
@@ -78,7 +78,7 @@ export type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
||||
}[T]
|
||||
```
|
||||
|
||||
Sources: [`packages/core/session/src/types.ts:276`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:283`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:312`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:344`](../packages/core/session/src/types.ts)
|
||||
Sources: [`packages/core/session/src/types.ts:270`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:277`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:306`](../packages/core/session/src/types.ts) · [`packages/core/session/src/types.ts:338`](../packages/core/session/src/types.ts)
|
||||
|
||||
## Events
|
||||
|
||||
@@ -408,28 +408,22 @@ Source: [`packages/sandbox/sandbox-policy/src/session-mode.ts:33`](../packages/s
|
||||
|
||||
```ts persistence-catalog
|
||||
/**
|
||||
* The log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* BELOW it was inherited through a constructor seed — resume, fork, or replay
|
||||
* — and no writer in this session's lifecycle produced it. Appended as the
|
||||
* first live event of every seeded session.
|
||||
* Log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* below it was inherited through a constructor seed (resume, fork, or replay)
|
||||
* and no writer in this lifecycle produced it. Payload is empty — position
|
||||
* and `time` carry the meaning.
|
||||
*
|
||||
* A plugin owning a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) needs it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below this boundary
|
||||
* belongs to an ended lifecycle, so it is dead whether the writer crashed,
|
||||
* the process succeeded it, or the events were forked out of a parent that is
|
||||
* still running. Read it through `isInheritedSeq`.
|
||||
*
|
||||
* NOT a liveness signal about other writers: a concurrently live session may
|
||||
* hold an open bracket over the same stored history with its own boundary
|
||||
* An owner of a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) reads it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below the boundary
|
||||
* belongs to an ended lifecycle, whatever ended it. NOT a liveness signal
|
||||
* about other writers — a concurrently live session holds its own boundary
|
||||
* elsewhere, so tolerating concurrent writers needs a signal beyond the log.
|
||||
*
|
||||
* The payload is empty by design — position and `time` carry the meaning.
|
||||
*/
|
||||
'session/inherited': Record<string, never>
|
||||
```
|
||||
|
||||
Source: [`packages/core/session/src/types.ts:272`](../packages/core/session/src/types.ts)
|
||||
Source: [`packages/core/session/src/types.ts:266`](../packages/core/session/src/types.ts)
|
||||
|
||||
#### `session/title` — log-only
|
||||
|
||||
|
||||
@@ -23,7 +23,7 @@ export * from './types.ts'
|
||||
export type { AssistantMessage, ToolResultMessage, UserMessage } from '@deepseek-ai/dsh-llm'
|
||||
export { isJsonValue, snapshotJsonValue } from './json.ts'
|
||||
export type { JsonValue } from './json.ts'
|
||||
export { interruptedTurnClosers, isInheritedSeq, lastActivityTime, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts'
|
||||
export { interruptedTurnClosers, lastActivityTime, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from './repair.ts'
|
||||
export { decodeStorageRecord, packChunkRuns } from './chunk-rows.ts'
|
||||
export type { ChunkRow, StorageRecord } from './chunk-rows.ts'
|
||||
export type { SessionSurface, SurfaceFoldReplacement, SurfaceFoldResult } from './surface.ts'
|
||||
|
||||
@@ -11,44 +11,11 @@ import type { ToolResultMessage } from '@deepseek-ai/dsh-llm'
|
||||
import type { SessionEvent } from './types.ts'
|
||||
|
||||
/**
|
||||
* Whether the event at `seq` was inherited rather than written by the lifecycle
|
||||
* that owns `events` — the stored-history reading of `Session.firstLiveSeq`.
|
||||
*
|
||||
* An owner of a standalone open/close bracket calls this on an unmatched
|
||||
* opening marker: `true` means the operation cannot still be running, because
|
||||
* the lifecycle that opened it has ended (a crashed writer, a succeeding
|
||||
* process, or a parent the events were forked out of). `false` means it belongs
|
||||
* to the current lifecycle and must be treated as live.
|
||||
*
|
||||
* Reads the log rather than a `Session`, so it serves a consumer holding only
|
||||
* loaded events; in-process, compare against `session.firstLiveSeq` instead.
|
||||
* @param events - the log to scan, contiguous from seq 0.
|
||||
* @param seq - the event seq to classify.
|
||||
* @returns true when a `session/inherited` boundary sits at or above `seq`.
|
||||
*/
|
||||
export function isInheritedSeq(events: readonly SessionEvent[], seq: number): boolean {
|
||||
// Tail-first: an unmarked log costs no full scan, and bracket queries are
|
||||
// usually about recent events.
|
||||
for (let index = events.length - 1; index >= 0; index -= 1) {
|
||||
const event = events[index]
|
||||
/* v8 ignore next -- a contiguous log has no holes; the guard is for the index type */
|
||||
if (event === undefined) continue
|
||||
if (event.seq < seq) return false
|
||||
if (event.type === 'session/inherited') return true
|
||||
}
|
||||
return false
|
||||
}
|
||||
|
||||
/**
|
||||
* The `time` of the log's last event that represents actual work, skipping the
|
||||
* `session/inherited` boundary.
|
||||
*
|
||||
* Picking a session up is not activity, and lazy resume means browsing writes a
|
||||
* boundary, so activity ordering (a resume picker, a session list) must skip it
|
||||
* or every opened session sorts as freshly worked in.
|
||||
* The `time` of the log's last event representing actual work, skipping the
|
||||
* `session/inherited` boundary — picking a session up is not activity, so
|
||||
* activity ordering must exclude it.
|
||||
* @param events - the log to scan, in seq order.
|
||||
* @returns the latest non-boundary event's `time`, or undefined when the log has
|
||||
* no such event (empty, or nothing but boundaries).
|
||||
* @returns the latest non-boundary event's `time`, or undefined when there is none.
|
||||
*/
|
||||
export function lastActivityTime(events: readonly SessionEvent[]): number | undefined {
|
||||
return events.findLast(event => event.type !== 'session/inherited')?.time
|
||||
|
||||
@@ -251,23 +251,17 @@ export interface SessionEventMap {
|
||||
*/
|
||||
'request/header': { header: EpochHeader; reason: RequestHeaderReason }
|
||||
/**
|
||||
* The log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* BELOW it was inherited through a constructor seed — resume, fork, or replay
|
||||
* — and no writer in this session's lifecycle produced it. Appended as the
|
||||
* first live event of every seeded session.
|
||||
* Log-only durable projection of {@link Session.firstLiveSeq}: everything
|
||||
* below it was inherited through a constructor seed (resume, fork, or replay)
|
||||
* and no writer in this lifecycle produced it. Payload is empty — position
|
||||
* and `time` carry the meaning.
|
||||
*
|
||||
* A plugin owning a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) needs it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below this boundary
|
||||
* belongs to an ended lifecycle, so it is dead whether the writer crashed,
|
||||
* the process succeeded it, or the events were forked out of a parent that is
|
||||
* still running. Read it through `isInheritedSeq`.
|
||||
*
|
||||
* NOT a liveness signal about other writers: a concurrently live session may
|
||||
* hold an open bracket over the same stored history with its own boundary
|
||||
* An owner of a standalone open/close bracket (`compact/start` …
|
||||
* `compact/end`) reads it because inherited history and live work are
|
||||
* otherwise byte-identical: an unmatched opening marker below the boundary
|
||||
* belongs to an ended lifecycle, whatever ended it. NOT a liveness signal
|
||||
* about other writers — a concurrently live session holds its own boundary
|
||||
* elsewhere, so tolerating concurrent writers needs a signal beyond the log.
|
||||
*
|
||||
* The payload is empty by design — position and `time` carry the meaning.
|
||||
*/
|
||||
'session/inherited': Record<string, never>
|
||||
}
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import { describe, expect, it } from 'vitest'
|
||||
import { CallId , createMessage, createToolResultMessage } from '@deepseek-ai/dsh-llm'
|
||||
import { interruptedTurnClosers, isInheritedSeq, lastActivityTime, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from '../src/index.ts'
|
||||
import { interruptedTurnClosers, lastActivityTime, TOOL_NOT_STARTED, TOOL_OUTCOME_UNKNOWN } from '../src/index.ts'
|
||||
import type { SessionEvent, SurfaceEvent } from '../src/index.ts'
|
||||
|
||||
/**
|
||||
@@ -274,64 +274,6 @@ describe('interruptedTurnClosers', () => {
|
||||
})
|
||||
})
|
||||
|
||||
/**
|
||||
* The stored-history reading of the inherited boundary. A bracket owner calls
|
||||
* this on an unmatched opening marker to decide whether the operation can still
|
||||
* be running, so the classification of the marker's own seq — and of the
|
||||
* boundary seq itself — is the contract.
|
||||
*/
|
||||
describe('isInheritedSeq', () => {
|
||||
const inheritedAt = (seq: number): SessionEvent =>
|
||||
({ type: 'session/inherited', seq, time: seq, data: {} })
|
||||
|
||||
it('classifies nothing as inherited in a log without a boundary', () => {
|
||||
const events: SessionEvent[] = [
|
||||
userTurnStart(1, 0),
|
||||
{ type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } } },
|
||||
]
|
||||
expect(isInheritedSeq(events, 0)).toBe(false)
|
||||
expect(isInheritedSeq(events, 1)).toBe(false)
|
||||
})
|
||||
|
||||
it('treats an empty log as owning nothing', () => {
|
||||
expect(isInheritedSeq([], 0)).toBe(false)
|
||||
})
|
||||
|
||||
it('splits the log at the boundary', () => {
|
||||
// seqs 0-1 inherited; the boundary at 2; seq 3 written by this lifecycle.
|
||||
const events: SessionEvent[] = [
|
||||
userTurnStart(1, 0),
|
||||
{ type: 'turn/end', seq: 1, time: 1, data: { turn: 1, reason: { kind: 'completed' } } },
|
||||
inheritedAt(2),
|
||||
userTurnStart(2, 3),
|
||||
]
|
||||
expect(isInheritedSeq(events, 0)).toBe(true)
|
||||
expect(isInheritedSeq(events, 1)).toBe(true)
|
||||
// The boundary's own seq counts as inherited: it belongs to the pickup.
|
||||
expect(isInheritedSeq(events, 2)).toBe(true)
|
||||
expect(isInheritedSeq(events, 3)).toBe(false)
|
||||
})
|
||||
|
||||
it('reports inherited for an event below a later boundary', () => {
|
||||
// Two pickups in turn: the tail scan must not stop at the nearer boundary.
|
||||
const events: SessionEvent[] = [
|
||||
userTurnStart(1, 0),
|
||||
inheritedAt(1),
|
||||
userTurnStart(2, 2),
|
||||
inheritedAt(3),
|
||||
userTurnStart(3, 4),
|
||||
]
|
||||
expect(isInheritedSeq(events, 0)).toBe(true)
|
||||
expect(isInheritedSeq(events, 2)).toBe(true)
|
||||
expect(isInheritedSeq(events, 4)).toBe(false)
|
||||
})
|
||||
})
|
||||
|
||||
/**
|
||||
* Activity ordering excludes the pickup boundary. A resume picker or session
|
||||
* list sorting by log tail would otherwise promote every session the user
|
||||
* merely opened above the ones they actually worked in.
|
||||
*/
|
||||
describe('lastActivityTime', () => {
|
||||
const inheritedAt = (seq: number, time: number): SessionEvent =>
|
||||
({ type: 'session/inherited', seq, time, data: {} })
|
||||
|
||||
Reference in New Issue
Block a user