1494 lines
60 KiB
TypeScript
1494 lines
60 KiB
TypeScript
/**
|
|
* Owns subagent startup, message admission, cold resume, and execution lifetimes.
|
|
* One child lock orders input acceptance and closure; one activation map owns
|
|
* capacity, parent relationships, and resource release across all providers.
|
|
*
|
|
* @module @deepseek-ai/dsh-subagent/manager
|
|
*/
|
|
|
|
import { randomUUID } from 'node:crypto'
|
|
import { isAbsolute, resolve } from 'node:path'
|
|
import type {} from '@deepseek-ai/dsh-working-directory'
|
|
import type { Context } from '@deepseek-ai/cordis'
|
|
import type { Agent, AgentOptions, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
|
|
import { brandString } from '@deepseek-ai/dsh-brand'
|
|
import { ReasoningEffortId, contentHasImage, createUserMessage, errorChain } from '@deepseek-ai/dsh-llm'
|
|
import type { ContentBlock, MessageId, MessageSource } from '@deepseek-ai/dsh-llm'
|
|
import { SessionLogOffset } from '@deepseek-ai/dsh-session'
|
|
import type { SessionId, SessionEvent, UserMessage } from '@deepseek-ai/dsh-session'
|
|
import type { SessionPersistence } from '@deepseek-ai/dsh-session-persistence'
|
|
import type { SessionObservation, SessionQueryEngine } from '@deepseek-ai/dsh-session-query'
|
|
import type { ObjectJsonSchema } from '@deepseek-ai/dsh-tools'
|
|
import {
|
|
appendDelegatedPolicyOverrides, applyChildComposition, captureDelegatedPolicyOverrides,
|
|
childSessionMeta, resolveChildAgentOptions, resolveChildDepth,
|
|
} from './child-agent.ts'
|
|
import type { ChildComposition, DelegatedPolicyOverrides } from './child-agent.ts'
|
|
import { createAgentMessage, withContinuableReturnGuidance, createSettlementMessage } from './continuation-messages.ts'
|
|
import { assertSubagentMaxDepth } from './depth.ts'
|
|
import { foldSubagentDescriptor, snapshotSubagentDescriptor } from './descriptor.ts'
|
|
import type { SubagentDescriptorData } from './descriptor.ts'
|
|
import { establishCatalogChild, establishExternalCatalogChild } from './catalog.ts'
|
|
import { SubagentError } from './error.ts'
|
|
import { isAdjacentAgentSendMessageTool } from './internal.ts'
|
|
import type { ActivationObserver } from './lifecycle.ts'
|
|
import type {
|
|
ContinuableCreateRequest, ContinuableCreateSpec, SubagentInterruptAuthority,
|
|
SubagentActivationSpec, SubagentActivation, SubagentStartRequest, SubagentRun,
|
|
SubagentSendMessageOptions, SubagentResult, ResolvedSubagentStartRequest,
|
|
} from './types.ts'
|
|
import { attachStructuredRuntime } from './structured.ts'
|
|
import type { StructuredAttachment } from './structured.ts'
|
|
import type { SubagentDelivery } from './control-types.ts'
|
|
import { ActivationPool, ChildLock, activationAgent, captureLocalResult, observeLocalFailure, requireLocalActivation } from './activation.ts'
|
|
import type { Activation, ActivationResource, LocalActivation } from './activation.ts'
|
|
|
|
/** Inputs shared by model steering and human prompt delivery. */
|
|
type ChildDeliveryOptions =
|
|
| {
|
|
readonly delivery: 'steer'
|
|
/**
|
|
* A provided host source is preserved on the user message; omission attributes
|
|
* an adjacent-Agent message to the parent.
|
|
*/
|
|
readonly source?: MessageSource
|
|
readonly signal: AbortSignal
|
|
}
|
|
| { readonly delivery: 'queue'; readonly source: MessageSource; readonly signal: AbortSignal }
|
|
|
|
/** Package-private hooks supplied by the owning service. */
|
|
interface SubagentHost {
|
|
startExternal(name: string, request: ResolvedSubagentStartRequest): Promise<SubagentRun>
|
|
/** Resolve one provider's detached continuable-creation contribution. */
|
|
prepareContinuable(name: string, request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>
|
|
/** Build the lifecycle observer for one Activation residency epoch. */
|
|
observeActivation(provider: string, childId: SessionId, parent: Agent): ActivationObserver
|
|
}
|
|
|
|
/** Inputs shared by fresh and resumed Activation materialization. */
|
|
interface MaterializeBase {
|
|
childId: SessionId
|
|
provider: string
|
|
parent: Agent
|
|
signal: AbortSignal
|
|
delivery?: 'parent' | 'caller' | undefined
|
|
}
|
|
|
|
/** Creation inputs for a local residency or one external backend execution. */
|
|
type MaterializeInputs = MaterializeBase & (
|
|
| {
|
|
kind: 'local'
|
|
/**
|
|
* Creation inputs; absent for a cold resume, which loads the persisted
|
|
* session — including the delegation policy events a fresh creation seeded,
|
|
* so a resume never re-captures the parent's policy.
|
|
*/
|
|
create?: {
|
|
/** Absolute initial directory captured before provider preparation. */
|
|
cwd: string
|
|
seed: readonly SessionEvent[] | undefined
|
|
meta: NonNullable<CreateAgentOptions['meta']>
|
|
/** Exact parent-log prefix length inside {@link seed}. */
|
|
inheritedEventCount: SessionLogOffset
|
|
/** Policy captured at delegation: the parent's sandbox override plus the approval pin. */
|
|
delegatedPolicies: DelegatedPolicyOverrides
|
|
/** Child-owned composition record appended after the inherited marker. */
|
|
descriptor: SubagentDescriptorData
|
|
}
|
|
agentOptions: AgentOptions
|
|
composition: ChildComposition
|
|
outputSchema?: ObjectJsonSchema | undefined
|
|
}
|
|
| { kind: 'external'; start: (signal: AbortSignal) => Promise<SubagentRun> }
|
|
)
|
|
|
|
/**
|
|
* One admitted materialization and the exact live ancestry observed at its
|
|
* synchronous admission point. Retaining identities lets a scoped teardown
|
|
* keep waiting even if an intermediate Agent leaves the registry meanwhile.
|
|
*/
|
|
interface Materialization {
|
|
readonly lineage: readonly Agent[]
|
|
readonly settled: Promise<void>
|
|
readonly controller: AbortController
|
|
}
|
|
|
|
/** Residency state observed by the natural-settlement watcher. */
|
|
type SettlementState = 'closed' | 'retry' | 'wait' | 'ready'
|
|
|
|
/** Result of the final child-lock settlement decision. */
|
|
type SettlementAttempt =
|
|
| Exclude<SettlementState, 'ready'>
|
|
| { readonly done: Promise<void> }
|
|
|
|
/** Render only the safe outer message from execution or teardown failures. */
|
|
function failureMessage(error: unknown): string {
|
|
return error instanceof Error ? error.message : 'unknown teardown failure'
|
|
}
|
|
|
|
/** Own subagent requests and the resources of every live activation. */
|
|
export class SubagentManager {
|
|
/** Child session id → its live Activation. Process-local, never durable. */
|
|
private readonly resident = new Map<SessionId, Activation>()
|
|
/** Root identities retain their pool across child settlement without retaining dead roots. */
|
|
private readonly rootPools = new WeakMap<Agent, ActivationPool>()
|
|
/** Materializations admitted before drain, tracked through publication or rollback. */
|
|
private readonly materializations = new Set<Materialization>()
|
|
/** Per-child serializer shared by delivery, release, and disposal. */
|
|
private readonly locks = new ChildLock()
|
|
/** Structural Cordis owner of every Activation handle. */
|
|
private readonly ownerCtx: Context
|
|
/**
|
|
* Exact roots whose host teardown has begun, with the live lineage members
|
|
* observed under each root. Entries remain until that exact root leaves the
|
|
* Agent registry, closing admission throughout its host's teardown without
|
|
* poisoning a later same-id replacement.
|
|
*/
|
|
private readonly closingScopes = new Map<Agent, Set<Agent>>()
|
|
private draining = false
|
|
|
|
/**
|
|
* Build one manager inside the service's Agent-injected context.
|
|
* @param ctx - context providing Agents, Sessions, and teardown ownership.
|
|
* @param host - provider dispatch and lifecycle observation owned by the service.
|
|
* @param maxActiveSubagents - the current configured child capacity.
|
|
*/
|
|
constructor(
|
|
private readonly ctx: Context,
|
|
private readonly host: SubagentHost,
|
|
private readonly maxActiveSubagents: () => number,
|
|
) {
|
|
// Ordinary Cordis owner effects unwind in reverse registration order, which
|
|
// cannot express the dynamic child graph. Register the private scope's
|
|
// structural disposer FIRST and the drain SECOND, so reverse unwind invokes
|
|
// the drain before releasing the scope; a cleanup effect on the same scope
|
|
// as the Agent handles would let structural handle disposal bypass
|
|
// child-first ordering.
|
|
const scope = ctx.plugin(function activationOwner() {})
|
|
this.ownerCtx = scope.ctx
|
|
ctx.on('agent/disposed', ({ agent }) => {
|
|
this.closingScopes.delete(agent)
|
|
})
|
|
ctx.effect(function* (this: SubagentManager) {
|
|
yield scope.dispose
|
|
yield () => this.drain()
|
|
}.bind(this), 'subagents.manager()')
|
|
}
|
|
|
|
/**
|
|
* Interrupt one live continuable child's current turn under the supplied authority.
|
|
* @param targetSessionId - the durable child session id to interrupt.
|
|
* @param authority - the human parent address or exact live ancestor Agent.
|
|
*/
|
|
interrupt(
|
|
targetSessionId: SessionId,
|
|
authority: SubagentInterruptAuthority,
|
|
): void {
|
|
if (authority.kind === 'ancestor') {
|
|
const caller = authority.agent
|
|
if (this.ctx.agents.get(caller.id) !== caller) {
|
|
throw new SubagentError(
|
|
`interrupting "${targetSessionId}" requires the exact live ancestor agent`,
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
if (caller.id === targetSessionId) {
|
|
throw new SubagentError(
|
|
`agent "${caller.id}" cannot interrupt itself`,
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
}
|
|
const activation = this.resident.get(targetSessionId)
|
|
if (activation === undefined) return
|
|
if (authority.kind === 'user') {
|
|
if (activation.parent.id !== authority.parentSessionId) {
|
|
throw new SubagentError(
|
|
`subagent "${targetSessionId}" belongs to another parent session`,
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
} else if (!activation.ancestry.has(authority.agent)) {
|
|
throw new SubagentError(
|
|
`subagent "${targetSessionId}" is not a live descendant of agent "${authority.agent.id}"`,
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
// Disposal already stopped the target with a whole-Activation teardown;
|
|
// a second cancel would be a redundant signal on a closing handle.
|
|
if (activation.closing !== undefined) return
|
|
const kind = authority.kind === 'user' ? 'user' : 'parent'
|
|
if (activation.kind === 'local') {
|
|
activation.handle.agent.cancel({ kind }, { keepInbox: true })
|
|
} else {
|
|
activation.controller.abort({ kind })
|
|
// The settlement observer reports teardown failures.
|
|
void this.dispose(activation).catch(() => undefined)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Close admission, await every already-admitted materialization through
|
|
* publication or rollback, then dispose the stable live Activation graph
|
|
* child-first.
|
|
*/
|
|
async drain(): Promise<void> {
|
|
this.draining = true
|
|
for (const pending of this.materializations) pending.controller.abort()
|
|
await Promise.all([...this.materializations].map(materialization => materialization.settled))
|
|
const owned = new Set<SessionId>()
|
|
for (const activation of this.resident.values()) {
|
|
for (const child of activation.ownedChildren) owned.add(child)
|
|
}
|
|
const roots = [...this.resident.values()].filter(activation => !owned.has(activation.childId))
|
|
await this.disposeRoots(roots, 'activation(s)')
|
|
}
|
|
|
|
/**
|
|
* Join progressing child work, leaving idle parked inboxes resident.
|
|
* @param parent - exact live parent whose descendants are observed.
|
|
* @returns whether work was joined and the host must recheck parent completion.
|
|
*/
|
|
async waitForChildren(parent: Agent): Promise<boolean> {
|
|
let observed = false
|
|
while (true) {
|
|
const pending = [...this.materializations].filter(item => item.lineage.includes(parent))
|
|
const children = [...this.resident.values()].filter(item => activationAgent(item) !== parent && item.ancestry.has(parent))
|
|
observed ||= children.some(item => item.kind === 'local' && item.handle.agent.status !== 'idle')
|
|
await Promise.all(children.flatMap(item => item.kind === 'local' ? [item.handle.agent.whenIdle()] : []))
|
|
const waits: Promise<unknown>[] = pending.map(item => item.settled)
|
|
for (const item of children) {
|
|
if (item.kind === 'external' || item.closing !== undefined) {
|
|
waits.push(item.result.promise.catch(() => undefined))
|
|
continue
|
|
}
|
|
if (item.handle.agent.status !== 'idle') {
|
|
waits.push(item.handle.agent.whenIdle())
|
|
continue
|
|
}
|
|
if (item.ownedChildren.size > 0) {
|
|
// Published descendants are observed separately; preparation holds
|
|
// keep the owner pending until publication or rollback wakes it.
|
|
if ([...item.ownedChildren].some(id => !this.resident.has(id))) waits.push(item.poke.promise)
|
|
continue
|
|
}
|
|
const inbox = item.handle.agent.inbox
|
|
if (item.failureAt === undefined && (inbox.nextTurn.length > 0 || inbox.nextStep.length > 0)) continue
|
|
waits.push(Promise.race([item.result.promise.catch(() => undefined), item.poke.promise]))
|
|
}
|
|
if (waits.length > 0) {
|
|
observed = true
|
|
await Promise.all(waits)
|
|
continue
|
|
}
|
|
// A descendant can be published while whenIdle follows another child.
|
|
if ([...this.materializations].some(item => item.lineage.includes(parent) && !pending.includes(item))
|
|
|| [...this.resident.values()].some(item => activationAgent(item) !== parent
|
|
&& item.ancestry.has(parent) && !children.includes(item))) continue
|
|
return observed
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Stop the managed descendants of exact live host-owned parents.
|
|
* @param parents - exact live roots whose managed descendants must stop.
|
|
*/
|
|
async drainDescendants(parents: readonly Agent[]): Promise<void> {
|
|
const roots = new Set(parents.filter(parent => this.ctx.agents.get(parent.id) === parent))
|
|
if (roots.size === 0) return
|
|
|
|
for (const root of roots) {
|
|
this.closingMembers(root).add(root)
|
|
}
|
|
|
|
const targets: Activation[] = []
|
|
for (const activation of this.resident.values()) {
|
|
const child = activationAgent(activation)
|
|
const lineage = this.liveLineage(child ?? activation.parent)
|
|
const owners = [...roots].filter(root => child !== root
|
|
&& activation.ancestry.has(root))
|
|
if (owners.length === 0) continue
|
|
targets.push(activation)
|
|
for (const owner of owners) {
|
|
const members = this.closingMembers(owner)
|
|
if (child !== undefined) members.add(child)
|
|
for (const agent of lineage) members.add(agent)
|
|
}
|
|
}
|
|
const materializations = [...this.materializations].filter((materialization) => {
|
|
const owners = [...roots].filter(root => materialization.lineage.includes(root))
|
|
for (const owner of owners) {
|
|
const members = this.closingMembers(owner)
|
|
for (const agent of materialization.lineage) members.add(agent)
|
|
}
|
|
if (owners.length > 0) materialization.controller.abort()
|
|
return owners.length > 0
|
|
})
|
|
|
|
const ownedTargets = new Set<SessionId>()
|
|
for (const activation of targets) {
|
|
for (const child of activation.ownedChildren) ownedTargets.add(child)
|
|
}
|
|
const targetRoots = targets.filter(activation => !ownedTargets.has(activation.childId))
|
|
|
|
for (const activation of targets) {
|
|
const disposal = this.dispose(activation)
|
|
void disposal.catch(() => undefined)
|
|
}
|
|
|
|
await Promise.all(materializations.map(materialization => materialization.settled))
|
|
await this.disposeRoots(targetRoots, 'scoped activation(s)')
|
|
}
|
|
|
|
/**
|
|
* Release selected resident direct children of one exact live parent.
|
|
* @param parent - exact live direct parent authorizing the selected release.
|
|
* @param childIds - durable direct-child ids to release when resident.
|
|
*/
|
|
async drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void> {
|
|
if (this.ctx.agents.get(parent.id) !== parent) {
|
|
throw new SubagentError('selected child teardown requires the exact live parent agent', 'UNAUTHORIZED')
|
|
}
|
|
const targets: Activation[] = []
|
|
for (const childId of new Set(childIds)) {
|
|
const activation = this.resident.get(childId)
|
|
if (activation === undefined) continue
|
|
if (activation.parent.id !== parent.id || !activation.ancestry.has(parent)) {
|
|
throw new SubagentError(
|
|
`subagent "${childId}" is not a direct child of agent "${parent.id}"`,
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
targets.push(activation)
|
|
}
|
|
|
|
for (const activation of targets) {
|
|
const disposal = this.dispose(activation)
|
|
void disposal.catch(() => undefined)
|
|
}
|
|
await this.disposeRoots(targets, 'selected activation(s)')
|
|
}
|
|
|
|
/**
|
|
* Start one continuable background child and resolve at initial inbox acceptance.
|
|
* Every earlier failure disposes any created handle and rolls back Activation
|
|
* and parent ownership without returning either id.
|
|
* @param spec - provider, delegation request, and caller cancellation.
|
|
* @returns the durable child id and accepted initial prompt message id.
|
|
*/
|
|
async startLocal(spec: SubagentActivationSpec): Promise<SubagentActivation & { messageId: MessageId }> {
|
|
const request = spec.request
|
|
const parent = request.parent
|
|
this.assertAdmitting(parent)
|
|
const persistence = spec.delivery === 'caller' ? this.ctx.get('sessionPersistence') : this.requirePersistence()
|
|
assertSubagentMaxDepth(request.maxDepth)
|
|
const childId = spec.childId ?? brandString<SessionId>(randomUUID())
|
|
this.assertChildIdAvailable(childId)
|
|
const childDepth = resolveChildDepth(parent, request.maxDepth)
|
|
// Snapshot before any await: invalid descriptor JSON rejects the call
|
|
// before a child exists, and the detached value is what reaches the log.
|
|
const agentOptions = resolveChildAgentOptions(parent, request.agentOptions, childDepth)
|
|
const agentProvider = agentOptions.provider
|
|
const agentModel = agentOptions.model
|
|
const agentReasoningEffort = agentOptions.reasoningEffort
|
|
const descriptor = snapshotSubagentDescriptor({
|
|
mode: 'continuable',
|
|
provider: spec.provider,
|
|
label: spec.label,
|
|
...agentProvider !== undefined ? { agentProvider } : {},
|
|
...agentModel !== undefined ? { agentModel } : {},
|
|
...agentReasoningEffort !== undefined ? { agentReasoningEffort } : {},
|
|
})
|
|
// Capture before the first await: a later parent switch belongs to the
|
|
// parent's future, not to this child.
|
|
const delegatedPolicies = captureDelegatedPolicyOverrides(parent)
|
|
|
|
// An idle continuation-managed parent must not settle while a caller is
|
|
// still creating its child. A turn-scoped delegation does not need this,
|
|
// but the service is also callable outside a turn.
|
|
const releaseHold = this.holdOwnership(parent, childId)
|
|
try {
|
|
const cwd = await this.resolveDirectory(request, spec.signal)
|
|
const prepared = await this.host.prepareContinuable(spec.provider, {
|
|
sessionId: childId,
|
|
cwd,
|
|
parent,
|
|
signal: spec.signal,
|
|
})
|
|
spec.signal.throwIfAborted()
|
|
this.assertAdmitting(parent)
|
|
|
|
const inheritedEventCount = SessionLogOffset(prepared.seed?.length ?? 0)
|
|
const seed = prepared.seed
|
|
let established!: Activation
|
|
const messageId = await this.locks.run(childId, async () => {
|
|
spec.signal.throwIfAborted()
|
|
this.assertAdmitting(parent)
|
|
this.assertChildIdAvailable(childId)
|
|
if (spec.childId !== undefined) {
|
|
const persisted = await persistence?.stat(childId, { signal: spec.signal })
|
|
spec.signal.throwIfAborted()
|
|
this.assertAdmitting(parent)
|
|
this.assertChildIdAvailable(childId)
|
|
if (persisted !== undefined) {
|
|
throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD')
|
|
}
|
|
}
|
|
const activation = await this.materialize({
|
|
kind: 'local',
|
|
childId,
|
|
provider: spec.provider,
|
|
parent,
|
|
create: {
|
|
cwd,
|
|
seed,
|
|
meta: childSessionMeta(parent, childDepth, prepared.seed !== undefined, request.agentPreset),
|
|
inheritedEventCount,
|
|
delegatedPolicies,
|
|
descriptor,
|
|
},
|
|
agentOptions,
|
|
composition: { agentPreset: request.agentPreset },
|
|
signal: spec.signal,
|
|
delivery: spec.delivery,
|
|
outputSchema: spec.request.outputSchema,
|
|
})
|
|
established = activation
|
|
const child = requireLocalActivation(activation).handle.agent
|
|
const childHeader = child.session.header
|
|
return await this.submitMaterialized(
|
|
activation,
|
|
spec.delivery !== 'caller' && isAdjacentAgentSendMessageTool(this.ctx.get('tools')?.get('send_message', child))
|
|
? withContinuableReturnGuidance(parent.id, request.prompt)
|
|
: request.prompt,
|
|
{ source: { kind: 'user' }, signal: spec.signal, delivery: 'queue' },
|
|
parent,
|
|
() => {
|
|
establishCatalogChild(parent.session, childHeader, descriptor)
|
|
},
|
|
)
|
|
})
|
|
return { ...this.receipt(established), childId, messageId }
|
|
} catch (error: unknown) {
|
|
releaseHold()
|
|
throw error
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Start an external backend under activation ownership.
|
|
* @param spec - task, provider, cancellation, and delivery policy.
|
|
* @returns the accepted activation and its result/disposal capabilities.
|
|
*/
|
|
async startExternal(spec: SubagentActivationSpec): Promise<SubagentActivation> {
|
|
const parent = spec.request.parent
|
|
this.assertAdmitting(parent)
|
|
const pendingId = brandString<SessionId>(randomUUID())
|
|
const releaseHold = this.holdOwnership(parent, pendingId)
|
|
let activation: Activation | undefined
|
|
try {
|
|
const cwd = await this.resolveDirectory(spec.request, spec.signal)
|
|
activation = await this.materialize({
|
|
kind: 'external',
|
|
childId: pendingId,
|
|
provider: spec.provider,
|
|
parent,
|
|
signal: spec.signal,
|
|
delivery: spec.delivery,
|
|
start: signal => this.host.startExternal(spec.provider, {
|
|
...spec.request, cwd, label: spec.label, signal,
|
|
}),
|
|
})
|
|
this.assertAdmitting(parent)
|
|
this.assertLiveParent(parent, activation.childId)
|
|
spec.signal.throwIfAborted()
|
|
if (spec.delivery === 'parent') {
|
|
establishExternalCatalogChild(parent.session, activation.childId, spec.label)
|
|
}
|
|
this.announce(activation)
|
|
return this.receipt(activation)
|
|
} catch (error: unknown) {
|
|
if (activation !== undefined) {
|
|
try {
|
|
await this.dispose(activation)
|
|
} catch (cleanupError: unknown) {
|
|
this.ctx.logger.warn(`subagent "${activation.childId}" admission rollback failed: ${failureMessage(cleanupError)}`)
|
|
}
|
|
}
|
|
throw error
|
|
} finally {
|
|
releaseHold()
|
|
}
|
|
}
|
|
|
|
/** Capture the explicit or inherited directory while the parent still owns startup. */
|
|
private async resolveDirectory(request: Pick<SubagentStartRequest, 'parent' | 'cwd'>, signal: AbortSignal): Promise<string> {
|
|
const cwd = request.cwd !== undefined && isAbsolute(request.cwd)
|
|
? request.cwd
|
|
: resolve(await this.ctx.workingDirectory.ensure(request.parent, signal), request.cwd ?? '.')
|
|
signal.throwIfAborted()
|
|
return cwd
|
|
}
|
|
|
|
/**
|
|
* Deliver one model-authored message to a direct continuable child or to the
|
|
* sender's direct parent. A missing direct child cold-resumes through the
|
|
* ordinary continuation lifecycle.
|
|
* @param sender - exact live Agent authorizing and originating the message.
|
|
* @param targetId - durable direct-parent or direct-child session id.
|
|
* @param content - model-authored content to deliver.
|
|
* @param options - caller cancellation before acceptance.
|
|
* @returns the accepted message's inbox id.
|
|
*/
|
|
async sendMessage(
|
|
sender: Agent,
|
|
targetId: SessionId,
|
|
content: ContentBlock[],
|
|
options: SubagentSendMessageOptions,
|
|
): Promise<MessageId> {
|
|
if (this.ctx.agents.get(sender.id) !== sender) {
|
|
throw new SubagentError(
|
|
'message delivery requires the exact live sender agent',
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
this.assertAdmitting(sender)
|
|
const senderActivation = this.resident.get(sender.id)
|
|
if (senderActivation !== undefined
|
|
&& senderActivation.kind === 'local'
|
|
&& senderActivation.handle.agent === sender
|
|
&& senderActivation.parent.id === targetId) {
|
|
options.signal.throwIfAborted()
|
|
return this.sendToParent(senderActivation, sender, content)
|
|
}
|
|
if (sender.session.header.parentSession === targetId) {
|
|
throw new SubagentError(
|
|
`agent "${sender.id}" is not a resident continuable child and cannot send to parent "${targetId}"`,
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
return this.deliverToChild(sender, targetId, content, {
|
|
signal: options.signal,
|
|
delivery: 'steer',
|
|
})
|
|
}
|
|
|
|
/**
|
|
* Queue one human-authored prompt as a distinct direct-child turn.
|
|
* @param parent - exact live direct parent authorizing delivery.
|
|
* @param childId - durable direct-child session id.
|
|
* @param content - model-visible prompt blocks.
|
|
* @param source - durable attribution for the human prompt.
|
|
* @param signal - caller cancellation before inbox acceptance.
|
|
* @returns the accepted durable message id.
|
|
*/
|
|
async queuePrompt(
|
|
parent: Agent,
|
|
childId: SessionId,
|
|
content: ContentBlock[],
|
|
source: MessageSource,
|
|
signal: AbortSignal,
|
|
): Promise<MessageId> {
|
|
return this.deliverToChild(parent, childId, content, { source, signal, delivery: 'queue' })
|
|
}
|
|
|
|
/**
|
|
* Steer one host-authored prompt to a direct continuable child.
|
|
* @param parent - exact live direct parent authorizing delivery.
|
|
* @param childId - durable direct-child session id.
|
|
* @param content - model-visible prompt blocks.
|
|
* @param source - durable attribution for the host prompt.
|
|
* @param signal - caller cancellation before inbox acceptance.
|
|
* @returns the accepted durable message id.
|
|
*/
|
|
async steerPrompt(
|
|
parent: Agent,
|
|
childId: SessionId,
|
|
content: ContentBlock[],
|
|
source: MessageSource,
|
|
signal: AbortSignal,
|
|
): Promise<MessageId> {
|
|
return this.deliverToChild(parent, childId, content, { source, signal, delivery: 'steer' })
|
|
}
|
|
|
|
/** Admit local input synchronously before any teardown can begin. */
|
|
private deliver(activation: Activation, message: UserMessage, delivery: SubagentDelivery): void {
|
|
if (activation.closing !== undefined) {
|
|
throw new SubagentError(
|
|
'subagent activation is being disposed; the message was not accepted',
|
|
'ACTIVATION_CLOSING',
|
|
)
|
|
}
|
|
const local = requireLocalActivation(activation)
|
|
if (local.structured?.acceptsInput() === false) {
|
|
throw new SubagentError('subagent is submitting or has submitted its structured result; the message was not accepted', 'INPUT_CLOSED')
|
|
}
|
|
if (delivery === 'steer') local.handle.agent.steer(message)
|
|
else local.handle.agent.followup(message)
|
|
}
|
|
|
|
/**
|
|
* Reject one child identity already owned by a live Agent or Session.
|
|
* @param childId - proposed durable child session id.
|
|
*/
|
|
private assertChildIdAvailable(childId: SessionId): void {
|
|
if (this.resident.has(childId) || this.ctx.agents.get(childId) !== undefined || this.ctx.get('sessions')?.get(childId) !== undefined) {
|
|
throw new SubagentError(`subagent "${childId}" already exists`, 'DUPLICATE_CHILD')
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Pre-register `childId` in a continuation-managed parent's owned set so the
|
|
* parent cannot settle while a caller is still establishing or resuming that
|
|
* child. Returns a releaser for the failure path; it removes only a hold
|
|
* this call added, and leaves ownership in place once a live Activation for
|
|
* the child exists.
|
|
* @param parent - the live direct parent the operation is admitted under.
|
|
* @param childId - the durable child the operation addresses.
|
|
* @returns the failure-path releaser; a no-op when nothing was added.
|
|
*/
|
|
private holdOwnership(parent: Agent, childId: SessionId): () => void {
|
|
const parentActivation = this.resident.get(parent.id)
|
|
if (parentActivation === undefined || activationAgent(parentActivation) !== parent) return () => {}
|
|
if (parentActivation.closing !== undefined) {
|
|
throw new SubagentError(
|
|
`subagent parent "${parent.id}" is being disposed; the child was not established`,
|
|
'ACTIVATION_CLOSING',
|
|
)
|
|
}
|
|
if (parentActivation.ownedChildren.has(childId)) return () => {}
|
|
parentActivation.ownedChildren.add(childId)
|
|
return () => {
|
|
const live = this.resident.get(childId)
|
|
/* v8 ignore next 4 -- reaching this arm needs another delivery to establish the child
|
|
* between this operation's failure and its releaser running, which no test can schedule
|
|
* deterministically: the ownership edge then belongs to that live Activation, so the
|
|
* conservative keep leaves it for finishDisposal's releaseOwnership. */
|
|
if (live !== undefined && live.closing === undefined) return
|
|
if (parentActivation.ownedChildren.delete(childId)) this.wake(parentActivation)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Apply activation admission to a resident parent before delivering input.
|
|
* @param parent - exact live Agent receiving the message.
|
|
* @param message - durable user message to deliver.
|
|
* @param delivery - receiving inbox destination.
|
|
*/
|
|
private sendWaking(parent: Agent, message: UserMessage, delivery: SubagentDelivery): void {
|
|
const parentActivation = this.resident.get(parent.id)
|
|
if (parentActivation !== undefined && activationAgent(parentActivation) === parent) {
|
|
try {
|
|
this.deliver(parentActivation, message, delivery)
|
|
} finally {
|
|
this.wake(parentActivation)
|
|
}
|
|
return
|
|
}
|
|
if (delivery === 'steer') parent.steer(message)
|
|
else parent.followup(message)
|
|
}
|
|
|
|
/**
|
|
* Reject new admission once the manager or this exact parent tree began draining.
|
|
* @param agent - exact live Agent whose lineage determines admission.
|
|
*/
|
|
private assertAdmitting(agent: Agent): void {
|
|
const closing = this.closingTeardownFor(agent)
|
|
if (closing === undefined) return
|
|
throw new SubagentError(
|
|
closing === 'manager'
|
|
? 'subagents are draining; the operation was not admitted'
|
|
: `subagents below parent "${closing.id}" are draining; the operation was not admitted`,
|
|
'DRAINING',
|
|
)
|
|
}
|
|
|
|
/**
|
|
* Authorize one operation against the durable direct-parent lineage.
|
|
* @param parent - exact live Agent claiming direct-parent authority.
|
|
* @param childId - durable child session id addressed by the operation.
|
|
* @param parentSession - durable direct-parent id recorded by the child.
|
|
*/
|
|
private authorizeLineage(
|
|
parent: Agent,
|
|
childId: SessionId,
|
|
parentSession: SessionId | undefined,
|
|
): void {
|
|
this.assertLiveParent(parent, childId)
|
|
if (parentSession !== parent.id) {
|
|
throw new SubagentError(`subagent "${childId}" belongs to another parent session`, 'UNAUTHORIZED')
|
|
}
|
|
}
|
|
|
|
/** Reject parent authority after the live registry entry changes. */
|
|
private assertLiveParent(parent: Agent, childId: SessionId): void {
|
|
if (this.ctx.agents.get(parent.id) !== parent) {
|
|
throw new SubagentError(
|
|
`subagent "${childId}" delivery requires the exact live parent agent`,
|
|
'UNAUTHORIZED',
|
|
)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Create or resume one child Agent and publish its Activation.
|
|
* @param inputs - reconstruction and admission inputs for the residency epoch.
|
|
* @returns the published process-local Activation.
|
|
*/
|
|
private materialize(inputs: MaterializeInputs): Promise<Activation> {
|
|
this.assertAdmitting(inputs.parent)
|
|
inputs.signal.throwIfAborted()
|
|
const lineage = this.liveLineage(inputs.parent)
|
|
const pool = this.resident.get(inputs.parent.id)?.pool ?? this.rootPool(inputs.parent)
|
|
const releaseSlot = pool.reserve(this.maxActiveSubagents())
|
|
const settled = Promise.withResolvers<void>()
|
|
const controller = new AbortController()
|
|
const materialization: Materialization = {
|
|
lineage,
|
|
settled: settled.promise,
|
|
controller,
|
|
}
|
|
this.materializations.add(materialization)
|
|
return this.materializeTracked(
|
|
{ ...inputs, signal: AbortSignal.any([inputs.signal, controller.signal]) }, lineage, pool, releaseSlot,
|
|
).catch((error: unknown) => {
|
|
releaseSlot()
|
|
if (error instanceof Error && error.name === 'AbortError') this.assertAdmitting(inputs.parent)
|
|
throw error
|
|
}).finally(() => {
|
|
this.materializations.delete(materialization)
|
|
settled.resolve()
|
|
})
|
|
}
|
|
|
|
/**
|
|
* Stop and release one Activation through its memoized close transaction.
|
|
* @param activation - exact residency epoch to close.
|
|
* @returns the shared close transaction.
|
|
*/
|
|
private dispose(activation: Activation): Promise<void> {
|
|
return this.close(activation, () => this.finishDisposal(activation, true))
|
|
}
|
|
|
|
/** Close admission synchronously and share one release, including startup rollback. */
|
|
private close(activation: Activation, release: () => Promise<void>): Promise<void> {
|
|
if (activation.closing !== undefined) return activation.closing
|
|
const completion = Promise.withResolvers<void>()
|
|
activation.closing = completion.promise
|
|
void release().then(completion.resolve, completion.reject)
|
|
return completion.promise
|
|
}
|
|
|
|
/** Dispose independent roots and report every branch failure after all settle. */
|
|
private async disposeRoots(
|
|
roots: readonly Activation[],
|
|
failureSubject: 'activation(s)' | 'scoped activation(s)' | 'selected activation(s)',
|
|
): Promise<void> {
|
|
const failures = await Promise.all(roots.map(async (activation) => {
|
|
try {
|
|
await this.dispose(activation)
|
|
return undefined
|
|
} catch (error: unknown) {
|
|
return error
|
|
}
|
|
}))
|
|
const reasons = failures.filter(failure => failure !== undefined)
|
|
if (reasons.length > 0) {
|
|
throw new SubagentError(
|
|
`subagent teardown failed for ${reasons.length} ${failureSubject}: `
|
|
+ reasons.map(reason => failureMessage(reason)).join('; '),
|
|
'ACTIVATION_TEARDOWN_FAILED',
|
|
)
|
|
}
|
|
}
|
|
|
|
/** Return the retained member set for one exact scoped-teardown root. */
|
|
private closingMembers(root: Agent): Set<Agent> {
|
|
const existing = this.closingScopes.get(root)
|
|
if (existing !== undefined) return existing
|
|
const members = new Set<Agent>()
|
|
this.closingScopes.set(root, members)
|
|
return members
|
|
}
|
|
|
|
/** Return the exact currently resolvable ancestry from `agent` upward. */
|
|
private liveLineage(agent: Agent): Agent[] {
|
|
const lineage = [agent]
|
|
const seen = new Set<SessionId>([agent.id])
|
|
let parentSession = agent.session.header.parentSession
|
|
while (parentSession !== undefined) {
|
|
const parent = this.ctx.agents.get(parentSession)
|
|
if (parent === undefined || seen.has(parent.id)) break
|
|
lineage.push(parent)
|
|
seen.add(parent.id)
|
|
parentSession = parent.session.header.parentSession
|
|
}
|
|
return lineage
|
|
}
|
|
|
|
/** Return the teardown that closed continuable admission for this agent's lineage. */
|
|
private closingTeardownFor(agent: Agent): Agent | 'manager' | undefined {
|
|
if (this.draining) return 'manager'
|
|
const lineage = this.liveLineage(agent)
|
|
for (const [root, members] of this.closingScopes) {
|
|
if (members.has(agent) || lineage.includes(root)) return root
|
|
}
|
|
return undefined
|
|
}
|
|
|
|
/** Resolve a root's pool once; descendants inherit their resident parent's pool directly. */
|
|
private rootPool(parent: Agent): ActivationPool {
|
|
let pool = this.rootPools.get(parent)
|
|
if (pool === undefined) {
|
|
pool = new ActivationPool()
|
|
this.rootPools.set(parent, pool)
|
|
}
|
|
return pool
|
|
}
|
|
|
|
/** Perform one tracked materialization through publication or rollback. */
|
|
private async materializeTracked(
|
|
inputs: MaterializeInputs,
|
|
parentLineage: readonly Agent[],
|
|
pool: ActivationPool,
|
|
releaseSlot: () => void,
|
|
): Promise<Activation> {
|
|
const { provider, parent } = inputs
|
|
let childId = inputs.childId
|
|
inputs.signal.throwIfAborted()
|
|
let resource: ActivationResource
|
|
if (inputs.kind === 'external') {
|
|
const controller = new AbortController()
|
|
const cancelStartup = (): void => { controller.abort(inputs.signal.reason) }
|
|
inputs.signal.addEventListener('abort', cancelStartup, { once: true })
|
|
try {
|
|
const run = await inputs.start(controller.signal)
|
|
resource = { kind: 'external', run, controller }
|
|
void run.result.catch(() => undefined)
|
|
childId = run.id
|
|
try { this.assertChildIdAvailable(childId) } catch (error: unknown) {
|
|
await run.dispose()
|
|
throw error
|
|
}
|
|
} finally {
|
|
inputs.signal.removeEventListener('abort', cancelStartup)
|
|
}
|
|
} else {
|
|
const { create } = inputs
|
|
let structured: StructuredAttachment | undefined
|
|
const setup = async (childCtx: Context, child: Agent): Promise<void> => {
|
|
// Only fresh creation appends the descriptor and delegated policy after
|
|
// the inherited marker; a cold resume replays those persisted events.
|
|
if (inputs.composition.agentPreset !== undefined) {
|
|
await applyChildComposition(childCtx, parent, inputs.composition)
|
|
}
|
|
if (create !== undefined) {
|
|
if (inputs.composition.agentPreset !== undefined) {
|
|
child.session.append('agent-preset/selected', { agentPreset: inputs.composition.agentPreset })
|
|
}
|
|
child.session.append('subagent/descriptor', create.descriptor)
|
|
appendDelegatedPolicyOverrides(child.session, create.delegatedPolicies)
|
|
const workingDirectory = childCtx.get('workingDirectory')
|
|
if (workingDirectory === undefined) throw new Error('local subagents require the working-directory service')
|
|
await workingDirectory.set(child, create.cwd, inputs.signal)
|
|
}
|
|
if (inputs.composition.agentPreset === undefined) await applyChildComposition(childCtx, parent, inputs.composition)
|
|
if (inputs.outputSchema !== undefined) {
|
|
structured = attachStructuredRuntime(childCtx, inputs.outputSchema, () =>
|
|
this.resident.get(childId)?.ownedChildren.size === 0
|
|
&& child.inbox.nextStep.length === 0
|
|
&& child.inbox.nextTurn.length === 0,
|
|
)
|
|
}
|
|
}
|
|
const handle = create === undefined
|
|
? await this.ownerCtx.agents.resume({
|
|
resumeSessionId: childId,
|
|
parentAgent: parent,
|
|
agentOptions: inputs.agentOptions,
|
|
signal: inputs.signal,
|
|
setup,
|
|
})
|
|
: await this.ownerCtx.agents.create({
|
|
sessionId: childId,
|
|
parentAgent: parent,
|
|
meta: create.meta,
|
|
...(create.seed === undefined ? {} : { seed: create.seed }),
|
|
inheritedEventCount: create.inheritedEventCount,
|
|
agentOptions: inputs.agentOptions,
|
|
signal: inputs.signal,
|
|
setup,
|
|
})
|
|
|
|
resource = { kind: 'local', handle, outputStart: handle.agent.session.seq, structured, failureAt: undefined, poke: Promise.withResolvers<void>() }
|
|
}
|
|
const observer = this.host.observeActivation(provider, childId, parent)
|
|
|
|
const activation: Activation = {
|
|
pool,
|
|
releaseSlot,
|
|
childId,
|
|
...resource,
|
|
parent,
|
|
delivery: inputs.delivery ?? 'parent',
|
|
result: Promise.withResolvers<SubagentResult>(),
|
|
closing: undefined,
|
|
ancestry: new WeakSet(resource.kind === 'external' ? parentLineage : [resource.handle.agent, ...parentLineage]),
|
|
ownedChildren: new Set(),
|
|
observer,
|
|
announced: false,
|
|
}
|
|
void activation.result.promise.catch(() => undefined)
|
|
this.resident.set(childId, activation)
|
|
try {
|
|
this.assertAdmitting(parent)
|
|
inputs.signal.throwIfAborted()
|
|
if (this.ctx.agents.get(parent.id) !== parent) throw new SubagentError('subagent parent is no longer live', 'UNAUTHORIZED')
|
|
this.acquireOwnership(parent, childId)
|
|
const wakeSettlement = (): void => { this.wake(activation) }
|
|
if (activation.kind === 'local') {
|
|
observeLocalFailure(activation, wakeSettlement)
|
|
activation.handle.agent.ctx.on('agent/inbox/inserted', wakeSettlement)
|
|
activation.handle.agent.ctx.on('agent/inbox/claimed', wakeSettlement)
|
|
activation.handle.agent.ctx.on('agent/inbox/discarded', wakeSettlement)
|
|
}
|
|
observer.start(activationAgent(activation))
|
|
} catch (error: unknown) {
|
|
/* v8 ignore next -- rollback failure must not mask the admission failure
|
|
* that prevented this operation from returning an accepted message id. */
|
|
await this.rollbackUnpublished(activation, error).catch(() => undefined)
|
|
throw error
|
|
}
|
|
return activation
|
|
}
|
|
|
|
/**
|
|
* Begin settlement observation after initial acceptance is recorded.
|
|
* @param activation - accepted activation to observe.
|
|
*/
|
|
private announce(activation: Activation): void {
|
|
if (activation.announced) return
|
|
activation.announced = true
|
|
if (activation.kind === 'local') {
|
|
this.watchLocalSettlement(activation)
|
|
} else {
|
|
const finish = (): Promise<void> => this.close(activation, () => this.finishDisposal(activation, false))
|
|
void activation.run.result.then(finish, finish).catch((error: unknown) => { this.reportTeardownFailure(activation, error) })
|
|
}
|
|
}
|
|
|
|
/** Release an Activation whose start edge was not published. */
|
|
private rollbackUnpublished(activation: Activation, error: unknown): Promise<void> {
|
|
return this.close(activation, async () => {
|
|
try {
|
|
await (activation.kind === 'local' ? activation.handle.dispose() : activation.run.dispose())
|
|
} finally {
|
|
this.resident.delete(activation.childId)
|
|
activation.releaseSlot()
|
|
this.releaseOwnership(activation.childId)
|
|
activation.result.reject(error)
|
|
}
|
|
})
|
|
}
|
|
|
|
/** Register the child in a continuation-managed parent's owned set. */
|
|
private acquireOwnership(parent: Agent, childId: SessionId): void {
|
|
const parentActivation = this.resident.get(parent.id)
|
|
if (parentActivation === undefined) return
|
|
if (parentActivation.closing !== undefined) {
|
|
throw new SubagentError(
|
|
`subagent parent "${parent.id}" is being disposed; the child was not established`,
|
|
'ACTIVATION_CLOSING',
|
|
)
|
|
}
|
|
parentActivation.ownedChildren.add(childId)
|
|
this.wake(parentActivation)
|
|
}
|
|
|
|
/** Remove one child from its live owner's set and let that owner re-check settlement. */
|
|
private releaseOwnership(childId: SessionId): void {
|
|
for (const candidate of this.resident.values()) {
|
|
if (candidate.ownedChildren.delete(childId)) this.wake(candidate)
|
|
}
|
|
}
|
|
|
|
/** Let a settlement watcher re-check residency after relevant state changes. */
|
|
private wake(activation: Activation): void {
|
|
if (activation.kind === 'external') return
|
|
activation.poke.resolve()
|
|
activation.poke = Promise.withResolvers<void>()
|
|
}
|
|
|
|
/** Follow one Activation to natural settlement. */
|
|
private watchLocalSettlement(activation: LocalActivation): void {
|
|
void (async () => {
|
|
while (true) {
|
|
const idleObservation = activation.poke
|
|
await activation.handle.agent.whenIdle()
|
|
if (activation.closing !== undefined) return
|
|
const readiness = await this.locks.run(activation.childId, () => Promise.resolve(
|
|
this.settlementState(activation, idleObservation),
|
|
))
|
|
if (readiness === 'closed') return
|
|
if (readiness === 'retry') continue
|
|
if (readiness === 'wait') {
|
|
await idleObservation.promise
|
|
continue
|
|
}
|
|
|
|
const finalSeq = activation.handle.agent.session.seq
|
|
await this.flushFinalState(activation)
|
|
const attempt = await this.locks.run<SettlementAttempt>(activation.childId, () => {
|
|
const state = this.settlementState(activation, idleObservation)
|
|
if (state !== 'ready') return Promise.resolve(state)
|
|
if (activation.handle.agent.session.seq !== finalSeq) {
|
|
return Promise.resolve('retry')
|
|
}
|
|
let done!: Promise<void>
|
|
try {
|
|
void activation.handle.agent.runMaintenance(() => {
|
|
done = this.close(activation, () => this.finishDisposal(activation, false))
|
|
return Promise.resolve()
|
|
})
|
|
} catch (_error: unknown) {
|
|
// Another activity already owns the Agent's idle phase.
|
|
return Promise.resolve('retry')
|
|
}
|
|
return Promise.resolve({ done })
|
|
})
|
|
|
|
if (typeof attempt === 'string') {
|
|
if (attempt === 'closed') return
|
|
continue
|
|
}
|
|
try {
|
|
await attempt.done
|
|
} catch (error: unknown) {
|
|
this.reportTeardownFailure(activation, error)
|
|
}
|
|
return
|
|
}
|
|
})()
|
|
}
|
|
|
|
/** Report disposal failure once after the natural settlement observer finishes. */
|
|
private reportTeardownFailure(activation: Activation, error: unknown): void {
|
|
this.ctx.logger.warn(`subagent "${activation.childId}" activation teardown failed: ${failureMessage(error)}`)
|
|
}
|
|
|
|
/** Check pending input and owned children before closing admission. */
|
|
private settlementState(
|
|
activation: LocalActivation,
|
|
observation: PromiseWithResolvers<void>,
|
|
): SettlementState {
|
|
if (activation.closing !== undefined) return 'closed'
|
|
if (activation.poke !== observation) return 'retry'
|
|
const inbox = activation.handle.agent.inbox
|
|
if (activation.ownedChildren.size > 0) return 'wait'
|
|
if (activation.failureAt === undefined && (inbox.nextTurn.length > 0 || inbox.nextStep.length > 0)) return 'wait'
|
|
return 'ready'
|
|
}
|
|
|
|
/** Propagate stop synchronously and await descendant startup rollback before release. */
|
|
private async finishDisposal(activation: Activation, stop: boolean): Promise<void> {
|
|
this.wake(activation)
|
|
const { childId } = activation
|
|
const failures: SubagentError[] = []
|
|
let result: SubagentResult = { output: [], stopReason: 'error' }
|
|
let resultFailure: { error: unknown } | undefined
|
|
let externalDisposal: Promise<void> | undefined
|
|
const child = activationAgent(activation)
|
|
const detail = (error: unknown): string => child === undefined
|
|
? failureMessage(error)
|
|
: errorChain(error)
|
|
try {
|
|
if (activation.kind === 'external') {
|
|
if (stop) {
|
|
activation.controller.abort({ kind: 'parent' })
|
|
// Some backends settle their result only when disposal begins.
|
|
externalDisposal = Promise.resolve().then(() => activation.run.dispose())
|
|
void externalDisposal.catch(() => undefined)
|
|
}
|
|
result = await activation.run.result
|
|
} else {
|
|
if (stop) {
|
|
activation.handle.agent.cancel({ kind: 'parent' })
|
|
const idle = activation.handle.agent.whenIdle()
|
|
const children = [...activation.ownedChildren]
|
|
.map(child => this.resident.get(child))
|
|
.filter((child): child is Activation => child !== undefined)
|
|
const pending = [...this.materializations].filter(item => item.lineage.includes(activation.handle.agent))
|
|
const childDisposals = children.map(child => this.dispose(child))
|
|
for (const item of pending) item.controller.abort()
|
|
childDisposals.push(...pending.map(item => item.settled))
|
|
const childFailures = await Promise.all(childDisposals.map(async (disposal) => {
|
|
try {
|
|
await disposal
|
|
return undefined
|
|
} catch (error: unknown) {
|
|
return error
|
|
}
|
|
}))
|
|
const reasons = childFailures.filter(reason => reason !== undefined)
|
|
if (reasons.length > 0) {
|
|
failures.push(new SubagentError(
|
|
`subagent "${childId}" child teardown failed: ${reasons.map(reason => failureMessage(reason)).join('; ')}`,
|
|
'ACTIVATION_TEARDOWN_FAILED',
|
|
))
|
|
}
|
|
await idle
|
|
await this.flushFinalState(activation)
|
|
}
|
|
result = captureLocalResult(activation)
|
|
}
|
|
} catch (error: unknown) {
|
|
resultFailure = { error }
|
|
failures.push(new SubagentError(
|
|
`subagent "${childId}" activation teardown failed: ${detail(error)}`,
|
|
'ACTIVATION_TEARDOWN_FAILED',
|
|
{ cause: error },
|
|
))
|
|
}
|
|
try {
|
|
if (activation.kind === 'local') await activation.handle.dispose()
|
|
else await (externalDisposal ?? activation.run.dispose())
|
|
} catch (error: unknown) {
|
|
failures.push(new SubagentError(
|
|
`subagent "${childId}" activation handle disposal failed: ${detail(error)}`,
|
|
'ACTIVATION_TEARDOWN_FAILED',
|
|
{ cause: error },
|
|
))
|
|
}
|
|
|
|
let failure: SubagentError | undefined
|
|
if (failures.length === 1) {
|
|
failure = failures[0]
|
|
} else if (failures.length > 1) {
|
|
failure = new SubagentError(
|
|
`subagent "${childId}" activation teardown failed at ${failures.length} boundaries: `
|
|
+ failures.map(item => detail(item)).join('; '),
|
|
'ACTIVATION_TEARDOWN_FAILED',
|
|
{ cause: new AggregateError(failures) },
|
|
)
|
|
}
|
|
this.resident.delete(childId)
|
|
activation.releaseSlot()
|
|
const terminal: SubagentResult = failure === undefined ? result : { output: [], stopReason: 'error' }
|
|
this.notifySettlement(activation, result)
|
|
this.releaseOwnership(childId)
|
|
activation.observer.settle(terminal)
|
|
if (resultFailure === undefined) activation.result.resolve(result)
|
|
else activation.result.reject(resultFailure.error)
|
|
if (failure !== undefined) throw failure
|
|
}
|
|
|
|
/** Deliver the captured execution result to the durable direct parent after cleanup. */
|
|
private notifySettlement(activation: Activation, terminal: SubagentResult): void {
|
|
if (!activation.announced || activation.delivery === 'caller') return
|
|
try {
|
|
const parent = this.ctx.agents.get(activation.parent.id)
|
|
if (parent !== activation.parent) return
|
|
const message = createSettlementMessage(
|
|
activation.childId, terminal, activationAgent(activation) !== undefined,
|
|
)
|
|
if (this.closingTeardownFor(parent) !== undefined) {
|
|
parent.inject(message)
|
|
return
|
|
}
|
|
this.sendWaking(parent, message, parent.status === 'idle' ? 'queue' : 'steer')
|
|
} catch (error: unknown) {
|
|
this.ctx.logger.warn(
|
|
`subagent "${activation.childId}" settlement notice was not delivered to its parent: `
|
|
+ errorChain(error),
|
|
)
|
|
}
|
|
}
|
|
|
|
/** Request a best-effort final session flush before closing natural-settlement admission. */
|
|
private async flushFinalState(activation: LocalActivation): Promise<void> {
|
|
try {
|
|
await activation.handle.agent.ctx.sessions.flush(activation.handle.agent.session)
|
|
} catch (error: unknown) {
|
|
this.ctx.logger.warn(
|
|
`subagent "${activation.childId}" best-effort final session flush failed; `
|
|
+ `the persisted state may be unavailable or stale on resume: ${errorChain(error)}`,
|
|
)
|
|
}
|
|
}
|
|
|
|
/** Return capabilities bound to an exact activation instead of a future same-id instance. */
|
|
private receipt(activation: Activation): SubagentActivation {
|
|
return {
|
|
childId: activation.childId,
|
|
result: activation.result.promise,
|
|
dispose: () => this.dispose(activation),
|
|
}
|
|
}
|
|
|
|
/** Route one parent-originated delivery through residency and cold resume. */
|
|
private async deliverToChild(
|
|
parent: Agent,
|
|
childId: SessionId,
|
|
content: ContentBlock[],
|
|
options: ChildDeliveryOptions,
|
|
): Promise<MessageId> {
|
|
this.assertAdmitting(parent)
|
|
const releaseHold = this.holdOwnership(parent, childId)
|
|
try {
|
|
return await this.deliverFollowup(parent, childId, content, options)
|
|
} catch (error: unknown) {
|
|
releaseHold()
|
|
throw error
|
|
}
|
|
}
|
|
|
|
/** The delivery loop behind {@link deliverToChild}, run under the parent hold. */
|
|
private async deliverFollowup(
|
|
parent: Agent,
|
|
childId: SessionId,
|
|
content: ContentBlock[],
|
|
options: ChildDeliveryOptions,
|
|
): Promise<MessageId> {
|
|
while (true) {
|
|
const live = await this.locks.run(childId, async () => {
|
|
const activation = this.resident.get(childId)
|
|
if (activation === undefined) return this.coldResume(parent, childId, content, options)
|
|
requireLocalActivation(activation)
|
|
const disposal = activation.closing
|
|
/* v8 ignore next 3 -- the send-versus-dispose cutoff needs a delivery to
|
|
* observe the transaction inside the same critical section that opened it. */
|
|
if (disposal !== undefined) {
|
|
return disposal.then(() => undefined, () => undefined)
|
|
}
|
|
if (contentHasImage(content)) {
|
|
await this.assertImageCapable(requireLocalActivation(activation).handle.agent, options.signal)
|
|
if (activation.closing !== undefined) {
|
|
await Promise.allSettled([activation.closing])
|
|
return undefined
|
|
}
|
|
}
|
|
const messageId = this.submitAdmitted(activation, content, options, parent)
|
|
this.announce(activation)
|
|
return messageId
|
|
})
|
|
/* v8 ignore start -- only a delivery that lost the disposal cutoff retries. */
|
|
if (live !== undefined) return live
|
|
this.assertAdmitting(parent)
|
|
options.signal.throwIfAborted()
|
|
/* v8 ignore stop */
|
|
}
|
|
}
|
|
|
|
/** Deliver one resident continuable child's message to its live direct parent. */
|
|
private sendToParent(
|
|
activation: Activation,
|
|
sender: Agent,
|
|
content: ContentBlock[],
|
|
): MessageId {
|
|
/* v8 ignore next 6 -- only synchronous re-entrant teardown can open this
|
|
* transaction between exact-agent authorization and this no-await span. */
|
|
if (activation.closing !== undefined) {
|
|
throw new SubagentError(
|
|
`subagent "${sender.id}" activation is being disposed; the message was not delivered`,
|
|
'ACTIVATION_CLOSING',
|
|
)
|
|
}
|
|
const parent = this.ctx.agents.get(activation.parent.id)
|
|
if (parent !== activation.parent) {
|
|
throw new SubagentError(
|
|
'direct parent is not live; the message was not delivered',
|
|
'PARENT_UNAVAILABLE',
|
|
)
|
|
}
|
|
const message = createAgentMessage(sender, content)
|
|
this.sendAgentMessage(parent, message)
|
|
return message.id
|
|
}
|
|
|
|
/** Send one Agent message while translating only the target's own rejection. */
|
|
private sendAgentMessage(
|
|
parent: Agent,
|
|
message: ReturnType<typeof createUserMessage>,
|
|
): void {
|
|
try {
|
|
this.sendWaking(parent, message, 'steer')
|
|
} catch (error: unknown) {
|
|
throw new SubagentError(
|
|
'direct parent is not live; the message was not delivered',
|
|
'PARENT_UNAVAILABLE',
|
|
{ cause: error },
|
|
)
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Cold-resume a persisted child and submit the waiting turn. The descriptor
|
|
* supplies every reconstruction input; no subagent provider is dispatched.
|
|
*/
|
|
private async coldResume(
|
|
parent: Agent,
|
|
childId: SessionId,
|
|
content: ContentBlock[],
|
|
options: ChildDeliveryOptions,
|
|
): Promise<MessageId> {
|
|
const query = this.requireSessionQuery()
|
|
let observation: SessionObservation
|
|
try {
|
|
observation = await query.observeSession(childId, {
|
|
signal: options.signal,
|
|
})
|
|
} catch (error: unknown) {
|
|
options.signal.throwIfAborted()
|
|
throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error })
|
|
}
|
|
using source = observation
|
|
this.assertAdmitting(parent)
|
|
this.authorizeLineage(parent, childId, source.header.parentSession)
|
|
const ownEvents = source.events.slice(source.inheritedEventCount)
|
|
const descriptor = foldSubagentDescriptor(ownEvents)
|
|
if (descriptor === undefined || descriptor.mode !== 'continuable') {
|
|
throw new SubagentError(
|
|
`subagent "${childId}" has no supported continuation state and cannot be resumed; choose a different target`,
|
|
'NOT_RESUMABLE',
|
|
)
|
|
}
|
|
let activation: Activation
|
|
try {
|
|
const independentlySelected = hasIndependentPresetSelection(ownEvents)
|
|
const agentPreset = independentlySelected ? source.projections?.values.agentPreset : undefined
|
|
if (independentlySelected && typeof agentPreset !== 'string') {
|
|
throw new SubagentError(`subagent "${childId}" has no agent preset projection for restoration`, 'NOT_RESUMABLE')
|
|
}
|
|
activation = await this.materialize({
|
|
kind: 'local',
|
|
childId,
|
|
provider: descriptor.provider,
|
|
parent,
|
|
agentOptions: {
|
|
...descriptor.agentProvider !== undefined ? { provider: descriptor.agentProvider } : {},
|
|
...descriptor.agentModel !== undefined ? { model: descriptor.agentModel } : {},
|
|
...descriptor.agentReasoningEffort !== undefined
|
|
? { reasoningEffort: ReasoningEffortId(descriptor.agentReasoningEffort) }
|
|
: {},
|
|
},
|
|
composition: { agentPreset: agentPreset ?? undefined, persona: descriptor.persona, toolFilter: descriptor.toolFilter },
|
|
signal: options.signal,
|
|
})
|
|
} catch (error: unknown) {
|
|
options.signal.throwIfAborted()
|
|
if (error instanceof SubagentError) throw error
|
|
throw new SubagentError(`subagent "${childId}" is unavailable`, 'NOT_RESUMABLE', { cause: error })
|
|
}
|
|
return await this.submitMaterialized(activation, content, options, parent)
|
|
}
|
|
|
|
/** Admit a materialized child, commit its creation fact, and release it on failure. */
|
|
private async submitMaterialized(
|
|
activation: Activation,
|
|
content: ContentBlock[],
|
|
options: ChildDeliveryOptions,
|
|
parent: Agent,
|
|
commit?: () => void,
|
|
): Promise<MessageId> {
|
|
try {
|
|
if (contentHasImage(content)) {
|
|
await this.assertImageCapable(requireLocalActivation(activation).handle.agent, options.signal)
|
|
if (activation.closing !== undefined) {
|
|
throw new SubagentError(`subagent "${activation.childId}" is closing`, 'ACTIVATION_CLOSING')
|
|
}
|
|
}
|
|
const messageId = this.submitAdmitted(activation, content, options, parent)
|
|
commit?.()
|
|
this.announce(activation)
|
|
return messageId
|
|
} catch (error: unknown) {
|
|
try {
|
|
await this.dispose(activation)
|
|
} catch (cleanupError: unknown) {
|
|
this.ctx.logger.warn(
|
|
`subagent continuation: disposal after admission or catalog append failure also failed: ${String(cleanupError)}`,
|
|
)
|
|
}
|
|
throw error
|
|
}
|
|
}
|
|
|
|
/** Build and submit one message across the final synchronous admission cutoff. */
|
|
private submitAdmitted(
|
|
activation: Activation,
|
|
content: ContentBlock[],
|
|
options: ChildDeliveryOptions,
|
|
parent: Agent,
|
|
): MessageId {
|
|
const message = options.source === undefined
|
|
? createAgentMessage(parent, content)
|
|
: createUserMessage({ content, source: options.source })
|
|
options.signal.throwIfAborted()
|
|
this.assertAdmitting(parent)
|
|
this.authorizeLineage(parent, activation.childId, activation.parent.id)
|
|
this.acquireOwnership(parent, activation.childId)
|
|
try {
|
|
this.deliver(activation, message, options.delivery)
|
|
} finally {
|
|
this.wake(activation)
|
|
}
|
|
return message.id
|
|
}
|
|
|
|
/** Refuse image content for a child whose fixed model accepts text only. */
|
|
private async assertImageCapable(
|
|
agent: Agent,
|
|
signal: AbortSignal,
|
|
): Promise<void> {
|
|
const { provider, model } = agent.options
|
|
if (provider === undefined || model === undefined) return
|
|
const llm = this.ctx.get('llm')
|
|
/* v8 ignore next -- without an LLM registry, delivery defers to projection. */
|
|
if (llm === undefined) return
|
|
const info = await llm.resolveModelInfo(provider, model, signal)
|
|
if (info.inputModalities !== undefined && !info.inputModalities.includes('image')) {
|
|
throw new SubagentError(
|
|
`Model "${model}" does not support image input.`,
|
|
'MODEL_DOES_NOT_SUPPORT_IMAGES',
|
|
)
|
|
}
|
|
}
|
|
|
|
/** Resolve the persistence service continuable children require, or fail loud. */
|
|
private requirePersistence(): SessionPersistence {
|
|
const persistence = this.ctx.get('sessionPersistence')
|
|
if (persistence === undefined) {
|
|
throw new SubagentError(
|
|
'continuable subagents require session persistence (load a dsh-session-persistence backend)',
|
|
'PERSISTENCE_UNAVAILABLE',
|
|
)
|
|
}
|
|
return persistence
|
|
}
|
|
|
|
/** Resolve the Session query service used for cold child observations. */
|
|
private requireSessionQuery(): SessionQueryEngine {
|
|
const query = this.ctx.get('sessionQuery')
|
|
if (query === undefined) {
|
|
throw new SubagentError(
|
|
'continuable subagents require session query (load @deepseek-ai/dsh-session-query)',
|
|
'CONTINUATION_UNAVAILABLE',
|
|
)
|
|
}
|
|
return query
|
|
}
|
|
}
|
|
|
|
export default SubagentManager
|
|
|
|
/** Creation-time selection precedes the own descriptor; historical forks can select after it. */
|
|
function hasIndependentPresetSelection(events: readonly SessionEvent[]): boolean {
|
|
for (const event of events) {
|
|
if (event.type === 'subagent/descriptor') return false
|
|
if (event.type === 'agent-preset/selected') return true
|
|
}
|
|
/* v8 ignore next -- coldResume rejects logs without a supported own descriptor before this lookup. */
|
|
return false
|
|
}
|