@ai-devkit/agent-manager 0.32.0 → 0.33.1

package/src/runtime/herdr/HerdrAgentRuntime.ts

@@ -0,0 +1,216 @@
+import { HerdrCliClient, isCommandMissing, type HerdrCommandRunner } from "./HerdrCliClient.js";
+import { HerdrRuntimeError } from "./HerdrErrors.js";
+import { parseHerdrRuntimeRef } from "./HerdrRuntimeRef.js";
+import {
+  extractAgentRuntimeRef,
+  extractForegroundProcessInfoPid,
+  extractProcessInfoPid,
+  extractWorkspaceStart,
+} from "./HerdrResponseParsers.js";
+import type {
+  AgentRuntimeAvailability,
+  InteractiveAgentRuntime,
+  RuntimeFocusInput,
+  RuntimeSendInput,
+  RuntimeStartInput,
+  RuntimeStartResult,
+  RuntimeStopInput,
+} from "../types.js";
+
+const AGENT_START_BUSY_RETRY_MS = 5000;
+const AGENT_START_BUSY_RETRY_INTERVAL_MS = 100;
+const PROCESS_INFO_POLL_MS = 3000;
+const PROCESS_INFO_POLL_INTERVAL_MS = 100;
+
+export interface HerdrRuntimeOptions {
+  runner?: HerdrCommandRunner;
+  env?: NodeJS.ProcessEnv;
+  agentStartBusyRetryMs?: number;
+  agentStartBusyRetryIntervalMs?: number;
+  processInfoPollMs?: number;
+  processInfoPollIntervalMs?: number;
+}
+
+export class HerdrAgentRuntime implements InteractiveAgentRuntime {
+  readonly provider = "herdr" as const;
+
+  private readonly client: HerdrCliClient;
+  private readonly env: NodeJS.ProcessEnv;
+  private readonly agentStartBusyRetryMs: number;
+  private readonly agentStartBusyRetryIntervalMs: number;
+  private readonly processInfoPollMs: number;
+  private readonly processInfoPollIntervalMs: number;
+
+  constructor(options: HerdrRuntimeOptions = {}) {
+    this.client = new HerdrCliClient(options.runner);
+    this.env = options.env ?? process.env;
+    this.agentStartBusyRetryMs = options.agentStartBusyRetryMs ?? AGENT_START_BUSY_RETRY_MS;
+    this.agentStartBusyRetryIntervalMs =
+      options.agentStartBusyRetryIntervalMs ?? AGENT_START_BUSY_RETRY_INTERVAL_MS;
+    this.processInfoPollMs = options.processInfoPollMs ?? PROCESS_INFO_POLL_MS;
+    this.processInfoPollIntervalMs =
+      options.processInfoPollIntervalMs ?? PROCESS_INFO_POLL_INTERVAL_MS;
+  }
+
+  async isAvailable(): Promise<AgentRuntimeAvailability> {
+    try {
+      await this.client.run(["--version"]);
+    } catch (error) {
+      if (isCommandMissing(error)) {
+        return {
+          ok: false,
+          reason: "binary-missing",
+          detail: "herdr command was not found in PATH.",
+        };
+      }
+      return {
+        ok: false,
+        reason: "backend-unreachable",
+        detail: (error as Error).message,
+      };
+    }
+
+    try {
+      await this.client.run(["api", "snapshot"]);
+    } catch (error) {
+      return {
+        ok: false,
+        reason: "backend-unreachable",
+        detail: (error as Error).message,
+      };
+    }
+
+    const currentPaneId = nonEmptyString(this.env.HERDR_PANE_ID);
+    return {
+      ok: true,
+      insideRuntime: this.env.HERDR_ENV === "1",
+      ...(currentPaneId ? { currentPaneId } : {}),
+    };
+  }
+
+  async startAgent(input: RuntimeStartInput): Promise<RuntimeStartResult> {
+    const workspace = extractWorkspaceStart(
+      await this.client.runJson(["workspace", "create", "--cwd", input.cwd, "--label", input.name]),
+    );
+
+    const agentResponse = await this.runAgentStartJson([
+      "agent",
+      "start",
+      input.name,
+      "--kind",
+      input.kind,
+      "--pane",
+      workspace.paneId,
+      ...(input.timeoutMs ? ["--timeout", String(input.timeoutMs)] : []),
+      ...(input.args?.length ? ["--", ...input.args] : []),
+    ]);
+    const runtimeRef = extractAgentRuntimeRef(agentResponse, {
+      name: input.name,
+      paneId: workspace.paneId,
+      workspaceId: workspace.workspaceId,
+    });
+    const pid = await this.readStartedAgentPid(runtimeRef.paneId);
+    if (pid === null) {
+      throw new HerdrRuntimeError("Herdr pane process-info response did not include process pid.");
+    }
+
+    return { pid, runtimeRef };
+  }
+
+  async send(input: RuntimeSendInput): Promise<void> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run(["agent", "prompt", ref.paneId, input.prompt]);
+  }
+
+  async wait(input: { runtimeRef: unknown; timeoutMs: number }): Promise<void> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run([
+      "agent",
+      "wait",
+      ref.paneId,
+      "--until",
+      "done",
+      "--until",
+      "blocked",
+      "--timeout",
+      String(input.timeoutMs),
+    ]);
+  }
+
+  async readOutput(input: { runtimeRef: unknown; lines?: number }): Promise<string> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    const { stdout } = await this.client.run([
+      "agent",
+      "read",
+      ref.paneId,
+      "--source",
+      "recent-unwrapped",
+      "--lines",
+      String(input.lines ?? 120),
+    ]);
+    return stdout;
+  }
+
+  async focus(input: RuntimeFocusInput): Promise<boolean> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run(["agent", "focus", ref.paneId]);
+    return true;
+  }
+
+  async stop(input: RuntimeStopInput): Promise<void> {
+    const ref = parseHerdrRuntimeRef(input.runtimeRef);
+    await this.client.run(["pane", "close", ref.paneId]);
+  }
+
+  private async runAgentStartJson(args: string[]): Promise<unknown> {
+    const deadline = Date.now() + this.agentStartBusyRetryMs;
+    let lastBusyError: HerdrRuntimeError | null = null;
+    do {
+      try {
+        return await this.client.runJson(args);
+      } catch (error) {
+        if (!(error instanceof HerdrRuntimeError) || error.code !== "agent_pane_busy") throw error;
+        lastBusyError = error;
+        if (Date.now() >= deadline) break;
+        await sleep(this.agentStartBusyRetryIntervalMs);
+      }
+    } while (Date.now() < deadline);
+    throw (
+      lastBusyError ??
+      new HerdrRuntimeError("Herdr agent start failed because the target pane stayed busy.", {
+        code: "agent_pane_busy",
+      })
+    );
+  }
+
+  private async readStartedAgentPid(paneId: string): Promise<number | null> {
+    const deadline = Date.now() + this.processInfoPollMs;
+    let fallbackPid: number | null = null;
+
+    do {
+      const processInfoResponse = await this.client.runJson([
+        "pane",
+        "process-info",
+        "--pane",
+        paneId,
+      ]);
+      const foregroundPid = extractForegroundProcessInfoPid(processInfoResponse);
+      if (foregroundPid !== null) return foregroundPid;
+      fallbackPid ??= extractProcessInfoPid(processInfoResponse);
+
+      if (Date.now() >= deadline) break;
+      await sleep(this.processInfoPollIntervalMs);
+    } while (Date.now() < deadline);
+
+    return fallbackPid;
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}

