@multiclawcli/core 0.3.1 → 0.4.0

package/src/agents/ui-designer.ts

@@ -1,61 +0,0 @@
-import type { AgentDefinition } from "../types/agent"
-
-type Overrides = Partial<AgentDefinition>
-
-const SYSTEM = `You are a UI/UX designer. Your job is to translate architecture and requirements into a detailed, developer-ready UI design specification.
-
-Responsibilities:
-- Define the component inventory: every page, section, and reusable component
-- Specify layouts, spacing principles, and responsive breakpoints
-- Define interaction patterns: loading states, empty states, error states, transitions
-- Specify design tokens: color palette, typography scale, spacing scale, shadow levels
-- Describe accessibility requirements: ARIA roles, keyboard navigation, focus management
-- Do not write implementation code — produce specification documents only
-
-Deliverables (save to the working directory):
-- ui-design.md — full UI design specification: component inventory, page layouts, interaction flows, design tokens, accessibility requirements
-
-Principles: Be specific enough that a developer can implement without guessing. Every component gets a name, purpose, props/variants, and states. Flag anything that depends on backend data.`
-
-const TASK = `## Task Scope
-{{file:task-plan.json}}
-
-Find the entry where id == "ui-designer" and treat its scope as the primary guide for your work.
-If task-plan.json is not found, determine your scope from the architecture design and API specification below.
-
----
-
-## Project
-{{projectName}}
-
-## Requirement
-{{requirement}}
-
-## Architecture Design
-{{file:architecture.md}}
-
-## API Specification
-{{file:api-spec.md}}
-
-## Task
-Create ui-design.md covering:
-1. **Component Inventory** — list every page and reusable component; for each: name, purpose, variants/states, props
-2. **Page Layouts** — describe the visual structure of each page (header, main, sidebar, footer zones); include responsive behaviour
-3. **Interaction Flows** — key user flows with step-by-step state transitions (loading → success → error)
-4. **Design Tokens** — color palette (primary, neutral, semantic), typography scale, spacing scale
-5. **Accessibility** — ARIA roles/labels for interactive components, keyboard nav, focus order
-
-Be concrete. Reference API endpoints where components bind to data. Flag any UX decision that needs product clarification.`
-
-export function uiDesigner(overrides?: Overrides): AgentDefinition {
-  return {
-    id: "ui-designer",
-    name: "UI Designer",
-    icon: "▣",
-    models: { claude: "sonnet" },
-    systemPrompt: SYSTEM,
-    taskPrompt: TASK,
-    tools: ["Read", "Write"],
-    ...overrides,
-  }
-}

package/src/config/defineConfig.ts

@@ -1,4 +0,0 @@
-import type { MultiClawConfig } from "../types/config"
-export function defineConfig(config: MultiClawConfig): MultiClawConfig {
-  return config
-}

package/src/event/EventBus.ts

@@ -1,19 +0,0 @@
-import type { MultiClawEvent, EventListener } from "../types/event"
-
-export class EventBus {
-  private listeners = new Set<EventListener>()
-
-  subscribe(listener: EventListener): () => void {
-    this.listeners.add(listener)
-    return () => this.listeners.delete(listener)
-  }
-
-  emit(event: MultiClawEvent): void {
-    for (const listener of this.listeners) {
-      try { listener(event) }
-      catch (err) { console.error("EventBus listener error:", err) }
-    }
-  }
-
-  clear(): void { this.listeners.clear() }
-}

package/src/index.ts

@@ -1,8 +0,0 @@
-export * from "./types"
-export { EventBus } from "./event/EventBus"
-export { Orchestrator } from "./orchestrator/Orchestrator"
-export { buildStages } from "./orchestrator/StageBuilder"
-export { runtimeRegistry, ClaudeRuntime } from "./runtime"
-export { RuntimeBase } from "./runtime/RuntimeBase"
-export { defineConfig } from "./config/defineConfig"
-export { agents } from "./agents"

package/src/orchestrator/AgentRunner.ts

