@deepseek-ai/dsh-subagent 0.2.1-alpha.1 → 0.2.1-alpha.3

package/lib/types/out-of-process.d.ts

@@ -2,8 +2,7 @@
  * Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
  * that enforce this seam's own contracts around a child in another process:
  * the no-capabilities advertisement, timing-bound validation, child
- * working-directory resolution (config override, else the delegating parent
- * session's workspace), the never-reject result settlement, and the standard
+ * working-directory validation, the never-reject result settlement, and the standard
  * run-handle publication. Backends compose these with their own wire drivers;
  * the process machinery itself (spawn, env scrub, managed-range teardown)
  * belongs to the `dsh-subprocess` seam.
@@ -15,7 +14,7 @@ import type { SubagentCapabilities, SubagentResult, SubagentRun, SubagentStopRea
 /**
  * The capability advertisement of an out-of-process backend: NONE. A child in
  * another process cannot honor parent-enforced start features
- * (`agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
+ * (`agentOptions`/`agentPreset`/`outputSchema`/`maxDepth`), so the service rejects a
  * request needing any of them before `start` runs — never accepted-then-ignored.
  */
 export declare const NO_START_CAPABILITIES: SubagentCapabilities;
@@ -38,31 +37,6 @@ export declare function assertPositiveFinite(prefix: string, name: string, value
  * @returns `cwd`, validated.
  */
 export declare function assertUsableCwd(prefix: string, label: string, cwd: string): string;
-/**
- * Validate a configured `cwd` override ONCE, at plugin load: reject the empty
- * string (`path.resolve('')` is the process cwd — it would silently
- * reintroduce the launch-directory fallback this resolution removes),
- * interpret a relative path against the harness launch directory, and require
- * an enterable directory.
- * @param prefix - the consuming plugin's diagnostic prefix.
- * @param cwd - the configured override, or `undefined` when the config omits it.
- * @returns the validated absolute override, or `undefined` when omitted.
- */
-export declare function validateConfiguredCwd(prefix: string, cwd: string | undefined): string | undefined;
-/**
- * Resolve the child's working directory at start: the deployment override
- * when configured (already validated at load), else the parent session's
- * workspace cwd (validated here, its earliest resolvable point). Fails loud
- * when neither exists — falling back to the harness process cwd would
- * silently bind the child to the server's launch directory instead of the
- * delegating session's workspace (one server process serves many sessions,
- * each with its own cwd).
- * @param prefix - the consuming plugin's diagnostic prefix.
- * @param configured - the load-validated override, or `undefined`.
- * @param parentCwd - the delegating parent session's workspace cwd, if any.
- * @returns the absolute child working directory.
- */
-export declare function resolveChildCwd(prefix: string, configured: string | undefined, parentCwd: string | undefined): string;
 /** Inputs to {@link settleRunResult}. */
 export interface RunResultSettlement {
     /** The turn attempt (typically racing local cancellation); returns the terminal result. */
@@ -112,7 +86,7 @@ export interface SubprocessRunHandleParts {
  * local cancellation — there is no assumption the child cooperates — and then
  * awaits the backend's teardown to actual exit.
  * @param parts - the run identity, result, cancellation wiring, and teardown.
- * @returns the seam run handle (`localAgent` is `undefined` for remote runs).
+ * @returns the external run handle.
  */
 export declare function subprocessRunHandle(parts: SubprocessRunHandleParts): SubagentRun;
 //# sourceMappingURL=out-of-process.d.ts.map

package/lib/types/out-of-process.js

@@ -2,8 +2,7 @@
  * Provider-side vocabulary for OUT-OF-PROCESS subagent backends — the pieces
  * that enforce this seam's own contracts around a child in another process:
  * the no-capabilities advertisement, timing-bound validation, child
- * working-directory resolution (config override, else the delegating parent
- * session's workspace), the never-reject result settlement, and the standard
+ * working-directory validation, the never-reject result settlement, and the standard
  * run-handle publication. Backends compose these with their own wire drivers;
  * the process machinery itself (spawn, env scrub, managed-range teardown)
  * belongs to the `dsh-subprocess` seam.
@@ -11,7 +10,7 @@
  * @module @deepseek-ai/dsh-subagent/out-of-process
  */
 import { accessSync, constants, statSync } from 'node:fs';
-import { isAbsolute, resolve } from 'node:path';
+import { isAbsolute } from 'node:path';
 /** Maximum UTF-8 size of {@link SubagentResult.diagnostic}. */
 const MAX_SUBAGENT_DIAGNOSTIC_BYTES = 4_096;
 const DIAGNOSTIC_TRUNCATION_SUFFIX = '\n[diagnostic truncated]';
@@ -43,15 +42,14 @@ function normalizeSubagentDiagnostic(result) {
 /**
  * The capability advertisement of an out-of-process backend: NONE. A child in
  * another process cannot honor parent-enforced start features
- * (`agentOptions`/`outputSchema`/`maxDepth`/`toolFilter`/`persona`), so the service rejects a
+ * (`agentOptions`/`agentPreset`/`outputSchema`/`maxDepth`), so the service rejects a
  * request needing any of them before `start` runs — never accepted-then-ignored.
  */
 export const NO_START_CAPABILITIES = Object.freeze({
     agentOptions: false,
+    agentPreset: false,
     outputSchema: false,
     depthLimit: false,
-    toolFilter: false,
-    persona: false,
 });
 /**
  * Assert a configured timing bound is a positive finite number (it bounds a
@@ -103,45 +101,6 @@ export function assertUsableCwd(prefix, label, cwd) {
     }
     return cwd;
 }
-/**
- * Validate a configured `cwd` override ONCE, at plugin load: reject the empty
- * string (`path.resolve('')` is the process cwd — it would silently
- * reintroduce the launch-directory fallback this resolution removes),
- * interpret a relative path against the harness launch directory, and require
- * an enterable directory.
- * @param prefix - the consuming plugin's diagnostic prefix.
- * @param cwd - the configured override, or `undefined` when the config omits it.
- * @returns the validated absolute override, or `undefined` when omitted.
- */
-export function validateConfiguredCwd(prefix, cwd) {
-    if (cwd === undefined)
-        return undefined;
-    if (cwd === '') {
-        throw new Error(`${prefix}: config cwd must not be empty — omit the key to inherit the parent session cwd`);
-    }
-    return assertUsableCwd(prefix, 'config cwd', resolve(cwd));
-}
-/**
- * Resolve the child's working directory at start: the deployment override
- * when configured (already validated at load), else the parent session's
- * workspace cwd (validated here, its earliest resolvable point). Fails loud
- * when neither exists — falling back to the harness process cwd would
- * silently bind the child to the server's launch directory instead of the
- * delegating session's workspace (one server process serves many sessions,
- * each with its own cwd).
- * @param prefix - the consuming plugin's diagnostic prefix.
- * @param configured - the load-validated override, or `undefined`.
- * @param parentCwd - the delegating parent session's workspace cwd, if any.
- * @returns the absolute child working directory.
- */
-export function resolveChildCwd(prefix, configured, parentCwd) {
-    if (configured !== undefined)
-        return configured;
-    if (parentCwd === undefined) {
-        throw new Error(`${prefix}: no working directory for the child — configure \`cwd\` or delegate from a parent session that has one`);
-    }
-    return assertUsableCwd(prefix, 'parent session cwd', parentCwd);
-}
 /** Normalize an unknown thrown value to an Error (the catch binding is `unknown`). */
 function toError(value) {
     // The rejecting surfaces (wire clients, spawn failures) only throw
@@ -198,13 +157,12 @@ export async function settleRunResult(parts) {
  * local cancellation — there is no assumption the child cooperates — and then
  * awaits the backend's teardown to actual exit.
  * @param parts - the run identity, result, cancellation wiring, and teardown.
- * @returns the seam run handle (`localAgent` is `undefined` for remote runs).
+ * @returns the external run handle.
  */
 export function subprocessRunHandle(parts) {
     let disposal;
     return {
         id: parts.id,
-        localAgent: undefined,
         result: parts.result,
         dispose() {
             if (disposal !== undefined)

package/lib/types/projection-types.d.ts

@@ -11,6 +11,9 @@ export type SubagentCatalogEntry = {
 } & ({
     readonly mode: 'one-shot';
     readonly label?: string;
+} | {
+    readonly mode: 'external';
+    readonly label?: string;
 } | {
     readonly mode: 'continuable';
     readonly label: string;

package/lib/types/structured.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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/structured
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ObjectJsonSchema } from '@deepseek-ai/dsh-tools';
+/** The model-facing tool name a structured child must call to finish. */
+export declare 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.
+ */
+export declare const STRUCTURED_OUTPUT_INSTRUCTION: string;
+/** One structured run's live handle: read the captured value once the child settles. */
+export interface StructuredAttachment {
+    /**
+     * Input stays closed from capture staging through its final result, including
+     * an enclosing PTC execution. A failed result discards its capture and reopens input.
+     * @returns whether the activation can accept another message.
+     */
+    acceptsInput(): boolean;
+    /**
+     * The captured value, once the child called the tool with valid arguments
+     * and the authoritative final tool result accepted that call.
+     * @returns the committed value, or undefined while none was accepted.
+     */
+    captured(): {
+        value: unknown;
+    } | undefined;
+}
+/**
+ * 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).
+ * @param canComplete - whether accepted input and owned child work have finished.
+ * @returns the attachment handle (read `captured()` after the child settles).
+ */
+export declare function attachStructuredRuntime(childCtx: Context, schema: ObjectJsonSchema, canComplete: () => boolean): StructuredAttachment;
+//# sourceMappingURL=structured.d.ts.map

package/lib/types/structured.js

@@ -0,0 +1,130 @@
+/**
+ * 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/structured
+ */
+import { ToolArgsError, validateJsonSchemaValue } from '@deepseek-ai/dsh-tools';
+/** The model-facing tool name a structured child must call to finish. */
+export 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.
+ */
+export 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).
+ * @param canComplete - whether accepted input and owned child work have finished.
+ * @returns the attachment handle (read `captured()` after the child settles).
+ */
+export function attachStructuredRuntime(childCtx, schema, canComplete) {
+    /**
+     * 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 Map
+     * 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 = new Map();
+    /** 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);
+            // ToolArgsError → isError result with INVALID_ARGS: the model retries
+            // within the same turn, exactly like a schema-validated defineTool call.
+            if (violations.length > 0)
+                throw new ToolArgsError(violations);
+            if (!canComplete())
+                throw new Error('Wait for all delegated child tasks to finish and process pending messages before submitting structured output.');
+            // Two-phase commit, keyed by THIS execution: later transformable
+            // waterfalls may still turn the success into an error. ToolRuntime has
+            // already frozen model-bound arguments at the actual input boundary.
+            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,
+    });
+    // Terminal WITHIN the step. Guards run after the whole pre-execute
+    // waterfall and compose monotonically (deny or abstain, never allow), so a
+    // later prepended listener cannot resurrect dispatch. Calls that precede
+    // capture in the same response remain untouched.
+    childCtx.tools.guard(exec => captured === undefined && pending === undefined
+        ? undefined
+        : `structured output already recorded: the run is complete, so \`${exec.name}\` is not executed`);
+    // The capture COMMIT observes the immutable, authoritative result after the
+    // complete pipeline and outer error normalization. This notification cannot
+    // transform the outcome, so there is no wrapper outside the commit verdict.
+    childCtx.on('tools/result', function (exec, result) {
+        if (exec.name === STRUCTURED_OUTPUT_TOOL) {
+            const entry = staged.get(exec);
+            if (entry === undefined)
+                return;
+            staged.delete(exec);
+            if (result.isError)
+                return;
+            if (exec.parent === undefined) {
+                /* v8 ignore else -- sequential agent-loop dispatch lets the guard block every later supported call */
+                if (captured === undefined)
+                    captured = { value: entry.value };
+            }
+            else {
+                /* v8 ignore else -- PTC mode serializes sub-dispatches, so the guard blocks every later supported call */
+                if (captured === undefined && pending === undefined) {
+                    pending = { parent: exec.parent, value: entry.value };
+                }
+            }
+            return;
+        }
+        if (pending?.parent !== exec.token)
+            return;
+        const entry = pending;
+        pending = undefined;
+        if (result.isError)
+            return;
+        /* v8 ignore else -- PTC mode serializes outer executions, so the guard blocks every later supported call */
+        if (captured === undefined)
+            captured = { value: entry.value };
+    });
+    return {
+        captured: () => captured,
+        acceptsInput: () => staged.size === 0 && pending === undefined && captured === undefined,
+    };
+}
+//# sourceMappingURL=structured.js.map

package/lib/types/types.d.ts

@@ -3,7 +3,7 @@
  * 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
+ * manager host in `./manager.ts` — so this module stays the published
  * surface rather than a bag of everything type-shaped.
  *
  * @module @deepseek-ai/dsh-subagent/types
@@ -12,8 +12,7 @@ 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';
+import type { ObjectJsonSchema } from '@deepseek-ai/dsh-tools';
 /** Identifies one accepted subagent run across its lifecycle event pair. */
 export type SubagentRunId = Branded<'SubagentRunId'>;
 /**
@@ -22,32 +21,34 @@ export type SubagentRunId = Branded<'SubagentRunId'>;
  * @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. */
+/** One managed child execution and its result delivery policy. */
+export interface SubagentActivationSpec {
+    /** Registered backend to use. */
     readonly provider: string;
-    /** The initial delegation's short `description`, persisted as the child's creation label. */
+    /** Short task label retained in cataloged child membership. */
     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.
-     */
+    /** Optional reserved identity for a local child; external backends allocate their own ids. */
     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. */
+    /** Task, parent, and backend-supported execution options. */
+    readonly request: Omit<SubagentStartRequest, 'label' | 'signal'>;
+    /** Cancellation before publication; callers own later cancellation through dispose. */
     readonly signal: AbortSignal;
+    /** Parent delivery notifies the model; caller delivery only returns the result. Local children always enter the parent catalog. */
+    readonly delivery: 'parent' | 'caller';
 }
-/** Identities returned once a continuable child accepted its initial prompt. */
-export interface ContinuableStart {
-    /** The durable child session id, stable across activations. */
+/** A managed execution; disposal addresses this exact activation, never a later resume. */
+export interface SubagentActivation {
+    /** Stable identity of the child. */
     readonly childId: SessionId;
-    /** The accepted initial prompt's inbox message id. */
-    readonly messageId: MessageId;
+    /** Accepted inbox message, when the backend has a local inbox. */
+    readonly messageId?: MessageId;
+    /**
+     * Execution result after teardown settles and notifications are sent; capture failures reject.
+     * Teardown failures are reported by dispose() without replacing a captured result.
+     */
+    readonly result: Promise<SubagentResult>;
+    /** Stop and release this activation and its owned descendants; rejects on teardown failure. */
+    dispose(): Promise<void>;
 }
 /**
  * Authority under which one interrupt request is admitted. `user` carries the
@@ -68,22 +69,19 @@ export interface SubagentSendMessageOptions {
 }
 /**
  * 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.
+ * `subagent/start`. Local and external activations share this payload.
  */
 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.
+     * Provider name recorded when the child was first created, retained even
+     * after that provider is unregistered.
      */
     readonly provider: string;
     /** The child agent's id. */
     readonly id: SessionId;
-    /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+    /** Whether this activation owns a local Agent, fixed at publication. */
     readonly local: boolean;
 }
 /**
@@ -97,7 +95,7 @@ export interface SubagentRunEndInfo {
     readonly provider: string;
     /** The child agent's id. */
     readonly id: SessionId;
-    /** Snapshot of whether `SubagentRun.localAgent` was present when start fulfilled. */
+    /** Whether this activation owns a local Agent, fixed at publication. */
     readonly local: boolean;
     /** The terminal stop reason. */
     readonly stopReason: SubagentResult['stopReason'];
@@ -109,39 +107,39 @@ export interface SubagentRunEndInfo {
     readonly lastAssistantMessage?: readonly 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.
+ * Start-time options supported by a registered backend. The manager checks
+ * every requested option before preparing a local child or starting an external
+ * execution. depthLimit controls maxDepth; the remaining flag names match
+ * SubagentStartRequest fields.
  */
 export interface SubagentCapabilities {
     readonly agentOptions: boolean;
+    /** Supports selecting a preset independently of the parent's composition. */
+    readonly agentPreset: 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}.
+ * Task and optional capabilities supplied to a backend. startActivation carries
+ * these fields in request while owning its label, cancellation, and delivery
+ * policy separately.
  */
 export interface SubagentStartRequest {
+    /** Initial child directory; relative paths resolve against the parent's current directory. Omitted inherits that directory at start. */
+    readonly cwd?: string;
+    /**
+     * Independent preset id; omission joins the parent's current generation.
+     * Requires a provider with `capabilities.agentPreset` that does not inherit
+     * parent context.
+     */
+    readonly agentPreset?: string;
     /** 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.
+     * The spawning agent. Its effective directory supplies the default cwd;
+     * in-process children retain its origin, lineage, and delegation depth.
      */
     readonly parent: Agent;
     /**
@@ -173,30 +171,11 @@ export interface SubagentStartRequest {
      * 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.
- */
+/** Provider-facing request with an absolute directory selected before startup. */
 export interface ResolvedSubagentStartRequest extends SubagentStartRequest {
-    /** Detached descriptor a session-backed provider persists in the child log. */
-    readonly descriptor: SubagentDescriptorData;
+    /** Absolute child directory captured from the parent or explicit request. */
+    readonly cwd: string;
 }
 /**
  * What the continuation manager asks a provider for while materializing one
@@ -206,6 +185,8 @@ export interface ResolvedSubagentStartRequest extends SubagentStartRequest {
  * history.
  */
 export interface ContinuableCreateRequest {
+    /** Absolute initial directory captured before provider preparation. */
+    readonly cwd: string;
     /** The reserved durable child session id, for provider diagnostics. */
     readonly sessionId: SessionId;
     /** The delegating parent agent whose history a seeding provider reads. */
@@ -281,27 +262,15 @@ export interface SubagentResult {
     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.
+ * Backend execution handle owned directly by the activation registry.
+ * A result may become available before resource release; the manager always
+ * disposes the handle and awaits cleanup. Backend startup failures clean up
+ * partial resources before rejecting, while accepted execution failures settle
+ * through result.
  */
 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.
-     */
+    /** Provider-minted id, unique across all parents, providers, and local Sessions in this runtime. */
     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
@@ -336,7 +305,7 @@ export interface SubagentProvider {
      */
     readonly inheritsParentContext: boolean;
     /**
-     * Optional static provider-owned provider/model route for one-shot Agent
+     * Optional static provider-owned provider/model route for child Agent
      * options. Consumers merge tool/model overrides over these values before
      * preflight; providers whose route derives from the parent omit it. The value
      * is detached immutable data and requires `agentOptions` support.
@@ -346,24 +315,21 @@ export interface SubagentProvider {
         model: string;
     }>;
     /**
-     * Establish a ONE-SHOT child and return its handle after publication.
+     * Establish one external execution and return its owned handle.
      * 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
+     * capability is supported. Before fulfillment, the provider owns setup and
+     * cleans any unpublished partial resources before rejecting. Ownership transfers on
      * fulfillment; subsequent turn or infrastructure failure settles through
      * the returned run. Distinct starts may overlap; cancellation, failure,
      * result settlement, and disposal remain independent for each run.
      */
-    start(request: ResolvedSubagentStartRequest): Promise<SubagentRun>;
+    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.
+     * presence selects local activation execution. Providers without it execute
+     * through start and do not accept subsequent messages.
      *
      * This is the provider's ONLY participation in a continuable child. The
      * continuation manager owns identity reservation, composition, Agent

package/lib/types/types.js

@@ -3,7 +3,7 @@
  * 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
+ * manager host in `./manager.ts` — so this module stays the published
  * surface rather than a bag of everything type-shaped.
  *
  * @module @deepseek-ai/dsh-subagent/types

package/locale/en.json

@@ -0,0 +1,5 @@
+{
+  "meta": {
+    "title": "subagent"
+  }
+}