feat(session-persistence): abstract seam + JSONL backend + wiring

Add the durable session-persistence capability seam (ADR 0016): an
abstract SessionPersistence service (dsh-session-persistence,
ctx.sessionPersistence) defining create/append/load/list/has/delete/
update over the existing SessionEvent — no parallel persisted type — and
a first implementation (dsh-session-persistence-jsonl): an append-only
JSONL log per session with crash-safe atomic writes, truncation-repair
of a never-committed crash tail, and a read/replay path. SessionMeta
(format version, cwd, lineage) travels out-of-log via session.header.

A shared runPersistenceContract suite holds every backend to the same
append-only / contiguous-seq / lazy-materialization / serializability
semantics.

Config-driven create() now uses a per-run ${id}-session-<uuid> session
id so a fixed name no longer collides with an on-disk log once a durable
backend is loaded; each run is a new session (a demo simplification). The
examples drop their hand-rolled session-jsonl.ts and load the JSONL
backend via cordis.yml; CI smoke-loads it too.

The agent-facing create/resume factory that consumes load() is a
separate seam, deferred to a follow-up; this change stops at the load
primitive and does not reach into the loop.

packages/agent-loop/README.md

@@ -8,7 +8,7 @@ This is the only package in the harness that contains concrete loop logic. Every
 
 ### Public API
 
-- `ctx.agentLoop.create(id: string, options?: AgentOptions): LoopAgent` Create an agent, start its loop, and register it in `ctx.agents`. Disposed with the calling fiber.
+- `ctx.agentLoop.create(id: string, options?: AgentOptions): LoopAgent` — create an agent on a fresh per-run session id `${id}-session-<uuid>`, start its loop, and register it in `ctx.agents`. The per-run uuid avoids colliding with the on-disk log a prior run materialized once a durable persistence backend is loaded; each run is a new session (a deliberate demo simplification — a real resume-or-create policy is a TODO). Disposed with the calling fiber.
 
 ### Injected services
 

packages/agent-loop/package.json

@@ -35,6 +35,7 @@
     "@deepseek-ai/dsh-invariants": "^0.0.1",
     "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
     "@deepseek-ai/dsh-system-prompt": "^0.0.1",
     "@deepseek-ai/dsh-tools": "^0.0.1",
     "cordis": "^4.0.0-rc.6"

packages/agent-loop/src/index.ts

@@ -8,6 +8,7 @@
  */
 
 import { Context, Service } from 'cordis'
+import { randomUUID } from 'node:crypto'
 import z from 'schemastery'
 import { AgentId } from '@deepseek-ai/dsh-agent'
 import type { AgentOptions } from '@deepseek-ai/dsh-agent'
@@ -62,12 +63,24 @@ export class AgentLoop extends Service {
    * Create an agent, start its loop, and register it. Returns the agent.
    * Disposed with the calling fiber.
    *
+   * The session id is per-run (`${id}-session-<uuid>`, no fixed name): once a
+   * durable persistence backend is loaded, a fixed `${id}-session` collides on
+   * the second run — the backend refuses to re-create an id whose log already
+   * exists on disk (the SessionId is the identity). A fresh id means each run
+   * is a new session.
+   *
+   * TODO(demo): each run starting a brand-new session is fine for demos but is
+   * NOT real conversation continuity. A production config-driven agent needs a
+   * deliberate resume-or-create policy (resume the prior session if one exists,
+   * else start fresh) or an explicit caller-chosen session id — revisit when the
+   * UI/ACP path owns session selection.
+   *
    * TODO(sub-agents): spawn/fork land here — accept a parent agent reference;
    * fork seeds the new Session with the parent's event log, spawn starts
    * fresh; the child is returned as a regular Agent handle.
    */
   create(id: string, options: AgentOptions = {}): LoopAgent {
-    const session = this.ctx.sessions.create(`${id}-session`)
+    const session = this.ctx.sessions.create(`${id}-session-${randomUUID()}`, { meta: {} })
     const agent = new LoopAgent(this.ctx, AgentId(id), options, session)
     // Generator effect: stop and unregister are independent disposables
     // (LIFO), so a throwing stop() cannot leak the registry entry.

packages/agent-loop/tests/config-session-id.spec.ts

@@ -0,0 +1,65 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import AgentLoop, { LoopAgent } from '@deepseek-ai/dsh-agent-loop'
+import { MockAdapter, textResponse } from './mock-adapter.ts'
+
+const dirs: string[] = []
+afterEach(async () => { for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true }) })
+
+function waitForIdle(ctx: Context, agent: LoopAgent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') { dispose(); resolve() }
+    })
+  })
+}
+
+describe('config-driven session id', () => {
+  it('config-driven create uses a fresh ${id}-session-<uuid> per run (restart-safe)', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-cfg-session-'))
+    dirs.push(root)
+    const idPattern = /^cfg-session-[0-9a-f-]{36}$/
+    // Run 1: a config agent persists a turn under a generated session id.
+    const ctx1 = new Context()
+    await ctx1.plugin(LlmService)
+    await ctx1.plugin(SessionStore)
+    await ctx1.plugin(SystemPrompt)
+    await ctx1.plugin(ToolRegistry)
+    await ctx1.plugin(AgentRegistry)
+    await ctx1.plugin(AgentLoop, { agents: [{ id: 'cfg', model: 'mock', systemPrompt: '' }] })
+    await ctx1.plugin(SessionPersistenceJsonl, { root })
+    ctx1.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg')]))
+    const a1 = ctx1.agents.get('cfg') as LoopAgent
+    expect(a1.session.id).toMatch(idPattern)
+    a1.send([{ type: 'text', text: 'q' }], { source: { kind: 'user' } })
+    await waitForIdle(ctx1, a1)
+    await ctx1.fiber.dispose()
+
+    // Run 2 over the SAME root: a fresh id means no on-disk collision (a fixed
+    // ${id}-session would crash here with "already has a persisted log").
+    const ctx2 = new Context()
+    await ctx2.plugin(LlmService)
+    await ctx2.plugin(SessionStore)
+    await ctx2.plugin(SystemPrompt)
+    await ctx2.plugin(ToolRegistry)
+    await ctx2.plugin(AgentRegistry)
+    await ctx2.plugin(AgentLoop, { agents: [{ id: 'cfg', model: 'mock', systemPrompt: '' }] })
+    await ctx2.plugin(SessionPersistenceJsonl, { root })
+    ctx2.llm.registerAdapter(['mock'], new MockAdapter([textResponse('cfg2')]))
+    const a2 = ctx2.agents.get('cfg') as LoopAgent
+    expect(a2.session.id).toMatch(idPattern)
+    expect(a2.session.id).not.toBe(a1.session.id)
+    a2.send([{ type: 'text', text: 'q2' }], { source: { kind: 'user' } })
+    await waitForIdle(ctx2, a2)
+    await ctx2.fiber.dispose()
+  })
+})