@morlay/dsh-subagent 0.0.6 → 0.0.8

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

@@ -0,0 +1,114 @@
+/**
+ * Continuation integration markers and host adapters outside the public
+ * Service Definition and model-facing Agent messaging contract.
+ * @module @deepseek-ai/dsh-subagent/internal
+ */
+
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { ContentBlock, MessageId, MessageSource } from "@deepseek-ai/dsh-llm";
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { ToolDefinition } from "@deepseek-ai/dsh-tools";
+import type SubagentRuntime from "./index.ts";
+import type { SubagentDelivery } from "./control-types.ts";
+
+/** Process-stable identity carried only by the standard adjacent-Agent messaging tool. */
+export const adjacentAgentSendMessageTool = Symbol.for("dsh.subagent.adjacentAgentSendMessageTool");
+
+/**
+ * Mark the standard adjacent-Agent messaging tool without changing its model-visible schema.
+ * @param definition - the standard `send_message` definition.
+ * @returns the same definition with its internal identity installed.
+ */
+export function markAdjacentAgentSendMessageTool(definition: ToolDefinition): ToolDefinition {
+  Object.defineProperty(definition, adjacentAgentSendMessageTool, { value: true });
+  return definition;
+}
+
+/**
+ * Test whether one visible definition is the standard adjacent-Agent messaging tool.
+ * @param definition - the scope-resolved `send_message` candidate.
+ * @returns whether the definition carries the internal standard-tool identity.
+ */
+export function isAdjacentAgentSendMessageTool(definition: ToolDefinition | undefined): boolean {
+  return (
+    definition !== undefined &&
+    (definition as ToolDefinition & { [adjacentAgentSendMessageTool]?: true })[
+      adjacentAgentSendMessageTool
+    ] === true
+  );
+}
+
+/**
+ * Process-stable symbol-keyed host delivery shared by the bundled runtime
+ * entry and this unbundled internal subpath.
+ * @internal
+ */
+export const deliverSubagentPrompt = Symbol.for("dsh.subagent.deliverPrompt");
+
+/** Runtime face required by the host-only prompt adapters. */
+export interface HostPromptDeliverer {
+  [deliverSubagentPrompt](
+    parent: Agent,
+    childId: SessionId,
+    content: ContentBlock[],
+    source: MessageSource,
+    signal: AbortSignal,
+    delivery: SubagentDelivery,
+  ): Promise<MessageId>;
+}
+
+/**
+ * Queue one host-protocol message without exposing another Service operation.
+ * @param runtime - subagent runtime owning continuation residency.
+ * @param parent - exact live direct parent authorizing delivery.
+ * @param childId - durable direct-child session id.
+ * @param content - host-authored content to deliver.
+ * @param source - durable host-protocol source descriptor.
+ * @param signal - caller cancellation before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ */
+export function queueHostSubagentPrompt(
+  runtime: SubagentRuntime,
+  parent: Agent,
+  childId: SessionId,
+  content: ContentBlock[],
+  source: MessageSource,
+  signal: AbortSignal,
+): Promise<MessageId> {
+  return (runtime as unknown as HostPromptDeliverer)[deliverSubagentPrompt](
+    parent,
+    childId,
+    content,
+    source,
+    signal,
+    "queue",
+  );
+}
+
+/**
+ * Steer one host-protocol message without exposing another Service operation.
+ * @param runtime - subagent runtime owning continuation residency.
+ * @param parent - exact live direct parent authorizing delivery.
+ * @param childId - durable direct-child session id.
+ * @param content - host-authored content to deliver.
+ * @param source - durable host-protocol source descriptor.
+ * @param signal - caller cancellation before inbox acceptance.
+ * @returns the accepted message's inbox id.
+ */
+export function steerHostSubagentPrompt(
+  runtime: SubagentRuntime,
+  parent: Agent,
+  childId: SessionId,
+  content: ContentBlock[],
+  source: MessageSource,
+  signal: AbortSignal,
+): Promise<MessageId> {
+  return (runtime as unknown as HostPromptDeliverer)[deliverSubagentPrompt](
+    parent,
+    childId,
+    content,
+    source,
+    signal,
+    "steer",
+  );
+}

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

