@namzu/sdk 20.3.0 → 21.0.0

package/src/types/run/event-cursor.ts

@@ -0,0 +1,118 @@
+/**
+ * Where a reconnecting consumer left off, and whether the kernel can honour it.
+ *
+ * The shortfall is a VALUE here, not a sentence in a document. A consumer that
+ * asks for everything after sequence 400 and silently receives a splice from a
+ * different generation of the run is wrong and has no way to find out; a
+ * consumer handed `{ status: 'unavailable', reason: 'cursor_ahead' }` re-derives
+ * from the transcript and is right. That is refuse-do-not-degrade applied to a
+ * subscription rather than to a capability.
+ */
+
+import type { ClaimFence } from './checkpoint-store.js'
+import type { PersistedRunEvent } from './events.js'
+
+/** What a consumer holds when it comes back. */
+export interface RunEventCursor {
+	/**
+	 * The last `seq` the consumer actually received, from the envelope. Zero —
+	 * or the field absent — means "from the beginning".
+	 */
+	readonly sinceSeq: number
+	/**
+	 * The `generation` carried on the events the consumer received, when they
+	 * carried one.
+	 *
+	 * Compared for equality only. Absent on both sides is not a match and not a
+	 * mismatch: it is an unfenced run, where the sequence is the only evidence
+	 * available and the log persisting is the assumption.
+	 */
+	readonly generation?: ClaimFence
+}
+
+/** Why a cursor could not be honoured. */
+export type RunEventReplayRefusal =
+	/**
+	 * The consumer claims to have seen more than the log holds.
+	 *
+	 * The ordinary cause is not a lying client: it is a log that did not
+	 * survive. An in-memory run store on a restarted process seeds at zero
+	 * while the consumer still holds 400, and this is the verdict that says so
+	 * instead of reporting a serene "you are up to date".
+	 */
+	| 'cursor_ahead'
+	/**
+	 * The run has been taken over since. The consumer's sequence numbers were
+	 * minted under an older claim and address a different sequence space, so
+	 * they are not comparable — not merely stale.
+	 */
+	| 'generation_changed'
+	/**
+	 * The store answered, and its oldest available event is above the one after
+	 * the cursor. A pruning or windowed backend, caught at the boundary rather
+	 * than delivered as a continuous stream with a hole in it.
+	 */
+	| 'gap'
+
+/** What came of a cursor. */
+export type RunEventReplay =
+	/** The cursor is already at the log's head. Nothing was missed. */
+	| { readonly status: 'complete' }
+	/** Contiguous from `sinceSeq + 1`, oldest first. */
+	| { readonly status: 'replayed'; readonly events: readonly PersistedRunEvent[] }
+	/** Nothing is delivered. The consumer re-derives from the transcript. */
+	| { readonly status: 'unavailable'; readonly reason: RunEventReplayRefusal }
+
+/** The log's present state, as the store reports it. */
+export interface RunEventLogHead {
+	/** Highest sequence in the log; zero when it is empty. */
+	readonly lastSeq: number
+	/** The fence the run is being written under, when it holds a claim. */
+	readonly generation?: ClaimFence
+}
+
+/**
+ * Decide what a cursor is owed, given what the log holds.
+ *
+ * Pure, and ordered deliberately: a takeover invalidates the sequence space, so
+ * comparing sequences across generations would be arithmetic on two different
+ * scales. The generation check therefore runs FIRST, before the numbers are
+ * allowed to mean anything.
+ *
+ * `events` is what the store returned for `{ sinceSeq: cursor.sinceSeq }`. It is
+ * passed in rather than fetched here so this stays a function of its arguments
+ * — the property "no gap, no duplicate" is decidable from the three inputs, and
+ * a test can drive every branch without a store.
+ */
+export function resolveRunEventReplay(
+	cursor: RunEventCursor,
+	head: RunEventLogHead,
+	events: readonly PersistedRunEvent[],
+): RunEventReplay {
+	// Both sides must carry one for a mismatch to mean anything. An unfenced run
+	// has no generation to disagree with, and treating "absent" as a distinct
+	// value would refuse every run that never took a claim — which is most of
+	// them.
+	if (
+		cursor.generation !== undefined &&
+		head.generation !== undefined &&
+		cursor.generation !== head.generation
+	) {
+		return { status: 'unavailable', reason: 'generation_changed' }
+	}
+
+	if (cursor.sinceSeq > head.lastSeq) {
+		return { status: 'unavailable', reason: 'cursor_ahead' }
+	}
+
+	if (cursor.sinceSeq === head.lastSeq) return { status: 'complete' }
+
+	// The log says there is something above the cursor, so an empty answer is
+	// the store contradicting its own head rather than "nothing to send".
+	const first = events[0]
+	if (!first || first.seq !== cursor.sinceSeq + 1) {
+		return { status: 'unavailable', reason: 'gap' }
+	}
+
+	return { status: 'replayed', events }
+}

