@meiyukichan/dsh-sandore 0.1.0-rc.6

package/packages/tests/mocks/storage-domain.ts

@@ -0,0 +1,101 @@
+/**
+ * 内存 mock storageDomain（测试专用，非发布面）。
+ *
+ * 用 `Map` 实现 `KvTable` 的等价语义（读同步、写 await、`delete` 幂等、
+ * `update` 缺 key 抛 `missing-key`），并提供 `open(spec)`/`get(name)` 的
+ * `DomainFacility` 形状，供 `persistence.spec.ts` / `remote.spec.ts` 以
+ * `ctx.provide('storageDomain', …)` 注入，避免在单元测试中拉起真实后端。
+ * @module dsh-sandore/workflow/tests/mocks/storage-domain
+ */
+import { DomainError, type Domain, type DomainSpec, type KvTable } from '@deepseek-ai/dsh-storage-domain'
+
+/** Map 版 `KvTable`：`K` 为记录键，`V` 为记录值。 */
+export class MemoryKvTable<K extends string, V> implements KvTable<K, V> {
+  private readonly records = new Map<K, V>()
+
+  get(key: K): V | undefined {
+    return this.records.get(key)
+  }
+
+  entries(): IterableIterator<[K, V]> {
+    return this.records.entries()
+  }
+
+  keys(): IterableIterator<K> {
+    return this.records.keys()
+  }
+
+  get size(): number {
+    return this.records.size
+  }
+
+  async put(key: K, value: V): Promise<void> {
+    this.records.set(key, value)
+  }
+
+  async delete(key: K): Promise<boolean> {
+    return this.records.delete(key)
+  }
+
+  async update(key: K, fn: (current: V) => V): Promise<V> {
+    const current = this.records.get(key)
+    if (current === undefined) {
+      throw new DomainError('missing-key', `key '${String(key)}' is missing`)
+    }
+    const next = fn(current)
+    this.records.set(key, next)
+    return next
+  }
+}
+
+/** 单个已打开域的内存实现：按 spec 声明的表名建空表，`close()` 幂等。 */
+export class MemoryDomain {
+  readonly name: string
+
+  private readonly tableMap = new Map<string, MemoryKvTable<string, unknown>>()
+  private isClosed = false
+
+  constructor(name: string, tableNames: readonly string[]) {
+    this.name = name
+    for (const tableName of tableNames) {
+      this.tableMap.set(tableName, new MemoryKvTable())
+    }
+  }
+
+  table<K extends string, V>(name: string): KvTable<K, V> {
+    const table = this.tableMap.get(name)
+    if (table === undefined) {
+      throw new Error(`memory domain '${this.name}' has no table '${name}'`)
+    }
+    return table as unknown as KvTable<K, V>
+  }
+
+  async close(): Promise<void> {
+    this.isClosed = true
+  }
+
+  get closed(): boolean {
+    return this.isClosed
+  }
+}
+
+/** 内存 `DomainFacility` 形状：`open` 建域（拒绝重复打开），`get` 供断言诊断。 */
+export class MemoryStorageDomain {
+  private readonly domains = new Map<string, MemoryDomain>()
+
+  async open<S extends DomainSpec>(spec: S): Promise<Domain<S>> {
+    const name = spec.name
+    const existing = this.domains.get(name)
+    if (existing !== undefined && !existing.closed) {
+      throw new DomainError('already-open', `domain '${name}' is already open`)
+    }
+    const domain = new MemoryDomain(name, Object.keys(spec.tables))
+    this.domains.set(name, domain)
+    // 测试 mock：MemoryDomain 是 Domain<S> 的等价实现（spec 未声明 global，句柄为 never）。
+    return domain as unknown as Domain<S>
+  }
+
+  get(name: string): MemoryDomain | undefined {
+    return this.domains.get(name)
+  }
+}

package/packages/tests/mocks/subagents.ts