@@ -0,0 +1,172 @@
+/**
+ * Lifecycle-edge publication for managed subagent activations.
+ *
+ * Public event payloads live in `./types.ts`; the package-private observer
+ * retains only the identity shared by each start/end pair.
+ *
+ * @module @deepseek-ai/dsh-subagent/lifecycle
+ */
+
+import { randomUUID } from "node:crypto";
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import { foldConsumedWork } from "@deepseek-ai/dsh-agent";
+import type { SessionEvent, SessionId } from "@deepseek-ai/dsh-session";
+import { SubagentRunId } from "./types.ts";
+import type { SubagentResult, SubagentRunEndInfo, SubagentRunInfo } from "./types.ts";
+
+/**
+ * Lifecycle observer for one activation's residency epoch. Package-private: the
+ * continuation manager is the only consumer, and its call ordering is an
+ * in-package contract rather than a published extension point.
+ */
+export interface ActivationObserver {
+  /**
+   * Publish the start edge once the epoch is resident.
+   * @param child - the resident local Agent, or undefined for an external execution.
+   */
+  start(child?: Agent): void;
+  /**
+   * Publish the terminal edge exactly once, pairing this epoch's {@link start},
+   * after the disposal outcome is known. Called only for a resident epoch: a
+   * failure before residency publishes no edge, because inventing one would
+   * report a lifecycle the child never had.
+   * @param result - the captured result, with teardown failures applied.
+   */
+  settle(result: SubagentResult): void;
+}
+
+/**
+ * Publish one lifecycle edge with per-listener exception containment. Run edges
+ * carry the delegating parent that keys scoped dispatch; provider removal has no
+ * parent carrier and reaches listeners unscoped.
+ *
+ * The service owns this closure because scoped dispatch keys its carrier by the
+ * exact service instance, whose own context filter composes into the carrier;
+ * a narrowed stand-in would silently change scope filtering.
+ */
+export type LifecycleEmitter = {
+  (name: "subagent/start", info: SubagentRunInfo, parent: Agent): void;
+  (name: "subagent/end", info: SubagentRunEndInfo, parent: Agent): void;
+  (name: "subagent/provider-removed", info: string): void;
+};
+
+/**
+ * Build the contained lifecycle emitter this seam publishes every edge through.
+ * Every listener is independently contained: a synchronous throw or a rejected
+ * returned promise is logged without starving peer listeners, changing the run,
+ * or — for provider removal, which fires from a disposer — breaking teardown.
+ * @param ctx - the service's own context, owning dispatch and the logger.
+ * @param carrier - resolve the scoped dispatch carrier for one delegating parent.
+ * @returns the emitter both observers and the provider registry publish through.
+ */
+export function createLifecycleEmitter(
+  ctx: Context,
+  carrier: (parent: Agent) => object,
+): LifecycleEmitter {
+  return (
+    name: "subagent/start" | "subagent/end" | "subagent/provider-removed",
+    info: SubagentRunInfo | SubagentRunEndInfo | string,
+    parent?: Agent,
+  ): void => {
+    const dispatchArgs: unknown[] =
+      parent === undefined ? [name, info] : [carrier(parent), name, info];
+    for (const callback of ctx.events.dispatch("emit", dispatchArgs)) {
+      try {
+        const returned: unknown = callback(info);
+        void Promise.resolve(returned).catch((error: unknown) => {
+          ctx.logger.warn(`subagent: ${name} listener rejected: ${renderThrown(error)}`);
+        });
+      } catch (error: unknown) {
+        ctx.logger.warn(`subagent: ${name} listener threw: ${renderThrown(error)}`);
+      }
+    }
+  };
+}
+
+/**
+ * Build the observer for one local or external activation's residency epoch. Creation failure before residency emits no lifecycle edge.
+ * @param emit - the contained lifecycle emitter.
+ * @param provider - the provider name recorded in the durable descriptor.
+ * @param childId - the durable child session id.
+ * @param parent - the exact live direct parent keying scoped dispatch.
+ * @returns the observer whose edges this epoch publishes.
+ */
+export function createActivationObserver(
+  emit: LifecycleEmitter,
+  provider: string,
+  childId: SessionId,
+  parent: Agent,
+): ActivationObserver {
+  const identity = { runId: SubagentRunId(randomUUID()), provider, id: childId, local: false };
+  return {
+    start: (child?: Agent): void => {
+      identity.local = child !== undefined;
+      emit("subagent/start", identity, parent);
+    },
+    settle: ({ stopReason, output }: SubagentResult): void => {
+      emit(
+        "subagent/end",
+        {
+          ...identity,
+          stopReason,
+          ...(output.length === 0 ? {} : { lastAssistantMessage: output }),
+        },
+        parent,
+      );
+    },
+  };
+}
+
+/**
+ * Why this child's epoch ended, for the terminal lifecycle edge and the
+ * manager's own parent delivery. The child's own log is authoritative:
+ * teardown succeeding says nothing about whether the model errored, hit its
+ * token ceiling, or was cancelled, so deriving the reason from disposal would
+ * report failed work as completed.
+ *
+ * {@link foldConsumedWork} supplies both halves the raw turn sequence cannot:
+ * which turn accounts for the work this epoch consumed, and whether accepted
+ * work was cancelled after it without any turn opening over it. A recorded
+ * failure still wins over a cancellation — stopping a child that had already
+ * failed does not turn its failure into a cancellation.
+ * @param events - this epoch's own event suffix.
+ * @returns its terminal stop reason; `completed` only for an epoch that both
+ *   closed cleanly and had nothing left to run.
+ */
+export function epochStopReason(events: readonly SessionEvent[]): SubagentResult["stopReason"] {
+  const { end, droppedUnrun } = foldConsumedWork(events);
+  switch (end?.data.reason.kind) {
+    case "max-tokens":
+      return "max-tokens";
+    case "aborted":
+    case "interrupted":
+      return "aborted";
+    case "error":
+      return "error";
+    // A pre-step rejection — a hook deny, a policy plugin — discarded input
+    // this epoch had claimed: the work was declined, not done.
+    case "blocked":
+      return "refusal";
+    // A clean ending and no accounting turn at all share one rule: the epoch
+    // finished what it was given unless a cancelled queue says otherwise.
+    case undefined:
+    case "completed":
+      return droppedUnrun ? "aborted" : "completed";
+    /* v8 ignore next 4 -- `forked` appears only in constructor seed history, while
+     * this function reads an epoch-owned suffix. `TurnEndReason` is merge-extensible,
+     * so a backend-added variant cannot be listed; treating an unnameable reason as
+     * success would report failed work as completed. */
+    default:
+      return "error";
+  }
+}
+
+/** Render any listener-thrown value without letting coercion escape containment. */
+function renderThrown(value: unknown): string {
+  try {
+    return value instanceof Error ? `${value.name}: ${value.message}` : String(value);
+  } catch {
+    return "<unrenderable thrown value>";
+  }
+}

