Merge remote-tracking branch 'origin/master' into xtr/agent-loop-message-machine

# Conflicts:
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/session.i18n.yaml
#	docs/event-producer-consumer.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl

packages/telemetry/session-telemetry/src/coordinator.ts

@@ -0,0 +1,285 @@
+/**
+ * Capture coordinator: the seam's upstream half. Subscribes to the session
+ * firehose plus the one live-bus relay (`agent/error`), applies the fixed
+ * chunk projection, builds logical records, runs each through the
+ * `telemetry/record` waterfall (deployment-mounted redaction rules;
+ * pass-through when none), and hands the result to the backend — synchronously, with every
+ * handler self-contained so a failing backend can never starve other
+ * subscribers (cordis `emit` is stop-on-throw) or touch the agent loop.
+ * Composed by a backend in its constructor.
+ *
+ * @module @deepseek-ai/dsh-session-telemetry/coordinator
+ */
+
+import type { Context } from 'cordis'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { TelemetryBackend, TelemetryRecord, TelemetrySeverity } from './index.ts'
+
+/**
+ * The handoff cursor: per session, the highest `seq` handed to a backend.
+ * Deliberately MODULE-scope ambient state — a narrow, documented exception
+ * to the registrations-are-effects discipline: cordis has no HMR
+ * state-handover API, and keying by the `Session` object (which belongs to
+ * the session store and outlives any telemetry fiber) is the only in-process
+ * lifetime that lets a re-adopting fiber resume instead of re-handing
+ * history. Entries die with their sessions; a missing entry safely means
+ * "re-hand everything". Advanced only at emit time — the cursor marks
+ * handed-off, not delivered.
+ */
+const handoffCursor = new WeakMap<Session, number>()
+
+/**
+ * Install the telemetry capture side onto a context for one backend.
+ *
+ * Registers the persistence-coordinator listener set plus the `agent/error`
+ * relay, all through `ctx.effect()`/`ctx.on()` on the composing fiber, and
+ * sweeps already-live sessions (a hot reload does not replay
+ * `session/created`). A `session/disposed` emits the session's `shutdown`
+ * operational record — the marker rides the session's own termination edge,
+ * where receivers key crash detection — and retires it from the adopted set,
+ * so a long-lived backend neither retains closed sessions (and their frozen
+ * event logs) nor re-marks them at unload. Disposal marks the sessions still
+ * alive at teardown (their own edge would fire unobserved) and then awaits
+ * the backend's `shutdown()`; a failure there warns instead of throwing —
+ * best-effort reporting must not fail application teardown.
+ */
+export class TelemetryCoordinator {
+  /**
+   * Sessions adopted by THIS fiber and still live, for double-adoption
+   * protection and the teardown sweep of unmarked sessions;
+   * `session/disposed` marks and retires entries.
+   */
+  private readonly adopted = new Set<Session>()
+  /** Per session, the `turn:step` keys whose first chunk already shipped; rebuilt from the log on re-adoption. */
+  private readonly chunkSeen = new WeakMap<Session, Set<string>>()
+
+  /**
+   * @param ctx - the composing backend's context; listeners bind to its fiber.
+   * @param backend - the backend receiving records; owned elsewhere, never disposed here beyond `shutdown()` forwarding.
+   */
+  constructor(
+    private readonly ctx: Context,
+    private readonly backend: TelemetryBackend,
+  ) {
+    ctx.on('session/created', (session) => {
+      this.adopt(session)
+    })
+    // The session's own termination edge: emit the shutdown marker HERE —
+    // receivers classify a session with activity and no marker as crashed,
+    // so a normally closed session in a long-running host must get its
+    // marker at disposal, not never. Then retire: the projection/cursor
+    // WeakMaps die with the Session object; only the strong adopted set
+    // needs the explicit release.
+    ctx.on('session/disposed', (session) => {
+      this.contain(() => {
+        if (!this.adopted.delete(session)) return
+        this.handOff(shutdownRecord(session))
+      })
+    })
+    ctx.on('session/event', (session, event) => {
+      this.contain(() => {
+        this.capture(session, event)
+      })
+    })
+    // Parallel listeners are awaited by the loop at turn end; returning void
+    // (not the SDK's flush promise) is the turn-latency contract.
+    ctx.on('session/flush', (session) => {
+      this.contain(() => {
+        this.hintFlush(session)
+      })
+    })
+    ctx.on('agent/error', (agent, turn, step, error) => {
+      this.contain(() => {
+        this.relayAgentError(agent, turn, step, error)
+      })
+    })
+    ctx.effect(() => async () => {
+      // Sessions still adopted here are alive through a whole-application
+      // teardown (their own disposal edge will fire after telemetry is gone,
+      // unobserved) — mark them now so the receiver sees a clean stop of
+      // observation rather than a crash-shaped silence.
+      for (const session of this.adopted) {
+        this.contain(() => {
+          this.handOff(shutdownRecord(session))
+        })
+      }
+      try {
+        await this.backend.shutdown()
+      } catch (error) {
+        this.ctx.logger.warn(`telemetry: backend shutdown failed: ${String(error)}`)
+      }
+    }, 'telemetry capture')
+    for (const session of ctx.sessions.list()) {
+      this.adopt(session)
+    }
+  }
+
+  /**
+   * Adopt a session: replay its log THROUGH the projection from the handoff
+   * cursor, then rely on the firehose for everything after. When no cursor
+   * survived, replay starts at the session's construction boundary
+   * (`firstLiveSeq`), not seq 0: constructor seeds never publish on the
+   * firehose, and their content already left the process under another
+   * identity — the same id in a previous process (resume) or the parent's
+   * stream (fork, stitched by receivers via `session.seed_length`). Events
+   * at or below the start still feed the projection state (first-chunk
+   * tracking) without being re-handed, so a resumed fiber drops mid-step
+   * chunk continuations exactly like the fiber that saw the step begin. The
+   * cost, accepted with the seam's at-most-once stance: a resume no longer
+   * backfills records a previous process failed to deliver.
+   * @param session - the live session to adopt; a second adoption is a no-op.
+   */
+  private adopt(session: Session): void {
+    if (this.adopted.has(session)) return
+    this.adopted.add(session)
+    const cursor = handoffCursor.get(session) ?? session.firstLiveSeq - 1
+    // Containment is PER EVENT, matching the firehose: one rejected record
+    // is withheld fail-closed while the rest of the historical replay
+    // proceeds — wrapping the whole loop would let a single failure silently
+    // skip the remainder of the log on an already-adopted session.
+    for (const event of session.events) {
+      this.contain(() => {
+        if (event.seq <= cursor) this.track(session, event)
+        else this.capture(session, event)
+      })
+    }
+  }
+
+  /** Feed the chunk projection without handing off — the ≤cursor half of re-adoption. */
+  private track(session: Session, event: SessionEvent): void {
+    if (event.type === 'assistant/chunk') {
+      this.seen(session).add(`${event.data.turn}:${event.data.step}`)
+    }
+  }
+
+  /** Project one event and hand it to the backend, advancing the cursor on handoff. */
+  private capture(session: Session, event: SessionEvent): void {
+    if (event.type === 'assistant/chunk') {
+      const key = `${event.data.turn}:${event.data.step}`
+      const seen = this.seen(session)
+      // Fixed chunk projection: only the first chunk of each (turn, step)
+      // ships — the stream-started signal; content is byte-complete in the
+      // step's assembled assistant/message. Dropped chunks do not advance
+      // the cursor, so re-adoption re-drops them deterministically.
+      if (seen.has(key)) return
+      seen.add(key)
+    }
+    this.handOff({
+      channel: 'ledger',
+      time: event.time,
+      severity: severityOf(event),
+      attributes: identityOf(session, event),
+      // The live event object is mutable and the backend serializes later;
+      // append-time validation guarantees this clone cannot throw.
+      body: structuredClone(event.data),
+    })
+    handoffCursor.set(session, event.seq)
+  }
+
+  /**
+   * Run the `telemetry/record` waterfall over one record and hand the result
+   * to the backend. The innermost `next` passes the record through unchanged
+   * — the seam ships no rules; exported data is as clean as the listeners a
+   * deployment mounts. Callers run inside {@link contain}, so a throwing
+   * rule withholds the record instead of reaching the loop (fail-closed).
+   */
+  private handOff(record: TelemetryRecord): void {
+    this.backend.emit(this.ctx.waterfall('telemetry/record', record, () => record))
+  }
+
+  /** Forward the turn-end boundary to the backend's optional flush hint. */
+  private hintFlush(session: Session): void {
+    if (this.adopted.has(session)) this.backend.flush?.()
+  }
+
+  /** Relay one `agent/error` bus emission as an `agent-error` operational record. */
+  private relayAgentError(agent: Agent, turn: number, step: number, error: unknown): void {
+    const detail = errorDetail(error)
+    this.handOff({
+      channel: 'ops',
+      time: Date.now(),
+      severity: 'error',
+      attributes: {
+        'telemetry.op': 'agent-error',
+        'session.id': String(agent.session.id),
+        'agent.id': agent.id,
+        'error.name': detail.name,
+        turn,
+        step,
+      },
+      body: detail,
+    })
+  }
+
+  /** Lazily create the per-session first-chunk tracking set. */
+  private seen(session: Session): Set<string> {
+    let set = this.chunkSeen.get(session)
+    if (!set) this.chunkSeen.set(session, set = new Set())
+    return set
+  }
+
+  /**
+   * Run one capture-side step with its exception contained: cordis `emit`
+   * is stop-on-throw, so a throwing listener would starve every subscriber
+   * registered after this plugin — nothing from the backend may escape.
+   */
+  private contain(step: () => void): void {
+    try {
+      step()
+    } catch (error) {
+      this.ctx.logger.warn(`telemetry: capture step failed: ${String(error)}`)
+    }
+  }
+}
+
+/**
+ * Build the per-session clean-exit marker: emitted at the session's own
+ * disposal edge, or at coordinator dispose for sessions still alive then.
+ */
+function shutdownRecord(session: Session): TelemetryRecord {
+  return {
+    channel: 'ops',
+    time: Date.now(),
+    severity: 'info',
+    attributes: { 'telemetry.op': 'shutdown', 'session.id': String(session.id) },
+    body: { op: 'shutdown' },
+  }
+}
+
+/** Map an event's own outcome flag to the pre-baked alerting severity. */
+function severityOf(event: SessionEvent): TelemetrySeverity {
+  switch (event.type) {
+    case 'tool/result':
+      return event.data.isError ? 'error' : 'info'
+    case 'turn/end':
+      return event.data.reason.kind === 'error' ? 'error' : 'info'
+    default:
+      // Merge-extensible fall-through (no assertNever): event types this seam
+      // does not depend on — including plugin-merged ones it never heard of —
+      // pass through as info; their owners' outcome semantics stay theirs.
+      return 'info'
+  }
+}
+
+/** Normalize the live bus's arbitrary thrown value into the stable operational-record shape. */
+function errorDetail(error: unknown): { name: string; message: string } {
+  const normalized = error instanceof Error ? error : new Error(String(error))
+  return { name: normalized.name, message: normalized.message }
+}
+
+/** Build the minimal identity attributes: envelope plus self-contained header facts. */
+function identityOf(session: Session, event: SessionEvent): Record<string, string | number> {
+  const attributes: Record<string, string | number> = {
+    'session.id': String(session.id),
+    'event.type': event.type,
+    'event.seq': event.seq,
+  }
+  const { cwd, parentSession, seedLength } = session.header
+  if (cwd !== undefined) attributes['session.cwd'] = cwd
+  if (parentSession !== undefined) attributes['session.parent_id'] = String(parentSession)
+  // The durable fork boundary: a forked stream starts here, and its prefix
+  // lives in the parent's stream — receivers stitch on (parent_id, seed_length).
+  if (seedLength !== undefined) attributes['session.seed_length'] = seedLength
+  return attributes
+}

