Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(agent): minimize inbox message contract

Browse Source
This commit is contained in:
_Kerman
2026-07-24 17:00:42 +08:00
parent b3c1abac67
commit 90e69a3123
16 changed files with 58 additions and 124 deletions
Download Patch File Download Diff File Expand all files Collapse all files

32
packages/core/agent-loop/src/agent.ts
View File

@@ -12,7 +12,6 @@ import { Agent, AgentMessageId, agentCarrier, agentInterruptReasonOf, assembleCo
import { createScope } from '@deepseek-ai/dsh-scope'
import type { Scope } from '@deepseek-ai/dsh-scope'
import type {
AgentMessage,
AgentMessageId as AgentMessageIdType,
CancelOptions,
AgentInterruptReason,
@@ -48,20 +47,6 @@ interface OutboxItem extends PromptMessageData {
steering?: PendingMessage
}
/** Build one live inbox event payload from a pending message. */
function inboxMessage(message: PendingMessage, steering: boolean): AgentMessage {
return {
id: message.id,
content: message.content,
source: message.source,
steering,
wakeup: message.wakeup,
}
}
/** Stable runtime-only reason used when lifecycle teardown interrupts a turn. */
export const DISPOSED_INTERRUPT_REASON = Object.freeze({ kind: 'disposed' } as const)
/** Normalize thrown values while preserving an existing error code. */
function toError(error: unknown): Error & { code?: string } {
return error instanceof Error ? error : new HarnessError(String(error), 'UNKNOWN', { cause: error })
@@ -69,12 +54,7 @@ function toError(error: unknown): Error & { code?: string } {
/** Rebuild the live {@link LlmError} for serializable provider facts; `cause` keeps the foreign original. */
function llmError(facts: LlmFailure, cause?: Error): LlmError {
return new LlmError(facts.message, facts.code, {
...facts.status === undefined ? {} : { status: facts.status },
...facts.providerRetryAfterMs === undefined ? {} : { providerRetryAfterMs: facts.providerRetryAfterMs },
...facts.requestId === undefined ? {} : { requestId: facts.requestId },
...cause === undefined ? {} : { cause },
})
return new LlmError(facts.message, facts.code, { ...facts, cause })
}
function withoutToolCalls(message: Message): Message {
@@ -154,7 +134,7 @@ export class ReactLoopAgent extends Agent {
} else {
this.queued.push(message)
}
emitAgentEvent(this.loopCtx, this, 'agent/inbox/enqueue', inboxMessage(message, steering))
emitAgentEvent(this.loopCtx, this, 'agent/inbox/enqueue', message)
if (!steering && wakeup) this.kick()
return id
}
@@ -174,8 +154,8 @@ export class ReactLoopAgent extends Agent {
}
if (!options.keepInbox) {
const discarded = [
...this.queued.map(message => inboxMessage(message, false)),
...this.outbox.flatMap(item => item.steering === undefined ? [] : [inboxMessage(item.steering, true)]),
...this.queued,
...this.outbox.map(item => item.steering).filter(steering => steering !== undefined),
]
// Clear before abort observers run: replacement work belongs to the next turn.
this.queued.length = 0
@@ -212,7 +192,7 @@ export class ReactLoopAgent extends Agent {
const message = this.queued.shift()
if (message === undefined) return
emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', inboxMessage(message, false))
emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', message)
const admission = new AbortController()
this.abort = admission
this.done = this.loopCtx.agents.withInitiator(this, async () => {
@@ -472,7 +452,7 @@ export class ReactLoopAgent extends Agent {
continue
}
steered = true
emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', inboxMessage(message, true))
emitAgentEvent(this.loopCtx, this, 'agent/inbox/dequeue', message)
this.session.append('steering/message', { turn, ...data }, { surfaceOp: 'append' })
}
return steered

4
packages/core/agent-loop/src/index.ts
View File

@@ -24,7 +24,7 @@ import type { Session, SessionHeader } from '@deepseek-ai/dsh-session'
import type {} from '@deepseek-ai/dsh-system-prompt'
import type {} from '@deepseek-ai/dsh-tools'
import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
import { DISPOSED_INTERRUPT_REASON, ReactLoopAgent } from './agent.ts'
import { ReactLoopAgent } from './agent.ts'
import { DEFAULT_MAX_PARALLEL_TOOL_CALLS } from './constants.ts'
/** Fiber states that cannot own or serve a new lifecycle. */
@@ -362,7 +362,7 @@ export class AgentLoop extends Service implements AgentFactory {
// sent after this point is the sender's bug — the registries are about
// to drop the agent, so nothing should still hold it.
if (machine !== undefined) {
machine.cancel(DISPOSED_INTERRUPT_REASON)
machine.cancel({ kind: 'disposed' })
await Promise.allSettled([machine.done])
await machine.scope.dispose()
}

27
packages/core/agent/src/types.ts
View File

@@ -2,23 +2,6 @@
* Public agent types and live-runtime events. Durable transcript facts and
* turn/step boundaries remain `@deepseek-ai/dsh-session` events.
*
* The agent is a naive message machine over the session log: prompts queue
* (one turn each), steering/context ride the outbox (taken whole at every
* step boundary), and the log re-derives the request history each step — so
* "edit history between steps" needs no dedicated seam. The extension surface
* is deliberately small:
*
* - `agent/prompt-submit` (waterfall): veto/rewrite a claimed prompt.
* - `agent/request` (waterfall): replace the call config per request.
* - `agent/step` (serial): awaited before every request is built — inject
* context, steer, or edit the log here; the request derives after it.
* - `agent/stopping` (serial): the turn is about to close — steer to object.
* - a tool result carrying `concludesTurn` ends the turn at its step (data,
* not a hook): the terminal-tool pattern.
* - `agent/idle` (emit): one per turn close, carrying why it ended. Error
* recovery is a consumer loop: observe an error idle, fix (edit the log,
* wait out a rate limit), then `agent.retry()`.
*
* @module @deepseek-ai/dsh-agent/types
*/
@@ -100,19 +83,13 @@ export function AgentMessageId(id: string): AgentMessageId {
* One accepted {@link Agent.send} message, carried by the `agent/inbox/*` live
* events. `id` is the value `send` returned to the caller, stable across this
* message's enqueue, dequeue, and discard events. Source defaults are already
* applied, so these are the exact values the item was accepted with. `steering`
* is true for a `next-step` item drained between steps; a `next-turn` item is
* claimed at a turn boundary.
* applied, so these are the exact values the item was accepted with.
*/
export interface AgentMessage {
/** The id `send` returned for this message. */
id: AgentMessageId
content: ContentBlock[]
source: MessageSource
/** Whether the item joined the steering FIFO (`next-step`) rather than the queued FIFO. */
steering: boolean
/** Whether the item is marked to wake the driver or force a continuation. */
wakeup: boolean
}
/** Options for {@link Agent.cancel}. */
@@ -319,7 +296,7 @@ declare module 'cordis' {
/**
* A frozen item entered the queued or steering inbox.
* @param agent - the owning agent.
* @param message - accepted routing data and correlation identity.
* @param message - accepted content, source, and correlation identity.
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
* @mode emit
*/

16
packages/core/agent/tests/invariant.spec.ts
View File

@@ -58,24 +58,24 @@ describe('agent status invariants', () => {
})
describe('agent inbox invariants', () => {
const info = (steering: boolean) => ({ id: AgentMessageId('m'), content: [], source: { kind: 'user' as const }, steering, wakeup: true })
const info = () => ({ id: AgentMessageId('m'), content: [], source: { kind: 'user' as const } })
it('accepts a dequeue and a discard covered by prior enqueues', async () => {
const ctx = await setup()
const agent = mockAgent('i1')
const at = scopeTarget(agent, agent)
expect(() => {
ctx.emit(at, 'agent/inbox/enqueue', agent, info(false))
ctx.emit(at, 'agent/inbox/enqueue', agent, info(true))
ctx.emit(at, 'agent/inbox/dequeue', agent, info(false))
ctx.emit(at, 'agent/inbox/discard', agent, [info(true)])
ctx.emit(at, 'agent/inbox/enqueue', agent, info())
ctx.emit(at, 'agent/inbox/enqueue', agent, info())
ctx.emit(at, 'agent/inbox/dequeue', agent, info())
ctx.emit(at, 'agent/inbox/discard', agent, [info()])
}).not.toThrow()
})
it('rejects a dequeue with no outstanding item', async () => {
const ctx = await setup()
const agent = mockAgent('i2')
expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/dequeue', agent, info(false)) })
expect(() => { ctx.emit(scopeTarget(agent, agent), 'agent/inbox/dequeue', agent, info()) })
.toThrow(/without a matching prior enqueue/)
})
@@ -83,8 +83,8 @@ describe('agent inbox invariants', () => {
const ctx = await setup()
const agent = mockAgent('i3')
const at = scopeTarget(agent, agent)
ctx.emit(at, 'agent/inbox/enqueue', agent, info(false))
expect(() => { ctx.emit(at, 'agent/inbox/discard', agent, [info(false), info(true)]) })
ctx.emit(at, 'agent/inbox/enqueue', agent, info())
expect(() => { ctx.emit(at, 'agent/inbox/discard', agent, [info(), info()]) })
.toThrow(/dropped 2 items but only 1 were outstanding/)
})

4
packages/core/scope/tests/invariant.spec.ts
View File

@@ -42,8 +42,8 @@ describe('scoped-dispatch invariants', () => {
'agent/created': [agent],
'agent/disposed': [agent],
'agent/status': [agent, 'idle'],
'agent/inbox/enqueue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' }, steering: false, wakeup: true }],
'agent/inbox/dequeue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' }, steering: false, wakeup: true }],
'agent/inbox/enqueue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' } }],
'agent/inbox/dequeue': [agent, { id: AgentMessageId('m'), content: [], source: { kind: 'user' } }],
'agent/inbox/discard': [agent, []],
'agent/cancel-requested': [agent, { kind: 'user' }],
'agent/session-start': [agent, 'startup'],