@@ -1,104 +0,0 @@
-import * as fs from "fs"
-import * as path from "path"
-import type { AgentDefinition, AgentResult } from "../types/agent"
-import { runtimeRegistry } from "../runtime"
-import { EventBus } from "../event/EventBus"
-import { ContextManager } from "./ContextManager"
-import { withRetry } from "../utils/retry"
-import { withTimeout } from "../utils/timeout"
-import { renderPrompt } from "../utils/prompt"
-
-export class AgentRunner {
-  constructor(
-    private eventBus: EventBus,
-    private contextManager: ContextManager,
-    private globalWorkDir: string
-  ) {}
-
-  async run(agent: AgentDefinition): Promise<AgentResult> {
-    const startTime = new Date()
-    const workDir = agent.workDir
-      ? path.resolve(this.globalWorkDir, agent.workDir)
-      : this.globalWorkDir
-    fs.mkdirSync(workDir, { recursive: true })
-
-    const runtime = runtimeRegistry.get(agent.runtime ?? "claude")
-    const retries = agent.retries ?? 0
-    const timeout = agent.timeout ?? 600_000
-    const tools = agent.tools ?? ["Read", "Write", "Bash"]
-    const model = agent.model ?? agent.models?.[agent.runtime ?? "claude"]
-
-    this.eventBus.emit({
-      type: "agent:start",
-      timestamp: new Date().toISOString(),
-      payload: { agentId: agent.id, agentName: agent.name, icon: agent.icon, model, taskTitle: agent.taskTitle },
-    })
-
-    let attempts = 0
-    let output = ""
-
-    try {
-      output = await withTimeout(
-        (signal) => withRetry(async (attempt) => {
-          attempts = attempt
-          const prompt = await renderPrompt(
-            agent.taskPrompt,
-            this.contextManager.snapshot(),
-            this.globalWorkDir
-          )
-          return (await runtime.execute({
-            agentId: agent.id,
-            systemPrompt: agent.systemPrompt,
-            prompt, tools, workDir, timeout, signal,
-            model,
-            onOutput: (chunk) => {
-              this.eventBus.emit({
-                type: "agent:output",
-                timestamp: new Date().toISOString(),
-                payload: { agentId: agent.id, chunk },
-              })
-            },
-          })).output
-        }, retries, (attempt, err) => {
-          this.eventBus.emit({
-            type: "agent:retrying",
-            timestamp: new Date().toISOString(),
-            payload: {
-              agentId: agent.id,
-              agentName: agent.name,
-              attempt,
-              maxAttempts: retries + 1,
-              error: (err as Error).message,
-            },
-          })
-        }),
-        timeout,
-        agent.name
-      )
-
-      const endTime = new Date()
-      const result: AgentResult = {
-        agentId: agent.id, agentName: agent.name, status: "success",
-        output, duration: endTime.getTime() - startTime.getTime(),
-        attempts, startTime: startTime.toISOString(), endTime: endTime.toISOString(),
-      }
-      this.eventBus.emit({
-        type: "agent:complete", timestamp: new Date().toISOString(), payload: result,
-      })
-      return result
-    } catch (err) {
-      const endTime = new Date()
-      const result: AgentResult = {
-        agentId: agent.id, agentName: agent.name, status: "failed",
-        output, duration: endTime.getTime() - startTime.getTime(),
-        attempts, error: (err as Error).message,
-        startTime: startTime.toISOString(), endTime: endTime.toISOString(),
-      }
-      this.eventBus.emit({
-        type: "agent:failed", timestamp: new Date().toISOString(), payload: result,
-      })
-      return result
-    }
-  }
-}
-

package/src/orchestrator/ContextManager.ts

@@ -1,11 +0,0 @@
-export class ContextManager {
-  private store = new Map<string, string>()
-  constructor(initial?: Record<string, string>) {
-    if (initial) for (const [k, v] of Object.entries(initial)) this.store.set(k, v)
-  }
-  set(key: string, value: string) { this.store.set(key, value) }
-  get(key: string) { return this.store.get(key) }
-  snapshot(): Record<string, string> {
-    return Object.fromEntries(this.store.entries())
-  }
-}

package/src/orchestrator/Orchestrator.ts