@@ -0,0 +1,197 @@
+/**
+ * 内存 mock subagents（测试专用，非发布面）。
+ *
+ * 提供 `startContinuable`/`followup`/`interrupt`/`start` 等价语义：`startContinuable`
+ * 记录委派请求并 resolve 为 `{ childId, messageId }`（inbox 接受即 resolve）。以
+ * `ctx.provide('subagents', …)` 注入。
+ *
+ * **settle 仿真**（对齐 DSH `SubagentContinuationManager`）：continuable 子代理「完成 =
+ * settle」。本 mock 不后台驱动 settle——由测试经 `settleChild(childId, stopReason)`
+ * 显式触发（模拟子代理自然完成/出错）；`interrupt` 自动 settle(`aborted`)（模拟 DSH
+ * interrupt → 子代理静止 → settle 销毁）。settle 经 `sandore/subagent-settled` 事件
+ * 发射，供 workflow-engine 的 `awaitSubagentSettlement`（`ctx.on('sandore/subagent-settled')`）
+ * 路由到对应 childId 的等待者——与真实 DSH `subagent/end`→`sandore/subagent-settled`
+ * 转译同一通道。`followup`（settle 后）模拟 cold-resume：状态回 `running`，等待测试
+ * 再次 `settleChild`（续跑产出）。
+ * @module dsh-sandore/workflow/tests/mocks/subagents
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { ContentBlock } from '@deepseek-ai/dsh-llm';
+
+import type {
+  Agent,
+  ContinuableSetupContribution,
+  ContinuableStart,
+  ContinuableStartSpec,
+  MessageId,
+  SessionId,
+  SubagentFollowupOptions,
+  SubagentInterruptAuthority,
+  SubagentListEntry,
+  SubagentResult,
+  SubagentRun,
+  SubagentRuntime,
+  SubagentSettlement,
+  SubagentStartRequest,
+  SubagentStopReason,
+} from '../../microflow/subagents';
+
+/** 一次 `followup` 调用的记录。 */
+export interface FakeFollowup {
+  parent: Agent;
+  childId: SessionId;
+  content: ContentBlock[];
+  options: SubagentFollowupOptions;
+}
+
+/** 可续接子代理状态机状态：`running` 活跃、`interrupted` 被 interrupt（已 settle aborted）。 */
+export type FakeChildStatus = 'running' | 'interrupted';
+
+/** 内存 mock subagents：记录调用、维护 interrupt→settle 状态机、发射 settle 事件。 */
+export class FakeSubagents implements SubagentRuntime {
+  readonly continuableStarts: ContinuableStartSpec[] = [];
+  readonly followups: FakeFollowup[] = [];
+  readonly interrupts: Array<{ targetSessionId: SessionId; authority: SubagentInterruptAuthority }> = [];
+  readonly startCalls: Array<{ name: string; request: SubagentStartRequest }> = [];
+  readonly listChildrenCalls: Array<{ parentSessionId: SessionId; signal?: AbortSignal }> = [];
+  /** 已注册的 continuable setup 贡献（registerContinuableSetup 记录，供 gate 断言）。 */
+  readonly continuableSetups: ContinuableSetupContribution[] = [];
+  /** 已发射的 settle 事件载荷（按发射顺序，供断言）。 */
+  readonly settlements: Array<SubagentSettlement> = [];
+  /** 可选：followup 抛错注入（缺陷 11 测试：recover() followup 失败落 failed）。 */
+  followupError: Error | undefined = undefined;
+  private readonly childParent = new Map<SessionId, SessionId>();
+  private readonly childStates = new Map<SessionId, FakeChildStatus>();
+
+  constructor(
+    private readonly ctx?: Context,
+    /** 取活子代理（auto-settle 判定 status 用；测试 harness 注入 `(id) => agents.get(id)`）。 */
+    private readonly getAgent?: (id: SessionId) => { readonly status: 'idle' | 'running'; readonly session: { readonly events: readonly { type: string }[] } } | undefined,
+  ) {}
+
+  async startContinuable(spec: ContinuableStartSpec): Promise<ContinuableStart> {
+    // 本 mock 有意不校验 `spec.provider` 是否为已注册的 subagent provider 名（宽松接受
+    // 任意字符串，供各 spec 以任意 provider 启动）。真实 DSH 只认注册名（fork/spawn），
+    // 把模型 provider id 当 subagent provider 名传入会在运行时报
+    // `no subagent provider registered for "<model provider id>"`——该约束由
+    // step-runner.spec.ts 对 `continuableStarts[0].provider === 'fork'` 的显式断言覆盖。
+    this.continuableStarts.push(spec);
+    const index = this.continuableStarts.length;
+    const childId = `child-${index}`;
+    this.childParent.set(childId, spec.request.parent.id);
+    this.childStates.set(childId, 'running');
+    // 真实 DSH：子代理静止（idle + 无 owned children + 无 accepted）即 settle。mock 无真实
+    // LLM，以 `child.status === 'idle'` 为「子代理已跑完」代理信号——`startContinuable` 后
+    // 若 child 已 idle（测试预填输出 / 空输出跑完）即自动 settle(completed)；`running`（挂起
+    // /暂停测试）则不自动 settle，由测试 `settleChild`/`interrupt` 驱动。经 `sandore/
+    // subagent-settled` 事件 + 引擎缓冲路由（buffer 解决早于 awaiter 的竞态）。
+    this.maybeAutoSettle(childId);
+    return { childId, messageId: `msg-${index}` };
+  }
+
+  async followup(parent: Agent, childId: SessionId, content: ContentBlock[], options: SubagentFollowupOptions): Promise<MessageId> {
+    if (this.followupError !== undefined) {
+      throw this.followupError;
+    }
+    this.followups.push({ parent, childId, content, options });
+    // cold-resume 仿真：settle 后的 followup 重建 Activation，状态回 running。
+    this.childStates.set(childId, 'running');
+    // 若 child 已 idle（续跑产出 / 空输出跑完），自动 settle(completed) 模拟续跑完成。
+    this.maybeAutoSettle(childId);
+    return `msg-${this.followups.length}`;
+  }
+
+  interrupt(targetSessionId: SessionId, authority: SubagentInterruptAuthority): void {
+    this.interrupts.push({ targetSessionId, authority });
+    this.childStates.set(targetSessionId, 'interrupted');
+    // 模拟 DSH interrupt → 子代理静止 → settle(aborted)：自动发射 settle 事件。
+    // 真实 DSH 中 `SubagentContinuationManager.interrupt` 发 `agent.cancel` 后，
+    // `watchSettlement` 观察到静止即 dispose + notifySettlement(aborted) + emit subagent/end。
+    this.emitSettlement({ childId: targetSessionId, stopReason: 'aborted' });
+  }
+
+  async listChildren(parentSessionId: SessionId, signal?: AbortSignal): Promise<SubagentListEntry[]> {
+    this.listChildrenCalls.push(signal === undefined ? { parentSessionId } : { parentSessionId, signal });
+    const entries: SubagentListEntry[] = [];
+    for (const [id, state] of this.childStates) {
+      if (this.childParent.get(id) !== parentSessionId) continue;
+      entries.push({
+        kind: 'child',
+        id,
+        activity: state === 'running' ? 'running' : 'inactive',
+        hasChildren: false,
+        mode: 'continuable',
+        label: 'test child',
+      });
+    }
+    return entries;
+  }
+
+  /** 记录注册的 continuable setup 贡献（不实际安装；测试可手动调用贡献模拟 child 安装）。 */
+  registerContinuableSetup(contribution: ContinuableSetupContribution): () => void {
+    this.continuableSetups.push(contribution);
+    return () => {};
+  }
+
+  /** 查询某可续接子代理当前状态（`startContinuable` 后为 running，interrupt 后为 interrupted）。 */
+  childStatus(childId: SessionId): FakeChildStatus | undefined {
+    return this.childStates.get(childId);
+  }
+
+  /**
+   * 测试手动触发子代理 settle（模拟自然完成/出错）。发射 `sandore/subagent-settled`
+   * 事件，供 workflow-engine `awaitSubagentSettlement` 路由。`output` 缺省时由
+   * `collectSubagentOutput` 回退 `finalAssistantOutput(child.session.events)` 读取。
+   */
+  settleChild(childId: SessionId, stopReason: SubagentStopReason, output?: readonly ContentBlock[]): void {
+    this.childStates.set(childId, stopReason === 'completed' ? 'running' : 'interrupted');
+    this.emitSettlement({
+      childId,
+      stopReason,
+      ...(output === undefined ? {} : { output }),
+    });
+  }
+
+  /** 发射 `sandore/subagent-settled` 事件（与 DSH 适配层 `subagent/end`→本事件同通道）。 */
+  private emitSettlement(settlement: SubagentSettlement): void {
+    this.settlements.push(settlement);
+    if (this.ctx === undefined) return;
+    // 与 sandore `emitContained` 同形：unscoped dispatch，同 ctx 的 `ctx.on` 监听器接收。
+    for (const callback of this.ctx.events.dispatch('emit', ['sandore/subagent-settled', settlement])) {
+      try {
+        const returned: unknown = callback(settlement);
+        void Promise.resolve(returned).catch(() => {});
+      } catch {
+        // 监听器异常不应影响 mock 状态机。
+      }
+    }
+  }
+
+  /**
+   * 若 `child.status === 'idle'`（子代理已跑完），自动 settle(completed) 模拟真实 DSH
+   * 子代理静止即 settle。经微任务延迟（让 collectSubagentOutput 先注册 awaiter 或落入引擎
+   * 缓冲）。`running`（挂起/暂停测试）则不自动 settle——由测试 `settleChild`/`interrupt` 驱动。
+   */
+  private maybeAutoSettle(childId: SessionId): void {
+    if (this.getAgent === undefined) return;
+    const child = this.getAgent(childId);
+    if (child === undefined || child.status !== 'idle') return;
+    queueMicrotask(() => {
+      const latest = this.getAgent?.(childId);
+      if (latest !== undefined && latest.status === 'idle') {
+        this.settleChild(childId, 'completed');
+      }
+    });
+  }
+
+  async start(name: string, request: SubagentStartRequest): Promise<SubagentRun> {
+    this.startCalls.push({ name, request });
+    const result: SubagentResult = { output: [], stopReason: 'completed' };
+    return {
+      id: `run-${this.startCalls.length}`,
+      localAgent: undefined,
+      result: Promise.resolve(result),
+      dispose: async () => {},
+    };
+  }
+}

