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

package/lib/types/assistant-output.js

@@ -0,0 +1,73 @@
+/**
+ * Canonical selection of a child's final assistant output. Backend run results
+ * and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+ * non-empty assistant message. An empty-content message records usage only
+ * when the loop appends it after a max-tokens step with no executable blocks,
+ * so it does not replace earlier output. If no non-empty message exists,
+ * select the accumulated assistant text. Selection is independent of the
+ * run's stop reason.
+ *
+ * @module @deepseek-ai/dsh-subagent/assistant-output
+ */
+import { joinAssistantStreamText } from '@deepseek-ai/dsh-llm';
+/**
+ * Incremental fold of the selection rule, for backends that observe a child's
+ * output as it streams: session-event backends {@link push} each event, and
+ * transports without session events (ACP content chunks) {@link pushText} raw
+ * text into the same streamed fallback.
+ */
+export class AssistantOutputFold {
+    message;
+    partial = [];
+    /**
+     * Fold one session event: a non-empty assistant message becomes the
+     * candidate final answer, while its embedded stream and any log-only attempt
+     * extend the streamed fallback; every other event contributes nothing.
+     * @param event - the next observed session event.
+     */
+    push(event) {
+        if (event.type === 'assistant/message') {
+            const content = event.data.message.content;
+            if (content.length > 0)
+                this.message = content;
+        }
+        if (event.type === 'assistant/message' || event.type === 'assistant/attempt') {
+            this.pushText(joinAssistantStreamText(event.data.stream));
+        }
+    }
+    /**
+     * Extend the streamed fallback with text observed outside session events.
+     * @param text - the next streamed text piece (an empty piece is a no-op).
+     */
+    pushText(text) {
+        if (text.length > 0)
+            this.partial.push(text);
+    }
+    /**
+     * Select the final output folded so far.
+     * @returns the last non-empty assistant message, else the accumulated
+     *   streamed text, or `undefined` when the child produced neither.
+     */
+    collect() {
+        if (this.message !== undefined)
+            return this.message;
+        const text = this.partial.join('');
+        return text.length > 0 ? [{ type: 'text', text }] : undefined;
+    }
+}
+/**
+ * Apply the selection rule to one complete child-owned event suffix.
+ * @param events - the child-owned events (after any seed or epoch boundary).
+ * @returns the selected output, or `undefined` when the child produced none.
+ */
+export function finalAssistantOutput(events) {
+    // TODO: this folds the complete suffix once per run/epoch settlement. If a
+    // long continuable epoch ever profiles hot here, scan backward with early
+    // exit for the last non-empty message and fold text deltas only on the
+    // no-message fallback.
+    const fold = new AssistantOutputFold();
+    for (const event of events)
+        fold.push(event);
+    return fold.collect();
+}
+//# sourceMappingURL=assistant-output.js.map