@@ -1,180 +0,0 @@
-import * as fs from "fs"
-import * as path from "path"
-import type { MultiClawConfig, OrchestratorResult } from "../types/config"
-import type { AgentDefinition, AgentResult, TaskPlan } from "../types/agent"
-import type { StageInfo } from "../types/event"
-import { EventBus } from "../event/EventBus"
-import { ContextManager } from "./ContextManager"
-import { AgentRunner } from "./AgentRunner"
-import { buildStages } from "./StageBuilder"
-
-export class Orchestrator {
-  readonly eventBus = new EventBus()
-  private contextManager: ContextManager
-  private runner: AgentRunner
-  private workDir: string
-
-  constructor(private config: MultiClawConfig) {
-    this.workDir = path.resolve(config.workDir)
-    fs.mkdirSync(this.workDir, { recursive: true })
-    this.contextManager = new ContextManager(config.context)
-    this.runner = new AgentRunner(this.eventBus, this.contextManager, this.workDir)
-  }
-
-  async run(): Promise<OrchestratorResult> {
-    const startTime = new Date()
-    const agents = await this.resolveAgents()
-    this.contextManager.set(
-      "pipelineAgents",
-      agents.map((a) => `${a.id}: ${a.name}`).join("\n")
-    )
-
-    let stages = buildStages(agents)
-
-    const getModel = (agent: AgentDefinition): string | undefined => {
-      return agent.model ?? agent.models?.[agent.runtime ?? "claude"]
-    }
-
-    const stageInfos: StageInfo[] = stages.map((stage, i) => ({
-      stageIndex: i,
-      agents: stage.map((a) => ({ id: a.id, name: a.name, icon: a.icon, model: getModel(a), taskTitle: a.taskTitle })),
-    }))
-
-    this.eventBus.emit({
-      type: "orchestration:start",
-      timestamp: new Date().toISOString(),
-      payload: { name: this.config.name, requirement: this.config.context?.requirement, totalAgents: agents.length, stages: stageInfos },
-    })
-
-    const results: AgentResult[] = []
-    let allSuccess = true
-
-    for (let i = 0; i < stages.length; i++) {
-      const stage = stages[i]
-
-      this.eventBus.emit({
-        type: "stage:start", timestamp: new Date().toISOString(),
-        payload: { stageIndex: i, agentIds: stage.map((a) => a.id) },
-      })
-
-      const stageResults = await this.runStage(stage)
-      results.push(...stageResults)
-
-      // After architect stage completes, apply task plan and rebuild stages
-      if (i === 0 && stage.some((a) => a.id === "architect") && stageResults.some((r) => r.status === "success")) {
-        await this.applyTaskPlan(agents)
-        stages = buildStages(agents)
-      }
-
-      for (const r of stageResults) {
-        if (r.status !== "success") {
-          allSuccess = false
-          if (!this.config.continueOnError) break
-        }
-      }
-
-      this.eventBus.emit({
-        type: "stage:complete", timestamp: new Date().toISOString(),
-        payload: { stageIndex: i },
-      })
-
-      if (!allSuccess && !this.config.continueOnError) {
-        for (const remainingStage of stages.slice(i + 1)) {
-          for (const agent of remainingStage) {
-            this.eventBus.emit({
-              type: "agent:skipped",
-              timestamp: new Date().toISOString(),
-              payload: { agentId: agent.id, agentName: agent.name, icon: agent.icon },
-            })
-          }
-        }
-        break
-      }
-    }
-
-    const endTime = new Date()
-    const result: OrchestratorResult = {
-      name: this.config.name, success: allSuccess,
-      totalDuration: endTime.getTime() - startTime.getTime(),
-      agentResults: results,
-      startTime: startTime.toISOString(), endTime: endTime.toISOString(),
-    }
-
-    this.eventBus.emit({
-      type: "orchestration:complete", timestamp: new Date().toISOString(), payload: result,
-    })
-    return result
-  }
-
-  private async resolveAgents(): Promise<AgentDefinition[]> {
-    if (!this.config.leader || this.config.useLeader === false) return this.config.agents
-
-    this.contextManager.set(
-      "availableAgents",
-      this.config.agents.map((a) => `${a.id}: ${a.name}`).join("\n")
-    )
-
-    const result = await this.runner.run(this.config.leader)
-    if (result.status !== "success") return this.config.agents
-
-    const match = result.output.match(/\{[\s\S]*?"run"\s*:\s*\[[\s\S]*?\]\s*\}/)
-    if (!match) return this.config.agents
-
-    let plan: { run: string[] }
-    try { plan = JSON.parse(match[0]) } catch { return this.config.agents }
-
-    const runSet = new Set(plan.run)
-    const skippedIds = new Set(
-      this.config.agents.filter((a) => !runSet.has(a.id)).map((a) => a.id)
-    )
-
-    for (const agent of this.config.agents.filter((a) => skippedIds.has(a.id))) {
-      this.eventBus.emit({
-        type: "agent:skipped",
-        timestamp: new Date().toISOString(),
-        payload: { agentId: agent.id, agentName: agent.name, icon: agent.icon },
-      })
-    }
-
-    return this.config.agents
-      .filter((a) => runSet.has(a.id))
-      .map((a) => ({
-        ...a,
-        dependsOn: a.dependsOn?.filter((dep) => !skippedIds.has(dep)),
-      }))
-  }
-
-  private async runStage(agents: AgentDefinition[]): Promise<AgentResult[]> {
-    const { maxConcurrency } = this.config
-    if (!maxConcurrency || agents.length <= maxConcurrency) {
-      return Promise.all(agents.map((a) => this.runner.run(a)))
-    }
-    const results: AgentResult[] = []
-    for (let i = 0; i < agents.length; i += maxConcurrency) {
-      const batch = agents.slice(i, i + maxConcurrency)
-      results.push(...(await Promise.all(batch.map((a) => this.runner.run(a)))))
-    }
-    return results
-  }
-
-  private async applyTaskPlan(agents: AgentDefinition[]): Promise<void> {
-    try {
-      const taskPlanPath = path.join(this.workDir, "task-plan.json")
-      if (!fs.existsSync(taskPlanPath)) return
-
-      const content = fs.readFileSync(taskPlanPath, "utf-8")
-      const taskPlan: TaskPlan = JSON.parse(content)
-
-      const taskMap = new Map(taskPlan.tasks.map((t) => [t.id, t]))
-      for (const agent of agents) {
-        const task = taskMap.get(agent.id)
-        if (task) {
-          agent.taskTitle = task.title
-          agent.dependsOn = task.dependsOn
-        }
-      }
-    } catch {
-      // Silently ignore parsing errors
-    }
-  }
-}

