Skip to content

A team of long-lived bots for DeepSeek Harness, with main bots, bot-to-bot messages and group chats.

Observe subagent results through the published lifecycle

Fei2411f8503afa4601
diff --git a/ds-bot/package-lock.json b/ds-bot/package-lock.json
index 7c88943c..6e2d7de2 100644
--- a/ds-bot/package-lock.json
+++ b/ds-bot/package-lock.json
@@ -18,6 +18,7 @@
"peerDependencies": {
"@deepseek-ai/cordis": "*",
"@deepseek-ai/dsh-llm": "*",
+ "@deepseek-ai/dsh-scope": "*",
"@deepseek-ai/dsh-tools": "*",
"@deepseek-ai/dsh-web": "*"
}
diff --git a/ds-bot/package.json b/ds-bot/package.json
index befeff42..a8307fce 100644
--- a/ds-bot/package.json
+++ b/ds-bot/package.json
@@ -51,6 +51,7 @@
"peerDependencies": {
"@deepseek-ai/cordis": "*",
"@deepseek-ai/dsh-llm": "*",
+ "@deepseek-ai/dsh-scope": "*",
"@deepseek-ai/dsh-tools": "*",
"@deepseek-ai/dsh-web": "*"
},
diff --git a/ds-bot/src/host/handoffs.js b/ds-bot/src/host/handoffs.js
index 6092c302..621fb8b9 100644
--- a/ds-bot/src/host/handoffs.js
+++ b/ds-bot/src/host/handoffs.js
@@ -138,6 +138,13 @@ export function install(rt) {
closeWork(id, work.name ?? 'subagent', text)
return parent
}
+ // A fast child can settle before its tool result identifies the call that made it.
+ const nameSubWork = (id, name) => {
+ const work = works()[id] ?? Object.values(works()).flatMap(work => work.results ?? []).find(result => result.id === id)
+ if (work === undefined || work.name === name) return
+ work.name = name
+ save()
+ }
const dropWork = (id) => {
const work = works()[id]
@@ -275,5 +282,5 @@ export function install(rt) {
return lines.join('; ')
}
- Object.assign(rt, { workOf, openWork, closeWork, dropWork, takenWork: taken, ownsWork: owns, waitsWork: waits, holdWork: hold, workAsker: askedBy, answerText, upstreamOf, sameWork, forgetBotWork: forgetBot, statusOf, waitingView, settleSubWork, subWorkParent })
+ Object.assign(rt, { workOf, openWork, closeWork, dropWork, takenWork: taken, ownsWork: owns, waitsWork: waits, holdWork: hold, workAsker: askedBy, answerText, upstreamOf, sameWork, forgetBotWork: forgetBot, statusOf, waitingView, settleSubWork, subWorkParent, nameSubWork })
}
diff --git a/ds-bot/src/host/turns.js b/ds-bot/src/host/turns.js
index 586c8790..6115c801 100644
--- a/ds-bot/src/host/turns.js
+++ b/ds-bot/src/host/turns.js
@@ -2,6 +2,7 @@
// triggered, the waiters and inboxes of group rounds, and routing a finished turn's reply.
//
// Turn tracking: which turns were triggered by another Bot, and what they said.
+import { carrierKeyOf } from '@deepseek-ai/dsh-scope'
import { HANDOFF_ACK, MESSAGE_INLINE_MAX, REFERENCE_KIND, REPLY_KIND, SOURCE_KIND, STEER_CUT } from './constants.js'
import { absoluteLinks } from './links.js'
import { textOf } from './text.js'
@@ -64,11 +65,14 @@ export const stripWrittenCalls = text => text
const PROGRAM_TOOL = 'run_code'
// DSH's delegation tools, named by the tool instance: a spawn child and a fork.
const SUBAGENT_TOOLS = new Set(['subagent', 'subagent_fork'])
-// A settled child's closing text, or why it ended without one.
+// A settled child's closing text, or why it ended without one. A child that did
+// not finish says so: output it left behind can be partial, so the reason it
+// ended is part of its result.
const subEndText = (data) => {
const text = textOf(data?.lastAssistantMessage)
- if (text !== '') return text
- return `subagent ended${typeof data?.stopReason === 'string' ? ` (${data.stopReason})` : ''} without a closing message.`
+ const reason = typeof data?.stopReason === 'string' ? data.stopReason : ''
+ if (text === '') return `subagent ended${reason === '' ? '' : ` (${reason})`} without a closing message.`
+ return reason === '' || reason === 'completed' ? text : `subagent ended (${reason}) before it finished. What it had written:\n${text}`
}
const RETRY_TEXT = 'Your last reply wrote a tool call as plain text (<tool_call>…), so it did not run and nothing happened. Call the tool through the tool interface now, then reply as you meant to.'
@@ -401,23 +405,6 @@ export function install(rt) {
case 'tool/result':
endCall(id, entry, event.data?.callId)
break
- case 'subagent/start': {
- // A subagent the turn delegated to is work handed on, like message_bot: it
- // hangs under the work the turn answers until its settlement notice comes
- // back, and its closing message joins that work's results.
- const work = rt.workOf?.(entry.info)
- const self = rt.selfOf(id)
- if (work !== undefined && self !== undefined && rt.chatOwners.has(id) && typeof event.data?.id === 'string' && rt.ownsWork?.(self, work)) {
- const call = [...(entry.calls?.values() ?? [])].findLast(item => SUBAGENT_TOOLS.has(item.name))
- let label
- try { label = JSON.parse(call?.args ?? '{}').description } catch {}
- rt.openWork?.(event.data.id, { from: self, parent: work, name: `subagent${typeof label === 'string' && label.trim() !== '' ? ` ${label.trim()}` : ''}` })
- }
- break
- }
- case 'subagent/end':
- if (typeof event.data?.id === 'string') rt.settleSubWork?.(event.data.id, subEndText(event.data))
- break
case 'turn/start':
setActivity(id, 'thinking')
entry.turn = event.data.turn
@@ -554,7 +541,14 @@ export function install(rt) {
rt.takenWork?.(parent, source.senderSessionId)
const info = { kind: SOURCE_KIND, role: 'reply', work: parent, replyTo: source.senderSessionId, exchangeId: source.senderSessionId, senderSessionId: source.senderSessionId }
if (entry.turn === undefined) entry.pending = info
- else if (rt.workOf?.(entry.info) !== parent) entry.later = [...(entry.later ?? []), { info, text: textOf(event.data.content) }]
+ else if (entry.info === undefined && !opened) {
+ // DSH opens the turn before it records the message that filled its
+ // inbox: a notice that opened the turn claims it, like the first
+ // relay of a turn.
+ entry.opened = true
+ entry.answers = true
+ claimTrigger(id, entry, info)
+ } else if (rt.workOf?.(entry.info) !== parent) entry.later = [...(entry.later ?? []), { info, text: textOf(event.data.content) }]
}
} else if (source?.kind === 'user' || source?.kind === REPLY_KIND) {
if (rt.roomOf(id) && source.kind === 'user') {
@@ -745,6 +739,30 @@ export function install(rt) {
}
})
+ // A subagent a Bot's turn delegates to is work handed on, like message_bot: the
+ // child hangs under the work the turn answers until its settlement notice comes
+ // back, and its closing message joins that work's results. These are Cordis
+ // events, not Session events: the dispatch keys `this` by the delegating parent
+ // Agent, which `carrierKeyOf` hands back.
+ ctx.on('subagent/start', function (info) {
+ const id = carrierKeyOf(this)?.session?.id
+ const entry = id === undefined ? undefined : live.get(id)
+ const work = rt.workOf?.(entry?.info)
+ const self = id === undefined ? undefined : rt.selfOf(id)
+ if (work === undefined || self === undefined || !rt.chatOwners.has(id) || typeof info?.id !== 'string' || !rt.ownsWork?.(self, work)) return
+ rt.openWork?.(info.id, { from: self, parent: work, name: 'subagent' })
+ })
+ // A settled child closes its sub-work: its closing text joins the results of
+ // the work it hung under.
+ ctx.on('subagent/end', (info) => {
+ if (typeof info?.id === 'string') rt.settleSubWork?.(info.id, subEndText(info))
+ })
+ ctx.on('tools/result', (exec, result) => {
+ if (!SUBAGENT_TOOLS.has(exec?.name) || result?.isError || typeof result?.value?.subagentId !== 'string') return
+ const description = exec.arguments?.description
+ rt.nameSubWork?.(result.value.subagentId, `subagent${typeof description === 'string' && description.trim() !== '' ? ` ${description.trim()}` : ''}`)
+ })
+
const markSteerCut = (id) => {
const entry = live.get(id)
if (entry?.turn !== undefined) entry.cut = { texts: entry.texts.length }
diff --git a/ds-bot/test/handoff-results.test.js b/ds-bot/test/handoff-results.test.js
index a6dce9fb..9500aff1 100644
--- a/ds-bot/test/handoff-results.test.js
+++ b/ds-bot/test/handoff-results.test.js
@@ -10,6 +10,7 @@ import { apply } from '../index.js'
import { fakeContext } from './fake-ctx.js'
import { SOURCE_KIND } from '../src/host/constants.js'
import { install as installHandoffs } from '../src/host/handoffs.js'
+import { scopeTarget } from '@deepseek-ai/dsh-scope'
const seed = () => ({
version: 1,
@@ -94,13 +95,20 @@ async function startHost(home, team) {
if (listener.length >= 2) listener({ id }, { type, seq: ++seq, data })
}
}
+ // Scoped Cordis events (subagent lifecycle, tool results) reach the plugin
+ // through a dispatch carrier DSH keys by the agent the event is for — that
+ // carrier is what `this` is in a real listener call.
+ const emitScoped = (parentId, name, ...args) => {
+ const carrier = scopeTarget({}, agentOf(parentId))
+ for (const listener of ctx.listeners.get(name) ?? []) listener.call(carrier, ...args)
+ }
const tool = (name, args, sessionId) => ctx.registeredTools.get(name).execute(args, { agent: { id: sessionId } })
const call = async (endpoint, payload) => (await route.fetch(new Request('http://localhost/api/bot', {
method: 'POST', body: JSON.stringify({ endpoint, payload }),
}))).json()
// Loading once fills the Session-owner indexes turns.js filters events by.
await tool('list_bots', {}, 'a')
- return { ctx, agents, agentOf, emit, tool, call, home, stop: () => ctx.dispose() }
+ return { ctx, agents, agentOf, emit, emitScoped, tool, call, home, stop: () => ctx.dispose() }
}
// The plugin folder of a test, and the hosts over it. A second host over the same
@@ -375,7 +383,7 @@ test('a team saved before the result was kept whole still answers, and says what
test('a subagent a Bot delegated to hands its result into the work the turn answered', async (t) => {
const { start } = bench(t)
const first = await start(seed())
- const { agents, emit, tool } = first
+ const { agents, emit, emitScoped, tool } = first
const turns = turnTaker(agents, emit)
turns.userTurn('a', 'have Writer do it')
await tool('message_bot', { to: 'Writer', message: 'carry out the plan' }, 'a')
@@ -383,7 +391,9 @@ test('a subagent a Bot delegated to hands its result into the work the turn answ
turns.take('b')
// Writer delegates part of the work to a subagent instead of another Bot.
emit('b', 'tool/call', { callId: 'call1', name: 'subagent', arguments: JSON.stringify({ description: 'deep review', prompt: 'review the plan' }) })
- emit('b', 'subagent/start', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true })
+ emitScoped('b', 'subagent/start', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true })
+ emitScoped('b', 'tools/result', { callId: 'call1', name: 'subagent', arguments: { description: 'deep review', prompt: 'review the plan' }, agent: agents.get('b') }, { isError: false, value: { kind: 'activation', subagentId: 'sub1' } })
+ emit('b', 'tool/result', { callId: 'call1', message: { callId: 'call1', content: textBlock('started subagent sub1'), isError: false } })
turns.end('b', 'subagent is on it')
// The answer waits while the sub-work is out, like a handed-on request.
await delay(50)
@@ -391,10 +401,11 @@ test('a subagent a Bot delegated to hands its result into the work the turn answ
const works = await worksIn(first)
const [work] = Object.values(works).filter(entry => entry.to === 'b')
assert.deepEqual(work.open, ['sub1'])
- // The child settles; its closing message is the sub-work's result.
- emit('b', 'subagent/end', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true, stopReason: 'completed', lastAssistantMessage: textBlock('reviewed: three findings') })
- emit('b', 'user/message', { content: textBlock('Subagent sub1 settled.\n\nIts closing message:\nreviewed: three findings'), source: { kind: 'subagent-settled', form: 'notice', senderSessionId: 'sub1' } })
+ // The child settles; its closing message is the sub-work's result. DSH opens
+ // the turn first, then records the notice that filled its inbox.
+ emitScoped('b', 'subagent/end', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true, stopReason: 'completed', lastAssistantMessage: textBlock('reviewed: three findings') })
emit('b', 'turn/start', { turn: 2 })
+ emit('b', 'user/message', { content: textBlock('Background subagent sub1 finished.\nIts closing message:\nreviewed: three findings'), source: { kind: 'subagent-settled', form: 'notice', summary: 'Background subagent sub1 finished.', senderSessionId: 'sub1' } })
emit('b', 'assistant/message', assistantText('all reviewed'))
emit('b', 'turn/end', { turn: 2, reason: { kind: 'completed' } })
await settled(() => callsOf(agents, 'a').length === 1)
@@ -409,12 +420,80 @@ test('a subagent a Bot delegated to hands its result into the work the turn answ
test('a subagent started on a turn that answers no work changes nothing', async (t) => {
const { start } = bench(t)
const first = await start(seed())
- const { emit } = first
+ const { emit, emitScoped } = first
const turns = turnTaker(first.agents, first.emit)
turns.userTurn('b', 'summarize this')
emit('b', 'tool/call', { callId: 'call1', name: 'subagent', arguments: JSON.stringify({ description: 'a summary', prompt: 'summarize' }) })
- emit('b', 'subagent/start', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true })
+ emitScoped('b', 'subagent/start', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true })
turns.end('b', 'done')
const works = await worksIn(first)
assert.deepEqual(works, {})
})
+
+for (const stopReason of ['aborted', 'error']) test(`a subagent ending with ${stopReason} hands up its partial work and reason`, async (t) => {
+ const { start } = bench(t)
+ const first = await start(seed())
+ const { agents, emit, emitScoped, tool } = first
+ const turns = turnTaker(agents, emit)
+ turns.userTurn('a', 'have Writer do it')
+ await tool('message_bot', { to: 'Writer', message: 'carry out the plan' }, 'a')
+ turns.end('a', 'asked Writer')
+ turns.take('b')
+ emit('b', 'tool/call', { callId: 'call1', name: 'subagent', arguments: JSON.stringify({ description: 'deep review', prompt: 'review the plan' }) })
+ emitScoped('b', 'subagent/start', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true })
+ emitScoped('b', 'tools/result', { callId: 'call1', name: 'subagent', arguments: { description: 'deep review', prompt: 'review the plan' }, agent: agents.get('b') }, { isError: false, value: { kind: 'activation', subagentId: 'sub1' } })
+ emit('b', 'tool/result', { callId: 'call1', message: { callId: 'call1', content: textBlock('started subagent sub1'), isError: false } })
+ turns.end('b', 'subagent is on it')
+ // The child was stopped with partial output: the result says so, it does not
+ // read like a finished answer.
+ emitScoped('b', 'subagent/end', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true, stopReason, lastAssistantMessage: textBlock('two of three findings') })
+ emit('b', 'turn/start', { turn: 2 })
+ emit('b', 'user/message', { content: textBlock('Background subagent sub1 was stopped before it finished.'), source: { kind: 'subagent-settled', form: 'notice', summary: 'Background subagent sub1 was stopped before it finished.', senderSessionId: 'sub1' } })
+ emit('b', 'assistant/message', assistantText('the review was stopped'))
+ emit('b', 'turn/end', { turn: 2, reason: { kind: 'completed' } })
+ await settled(() => callsOf(agents, 'a').length === 1)
+ const answer = textOf(callsOf(agents, 'a')[0][1].content)
+ assert.ok(answer.includes(`ended (${stopReason}) before it finished`), `the stop is in the result: ${answer}`)
+ assert.ok(answer.includes('two of three findings'), `partial output stays: ${answer}`)
+})
+
+test('parallel delegations get each call\'s own description for its child', async (t) => {
+ const { start } = bench(t)
+ const first = await start(seed())
+ const { agents, emit, emitScoped, tool } = first
+ const turns = turnTaker(agents, emit)
+ turns.userTurn('a', 'have Writer do it')
+ await tool('message_bot', { to: 'Writer', message: 'carry out the plan' }, 'a')
+ turns.end('a', 'asked Writer')
+ turns.take('b')
+ emit('b', 'tool/call', { callId: 'call1', name: 'subagent', arguments: JSON.stringify({ description: 'deep review', prompt: 'review the plan' }) })
+ emit('b', 'tool/call', { callId: 'call2', name: 'subagent_fork', arguments: JSON.stringify({ description: 'draft summary', prompt: 'summarize the plan' }) })
+ emitScoped('b', 'subagent/start', { runId: 'r2', provider: 'spawn', id: 'sub2', local: true })
+ emitScoped('b', 'subagent/start', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true })
+ // Publication order differs from call order, and one child even settles before
+ // its call returns. Only the result's child id identifies the right description.
+ emitScoped('b', 'subagent/end', { runId: 'r2', provider: 'spawn', id: 'sub2', local: true, stopReason: 'completed', lastAssistantMessage: textBlock('a summary') })
+ emitScoped('b', 'tools/result', { callId: 'call2', name: 'subagent_fork', arguments: { description: 'draft summary', prompt: 'summarize the plan' }, agent: agents.get('b') }, { isError: false, value: { kind: 'activation', subagentId: 'sub2' } })
+ emitScoped('b', 'tools/result', { callId: 'call1', name: 'subagent', arguments: { description: 'deep review', prompt: 'review the plan' }, agent: agents.get('b') }, { isError: false, value: { kind: 'activation', subagentId: 'sub1' } })
+ emit('b', 'tool/result', { callId: 'call1', message: { callId: 'call1', content: textBlock('started subagent sub1'), isError: false } })
+ emit('b', 'tool/result', { callId: 'call2', message: { callId: 'call2', content: textBlock('started subagent sub2'), isError: false } })
+ turns.end('b', 'subagents are on it')
+ const works = await worksIn(first)
+ assert.equal(works.sub1.name, 'subagent deep review')
+ assert.equal(Object.values(works).find(work => work.to === 'b').results.find(result => result.id === 'sub2').name, 'subagent draft summary')
+ emit('b', 'turn/start', { turn: 2 })
+ emit('b', 'user/message', { content: textBlock('Background subagent sub2 finished.\nIts closing message:\na summary'), source: { kind: 'subagent-settled', form: 'notice', summary: 'Background subagent sub2 finished.', senderSessionId: 'sub2' } })
+ emit('b', 'assistant/message', assistantText('summary back, review still out'))
+ emit('b', 'turn/end', { turn: 2, reason: { kind: 'completed' } })
+ await delay(50)
+ assert.equal(callsOf(agents, 'a').length, 0)
+ emitScoped('b', 'subagent/end', { runId: 'r1', provider: 'spawn', id: 'sub1', local: true, stopReason: 'completed', lastAssistantMessage: textBlock('three findings') })
+ emit('b', 'turn/start', { turn: 3 })
+ emit('b', 'user/message', { content: textBlock('Background subagent sub1 finished.\nIts closing message:\nthree findings'), source: { kind: 'subagent-settled', form: 'notice', summary: 'Background subagent sub1 finished.', senderSessionId: 'sub1' } })
+ emit('b', 'assistant/message', assistantText('all back'))
+ emit('b', 'turn/end', { turn: 3, reason: { kind: 'completed' } })
+ await settled(() => callsOf(agents, 'a').length === 1)
+ const answer = textOf(callsOf(agents, 'a')[0][1].content)
+ assert.ok(answer.includes('subagent draft summary:\na summary'), `first child's own name: ${answer}`)
+ assert.ok(answer.includes('subagent deep review:\nthree findings'), `second child's own name: ${answer}`)
+})
diff --git a/ds-bot/test/install.test.js b/ds-bot/test/install.test.js
index d5ec81e1..2339e093 100644
--- a/ds-bot/test/install.test.js
+++ b/ds-bot/test/install.test.js
@@ -40,6 +40,9 @@ test('apply registers listeners, tools, and effects in a fixed order', (t) => {
'on credentials/reference-updated',
'on settings/document-updated',
'on session/event',
+ 'on subagent/start',
+ 'on subagent/end',
+ 'on tools/result',
'on session/event',
'on tools/execute',
'effect ds-bot: agent tool restrict retry',