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

package/lib/types/continuation-messages.js

@@ -0,0 +1,116 @@
+/**
+ * Model-visible messages owned by continuable-subagent orchestration.
+ *
+ * @module @deepseek-ai/dsh-subagent/continuation-messages
+ */
+import { boundContextSummary, createUserMessage } from '@deepseek-ai/dsh-llm';
+/** Build durable attribution for one Agent message. */
+function agentMessageSource(sender) {
+    return {
+        kind: 'agent-message',
+        form: 'relay',
+        senderSessionId: sender.id,
+    };
+}
+/**
+ * Build the model-visible and durable representation of one Agent message.
+ * @param sender - exact live Agent that authored the message.
+ * @param content - model-visible message blocks supplied by the sender.
+ * @returns the durable user-message representation delivered to the recipient.
+ */
+export function createAgentMessage(sender, content) {
+    return createUserMessage({
+        content: [
+            { type: 'text', text: `Agent ${sender.id} sent a message: ` },
+            ...content,
+        ],
+        source: agentMessageSource(sender),
+    });
+}
+/**
+ * Append automatic result-delivery guidance to a parent-delivered child's initial task.
+ * @param prompt - initial model-visible task blocks.
+ * @returns task blocks followed by the result-delivery guidance.
+ */
+export function withResultDeliveryGuidance(prompt) {
+    return [
+        ...prompt,
+        {
+            type: 'text',
+            text: 'Your final answer is delivered automatically if your '
+                + 'parent is still online. Include the result and relevant evidence in that answer; the parent does not '
+                + 'receive your full transcript, tool output, or reasoning. If your last action is a message to your '
+                + 'parent, the completion notice omits your final answer; include the result and relevant evidence in that message.',
+        },
+    ];
+}
+/**
+ * One line telling a parent that a background child is finished and why, in
+ * the parent's own task vocabulary.
+ * @param childId - the durable child the parent knows by id.
+ * @param stopReason - how the child's last ordinary turn ended.
+ * @param continuable - whether the child accepts a later message.
+ * @returns the model-facing opening line of the settlement notice.
+ */
+function settlementSummary(childId, stopReason, continuable) {
+    const subject = `Background subagent ${childId}`;
+    switch (stopReason) {
+        case 'completed':
+            return continuable
+                ? `${subject} finished and will do no further work unless you send it more.`
+                : `${subject} finished. It cannot receive follow-up messages.`;
+        case 'aborted':
+            return `${subject} was stopped before it finished.`;
+        case 'max-tokens':
+            return `${subject} ran out of room before it finished.`;
+        // A pre-step rejection — a hook deny, a policy plugin — discarded input
+        // the child had claimed, so the parent must not treat the task as done.
+        case 'refusal':
+            return `${subject} declined the task.`;
+        case 'error':
+            return `${subject} failed before it finished.`;
+        /* v8 ignore next 4 -- `SubagentResult['stopReason']` is merge-extensible, so this arm
+         * needs a backend that adds a variant; an unnameable ending is reported as unfinished
+         * rather than silently as success. */
+        default:
+            return `${subject} ended abnormally (${String(stopReason)}) before it finished.`;
+    }
+}
+/**
+ * Build the runtime-owned settlement notice from the child's nonempty closing text.
+ * @param childId - durable child session id named in the notice.
+ * @param terminal - recorded terminal state for the settled Activation.
+ * @param continuable - whether the child can accept another task.
+ * @param omitClosingText - replace the closing text when the child's last action
+ *   was a message to its direct parent.
+ * @returns the durable user-message representation delivered to the parent.
+ */
+export function createSettlementMessage(childId, terminal, continuable = true, omitClosingText = false) {
+    const summary = settlementSummary(childId, terminal.stopReason, continuable);
+    // Parent providers receive this notice as a user message and may reject
+    // nontext assistant blocks. Keep this conversion local so SDK/UI consumers
+    // retain the complete child output.
+    const closingText = terminal.output.flatMap(block => block.type === 'text' && block.text.length > 0 ? [block] : []);
+    return createUserMessage({
+        content: [
+            { type: 'text', text: summary },
+            ...omitClosingText
+                ? [{ type: 'text', text: 'It sent you a message just before finishing, so its closing message is omitted.' }]
+                : closingText.length === 0
+                    ? [{ type: 'text', text: 'It left no closing message.' }]
+                    : [{ type: 'text', text: 'Its closing message:' }, ...closingText],
+            ...terminal.structured !== undefined
+                ? [{ type: 'text', text: `Structured result: ${JSON.stringify(terminal.structured)}` }] : [],
+            ...terminal.diagnostic !== undefined
+                ? [{ type: 'text', text: terminal.diagnostic }] : [],
+        ],
+        source: {
+            kind: 'subagent-settled',
+            form: 'notice',
+            summary: boundContextSummary(summary),
+            stopReason: terminal.stopReason,
+            senderSessionId: childId,
+        },
+    });
+}
+//# sourceMappingURL=continuation-messages.js.map

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