packages/telemetry/session-telemetry/src/index.ts

@@ -0,0 +1,156 @@
+/**
+ * Telemetry seam for the DeepSeek Harness.
+ *
+ * The seam owns the CAPTURE side of session-event reporting — which records
+ * exist (the chunk projection), what they carry (the logical record), when
+ * they are handed over (adoption, the per-append firehose, lifecycle
+ * forwarding), and the HMR handoff cursor. Everything downstream of
+ * {@link Telemetry.emit} — batching, retry, queueing, loss policy — is the
+ * reporting SDK's territory and is deliberately not modelled here. The
+ * design and its trade-offs are pinned in
+ * .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.md.
+ *
+ * @module @deepseek-ai/dsh-session-telemetry
+ */
+
+import { Context, Service } from 'cordis'
+
+declare module 'cordis' {
+  interface Context {
+    telemetry: Telemetry
+  }
+
+  interface Events {
+    /**
+     * Transform one outbound record before it reaches the backend. This
+     * waterfall is the seam's redaction extension point. It ships NO rules
+     * of its own: the
+     * innermost `next()` passes the record through unchanged, and with no
+     * listener mounted records reach the backend as captured, so exported
+     * data is exactly as clean as the rules a deployment mounts. Listeners
+     * stack by transforming `next()`'s return value; returning without
+     * `next()` replaces everything beneath. Dispatched synchronously on the
+     * capture hot path inside the coordinator's containment: a throwing
+     * listener withholds that one record (fail-closed) and never reaches the
+     * agent loop. Redaction applies to the exported copy only; the canonical
+     * session log is never rewritten.
+     * @param record - the candidate record, already the coordinator's own deep
+     *   copy; listeners return a (possibly new) record and must not mutate it.
+     * @mode waterfall
+     */
+    'telemetry/record'(record: TelemetryRecord, next: () => TelemetryRecord): TelemetryRecord
+  }
+}
+
+/**
+ * Severity of a telemetry record, pre-mapped at capture so a receiver can
+ * alert with zero configuration: `error` for events whose own outcome flag
+ * says so (`tool/result.isError`, `turn/end` error reasons) and for
+ * `agent-error` operational records. Captured events otherwise default to
+ * `info`; `warn` remains available to `telemetry/record` policies and
+ * backends.
+ */
+export type TelemetrySeverity = 'info' | 'warn' | 'error'
+
+/**
+ * One logical record handed to a backend — the seam's whole outbound
+ * vocabulary. Ledger records mirror session-log events one-to-one;
+ * operational records (`channel: 'ops'`) carry the two signals with no log
+ * home (`agent-error`, `shutdown`) and deliberately omit `event.seq`-style
+ * identity so they can never be mistaken for ledger rows.
+ */
+export interface TelemetryRecord {
+  /** Ledger (session-log mirror) or ops (operational signal) channel; backends keep the two under separate instrumentation scopes. */
+  channel: 'ledger' | 'ops'
+  /** Unix epoch milliseconds — the source event's append time for ledger records, the emission time for ops records. */
+  time: number
+  /** Pre-mapped alerting severity; see {@link TelemetrySeverity}. */
+  severity: TelemetrySeverity
+  /**
+   * Identity attributes, deliberately minimal: ledger records carry
+   * `session.id`, `event.type`, `event.seq`, plus `session.cwd` /
+   * `session.parent_id` when the header has them; ops records carry
+   * `telemetry.op`, `session.id`, and (for `agent-error`) `agent.id`,
+   * `turn`, `step`, `error.name`. Anything recoverable from the body is
+   * intentionally NOT duplicated here.
+   */
+  attributes: Record<string, string | number>
+  /**
+   * The complete payload: a deep copy of the session event's `data` for
+   * ledger records (JSON-serializable by `Session.append`'s own
+   * validation), or the op payload for ops records. Never mutated after
+   * handoff.
+   */
+  body: unknown
+}
+
+/**
+ * The backend contract the coordinator hands records to — the minimum any
+ * reporting SDK satisfies with zero bending. {@link Telemetry} is its
+ * service-registered form; tests compose the coordinator with a bare
+ * implementation of this interface.
+ */
+export interface TelemetryBackend {
+  /**
+   * Hand one record to the backend's pipeline. MUST be a non-blocking
+   * enqueue — the coordinator calls this synchronously from the
+   * `session/event` hot path, so anything slower than a queue push would tax
+   * the agent loop. Errors thrown here are contained by the coordinator and
+   * logged; they never reach the loop.
+   * @param record - the logical record to report; owned by the backend after the call.
+   */
+  emit(record: TelemetryRecord): void
+  /**
+   * Optional hint that a natural boundary (turn end) passed — a backend may
+   * forward it to its SDK's flush so records land at turn boundaries. Called
+   * fire-and-forget; implementations must not block and must not throw
+   * meaningfully (the coordinator contains exceptions). Most backends should
+   * leave this unimplemented and let their SDK's own batching cadence govern
+   * export timing: a backend that does implement it owns the interaction
+   * between its concurrent flushes and {@link shutdown}'s drain (the OTel
+   * backend removed its implementation for exactly that hazard — see the
+   * revival Agent Note).
+   */
+  flush?(): void
+  /**
+   * Forward the fiber's disposal to the SDK: flush whatever is queued and
+   * reach quiescence, per the SDK's own shutdown contract. Everything
+   * emitted before this call must still be delivered — including records
+   * enqueued while a {@link flush} hint is in flight, so a backend whose SDK
+   * guards against concurrent flushes orders behind the outstanding one (the
+   * coordinator emits its dispose-time `shutdown` markers immediately before
+   * calling this). Awaited by the coordinator's dispose; a rejection is
+   * logged as a warning and never fails application teardown.
+   * @returns resolves when the backend's pipeline has quiesced.
+   */
+  shutdown(): Promise<void>
+}
+
+/**
+ * The backend contract in its loadable form: one implementation per context —
+ * the cordis `Service` registration under the `telemetry` key throws on a
+ * duplicate, cordis' standard behavior. A backend composes a
+ * {@link TelemetryCoordinator} in its constructor to install the capture side.
+ */
+export abstract class Telemetry extends Service implements TelemetryBackend {
+  constructor(ctx: Context) {
+    super(ctx, 'telemetry')
+  }
+
+  /**
+   * See {@link TelemetryBackend.emit} — the seam declaration is the contract's one home.
+   * @param record - the logical record to report; owned by the backend after the call.
+   */
+  abstract emit(record: TelemetryRecord): void
+
+  /** See {@link TelemetryBackend.flush}. */
+  flush?(): void
+
+  /**
+   * See {@link TelemetryBackend.shutdown}.
+   * @returns resolves when the backend's pipeline has quiesced.
+   */
+  abstract shutdown(): Promise<void>
+}
+
+export { TelemetryCoordinator } from './coordinator.ts'

packages/telemetry/session-telemetry/src/invariant.ts

@@ -0,0 +1,32 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-session-telemetry`.
+ * @module @deepseek-ai/dsh-session-telemetry/invariant
+ */
+
+/* jscpd:ignore-start */
+import type { Context } from 'cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-session-telemetry'
+
+/** Cordis companion plugin name. */
+export const name = 'session-telemetry-invariant'
+/** Service required before the companion can reserve package ownership. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: the seam's whole output is the backend handoff — a
+ * synchronous `emit()` call outside every authoritative event stream — and its
+ * capture side never appends session events, so no event/data relation exists
+ * for an independent companion to observe.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
+/* jscpd:ignore-end */