package/src/types/run/events.ts

@@ -15,6 +15,7 @@ import type {
 import type { PlanStep } from '../plan/index.js'
 import type { PluginHookEvent, PluginHookResult } from '../plugin/index.js'
 import type { TaskStatus } from '../task/index.js'
+import type { ClaimFence } from './checkpoint-store.js'
 import type { Lineage } from './lineage.js'
 import type { MessageStopReason, StopReason } from './stop-reason.js'
 import type {
@@ -43,6 +44,57 @@ interface RunEventEnvelope {
 	 */
 	schemaVersion?: 3
 	lineage?: Lineage
+	/**
+	 * This event's position in its OWN run's durable event log, from 1.
+	 *
+	 * **Present means recorded.** The emitter takes a candidate number, appends
+	 * the event stamped with it, and only then advances the counter and hands
+	 * the event to the live stream — so a `seq` a consumer can see is a `seq`
+	 * the log contains. That is what makes it usable as a cursor: reconnect,
+	 * ask for everything above it, and nothing is missed and nothing arrives
+	 * twice.
+	 *
+	 * **Absent means not recoverable**, and three different things arrive that
+	 * way:
+	 *
+	 *  - the high-frequency events {@link isEphemeralEvent} names, which are
+	 *    deliberately never persisted;
+	 *  - an event whose durable write FAILED — it still reaches the live
+	 *    stream, unstamped, because losing the news of a failure is worse than
+	 *    delivering it without a cursor;
+	 *  - the delegation lifecycle events (`agent_pending`, `agent_completed`,
+	 *    `agent_failed`, `agent_canceled` and the three sub-session variants),
+	 *    which the agent manager hands straight to a host's listener without
+	 *    passing through the run's event translator at all. They are not in any
+	 *    run's log, and the missing `seq` is how a consumer learns that rather
+	 *    than discovering it after a reconnect.
+	 *
+	 * **Per run, not per stream.** A parent's listener also receives its
+	 * children's events, each numbered in its own run's log, so a consumer
+	 * keeps one cursor per `runId`. The SSE mapper carries the pair as
+	 * `<runId>:<seq>` for exactly this reason.
+	 *
+	 * Monotonic under a single writer. The run store takes no claim fence
+	 * today (see `QueryParams.claimFence`), so two workers that both took one
+	 * run can both append — `generation` is what makes that detectable.
+	 */
+	seq?: number
+	/**
+	 * The claim fence the run was being written under, when it holds a claim.
+	 *
+	 * A sequence alone lies across a takeover: a client at seq 400 reconnects
+	 * to a run whose store lost its log, the new writer starts at 1, and the
+	 * client's cursor silently addresses a different sequence space. The fence
+	 * is already the arbiter of who may write and it only increases, so
+	 * carrying it here makes a takeover ORDERED rather than merely
+	 * distinguishable.
+	 *
+	 * Absent when the run was written unfenced, which is every run that took no
+	 * claim. A cursor then relies on the log persisting — the disk store's
+	 * does, an in-memory store's does not, and `cursor_ahead` is the verdict
+	 * that catches the difference.
+	 */
+	generation?: ClaimFence
 }
 
 type CoreRunEvent =
@@ -679,12 +731,37 @@ type CoreRunEvent =
  */
 export type RunEvent =
 	| (CoreRunEvent & RunEventEnvelope)
-	| SubsessionSpawnedEvent
-	| SubsessionMessagedEvent
-	| SubsessionIdledEvent
+	// Intersected so `seq` is READABLE on every member of the union — TypeScript
+	// refuses a property access on a union where one member lacks the field, and
+	// a consumer holding a cursor has to be able to ask any event for its
+	// number. These three never carry one, and that is the answer rather than an
+	// omission: they are emitted straight to a host's listener and reach no run's
+	// durable log.
+	| (SubsessionSpawnedEvent & RunEventEnvelope)
+	| (SubsessionMessagedEvent & RunEventEnvelope)
+	| (SubsessionIdledEvent & RunEventEnvelope)
 
 export type RunEventListener = (event: RunEvent) => void | Promise<void>
 
+/**
+ * A run event as the durable log gives it back.
+ *
+ * `seq` and `timestamp` are REQUIRED here and optional on the live envelope,
+ * which is the whole difference between the two types: a recorded event has a
+ * position and a moment, and a live one may be neither recorded nor
+ * recoverable.
+ *
+ * `timestamp` is not new — both store implementations have always stamped it
+ * on write. It was simply never declared anywhere, so the field was persisted
+ * by two writers, typed by neither, and read by nobody. Declaring it is what
+ * lets the read-back stop casting.
+ */
+export type PersistedRunEvent = RunEvent & {
+	readonly seq: number
+	/** Epoch ms at which the store recorded the event. */
+	readonly timestamp: number
+}
+
 /**
  * Event types whose volume makes durable persistence wasteful.
  *

package/src/types/run/index.ts

@@ -4,6 +4,7 @@ export * from './stop-reason.js'
 export * from './config.js'
 export * from './checkpoint-store.js'
 export * from './store.js'
+export * from './event-cursor.js'
 export * from './entity.js'
 export * from './replay.js'
 // Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Safe to

package/src/types/run/store.ts

@@ -28,7 +28,19 @@
  */
 
 import type { Run } from './entity.js'
-import type { RunEvent } from './events.js'
+import type { PersistedRunEvent, RunEvent } from './events.js'
+
+/** What a caller asks the log for. See {@link RunStore.readEvents}. */
+export interface ReadRunEventsOptions {
+	/**
+	 * Return only events ABOVE this sequence — strictly greater, never equal.
+	 *
+	 * The exclusive boundary is what makes a cursor round-trip: a consumer that
+	 * last saw `seq: 12` passes 12 and receives 13 onward, so nothing is
+	 * delivered twice. Absent means the whole log.
+	 */
+	readonly sinceSeq?: number
+}
 
 /**
  * One finished tool call, recovered from the run's own transcript.
@@ -71,6 +83,36 @@ export interface RunStore {
 	 */
 	appendEvent(event: RunEvent): Promise<void>
 
+	/**
+	 * Read the run's durable event log back, oldest first.
+	 *
+	 * Required, unlike {@link RunStore.addToIndex}, and the asymmetry is the
+	 * point: a store that records a transcript it cannot read back is
+	 * write-only evidence, which is the defect the whole contract exists to
+	 * fix one level up. It is also what a reconnecting consumer catches up
+	 * through — "refresh the page and keep watching the answer arrive" is this
+	 * method plus a cursor and nothing else.
+	 *
+	 * Three obligations, each of which a consumer relies on:
+	 *
+	 *  1. **Ascending by `seq`, in the order the events were appended.** Do not
+	 *     sort a log back into order — a log that needs sorting was written by
+	 *     two processes, and hiding that produces a plausible transcript of a
+	 *     run that never happened.
+	 *  2. **`sinceSeq` is exclusive.** See {@link ReadRunEventsOptions}.
+	 *  3. **Contiguous, or honestly short.** A backend that prunes may return a
+	 *     first event above `sinceSeq + 1`; that is a gap, the caller detects
+	 *     it, and the reconnect is refused rather than spliced. Do NOT
+	 *     manufacture placeholders to close it.
+	 *
+	 * High-frequency events never enter the log (see
+	 * {@link RunStore.appendEvent}), so what a late subscriber recovers is
+	 * message-granular, not keystroke-granular. Aggregated assistant text,
+	 * every tool result and the full message list are all intact; the deltas
+	 * that composed them are not, and are not meant to be.
+	 */
+	readEvents(options?: ReadRunEventsOptions): Promise<readonly PersistedRunEvent[]>
+
 	/**
 	 * Persist the run's final report. Returns a location, or `null` when the
 	 * backend has none. See {@link RunStore.initRun}.