package/src/vendor/dsh-subagent/list-children.ts

@@ -0,0 +1,141 @@
+/**
+ * Direct-child and recursive descendant discovery from parent-owned catalogs.
+ * Each catalog read releases its Session observation before the next branch.
+ * @module @deepseek-ai/dsh-subagent
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type { SubagentListEntry } from "./control-types.ts";
+import { SubagentError } from "./error.ts";
+import type { SubagentCatalogEntry } from "./projection-types.ts";
+
+export type { SubagentListEntry } from "./control-types.ts";
+
+/** One catalog descendant with its direct parent and edge distance from the requested root. */
+export type SubagentDescendantListEntry = SubagentListEntry & {
+  /** Parent whose catalog contains this child. */
+  readonly parentId: SessionId;
+  /** Edge distance from the requested root; direct children are `1`. */
+  readonly depth: number;
+};
+
+/**
+ * Read one parent's durable catalog through a live-preferred Session observation.
+ * @param ctx - context carrying the Session query service.
+ * @param parentSessionId - parent whose direct children are requested.
+ * @param signal - cancellation forwarded to the Session observation.
+ * @returns direct-child rows in parent catalog event order.
+ * @throws {@link SubagentError} when query or catalog projection is unavailable.
+ */
+export async function listChildren(
+  ctx: Context,
+  parentSessionId: SessionId,
+  signal?: AbortSignal,
+): Promise<SubagentCatalogEntry[]> {
+  const query = ctx.get("sessionQuery");
+  if (query === undefined) {
+    throw new SubagentError(
+      "listing subagents requires the sessionQuery service (load @deepseek-ai/dsh-session-query)",
+      "SUBAGENT_CONTROL_QUERY_UNAVAILABLE",
+    );
+  }
+  using parent = await query.observeSession(parentSessionId, {
+    ...(signal === undefined ? {} : { signal }),
+  });
+  const entries = parent.projections?.values.subagentCatalog;
+  if (entries === undefined) {
+    throw new SubagentError(
+      "listing subagents requires the registered subagentCatalog projection",
+      "SUBAGENT_CONTROL_PROJECTIONS_UNAVAILABLE",
+    );
+  }
+  return entries;
+}
+
+/**
+ * Walk reachable parent catalogs in stable pre-order without loading Agents.
+ * @see SubagentRuntime.listDescendants for failure and cancellation semantics.
+ * @param ctx - context carrying the Session store and query service.
+ * @param rootSessionId - parent whose catalog starts the traversal.
+ * @param signal - cancellation checked around each catalog read.
+ * @returns children and branch diagnostics with catalog parent and depth.
+ */
+export async function listDescendants(
+  ctx: Context,
+  rootSessionId: SessionId,
+  signal?: AbortSignal,
+): Promise<SubagentDescendantListEntry[]> {
+  const sessions = ctx.get("sessions");
+  if (sessions === undefined) {
+    throw new SubagentError(
+      "listing subagents requires the session store (load @deepseek-ai/dsh-session)",
+      "SUBAGENT_CONTROL_SESSION_STORE_UNAVAILABLE",
+    );
+  }
+  const readChildren = async (id: SessionId): Promise<SubagentCatalogEntry[]> => {
+    assertListingNotCancelled(signal);
+    let children: SubagentCatalogEntry[];
+    try {
+      children = await listChildren(ctx, id, signal);
+    } catch (error) {
+      assertListingNotCancelled(signal);
+      throw error;
+    }
+    assertListingNotCancelled(signal);
+    return children;
+  };
+  const stack = (await readChildren(rootSessionId))
+    .map((entry) => ({ entry, parentId: rootSessionId, depth: 1 }))
+    .reverse();
+  const visited = new Set<SessionId>([rootSessionId]);
+  const result: SubagentDescendantListEntry[] = [];
+  for (let position = stack.pop(); position !== undefined; position = stack.pop()) {
+    const { entry, parentId, depth } = position;
+    if (visited.has(entry.id)) continue;
+    visited.add(entry.id);
+    let children: SubagentCatalogEntry[];
+    try {
+      children = entry.mode === "external" ? [] : await readChildren(entry.id);
+    } catch (error) {
+      if (error instanceof SubagentError) throw error;
+      const code = error instanceof Error && "code" in error ? error.code : undefined;
+      result.push({
+        kind: "diagnostic",
+        id: entry.id,
+        parentId,
+        depth,
+        reason:
+          code === "SESSION_QUERY_CORRUPT_SESSION" || code === "SESSION_QUERY_SOURCE_CONFLICT"
+            ? "corrupt"
+            : "unavailable",
+      });
+      continue;
+    }
+    if (entry.mode === "unknown") {
+      result.push({ kind: "diagnostic", id: entry.id, parentId, depth, reason: "unsupported" });
+    } else {
+      const { createdAt: _createdAt, ...identity } = entry;
+      result.push({
+        ...identity,
+        kind: "child",
+        parentId,
+        depth,
+        activity: sessions.get(entry.id) === undefined ? "inactive" : "running",
+        hasChildren: children.length > 0,
+      });
+    }
+    // Catalog event order defines siblings; the stack visits the first one next.
+    for (const child of [...children].reverse()) {
+      stack.push({ entry: child, parentId: entry.id, depth: depth + 1 });
+    }
+  }
+  return result;
+}
+
+/** Stop the complete traversal when its caller cancels. */
+function assertListingNotCancelled(signal: AbortSignal | undefined): void {
+  if (signal?.aborted) {
+    throw new SubagentError("subagent listing was cancelled", "CANCELLED");
+  }
+}