Merge remote-tracking branch 'origin/master' into feat/send-unify

# Conflicts: # 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/pty/pty-local/tests/index.spec.ts # packages/session-query/session-query/tests/tracing.spec.ts
2026-07-23 22:41:45 +08:00
parent 1f9a3e1bee a08a008fad
commit d5f88f1221
333 changed files with 10751 additions and 907 deletions
--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -15,7 +15,7 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it
 | `@deepseek-ai/dsh-command-goal` | the discoverable direct `/goal` producer; the app enables the spine's persisted-goal stack with it |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
-| `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | exact current-surface reads and bounded `dsh-session:` snapshots |
+| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | combined exact/FTS session queries and bounded `dsh-session:` snapshots |
 | `@deepseek-ai/dsh-session-checkpoint-policy` | semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
 | `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool |
 | ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately |
@@ -43,7 +43,7 @@ The app owns this cluster through one ordered Cordis effect. Teardown drains the
 | `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
 | `goals` | owner defaults | persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
 | `llmRetry` | owner defaults | bounded transient model-request retry policy routed through `dsh-agent-spine-demo` |
-| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
+| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory and the parent of the derived `session-query.db` index |
 | `packChunks` | `false` | write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`) |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
 | `sessionReferences` | service defaults | cross-session candidate and snapshot limits routed to `dsh-session-reference` |
@@ -58,7 +58,7 @@ The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the
 - honors `DSH_SNAPSHOT=replay` by booting the sibling `cordis.snapshot.yml` (the keyless replay tree, `llm-replay` in place of `llm-deepseek`);
 - in a snapshot run, disposes the context on stdin EOF so the session log is fully flushed before exit.

-Run it under `node --expose-internals`, or Loader's optional `node-addon-require-builtin` fallback is required, so the cordis Loader can resolve the config's bare plugin specifiers through its internal module loader. (`demo:acp` runs under tsx, whose tsconfig `paths` map resolves them instead.)
+The repository installs Loader's optional `node-addon-require-builtin` peer, so the built bin resolves bare plugin specifiers through the internal module loader under plain Node. (`demo:acp` runs under tsx, whose tsconfig `paths` map resolves them instead.)

 All diagnostics go to **stderr** — stdout is the protocol.

--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -46,6 +46,7 @@
    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
    "@deepseek-ai/dsh-session-reference": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
@@ -66,6 +67,7 @@
    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
    "@deepseek-ai/dsh-session-reference": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -12,6 +12,7 @@
 */

 import type { Context } from 'cordis'
+import { join } from 'node:path'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
 import CommandService from '@deepseek-ai/dsh-commands'
@@ -25,7 +26,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'

 export const name = 'acp-demo'
