@meiyukichan/dsh-sandore 0.1.0-rc.6

package/packages/workflow/host-agent.ts

@@ -0,0 +1,62 @@
+/**
+ * 宿主主代理的 setup 工厂（§3.0：宿主主代理 = 纯 DSH 默认主代理）。
+ *
+ * `createHostAgentSetup` 生成「同参同闭包」的 `AgentSetup` 回调，供宿主主代理的
+ * `ctx.agents.create` 与 `ctx.agents.resume` 共用：回调内唯一动作是挂默认 agent
+ * preset（系统提示词/skills/工具全进来），与工作区普通会话走同一组装路径。
+ *
+ * 实现对齐 apiproxy `composeAgent`（`packages/host/apiproxy/src/api-proxy.ts:1196`）：
+ * `agentPresets` 服务从引擎 ctx `get` 后**闭包捕获**传入工厂（不在 setup 内直接访问
+ * `agentCtx.agentPresets` 属性——agent scope Context 未声明该注入，属性访问会抛
+ * `cannot get property "agentPresets" without inject`）；setup 内 `presets.mount(agentCtx)`
+ * （无 id = 默认 preset）把 agent scope key 挂到默认 preset 的 standing mount。
+ *
+ * 不叠加任何 sandore 工具、不注入角色提示词（2026-08 探索定夺）：
+ * - 引擎驱动执行、UI 走 RPC，8 个 `sandore_*` 编排工具没有"必需"消费场景（暂停/
+ *   恢复/重试/状态都有按钮）；工具 schema 反而占模型上下文、暗示"你是编排器"。
+ * - 角色提示词与 DSH 默认系统提示词并存会造成角色冲突（"通用助手" vs "编排器"）。
+ * - 唯一必须保留的是 **`hostAgent` 引用**（不是注册！）：引擎用它的身份做
+ *   `subagents.interrupt`/`followup` 的 authority/parent——DSH 机制要求，与工具注册无关。
+ *
+ * setup 只组合、不驱动（DSH「setup composes, never drives」），因此主代理创建后不会
+ * 自动发送首轮 prompt，编排仍由引擎 `runInstance` 主循环驱动。
+ * @module dsh-sandore/workflow/src/host-agent
+ */
+import type { AgentSetup } from '../microflow/subagents';
+
+/** `ctx.agentPresets` 服务的最小面（由引擎 get 后传入工厂；签名对齐 DSH AgentPresets）。 */
+export interface AgentPresetsSeam {
+  /** 挂载 preset 组合到 agent scope（无 id = 默认 preset）。 */
+  mount(agentCtx: unknown, id?: string): Promise<unknown>;
+  /** 解析 preset（无 id = 默认），返回含 `id` 的 preset 对象。 */
+  resolve(id?: string): Promise<{ readonly id: string }>;
+}
+
+/**
+ * 创建宿主主代理 setup 回调的入参。
+ */
+export interface CreateHostAgentSetupOptions {
+  /** 工作流实例 ID。 */
+  readonly instanceId: string;
+  /** `ctx.agentPresets` 服务（由引擎在 create 前 resolve 并传入；无 preset 部署时为 undefined）。 */
+  readonly presets?: AgentPresetsSeam;
+}
+
+/**
+ * 创建宿主主代理的 setup 回调（create 与 resume 共用，保证注册行为一致）。
+ *
+ * 返回的 `AgentSetup` 在 agent/session 发布前执行：挂载 DSH 默认 agent preset。
+ * `presets` 服务缺失时（无 preset 部署）跳过 mount，与 apiproxy `composeAgent` 的
+ * `presets === undefined` 分支一致。
+ * @param options - 实例 ID 与（可选的）agentPresets 服务。
+ * @returns 宿主主代理的 setup 回调。
+ */
+export function createHostAgentSetup(options: CreateHostAgentSetupOptions): AgentSetup {
+  const { presets } = options;
+  return async (agentCtx) => {
+    if (presets === undefined) {
+      return;
+    }
+    await presets.mount(agentCtx);
+  };
+}

package/packages/workflow/index.ts

