@supaku/agentfactory 0.1.0

package/dist/src/orchestrator/orchestrator.d.ts

@@ -0,0 +1,246 @@
+/**
+ * Agent Orchestrator
+ * Spawns concurrent Claude agents to work on Linear backlog issues
+ * Uses the Claude Agent SDK for programmatic control
+ */
+import { type AgentWorkType } from '@supaku/agentfactory-linear';
+import type { OrchestratorConfig, OrchestratorIssue, AgentProcess, OrchestratorEvents, SpawnAgentOptions, OrchestratorResult, StopAgentResult, ForwardPromptResult, InjectMessageResult, SpawnAgentWithResumeOptions } from './types';
+/**
+ * Generate a worktree identifier that includes the work type suffix
+ *
+ * @param issueIdentifier - Issue identifier (e.g., "SUP-294")
+ * @param workType - Type of work being performed
+ * @returns Worktree identifier with suffix (e.g., "SUP-294-QA")
+ */
+export declare function getWorktreeIdentifier(issueIdentifier: string, workType: AgentWorkType): string;
+export declare class AgentOrchestrator {
+    private readonly config;
+    private readonly client;
+    private readonly events;
+    private readonly activeAgents;
+    private readonly agentHandles;
+    private provider;
+    private readonly agentSessions;
+    private readonly activityEmitters;
+    private readonly sessionToIssue;
+    private readonly abortControllers;
+    private readonly agentLoggers;
+    private readonly heartbeatWriters;
+    private readonly progressLoggers;
+    private readonly sessionLoggers;
+    constructor(config?: OrchestratorConfig, events?: OrchestratorEvents);
+    /**
+     * Update the last activity timestamp for an agent (for inactivity timeout tracking)
+     * @param issueId - The issue ID of the agent
+     * @param activityType - Optional description of the activity type
+     */
+    private updateLastActivity;
+    /**
+     * Get timeout configuration for a specific work type
+     * @param workType - The work type to get timeout config for
+     * @returns Timeout configuration with inactivity and max session values
+     */
+    private getTimeoutConfig;
+    /**
+     * Get backlog issues for the configured project
+     */
+    getBacklogIssues(limit?: number): Promise<OrchestratorIssue[]>;
+    /**
+     * Validate that a path is a valid git worktree
+     */
+    private validateWorktree;
+    /**
+     * Extract the full error message from an execSync error.
+     *
+     * Node's execSync throws an Error where .message only contains
+     * "Command failed: <command>", but the actual git error output
+     * is in .stderr. This helper combines both for reliable pattern matching.
+     */
+    private getExecSyncErrorMessage;
+    /**
+     * Check if a git error indicates a branch/worktree conflict.
+     *
+     * Git uses different error messages depending on the situation:
+     * - "is already checked out at '/path'" - branch checked out in another worktree
+     * - "is already used by worktree at '/path'" - branch associated with another worktree
+     *
+     * Both mean the same thing: the branch is occupied by another worktree.
+     */
+    private isBranchConflictError;
+    /**
+     * Extract the conflicting worktree path from a git branch conflict error.
+     *
+     * Parses paths like:
+     * - "fatal: 'SUP-402' is already checked out at '/path/to/.worktrees/SUP-402-DEV'"
+     * - "fatal: 'SUP-402' is already used by worktree at '/path/to/.worktrees/SUP-402-DEV'"
+     */
+    private parseConflictingWorktreePath;
+    /**
+     * Attempt to clean up a stale worktree that is blocking branch creation.
+     *
+     * During dev\u2192qa\u2192acceptance handoffs, the prior work type's worktree may still
+     * exist after its agent has finished (the orchestrator cleans up externally,
+     * but there's a race window). This method checks if the blocking worktree's
+     * agent is still alive via heartbeat. If not, it removes the stale worktree
+     * so the new work type can proceed.
+     *
+     * @returns true if the conflicting worktree was cleaned up
+     */
+    private tryCleanupConflictingWorktree;
+    /**
+     * Handle a branch conflict error by attempting to clean up the stale worktree
+     * and retrying, or throwing a retriable error for the worker's retry loop.
+     */
+    private handleBranchConflict;
+    /**
+     * Create a git worktree for an issue with work type suffix
+     *
+     * @param issueIdentifier - Issue identifier (e.g., "SUP-294")
+     * @param workType - Type of work being performed
+     * @returns Object containing worktreePath and worktreeIdentifier
+     */
+    createWorktree(issueIdentifier: string, workType: AgentWorkType): {
+        worktreePath: string;
+        worktreeIdentifier: string;
+    };
+    /**
+     * Clean up a git worktree
+     *
+     * @param worktreeIdentifier - Worktree identifier with work type suffix (e.g., "SUP-294-QA")
+     */
+    removeWorktree(worktreeIdentifier: string): void;
+    /**
+     * Pre-install dependencies in a worktree before spawning an agent.
+     * This prevents agents from wasting time/tokens running pnpm install themselves,
+     * and avoids pathological polling loops when pnpm install is run as a background task.
+     *
+     * @param worktreePath - Absolute path to the worktree
+     * @param identifier - Issue identifier for logging (e.g., "SUP-123")
+     */
+    preInstallDependencies(worktreePath: string, identifier: string): void;
+    /**
+     * Spawn a Claude agent for a specific issue using the Agent SDK
+     */
+    spawnAgent(options: SpawnAgentOptions): AgentProcess;
+    /**
+     * Process the provider event stream and emit activities
+     */
+    private processEventStream;
+    /**
+     * Handle a single normalized agent event from any provider
+     */
+    private handleAgentEvent;
+    /**
+     * Extract GitHub PR URL from text (typically from gh pr create output)
+     */
+    private extractPullRequestUrl;
+    /**
+     * Update the Linear session with the PR URL
+     */
+    private updateSessionPullRequest;
+    /**
+     * Post completion comment with full result message
+     * Uses multi-comment splitting for long messages (up to 10 comments, 10k chars each)
+     */
+    private postCompletionComment;
+    /**
+     * Clean up agent resources
+     */
+    private cleanupAgent;
+    /**
+     * Finalize the session logger with final status
+     */
+    private finalizeSessionLogger;
+    /**
+     * Run the orchestrator - spawn agents for backlog issues
+     */
+    run(): Promise<OrchestratorResult>;
+    /**
+     * Spawn agent for a single issue (webhook-triggered or CLI)
+     * Generates a session ID if not provided to enable autonomous mode
+     *
+     * This method includes crash recovery support:
+     * - If a worktree exists with valid state and stale heartbeat, triggers recovery
+     * - If a worktree exists with fresh heartbeat (agent alive), throws error to prevent duplicates
+     *
+     * @param issueIdOrIdentifier - Issue ID or identifier (e.g., SUP-123)
+     * @param sessionId - Optional Linear session ID
+     * @param workType - Optional work type (auto-detected from issue status if not provided)
+     * @param prompt - Optional custom prompt override
+     */
+    spawnAgentForIssue(issueIdOrIdentifier: string, sessionId?: string, workType?: AgentWorkType, prompt?: string): Promise<AgentProcess>;
+    /**
+     * Get all active agents
+     */
+    getActiveAgents(): AgentProcess[];
+    /**
+     * Stop a running agent by issue ID
+     * @param issueId - The Linear issue ID
+     * @param cleanupWorktree - Whether to remove the git worktree
+     * @param stopReason - Why the agent is being stopped: 'user_request' or 'timeout'
+     */
+    stopAgent(issueId: string, cleanupWorktree?: boolean, stopReason?: 'user_request' | 'timeout'): Promise<StopAgentResult>;
+    /**
+     * Stop a running agent by session ID
+     */
+    stopAgentBySession(sessionId: string, cleanupWorktree?: boolean): Promise<StopAgentResult>;
+    /**
+     * Get agent by session ID
+     */
+    getAgentBySession(sessionId: string): AgentProcess | undefined;
+    /**
+     * Update the worker ID for all active activity emitters.
+     * Called after worker re-registration to ensure activities are attributed
+     * to the new worker ID and pass ownership checks.
+     *
+     * @param newWorkerId - The new worker ID after re-registration
+     */
+    updateWorkerId(newWorkerId: string): void;
+    /**
+     * Forward a follow-up prompt to an existing or new agent
+     *
+     * If the agent is running, attempts to inject the message into the running session
+     * without stopping it. If injection fails or agent isn't running, it will be
+     * stopped gracefully and resumed with the new prompt.
+     *
+     * @param workType - Optional work type. If not provided, inherits from existing agent or defaults to 'development'.
+     */
+    forwardPrompt(issueId: string, sessionId: string, prompt: string, claudeSessionId?: string, workType?: AgentWorkType): Promise<ForwardPromptResult>;
+    /**
+     * Inject a user message into a running agent session without stopping it.
+     *
+     * Uses the SDK's streamInput() method to send follow-up messages to a running session.
+     * This is the preferred method for user follow-ups as it doesn't interrupt agent work.
+     *
+     * @param issueId - The issue ID the agent is working on
+     * @param sessionId - The Linear session ID
+     * @param message - The user message to inject
+     * @returns Result indicating if injection was successful
+     */
+    injectMessage(issueId: string, sessionId: string, message: string): Promise<InjectMessageResult>;
+    /**
+     * Spawn an agent with resume capability for continuing a previous session
+     * If autoTransition is enabled, also transitions the issue status to the appropriate working state
+     */
+    spawnAgentWithResume(options: SpawnAgentWithResumeOptions): Promise<AgentProcess>;
+    /**
+     * Stop all running agents
+     */
+    stopAll(): void;
+    /**
+     * Wait for all agents to complete with inactivity-based timeout
+     *
+     * Unlike a simple session timeout, this method monitors each agent's activity
+     * and only stops agents that have been inactive for longer than the inactivity
+     * timeout. Active agents are allowed to run indefinitely (unless maxSessionTimeoutMs
+     * is set as a hard cap).
+     *
+     * @param inactivityTimeoutMsOverride - Override inactivity timeout from config (for backwards compatibility)
+     */
+    waitForAll(inactivityTimeoutMsOverride?: number): Promise<AgentProcess[]>;
+}
+/**
+ * Create an orchestrator instance
+ */
+export declare function createOrchestrator(config?: OrchestratorConfig, events?: OrchestratorEvents): AgentOrchestrator;
+//# sourceMappingURL=orchestrator.d.ts.map