package/lib/types/catalog.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Parent-owned durable subagent catalog events and their chunked projection.
+ *
+ * @module @deepseek-ai/dsh-subagent/catalog
+ */
+import { z } from 'zod';
+import type { ChunkedList } from '@deepseek-ai/dsh-chunked-list';
+import type { Session, SessionEvent, SessionHeader, SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session';
+import type { SubagentCatalogEntry } from './projection-types.ts';
+/** Catalog payload version emitted by local child creation. */
+export declare const SUBAGENT_CATALOG_VERSION = 0;
+type KnownCatalogMode = {
+    readonly mode: 'one-shot';
+    readonly label?: string;
+} | {
+    readonly mode: 'continuable';
+    readonly label: string;
+};
+/** Parent catalog v0 records local modes, v1 adds unknown children, and v2 records external executions. */
+export type SubagentCatalogEvent = {
+    readonly childId: SessionId;
+    readonly childCreatedAt: number;
+} & (({
+    readonly version: 0;
+} & KnownCatalogMode) | ({
+    readonly version: 1;
+} & (KnownCatalogMode | {
+    readonly mode: 'unknown';
+    readonly label?: string;
+})) | {
+    readonly version: 2;
+    readonly mode: 'external';
+    readonly label?: string;
+});
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * A direct child's identity and available discovery fields.
+         * @param data - versioned parent-owned catalog entry.
+         */
+        'subagent/catalog': SubagentCatalogEvent;
+    }
+}
+/** Host fold state for one parent catalog. */
+export interface SubagentCatalogState {
+    readonly inheritedEventCount: SessionLogOffset;
+    readonly head?: ChunkedList<SubagentCatalogEvent> | undefined;
+}
+/**
+ * Materialize complete and unknown-mode child identities from parent catalog events.
+ * @param state - parent catalog fold state.
+ * @returns current direct-child rows in parent catalog event order.
+ */
+declare function subagentCatalogEntries(state: SubagentCatalogState): SubagentCatalogEntry[];
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+export declare const subagentCatalogProjectionDefinition: {
+    key: "subagentCatalog";
+    stateSchema: z.ZodType<SubagentCatalogState, unknown, z.core.$ZodTypeInternals<SubagentCatalogState, unknown>>;
+    init: (_header: SessionHeader, inheritedEventCount: SessionLogOffset) => {
+        inheritedEventCount: SessionLogOffset;
+    };
+    apply: (state: NoInfer<SubagentCatalogState>, event: SessionEvent) => SubagentCatalogState;
+    stateVersion: number;
+    wire: {
+        viewSchema: z.ZodType<SubagentCatalogEntry[], unknown, z.core.$ZodTypeInternals<SubagentCatalogEntry[], unknown>>;
+        view: typeof subagentCatalogEntries;
+    };
+};
+/**
+ * Append a complete direct-child discovery fact to its parent Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param child - established child's immutable Session metadata.
+ * @param descriptor - mode-discriminated creation label frozen with the child.
+ */
+export declare function establishCatalogChild(parent: Session, child: SessionHeader, descriptor: {
+    readonly mode: 'continuable';
+    readonly label: string;
+}): void;
+/**
+ * Record an external execution without a local child Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param childId - identity returned by the external provider.
+ * @param label - display label assigned by the caller.
+ */
+export declare function establishExternalCatalogChild(parent: Session, childId: SessionId, label: string): void;
+export {};
+//# sourceMappingURL=catalog.d.ts.map

package/lib/types/catalog.js

@@ -0,0 +1,113 @@
+/**
+ * Parent-owned durable subagent catalog events and their chunked projection.
+ *
+ * @module @deepseek-ai/dsh-subagent/catalog
+ */
+import { z } from 'zod';
+import { appendChunkedList, chunkedListSchema, iterateChunkedList } from '@deepseek-ai/dsh-chunked-list';
+/** Catalog payload version emitted by local child creation. */
+export const SUBAGENT_CATALOG_VERSION = 0;
+const sessionIdSchema = z.string();
+const oneShotCatalogSchema = z.object({
+    version: z.union([z.literal(0), z.literal(1)]),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal('one-shot'),
+    label: z.string().optional(),
+}).strict();
+const continuableCatalogSchema = z.object({
+    version: z.union([z.literal(0), z.literal(1)]),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal('continuable'),
+    label: z.string(),
+}).strict();
+const externalCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(2), mode: z.literal('external') });
+const unknownCatalogSchema = oneShotCatalogSchema.extend({ version: z.literal(1), mode: z.literal('unknown') });
+const eventDataSchema = z.union([
+    oneShotCatalogSchema,
+    externalCatalogSchema,
+    continuableCatalogSchema,
+    unknownCatalogSchema,
+]);
+const viewSchema = z.array(z.union([
+    oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: oneShotCatalogSchema.shape.childCreatedAt,
+    }),
+    externalCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: externalCatalogSchema.shape.childCreatedAt,
+    }),
+    continuableCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: continuableCatalogSchema.shape.childCreatedAt,
+    }),
+    unknownCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+        id: sessionIdSchema,
+        createdAt: unknownCatalogSchema.shape.childCreatedAt,
+    }),
+]));
+const stateSchema = z.object({
+    inheritedEventCount: z.number().int().nonnegative(),
+    head: chunkedListSchema(eventDataSchema).optional(),
+}).strict();
+/**
+ * Materialize complete and unknown-mode child identities from parent catalog events.
+ * @param state - parent catalog fold state.
+ * @returns current direct-child rows in parent catalog event order.
+ */
+function subagentCatalogEntries(state) {
+    const entries = [];
+    for (const data of iterateChunkedList(state.head)) {
+        const { version: _version, childId, childCreatedAt, ...descriptor } = data;
+        entries.push({ id: childId, createdAt: childCreatedAt, ...descriptor });
+    }
+    return entries;
+}
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+export const subagentCatalogProjectionDefinition = {
+    key: 'subagentCatalog',
+    stateSchema,
+    init: (_header, inheritedEventCount) => ({ inheritedEventCount }),
+    apply: (state, event) => {
+        if (event.type !== 'subagent/catalog' || event.seq < state.inheritedEventCount)
+            return state;
+        return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) };
+    },
+    stateVersion: 6,
+    wire: { viewSchema, view: subagentCatalogEntries },
+};
+/**
+ * Append a complete direct-child discovery fact to its parent Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param child - established child's immutable Session metadata.
+ * @param descriptor - mode-discriminated creation label frozen with the child.
+ */
+export function establishCatalogChild(parent, child, descriptor) {
+    parent.append('subagent/catalog', {
+        version: SUBAGENT_CATALOG_VERSION,
+        childId: child.id,
+        childCreatedAt: child.createdAt,
+        mode: descriptor.mode,
+        label: descriptor.label,
+    });
+}
+/** Catalog payload version emitted by external execution creation. */
+const EXTERNAL_SUBAGENT_CATALOG_VERSION = 2;
+/**
+ * Record an external execution without a local child Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param childId - identity returned by the external provider.
+ * @param label - display label assigned by the caller.
+ */
+export function establishExternalCatalogChild(parent, childId, label) {
+    parent.append('subagent/catalog', {
+        version: EXTERNAL_SUBAGENT_CATALOG_VERSION,
+        childId,
+        childCreatedAt: Date.now(),
+        mode: 'external',
+        label,
+    });
+}
+//# sourceMappingURL=catalog.js.map