package/src/orchestrator/StageBuilder.ts

@@ -1,30 +0,0 @@
-import type { AgentDefinition } from "../types/agent"
-
-export function buildStages(agents: AgentDefinition[]): AgentDefinition[][] {
-  const stages: AgentDefinition[][] = []
-  const completed = new Set<string>()
-  let remaining = [...agents]
-
-  const allIds = new Set(agents.map((a) => a.id))
-  for (const a of agents) {
-    for (const dep of a.dependsOn ?? []) {
-      if (!allIds.has(dep)) {
-        throw new Error(`Agent "${a.id}" depends on "${dep}" which does not exist`)
-      }
-    }
-  }
-
-  while (remaining.length > 0) {
-    const stage = remaining.filter((a) =>
-      (a.dependsOn ?? []).every((dep) => completed.has(dep))
-    )
-    if (stage.length === 0) {
-      const ids = remaining.map((a) => a.id).join(", ")
-      throw new Error(`Circular or unsatisfiable dependency detected: ${ids}`)
-    }
-    stages.push(stage)
-    stage.forEach((a) => completed.add(a.id))
-    remaining = remaining.filter((a) => !stage.includes(a))
-  }
-  return stages
-}

package/src/runtime/ClaudeRuntime.ts

@@ -1,41 +0,0 @@
-import { spawn, execSync } from "child_process"
-import { RuntimeBase } from "./RuntimeBase"
-import type { AgentTask, AgentOutput } from "../types/runtime"
-
-export class ClaudeRuntime extends RuntimeBase {
-  readonly name = "claude"
-
-  async checkAvailable(): Promise<boolean> {
-    try { execSync("claude --version", { stdio: "ignore" }); return true }
-    catch { return false }
-  }
-
-  async execute(task: AgentTask): Promise<AgentOutput> {
-    const args = [
-      "-p", task.prompt,
-      "--allowedTools", task.tools.join(","),
-    ]
-    if (task.systemPrompt) args.push("--system-prompt", task.systemPrompt)
-    if (task.model) args.push("--model", task.model)
-
-    return new Promise((resolve, reject) => {
-      const child = spawn("claude", args, { cwd: task.workDir, env: process.env })
-      task.signal?.addEventListener("abort", () => child.kill())
-
-      let output = ""
-      let errorOutput = ""
-      child.stdout.on("data", (d: Buffer) => {
-        const chunk = d.toString(); output += chunk; task.onOutput?.(chunk)
-      })
-      child.stderr.on("data", (d: Buffer) => { errorOutput += d.toString() })
-      child.on("close", (code) => {
-        if (task.signal?.aborted) return
-        code === 0
-          ? resolve({ output, exitCode: code })
-          : reject(new Error(`claude exited with code ${code}: ${errorOutput}`))
-      })
-      child.on("error", (err) => reject(new Error(`Failed to start claude: ${err.message}`)))
-    })
-  }
-}
-