package/src/runtime/herdr/HerdrCliClient.ts

@@ -0,0 +1,78 @@
+import { execFile } from "child_process";
+import { promisify } from "util";
+import { HerdrRuntimeError } from "./HerdrErrors.js";
+import { herdrErrorFromResponse } from "./HerdrResponseParsers.js";
+
+const execFileAsync = promisify(execFile);
+
+export interface HerdrCommandResult {
+  stdout: string;
+  stderr: string;
+}
+
+export type HerdrCommandRunner = (command: string, args: string[]) => Promise<HerdrCommandResult>;
+
+export class HerdrCliClient {
+  constructor(private readonly runner: HerdrCommandRunner = defaultRunner) {}
+
+  run(args: string[]): Promise<HerdrCommandResult> {
+    return this.runner("herdr", args);
+  }
+
+  async runJson(args: string[]): Promise<unknown> {
+    let stdout: string;
+    try {
+      ({ stdout } = await this.run(args));
+    } catch (error) {
+      throw parseHerdrCommandError(error);
+    }
+    try {
+      const parsed = JSON.parse(stdout) as unknown;
+      const herdrError = herdrErrorFromResponse(parsed);
+      if (herdrError) throw herdrError;
+      return parsed;
+    } catch (error) {
+      if (error instanceof HerdrRuntimeError) throw error;
+      throw new HerdrRuntimeError(`Herdr returned invalid JSON: ${(error as Error).message}`);
+    }
+  }
+}
+
+export function isCommandMissing(error: unknown): boolean {
+  return Boolean(
+    error &&
+    typeof error === "object" &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ENOENT",
+  );
+}
+
+function defaultRunner(command: string, args: string[]): Promise<HerdrCommandResult> {
+  return execFileAsync(command, args).then(({ stdout, stderr }) => ({ stdout, stderr }));
+}
+
+function parseHerdrCommandError(error: unknown): HerdrRuntimeError {
+  const stdout =
+    typeof error === "object" && error && "stdout" in error
+      ? String((error as { stdout?: unknown }).stdout ?? "")
+      : "";
+  const stderr =
+    typeof error === "object" && error && "stderr" in error
+      ? String((error as { stderr?: unknown }).stderr ?? "")
+      : "";
+  const parsed = parseJson(stdout) ?? parseJson(stderr);
+  if (parsed) {
+    const herdrError = herdrErrorFromResponse(parsed);
+    if (herdrError) return herdrError;
+  }
+  return new HerdrRuntimeError((error as Error).message);
+}
+
+function parseJson(value: string): unknown | null {
+  if (!value.trim()) return null;
+  try {
+    return JSON.parse(value) as unknown;
+  } catch {
+    return null;
+  }
+}

