@toddzheng024/dscode-bundle 0.4.0 → 0.6.0

package/vendor/subagent-core/types/types.d.ts

@@ -0,0 +1,377 @@
+/**
+ * The seam's consumer-facing contracts: request, result, and capability types
+ * for {@link SubagentProvider}, plus the `subagent/start` and `subagent/end`
+ * payloads that plugins and hosts observe. Internal control interfaces belong
+ * with their implementation — the lifecycle observer in `./lifecycle.ts`, the
+ * continuation host in `./continuation.ts` — so this module stays the published
+ * surface rather than a bag of everything type-shaped.
+ *
+ * @module @deepseek-ai/dsh-subagent/types
+ */
+import type { Agent, AgentOptions } from '@deepseek-ai/dsh-agent';
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { ContentBlock, MessageId } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session';
+import type { ObjectJsonSchema, ToolRestriction } from '@deepseek-ai/dsh-tools';
+import type { SubagentDescriptorData } from './descriptor.ts';
+/** Identifies one accepted subagent run across its lifecycle event pair. */
+export type SubagentRunId = Branded<'SubagentRunId'>;
+/**
+ * Brand a string as a {@link SubagentRunId}.
+ * @param id - the raw run id.
+ * @returns the same string, branded.
+ */
+export declare function SubagentRunId(id: string): SubagentRunId;
+/** What a caller asks for when starting a continuable background child. */
+export interface ContinuableStartSpec {
+    /** The `ctx.subagents` provider whose continuable-creation capability establishes the child. */
+    readonly provider: string;
+    /** The initial delegation's short `description`, persisted as the child's creation label. */
+    readonly label: string;
+    /**
+     * Optional caller-reserved child identity. Omission preserves the manager's
+     * UUID allocation; supplying one lets a durable parent record provisioning
+     * before child materialization without a second identity handshake.
+     */
+    readonly childId?: SessionId;
+    /**
+     * The delegation request. The manager reserves the stable child id, resolves
+     * the durable descriptor, and composes the child itself.
+     */
+    readonly request: Omit<SubagentStartRequest, 'label' | 'signal' | 'outputSchema'>;
+    /** Caller cancellation, owning the operation only until inbox acceptance. */
+    readonly signal: AbortSignal;
+}
+/** Identities returned once a continuable child accepted its initial prompt. */
+export interface ContinuableStart {
+    /** The durable child session id, stable across activations. */
+    readonly childId: SessionId;
+    /** The accepted initial prompt's inbox message id. */
+    readonly messageId: MessageId;
+}
+/**
+ * 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.
+ */
+export type SubagentInterruptAuthority = {
+    readonly kind: 'user';
+    readonly parentSessionId: SessionId;
+} | {
+    readonly kind: 'ancestor';
+    readonly agent: Agent;
+};
+/** Options for one model-authored message between adjacent Agents. */
+export interface SubagentSendMessageOptions {
+    /** Caller cancellation, owning the operation only until inbox acceptance. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Observe-only identifying detail for a published subagent run, carried by
+ * `subagent/start`. One-shot runs and continuable Activation epochs share this
+ * payload, so an observer sees the same vocabulary for both.
+ */
+export interface SubagentRunInfo {
+    /** Unique identity shared with the paired terminal event. */
+    readonly runId: SubagentRunId;
+    /**
+     * Provider name recorded when the child was first created. The provider may
+     * be absent when an accepted one-shot run becomes ready or a persisted
+     * Activation cold-resumes, because neither lifecycle depends on continued
+     * registration.
+     */
+    readonly provider: string;
+    /** The child agent's id. */
+    readonly id: SessionId;
+    /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+    readonly local: boolean;
+}
+/**
+ * Observe-only outcome detail for a settled subagent run, carried by
+ * `subagent/end` and paired with one {@link SubagentRunInfo} by `runId`.
+ */
+export interface SubagentRunEndInfo {
+    /** Unique identity shared with the paired start event. */
+    readonly runId: SubagentRunId;
+    /** The same provider name carried by the paired start event. */
+    readonly provider: string;
+    /** The child agent's id. */
+    readonly id: SessionId;
+    /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+    readonly local: boolean;
+    /** The terminal stop reason. */
+    readonly stopReason: SubagentResult['stopReason'];
+    /**
+     * The child's final assistant output, selected by the same rule as
+     * {@link SubagentResult.output}; absent on infrastructure rejection or when
+     * the child produced none.
+     */
+    readonly lastAssistantMessage?: ContentBlock[];
+}
+/**
+ * Which START-TIME features a provider supports. Checked by the service before delegating to
+ * {@link SubagentProvider.start}: a request that needs a capability the chosen provider lacks
+ * is rejected with a typed error rather than accepted-then-ignored (the "fail loud, no silent
+ * degradation" rule). These flags describe the ONE-SHOT
+ * {@link SubagentProvider.start} path, where the provider composes the child;
+ * continuable children are composed by the continuation manager itself and are
+ * gated by {@link SubagentProvider.prepareContinuable} instead. Each flag
+ * corresponds one-to-one to a {@link SubagentStartRequest} option: `depthLimit`
+ * to `maxDepth`; the other names match.
+ */
+export interface SubagentCapabilities {
+    readonly agentOptions: boolean;
+    readonly outputSchema: boolean;
+    readonly depthLimit: boolean;
+    readonly toolFilter: boolean;
+    readonly persona: boolean;
+}
+/**
+ * What a caller asks for when starting a ONE-SHOT subagent. The tool layer
+ * builds this from the model's `{ description, prompt }` plus its own config;
+ * the service validates {@link SubagentCapabilities} against the named provider
+ * and resolves the durable descriptor before dispatching to
+ * {@link SubagentProvider.start}.
+ */
+export 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;
+}
+/**
+ * Provider-facing one-shot request after {@link SubagentRuntime.start} resolves
+ * the durable child descriptor.
+ */
+export interface ResolvedSubagentStartRequest extends SubagentStartRequest {
+    /** Detached descriptor a session-backed provider persists in the child log. */
+    readonly descriptor: SubagentDescriptorData;
+}
+/**
+ * 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.
+ */
+export 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.
+ */
+export 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[];
+}
+/**
+ * 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.
+ */
+export 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';
+}
+/** The union over {@link SubagentStopReasonMap} — widens automatically as backends merge in variants. */
+export type SubagentStopReason = SubagentStopReasonMap[keyof SubagentStopReasonMap];
+/**
+ * The terminal outcome of a subagent run, resolved by {@link SubagentRun.result}.
+ */
+export 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: 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;
+}
+/**
+ * ONE-SHOT child handle returned after publication. Prompt submission, turn
+ * work, and infrastructure faults after that boundary belong to {@link result}.
+ * Consumers await that result and must always {@link dispose} to cancel
+ * remaining work and reach quiescence. A run is one disposable foreground
+ * delegation with one result; continuable conversations have no run — the
+ * continuation manager holds their `AgentHandle` directly and orders every
+ * turn through the child's own inbox.
+ */
+export interface SubagentRun {
+    /**
+     * Parent-scoped run id. For a local run, this MUST equal the published child
+     * session id, whose `parentSession` records `request.parent.session.id`; a
+     * remote provider mints an id unique in the parent namespace.
+     */
+    readonly id: SessionId;
+    /**
+     * The exact published in-process child, or `undefined` for a remote run.
+     * When present, its id is {@link id}; the provider retains no ownership
+     * implication beyond the run's ordinary {@link dispose} contract.
+     */
+    readonly localAgent: Agent | undefined;
+    /**
+     * 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>;
+}
+/**
+ * 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.
+ */
+export 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 one-shot 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 a ONE-SHOT child and return its handle after publication.
+     * The service has already validated that every requested start-time
+     * capability is supported and resolved `request.descriptor`, so a
+     * session-backed implementation appends that descriptor inside the child's
+     * initial turn. 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: ResolvedSubagentStartRequest): 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 IS the capability: the service rejects continuable starts on
+     * providers without it, while a provider that has it may still serve
+     * ordinary one-shot delegations.
+     *
+     * 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>;
+}
+//# sourceMappingURL=types.d.ts.map

