@morlay/dsh-subagent 0.0.5 → 0.0.7

package/src/rows.ts

@@ -0,0 +1,44 @@
+// 本包作为能力包发布的**装配数据**：行本身在部署那一层装（`packages/bundles/session-mode-profile`
+// 引用它渲染 patch）。
+//
+// 接管方式是**按官方行 id 复用**：Loader 对同 id 的条目复用同一个 Entry、后者替换入口 options，所以行
+// id 与 settings namespace 都还是 `subagent`（官方设置卡照常可用），换掉的只是实现包。顺序前提：本包排在
+// `@deepseek-ai/dsh-base` 之后；模型白名单服务行仍留官方卡片第二段。
+
+// 一行装配条目：与 `cordis.patch.yml` 的顶层结构同形。
+export interface PatchRow {
+  readonly id?: string;
+  readonly disabled?: boolean;
+  readonly insert?: readonly RowEntry[];
+}
+
+// `insert` 里的一个条目。
+export interface RowEntry {
+  readonly id: string;
+  readonly name: string;
+  readonly config?: Readonly<Record<string, unknown>>;
+}
+
+export interface SubagentRowsOptions {
+  // 把中文回报指引**限制**到这些 preset（本行 `config.localizedReturnGuidancePresets`）。
+  // 不传就是不限：任意 preset（含官方四个 shipped）与还没绑 preset 的会话都用我们的中文文案。
+  readonly localizedReturnGuidancePresets?: readonly string[];
+}
+
+// 服务接管的装配行：占官方 `subagent` 那个行 id。
+export function subagentRows(options: SubagentRowsOptions = {}): readonly PatchRow[] {
+  const presets = options.localizedReturnGuidancePresets;
+  return [
+    {
+      insert: [
+        {
+          id: "subagent",
+          name: "@morlay/dsh-subagent",
+          ...(presets === undefined
+            ? {}
+            : { config: { localizedReturnGuidancePresets: [...presets] } }),
+        },
+      ],
+    },
+  ];
+}

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

