Merge remote-tracking branch 'origin/master' into session-surface

packages/session/src/json.ts

@@ -1,7 +1,7 @@
 /**
  * JSON-serializability validation for session event data.
  *
- * The session event log is the durable source of truth (ADR 0003/0018): every
+ * The session event log is the durable source of truth (the event-sourcing / session-persistence RFCs): every
  * `event.data` must round-trip losslessly through JSON so any persistence
  * backend can store and reload it byte-identically. This invariant belongs to
  * the log itself — `Session.append` enforces it at the source, so a

packages/session/src/repair.ts

@@ -16,7 +16,7 @@
  *   3. a `turn/end` carrying the merge-extensible `{ kind: 'interrupted' }` reason.
  *
  * The marker records that the turn was cut short by a crash, not completed by
- * the model. See ADR 0018.
+ * the model. See the session-persistence RFC.
  *
  * Why the synthetic tool results matter: `deriveMessages()` renders the
  * `tool-call` blocks inside a durable `assistant/message` but only emits a

packages/session/src/types.ts

@@ -93,12 +93,26 @@ export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap]
 /**
  * Why a turn ended.
  * Merge-extensible sum type.
+ *
+ * `max-tokens` mirrors the model-call `FinishReasonMap` variant (DeepSeek's
+ * `length`): the turn ended because a step hit the output-token ceiling, not
+ * because the model chose to stop. The agent-loop surfaces it via the rule
+ * "any `max-tokens` step in the turn makes the turn end `max-tokens`" (a
+ * continuation plugin can run further steps after one, but the cut-short fact
+ * still wins). It is distinct from `completed` so a consumer (e.g. the ACP
+ * bridge mapping to `StopReason: 'max_tokens'`) can tell a clean stop from a
+ * truncated one. The next variants to add — when an adapter/loop first emits
+ * them — are `refusal` and `max_turn_requests` (both named by the ACP RFC as ACP
+ * stop reasons); no current adapter produces a `refusal` finish (unknown
+ * DeepSeek finish reasons collapse to `error`), so it is deliberately omitted
+ * until one does.
  */
 export interface TurnEndReasonMap {
   completed: { kind: 'completed' }
   aborted: { kind: 'aborted'; reason?: string }
   error: { kind: 'error'; message: string; code?: string }
   disposed: { kind: 'disposed' }
+  'max-tokens': { kind: 'max-tokens' }
   /**
    * The turn never ended on its own: the process crashed mid-turn and a
    * persistence backend later closed the orphaned (open) turn on reload so the
@@ -107,7 +121,7 @@ export interface TurnEndReasonMap {
    * the crash) and are PRESERVED, not discarded: a single turn can be huge in a
    * long-horizon task (many steps, large tool output), so truncating it would
    * lose real work. The marker records that the turn was cut short, not that the
-   * model completed it. See ADR 0018.
+   * model completed it. See the session-persistence RFC.
    */
   interrupted: { kind: 'interrupted' }
 }

packages/session/tests/properties.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Property-based tests for the Session event log (RFC 001 → ADR 0013).
+ * Property-based tests for the Session event log (the property-testing RFC).
  *
  * Generates arbitrary event logs and asserts the derivation invariants the
  * agent loop and replay depend on: deriveMessages is deterministic and

packages/session/tests/session.spec.ts

@@ -26,6 +26,19 @@ describe('Session', () => {
     expect(messages[2]!.content[0]).toMatchObject({ type: 'tool-result', toolCallId: CallId('c1') })
   })
 
+  it('accepts and round-trips a max-tokens turn/end reason', () => {
+    // The max-tokens TurnEndReason variant carries no extra data, so it must
+    // append and persist like any other reason (JSON-serializable, no fields).
+    const session = new Session(SessionId('s1'))
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('turn/end', { turn: 1, reason: { kind: 'max-tokens' } })
+
+    const turnEnd = session.events.findLast(e => e.type === 'turn/end')!
+    expect(turnEnd.data.reason).toEqual({ kind: 'max-tokens' })
+    // survives a structuredClone (the persistence-serialization boundary)
+    expect(structuredClone(turnEnd.data.reason)).toEqual({ kind: 'max-tokens' })
+  })
+
   it('renders context and steering messages as tagged synthetic user content', () => {
     const session = new Session(SessionId('s2'))
     session.append('context/message', {