Merge remote-tracking branch 'origin/master' into codex/truncated-design

# Conflicts:
#	docs/capability-seams.md
#	docs/config-catalog.md
#	docs/cordis-catalog/services.md
#	docs/core-data-structures/core.md
#	docs/event-producer-consumer.md
#	docs/module-graph.md
#	docs/rfc/INDEX.md
#	docs/tool-catalog.md
#	examples/acp-agent/README.md
#	packages/README.md
#	packages/bash/bash/README.md
#	packages/core/tools/tests/gen-tool-catalog.spec.ts
#	packages/support/acp-snapshot/src/harness.ts
#	pnpm-lock.yaml
#	scripts/gen-doc-graphs.ts
#	scripts/gen-tool-catalog.ts
#	scripts/type-equiv.manifest.json
This commit is contained in:
Dudu-0223
2026-07-13 09:49:46 +08:00
424 changed files with 35979 additions and 6313 deletions

View File

@@ -109,7 +109,7 @@ async function makeConsumer(
' name: \'@deepseek-ai/dsh-stdio-agent\'',
' config:',
' model: mock-echo',
' systemPrompt: \'demo\'',
' persona: \'demo\'',
` welcome: '${welcome}'`,
...extraEntries,
...disabledBrokenEntry
@@ -129,7 +129,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 = ''

View File

@@ -19,6 +19,7 @@ function fakeContext(): Context {
// The UI seeds its label map from the registry at install; this suite only
// exercises readline terminal-mode selection, so an empty roster suffices.
agents: { list: vi.fn(() => []) },
userInteraction: { registerProvider: vi.fn(() => vi.fn()) },
} as unknown as Context
}

View File

@@ -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,15 +34,57 @@ 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()
expect(ctx.get('sessionPersistence')).toBeDefined()
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()
})
@@ -49,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 —
@@ -65,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()
@@ -92,7 +157,7 @@ describe('dsh-stdio-agent app', () => {
})
}
const assembly = await ctx.get('systemPrompt')!.assemble()
expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha'])
expect(assembly.tools.map(tool => tool.name)).toEqual(['zulu', 'alpha', 'ask_user_question', 'skill'])
await ctx.fiber.dispose()
})

View File