@@ -0,0 +1,121 @@
+/**
+ * Client-safe recursive catalog rows and browser continuation requests,
+ * receipts, and failures.
+ *
+ * @module @deepseek-ai/dsh-subagent/control-types
+ */
+import type { PromptContentPart } from '@deepseek-ai/dsh-attachment/types';
+import type { Branded } from '@deepseek-ai/dsh-brand';
+import type { MessageId } from '@deepseek-ai/dsh-llm/brand';
+import type { SessionId } from '@deepseek-ai/dsh-session/types';
+import type { KnownSubagentCatalogFields } from './projection-types.ts';
+/**
+ * Client-minted identity of one browser prompt, persisted on the exact accepted
+ * message. It carries the Session Controller's `session-request-id` brand so a
+ * subagent prompt and an ordinary Session prompt share one identity
+ * vocabulary; that package depends on this one, so the brand is spelled here
+ * rather than imported.
+ */
+export type SubagentPromptRequestId = Branded<'session-request-id'>;
+/** Shared child fields for recursive catalog listing. */
+export type SubagentCatalogRow = {
+    /** The durable child session id, stable across Activations. */
+    readonly id: SessionId;
+    /**
+     * Whether recursive catalog listing observed a resident Session. This
+     * does not encode a durable outcome or guarantee continuation delivery.
+     */
+    readonly activity: 'running' | 'inactive';
+} & KnownSubagentCatalogFields;
+/**
+ * One recursive catalog row. Traversal may also return diagnostics for
+ * unknown catalog modes or unreadable child catalogs.
+ */
+export type SubagentListEntry = SubagentCatalogRow & {
+    readonly kind: 'child';
+    /** Whether the child catalog contains a direct child. */
+    readonly hasChildren: boolean;
+} | {
+    readonly kind: 'diagnostic';
+    /** The candidate's session id. */
+    readonly id: SessionId;
+    /**
+     * `corrupt` means the child catalog read found invalid or conflicting
+     * Session data; `unavailable` means it could not be read. Either failure
+     * stops that branch. `unsupported` means the parent catalog records an
+     * unknown child mode; its readable catalog is still traversed.
+     */
+    readonly reason: 'corrupt' | 'unsupported' | 'unavailable';
+};
+/** Durable parent/child browsing address; unknown mode is resolved when child history is read. */
+export type SubagentAddress = {
+    readonly parentSessionId: SessionId;
+    readonly childSessionId: SessionId;
+} & ({
+    readonly mode: 'one-shot';
+} | {
+    readonly mode: 'continuable';
+} | {
+    readonly mode: 'unknown';
+});
+/** One Agent inbox destination for a continuation message. */
+export type SubagentDelivery = 'queue' | 'steer';
+/** One human message addressed to a continuable subagent. */
+export interface SubagentPromptRequest {
+    /** Identity persisted on the accepted message, minted before the call. */
+    readonly requestId: SubagentPromptRequestId;
+    readonly childSessionId: SessionId;
+    /** Whether this message queues a later turn or targets the nearest step. */
+    readonly delivery: SubagentDelivery;
+    /**
+     * Browser prompt parts delivered as the child's user message. The Host
+     * admits and persists image parts before delivery, so the wire never
+     * carries a durable attachment reference the caller could fabricate.
+     */
+    readonly content: readonly PromptContentPart[];
+    /** Optional browser zone sampled for this exact human prompt. */
+    readonly clientTimeZone?: string;
+}
+/** Inbox identity returned once the continuation accepts one human message. */
+export interface SubagentPromptReceipt {
+    readonly messageId: MessageId;
+}
+/** Uniform acknowledgement that one interrupt request was admitted. */
+export interface SubagentInterruptReceipt {
+    readonly accepted: true;
+}
+/**
+ * Failure details the control surface answers with. Prompts and interrupts
+ * share these failures with the Client Remote result.
+ */
+declare module '@deepseek-ai/dsh-workspace/types' {
+    interface SessionActivityKindMap {
+        /** A subagent session delegated from this session (at any depth) is inside a turn. */
+        subagent: true;
+    }
+}
+declare module '@deepseek-ai/dsh-typert-protocol' {
+    interface RemoteErrorDetailsMap {
+        /** A browser-supplied zone is neither UTC nor a canonical IANA name. */
+        'subagent/invalid-time-zone': {
+            readonly value: string;
+        };
+        /** The addressed child cannot take a continuation. */
+        'subagent/not-resumable': {
+            readonly childSessionId: SessionId;
+        };
+        /** The supplied address or live subagent-tree identity could not be verified. */
+        'subagent/unauthorized': {
+            readonly childSessionId: SessionId;
+        };
+        /** Image admission or model image-capability refusal. */
+        'subagent/attachment-invalid': {
+            readonly reason: string;
+        };
+        /** The child exists but its inbox cannot admit the message now. */
+        'subagent/delivery-unavailable': {
+            readonly childSessionId: SessionId;
+        };
+    }
+}
+//# sourceMappingURL=control-types.d.ts.map