package/packages/tests/mocks/subprocess.ts

@@ -0,0 +1,59 @@
+/**
+ * 内存 mock subprocess（测试专用，非发布面）。
+ *
+ * 提供 `resolveExecutable`/`spawn` 等价语义：`resolveExecutable` 记录命令并返回规范
+ * 路径，`spawn` 记录规格并返回可注入行为的内存句柄。以 `ctx.provide('subprocess', …)`
+ * 注入。
+ * @module dsh-sandore/workflow/tests/mocks/subprocess
+ */
+import type {
+  SubprocessHandle,
+  SubprocessOutcome,
+  SubprocessRuntime,
+  SubprocessSpawnSpec,
+} from '../../workflow/shell.ts';
+
+/** 生成一次成功（exitCode 0）的子进程结果。 */
+export function successOutcome(): SubprocessOutcome {
+  return { exitCode: 0, signal: null };
+}
+
+/** 内存子进程句柄：`done` 由 `outcomeHandler` 决定，`terminate`/`waitForExit` 记录调用。 */
+export class FakeSubprocessHandle implements SubprocessHandle {
+  readonly pid: number;
+  readonly collected: SubprocessHandle['collected'];
+  readonly done: Promise<SubprocessOutcome>;
+  terminated = false;
+
+  constructor(pid: number, outcomeHandler: () => SubprocessOutcome = successOutcome) {
+    this.pid = pid;
+    this.collected = {};
+    this.done = Promise.resolve(outcomeHandler());
+  }
+
+  terminate(): void {
+    this.terminated = true;
+  }
+
+  async waitForExit(): Promise<boolean> {
+    return true;
+  }
+}
+
+/** 内存 mock subprocess：记录 resolve/spawn 调用并可注入行为。 */
+export class FakeSubprocess implements SubprocessRuntime {
+  readonly resolved: string[] = [];
+  readonly specs: SubprocessSpawnSpec[] = [];
+  resolveHandler: (command: string) => string = command => `/usr/bin/${command}`;
+  outcomeHandler: () => SubprocessOutcome = successOutcome;
+
+  async resolveExecutable(command: string): Promise<string> {
+    this.resolved.push(command);
+    return this.resolveHandler(command);
+  }
+
+  spawn(spec: SubprocessSpawnSpec): SubprocessHandle {
+    this.specs.push(spec);
+    return new FakeSubprocessHandle(this.specs.length, this.outcomeHandler);
+  }
+}

