Merge remote-tracking branch 'origin/master' into codex/rfc-subagent-background-tasks

# Conflicts: # docs/config-catalog.md # docs/cordis-catalog/services.md # docs/core-data-structures/bash.md # docs/core-data-structures/core.md # docs/event-producer-consumer.md # docs/module-graph.md # docs/tool-catalog.md # examples/acp-agent/tests/snapshots/both-mode-turn/session.jsonl # examples/acp-agent/tests/snapshots/code-mode-turn/session.jsonl # examples/acp-agent/tests/snapshots/text-turn/session.jsonl # packages/README.md # packages/bash/README.md # packages/bash/bash-local/src/index.ts # packages/bash/bash/README.md # packages/bash/bash/package.json # packages/bash/bash/src/index.ts # packages/bash/bash/src/types.ts # packages/bash/bash/tests/service.spec.ts # packages/bash/bash/tsconfig.json # packages/bash/tool-bash/README.md # packages/bash/tool-bash/src/index.ts # packages/bash/tool-bash/tests/tools.spec.ts # packages/bash/tool-bash/tsconfig.json # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-core/README.md # packages/core/agent-core/package.json # packages/core/agent-core/src/index.ts # packages/core/agent-core/tests/agent-core.spec.ts # packages/core/tools/tests/gen-tool-catalog.spec.ts # packages/hooks/hook-protocol/tests/runner.spec.ts # packages/ui/acp-agent/tests/acp-agent.spec.ts # packages/ui/stdio-agent/tests/stdio-agent.spec.ts # pnpm-lock.yaml # scripts/doc-budgets.manifest.json # scripts/gen-tool-catalog.ts
2026-07-11 23:04:27 +08:00
parent b4d09d3a2d 7331720c8a
commit 740106a51a
193 changed files with 11980 additions and 803 deletions
--- a/packages/ui/stdio-agent/README.md
+++ b/packages/ui/stdio-agent/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-stdio-agent

-The **terminal stdio chat app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
+The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.

 It is the readline counterpart to [`@deepseek-ai/dsh-acp-agent`](../acp-agent/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.

@@ -11,7 +11,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | Plugin | Why it is here |
 |---|---|
 | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` and carrying its `persona` |
+| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
@@ -32,6 +32,8 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |

+Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-agent` was started. Resumed sessions keep the cwd stored in the persisted session header.
+
 ## The bin

 `dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`: the cordis Loader resolves the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages) through its internal module loader, which is only active under that flag. The `demo:echo` / `demo:repl` scripts invoke it that way.