package/lib/types/control-types.js

@@ -0,0 +1,8 @@
+/**
+ * Client-safe recursive catalog rows and browser continuation requests,
+ * receipts, and failures.
+ *
+ * @module @deepseek-ai/dsh-subagent/control-types
+ */
+export {};
+//# sourceMappingURL=control-types.js.map

package/lib/types/control.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Browser-facing subagent prompt and interrupt request validation plus the
+ * stable prompt failure codes returned by the Remote surface.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session';
+import { z } from 'zod';
+declare const CONTROL_ID_SCHEMAS: {
+    readonly 'subagent.prompt': z.ZodObject<{
+        childSessionId: z.ZodString;
+        delivery: z.ZodEnum<{
+            queue: "queue";
+            steer: "steer";
+        }>;
+    }, z.core.$strip>;
+    readonly 'subagent.interrupt': z.ZodObject<{
+        childSessionId: z.ZodString;
+    }, z.core.$strip>;
+};
+/**
+ * Apply the subagent payload checks that are stricter than generated
+ * branded-string codecs.
+ * @param method - method name carried in the failure message.
+ * @param payload - decoded control fields to validate.
+ * @throws {RemoteError} `gateway/bad-request` with the original Zod issues.
+ */
+export declare function validateControlRequest(method: keyof typeof CONTROL_ID_SCHEMAS, payload: unknown): void;
+/**
+ * Refuse one continuation prompt without exposing provider detail: admission
+ * failures the caller can act on keep their own code, everything else is
+ * internal.
+ * @param error - the thrown value.
+ * @param childSessionId - the addressed child.
+ * @param signal - the caller's cancellation.
+ * @returns Never — the refusal is thrown.
+ * @throws {RemoteError} always.
+ */
+export declare function rejectPrompt(error: unknown, childSessionId: SessionId, signal: AbortSignal): never;
+export {};
+//# sourceMappingURL=control.d.ts.map

package/lib/types/control.js