package/src/runtime/herdr/HerdrErrors.ts

@@ -0,0 +1,9 @@
+export class HerdrRuntimeError extends Error {
+  readonly code?: string;
+
+  constructor(message: string, options: { code?: string } = {}) {
+    super(message);
+    this.name = "HerdrRuntimeError";
+    this.code = options.code;
+  }
+}

package/src/runtime/herdr/HerdrResponseParsers.ts

@@ -0,0 +1,86 @@
+import { HerdrRuntimeError } from "./HerdrErrors.js";
+import type { HerdrRuntimeRef } from "./HerdrRuntimeRef.js";
+
+export function extractWorkspaceStart(value: unknown): { workspaceId?: string; paneId: string } {
+  const workspaceId = getString(value, ["result", "workspace", "workspace_id"]);
+  const paneId = getString(value, ["result", "root_pane", "pane_id"]);
+  if (!paneId) {
+    throw new HerdrRuntimeError("Herdr workspace create response did not include root pane id.");
+  }
+  return {
+    ...(workspaceId ? { workspaceId } : {}),
+    paneId,
+  };
+}
+
+export function extractAgentRuntimeRef(
+  value: unknown,
+  fallback: { paneId: string; name: string; workspaceId?: string },
+): HerdrRuntimeRef {
+  const agentPaneId = getString(value, ["result", "agent", "pane_id"]) ?? fallback.paneId;
+  const agentName = getString(value, ["result", "agent", "name"]) ?? fallback.name;
+  const tabId = getString(value, ["result", "agent", "tab_id"]);
+  return {
+    session: "default",
+    ...(fallback.workspaceId ? { workspaceId: fallback.workspaceId } : {}),
+    ...(tabId ? { tabId } : {}),
+    paneId: agentPaneId,
+    agentName,
+  };
+}
+
+export function extractProcessInfoPid(value: unknown): number | null {
+  return extractForegroundProcessInfoPid(value) ?? extractShellPid(value);
+}
+
+export function extractForegroundProcessInfoPid(value: unknown): number | null {
+  const processInfo = getObject(value, ["result", "process_info"]);
+  if (!processInfo) return null;
+  const processes = processInfo.foreground_processes;
+  if (!Array.isArray(processes)) return null;
+  for (const processInfo of processes) {
+    if (!processInfo || typeof processInfo !== "object") continue;
+    const pid = numberOrNull((processInfo as { pid?: unknown }).pid);
+    if (pid !== null) return pid;
+  }
+  return null;
+}
+
+export function extractShellPid(value: unknown): number | null {
+  const processInfo = getObject(value, ["result", "process_info"]);
+  if (!processInfo) return null;
+  return numberOrNull(processInfo.shell_pid);
+}
+
+export function herdrErrorFromResponse(value: unknown): HerdrRuntimeError | null {
+  const error = getObject(value, ["error"]);
+  if (!error) return null;
+  const message = nonEmptyString(error.message) ?? "Herdr command failed.";
+  const code = nonEmptyString(error.code);
+  return new HerdrRuntimeError(message, code ? { code } : {});
+}
+
+function getObject(value: unknown, path: string[]): Record<string, unknown> | null {
+  let current = value;
+  for (const part of path) {
+    if (!current || typeof current !== "object" || Array.isArray(current) || !(part in current))
+      return null;
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current && typeof current === "object" && !Array.isArray(current)
+    ? (current as Record<string, unknown>)
+    : null;
+}
+
+function getString(value: unknown, path: string[]): string | undefined {
+  const parent = getObject(value, path.slice(0, -1));
+  return parent ? nonEmptyString(parent[path[path.length - 1]!]) : undefined;
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function numberOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}

package/src/runtime/herdr/HerdrRuntimeRef.ts

@@ -0,0 +1,41 @@
+import { HerdrRuntimeError } from "./HerdrErrors.js";
+
+export interface HerdrRuntimeRef {
+  session: string;
+  workspaceId?: string;
+  tabId?: string;
+  paneId: string;
+  agentName?: string;
+}
+
+export function parseHerdrRuntimeRef(value: unknown): HerdrRuntimeRef {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new HerdrRuntimeError("Herdr runtime ref is missing or invalid.");
+  }
+  const ref = value as {
+    session?: unknown;
+    workspaceId?: unknown;
+    tabId?: unknown;
+    paneId?: unknown;
+    agentName?: unknown;
+  };
+  const session = nonEmptyString(ref.session) ?? "default";
+  const workspaceId = nonEmptyString(ref.workspaceId);
+  const tabId = nonEmptyString(ref.tabId);
+  const paneId = nonEmptyString(ref.paneId);
+  const agentName = nonEmptyString(ref.agentName);
+  if (!paneId) {
+    throw new HerdrRuntimeError("Herdr runtime ref is missing paneId.");
+  }
+  return {
+    session,
+    paneId,
+    ...(workspaceId ? { workspaceId } : {}),
+    ...(tabId ? { tabId } : {}),
+    ...(agentName ? { agentName } : {}),
+  };
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}