package/dist/src/orchestrator/orchestrator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/orchestrator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA+BH,OAAO,EAML,KAAK,aAAa,EAMnB,MAAM,6BAA6B,CAAA;AAKpC,OAAO,KAAK,EACV,kBAAkB,EAClB,iBAAiB,EACjB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAElB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,2BAA2B,EAC5B,MAAM,SAAS,CAAA;AA0kBhB;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,aAAa,GACtB,MAAM,CAGR;AAED,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAMtB;IACD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAoB;IAC3C,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAuC;IACpE,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAe;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAuC;IACrE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA+D;IAEhG,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAiC;IAEhE,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0C;IAE3E,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAiC;IAE9D,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAA0C;IAE3E,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAyC;IAEzE,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAwC;gBAE3D,MAAM,GAAE,kBAAuB,EAAE,MAAM,GAAE,kBAAuB;IAoC5E;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAQ1B;;;;OAIG;IACH,OAAO,CAAC,gBAAgB;IAkBxB;;OAEG;IACG,gBAAgB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,EAAE,CAAC;IAiDpE;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA2BxB;;;;;;OAMG;IACH,OAAO,CAAC,uBAAuB;IAiB/B;;;;;;;;OAQG;IACH,OAAO,CAAC,qBAAqB;IAK7B;;;;;;OAMG;IACH,OAAO,CAAC,4BAA4B;IAMpC;;;;;;;;;;OAUG;IACH,OAAO,CAAC,6BAA6B;IAwDrC;;;OAGG;IACH,OAAO,CAAC,oBAAoB;IAkB5B;;;;;;OAMG;IACH,cAAc,CACZ,eAAe,EAAE,MAAM,EACvB,QAAQ,EAAE,aAAa,GACtB;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,kBAAkB,EAAE,MAAM,CAAA;KAAE;IA0JvD;;;;OAIG;IACH,cAAc,CAAC,kBAAkB,EAAE,MAAM,GAAG,IAAI;IA4BhD;;;;;;;OAOG;IACH,sBAAsB,CAAC,YAAY,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IA+BtE;;OAEG;IACH,UAAU,CAAC,OAAO,EAAE,iBAAiB,GAAG,YAAY;IA+NpD;;OAEG;YACW,kBAAkB;IAqOhC;;OAEG;YACW,gBAAgB;IA6O9B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAO7B;;OAEG;YACW,wBAAwB;IAiDtC;;;OAGG;YACW,qBAAqB;IA+DnC;;OAEG;IACH,OAAO,CAAC,YAAY;IA8BpB;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAW7B;;OAEG;IACG,GAAG,IAAI,OAAO,CAAC,kBAAkB,CAAC;IA4DxC;;;;;;;;;;;;OAYG;IACG,kBAAkB,CACtB,mBAAmB,EAAE,MAAM,EAC3B,SAAS,CAAC,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,aAAa,EACxB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,YAAY,CAAC;IAuGxB;;OAEG;IACH,eAAe,IAAI,YAAY,EAAE;IAMjC;;;;;OAKG;IACG,SAAS,CACb,OAAO,EAAE,MAAM,EACf,eAAe,UAAQ,EACvB,UAAU,GAAE,cAAc,GAAG,SAA0B,GACtD,OAAO,CAAC,eAAe,CAAC;IA4D3B;;OAEG;IACG,kBAAkB,CAAC,SAAS,EAAE,MAAM,EAAE,eAAe,UAAQ,GAAG,OAAO,CAAC,eAAe,CAAC;IAS9F;;OAEG;IACH,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS;IAM9D;;;;;;OAMG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI;IAgBzC;;;;;;;;OAQG;IACG,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,eAAe,CAAC,EAAE,MAAM,EACxB,QAAQ,CAAC,EAAE,aAAa,GACvB,OAAO,CAAC,mBAAmB,CAAC;IAiH/B;;;;;;;;;;OAUG;IACG,aAAa,CACjB,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,mBAAmB,CAAC;IAqD/B;;;OAGG;IACG,oBAAoB,CAAC,OAAO,EAAE,2BAA2B,GAAG,OAAO,CAAC,YAAY,CAAC;IAuNvF;;OAEG;IACH,OAAO,IAAI,IAAI;IAkBf;;;;;;;;;OASG;IACG,UAAU,CAAC,2BAA2B,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,EAAE,CAAC;CA8DhF;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,CAAC,EAAE,kBAAkB,EAC3B,MAAM,CAAC,EAAE,kBAAkB,GAC1B,iBAAiB,CAEnB"}