@@ -0,0 +1,75 @@
+/**
+ * Browser-facing subagent prompt and interrupt request validation plus the
+ * stable prompt failure codes returned by the Remote surface.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+import { AttachmentError } from '@deepseek-ai/dsh-attachment';
+import { RemoteError } from '@deepseek-ai/dsh-typert-protocol';
+import { z } from 'zod';
+import { SubagentError } from "./error.js";
+const SESSION_ID_SCHEMA = z.string().min(1);
+const CONTROL_ID_SCHEMAS = {
+    'subagent.prompt': z.object({
+        childSessionId: SESSION_ID_SCHEMA,
+        delivery: z.enum(['queue', 'steer']),
+    }),
+    'subagent.interrupt': z.object({
+        childSessionId: SESSION_ID_SCHEMA,
+    }),
+};
+/**
+ * Apply the subagent payload checks that are stricter than generated
+ * branded-string codecs.
+ * @param method - method name carried in the failure message.
+ * @param payload - decoded control fields to validate.
+ * @throws {RemoteError} `gateway/bad-request` with the original Zod issues.
+ */
+export function validateControlRequest(method, payload) {
+    const parsed = CONTROL_ID_SCHEMAS[method].safeParse(payload);
+    if (!parsed.success) {
+        throw new RemoteError('gateway/bad-request', `invalid payload for ${method}`, { issues: parsed.error.issues });
+    }
+}
+/**
+ * Refuse one continuation prompt without exposing provider detail: admission
+ * failures the caller can act on keep their own code, everything else is
+ * internal.
+ * @param error - the thrown value.
+ * @param childSessionId - the addressed child.
+ * @param signal - the caller's cancellation.
+ * @returns Never — the refusal is thrown.
+ * @throws {RemoteError} always.
+ */
+export function rejectPrompt(error, childSessionId, signal) {
+    if (isCancellation(error, signal)) {
+        throw new RemoteError('gateway/cancelled', 'subagent prompt was cancelled', {}, { cause: error });
+    }
+    if (error instanceof AttachmentError) {
+        throw new RemoteError('subagent/attachment-invalid', error.message, { reason: error.code }, { cause: error });
+    }
+    if (error instanceof SubagentError) {
+        switch (error.code) {
+            case 'MODEL_DOES_NOT_SUPPORT_IMAGES':
+                throw new RemoteError('subagent/attachment-invalid', error.message, { reason: error.code }, { cause: error });
+            case 'NOT_RESUMABLE':
+                throw new RemoteError('subagent/not-resumable', 'subagent cannot be resumed', { childSessionId }, { cause: error });
+            case 'UNAUTHORIZED':
+                throw new RemoteError('subagent/unauthorized', 'subagent membership in the active tree could not be verified', { childSessionId }, { cause: error });
+            case 'DRAINING':
+            case 'ACTIVATION_CLOSING':
+            case 'ACTIVATION_LIMIT_REACHED':
+            case 'CONTINUATION_UNAVAILABLE':
+            case 'PERSISTENCE_UNAVAILABLE':
+                throw new RemoteError('subagent/delivery-unavailable', 'subagent follow-up is temporarily unavailable', { childSessionId }, { cause: error });
+            // A code outside the admission vocabulary is not the caller's move to make.
+            default:
+                break;
+        }
+    }
+    throw new RemoteError('gateway/internal', 'subagent prompt failed', {}, { cause: error });
+}
+function isCancellation(error, signal) {
+    return signal.aborted || (error instanceof SubagentError && error.code === 'CANCELLED');
+}
+//# sourceMappingURL=control.js.map

package/lib/types/depth.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Delegation-depth accounting: the recursion budget a parent passes to its
+ * children. Kept apart from the service so composition helpers can read it
+ * without importing the registry.
+ *
+ * @module @deepseek-ai/dsh-subagent/depth
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+declare module '@deepseek-ai/dsh-agent' {
+    interface AgentOptions {
+        /** Delegation depth: zero for a top-level agent and parent depth + 1 for a child. */
+        subagentDepth?: number;
+    }
+}
+/**
+ * Read an agent's delegation depth, treating absence as top-level depth zero.
+ * The persisted session header is authoritative and monotone: runtime
+ * `AgentOptions.subagentDepth` may DEEPEN the count but can never lower it —
+ * a resumed child arrives with fresh options, and counting it from zero would
+ * let it delegate as if it were top-level.
+ * @param agent - the agent whose header and options carry the depth.
+ * @returns its non-negative safe-integer depth.
+ * @throws if the runtime `AgentOptions.subagentDepth` is not a non-negative safe integer.
+ */
+export declare function delegationDepthOf(agent: Agent): number;
+/**
+ * Reject a recursion cap that cannot represent an exact delegation depth.
+ * @param maxDepth - the optional runtime value to validate.
+ */
+export declare function assertSubagentMaxDepth(maxDepth: unknown): void;
+//# sourceMappingURL=depth.d.ts.map

