@fishwithcat/dsh-subagent 0.0.0-stage → 0.2.2-alpha.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. package/README.i18n.yaml +121 -0
  2. package/README.md +258 -2
  3. package/README.zh.md +259 -0
  4. package/lib/index.js +3065 -0
  5. package/lib/typert.host.d.ts +3 -0
  6. package/lib/typert.host.js +1086 -0
  7. package/lib/typert.remote-client.d.ts +29 -0
  8. package/lib/typert.remote-client.js +122 -0
  9. package/lib/types/activation.d.ts +110 -0
  10. package/lib/types/activation.js +112 -0
  11. package/lib/types/archive-admission.d.ts +23 -0
  12. package/lib/types/archive-admission.js +75 -0
  13. package/lib/types/assistant-output.d.ts +48 -0
  14. package/lib/types/assistant-output.js +73 -0
  15. package/lib/types/catalog.d.ts +87 -0
  16. package/lib/types/catalog.js +113 -0
  17. package/lib/types/child-agent.d.ts +145 -0
  18. package/lib/types/child-agent.js +229 -0
  19. package/lib/types/client.d.ts +8 -0
  20. package/lib/types/client.js +7 -0
  21. package/lib/types/continuation-messages.d.ts +66 -0
  22. package/lib/types/continuation-messages.js +116 -0
  23. package/lib/types/control-types.d.ts +121 -0
  24. package/lib/types/control-types.js +8 -0
  25. package/lib/types/control.d.ts +41 -0
  26. package/lib/types/control.js +75 -0
  27. package/lib/types/depth.d.ts +31 -0
  28. package/lib/types/depth.js +39 -0
  29. package/lib/types/descriptor.d.ts +105 -0
  30. package/lib/types/descriptor.js +192 -0
  31. package/lib/types/error.d.ts +11 -0
  32. package/lib/types/error.js +14 -0
  33. package/lib/types/index.d.ts +282 -0
  34. package/lib/types/index.js +398 -0
  35. package/lib/types/lifecycle.d.ts +54 -0
  36. package/lib/types/lifecycle.js +89 -0
  37. package/lib/types/list-children.d.ts +36 -0
  38. package/lib/types/list-children.js +166 -0
  39. package/lib/types/manager.d.ts +215 -0
  40. package/lib/types/manager.js +1171 -0
  41. package/lib/types/out-of-process.d.ts +92 -0
  42. package/lib/types/out-of-process.js +177 -0
  43. package/lib/types/projection-types.d.ts +93 -0
  44. package/lib/types/projection-types.js +7 -0
  45. package/lib/types/projection.d.ts +94 -0
  46. package/lib/types/projection.js +157 -0
  47. package/lib/types/structured.d.ts +49 -0
  48. package/lib/types/structured.js +130 -0
  49. package/lib/types/types.d.ts +331 -0
  50. package/lib/types/types.js +17 -0
  51. package/locale/de.json +6 -0
  52. package/locale/en.json +5 -0
  53. package/locale/es.json +6 -0
  54. package/locale/fr.json +6 -0
  55. package/locale/ja.json +6 -0
  56. package/locale/pt.json +6 -0
  57. package/locale/ru.json +6 -0
  58. package/locale/zh.json +6 -0
  59. package/package.json +131 -4
