@renseiai/agentfactory 0.8.0

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

@@ -0,0 +1,316 @@
+/**
+ * Agent Orchestrator
+ * Spawns concurrent Claude agents to work on Linear backlog issues
+ * Uses the Claude Agent SDK for programmatic control
+ */
+import { type AgentWorkType } from '@renseiai/agentfactory-linear';
+import type { OrchestratorConfig, OrchestratorIssue, AgentProcess, OrchestratorEvents, SpawnAgentOptions, OrchestratorResult, StopAgentResult, ForwardPromptResult, InjectMessageResult, SpawnAgentWithResumeOptions } from './types.js';
+/**
+ * Validate that the git remote origin URL contains the expected repository pattern.
+ * Supports both HTTPS (github.com/org/repo) and SSH (git@github.com:org/repo) formats.
+ *
+ * @param expectedRepo - The expected repository pattern (e.g. 'github.com/renseiai/agentfactory')
+ * @param cwd - Working directory to run git commands in
+ * @throws Error if the git remote does not match the expected repository
+ */
+export declare function validateGitRemote(expectedRepo: string, cwd?: string): void;
+/**
+ * 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;
+    private readonly templateRegistry;
+    private allowedProjects?;
+    private projectPaths?;
+    private sharedPaths?;
+    private linearCli?;
+    private packageManager?;
+    private buildCommand?;
+    private testCommand?;
+    private validateCommand?;
+    private readonly toolRegistry;
+    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;
+    /**
+     * Check if a path is the main git working tree (not a worktree).
+     *
+     * The main working tree has a `.git` directory, while worktrees have a
+     * `.git` file containing a `gitdir:` pointer. This is the primary safeguard
+     * against accidentally destroying the main repository.
+     */
+    private isMainWorktree;
+    /**
+     * Check if a path is inside the configured .worktrees/ directory.
+     *
+     * Only paths within the worktrees directory should ever be candidates for
+     * automated cleanup. This prevents the main repo or other directories from
+     * being targeted.
+     */
+    private isInsideWorktreesDir;
+    /**
+     * 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.
+     *
+     * SAFETY: This method will NEVER clean up the main working tree. It only
+     * operates on paths inside the .worktrees/ directory. This prevents
+     * catastrophic data loss when a branch is checked out in the main tree
+     * (e.g., by a user in their IDE).
+     *
+     * @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;
+    /**
+     * Write helper scripts into the worktree's .agent/ directory.
+     *
+     * Currently writes:
+     * - .agent/add-dep.sh: Safely adds a new dependency by removing symlinked
+     *   node_modules first, then running `pnpm add` with the guard bypass.
+     */
+    private writeWorktreeHelpers;
+    /**
+     * Link dependencies from the main repo into a worktree via symlinks.
+     *
+     * Creates a REAL node_modules directory in the worktree and symlinks each
+     * entry (packages, .pnpm, .bin) individually. This prevents pnpm from
+     * resolving through a directory-level symlink and corrupting the main
+     * repo's node_modules when an agent accidentally runs `pnpm install`.
+     *
+     * For non-Node repos (no node_modules in main repo), this is a no-op.
+     *
+     * Falls back to `pnpm install --frozen-lockfile` if symlinking fails.
+     */
+    linkDependencies(worktreePath: string, identifier: string): void;
+    /**
+     * Create a real node_modules directory and symlink each entry from the source.
+     *
+     * Instead of symlinking the entire node_modules directory (which lets pnpm
+     * resolve through the symlink and corrupt the original), we create a real
+     * directory and symlink each entry individually. If pnpm "recreates" this
+     * directory, it only destroys the worktree's symlinks — not the originals.
+     */
+    private linkNodeModulesContents;
+    /**
+     * Fallback: install dependencies via pnpm install.
+     * Only called when symlinking fails.
+     */
+    private installDependencies;
+    /**
+     * @deprecated Use linkDependencies() instead. This now delegates to linkDependencies.
+     */
+    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, providerSessionId?: 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":"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"}