package/lib/types/child-agent.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Shared in-process child composition: the delegation-depth budget, the
+ * durable session metadata, the resolved child `AgentOptions`, the delegated
+ * policy seed, and the scoped setup used by local activations.
+ *
+ * @module @deepseek-ai/dsh-subagent/child-agent
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentOptions, CreateAgentOptions } from '@deepseek-ai/dsh-agent';
+import type { SandboxMode } from '@deepseek-ai/dsh-sandbox';
+import type { Session, SessionId } from '@deepseek-ai/dsh-session';
+import type { ToolRestriction } from '@deepseek-ai/dsh-tools';
+import type { ApprovalPolicy } from '@deepseek-ai/dsh-user-approval';
+/** Thrown when starting a child would exceed the requested depth cap. */
+export declare class SubagentDepthError extends Error {
+    readonly attemptedDepth: number;
+    readonly maxDepth: number;
+    constructor(attemptedDepth: number, maxDepth: number);
+}
+/**
+ * Resolve the child's delegation depth from its parent and enforce an optional
+ * cap. The persisted parent header is the monotone floor, so a resumed parent
+ * cannot delegate as if it were top-level.
+ * @param parent - the delegating parent agent.
+ * @param maxDepth - optional absolute cap the resolved depth must not exceed.
+ * @returns the child's non-negative safe-integer depth.
+ * @throws {SubagentDepthError} when the resolved depth exceeds `maxDepth`.
+ * @throws {RangeError} when the resolved depth leaves the safe-integer range.
+ */
+export declare function resolveChildDepth(parent: Agent, maxDepth: number | undefined): number;
+/**
+ * Resolve the parent values inherited by a child. The latest request header
+ * owns provider, model, and reasoning effort after request-time selection;
+ * creation options remain the fallback before the first request and retain
+ * the configured output-token limit.
+ * @param parent - delegating parent Agent.
+ * @returns detached Agent options for child-option merging.
+ */
+export declare function parentAgentOptionsForDelegation(parent: Agent): AgentOptions;
+/**
+ * Resolve the child's `AgentOptions`: the parent's provider/model,
+ * reasoning-effort, and maxTokens values unless the request overrides them,
+ * stamped with the child's own delegation depth. Changing the route without
+ * naming an effort clears the parent's route-owned effort so the selected
+ * model resolves its own default.
+ * @param parent - the delegating parent whose route the child inherits.
+ * @param requested - per-child overrides, if any.
+ * @param childDepth - the resolved delegation depth to stamp.
+ * @returns the resolved options for `ctx.agents.create()`.
+ */
+export declare function resolveChildAgentOptions(parent: Agent, requested: AgentOptions | undefined, childDepth: number): AgentOptions;
+/**
+ * Build the child session's durable creation metadata: the parent's workspace,
+ * its direct lineage, coarse product origin, the recursion budget that must
+ * survive persistence, the seed boundary that separates inherited parent
+ * history from child work, and the composition the child runs under.
+ *
+ * Omitted selection uses the parent's live composition, including any switch
+ * made while the parent was blank.
+ * @param parent - the delegating parent agent.
+ * @param childDepth - the resolved delegation depth to persist.
+ * @param isSeeded - whether this child inherits a parent-log prefix, including an explicitly empty one.
+ * @param selectedPreset - independent selection, or omission to inherit the parent.
+ * @returns the `meta` for `ctx.agents.create()`.
+ */
+export declare function childSessionMeta(parent: Agent, childDepth: number, isSeeded: boolean, selectedPreset?: string): NonNullable<CreateAgentOptions['meta']>;
+/** The scoped composition a child agent's creation window applies. */
+export interface ChildComposition {
+    /** Independently mounted preset; omission shares the parent's standing generation. */
+    readonly agentPreset?: string | undefined;
+    /** Historical descriptor persona reapplied only during cold resume. */
+    readonly persona?: string | undefined;
+    /** Historical descriptor tool restriction reapplied only during cold resume. */
+    readonly toolFilter?: ToolRestriction | undefined;
+}
+/**
+ * Model-facing delegation-scope statement for an in-process child whose approval
+ * policy is `never`. A runtime-context contribution rather than a system-prompt
+ * section, so the deployment's system prompt stays uniform across parents and
+ * children.
+ */
+export declare const SUBAGENT_DELEGATION_CONTEXT: string;
+/**
+ * Model-facing delegation-scope statement for an in-process child whose approval
+ * policy is `ask`: the scope stays fixed, but one operation may request a
+ * decision from the user who owns the answerers.
+ */
+export declare const SUBAGENT_DELEGATION_INTERACTIVE_CONTEXT: string;
+/**
+ * Compose a child before publication and restore historical descriptor overrides.
+ * Explicit selection mounts the named preset; omission synchronously joins the
+ * parent's current generation. Registrations belong to the child's scope.
+ * @param childCtx - the child agent's scoped creation context.
+ * @param parent - the delegating parent used when no preset is selected.
+ * @param composition - independent preset and any overrides read from a historical descriptor.
+ * @param approvalPolicy - the child's effective approval policy, selecting its delegation statement.
+ * @returns A promise when mounting an independent preset; otherwise completes synchronously.
+ */
+export declare function applyChildComposition(childCtx: Context, parent: Agent, composition: ChildComposition, approvalPolicy: ApprovalPolicy | undefined): void | Promise<void>;
+/** How a delegated child's approval policy is seeded at creation. */
+export type DelegatedApprovalPolicy = 'never' | 'inherit';
+/** Policy seeded onto a child session's log at the delegation boundary. */
+export interface DelegatedPolicyOverrides {
+    /**
+     * The parent's current preset identity when it runs in Auto or Full access;
+     * the child keeps it under the delegated approval policy.
+     */
+    readonly permissionPreset: 'auto' | 'danger-full-access' | undefined;
+    /** The parent session's explicit sandbox-mode override, or `undefined` without one. */
+    readonly sandboxMode: SandboxMode | undefined;
+    /**
+     * The policy to append to the child's own log, or `undefined` without an
+     * approval capability. `'never'` keeps every ask deterministic; `'ask'`
+     * inherits an interactive parent's policy so a composed answerer may decide
+     * the child's requests.
+     */
+    readonly approvalPolicy: ApprovalPolicy | undefined;
+}
+/**
+ * Capture the permission state to seed into one delegation. Call synchronously before
+ * the child start's first await: a later parent switch belongs to the
+ * parent's future, not to this child. Auto and Full access identities are
+ * inherited only through the in-process DSH path so either can replace a stale
+ * same-bundle fork value. Only the parent session's explicit sandbox override
+ * is captured — never deployment defaults or one-shot grants. Approval is
+ * pinned to `'never'` by default; `'inherit'` seeds the parent's current
+ * effective policy instead, which only a surface that also answers descendant
+ * Agents can turn into a prompt.
+ * @param parent - the delegating parent agent.
+ * @param delegatedApproval - `'never'` to pin rejection, `'inherit'` to seed the parent's effective policy.
+ * @returns the sandbox override (or `undefined` without one) and the approval policy seed.
+ */
+export declare function captureDelegatedPolicyOverrides(parent: Agent, delegatedApproval: DelegatedApprovalPolicy): DelegatedPolicyOverrides;
+/**
+ * Append the captured delegation policy onto the child's own log as
+ * `source: 'delegation'` events after Session announcement and before Agent registration, so the
+ * child's effective policy is reconstructable from its log alone. Appends land
+ * after any fork seed, so fresh policy wins stale seed state; later child
+ * switches still win over these events.
+ * @param childSession - the child's announced, writable Session.
+ * @param overrides - the policy captured at delegation.
+ */
+export declare function appendDelegatedPolicyOverrides(childSession: Session, overrides: DelegatedPolicyOverrides): void;
+/** Identity and lineage inputs shared by every in-process child creation. */
+export interface ChildCreateInputs {
+    /** The child's reserved session id. */
+    readonly sessionId: SessionId;
+    /** The delegating parent agent. */
+    readonly parent: Agent;
+    /** The resolved delegation depth. */
+    readonly childDepth: number;
+    /** How many leading seed events came from the parent's log. */
+    readonly lineageSeedLength: number;
+}
+//# sourceMappingURL=child-agent.d.ts.map