@@ -0,0 +1,192 @@
1
+ /**
2
+ * The durable subagent-child descriptor: the versioned, model-hidden
3
+ * `subagent/descriptor` session event that identifies every session-backed
4
+ * subagent, including historical one-shot records. The manager appends each
5
+ * continuable child's descriptor inside its initial turn, preserving the
6
+ * declared composition required for cold resume.
7
+ *
8
+ * The descriptor deliberately snapshots explicit fields rather than the
9
+ * merge-extensible `AgentOptions` object: an unrelated extension value cannot
10
+ * make continuation fail merely because it is not JSON, and later composition
11
+ * inputs require a deliberate {@link SUBAGENT_DESCRIPTOR_VERSION} change. It
12
+ * omits `subagentDepth` — cold resume trusts the persisted header's
13
+ * `delegationDepth` as the monotone floor — and `outputSchema`, which belongs
14
+ * to one activation's result contract rather than durable child composition.
15
+ * Per-activation knobs such as `maxTokens` are omitted for the same reason as
16
+ * `outputSchema`: they budget one activation. Cold resume requires the exact
17
+ * live subagent tree root for authorization but reconstructs child options only from the
18
+ * durable descriptor, so it neither restores the prior budget nor inherits
19
+ * the parent's current one; the resumed route's defaults apply instead.
20
+ *
21
+ * @module @deepseek-ai/dsh-subagent/descriptor
22
+ */
23
+ import { snapshotJsonValue } from '@deepseek-ai/dsh-util-values';
24
+ /**
25
+ * The current descriptor format version, stamped into every appended
26
+ * `subagent/descriptor` event and required verbatim by {@link foldSubagentDescriptor}.
27
+ * Supporting another composition input is a deliberate version change, never
28
+ * an implicit extra field.
29
+ */
30
+ export const SUBAGENT_DESCRIPTOR_VERSION = 3;
31
+ const DESCRIPTOR_BASE_KEYS = [
32
+ 'version',
33
+ 'mode',
34
+ 'provider',
35
+ 'label',
36
+ ];
37
+ const ONE_SHOT_DESCRIPTOR_KEYS = new Set(DESCRIPTOR_BASE_KEYS);
38
+ const CONTINUABLE_DESCRIPTOR_KEYS = new Set([
39
+ ...DESCRIPTOR_BASE_KEYS,
40
+ 'agentProvider',
41
+ 'agentModel',
42
+ 'agentReasoningEffort',
43
+ 'persona',
44
+ 'toolFilter',
45
+ ]);
46
+ const TOOL_FILTER_KEYS = new Set(['allow', 'deny']);
47
+ /** Whether a persisted JSON value is an object record. */
48
+ function isRecord(value) {
49
+ return typeof value === 'object' && value !== null && !Array.isArray(value);
50
+ }
51
+ /** Reject fields outside one versioned record's declared schema. */
52
+ function assertKnownKeys(value, keys, path) {
53
+ const unknown = Object.keys(value).find(key => !keys.has(key));
54
+ if (unknown !== undefined) {
55
+ throw new Error(`persisted subagent descriptor ${path} has unknown field "${unknown}"`);
56
+ }
57
+ }
58
+ /** Read one optional string field from a persisted descriptor record. */
59
+ function optionalString(value, key) {
60
+ if (!Object.hasOwn(value, key))
61
+ return undefined;
62
+ const field = value[key];
63
+ if (typeof field !== 'string') {
64
+ throw new Error(`persisted subagent descriptor ${key} must be a string`);
65
+ }
66
+ return field;
67
+ }
68
+ /** Read one optional string-array field from a persisted tool restriction. */
69
+ function optionalStringArray(value, key) {
70
+ if (!Object.hasOwn(value, key))
71
+ return undefined;
72
+ const field = value[key];
73
+ if (!Array.isArray(field)) {
74
+ throw new Error(`persisted subagent descriptor toolFilter.${key} must be an array of strings`);
75
+ }
76
+ const items = field;
77
+ if (items.some(item => typeof item !== 'string')) {
78
+ throw new Error(`persisted subagent descriptor toolFilter.${key} must be an array of strings`);
79
+ }
80
+ return items;
81
+ }
82
+ /** Validate and reconstruct a persisted tool restriction. */
83
+ function parseToolFilter(value) {
84
+ if (!isRecord(value)) {
85
+ throw new Error('persisted subagent descriptor toolFilter must be an object');
86
+ }
87
+ assertKnownKeys(value, TOOL_FILTER_KEYS, 'toolFilter');
88
+ const allow = optionalStringArray(value, 'allow');
89
+ const deny = optionalStringArray(value, 'deny');
90
+ if (allow === undefined && deny === undefined) {
91
+ throw new Error('persisted subagent descriptor toolFilter must declare allow and/or deny');
92
+ }
93
+ return {
94
+ ...allow !== undefined ? { allow } : {},
95
+ ...deny !== undefined ? { deny } : {},
96
+ };
97
+ }
98
+ /** Validate one persisted descriptor payload for the current runtime. */
99
+ function parseSubagentDescriptor(value) {
100
+ if (!isRecord(value)) {
101
+ throw new Error('persisted subagent descriptor payload must be an object');
102
+ }
103
+ const version = value['version'];
104
+ if (typeof version !== 'number') {
105
+ throw new Error('persisted subagent descriptor version must be a number');
106
+ }
107
+ if (version !== SUBAGENT_DESCRIPTOR_VERSION)
108
+ return undefined;
109
+ const mode = value['mode'];
110
+ if (mode !== 'one-shot' && mode !== 'continuable') {
111
+ throw new Error('persisted subagent descriptor mode must be "one-shot" or "continuable"');
112
+ }
113
+ assertKnownKeys(value, mode === 'one-shot' ? ONE_SHOT_DESCRIPTOR_KEYS : CONTINUABLE_DESCRIPTOR_KEYS, 'payload');
114
+ const provider = value['provider'];
115
+ if (typeof provider !== 'string') {
116
+ throw new Error('persisted subagent descriptor provider must be a string');
117
+ }
118
+ if (mode === 'one-shot') {
119
+ const label = optionalString(value, 'label');
120
+ return {
121
+ version: SUBAGENT_DESCRIPTOR_VERSION,
122
+ mode,
123
+ provider,
124
+ ...label !== undefined ? { label } : {},
125
+ };
126
+ }
127
+ const label = value['label'];
128
+ if (typeof label !== 'string') {
129
+ throw new Error('persisted subagent descriptor label must be a string');
130
+ }
131
+ const agentProvider = optionalString(value, 'agentProvider');
132
+ const agentModel = optionalString(value, 'agentModel');
133
+ const agentReasoningEffort = optionalString(value, 'agentReasoningEffort');
134
+ const persona = optionalString(value, 'persona');
135
+ const toolFilter = Object.hasOwn(value, 'toolFilter')
136
+ ? parseToolFilter(value['toolFilter'])
137
+ : undefined;
138
+ return {
139
+ version: SUBAGENT_DESCRIPTOR_VERSION,
140
+ mode,
141
+ provider,
142
+ label,
143
+ ...agentProvider !== undefined ? { agentProvider } : {},
144
+ ...agentModel !== undefined ? { agentModel } : {},
145
+ ...agentReasoningEffort !== undefined ? { agentReasoningEffort } : {},
146
+ ...persona !== undefined ? { persona } : {},
147
+ ...toolFilter !== undefined ? { toolFilter } : {},
148
+ };
149
+ }
150
+ /**
151
+ * Validate and detach a continuable descriptor input.
152
+ * @param input - the caller-collected continuable composition fields.
153
+ * @returns the versioned, detached continuable descriptor payload.
154
+ * @throws when a field is not losslessly JSON-serializable.
155
+ */
156
+ export function snapshotSubagentDescriptor(input) {
157
+ const candidate = {
158
+ version: SUBAGENT_DESCRIPTOR_VERSION,
159
+ mode: input.mode,
160
+ provider: input.provider,
161
+ label: input.label,
162
+ ...input.agentProvider !== undefined ? { agentProvider: input.agentProvider } : {},
163
+ ...input.agentModel !== undefined ? { agentModel: input.agentModel } : {},
164
+ ...input.agentReasoningEffort !== undefined ? { agentReasoningEffort: input.agentReasoningEffort } : {},
165
+ ...input.persona !== undefined ? { persona: input.persona } : {},
166
+ ...input.toolFilter !== undefined ? { toolFilter: input.toolFilter } : {},
167
+ };
168
+ const snapshot = snapshotJsonValue(candidate);
169
+ if (snapshot === undefined) {
170
+ throw new Error('subagent descriptor is not losslessly JSON-serializable');
171
+ }
172
+ return snapshot;
173
+ }
174
+ /**
175
+ * Fold a persisted child log to its supported descriptor. The first
176
+ * `subagent/descriptor` event is authoritative — the establishing provider
177
+ * appends exactly one, so a later same-type event cannot rewrite the declared
178
+ * composition.
179
+ * @param events - the loaded child session events.
180
+ * @returns the descriptor, or `undefined` when the log has none or its
181
+ * version is not {@link SUBAGENT_DESCRIPTOR_VERSION} (the child cannot be
182
+ * classified by this runtime).
183
+ * @throws when a current-version persisted payload does not match its complete
184
+ * declared schema.
185
+ */
186
+ export function foldSubagentDescriptor(events) {
187
+ const event = events.find((candidate) => candidate.type === 'subagent/descriptor');
188
+ if (event === undefined)
189
+ return undefined;
190
+ return parseSubagentDescriptor(event.data);
191
+ }
192
+ //# sourceMappingURL=descriptor.js.map
@@ -0,0 +1,11 @@
1
+ /**
2
+ * Typed failures shared by subagent service and provider operations.
3
+ *
4
+ * @module @deepseek-ai/dsh-subagent
5
+ */
6
+ import { HarnessError } from '@deepseek-ai/dsh-llm';
7
+ /** Typed failure for the subagent seam. */
8
+ export declare class SubagentError extends HarnessError {
9
+ constructor(message: string, code: string, options?: ErrorOptions);
10
+ }
11
+ //# sourceMappingURL=error.d.ts.map
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Typed failures shared by subagent service and provider operations.
3
+ *
4
+ * @module @deepseek-ai/dsh-subagent
5
+ */
6
+ import { HarnessError } from '@deepseek-ai/dsh-llm';
7
+ /** Typed failure for the subagent seam. */
8
+ export class SubagentError extends HarnessError {
9
+ constructor(message, code, options) {
10
+ super(message, code, options);
11
+ this.name = 'SubagentError';
12
+ }
13
+ }
14
+ //# sourceMappingURL=error.js.map
@@ -0,0 +1,282 @@
1
+ /**
2
+ * Service Definition for the subagent capability seam (`ctx.subagents`): a named-provider registry plus a
3
+ * capability-validating asynchronous start API. Providers establish a
4
+ * child before returning its run, so fulfillment is the single publication and
5
+ * ownership-transfer boundary.
6
+ *
7
+ * Multiple providers coexist: each registers under a unique name and callers
8
+ * select one by name.
9
+ *
10
+ * This package owns the Service Definition role of the capability seam. Service Providers
11
+ * (`@deepseek-ai/dsh-subagent-spawn-in-process`, `-fork`, `-acp`) and the model-facing
12
+ * consumer (`@deepseek-ai/dsh-tool-subagent`) are separate packages.
13
+ *
14
+ * `startActivation` establishes every child under the activation manager, which
15
+ * owns execution, result delivery, and resource release. Local providers seed
16
+ * resumable Agents; external providers return a single execution handle.
17
+ * `sendMessage` steers between local Agents in one subagent tree without exposing
18
+ * whether a child is resident. Discovery combines real child Sessions with
19
+ * parent-owned records for external executions.
20
+ * Direct discovery reads parent catalogs; descendants recursively read reachable
21
+ * child catalogs. External entries are leaves without local Sessions.
22
+ *
23
+ * Same-process providers are trusted typed collaborators. Requests, provider
24
+ * descriptors, results, and lifecycle payloads are borrowed immutable values;
25
+ * serialization and hostile-input validation belong at real process, worker,
26
+ * persistence, and model boundaries.
27
+ *
28
+ * @module @deepseek-ai/dsh-subagent
29
+ */
30
+ import type { Volatile } from '@deepseek-ai/cordis';
31
+ import { Context, Service } from '@deepseek-ai/cordis';
32
+ import z from '@deepseek-ai/schemastery';
33
+ import type { Scoped } from '@deepseek-ai/dsh-scope';
34
+ import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm';
35
+ import type { Agent } from '@deepseek-ai/dsh-agent';
36
+ import type { SessionId } from '@deepseek-ai/dsh-session';
37
+ import { TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol';
38
+ import type { SubagentInterruptReceipt, SubagentPromptReceipt, SubagentPromptRequest } from './control-types.ts';
39
+ import type { SubagentActivation, SubagentActivationSpec, SubagentInterruptAuthority, SubagentProvider, SubagentRunEndInfo, SubagentRunInfo, SubagentSendMessageOptions } from './types.ts';
40
+ import type { SubagentDescendantListEntry } from './list-children.ts';
41
+ import type { DelegatedApprovalPolicy } from './child-agent.ts';
42
+ export type {} from './catalog.ts';
43
+ export type {} from './projection.ts';
44
+ export * from './out-of-process.ts';
45
+ export { AssistantOutputFold, finalAssistantOutput } from './assistant-output.ts';
46
+ export { SubagentRunId } from './types.ts';
47
+ export type { ContinuableCreateRequest, ContinuableCreateSpec, SubagentCapabilities, SubagentActivation, SubagentActivationSpec, SubagentInterruptAuthority, SubagentProvider, SubagentResult, SubagentRun, SubagentSendMessageOptions, SubagentStartRequest, ResolvedSubagentStartRequest, SubagentStopReason, SubagentStopReasonMap, } from './types.ts';
48
+ export { foldSubagentDescriptor, snapshotSubagentDescriptor, SUBAGENT_DESCRIPTOR_VERSION, } from './descriptor.ts';
49
+ export type { ContinuableSubagentDescriptorData, ContinuableSubagentDescriptorInput, OneShotSubagentDescriptorData, SubagentDescriptorData, } from './descriptor.ts';
50
+ export { STRUCTURED_OUTPUT_TOOL } from './structured.ts';
51
+ export { SubagentError } from './error.ts';
52
+ export { assertSubagentMaxDepth, delegationDepthOf } from './depth.ts';
53
+ export { appendDelegatedPolicyOverrides, applyChildComposition, captureDelegatedPolicyOverrides, childSessionMeta, parentAgentOptionsForDelegation, resolveChildAgentOptions, resolveChildDepth, SubagentDepthError, } from './child-agent.ts';
54
+ export type { ChildComposition, DelegatedApprovalPolicy, DelegatedPolicyOverrides } from './child-agent.ts';
55
+ export type { AgentMessageSource, SubagentSettledMessageSource } from './continuation-messages.ts';
56
+ export type * from './control-types.ts';
57
+ export type { SubagentDescendantListEntry } from './list-children.ts';
58
+ export type { SubagentRunEndInfo, SubagentRunInfo } from './types.ts';
59
+ export type { SubagentCatalogEntry, SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
60
+ declare module '@deepseek-ai/cordis' {
61
+ interface Context {
62
+ subagents: SubagentRuntime;
63
+ }
64
+ interface Events {
65
+ /**
66
+ * A provider became resolvable in the registry.
67
+ * @param provider - the registered provider.
68
+ * @mode emit
69
+ */
70
+ 'subagent/provider-added'(provider: SubagentProvider): void;
71
+ /**
72
+ * A provider left the registry. Accepted runs remain holder-owned.
73
+ * @param name - the provider name that no longer resolves.
74
+ * @mode emit
75
+ */
76
+ 'subagent/provider-removed'(name: string): void;
77
+ /**
78
+ * A provider established a published child. For in-process providers,
79
+ * `ctx.agents.get(info.id)` resolves during this notification.
80
+ * Scope-filtered dispatch keys the carrier by the subagent tree root, so a
81
+ * root-scoped listener observes all subagent tree activations. Paired with
82
+ * `subagent/end`.
83
+ * @param info - provider, child identity, and durable direct creator `parentSessionId`.
84
+ * @mode emit
85
+ */
86
+ 'subagent/start'(this: Scoped<SubagentRuntime>, info: SubagentRunInfo): void;
87
+ /**
88
+ * A published child settled. Scope-filtered dispatch uses the same subagent tree-root
89
+ * carrier as `subagent/start`, so the lifecycle pair reaches the
90
+ * same scoped audience.
91
+ * @param info - run identity, durable direct creator `parentSessionId`, and terminal outcome.
92
+ * @mode emit
93
+ */
94
+ 'subagent/end'(this: Scoped<SubagentRuntime>, info: SubagentRunEndInfo): void;
95
+ }
96
+ }
97
+ /** Host configuration for continuable subagent capacity. */
98
+ export interface Config {
99
+ /**
100
+ * Approval policy seeded onto every in-process child when the approval
101
+ * capability is composed. `'never'` pins deterministic rejection;
102
+ * `'inherit'` seeds the parent's current effective policy so a surface that
103
+ * also answers descendant Agents can decide the child's asks. Defaults to
104
+ * `'never'`.
105
+ */
106
+ delegatedApproval: Volatile<DelegatedApprovalPolicy>;
107
+ /** Maximum live children sharing uninterrupted continuable parent links; defaults to 8. */
108
+ maxActiveSubagents: Volatile<number>;
109
+ /** Default delegation depth for tools without an explicit limit; defaults to 1. */
110
+ maxDepth: Volatile<number>;
111
+ }
112
+ /** Named provider registry with managed activations, durable discovery, and local child messaging. */
113
+ export declare class SubagentRuntime extends TypertRemoteService {
114
+ private config;
115
+ static Config: z<Schemastery.ObjectS<NoInfer<{
116
+ delegatedApproval: z<"never" | "inherit", "never" | "inherit", "volatile-defined">;
117
+ maxDepth: z<number, number, "volatile-defined">;
118
+ maxActiveSubagents: z<number, number, "volatile-defined">;
119
+ }>>, Schemastery.ObjectT<NoInfer<{
120
+ delegatedApproval: z<"never" | "inherit", "never" | "inherit", "volatile-defined">;
121
+ maxDepth: z<number, number, "volatile-defined">;
122
+ maxActiveSubagents: z<number, number, "volatile-defined">;
123
+ }>>, "plain">;
124
+ static inject: string[];
125
+ private providers;
126
+ private manager;
127
+ /**
128
+ * The contained lifecycle-edge publisher. Built here because scoped dispatch
129
+ * keys its carrier by this exact service instance, whose own context filter
130
+ * composes into the carrier.
131
+ */
132
+ private readonly emitLifecycle;
133
+ constructor(ctx: Context, config: Config);
134
+ protected [Service.init](): Promise<void>;
135
+ /**
136
+ * Resolve a delegation tool's depth policy against the current user setting.
137
+ * @param configured - Explicit tool limit, or provider-managed for external delegation.
138
+ * @returns The numeric limit, or undefined when the provider owns depth enforcement.
139
+ */
140
+ resolveMaxDepth(configured?: number | 'provider-managed'): number | undefined;
141
+ /**
142
+ * Start a local child under its reserved identity.
143
+ * @param spec - local task, reserved child id, and result recipient.
144
+ * @returns activation with its accepted initial message id.
145
+ */
146
+ startActivation(spec: SubagentActivationSpec & {
147
+ readonly childId: SessionId;
148
+ }): Promise<SubagentActivation & {
149
+ readonly messageId: MessageId;
150
+ }>;
151
+ /**
152
+ * Start a local or external child.
153
+ * @param spec - task, backend, and result recipient.
154
+ * @returns activation with a message id only for local children.
155
+ */
156
+ startActivation(spec: SubagentActivationSpec): Promise<SubagentActivation>;
157
+ /**
158
+ * Resolve the root shared by an Agent and its other agents in its subagent tree.
159
+ * @param caller - exact live Agent whose subagent ancestry selects the tree.
160
+ * @returns the live root; ordinary Session forks lead independent trees.
161
+ * @throws when the caller or its runtime owner is unavailable.
162
+ */
163
+ rootOf(caller: Agent): Agent;
164
+ /**
165
+ * Join progressing subagent tree work for its root. Idle members with parked input
166
+ * stay resident without delaying host completion. Ordinary members return false.
167
+ * @param root - exact live subagent tree root whose member work is awaited.
168
+ * @returns whether work was joined; hosts recheck root idle after true.
169
+ */
170
+ waitForTreeWork(root: Agent): Promise<boolean>;
171
+ /**
172
+ * Steer one model-authored message to another member of the same subagent tree.
173
+ * A running target receives it at its next step; an idle target starts a turn.
174
+ * A cold target resumes under its runtime subagent tree root without restoring
175
+ * its creation ancestors. Sender identity is rechecked before inbox acceptance; cancellation
176
+ * stops only pre-acceptance work and never retracts an accepted message.
177
+ * @param sender - exact live root or resident continuable Agent originating the message.
178
+ * @param targetId - another root or continuable member's durable Session id.
179
+ * @param content - model-authored content to deliver.
180
+ * @param options - caller cancellation before inbox acceptance.
181
+ * @returns the accepted message's inbox id.
182
+ * @throws when the target is outside the tree, cannot resume, or rejects input.
183
+ */
184
+ sendMessage(sender: Agent, targetId: SessionId, content: ContentBlock[], options: SubagentSendMessageOptions): Promise<MessageId>;
185
+ /**
186
+ * Interrupt one live child's current execution under a trusted user
187
+ * operation or an exact live ancestor Agent. Fire-and-return: the cancel
188
+ * signal is issued before this returns, but the target may keep running
189
+ * until it observes the signal. Unclaimed pending inbox work, the Activation,
190
+ * and published descendants are preserved; claimed work is not requeued.
191
+ * Once the interrupted Agent is idle, a waking send resumes the parked FIFO
192
+ * queue. External backends stop their single execution. An absent target
193
+ * is an accepted no-op, as is a manager-less composition, which cannot own a
194
+ * live Activation.
195
+ * @param targetSessionId - the durable child session id to interrupt.
196
+ * @param authority - a trusted user operation or exact live ancestor Agent.
197
+ * @throws {SubagentError} `UNAUTHORIZED` when the authority does not own the
198
+ * live target.
199
+ */
200
+ interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void;
201
+ /**
202
+ * Close admission and stop all instances in the selected subagent trees, then await
203
+ * pending startup and cleanup. Ordinary members are ignored. The cutoff lasts
204
+ * until each exact root leaves the registry; unrelated subagent trees remain live.
205
+ * @param parents - exact live subagent tree roots entering teardown.
206
+ * @returns once all admitted startup and member cleanup have settled.
207
+ * @throws an aggregate error after all branches settle when any failed.
208
+ */
209
+ drainDescendants(parents: readonly Agent[]): Promise<void>;
210
+ /**
211
+ * Recursively list reachable parent catalogs in stable pre-order, preserving
212
+ * each catalog's event order. Each row carries its catalog parent and depth;
213
+ * external children are leaves; one-shot and unknown-mode children remain
214
+ * traversal nodes. Unknown modes
215
+ * produce unsupported diagnostics. Unreadable child catalogs produce corrupt
216
+ * or unavailable diagnostics and stop only that branch. Root read failures,
217
+ * missing services or projections, and cancellation reject the whole listing.
218
+ * Each catalog is observed once and released before the next read. No Agent
219
+ * is loaded or resumed; Sessions absent from reachable catalogs are omitted.
220
+ * @param rootSessionId - session whose catalog starts descendant discovery.
221
+ * @param signal - cancellation forwarded to and checked around each catalog read.
222
+ * @returns children and branch diagnostics in parent-catalog pre-order.
223
+ * @throws {@link SubagentError} when listing dependencies are unavailable or the caller cancels.
224
+ * @throws SessionQueryError when the root catalog cannot be read.
225
+ */
226
+ listDescendants(rootSessionId: SessionId, signal?: AbortSignal): Promise<SubagentDescendantListEntry[]>;
227
+ /**
228
+ * Deliver one browser-authored message to a continuable child through its
229
+ * live subagent tree root, retaining the caller-minted request identity and
230
+ * validated browser zone on the accepted message. Success identifies the
231
+ * message the child's inbox accepted; later execution is independent of this
232
+ * call. Queue delivery targets a later turn; steer delivery targets the
233
+ * nearest step and retains the Agent loop's best-effort fallback semantics.
234
+ * Image parts are admitted and persisted through the attachment store
235
+ * before delivery, and the child's model must accept image input.
236
+ * Cold resume at capacity rejects with `subagent/delivery-unavailable`.
237
+ * Access is checked on the target Session before attachment admission or restoration.
238
+ * @param request - target id, delivery, minted identity, content, and optional browser zone.
239
+ * @param signal - carrier cancellation, owning the call until inbox acceptance.
240
+ * @returns the accepted message's inbox identity.
241
+ * @throws {RemoteError} `gateway/bad-request`, `subagent/attachment-invalid`,
242
+ * `subagent/invalid-time-zone`,
243
+ * `subagent/not-resumable`, `subagent/unauthorized`,
244
+ * `subagent/delivery-unavailable`, `gateway/cancelled`, or `gateway/internal`.
245
+ */
246
+ prompt(request: SubagentPromptRequest, signal: AbortSignal): Promise<SubagentPromptReceipt>;
247
+ /**
248
+ * Remote face of {@link interrupt}, authorized on the target Session by the Gateway.
249
+ * No catalog, history, persistence, or parent Agent lookup runs.
250
+ * Absent, idle, and already-completed targets are accepted no-ops there.
251
+ * @param childSessionId - durable child session id to interrupt.
252
+ * @returns acknowledgement that the cancel signal was admitted, not that the target is quiescent.
253
+ * @throws {RemoteError} `gateway/bad-request` for an empty id,
254
+ * otherwise `gateway/internal`.
255
+ */
256
+ interruptByUser(childSessionId: SessionId): SubagentInterruptReceipt;
257
+ /**
258
+ * Register a provider under its name. Registration is effect-scoped and HMR
259
+ * safe; removing a provider blocks new starts but does not revoke runs that
260
+ * were already returned to their holders. Providers without either execution
261
+ * method are rejected with UNSUPPORTED_CAPABILITY before registration.
262
+ * @param provider - the trusted provider implementation.
263
+ * @returns the exact Cordis effect disposer.
264
+ */
265
+ registerProvider(provider: SubagentProvider): () => void;
266
+ /**
267
+ * Look up a provider by name.
268
+ * @param name - the provider name.
269
+ * @returns the provider, or undefined when absent.
270
+ */
271
+ getProvider(name: string): SubagentProvider | undefined;
272
+ /** A pending start must use the exact provider whose capabilities were checked. */
273
+ private assertProviderCurrent;
274
+ /** Look up a provider for dispatch or fail loud. */
275
+ private expectProvider;
276
+ /** Resolve the subagent manager or fail loud. */
277
+ private requireManager;
278
+ /** Reject the first requested capability that the provider lacks. */
279
+ private assertCapabilities;
280
+ }
281
+ export default SubagentRuntime;
282
+ //# sourceMappingURL=index.d.ts.map