@deepseek-ai/dsh-subagent 0.0.1-rc.1

package/lib/types/projection-types.js

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

package/lib/types/projection.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
+ *
+ * @module @deepseek-ai/dsh-subagent/projection
+ */
+import type { ProjectionDefinition } from '@deepseek-ai/dsh-session-projection';
+import type { SubagentIdentityProjection } from './projection-types.ts';
+interface TimingState {
+    /** Milliseconds accumulated across completed post-descriptor turns. */
+    settledMs: number;
+    /** Current open interval kept paired inside the fold. */
+    active?: {
+        since: number;
+        through: number;
+    };
+    /** Latest pre-descriptor turn start, promoted when the child's own descriptor arrives. */
+    pendingTurnStart?: number;
+    /** Whether the fold has crossed a descriptor in this logical log. */
+    descriptorSeen: boolean;
+}
+/**
+ * Fold turn boundaries around the child's own durable descriptor.
+ *
+ * A fork seed may contain an ancestor descriptor and completed turns. Every
+ * descriptor therefore resets the accumulated state; the healthy catalog
+ * admits only a child with exactly one descriptor in its own suffix, making
+ * the final reset the child's authoritative timing origin.
+ */
+export declare const subagentTimingProjectionDefinition: ProjectionDefinition<'subagentTiming', TimingState>;
+interface IdentityState {
+    /** Identity from the last valid descriptor; absent before one, and after an invalid one. */
+    identity?: SubagentIdentityProjection;
+}
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export declare const subagentIdentityProjectionDefinition: ProjectionDefinition<'subagent', IdentityState>;
+export {};
+//# sourceMappingURL=projection.d.ts.map

package/lib/types/projection.js

@@ -0,0 +1,135 @@
+/**
+ * Pure session projections for subagent identity (mode/label) and active-turn
+ * duration.
+ *
+ * @module @deepseek-ai/dsh-subagent/projection
+ */
+import { z } from 'zod';
+import { foldSubagentDescriptor } from "./descriptor.js";
+// Zod's optional output includes explicit `undefined`; with
+// exactOptionalPropertyTypes the public interface permits omission only.
+const projectionSchema = z.object({
+    settledMs: z.number().int().nonnegative(),
+    active: z.object({
+        since: z.number().int().nonnegative(),
+        through: z.number().int().nonnegative(),
+    }).strict().optional(),
+}).strict();
+/**
+ * Fold turn boundaries around the child's own durable descriptor.
+ *
+ * A fork seed may contain an ancestor descriptor and completed turns. Every
+ * descriptor therefore resets the accumulated state; the healthy catalog
+ * admits only a child with exactly one descriptor in its own suffix, making
+ * the final reset the child's authoritative timing origin.
+ */
+export const subagentTimingProjectionDefinition = {
+    key: 'subagentTiming',
+    schema: projectionSchema,
+    init: () => ({ descriptorSeen: false, settledMs: 0 }),
+    apply: (state, event) => {
+        if (event.type === 'turn/start') {
+            return state.descriptorSeen
+                ? { ...state, active: { since: event.time, through: event.time } }
+                : { ...state, pendingTurnStart: event.time };
+        }
+        if (event.type === 'subagent/descriptor') {
+            const activeSince = state.active?.since ?? state.pendingTurnStart;
+            return {
+                descriptorSeen: true,
+                settledMs: 0,
+                ...(activeSince === undefined
+                    ? {}
+                    : { active: { since: activeSince, through: event.time } }),
+            };
+        }
+        if (event.type === 'turn/end') {
+            if (!state.descriptorSeen) {
+                if (state.pendingTurnStart === undefined)
+                    return state;
+                const { pendingTurnStart: _closed, ...next } = state;
+                return next;
+            }
+            if (state.active === undefined)
+                return state;
+            const { active, ...rest } = state;
+            return {
+                ...rest,
+                settledMs: state.settledMs + Math.max(0, event.time - active.since),
+            };
+        }
+        if (state.active === undefined)
+            return state;
+        return { ...state, active: { ...state.active, through: event.time } };
+    },
+    view: state => ({
+        settledMs: state.settledMs,
+        ...(state.active === undefined ? {} : { active: state.active }),
+    }),
+    stateVersion: 2,
+};
+// The cast bridges only the optional-label arm: Zod's optional output
+// includes explicit `undefined`, which exactOptionalPropertyTypes excludes
+// from the public interface. The no-value state itself is the serializable
+// `null` arm — never `undefined` — so every registry read and push frame
+// survives JSON.stringify losslessly.
+const identitySchema = z.discriminatedUnion('mode', [
+    z.object({
+        mode: z.literal('one-shot'),
+        label: z.string().optional(),
+        seq: z.number().int().nonnegative(),
+    }).strict(),
+    z.object({
+        mode: z.literal('continuable'),
+        label: z.string(),
+        seq: z.number().int().nonnegative(),
+    }).strict(),
+]).nullable();
+/** Interpret one `subagent/descriptor` event's identity; no value when the payload cannot be trusted. */
+function descriptorIdentity(event) {
+    let descriptor;
+    try {
+        descriptor = foldSubagentDescriptor([event]);
+    }
+    catch {
+        // Only a malformed current-version payload throws in descriptor parsing;
+        // a projection fold must never throw, so damage folds to no value.
+        descriptor = undefined;
+    }
+    if (descriptor === undefined)
+        return undefined;
+    return descriptor.mode === 'one-shot'
+        ? {
+            mode: 'one-shot',
+            ...descriptor.label !== undefined ? { label: descriptor.label } : {},
+            seq: event.seq,
+        }
+        : { mode: 'continuable', label: descriptor.label, seq: event.seq };
+}
+/**
+ * Fold the durable mode/label identity from `subagent/descriptor` events,
+ * last-wins: a fork seed may replay an ancestor's descriptor, and the child's
+ * own descriptor must override it — the same reset discipline as
+ * {@link subagentTimingProjectionDefinition}. A malformed or unknown-version
+ * payload resets to the `null` sentinel instead of throwing, so a fork of a
+ * healthy ancestor never inherits an identity its own descriptor failed to
+ * establish — and the reset survives every JSON push frame, so a consumer
+ * holding the earlier identity replaces it instead of keeping it stale;
+ * `null` ⟺ no valid descriptor, with the causes deliberately undistinguished.
+ */
+export const subagentIdentityProjectionDefinition = {
+    key: 'subagent',
+    schema: identitySchema,
+    init: () => ({}),
+    apply: (state, event) => {
+        if (event.type !== 'subagent/descriptor')
+            return state;
+        const identity = descriptorIdentity(event);
+        return identity === undefined ? {} : { identity };
+    },
+    view: state => state.identity ?? null,
+    // Bumped when the identity gained its `seq` field: an older checkpoint row
+    // would replay into a value the schema rejects, so it must refold instead.
+    stateVersion: 2,
+};
+//# sourceMappingURL=projection.js.map