@@ -0,0 +1,25 @@
+/**
+ * sandore 工作流引擎包入口。
+ *
+ * 默认导出 `SandoreWorkflowPlugin`（复合插件，见 `plugin.ts`）——它在
+ * `[Service.init]` 中注册 `SandorePersistence` / `SandoreEngineRuntime` /
+ * `SandoreRemote` 三个子服务，使 cordis.yml 单条目挂载即可提供
+ * `sandorePersistence` / `sandoreEngine` / `sandore` RPC。`SandoreEngine`
+ * 抽象 Service、13 个 `sandore/*` 事件双声明与 `SandoreEngineStub` 桩以
+ * named export 提供（见 `seam.ts`）。
+ */
+export type * from './types.ts'
+export * from './errors.ts'
+export * from './schema.ts'
+export * from './domain.ts'
+export * from './yaml-parser.ts'
+export type * from './shell.ts'
+export * from './seam.ts'
+export * from './dag-navigator.ts'
+export * from './remote.ts'
+
+import SandoreEngineRuntime from './workflow-engine.ts';
+import SandoreWorkflowPlugin from './plugin.ts';
+
+export { SandoreEngineRuntime, SandoreWorkflowPlugin }
+export default SandoreWorkflowPlugin

package/packages/workflow/interaction-manager.spec.ts

