@s_s/harmonia 1.3.0 → 1.4.0

package/build/core/types.d.ts

@@ -1,109 +1,225 @@
 /**
  * Core type definitions for Harmonia.
- * These types are workflow-agnostic — no hardcoded role names or phase names.
+ *
+ * Architecture: Core provides composable collaboration primitives.
+ * Workflow plugins use these primitives to define specific processes.
+ *
+ * This file defines:
+ * - Workflow node types (task, sequence, parallel, gate, loop)
+ * - Workflow state (node-based, not phase-based)
+ * - Engine types (nextAction, events, gate evaluation)
+ * - Artifact system
+ * - Plugin interface
+ * - Session & Dispatch tracking
+ * - Override configuration (simplified to 2-layer)
+ * - Sequential step tracking
+ * - Issue tracking
+ * - Review state
  */
-export interface PhaseDefinition {
+/** Agent type for spawning team member agents (re-exported from @s_s/agent-kit) */
+import type { AgentType } from '@s_s/agent-kit';
+export type { AgentType };
+export type NodeType = 'task' | 'sequence' | 'parallel' | 'gate' | 'loop';
+/** Hook configuration for beforeDispatch / afterComplete */
+export interface NodeHook {
+    /** Extra prompt text to inject */
+    inject?: string[];
+    /** Registered action names to execute synchronously */
+    actions?: string[];
+}
+/** Failure handler for task and parallel nodes */
+export interface FailureHandler {
+    /** Target node ID to jump back to (must satisfy ancestor-chain constraint) */
+    goto: string;
+    /** Max retry count; omit for unlimited */
+    maxRetries?: number;
+    /** Floating node ID to jump to when retries exhausted */
+    onExhausted?: string;
+}
+/** Goto target for gate fail paths */
+export interface GotoTarget {
+    /** Target node ID to jump back to */
+    goto: string;
+    /** Max retry count; omit for unlimited */
+    maxRetries?: number;
+    /** Floating node ID to jump to when retries exhausted */
+    onExhausted?: string;
+}
+/** Task node — work unit assigned to a role */
+export interface TaskNode {
+    type: 'task';
+    id: string;
+    /** Role ID that executes this task */
+    role: string;
+    /** Artifact IDs this task needs as input (resolved to name + path references at dispatch time) */
+    inputArtifacts?: string[];
+    /** Optional timeout in seconds */
+    timeout?: number;
+    /** Optional failure handler */
+    onFailed?: FailureHandler;
+    /** Hook before dispatching to role */
+    beforeDispatch?: NodeHook;
+    /** Hook after task completion */
+    afterComplete?: NodeHook;
+}
+/** Sequence node — children execute in order */
+export interface SequenceNode {
+    type: 'sequence';
+    id: string;
+    children: WorkflowNode[];
+}
+/** Parallel node — children execute simultaneously */
+export interface ParallelNode {
+    type: 'parallel';
+    id: string;
+    /** Required: how to handle child failures */
+    failStrategy: 'fail-fast' | 'wait-all';
+    children: WorkflowNode[];
+    /** Optional failure handler */
+    onFailed?: FailureHandler;
+}
+/** Gate condition types */
+export interface ArtifactExistsCondition {
+    type: 'artifact_exists';
+    /** Artifact ID to check */
+    artifact: string;
+}
+export interface ArtifactApprovedCondition {
+    type: 'artifact_approved';
+    /** Artifact ID to check */
+    artifact: string;
+}
+export type ArtifactFieldOperator = 'eq' | 'neq' | 'gt' | 'lt' | 'gte' | 'lte' | 'contains' | 'in';
+export interface ArtifactFieldCondition {
+    type: 'artifact_field';
+    /** Artifact ID to check */
+    artifact: string;
+    /** Field path within the artifact */
+    field: string;
+    /** Comparison operator */
+    operator: ArtifactFieldOperator;
+    /** Expected value */
+    value: unknown;
+}
+export type GateCondition = ArtifactExistsCondition | ArtifactApprovedCondition | ArtifactFieldCondition;
+/** Gate node — condition check with pass/fail paths */
+export interface GateNode {
+    type: 'gate';
     id: string;
+    /** All conditions must be met for pass */
+    conditions: GateCondition[];
+    /** Path when all conditions pass (inline node) */
+    pass: WorkflowNode;
+    /** Path when conditions fail — inline node or goto */
+    fail: WorkflowNode | GotoTarget;
+}
+/** Loop node — repeated execution of a sub-workflow with iteration state */
+export interface LoopNode {
+    type: 'loop';
+    id: string;
+    /** Maximum iterations (safety cap) */
+    maxIterations: number;
+    /** The sub-workflow to repeat each iteration */
+    body: WorkflowNode;
+    /** Optional failure handler */
+    onFailed?: FailureHandler;
+}
+/** Union of all workflow node types */
+export type WorkflowNode = TaskNode | SequenceNode | ParallelNode | GateNode | LoopNode;
+/** Complete workflow definition loaded from workflow.json */
+export interface WorkflowDefinition {
     name: string;
-    roles: string[];
-    inputs?: string[];
-    outputs: string[];
     description: string;
+    version?: string;
+    /** Author of this workflow */
+    author?: string;
+    /** Coordinator role ID — every workflow must have one */
+    coordinator: string;
+    /** Root node of the workflow tree */
+    root: WorkflowNode;
+    /** Standalone nodes referenced by onExhausted/onFailed */
+    floatingNodes?: TaskNode[];
 }
-export type DocScale = 'full' | 'lite' | 'skip' | 'optional';
-/** Step definition within a doc (for sequential mode) */
-export interface DocStepDefinition {
+/** Step definition within an artifact (for sequential mode) */
+export interface ArtifactStepDefinition {
     /** Step ID, e.g. "requirements", "draft", "final" */
     id: string;
     /** Human-readable name */
     name: string;
-    /** Output format for this step's artifact */
+    /** Output format for this step */
     format: 'json' | 'md';
     /** Description shown to agent */
     description: string;
 }
-export interface DocDefinition {
+/** Artifact definition — metadata for an artifact type */
+export interface ArtifactDefinition {
+    /** Human-readable name */
     name: string;
-    scale: Record<ProjectScale, DocScale>;
-    /** File format: "md" (default) or "html" */
-    format?: 'md' | 'html';
-    /** Whether this doc requires user review/approval after creation */
+    /** File format: "md" (default), "html", or "json" */
+    format?: 'md' | 'html' | 'json';
+    /** Whether this artifact requires user review/approval */
     review?: boolean;
-    /** External output — not managed by write_doc (e.g. code written directly to project dir) */
-    external?: boolean;
-    /** Sequential steps — when defined and scale >= medium, write_doc requires step parameter */
-    steps?: DocStepDefinition[];
-}
-export interface ScaleDimension {
-    small: string | number | boolean;
-    medium: string | number | boolean;
-    large: string | number | boolean;
-}
-export interface WorkflowDefinition {
-    name: string;
-    description: string;
-    version?: string;
-    author?: string;
-    phases: PhaseDefinition[];
-    docs: Record<string, DocDefinition>;
-    scale_criteria: {
-        description: string;
-        dimensions: Record<string, ScaleDimension>;
-    };
+    /** Unmanaged output — not managed by artifact_write (e.g. code written directly by agent) */
+    unmanaged?: boolean;
+    /**
+     * Output directory template using placeholders:
+     * - `{global}` → `<data_dir>/<project>/iter-N/artifacts/`
+     * - `{project}` → `<projectDir>/`
+     * - `{context}` → `iter-N` or `patch-N` (must follow `{global}` or `{project}`)
+     *
+     * When undefined, defaults to `{global}` behavior.
+     * File name is always `<artifactId>.<ext>` — output only controls the directory.
+     */
+    output?: string;
+    /** Sequential steps — when defined, artifact_write requires step parameter */
+    steps?: ArtifactStepDefinition[];
 }
-/**
- * A required section (heading) in a markdown document.
- * Validation checks that the document contains a heading matching the primary
- * pattern or one of the aliases.
- */
-export interface DocSchemaSection {
+/** A required section (heading) in a markdown artifact */
+export interface ArtifactSchemaSection {
     /** Primary heading text, e.g. "## 项目概述" */
     heading: string;
-    /** Per-scale requirement: true = required, false = optional */
-    required: Record<ProjectScale, boolean>;
+    /** Whether this section is required */
+    required: boolean;
     /** Alternative heading texts that satisfy this requirement */
     aliases?: string[];
 }
-/**
- * Schema definition for a document type.
- * Used by write_doc to validate content structure before writing.
- */
-export interface DocSchema {
-    /** Required sections for markdown documents */
-    sections?: DocSchemaSection[];
-    /** Required HTML tags for html-format documents (e.g. ["html", "body", "nav"]) */
-    htmlTags?: string[];
-    /** Required top-level JSON fields (for JSON step artifacts) */
-    jsonFields?: DocSchemaJsonField[];
-    /** Minimum content length in characters (optional) */
-    minLength?: number;
-}
-/**
- * A required top-level field in a JSON document.
- * Used for validating structured step artifacts.
- */
-export interface DocSchemaJsonField {
+/** A required top-level field in a JSON artifact */
+export interface ArtifactSchemaJsonField {
     /** Field name (top-level key in JSON) */
     field: string;
-    /** Per-scale requirement: true = required, false = optional */
-    required: Record<ProjectScale, boolean>;
+    /** Whether this field is required */
+    required: boolean;
     /** Expected type: "string", "array", "object", "number", "boolean" */
     type?: string;
     /** If type is "array", minimum number of items */
     minItems?: number;
 }
+/** Schema definition for an artifact type */
+export interface ArtifactSchema {
+    /** Required sections for markdown artifacts */
+    sections?: ArtifactSchemaSection[];
+    /** Required HTML tags for html-format artifacts */
+    htmlTags?: string[];
+    /** Required top-level JSON fields */
+    jsonFields?: ArtifactSchemaJsonField[];
+    /** Minimum content length in characters */
+    minLength?: number;
+    /** Human-readable guidance for agents */
+    guidance?: string;
+}
 export interface RoleCapability {
     /** Unique ID for this capability */
     id: string;
-    /** Human-readable description of what this capability does */
+    /** Human-readable description */
     description: string;
-    /** Associated doc ID — if set, this capability produces this document */
-    doc?: string;
+    /** Associated artifact ID — if set, this capability produces this artifact */
+    artifact?: string;
 }
 export interface RoleFrontmatter {
-    model: string;
+    model?: string;
     session: 'none' | 'persistent' | 'optional';
     parallel: boolean;
+    agent?: string;
     /** Capabilities this role provides (used by override system) */
     capabilities?: RoleCapability[];
 }
@@ -112,45 +228,200 @@ export interface RoleDefinition {
     frontmatter: RoleFrontmatter;
     prompt: string;
 }
-export interface LoadedWorkflow {
-    definition: WorkflowDefinition;
-    roles: Record<string, RoleDefinition>;
-}
-export type PhaseStatus = 'pending' | 'in_progress' | 'completed' | 'blocked' | 'review' | 'skipped';
-export type ProjectScale = 'small' | 'medium' | 'large';
+export type NodeStatus = 'pending' | 'active' | 'completed' | 'failed' | 'cancelled' | 'skipped';
 export type ContextType = 'iteration' | 'patch';
-export interface PhaseState {
+/** Runtime state of a single node */
+export interface NodeState {
+    /** Node ID (matches definition) */
     id: string;
-    status: PhaseStatus;
+    /** Current status */
+    status: NodeStatus;
+    /** Number of times this node has been retried (0 = first execution) */
+    retryCount: number;
+    /** When this node became active */
     startedAt?: string;
+    /** When this node completed (or failed) */
     completedAt?: string;
-    blockedReason?: string;
+    /** Error message if failed */
+    error?: string;
+}
+/** Runtime state for loop nodes (extends NodeState) */
+export interface LoopNodeState extends NodeState {
+    /** Current iteration index (0-based) */
+    currentIteration: number;
+    /** Whether loop_done has been called — loop will terminate after current iteration completes */
+    done: boolean;
 }
-export interface ProjectState {
+/** Complete workflow state (persisted in state.json) */
+export interface WorkflowState {
     /** Project name (unique identifier) */
     projectName: string;
     /** Absolute path to the project source directory */
     projectDir: string;
-    /** Workflow name, e.g. "dev" */
+    /** Workflow plugin name, e.g. "dev" */
     workflow: string;
-    /** Context type: "iteration" for full iterations, "patch" for lightweight patches */
+    /** Context type: iteration or patch */
     type: ContextType;
-    /** Iteration or patch number this state belongs to */
+    /** Iteration or patch number */
     iteration: number;
-    /** Project scale determined by PM (null until set via project_set_scale) */
-    scale: ProjectScale | null;
-    /** Current phase id */
-    currentPhase: string;
-    /** State of each phase */
-    phases: PhaseState[];
-    /** Timestamp of project initialization */
+    /** Currently active node ID (null when workflow is completed or not started) */
+    activeNodeId: string | null;
+    /** State of every node, keyed by node ID */
+    nodes: Record<string, NodeState>;
+    /** Timestamp of state initialization */
     createdAt: string;
     /** Last updated timestamp */
     updatedAt: string;
+    /** Optional metadata (e.g. patch description, linked issue) */
+    meta?: Record<string, unknown>;
+}
+/** Per-condition evaluation detail */
+export interface GateConditionResult {
+    /** The condition that was evaluated */
+    condition: GateCondition;
+    /** Whether the condition was met */
+    met: boolean;
+    /** Actual value found (for artifact_field conditions) */
+    actualValue?: unknown;
+}
+/** Gate evaluation result */
+export interface GateEvaluationResult {
+    /** Whether all conditions passed */
+    passed: boolean;
+    /** Per-condition evaluation details */
+    conditions: GateConditionResult[];
+}
+/** nextAction type — tells the coordinator what to do next */
+export type NextActionType = 'dispatch' | 'write_artifact' | 'approve_artifact' | 'wait' | 'completed' | 'failed' | 'evaluate_gate' | 'none';
+/** Unified nextAction return structure */
+export interface NextAction {
+    /** What the coordinator should do */
+    type: NextActionType;
+    /** Target node ID (if applicable) */
+    nodeId?: string;
+    /** Role to dispatch (if type is 'dispatch') */
+    role?: string;
+    /** Human-readable instructions for the coordinator */
+    instructions: string;
+    /** Fully assembled prompt for the team member (if dispatching) */
+    rolePrompt?: string;
+    /** Gate evaluation results (if coming from a gate fail/goto) */
+    gateResults?: GateEvaluationResult;
+    /** Parallel dispatch targets (when dispatching multiple tasks simultaneously) */
+    parallelDispatch?: Array<{
+        nodeId: string;
+        role: string;
+    }>;
+}
+/** Events that trigger engine state transitions */
+export type WorkflowEvent = {
+    type: 'node_completed';
+    nodeId: string;
+    result?: unknown;
+} | {
+    type: 'node_failed';
+    nodeId: string;
+    error: string;
+} | {
+    type: 'artifact_written';
+    artifactId: string;
+} | {
+    type: 'artifact_approved';
+    artifactId: string;
+} | {
+    type: 'dispatch_requested';
+    nodeId: string;
+} | {
+    type: 'query_status';
+} | {
+    type: 'loop_done';
+    nodeId: string;
+};
+/** Context passed to action handlers */
+export interface ActionContext {
+    /** Current node ID */
+    nodeId: string;
+    /** Current node's role */
+    role: string;
+    /** Current retry count (0 = first execution) */
+    retryCount: number;
+    /** Project name */
+    projectName: string;
+    /** Plugin-specific configuration (opaque to Core) */
+    pluginConfig: unknown;
+    /** Gate evaluation results (if arriving via goto from gate fail) */
+    gateResults?: GateEvaluationResult;
+    /** Current workflow state snapshot */
+    workflowState: WorkflowState;
+    /** Artifact access API */
+    artifacts: {
+        read: (artifactId: string) => Promise<string>;
+        list: () => Promise<string[]>;
+    };
+    /** Task completion result (only in afterComplete) */
+    taskResult?: unknown;
+    /** Current loop iteration index (0-based), only set when task is inside a loop */
+    loopIteration?: number;
+}
+/** Return value from action handlers */
+export interface ActionResult {
+    /** Dynamic prompt text to inject */
+    inject?: string[];
+    /** Additional data to pass downstream */
+    data?: unknown;
+}
+/** Action handler function signature */
+export type ActionHandler = (context: ActionContext) => Promise<ActionResult>;
+/** Hook creator function signature */
+export type HookCreator = (agentType: AgentType, context: HookCreatorContext) => unknown;
+/** Context passed to plugin's createHooks function */
+export interface HookCreatorContext {
+    /** defineHooks function from agent-kit */
+    defineHooks: unknown;
+    /** Harmonia data directory */
+    dataDir: string;
+    /** Project name */
+    projectName: string;
+}
+/** Complete loaded workflow plugin */
+export interface WorkflowPlugin {
+    /** Plugin name (matches workflow name) */
+    name: string;
+    /** Workflow tree definition */
+    definition: WorkflowDefinition;
+    /** Role definitions keyed by role ID */
+    roles: Record<string, RoleDefinition>;
+    /** Artifact schemas keyed by artifact ID */
+    artifactSchemas: Record<string, ArtifactSchema>;
+    /** Artifact definitions keyed by artifact ID */
+    artifactDefinitions: Record<string, ArtifactDefinition>;
+    /** Registered actions (from tools/index.js) */
+    actions?: Record<string, ActionHandler>;
+    /** Hook creator (from hooks/index.js) */
+    hooks?: HookCreator;
+    /** Plugin-specific configuration (from config.json) */
+    config?: unknown;
+    /** Filesystem path to the plugin directory */
+    pluginDir: string;
+}
+/** Plugin entry in config.json */
+export interface PluginEntry {
+    /** Workflow name */
+    name?: string;
+    /** Filesystem path to the plugin directory */
+    path: string;
+    /** Plugin-specific configuration */
+    config?: unknown;
+}
+/** Global config.json structure */
+export interface GlobalConfig {
+    /** Registered workflow plugins */
+    workflows: Record<string, PluginEntry>;
 }
 export type ReviewStatus = 'pending' | 'approved' | 'rejected';
-export interface DocReviewState {
-    docId: string;
+export interface ReviewState {
+    /** Artifact ID */
+    artifactId: string;
     status: ReviewStatus;
     submittedAt: string;
     reviewedAt?: string;
@@ -162,13 +433,13 @@ export interface SessionRecord {
     id: string;
     /** Role this session belongs to */
     role: string;
-    /** Actual session ID from the host agent (e.g. OpenCode session ID) */
+    /** Actual session ID from the host agent */
     agentSessionId?: string;
     /** Agent type used for this session */
     agentType?: AgentType;
     /** Current session status */
     status: SessionStatus;
-    /** PM-defined label, e.g. "dev-auth-module" */
+    /** Coordinator-defined label */
     label?: string;
     /** When this session was created */
     createdAt: string;
@@ -187,7 +458,9 @@ export interface DispatchRecord {
     taskBrief: string;
     /** Current dispatch status */
     status: DispatchStatus;
-    /** Expected output doc IDs from this dispatch */
+    /** Node ID this dispatch is for */
+    nodeId?: string;
+    /** Expected output artifact IDs from this dispatch */
     expectedOutputs: string[];
     /** When this dispatch was created */
     createdAt: string;
@@ -206,43 +479,32 @@ export interface CapabilityOverride {
     tool: string;
     /** MCP server name (required when type is "mcp") */
     server?: string;
-    /** Static parameters to always pass when calling the tool */
+    /** Static parameters to always pass */
     params?: Record<string, unknown>;
-    /** Additional notes for prompt generation (rarely needed) */
+    /** Additional notes for prompt generation */
     notes?: string;
 }
-/** Agent type for spawning team member agents (re-exported from @s_s/agent-kit) */
-import type { AgentType } from '@s_s/agent-kit';
-export type { AgentType };
 /** Per-role override configuration */
 export interface RoleOverride {
     /** Agent type to use for this role */
     agent?: AgentType;
-    /** Model to use for this role (overrides the role's default model level) */
+    /** Model to use (overrides role's default) */
     model?: string;
-    /** Capability overrides for this role */
+    /** Capability overrides */
     capabilities?: Record<string, CapabilityOverride>;
 }
 /**
- * Override configuration file structure (<data_dir>/overrides.json or project-level).
- *
- * review: boolean | Record<docId, boolean>
- *   - boolean: global toggle for all docs
- *   - Record: per-doc toggle
- *
- * roles: Record<roleId, RoleOverride>
- *   - agent: agent type for spawning
- *   - model: model override
- *   - capabilities: Record<capabilityId, CapabilityOverride>
+ * Override configuration (project-level only, no global layer).
+ * Merges: project-level > workflow defaults.
  */
 export interface OverrideConfig {
-    /** Review overrides — global toggle or per-doc */
+    /** Review overrides — global toggle or per-artifact */
     review?: boolean | Record<string, boolean>;
     /** Role overrides (agent, model, capabilities) */
     roles?: Record<string, RoleOverride>;
 }
 /** Step completion record */
-export interface DocStepRecord {
+export interface ArtifactStepRecord {
     /** Step ID */
     stepId: string;
     /** When this step was completed */
@@ -250,13 +512,13 @@ export interface DocStepRecord {
     /** File path of the step artifact (relative to project data dir) */
     artifactPath: string;
 }
-/** Per-doc step tracking state */
-export interface DocStepState {
-    /** Doc ID */
-    docId: string;
+/** Per-artifact step tracking state */
+export interface ArtifactStepState {
+    /** Artifact ID */
+    artifactId: string;
     /** Completed steps (in order) */
-    completedSteps: DocStepRecord[];
-    /** Whether the final doc has been written (last step completed + merged) */
+    completedSteps: ArtifactStepRecord[];
+    /** Whether the final artifact has been written */
     finalized: boolean;
     /** Finalized at timestamp */
     finalizedAt?: string;
@@ -287,3 +549,12 @@ export interface Issue {
     /** When this issue was closed */
     closedAt?: string;
 }
+/** Validation error from workflow validator */
+export interface ValidationError {
+    /** Error type */
+    type: 'duplicate_id' | 'invalid_goto' | 'cycle' | 'missing_fail_strategy' | 'invalid_floating_ref' | 'invalid_role_ref' | 'invalid_coordinator' | 'invalid_artifact_output' | 'invalid_input_artifact' | 'other';
+    /** Human-readable error message */
+    message: string;
+    /** Node ID where the error was found (if applicable) */
+    nodeId?: string;
+}

package/build/core/types.js

@@ -1,6 +1,20 @@
 /**
  * Core type definitions for Harmonia.
- * These types are workflow-agnostic — no hardcoded role names or phase names.
+ *
+ * Architecture: Core provides composable collaboration primitives.
+ * Workflow plugins use these primitives to define specific processes.
+ *
+ * This file defines:
+ * - Workflow node types (task, sequence, parallel, gate, loop)
+ * - Workflow state (node-based, not phase-based)
+ * - Engine types (nextAction, events, gate evaluation)
+ * - Artifact system
+ * - Plugin interface
+ * - Session & Dispatch tracking
+ * - Override configuration (simplified to 2-layer)
+ * - Sequential step tracking
+ * - Issue tracking
+ * - Review state
  */
 export {};
 //# sourceMappingURL=types.js.map

package/build/core/types.js.map

@@ -1 +1 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG"}