Add abstract service interface packages

@deepseek-ai/dsh-llm: provider-neutral content-block vocabulary
(merge-extensible maps), raw StreamChunk protocol, ToolSchema,
abstract LlmAdapter, LlmService adapter registry, BlockAssembler.

@deepseek-ai/dsh-session: event-sourced Session (append-only log,
deriveMessages; context/steering render as tagged envelopes),
SessionStore, session/event + awaited session/flush durability seam.

@deepseek-ai/dsh-system-prompt: ordered sections + tool-schema
providers; assemble() through the system-prompt/assemble waterfall.
Tool schemas are part of the assembly by design.

@deepseek-ai/dsh-tools: tool registry feeding schemas into the
assembly; execute() through the tools/execute waterfall (the single
sandbox/permission/hook seam).

@deepseek-ai/dsh-agent: Agent interface (send/steer/inject/abort,
spawn/fork TODO seams), AgentRegistry, and the full agent/* event
taxonomy so plugins never depend on the concrete loop.

packages/session/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@deepseek-ai/dsh-session",
+  "description": "Event-sourced session store for the DeepSeek Harness",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/session/src/index.ts

@@ -0,0 +1,163 @@
+import { Context, Service } from 'cordis'
+import type { ContentBlock, Message, MessageSource } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent, SessionEventMap, SessionEventType } from './types.ts'
+
+export * from './types.ts'
+
+declare module 'cordis' {
+  interface Context {
+    sessions: SessionStore
+  }
+
+  interface Events {
+    /** A session was created in the store. */
+    'session/created'(session: Session): void
+    /** An event was appended to a session log (sync, fire-and-forget). */
+    'session/event'(session: Session, event: SessionEvent): void
+    /**
+     * Awaited durability checkpoint. The agent loop awaits
+     * `ctx.parallel('session/flush', session)` at every turn end; persistence
+     * plugins (JSONL, sqlite — TODO, future phase) drain their write-behind
+     * buffers here and on fiber dispose.
+     */
+    'session/flush'(session: Session): Promise<void> | void
+  }
+}
+
+/**
+ * Renders a `context/message` or `steering/message` event as a tagged
+ * synthetic user-role message (the system-reminder pattern: zero adapter
+ * burden, models distinguish it from real user prompts by the envelope).
+ *
+ * TODO(review): revisit the envelope once a real adapter exists.
+ */
+function renderTagged(tag: string, content: ContentBlock[], source: MessageSource): ContentBlock[] {
+  const open = `<${tag} source=${JSON.stringify(source.kind)}>`
+  const close = `</${tag}>`
+  return [
+    { type: 'text', text: open },
+    ...content,
+    { type: 'text', text: close },
+  ]
+}
+
+/**
+ * An event-sourced session: an append-only log of {@link SessionEvent}s.
+ *
+ * Plain class (not a Service) — create instances via `ctx.sessions.create()`.
+ * Seeding with an existing event log replays/forks a session.
+ */
+export class Session {
+  private log: SessionEvent[] = []
+  /** Set by the store so appends are observable; no-op when detached. */
+  onAppend?: (event: SessionEvent) => void
+
+  constructor(public readonly id: string, seed?: SessionEvent[]) {
+    if (seed) this.log = [...seed]
+  }
+
+  get events(): readonly SessionEvent[] {
+    return this.log
+  }
+
+  get seq(): number {
+    return this.log.length
+  }
+
+  /** Append one event. Synchronous — the hot path never blocks on I/O. */
+  append<T extends SessionEventType>(type: T, data: SessionEventMap[T]): SessionEvent<T> {
+    const event: SessionEvent<T> = { type, seq: this.log.length, time: Date.now(), data }
+    this.log.push(event as SessionEvent)
+    this.onAppend?.(event as SessionEvent)
+    return event
+  }
+
+  /**
+   * Derive the LLM message history from the event log.
+   *
+   * - `user/message` → user message
+   * - `assistant/message` → assistant message (chunks are skipped — they are
+   *   replay/UI data; the assembled message is authoritative for history)
+   * - `tool/result` → user message carrying a tool-result block
+   * - `context/message` / `steering/message` → tagged synthetic user messages
+   *   at their chronological position
+   */
+  deriveMessages(): Message[] {
+    const messages: Message[] = []
+    for (const event of this.log) {
+      switch (event.type) {
+        case 'user/message': {
+          const { content } = event.data as SessionEventMap['user/message']
+          messages.push({ role: 'user', content })
+          break
+        }
+        case 'assistant/message': {
+          const { content } = event.data as SessionEventMap['assistant/message']
+          messages.push({ role: 'assistant', content })
+          break
+        }
+        case 'tool/result': {
+          const { callId, content, isError } = event.data as SessionEventMap['tool/result']
+          messages.push({
+            role: 'user',
+            content: [{ type: 'tool-result', toolCallId: callId, content, isError }],
+          })
+          break
+        }
+        case 'context/message': {
+          const { content, source } = event.data as SessionEventMap['context/message']
+          messages.push({ role: 'user', content: renderTagged('context', content, source) })
+          break
+        }
+        case 'steering/message': {
+          const { content, source } = event.data as SessionEventMap['steering/message']
+          messages.push({ role: 'user', content: renderTagged('steering', content, source) })
+          break
+        }
+      }
+    }
+    return messages
+  }
+}
+
+/**
+ * In-memory session store (`ctx.sessions`).
+ *
+ * Persistence is intentionally not implemented here — persistence plugins
+ * subscribe to `session/event` and flush on `session/flush` / dispose.
+ */
+export class SessionStore extends Service {
+  private store = new Map<string, Session>()
+  private counter = 0
+
+  constructor(ctx: Context) {
+    super(ctx, 'sessions')
+  }
+
+  /** Create a session. `seed` replays/forks an existing event log. */
+  create(id?: string, seed?: SessionEvent[]): Session {
+    id ??= `session-${++this.counter}`
+    if (this.store.has(id)) throw new Error(`session "${id}" already exists`)
+    const session = new Session(id, seed)
+    session.onAppend = (event) => this.ctx.emit('session/event', session, event)
+    this.ctx.effect(() => {
+      this.store.set(id, session)
+      this.ctx.emit('session/created', session)
+      return () => {
+        session.onAppend = undefined
+        this.store.delete(id)
+      }
+    }, 'sessions.create()')
+    return session
+  }
+
+  get(id: string): Session | undefined {
+    return this.store.get(id)
+  }
+
+  list(): Session[] {
+    return [...this.store.values()]
+  }
+}
+
+export default SessionStore