package/vendor/subagent-core/types/types.js

@@ -0,0 +1,19 @@
+/**
+ * The seam's consumer-facing contracts: request, result, and capability types
+ * for {@link SubagentProvider}, plus the `subagent/start` and `subagent/end`
+ * payloads that plugins and hosts observe. Internal control interfaces belong
+ * with their implementation — the lifecycle observer in `./lifecycle.ts`, the
+ * continuation host in `./continuation.ts` — so this module stays the published
+ * surface rather than a bag of everything type-shaped.
+ *
+ * @module @deepseek-ai/dsh-subagent/types
+ */
+/**
+ * Brand a string as a {@link SubagentRunId}.
+ * @param id - the raw run id.
+ * @returns the same string, branded.
+ */
+export function SubagentRunId(id) {
+    return id;
+}
+//# sourceMappingURL=types.js.map

package/vendor/subagent-driver/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/subagent-driver/index.js

@@ -0,0 +1,255 @@
+// dscode-child-cwd-v1
+import { randomUUID } from "node:crypto";
+import { brandString } from "@deepseek-ai/dsh-brand";
+import { foldConsumedWork } from "@deepseek-ai/dsh-agent";
+import { SessionLogOffset } from "@deepseek-ai/dsh-session";
+import { createUserMessage } from "@deepseek-ai/dsh-llm";
+import { appendDelegatedPolicyOverrides, applyChildComposition, assertSubagentMaxDepth, captureDelegatedPolicyOverrides, childSessionMeta, finalAssistantOutput, resolveChildAgentOptions, resolveChildDepth } from "../subagent-core/index.js";
+import { ToolArgsError, validateJsonSchemaValue } from "@deepseek-ai/dsh-tools";
+//#region lib/types/structured.js
+/**
+* Child-scoped structured-output tool, prompt instruction, terminal guard, and authoritative
+* result capture for in-process subagents. Each child registers its real schema on its own
+* scope, so concurrent runs do not interact and disposal leaves no global residue. The prompt
+* contribution is ordinary reconstructed request state.
+*
+* Capture commits only after the authoritative `tools/result` succeeds; PTC mode capture also
+* waits for the enclosing `run_code` result. The terminal result marker and monotonic tool
+* guard prevent later calls from reopening a completed structured run.
+* @module @deepseek-ai/dsh-subagent-in-process-driver/structured
+*/
+/** The model-facing tool name a structured child must call to finish. */
+const STRUCTURED_OUTPUT_TOOL = "structured_output";
+/**
+* The instruction registered as the child's trailing scoped prompt section:
+* the demand travels with the
+* tool, as ordinary prompt state of exactly one agent.
+*/
+const STRUCTURED_OUTPUT_INSTRUCTION = `When you have your final answer, you MUST report it by calling the \`${STRUCTURED_OUTPUT_TOOL}\` tool with arguments matching its parameter schema exactly. Do not finish with a plain text answer: only the tool call counts as your result.`;
+/**
+* Attach the scoped capture tool, instruction, and enforcement to a child during
+* its creation window. Child disposal removes every registration.
+* @param childCtx - the child agent's scope context (`setup`'s argument).
+* @param schema - the trusted, already-asserted schema subset to enforce (see
+*   `assertObjectJsonSchema` in dsh-tools).
+* @returns the attachment handle (read `captured()` after the child settles).
+*/
+function attachStructuredRuntime(childCtx, schema) {
+	/**
+	* Validated values staged by the capture tool body, awaiting THEIR OWN
+	* authoritative `tools/result` notification. The execution object's identity
+	* uniquely identifies a trip through the pipeline: adapter call ids may
+	* repeat across steps, but another execution can never reach this WeakMap
+	* entry. This is distinct from the opaque `ToolExecutionToken` used to
+	* correlate nested transports. The final notification always deletes its own
+	* stage, whether the result succeeded or failed.
+	*/
+	const staged = /* @__PURE__ */ new WeakMap();
+	/** Successful nested capture waiting for its enclosing transport to commit. */
+	let pending;
+	let captured;
+	const schemaEntry = {
+		name: STRUCTURED_OUTPUT_TOOL,
+		description: "Report your final structured result. Call this exactly once, when your answer is complete; the arguments must match this tool's parameter schema exactly.",
+		parameters: schema
+	};
+	childCtx.tools.register({
+		...schemaEntry,
+		output: {
+			schema: {
+				type: "object",
+				properties: { recorded: {
+					type: "boolean",
+					const: true
+				} },
+				required: ["recorded"],
+				additionalProperties: false
+			},
+			render: () => [{
+				type: "text",
+				text: "Structured output recorded."
+			}]
+		},
+		execute(args, exec) {
+			const violations = validateJsonSchemaValue(schema, args);
+			if (violations.length > 0) throw new ToolArgsError(violations);
+			staged.set(exec, { value: args });
+			exec.concludeTurn();
+			return Promise.resolve({ recorded: true });
+		}
+	});
+	childCtx.systemPrompt.section({
+		name: `tool:${STRUCTURED_OUTPUT_TOOL}`,
+		order: childCtx.systemPrompt.getSectionOrder("STRUCTURED_OUTPUT"),
+		text: STRUCTURED_OUTPUT_INSTRUCTION
+	});
+	childCtx.tools.guard((exec) => captured === void 0 && pending === void 0 ? void 0 : `structured output already recorded: the run is complete, so \`${exec.name}\` is not executed`);
+	childCtx.on("tools/result", function(exec, result) {
+		if (exec.name === "structured_output") {
+			const entry = staged.get(exec);
+			if (entry === void 0) return;
+			staged.delete(exec);
+			if (result.isError) return;
+			if (exec.parent === void 0) {
+				/* v8 ignore else -- sequential agent-loop dispatch lets the guard block every later supported call */
+				if (captured === void 0) captured = { value: entry.value };
+			} else if (captured === void 0 && pending === void 0) pending = {
+				parent: exec.parent,
+				value: entry.value
+			};
+			return;
+		}
+		if (pending?.parent !== exec.token) return;
+		const entry = pending;
+		pending = void 0;
+		if (result.isError) return;
+		/* v8 ignore else -- PTC mode serializes outer executions, so the guard blocks every later supported call */
+		if (captured === void 0) captured = { value: entry.value };
+	});
+	return { captured: () => captured };
+}
+//#endregion
+//#region lib/types/index.js
+/**
+* Shared driver for in-process ONE-SHOT subagent providers. The agent factory's
+* creation transaction owns unpublished setup and rollback; after publication
+* the returned AgentHandle is the one quiescent lifecycle owner held by the
+* provider's caller.
+*
+* Continuable children never come through here: the continuation manager
+* composes and drives them directly, so this driver owns exactly one turn with
+* one result.
+*
+* @module @deepseek-ai/dsh-subagent-in-process-driver
+*/
+/** Map a session turn outcome to the subagent seam's terminal vocabulary. */
+function toStopReason(reason) {
+	switch (reason?.kind) {
+		case "completed": return "completed";
+		case "max-tokens": return "max-tokens";
+		case "aborted": return "aborted";
+		case "blocked": return "refusal";
+		default: return "error";
+	}
+}
+/** Error used when cancellation wins before the child publication boundary. */
+function prePublicationAbort() {
+	return /* @__PURE__ */ new Error("subagent request was aborted before child publication");
+}
+/** Append one one-shot descriptor inside the child's initial turn before its first request. */
+function attachDescriptorAppend(childCtx, descriptor) {
+	let appended = false;
+	childCtx.on("agent/pre-step", async ({ agent }, next) => {
+		const decision = await next();
+		if (!appended && decision.kind === "enter") {
+			appended = true;
+			agent.session.append("subagent/descriptor", descriptor);
+		}
+		return decision;
+	});
+}
+/**
+* Establish and drive one in-process one-shot child. Fulfillment means the agent
+* is already published in the registry and transfers its turn, cancellation,
+* and disposal work through the returned run. Rejection means the agent
+* factory's unpublished creation transaction reached quiescence without
+* publishing a child. Every start appends its resolved descriptor inside the
+* child's initial turn.
+* @param request - the trusted typed start request, including its required signal.
+* @param options - the optional fork seed.
+* @returns a published holder-owned run.
+*/
+async function startInProcessRun(request, options) {
+	assertSubagentMaxDepth(request.maxDepth);
+	if (request.signal.aborted) throw prePublicationAbort();
+	const parent = request.parent;
+	const childDepth = resolveChildDepth(parent, request.maxDepth);
+	const childId = brandString(randomUUID());
+	const seed = options.seed;
+	const activationBoundary = SessionLogOffset(seed?.length ?? 0);
+	const inherited = captureDelegatedPolicyOverrides(parent);
+	let structured;
+	const setup = (childCtx, child) => {
+		appendDelegatedPolicyOverrides(child.session, inherited);
+		applyChildComposition(childCtx, parent, {
+			persona: request.persona,
+			toolFilter: request.toolFilter
+		});
+		if (request.outputSchema !== void 0) structured = attachStructuredRuntime(childCtx, request.outputSchema);
+		attachDescriptorAppend(childCtx, request.descriptor);
+	};
+	return drivePublishedRun(await parent.ctx.agents.create({
+		sessionId: childId,
+		parentAgent: parent,
+		meta: childSessionMeta(parent, childDepth, seed !== void 0, request.workspaceCwd),
+		...seed !== void 0 ? { seed } : {},
+		...seed === void 0 ? {} : { inheritedEventCount: activationBoundary },
+		agentOptions: resolveChildAgentOptions(parent, request.agentOptions, childDepth),
+		signal: request.signal,
+		setup
+	}), request.signal, request.prompt, childId, activationBoundary, structured);
+}
+/**
+* Wrap a published child in the single run lifecycle that owns signal handoff,
+* one turn, result settlement, and quiescent disposal.
+*/
+function drivePublishedRun(handle, signal, prompt, childId, boundary, structured) {
+	const child = handle.agent;
+	const flags = { cancelled: false };
+	const onAbort = () => {
+		flags.cancelled = true;
+		child.cancel({ kind: "parent" });
+	};
+	signal.addEventListener("abort", onAbort, { once: true });
+	if (signal.aborted) onAbort();
+	const result = (async () => {
+		try {
+			if (!flags.cancelled) {
+				child.followup(createUserMessage({
+					content: prompt,
+					source: { kind: "user" }
+				}));
+				await child.whenIdle();
+			}
+			return readResult(child, boundary, flags.cancelled, structured ? { captured: structured.captured() } : void 0);
+		} finally {
+			signal.removeEventListener("abort", onAbort);
+		}
+	})();
+	return {
+		id: childId,
+		localAgent: child,
+		result,
+		async dispose() {
+			signal.removeEventListener("abort", onAbort);
+			flags.cancelled = true;
+			const disposal = (await Promise.allSettled([handle.dispose(), result]))[0];
+			if (disposal.status === "rejected") throw disposal.reason;
+		}
+	};
+}
+/** Read one settled child's result from events after its activation boundary. */
+function readResult(child, boundary, cancelled, structured) {
+	const own = child.session.snapshotEvents(boundary);
+	const lastEnd = foldConsumedWork(own).end;
+	const output = finalAssistantOutput(own) ?? [];
+	const recorded = toStopReason(lastEnd?.data.reason);
+	const stopReason = cancelled && recorded !== "completed" ? "aborted" : recorded;
+	if (structured !== void 0) {
+		if (structured.captured !== void 0) return {
+			output,
+			structured: structured.captured.value,
+			stopReason
+		};
+		if (stopReason === "completed") return {
+			output,
+			stopReason: cancelled ? "aborted" : "error"
+		};
+	}
+	return {
+		output,
+		stopReason
+	};
+}
+//#endregion
+export { STRUCTURED_OUTPUT_INSTRUCTION, STRUCTURED_OUTPUT_TOOL, startInProcessRun };