@@ -0,0 +1,200 @@
+/** Execution-period records, capacity slots, child serialization, and local output capture.
+ * @module @deepseek-ai/dsh-subagent/activation
+ */
+
+import type { Agent, AgentHandle } from "@deepseek-ai/dsh-agent";
+import type { SessionId, SessionLogOffset } from "@deepseek-ai/dsh-session";
+import { assertNever } from "@deepseek-ai/dsh-util-values";
+import { finalAssistantOutput } from "./assistant-output.ts";
+import { epochStopReason } from "./lifecycle.ts";
+import type { ActivationObserver } from "./lifecycle.ts";
+import { SubagentError } from "./error.ts";
+import type { StructuredAttachment } from "./structured.ts";
+import type { SubagentResult, SubagentRun } from "./types.ts";
+
+/** Process-local slots shared through uninterrupted continuable parent links. */
+export class ActivationPool {
+  private readonly slots = new Set<symbol>();
+
+  /**
+   * Reserve before reconstruction; release also tolerates unpublished rollback.
+   * @param capacity - the maximum simultaneous activations in this pool.
+   * @returns an idempotent slot release.
+   */
+  reserve(capacity: number): () => void {
+    if (this.slots.size >= capacity) {
+      throw new SubagentError(
+        `subagent limit reached (active child limit: ${capacity}); wait for an existing child to finish ` +
+          "or complete this work with the current agents",
+        "ACTIVATION_LIMIT_REACHED",
+      );
+    }
+    const slot = Symbol();
+    this.slots.add(slot);
+    return () => {
+      this.slots.delete(slot);
+    };
+  }
+}
+
+/**
+ * One residency epoch for a local child or an external execution.
+ * The manager owns admission, execution handles, and resource release.
+ */
+interface ActivationBase {
+  /** Shared capacity for this Activation and all its managed descendants. */
+  readonly pool: ActivationPool;
+  /** Return this epoch's slot after its handle has finished disposal. */
+  readonly releaseSlot: () => void;
+  /** The durable child this Activation is an epoch of. */
+  readonly childId: SessionId;
+  readonly parent: Agent;
+  readonly delivery: "parent" | "caller";
+  readonly result: PromiseWithResolvers<SubagentResult>;
+  /** Published synchronously before teardown; subsequent callers share this transaction. */
+  closing: Promise<void> | undefined;
+  /**
+   * 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;
+}
+
+/** Resources retained only for the selected execution kind. */
+export type ActivationResource =
+  | {
+      readonly kind: "local";
+      readonly handle: AgentHandle;
+      readonly outputStart: SessionLogOffset;
+      readonly structured: StructuredAttachment | undefined;
+      /** Latest live failure not superseded by a later committed turn ending. */
+      failureAt: SessionLogOffset | undefined;
+      /** Renewed when local settlement must recheck input or owned children. */
+      poke: PromiseWithResolvers<void>;
+    }
+  | {
+      readonly kind: "external";
+      readonly run: SubagentRun;
+      readonly controller: AbortController;
+    };
+
+/** One managed execution period with its provider-specific resources. */
+export type Activation = ActivationBase & ActivationResource;
+
+/** Local residency with input admission and Session-backed result capture. */
+export type LocalActivation = Extract<Activation, { kind: "local" }>;
+
+/**
+ * Read the live Agent retained by local execution.
+ * @param activation - the managed local or external execution.
+ * @returns the local Agent, absent for an external run.
+ */
+export function activationAgent(activation: Activation): Agent | undefined {
+  return activation.kind === "local" ? activation.handle.agent : undefined;
+}
+
+/**
+ * Require local residency before accepting further input.
+ * @param activation - execution targeted by message delivery.
+ * @returns the local activation.
+ * @throws when the external backend cannot accept another message.
+ */
+export function requireLocalActivation(activation: Activation): LocalActivation {
+  switch (activation.kind) {
+    case "local":
+      return activation;
+    case "external":
+      throw new SubagentError(
+        `subagent "${activation.childId}" does not accept follow-up input`,
+        "NOT_CONTINUABLE",
+      );
+    /* v8 ignore next 2 -- Both execution kinds are handled above. */
+    default:
+      return assertNever(activation);
+  }
+}
+
+/**
+ * Retain local failures whose turn ending could not be committed.
+ * @param activation - exact local Agent and epoch receiving the scoped observers.
+ * @param wake - notify its settlement watcher when failure changes readiness.
+ */
+export function observeLocalFailure(activation: LocalActivation, wake: () => void): void {
+  const child = activation.handle.agent;
+  child.ctx.on("agent/error", ({ agent }) => {
+    if (agent !== child) return;
+    activation.failureAt = child.session.seq;
+    wake();
+  });
+  child.ctx.on("session/event", (session, event) => {
+    if (
+      session === child.session &&
+      event.type === "turn/end" &&
+      activation.failureAt !== undefined &&
+      event.seq >= activation.failureAt
+    ) {
+      activation.failureAt = undefined;
+    }
+  });
+}
+
+/**
+ * Capture local output and retain failures without a later committed turn ending.
+ * @param activation - the settled local execution and any structured result.
+ * @returns final output, stop reason, and committed structured value.
+ */
+export function captureLocalResult(activation: LocalActivation): SubagentResult {
+  // oxlint-disable-next-line typescript/no-deprecated -- Existing Session history read; migration deferred.
+  const events = activation.handle.agent.session.snapshotEvents(activation.outputStart);
+  const output = finalAssistantOutput(events) ?? [];
+  const stopReason = activation.failureAt === undefined ? epochStopReason(events) : "error";
+  const structured = activation.structured;
+  if (structured !== undefined) {
+    const captured = structured.captured();
+    if (captured !== undefined) return { output, stopReason, structured: captured.value };
+    if (stopReason === "completed") return { output, stopReason: "error" };
+  }
+  return { output, stopReason };
+}
+
+/** Serialize each durable child's delivery, release, and disposal. */
+export class ChildLock {
+  private tails = new Map<SessionId, Promise<unknown>>();
+
+  /**
+   * 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> {
+    const previous = this.tails.get(childId) ?? Promise.resolve();
+    const result = previous.then(operation, operation);
+    // Absorb rejections in the chaining tail so one failed critical section
+    // cannot reject an unrelated later caller.
+    const tail = result.then(
+      () => undefined,
+      () => undefined,
+    );
+    this.tails.set(childId, tail);
+    void tail.then(() => {
+      if (this.tails.get(childId) === tail) this.tails.delete(childId);
+    });
+    return result;
+  }
+}

package/src/vendor/dsh-subagent/archive-admission.ts

@@ -0,0 +1,97 @@
+/**
+ * The `subagent` family of the Workspace registry's archive admission: which
+ * subagent descendants of a Session are still inside a turn, and how they
+ * stop when the Session is archived with its work.
+ *
+ * @module @deepseek-ai/dsh-subagent
+ */
+
+import type { Context } from "@deepseek-ai/cordis";
+import type { Agent } from "@deepseek-ai/dsh-agent";
+import type { SessionId } from "@deepseek-ai/dsh-session";
+import type {} from "@deepseek-ai/dsh-session-query";
+import type { SessionActivity, SessionActivityItem } from "@deepseek-ai/dsh-workspace";
+import { foldSubagentDescriptor } from "./descriptor.ts";
+
+/**
+ * Answer `workspace/session-activity` with the running subagent descendants of
+ * the asked Session, and `workspace/session-stop` by cancelling each of them
+ * as their parent would. Both listeners live as long as `ctx`'s fiber.
+ * @param ctx - context carrying the Agent registry; the Session query service is optional and only supplies labels.
+ */
+export function installSubagentArchiveAdmission(ctx: Context): void {
+  ctx.on("workspace/session-activity", async ({ sessionId }, next) => {
+    const running = runningDescendants(ctx, sessionId);
+    const rest = await next();
+    if (running.length === 0) return rest;
+    const own: SessionActivity = {
+      kind: "subagent",
+      items: await Promise.all(running.map((child) => describe(ctx, child))),
+    };
+    return [own, ...rest];
+  });
+  ctx.on("workspace/session-stop", ({ sessionId }) => {
+    for (const child of runningDescendants(ctx, sessionId)) {
+      try {
+        child.cancel({ kind: "parent" });
+      } catch (error: unknown) {
+        // One child refusing its cancel must not keep its siblings running for an archived parent.
+        ctx.logger.warn(
+          `subagent: cancelling "${child.id}" for an archived Session failed: ${String(error)}`,
+        );
+      }
+    }
+  });
+}
+
+/**
+ * Live subagent descendants inside a turn, by durable lineage: a child whose
+ * header names its parent and carries the subagent origin this package
+ * records, at any depth. A fork shares the lineage field without the origin
+ * and is an independent conversation, so it never holds its source. Lineage
+ * is read as data, so a damaged header chain that loops is visited once.
+ */
+function runningDescendants(ctx: Context, rootId: SessionId): Agent[] {
+  const childrenOf = new Map<SessionId, Agent[]>();
+  for (const agent of ctx.agents.list()) {
+    const { parentSession, origin } = agent.session.header;
+    if (parentSession === undefined || origin !== "subagent") continue;
+    const siblings = childrenOf.get(parentSession) ?? [];
+    siblings.push(agent);
+    childrenOf.set(parentSession, siblings);
+  }
+  const running: Agent[] = [];
+  const pending = [rootId];
+  const visited = new Set<SessionId>();
+  while (pending.length > 0) {
+    const parentId = pending.shift() as SessionId;
+    if (visited.has(parentId)) continue;
+    visited.add(parentId);
+    for (const child of childrenOf.get(parentId) ?? []) {
+      if (child.status === "running") running.push(child);
+      pending.push(child.id);
+    }
+  }
+  return running;
+}
+
+/**
+ * The child's activity item: its id, plus the durable creation label its
+ * descriptor carries, read through a live Session observation. Without the
+ * Session query service, or with a descriptor that is absent or unreadable,
+ * the item names the child by id alone.
+ */
+async function describe(ctx: Context, child: Agent): Promise<SessionActivityItem> {
+  const query = ctx.get("sessionQuery");
+  if (query === undefined) return { id: child.id };
+  try {
+    using observation = await query.observeSession(child.id, { projectionMode: "none" });
+    const label = foldSubagentDescriptor(
+      observation.events.slice(observation.inheritedEventCount),
+    )?.label;
+    return label === undefined ? { id: child.id } : { id: child.id, label };
+  } catch {
+    // A damaged descriptor is data damage in the child; the report still names the child.
+    return { id: child.id };
+  }
+}

package/src/vendor/dsh-subagent/assistant-output.ts

@@ -0,0 +1,77 @@
+/**
+ * Canonical selection of a child's final assistant output. Backend run results
+ * and `subagent/end.lastAssistantMessage` apply the same rule: select the last
+ * non-empty assistant message. An empty-content message records usage only
+ * when the loop appends it after a max-tokens step with no executable blocks,
+ * so it does not replace earlier output. If no non-empty message exists,
+ * select the accumulated assistant text. Selection is independent of the
+ * run's stop reason.
+ *
+ * @module @deepseek-ai/dsh-subagent/assistant-output
+ */
+
+import { joinAssistantStreamText, type ContentBlock } from "@deepseek-ai/dsh-llm";
+import type { SessionEvent } from "@deepseek-ai/dsh-session";
+
+/**
+ * Incremental fold of the selection rule, for backends that observe a child's
+ * output as it streams: session-event backends {@link push} each event, and
+ * transports without session events (ACP content chunks) {@link pushText} raw
+ * text into the same streamed fallback.
+ */
+export class AssistantOutputFold {
+  private message: readonly ContentBlock[] | undefined;
+  private partial: string[] = [];
+
+  /**
+   * Fold one session event: a non-empty assistant message becomes the
+   * candidate final answer, while its embedded stream and any log-only attempt
+   * extend the streamed fallback; every other event contributes nothing.
+   * @param event - the next observed session event.
+   */
+  push(event: SessionEvent): void {
+    if (event.type === "assistant/message") {
+      const content = event.data.message.content;
+      if (content.length > 0) this.message = content;
+    }
+    if (event.type === "assistant/message" || event.type === "assistant/attempt") {
+      this.pushText(joinAssistantStreamText(event.data.stream));
+    }
+  }
+
+  /**
+   * Extend the streamed fallback with text observed outside session events.
+   * @param text - the next streamed text piece (an empty piece is a no-op).
+   */
+  pushText(text: string): void {
+    if (text.length > 0) this.partial.push(text);
+  }
+
+  /**
+   * Select the final output folded so far.
+   * @returns the last non-empty assistant message, else the accumulated
+   *   streamed text, or `undefined` when the child produced neither.
+   */
+  collect(): readonly ContentBlock[] | undefined {
+    if (this.message !== undefined) return this.message;
+    const text = this.partial.join("");
+    return text.length > 0 ? [{ type: "text", text }] : undefined;
+  }
+}
+
+/**
+ * Apply the selection rule to one complete child-owned event suffix.
+ * @param events - the child-owned events (after any seed or epoch boundary).
+ * @returns the selected output, or `undefined` when the child produced none.
+ */
+export function finalAssistantOutput(
+  events: readonly SessionEvent[],
+): readonly ContentBlock[] | undefined {
+  // TODO: this folds the complete suffix once per run/epoch settlement. If a
+  // long continuable epoch ever profiles hot here, scan backward with early
+  // exit for the last non-empty message and fold text deltas only on the
+  // no-message fallback.
+  const fold = new AssistantOutputFold();
+  for (const event of events) fold.push(event);
+  return fold.collect();
+}

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

@@ -0,0 +1,196 @@
+/**
+ * Parent-owned durable subagent catalog events and their chunked projection.
+ *
+ * @module @deepseek-ai/dsh-subagent/catalog
+ */
+
+import { z } from "zod";
+import {
+  appendChunkedList,
+  chunkedListSchema,
+  iterateChunkedList,
+} from "@deepseek-ai/dsh-chunked-list";
+import type { ChunkedList } from "@deepseek-ai/dsh-chunked-list";
+import type {
+  Session,
+  SessionEvent,
+  SessionHeader,
+  SessionId,
+  SessionLogOffset,
+} from "@deepseek-ai/dsh-session";
+import type { ProjectionDefinition } from "@deepseek-ai/dsh-session-projection";
+import type { SubagentCatalogEntry } from "./projection-types.ts";
+
+/** Catalog payload version emitted by local child creation. */
+export const SUBAGENT_CATALOG_VERSION = 0;
+
+type KnownCatalogMode =
+  | { readonly mode: "one-shot"; readonly label?: string }
+  | { readonly mode: "continuable"; readonly label: string };
+
+/** Parent catalog v0 records local modes, v1 adds unknown children, and v2 records external executions. */
+export type SubagentCatalogEvent = {
+  readonly childId: SessionId;
+  readonly childCreatedAt: number;
+} & (
+  | ({ readonly version: 0 } & KnownCatalogMode)
+  | ({ readonly version: 1 } & (
+      | KnownCatalogMode
+      | { readonly mode: "unknown"; readonly label?: string }
+    ))
+  | { readonly version: 2; readonly mode: "external"; readonly label?: string }
+);
+
+declare module "@deepseek-ai/dsh-session/types" {
+  interface SessionEventMap {
+    /**
+     * A direct child's identity and available discovery fields.
+     * @param data - versioned parent-owned catalog entry.
+     */
+    "subagent/catalog": SubagentCatalogEvent;
+  }
+}
+
+/** Host fold state for one parent catalog. */
+export interface SubagentCatalogState {
+  readonly inheritedEventCount: SessionLogOffset;
+  readonly head?: ChunkedList<SubagentCatalogEvent> | undefined;
+}
+
+const sessionIdSchema = z.string() as unknown as z.ZodType<SessionId>;
+const oneShotCatalogSchema = z
+  .object({
+    version: z.union([z.literal(0), z.literal(1)]),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal("one-shot"),
+    label: z.string().optional(),
+  })
+  .strict();
+const continuableCatalogSchema = z
+  .object({
+    version: z.union([z.literal(0), z.literal(1)]),
+    childId: sessionIdSchema,
+    childCreatedAt: z.number().int().nonnegative(),
+    mode: z.literal("continuable"),
+    label: z.string(),
+  })
+  .strict();
+const externalCatalogSchema = oneShotCatalogSchema.extend({
+  version: z.literal(2),
+  mode: z.literal("external"),
+});
+const unknownCatalogSchema = oneShotCatalogSchema.extend({
+  version: z.literal(1),
+  mode: z.literal("unknown"),
+});
+const eventDataSchema = z.union([
+  oneShotCatalogSchema,
+  externalCatalogSchema,
+  continuableCatalogSchema,
+  unknownCatalogSchema,
+]) as z.ZodType<SubagentCatalogEvent>;
+const viewSchema = z.array(
+  z.union([
+    oneShotCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+      id: sessionIdSchema,
+      createdAt: oneShotCatalogSchema.shape.childCreatedAt,
+    }),
+    externalCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+      id: sessionIdSchema,
+      createdAt: externalCatalogSchema.shape.childCreatedAt,
+    }),
+    continuableCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+      id: sessionIdSchema,
+      createdAt: continuableCatalogSchema.shape.childCreatedAt,
+    }),
+    unknownCatalogSchema.omit({ version: true, childId: true, childCreatedAt: true }).extend({
+      id: sessionIdSchema,
+      createdAt: unknownCatalogSchema.shape.childCreatedAt,
+    }),
+  ]),
+) as z.ZodType<SubagentCatalogEntry[]>;
+const stateSchema: z.ZodType<SubagentCatalogState> = z
+  .object({
+    inheritedEventCount: z.number().int().nonnegative() as unknown as z.ZodType<SessionLogOffset>,
+    head: chunkedListSchema(eventDataSchema).optional(),
+  })
+  .strict();
+
+declare module "@deepseek-ai/dsh-session-projection/types" {
+  interface SessionProjectionStateMap {
+    subagentCatalog: SubagentCatalogState;
+  }
+}
+
+/**
+ * Materialize complete and unknown-mode child identities from parent catalog events.
+ * @param state - parent catalog fold state.
+ * @returns current direct-child rows in parent catalog event order.
+ */
+function subagentCatalogEntries(state: SubagentCatalogState): SubagentCatalogEntry[] {
+  const entries: SubagentCatalogEntry[] = [];
+  for (const data of iterateChunkedList(state.head)) {
+    const { version: _version, childId, childCreatedAt, ...descriptor } = data;
+    entries.push({ id: childId, createdAt: childCreatedAt, ...descriptor });
+  }
+  return entries;
+}
+
+/** Parent-owned direct-child catalog projection; invalid own facts reject restoration. */
+export const subagentCatalogProjectionDefinition = {
+  key: "subagentCatalog",
+  stateSchema,
+  init: (_header: SessionHeader, inheritedEventCount: SessionLogOffset) => ({
+    inheritedEventCount,
+  }),
+  apply: (state, event: SessionEvent) => {
+    if (event.type !== "subagent/catalog" || event.seq < state.inheritedEventCount) return state;
+    return { ...state, head: appendChunkedList(state.head, eventDataSchema.parse(event.data)) };
+  },
+  stateVersion: 6,
+  wire: { viewSchema, view: subagentCatalogEntries },
+} satisfies ProjectionDefinition<"subagentCatalog", SubagentCatalogState>;
+
+/**
+ * Append a complete direct-child discovery fact to its parent Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param child - established child's immutable Session metadata.
+ * @param descriptor - mode-discriminated creation label frozen with the child.
+ */
+export function establishCatalogChild(
+  parent: Session,
+  child: SessionHeader,
+  descriptor: { readonly mode: "continuable"; readonly label: string },
+): void {
+  parent.append("subagent/catalog", {
+    version: SUBAGENT_CATALOG_VERSION,
+    childId: child.id,
+    childCreatedAt: child.createdAt,
+    mode: descriptor.mode,
+    label: descriptor.label,
+  });
+}
+
+/** Catalog payload version emitted by external execution creation. */
+const EXTERNAL_SUBAGENT_CATALOG_VERSION = 2;
+
+/**
+ * Record an external execution without a local child Session.
+ * @param parent - durable direct parent receiving the discovery fact.
+ * @param childId - identity returned by the external provider.
+ * @param label - display label assigned by the caller.
+ */
+export function establishExternalCatalogChild(
+  parent: Session,
+  childId: SessionId,
+  label: string,
+): void {
+  parent.append("subagent/catalog", {
+    version: EXTERNAL_SUBAGENT_CATALOG_VERSION,
+    childId,
+    childCreatedAt: Date.now(),
+    mode: "external",
+    label,
+  });
+}