packages/session/src/types.ts

@@ -0,0 +1,74 @@
+import type { ContentBlock, MessageSource, StreamChunk, TokenUsage } from '@deepseek-ai/dsh-llm'
+
+/**
+ * What started a turn.
+ * Merge-extensible sum type (same pattern as MessageSourceMap).
+ */
+export interface TurnTriggerMap {
+  message: { kind: 'message'; source: MessageSource }
+  continuation: { kind: 'continuation' }
+}
+
+export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap]
+
+/**
+ * Why a turn ended.
+ * Merge-extensible sum type.
+ */
+export interface TurnEndReasonMap {
+  completed: { kind: 'completed' }
+  aborted: { kind: 'aborted'; reason?: string }
+  error: { kind: 'error'; message: string; code?: string }
+  disposed: { kind: 'disposed' }
+}
+
+export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap]
+
+/**
+ * The session event vocabulary — the append-only source of truth for an
+ * agent's whole interaction history. The LLM message history is *derived*
+ * from this log; nothing else is authoritative. Replay = re-derive from the
+ * same events; trace/telemetry = subscribe to the log.
+ *
+ * Merge-extensible: plugins declare extra event types via declaration merging
+ * (e.g. a compaction plugin adds `'compaction/marker'`).
+ *
+ * TODO(review): this vocabulary needs careful review once the loop and the
+ * first persistence plugin exist side by side.
+ */
+export interface SessionEventMap {
+  'turn/start': { turn: number; trigger: TurnTrigger }
+  'turn/end': { turn: number; reason: TurnEndReason }
+  'step/start': { turn: number; step: number }
+  'step/end': { turn: number; step: number }
+  /** A user-visible prompt (queued message drained at turn start). */
+  'user/message': { content: ContentBlock[]; source: MessageSource }
+  /**
+   * In-session context injection (file-change notices, subdir AGENTS.md,
+   * skill content, cron notifications, …). Rendered into the derived history
+   * as tagged synthetic context — NOT a user prompt.
+   */
+  'context/message': { content: ContentBlock[]; source: MessageSource }
+  /** Raw stream chunk — token-level replay fidelity. */
+  'assistant/chunk': { turn: number; step: number; chunk: StreamChunk }
+  /** Assembled assistant message for one step (derived history uses this). */
+  'assistant/message': { turn: number; step: number; content: ContentBlock[] }
+  'tool/call': { turn: number; step: number; callId: string; name: string; arguments: string }
+  'tool/result': { turn: number; step: number; callId: string; content: ContentBlock[]; isError: boolean }
+  /** Steering content injected between steps of a running turn. */
+  'steering/message': { turn: number; content: ContentBlock[]; source: MessageSource }
+  'usage': { turn: number; step: number; usage: TokenUsage }
+  'error': { turn: number; step: number; message: string; code?: string }
+}
+
+export type SessionEventType = keyof SessionEventMap
+
+/** One immutable entry in the session log. */
+export interface SessionEvent<T extends SessionEventType = SessionEventType> {
+  type: T
+  /** Monotonic sequence number within the session. */
+  seq: number
+  /** Unix epoch milliseconds. */
+  time: number
+  data: SessionEventMap[T]
+}

