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

refactor(events): add stable conversation correlation ids

Browse Source
This commit is contained in:
imccyu
2026-08-09 18:13:00 +08:00
parent dc825be8d8
commit aa623b6e7a
23 changed files with 347 additions and 41 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/compact/command-compact/src/index.ts
+1 -1
View File
@@ -63,7 +63,7 @@ async function executeCompact(
return { kind: 'error', text: USAGE }
}
try {
const result = await ctx.compact.compactNow(invocation.agent, invocation.signal)
const result = await ctx.compact.compactNow(invocation.agent, invocation.signal, invocation.commandId)
if (result === null) return { kind: 'success', text: 'No compactable history yet.' }
return {
kind: 'success',
packages/compact/compact-basic/package.json
+2
View File
@@ -27,6 +27,7 @@
"peerDependencies": {
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-compact": "^0.0.1",
"@deepseek-ai/dsh-commands": "^0.0.1",
"@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
@@ -49,6 +50,7 @@
"@deepseek-ai/dsh-agent-loop": "workspace:^",
"@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
"@deepseek-ai/dsh-compact": "workspace:^",
"@deepseek-ai/dsh-commands": "workspace:^",
"@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-llm-retry": "workspace:^",
packages/compact/compact-basic/src/index.ts
+8 -1
View File
@@ -13,6 +13,7 @@ import type { Session } from '@deepseek-ai/dsh-session'
import { CONTEXT_WINDOW_EXCEEDED_CODE, assertNever } from '@deepseek-ai/dsh-llm'
import type { LlmCallConfig } from '@deepseek-ai/dsh-llm'
import type { Agent, PreStepDecision } from '@deepseek-ai/dsh-agent'
import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
// Type-only: makes the optional sibling service available to `ctx.get()`.
import type {} from '@deepseek-ai/dsh-compact-tool-result-prune'
import {
@@ -361,9 +362,14 @@ export class BasicCompactService extends CompactService {
* resolve only after its standalone marker pair is durably checkpointed.
* @param agent - idle agent whose next-turn admission this call reserves.
* @param signal - cancellation scoped to this compaction request.
* @param sourceCommandId - initiating command identity for presentation correlation.
* @returns the committed result, or `null` when no safe useful range exists.
*/
override compactNow(agent: Agent, signal: AbortSignal): Promise<CompactionResult | null> {
override compactNow(
agent: Agent,
signal: AbortSignal,
sourceCommandId?: CommandId,
): Promise<CompactionResult | null> {
signal.throwIfAborted()
try {
return agent.runMaintenance(async (agentSignal) => {
@@ -385,6 +391,7 @@ export class BasicCompactService extends CompactService {
{
owner: null,
stability: 'selected-span',
...sourceCommandId === undefined ? {} : { sourceCommandId },
flush: async () => {
await this.ctx.sessions.flush(agent.session)
},
packages/compact/compact-basic/src/region.ts
+34 -6
View File
@@ -5,14 +5,17 @@
* @module @deepseek-ai/dsh-compact-basic/region
*/
import { randomUUID } from 'node:crypto'
import { isDeepStrictEqual } from 'node:util'
import {
COMPACT_CHECKPOINT_SOURCE,
CompactionId,
ManualCompactionError,
compactCheckpointSource,
toolPairingBalancedAfter,
toolPairingBalancedBefore,
} from '@deepseek-ai/dsh-compact'
import type { CompactionResult } from '@deepseek-ai/dsh-compact'
import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
import { createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
import type { Message, UserMessage } from '@deepseek-ai/dsh-llm'
import type { TokenMeasurement, TokenMeterService } from '@deepseek-ai/dsh-token-meter'
@@ -54,6 +57,8 @@ interface CompactionTransactionOptions {
readonly stability: 'whole-surface' | 'selected-span'
/** Optional durability checkpoint after a successfully closed bracket. */
readonly flush?: () => Promise<void>
/** Manual command that initiated this transaction, when present. */
readonly sourceCommandId?: CommandId
}
interface CompactionEntryState {
@@ -175,7 +180,13 @@ export async function compactSurfaceRegion(
owner = entryState.openTurn
}
const startEvent = session.append('compact/start', { turn: owner })
const compactionId = CompactionId(randomUUID())
const lifecycle = {
compactionId,
...options.sourceCommandId === undefined ? {} : { sourceCommandId: options.sourceCommandId },
turn: owner,
}
const startEvent = session.append('compact/start', lifecycle)
const assertStable: StabilityCheck = options.stability === 'whole-surface'
? assertWholeSurfaceUnchanged
: assertSelectedSpanStable
@@ -188,13 +199,20 @@ export async function compactSurfaceRegion(
try {
const prepared = prepareCompaction(dependencies, session, selection)
const summarized = await summarizeCompaction(dependencies, prepared, agent, signal)
const summarized = await summarizeCompaction(
dependencies,
prepared,
agent,
compactionId,
options.sourceCommandId,
signal,
)
if (options.owner === null) signal?.throwIfAborted()
assertStable(dependencies, session, summarized)
stage = 'commit'
const pending = commitCompactionBody(session, startEvent, summarized)
closing = true
const endEvent = session.append('compact/end', { turn: owner })
const endEvent = session.append('compact/end', lifecycle)
closed = true
result = completeCompaction(pending, endEvent)
} catch (error: unknown) {
@@ -202,7 +220,7 @@ export async function compactSurfaceRegion(
if (!closing) {
closing = true
try {
session.append('compact/end', { turn: owner, error: errorChain(error) })
session.append('compact/end', { ...lifecycle, error: errorChain(error) })
closed = true
} catch (closeError: unknown) {
failure = { error: closeError, stage: 'commit' }
@@ -343,12 +361,14 @@ async function summarizeCompaction(
dependencies: RegionDependencies,
prepared: PreparedCompaction,
agent: Agent,
compactionId: CompactionResult['compactionId'],
sourceCommandId: CommandId | undefined,
signal?: AbortSignal,
): Promise<SummarizedCompaction> {
const summaryResult = await dependencies.summarize(prepared.input, agent, signal)
const checkpointMessage = createUserMessage({
content: frameSummary(summaryResult.summary),
source: COMPACT_CHECKPOINT_SOURCE,
source: compactCheckpointSource(compactionId, sourceCommandId),
})
const framedSummaryTokenCount = dependencies.meter.estimateMessage(checkpointMessage)
if (framedSummaryTokenCount >= prepared.shadowedTokenCount) {
@@ -425,6 +445,10 @@ function commitCompactionBody(
? { rawOutput: summarized.rawOutput, llmStreamCall: true as const }
: summarized.rawOutput === undefined ? {} : { rawOutput: summarized.rawOutput }
const summaryEvent = session.append('compact/summary', {
compactionId: startEvent.data.compactionId,
...startEvent.data.sourceCommandId === undefined
? {}
: { sourceCommandId: startEvent.data.sourceCommandId },
summary,
...callProvenance,
shadowedRange: { start, end },
@@ -440,6 +464,10 @@ function commitCompactionBody(
sourceEventSeqs: [startEvent.seq, summaryEvent.seq, ...shadowedSeqs],
})
return {
compactionId: startEvent.data.compactionId,
...startEvent.data.sourceCommandId === undefined
? {}
: { sourceCommandId: startEvent.data.sourceCommandId },
startSeq: startEvent.seq,
summarySeq: summaryEvent.seq,
summary,
packages/compact/compact-basic/tsconfig.json
+3
View File
@@ -27,6 +27,9 @@
{
"path": "../../core/agent"
},
{
"path": "../../interaction/commands"
},
{
"path": "../compact"
},
packages/compact/compact/package.json
+8
View File
@@ -19,6 +19,10 @@
"types": "./lib/types/checkpoint.d.ts",
"default": "./lib/types/checkpoint.js"
},
"./brand": {
"types": "./lib/types/brand.d.ts",
"default": "./lib/types/brand.js"
},
"./src/*": "./src/*",
"./package.json": "./package.json"
},
@@ -30,12 +34,16 @@
],
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
"@deepseek-ai/dsh-commands": "^0.0.1",
"@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
"@deepseek-ai/dsh-session": "^0.0.1",
"cordis": "^4.0.0-rc.7"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
"@deepseek-ai/dsh-commands": "workspace:^",
"@deepseek-ai/dsh-invariants": "workspace:^",
"@deepseek-ai/dsh-llm": "workspace:^",
"@deepseek-ai/dsh-session": "workspace:^",
packages/compact/compact/src/brand.ts
+13
View File
@@ -0,0 +1,13 @@
import type { Branded } from '@deepseek-ai/dsh-brand'
/** Stable identity shared by one compact start/summary/checkpoint/end transaction. */
export type CompactionId = Branded<'CompactionId'>
/**
* Brand an implementation-minted compaction identity.
* @param id - opaque transaction identity.
* @returns the same string, branded; no validation is performed.
*/
export function CompactionId(id: string): CompactionId {
return id as CompactionId
}
packages/compact/compact/src/checkpoint.ts
+25
View File
@@ -13,10 +13,35 @@
*/
import type { MessageSource } from '@deepseek-ai/dsh-llm/message'
import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
import type { CompactionId } from './brand.ts'
/** Canonical source for the replacement user message produced by every compaction backend. */
export const COMPACT_CHECKPOINT_SOURCE = Object.freeze({ kind: 'plugin', plugin: 'compact' } as const)
/** Message provenance carried by a concrete compaction checkpoint. */
export type CompactCheckpointSource = typeof COMPACT_CHECKPOINT_SOURCE & {
readonly compactionId: CompactionId
readonly sourceCommandId?: CommandId
}
/**
* Create checkpoint provenance correlated with one compaction transaction.
* @param compactionId - owning compaction identity.
* @param sourceCommandId - initiating manual command, when present.
* @returns immutable checkpoint source.
*/
export function compactCheckpointSource(
compactionId: CompactionId,
sourceCommandId?: CommandId,
): CompactCheckpointSource {
return Object.freeze({
...COMPACT_CHECKPOINT_SOURCE,
compactionId,
...sourceCommandId === undefined ? {} : { sourceCommandId },
})
}
/**
* Test whether a persisted message source identifies a compaction checkpoint.
* @param source - source restored from a surface user message.
packages/compact/compact/src/index.ts
+6 -1
View File
@@ -9,14 +9,17 @@
import { Context, Service } from 'cordis'
import type { Session } from '@deepseek-ai/dsh-session'
import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
import type { CompactionResult } from './types.ts'
export type { CompactionResult } from './types.ts'
export { CompactionId } from './brand.ts'
export { toolPairingBalancedAfter, toolPairingBalancedBefore } from './tool-pairing.ts'
// The checkpoint source and its predicate are declared on the cordis-free
// `./checkpoint` leaf so client and wire programs can name them without this
// root's Context merge; the root stays the host-side entry point for both.
export { COMPACT_CHECKPOINT_SOURCE, isCompactCheckpointSource } from './checkpoint.ts'
export { COMPACT_CHECKPOINT_SOURCE, compactCheckpointSource, isCompactCheckpointSource } from './checkpoint.ts'
export type { CompactCheckpointSource } from './checkpoint.ts'
/** Why automatic policy is asking a backend to consider compaction. */
export type CompactionTrigger = 'pressure' | 'context-overflow'
@@ -126,6 +129,7 @@ export abstract class CompactService extends Service {
*
* @param agent - idle agent whose durable history should be compacted.
* @param signal - cancellation scoped to this compaction request.
* @param sourceCommandId - initiating command identity for a manual compaction.
* @returns the compaction result, or `null` when no safe useful range exists.
* @throws {@link ManualCompactionError} for expected busy, agent-cancellation,
* changed-span, summarization/shrink, commit-stage, or persistence failures;
@@ -135,6 +139,7 @@ export abstract class CompactService extends Service {
abstract compactNow(
agent: ManualCompactAgentContext,
signal: AbortSignal,
sourceCommandId?: CommandId,
): Promise<CompactionResult | null>
/**
packages/compact/compact/src/invariant.ts
+89 -4
View File
@@ -1,8 +1,12 @@
/** Package-owned compaction log-stream invariants. @module @deepseek-ai/dsh-compact/invariant */
import type { Context } from 'cordis'
import { isReplacementSurfaceEvent } from '@deepseek-ai/dsh-session'
import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
import type { InvariantFailure, InvariantInstaller } from '@deepseek-ai/dsh-invariants'
import type { CompactionId } from './brand.ts'
import { isCompactCheckpointSource } from './checkpoint.ts'
import type { CompactCheckpointSource } from './checkpoint.ts'
import type {} from './types.ts'
const PACKAGE_NAME = '@deepseek-ai/dsh-compact'
@@ -13,6 +17,8 @@ export const name = 'compact-invariant'
export const inject = ['invariants']
interface CompactionTrace {
compactionId: CompactionId
sourceCommandId: string | undefined
startSeq: number
turn: number | null
summarized: boolean
@@ -24,11 +30,48 @@ interface SessionTrace {
}
type CompactionTransition =
| { kind: 'start'; startSeq: number; turn: number | null }
| { kind: 'summary'; startSeq: number; turn: number | null }
| { kind: 'start'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
| { kind: 'summary'; compactionId: CompactionId; sourceCommandId: string | undefined; startSeq: number; turn: number | null }
| { kind: 'end' }
| { kind: 'end-seed' }
/** Require a durable opaque identity to be a non-empty string. */
function validateId(value: unknown, label: string, fail: InvariantFailure): asserts value is string {
if (typeof value !== 'string' || value.length === 0) fail(`${label} must be a non-empty string`)
}
/** Keep the optional initiating command identity stable across one transaction. */
function validateSourceCommandId(
eventType: string,
value: unknown,
expected: string | undefined,
fail: InvariantFailure,
): void {
if (value !== undefined) validateId(value, `${eventType} sourceCommandId`, fail)
if (value !== expected) {
fail(`${eventType} sourceCommandId ${String(value)} does not match compact/start sourceCommandId ${String(expected)}`)
}
}
/** Validate one replacement checkpoint against its open compaction transaction. */
function validateCheckpoint(
trace: SessionTrace,
event: SessionEvent<'user/message'>,
fail: InvariantFailure,
): void {
const source = event.data.source as typeof event.data.source & Partial<CompactCheckpointSource>
validateId(source.compactionId, 'compaction checkpoint compactionId', fail)
if (source.sourceCommandId !== undefined) {
validateId(source.sourceCommandId, 'compaction checkpoint sourceCommandId', fail)
}
const open = trace.compaction
if (open === undefined) fail('compaction checkpoint has no matching compact/start')
if (source.compactionId !== open.compactionId) {
fail(`compaction checkpoint id ${source.compactionId} does not match compact/start id ${open.compactionId}`)
}
validateSourceCommandId('compaction checkpoint', source.sourceCommandId, open.sourceCommandId, fail)
}
/** Compaction starts still unmatched when a later seed boundary made them stale. */
function inheritedOrphanStartSeqs(
events: readonly SessionEvent[],
@@ -99,20 +142,44 @@ function validateCompactionEvent(
fail: InvariantFailure,
): CompactionTransition | undefined {
if (event.type === 'session/end-seed') return { kind: 'end-seed' }
if (event.type === 'user/message'
&& isReplacementSurfaceEvent(event)
&& isCompactCheckpointSource(event.data.source)) {
validateCheckpoint(trace, event, fail)
return undefined
}
if (event.type !== 'compact/start' && event.type !== 'compact/summary' && event.type !== 'compact/end') {
return undefined
}
const open = trace.compaction
if (event.type === 'compact/start') {
validateId(event.data.compactionId, 'compact/start compactionId', fail)
if (event.data.sourceCommandId !== undefined) {
validateId(event.data.sourceCommandId, 'compact/start sourceCommandId', fail)
}
if (open !== undefined) {
const owner = open.turn === null ? 'standalone compaction' : `turn ${open.turn}`
fail(`compact/start while ${owner} is still compacting`)
}
validateOwner(event.data.turn, trace.openTurn, event.type, fail)
return { kind: 'start', startSeq: event.seq, turn: event.data.turn }
return {
kind: 'start',
compactionId: event.data.compactionId,
sourceCommandId: event.data.sourceCommandId,
startSeq: event.seq,
turn: event.data.turn,
}
}
if (event.type === 'compact/summary') {
validateId(event.data.compactionId, 'compact/summary compactionId', fail)
if (event.data.sourceCommandId !== undefined) {
validateId(event.data.sourceCommandId, 'compact/summary sourceCommandId', fail)
}
if (open === undefined) fail('compact/summary has no matching compact/start')
if (event.data.compactionId !== open.compactionId) {
fail(`compact/summary id ${event.data.compactionId} does not match compact/start id ${open.compactionId}`)
}
validateSourceCommandId('compact/summary', event.data.sourceCommandId, open.sourceCommandId, fail)
validateOwner(open.turn, trace.openTurn, event.type, fail)
if (open.summarized) fail('compact/summary repeated within one compaction')
const seqs = event.data.shadowedSeqs
@@ -123,9 +190,23 @@ function validateCompactionEvent(
if (!Number.isSafeInteger(event.data.shadowedTokenCount) || event.data.shadowedTokenCount < 0) {
fail('compact/summary shadowedTokenCount must be a non-negative safe integer')
}
return { kind: 'summary', startSeq: open.startSeq, turn: open.turn }
return {
kind: 'summary',
compactionId: open.compactionId,
sourceCommandId: open.sourceCommandId,
startSeq: open.startSeq,
turn: open.turn,
}
}
validateId(event.data.compactionId, 'compact/end compactionId', fail)
if (event.data.sourceCommandId !== undefined) {
validateId(event.data.sourceCommandId, 'compact/end sourceCommandId', fail)
}
if (open === undefined) fail('compact/end has no matching compact/start')
if (event.data.compactionId !== open.compactionId) {
fail(`compact/end id ${event.data.compactionId} does not match compact/start id ${open.compactionId}`)
}
validateSourceCommandId('compact/end', event.data.sourceCommandId, open.sourceCommandId, fail)
if (event.data.turn !== open.turn) {
fail(`compact/end owner ${String(event.data.turn)} does not match compact/start owner ${String(open.turn)}`)
}
@@ -142,6 +223,8 @@ function applyCompactionTransition(
): CompactionTrace | undefined {
if (transition.kind === 'start') {
return {
compactionId: transition.compactionId,
sourceCommandId: transition.sourceCommandId,
startSeq: transition.startSeq,
turn: transition.turn,
summarized: false,
@@ -149,6 +232,8 @@ function applyCompactionTransition(
}
if (transition.kind === 'summary') {
return {
compactionId: transition.compactionId,
sourceCommandId: transition.sourceCommandId,
startSeq: transition.startSeq,
turn: transition.turn,
summarized: true,
packages/compact/compact/src/types.ts
+10 -2
View File
@@ -8,6 +8,8 @@
*/
import type { ContentBlock, TokenUsage } from '@deepseek-ai/dsh-llm'
import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
import type { CompactionId } from './brand.ts'
declare module '@deepseek-ai/dsh-session' {
interface SessionEventMap {
@@ -16,7 +18,7 @@ declare module '@deepseek-ai/dsh-session' {
* `compact/end`. A numbered owner is strictly enclosed by that open turn;
* `null` identifies a standalone manual transaction between turns.
*/
'compact/start': { turn: number | null }
'compact/start': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null }
/**
* Completed summary, its inputs, and its model call facts — log-only, no surfaceOp.
* The summary content is in `data.summary`; the actual surface replacement
@@ -27,6 +29,8 @@ declare module '@deepseek-ai/dsh-session' {
* before it (`compact/prune` documents the shared protocol).
*/
'compact/summary': {
compactionId: CompactionId
sourceCommandId?: CommandId
summary: ContentBlock[]
shadowedRange: { start: number; end: number }
shadowedSeqs: number[]
@@ -62,7 +66,7 @@ declare module '@deepseek-ai/dsh-session' {
* Marks the end of a compaction — log-only, releases the lock. Its owner
* matches `compact/start`; `error` records an unsuccessful attempt.
*/
'compact/end': { turn: number | null; error?: string }
'compact/end': { compactionId: CompactionId; sourceCommandId?: CommandId; turn: number | null; error?: string }
/**
* Shadow price of one model-free prune replacement — log-only, no
* surfaceOp. The shared shadow-price protocol: a surface `replace` event
@@ -85,6 +89,10 @@ declare module '@deepseek-ai/dsh-session' {
/** Result of a successful compaction operation. */
export interface CompactionResult {
/** Stable identity shared by this compaction's complete durable lifecycle. */
compactionId: CompactionId
/** Human command that initiated this compaction, when it was manual. */
sourceCommandId?: CommandId
/** The seq of the appended `compact/start` event. */
startSeq: number
/** The seq of the appended `compact/summary` event. */
packages/compact/compact/tsconfig.json
+6
View File
@@ -8,6 +8,9 @@
"src"
],
"references": [
{
"path": "../../util/brand"
},
{
"path": "../../../vendor/cosmokit"
},
@@ -17,6 +20,9 @@
{
"path": "../../llm/llm"
},
{
"path": "../../interaction/commands"
},
{
"path": "../../core/session"
},
packages/compact/compact/tsdown.config.ts
+13
View File
@@ -0,0 +1,13 @@
import { defineConfig } from 'tsdown'
/** Builds each published entry as a self-contained file admitted by the package whitelist. */
export default defineConfig([
{
entry: ['lib/types/index.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
},
{
entry: ['lib/types/invariant.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
},
])
packages/core/tools/src/code-mode.ts
+5 -2
View File
@@ -30,7 +30,7 @@ declare module '@deepseek-ai/dsh-session' {
* with `tool/code-dispatch` by `subCallId` (timing = the two events'
* `time` fields).
*/
'tool/code-dispatch-start': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
'tool/code-dispatch-start': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown }
/**
* One bridged sub-dispatch SETTLING: the pairing ids (matching the
* `tool/code-dispatch-start` with the same `subCallId`), the tool `name`
@@ -46,7 +46,7 @@ declare module '@deepseek-ai/dsh-session' {
* before returning), so its execution-enclosure relation holds by
* construction.
*/
'tool/code-dispatch': { parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
'tool/code-dispatch': { rootCallId: CallId; parentCallId: CallId; subCallId: CallId; name: string; arguments: unknown; isError: boolean; content: ContentBlock[] }
}
}
@@ -502,6 +502,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
const subCallId = CallId(`${String(exec.callId)}:code:${n}`)
const input = {
callId: subCallId,
rootCallId: exec.rootCallId,
name,
arguments: normalized.dispatched,
...exec.agent ? { agent: exec.agent } : {},
@@ -539,6 +540,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
content: result.content,
})
agent.session.append('tool/code-dispatch', {
rootCallId: exec.rootCallId,
parentCallId: exec.callId,
subCallId,
name,
@@ -563,6 +565,7 @@ export function createRunCodeTool(registry: ToolRegistry, options: RunCodeBridge
},
async start(): Promise<void> {
exec.agent?.session.append('tool/code-dispatch-start', {
rootCallId: exec.rootCallId,
parentCallId: exec.callId,
subCallId,
name,
packages/core/tools/src/index.ts
+9
View File
@@ -297,6 +297,11 @@ export type ToolExecutionToken = symbol & { readonly [toolExecutionTokenBrand]:
*/
export interface ToolExecutionInput {
readonly callId: CallId
/**
* Root model-requested call owning this execution tree. Callers omit it for
* a root execution; nested dispatchers propagate the enclosing value.
*/
readonly rootCallId?: CallId
readonly name: string
/** Losslessly JSON-serializable parsed arguments (tools validate their own schema). */
readonly arguments: unknown
@@ -352,6 +357,8 @@ export interface CodeDispatchLog {
* observers run.
*/
export interface ToolExecution extends ToolExecutionInput {
/** Root model-requested call, resolved for every root and nested execution. */
readonly rootCallId: CallId
/** Registry-assigned identity shared with nested calls only as their opaque `parent` token. */
readonly token: ToolExecutionToken
}
@@ -1123,6 +1130,7 @@ export class ToolRegistry extends Service {
const deferredContexts: UserMessage[] = []
const token = createExecutionToken()
const callId = exec.callId
const rootCallId = exec.rootCallId ?? callId
const name = exec.name
const agent = exec.agent
const parent = exec.parent
@@ -1133,6 +1141,7 @@ export class ToolRegistry extends Service {
const base = {
token,
callId,
rootCallId,
name,
signal,
...agent !== undefined ? { agent } : {},
packages/core/tools/src/invariant.ts
+28
View File
@@ -33,9 +33,34 @@ function validateResult(
const install: InvariantInstaller = Object.assign((ctx: Context, fail: InvariantFailure) => {
const stages = new WeakMap<object, ToolStage>()
const openTurns = new WeakMap<Session, number | null>()
const dispatchRoots = new WeakMap<Session, Map<string, string>>()
const validateDispatch = (session: Session, event: SessionEvent): void => {
if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return
const root = String(event.data.rootCallId)
const parent = String(event.data.parentCallId)
const child = String(event.data.subCallId)
if (root.length === 0 || parent.length === 0 || child.length === 0) {
fail(`${event.type} must carry non-empty rootCallId, parentCallId, and subCallId`)
return
}
const roots = dispatchRoots.get(session)
const known = roots?.get(child)
if (known !== undefined && known !== root) fail(`${event.type} changed rootCallId for subCallId ${child}`)
if (parent !== root && roots?.get(parent) !== root) {
fail(`${event.type} parentCallId ${parent} does not belong to rootCallId ${root}`)
}
}
const commitDispatch = (session: Session, event: SessionEvent): void => {
if (event.type !== 'tool/code-dispatch-start' && event.type !== 'tool/code-dispatch') return
const roots = dispatchRoots.get(session) as Map<string, string>
roots.set(String(event.data.subCallId), String(event.data.rootCallId))
}
const seed = (session: Session): number | null => {
let openTurn: number | null = null
dispatchRoots.set(session, new Map())
for (const event of session.events) {
validateDispatch(session, event)
commitDispatch(session, event)
if (event.type === 'turn/start') openTurn = event.data.turn
else if (event.type === 'turn/end') openTurn = null
else if ((event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch')
@@ -51,12 +76,15 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
for (const session of ctx.sessions.list()) seed(session)
ctx.on('session/created', (session) => { seed(session) }, { global: true })
ctx.on('session/event', (session, event) => {
validateDispatch(session, event)
commitDispatch(session, event)
if (event.type === 'turn/start') openTurns.set(session, event.data.turn)
else if (event.type === 'turn/end') openTurns.set(session, null)
}, { global: true })
ctx.on('internal/dispatch', (_mode, eventName, args) => {
if (eventName === 'session/event') {
const [session, event] = args as [Session, SessionEvent]
validateDispatch(session, event)
if ((event.type === 'tool/code-dispatch-start' || event.type === 'tool/code-dispatch')
&& openTurnFor(session) === null) {
fail(`${event.type} appended outside any open turn`)
packages/interaction/commands/src/index.ts
+3 -1
View File
@@ -37,6 +37,8 @@ export interface CommandInputDescriptor {
/** Invocation passed to one registered command handler. */
export interface CommandInvocation {
/** Pairing id already written to this invocation's `command/run` event. */
readonly commandId: CommandId
/** Exact agent whose human-facing surface received the command. */
readonly agent: Agent
/** Exact text following the registered command name, including separator whitespace. */
@@ -389,7 +391,7 @@ export class CommandService extends Service {
...command.definition.recordInput === false ? {} : { args: parsed.rawInput },
source: { kind: 'user' },
})
const invocation = Object.freeze({ agent, rawInput: parsed.rawInput, signal })
const invocation = Object.freeze({ commandId, agent, rawInput: parsed.rawInput, signal })
let result: CommandResult
try {
const output = command.definition.handler(invocation)
packages/llm/llm-retry/package.json
+6
View File
@@ -19,6 +19,10 @@
"types": "./lib/types/types.d.ts",
"default": "./lib/types/types.js"
},
"./brand": {
"types": "./lib/types/brand.d.ts",
"default": "./lib/types/brand.js"
},
"./package.json": "./package.json"
},
"files": [
@@ -29,6 +33,7 @@
],
"license": "BSD-3-Clause",
"peerDependencies": {
"@deepseek-ai/dsh-brand": "^0.0.1",
"@deepseek-ai/dsh-agent": "^0.0.1",
"@deepseek-ai/dsh-invariants": "^0.0.1",
"@deepseek-ai/dsh-llm": "^0.0.1",
@@ -40,6 +45,7 @@
"schemastery": "^3.18.0"
},
"devDependencies": {
"@deepseek-ai/dsh-brand": "workspace:^",
"@cordisjs/plugin-include": "workspace:^",
"@cordisjs/plugin-loader": "workspace:^",
"@deepseek-ai/dsh-agent": "workspace:^",
packages/llm/llm-retry/src/brand.ts
+13
View File
@@ -0,0 +1,13 @@
import type { Branded } from '@deepseek-ai/dsh-brand'
/** Stable identity shared by every attempt in one request-step retry chain. */
export type RetryId = Branded<'RetryId'>
/**
* Brand an implementation-minted retry-chain identity.
* @param id - opaque retry identity.
* @returns the same string, branded; no validation is performed.
*/
export function RetryId(id: string): RetryId {
return id as RetryId
}
packages/llm/llm-retry/src/index.ts
+14 -22
View File
@@ -5,39 +5,26 @@
* @module @deepseek-ai/dsh-llm-retry
*/
import { randomUUID } from 'node:crypto'
import type { Context, Events } from 'cordis'
import z from 'schemastery'
import type { Agent, RequestErrorAction } from '@deepseek-ai/dsh-agent'
import type { LlmFailure, ResolvedRetryPolicy } from '@deepseek-ai/dsh-llm'
import type { SessionEvent } from '@deepseek-ai/dsh-session'
import { RetryId } from './brand.ts'
import type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
declare module '@deepseek-ai/dsh-session' {
interface SessionEventMap {
/** Durable, non-surface record of one provider-routed retry scheduled after a failed request attempt. */
'llm/retry': {
turn: number
step: number
provider: string
mode: 'normal'
policyKey: string
retry: number
maxRetries: number
delayMs: number
failure: LlmFailure
} | {
turn: number
step: number
provider: string
mode: 'always'
policyKey: string
retry: number
delayMs: number
failure: LlmFailure
}
'llm/retry': LlmRetryEventData
/** Durable transition written after a retry wait succeeds and before the next request attempt starts. */
'llm/retry-started': LlmRetryStartedEventData
}
}
export type { LlmRetryEventData } from './types.ts'
export type { LlmRetryEventData, LlmRetryStartedEventData } from './types.ts'
export { RetryId } from './brand.ts'
export const name = 'llm-retry'
export const inject = ['agents']
@@ -139,6 +126,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
policy: ResolvedRetryPolicy,
policyKey: string,
retry: number,
retryId: RetryId,
delayMs: number,
signal: AbortSignal,
): Promise<RequestErrorAction> {
@@ -146,6 +134,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
if (fusedSignal.aborted) return
const eventData = policy.mode === 'normal'
? {
retryId,
turn,
step,
provider,
@@ -157,6 +146,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
failure,
}
: {
retryId,
turn,
step,
provider,
@@ -168,6 +158,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
}
agent.session.append('llm/retry', eventData)
if (!await cancellableDelay(delayMs, fusedSignal)) return
agent.session.append('llm/retry-started', { retryId, turn, step, retry })
return { kind: 'retry' }
}
@@ -207,6 +198,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
const previousRetry = priorPolicyRetry?.data.retry ?? 0
if (policy.mode === 'normal' && previousRetry >= policy.maxRetries) return next()
const retry = previousRetry + 1
const retryId = priorPolicyRetry?.data.retryId ?? RetryId(randomUUID())
let delayMs: number
if (failure.providerRetryAfterMs !== undefined
&& Number.isFinite(failure.providerRetryAfterMs)
@@ -221,7 +213,7 @@ export function apply(ctx: Context, config: Config = {}, internals: RetryInterna
delayMs = localDelay(policy, retry, random)
}
return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, delayMs, signal)
return backoff(agent, turn, step, failure, provider, policy, policyKey, retry, retryId, delayMs, signal)
}
const disposeListener = ctx.on('agent/request-error', (
packages/llm/llm-retry/src/invariant.ts
+36 -1
View File
@@ -47,7 +47,10 @@ function validateRetry(
event: SessionEvent<'llm/retry'>,
fail: InvariantFailure,
): void {
const { turn, step, provider, mode, policyKey, retry, delayMs } = event.data
const { retryId, turn, step, provider, mode, policyKey, retry, delayMs } = event.data
if (typeof retryId !== 'string' || retryId.length === 0) {
fail('llm/retry retryId must be a non-empty string')
}
const failure: unknown = event.data.failure
validateFailure(failure, fail)
if (!Number.isSafeInteger(retry) || retry < 1) {
@@ -110,12 +113,43 @@ function validateRetry(
if (retry !== expectedRetry) {
fail(`llm/retry retry ${retry} must equal provider policy retry ${expectedRetry}`)
}
if (priorPolicyRetry !== undefined && priorPolicyRetry.data.retryId !== retryId) {
fail('llm/retry must preserve retryId across one provider-policy chain')
}
if (priorPolicyRetry === undefined && history.some(prior =>
(prior.type === 'llm/retry' || prior.type === 'llm/retry-started')
&& prior.data.retryId === retryId)) {
fail(`llm/retry retryId ${JSON.stringify(retryId)} is already owned by another chain`)
}
}
/** Validate one wait-complete transition against its scheduled attempt. */
function validateStarted(
history: readonly SessionEvent[],
event: SessionEvent<'llm/retry-started'>,
fail: InvariantFailure,
): void {
const { retryId, turn, step, retry } = event.data
if (typeof retryId !== 'string' || retryId.length === 0) {
fail('llm/retry-started retryId must be a non-empty string')
}
const scheduled = history.findLast((prior): prior is SessionEvent<'llm/retry'> =>
prior.type === 'llm/retry' && prior.data.retryId === retryId && prior.data.retry === retry)
if (scheduled === undefined) fail('llm/retry-started pairs no prior scheduled attempt')
if (scheduled.data.turn !== turn || scheduled.data.step !== step) {
fail('llm/retry-started turn/step must match its scheduled attempt')
}
if (history.some(prior => prior.type === 'llm/retry-started'
&& prior.data.retryId === retryId && prior.data.retry === retry)) {
fail('llm/retry-started repeats one scheduled attempt')
}
}
/** Validate every retry record already present in one loaded session. */
function validateSession(session: Session, fail: InvariantFailure): void {
for (const [index, event] of session.events.entries()) {
if (event.type === 'llm/retry') validateRetry(session.events.slice(0, index), event, fail)
else if (event.type === 'llm/retry-started') validateStarted(session.events.slice(0, index), event, fail)
}
}
@@ -127,6 +161,7 @@ const install: InvariantInstaller = Object.assign((ctx: Context, fail: Invariant
if (eventName !== 'session/event') return
const [session, event] = args as [Session, SessionEvent]
if (event.type === 'llm/retry') validateRetry(session.events, event, fail)
else if (event.type === 'llm/retry-started') validateStarted(session.events, event, fail)
}, { global: true })
}, { inject: ['sessions'] })
packages/llm/llm-retry/src/types.ts
+12
View File
@@ -1,8 +1,10 @@
import type { LlmFailure } from '@deepseek-ai/dsh-llm/types'
import type { RetryId } from './brand.ts'
/** Durable payload recorded before one provider-routed model-request retry wait. */
export type LlmRetryEventData =
| {
retryId: RetryId
turn: number
step: number
provider: string
@@ -13,7 +15,9 @@ export type LlmRetryEventData =
delayMs: number
failure: LlmFailure
}
| {
retryId: RetryId
turn: number
step: number
provider: string
@@ -23,3 +27,11 @@ export type LlmRetryEventData =
delayMs: number
failure: LlmFailure
}
/** Durable transition recorded after one retry delay completes. */
export interface LlmRetryStartedEventData {
retryId: RetryId
turn: number
step: number
retry: number
}
packages/llm/llm-retry/tsconfig.json
+3
View File
@@ -8,6 +8,9 @@
"src"
],
"references": [
{
"path": "../../util/brand"
},
{
"path": "../../../vendor/cosmokit"
},