package/lib/types/child-agent.js

@@ -0,0 +1,227 @@
+/**
+ * Shared in-process child composition: the delegation-depth budget, the
+ * durable session metadata, the resolved child `AgentOptions`, the delegated
+ * policy seed, and the scoped setup used by local activations.
+ *
+ * @module @deepseek-ai/dsh-subagent/child-agent
+ */
+import { delegationDepthOf } from "./depth.js";
+import { SubagentError } from "./error.js";
+/** Thrown when starting a child would exceed the requested depth cap. */
+export class SubagentDepthError extends Error {
+    attemptedDepth;
+    maxDepth;
+    constructor(attemptedDepth, maxDepth) {
+        super(`subagent depth ${attemptedDepth} exceeds maxDepth ${maxDepth}`);
+        this.attemptedDepth = attemptedDepth;
+        this.maxDepth = maxDepth;
+        this.name = 'SubagentDepthError';
+    }
+}
+/**
+ * Resolve the child's delegation depth from its parent and enforce an optional
+ * cap. The persisted parent header is the monotone floor, so a resumed parent
+ * cannot delegate as if it were top-level.
+ * @param parent - the delegating parent agent.
+ * @param maxDepth - optional absolute cap the resolved depth must not exceed.
+ * @returns the child's non-negative safe-integer depth.
+ * @throws {SubagentDepthError} when the resolved depth exceeds `maxDepth`.
+ * @throws {RangeError} when the resolved depth leaves the safe-integer range.
+ */
+export function resolveChildDepth(parent, maxDepth) {
+    const childDepth = delegationDepthOf(parent) + 1;
+    if (!Number.isSafeInteger(childDepth)) {
+        throw new RangeError('subagent child depth exceeds the safe-integer range');
+    }
+    if (maxDepth !== undefined && childDepth > maxDepth) {
+        throw new SubagentDepthError(childDepth, maxDepth);
+    }
+    return childDepth;
+}
+/**
+ * Resolve the parent values inherited by a child. The latest request header
+ * owns provider, model, and reasoning effort after request-time selection;
+ * creation options remain the fallback before the first request and retain
+ * the configured output-token limit.
+ * @param parent - delegating parent Agent.
+ * @returns detached Agent options for child-option merging.
+ */
+export function parentAgentOptionsForDelegation(parent) {
+    const requestConfig = parent.session.requestHeader()?.config;
+    if (requestConfig === undefined)
+        return { ...parent.options };
+    const { provider: _createdProvider, model: _createdModel, reasoningEffort: _createdReasoningEffort, ...createdOptions } = parent.options;
+    return {
+        ...createdOptions,
+        provider: requestConfig.provider,
+        model: requestConfig.model,
+        ...requestConfig.reasoningEffort === undefined
+            ? {}
+            : { reasoningEffort: requestConfig.reasoningEffort },
+    };
+}
+/**
+ * Resolve the child's `AgentOptions`: the parent's provider/model,
+ * reasoning-effort, and maxTokens values unless the request overrides them,
+ * stamped with the child's own delegation depth. Changing the route without
+ * naming an effort clears the parent's route-owned effort so the selected
+ * model resolves its own default.
+ * @param parent - the delegating parent whose route the child inherits.
+ * @param requested - per-child overrides, if any.
+ * @param childDepth - the resolved delegation depth to stamp.
+ * @returns the resolved options for `ctx.agents.create()`.
+ */
+export function resolveChildAgentOptions(parent, requested, childDepth) {
+    const parentOptions = parentAgentOptionsForDelegation(parent);
+    const parentProvider = parentOptions.provider;
+    const parentModel = parentOptions.model;
+    const parentReasoningEffort = parentOptions.reasoningEffort;
+    const parentMaxTokens = parentOptions.maxTokens;
+    const resolved = {
+        ...parentProvider !== undefined ? { provider: parentProvider } : {},
+        ...parentModel !== undefined ? { model: parentModel } : {},
+        ...parentReasoningEffort !== undefined ? { reasoningEffort: parentReasoningEffort } : {},
+        ...parentMaxTokens !== undefined ? { maxTokens: parentMaxTokens } : {},
+        ...requested,
+        subagentDepth: childDepth,
+    };
+    const routeChanged = resolved.provider !== parentProvider || resolved.model !== parentModel;
+    if (routeChanged && requested?.reasoningEffort === undefined)
+        delete resolved.reasoningEffort;
+    return resolved;
+}
+/**
+ * Build the child session's durable creation metadata: the parent's workspace,
+ * its direct lineage, coarse product origin, the recursion budget that must
+ * survive persistence, the seed boundary that separates inherited parent
+ * history from child work, and the composition the child runs under.
+ *
+ * Omitted selection uses the parent's live composition, including any switch
+ * made while the parent was blank.
+ * @param parent - the delegating parent agent.
+ * @param childDepth - the resolved delegation depth to persist.
+ * @param isSeeded - whether this child inherits a parent-log prefix, including an explicitly empty one.
+ * @param selectedPreset - independent selection, or omission to inherit the parent.
+ * @returns the `meta` for `ctx.agents.create()`.
+ */
+export function childSessionMeta(parent, childDepth, isSeeded, selectedPreset) {
+    const parentHeader = parent.session.header;
+    const agentPreset = selectedPreset ?? parent.ctx.get('agentPresets')?.composedPreset(parent.ctx);
+    return {
+        ...parentHeader.cwd !== undefined ? { cwd: parentHeader.cwd } : {},
+        ...agentPreset === undefined ? {} : { agentPreset },
+        parentSession: parentHeader.id,
+        isSeeded,
+        // Navigation classification only; the descriptor remains the authority
+        // for mode and continuation capability.
+        origin: 'subagent',
+        // Durable: the recursion budget must survive persistence and resume.
+        delegationDepth: childDepth,
+    };
+}
+/**
+ * Model-facing delegation-scope statement for an in-process child whose approval
+ * policy is `never`. A runtime-context contribution rather than a system-prompt
+ * section, so the deployment's system prompt stays uniform across parents and
+ * children.
+ */
+export const SUBAGENT_DELEGATION_CONTEXT = 'You are a delegated subagent: your permission scope was fixed when you were started and cannot be '
+    + 'widened from inside this session — operations that require approval are rejected automatically. '
+    + 'When the task needs access beyond that scope, do not retry the denied operation; state the '
+    + 'limitation in your reply so the delegating agent can handle it.';
+/**
+ * Model-facing delegation-scope statement for an in-process child whose approval
+ * policy is `ask`: the scope stays fixed, but one operation may request a
+ * decision from the user who owns the answerers.
+ */
+export const SUBAGENT_DELEGATION_INTERACTIVE_CONTEXT = 'You are a delegated subagent: your permission scope was fixed when you were started and cannot be '
+    + 'widened from inside this session. An operation that needs access beyond that scope may request '
+    + 'approval from the user, who can allow or reject it. Do not retry a rejected or denied operation; '
+    + 'state the limitation in your reply so the delegating agent can handle it.';
+/**
+ * Compose a child before publication and restore historical descriptor overrides.
+ * Explicit selection mounts the named preset; omission synchronously joins the
+ * parent's current generation. Registrations belong to the child's scope.
+ * @param childCtx - the child agent's scoped creation context.
+ * @param parent - the delegating parent used when no preset is selected.
+ * @param composition - independent preset and any overrides read from a historical descriptor.
+ * @param approvalPolicy - the child's effective approval policy, selecting its delegation statement.
+ * @returns A promise when mounting an independent preset; otherwise completes synchronously.
+ */
+export function applyChildComposition(childCtx, parent, composition, approvalPolicy) {
+    if (composition.agentPreset !== undefined) {
+        const presets = childCtx.get('agentPresets');
+        if (presets === undefined) {
+            throw new SubagentError('selecting a child agent preset requires the agent-presets service', 'PRESET_UNAVAILABLE');
+        }
+        return presets.mount(childCtx, composition.agentPreset).then(() => {
+            applyChildOverrides(childCtx, composition, approvalPolicy);
+        });
+    }
+    childCtx.get('agentPresets')?.composeFrom(childCtx, parent.ctx);
+    applyChildOverrides(childCtx, composition, approvalPolicy);
+}
+function applyChildOverrides(childCtx, composition, approvalPolicy) {
+    childCtx.systemPrompt.context({
+        name: 'subagent:delegation',
+        order: childCtx.systemPrompt.getContextOrder('SUBAGENT_DELEGATION'),
+        text: approvalPolicy === 'ask'
+            ? SUBAGENT_DELEGATION_INTERACTIVE_CONTEXT
+            : SUBAGENT_DELEGATION_CONTEXT,
+    });
+    if (composition.persona !== undefined) {
+        childCtx.systemPrompt.section({
+            name: 'deployment:persona-prefix',
+            order: childCtx.systemPrompt.getSectionOrder('DEPLOYMENT_PERSONA_PREFIX'),
+            text: composition.persona,
+        });
+    }
+    if (composition.toolFilter !== undefined)
+        childCtx.tools.restrict(composition.toolFilter);
+}
+/**
+ * Capture the permission state to seed into one delegation. Call synchronously before
+ * the child start's first await: a later parent switch belongs to the
+ * parent's future, not to this child. Auto and Full access identities are
+ * inherited only through the in-process DSH path so either can replace a stale
+ * same-bundle fork value. Only the parent session's explicit sandbox override
+ * is captured — never deployment defaults or one-shot grants. Approval is
+ * pinned to `'never'` by default; `'inherit'` seeds the parent's current
+ * effective policy instead, which only a surface that also answers descendant
+ * Agents can turn into a prompt.
+ * @param parent - the delegating parent agent.
+ * @param delegatedApproval - `'never'` to pin rejection, `'inherit'` to seed the parent's effective policy.
+ * @returns the sandbox override (or `undefined` without one) and the approval policy seed.
+ */
+export function captureDelegatedPolicyOverrides(parent, delegatedApproval) {
+    const preset = parent.ctx.get('permissionPresets')?.current(parent.session);
+    const approval = parent.ctx.get('approval');
+    return {
+        permissionPreset: preset === 'auto' || preset === 'danger-full-access' ? preset : undefined,
+        sandboxMode: parent.ctx.get('sandboxPolicy')?.overrideOf(parent.session),
+        approvalPolicy: approval === undefined
+            ? undefined
+            : delegatedApproval === 'inherit' ? approval.effectivePolicy(parent.session) : 'never',
+    };
+}
+/**
+ * Append the captured delegation policy onto the child's own log as
+ * `source: 'delegation'` events after Session announcement and before Agent registration, so the
+ * child's effective policy is reconstructable from its log alone. Appends land
+ * after any fork seed, so fresh policy wins stale seed state; later child
+ * switches still win over these events.
+ * @param childSession - the child's announced, writable Session.
+ * @param overrides - the policy captured at delegation.
+ */
+export function appendDelegatedPolicyOverrides(childSession, overrides) {
+    if (overrides.sandboxMode !== undefined) {
+        childSession.append('sandbox/mode', { mode: overrides.sandboxMode, source: 'delegation' });
+    }
+    if (overrides.approvalPolicy !== undefined) {
+        childSession.append('approval/policy', { policy: overrides.approvalPolicy, source: 'delegation' });
+    }
+    if (overrides.permissionPreset !== undefined) {
+        childSession.append('permission/preset', { preset: overrides.permissionPreset });
+    }
+}
+//# sourceMappingURL=child-agent.js.map

package/lib/types/client.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Browser-safe subagent projection and control vocabulary.
+ *
+ * @module @deepseek-ai/dsh-subagent/client
+ */
+export type * from './control-types.ts';
+export type { SubagentCatalogEntry, SubagentIdentityProjection, SubagentTimingProjection } from './projection-types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,7 @@
+/**
+ * Browser-safe subagent projection and control vocabulary.
+ *
+ * @module @deepseek-ai/dsh-subagent/client
+ */
+export {};
+//# sourceMappingURL=client.js.map