@morlay/dsh-subagent 0.0.6 → 0.0.7

package/src/vendor/dsh-subagent/control.ts

@@ -0,0 +1,123 @@
+/**
+ * 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 type { SessionId } from "@deepseek-ai/dsh-session";
+import { RemoteError } from "@deepseek-ai/dsh-typert-protocol";
+import { z } from "zod";
+import { SubagentError } from "./error.ts";
+
+const SESSION_ID_SCHEMA = z.string().min(1);
+const CONTROL_ID_SCHEMAS = {
+  "subagent.prompt": z.object({
+    parentSessionId: SESSION_ID_SCHEMA,
+    childSessionId: SESSION_ID_SCHEMA,
+    mode: z.literal("continuable"),
+    delivery: z.enum(["queue", "steer"]),
+  }),
+  "subagent.interrupt": z.object({
+    parentSessionId: SESSION_ID_SCHEMA,
+    childSessionId: SESSION_ID_SCHEMA,
+    mode: z.literal("continuable"),
+  }),
+} as const;
+
+/**
+ * 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: keyof typeof CONTROL_ID_SCHEMAS,
+  payload: unknown,
+): void {
+  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: unknown,
+  childSessionId: SessionId,
+  signal: AbortSignal,
+): never {
+  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 does not belong to this parent",
+          { 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: unknown, signal: AbortSignal): boolean {
+  return signal.aborted || (error instanceof SubagentError && error.code === "CANCELLED");
+}

package/src/vendor/dsh-subagent/depth.ts

@@ -0,0 +1,55 @@
+/**
+ * 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 function delegationDepthOf(agent: Agent): number {
+  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: unknown): void {
+  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");
+  }
+}

package/src/vendor/dsh-subagent/descriptor.ts

@@ -0,0 +1,275 @@
+/**
+ * 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 parent 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 { snapshotJsonValue } from "@deepseek-ai/dsh-util-values";
+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 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">;
+
+const DESCRIPTOR_BASE_KEYS = ["version", "mode", "provider", "label"] as const;
+const ONE_SHOT_DESCRIPTOR_KEYS = new Set(DESCRIPTOR_BASE_KEYS);
+const CONTINUABLE_DESCRIPTOR_KEYS = new Set([
+  ...DESCRIPTOR_BASE_KEYS,
+  "agentProvider",
+  "agentModel",
+  "agentReasoningEffort",
+  "persona",
+  "toolFilter",
+]);
+const TOOL_FILTER_KEYS = new Set(["allow", "deny"]);
+
+/** Whether a persisted JSON value is an object record. */
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Reject fields outside one versioned record's declared schema. */
+function assertKnownKeys(
+  value: Record<string, unknown>,
+  keys: ReadonlySet<string>,
+  path: string,
+): void {
+  const unknown = Object.keys(value).find((key) => !keys.has(key));
+  if (unknown !== undefined) {
+    throw new Error(`persisted subagent descriptor ${path} has unknown field "${unknown}"`);
+  }
+}
+
+/** Read one optional string field from a persisted descriptor record. */
+function optionalString(value: Record<string, unknown>, key: string): string | undefined {
+  if (!Object.hasOwn(value, key)) return undefined;
+  const field = value[key];
+  if (typeof field !== "string") {
+    throw new Error(`persisted subagent descriptor ${key} must be a string`);
+  }
+  return field;
+}
+
+/** Read one optional string-array field from a persisted tool restriction. */
+function optionalStringArray(value: Record<string, unknown>, key: string): string[] | undefined {
+  if (!Object.hasOwn(value, key)) return undefined;
+  const field = value[key];
+  if (!Array.isArray(field)) {
+    throw new Error(`persisted subagent descriptor toolFilter.${key} must be an array of strings`);
+  }
+  const items: unknown[] = field;
+  if (items.some((item) => typeof item !== "string")) {
+    throw new Error(`persisted subagent descriptor toolFilter.${key} must be an array of strings`);
+  }
+  return items as string[];
+}
+
+/** Validate and reconstruct a persisted tool restriction. */
+function parseToolFilter(value: unknown): ToolRestriction {
+  if (!isRecord(value)) {
+    throw new Error("persisted subagent descriptor toolFilter must be an object");
+  }
+  assertKnownKeys(value, TOOL_FILTER_KEYS, "toolFilter");
+  const allow = optionalStringArray(value, "allow");
+  const deny = optionalStringArray(value, "deny");
+  if (allow === undefined && deny === undefined) {
+    throw new Error("persisted subagent descriptor toolFilter must declare allow and/or deny");
+  }
+  return {
+    ...(allow !== undefined ? { allow } : {}),
+    ...(deny !== undefined ? { deny } : {}),
+  };
+}
+
+/** Validate one persisted descriptor payload for the current runtime. */
+function parseSubagentDescriptor(value: unknown): SubagentDescriptorData | undefined {
+  if (!isRecord(value)) {
+    throw new Error("persisted subagent descriptor payload must be an object");
+  }
+  const version = value["version"];
+  if (typeof version !== "number") {
+    throw new Error("persisted subagent descriptor version must be a number");
+  }
+  if (version !== SUBAGENT_DESCRIPTOR_VERSION) return undefined;
+
+  const mode = value["mode"];
+  if (mode !== "one-shot" && mode !== "continuable") {
+    throw new Error('persisted subagent descriptor mode must be "one-shot" or "continuable"');
+  }
+  assertKnownKeys(
+    value,
+    mode === "one-shot" ? ONE_SHOT_DESCRIPTOR_KEYS : CONTINUABLE_DESCRIPTOR_KEYS,
+    "payload",
+  );
+  const provider = value["provider"];
+  if (typeof provider !== "string") {
+    throw new Error("persisted subagent descriptor provider must be a string");
+  }
+  if (mode === "one-shot") {
+    const label = optionalString(value, "label");
+    return {
+      version: SUBAGENT_DESCRIPTOR_VERSION,
+      mode,
+      provider,
+      ...(label !== undefined ? { label } : {}),
+    };
+  }
+  const label = value["label"];
+  if (typeof label !== "string") {
+    throw new Error("persisted subagent descriptor label must be a string");
+  }
+  const agentProvider = optionalString(value, "agentProvider");
+  const agentModel = optionalString(value, "agentModel");
+  const agentReasoningEffort = optionalString(value, "agentReasoningEffort") as
+    | ReasoningEffortId
+    | undefined;
+  const persona = optionalString(value, "persona");
+  const toolFilter = Object.hasOwn(value, "toolFilter")
+    ? parseToolFilter(value["toolFilter"])
+    : undefined;
+  return {
+    version: SUBAGENT_DESCRIPTOR_VERSION,
+    mode,
+    provider,
+    label,
+    ...(agentProvider !== undefined ? { agentProvider } : {}),
+    ...(agentModel !== undefined ? { agentModel } : {}),
+    ...(agentReasoningEffort !== undefined ? { agentReasoningEffort } : {}),
+    ...(persona !== undefined ? { persona } : {}),
+    ...(toolFilter !== undefined ? { toolFilter } : {}),
+  };
+}
+
+/**
+ * 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 function snapshotSubagentDescriptor(
+  input: ContinuableSubagentDescriptorInput,
+): ContinuableSubagentDescriptorData {
+  const candidate: ContinuableSubagentDescriptorData = {
+    version: SUBAGENT_DESCRIPTOR_VERSION,
+    mode: input.mode,
+    provider: input.provider,
+    label: input.label,
+    ...(input.agentProvider !== undefined ? { agentProvider: input.agentProvider } : {}),
+    ...(input.agentModel !== undefined ? { agentModel: input.agentModel } : {}),
+    ...(input.agentReasoningEffort !== undefined
+      ? { agentReasoningEffort: input.agentReasoningEffort }
+      : {}),
+    ...(input.persona !== undefined ? { persona: input.persona } : {}),
+    ...(input.toolFilter !== undefined ? { toolFilter: input.toolFilter } : {}),
+  };
+  const snapshot = snapshotJsonValue(candidate);
+  if (snapshot === undefined) {
+    throw new Error("subagent descriptor is not losslessly JSON-serializable");
+  }
+  return snapshot;
+}
+
+/**
+ * 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 function foldSubagentDescriptor(
+  events: readonly SessionEvent[],
+): SubagentDescriptorData | undefined {
+  const event = events.find(
+    (candidate): candidate is SessionEvent<"subagent/descriptor"> =>
+      candidate.type === "subagent/descriptor",
+  );
+  if (event === undefined) return undefined;
+  return parseSubagentDescriptor(event.data);
+}

package/src/vendor/dsh-subagent/error.ts

@@ -0,0 +1,15 @@
+/**
+ * Typed failures shared by subagent service and provider operations.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+
+import { HarnessError } from "@deepseek-ai/dsh-llm";
+
+/** Typed failure for the subagent seam. */
+export class SubagentError extends HarnessError {
+  constructor(message: string, code: string, options?: ErrorOptions) {
+    super(message, code, options);
+    this.name = "SubagentError";
+  }
+}