@@ -57,7 +58,7 @@ export interface Config {
  dshHome?: string
  /** Fallback session-title limits forwarded through agent-spine-demo. */
  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** Write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`). Defaults to `false`. */
  packChunks?: boolean
@@ -110,14 +111,16 @@ export const Config: z<Config> = z.object({
 /**
 * Compose the spine with the ACP front door. The agent-spine-demo bundle pre-creates
 * NO agents (its `agents` list defaults to `[]`) and carries the deployment
- * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
- * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
- * from the provider/model pair. The composite effect unloads in reverse order,
- * keeping checkpoint and persistence listeners attached until ACP agents have
- * flushed their closing events. No logger, no `hmr` — stdout stays pure.
+ * `persona`; the JSONL backend and derived query index persist under
+ * `persistenceRoot`; the ACP bridge owns stdout for JSON-RPC and creates one
+ * agent per `session/new` from the provider/model pair. The composite effect
+ * unloads in reverse order, keeping checkpoint and persistence listeners
+ * attached until ACP agents have flushed their closing events. No logger, no
+ * `hmr` — stdout stays pure.
 */
 export function apply(ctx: Context, config: Config): void {
  const goals = config.goals ?? {}
+  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
  ctx.effect(function* () {
    yield ctx.plugin(CommandService).dispose
    if (goals !== false) yield ctx.plugin(commandGoal).dispose
@@ -127,13 +130,13 @@ export function apply(ctx: Context, config: Config): void {
    // persistence passthroughs rather than sharing a facade with stdio-demo.
    /* jscpd:ignore-start */
    yield ctx.plugin(SessionPersistenceJsonl, {
-      root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
+      root: persistenceRoot,
      ...config.packChunks !== undefined ? { packChunks: config.packChunks } : {},
      ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
    }).dispose
    /* jscpd:ignore-end */
    yield ctx.plugin(sessionCheckpointPolicy).dispose
-    yield ctx.plugin(SessionQueryService).dispose
+    yield ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') }).dispose
    yield ctx.plugin(SessionReferenceService, config.sessionReferences ?? {}).dispose
    yield ctx.plugin(acp, { provider: config.provider, model: config.model }).dispose
  }, 'acp-demo.composition')
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -23,8 +23,7 @@ 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
 * complete a mock-backed turn. This catches built-only settle races, stdout protocol leaks, and
- * published persistence behavior that the tsx source-path smoke cannot. It skips before build;
- * `--expose-internals` enables Cordis bare-plugin loading.
+ * published persistence behavior that the tsx source-path smoke cannot. It skips before build.
 */

 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
@@ -37,7 +36,8 @@ 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',
-  'session-query/session-query', 'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
+  'session-query/session-query', 'session-query/session-query-sqlite',
+  'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
@@ -133,7 +133,7 @@ afterEach(async () => {
 describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, no tsx)', () => {
  it('boots the published bin, completes a turn, and writes default Zstandard persistence', async () => {
    consumer = await makeConsumer()
-    child = spawn(process.execPath, ['--expose-internals', acpBin, '--config', './cordis.yml'], {
+    child = spawn(process.execPath, [acpBin, '--config', './cordis.yml'], {
      cwd: consumer,
      env: {
        ...process.env,
@@ -226,7 +226,7 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, n
 /** Spawn the built acp bin against `configArg` and resolve with its exit code + stderr. */
 function runBinExpectingExit(configArg: string, cwd: string = tmpdir()): Promise<{ code: number; stderr: string }> {
  return new Promise((resolve, reject) => {
-    const proc = spawn(process.execPath, ['--expose-internals', acpBin, '--config', configArg], {
+    const proc = spawn(process.execPath, [acpBin, '--config', configArg], {
      cwd,
      env: {
        ...process.env,
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -26,6 +26,9 @@
    {
      "path": "../../session-query/session-query"
    },
+    {
+      "path": "../../session-query/session-query-sqlite"
+    },
    {
      "path": "../../context/session-reference"
    },
--- a/packages/examples/cli-demo/README.md
+++ b/packages/examples/cli-demo/README.md
@@ -38,7 +38,7 @@ The root headless-agent example supplies its leaf:
 pnpm run demo:headless "inspect the failing test and fix it"
 ```

-Loader configs with bare package specifiers require `node --expose-internals` or the Loader's optional native fallback. The root command supplies the Node flag.
+Loader configs resolve bare package specifiers through the optional native helper installed by the repository, so the root command needs no special Node flags.

 ### Output formats

--- a/packages/examples/cli-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts
@@ -116,7 +116,7 @@ interface BinResult {

 function runBuiltBin(cwd: string, args: readonly string[], interrupt?: NodeJS.Signals): Promise<BinResult> {
  return new Promise((resolveResult, reject) => {
-    const child = spawn(process.execPath, ['--expose-internals', cliBin, ...args], {
+    const child = spawn(process.execPath, [cliBin, ...args], {
      cwd,
      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
      stdio: ['ignore', 'pipe', 'pipe'],
--- a/packages/examples/tui-demo/README.md
+++ b/packages/examples/tui-demo/README.md
@@ -13,7 +13,7 @@ Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and
 | `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
-| `@deepseek-ai/dsh-session-query` + `@deepseek-ai/dsh-session-reference` | Exact current-surface reads and bounded `@session` snapshots consumed by the TUI |
+| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | Combined exact/FTS session queries and bounded `@session` snapshots consumed by the TUI |
 | `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
 | `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
 | `@deepseek-ai/dsh-tool-ask-user` | Model-facing `ask_user_question` tool |
@@ -37,7 +37,7 @@ Swappable LLM, bash, filesystem, and other capability providers remain in the le
 | `toolTasks` | owner defaults | Background-task control-tool config, or `false` |
 | `goals` | owner defaults | Persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
 | `workspaceContext` | required | Workspace-instruction config, or `false` |
-| `persistenceRoot` | `./.sessions` | JSONL persistence root |
+| `persistenceRoot` | `./.sessions` | JSONL persistence root and parent of the derived `session-query.db` index |
 | `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
 | `sessionReferences` | service defaults | Cross-session candidate and snapshot limits routed to `dsh-session-reference` |
 | `welcome` | `ready.` | TUI subtitle |
@@ -48,7 +48,7 @@ Fresh runs mint a `main-session-<uuid>` session id and pass it to both the TUI a

 ## The bin

-`dsh-tui-demo [path-to-cordis.yml]` defaults to `./cordis.yml`, loads the optional cwd `.env`, boots the Cordis Loader, and waits for the full plugin tree. Bare package specifiers require `node --expose-internals` or the Loader's optional native fallback; the repository scripts use `--expose-internals`.
+`dsh-tui-demo [path-to-cordis.yml]` defaults to `./cordis.yml`, loads the optional cwd `.env`, boots the Cordis Loader, and waits for the full plugin tree. The repository installs Loader's optional native helper, so bare package specifiers resolve under plain Node.

 ## Example leaf

--- a/packages/examples/tui-demo/package.json
+++ b/packages/examples/tui-demo/package.json
@@ -48,6 +48,7 @@
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
    "@deepseek-ai/dsh-session-query": "^0.0.1",
+    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
    "@deepseek-ai/dsh-session-reference": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-tui": "^0.0.1",
@@ -72,6 +73,7 @@
    "@deepseek-ai/dsh-session": "workspace:^",
    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
    "@deepseek-ai/dsh-session-reference": "workspace:^",
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
--- a/packages/examples/tui-demo/src/index.ts
+++ b/packages/examples/tui-demo/src/index.ts
@@ -10,6 +10,7 @@

 import type { Context } from 'cordis'
 import { randomUUID } from 'node:crypto'
+import { join } from 'node:path'
 import z from 'schemastery'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
@@ -23,7 +24,7 @@ import SessionPersistenceJsonl, {
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQueryService from '@deepseek-ai/dsh-session-query'
+import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
 import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as uiTui from '@deepseek-ai/dsh-tui'
@@ -52,7 +53,7 @@ export interface Config {
  dshHome?: string
  /** Fallback session-title limits forwarded through agent-spine-demo. */
  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
  persistenceCompression?: JsonlCompression
@@ -119,14 +120,15 @@ export function composeTuiApp(ctx: Context, config: Config): void {
  const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId
  const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`)
  const goals = config.goals ?? {}
+  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
  ctx.plugin(CommandService)
  if (goals !== false) ctx.plugin(commandGoal)
  ctx.plugin(SessionPersistenceJsonl, {
-    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
+    root: persistenceRoot,
    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
  })
  ctx.plugin(sessionCheckpointPolicy)
-  ctx.plugin(SessionQueryService)
+  ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
  ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
  ctx.plugin(UserInteractionService)
  ctx.plugin(uiTui, {
--- a/packages/examples/tui-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/tui-demo/tests/built-bin.e2e.ts
@@ -54,9 +54,9 @@ async function makeConsumer(): Promise<string> {
 /** Run the built bin in `cwd` with PIPED stdio; resolve with output + exit code. */
 function runBuiltBin(cwd: string): Promise<{ stdout: string; code: number; stderr: string }> {
  return new Promise((resolve, reject) => {
-    // NO tsx — this is the published `node lib/bin.js` path (`--expose-internals`
-    // matches the demo command; the guard fires before the Loader needs it).
-    const child = spawn(process.execPath, ['--expose-internals', tuiBin, './cordis.yml'], {
+    // NO tsx — this is the published `node lib/bin.js` path; the guard fires
+    // before the Loader resolves the config tree.
+    const child = spawn(process.execPath, [tuiBin, './cordis.yml'], {
      cwd,
      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
      stdio: ['pipe', 'pipe', 'pipe'],
--- a/packages/examples/tui-demo/tests/tui-agent.spec.ts
+++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts
@@ -51,7 +51,7 @@ describe('dsh-tui-demo app', () => {
      'command-goal',
      'SessionPersistenceJsonl',
      'session-checkpoint-policy',
-      'SessionQueryService',
+      'SessionQuerySqlite',
      'SessionReferenceService',
      'UserInteractionService',
      'ui-tui',
@@ -60,6 +60,7 @@ describe('dsh-tui-demo app', () => {
    ])
    expect(calls[0]?.config).toBeUndefined()
    expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
+    expect(calls[4]?.config).toEqual({ path: '/tmp/tui-sessions/session-query.db' })
    expect(calls[5]?.config).toEqual({
      maxReferences: 2,
      candidateLimit: 7,
--- a/packages/examples/tui-demo/tsconfig.json
+++ b/packages/examples/tui-demo/tsconfig.json
@@ -29,6 +29,9 @@
    {
      "path": "../../session-query/session-query"
    },
+    {
+      "path": "../../session-query/session-query-sqlite"
+    },
    {
      "path": "../../context/session-reference"
    },