package/src/runtime/tmux/PidPolling.ts

@@ -0,0 +1,34 @@
+import type { TmuxManager } from "../../terminal/TmuxManager.js";
+
+export const DEFAULT_PID_POLL_INTERVAL_MS = 500;
+export const DEFAULT_PID_POLL_TIMEOUT_MS = 15_000;
+const REQUIRED_STABLE_PID_POLLS = 5;
+
+export async function pollForPid(
+  tmux: Pick<TmuxManager, "findAgentPid">,
+  session: string,
+  matches: (psCommand: string) => boolean,
+  intervalMs: number,
+  timeoutMs: number,
+): Promise<number | null> {
+  const deadline = Date.now() + timeoutMs;
+  let candidatePid: number | null = null;
+  let stablePolls = 0;
+
+  while (Date.now() < deadline) {
+    const pid = await tmux.findAgentPid(session, matches);
+    if (pid !== null) {
+      if (pid === candidatePid) {
+        stablePolls += 1;
+      } else {
+        candidatePid = pid;
+        stablePolls = 1;
+      }
+
+      if (stablePolls >= REQUIRED_STABLE_PID_POLLS) return pid;
+    }
+    await new Promise((resolve) => setTimeout(resolve, intervalMs));
+  }
+
+  return null;
+}

package/src/runtime/tmux/TmuxAgentRuntime.ts