@@ -0,0 +1,390 @@
+/**
+ * interaction-manager.ts 的单元测试：引擎级 ask 主通道（登记 + 事件 + 卡片 await）、
+ * pending Map 镜像持久化、replyQuestion/replyPermission 兼容路径与 unknown
+ * requestId 报错、权限镜像（无自动审批）。
+ *
+ * 双通道 ask 重构（4.4）后不再测试 `[[SANDORE_ASK]]` 标记块解析/转接——该机制已随
+ * delegateSubagentAsk/parseDelegatedAsk 删除（子代理提问走 child-scope
+ * ask_user_question 工具 → 引擎 askFromSubagent → 本管理器 ask 主通道）。
+ * @module dsh-sandore/workflow/src/interaction-manager.spec
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+import { FakeAgent } from '../tests/mocks/agents.ts';
+import { FakeUserQuestions } from '../tests/mocks/user-questions.ts';
+import type { Agent } from '../microflow/subagents';
+import {
+  InteractionManager,
+  isRejectedAnswer,
+  type InteractionManagerOptions,
+  type PermissionReply,
+} from './interaction-manager.ts';
+import type {
+  AskUserQuestionAnswer,
+  AskUserQuestionPayload,
+  PendingPermissionEntry,
+  PendingQuestionEntry,
+} from './types.ts';
+
+/** 构造一条 pending question 条目。 */
+function questionEntry(requestId: string, payload: AskUserQuestionPayload): PendingQuestionEntry {
+  return {
+    id: requestId,
+    stageId: 'stg-1',
+    stepId: 'step-1',
+    sessionId: 'inst-1',
+    requestId,
+    kind: 'question',
+    status: 'pending',
+    payload,
+    createdAt: '2026-08-16T00:00:00.000Z',
+  };
+}
+
+/** 构造一条 pending permission 条目。 */
+function permissionEntry(requestId: string): PendingPermissionEntry {
+  return {
+    id: requestId,
+    stageId: 'stg-1',
+    stepId: 'step-1',
+    sessionId: 'inst-1',
+    requestId,
+    kind: 'permission',
+    status: 'pending',
+    payload: { permission: 'write_file', patterns: ['/tmp/**'] },
+    createdAt: '2026-08-16T00:00:00.000Z',
+  };
+}
+
+/** 构造一个单题载荷（带选项）。 */
+function singleQuestionPayload(): AskUserQuestionPayload {
+  return {
+    questions: [{
+      id: 'q1',
+      question: 'Which one?',
+      options: [{ label: 'A' }, { label: 'B', description: 'second' }],
+    }],
+  };
+}
+
+/** 构造一个整批回答。 */
+function answer(selected: string[]): AskUserQuestionAnswer {
+  return { answers: [{ id: 'q1', selected }] };
+}
+
+/** 组装测试依赖（hostAgent + FakeUserQuestions + vi.fn 桩）。 */
+function makeDeps(options?: { userQuestions?: FakeUserQuestions; hostAgent?: Agent; reportToHost?: boolean }): {
+  deps: InteractionManagerOptions;
+  userQuestions: FakeUserQuestions;
+  hostAgent: Agent;
+  persist: ReturnType<typeof vi.fn>;
+  emitQuestion: ReturnType<typeof vi.fn>;
+  emitPermission: ReturnType<typeof vi.fn>;
+  emitQuestionRejected: ReturnType<typeof vi.fn>;
+} {
+  const userQuestions = options?.userQuestions ?? new FakeUserQuestions();
+  const hostAgent = options?.hostAgent ?? new FakeAgent('host-1');
+  const persist = vi.fn();
+  const emitQuestion = vi.fn();
+  const emitPermission = vi.fn();
+  const emitQuestionRejected = vi.fn();
+  const deps: InteractionManagerOptions = {
+    hostAgent,
+    userQuestions: () => userQuestions,
+    // Round 26：默认上报宿主（场景 B，兼容既有用例）；场景 A 用例显式传 false。
+    reportToHost: options?.reportToHost ?? true,
+    persist,
+    emitQuestion,
+    emitPermission,
+    emitQuestionRejected,
+  };
+  return { deps, userQuestions, hostAgent, persist, emitQuestion, emitPermission, emitQuestionRejected };
+}
+
+describe('InteractionManager.addPendingQuestion / addPendingPermission', () => {
+  it('addPendingQuestion 登记即持久化（pending 条目）并发射 sandore/question', () => {
+    const { deps, persist, emitQuestion, emitPermission } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = questionEntry('req-1', singleQuestionPayload());
+
+    mgr.addPendingQuestion(entry);
+
+    expect(persist).toHaveBeenCalledWith([entry]);
+    expect(emitQuestion).toHaveBeenCalledWith(entry);
+    expect(emitPermission).not.toHaveBeenCalled();
+  });
+
+  it('addPendingPermission 登记即持久化（pending 条目）并发射 sandore/permission', () => {
+    const { deps, persist, emitPermission } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = permissionEntry('req-p');
+
+    mgr.addPendingPermission(entry);
+
+    expect(persist).toHaveBeenCalledWith([entry]);
+    expect(emitPermission).toHaveBeenCalledWith(entry);
+  });
+});
+
+describe('InteractionManager.ask（引擎级 ask 主通道）', () => {
+  it('以 hostAgent 身份调用 userQuestions.ask，questions 对齐 AskUserQuestionItem（蛇形 multi_select → 驼峰 multiSelect）', async () => {
+    const { deps, userQuestions, hostAgent } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const payload: AskUserQuestionPayload = {
+      questions: [{
+        id: 'q1',
+        question: 'Which one?',
+        header: 'Choice',
+        options: [{ label: 'A' }],
+        multi_select: true,
+      }],
+    };
+    const entry = questionEntry('req-1', payload);
+    const result = answer(['A']);
+    userQuestions.answers.push(result);
+
+    await expect(mgr.ask({ entry })).resolves.toEqual(result);
+
+    expect(userQuestions.calls).toHaveLength(1);
+    const request = userQuestions.calls[0]!;
+    expect(request.agent).toBe(hostAgent);
+    expect(request.questions).toEqual([{
+      id: 'q1',
+      question: 'Which one?',
+      header: 'Choice',
+      options: [{ label: 'A' }],
+      multiSelect: true,
+    }]);
+  });
+
+  it('卡片回复后条目移出 pending 并持久化空列表（终态条目只留内存审计）', async () => {
+    const { deps, userQuestions, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = questionEntry('req-1', singleQuestionPayload());
+    userQuestions.answers.push(answer(['A']));
+
+    await mgr.ask({ entry });
+
+    // §3.6A P0#3：syncState 只持久化 pending；回复后 pending Map 清空 → 持久化 []。
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingQuestionEntry[];
+    expect(lastCall).toEqual([]);
+  });
+
+  it('无卡片通道时挂起，等待 replyQuestion 兼容路径 resolve（与 ask 的 await 汇合）', async () => {
+    const { deps, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = questionEntry('req-1', singleQuestionPayload());
+    const result = answer(['A']);
+
+    const asking = mgr.ask({ entry });
+    await mgr.replyQuestion('req-1', result);
+    await expect(asking).resolves.toEqual(result);
+
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingQuestionEntry[];
+    expect(lastCall).toEqual([]);
+  });
+});
+
+describe('InteractionManager.replyQuestion', () => {
+  it('未知 requestId 抛 SandoreError(INVALID_OPERATION)', async () => {
+    const { deps } = makeDeps();
+    const mgr = new InteractionManager(deps);
+
+    await expect(mgr.replyQuestion('nope', answer(['A']))).rejects.toMatchObject({ code: 'INVALID_OPERATION' });
+  });
+
+  it('已 replied 的 requestId 再次回复抛 SandoreError(INVALID_OPERATION)', async () => {
+    const { deps, userQuestions } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = questionEntry('req-1', singleQuestionPayload());
+    userQuestions.answers.push(answer(['A']));
+
+    await mgr.ask({ entry });
+    await expect(mgr.replyQuestion('req-1', answer(['A']))).rejects.toMatchObject({ code: 'INVALID_OPERATION' });
+  });
+});
+
+describe('InteractionManager.replyPermission', () => {
+  it('reply=once/always 将条目移出 pending 并持久化空列表（终态条目只留内存审计）', async () => {
+    const { deps, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = permissionEntry('req-p');
+    mgr.addPendingPermission(entry);
+
+    await mgr.replyPermission('req-p', 'always');
+
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingPermissionEntry[];
+    expect(lastCall).toEqual([]);
+  });
+
+  it('reply=reject 将条目移出 pending 并持久化空列表（终态条目只留内存审计）', async () => {
+    const { deps, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = permissionEntry('req-p');
+    mgr.addPendingPermission(entry);
+
+    await mgr.replyPermission('req-p', 'reject');
+
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingPermissionEntry[];
+    expect(lastCall).toEqual([]);
+  });
+
+  it('未知 permission requestId 抛 SandoreError(INVALID_OPERATION)', async () => {
+    const { deps } = makeDeps();
+    const mgr = new InteractionManager(deps);
+
+    await expect(mgr.replyPermission('nope', 'once' as PermissionReply)).rejects.toMatchObject({ code: 'INVALID_OPERATION' });
+  });
+});
+
+describe('InteractionManager.rejectQuestion（缺陷 26：公开拒绝 → 终态化 + resolve 占位非 reject）', () => {
+  it('终态化（status rejected）+ 删 Map + resolve（非 reject）waiter 占位答案 + 持久化空列表 + 发 question_rejected', async () => {
+    const { deps, persist, emitQuestionRejected } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = questionEntry('req-1', singleQuestionPayload());
+    const asking = mgr.ask({ entry });
+
+    await mgr.rejectQuestion('req-1');
+
+    // waiter 以拒绝占位 resolve（非 reject——避免冒泡 runAndCatch 落实例 failed）。
+    const answer = await asking;
+    expect(answer).toEqual({ answers: [], rejected: true });
+    expect(isRejectedAnswer(answer)).toBe(true);
+    // 终态条目移出 pending Map → 持久化空列表（终态条目只留内存审计）。
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingQuestionEntry[];
+    expect(lastCall).toEqual([]);
+    // 双发 sandore/question_rejected（供 UI 刷新）；载荷是终态化（rejected）条目。
+    expect(emitQuestionRejected).toHaveBeenCalledWith({ ...entry, status: 'rejected' });
+  });
+
+  it('拒绝后条目不再 pending（再次 reject/reply 抛 INVALID_OPERATION）', async () => {
+    const { deps } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = questionEntry('req-1', singleQuestionPayload());
+    const asking = mgr.ask({ entry });
+    await mgr.rejectQuestion('req-1');
+    await asking;
+
+    await expect(mgr.rejectQuestion('req-1')).rejects.toMatchObject({ code: 'INVALID_OPERATION' });
+    await expect(mgr.replyQuestion('req-1', answer(['A']))).rejects.toMatchObject({ code: 'INVALID_OPERATION' });
+  });
+
+  it('未知 requestId 抛 SandoreError(INVALID_OPERATION)', async () => {
+    const { deps } = makeDeps();
+    const mgr = new InteractionManager(deps);
+
+    await expect(mgr.rejectQuestion('nope')).rejects.toMatchObject({ code: 'INVALID_OPERATION' });
+  });
+
+  it('resolve 占位答案与 cancelMatching 的 CANCELLED_ANSWER 区分（带 rejected 标记）', async () => {
+    const { deps } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const entry = questionEntry('req-1', singleQuestionPayload());
+    const asking = mgr.ask({ entry });
+
+    await mgr.rejectQuestion('req-1');
+    const answer = await asking;
+
+    // 拒绝占位带 rejected:true 标记；clearAll/clearPendingInteractions 的 CANCELLED_ANSWER 无此标记。
+    expect(isRejectedAnswer(answer)).toBe(true);
+    expect(isRejectedAnswer({ answers: [] })).toBe(false);
+  });
+});
+
+// ── 双通道 ask 重构（4.4）后：delegateSubagentAsk / parseDelegatedAsk 已随
+// [[SANDORE_ASK]] 标记块机制删除——子代理提问走 child-scope ask_user_question 工具
+// （引擎 askFromSubagent → 本管理器 ask 主通道，见 workflow-engine.spec.ts 的
+// askFromSubagent 测试）。交互管理器保留的 ask 主通道/兼容回复/拒绝语义由上方
+// 各 describe 覆盖（登记 + 事件 + 卡片 await + replyQuestion/rejectQuestion）。
+
+describe('InteractionManager.clearPendingInteractions / clearAll（缺陷 27 + 缺陷 9 崩溃恢复）', () => {
+  it('clearPendingInteractions(stepId) 终态化匹配条目 + resolve waiter 占位答案 + 持久化剩余 pending', async () => {
+    const { deps, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const step1Entry = questionEntry('req-1', singleQuestionPayload());
+    const step2Entry: PendingQuestionEntry = { ...questionEntry('req-2', singleQuestionPayload()), stepId: 'step-2' };
+
+    // 登记 step-1 的 ask（挂起 waiter）+ step-2 的 pending（不挂 waiter）。
+    const asking = mgr.ask({ entry: step1Entry });
+    mgr.addPendingQuestion(step2Entry);
+
+    mgr.clearPendingInteractions('step-1');
+
+    // step-1 waiter 以「已取消」占位答案 resolve（非 reject，避免冒泡 failed）。
+    await expect(asking).resolves.toEqual({ answers: [] });
+    // step-2 条目保留并重持久化（step-1 已清）。
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingQuestionEntry[];
+    expect(lastCall).toEqual([step2Entry]);
+  });
+
+  it('clearPendingInteractions 无匹配 stepId 时不触发 syncState（无 spurious 持久化）', async () => {
+    const { deps, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    mgr.addPendingQuestion(questionEntry('req-1', singleQuestionPayload()));
+    const callsBefore = persist.mock.calls.length;
+
+    mgr.clearPendingInteractions('step-missing');
+
+    expect(persist.mock.calls.length).toBe(callsBefore);
+    // 条目仍在（无匹配未清理）：replyQuestion 可正常终态化。
+    await expect(mgr.replyQuestion('req-1', answer(['A']))).resolves.toBeUndefined();
+  });
+
+  it('clearAll 终态化全部 pending（question+permission）+ resolve 全部 waiter + 持久化空列表', async () => {
+    const { deps, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const qEntry = questionEntry('req-q', singleQuestionPayload());
+    const pEntry = permissionEntry('req-p');
+    const asking = mgr.ask({ entry: qEntry });
+    mgr.addPendingPermission(pEntry);
+
+    mgr.clearAll();
+
+    await expect(asking).resolves.toEqual({ answers: [] });
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingInteractionEntry[];
+    expect(lastCall).toEqual([]);
+  });
+
+  it('clearAll 在 Maps 为空时仍 syncState 覆盖 stale 快照 pendingInteractions（缺陷 9 崩溃恢复路径）', () => {
+    const { deps, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+
+    // Maps 为空（崩溃恢复重建态）：clearAll 仍触发 syncState 持久化空 pending。
+    mgr.clearAll();
+
+    expect(persist).toHaveBeenCalledWith([]);
+  });
+
+  it('场景 A（reportToHost=false）：ask 不上报宿主（不调 userQuestions.ask），仅 replyQuestion 驱动', async () => {
+    const { deps, userQuestions, persist } = makeDeps({ reportToHost: false });
+    const mgr = new InteractionManager(deps);
+    const asking = mgr.ask({ entry: questionEntry('req-a', singleQuestionPayload()) });
+
+    // 不上报宿主：userQuestions.ask 不被调用（等 replyQuestion 兼容路径）。
+    await Promise.resolve();
+    expect(userQuestions.calls).toHaveLength(0);
+
+    await mgr.replyQuestion('req-a', answer(['A']));
+    await expect(asking).resolves.toEqual(answer(['A']));
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingInteractionEntry[];
+    expect(lastCall).toEqual([]);
+  });
+
+  it('场景 B（reportToHost=true）：composer 回答（replyQuestion）后同步 abort 宿主 DSH 弹窗', async () => {
+    const { deps, userQuestions, persist } = makeDeps();
+    const mgr = new InteractionManager(deps);
+    const asking = mgr.ask({ entry: questionEntry('req-b', singleQuestionPayload()) });
+
+    await Promise.resolve();
+    expect(userQuestions.calls).toHaveLength(1);
+    const signal = userQuestions.calls[0]?.signal;
+    expect(signal?.aborted).toBe(false);
+
+    // composer 卡回答 → finishQuestion resolve 引擎 waiter + abort DSH 弹窗 signal。
+    await mgr.replyQuestion('req-b', answer(['B']));
+    await expect(asking).resolves.toEqual(answer(['B']));
+    expect(signal?.aborted).toBe(true);
+    const lastCall = persist.mock.calls[persist.mock.calls.length - 1]?.[0] as PendingInteractionEntry[];
+    expect(lastCall).toEqual([]);
+  });
+});