Merge branch 'codex/tool-json-schema-dsl' into codex/canonical-tool-output

# Conflicts:
#	docs/config-catalog.md
#	docs/persistence-catalog.md
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
#	examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl
#	packages/cordis/tool-cordis/src/api-catalog.ts
#	packages/core/agent-loop/tests/contract-regressions.spec.ts
#	packages/ui/acp/src/index.ts
#	packages/ui/tui/src/index.ts

packages/examples/acp-demo/tests/acp-agent.spec.ts

@@ -5,6 +5,7 @@ import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import type { Message } from '@deepseek-ai/dsh-llm'
 import * as acpAgent from '../src/index.ts'
@@ -83,18 +84,26 @@ describe('dsh-acp-demo composition', () => {
       persona: 'hi',
       persistenceRoot: '/tmp/dsh-acp-demo-test',
       persistenceCompression: 'none',
+      sessionReferences: { candidateLimit: 1 },
       skills: await isolatedSkillsConfig(),
       workspaceContext: false,
     })
     expect(ctx.get('agents')).toBeDefined()
     expect(ctx.get('sessions')).toBeDefined()
     expect(ctx.get('sessionPersistence')).toBeDefined()
+    expect(ctx.get('sessionQuery')).toBeDefined()
+    expect(ctx.get('sessionReferences')).toBeDefined()
     expect((ctx.get('sessionPersistence') as unknown as { config: { compression?: string } }).config.compression).toBe('none')
     expect(ctx.get('agentLoop')).toBeDefined()
     expect(ctx.get('userInteraction')).toBeDefined()
     expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined()
     expect(ctx.get('goals')).toBeDefined()
     expect(ctx.get('tools')?.get('get_goal')).toBeDefined()
+    const target = ctx.sessions.create(SessionId('candidate-target'))
+    ctx.sessions.create(SessionId('candidate-one'))
+    ctx.sessions.create(SessionId('candidate-two'))
+    await expect(ctx.sessionReferences.listCandidates({ id: target.id, session: target } as Agent))
+      .resolves.toHaveLength(1)
     // No pre-created agents — ACP session/new creates them on demand.
     expect(ctx.get('agents')!.list()).toHaveLength(0)
     await ctx.fiber.dispose()

packages/examples/acp-demo/tests/built-bin.e2e.ts

@@ -18,6 +18,7 @@ import { Readable, Writable } from 'node:stream'
 import { promisify } from 'node:util'
 import { zstdDecompress } from 'node:zlib'
 import { afterEach, describe, expect, it } from 'vitest'
+import { ACP_SESSION_REFERENCE_META_KEY } from '@deepseek-ai/dsh-acp'
 
 /**
  * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer and
@@ -36,7 +37,7 @@ const dshPackages = [
   'bash/bash-local', 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence',
   'session-persistence/session-checkpoint-policy', 'session-persistence/session-persistence-jsonl',
-  'ui/acp', 'examples/acp-demo', 'util/paths',
+  'session-query/session-query', 'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
   'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
@@ -166,10 +167,30 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, n
     // regression would exit before answering); loadSession proves the real app
     // mounted, not a collapsed export shape.
     expect(init.agentCapabilities?.loadSession).toBe(true)
-    const { sessionId } = await client.newSession({ cwd: consumer, mcpServers: [] })
+    expect(init.agentCapabilities?.sessionCapabilities?.list).toEqual({})
+    const sessionCwd = consumer
+    const { sessionId } = await client.newSession({ cwd: sessionCwd, mcpServers: [] })
     const result = await client.prompt({ sessionId, prompt: [{ type: 'text', text: 'reply' }] })
     expect(result.stopReason).toBe('end_turn')
-    const sessionsRoot = join(consumer, '.sessions')
+    await expect.poll(async () => {
+      return (await client.listSessions({ cwd: sessionCwd })).sessions.find(candidate => candidate.sessionId === sessionId)
+    }).toMatchObject({
+      sessionId,
+      cwd: sessionCwd,
+      title: 'reply',
+    })
+    const listed = await client.listSessions({ cwd: sessionCwd })
+    const reference = listed.sessions.find(candidate => candidate.sessionId === sessionId)
+      ?._meta?.[ACP_SESSION_REFERENCE_META_KEY]
+    expect(reference).toBeTypeOf('object')
+    expect(reference).not.toBeNull()
+    expect(reference).toHaveProperty('uri')
+    if (typeof reference !== 'object' || reference === null || !('uri' in reference)) {
+      throw new Error('expected session reference metadata')
+    }
+    expect(reference.uri).toBeTypeOf('string')
+    expect(reference.uri).toMatch(/^dsh-session:[A-Za-z0-9_-]+$/u)
+    const sessionsRoot = join(sessionCwd, '.sessions')
     let log: string | undefined
     await expect.poll(async () => {
       log = (await readdir(sessionsRoot, { recursive: true })).find(file => file.endsWith('.jsonl.zstd'))