package/lib/types/depth.js

@@ -0,0 +1,39 @@
+/**
+ * Delegation-depth accounting: the recursion budget a parent passes to its
+ * children. Kept apart from the service so composition helpers can read it
+ * without importing the registry.
+ *
+ * @module @deepseek-ai/dsh-subagent/depth
+ */
+/**
+ * Read an agent's delegation depth, treating absence as top-level depth zero.
+ * The persisted session header is authoritative and monotone: runtime
+ * `AgentOptions.subagentDepth` may DEEPEN the count but can never lower it —
+ * a resumed child arrives with fresh options, and counting it from zero would
+ * let it delegate as if it were top-level.
+ * @param agent - the agent whose header and options carry the depth.
+ * @returns its non-negative safe-integer depth.
+ * @throws if the runtime `AgentOptions.subagentDepth` is not a non-negative safe integer.
+ */
+export function delegationDepthOf(agent) {
+    const runtime = agent.options.subagentDepth;
+    if (runtime !== undefined && (!Number.isSafeInteger(runtime) || runtime < 0 || Object.is(runtime, -0))) {
+        throw new TypeError('agent subagentDepth must be a non-negative safe integer');
+    }
+    // The header value was validated at the session boundary (creation and
+    // persistence load both construct through the store).
+    return Math.max(agent.session.header.delegationDepth ?? 0, runtime ?? 0);
+}
+/**
+ * Reject a recursion cap that cannot represent an exact delegation depth.
+ * @param maxDepth - the optional runtime value to validate.
+ */
+export function assertSubagentMaxDepth(maxDepth) {
+    if (maxDepth !== undefined && (typeof maxDepth !== 'number'
+        || !Number.isSafeInteger(maxDepth)
+        || maxDepth < 0
+        || Object.is(maxDepth, -0))) {
+        throw new TypeError('subagent maxDepth must be a non-negative safe integer');
+    }
+}
+//# sourceMappingURL=depth.js.map

package/lib/types/descriptor.d.ts

