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/llm/tests/assembler.spec.ts

@@ -0,0 +1,46 @@
+import { describe, expect, it } from 'vitest'
+import { BlockAssembler, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+describe('BlockAssembler', () => {
+  it('assembles interleaved text, reasoning, and tool-call deltas', () => {
+    const chunks: StreamChunk[] = [
+      { type: 'block-start', index: 0, blockType: 'reasoning' },
+      { type: 'reasoning-delta', index: 0, text: 'thinking…' },
+      { type: 'block-end', index: 0, block: { type: 'reasoning', text: 'thinking…' } },
+      { type: 'block-start', index: 1, blockType: 'text' },
+      { type: 'text-delta', index: 1, text: 'Hello' },
+      { type: 'text-delta', index: 1, text: ' world' },
+      { type: 'block-start', index: 2, blockType: 'tool-call' },
+      { type: 'tool-call-delta', index: 2, id: 'call-1', name: 'echo', argumentsDelta: '{"text":' },
+      { type: 'tool-call-delta', index: 2, id: 'call-1', argumentsDelta: '"hi"}' },
+      { type: 'usage', usage: { inputTokens: 10, outputTokens: 5 } },
+      { type: 'finish', reason: { kind: 'tool-calls' } },
+    ]
+    const assembler = new BlockAssembler()
+    for (const chunk of chunks) assembler.push(chunk)
+
+    expect(assembler.blocks()).toEqual([
+      { type: 'reasoning', text: 'thinking…' },
+      { type: 'text', text: 'Hello world' },
+      { type: 'tool-call', id: 'call-1', name: 'echo', arguments: '{"text":"hi"}' },
+    ])
+    expect(assembler.usage).toEqual({ inputTokens: 10, outputTokens: 5 })
+    expect(assembler.finish).toEqual({ kind: 'tool-calls' })
+    expect(assembler.message().role).toBe('assistant')
+  })
+
+  it('returns the completed block from push() on block-end', () => {
+    const assembler = new BlockAssembler()
+    expect(assembler.push({ type: 'block-start', index: 0, blockType: 'text' })).toBeUndefined()
+    expect(assembler.push({ type: 'text-delta', index: 0, text: 'hi' })).toBeUndefined()
+    const block = assembler.push({ type: 'block-end', index: 0, block: { type: 'text', text: 'hi' } })
+    expect(block).toEqual({ type: 'text', text: 'hi' })
+  })
+
+  it('tolerates deltas without explicit block-start/end', () => {
+    const assembler = new BlockAssembler()
+    assembler.push({ type: 'text-delta', index: 0, text: 'implicit' })
+    expect(assembler.blocks()).toEqual([{ type: 'text', text: 'implicit' }])
+    expect(assembler.finish).toEqual({ kind: 'stop' })
+  })
+})

packages/llm/tests/service.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import LlmService, { GenerateOptions, LlmAdapter, StreamChunk } from '@deepseek-ai/dsh-llm'
+
+class ScriptedAdapter extends LlmAdapter {
+  constructor(private script: StreamChunk[]) {
+    super()
+  }
+
+  async * stream(_options: GenerateOptions): AsyncIterable<StreamChunk> {
+    yield * this.script
+  }
+}
+
+const SCRIPT: StreamChunk[] = [
+  { type: 'block-start', index: 0, blockType: 'text' },
+  { type: 'text-delta', index: 0, text: 'hi' },
+  { type: 'finish', reason: { kind: 'stop' } },
+]
+
+describe('LlmService', () => {
+  it('routes stream() to the registered adapter and generate() assembles it', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter(SCRIPT))
+
+    const chunks: StreamChunk[] = []
+    for await (const chunk of ctx.llm.stream({ model: 'test-model', messages: [] })) chunks.push(chunk)
+    expect(chunks).toHaveLength(3)
+
+    const result = await ctx.llm.generate({ model: 'test-model', messages: [] })
+    expect(result.message.content).toEqual([{ type: 'text', text: 'hi' }])
+    expect(result.finish).toEqual({ kind: 'stop' })
+  })
+
+  it('throws NO_ADAPTER for unregistered models', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    await expect(ctx.llm.generate({ model: 'nope', messages: [] })).rejects.toThrow('no adapter registered')
+  })
+
+  it('unregisters adapters when the owning fiber is disposed (HMR safety)', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+
+    const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+      inner.llm.registerAdapter(['scoped-model'], new ScriptedAdapter(SCRIPT))
+    }, { inject: ['llm'] }))
+    expect(ctx.llm.models()).toEqual(['scoped-model'])
+
+    await fiber.dispose()
+    expect(ctx.llm.models()).toEqual([])
+  })
+
+  it('lets llm/stream waterfall listeners wrap the underlying stream', async () => {
+    const ctx = new Context()
+    await ctx.plugin(LlmService)
+    ctx.llm.registerAdapter(['test-model'], new ScriptedAdapter(SCRIPT))
+
+    ctx.on('llm/stream', function (options, next) {
+      const inner = next()
+      return (async function * () {
+        yield { type: 'block-start', index: 99, blockType: 'text' } satisfies StreamChunk
+        yield * inner
+      })()
+    })
+
+    const chunks: StreamChunk[] = []
+    for await (const chunk of ctx.llm.stream({ model: 'test-model', messages: [] })) chunks.push(chunk)
+    expect(chunks).toHaveLength(4)
+    expect(chunks[0]).toMatchObject({ index: 99 })
+  })
+})