@@ -1,10 +1,11 @@
import { Readable } from 'node:stream'
import { Readable, Writable } from 'node:stream'
import { describe, expect, it, vi } from 'vitest'
import { Context } from 'cordis'
import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
import AgentRegistry from '@deepseek-ai/dsh-agent'
import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
import { createStdioChat, type Config, type StdioRuntime } from '../src/stdio-chat.ts'
/**
@@ -79,10 +80,11 @@ const CONFIG: Config = { welcome: 'hi there', agent: 'main' }
async function setup(config: Config = CONFIG, runtimeOver: Partial<StdioRuntime> = {}) {
const ctx = new Context()
await ctx.plugin(AgentRegistry)
await ctx.plugin(UserInteractionService)
const { runtime, input, out, exit } = makeRuntime(runtimeOver)
const fiber = await ctx.plugin(Object.assign((inner: Context) => {
createStdioChat(inner, config, runtime)
}, { inject: ['agents'] }))
}, { inject: ['agents', 'userInteraction'] }))
return { ctx, fiber, input, out, exit }
}
@@ -105,6 +107,30 @@ describe('createStdioChat rendering', () => {
// And it drives the default agent id 'main'.
})
it('detects readline terminal mode from both stream TTY flags', async () => {
for (const [inputTTY, outputTTY] of [[true, false], [true, true]] as const) {
const ctx = new Context()
await ctx.plugin(AgentRegistry)
await ctx.plugin(UserInteractionService)
let text = ''
const output = new Writable({
write(chunk, _encoding, callback) {
text += String(chunk)
callback()
},
}) as Writable & { isTTY?: boolean }
const { runtime } = makeRuntime({ output })
;(runtime.input as Readable & { isTTY?: boolean }).isTTY = inputTTY
output.isTTY = outputTTY
const fiber = await ctx.plugin(Object.assign((inner: Context) => {
createStdioChat(inner, CONFIG, runtime)
}, { inject: ['agents', 'userInteraction'] }))
expect(text).toContain('hi there')
await fiber.dispose()
}
})
it('renders text-delta chunks verbatim', async () => {
const { ctx, out } = await setup()
ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' }))
@@ -160,12 +186,13 @@ describe('createStdioChat rendering', () => {
// of the raw session id.
const ctx = new Context()
await ctx.plugin(AgentRegistry)
await ctx.plugin(UserInteractionService)
const agent = makeAgent('main')
ctx.agents.register(agent) // registered BEFORE the UI plugin below
const { runtime, out } = makeRuntime()
await ctx.plugin(Object.assign((inner: Context) => {
createStdioChat(inner, CONFIG, runtime)
}, { inject: ['agents'] }))
}, { inject: ['agents', 'userInteraction'] }))
ctx.emit('session/event', makeSession('main'), {
type: 'turn/start', seq: 1, time: 0, data: { turn: 5, trigger: { kind: 'message' } },
} as SessionEvent)
@@ -264,6 +291,347 @@ describe('createStdioChat rendering', () => {
})
describe('createStdioChat input', () => {
it('answers a pending user question instead of sending the line to the agent', async () => {
const { ctx, input, out } = await setup()
const agent = makeAgent('main', 'idle')
ctx.agents.register(agent)
const answer = ctx.userInteraction.ask({
questions: [{
id: 'confirm',
header: 'Confirm',
question: 'Proceed with the edit?',
options: [{ label: 'Yes', description: 'Apply the edit now.' }],
}],
})
await new Promise(r => setImmediate(r))
input.feed('Use a smaller change')
await expect(answer).resolves.toEqual({ answers: [{ id: 'confirm', selected: [], custom: 'Use a smaller change' }] })
expect(agent.sent).toEqual([])
expect(out.text()).toContain('[Confirm] Proceed with the edit?')
expect(out.text()).toContain('1. Yes')
expect(out.text()).toContain('Apply the edit now.')
})
it('answers a pending user question by numeric option selection', async () => {
const { ctx, input } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'mode',
question: 'Which mode?',
options: [
{ label: 'Safe' },
{ label: 'Fast' },
],
}],
})
await new Promise(r => setImmediate(r))
input.feed('2')
await expect(answer).resolves.toEqual({
answers: [{ id: 'mode', selected: ['Fast'] }],
})
})
it('renders options in input order and selects by displayed number', async () => {
const { ctx, input, out } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'topic',
question: 'Which topic?',
options: [
{ label: 'Hobbies' },
{ label: 'Work', description: 'Questions about current projects.' },
{ label: 'Casual', description: 'Easy conversation.' },
],
}],
})
await new Promise(r => setImmediate(r))
expect(out.text()).toContain([
'Which topic?',
' 1. Hobbies',
' 2. Work',
' Questions about current projects.',
' 3. Casual',
' Easy conversation.',
].join('\n'))
input.feed('3')
await expect(answer).resolves.toEqual({
answers: [{ id: 'topic', selected: ['Casual'] }],
})
})
it('answers a multi-select question with multiple numeric selections', async () => {
const { ctx, input } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'targets',
question: 'What should I update?',
options: [{ label: 'Tests' }, { label: 'Docs' }, { label: 'Code' }],
multiSelect: true,
}],
})
await new Promise(r => setImmediate(r))
input.feed('1 1, 3')
await expect(answer).resolves.toEqual({
answers: [{ id: 'targets', selected: ['Tests', 'Code'] }],
})
})
it('accepts non-numeric multi-select input as a custom answer', async () => {
const { ctx, input } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'targets',
question: 'What should I update?',
options: [{ label: 'Tests' }, { label: 'Docs' }],
multiSelect: true,
}],
})
await new Promise(r => setImmediate(r))
input.feed('the release notes')
await expect(answer).resolves.toEqual({
answers: [{ id: 'targets', selected: [], custom: 'the release notes' }],
})
})
it('asks every question in a batch and returns answers by id', async () => {
const { ctx, input, out } = await setup()
const answer = ctx.userInteraction.ask({
questions: [
{ id: 'language', question: 'Which language?', options: [{ label: 'Python' }, { label: 'TypeScript' }] },
{ id: 'note', question: 'Any note?' },
],
})
await new Promise(r => setImmediate(r))
input.feed('2')
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('\nAny note?\n')
input.feed('ship today')
await expect(answer).resolves.toEqual({
answers: [
{ id: 'language', selected: ['TypeScript'] },
{ id: 'note', selected: [], custom: 'ship today' },
],
})
})
it('re-prompts when option input is invalid', async () => {
const { ctx, input, out } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'mode',
question: 'Which mode?',
options: [{ label: 'Safe' }],
multiSelect: true,
}],
})
await new Promise(r => setImmediate(r))
input.feed('2')
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.')
input.feed('1')
await expect(answer).resolves.toEqual({
answers: [{ id: 'mode', selected: ['Safe'] }],
})
})
it('re-prompts when single-select option input is out of range', async () => {
const { ctx, input, out } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'mode',
question: 'Which mode?',
options: [{ label: 'Safe' }],
}],
})
await new Promise(r => setImmediate(r))
input.feed('2')
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.')
input.feed('1')
await expect(answer).resolves.toEqual({
answers: [{ id: 'mode', selected: ['Safe'] }],
})
})
it('re-prompts when multi-select input contains no option numbers', async () => {
const { ctx, input, out } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'mode',
question: 'Which mode?',
options: [{ label: 'Safe' }],
multiSelect: true,
}],
})
await new Promise(r => setImmediate(r))
input.feed(',')
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('Please enter one of the option numbers (comma or space separated) or a custom answer.')
input.feed('1')
await expect(answer).resolves.toEqual({
answers: [{ id: 'mode', selected: ['Safe'] }],
})
})
it('re-prompts when an option question receives an empty answer', async () => {
const { ctx, input, out } = await setup()
const answer = ctx.userInteraction.ask({
questions: [{
id: 'mode',
question: 'Which mode?',
options: [{ label: 'Safe' }],
}],
})
await new Promise(r => setImmediate(r))
input.feed('')
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('Please enter one of the option numbers or a custom answer.')
input.feed('1')
await expect(answer).resolves.toEqual({
answers: [{ id: 'mode', selected: ['Safe'] }],
})
})
it('re-prompts when a question receives an empty answer', async () => {
const { ctx, input, out } = await setup()
const answer = ctx.userInteraction.ask({ questions: [{ id: 'path', question: 'What should I use?' }] })
await new Promise(r => setImmediate(r))
input.feed('')
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('Please enter an answer.')
input.feed('Use defaults')
await expect(answer).resolves.toEqual({ answers: [{ id: 'path', selected: [], custom: 'Use defaults' }] })
})
it('rejects an active question when its signal aborts', async () => {
const { ctx } = await setup()
const controller = new AbortController()
const answer = ctx.userInteraction.ask({ questions: [{ id: 'continue', question: 'Continue?' }], signal: controller.signal })
const rejected = expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
await new Promise(r => setImmediate(r))
controller.abort()
await rejected
})
it('continues to the next queued question when the active question aborts', async () => {
const { ctx, input, out } = await setup()
const controller = new AbortController()
const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }], signal: controller.signal })
const firstRejected = expect(first).rejects.toMatchObject({ code: 'ASK_ABORTED' })
const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }] })
await new Promise(r => setImmediate(r))
controller.abort()
await firstRejected
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('\nSecond?\n')
input.feed('second answer')
await expect(second).resolves.toEqual({ answers: [{ id: 'second', selected: [], custom: 'second answer' }] })
})
it('skips a queued question whose signal aborted before it became active', async () => {
const { ctx, input, out } = await setup()
const controller = new AbortController()
const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] })
const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal })
await new Promise(r => setImmediate(r))
controller.abort()
await expect(Promise.race([
second.then(
() => 'resolved',
(error: unknown) => (error as { code?: string }).code,
),
new Promise<string>((resolve) => { setImmediate(() => { resolve('pending') }) }),
])).resolves.toBe('ASK_ABORTED')
expect(out.text()).not.toContain('\nSecond?\n')
input.feed('first answer')
await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] })
})
it('removes an aborted queued question without promoting later queued work early', async () => {
const { ctx, input, out } = await setup()
const controller = new AbortController()
const first = ctx.userInteraction.ask({ questions: [{ id: 'first', question: 'First?' }] })
const second = ctx.userInteraction.ask({ questions: [{ id: 'second', question: 'Second?' }], signal: controller.signal })
const third = ctx.userInteraction.ask({ questions: [{ id: 'third', question: 'Third?' }] })
await new Promise(r => setImmediate(r))
controller.abort()
await expect(second).rejects.toMatchObject({ code: 'ASK_ABORTED' })
expect(out.text()).toContain('\nFirst?\n')
expect(out.text()).not.toContain('\nSecond?\n')
expect(out.text()).not.toContain('\nThird?\n')
input.feed('first answer')
await new Promise(r => setImmediate(r))
expect(out.text()).toContain('\nThird?\n')
input.feed('third answer')
await expect(first).resolves.toEqual({ answers: [{ id: 'first', selected: [], custom: 'first answer' }] })
await expect(third).resolves.toEqual({ answers: [{ id: 'third', selected: [], custom: 'third answer' }] })
})
it('rejects active and queued questions when the UI is disposed', async () => {
const { ctx, fiber } = await setup()
const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] })
const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] })
const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
await new Promise(r => setImmediate(r))
await fiber.dispose()
await activeRejected
await queuedRejected
})
it('rejects active and queued questions when stdin closes before the user answers', async () => {
const { ctx, input, exit } = await setup()
const active = ctx.userInteraction.ask({ questions: [{ id: 'active', question: 'Active?' }] })
const queued = ctx.userInteraction.ask({ questions: [{ id: 'queued', question: 'Queued?' }] })
const activeRejected = expect(active).rejects.toMatchObject({ code: 'ASK_ABORTED' })
const queuedRejected = expect(queued).rejects.toMatchObject({ code: 'ASK_ABORTED' })
await new Promise(r => setImmediate(r))
input.finish()
await new Promise(r => setImmediate(r))
await activeRejected
await queuedRejected
expect(exit).not.toHaveBeenCalled()
})
it('rejects new questions immediately after stdin has closed', async () => {
const { ctx, input, out } = await setup()
input.finish()
await new Promise(r => setImmediate(r))
const before = out.text()
const answer = ctx.userInteraction.ask({ questions: [{ id: 'late', question: 'Too late?' }] })
await expect(answer).rejects.toMatchObject({ code: 'ASK_ABORTED' })
expect(out.text()).toBe(before)
})
it('sends a typed line to an idle agent', async () => {
const { ctx, input } = await setup()
const agent = makeAgent('main', 'idle')