package/packages/tests/mocks/user-questions.ts

@@ -0,0 +1,33 @@
+/**
+ * 内存 mock userQuestions（测试专用，非发布面）。
+ *
+ * 提供 `ask` 等价语义：记录每次调用，支持「可编程 handler」与「答案队列」两种
+ * 回复注入；无 handler 且队列空时挂起（等待引擎 `replyQuestion` 兼容路径或测试
+ * 手动 resolve）。以 `ctx.provide('userQuestions', …)` 注入。
+ * @module dsh-sandore/workflow/tests/mocks/user-questions
+ */
+import type { AskUserQuestionAnswer } from '../../workflow/types.ts';
+import type { UserQuestions, UserQuestionsRequest } from '../../workflow/seam.ts';
+
+/** 内存 mock userQuestions：记录调用并支持可编程回复。 */
+export class FakeUserQuestions implements UserQuestions {
+  /** 每次 `ask` 调用的入参记录。 */
+  readonly calls: UserQuestionsRequest[] = [];
+  /** 待回复答案队列（`ask` 依次弹出）。 */
+  readonly answers: AskUserQuestionAnswer[] = [];
+  /** 可编程回复 handler（优先级高于答案队列）。 */
+  resolveNext?: (request: UserQuestionsRequest) => Promise<AskUserQuestionAnswer>;
+
+  ask(request: UserQuestionsRequest): Promise<AskUserQuestionAnswer> {
+    this.calls.push(request);
+    if (this.resolveNext !== undefined) {
+      return this.resolveNext(request);
+    }
+    const answer = this.answers.shift();
+    if (answer !== undefined) {
+      return Promise.resolve(answer);
+    }
+    // 无编程回复：挂起（永不 resolve），由兼容路径或测试手动驱动。
+    return new Promise<AskUserQuestionAnswer>(() => {});
+  }
+}

