fix(scope): harden final ownership boundaries
This commit is contained in:
Tianyi Cui
@@ -18,23 +18,23 @@ Unlike the bash seam (one executor per context, second load throws), **multiple
|
||||
|
||||
| Member | Semantics |
|
||||
|---|---|
|
||||
| `registerProvider(provider)` | Register a frozen acceptance snapshot under `provider.name`; later caller mutation cannot change registry behavior or HMR cleanup, while `start` stays bound to the original provider receiver. Throws `SubagentError('DUPLICATE_PROVIDER')` on a name clash. Effect-scoped (HMR-safe); returns the disposer. |
|
||||
| `registerProvider(provider)` | Read and validate the name, capability object and four boolean flags, `inheritsParentContext`, and `start` callback exactly once, then register a frozen acceptance snapshot under the accepted name. Malformed fixed fields fail loud before registration; later caller mutation cannot change registry behavior or HMR cleanup, while `start` stays bound to the original provider receiver. Throws `SubagentError('DUPLICATE_PROVIDER')` on a name clash. Effect-scoped (HMR-safe); returns the disposer. |
|
||||
| `getProvider(name)` | Look up the frozen registry snapshot (`undefined` if absent). |
|
||||
| `list()` | Registered provider names (insertion order). |
|
||||
| `start(name, request)` | Resolve the provider (`NO_PROVIDER` if absent), read every caller field once into one acceptance snapshot, validate every requested START-TIME capability and scalar value before any child is created, and materialize prompt/schema/options/filter data through a single-pass lossless-JSON snapshot before delegating to `provider.start`. Return a frozen service-owned run wrapper whose provider fields are captured once, whose methods remain bound to the provider handle, and whose `result` is one detached, deeply frozen normalization shared by the caller and telemetry. Emit `subagent/start` only after `run.started` fulfills and the paired `subagent/end` after that started run settles; a pre-publication readiness rejection emits neither. |
|
||||
| `start(name, request)` | Resolve the provider (`NO_PROVIDER` if absent), read every caller field once into one acceptance snapshot, validate every requested START-TIME capability and scalar value before any child is created, and materialize prompt/schema/options/filter data through a single-pass lossless-JSON snapshot before delegating to `provider.start`. Acquire and memoize the provider run's disposer before reading the rest of its handle, then return a frozen service-owned wrapper whose fields are captured once, whose methods remain bound to the provider handle, and whose `result` is one detached, deeply frozen normalization shared by the caller and telemetry. Malformed handle access/binding starts rollback before the synchronous fault escapes; malformed terminal data rejects only after rollback reaches quiescence. Emit `subagent/start` only after `run.started` fulfills and the paired `subagent/end` after that started run settles; a pre-publication readiness rejection emits neither. |
|
||||
|
||||
## Capabilities: two kinds, discovered two ways
|
||||
|
||||
- **Start-time features** (`outputSchema`, `depthLimit`, `toolFilter/persona`) are a static `provider.capabilities` descriptor, checked by the service BEFORE a run exists. A request that needs one the provider lacks is **rejected loud** (`UNSUPPORTED_CAPABILITY`), never accepted-then-ignored.
|
||||
- **Runtime features** (steering, resume) are **optional methods** on `SubagentRun` (`sendMessage?`, `resume?`). The method's presence IS the capability; TS narrowing is the discovery mechanism — a consumer cannot call an absent method without narrowing first, so there is no silent degradation path.
|
||||
|
||||
Beside `capabilities` sits one DESCRIPTIVE fact, not validated by the service: `provider.inheritsParentContext` — whether a child sees the parent conversation (`fork`: true — seeded with the completed-turn prefix; `spawn`/`acp`: false). The model-facing consumer (`dsh-tool-subagent`) derives truthful tool wording from it.
|
||||
Beside `capabilities` sits one DESCRIPTIVE fact: `provider.inheritsParentContext` — whether a child sees the parent conversation (`fork`: true — seeded with the completed-turn prefix; `spawn`/`acp`: false). The service validates that the descriptor is a boolean but does not interpret or enforce its meaning; the model-facing consumer (`dsh-tool-subagent`) derives truthful tool wording from it.
|
||||
|
||||
## Run lifecycle
|
||||
|
||||
`provider.start(request)` returns a provider-owned `SubagentRun`; `SubagentService.start` captures that handle once and returns a frozen service-owned wrapper with `started` (the publication/readiness promise), a normalized `result` (the terminal outcome), bound `cancel()` and `dispose()`, and bound optional runtime methods. `started` resolves only after the provider has established a real child and rejects if the attempt fails or is cancelled first. `result` resolves with one detached, deeply frozen `SubagentResult` (`output`, optional `structured`, `stopReason`) that the service and caller share — it does **not** reject on a child-level failure (a model/transport failure resolves with `stopReason: 'error'`), but malformed provider data rejects as an infrastructure contract fault. The consumer maps a non-`completed` reason to an `isError` tool result and MUST `dispose()` on every path (success, error, abort) to reach child quiescence and avoid leaking an idle child / session.
|
||||
|
||||
The service also announces provider lifecycle: `subagent/provider-added` (the frozen registry snapshot) fires after a registration and `subagent/provider-removed` (the accepted name) after an unregistration, so a consumer deriving state from a named provider (the model-facing tool wording) mirrors registry membership instead of assuming load order — the cordis Loader starts sibling plugins concurrently, so "listed earlier" does not mean "registered earlier". Run lifecycle is gated by provider readiness: the service captures the provider handle's public fields once, `subagent/start` (payload `SubagentRunInfo`) fires only after the accepted `started` promise fulfills, and `subagent/end` (payload `SubagentRunEndInfo`) uses the same accepted id and normalized result; readiness rejection emits neither. For spawn/fork, the start listener can resolve the published child via `ctx.agents.get(info.id)`; a remote provider need not have a local registry entry. Both events are **observe-only** plain emits whose service-owned payloads are deeply frozen before per-listener dispatch. The service observes the normalized `result` immediately even while readiness is pending and buffers that end payload until start has fired; a malformed provider result rejects the returned result promise and becomes contained `error` telemetry, a rejection cannot become an unhandled detached promise, start always precedes end, and one listener cannot corrupt either the caller or later listeners. `subagent/end` carries the same frozen output as `lastAssistantMessage` on a valid settle path and omits it on infrastructure or result-contract failure. Any run-affecting decision is out of scope for this observe-only surface.
|
||||
The service also announces provider lifecycle: `subagent/provider-added` (the frozen registry snapshot) fires after a registration and `subagent/provider-removed` (the accepted name) after an unregistration, so a consumer deriving state from a named provider (the model-facing tool wording) mirrors registry membership instead of assuming load order — the cordis Loader starts sibling plugins concurrently, so "listed earlier" does not mean "registered earlier". Run lifecycle is gated by provider readiness: the service captures the provider handle's public fields once, `subagent/start` (payload `SubagentRunInfo`) fires only after the accepted `started` promise fulfills, and `subagent/end` (payload `SubagentRunEndInfo`) uses the same accepted id and normalized result; readiness rejection emits neither. For spawn/fork, the start listener can resolve the published child via `ctx.agents.get(info.id)`; a remote provider need not have a local registry entry. Both events are **observe-only** plain emits whose service-owned payloads are deeply frozen before per-listener dispatch. A synchronous listener throw or returned-promise rejection is logged per listener; later listeners still run synchronously, and async listeners remain concurrent fire-and-forget. The service observes the normalized `result` immediately even while readiness is pending and buffers that end payload until start has fired; a malformed provider result rejects the returned result promise and becomes contained `error` telemetry, a rejection cannot become an unhandled detached promise, start always precedes end, and one listener cannot corrupt either the caller or later listeners. `subagent/end` carries the same frozen output as `lastAssistantMessage` on a valid settle path and omits it on infrastructure or result-contract failure. Any run-affecting decision is out of scope for this observe-only surface.
|
||||
|
||||
## Scope (first cut)
|
||||
|
||||
|
||||
@@ -169,9 +169,11 @@ export class SubagentService extends Service {
|
||||
* Register a provider under its `provider.name`. Throws {@link SubagentError}
|
||||
* (`DUPLICATE_PROVIDER`) if the name is already taken. The registry snapshots
|
||||
* the name, static descriptors, and `start` callback identity at acceptance;
|
||||
* later caller mutation cannot change lookup, capability validation, consumer
|
||||
* wording, dispatch, or HMR cleanup. The callback remains bound to the
|
||||
* original provider object, so provider-owned mutable state stays live.
|
||||
* every fixed field and capability flag is read once and validated before
|
||||
* registration, so malformed provider objects fail loud without entering the
|
||||
* registry. Later caller mutation cannot change lookup, capability validation,
|
||||
* consumer wording, dispatch, or HMR cleanup. The callback remains bound to
|
||||
* the original provider object, so provider-owned mutable state stays live.
|
||||
* Effect-scoped: disposed with the calling fiber (HMR-safe). Emits
|
||||
* `subagent/provider-added` after the registration and
|
||||
* `subagent/provider-removed` on unregistration, so consumers can mirror
|
||||
@@ -187,18 +189,49 @@ export class SubagentService extends Service {
|
||||
// mutate or reuse the provider object before its old fiber unloads. Binding
|
||||
// preserves the provider method's receiver while making replacement of the
|
||||
// public callback field after registration inert.
|
||||
const inputCapabilities = provider.capabilities
|
||||
const name: unknown = provider.name
|
||||
const inputCapabilities: unknown = provider.capabilities
|
||||
const inheritsParentContext: unknown = provider.inheritsParentContext
|
||||
// eslint-disable-next-line @typescript-eslint/unbound-method
|
||||
const inputStart: unknown = provider.start
|
||||
if (typeof name !== 'string') {
|
||||
throw new TypeError('subagent provider name must be a string')
|
||||
}
|
||||
if (inputCapabilities === null || typeof inputCapabilities !== 'object' || Array.isArray(inputCapabilities)) {
|
||||
throw new TypeError(`subagent provider "${name}" capabilities must be an object`)
|
||||
}
|
||||
const inputCapabilityFields = inputCapabilities as Record<keyof SubagentCapabilities, unknown>
|
||||
const outputSchema = inputCapabilityFields.outputSchema
|
||||
const depthLimit = inputCapabilityFields.depthLimit
|
||||
const toolFilter = inputCapabilityFields.toolFilter
|
||||
const persona = inputCapabilityFields.persona
|
||||
for (const [capability, value] of [
|
||||
['outputSchema', outputSchema],
|
||||
['depthLimit', depthLimit],
|
||||
['toolFilter', toolFilter],
|
||||
['persona', persona],
|
||||
] as const) {
|
||||
if (typeof value !== 'boolean') {
|
||||
throw new TypeError(`subagent provider "${name}" capability "${capability}" must be a boolean`)
|
||||
}
|
||||
}
|
||||
if (typeof inheritsParentContext !== 'boolean') {
|
||||
throw new TypeError(`subagent provider "${name}" inheritsParentContext must be a boolean`)
|
||||
}
|
||||
if (typeof inputStart !== 'function') {
|
||||
throw new TypeError(`subagent provider "${name}" start must be a function`)
|
||||
}
|
||||
const capabilities: SubagentCapabilities = Object.freeze({
|
||||
outputSchema: inputCapabilities.outputSchema,
|
||||
depthLimit: inputCapabilities.depthLimit,
|
||||
toolFilter: inputCapabilities.toolFilter,
|
||||
persona: inputCapabilities.persona,
|
||||
outputSchema: outputSchema as boolean,
|
||||
depthLimit: depthLimit as boolean,
|
||||
toolFilter: toolFilter as boolean,
|
||||
persona: persona as boolean,
|
||||
})
|
||||
const snapshot: SubagentProvider = Object.freeze({
|
||||
name: provider.name,
|
||||
name,
|
||||
capabilities,
|
||||
inheritsParentContext: provider.inheritsParentContext,
|
||||
start: provider.start.bind(provider),
|
||||
inheritsParentContext,
|
||||
start: Function.prototype.bind.call(inputStart, provider) as SubagentProvider['start'],
|
||||
})
|
||||
const dispose = this.ctx.effect(function* (this: SubagentService) {
|
||||
if (this.providers.has(snapshot.name)) {
|
||||
@@ -255,7 +288,10 @@ export class SubagentService extends Service {
|
||||
* {@link SubagentProvider.start}. The returned handle is a service-owned,
|
||||
* frozen wrapper: provider fields are captured once, methods stay bound to the
|
||||
* provider handle, and `result` resolves to one detached, deeply frozen value
|
||||
* shared by the caller and lifecycle telemetry. Emits `subagent/start` /
|
||||
* shared by the caller and lifecycle telemetry. Once a provider returns a
|
||||
* callable disposer, malformed handle access/binding starts rollback before
|
||||
* the synchronous fault escapes; malformed terminal data rejects only after
|
||||
* that same memoized disposal reaches quiescence. Emits `subagent/start` /
|
||||
* `subagent/end` only after the run's readiness boundary fulfills. A provider
|
||||
* that fails before establishing a child emits neither event.
|
||||
* @param name - the provider to run on.
|
||||
@@ -324,82 +360,176 @@ export class SubagentService extends Service {
|
||||
...toolFilter !== undefined ? { toolFilter } : {},
|
||||
...input.persona !== undefined ? { persona: input.persona } : {},
|
||||
}
|
||||
const providerRun = provider.start(accepted)
|
||||
const providerRun: unknown = provider.start(accepted)
|
||||
if (providerRun === null || (typeof providerRun !== 'object' && typeof providerRun !== 'function')) {
|
||||
throw new TypeError(`subagent provider "${name}" start must return a SubagentRun object`)
|
||||
}
|
||||
const acceptedRun = providerRun as SubagentRun
|
||||
// Acquire the one rollback capability BEFORE touching any other provider-run
|
||||
// field. Once start() returned a handle, the service owns an accepted live
|
||||
// attempt; a hostile later accessor or bind must not make that attempt
|
||||
// unreachable. The wrapper also memoizes provider disposal, so automatic
|
||||
// rollback and a racing caller join one quiescence transaction even if a
|
||||
// contract-violating provider forgot to make its own method idempotent.
|
||||
// eslint-disable-next-line @typescript-eslint/unbound-method
|
||||
const inputDispose = acceptedRun.dispose
|
||||
if (typeof inputDispose !== 'function') {
|
||||
throw new TypeError(`subagent provider "${name}" run dispose must be a function`)
|
||||
}
|
||||
let disposal: Promise<void> | undefined
|
||||
const dispose = (): Promise<void> => {
|
||||
if (disposal === undefined) {
|
||||
try {
|
||||
// Invoke through the captured callable without reading its public
|
||||
// `bind`/`length`/`name` properties. Disposal is the recovery
|
||||
// capability itself; hostile function metadata must not prevent the
|
||||
// seam from exercising it when a later handle field is malformed.
|
||||
disposal = Promise.resolve(Reflect.apply(inputDispose, acceptedRun, []))
|
||||
} catch (error: unknown) {
|
||||
disposal = Promise.reject(error instanceof Error
|
||||
? error
|
||||
: new Error('subagent provider run dispose threw a non-Error value', { cause: error }))
|
||||
}
|
||||
}
|
||||
return disposal
|
||||
}
|
||||
// Provider-owned run objects can be accessor-backed too. Capture every
|
||||
// public field exactly once, bind methods to the provider's original handle,
|
||||
// and expose only this service-owned wrapper. The normalized result promise
|
||||
// is also the one lifecycle telemetry observes, so the caller and observers
|
||||
// cannot receive different values from stateful accessors.
|
||||
const id = providerRun.id
|
||||
const started = providerRun.started
|
||||
const providerResult = providerRun.result
|
||||
const cancel = providerRun.cancel.bind(providerRun)
|
||||
const sendMessage = providerRun.sendMessage?.bind(providerRun)
|
||||
const dispose = providerRun.dispose.bind(providerRun)
|
||||
const resume = providerRun.resume?.bind(providerRun)
|
||||
const result = providerResult.then(value => this.snapshotRunResult(value))
|
||||
const run: SubagentRun = Object.freeze({
|
||||
id,
|
||||
started,
|
||||
result,
|
||||
cancel,
|
||||
dispose,
|
||||
...sendMessage === undefined
|
||||
? {}
|
||||
: { sendMessage },
|
||||
...resume === undefined
|
||||
? {}
|
||||
: { resume },
|
||||
})
|
||||
|
||||
// Observe result settlement IMMEDIATELY, before waiting on readiness. A
|
||||
// provider may fail both promises in the same turn; deferring the rejection
|
||||
// handler until `started` fulfilled would leave `result` transiently
|
||||
// unhandled. The settled event is buffered until start has been announced,
|
||||
// preserving start → end order even for an already-settled scripted run.
|
||||
let readiness: 'pending' | 'started' | 'failed' = 'pending'
|
||||
let pendingEnd: SubagentRunEndInfo | undefined
|
||||
const deliverEnd = (info: SubagentRunEndInfo): void => {
|
||||
if (readiness === 'started') this.emitLifecycle('subagent/end', info, parent)
|
||||
else if (readiness === 'pending') pendingEnd = info
|
||||
// A pre-publication readiness failure has no lifecycle pair; result
|
||||
// remains observable by the run's consumer, but telemetry must not claim
|
||||
// that a child started.
|
||||
}
|
||||
void result.then(
|
||||
(value) => {
|
||||
deliverEnd({
|
||||
provider: name,
|
||||
id,
|
||||
stopReason: value.stopReason,
|
||||
lastAssistantMessage: value.output,
|
||||
})
|
||||
},
|
||||
() => { deliverEnd({ provider: name, id, stopReason: 'error' }) },
|
||||
)
|
||||
|
||||
// Readiness is the publication boundary owned by the provider. For
|
||||
// in-process runs, fulfillment means the agent registry already contains
|
||||
// `run.id`; for ACP it means the remote session exists. Emit start with
|
||||
// per-listener containment, then flush an outcome that settled unusually
|
||||
// early. A readiness rejection is handled here and deliberately emits no
|
||||
// false start/end pair; the result path above remains independently handled.
|
||||
void started.then(
|
||||
() => {
|
||||
readiness = 'started'
|
||||
this.emitLifecycle('subagent/start', { provider: name, id }, parent)
|
||||
if (pendingEnd !== undefined) {
|
||||
const info = pendingEnd
|
||||
pendingEnd = undefined
|
||||
this.emitLifecycle('subagent/end', info, parent)
|
||||
try {
|
||||
const id = acceptedRun.id
|
||||
if (typeof id !== 'string') {
|
||||
throw new TypeError(`subagent provider "${name}" run id must be a string`)
|
||||
}
|
||||
const started = acceptedRun.started
|
||||
if (!(started instanceof Promise)) {
|
||||
throw new TypeError(`subagent provider "${name}" run started must be a Promise`)
|
||||
}
|
||||
// Observe each accepted provider promise before reading the next hostile
|
||||
// field. A later accessor/validation failure prevents a wrapper from being
|
||||
// returned, but must not leave an already-rejected provider promise
|
||||
// unhandled while rollback proceeds.
|
||||
void started.catch(() => undefined)
|
||||
const providerResult = acceptedRun.result
|
||||
if (!(providerResult instanceof Promise)) {
|
||||
throw new TypeError(`subagent provider "${name}" run result must be a Promise`)
|
||||
}
|
||||
void providerResult.catch(() => undefined)
|
||||
// eslint-disable-next-line @typescript-eslint/unbound-method
|
||||
const inputCancel = acceptedRun.cancel
|
||||
if (typeof inputCancel !== 'function') {
|
||||
throw new TypeError(`subagent provider "${name}" run cancel must be a function`)
|
||||
}
|
||||
// eslint-disable-next-line @typescript-eslint/unbound-method
|
||||
const inputSendMessage = acceptedRun.sendMessage
|
||||
if (inputSendMessage !== undefined && typeof inputSendMessage !== 'function') {
|
||||
throw new TypeError(`subagent provider "${name}" run sendMessage must be a function when provided`)
|
||||
}
|
||||
// eslint-disable-next-line @typescript-eslint/unbound-method
|
||||
const inputResume = acceptedRun.resume
|
||||
if (inputResume !== undefined && typeof inputResume !== 'function') {
|
||||
throw new TypeError(`subagent provider "${name}" run resume must be a function when provided`)
|
||||
}
|
||||
const cancel = Function.prototype.bind.call(inputCancel, acceptedRun) as SubagentRun['cancel']
|
||||
const sendMessage = inputSendMessage === undefined
|
||||
? undefined
|
||||
: Function.prototype.bind.call(inputSendMessage, acceptedRun) as NonNullable<SubagentRun['sendMessage']>
|
||||
const resume = inputResume === undefined
|
||||
? undefined
|
||||
: Function.prototype.bind.call(inputResume, acceptedRun) as NonNullable<SubagentRun['resume']>
|
||||
const result = providerResult.then(async (value) => {
|
||||
try {
|
||||
return this.snapshotRunResult(value)
|
||||
} catch (error: unknown) {
|
||||
// A malformed terminal value is an infrastructure contract fault. The
|
||||
// result rejects only after the accepted provider attempt has reached
|
||||
// quiescence, so a caller cannot lose the only cleanup handle by merely
|
||||
// observing the normalization failure.
|
||||
await this.rollbackProviderRun(name, dispose)
|
||||
throw error
|
||||
}
|
||||
},
|
||||
() => {
|
||||
readiness = 'failed'
|
||||
pendingEnd = undefined
|
||||
},
|
||||
)
|
||||
return run
|
||||
})
|
||||
const run: SubagentRun = Object.freeze({
|
||||
id,
|
||||
started,
|
||||
result,
|
||||
cancel,
|
||||
dispose,
|
||||
...sendMessage === undefined
|
||||
? {}
|
||||
: { sendMessage },
|
||||
...resume === undefined
|
||||
? {}
|
||||
: { resume },
|
||||
})
|
||||
|
||||
// Observe result settlement IMMEDIATELY, before waiting on readiness. A
|
||||
// provider may fail both promises in the same turn; deferring the rejection
|
||||
// handler until `started` fulfilled would leave `result` transiently
|
||||
// unhandled. The settled event is buffered until start has been announced,
|
||||
// preserving start → end order even for an already-settled scripted run.
|
||||
let readiness: 'pending' | 'started' | 'failed' = 'pending'
|
||||
let pendingEnd: SubagentRunEndInfo | undefined
|
||||
const deliverEnd = (info: SubagentRunEndInfo): void => {
|
||||
if (readiness === 'started') this.emitLifecycle('subagent/end', info, parent)
|
||||
else if (readiness === 'pending') pendingEnd = info
|
||||
// A pre-publication readiness failure has no lifecycle pair; result
|
||||
// remains observable by the run's consumer, but telemetry must not claim
|
||||
// that a child started.
|
||||
}
|
||||
void result.then(
|
||||
(value) => {
|
||||
deliverEnd({
|
||||
provider: name,
|
||||
id,
|
||||
stopReason: value.stopReason,
|
||||
lastAssistantMessage: value.output,
|
||||
})
|
||||
},
|
||||
() => { deliverEnd({ provider: name, id, stopReason: 'error' }) },
|
||||
)
|
||||
|
||||
// Readiness is the publication boundary owned by the provider. For
|
||||
// in-process runs, fulfillment means the agent registry already contains
|
||||
// `run.id`; for ACP it means the remote session exists. Emit start with
|
||||
// per-listener containment, then flush an outcome that settled unusually
|
||||
// early. A readiness rejection is handled here and deliberately emits no
|
||||
// false start/end pair; the result path above remains independently handled.
|
||||
void started.then(
|
||||
() => {
|
||||
readiness = 'started'
|
||||
this.emitLifecycle('subagent/start', { provider: name, id }, parent)
|
||||
if (pendingEnd !== undefined) {
|
||||
const info = pendingEnd
|
||||
pendingEnd = undefined
|
||||
this.emitLifecycle('subagent/end', info, parent)
|
||||
}
|
||||
},
|
||||
() => {
|
||||
readiness = 'failed'
|
||||
pendingEnd = undefined
|
||||
},
|
||||
)
|
||||
return run
|
||||
} catch (error: unknown) {
|
||||
// start() has already transferred a live attempt to the seam. Begin
|
||||
// rollback synchronously before surfacing the malformed-handle failure;
|
||||
// the contained cleanup promise prevents either a resource leak or an
|
||||
// unhandled rejection even though this API cannot synchronously await it.
|
||||
void this.rollbackProviderRun(name, dispose)
|
||||
throw error
|
||||
}
|
||||
}
|
||||
|
||||
/** Dispose one malformed provider attempt without letting cleanup mask the contract fault. */
|
||||
private async rollbackProviderRun(providerName: string, dispose: () => Promise<void>): Promise<void> {
|
||||
try {
|
||||
await dispose()
|
||||
} catch (error: unknown) {
|
||||
this.ctx.logger.warn(`subagent provider "${providerName}" malformed run rollback failed: ${renderThrown(error)}`)
|
||||
}
|
||||
}
|
||||
|
||||
/** Normalize one provider result into the immutable seam value. */
|
||||
@@ -452,10 +582,12 @@ export class SubagentService extends Service {
|
||||
|
||||
/**
|
||||
* Emit a `subagent/*` lifecycle event with PER-LISTENER containment: dispatch
|
||||
* each subscriber individually and log (never propagate) a thrown one, so one
|
||||
* bad subscriber can neither strand the already-live run, surface as an
|
||||
* unhandled rejection on the detached settle hook, NOR starve the listeners
|
||||
* registered after it. A single try/catch around `ctx.emit` would not do the
|
||||
* each subscriber individually and log (never propagate) either a synchronous
|
||||
* throw or a returned-promise rejection, so one bad subscriber can neither
|
||||
* strand the already-live run, surface as an unhandled rejection on the
|
||||
* detached settle hook, NOR starve the listeners registered after it. Async
|
||||
* listeners remain concurrent fire-and-forget; dispatch does not await or
|
||||
* serialize them. A single try/catch around `ctx.emit` would not do the
|
||||
* last part — cordis `emit` runs listeners in a `.map(cb => cb())` that halts
|
||||
* on the first throw — so this resolves the listener callbacks via
|
||||
* `ctx.events.dispatch` and contains each call, the same guarantee
|
||||
@@ -488,7 +620,14 @@ export class SubagentService extends Service {
|
||||
: [scopeTarget(this, parent), name, acceptedInfo]
|
||||
for (const callback of this.ctx.events.dispatch('emit', dispatchArgs)) {
|
||||
try {
|
||||
callback(acceptedInfo)
|
||||
const returned: unknown = callback(acceptedInfo)
|
||||
// Plain emits remain fire-and-forget and every callback is still invoked
|
||||
// synchronously in this loop. Observe a returned promise independently so
|
||||
// an async listener rejection is contained without serializing listeners
|
||||
// or delaying provider/run lifecycle.
|
||||
void Promise.resolve(returned).catch((error: unknown) => {
|
||||
this.ctx.logger.warn(`subagent: ${name} listener rejected: ${renderThrown(error)}`)
|
||||
})
|
||||
} catch (error: unknown) {
|
||||
this.ctx.logger.warn(`subagent: ${name} listener threw: ${renderThrown(error)}`)
|
||||
}
|
||||
|
||||
@@ -150,6 +150,93 @@ describe('SubagentService', () => {
|
||||
}
|
||||
})
|
||||
|
||||
it.each([
|
||||
{ label: 'a non-string name', patch: { name: 42 }, message: 'name must be a string' },
|
||||
{ label: 'null capabilities', patch: { capabilities: null }, message: 'capabilities must be an object' },
|
||||
{ label: 'primitive capabilities', patch: { capabilities: 42 }, message: 'capabilities must be an object' },
|
||||
{ label: 'array capabilities', patch: { capabilities: [] }, message: 'capabilities must be an object' },
|
||||
{
|
||||
label: 'a non-boolean outputSchema capability',
|
||||
patch: { capabilities: { ...NO_CAPS, outputSchema: 'yes' } },
|
||||
message: 'capability "outputSchema" must be a boolean',
|
||||
},
|
||||
{
|
||||
label: 'a non-boolean depthLimit capability',
|
||||
patch: { capabilities: { ...NO_CAPS, depthLimit: 'yes' } },
|
||||
message: 'capability "depthLimit" must be a boolean',
|
||||
},
|
||||
{
|
||||
label: 'a non-boolean toolFilter capability',
|
||||
patch: { capabilities: { ...NO_CAPS, toolFilter: 'yes' } },
|
||||
message: 'capability "toolFilter" must be a boolean',
|
||||
},
|
||||
{
|
||||
label: 'a non-boolean persona capability',
|
||||
patch: { capabilities: { ...NO_CAPS, persona: 'yes' } },
|
||||
message: 'capability "persona" must be a boolean',
|
||||
},
|
||||
{ label: 'a non-boolean context descriptor', patch: { inheritsParentContext: 'yes' }, message: 'inheritsParentContext must be a boolean' },
|
||||
{ label: 'a non-callable start field', patch: { start: 42 }, message: 'start must be a function' },
|
||||
])('rejects a provider registration with $label before entering the registry', async ({ patch, message }) => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const provider = Object.assign(new StubProvider('invalid'), patch)
|
||||
|
||||
expect(() => ctx.subagents.registerProvider(provider as unknown as SubagentProvider)).toThrow(message)
|
||||
expect(ctx.subagents.list()).toEqual([])
|
||||
expect(Object.isFrozen(provider)).toBe(false)
|
||||
})
|
||||
|
||||
it('reads every registration field once and binds the accepted start callback to the provider', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const reads = {
|
||||
name: 0,
|
||||
capabilities: 0,
|
||||
outputSchema: 0,
|
||||
depthLimit: 0,
|
||||
toolFilter: 0,
|
||||
persona: 0,
|
||||
inheritsParentContext: 0,
|
||||
start: 0,
|
||||
}
|
||||
const capabilities = Object.defineProperties({}, {
|
||||
outputSchema: { enumerable: true, get: () => { reads.outputSchema += 1; return false } },
|
||||
depthLimit: { enumerable: true, get: () => { reads.depthLimit += 1; return false } },
|
||||
toolFilter: { enumerable: true, get: () => { reads.toolFilter += 1; return false } },
|
||||
persona: { enumerable: true, get: () => { reads.persona += 1; return false } },
|
||||
}) as SubagentCapabilities
|
||||
const acceptedStart = function (this: SubagentProvider, request: SubagentStartRequest): SubagentRun {
|
||||
expect(this).toBe(provider)
|
||||
return {
|
||||
id: AgentId(`one-read:${request.parent.id}`),
|
||||
started: Promise.resolve(),
|
||||
result: Promise.resolve({ output: [], stopReason: 'completed' }),
|
||||
cancel() {},
|
||||
async dispose() {},
|
||||
}
|
||||
}
|
||||
const provider = Object.defineProperties({}, {
|
||||
name: { enumerable: true, get: () => { reads.name += 1; return 'one-read' } },
|
||||
capabilities: { enumerable: true, get: () => { reads.capabilities += 1; return capabilities } },
|
||||
inheritsParentContext: { enumerable: true, get: () => { reads.inheritsParentContext += 1; return false } },
|
||||
start: { enumerable: true, get: () => { reads.start += 1; return acceptedStart } },
|
||||
}) as SubagentProvider
|
||||
|
||||
ctx.subagents.registerProvider(provider)
|
||||
await expect(ctx.subagents.start('one-read', baseRequest()).result).resolves.toMatchObject({ stopReason: 'completed' })
|
||||
expect(reads).toEqual({
|
||||
name: 1,
|
||||
capabilities: 1,
|
||||
outputSchema: 1,
|
||||
depthLimit: 1,
|
||||
toolFilter: 1,
|
||||
persona: 1,
|
||||
inheritsParentContext: 1,
|
||||
start: 1,
|
||||
})
|
||||
})
|
||||
|
||||
it('unregisters a provider when its owning fiber is disposed (HMR safety)', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
@@ -608,6 +695,178 @@ describe('SubagentService', () => {
|
||||
})
|
||||
})
|
||||
|
||||
it.each([
|
||||
{ label: 'a non-string id', field: 'id', value: 42, message: 'run id must be a string' },
|
||||
{ label: 'a non-Promise started field', field: 'started', value: undefined, message: 'run started must be a Promise' },
|
||||
{ label: 'a non-Promise result field', field: 'result', value: undefined, message: 'run result must be a Promise' },
|
||||
{ label: 'a non-callable cancel field', field: 'cancel', value: undefined, message: 'run cancel must be a function' },
|
||||
{ label: 'a non-callable sendMessage field', field: 'sendMessage', value: 42, message: 'run sendMessage must be a function' },
|
||||
{ label: 'a non-callable resume field', field: 'resume', value: 42, message: 'run resume must be a function' },
|
||||
])('rolls back a provider run with $label', async ({ field, value, message }) => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const providerDispose = vi.fn(async () => {})
|
||||
const providerRun = {
|
||||
id: AgentId('invalid-handle-child'),
|
||||
started: Promise.resolve(),
|
||||
result: Promise.resolve({ output: [], stopReason: 'completed' } satisfies SubagentResult),
|
||||
cancel() {},
|
||||
dispose: providerDispose,
|
||||
[field]: value,
|
||||
} as unknown as SubagentRun
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'invalid-handle',
|
||||
capabilities: NO_CAPS,
|
||||
inheritsParentContext: false,
|
||||
start: () => providerRun,
|
||||
})
|
||||
|
||||
expect(() => ctx.subagents.start('invalid-handle', baseRequest())).toThrow(message)
|
||||
expect(providerDispose).toHaveBeenCalledOnce()
|
||||
})
|
||||
|
||||
it.each([
|
||||
{ label: 'null', value: null },
|
||||
{ label: 'a primitive', value: 42 },
|
||||
])('rejects $label returned by provider.start before reading a disposer', async ({ value }) => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'invalid-run-shell',
|
||||
capabilities: NO_CAPS,
|
||||
inheritsParentContext: false,
|
||||
start: () => value as unknown as SubagentRun,
|
||||
})
|
||||
|
||||
expect(() => ctx.subagents.start('invalid-run-shell', baseRequest())).toThrow('must return a SubagentRun object')
|
||||
})
|
||||
|
||||
it('rejects a run without a callable disposer before accepting ownership', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'invalid-dispose',
|
||||
capabilities: NO_CAPS,
|
||||
inheritsParentContext: false,
|
||||
start: () => ({ dispose: 42 }) as unknown as SubagentRun,
|
||||
})
|
||||
|
||||
expect(() => ctx.subagents.start('invalid-dispose', baseRequest())).toThrow('run dispose must be a function')
|
||||
})
|
||||
|
||||
it('observes accepted provider promises when a later handle field is malformed', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const providerDispose = vi.fn(async () => {})
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'rejected-malformed-handle',
|
||||
capabilities: NO_CAPS,
|
||||
inheritsParentContext: false,
|
||||
start: () => ({
|
||||
id: AgentId('rejected-malformed-child'),
|
||||
started: Promise.reject(new Error('readiness already rejected')),
|
||||
result: Promise.reject(new Error('result already rejected')),
|
||||
cancel: 42,
|
||||
dispose: providerDispose,
|
||||
}) as unknown as SubagentRun,
|
||||
})
|
||||
|
||||
expect(() => ctx.subagents.start('rejected-malformed-handle', baseRequest())).toThrow('run cancel must be a function')
|
||||
expect(providerDispose).toHaveBeenCalledOnce()
|
||||
// Let both provider rejections run: the seam's immediate observers keep
|
||||
// them from surfacing as unhandled after no wrapper was returned.
|
||||
await Promise.resolve()
|
||||
})
|
||||
|
||||
it('starts rollback before surfacing a hostile run accessor failure', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const disposalGate = Promise.withResolvers<undefined>()
|
||||
const order: string[] = []
|
||||
const providerRun = Object.defineProperties({}, {
|
||||
dispose: {
|
||||
get: () => {
|
||||
order.push('dispose:get')
|
||||
return async function (this: SubagentRun): Promise<void> {
|
||||
expect(this).toBe(providerRun)
|
||||
order.push('dispose:call')
|
||||
await disposalGate.promise
|
||||
order.push('dispose:quiescent')
|
||||
}
|
||||
},
|
||||
},
|
||||
id: { get: () => { order.push('id:get'); return AgentId('hostile-handle-child') } },
|
||||
started: { get: () => { order.push('started:get'); return Promise.resolve() } },
|
||||
result: { get: () => { order.push('result:get'); throw new Error('result accessor exploded') } },
|
||||
}) as SubagentRun
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'hostile-handle',
|
||||
capabilities: NO_CAPS,
|
||||
inheritsParentContext: false,
|
||||
start: () => providerRun,
|
||||
})
|
||||
|
||||
expect(() => ctx.subagents.start('hostile-handle', baseRequest())).toThrow('result accessor exploded')
|
||||
expect(order).toEqual(['dispose:get', 'id:get', 'started:get', 'result:get', 'dispose:call'])
|
||||
disposalGate.resolve(undefined)
|
||||
await vi.waitFor(() => { expect(order).toContain('dispose:quiescent') })
|
||||
})
|
||||
|
||||
it('rolls back when binding a hostile optional run method fails', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const providerDispose = vi.fn(async () => {})
|
||||
const hostileCancel = new Proxy(() => {}, {
|
||||
get(_target, property) {
|
||||
if (property === 'length') throw new Error('cancel bind exploded')
|
||||
return undefined
|
||||
},
|
||||
})
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'hostile-bind',
|
||||
capabilities: NO_CAPS,
|
||||
inheritsParentContext: false,
|
||||
start: () => ({
|
||||
id: AgentId('hostile-bind-child'),
|
||||
started: Promise.resolve(),
|
||||
result: Promise.resolve({ output: [], stopReason: 'completed' }),
|
||||
cancel: hostileCancel,
|
||||
dispose: providerDispose,
|
||||
}),
|
||||
})
|
||||
|
||||
expect(() => ctx.subagents.start('hostile-bind', baseRequest())).toThrow('cancel bind exploded')
|
||||
expect(providerDispose).toHaveBeenCalledOnce()
|
||||
})
|
||||
|
||||
it.each([
|
||||
{ label: 'an Error', thrown: new Error('cleanup exploded'), warning: 'cleanup exploded' },
|
||||
{ label: 'a non-Error value', thrown: 'naked cleanup fault', warning: 'dispose threw a non-Error value' },
|
||||
])('contains rollback failure from $label while preserving the malformed-handle fault', async ({ thrown, warning }) => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const warnings: string[] = []
|
||||
ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'rollback-failure',
|
||||
capabilities: NO_CAPS,
|
||||
inheritsParentContext: false,
|
||||
start: () => ({
|
||||
id: 42,
|
||||
started: Promise.resolve(),
|
||||
result: Promise.resolve({ output: [], stopReason: 'completed' }),
|
||||
cancel() {},
|
||||
dispose: () => {
|
||||
// Deliberately violate the seam contract to exercise normalization.
|
||||
throw thrown
|
||||
},
|
||||
}) as unknown as SubagentRun,
|
||||
})
|
||||
|
||||
expect(() => ctx.subagents.start('rollback-failure', baseRequest())).toThrow('run id must be a string')
|
||||
await vi.waitFor(() => { expect(warnings.some(message => message.includes(warning))).toBe(true) })
|
||||
})
|
||||
|
||||
it('waits for provider readiness and observes an early result rejection without reordering lifecycle', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
@@ -811,6 +1070,8 @@ describe('SubagentService', () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const nonJsonOutput = [{ type: 'text', text: 'x', evil: () => 0 }] as unknown as SubagentResult['output']
|
||||
const disposalGate = Promise.withResolvers<undefined>()
|
||||
const providerDispose = vi.fn(async () => { await disposalGate.promise })
|
||||
ctx.subagents.registerProvider({
|
||||
name: 'unclone',
|
||||
capabilities: NO_CAPS,
|
||||
@@ -820,16 +1081,23 @@ describe('SubagentService', () => {
|
||||
started: Promise.resolve(),
|
||||
result: Promise.resolve({ output: nonJsonOutput, stopReason: 'completed' } as SubagentResult),
|
||||
cancel() {},
|
||||
dispose: async () => {},
|
||||
dispose: providerDispose,
|
||||
}),
|
||||
})
|
||||
|
||||
const ended = vi.fn()
|
||||
ctx.on('subagent/end', ended)
|
||||
const run = ctx.subagents.start('unclone', baseRequest())
|
||||
let resultSettled = false
|
||||
void run.result.catch(() => { resultSettled = true })
|
||||
await vi.waitFor(() => { expect(providerDispose).toHaveBeenCalledOnce() })
|
||||
expect(resultSettled).toBe(false)
|
||||
disposalGate.resolve(undefined)
|
||||
await expect(run.result).rejects.toThrow('subagent result must be losslessly JSON-serializable')
|
||||
await run.dispose()
|
||||
await Promise.resolve()
|
||||
|
||||
expect(providerDispose).toHaveBeenCalledOnce()
|
||||
const endInfo = ended.mock.calls[0]![0] as Record<string, unknown>
|
||||
expect(endInfo.stopReason).toBe('error')
|
||||
expect('lastAssistantMessage' in endInfo).toBe(false)
|
||||
@@ -922,6 +1190,42 @@ describe('SubagentService', () => {
|
||||
await expect(run.result).resolves.toMatchObject({ stopReason: 'completed' })
|
||||
})
|
||||
|
||||
it('contains asynchronous lifecycle-listener rejections without serializing later listeners', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
const warnings: string[] = []
|
||||
ctx.logger.warn = ((message: unknown) => { warnings.push(String(message)) }) as typeof ctx.logger.warn
|
||||
const laterStart = vi.fn()
|
||||
const laterEnd = vi.fn()
|
||||
const laterRemoved = vi.fn()
|
||||
const asyncStart = (async () => { await Promise.resolve(); throw new Error('async start listener') }) as unknown as () => void
|
||||
const asyncEnd = (async () => { await Promise.resolve(); throw new Error('async end listener') }) as unknown as () => void
|
||||
const asyncRemoved = (async () => { await Promise.resolve(); throw new Error('async removed listener') }) as unknown as () => void
|
||||
ctx.on('subagent/start', asyncStart)
|
||||
ctx.on('subagent/start', laterStart)
|
||||
ctx.on('subagent/end', asyncEnd)
|
||||
ctx.on('subagent/end', laterEnd)
|
||||
ctx.on('subagent/provider-removed', asyncRemoved)
|
||||
ctx.on('subagent/provider-removed', laterRemoved)
|
||||
const unregister = ctx.subagents.registerProvider(new StubProvider('async-listeners'))
|
||||
|
||||
const run = ctx.subagents.start('async-listeners', baseRequest())
|
||||
await run.started
|
||||
expect(laterStart).toHaveBeenCalledOnce()
|
||||
await run.result
|
||||
await vi.waitFor(() => {
|
||||
expect(laterEnd).toHaveBeenCalledOnce()
|
||||
expect(warnings.some(message => message.includes('async start listener'))).toBe(true)
|
||||
expect(warnings.some(message => message.includes('async end listener'))).toBe(true)
|
||||
})
|
||||
|
||||
await unregister()
|
||||
expect(laterRemoved).toHaveBeenCalledWith('async-listeners')
|
||||
await vi.waitFor(() => {
|
||||
expect(warnings.some(message => message.includes('async removed listener'))).toBe(true)
|
||||
})
|
||||
})
|
||||
|
||||
it('contains a listener whose thrown value cannot be stringified', async () => {
|
||||
const ctx = new Context()
|
||||
await ctx.plugin(SubagentService)
|
||||
|
||||
Reference in New Issue
Block a user