30 KiB
30 KiB
Subagents
English | 中文
The unified activation API manages local conversations and external executions.
Capabilities and activation requests
Every backend uses startActivation. Capability flags validate request options; prepareContinuable selects the local driver, while start selects one external execution. The model-facing tool uses parent delivery. Workflow and code mode consumers can await caller results without injecting another parent message. Historical children with unavailable descriptors remain discoverable as mode: 'unknown' without granting continuation capabilities; the package README defines catalog persistence.
/**
* Start-time options supported by a registered backend. The manager checks
* every requested option before preparing a local child or starting an external
* execution. depthLimit controls maxDepth; the remaining flag names match
* SubagentStartRequest fields.
*/
interface SubagentCapabilities {
readonly agentOptions: boolean
readonly outputSchema: boolean
readonly depthLimit: boolean
readonly toolFilter: boolean
readonly persona: boolean
}
/** One managed child execution and its result delivery policy. */
interface SubagentActivationSpec {
/** Registered backend to use. */
readonly provider: string
/** Short task label retained in the parent catalog. */
readonly label: string
/** Optional reserved identity for a local child; external backends allocate their own ids. */
readonly childId?: SessionId
/** Task, parent, and backend-supported execution options. */
readonly request: Omit<SubagentStartRequest, 'label' | 'signal'>
/** Cancellation before publication; callers own later cancellation through dispose. */
readonly signal: AbortSignal
/** Parent-model notification or a program-owned result. */
readonly delivery: 'parent' | 'caller'
}
/** A managed execution; disposal addresses this exact activation, never a later resume. */
interface SubagentActivation {
/** Stable identity of the child. */
readonly childId: SessionId
/** Accepted inbox message, when the backend has a local inbox. */
readonly messageId?: MessageId
/** Execution result, independently of eventual resource release. */
readonly result: Promise<SubagentResult>
/** Stop and release this activation and its owned descendants. */
dispose(): Promise<void>
}
/**
* Task and optional capabilities supplied to a backend. startActivation carries
* these fields in request while owning its label, cancellation, and delivery
* policy separately.
*/
interface SubagentStartRequest {
/** Optional short display label persisted with a session-backed child. */
readonly label?: string
/** Content delivered as the child's user message. */
readonly prompt: ContentBlock[]
/**
* The spawning agent. In-process providers derive workspace, lineage, and
* delegation depth from its durable session state. ACP reads only its cwd,
* and only when no deployment `cwd` override is configured.
*/
readonly parent: Agent
/**
* Cancellation signal from the spawning context (the tool's `exec.signal`).
* This is the canonical cancellation channel both before and after startup:
* a provider rejects `start()` after cleaning partial resources when it
* fires before the run is published, and cancels the published run's
* remaining turn work when it fires afterward.
*/
readonly signal: AbortSignal
/**
* Optional host-Agent provider, model, reasoning-effort, and output-token
* overrides. Requires {@link SubagentCapabilities.agentOptions}; in-process
* providers merge them over the parent Agent's options when they create the
* child, while the DSH SDK provider merges them over its instance defaults
* before initializing the separate child runtime.
*/
readonly agentOptions?: AgentOptions
/**
* Object-rooted JSON Schema within `assertObjectJsonSchema`'s enforced subset. Start rejects
* unsupported schemas or providers without the capability. Data must be plain host-realm JSON;
* a successful child returns the matching value as {@link SubagentResult.structured}.
*/
readonly outputSchema?: ObjectJsonSchema
/**
* Optional absolute delegation-depth cap for the child being started: its
* computed depth must be less than or equal to this non-negative safe
* integer. Requires {@link SubagentCapabilities.depthLimit}; rejected at
* start otherwise.
*/
readonly maxDepth?: number
/**
* Optional child tool scoping. Requires {@link SubagentCapabilities.toolFilter};
* rejected at start otherwise. In-process backends apply it as a scoped
* `tools.restrict()` in the child's creation window: the named tools vanish
* from the child's prompt AND refuse to execute (one visibility), with loud
* unknown-name validation.
*/
readonly toolFilter?: ToolRestriction
/**
* Optional per-child persona. Requires {@link SubagentCapabilities.persona};
* rejected at start otherwise. In-process backends register it as a scoped
* `deployment:persona-prefix` section on the child, SHADOWING the deployment's
* persona for this child alone — same template semantics as the deployment
* persona (strict `{{…}}` interpolation against the registered variables).
*/
readonly persona?: string
}
Local children and activations
A local child has a durable Session and at most one live activation. The manager reserves identity and capacity, prepares the child through its backend, and owns input admission, cold resume, and child-first disposal. A result can settle before resources are released; callers await dispose for cleanup. Structured capture closes input for that activation; a later cold resume does not inherit the output schema.
/**
* What the continuation manager asks a provider for while materializing one
* continuable child's FIRST activation. The manager has already reserved the
* durable child identity and owns every later operation, so this request
* carries only what distinguishes a fresh child from one seeded with parent
* history.
*/
interface ContinuableCreateRequest {
/** The reserved durable child session id, for provider diagnostics. */
readonly sessionId: SessionId
/** The delegating parent agent whose history a seeding provider reads. */
readonly parent: Agent
/**
* Caller cancellation, which owns preparation only until the manager accepts
* the initial prompt into the child's inbox.
*/
readonly signal: AbortSignal
}
/**
* A provider's detached contribution to one continuable child's creation. This
* is DATA, never a capability: it carries no Agent, `AgentHandle`, prompt
* delivery, result, disposal, or resume operation, because the continuation
* manager owns the child's whole lifecycle after preparation.
*/
interface ContinuableCreateSpec {
/**
* Completed-turn prefix of the parent's log to seed the child session with,
* or absent for a fresh child. Same durable contract as
* `CreateAgentOptions.seed`: contiguous from seq 0, lossless JSON, balanced.
*/
readonly seed?: readonly SessionEvent[]
}
Messages and interruption
sendMessage authorizes the exact live sender and permits only adjacent local agents. Running children receive steering input; absent continuable children resume from persistence. External executions reject follow-ups. Local children report their content through send_message; their parent receives an automatic status-only settlement notice. External executions automatically report their final text, structured result, diagnostic, and status. caller delivery suppresses these notices. drainDescendants and drainChildren await owned work teardown for both drivers.
/** Durable attribution for one model-authored message between adjacent Agents. */
interface AgentMessageSource {
readonly kind: 'agent-message'
/** A message another agent addressed to this one (`relay` context form). */
readonly form: 'relay'
/** Session id of the Agent whose tool call produced the message. */
readonly senderSessionId: SessionId
}
/**
* Durable attribution for the runtime's own account of a continuable child
* settling. Deliberately a different kind from
* {@link AgentMessageSource}: an Agent message is content the sender chose,
* while this message is the manager stating what became of the child, and a
* transcript that merged them would credit the child with words it never wrote.
*/
interface SubagentSettledMessageSource {
readonly kind: 'subagent-settled'
/** A runtime account shown without expanding the row (`notice` context form). */
readonly form: 'notice'
/** One-line account of how the child ended. */
readonly summary: string
/** Session id of the child that settled. */
readonly senderSessionId: SessionId
}
/** Options for one model-authored message between adjacent Agents. */
interface SubagentSendMessageOptions {
/** Caller cancellation, owning the operation only until inbox acceptance. */
readonly signal: AbortSignal
}
/**
* Authority under which one interrupt request is admitted. `user` carries the
* durable direct-parent address a human client presented; `ancestor` carries
* the exact live Agent object whose recorded lineage must contain the caller.
*/
type SubagentInterruptAuthority =
| { readonly kind: 'user'; readonly parentSessionId: SessionId }
| { readonly kind: 'ancestor'; readonly agent: Agent }
Durable enumeration
listChildren reads the parent-owned catalog. listDescendants combines Session corpus identity with parent catalogs, including external leaves beneath ordinary Sessions. External one-shot entries carry external: true and cannot open a child Session or accept follow-ups. Catalog entries record membership at creation without execution status. Complete results go to the caller or the parent completion notice. list_agents exposes only continuable children with running or inactive activity; see the control tool for its scopes and diagnostics.
/**
* One entry of a descendant listing: the interpreted subagent facts plus its
* position in the complete session tree. `parentId` is the durable direct
* parent from the enumerated header, and `depth` counts edges from the root.
*/
type SubagentDescendantListEntry = SubagentListEntry & {
/** Durable direct parent of this candidate in the enumerated tree. */
readonly parentId: SessionId
/** Edge distance from the requested root; direct children are `1`. */
readonly depth: number
}
Results and backend handles
SubagentResult is available to program consumers. The external driver retains the backend handle until disposal completes. A cleanup failure does not overwrite an already returned result; the parent log retains that output and records the final failure status. Backend-owned diagnostics must satisfy the safe-detail requirements below.
/**
* The terminal outcome of a subagent run, resolved by {@link SubagentRun.result}.
*/
interface SubagentResult {
/**
* The child's final assistant output is the content of its last non-empty
* assistant message. Empty-content messages, including usage-only messages,
* are skipped. Without a non-empty message, the output is its accumulated
* assistant text stream, or `[]` when the child produced neither.
*/
readonly output: readonly ContentBlock[]
/**
* The structured result after a requested `outputSchema` was successfully
* satisfied. Requesting a schema does not guarantee presence: a provider can
* end with `stopReason: 'error'` when the child fails or finishes without a
* valid capture. The structured value is validated against the requested
* output schema by the provider; `unknown` here because the seam is
* schema-agnostic.
*/
readonly structured?: unknown
/**
* Provider-authored, non-assistant failure detail for a non-`completed`
* result. Providers keep this text free of tool inputs, file contents,
* environment values, credentials, and raw protocol payloads, and limit it
* to 4096 UTF-8 bytes. Consumers present it separately from {@link output}.
*/
readonly diagnostic?: string
/** Why the run ended. A non-`completed` reason means `output` may be partial. */
readonly stopReason: SubagentStopReason
}
/**
* Why a subagent run ended. Merge-extensible (a backend may add variants);
* consumers branch on the known cases and fall through `default`. The known
* cases mirror the harness turn-end vocabulary so the tool layer can map a
* non-`completed` result to an `isError` tool result.
*/
interface SubagentStopReasonMap {
/** The child finished its turn normally. */
completed: 'completed'
/** Cancelled through the request signal or disposal. */
aborted: 'aborted'
/** Model or transport failure. */
error: 'error'
/** The child hit its token ceiling before finishing. */
'max-tokens': 'max-tokens'
/** The child declined the task. */
refusal: 'refusal'
}
/**
* Backend execution handle owned by the external activation driver.
* A result may become available before resource release; the manager always
* disposes the handle and awaits cleanup. Backend startup failures clean up
* partial resources before rejecting, while accepted execution failures settle
* through result.
*/
interface SubagentRun {
/** Provider-minted run id, unique in the parent namespace. */
readonly id: SessionId
/**
* Resolves with the child's terminal {@link SubagentResult} when the run
* settles. Does NOT reject on a child-level failure — a model/transport
* failure resolves with `stopReason: 'error'` so the consumer maps it to an
* `isError` tool result. Rejects on an infrastructure fault the seam cannot
* represent as a stop reason.
*/
readonly result: Promise<SubagentResult>
/**
* Cancel remaining work, reach child quiescence, and release resources.
* Idempotent.
*/
dispose(): Promise<void>
}
The provider contract: SubagentProvider
Spawn and Fork contribute detached creation inputs to the local driver. Codex, Claude Code, ACP, and DSH SDK contribute one execution handle to the external driver; they do not gain multiple turns. Both paths share admission, capacity, parent ownership, cancellation, and disposal. The package reference describes composition and deployment requirements.
/**
* One registered transport for running child agents. Providers are trusted
* same-process implementations; callers treat descriptors and returned values
* as borrowed immutable data. The service may call one provider concurrently
* for distinct children. Providers isolate operation-local mutable state; a
* shared capacity controller may delay an operation but must not couple its
* settlement or cleanup to a sibling.
*/
interface SubagentProvider {
/** Unique registry name (e.g. `spawn`, `fork`, `acp`). */
readonly name: string
/** The start-time features this provider supports (see {@link SubagentCapabilities}). */
readonly capabilities: SubagentCapabilities
/**
* Whether the child sees the parent's completed-turn prefix. This is descriptive, not a
* service-validated start capability: the model-facing tool derives truthful wording from it.
* It says nothing about tool registration, injected services, or authority inheritance.
*/
readonly inheritsParentContext: boolean
/**
* Optional static provider-owned provider/model route for child Agent
* options. Consumers merge tool/model overrides over these values before
* preflight; providers whose route derives from the parent omit it. The value
* is detached immutable data and requires `agentOptions` support.
*/
readonly agentRouteDefaults?: Readonly<{ provider: string; model: string }>
/**
* Establish one external execution and return its owned handle.
* The service has already validated that every requested start-time
* capability is supported. Before fulfillment, the provider owns setup and
* cleans any unpublished partial resources before rejecting. Ownership transfers on
* fulfillment; subsequent turn or infrastructure failure settles through
* the returned run. Distinct starts may overlap; cancellation, failure,
* result settlement, and disposal remain independent for each run.
*/
start?(request: SubagentStartRequest): Promise<SubagentRun>
/**
* OPTIONAL (continuable-creation capability): contribute the detached
* creation inputs that distinguish this provider's continuable children —
* only whether the child session is seeded with parent history. Method
* presence selects local activation execution. Providers without it execute
* through start and do not accept subsequent messages.
*
* This is the provider's ONLY participation in a continuable child. The
* continuation manager owns identity reservation, composition, Agent
* creation, prompt delivery, cold resume, ownership, and disposal, so a
* provider never sees the child's Agent, handle, turns, or teardown.
* Distinct preparations may overlap; each follows its own signal and returns
* data belonging only to `request.sessionId`.
*/
prepareContinuable?(request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>
}
Cordis API
Generated from source by scripts/gen-cordis-catalog.ts (verified fresh by pnpm run verify-cordis-catalog in doc-sync; regenerate with pnpm run gen-cordis-catalog) — the language sides differ only in locale-specific paired document paths. Signature blocks use a ts cordis-catalog fence and keep the original source JSDoc; dispatch modes are defined in the primer, and the framework-inherited ctx API lives in cordis-api/inherited.md.
ctx.subagentModelSelection — SubagentModelSelectionConfig
Singleton settings owner read when delegation tools are composed for a Session.
/**
* Read a detached selection preference for the next eligible Session composition.
* @returns the enabled state and exact allowed routes.
*/
current(): SubagentModelSelectionSettings
Source: packages/subagent/tool-subagent/src/model-selection-settings.ts
ctx.subagents — SubagentRuntime
Named provider registry with managed activations, durable discovery, and local child messaging.
/**
* Resolve a delegation tool's depth policy against the current user setting.
* @param configured - Explicit tool limit, or provider-managed for external delegation.
* @returns The numeric limit, or undefined when the provider owns depth enforcement.
*/
resolveMaxDepth(configured?: number | 'provider-managed'): number | undefined
/**
* Start a local child under its reserved identity.
* @param spec - local task, reserved child id, and result recipient.
* @returns activation with its accepted initial message id.
*/
startActivation(spec: SubagentActivationSpec & { readonly childId: SessionId }): Promise<SubagentActivation & { readonly messageId: MessageId }>
/**
* Start a local or external child.
* @param spec - task, backend, and result recipient.
* @returns activation with a message id only for local children.
*/
startActivation(spec: SubagentActivationSpec): Promise<SubagentActivation>
/**
* Wait for this live parent's currently owned child work without cancelling it.
* @param parent - the exact parent whose descendants should settle.
* @returns whether any work was observed; hosts recheck parent idle after true.
*/
async waitForChildren(parent: Agent): Promise<boolean>
/**
* Steer one model-authored message to the sender's direct parent or direct
* continuable child. A running target admits it at the nearest step boundary;
* an idle target starts a turn, and an absent direct child cold-resumes from
* persistence. The service derives durable sender attribution from the exact
* live sender. Caller cancellation stops only pre-acceptance work.
* @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 inbox acceptance.
* @returns the accepted message's inbox id.
* @throws when continuation services are unavailable, adjacency is rejected,
* or the message was not admitted.
*/
async sendMessage( sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions, ): Promise<MessageId>
/**
* Interrupt one live child's current execution under a human parent
* address or an exact live ancestor Agent. Fire-and-return: the cancel
* signal is issued before this returns, but the target may keep running
* until it observes the signal. Unclaimed pending inbox work, the Activation,
* and published descendants are preserved; claimed work is not requeued.
* Once the interrupted driver is idle, a waking send resumes the parked FIFO
* queue. External backends stop their single execution. An absent target
* is an accepted no-op, as is a manager-less composition, which cannot own a
* live Activation.
* @param targetSessionId - the durable child session id to interrupt.
* @param authority - the human parent address or exact live ancestor Agent.
* @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
* live target.
*/
interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void
/**
* Close subagent admission below exact live parent Agents, stop only their
* visible descendant Activations synchronously, then await admitted scoped
* materializations and release those forests child-first. The scoped cutoff
* lasts until each exact parent leaves the registry; unrelated parent trees
* remain live.
* @param parents - exact host-owned parent Agents entering teardown.
* @returns once every retained descendant activation released its driver.
* @throws an aggregate error after all branches settle when any failed.
*/
async drainDescendants(parents: readonly Agent[]): Promise<void>
/**
* Release selected resident direct children of one exact live
* parent. Other children of the same parent remain admitted and resident.
* Absent targets and a manager-less composition are accepted no-ops.
* @param parent - exact live direct parent authorizing the selected release.
* @param childIds - durable direct-child ids to release when resident.
* @returns once every selected activation released its driver.
* @throws {SubagentError} `UNAUTHORIZED` when a resident target belongs to a
* different parent or the supplied parent identity is stale.
*/
async drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>
/**
* Read the parent's durable direct-child catalog without loading or resuming an Agent.
* The service owns and releases the live-preferred Session observation.
* @param parentSessionId - parent whose direct children are requested.
* @param signal - cancellation forwarded to the Session query.
* @returns catalog children in parent event order.
* @throws {@link SubagentError} when query or catalog projection is unavailable.
* @throws SessionQueryError when the parent cannot be read or the query is cancelled.
*/
async listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentCatalogEntry[]>
/**
* Enumerate the root's complete session-backed subagent tree in stable
* pre-order from one live-preferred corpus, without loading or resuming an
* Agent. Ordinary sessions and one-shot children remain traversal nodes so
* continuable descendants below them are discovered; each returned entry
* adds its durable `parentId` and root-relative `depth`. Identity resolution,
* diagnostics, optional persistence, and cancellation use the registered
* child identity projection and complete Session corpus.
* @param rootSessionId - session whose complete descendant tree is listed.
* @param signal - caller-owned cancellation forwarded to persistence reads
* and observed around every read await.
* @returns children and per-candidate diagnostics with tree position, in
* stable pre-order.
* @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
*/
async listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>
/**
* Deliver one browser-authored message to a continuable child through the
* exact live direct parent, retaining the caller-minted request identity and
* validated browser zone on the accepted message. Success identifies the
* message the child's inbox accepted; later execution is independent of this
* call. Queue delivery targets a later turn; steer delivery targets the
* nearest step and retains the Agent loop's best-effort fallback semantics.
* Image parts are admitted and persisted through the attachment store
* before delivery, and the child's model must accept image input.
* Cold resume at capacity rejects with `subagent/delivery-unavailable`.
* @param request - durable address, delivery, minted identity, content, and optional browser zone.
* @param signal - carrier cancellation, owning the call until inbox acceptance.
* @returns the accepted message's inbox identity.
* @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
* `subagent/invalid-time-zone`, `subagent/parent-unavailable`,
* `subagent/not-resumable`, `subagent/unauthorized`,
* `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
*/
@Remote('prompt') async prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>
/**
* Remote face of {@link interrupt} under one durable parent address. No
* catalog, history, persistence, or parent Agent lookup runs: the core
* primitive alone authorizes the address against the live Activation, which
* is what keeps a live child interruptible while its parent Agent is offline.
* Absent, idle, and already-completed targets are accepted no-ops there.
* @param childSessionId - durable child session id to interrupt.
* @param parentSessionId - durable direct parent whose authority is claimed.
* @param mode - required continuable-address discriminator.
* @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
* @throws {RemoteError} `gateway/bad-request` for an empty id,
* `subagent/unauthorized` when the address does not own the live target,
* otherwise `gateway/internal`.
*/
@Remote('interruptByParent') interruptByParent( childSessionId: SessionId, parentSessionId: SessionId, mode: 'continuable', ): SubagentInterruptReceipt
/**
* Register a provider under its name. Registration is effect-scoped and HMR
* safe; removing a provider blocks new starts but does not revoke runs that
* were already returned to their holders.
* @param provider - the trusted provider implementation.
* @returns the exact Cordis effect disposer.
*/
registerProvider(provider: SubagentProvider): () => void
/**
* Look up a provider by name.
* @param name - the provider name.
* @returns the provider, or undefined when absent.
*/
getProvider(name: string): SubagentProvider | undefined
/**
* List registered provider names in insertion order.
* @returns the registered names.
*/
list(): string[]
Types: Agent · ContentBlock · MessageId · SessionId
Source: packages/subagent/subagent/src/index.ts
subagent/* events
subagent/end — emit
A published child settled. Scope-filtered dispatch uses the same delegating parent carrier as subagent/start, so the lifecycle pair reaches the same scoped audience.
/**
* A published child settled. Scope-filtered dispatch uses the same delegating
* parent carrier as `subagent/start`, so the lifecycle pair reaches the
* same scoped audience.
* @param info - the run identity and terminal outcome.
* @dshScopeScan unsupported
* @mode emit
*/
'subagent/end'(this: Scoped<SubagentRuntime>, info: SubagentRunEndInfo): void
Types: Scoped
Source: packages/subagent/subagent/src/index.ts
subagent/provider-added — emit
A provider became resolvable in the registry.
/**
* A provider became resolvable in the registry.
* @param provider - the registered provider.
* @mode emit
*/
'subagent/provider-added'(provider: SubagentProvider): void
Source: packages/subagent/subagent/src/index.ts
subagent/provider-removed — emit
A provider left the registry. Accepted runs remain holder-owned.
/**
* A provider left the registry. Accepted runs remain holder-owned.
* @param name - the provider name that no longer resolves.
* @mode emit
*/
'subagent/provider-removed'(name: string): void
Source: packages/subagent/subagent/src/index.ts
subagent/start — emit
A provider established a published child. For in-process providers, ctx.agents.get(info.id) resolves during this notification. Scope-filtered dispatch keys the carrier by the delegating parent, so a parent-scoped listener observes only its own delegations. Paired with subagent/end.
/**
* A provider established a published child. For in-process providers,
* `ctx.agents.get(info.id)` resolves during this notification.
* Scope-filtered dispatch keys the carrier by the delegating parent, so a
* parent-scoped listener observes only its own delegations. Paired with
* `subagent/end`.
* @param info - the provider and published child identity.
* @dshScopeScan unsupported
* @mode emit
*/
'subagent/start'(this: Scoped<SubagentRuntime>, info: SubagentRunInfo): void
Types: Scoped