claude-code-controller 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,523 @@
+import { EventEmitter } from 'node:events';
+import { ChildProcess } from 'node:child_process';
+
+interface InboxMessage {
+    from: string;
+    text: string;
+    timestamp: string;
+    color?: string;
+    read: boolean;
+    summary?: string;
+}
+type StructuredMessage = TaskAssignmentMessage | ShutdownRequestMessage | ShutdownApprovedMessage | IdleNotificationMessage | PlanApprovalRequestMessage | PlanApprovalResponseMessage | PermissionRequestMessage | PermissionResponseMessage | PlainTextMessage;
+interface TaskAssignmentMessage {
+    type: "task_assignment";
+    taskId: string;
+    subject: string;
+    description: string;
+    assignedBy: string;
+    timestamp: string;
+}
+interface ShutdownRequestMessage {
+    type: "shutdown_request";
+    requestId: string;
+    from: string;
+    reason?: string;
+    timestamp: string;
+}
+interface ShutdownApprovedMessage {
+    type: "shutdown_approved";
+    requestId: string;
+    from: string;
+    timestamp: string;
+    paneId?: string;
+    backendType?: string;
+}
+interface IdleNotificationMessage {
+    type: "idle_notification";
+    from: string;
+    timestamp: string;
+    idleReason: string;
+}
+interface PlanApprovalRequestMessage {
+    type: "plan_approval_request";
+    requestId: string;
+    from: string;
+    planContent?: string;
+    timestamp: string;
+}
+interface PlanApprovalResponseMessage {
+    type: "plan_approval_response";
+    requestId: string;
+    from: string;
+    approved: boolean;
+    feedback?: string;
+    timestamp: string;
+}
+interface PermissionRequestMessage {
+    type: "permission_request";
+    requestId: string;
+    from: string;
+    toolName: string;
+    toolUseId?: string;
+    description: string;
+    input?: unknown;
+    permissionSuggestions?: string[];
+    timestamp: string;
+}
+interface PermissionResponseMessage {
+    type: "permission_response";
+    requestId: string;
+    from: string;
+    approved: boolean;
+    timestamp: string;
+}
+interface PlainTextMessage {
+    type: "plain_text";
+    text: string;
+}
+interface TeamConfig {
+    name: string;
+    description?: string;
+    createdAt: number;
+    leadAgentId: string;
+    leadSessionId: string;
+    members: TeamMember[];
+}
+interface TeamMember {
+    agentId: string;
+    name: string;
+    agentType: string;
+    model?: string;
+    joinedAt: number;
+    tmuxPaneId?: string;
+    cwd: string;
+    subscriptions?: string[];
+}
+interface TaskFile {
+    id: string;
+    subject: string;
+    description: string;
+    activeForm?: string;
+    owner?: string;
+    status: TaskStatus;
+    blocks: string[];
+    blockedBy: string[];
+    metadata?: Record<string, unknown>;
+}
+type TaskStatus = "pending" | "in_progress" | "completed";
+type AgentType = "general-purpose" | "Bash" | "Explore" | "Plan" | string;
+interface SpawnAgentOptions {
+    name: string;
+    type?: AgentType;
+    model?: string;
+    cwd?: string;
+    prompt?: string;
+    permissions?: string[];
+    /** Environment variables to inject into the agent's process */
+    env?: Record<string, string>;
+}
+interface ControllerOptions {
+    teamName?: string;
+    cwd?: string;
+    claudeBinary?: string;
+    logger?: Logger;
+    /** Default environment variables for all spawned agents */
+    env?: Record<string, string>;
+}
+interface ReceiveOptions {
+    timeout?: number;
+    pollInterval?: number;
+    /** If true, return all unread messages, not just the first one */
+    all?: boolean;
+}
+interface ControllerEvents {
+    message: [agentName: string, message: InboxMessage];
+    idle: [agentName: string];
+    "shutdown:approved": [agentName: string, message: ShutdownApprovedMessage];
+    "plan:approval_request": [agentName: string, message: PlanApprovalRequestMessage];
+    "permission:request": [agentName: string, message: PermissionRequestMessage];
+    "task:completed": [task: TaskFile];
+    "agent:spawned": [agentName: string, pid: number];
+    "agent:exited": [agentName: string, code: number | null];
+    error: [error: Error];
+}
+type LogLevel = "debug" | "info" | "warn" | "error" | "silent";
+interface Logger {
+    debug(msg: string, ...args: unknown[]): void;
+    info(msg: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+}
+
+declare class TeamManager {
+    readonly teamName: string;
+    readonly sessionId: string;
+    private log;
+    constructor(teamName: string, logger: Logger);
+    /**
+     * Create the team directory structure and config.json.
+     * The controller registers itself as the lead member.
+     */
+    create(opts?: {
+        description?: string;
+        cwd?: string;
+    }): Promise<TeamConfig>;
+    /**
+     * Add a member to the team config.
+     */
+    addMember(member: TeamMember): Promise<void>;
+    /**
+     * Remove a member from the team config.
+     */
+    removeMember(name: string): Promise<void>;
+    /**
+     * Read the current team config.
+     */
+    getConfig(): Promise<TeamConfig>;
+    /**
+     * Check if the team already exists on disk.
+     */
+    exists(): boolean;
+    /**
+     * Destroy the team: remove all team directories and task directories.
+     */
+    destroy(): Promise<void>;
+    private writeConfig;
+}
+
+declare class TaskManager {
+    private teamName;
+    private log;
+    private nextId;
+    constructor(teamName: string, log: Logger);
+    /**
+     * Initialize the task directory. Call after team creation.
+     * Also scans for existing tasks to set the next ID correctly.
+     */
+    init(): Promise<void>;
+    /**
+     * Create a new task. Returns the assigned task ID.
+     */
+    create(task: Omit<TaskFile, "id" | "blocks" | "blockedBy" | "status"> & {
+        blocks?: string[];
+        blockedBy?: string[];
+        status?: TaskStatus;
+    }): Promise<string>;
+    /**
+     * Get a task by ID.
+     */
+    get(taskId: string): Promise<TaskFile>;
+    /**
+     * Update a task. Merges the provided fields.
+     */
+    update(taskId: string, updates: Partial<Pick<TaskFile, "subject" | "description" | "activeForm" | "owner" | "status" | "blocks" | "blockedBy" | "metadata">>): Promise<TaskFile>;
+    /**
+     * Add blocking relationships.
+     */
+    addBlocks(taskId: string, blockedTaskIds: string[]): Promise<void>;
+    /**
+     * List all tasks.
+     */
+    list(): Promise<TaskFile[]>;
+    /**
+     * Delete a task file.
+     */
+    delete(taskId: string): Promise<void>;
+    /**
+     * Wait for a task to reach a target status.
+     */
+    waitFor(taskId: string, targetStatus?: TaskStatus, opts?: {
+        timeout?: number;
+        pollInterval?: number;
+    }): Promise<TaskFile>;
+    private writeTask;
+}
+
+/**
+ * Interface for the controller methods that AgentHandle needs.
+ * This avoids a circular dependency with the full controller.
+ */
+interface AgentController {
+    send(agentName: string, message: string, summary?: string): Promise<void>;
+    receive(agentName: string, opts?: ReceiveOptions): Promise<InboxMessage[]>;
+    killAgent(agentName: string): Promise<void>;
+    sendShutdownRequest(agentName: string): Promise<void>;
+    isAgentRunning(agentName: string): boolean;
+}
+/**
+ * Proxy object for interacting with a specific agent.
+ */
+declare class AgentHandle {
+    readonly name: string;
+    readonly pid: number | undefined;
+    private controller;
+    constructor(controller: AgentController, name: string, pid: number | undefined);
+    /**
+     * Send a message to this agent.
+     */
+    send(message: string, summary?: string): Promise<void>;
+    /**
+     * Wait for a response from this agent.
+     * Returns the text of the first unread plain-text message.
+     */
+    receive(opts?: ReceiveOptions): Promise<string>;
+    /**
+     * Send a message and wait for the response. Convenience method.
+     */
+    ask(question: string, opts?: ReceiveOptions): Promise<string>;
+    /**
+     * Check if the agent process is still running.
+     */
+    get isRunning(): boolean;
+    /**
+     * Request the agent to shut down gracefully.
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Force-kill the agent process.
+     */
+    kill(): Promise<void>;
+    /**
+     * Async iterator for agent events (messages from this agent).
+     * Polls the controller's inbox for messages from this agent.
+     */
+    events(opts?: {
+        pollInterval?: number;
+        timeout?: number;
+    }): AsyncGenerator<InboxMessage>;
+}
+
+declare class ClaudeCodeController extends EventEmitter<ControllerEvents> implements AgentController {
+    readonly teamName: string;
+    readonly team: TeamManager;
+    readonly tasks: TaskManager;
+    private processes;
+    private poller;
+    private log;
+    private cwd;
+    private claudeBinary;
+    private defaultEnv;
+    private colorIndex;
+    private initialized;
+    constructor(opts?: ControllerOptions & {
+        logLevel?: LogLevel;
+    });
+    /**
+     * Initialize the controller: create the team and start polling.
+     * Must be called before any other operations.
+     */
+    init(): Promise<this>;
+    /**
+     * Graceful shutdown:
+     * 1. Send shutdown requests to all agents
+     * 2. Wait briefly for acknowledgment
+     * 3. Kill remaining processes
+     * 4. Clean up team files
+     */
+    shutdown(): Promise<void>;
+    /**
+     * Spawn a new Claude Code agent.
+     */
+    spawnAgent(opts: SpawnAgentOptions): Promise<AgentHandle>;
+    /**
+     * Send a message to a specific agent.
+     */
+    send(agentName: string, message: string, summary?: string): Promise<void>;
+    /**
+     * Send a structured shutdown request to an agent.
+     */
+    sendShutdownRequest(agentName: string): Promise<void>;
+    /**
+     * Broadcast a message to all registered agents (except controller).
+     */
+    broadcast(message: string, summary?: string): Promise<void>;
+    /**
+     * Wait for messages from a specific agent.
+     * Polls the controller's inbox for messages from the given agent.
+     *
+     * Returns when:
+     * - A non-idle message is received (SendMessage from agent), OR
+     * - An idle_notification is received (agent finished its turn),
+     *   in which case the idle message is returned.
+     */
+    receive(agentName: string, opts?: ReceiveOptions): Promise<InboxMessage[]>;
+    /**
+     * Wait for any message from any agent.
+     */
+    receiveAny(opts?: ReceiveOptions): Promise<InboxMessage>;
+    /**
+     * Create a task and optionally notify the assigned agent.
+     */
+    createTask(task: Omit<TaskFile, "id" | "blocks" | "blockedBy" | "status"> & {
+        blocks?: string[];
+        blockedBy?: string[];
+        status?: TaskStatus;
+    }): Promise<string>;
+    /**
+     * Assign a task to an agent.
+     */
+    assignTask(taskId: string, agentName: string): Promise<void>;
+    /**
+     * Approve or reject a teammate's plan.
+     * Send this in response to a `plan:approval_request` event.
+     */
+    sendPlanApproval(agentName: string, requestId: string, approve: boolean, feedback?: string): Promise<void>;
+    /**
+     * Approve or reject a teammate's permission/tool-use request.
+     * Send this in response to a `permission:request` event.
+     */
+    sendPermissionResponse(agentName: string, requestId: string, approve: boolean): Promise<void>;
+    /**
+     * Wait for a task to be completed.
+     */
+    waitForTask(taskId: string, timeout?: number): Promise<TaskFile>;
+    /**
+     * Check if an agent process is still running.
+     */
+    isAgentRunning(name: string): boolean;
+    /**
+     * Kill a specific agent.
+     */
+    killAgent(name: string): Promise<void>;
+    /**
+     * Get the installed Claude Code version.
+     */
+    getClaudeVersion(): string | null;
+    /**
+     * Verify that the required CLI flags exist in the installed version.
+     */
+    verifyCompatibility(): {
+        compatible: boolean;
+        version: string | null;
+    };
+    private handlePollEvents;
+    private ensureInitialized;
+}
+
+interface SpawnOptions {
+    teamName: string;
+    agentName: string;
+    agentId: string;
+    agentType?: string;
+    model?: string;
+    cwd?: string;
+    parentSessionId?: string;
+    color?: string;
+    claudeBinary?: string;
+    permissions?: string[];
+    teammateMode?: "auto" | "tmux" | "in-process";
+    /** Extra environment variables to inject into the agent process */
+    env?: Record<string, string>;
+}
+/**
+ * Manages Claude Code agent processes.
+ * Spawns agents inside a Python-based PTY wrapper since the Claude Code TUI
+ * binary requires a real terminal to function.
+ */
+declare class ProcessManager {
+    private processes;
+    private log;
+    constructor(logger: Logger);
+    /**
+     * Spawn a new claude CLI process in teammate mode.
+     * Uses a Python PTY wrapper to provide the terminal the TUI needs.
+     */
+    spawn(opts: SpawnOptions): ChildProcess;
+    /**
+     * Register a callback for when an agent process exits.
+     */
+    onExit(name: string, callback: (code: number | null) => void): void;
+    /**
+     * Get the process for a named agent.
+     */
+    get(name: string): ChildProcess | undefined;
+    /**
+     * Check if an agent process is still running.
+     */
+    isRunning(name: string): boolean;
+    /**
+     * Get the PID of a running agent.
+     */
+    getPid(name: string): number | undefined;
+    /**
+     * Kill a specific agent process.
+     */
+    kill(name: string, signal?: NodeJS.Signals): Promise<void>;
+    /**
+     * Kill all agent processes.
+     */
+    killAll(): Promise<void>;
+    /**
+     * Get all running agent names.
+     */
+    runningAgents(): string[];
+}
+
+interface PollEvent {
+    raw: InboxMessage;
+    parsed: StructuredMessage;
+}
+/**
+ * Polls an agent's inbox for new messages.
+ * Used by the controller to watch its own inbox for responses from agents.
+ */
+declare class InboxPoller {
+    private teamName;
+    private agentName;
+    private interval;
+    private timer;
+    private log;
+    private handlers;
+    constructor(teamName: string, agentName: string, logger: Logger, opts?: {
+        pollInterval?: number;
+    });
+    /**
+     * Register a handler for new messages.
+     */
+    onMessages(handler: (events: PollEvent[]) => void): void;
+    /**
+     * Start polling.
+     */
+    start(): void;
+    /**
+     * Stop polling.
+     */
+    stop(): void;
+    /**
+     * Poll once for new messages.
+     */
+    poll(): Promise<PollEvent[]>;
+}
+
+/**
+ * Write a message to an agent's inbox with file-locking.
+ */
+declare function writeInbox(teamName: string, agentName: string, message: Omit<InboxMessage, "read">, logger?: Logger): Promise<void>;
+/**
+ * Read all messages from an agent's inbox.
+ */
+declare function readInbox(teamName: string, agentName: string): Promise<InboxMessage[]>;
+/**
+ * Read unread messages from an agent's inbox and mark them as read.
+ */
+declare function readUnread(teamName: string, agentName: string): Promise<InboxMessage[]>;
+/**
+ * Parse a structured message from an inbox message's text field.
+ * Messages can be either JSON-encoded structured messages or plain text.
+ */
+declare function parseMessage(msg: InboxMessage): StructuredMessage;
+
+declare function teamsDir(): string;
+declare function teamDir(teamName: string): string;
+declare function teamConfigPath(teamName: string): string;
+declare function inboxesDir(teamName: string): string;
+declare function inboxPath(teamName: string, agentName: string): string;
+declare function tasksBaseDir(): string;
+declare function tasksDir(teamName: string): string;
+declare function taskPath(teamName: string, taskId: string): string;
+
+declare function createLogger(level?: LogLevel): Logger;
+declare const silentLogger: Logger;
+
+export { AgentHandle, type AgentType, ClaudeCodeController, type ControllerEvents, type ControllerOptions, type IdleNotificationMessage, type InboxMessage, InboxPoller, type LogLevel, type Logger, type PermissionRequestMessage, type PermissionResponseMessage, type PlainTextMessage, type PlanApprovalRequestMessage, type PlanApprovalResponseMessage, ProcessManager, type ReceiveOptions, type ShutdownApprovedMessage, type ShutdownRequestMessage, type SpawnAgentOptions, type StructuredMessage, type TaskAssignmentMessage, type TaskFile, TaskManager, type TaskStatus, type TeamConfig, TeamManager, type TeamMember, createLogger, inboxPath, inboxesDir, parseMessage, readInbox, readUnread, silentLogger, taskPath, tasksBaseDir, tasksDir, teamConfigPath, teamDir, teamsDir, writeInbox };