package/lib/types/run-settlement.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Settlement of one ONE-SHOT subagent run into a background-Task outcome. Only
+ * the one-shot background path uses Tasks; continuable children have no Task,
+ * no per-message result, and no Task cancellation.
+ *
+ * @module @deepseek-ai/dsh-subagent/run-settlement
+ */
+import type { TaskOutcome } from '@deepseek-ai/dsh-tasks';
+import type { SubagentRun } from './types.ts';
+/**
+ * Await the child result, dispose the run, then return its task outcome. Result
+ * and disposal failures become `failed`; when both fail, both details survive.
+ * @param run - live run to settle and release.
+ * @returns outcome after child resources are released.
+ */
+export declare function settleRun(run: SubagentRun): Promise<TaskOutcome>;
+//# sourceMappingURL=run-settlement.d.ts.map

package/lib/types/run-settlement.js

@@ -0,0 +1,59 @@
+/**
+ * Settlement of one ONE-SHOT subagent run into a background-Task outcome. Only
+ * the one-shot background path uses Tasks; continuable children have no Task,
+ * no per-message result, and no Task cancellation.
+ *
+ * @module @deepseek-ai/dsh-subagent/run-settlement
+ */
+/** Flatten a child's final output blocks to the task's final text. */
+function finalText(blocks) {
+    return blocks
+        .filter((block) => block.type === 'text')
+        .map(block => block.text)
+        .join('');
+}
+/**
+ * Map a child result to the task outcome: completed carries final text,
+ * aborted is killed, and every other reason is failed without partial output.
+ * @param result - child terminal result.
+ * @returns outcome for the `ctx.tasks` registration.
+ */
+function runOutcome(result) {
+    switch (result.stopReason) {
+        case 'completed':
+            return { status: 'completed', output: finalText(result.output) };
+        case 'aborted':
+            return { status: 'killed' };
+        case 'error':
+        case 'max-tokens':
+        case 'refusal':
+            return { status: 'failed', detail: result.stopReason };
+        // Merge-extensible reasons remain failures with their raw detail.
+        default:
+            return { status: 'failed', detail: String(result.stopReason) };
+    }
+}
+/**
+ * Await the child result, dispose the run, then return its task outcome. Result
+ * and disposal failures become `failed`; when both fail, both details survive.
+ * @param run - live run to settle and release.
+ * @returns outcome after child resources are released.
+ */
+export async function settleRun(run) {
+    let outcome;
+    try {
+        outcome = runOutcome(await run.result);
+    }
+    catch (error) {
+        outcome = { status: 'failed', detail: String(error) };
+    }
+    try {
+        await run.dispose();
+    }
+    catch (error) {
+        const prefix = outcome.detail === undefined ? '' : `${outcome.detail}; `;
+        return { status: 'failed', detail: `${prefix}dispose failed: ${String(error)}` };
+    }
+    return outcome;
+}
+//# sourceMappingURL=run-settlement.js.map

package/lib/types/types.d.ts

@@ -0,0 +1,293 @@
+/**
+ * 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 } 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;
+/**
+ * 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, absent on infrastructure rejection. */
+    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 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;
+    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` 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 SubagentService.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 (the last assistant message's content). */
+    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;
+    /** 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.
+ */
+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;
+    /**
+     * 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.
+     */
+    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.
+     */
+    prepareContinuable?(request: ContinuableCreateRequest): Promise<ContinuableCreateSpec>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/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