Files
deepseek-harness/packages/subagent/subagent/src/manager.ts
T

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
}