@s_s/harmonia 1.3.0 → 1.4.0

package/build/tools/project-init.js

@@ -1,19 +1,23 @@
 /**
  * MCP Tool: project_init
- * Register a new Harmonia project in the global registry.
+ * Register a new Harmonia project in the global registry and install workflow hooks.
  *
- * This tool ONLY registers the project — it does NOT create iteration directories
- * or initialize state. After registration, call `iteration_start` to begin the
- * first iteration.
+ * This tool registers the project AND installs workflow-defined hooks for the
+ * detected agent. It does NOT create iteration directories or initialize state.
+ * After registration, call `iteration_start` to begin the first iteration.
  *
  * Supports an optional `workflow` parameter. When multiple workflows are
  * available and none is specified, returns an error with the available list
  * so the agent can re-call with a specific choice.
  */
 import { z } from 'zod';
-import { loadWorkflow, listWorkflows } from '../core/workflow.js';
-import { registerProject, getProject } from '../core/registry.js';
-export function registerProjectInit(server, builtinDir, customDir) {
+import { createKit, defineHooks } from '@s_s/agent-kit';
+import { loadWorkflow, listWorkflows } from '../core/plugin.js';
+import { registerProject, getProject, getGlobalDir } from '../core/registry.js';
+import { detectHostAgent } from '../setup/inject.js';
+/** Shared kit instance for hook installation */
+const kit = createKit('harmonia');
+export function registerProjectInit(server, workflowsDir) {
     server.tool('project_init', 'Register a new Harmonia project. Creates the project entry in the global registry and the project source directory. Does NOT start an iteration — call iteration_start after registration to begin the first iteration.', {
         project_name: z
             .string()
@@ -59,7 +63,7 @@ export function registerProjectInit(server, builtinDir, customDir) {
             };
         }
         // Resolve workflow name
-        const available = await listWorkflows(builtinDir, customDir);
+        const available = await listWorkflows(workflowsDir);
         if (available.length === 0) {
             return {
                 content: [
@@ -97,7 +101,7 @@ export function registerProjectInit(server, builtinDir, customDir) {
             const descriptions = [];
             for (const name of available) {
                 try {
-                    const wf = await loadWorkflow(builtinDir, customDir, name);
+                    const wf = await loadWorkflow(workflowsDir, name);
                     descriptions.push(`- ${name}: ${wf.definition.description}`);
                 }
                 catch {
@@ -121,9 +125,35 @@ export function registerProjectInit(server, builtinDir, customDir) {
             };
         }
         // Load workflow definition (validate it loads correctly)
-        const wf = await loadWorkflow(builtinDir, customDir, workflowName);
+        const wf = await loadWorkflow(workflowsDir, workflowName);
         // Register project (creates global data dir + project source dir)
         await registerProject(project_name, project_dir, workflowName);
+        // Install workflow hooks if the plugin provides a hook creator
+        let hookMessage = '';
+        if (wf.hooks) {
+            try {
+                const agentType = await detectHostAgent(project_dir);
+                const context = {
+                    defineHooks,
+                    dataDir: getGlobalDir(),
+                    projectName: project_name,
+                };
+                const hookSet = wf.hooks(agentType, context);
+                const hookResult = await kit.installHooks(agentType, hookSet);
+                if (hookResult.success) {
+                    hookMessage = `\nHooks 已安装 (${hookResult.filesWritten.length} 个文件)`;
+                    if (hookResult.warnings.length > 0) {
+                        hookMessage += `\n警告: ${hookResult.warnings.join('; ')}`;
+                    }
+                }
+                else {
+                    hookMessage = `\n[warn] Hook 安装失败: ${hookResult.error ?? '未知错误'}`;
+                }
+            }
+            catch (err) {
+                hookMessage = `\n[warn] Hook 安装出错: ${err instanceof Error ? err.message : String(err)}`;
+            }
+        }
         return {
             content: [
                 {
@@ -134,6 +164,7 @@ export function registerProjectInit(server, builtinDir, customDir) {
                         `源代码目录: ${project_dir}`,
                         `工作流: ${wf.definition.name} (${wf.definition.description})`,
                         `可用角色: ${Object.keys(wf.roles).join(', ')}`,
+                        hookMessage,
                         ``,
                         `下一步: 调用 iteration_start(project_name="${project_name}") 开始第一轮迭代。`,
                     ].join('\n'),

package/build/tools/project-init.js.map

@@ -1 +1 @@
-{"version":3,"file":"project-init.js","sourceRoot":"","sources":["../../src/tools/project-init.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"project-init.js","sourceRoot":"","sources":["../../src/tools/project-init.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,SAAS,EAAE,WAAW,EAAwC,MAAM,gBAAgB,CAAC;AAC9F,OAAO,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAChF,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAGrD,gDAAgD;AAChD,MAAM,GAAG,GAAG,SAAS,CAAC,UAAU,CAAC,CAAC;AAElC,MAAM,UAAU,mBAAmB,CAAC,MAAiB,EAAE,YAAoB;IACvE,MAAM,CAAC,IAAI,CACP,cAAc,EACd,yNAAyN,EACzN;QACI,YAAY,EAAE,CAAC;aACV,MAAM,EAAE;aACR,KAAK,CACF,8BAA8B,EAC9B,0CAA0C,CAC7C;aACA,GAAG,CAAC,CAAC,EAAE,uBAAuB,CAAC;aAC/B,GAAG,CAAC,EAAE,EAAE,wBAAwB,CAAC;aACjC,QAAQ,CAAC,kCAAkC,CAAC;QACjD,WAAW,EAAE,CAAC;aACT,MAAM,EAAE;aACR,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,EAAE,EAAE,OAAO,EAAE,6BAA6B,EAAE,CAAC;aAC5E,QAAQ,CAAC,yBAAyB,CAAC;QACxC,QAAQ,EAAE,CAAC;aACN,MAAM,EAAE;aACR,QAAQ,EAAE;aACV,QAAQ,CAAC,sCAAsC,CAAC;KACxD,EACD,KAAK,EAAE,EAAE,YAAY,EAAE,WAAW,EAAE,QAAQ,EAAE,EAAE,EAAE;QAC9C,8BAA8B;QAC9B,MAAM,QAAQ,GAAG,MAAM,UAAU,CAAC,YAAY,CAAC,CAAC;QAChD,IAAI,QAAQ,EAAE,CAAC;YACX,MAAM,WAAW,GAAG,QAAQ,CAAC,aAAa;gBACtC,CAAC,CAAC,UAAU,QAAQ,CAAC,aAAa,EAAE;gBACpC,CAAC,CAAC,WAAW,CAAC;YAElB,OAAO;gBACH,OAAO,EAAE;oBACL;wBACI,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE;4BACF,OAAO,YAAY,QAAQ;4BAC3B,EAAE;4BACF,UAAU,QAAQ,CAAC,GAAG,EAAE;4BACxB,QAAQ,QAAQ,CAAC,QAAQ,EAAE;4BAC3B,OAAO,QAAQ,CAAC,eAAe,UAAU,QAAQ,CAAC,YAAY,IAAI;4BAClE,GAAG,WAAW,EAAE;4BAChB,EAAE;4BACF,QAAQ,CAAC,aAAa;gCAClB,CAAC,CAAC,6CAA6C,YAAY,KAAK;gCAChE,CAAC,CAAC,qCAAqC,YAAY,aAAa;yBACvE;6BACI,MAAM,CAAC,OAAO,CAAC;6BACf,IAAI,CAAC,IAAI,CAAC;qBAClB;iBACJ;aACJ,CAAC;QACN,CAAC;QAED,wBAAwB;QACxB,MAAM,SAAS,GAAG,MAAM,aAAa,CAAC,YAAY,CAAC,CAAC;QAEpD,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACzB,OAAO;gBACH,OAAO,EAAE;oBACL;wBACI,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE,gDAAgD;qBACzD;iBACJ;gBACD,OAAO,EAAE,IAAI;aAChB,CAAC;QACN,CAAC;QAED,IAAI,YAAoB,CAAC;QAEzB,IAAI,QAAQ,EAAE,CAAC;YACX,mDAAmD;YACnD,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAChC,OAAO;oBACH,OAAO,EAAE;wBACL;4BACI,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,QAAQ,QAAQ,iBAAiB,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;yBAChE;qBACJ;oBACD,OAAO,EAAE,IAAI;iBAChB,CAAC;YACN,CAAC;YACD,YAAY,GAAG,QAAQ,CAAC;QAC5B,CAAC;aAAM,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAChC,kCAAkC;YAClC,YAAY,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;QAChC,CAAC;aAAM,CAAC;YACJ,+CAA+C;YAC/C,+DAA+D;YAC/D,MAAM,YAAY,GAAa,EAAE,CAAC;YAClC,KAAK,MAAM,IAAI,IAAI,SAAS,EAAE,CAAC;gBAC3B,IAAI,CAAC;oBACD,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,YAAY,EAAE,IAAI,CAAC,CAAC;oBAClD,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,WAAW,EAAE,CAAC,CAAC;gBACjE,CAAC;gBAAC,MAAM,CAAC;oBACL,YAAY,CAAC,IAAI,CAAC,KAAK,IAAI,YAAY,CAAC,CAAC;gBAC7C,CAAC;YACL,CAAC;YAED,OAAO;gBACH,OAAO,EAAE;oBACL;wBACI,IAAI,EAAE,MAAe;wBACrB,IAAI,EAAE;4BACF,KAAK,SAAS,CAAC,MAAM,0BAA0B;4BAC/C,EAAE;4BACF,GAAG,YAAY;4BACf,EAAE;4BACF,kCAAkC,YAAY,mBAAmB,WAAW,oBAAoB;yBACnG,CAAC,IAAI,CAAC,IAAI,CAAC;qBACf;iBACJ;gBACD,OAAO,EAAE,IAAI;aAChB,CAAC;QACN,CAAC;QAED,yDAAyD;QACzD,MAAM,EAAE,GAAG,MAAM,YAAY,CAAC,YAAY,EAAE,YAAY,CAAC,CAAC;QAE1D,kEAAkE;QAClE,MAAM,eAAe,CAAC,YAAY,EAAE,WAAW,EAAE,YAAY,CAAC,CAAC;QAE/D,+DAA+D;QAC/D,IAAI,WAAW,GAAG,EAAE,CAAC;QACrB,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC;YACX,IAAI,CAAC;gBACD,MAAM,SAAS,GAAG,MAAM,eAAe,CAAC,WAAW,CAAC,CAAC;gBACrD,MAAM,OAAO,GAAuB;oBAChC,WAAW;oBACX,OAAO,EAAE,YAAY,EAAE;oBACvB,WAAW,EAAE,YAAY;iBAC5B,CAAC;gBACF,MAAM,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC,SAAS,EAAE,OAAO,CAAwB,CAAC;gBACpE,MAAM,UAAU,GAAsB,MAAM,GAAG,CAAC,YAAY,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;gBACjF,IAAI,UAAU,CAAC,OAAO,EAAE,CAAC;oBACrB,WAAW,GAAG,gBAAgB,UAAU,CAAC,YAAY,CAAC,MAAM,OAAO,CAAC;oBACpE,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;wBACjC,WAAW,IAAI,SAAS,UAAU,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;oBAC7D,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACJ,WAAW,GAAG,uBAAuB,UAAU,CAAC,KAAK,IAAI,MAAM,EAAE,CAAC;gBACtE,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACX,WAAW,GAAG,uBAAuB,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;YAC5F,CAAC;QACL,CAAC;QAED,OAAO;YACH,OAAO,EAAE;gBACL;oBACI,IAAI,EAAE,MAAe;oBACrB,IAAI,EAAE;wBACF,OAAO,YAAY,SAAS;wBAC5B,EAAE;wBACF,UAAU,WAAW,EAAE;wBACvB,QAAQ,EAAE,CAAC,UAAU,CAAC,IAAI,KAAK,EAAE,CAAC,UAAU,CAAC,WAAW,GAAG;wBAC3D,SAAS,MAAM,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE;wBAC3C,WAAW;wBACX,EAAE;wBACF,yCAAyC,YAAY,aAAa;qBACrE,CAAC,IAAI,CAAC,IAAI,CAAC;iBACf;aACJ;SACJ,CAAC;IACN,CAAC,CACJ,CAAC;AACN,CAAC"}

package/build/tools/role-dispatch.d.ts

@@ -0,0 +1,55 @@
+/**
+ * MCP Tool: role_dispatch
+ *
+ * Prepare all data needed to hand off a task to a team member role.
+ * Returns: role prompt (with overrides injected), session guidance,
+ * input artifacts, task brief, and dispatch tracking info.
+ *
+ * Node-based architecture: validates against workflow node states.
+ * Accepts an optional node_id parameter to target a specific task node.
+ *
+ * Session/parallel behavior is enforced by Core:
+ * - session: none → never searches for idle sessions
+ * - session: persistent → searches for idle sessions, directs reuse
+ * - session: optional → searches for idle sessions, suggests reuse
+ * - parallel: true + running dispatch → forces new session
+ *
+ * Automatically:
+ * - Creates a dispatch record for tracking
+ * - Enforces session/parallel strategy from role frontmatter
+ * - Triggers a dispatch_requested engine event
+ * - Returns nextAction from the workflow engine
+ *
+ * This tool does NOT launch agents — it only prepares the data.
+ * The coordinator decides how to pass this to the team member.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { ArtifactIOContext } from '../core/artifacts.js';
+import type { WorkflowPlugin } from '../core/types.js';
+/**
+ * Get file extension from artifact definition format.
+ * - 'html' → '.html'
+ * - 'json' → '.json'
+ * - 'md' or undefined → '.md'
+ */
+export declare function getFormatExtension(format?: 'md' | 'html' | 'json'): string;
+/** A resolved input artifact reference */
+export interface InputReference {
+    /** Artifact ID */
+    id: string;
+    /** Human-readable name from artifact definition */
+    name: string;
+    /** Resolved file path (managed) or directory path (unmanaged) */
+    path: string;
+    /** Whether this artifact was found on disk */
+    found: boolean;
+}
+/**
+ * Resolve an artifact ID to a name + path reference.
+ *
+ * - Managed artifacts: resolves to full file path via format → extension mapping
+ * - Unmanaged artifacts: resolves to the output directory
+ * - Unknown artifacts: returns not-found
+ */
+export declare function resolveInputReference(artifactId: string, wf: WorkflowPlugin, ioCtx: ArtifactIOContext, existingArtifacts: Set<string>): InputReference;
+export declare function registerDispatchRole(server: McpServer, workflowsDir: string): void;

package/build/tools/role-dispatch.js

@@ -0,0 +1,508 @@
+/**
+ * MCP Tool: role_dispatch
+ *
+ * Prepare all data needed to hand off a task to a team member role.
+ * Returns: role prompt (with overrides injected), session guidance,
+ * input artifacts, task brief, and dispatch tracking info.
+ *
+ * Node-based architecture: validates against workflow node states.
+ * Accepts an optional node_id parameter to target a specific task node.
+ *
+ * Session/parallel behavior is enforced by Core:
+ * - session: none → never searches for idle sessions
+ * - session: persistent → searches for idle sessions, directs reuse
+ * - session: optional → searches for idle sessions, suggests reuse
+ * - parallel: true + running dispatch → forces new session
+ *
+ * Automatically:
+ * - Creates a dispatch record for tracking
+ * - Enforces session/parallel strategy from role frontmatter
+ * - Triggers a dispatch_requested engine event
+ * - Returns nextAction from the workflow engine
+ *
+ * This tool does NOT launch agents — it only prepares the data.
+ * The coordinator decides how to pass this to the team member.
+ */
+import { z } from 'zod';
+import { readArtifact, listArtifacts, resolveArtifactDir } from '../core/artifacts.js';
+import { getMergedOverrides, resolveRoleConfig } from '../core/overrides.js';
+import { createDispatch, findIdleSession, hasRunningDispatch } from '../core/dispatch.js';
+import { loadArtifactSchema, formatSchemaGuidance } from '../core/schema.js';
+import { resolveActive, isError, buildOverrideSection } from './utils.js';
+import { loadWorkflowForContext, processWorkflowEvent, formatNextAction, findTaskNode } from './engine-helpers.js';
+import { collectTaskNodes, findAncestorLoopId } from '../core/tree-utils.js';
+/**
+ * Find task nodes for a given role that are active or pending.
+ */
+function findDispatchableNodes(wf, state, role) {
+    const allTasks = collectTaskNodes(wf.definition.root);
+    // Include floating nodes
+    if (wf.definition.floatingNodes) {
+        allTasks.push(...wf.definition.floatingNodes);
+    }
+    return allTasks.filter((t) => {
+        if (t.role !== role)
+            return false;
+        const nodeState = state.nodes[t.id];
+        return nodeState && (nodeState.status === 'active' || nodeState.status === 'pending');
+    });
+}
+/**
+ * Build session guidance text.
+ *
+ * Incorporates session type behavior, parallel status, model, and agent info.
+ * This replaces the former separate "## Configuration" section — all dispatch
+ * configuration info is now part of Session Guidance.
+ */
+function buildSessionGuidance(params) {
+    const { idleSession, sessionType, model, agent, parallelForced } = params;
+    const lines = [];
+    // Consistent agent descriptor used across all Action lines
+    const agentDesc = agent ? `拉起 ${agent} 作为子 agent 执行任务` : '拉起子 agent 执行任务';
+    // Model/agent header
+    if (model) {
+        const agentSuffix = agent ? `，使用 ${agent}` : '';
+        lines.push(`**Model**: \`${model}\`${agentSuffix}`);
+    }
+    else if (agent) {
+        lines.push(`**Agent**: ${agent}`);
+    }
+    if (lines.length > 0)
+        lines.push('');
+    // Session guidance based on type and findings
+    if (parallelForced) {
+        // parallel=true and same role already has a running dispatch → force new session
+        lines.push(`**Session**: 该角色已有运行中的 dispatch，强制启动新会话（parallel 模式）`);
+        lines.push('');
+        lines.push(`**Action**: ${agentDesc}。`);
+    }
+    else if (idleSession) {
+        const agentId = idleSession.agentSessionId
+            ? `Agent session ID: \`${idleSession.agentSessionId}\``
+            : 'Agent session ID: not recorded';
+        const label = idleSession.label ? ` (${idleSession.label})` : '';
+        lines.push(`**Reusable session found**: ${idleSession.id}${label}`);
+        lines.push(`- ${agentId}`);
+        lines.push(`- Agent type: ${idleSession.agentType ?? 'unknown'}`);
+        lines.push(`- Last active: ${idleSession.lastActiveAt}`);
+        lines.push('');
+        if (sessionType === 'persistent') {
+            lines.push(`**Action**: 复用已有会话，而非启动新 agent。`);
+            lines.push(idleSession.agentSessionId
+                ? `使用 \`--resume ${idleSession.agentSessionId}\` 或 \`--session ${idleSession.agentSessionId}\` 恢复会话。`
+                : `注意: 该会话未记录 agent session ID，可能需要${agentDesc}。`);
+        }
+        else {
+            // optional — suggestion, not directive
+            lines.push(`**Suggestion**: 存在空闲会话，可复用也可启动新会话，由你决定。`);
+            if (idleSession.agentSessionId) {
+                lines.push(`如需复用: \`--resume ${idleSession.agentSessionId}\` 或 \`--session ${idleSession.agentSessionId}\``);
+            }
+        }
+    }
+    else {
+        // No idle session found (or session type is 'none')
+        if (sessionType === 'none') {
+            lines.push(`**Session**: 每次 dispatch 启动全新会话（session: none）`);
+        }
+        else {
+            lines.push(`**未找到可复用会话**`);
+            lines.push(`Session type: ${sessionType}`);
+        }
+        lines.push('');
+        lines.push(`**Action**: ${agentDesc}。`);
+    }
+    return lines.join('\n');
+}
+/**
+ * Get file extension from artifact definition format.
+ * - 'html' → '.html'
+ * - 'json' → '.json'
+ * - 'md' or undefined → '.md'
+ */
+export function getFormatExtension(format) {
+    switch (format) {
+        case 'html':
+            return '.html';
+        case 'json':
+            return '.json';
+        default:
+            return '.md';
+    }
+}
+/**
+ * Resolve an artifact ID to a name + path reference.
+ *
+ * - Managed artifacts: resolves to full file path via format → extension mapping
+ * - Unmanaged artifacts: resolves to the output directory
+ * - Unknown artifacts: returns not-found
+ */
+export function resolveInputReference(artifactId, wf, ioCtx, existingArtifacts) {
+    const artifactDef = wf.artifactDefinitions[artifactId];
+    if (!artifactDef) {
+        return {
+            id: artifactId,
+            name: artifactId,
+            path: '',
+            found: false,
+        };
+    }
+    if (artifactDef.unmanaged) {
+        // Unmanaged: resolve to directory
+        const dir = resolveArtifactDir(artifactDef.output, ioCtx);
+        return {
+            id: artifactId,
+            name: artifactDef.name,
+            path: dir,
+            found: true, // unmanaged dirs are always "available"
+        };
+    }
+    // Managed: resolve to full file path via format → extension
+    const dir = resolveArtifactDir(artifactDef.output, ioCtx);
+    const ext = getFormatExtension(artifactDef.format);
+    const filePath = `${dir}/${artifactId}${ext}`;
+    return {
+        id: artifactId,
+        name: artifactDef.name,
+        path: filePath,
+        found: existingArtifacts.has(artifactId),
+    };
+}
+/**
+ * Build Artifact Requirements section for the dispatch data package.
+ * Only includes schemas for artifacts associated with the dispatched role
+ * (via the role's capabilities).
+ */
+async function buildArtifactRequirements(wf, workflowsDir, workflowName, role) {
+    const artifactDefs = wf.artifactDefinitions;
+    // Extract artifact IDs from role capabilities
+    const roleDef = wf.roles[role];
+    const roleArtifactIds = new Set();
+    if (roleDef?.frontmatter.capabilities) {
+        for (const cap of roleDef.frontmatter.capabilities) {
+            if (cap.artifact) {
+                roleArtifactIds.add(cap.artifact);
+            }
+        }
+    }
+    // If role has no artifact capabilities, skip
+    if (roleArtifactIds.size === 0)
+        return '';
+    const sections = [];
+    for (const artifactId of roleArtifactIds) {
+        const artifactDef = artifactDefs[artifactId];
+        if (!artifactDef || artifactDef.unmanaged)
+            continue;
+        // Load main schema
+        const schema = await loadArtifactSchema(workflowsDir, workflowName, artifactId);
+        // Load step schemas if artifact has steps
+        let stepSchemas;
+        if (artifactDef.steps && artifactDef.steps.length > 0) {
+            stepSchemas = [];
+            for (const step of artifactDef.steps) {
+                const stepSchema = await loadArtifactSchema(workflowsDir, workflowName, `${artifactId}.${step.id}`);
+                stepSchemas.push({ step, schema: stepSchema });
+            }
+        }
+        // Skip if no schema at all
+        if (!schema && (!stepSchemas || stepSchemas.every((s) => !s.schema)))
+            continue;
+        sections.push(formatSchemaGuidance(artifactId, artifactDef, schema, stepSchemas));
+    }
+    if (sections.length === 0)
+        return '';
+    return ['## Artifact Requirements', '', ...sections].join('\n');
+}
+export function registerDispatchRole(server, workflowsDir) {
+    server.tool('role_dispatch', "Prepare all data needed to dispatch a task to a team member. Returns the role's prompt (with capability overrides), configuration, input artifacts, task brief, and a dispatch tracking ID. Automatically searches for reusable sessions and provides guidance. Does NOT launch agents — you (coordinator) decide how to pass this to the team member. After launching, call dispatch_report to register the session.", {
+        project_name: z.string().describe('Project name'),
+        role: z.string().describe('Role ID to dispatch (e.g. architect, developer, tester)'),
+        task_brief: z
+            .string()
+            .describe('Task description for the team member — what they need to do, which tasks from the breakdown, specific instructions, etc.'),
+        node_id: z
+            .string()
+            .optional()
+            .describe('Target task node ID from the workflow tree. If omitted, automatically finds an active/pending task node for the specified role.'),
+        input_artifact_ids: z
+            .array(z.string())
+            .optional()
+            .describe('Supplementary artifact IDs to include as input references (name + path) for the team member. These are merged with the node-level inputArtifacts declaration. Note: only path references are provided, not content.'),
+    }, async ({ project_name, role, task_brief, node_id, input_artifact_ids }) => {
+        try {
+            const ctx = await resolveActive(project_name);
+            if (isError(ctx))
+                return ctx;
+            // Load project state and workflow plugin
+            const { wf, state } = await loadWorkflowForContext(workflowsDir, project_name, ctx);
+            // Validate role exists
+            const roleDef = wf.roles[role];
+            if (!roleDef) {
+                const available = Object.keys(wf.roles).join(', ');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Role "${role}" not found. Available: ${available}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            // Resolve target task node
+            let targetNode;
+            if (node_id) {
+                // Explicit node_id — validate it
+                targetNode = findTaskNode(wf, node_id);
+                if (!targetNode) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Node "${node_id}" not found or is not a task node in the workflow.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                if (targetNode.role !== role) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Node "${node_id}" is assigned to role "${targetNode.role}", not "${role}".`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Validate node state allows dispatch
+                const nodeState = state.nodes[node_id];
+                if (nodeState && nodeState.status !== 'active' && nodeState.status !== 'pending') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Node "${node_id}" is in status "${nodeState.status}" — cannot dispatch. Only active or pending nodes can be dispatched.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+            }
+            else {
+                // Auto-find: look for active/pending task nodes for this role
+                const candidates = findDispatchableNodes(wf, state, role);
+                if (candidates.length === 0) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `No active or pending task nodes found for role "${role}". Check project_status to see the current workflow state.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Prefer active over pending
+                targetNode = candidates.find((t) => state.nodes[t.id]?.status === 'active') ?? candidates[0];
+            }
+            const targetNodeId = targetNode.id;
+            // Build I/O context for artifact path resolution
+            const ioCtx = {
+                contextDir: ctx.dir,
+                projectDir: ctx.entry.dir,
+                contextLabel: ctx.activeContext,
+            };
+            // Get merged overrides
+            const overrides = await getMergedOverrides(project_name);
+            // Build the full prompt with overrides injected
+            const overrideSection = buildOverrideSection(role, overrides);
+            let fullPrompt = overrideSection ? `${roleDef.prompt}\n${overrideSection}` : roleDef.prompt;
+            // Execute beforeDispatch hooks (if defined on the target node)
+            const hookInjections = [];
+            if (targetNode.beforeDispatch) {
+                // Collect static inject text
+                if (targetNode.beforeDispatch.inject) {
+                    hookInjections.push(...targetNode.beforeDispatch.inject);
+                }
+                // Execute registered actions
+                if (targetNode.beforeDispatch.actions && wf.actions) {
+                    const nodeState = state.nodes[targetNodeId];
+                    // Resolve loopIteration: find ancestor loop node and read its current iteration
+                    let loopIteration;
+                    const ancestorLoopId = findAncestorLoopId(wf.definition.root, targetNodeId);
+                    if (ancestorLoopId) {
+                        const loopState = state.nodes[ancestorLoopId];
+                        if (loopState) {
+                            loopIteration = loopState.currentIteration;
+                        }
+                    }
+                    const actionCtx = {
+                        nodeId: targetNodeId,
+                        role,
+                        retryCount: nodeState?.retryCount ?? 0,
+                        projectName: project_name,
+                        pluginConfig: wf.config,
+                        workflowState: state,
+                        artifacts: {
+                            read: (artifactId) => readArtifact(artifactId, ioCtx, wf.artifactDefinitions[artifactId]),
+                            list: () => listArtifacts(ioCtx, wf.artifactDefinitions),
+                        },
+                        loopIteration,
+                    };
+                    for (const actionName of targetNode.beforeDispatch.actions) {
+                        const handler = wf.actions[actionName];
+                        if (handler) {
+                            try {
+                                const result = await handler(actionCtx);
+                                if (result.inject) {
+                                    hookInjections.push(...result.inject);
+                                }
+                            }
+                            catch (err) {
+                                console.warn(`[harmonia] beforeDispatch action "${actionName}" failed:`, err);
+                            }
+                        }
+                        else {
+                            console.warn(`[harmonia] beforeDispatch action "${actionName}" not registered`);
+                        }
+                    }
+                }
+            }
+            // Append hook injections to the role prompt
+            if (hookInjections.length > 0) {
+                fullPrompt += '\n\n' + hookInjections.join('\n\n');
+            }
+            // Resolve input artifact references (merge node declaration + coordinator parameter)
+            const nodeInputIds = targetNode.inputArtifacts ?? [];
+            const paramInputIds = input_artifact_ids ?? [];
+            const mergedInputIds = [...new Set([...nodeInputIds, ...paramInputIds])];
+            // List existing artifacts for reference resolution
+            const existingArtifacts = new Set(await listArtifacts(ioCtx, wf.artifactDefinitions));
+            // Resolve all input references
+            const inputRefs = mergedInputIds.map((id) => resolveInputReference(id, wf, ioCtx, existingArtifacts));
+            const foundRefs = inputRefs.filter((r) => r.found);
+            const missingRefs = inputRefs.filter((r) => !r.found);
+            // Resolve agent/model: override takes precedence over frontmatter
+            const roleConfig = resolveRoleConfig(role, overrides);
+            const modelDisplay = roleConfig.model ?? roleDef.frontmatter.model;
+            const agentDisplay = roleConfig.agent ?? roleDef.frontmatter.agent;
+            const sessionType = roleDef.frontmatter.session;
+            // Determine session strategy based on session type + parallel field
+            let idleSession = null;
+            let parallelForced = false;
+            if (sessionType === 'none') {
+                // session: none → never look for idle sessions
+                idleSession = null;
+            }
+            else if (roleDef.frontmatter.parallel) {
+                // parallel=true → check if same role has running dispatches
+                const hasRunning = await hasRunningDispatch(project_name, ctx.number, role, ctx.dir);
+                if (hasRunning) {
+                    // Force new session — don't look for idle ones
+                    parallelForced = true;
+                    idleSession = null;
+                }
+                else {
+                    // No running dispatch → follow normal session behavior
+                    idleSession = await findIdleSession(project_name, ctx.number, role, ctx.dir);
+                }
+            }
+            else {
+                // session: persistent or optional → look for idle sessions
+                idleSession = await findIdleSession(project_name, ctx.number, role, ctx.dir);
+            }
+            // Create dispatch record
+            const dispatch = await createDispatch(project_name, ctx.number, role, task_brief, [], // expectedOutputs — determined dynamically by workflow engine
+            idleSession?.id, ctx.dir, targetNodeId);
+            // Trigger engine event: dispatch_requested
+            const engineResult = await processWorkflowEvent(workflowsDir, project_name, ctx, {
+                type: 'dispatch_requested',
+                nodeId: targetNodeId,
+            });
+            const nextActionText = formatNextAction(engineResult.nextAction);
+            // Build session guidance (now includes model/agent info — replaces ## Configuration)
+            const sessionGuidance = buildSessionGuidance({
+                idleSession,
+                sessionType,
+                model: modelDisplay,
+                agent: agentDisplay,
+                parallelForced,
+            });
+            // Build artifact requirements for expected outputs
+            const artifactRequirements = await buildArtifactRequirements(wf, workflowsDir, state.workflow, role);
+            const summary = [
+                `# Dispatch: ${role}`,
+                ``,
+                `## Dispatch Tracking`,
+                `- Dispatch ID: \`${dispatch.id}\``,
+                `- Status: ${dispatch.status}`,
+                `- Target Node: ${targetNodeId}`,
+                ``,
+                `## Session Guidance`,
+                sessionGuidance,
+                ``,
+                `## Task Brief`,
+                task_brief,
+                ``,
+                `## Project Context`,
+                `- Project: ${project_name}`,
+                `- Directory: ${state.projectDir}`,
+                `- Workflow: ${state.workflow}`,
+            ];
+            // Inject unmanaged artifact output path hints
+            const unmanagedHints = [];
+            for (const cap of roleDef.frontmatter.capabilities ?? []) {
+                if (!cap.artifact)
+                    continue;
+                const def = wf.artifactDefinitions[cap.artifact];
+                if (!def?.unmanaged)
+                    continue;
+                const outputDir = resolveArtifactDir(def.output, ioCtx);
+                unmanagedHints.push(`- **${cap.artifact}** (${def.name}): \`${outputDir}\``);
+            }
+            if (unmanagedHints.length > 0) {
+                summary.push(``, `## Unmanaged Artifact Output Paths`, `以下 artifact 由 agent 直接输出（非 artifact_write），请将产出写入对应路径:`, ...unmanagedHints);
+            }
+            summary.push(``, `## Input References (${foundRefs.length}${missingRefs.length > 0 ? `, ${missingRefs.length} missing` : ''})`);
+            if (foundRefs.length > 0) {
+                for (const ref of foundRefs) {
+                    summary.push(`- **${ref.id}** (${ref.name}): \`${ref.path}\``);
+                }
+            }
+            if (missingRefs.length > 0) {
+                summary.push(``, `### Missing`);
+                for (const ref of missingRefs) {
+                    summary.push(`- **${ref.id}** (${ref.name}): 未找到`);
+                }
+            }
+            summary.push(``, `## Next Step`, `After launching the agent, call \`dispatch_report\` with dispatch_id="${dispatch.id}" and the agent's session ID.`, `When the agent finishes, call \`dispatch_report\` again with status="completed" (or "failed").`);
+            if (artifactRequirements) {
+                summary.push(``, artifactRequirements);
+            }
+            summary.push(``, `## Role Prompt`, ``, fullPrompt);
+            summary.push(nextActionText);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: summary.join('\n'),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `Error: ${err instanceof Error ? err.message : String(err)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=role-dispatch.js.map