@@ -0,0 +1,113 @@
+import { TmuxManager } from "../../terminal/TmuxManager.js";
+import { TtyWriter } from "../../terminal/TtyWriter.js";
+import { AgentPidPollTimeoutError, AgentTerminalNotFoundError } from "../errors.js";
+import { pollForPid } from "./PidPolling.js";
+import { parseTmuxRuntimeRef } from "./TmuxRuntimeRef.js";
+import type {
+  AgentRuntimeAvailability,
+  InteractiveAgentRuntime,
+  RuntimeFocusInput,
+  RuntimeSendDeps,
+  RuntimeSendInput,
+  RuntimeStartInput,
+  RuntimeStartResult,
+  RuntimeStopInput,
+} from "../types.js";
+
+export class TmuxAgentRuntime implements InteractiveAgentRuntime {
+  readonly provider = "tmux" as const;
+  private readonly tmux: TmuxManager;
+
+  constructor(tmux: TmuxManager = new TmuxManager()) {
+    this.tmux = tmux;
+  }
+
+  async isAvailable(): Promise<AgentRuntimeAvailability> {
+    if (await this.tmux.isAvailable()) {
+      return { ok: true, insideRuntime: Boolean(process.env.TMUX) };
+    }
+    return {
+      ok: false,
+      reason: "binary-missing",
+      detail: "tmux is not installed or not in PATH.",
+    };
+  }
+
+  async startAgent(
+    input: RuntimeStartInput & {
+      command?: string;
+      matches?: (psCommand: string) => boolean;
+      pollIntervalMs?: number;
+    },
+  ): Promise<RuntimeStartResult> {
+    if (!input.command || !input.matches || input.pollIntervalMs === undefined) {
+      throw new Error("Tmux start requires command, process matcher, and poll interval.");
+    }
+
+    if (await this.tmux.sessionExists(input.name)) {
+      await this.tmux.killSession(input.name);
+    }
+
+    await this.tmux.createSession(input.name, input.cwd);
+    await this.tmux.sendKeys(input.name, input.command);
+
+    const pid = await pollForPid(
+      this.tmux,
+      input.name,
+      input.matches,
+      input.pollIntervalMs,
+      input.timeoutMs,
+    );
+    if (pid === null) {
+      await this.tmux.killSession(input.name);
+      throw new AgentPidPollTimeoutError(input.name, input.command, input.timeoutMs);
+    }
+
+    return {
+      pid,
+      runtimeRef: { session: input.name },
+    };
+  }
+
+  async send(input: RuntimeSendInput, deps?: RuntimeSendDeps): Promise<void> {
+    if (!deps) {
+      throw new Error("Tmux send requires terminal lookup dependencies.");
+    }
+    const location = await deps.focusManager.findTerminal(input.agent.pid);
+    if (!location) {
+      throw new AgentTerminalNotFoundError(input.agent.name, input.agent.pid);
+    }
+    await (deps.writer ?? TtyWriter.send)(location, input.prompt);
+  }
+
+  async focus(input: RuntimeFocusInput): Promise<boolean> {
+    const location = await input.focusManager.findTerminal(input.agent.pid);
+    if (!location) return false;
+    return await input.focusManager.focusTerminal(location);
+  }
+
+  async stop(input: RuntimeStopInput): Promise<void> {
+    const killProcess = input.killProcess ?? ((pid, signal) => process.kill(pid, signal));
+    try {
+      killProcess(input.agent.pid, "SIGTERM");
+    } catch (error) {
+      if (!isProcessAlreadyGone(error)) {
+        throw error;
+      }
+    }
+
+    const tmuxRef = parseTmuxRuntimeRef(input.runtimeRef);
+    if (tmuxRef) {
+      await this.tmux.killSession(tmuxRef.session);
+    }
+  }
+}
+
+function isProcessAlreadyGone(error: unknown): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === "ESRCH"
+  );
+}

package/src/runtime/tmux/TmuxRuntimeRef.ts

@@ -0,0 +1,9 @@
+export interface TmuxRuntimeRef {
+  session: string;
+}
+
+export function parseTmuxRuntimeRef(value: unknown): TmuxRuntimeRef | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const session = (value as { session?: unknown }).session;
+  return typeof session === "string" && session.trim() ? { session } : null;
+}

package/src/runtime/types.ts

@@ -0,0 +1,56 @@
+import type { AgentInfo } from "../adapters/AgentAdapter.js";
+import type { TerminalLocation } from "../terminal/TerminalFocusManager.js";
+import type { AgentRuntimeProvider } from "../utils/AgentRegistry.js";
+
+export type AgentRuntimeAvailability =
+  | { ok: true; insideRuntime: boolean; currentPaneId?: string }
+  | { ok: false; reason: "binary-missing" | "backend-unreachable"; detail: string };
+
+export interface RuntimeStartInput {
+  name: string;
+  cwd: string;
+  kind: string;
+  args: string[];
+  timeoutMs: number;
+}
+
+export interface RuntimeStartResult {
+  pid: number;
+  runtimeRef: unknown;
+}
+
+export interface RuntimeTargetInput {
+  agent: Pick<AgentInfo, "name" | "pid">;
+  runtimeRef: unknown | null;
+}
+
+export interface RuntimeSendInput extends RuntimeTargetInput {
+  prompt: string;
+}
+
+export interface RuntimeFocusInput extends RuntimeTargetInput {
+  focusManager: {
+    findTerminal(pid: number): Promise<TerminalLocation | null>;
+    focusTerminal(location: TerminalLocation): Promise<boolean>;
+  };
+}
+
+export interface RuntimeStopInput extends RuntimeTargetInput {
+  killProcess?: (pid: number, signal: NodeJS.Signals) => void;
+}
+
+export interface RuntimeSendDeps {
+  focusManager: {
+    findTerminal(pid: number): Promise<TerminalLocation | null>;
+  };
+  writer?: (location: TerminalLocation, text: string) => Promise<void>;
+}
+
+export interface InteractiveAgentRuntime {
+  provider: AgentRuntimeProvider;
+  isAvailable(): Promise<AgentRuntimeAvailability>;
+  startAgent(input: RuntimeStartInput): Promise<RuntimeStartResult>;
+  send(input: RuntimeSendInput, deps?: RuntimeSendDeps): Promise<void>;
+  focus(input: RuntimeFocusInput): Promise<boolean>;
+  stop(input: RuntimeStopInput): Promise<void>;
+}