@s_s/harmonia 1.2.0 → 1.4.0

package/build/cli/setup.js

@@ -1,8 +1,10 @@
 /**
  * CLI command: harmonia setup
  *
- * Prompt injection + hook installation only.
- * No project registration, no state init — PM does that at runtime via MCP tools.
+ * Prompt injection only.
+ * No project registration, no state init, no hook installation.
+ * Coordinator does project registration at runtime via MCP tools (project_init),
+ * which also handles hook installation.
  *
  * Usage:
  *   harmonia setup [options]
@@ -10,10 +12,13 @@
  * Options:
  *   --agent <type>       Agent type: opencode | claude-code | codex | openclaw (default: auto-detect)
  */
-import { resolve } from 'node:path';
+import { resolve, join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { cp, readdir, stat, mkdir } from 'node:fs/promises';
 import { detectHostAgent, injectPrompt } from '../setup/inject.js';
-import { installHooks } from '../hooks/install.js';
 import { getGlobalDir } from '../core/registry.js';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
 const VALID_AGENTS = ['opencode', 'claude-code', 'codex', 'openclaw'];
 /** Parse CLI flags from argv (starting after 'setup'). */
 export function parseSetupArgs(args) {
@@ -47,25 +52,46 @@ export async function runSetup(opts) {
     const result = await injectPrompt(agentType);
     const action = result.created ? 'Created' : result.replaced ? 'Updated' : 'Appended to';
     console.log(`  [done] ${action} ${result.filePath}`);
-    // 3. Install hooks
+    // 3. Copy built-in workflows to user data directory (skip existing)
+    const builtinWorkflowsRoot = resolve(__dirname, '..', '..', 'workflows');
+    const targetWorkflowsDir = join(getGlobalDir(), '.workflows');
     try {
-        const hookResult = await installHooks(agentType, {
-            dataDir: getGlobalDir(),
-        });
-        if (hookResult.success) {
-            console.log(`  [done] Hooks installed (${hookResult.filesWritten.length} files)`);
-            for (const w of hookResult.warnings) {
-                console.log(`  [warn] ${w}`);
-            }
+        const entries = await readdir(builtinWorkflowsRoot);
+        const workflowDirs = [];
+        for (const entry of entries) {
+            const entryPath = join(builtinWorkflowsRoot, entry);
+            const s = await stat(entryPath);
+            if (s.isDirectory())
+                workflowDirs.push(entry);
         }
-        else {
-            console.log(`  [fail] Hook install failed: ${hookResult.error ?? 'unknown'}`);
+        if (workflowDirs.length > 0) {
+            await mkdir(targetWorkflowsDir, { recursive: true });
+            let copied = 0;
+            let skipped = 0;
+            for (const dir of workflowDirs) {
+                const dest = join(targetWorkflowsDir, dir);
+                try {
+                    await stat(dest);
+                    // Already exists — skip
+                    skipped++;
+                }
+                catch {
+                    // Does not exist — copy
+                    await cp(join(builtinWorkflowsRoot, dir), dest, { recursive: true });
+                    copied++;
+                }
+            }
+            if (copied > 0)
+                console.log(`  [done] Copied ${copied} built-in workflow(s) to ${targetWorkflowsDir}`);
+            if (skipped > 0)
+                console.log(`  [skip] ${skipped} workflow(s) already exist in ${targetWorkflowsDir}`);
         }
     }
-    catch (err) {
-        console.log(`  [fail] Hook install error: ${err instanceof Error ? err.message : String(err)}`);
+    catch {
+        // Built-in workflows dir may not exist (e.g. development environment) — not fatal
+        console.log(`  [warn] Could not read built-in workflows from ${builtinWorkflowsRoot}`);
     }
     // 4. Summary
-    console.log(`\n  Ready. Run your agent and call project_status() to begin.\n`);
+    console.log(`\n  Ready. Run your agent and call project_init() to register a project.\n`);
 }
 //# sourceMappingURL=setup.js.map

package/build/cli/setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"setup.js","sourceRoot":"","sources":["../../src/cli/setup.ts"],"names":[],"mappings":"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"}

package/build/core/action-registry.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Action registry — manages node hook action registration and execution.
+ *
+ * Actions are registered by workflow plugins (via tools/index.js) and executed
+ * synchronously by the Core during tool call processing (in beforeDispatch
+ * and afterComplete hooks).
+ *
+ * Actions cannot require agent behavior — only data operations and external
+ * API calls. They execute within the MCP server context.
+ */
+import type { ActionHandler, ActionContext, ActionResult } from './types.js';
+export declare class ActionRegistry {
+    private actions;
+    /**
+     * Register an action handler.
+     * @throws If an action with the same name is already registered
+     */
+    register(name: string, handler: ActionHandler): void;
+    /**
+     * Execute a registered action.
+     * @throws If the action is not registered
+     */
+    execute(name: string, context: ActionContext): Promise<ActionResult>;
+    /**
+     * Check if an action is registered.
+     */
+    has(name: string): boolean;
+    /**
+     * List all registered action names.
+     */
+    list(): string[];
+    /**
+     * Remove all registered actions. Useful for testing or plugin reload.
+     */
+    clear(): void;
+}

package/build/core/action-registry.js

@@ -0,0 +1,53 @@
+/**
+ * Action registry — manages node hook action registration and execution.
+ *
+ * Actions are registered by workflow plugins (via tools/index.js) and executed
+ * synchronously by the Core during tool call processing (in beforeDispatch
+ * and afterComplete hooks).
+ *
+ * Actions cannot require agent behavior — only data operations and external
+ * API calls. They execute within the MCP server context.
+ */
+export class ActionRegistry {
+    actions = new Map();
+    /**
+     * Register an action handler.
+     * @throws If an action with the same name is already registered
+     */
+    register(name, handler) {
+        if (this.actions.has(name)) {
+            throw new Error(`Action "${name}" is already registered`);
+        }
+        this.actions.set(name, handler);
+    }
+    /**
+     * Execute a registered action.
+     * @throws If the action is not registered
+     */
+    async execute(name, context) {
+        const handler = this.actions.get(name);
+        if (!handler) {
+            throw new Error(`Action "${name}" is not registered. Available actions: ${this.list().join(', ') || 'none'}`);
+        }
+        return handler(context);
+    }
+    /**
+     * Check if an action is registered.
+     */
+    has(name) {
+        return this.actions.has(name);
+    }
+    /**
+     * List all registered action names.
+     */
+    list() {
+        return Array.from(this.actions.keys());
+    }
+    /**
+     * Remove all registered actions. Useful for testing or plugin reload.
+     */
+    clear() {
+        this.actions.clear();
+    }
+}
+//# sourceMappingURL=action-registry.js.map

package/build/core/action-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"action-registry.js","sourceRoot":"","sources":["../../src/core/action-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,OAAO,cAAc;IACf,OAAO,GAAG,IAAI,GAAG,EAAyB,CAAC;IAEnD;;;OAGG;IACH,QAAQ,CAAC,IAAY,EAAE,OAAsB;QACzC,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC;YACzB,MAAM,IAAI,KAAK,CAAC,WAAW,IAAI,yBAAyB,CAAC,CAAC;QAC9D,CAAC;QACD,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IACpC,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,OAAO,CAAC,IAAY,EAAE,OAAsB;QAC9C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACvC,IAAI,CAAC,OAAO,EAAE,CAAC;YACX,MAAM,IAAI,KAAK,CACX,WAAW,IAAI,2CAA2C,IAAI,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,MAAM,EAAE,CAC/F,CAAC;QACN,CAAC;QACD,OAAO,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IAED;;OAEG;IACH,GAAG,CAAC,IAAY;QACZ,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,IAAI;QACA,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC3C,CAAC;IAED;;OAEG;IACH,KAAK;QACD,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,CAAC;IACzB,CAAC;CACJ"}

package/build/core/artifacts.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Artifact management — read/write files to resolved output directories.
+ *
+ * All path resolution goes through `ArtifactIOContext`:
+ * - Default: `<contextDir>/artifacts/`
+ * - Custom: resolved via `ArtifactDefinition.output` template
+ *
+ * Supports .md, .html, and .json files based on artifact format configuration.
+ * Also supports step artifact files for sequential mode (e.g. prd.requirements.json).
+ */
+import type { ArtifactDefinition } from './types.js';
+/** Context needed for artifact I/O path resolution */
+export interface ArtifactIOContext {
+    /** Absolute path to the context directory (iter-N/ or patch-N/) */
+    contextDir: string;
+    /** Absolute path to the project source directory */
+    projectDir: string;
+    /** Context label string, e.g. "iter-1" or "patch-2" */
+    contextLabel: string;
+}
+/**
+ * Resolve the output directory for an artifact based on its `output` template.
+ *
+ * Placeholder resolution:
+ * - `{global}` → `<contextDir>/artifacts/`
+ * - `{project}` → `<projectDir>/`
+ * - `{context}` → contextLabel (e.g. "iter-1")
+ *
+ * When `output` is undefined, returns `<contextDir>/artifacts/` (default behavior).
+ */
+export declare function resolveArtifactDir(output: string | undefined, ioCtx: ArtifactIOContext): string;
+/**
+ * Write an artifact to the resolved output directory.
+ */
+export declare function writeArtifact(artifactId: string, content: string, ioCtx: ArtifactIOContext, artifactDef?: ArtifactDefinition): Promise<string>;
+/**
+ * Read an artifact from the resolved output directory.
+ *
+ * When `artifactDef` is provided with a known format, tries that extension first
+ * before falling back to probing all extensions.
+ */
+export declare function readArtifact(artifactId: string, ioCtx: ArtifactIOContext, artifactDef?: ArtifactDefinition): Promise<string>;
+/**
+ * List artifacts that exist on disk.
+ *
+ * Groups definitions by their resolved output directory and does one `readdir`
+ * per unique directory, then matches artifact IDs in memory.
+ *
+ * When `artifactDefinitions` is empty, falls back to scanning
+ * `<ioCtx.contextDir>/artifacts/`.
+ */
+export declare function listArtifacts(ioCtx: ArtifactIOContext, artifactDefinitions: Record<string, ArtifactDefinition>): Promise<string[]>;
+/**
+ * Write a step artifact to the resolved output directory.
+ *
+ * Step artifacts follow the main artifact's `output` configuration.
+ *
+ * @param format - "json" or "md" (determines file extension)
+ * @returns The file path written
+ */
+export declare function writeStepArtifact(artifactId: string, stepId: string, content: string, format: 'json' | 'md', ioCtx: ArtifactIOContext, artifactDef?: ArtifactDefinition): Promise<string>;
+/**
+ * Read a step artifact from the resolved output directory.
+ * Tries .json first, then .md.
+ */
+export declare function readStepArtifact(artifactId: string, stepId: string, ioCtx: ArtifactIOContext, artifactDef?: ArtifactDefinition): Promise<string>;

package/build/core/artifacts.js

@@ -0,0 +1,178 @@
+/**
+ * Artifact management — read/write files to resolved output directories.
+ *
+ * All path resolution goes through `ArtifactIOContext`:
+ * - Default: `<contextDir>/artifacts/`
+ * - Custom: resolved via `ArtifactDefinition.output` template
+ *
+ * Supports .md, .html, and .json files based on artifact format configuration.
+ * Also supports step artifact files for sequential mode (e.g. prd.requirements.json).
+ */
+import { mkdir, readFile, writeFile, readdir } from 'node:fs/promises';
+import { join } from 'node:path';
+function artifactsDir(contextDir) {
+    return join(contextDir, 'artifacts');
+}
+/**
+ * Resolve the output directory for an artifact based on its `output` template.
+ *
+ * Placeholder resolution:
+ * - `{global}` → `<contextDir>/artifacts/`
+ * - `{project}` → `<projectDir>/`
+ * - `{context}` → contextLabel (e.g. "iter-1")
+ *
+ * When `output` is undefined, returns `<contextDir>/artifacts/` (default behavior).
+ */
+export function resolveArtifactDir(output, ioCtx) {
+    if (!output) {
+        return artifactsDir(ioCtx.contextDir);
+    }
+    const resolved = output
+        .replace(/\{global\}/g, artifactsDir(ioCtx.contextDir))
+        .replace(/\{project\}/g, ioCtx.projectDir)
+        .replace(/\{context\}/g, ioCtx.contextLabel);
+    return resolved;
+}
+/**
+ * Get file extension for an artifact based on its definition.
+ */
+function getArtifactExtension(artifactDef) {
+    switch (artifactDef?.format) {
+        case 'html':
+            return '.html';
+        case 'json':
+            return '.json';
+        default:
+            return '.md';
+    }
+}
+/**
+ * Write an artifact to the resolved output directory.
+ */
+export async function writeArtifact(artifactId, content, ioCtx, artifactDef) {
+    const dir = resolveArtifactDir(artifactDef?.output, ioCtx);
+    await mkdir(dir, { recursive: true });
+    const ext = getArtifactExtension(artifactDef);
+    const filePath = join(dir, `${artifactId}${ext}`);
+    await writeFile(filePath, content, 'utf-8');
+    return filePath;
+}
+/**
+ * Read an artifact from the resolved output directory.
+ *
+ * When `artifactDef` is provided with a known format, tries that extension first
+ * before falling back to probing all extensions.
+ */
+export async function readArtifact(artifactId, ioCtx, artifactDef) {
+    const dir = resolveArtifactDir(artifactDef?.output, ioCtx);
+    // If we know the format, try it first for a fast path
+    if (artifactDef?.format) {
+        const knownExt = getArtifactExtension(artifactDef);
+        try {
+            return await readFile(join(dir, `${artifactId}${knownExt}`), 'utf-8');
+        }
+        catch {
+            // fall through to probe all extensions
+        }
+    }
+    for (const ext of ['.md', '.html', '.json']) {
+        try {
+            return await readFile(join(dir, `${artifactId}${ext}`), 'utf-8');
+        }
+        catch {
+            // try next extension
+        }
+    }
+    throw new Error(`Artifact "${artifactId}" not found`);
+}
+/**
+ * List artifacts that exist on disk.
+ *
+ * Groups definitions by their resolved output directory and does one `readdir`
+ * per unique directory, then matches artifact IDs in memory.
+ *
+ * When `artifactDefinitions` is empty, falls back to scanning
+ * `<ioCtx.contextDir>/artifacts/`.
+ */
+export async function listArtifacts(ioCtx, artifactDefinitions) {
+    // Definition-based grouping
+    if (Object.keys(artifactDefinitions).length > 0) {
+        // Group artifact IDs by resolved directory
+        const dirToIds = new Map();
+        for (const [id, def] of Object.entries(artifactDefinitions)) {
+            const dir = resolveArtifactDir(def.output, ioCtx);
+            const existing = dirToIds.get(dir);
+            if (existing) {
+                existing.push(id);
+            }
+            else {
+                dirToIds.set(dir, [id]);
+            }
+        }
+        const found = [];
+        for (const [dir, ids] of dirToIds) {
+            let files;
+            try {
+                files = await readdir(dir);
+            }
+            catch {
+                continue; // directory doesn't exist yet
+            }
+            // Strip extensions from filenames for matching
+            const fileBaseNames = new Set(files
+                .filter((f) => f.endsWith('.md') || f.endsWith('.html') || f.endsWith('.json'))
+                .map((f) => f.replace(/\.(md|html|json)$/, '')));
+            for (const id of ids) {
+                if (fileBaseNames.has(id)) {
+                    found.push(id);
+                }
+            }
+        }
+        return found;
+    }
+    // Fallback: scan default artifacts directory
+    const dir = artifactsDir(ioCtx.contextDir);
+    try {
+        const files = await readdir(dir);
+        return files
+            .filter((f) => f.endsWith('.md') || f.endsWith('.html') || f.endsWith('.json'))
+            .map((f) => f.replace(/\.(md|html|json)$/, ''));
+    }
+    catch {
+        return [];
+    }
+}
+// ─── Step Artifact I/O ───
+/**
+ * Write a step artifact to the resolved output directory.
+ *
+ * Step artifacts follow the main artifact's `output` configuration.
+ *
+ * @param format - "json" or "md" (determines file extension)
+ * @returns The file path written
+ */
+export async function writeStepArtifact(artifactId, stepId, content, format, ioCtx, artifactDef) {
+    const dir = resolveArtifactDir(artifactDef?.output, ioCtx);
+    await mkdir(dir, { recursive: true });
+    const ext = format === 'json' ? '.json' : '.md';
+    const filePath = join(dir, `${artifactId}.${stepId}${ext}`);
+    await writeFile(filePath, content, 'utf-8');
+    return filePath;
+}
+/**
+ * Read a step artifact from the resolved output directory.
+ * Tries .json first, then .md.
+ */
+export async function readStepArtifact(artifactId, stepId, ioCtx, artifactDef) {
+    const dir = resolveArtifactDir(artifactDef?.output, ioCtx);
+    for (const ext of ['.json', '.md']) {
+        try {
+            return await readFile(join(dir, `${artifactId}.${stepId}${ext}`), 'utf-8');
+        }
+        catch {
+            // try next extension
+        }
+    }
+    throw new Error(`Step artifact "${artifactId}.${stepId}" not found`);
+}
+//# sourceMappingURL=artifacts.js.map

package/build/core/artifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"artifacts.js","sourceRoot":"","sources":["../../src/core/artifacts.ts"],"names":[],"mappings":"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"}

package/build/core/dispatch.d.ts

@@ -1,41 +1,43 @@
 /**
  * Dispatch & Session tracking — manages:
- *   <data_dir>/<project_name>/iter-<n>/sessions.json
- *   <data_dir>/<project_name>/iter-<n>/dispatches.json
+ *   <context_dir>/sessions.json
+ *   <context_dir>/dispatches.json
+ *
+ * context_dir is typically iter-<n>/ or patch-<n>/ under the project data dir.
  *
  * Sessions represent agent instances (can be reused across dispatches).
  * Dispatches represent individual task assignments to a role.
  * Relationship: Session 1:N Dispatch (a persistent session can receive multiple dispatches).
  */
 import type { AgentType, SessionRecord, SessionStatus, DispatchRecord, DispatchStatus } from './types.js';
-export declare function readSessions(projectName: string, iteration: number): Promise<SessionRecord[]>;
-export declare function createSession(projectName: string, iteration: number, role: string, agentType?: AgentType, label?: string): Promise<SessionRecord>;
+export declare function readSessions(projectName: string, iteration: number, contextDir?: string): Promise<SessionRecord[]>;
+export declare function createSession(projectName: string, iteration: number, role: string, agentType?: AgentType, label?: string, contextDir?: string): Promise<SessionRecord>;
 export declare function updateSession(projectName: string, iteration: number, sessionId: string, updates: {
     status?: SessionStatus;
     agentSessionId?: string;
     agentType?: AgentType;
     label?: string;
-}): Promise<SessionRecord>;
+}, contextDir?: string): Promise<SessionRecord>;
 /**
  * Find an idle session for a given role (for session reuse).
  * Returns the most recently active idle session, or null if none found.
  */
-export declare function findIdleSession(projectName: string, iteration: number, role: string): Promise<SessionRecord | null>;
+export declare function findIdleSession(projectName: string, iteration: number, role: string, contextDir?: string): Promise<SessionRecord | null>;
 /**
  * Find a session by its agent session ID (for correlating external sessions).
  */
-export declare function findSessionByAgentId(projectName: string, iteration: number, role: string, agentSessionId: string): Promise<SessionRecord | null>;
-export declare function readDispatches(projectName: string, iteration: number): Promise<DispatchRecord[]>;
-export declare function createDispatch(projectName: string, iteration: number, role: string, taskBrief: string, expectedOutputs: string[], sessionId?: string): Promise<DispatchRecord>;
+export declare function findSessionByAgentId(projectName: string, iteration: number, role: string, agentSessionId: string, contextDir?: string): Promise<SessionRecord | null>;
+export declare function readDispatches(projectName: string, iteration: number, contextDir?: string): Promise<DispatchRecord[]>;
+export declare function createDispatch(projectName: string, iteration: number, role: string, taskBrief: string, expectedOutputs: string[], sessionId?: string, contextDir?: string, nodeId?: string): Promise<DispatchRecord>;
 export declare function updateDispatch(projectName: string, iteration: number, dispatchId: string, updates: {
     status?: DispatchStatus;
     sessionId?: string;
     note?: string;
-}): Promise<DispatchRecord>;
+}, contextDir?: string): Promise<DispatchRecord>;
 /**
  * Get a single dispatch record by ID.
  */
-export declare function getDispatch(projectName: string, iteration: number, dispatchId: string): Promise<DispatchRecord | null>;
+export declare function getDispatch(projectName: string, iteration: number, dispatchId: string, contextDir?: string): Promise<DispatchRecord | null>;
 /** Valid state transitions for dispatch status. */
 export declare const DISPATCH_TRANSITIONS: Record<DispatchStatus, DispatchStatus[]>;
 /**
@@ -46,3 +48,8 @@ export declare function isValidTransition(from: DispatchStatus, to: DispatchStat
  * Check if a dispatch status is terminal (no further transitions allowed).
  */
 export declare function isTerminalStatus(status: DispatchStatus): boolean;
+/**
+ * Check if a role has any running dispatches (status: 'dispatched' or 'running').
+ * Used by parallel dispatch logic to decide whether to force a new session.
+ */
+export declare function hasRunningDispatch(projectName: string, iteration: number, role: string, contextDir?: string): Promise<boolean>;