@toddzheng024/dscode-bundle 0.4.0 → 0.5.0

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

@@ -0,0 +1,207 @@
+/**
+ * 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 a child agent needs. Both the one-shot
+ * provider driver and the continuation manager compose children this way, so
+ * depth accounting, lineage stamping, and delegation policy have one home.
+ *
+ * @module @deepseek-ai/dsh-subagent/child-agent
+ */
+import { delegationDepthOf } from "./depth.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.
+ *
+ * The preset is read from the parent's LIVE scope chain rather than from its
+ * header, because a parent that switched preset while blank runs on the newer
+ * composition and its header still names the older one. Recording it is what
+ * makes a child's history reconstructable: without it a cold read of the child
+ * resolves the deployment default and rebuilds turns under a tool set the
+ * child never had.
+ * @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.
+ * @returns the `meta` for `ctx.agents.create()`.
+ */
+export function childSessionMeta(parent, childDepth, isSeeded) {
+    const parentHeader = parent.session.header;
+    const agentPreset = 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 every in-process child. 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.';
+/**
+ * Compose one child inside its creation window: join its parent's preset,
+ * register the fixed delegation-scope statement, then apply the child's own
+ * shadowing persona section and tool restriction, all owned by the child's
+ * scope and therefore invisible to its parent and siblings. Creation and cold
+ * resume both pass through here.
+ *
+ * The join comes first and the child's own registrations second, which is the
+ * order the layering already implies — the nearest scope wins a name, and a
+ * per-child restriction intersects with everything its chain admits — but
+ * stating it here keeps the two steps from being read as independent.
+ *
+ * The join and the per-child registrations live in ONE call because a child
+ * composed without the join is exactly the defect this function exists to
+ * prevent: with every model-facing row on the agent plane, a child that joins
+ * no preset sees an empty tool registry and none of its parent's prompt
+ * sections. Taking the parent as a parameter is what makes that omission
+ * unrepresentable at the call sites.
+ * @param childCtx - the child agent's scoped creation context.
+ * @param parent - the delegating parent whose composition the child joins.
+ * @param composition - the per-child persona and tool filter to install.
+ */
+export function applyChildComposition(childCtx, parent, composition) {
+    childCtx.get('agentPresets')?.composeFrom(childCtx, parent.ctx);
+    childCtx.systemPrompt.context({
+        name: 'subagent:delegation',
+        order: childCtx.systemPrompt.getContextOrder('SUBAGENT_DELEGATION'),
+        text: 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 policy 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. Only the parent session's explicit
+ * sandbox override is captured — never deployment defaults or one-shot
+ * grants — and the approval policy is pinned to `'never'` regardless of the
+ * parent's own policy.
+ * @param parent - the delegating parent agent.
+ * @returns the sandbox override (or `undefined` without one) and the approval pin.
+ */
+export function captureDelegatedPolicyOverrides(parent) {
+    return {
+        sandboxMode: parent.ctx.get('sandboxPolicy')?.overrideOf(parent.session),
+        approvalPolicy: parent.ctx.get('approval') === undefined ? undefined : 'never',
+    };
+}
+/**
+ * Append the captured delegation policy onto the child's own log as
+ * `source: 'delegation'` events inside the unpublished creation window, 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 unpublished child's 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' });
+    }
+}
+//# sourceMappingURL=child-agent.js.map

package/vendor/subagent-core/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/vendor/subagent-core/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

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

@@ -0,0 +1,251 @@
+/**
+ * Process-local Activation ownership for continuable subagents: admission,
+ * parent-child residency, serialized delivery, settlement, and disposal.
+ *
+ * The continuation manager owns durable request orchestration and delegates
+ * every mutable residency decision to this registry, so delivery and teardown
+ * share one child lock and one Activation map.
+ *
+ * @module @deepseek-ai/dsh-subagent/continuation-activation
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentHandle, AgentOptions, CreateAgentOptions } from '@deepseek-ai/dsh-agent';
+import type { MessageId } from '@deepseek-ai/dsh-llm';
+import type { SessionEvent, SessionId, SessionLogOffset as SessionLogOffsetType, UserMessage } from '@deepseek-ai/dsh-session';
+import type { ToolRestriction } from '@deepseek-ai/dsh-tools';
+import type { DelegatedPolicyOverrides } from './child-agent.ts';
+import type { SubagentDescriptorData } from './descriptor.ts';
+import { SubagentInbox } from './inbox.ts';
+import type { SubagentDelivery } from './inbox.ts';
+import type { ActivationObserver } from './lifecycle.ts';
+/**
+ * One residency epoch for a reconstructed continuable child Agent. It directly
+ * owns the published `AgentHandle`; the registry's private activation-owner
+ * scope is its structural Cordis owner.
+ */
+export interface Activation {
+    /** The durable child this Activation is an epoch of. */
+    readonly childId: SessionId;
+    /**
+     * The durable direct parent, stored because settlement delivery must resolve
+     * that parent after the child handle is gone. {@link ancestry} cannot answer
+     * it: a `WeakSet` is not enumerable, and the child's own header is only
+     * reachable through a handle disposal has already released.
+     */
+    readonly parentSession: SessionId;
+    /** The provider name recorded in the durable descriptor. */
+    readonly provider: string;
+    /** The retained live Agent handle, disposed exactly once at settlement. */
+    readonly handle: AgentHandle;
+    /** The Activation-local admission and close wrapper around the handle's Agent inbox. */
+    readonly inbox: SubagentInbox;
+    /**
+     * Exact live Agent ancestry observed when this Activation materialized.
+     * Weak membership preserves host-scope identity across an intermediate
+     * ancestor leaving the registry without retaining that ancestor's runtime.
+     */
+    readonly ancestry: WeakSet<Agent>;
+    /**
+     * Session ids of the child Activations this one owns. Because one Session has
+     * at most one live Activation, the id identifies the live child without
+     * another runtime-incarnation reference. Non-empty blocks settlement.
+     */
+    readonly ownedChildren: Set<SessionId>;
+    /** The lifecycle observer that emits this epoch's start and terminal edges. */
+    readonly observer: ActivationObserver;
+    /**
+     * Whether any delivery to this child was ever accepted. A materialization
+     * rolled back before its first acceptance is a child the caller was told does
+     * not exist, so its teardown owes the parent no settlement account.
+     */
+    announced: boolean;
+    /** Renewed whenever a settlement watcher must re-check residency state. */
+    poke: PromiseWithResolvers<void>;
+}
+/** Inputs shared by fresh and resumed Activation materialization. */
+export interface MaterializeInputs {
+    childId: SessionId;
+    provider: string;
+    parent: Agent;
+    /**
+     * Creation inputs; absent for a cold resume, which loads the persisted
+     * session — including the delegation policy events a fresh creation seeded,
+     * so a resume never re-captures the parent's policy.
+     */
+    create?: {
+        seed: readonly SessionEvent[] | undefined;
+        meta: NonNullable<CreateAgentOptions['meta']>;
+        /** Exact parent-log prefix length inside {@link seed}. */
+        inheritedEventCount: SessionLogOffsetType;
+        /** Policy captured at delegation: the parent's sandbox override plus the approval pin. */
+        delegatedPolicies: DelegatedPolicyOverrides;
+        /** Child-owned composition record appended after the inherited marker. */
+        descriptor: SubagentDescriptorData;
+    };
+    agentOptions: AgentOptions;
+    composition: {
+        persona?: string | undefined;
+        toolFilter?: ToolRestriction | undefined;
+    };
+    signal: AbortSignal;
+}
+/** Serialize each durable child's delivery, release, and disposal. */
+export declare class ChildLock {
+    private tails;
+    /**
+     * Run `operation` after every previously queued operation for `childId`.
+     * @param childId - the durable child whose operations are linearized.
+     * @param operation - the critical section to run in order.
+     * @returns the operation's own settlement.
+     */
+    run<T>(childId: SessionId, operation: () => Promise<T>): Promise<T>;
+}
+/** Own the complete process-local lifetime of continuable child Activations. */
+export declare class ContinuableActivationRegistry {
+    private readonly ctx;
+    private readonly observeActivation;
+    /** Child session id → its live Activation. Process-local, never durable. */
+    private readonly resident;
+    /** Materializations admitted before drain, tracked through publication or rollback. */
+    private readonly materializations;
+    /** Per-child serializer shared by delivery, release, and disposal. */
+    readonly locks: ChildLock;
+    /** Structural Cordis owner of every Activation handle. */
+    readonly ownerCtx: Context;
+    /**
+     * Exact roots whose host teardown has begun, with the live lineage members
+     * observed under each root. Entries remain until that exact root leaves the
+     * Agent registry, closing admission throughout its host's teardown without
+     * poisoning a later same-id replacement.
+     */
+    private readonly closingScopes;
+    private draining;
+    /**
+     * Build one registry inside the service's Agent-injected context.
+     * @param ctx - context providing Agents, Sessions, and teardown ownership.
+     * @param observeActivation - build the lifecycle observer for one residency epoch.
+     */
+    constructor(ctx: Context, observeActivation: (provider: string, childId: SessionId, parent: Agent) => ActivationObserver);
+    /**
+     * Return the live Activation for a durable child id, if resident.
+     * @param childId - durable child session id to look up.
+     * @returns the process-local Activation, or `undefined` when it is not resident.
+     */
+    get(childId: SessionId): Activation | undefined;
+    /**
+     * Reject one child identity already owned by a live Agent or Session.
+     * @param childId - proposed durable child session id.
+     */
+    assertChildIdAvailable(childId: SessionId): void;
+    /**
+     * Pre-register `childId` in a continuation-managed parent's owned set so the
+     * parent cannot settle while a caller is still establishing or resuming that
+     * child. Returns a releaser for the failure path; it removes only a hold
+     * this call added, and leaves ownership in place once a live Activation for
+     * the child exists.
+     * @param parent - the live direct parent the operation is admitted under.
+     * @param childId - the durable child the operation addresses.
+     * @returns the failure-path releaser; a no-op when nothing was added.
+     */
+    holdOwnership(parent: Agent, childId: SessionId): () => void;
+    /**
+     * Interrupt one live continuable child's current turn under the supplied authority.
+     * @param targetSessionId - the durable child session id to interrupt.
+     * @param authority - the human parent address or exact live ancestor Agent.
+     */
+    interrupt(targetSessionId: SessionId, authority: {
+        readonly kind: 'user';
+        readonly parentSessionId: SessionId;
+    } | {
+        readonly kind: 'ancestor';
+        readonly agent: Agent;
+    }): void;
+    /**
+     * Send through a receiving parent's Activation inbox when it has one.
+     * @param parent - exact live Agent receiving the message.
+     * @param message - durable user message to deliver.
+     * @param delivery - receiving inbox destination.
+     */
+    sendWaking(parent: Agent, message: UserMessage, delivery: SubagentDelivery): void;
+    /**
+     * Close admission, await every already-admitted materialization through
+     * publication or rollback, then dispose the stable live Activation graph
+     * child-first.
+     */
+    drain(): Promise<void>;
+    /**
+     * Stop only the continuable descendants of exact live host-owned parents.
+     * @param parents - exact live roots whose continuable descendants must stop.
+     */
+    drainDescendants(parents: readonly Agent[]): Promise<void>;
+    /**
+     * Release selected resident direct children of one exact live parent.
+     * @param parent - exact live direct parent authorizing the selected release.
+     * @param childIds - durable direct-child ids to release when resident.
+     */
+    drainChildren(parent: Agent, childIds: readonly SessionId[]): Promise<void>;
+    /**
+     * Reject new admission once the registry or this exact parent tree began draining.
+     * @param agent - exact live Agent whose lineage determines admission.
+     */
+    assertAdmitting(agent: Agent): void;
+    /**
+     * Authorize one operation against the durable direct-parent lineage.
+     * @param parent - exact live Agent claiming direct-parent authority.
+     * @param childId - durable child session id addressed by the operation.
+     * @param parentSession - durable direct-parent id recorded by the child.
+     */
+    authorizeLineage(parent: Agent, childId: SessionId, parentSession: SessionId | undefined): void;
+    /**
+     * Create or resume one child Agent and publish its Activation.
+     * @param inputs - reconstruction and admission inputs for the residency epoch.
+     * @returns the published process-local Activation.
+     */
+    materialize(inputs: MaterializeInputs): Promise<Activation>;
+    /**
+     * Cross the final admission cutoff and submit without yielding.
+     * @param activation - the exact resident child receiving the message.
+     * @param message - the already-built durable user message.
+     * @param delivery - the Agent inbox destination.
+     * @param parent - exact live direct parent authorizing admission.
+     * @param signal - caller cancellation before inbox acceptance.
+     * @returns the accepted durable message id.
+     */
+    submitAdmitted(activation: Activation, message: UserMessage, delivery: SubagentDelivery, parent: Agent, signal: AbortSignal): MessageId;
+    /**
+     * Stop and release one Activation through its memoized close transaction.
+     * @param activation - exact residency epoch to close.
+     * @param finalStateFlushed - whether natural settlement already flushed final state.
+     * @returns the shared close transaction.
+     */
+    dispose(activation: Activation, finalStateFlushed?: boolean): Promise<void>;
+    /** Dispose independent roots and report every branch failure after all settle. */
+    private disposeRoots;
+    /** Return the retained member set for one exact scoped-teardown root. */
+    private closingMembers;
+    /** Return the exact currently resolvable ancestry from `agent` upward. */
+    private liveLineage;
+    /** Return the teardown that closed continuable admission for this agent's lineage. */
+    private closingTeardownFor;
+    /** Perform one tracked materialization through publication or rollback. */
+    private materializeTracked;
+    /** Release an Activation whose start edge was not published. */
+    private rollbackUnpublished;
+    /** Register the child in a continuation-managed parent's owned set. */
+    private acquireOwnership;
+    /** Remove one child from its live owner's set and let that owner re-check settlement. */
+    private releaseOwnership;
+    /** Let a settlement watcher re-check residency after relevant state changes. */
+    private wake;
+    /** Follow one Activation to natural settlement. */
+    private watchSettlement;
+    /** Classify one Inbox and owned-child observation without reading Agent execution state. */
+    private settlementState;
+    /** Propagate stop synchronously, then finish the child-first release. */
+    private finishDisposal;
+    /** Tell the durable direct parent how this Activation ended. */
+    private notifySettlement;
+    /** Request a best-effort final session flush before closing natural-settlement admission. */
+    private flushFinalState;
+}
+//# sourceMappingURL=continuation-activation.d.ts.map