@doriandev/devcc 0.1.2 → 0.3.0

package/src/devcc/agents/agents.ts

@@ -0,0 +1,292 @@
+import { existsSync } from "node:fs"
+import { isAbsolute } from "node:path"
+import { isActive, type ProcessDefinition, type ProcessStatus } from "../processes/ManagedProcess.js"
+import type { ProcessManager } from "../processes/ProcessManager.js"
+import { DevccError } from "../utils/errors.js"
+import { exec, type ExecOptions, type ExecResult } from "../utils/exec.js"
+import type { ScopedLogger } from "../utils/logger.js"
+
+/**
+ * AI coding agents (Claude Code, Codex, ...).
+ *
+ * An agent is not a new kind of process: an adapter only describes how to run
+ * the agent's CLI non-interactively, and `AgentManager` hands the result to the
+ * project's `ProcessManager`. Status, PID, logs, stop and cleanup on quit all
+ * come from the existing process infrastructure.
+ */
+
+export interface AgentLaunchOptions {
+  /** Working directory - the selected worktree. Must be absolute. */
+  cwd: string
+  /** The task for the agent. */
+  prompt: string
+  /** Branch of the worktree, for display. */
+  branch?: string
+}
+
+export interface AgentAdapter {
+  id: string
+  name: string
+  /** Executable, overridable per machine through config. */
+  command: string
+  /** Whether the CLI is installed and runnable. */
+  detect: () => Promise<boolean>
+  /** argv for a non-interactive run of `prompt`. */
+  args: (prompt: string) => string[]
+  /**
+   * True when `args` puts `--` before the prompt, so a task starting with `-`
+   * cannot be read as an option. Tasks starting with `-` are refused otherwise.
+   */
+  separatesPrompt: boolean
+  /**
+   * argv to start the agent's interactive session with `prompt` as the first
+   * message. Only for agents known to support it (the built-ins).
+   */
+  interactiveArgs?: (prompt: string) => string[]
+}
+
+export interface AgentConfig {
+  /** Display name (defaults per built-in, or to the id). */
+  name?: string
+  /** Executable name or path. */
+  command?: string
+  /** Extra arguments placed before the prompt, e.g. `["--permission-mode", "acceptEdits"]`. */
+  args?: string[]
+  /** Set false to hide a built-in agent. */
+  enabled?: boolean
+}
+
+export interface AgentSession {
+  /** Process id in the ProcessManager, also the log source id. */
+  id: string
+  agentId: string
+  agentName: string
+  cwd: string
+  branch?: string
+  /** First line of the prompt, for display. */
+  task: string
+  status: ProcessStatus
+  pid?: number
+  startedAt: Date
+  exitCode?: number
+}
+
+type Exec = (command: string, args: readonly string[], options?: ExecOptions) => Promise<ExecResult>
+
+interface BuiltinAgent {
+  name: string
+  command: string
+  /** Where the prompt goes relative to the user's extra args. */
+  args: (extra: string[], prompt: string) => string[]
+  /** Interactive session opened with `prompt` as the first message. */
+  interactiveArgs: (extra: string[], prompt: string) => string[]
+}
+
+/**
+ * Non-interactive invocations: `claude -p -- <prompt>` and `codex exec -- <prompt>`.
+ * The `--` matters: without it a task like `--dangerously-skip-permissions`
+ * would be parsed as a flag.
+ */
+export const BUILTIN_AGENTS: Readonly<Record<string, BuiltinAgent>> = {
+  claude: {
+    name: "Claude Code",
+    command: "claude",
+    args: (extra, prompt) => [...extra, "-p", "--", prompt],
+    interactiveArgs: (extra, prompt) => [...extra, "--", prompt],
+  },
+  codex: {
+    name: "Codex",
+    command: "codex",
+    args: (extra, prompt) => ["exec", ...extra, "--", prompt],
+    interactiveArgs: (extra, prompt) => [...extra, "--", prompt],
+  },
+}
+
+/**
+ * Build adapters from config. Built-ins are always present unless disabled;
+ * any other key defines a custom agent whose prompt is the last argument.
+ */
+export function createAgentAdapters(
+  config: Readonly<Record<string, AgentConfig>> = {},
+  run: Exec = exec,
+): AgentAdapter[] {
+  const ids = [...new Set([...Object.keys(BUILTIN_AGENTS), ...Object.keys(config)])]
+  const adapters: AgentAdapter[] = []
+
+  for (const id of ids) {
+    const entry = config[id] ?? {}
+    if (entry.enabled === false) continue
+    const builtin = BUILTIN_AGENTS[id]
+    const command = entry.command ?? builtin?.command
+    if (!command) continue
+
+    const extra = entry.args ?? []
+    adapters.push({
+      id,
+      name: entry.name ?? builtin?.name ?? id,
+      command,
+      detect: async () => {
+        const result = await run(command, ["--version"], { timeoutMs: 3_000 })
+        return result.ok
+      },
+      // Custom agents keep the prompt as the literal last argument (it may be an
+      // option's value, e.g. `--message`), so they cannot take a `--` guard.
+      args: (prompt) => (builtin ? builtin.args(extra, prompt) : [...extra, prompt]),
+      separatesPrompt: builtin !== undefined,
+      interactiveArgs: builtin ? (prompt) => builtin.interactiveArgs(extra, prompt) : undefined,
+    })
+  }
+
+  return adapters
+}
+
+export interface AgentManagerOptions {
+  processes: ProcessManager
+  adapters: readonly AgentAdapter[]
+  logger?: ScopedLogger
+  /** Injected for tests. */
+  exists?: (path: string) => boolean
+}
+
+interface SessionMeta {
+  agentId: string
+  agentName: string
+  cwd: string
+  branch?: string
+  task: string
+  startedAt: Date
+}
+
+export const AGENT_PROCESS_PREFIX = "agent:"
+
+export class AgentManager {
+  private readonly adapters: Map<string, AgentAdapter>
+  private readonly meta = new Map<string, SessionMeta>()
+  /** Detection results, cached for the session: installing a CLI mid-session is rare. */
+  private readonly detected = new Map<string, Promise<boolean>>()
+  private sequence = 0
+
+  constructor(private readonly options: AgentManagerOptions) {
+    this.adapters = new Map(options.adapters.map((adapter) => [adapter.id, adapter]))
+  }
+
+  list(): AgentAdapter[] {
+    return [...this.adapters.values()]
+  }
+
+  get(id: string): AgentAdapter | undefined {
+    return this.adapters.get(id)
+  }
+
+  /** Whether an agent's CLI is installed. `refresh` re-runs the probe. */
+  detect(id: string, refresh = false): Promise<boolean> {
+    const adapter = this.adapters.get(id)
+    if (!adapter) return Promise.resolve(false)
+    let pending = refresh ? undefined : this.detected.get(id)
+    if (!pending) {
+      pending = adapter.detect().catch(() => false)
+      this.detected.set(id, pending)
+    }
+    return pending
+  }
+
+  /**
+   * Start an agent in `options.cwd` as a managed task. Throws a `DevccError`
+   * with an actionable message when the agent is unknown, not installed, or
+   * the directory is missing.
+   */
+  async launch(agentId: string, options: AgentLaunchOptions): Promise<AgentSession> {
+    const adapter = this.adapters.get(agentId)
+    if (!adapter) throw new DevccError({ scope: "process", message: `Unknown agent "${agentId}"` })
+
+    const prompt = options.prompt.trim()
+    if (prompt === "") throw new DevccError({ scope: "process", message: `${adapter.name} needs a task` })
+    if (prompt.startsWith("-") && !adapter.separatesPrompt) {
+      throw new DevccError({
+        scope: "process",
+        message: `${adapter.name}: a task cannot start with "-" (it would be read as an option)`,
+      })
+    }
+
+    const exists = this.options.exists ?? existsSync
+    if (!isAbsolute(options.cwd) || !exists(options.cwd)) {
+      throw new DevccError({ scope: "process", message: `Working directory does not exist: ${options.cwd}` })
+    }
+
+    if (!(await this.detect(agentId, true))) {
+      throw new DevccError({
+        scope: "process",
+        message: `${adapter.name} is not installed (\`${adapter.command}\` was not found)`,
+        detail: `Install it, or point devcc at it with agents.${agentId}.command in .devcc.ts.`,
+      })
+    }
+
+    this.sequence += 1
+    const id = `${AGENT_PROCESS_PREFIX}${agentId}:${this.sequence}`
+    const where = options.branch ?? options.cwd
+    const definition: ProcessDefinition = {
+      id,
+      name: `${adapter.name} · ${where}`,
+      command: adapter.command,
+      args: adapter.args(prompt),
+      cwd: options.cwd,
+      kind: "task",
+    }
+
+    this.meta.set(id, {
+      agentId,
+      agentName: adapter.name,
+      cwd: options.cwd,
+      branch: options.branch,
+      task: prompt.split("\n")[0] ?? prompt,
+      startedAt: new Date(),
+    })
+
+    this.options.processes.register(definition)
+    this.options.logger?.info("agent launch", { agent: agentId, cwd: options.cwd })
+    try {
+      await this.options.processes.start(id)
+    } catch (error) {
+      this.options.logger?.warn("agent launch failed", { agent: agentId, cwd: options.cwd })
+      throw error
+    }
+    return this.session(id) as AgentSession
+  }
+
+  /** Every agent session this manager started, newest first. */
+  sessions(): AgentSession[] {
+    return [...this.meta.keys()]
+      .map((id) => this.session(id))
+      .filter((session): session is AgentSession => session !== undefined)
+      .reverse()
+  }
+
+  async stop(sessionId: string): Promise<void> {
+    await this.options.processes.stop(sessionId)
+  }
+
+  /** Directories where an agent is still running; worktree removal refuses these. */
+  busyPaths(): string[] {
+    return this.sessions()
+      .filter((session) => isActive(session.status))
+      .map((session) => session.cwd)
+  }
+
+  private session(id: string): AgentSession | undefined {
+    const meta = this.meta.get(id)
+    const process = this.options.processes.get(id)
+    if (!meta || !process) return undefined
+    return {
+      id,
+      agentId: meta.agentId,
+      agentName: meta.agentName,
+      cwd: meta.cwd,
+      branch: meta.branch,
+      task: meta.task,
+      status: process.status,
+      pid: process.pid,
+      startedAt: process.startedAt ?? meta.startedAt,
+      exitCode: process.exitCode,
+    }
+  }
+}