package/src/runtime/RuntimeBase.ts

@@ -1,7 +0,0 @@
-import type { AgentRuntime, AgentTask, AgentOutput } from "../types/runtime"
-
-export abstract class RuntimeBase implements AgentRuntime {
-  abstract readonly name: string
-  abstract checkAvailable(): Promise<boolean>
-  abstract execute(task: AgentTask): Promise<AgentOutput>
-}

package/src/runtime/index.ts

@@ -1,20 +0,0 @@
-import type { AgentRuntime } from "../types/runtime"
-import { ClaudeRuntime } from "./ClaudeRuntime"
-
-class RuntimeRegistry {
-  private runtimes = new Map<string, AgentRuntime>()
-  constructor() {
-    this.register(new ClaudeRuntime())
-  }
-  register(r: AgentRuntime) { this.runtimes.set(r.name, r) }
-  get(name: string): AgentRuntime {
-    const r = this.runtimes.get(name)
-    if (!r) throw new Error(`Runtime not found: "${name}". Available: ${[...this.runtimes.keys()].join(", ")}`)
-    return r
-  }
-  has(name: string) { return this.runtimes.has(name) }
-  list(): string[] { return [...this.runtimes.keys()] }
-}
-
-export const runtimeRegistry = new RuntimeRegistry()
-export { ClaudeRuntime }

package/src/types/agent.ts

@@ -1,48 +0,0 @@
-export type ToolName =
-  | "Read" | "Write" | "Edit" | "MultiEdit"
-  | "Bash" | "Glob" | "Grep" | "WebFetch"
-
-export interface AgentDefinition {
-  id: string
-  name: string
-  icon?: string
-  runtime?: string
-  model?: string
-  models?: Partial<Record<string, string>>
-  systemPrompt: string
-  taskPrompt: string
-  taskTitle?: string
-  tools?: ToolName[]
-  dependsOn?: string[]
-  timeout?: number
-  retries?: number
-  workDir?: string
-}
-
-export type AgentStatus =
-  | "pending" | "running" | "retrying" | "success" | "failed" | "skipped"
-
-export interface AgentResult {
-  agentId: string
-  agentName: string
-  status: AgentStatus
-  output: string
-  duration: number
-  attempts: number
-  error?: string
-  startTime: string
-  endTime: string
-}
-
-export interface SubTask {
-  id: string       // matches AgentDefinition.id
-  title: string
-  scope: string
-  dependsOn?: string[]
-}
-
-export interface TaskPlan {
-  projectName: string
-  requirement: string
-  tasks: SubTask[]
-}

package/src/types/config.ts

@@ -1,26 +0,0 @@
-import type { AgentDefinition } from "./agent"
-
-export interface MultiClawConfig {
-  name: string
-  workDir: string
-  leader?: AgentDefinition
-  agents: AgentDefinition[]
-  context?: Record<string, string>
-  logDir?: string
-  continueOnError?: boolean
-  maxConcurrency?: number
-  useLeader?: boolean
-  dashboard?: {
-    port?: number
-    autoOpen?: boolean
-  }
-}
-
-export interface OrchestratorResult {
-  name: string
-  success: boolean
-  totalDuration: number
-  agentResults: import("./agent").AgentResult[]
-  startTime: string
-  endTime: string
-}