@@ -0,0 +1,105 @@
+/**
+ * The durable subagent-child descriptor: the versioned, model-hidden
+ * `subagent/descriptor` session event that identifies every session-backed
+ * subagent, including historical one-shot records. The manager appends each
+ * continuable child's descriptor inside its initial turn, preserving the
+ * declared composition required for cold resume.
+ *
+ * The descriptor deliberately snapshots explicit fields rather than the
+ * merge-extensible `AgentOptions` object: an unrelated extension value cannot
+ * make continuation fail merely because it is not JSON, and later composition
+ * inputs require a deliberate {@link SUBAGENT_DESCRIPTOR_VERSION} change. It
+ * omits `subagentDepth` — cold resume trusts the persisted header's
+ * `delegationDepth` as the monotone floor — and `outputSchema`, which belongs
+ * to one activation's result contract rather than durable child composition.
+ * Per-activation knobs such as `maxTokens` are omitted for the same reason as
+ * `outputSchema`: they budget one activation. Cold resume requires the exact
+ * live subagent tree root for authorization but reconstructs child options only from the
+ * durable descriptor, so it neither restores the prior budget nor inherits
+ * the parent's current one; the resumed route's defaults apply instead.
+ *
+ * @module @deepseek-ai/dsh-subagent/descriptor
+ */
+import type { SessionEvent } from '@deepseek-ai/dsh-session';
+import type { ReasoningEffortId } from '@deepseek-ai/dsh-llm';
+import type { ToolRestriction } from '@deepseek-ai/dsh-tools';
+declare module '@deepseek-ai/dsh-session/types' {
+    interface SessionEventMap {
+        /**
+         * Durable identity and lifecycle mode of a session-backed subagent child,
+         * appended once inside the child's initial turn, before its first
+         * request. Continuable records also carry their
+         * resumable composition. Log-only: it carries no `surfaceOp`, never enters
+         * model history, and survives compaction.
+         */
+        'subagent/descriptor': SubagentDescriptorData;
+    }
+}
+/**
+ * The current descriptor format version, stamped into every appended
+ * `subagent/descriptor` event and required verbatim by {@link foldSubagentDescriptor}.
+ * Supporting another composition input is a deliberate version change, never
+ * an implicit extra field.
+ */
+export declare const SUBAGENT_DESCRIPTOR_VERSION = 3;
+/** Fields shared by every supported `subagent/descriptor` payload. */
+interface SubagentDescriptorBase {
+    /** Descriptor format version ({@link SUBAGENT_DESCRIPTOR_VERSION}). */
+    readonly version: number;
+    /** Whether the child is a terminal one-shot run or a resumable conversation. */
+    readonly mode: 'one-shot' | 'continuable';
+    /** The `ctx.subagents` provider name that established the child. */
+    readonly provider: string;
+}
+/** A session-backed subagent that cannot be cold-resumed after its run. */
+export interface OneShotSubagentDescriptorData extends SubagentDescriptorBase {
+    readonly mode: 'one-shot';
+    /**
+     * The initial delegation's short `description`, kept as the child's durable
+     * creation label so enumeration can identify the conversation without
+     * replaying parent tool results or exposing the child prompt.
+     */
+    readonly label?: string;
+}
+/** A session-backed subagent whose declared composition supports cold resume. */
+export interface ContinuableSubagentDescriptorData extends SubagentDescriptorBase {
+    readonly mode: 'continuable';
+    /** The initial delegation's short `description`, used for durable enumeration. */
+    readonly label: string;
+    /** Resolved child `agentOptions.provider`, when one was declared. */
+    readonly agentProvider?: string;
+    /** Resolved child `agentOptions.model`, when one was declared. */
+    readonly agentModel?: string;
+    /** Resolved child `agentOptions.reasoningEffort`, when one was declared. */
+    readonly agentReasoningEffort?: ReasoningEffortId;
+    /** Per-child persona that shadows the deployment persona on resume. */
+    readonly persona?: string;
+    /** Child tool scoping reapplied on resume. */
+    readonly toolFilter?: ToolRestriction;
+}
+/** The supported durable subagent identity and optional continuation composition. */
+export type SubagentDescriptorData = OneShotSubagentDescriptorData | ContinuableSubagentDescriptorData;
+/** Continuable composition fields before the snapshot stamps their format version. */
+export type ContinuableSubagentDescriptorInput = Omit<ContinuableSubagentDescriptorData, 'version'>;
+/**
+ * Validate and detach a continuable descriptor input.
+ * @param input - the caller-collected continuable composition fields.
+ * @returns the versioned, detached continuable descriptor payload.
+ * @throws when a field is not losslessly JSON-serializable.
+ */
+export declare function snapshotSubagentDescriptor(input: ContinuableSubagentDescriptorInput): ContinuableSubagentDescriptorData;
+/**
+ * Fold a persisted child log to its supported descriptor. The first
+ * `subagent/descriptor` event is authoritative — the establishing provider
+ * appends exactly one, so a later same-type event cannot rewrite the declared
+ * composition.
+ * @param events - the loaded child session events.
+ * @returns the descriptor, or `undefined` when the log has none or its
+ *   version is not {@link SUBAGENT_DESCRIPTOR_VERSION} (the child cannot be
+ *   classified by this runtime).
+ * @throws when a current-version persisted payload does not match its complete
+ *   declared schema.
+ */
+export declare function foldSubagentDescriptor(events: readonly SessionEvent[]): SubagentDescriptorData | undefined;
+export {};
+//# sourceMappingURL=descriptor.d.ts.map