package/packages/tests/mocks/workspace.ts

@@ -0,0 +1,52 @@
+/**
+ * 内存 mock workspace（测试专用，非发布面）。
+ *
+ * 对齐引擎接缝类型 `WorkspaceRegistrySeam`/`WorkspaceSeam`（签名同 DSH
+ * `WorkspaceRegistry.resolveByPath` / `WorkspaceRegistry.create` /
+ * `Workspace.attachSession`）：FakeWorkspaceRegistry 按路径 Map 解析，
+ * `create` 把路径登记为新 workspace（mock 不做目录存在性校验——校验是 DSH
+ * 真实实体职责），FakeWorkspace 只记录 attach 的会话 id（不做 header cwd
+ * 校验——校验是 DSH 真实实体职责，mock 只验证引擎的 attach 调用面）。以
+ * `ctx.provide('workspaceRegistry', …)` 注入。
+ * @module dsh-sandore/workflow/tests/mocks/workspace
+ */
+import type { SessionId } from '@deepseek-ai/dsh-session';
+
+/** 单个 fake workspace：`attachSession` 记录会话 id（不校验 header cwd）。 */
+export class FakeWorkspace {
+  /** 已 attach 的会话 id（按调用顺序）。 */
+  readonly attached: SessionId[] = [];
+
+  /** @param path - 该 workspace 的规范目录路径（`resolveByPath` 的匹配键）。 */
+  constructor(readonly path: string) {}
+
+  attachSession(sessionId: SessionId): Promise<void> {
+    this.attached.push(sessionId);
+    return Promise.resolve();
+  }
+}
+
+/** fake workspace 注册表：按路径 Map 解析（未命中返回 undefined）。 */
+export class FakeWorkspaceRegistry {
+  private readonly byPath = new Map<string, FakeWorkspace>();
+
+  /** @param workspaces - 登记进注册表的 fake workspace 列表。 */
+  constructor(workspaces: readonly FakeWorkspace[]) {
+    for (const workspace of workspaces) {
+      this.byPath.set(workspace.path, workspace);
+    }
+  }
+
+  resolveByPath(path: string): Promise<FakeWorkspace | undefined> {
+    return Promise.resolve(this.byPath.get(path));
+  }
+
+  /** 按路径登记一个新 workspace（已存在则返回原实体，对齐 DSH create 语义）。 */
+  create(path: string): Promise<FakeWorkspace> {
+    const existing = this.byPath.get(path);
+    if (existing !== undefined) return Promise.resolve(existing);
+    const workspace = new FakeWorkspace(path);
+    this.byPath.set(path, workspace);
+    return Promise.resolve(workspace);
+  }
+}