package/src/types/event.ts

@@ -1,21 +0,0 @@
-import type { AgentResult, OrchestratorResult } from "./index"
-
-export interface StageInfo {
-  stageIndex: number
-  agents: Array<{ id: string; name: string; icon?: string; model?: string; taskTitle?: string }>
-}
-
-export type MultiClawEvent =
-  | { type: "orchestration:start";    timestamp: string; payload: { name: string; requirement?: string; totalAgents: number; stages: StageInfo[] } }
-  | { type: "orchestration:complete"; timestamp: string; payload: OrchestratorResult }
-  | { type: "stage:start";            timestamp: string; payload: { stageIndex: number; agentIds: string[] } }
-  | { type: "stage:complete";         timestamp: string; payload: { stageIndex: number } }
-  | { type: "agent:start";            timestamp: string; payload: { agentId: string; agentName: string; icon?: string; model?: string; taskTitle?: string } }
-  | { type: "agent:output";           timestamp: string; payload: { agentId: string; chunk: string } }
-  | { type: "agent:complete";         timestamp: string; payload: AgentResult }
-  | { type: "agent:failed";           timestamp: string; payload: AgentResult }
-  | { type: "agent:skipped";          timestamp: string; payload: { agentId: string; agentName: string; icon?: string } }
-  | { type: "agent:retrying";         timestamp: string; payload: { agentId: string; agentName: string; attempt: number; maxAttempts: number; error: string } }
-
-export type EventListener = (event: MultiClawEvent) => void
-

package/src/types/index.ts

@@ -1,4 +0,0 @@
-export * from "./agent"
-export * from "./runtime"
-export * from "./config"
-export * from "./event"

package/src/types/runtime.ts

@@ -1,23 +0,0 @@
-export interface AgentTask {
-  agentId: string
-  systemPrompt: string
-  prompt: string
-  tools: string[]
-  workDir: string
-  timeout: number
-  signal?: AbortSignal
-  onOutput?: (chunk: string) => void
-  model?: string
-}
-
-export interface AgentOutput {
-  output: string
-  exitCode: number
-}
-
-export interface AgentRuntime {
-  readonly name: string
-  checkAvailable(): Promise<boolean>
-  execute(task: AgentTask): Promise<AgentOutput>
-}
-

package/src/utils/prompt.ts

@@ -1,24 +0,0 @@
-import * as fs from "fs/promises"
-import * as path from "path"
-
-export async function renderPrompt(
-  template: string,
-  context: Record<string, string>,
-  workDir: string
-): Promise<string> {
-  let result = template
-  const fileMatches = [...template.matchAll(/\{\{file:([^}]+)\}\}/g)]
-  for (const match of fileMatches) {
-    const filePath = path.resolve(workDir, match[1].trim())
-    try {
-      const content = await fs.readFile(filePath, "utf-8")
-      result = result.replace(match[0], content)
-    } catch {
-      result = result.replace(match[0], `[file not found: ${match[1]}]`)
-    }
-  }
-  for (const [key, value] of Object.entries(context)) {
-    result = result.replaceAll(`{{${key}}}`, value)
-  }
-  return result
-}

package/src/utils/retry.ts

@@ -1,24 +0,0 @@
-export function sleep(ms: number): Promise<void> {
-  return new Promise((r) => setTimeout(r, ms))
-}
-
-export async function withRetry<T>(
-  fn: (attempt: number) => Promise<T>,
-  retries: number,
-  onRetry?: (failedAttempt: number, error: unknown) => void,
-  delayMs = 2000
-): Promise<T> {
-  let lastError: Error = new Error("Unknown error")
-  for (let attempt = 1; attempt <= retries + 1; attempt++) {
-    try { return await fn(attempt) }
-    catch (err) {
-      lastError = err as Error
-      if (attempt <= retries) {
-        onRetry?.(attempt, err)
-        await sleep(delayMs * attempt)
-      }
-    }
-  }
-  throw lastError
-}
-