@maestroai/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,1007 @@
+import EventEmitter, { EventEmitter as EventEmitter$1 } from 'eventemitter3';
+import pino from 'pino';
+
+type AgentRole = 'orchestrator' | 'project-manager' | 'architect' | 'developer' | 'designer' | 'qa-engineer' | 'devops' | 'technical-writer' | 'code-reviewer';
+type AgentStatus = 'idle' | 'starting' | 'running' | 'stopping' | 'stopped' | 'error';
+interface AgentConfig {
+    id: string;
+    role: AgentRole;
+    name: string;
+    model?: string;
+    systemPrompt: string;
+    allowedTools?: string[];
+    maxBudgetUsd?: number;
+    workingDirectory: string;
+    permissionMode: 'default' | 'acceptEdits' | 'bypassPermissions';
+    /** Path to the claude CLI binary (default: "claude") */
+    claudeCommand?: string;
+    /** Extra CLI args appended to every invocation */
+    claudeArgs?: string[];
+    /** Extra environment variables merged into the subprocess env */
+    claudeEnv?: Record<string, string>;
+    /** Max agentic turns per invocation (maps to --max-turns) */
+    maxTurns?: number;
+}
+interface AgentState {
+    config: AgentConfig;
+    status: AgentStatus;
+    pid: number | null;
+    sessionId: string | null;
+    currentTask: string | null;
+    startedAt: string | null;
+    lastActivityAt: string | null;
+    totalCostUsd: number;
+    turnCount: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheCreationTokens: number;
+    error: string | null;
+    /** Set when the agent result has is_error: true (e.g. rate limit) */
+    resultError: string | null;
+    /** True when the agent hit an API rate limit (429) */
+    rateLimited: boolean;
+    /** Human-readable rate limit reset time from the API response */
+    rateLimitResetAt: string | null;
+}
+interface AgentStreamEvent {
+    type: 'system' | 'user' | 'assistant' | 'tool_use' | 'tool_result' | 'result' | 'error';
+    agentId: string;
+    timestamp: string;
+    data: Record<string, unknown>;
+}
+
+type TaskStatus = 'pending' | 'in-progress' | 'done' | 'blocked' | 'cancelled';
+type TaskPriority = 'critical' | 'high' | 'medium' | 'low';
+interface Task {
+    id: string;
+    title: string;
+    description: string;
+    status: TaskStatus;
+    priority: TaskPriority;
+    assignee: string | null;
+    dependencies: string[];
+    tags: string[];
+    createdAt: string;
+    updatedAt: string;
+    completedAt: string | null;
+    notes: string[];
+}
+interface TaskFilter {
+    status?: TaskStatus[];
+    assignee?: string | null;
+    priority?: TaskPriority[];
+    tags?: string[];
+}
+interface TaskUpdate {
+    status?: TaskStatus;
+    assignee?: string | null;
+    priority?: TaskPriority;
+    notes?: string[];
+}
+
+type MessageType = 'task-assignment' | 'task-update' | 'task-complete' | 'task-blocked' | 'question' | 'answer' | 'review-request' | 'review-result' | 'system' | 'directive';
+interface Message {
+    id: string;
+    type: MessageType;
+    from: string;
+    to: string;
+    subject: string;
+    body: string;
+    replyTo?: string;
+    taskId?: string;
+    priority: 'normal' | 'urgent';
+    timestamp: string;
+    metadata?: Record<string, unknown>;
+}
+interface MessageEnvelope {
+    message: Message;
+    deliveredAt: string | null;
+    readAt: string | null;
+    status: 'pending' | 'delivered' | 'read' | 'processed';
+}
+
+type InteractionMode = 'unattended' | 'supervised' | 'interactive';
+interface PlanProposal {
+    id: string;
+    tasks: PlannedTaskSummary[];
+    totalEstimatedTasks: number;
+    projectGoal: string;
+    createdAt: string;
+    status: 'pending' | 'approved' | 'rejected' | 'modified';
+}
+interface PlannedTaskSummary {
+    title: string;
+    description: string;
+    priority: string;
+    assignedRole: string;
+    tags: string[];
+}
+interface UserQuestion {
+    id: string;
+    fromAgent: string;
+    taskId?: string;
+    question: string;
+    context?: string;
+    options?: string[];
+    createdAt: string;
+    status: 'pending' | 'answered' | 'timed-out';
+    answer?: string;
+}
+interface ProgressReport {
+    id: string;
+    phase: string;
+    completedTasks: number;
+    totalTasks: number;
+    percentComplete: number;
+    recentCompletions: string[];
+    upcomingWork: string[];
+    blockers: string[];
+    totalCostUsd: number;
+    createdAt: string;
+}
+interface MilestoneEvent {
+    id: string;
+    name: string;
+    percentComplete: number;
+    message: string;
+    requiresAck: boolean;
+    createdAt: string;
+}
+interface FeedbackSettings {
+    interactionMode: InteractionMode;
+    progressReportIntervalMs: number;
+    milestonePercentages: number[];
+    questionTimeoutMs: number;
+    requirePlanApproval: boolean;
+}
+
+interface TechStackConfig {
+    frontend?: string;
+    uiLibrary?: string;
+    backend?: string;
+    database?: string;
+    other?: string;
+}
+interface ProjectConfig {
+    name: string;
+    description: string;
+    version: string;
+    agents: AgentRoleConfig[];
+    settings: ProjectSettings;
+    techStack?: TechStackConfig;
+}
+interface ProjectSettings {
+    workingDirectory: string;
+    todoFile: string;
+    messagesDirectory: string;
+    logsDirectory: string;
+    defaultModel: string;
+    maxConcurrentAgents: number;
+    pollIntervalMs: number;
+    maxTotalBudgetUsd?: number;
+    feedback?: FeedbackSettings;
+    /** Path to the claude CLI binary (default: "claude") */
+    claudeCommand?: string;
+    /** Extra CLI args passed to every agent invocation */
+    claudeArgs?: string[];
+    /** Extra environment variables passed to every agent invocation */
+    claudeEnv?: Record<string, string>;
+}
+interface AgentRoleConfig {
+    role: AgentRole;
+    count: number;
+    model?: string;
+    systemPromptFile?: string;
+    systemPromptOverride?: string;
+    allowedTools?: string[];
+    maxBudgetUsd?: number;
+    permissionMode?: 'default' | 'acceptEdits' | 'bypassPermissions';
+    /** Extra CLI args for this agent (merged with settings.claudeArgs) */
+    claudeArgs?: string[];
+    /** Extra environment variables for this agent (merged with settings.claudeEnv) */
+    claudeEnv?: Record<string, string>;
+    /** Max agentic turns per invocation (maps to --max-turns) */
+    maxTurns?: number;
+}
+
+/**
+ * Orchestrator activity log types.
+ *
+ * These represent structured events that the orchestrator emits so that
+ * a persistent "Orchestrator" panel in the TUI can display what's happening
+ * at a high level: task delegations, status updates, phase transitions,
+ * agent hand-offs, and pipeline progress.
+ */
+type OrchestratorActivityKind = 'task-delegated' | 'task-completed' | 'task-blocked' | 'task-failed' | 'agent-spawned' | 'agent-stopped' | 'agent-error' | 'phase-changed' | 'pipeline-handoff' | 'plan-created' | 'plan-approved' | 'plan-rejected' | 'budget-warning' | 'rate-limit' | 'project-completed' | 'cycle-summary' | 'gap-detected' | 'pm-scan' | 'info';
+interface OrchestratorActivity {
+    id: string;
+    kind: OrchestratorActivityKind;
+    timestamp: string;
+    message: string;
+    details?: {
+        taskId?: string;
+        taskTitle?: string;
+        agentId?: string;
+        agentRole?: string;
+        fromPhase?: string;
+        toPhase?: string;
+        pipelineStage?: string;
+        cost?: number;
+        [key: string]: unknown;
+    };
+}
+/**
+ * Task pipeline stages — each task flows through a defined sequence of
+ * stages with role-based handoffs between agents.
+ */
+type PipelineStage = 'plan' | 'develop' | 'qa' | 'review';
+declare const PIPELINE_STAGE_ORDER: PipelineStage[];
+/**
+ * Maps pipeline stages to the agent roles responsible for executing them.
+ */
+declare const PIPELINE_STAGE_ROLES: Record<PipelineStage, string[]>;
+interface TaskPipelineState {
+    taskId: string;
+    currentStage: PipelineStage;
+    stageHistory: {
+        stage: PipelineStage;
+        agentId: string;
+        startedAt: string;
+        completedAt: string | null;
+        status: 'in-progress' | 'completed' | 'failed';
+    }[];
+    createdAt: string;
+}
+
+interface AgentInfo {
+    id: string;
+    name: string;
+    role: string;
+    status: AgentStatus;
+    spawned: boolean;
+    currentTask: string | null;
+}
+interface OrchestratorStats {
+    totalTasks: number;
+    completedTasks: number;
+    activeAgents: number;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheCreationTokens: number;
+    uptimeMs: number;
+    agents: AgentInfo[];
+}
+interface ProjectCompletionSummary {
+    totalTasks: number;
+    doneTasks: number;
+    cancelledTasks: number;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCacheReadTokens: number;
+    totalCacheCreationTokens: number;
+    uptimeMs: number;
+    agentSummaries: {
+        agentId: string;
+        name: string;
+        role: string;
+        tasksCompleted: number;
+        costUsd: number;
+        inputTokens: number;
+        outputTokens: number;
+    }[];
+    completedAt: string;
+}
+interface MaestroEvents {
+    'agent:spawned': (state: AgentState) => void;
+    'agent:status-changed': (agentId: string, oldStatus: AgentStatus, newStatus: AgentStatus) => void;
+    'agent:output': (event: AgentStreamEvent) => void;
+    'agent:error': (agentId: string, error: Error) => void;
+    'agent:stopped': (agentId: string, exitCode: number | null) => void;
+    'task:created': (task: Task) => void;
+    'task:updated': (task: Task, changes: TaskUpdate) => void;
+    'task:assigned': (task: Task, agentId: string) => void;
+    'task:completed': (task: Task) => void;
+    'tasks:loaded': (tasks: Task[]) => void;
+    'message:sent': (message: Message) => void;
+    'message:received': (message: Message) => void;
+    'orchestrator:cycle': (stats: OrchestratorStats) => void;
+    'project:completed': (summary: ProjectCompletionSummary) => void;
+    'budget:warning': (currentUsd: number, maxUsd: number) => void;
+    'budget:exceeded': (currentUsd: number, maxUsd: number) => void;
+    'rate-limit': (agentId: string, resetAt: string | null) => void;
+    'architecture:ready': (archTasks: Task[]) => void;
+    'phase:changed': (phase: string) => void;
+    'plan:proposed': (proposal: PlanProposal) => void;
+    'plan:decided': (proposalId: string, decision: 'approved' | 'rejected', modifications?: string) => void;
+    'question:asked': (question: UserQuestion) => void;
+    'question:answered': (questionId: string, answer: string) => void;
+    'progress:report': (report: ProgressReport) => void;
+    'milestone:reached': (milestone: MilestoneEvent) => void;
+    'milestone:acknowledged': (milestoneId: string) => void;
+    'interaction-mode:changed': (mode: InteractionMode) => void;
+    'orchestrator:paused': () => void;
+    'orchestrator:resumed': () => void;
+    'instructions:decomposing': (instructions: string) => void;
+    'instructions:added': (tasks: Task[]) => void;
+    'orchestrator:activity': (activity: OrchestratorActivity) => void;
+}
+
+declare class TaskParser {
+    parse(content: string): {
+        projectName: string;
+        tasks: Task[];
+    };
+    parseLine(line: string, currentPriority: TaskPriority): Task | null;
+}
+
+declare class TaskWriter {
+    write(projectName: string, tasks: Task[]): string;
+    formatTask(task: Task): string;
+}
+
+interface TaskManagerOptions {
+    filePath: string;
+    projectName: string;
+}
+declare class TaskManager extends EventEmitter {
+    private readonly filePath;
+    private readonly projectName;
+    private readonly parser;
+    private readonly writer;
+    constructor(options: TaskManagerOptions);
+    private ensureFile;
+    load(): Promise<Task[]>;
+    save(tasks: Task[]): Promise<void>;
+    getTask(id: string): Promise<Task | undefined>;
+    getTasks(filter?: TaskFilter): Promise<Task[]>;
+    createTask(data: {
+        title: string;
+        priority: TaskPriority;
+        description?: string;
+        dependencies?: string[];
+        tags?: string[];
+    }): Promise<Task>;
+    updateTask(id: string, update: TaskUpdate): Promise<Task>;
+    assignTask(id: string, agentId: string): Promise<Task>;
+    completeTask(id: string): Promise<Task>;
+    private extractMaxTaskNumber;
+}
+
+interface AgentProcessEvents {
+    'output': (event: AgentStreamEvent) => void;
+    'status-changed': (oldStatus: AgentStatus, newStatus: AgentStatus) => void;
+    'error': (error: Error) => void;
+    'stopped': (exitCode: number | null) => void;
+}
+declare class AgentProcess extends EventEmitter$1<AgentProcessEvents> {
+    private readonly config;
+    private subprocess;
+    private state;
+    private streamBuffer;
+    constructor(config: AgentConfig);
+    get id(): string;
+    get currentState(): AgentState;
+    /**
+     * Set the current task this agent is working on (task ID + title).
+     */
+    setCurrentTask(taskInfo: string | null): void;
+    /**
+     * Spawn a claude CLI process with the given prompt.
+     */
+    spawn(prompt: string): Promise<void>;
+    /**
+     * Resume a previous session with a new prompt.
+     */
+    resume(prompt: string): Promise<void>;
+    /**
+     * Graceful stop: SIGTERM, wait, then force kill.
+     */
+    stop(timeoutMs?: number): Promise<void>;
+    /**
+     * Force kill immediately.
+     */
+    kill(): Promise<void>;
+    /**
+     * Build CLI arguments for the claude command.
+     * The prompt is piped via stdin, not passed as a positional argument.
+     */
+    private buildArgs;
+    /**
+     * Parse NDJSON stream from claude stdout.
+     * Reads stdout line by line and emits typed events.
+     */
+    private processStream;
+    /**
+     * Read stderr and emit lines as error events so they're visible.
+     */
+    private processStderr;
+    /**
+     * Emit a synthetic output event.
+     */
+    private emitOutput;
+    /**
+     * Update internal state and emit status change events.
+     */
+    private setStatus;
+}
+
+interface AgentPoolEvents {
+    'agent:spawned': (agentId: string, process: AgentProcess) => void;
+    'agent:output': (event: AgentStreamEvent) => void;
+    'agent:status-changed': (agentId: string, oldStatus: AgentStatus, newStatus: AgentStatus) => void;
+    'agent:error': (agentId: string, error: Error) => void;
+    'agent:stopped': (agentId: string, exitCode: number | null) => void;
+}
+declare class AgentPool extends EventEmitter$1<AgentPoolEvents> {
+    private agents;
+    /**
+     * Spawn a new agent process with the given config and initial prompt.
+     */
+    spawnAgent(config: AgentConfig, prompt: string): Promise<AgentProcess>;
+    /**
+     * Stop a specific agent by ID with an optional timeout.
+     */
+    stopAgent(id: string, timeoutMs?: number): Promise<void>;
+    /**
+     * Stop all agents concurrently. Uses Promise.allSettled for graceful handling.
+     */
+    stopAll(timeoutMs?: number): Promise<void>;
+    /**
+     * Remove a stopped agent from the pool so it can be re-spawned.
+     */
+    removeAgent(id: string): void;
+    /**
+     * Get an agent process by ID.
+     */
+    getAgent(id: string): AgentProcess | undefined;
+    /**
+     * Get all agents with a specific role.
+     */
+    getAgentsByRole(role: AgentRole): AgentProcess[];
+    /**
+     * Get all agents with a specific status.
+     */
+    getAgentsByStatus(status: AgentStatus): AgentProcess[];
+    /**
+     * Get all agents in the pool.
+     */
+    getAllAgents(): AgentProcess[];
+    /**
+     * Get aggregate statistics across all agents.
+     */
+    getStats(): {
+        total: number;
+        running: number;
+        idle: number;
+        stopped: number;
+        totalCostUsd: number;
+    };
+    /**
+     * Attach event forwarding listeners from an agent process to the pool.
+     */
+    private attachListeners;
+}
+
+declare const ROLE_DESCRIPTIONS: Record<AgentRole, string>;
+interface SystemPromptParams {
+    role: AgentRole;
+    agentId: string;
+    projectName: string;
+    todoFilePath: string;
+    inboxPath: string;
+    outboxPath: string;
+    workingDirectory: string;
+    techStack?: TechStackConfig;
+}
+declare function getDefaultSystemPrompt(params: SystemPromptParams): string;
+
+/**
+ * Load and generate AgentConfig[] from a ProjectConfig.
+ *
+ * For each role config:
+ * - If count > 1, generates multiple configs with IDs like "developer-1", "developer-2"
+ * - If count === 1, uses the role as the ID (e.g., "orchestrator")
+ * - Loads system prompts from systemPromptFile if specified, otherwise uses getDefaultSystemPrompt
+ */
+declare function loadAgentConfigs(projectConfig: ProjectConfig): AgentConfig[];
+
+declare class MessageBroker extends EventEmitter$1 {
+    private baseDir;
+    private watchers;
+    private registeredAgents;
+    constructor(baseDir: string);
+    /**
+     * Initialize directory structure for an agent.
+     * Creates inbox/, outbox/, and processed/ directories.
+     */
+    registerAgent(agentId: string): Promise<void>;
+    /**
+     * Initialize directories for all agents and start watching.
+     * Watches each agent's outbox directory so that messages agents write
+     * there are automatically picked up and routed.
+     */
+    start(agentIds: string[]): Promise<void>;
+    /**
+     * Send a message to an agent's inbox.
+     * If message.to is "*", broadcasts to all registered agents instead.
+     */
+    sendMessage(message: Message): Promise<void>;
+    /**
+     * Send a message to all registered agents' inboxes.
+     */
+    broadcast(message: Message): Promise<void>;
+    /**
+     * Mark an inbox message as processed and move it to the processed directory.
+     * Called when a task completes so the inbox reflects the current state.
+     */
+    markInboxProcessed(agentId: string, taskId: string): Promise<void>;
+    /**
+     * Clean up stale inbox messages for a task (e.g., after restart when
+     * in-progress tasks are reset). Moves matching messages to processed/.
+     */
+    cleanInboxForTask(agentId: string, taskId: string): Promise<void>;
+    /**
+     * Read processed messages for a specific task across all agents.
+     * Used to display task completion details in the TUI.
+     */
+    getProcessedMessagesForTask(taskId: string): Promise<MessageEnvelope[]>;
+    /**
+     * Move ALL inbox messages to processed/ for every agent directory.
+     * Called on startup to ensure a clean slate — agents should not pick up
+     * stale task-assignment messages from a previous session.
+     */
+    cleanAllInboxes(): Promise<void>;
+    get messagesBaseDir(): string;
+    /**
+     * Stop all watchers and clean up.
+     */
+    stop(): Promise<void>;
+}
+
+declare class InboxWatcher extends EventEmitter$1 {
+    private watcher;
+    private dir;
+    private processedDir;
+    constructor(inboxDir: string, processedDir: string);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private processFile;
+}
+
+declare class Orchestrator extends EventEmitter$1 {
+    private config;
+    private running;
+    private paused;
+    private intervalId;
+    private startedAt;
+    private broker;
+    private scheduler;
+    private planner;
+    private pipeline;
+    private pmScanner;
+    private taskManager;
+    private agentPool;
+    private agentConfigs;
+    private cachedTasks;
+    private feedbackLoop;
+    private planApprovalPending;
+    private phase;
+    private architectureApprovalPending;
+    constructor(config: ProjectConfig);
+    get isActive(): boolean;
+    get isPaused(): boolean;
+    /**
+     * Emit a structured orchestrator activity event.
+     * These feed the persistent "Orchestrator" panel in the TUI.
+     */
+    private emitActivity;
+    /**
+     * Start the orchestrator:
+     * 1. Ensure workspace directories exist
+     * 2. Initialize TaskManager, AgentPool, MessageBroker, Scheduler, Planner
+     * 3. Load agent configs and register them with the broker
+     * 4. If no tasks exist, use Planner to decompose the project description
+     * 5. Start the polling loop
+     */
+    start(): Promise<void>;
+    /**
+     * Stop the orchestrator gracefully.
+     */
+    stop(): Promise<void>;
+    /**
+     * Pause the orchestrator: stop the polling cycle and all running agents.
+     * Tasks and state are preserved so work can be resumed later.
+     */
+    pause(): Promise<void>;
+    /**
+     * Resume the orchestrator after a pause. Restarts the polling cycle
+     * and PM scanner so agents can be re-assigned to pending tasks.
+     */
+    resume(): Promise<void>;
+    /**
+     * Add new instructions: decompose them into tasks and append to the
+     * existing todo.md without deleting any existing tasks.
+     */
+    addInstructions(instructions: string): Promise<Task[]>;
+    /**
+     * A single orchestration cycle:
+     * 1. Load current tasks
+     * 2. Run scheduler to determine assignments
+     * 3. For each assignment: update task, send message, spawn agent
+     * 4. Handle pipeline handoffs for completed tasks
+     * 5. Check budget limits
+     * 6. Emit cycle stats
+     */
+    private cycle;
+    /**
+     * Run a single PM scan pass — assess project health, identify gaps and
+     * blockers, and surface findings in the orchestrator activity log.
+     */
+    private runPMScan;
+    /**
+     * Build a task prompt for an agent.
+     */
+    private buildTaskPrompt;
+    /**
+     * Check whether the total cost across all agents exceeds the budget.
+     */
+    private checkBudget;
+    /**
+     * Get all current tasks.
+     */
+    getTasks(): Promise<Task[]>;
+    /**
+     * Get all agent states.
+     */
+    getAgentStates(): any[];
+    /**
+     * Get the pipeline state for a specific task.
+     */
+    getTaskPipelineState(taskId: string): TaskPipelineState | undefined;
+    /**
+     * Get current orchestrator statistics.
+     */
+    getStats(): OrchestratorStats;
+    /**
+     * Format a token count for display (e.g. 1234567 → "1.23M", 45678 → "45.7k").
+     */
+    private formatTokenCount;
+    /**
+     * Build a summary of the completed project for reporting.
+     */
+    private buildCompletionSummary;
+    /**
+     * Approve the architecture and advance to development phase.
+     */
+    approveArchitecture(): void;
+    /**
+     * Get the current orchestration phase.
+     */
+    getPhase(): string;
+    decidePlan(proposalId: string, decision: 'approved' | 'rejected', modifications?: string): void;
+    answerQuestion(questionId: string, answer: string): void;
+    acknowledgeMilestone(milestoneId: string): void;
+    setInteractionMode(mode: InteractionMode): void;
+    getInteractionMode(): InteractionMode;
+    getPendingPlan(): PlanProposal | null;
+    getPendingQuestions(): UserQuestion[];
+    /**
+     * Get processed messages for a specific task (for task detail view).
+     */
+    getTaskMessages(taskId: string): Promise<MessageEnvelope[]>;
+}
+
+interface PlannedTask {
+    title: string;
+    priority: TaskPriority;
+    description: string;
+    dependencies: string[];
+    tags: string[];
+}
+declare class Planner {
+    private model;
+    private workingDirectory;
+    private claudeCommand;
+    private claudeEnv?;
+    private techStack?;
+    constructor(opts: {
+        model?: string;
+        workingDirectory: string;
+        claudeCommand?: string;
+        claudeEnv?: Record<string, string>;
+        techStack?: TechStackConfig;
+    });
+    /**
+     * Use Claude CLI to decompose a goal into a list of planned tasks.
+     */
+    decompose(goal: string): Promise<PlannedTask[]>;
+    /**
+     * Scan a directory recursively and return an indented tree listing.
+     */
+    private scanDirectory;
+    private parseResponse;
+}
+
+/**
+ * TaskPipeline manages the lifecycle of tasks through a multi-stage pipeline:
+ *   plan -> develop -> qa -> review
+ *
+ * Each stage maps to one or more agent roles. When a stage completes, the
+ * pipeline advances the task to the next stage and returns handoff information
+ * so the orchestrator can delegate to the appropriate agent.
+ */
+declare class TaskPipeline {
+    private pipelines;
+    /**
+     * Register a task in the pipeline at a given starting stage.
+     * Tasks tagged with 'architecture' or 'planning' start at 'plan'.
+     * Tasks tagged with 'testing' or 'qa' start at 'qa'.
+     * All others start at 'develop' (they'll skip the plan stage
+     * if they were already created from the planner).
+     */
+    initTask(task: Task, startStage?: PipelineStage): TaskPipelineState;
+    /**
+     * Get the pipeline state for a task.
+     */
+    getState(taskId: string): TaskPipelineState | undefined;
+    /**
+     * Record that an agent has started working on the current stage.
+     */
+    startStage(taskId: string, agentId: string): void;
+    /**
+     * Complete the current stage and return the next stage (if any).
+     * Returns null if the pipeline is finished.
+     */
+    completeStage(taskId: string): {
+        nextStage: PipelineStage | null;
+        requiredRoles: string[];
+        handoffMessage: string;
+    } | null;
+    /**
+     * Mark a stage as failed.
+     */
+    failStage(taskId: string): void;
+    /**
+     * Get the role(s) needed for the current pipeline stage of a task.
+     */
+    getRequiredRoles(taskId: string): AgentRole[];
+    /**
+     * Check if a task has a pipeline registered.
+     */
+    has(taskId: string): boolean;
+    /**
+     * Infer the starting pipeline stage from task tags.
+     */
+    private inferStartStage;
+}
+
+interface TaskAssignment {
+    taskId: string;
+    agentId: string;
+}
+declare class Scheduler {
+    /** Optional pipeline reference for pipeline-aware scheduling. */
+    private pipeline;
+    /**
+     * Set a pipeline reference so the scheduler can use pipeline stage
+     * information when determining which role should handle a task.
+     */
+    setPipeline(pipeline: TaskPipeline): void;
+    /**
+     * Determine which pending tasks should be assigned to which idle agents.
+     *
+     * Rules:
+     * 1. Only consider tasks whose status is 'pending' and whose dependencies are all 'done'.
+     * 2. Only consider agents whose status is 'idle'.
+     * 3. Match tasks to agents by role:
+     *    - If a task has a pipeline state, use the pipeline stage to determine role
+     *    - Otherwise, fall back to tag-based role determination
+     * 4. Assign higher-priority tasks first.
+     * 5. Each agent receives at most one assignment per scheduling cycle.
+     */
+    schedule(tasks: Task[], agents: AgentState[]): TaskAssignment[];
+    /**
+     * Determine the best role for a task.
+     *
+     * If the task has an active pipeline state, the pipeline stage takes
+     * priority over tag-based role determination. This enables the
+     * plan -> develop -> qa -> review handoff sequence.
+     *
+     * Falls back to tag-based determination, then defaults to 'developer'.
+     */
+    private determineRole;
+}
+
+/**
+ * Findings from a PM scan cycle — these are deterministic assessments
+ * that the orchestrator can act on or surface in the activity log.
+ */
+interface PMScanResult {
+    timestamp: string;
+    findings: PMFinding[];
+    summary: string;
+}
+type PMFindingKind = 'blocked-task' | 'stale-task' | 'unassigned-ready-task' | 'agent-idle' | 'agent-errored' | 'dependency-bottleneck' | 'high-priority-waiting' | 'progress-stalled' | 'all-clear';
+interface PMFinding {
+    kind: PMFindingKind;
+    severity: 'info' | 'warning' | 'critical';
+    message: string;
+    taskId?: string;
+    agentId?: string;
+}
+/**
+ * ProjectManagerScanner runs a periodic assessment loop that inspects the
+ * current task board and agent pool, identifies gaps, blockers, stalled
+ * progress, and idle resources, then reports findings via the orchestrator's
+ * activity log and (optionally) sends messages to the relevant agents.
+ *
+ * This is NOT an LLM call — it's deterministic analysis. It runs the PM
+ * role at the *orchestration layer* rather than spawning a Claude subprocess.
+ * For deeper analysis that requires reasoning (e.g., "is this architecture
+ * design good?"), a real PM agent is spawned via the pipeline's `review` stage.
+ */
+declare class ProjectManagerScanner {
+    private intervalId;
+    private scanIntervalMs;
+    private lastScanTasks;
+    private cycleCount;
+    /** Track tasks that have already received a PM message to avoid duplicates. */
+    private messagedTasks;
+    constructor(scanIntervalMs?: number);
+    /**
+     * Start the periodic scan loop.
+     * @param scanFn — called each interval; the orchestrator provides context.
+     */
+    start(scanFn: () => void): void;
+    stop(): void;
+    /**
+     * Run a single scan pass.
+     *
+     * @param tasks   - Current task list
+     * @param agents  - Current agent states (from pool + virtual)
+     * @param phase   - Current orchestrator phase
+     */
+    scan(tasks: Task[], agents: AgentState[], phase: string): PMScanResult;
+    /**
+     * Build messages from PM findings that should be sent to agents.
+     * Only produces messages for actionable findings.
+     * Tracks which tasks have already been messaged to avoid flooding inboxes.
+     */
+    buildMessages(result: PMScanResult): Message[];
+    /**
+     * Clear tracked messages for a task (e.g., when it moves from in-progress
+     * back to pending, allowing a new message if it stalls again later).
+     */
+    clearTrackedTask(taskId: string): void;
+}
+
+declare class FeedbackLoop extends EventEmitter$1 {
+    private mode;
+    private settings;
+    private pendingPlan;
+    private planResolver;
+    private pendingQuestions;
+    private lastProgressReport;
+    private progressTracker;
+    private reachedMilestones;
+    private pendingMilestone;
+    constructor(settings?: Partial<FeedbackSettings>);
+    get interactionMode(): InteractionMode;
+    setMode(mode: InteractionMode): void;
+    /**
+     * Propose a plan for approval.
+     * In unattended mode: auto-approves immediately.
+     * In supervised/interactive: emits plan:proposed and waits for decidePlan() call.
+     */
+    proposePlan(tasks: PlannedTaskSummary[], projectGoal: string): Promise<'approved' | 'rejected'>;
+    decidePlan(proposalId: string, decision: 'approved' | 'rejected', modifications?: string): void;
+    /**
+     * Route a question from an agent to the user.
+     * In unattended mode: returns null immediately (agent should handle itself).
+     * In interactive: emits question:asked and waits for answerQuestion() call with timeout.
+     * In supervised: same as interactive but question is lower priority.
+     */
+    routeQuestion(fromAgent: string, question: string, opts?: {
+        taskId?: string;
+        context?: string;
+        options?: string[];
+    }): Promise<string | null>;
+    answerQuestion(questionId: string, answer: string): void;
+    /**
+     * Called each orchestrator cycle to check progress and emit reports/milestones.
+     */
+    checkProgress(tasks: Task[], stats: OrchestratorStats): void;
+    acknowledgeMilestone(milestoneId: string): void;
+    /**
+     * Clean up all pending timers and resolvers.
+     * Call this during shutdown to prevent leaked timers from blocking process exit.
+     */
+    cleanup(): void;
+    getPendingPlan(): PlanProposal | null;
+    getPendingQuestions(): UserQuestion[];
+}
+
+declare class ProgressTracker {
+    generateReport(tasks: Task[], stats: OrchestratorStats): ProgressReport;
+    getCompletionPercentage(tasks: Task[]): number;
+    detectPhase(tasks: Task[]): string;
+}
+
+/**
+ * Load and validate a project configuration from a YAML file.
+ *
+ * Reads the file at the given path, parses it as YAML, and validates
+ * the result against the project config schema.
+ */
+declare function loadProjectConfig(filePath: string): Promise<ProjectConfig>;
+/**
+ * Validate an unknown value against the project config schema.
+ *
+ * Returns a fully typed ProjectConfig with defaults applied, or
+ * throws a ZodError if validation fails.
+ */
+declare function validateProjectConfig(config: unknown): ProjectConfig;
+
+/**
+ * Manages the runtime directory structure for a Maestro project.
+ *
+ * Ensures all required directories exist and provides absolute path
+ * resolution for todo files, message inboxes/outboxes, and log files.
+ */
+declare class WorkspaceManager {
+    private baseDir;
+    private config;
+    constructor(baseDir: string);
+    /**
+     * Create all runtime directories required by the project.
+     *
+     * This creates the top-level .maestro directory, the messages directory,
+     * the logs directory, and per-agent inbox/outbox directories for every
+     * agent defined in the project config.
+     */
+    initialize(config: ProjectConfig): Promise<void>;
+    /**
+     * Get the absolute path to the project's todo file.
+     */
+    getTodoFilePath(): string;
+    /**
+     * Get the absolute path to the messages directory.
+     */
+    getMessagesDir(): string;
+    /**
+     * Get the absolute path to the logs directory.
+     */
+    getLogsDir(): string;
+    /**
+     * Get the absolute path to a specific agent's log file.
+     */
+    getAgentLogPath(agentId: string): string;
+    /**
+     * Get the absolute path to a specific agent's inbox directory.
+     */
+    getAgentInboxPath(agentId: string): string;
+    /**
+     * Get the absolute path to a specific agent's outbox directory.
+     */
+    getAgentOutboxPath(agentId: string): string;
+}
+
+/**
+ * Create a pino logger that writes only to a log file (if provided).
+ * Console output is intentionally disabled — all user-facing info is
+ * surfaced through orchestrator:activity events and the TUI/CLI handlers.
+ * This avoids pino output bleeding into the terminal and corrupting the TUI.
+ *
+ * Uses synchronous file writes to avoid transport/worker thread issues in Electron.
+ */
+declare function createLogger(name: string, logFile?: string): pino.Logger;
+
+declare function generateId(): string;
+declare function generateTaskId(): string;
+declare function resetTaskCounter(startFrom?: number): void;
+
+export { type AgentConfig, type AgentInfo, AgentPool, AgentProcess, type AgentRole, type AgentRoleConfig, type AgentState, type AgentStatus, type AgentStreamEvent, FeedbackLoop, type FeedbackSettings, InboxWatcher, type InteractionMode, type MaestroEvents, type Message, MessageBroker, type MessageEnvelope, type MessageType, type MilestoneEvent, Orchestrator, type OrchestratorActivity, type OrchestratorActivityKind, type OrchestratorStats, PIPELINE_STAGE_ORDER, PIPELINE_STAGE_ROLES, type PipelineStage, type PlanProposal, type PlannedTask, type PlannedTaskSummary, Planner, type ProgressReport, ProgressTracker, type ProjectCompletionSummary, type ProjectConfig, ProjectManagerScanner, type ProjectSettings, ROLE_DESCRIPTIONS, Scheduler, type Task, type TaskFilter, TaskManager, TaskParser, TaskPipeline, type TaskPipelineState, type TaskPriority, type TaskStatus, type TaskUpdate, TaskWriter, type TechStackConfig, type UserQuestion, WorkspaceManager, createLogger, generateId, generateTaskId, getDefaultSystemPrompt, loadAgentConfigs, loadProjectConfig, resetTaskCounter, validateProjectConfig };