--- a/packages/ui/stdio-agent/src/index.ts
+++ b/packages/ui/stdio-agent/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * The stdio chat app: the providerless agent spine ({@link
+ * The stdio chat app: the default agent spine ({@link
 * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal
 * chat needs — a console logger, the readline UI (the in-package `stdio-chat`
 * module), JSONL session
@@ -58,7 +58,9 @@ export const name = 'stdio-agent'
 * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
 * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
 * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
- * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner.
+ * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions
+ * keep their persisted cwd. `persistenceRoot` is the JSONL backend's directory;
+ * `welcome` is the UI banner.
 */
 export interface Config {
  /** Model name for the `main` agent (must have a registered adapter). */
@@ -73,6 +75,8 @@ export interface Config {
  persistenceRoot?: string
  /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
  welcome?: string
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  skills?: agentCore.SkillConfig
  /**
   * If set, the `main` agent RESUMES this persisted session id instead of
   * starting fresh. Sourced from an env var in the leaf `cordis.yml`
@@ -91,6 +95,7 @@ export const Config: z<Config> = z.object({
  tools: ToolRegistry.Config,
  persistenceRoot: z.string().default('./.sessions'),
  welcome: z.string().default('ready.'),
+  skills: agentCore.SkillConfigSchema,
  resumeSessionId: z.string(),
 })

@@ -110,8 +115,10 @@ export function apply(ctx: Context, config: Config): void {
    agents: [{
      id: AgentId('main'),
      model: config.model,
+      cwd: process.cwd(),
      ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
    }],
+    ...config.skills !== undefined ? { skills: config.skills } : {},
  })
  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
  ctx.plugin(UserInteractionService)
--- a/packages/ui/stdio-agent/tests/built-bin.e2e.ts
+++ b/packages/ui/stdio-agent/tests/built-bin.e2e.ts
@@ -92,7 +92,7 @@ async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promi
    '  name: \'@deepseek-ai/dsh-stdio-agent\'',
    '  config:',
    '    model: mock-echo',
-    '    systemPrompt: \'demo\'',
+    '    persona: \'demo\'',
    `    welcome: '${welcome}'`,
    ...disabledBrokenEntry
      ? ['- id: off', '  name: \'./src/does-not-exist.ts\'', '  disabled: true']
@@ -111,7 +111,7 @@ function runBuiltBin(cwd: string, configArg: string, line: string): Promise<{ st
    const child = spawn(process.execPath, ['--expose-internals', stdioBin, configArg], {
      cwd,
      // Mock model: never calls the network, so no key needed.
-      env: { ...process.env },
+      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
      stdio: ['pipe', 'pipe', 'pipe'],
    })
    let stdout = ''
--- a/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
+++ b/packages/ui/stdio-agent/tests/stdio-agent.spec.ts
@@ -1,7 +1,11 @@
 import { describe, it, expect } from 'vitest'
+import { mkdtemp } from 'node:fs/promises'
+import { join } from 'node:path'
+import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { AgentId } from '@deepseek-ai/dsh-agent'
+import type { Message } from '@deepseek-ai/dsh-llm'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as stdioAgent from '../src/index.ts'

@@ -30,9 +34,47 @@ async function mount(config: stdioAgent.Config): Promise<Context> {
  return ctx
 }

+async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<stdioAgent.Config['skills']>> {
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-skills-'))
+  return {
+    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
+    ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {},
+  }
+}
+
+async function composePrefix(ctx: Context): Promise<Message[]> {
+  const empty: Message[] = []
+  return await ctx.waterfall(
+    'agent/session-prefix', { session: { header: { cwd: '/tmp' } } } as never,
+    empty, new AbortController().signal, () => Promise.resolve(empty),
+  )
+}
+
+async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
+  const oldDshHome = process.env.DSH_HOME
+  const oldAgentsHome = process.env.DSH_AGENTS_HOME
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-default-skills-'))
+  process.env.DSH_HOME = join(home, '.dsh')
+  process.env.DSH_AGENTS_HOME = join(home, '.agents')
+  try {
+    return await run()
+  } finally {
+    if (oldDshHome === undefined) {
+      delete process.env.DSH_HOME
+    } else {
+      process.env.DSH_HOME = oldDshHome
+    }
+    if (oldAgentsHome === undefined) {
+      delete process.env.DSH_AGENTS_HOME
+    } else {
+      process.env.DSH_AGENTS_HOME = oldAgentsHome
+    }
+  }
+}
+
 describe('dsh-stdio-agent app', () => {
  it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec' })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec', skills: await isolatedSkillsConfig() })
    // The spine services (brought up by the agent-core bundle) are all present.
    expect(ctx.get('agents')).toBeDefined()
    expect(ctx.get('agentLoop')).toBeDefined()
@@ -40,7 +82,9 @@ describe('dsh-stdio-agent app', () => {
    expect(ctx.get('userInteraction')).toBeDefined()
    expect(ctx.get('tools')?.get('ask_user_question')).toBeDefined()
    // The pre-created `main` agent the UI drives.
-    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    const agent = ctx.get('agents')?.get(AgentId('main'))
+    expect(agent).toBeDefined()
+    expect(agent?.session.header.cwd).toBe(process.cwd())
    await ctx.fiber.dispose()
  })

@@ -51,13 +95,24 @@ describe('dsh-stdio-agent app', () => {
    // schema-bypassing direct-mount caller.
    const ctx = new Context()
    // No persona: covers the omitted-persona forwarding branch too.
-    stdioAgent.apply(ctx, { model: 'mock' })
+    stdioAgent.apply(ctx, { model: 'mock', skills: await isolatedSkillsConfig() })
    await new Promise(resolve => setTimeout(resolve, 80))
    expect(ctx.get('sessionPersistence')).toBeDefined()
    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
    await ctx.fiber.dispose()
  })

+  it('uses default skill config when apply is called directly without skills', async () => {
+    await withIsolatedSkillHomes(async () => {
+      const ctx = new Context()
+      stdioAgent.apply(ctx, { model: 'mock' })
+      await new Promise(resolve => setTimeout(resolve, 80))
+      expect(ctx.skills).toBeDefined()
+      expect(await ctx.skills.list()).toEqual([])
+      await ctx.fiber.dispose()
+    })
+  })
+
  it('forwards resumeSessionId onto the pre-created agent when set', async () => {
    // A resume id defers agent creation until persistence loads; with no backing
    // session the resume is contained + logged, so no `main` agent registers —
@@ -67,11 +122,19 @@ describe('dsh-stdio-agent app', () => {
      persona: 'hi',
      persistenceRoot: '/tmp/dsh-stdio-agent-spec-resume',
      resumeSessionId: 'no-such-session',
+      skills: await isolatedSkillsConfig(),
    })
    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
    await ctx.fiber.dispose()
  })

+  it('forwards skill config into agent-core', async () => {
+    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6) })
+    ctx.skills.register({ name: 'stdio-skill', description: 'Stdio skill', source: 'runtime', content: 'body' })
+    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `stdio-skill`: Std...')
+    await ctx.fiber.dispose()
+  })
+
  it('exposes its name and Config schema', () => {
    expect(stdioAgent.name).toBe('stdio-agent')
    expect(stdioAgent.Config).toBeDefined()
@@ -94,10 +157,7 @@ describe('dsh-stdio-agent app', () => {
      })
    }
    const assembly = await ctx.get('systemPrompt')!.assemble()
-    // The rest-slot is lexicographic: the app's ask_user_question and the
-    // bundle's own task control tools (neither needs an executor, unlike the
-    // pending bash tool) follow alpha.
-    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question', 'task_kill', 'task_list', 'task_output'])
+    expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question', 'skill', 'task_kill', 'task_list', 'task_output'])
    await ctx.fiber.dispose()
  })