agent-detective 1.0.0

package/dist/index.js

@@ -0,0 +1,661 @@
+#!/usr/bin/env node
+import {
+  createLimitedConcurrencyTaskQueue,
+  createMemoryTaskQueue,
+  createPluginSystem
+} from "./chunk-OIYJYLCB.js";
+import {
+  APP_NAME,
+  APP_VERSION,
+  applyLogLevelAliasForObservability,
+  createServer,
+  getAgentLabel,
+  listAgents,
+  loadConfig,
+  normalizeAgent
+} from "./chunk-H2IXGHNA.js";
+
+// src/core/event-bus.ts
+var AsyncEventBus = class {
+  constructor(log = console) {
+    this.log = log;
+  }
+  log;
+  handlers = /* @__PURE__ */ new Map();
+  /**
+   * Register a listener for an event.
+   */
+  on(event, handler) {
+    const list = this.handlers.get(event) || [];
+    list.push(handler);
+    this.handlers.set(event, list);
+  }
+  /**
+   * Unregister a listener for an event.
+   */
+  off(event, handler) {
+    const list = this.handlers.get(event) || [];
+    const index = list.indexOf(handler);
+    if (index !== -1) {
+      list.splice(index, 1);
+      if (list.length === 0) {
+        this.handlers.delete(event);
+      } else {
+        this.handlers.set(event, list);
+      }
+    }
+  }
+  /**
+   * Emit an event without waiting for responses (fire-and-forget).
+   */
+  emit(event, ...args) {
+    const list = this.handlers.get(event) || [];
+    for (const handler of list) {
+      try {
+        void handler(...args);
+      } catch (err) {
+        this.log.error(`Error in event handler for ${event}: ${err.message}`);
+      }
+    }
+  }
+  /**
+   * Invoke all handlers asynchronously and gather their return values.
+   * Useful for hook-like behavior where handlers provide data.
+   */
+  async invokeAsync(event, ...args) {
+    const list = this.handlers.get(event) || [];
+    const promises = list.map(async (handler) => {
+      try {
+        return await handler(...args);
+      } catch (err) {
+        this.log.error(
+          `Error in async event handler for ${event}: ${err instanceof Error ? err.message : String(err)}`
+        );
+        return null;
+      }
+    });
+    const results = await Promise.all(promises);
+    return results.filter((r) => r !== null && r !== void 0);
+  }
+};
+function createEventBus(log) {
+  return new AsyncEventBus(log);
+}
+
+// src/core/orchestrator.ts
+import { StandardEvents } from "@agent-detective/sdk";
+
+// src/core/run-records.ts
+import { appendFile } from "fs/promises";
+var RUN_RECORD_SCHEMA = "agent-detective.run-record/v1";
+function createRunRecordWriter(absolutePath, logger) {
+  return {
+    async append(record) {
+      try {
+        await appendFile(absolutePath, `${JSON.stringify(record)}
+`, "utf8");
+      } catch (err) {
+        logger.warn(`runRecords: append failed (${absolutePath}): ${err.message}`);
+      }
+    }
+  };
+}
+function buildRunRecordBase(task) {
+  const issueKey = task.replyTo?.type === "issue" && typeof task.replyTo.id === "string" ? task.replyTo.id : void 0;
+  return {
+    taskId: task.id,
+    ...typeof task.source === "string" && task.source.length > 0 ? { source: task.source } : {},
+    ...issueKey ? { issueKey } : {}
+  };
+}
+
+// src/core/orchestrator.ts
+function createOrchestrator(deps) {
+  const { eventBus, agentRunner, enqueue, logger, maxWallTimeMs, runRecords } = deps;
+  function start() {
+    eventBus.on(StandardEvents.TASK_CREATED, handleTaskCreated);
+  }
+  async function handleTaskCreated(task) {
+    const queueKey = task.id;
+    await enqueue(queueKey, async () => {
+      const startedAt = Date.now();
+      const base = buildRunRecordBase(task);
+      if (runRecords) {
+        await runRecords.append({
+          schema: RUN_RECORD_SCHEMA,
+          phase: "started",
+          ts: (/* @__PURE__ */ new Date()).toISOString(),
+          ...base
+        });
+      }
+      try {
+        const contextPieces = await eventBus.invokeAsync(
+          StandardEvents.TASK_GATHER_CONTEXT,
+          task
+        );
+        let finalPrompt = task.message;
+        if (contextPieces.length > 0) {
+          finalPrompt += "\n\nAdditional Context:\n" + contextPieces.join("\n\n");
+        }
+        const runPromise = agentRunner.runAgentForChat(task.id, finalPrompt, {
+          repoPath: task.context.repoPath,
+          model: task.context.model,
+          cwd: task.context.cwd,
+          readOnly: task.metadata?.readOnly === true,
+          threadId: task.context.threadId ?? void 0
+        });
+        const result = maxWallTimeMs !== void 0 && maxWallTimeMs > 0 ? await raceWithWallTimeout(runPromise, maxWallTimeMs) : await runPromise;
+        eventBus.emit(StandardEvents.TASK_COMPLETED, {
+          event: task,
+          result: result.text
+        });
+        if (runRecords) {
+          await runRecords.append({
+            schema: RUN_RECORD_SCHEMA,
+            phase: "completed",
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            ...base,
+            durationMs: Date.now() - startedAt
+          });
+        }
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        logger.error(`Orchestrator error for task ${task.id}: ${message}`);
+        eventBus.emit(StandardEvents.TASK_FAILED, {
+          event: task,
+          error: message
+        });
+        if (runRecords) {
+          await runRecords.append({
+            schema: RUN_RECORD_SCHEMA,
+            phase: "failed",
+            ts: (/* @__PURE__ */ new Date()).toISOString(),
+            ...base,
+            durationMs: Date.now() - startedAt,
+            error: message
+          });
+        }
+      }
+    });
+  }
+  return {
+    start
+  };
+}
+async function raceWithWallTimeout(work, maxWallTimeMs) {
+  let timeoutId;
+  const timeout = new Promise((_, reject) => {
+    timeoutId = setTimeout(() => {
+      reject(new Error(`Task exceeded orchestrator wall time (${maxWallTimeMs}ms)`));
+    }, maxWallTimeMs);
+  });
+  try {
+    return await Promise.race([work, timeout]);
+  } finally {
+    if (timeoutId !== void 0) clearTimeout(timeoutId);
+  }
+}
+
+// src/core/process.ts
+import {
+  shellQuote,
+  wrapCommandWithPty,
+  terminateChildProcess,
+  execLocal,
+  execLocalStreaming
+} from "@agent-detective/process-utils";
+
+// src/core/agent-runner.ts
+var DEFAULT_TIMEOUT_MS = 12e4;
+var DEFAULT_MAX_BUFFER = 10 * 1024 * 1024;
+function createAgentRunner(options) {
+  const {
+    agentTimeoutMs = DEFAULT_TIMEOUT_MS,
+    agentMaxBuffer = DEFAULT_MAX_BUFFER,
+    execLocal: execLocal2,
+    execLocalStreaming: execLocalStreaming2,
+    terminateChildProcess: terminateChildProcess2,
+    defaultModels,
+    postFinalGraceMs = 3e4,
+    forceKillDelayMs = 1e3,
+    logger: log = console,
+    defaultAgentId
+  } = options;
+  const agents = /* @__PURE__ */ new Map();
+  const activeRuns = /* @__PURE__ */ new Map();
+  const agentSerializationTails = /* @__PURE__ */ new Map();
+  function buildActiveRunKey(taskId, contextKey) {
+    return `${taskId}:${contextKey || "default"}`;
+  }
+  async function acquireAgentSlot(agentId, taskId) {
+    const prev = agentSerializationTails.get(agentId) ?? Promise.resolve();
+    let release;
+    const ours = new Promise((resolve2) => {
+      release = resolve2;
+    });
+    agentSerializationTails.set(agentId, ours);
+    const waitStartedAt = Date.now();
+    await prev;
+    const waitMs = Date.now() - waitStartedAt;
+    if (waitMs > 10) {
+      log.info(
+        `Agent queued task=${taskId} agent=${agentId} singleInstance=true waitMs=${waitMs}`
+      );
+    }
+    return () => {
+      release();
+      if (agentSerializationTails.get(agentId) === ours) {
+        agentSerializationTails.delete(agentId);
+      }
+    };
+  }
+  async function runAgentForChat(taskId, prompt, runOptions = {}) {
+    const {
+      contextKey,
+      repoPath,
+      cwd = process.cwd(),
+      agentId: overrideAgentId,
+      model: modelOverride,
+      onFinal,
+      onProgress,
+      onStdout: callerOnStdout,
+      readOnly,
+      timeoutMs: runTimeoutMs,
+      threadId,
+      inputFiles
+    } = runOptions;
+    const effectiveAgentId = overrideAgentId || defaultAgentId || "opencode";
+    const agent = agents.get(effectiveAgentId);
+    if (!agent) {
+      throw new Error(`Unknown agent: ${effectiveAgentId}. Ensure it is registered.`);
+    }
+    const activeKey = buildActiveRunKey(taskId, contextKey);
+    const releaseAgentSlot = agent.singleInstance ? await acquireAgentSlot(agent.id, taskId) : null;
+    log.info(
+      `Agent start task=${taskId} agent=${effectiveAgentId} repo=${repoPath || "none"}${readOnly ? " readOnly=true" : ""}`
+    );
+    const startedAt = Date.now();
+    const run = {
+      child: null,
+      finalEmitted: false,
+      settled: false,
+      stopPending: false
+    };
+    activeRuns.set(activeKey, run);
+    const schedulePostFinalKill = () => {
+      if (!run.child || run.finalEmitted) return;
+      const delayMs = Math.max(0, Number(postFinalGraceMs) || 0);
+      setTimeout(() => {
+        if (run.settled || !run.child) return;
+        terminateChildProcess2?.(run.child, "SIGTERM");
+        setTimeout(() => {
+          if (run.settled || !run.child) return;
+          terminateChildProcess2?.(run.child, "SIGKILL");
+        }, Math.max(0, Number(forceKillDelayMs) || 0));
+      }, delayMs);
+    };
+    const emitFinal = (text) => {
+      const normalizedText = String(text || "").trim();
+      if (!normalizedText || run.finalEmitted) return;
+      run.finalEmitted = true;
+      onFinal?.(normalizedText);
+      schedulePostFinalKill();
+    };
+    const emitProgress = (payload) => {
+      onProgress?.(payload);
+    };
+    try {
+      const result = await runShellAgent(agent, {
+        prompt,
+        cwd,
+        model: modelOverride,
+        defaultModels,
+        run,
+        emitFinal,
+        emitProgress,
+        callerOnStdout,
+        readOnly,
+        timeoutMs: runTimeoutMs,
+        threadId: threadId && String(threadId).trim() ? String(threadId).trim() : void 0,
+        inputFiles
+      });
+      run.settled = true;
+      const elapsedMs = Date.now() - startedAt;
+      result.usage = { ...result.usage, wallTimeMs: elapsedMs };
+      log.info(`Agent finished task=${taskId} durationMs=${elapsedMs}${result.threadId ? ` threadId=${result.threadId}` : ""}`);
+      return result;
+    } catch (err) {
+      run.settled = true;
+      const elapsedMs = Date.now() - startedAt;
+      log.error(
+        `Agent error task=${taskId} durationMs=${elapsedMs} error=${err.message}`
+      );
+      throw err;
+    } finally {
+      activeRuns.delete(activeKey);
+      releaseAgentSlot?.();
+    }
+  }
+  async function runShellAgent(agent, {
+    prompt,
+    cwd,
+    model,
+    defaultModels: defaultModels2,
+    run,
+    emitFinal,
+    emitProgress,
+    callerOnStdout,
+    readOnly,
+    timeoutMs: shellTimeoutMs,
+    threadId,
+    inputFiles
+  }) {
+    const effectiveTimeoutMs = typeof shellTimeoutMs === "number" && shellTimeoutMs > 0 ? shellTimeoutMs : agentTimeoutMs;
+    const promptBase64 = Buffer.from(prompt, "utf8").toString("base64");
+    const promptExpression = '"$PROMPT"';
+    const effectiveModel = model || defaultModels2?.[agent.id]?.defaultModel || agent.defaultModel;
+    const agentCmd = agent.buildCommand?.({
+      prompt,
+      promptExpression,
+      model: effectiveModel,
+      thinking: void 0,
+      readOnly,
+      threadId,
+      inputFiles
+    }) || `${agent.command} ${promptExpression}`;
+    const command = [
+      `PROMPT_B64=${shellQuote(promptBase64)};`,
+      'PROMPT=$(printf %s "$PROMPT_B64" | base64 --decode);',
+      agentCmd
+    ].join(" ");
+    let commandToRun = command;
+    if (agent.needsPty) {
+      commandToRun = wrapCommandWithPty(commandToRun);
+    }
+    if (agent.mergeStderr) {
+      commandToRun = `${commandToRun} 2>&1`;
+    }
+    const canStream = typeof emitProgress === "function" || typeof agent.parseStreamingOutput === "function";
+    if (canStream) {
+      let streamedOutput = "";
+      await execLocalStreaming2("bash", ["-lc", commandToRun], {
+        timeout: effectiveTimeoutMs,
+        maxBuffer: agentMaxBuffer,
+        cwd,
+        onSpawn: (child) => {
+          run.child = child;
+        },
+        onStdout: (chunk) => {
+          streamedOutput += chunk;
+          callerOnStdout?.(chunk);
+          if (agent.parseStreamingOutput) {
+            const partial = agent.parseStreamingOutput(streamedOutput);
+            if (partial.commentaryMessages?.length) {
+              emitProgress(partial.commentaryMessages);
+            }
+            if (partial.sawFinal && partial.text) {
+              emitFinal(partial.text);
+            }
+          }
+        }
+      });
+      const parsed = agent.parseOutput?.(streamedOutput) || { text: streamedOutput, sawJson: false };
+      return { text: parsed.text || streamedOutput, sawJson: parsed.sawJson, threadId: parsed.threadId, usage: parsed.usage };
+    } else {
+      const output = await execLocal2("bash", ["-lc", commandToRun], {
+        timeout: effectiveTimeoutMs,
+        maxBuffer: agentMaxBuffer,
+        cwd
+      });
+      const parsed = agent.parseOutput?.(output) || { text: output, sawJson: false };
+      if (parsed.text) {
+        emitFinal(parsed.text);
+      }
+      return { text: parsed.text || output, sawJson: parsed.sawJson, threadId: parsed.threadId, usage: parsed.usage };
+    }
+  }
+  return {
+    runAgentForChat,
+    stopActiveRun: async (taskId, contextKey) => {
+      const run = activeRuns.get(buildActiveRunKey(taskId, contextKey));
+      if (!run || run.settled) return { status: "idle" };
+      if (run.stopPending) return { status: "stopping" };
+      run.stopPending = true;
+      terminateChildProcess2?.(run.child, "SIGTERM");
+      return { status: "stopping" };
+    },
+    registerAgent: (agent) => {
+      if (agents.has(agent.id)) {
+        log.warn(`Agent ${agent.id} already registered, overwriting`);
+      }
+      agents.set(agent.id, agent);
+    },
+    listAgents: async () => {
+      const results = [];
+      for (const agent of agents.values()) {
+        const available = agent.checkAvailable ? await agent.checkAvailable() : true;
+        results.push({
+          id: agent.id,
+          label: agent.label,
+          defaultModel: agent.defaultModel,
+          available,
+          needsPty: agent.needsPty,
+          mergeStderr: agent.mergeStderr
+        });
+      }
+      return results;
+    },
+    shutdown: () => {
+      for (const [key, run] of activeRuns) {
+        if (!run.settled && run.child) {
+          log.info(`Shutting down active agent run: ${key}`);
+          terminateChildProcess2?.(run.child, "SIGTERM");
+        }
+      }
+    }
+  };
+}
+
+// src/index.ts
+import { createObservability } from "@agent-detective/observability";
+import { isAbsolute, resolve } from "path";
+import { homedir } from "os";
+function resolveCliArgs(argv) {
+  const args = argv.slice(2);
+  if (args.includes("--help") || args.includes("-h") || args[0] === "help") {
+    return { command: "help" };
+  }
+  if (args.includes("--version") || args[0] === "version") {
+    return { command: "version" };
+  }
+  const command = args[0] === "doctor" ? "doctor" : args[0] === "init" ? "init" : args[0] === "validate-config" || args.includes("--validate-config") ? "validate-config" : "serve";
+  let configRoot;
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--config-root") {
+      configRoot = args[i + 1];
+      i++;
+    } else if (a?.startsWith("--config-root=")) {
+      configRoot = a.slice("--config-root=".length);
+    }
+  }
+  return { command, configRoot };
+}
+function printHelp() {
+  console.log(`${APP_NAME} ${APP_VERSION}
+
+Usage:
+  ${APP_NAME} [--config-root <dir>]              Start server (default)
+  ${APP_NAME} doctor [--config-root <dir>] [--json] [--verbose]
+                                              Validate config/tools/plugins and exit
+  ${APP_NAME} validate-config [--config-root <dir>] [--json] [--verbose]
+                                              Validate config only and exit
+  ${APP_NAME} init [--config-root <dir>] [--repo-path <dir>] [--repo-name <name>]
+                   [--agent <id>] [--force] [--json]
+                                              Scaffold config/local.json for a mock first run
+  ${APP_NAME} --version                         Print version and exit
+  ${APP_NAME} --help                            Print this help and exit
+
+Config:
+  --config-root <dir>     Directory containing config/ (or the config/ dir itself)
+  AGENT_DETECTIVE_CONFIG_ROOT can be used instead of --config-root
+`);
+}
+function resolveInstallRoot(cliConfigRoot) {
+  const expandHome = (value) => {
+    if (value === "~") return homedir();
+    if (value.startsWith("~/")) return resolve(homedir(), value.slice(2));
+    return value;
+  };
+  if (cliConfigRoot) return resolve(expandHome(cliConfigRoot));
+  if (process.env.AGENT_DETECTIVE_CONFIG_ROOT) return resolve(expandHome(process.env.AGENT_DETECTIVE_CONFIG_ROOT));
+  return void 0;
+}
+function resolveConfigDirFromInstallRoot(installRoot) {
+  if (!installRoot) return void 0;
+  if (installRoot.split(/[\\/]/).pop() === "config") return installRoot;
+  return resolve(installRoot, "config");
+}
+async function serve(installRoot) {
+  applyLogLevelAliasForObservability();
+  const configRoot = resolveConfigDirFromInstallRoot(installRoot);
+  const configRootUsed = configRoot ?? resolve(process.cwd(), "config");
+  const config = loadConfig({ configRoot });
+  const observability = createObservability(config.observability || {});
+  const logger = observability.logger;
+  const serverLogger = logger.child("server");
+  serverLogger.info("Starting agent-detective...", {
+    agent: getAgentLabel(config.agent || "opencode"),
+    port: config.port || 3001,
+    configRoot: configRootUsed
+  });
+  const defaultModels = {};
+  let runnerConfig;
+  if (config.agents) {
+    for (const [key, value] of Object.entries(config.agents)) {
+      if (key === "runner") {
+        runnerConfig = value;
+      } else {
+        defaultModels[key] = value;
+      }
+    }
+  }
+  const agentRunner = createAgentRunner({
+    execLocal,
+    execLocalStreaming,
+    terminateChildProcess,
+    defaultModels,
+    agentTimeoutMs: runnerConfig?.timeoutMs,
+    agentMaxBuffer: runnerConfig?.maxBufferBytes,
+    postFinalGraceMs: runnerConfig?.postFinalGraceMs,
+    forceKillDelayMs: runnerConfig?.forceKillDelayMs,
+    logger: logger.child("agent-runner"),
+    defaultAgentId: normalizeAgent(config.agent)
+  });
+  for (const agent of listAgents()) {
+    agentRunner.registerAgent(agent);
+  }
+  const eventBus = createEventBus(logger.child("events"));
+  const memoryQueue = createMemoryTaskQueue(logger.child("task-queue"));
+  const taskQueue = config.tasks?.maxConcurrent !== void 0 && config.tasks.maxConcurrent > 0 ? createLimitedConcurrencyTaskQueue(memoryQueue, config.tasks.maxConcurrent, logger.child("task-queue")) : memoryQueue;
+  const runRecordsPath = config.runRecords?.path !== void 0 && config.runRecords.path.trim().length > 0 ? isAbsolute(config.runRecords.path) ? config.runRecords.path : resolve(configRootUsed, config.runRecords.path) : void 0;
+  const runRecords = runRecordsPath ? createRunRecordWriter(runRecordsPath, logger.child("run-records")) : void 0;
+  const pluginSystem = createPluginSystem({
+    agentRunner,
+    events: eventBus,
+    logger: logger.child("plugin-system"),
+    metrics: observability.metrics,
+    health: observability.health,
+    failOnContractErrors: config.pluginSystem?.failOnContractErrors ?? false,
+    failOnDependencyErrors: config.pluginSystem?.failOnDependencyErrors ?? true,
+    failOnPluginLoadErrors: config.pluginSystem?.failOnPluginLoadErrors ?? true,
+    pathResolutionRoot: installRoot ?? process.cwd(),
+    taskQueue
+  });
+  const enqueue = pluginSystem.enqueue;
+  const orchestrator = createOrchestrator({
+    eventBus,
+    agentRunner,
+    enqueue,
+    logger: logger.child("orchestrator"),
+    maxWallTimeMs: config.tasks?.maxWallTimeMs,
+    runRecords
+  });
+  orchestrator.start();
+  const { app } = await createServer(config, observability, defaultModels, agentRunner, enqueue, {
+    getPluginTags: () => pluginSystem.getPluginTags(),
+    getPluginStatus: () => ({
+      loaded: pluginSystem.getLoadedPlugins().map((p) => `${p.name}@${p.version}`),
+      failures: pluginSystem.getPluginLoadFailures()
+    })
+  });
+  await pluginSystem.loadAll(app, config);
+  const loaded = pluginSystem.getLoadedPlugins();
+  if (loaded.length > 0) {
+    serverLogger.info("Loaded plugins", {
+      plugins: loaded.map((p) => `${p.name}@${p.version}`)
+    });
+  } else {
+    serverLogger.info("No plugins loaded");
+  }
+  const PORT = config.port || 3001;
+  async function gracefulShutdown(signal) {
+    serverLogger.info(`Received ${signal}, shutting down...`);
+    const timeout = setTimeout(() => process.exit(1), 1e4);
+    timeout.unref();
+    await pluginSystem.shutdown();
+    await app.close();
+    agentRunner.shutdown();
+    clearTimeout(timeout);
+    process.exit(0);
+  }
+  process.on("SIGINT", () => {
+    void gracefulShutdown("SIGINT");
+  });
+  process.on("SIGTERM", () => {
+    void gracefulShutdown("SIGTERM");
+  });
+  await app.listen({ port: PORT, host: "0.0.0.0" });
+  serverLogger.info("Server started", {
+    port: PORT,
+    listeningOn: `http://localhost:${PORT}`
+  });
+  const spec = app.swagger();
+  serverLogger.info("Generated OpenAPI spec", {
+    paths: Object.keys(spec.paths ?? {}).length,
+    tags: (spec.tags ?? []).map((t) => t.name).join(", ")
+  });
+}
+async function main() {
+  const cli = resolveCliArgs(process.argv);
+  const installRoot = resolveInstallRoot(cli.configRoot);
+  if (cli.command === "help") {
+    printHelp();
+    return;
+  }
+  if (cli.command === "version") {
+    console.log(APP_VERSION);
+    return;
+  }
+  if (cli.command === "doctor") {
+    const mod = await import("./doctor-3ZMDZLW6.js");
+    await mod.runDoctor({ installRoot, argv: process.argv });
+    return;
+  }
+  if (cli.command === "validate-config") {
+    const mod = await import("./doctor-3ZMDZLW6.js");
+    await mod.runValidateConfig({ installRoot, argv: process.argv });
+    return;
+  }
+  if (cli.command === "init") {
+    const mod = await import("./init-IPCDLNHA.js");
+    await mod.runInit({ installRoot, argv: process.argv });
+    return;
+  }
+  await serve(installRoot);
+}
+void main().catch((err) => {
+  const message = err instanceof Error ? err.message : String(err);
+  console.error(message);
+  process.exit(1);
+});