packages/session/tests/session.spec.ts

@@ -0,0 +1,109 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import SessionStore, { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+
+describe('Session', () => {
+  it('derives message history from the event log', () => {
+    const session = new Session('s1')
+    session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
+    session.append('user/message', { content: [{ type: 'text', text: 'hello' }], source: { kind: 'user' } })
+    session.append('assistant/chunk', { turn: 1, step: 1, chunk: { type: 'text-delta', index: 0, text: 'hi' } })
+    session.append('assistant/message', {
+      turn: 1, step: 1,
+      content: [
+        { type: 'text', text: 'let me check' },
+        { type: 'tool-call', id: 'c1', name: 'echo', arguments: '{}' },
+      ],
+    })
+    session.append('tool/result', { turn: 1, step: 1, callId: 'c1', content: [{ type: 'text', text: 'ok' }], isError: false })
+    session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+
+    const messages = session.deriveMessages()
+    expect(messages.map(m => m.role)).toEqual(['user', 'assistant', 'user'])
+    // raw chunks must NOT appear in derived history
+    expect(messages[1].content).toHaveLength(2)
+    expect(messages[2].content[0]).toMatchObject({ type: 'tool-result', toolCallId: 'c1' })
+  })
+
+  it('renders context and steering messages as tagged synthetic user content', () => {
+    const session = new Session('s2')
+    session.append('context/message', {
+      content: [{ type: 'text', text: 'file changed: a.ts' }],
+      source: { kind: 'plugin', plugin: 'watcher' },
+    })
+    session.append('steering/message', {
+      turn: 1,
+      content: [{ type: 'text', text: 'focus on tests' }],
+      source: { kind: 'user' },
+    })
+
+    const [contextMessage, steeringMessage] = session.deriveMessages()
+    expect(contextMessage.role).toBe('user')
+    expect(contextMessage.content[0]).toMatchObject({ type: 'text', text: '<context source="plugin">' })
+    expect(contextMessage.content.at(-1)).toMatchObject({ type: 'text', text: '</context>' })
+    expect(steeringMessage.content[0]).toMatchObject({ type: 'text', text: '<steering source="user">' })
+  })
+
+  it('replays identically from a seeded event log', () => {
+    const original = new Session('s3')
+    original.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } })
+    original.append('assistant/message', { turn: 1, step: 1, content: [{ type: 'text', text: 'a' }] })
+
+    const replayed = new Session('s3-replay', [...original.events])
+    expect(replayed.deriveMessages()).toEqual(original.deriveMessages())
+    expect(replayed.seq).toBe(original.seq)
+  })
+})
+
+describe('SessionStore', () => {
+  it('creates sessions, emits session/created and session/event', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+
+    const created: Session[] = []
+    const events: [Session, SessionEvent][] = []
+    ctx.on('session/created', session => void created.push(session))
+    ctx.on('session/event', (session, event) => void events.push([session, event]))
+
+    const session = ctx.sessions.create()
+    expect(created).toEqual([session])
+
+    session.append('user/message', { content: [{ type: 'text', text: 'x' }], source: { kind: 'user' } })
+    expect(events).toHaveLength(1)
+    expect(events[0][0]).toBe(session)
+    expect(events[0][1].type).toBe('user/message')
+
+    expect(ctx.sessions.get(session.id)).toBe(session)
+    expect(ctx.sessions.list()).toEqual([session])
+  })
+
+  it('rejects duplicate ids and supports seeding', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+    const a = ctx.sessions.create('fixed')
+    expect(() => ctx.sessions.create('fixed')).toThrow('already exists')
+
+    a.append('user/message', { content: [{ type: 'text', text: 'q' }], source: { kind: 'user' } })
+    const forked = ctx.sessions.create('fork', [...a.events])
+    expect(forked.deriveMessages()).toEqual(a.deriveMessages())
+  })
+
+  it('detaches sessions when the creating fiber is disposed (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SessionStore)
+
+    let session!: Session
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      session = inner.sessions.create('scoped')
+    }, { inject: ['sessions'] }))
+    expect(ctx.sessions.get('scoped')).toBe(session)
+
+    let observed = 0
+    ctx.on('session/event', () => void observed++)
+
+    await fiber.dispose()
+    expect(ctx.sessions.get('scoped')).toBeUndefined()
+    session.append('user/message', { content: [{ type: 'text', text: 'late' }], source: { kind: 'user' } })
+    expect(observed).toBe(0)
+  })
+})

packages/session/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../vendor/cosmokit" },
+    { "path": "../../vendor/cordis" },
+    { "path": "../llm" }
+  ]
+}