@ai-devkit/agent-manager 0.32.0 → 0.33.1

package/src/runtime/ManagedAgentRuntime.ts

@@ -0,0 +1,266 @@
+import type { AgentInfo } from "../adapters/AgentAdapter.js";
+import type { TerminalLocation } from "../terminal/TerminalFocusManager.js";
+import { TmuxManager } from "../terminal/TmuxManager.js";
+import {
+  AgentRegistry,
+  type AgentRuntimeProvider,
+  type RegistryEntry,
+} from "../utils/AgentRegistry.js";
+import { AGENTS, type StartableAgentType } from "../utils/agents.js";
+import { createInteractiveRuntime } from "./RuntimeFactory.js";
+import { DEFAULT_PID_POLL_INTERVAL_MS, DEFAULT_PID_POLL_TIMEOUT_MS } from "./tmux/PidPolling.js";
+import { TmuxAgentRuntime } from "./tmux/TmuxAgentRuntime.js";
+import type { InteractiveAgentRuntime } from "./types.js";
+import {
+  AgentNameInUseError,
+  AgentPidPollTimeoutError,
+  AgentRuntimeUnavailableError,
+  AgentTerminalNotFoundError,
+  TmuxUnavailableError,
+} from "./errors.js";
+
+export {
+  AgentNameInUseError,
+  AgentPidPollTimeoutError,
+  AgentRuntimeUnavailableError,
+  AgentTerminalNotFoundError,
+  TmuxUnavailableError,
+};
+export { DEFAULT_PID_POLL_INTERVAL_MS, DEFAULT_PID_POLL_TIMEOUT_MS };
+
+export interface StartAgentOptions {
+  type: StartableAgentType;
+  name: string;
+  cwd: string;
+  runtimeProvider?: AgentRuntimeProvider;
+  pollIntervalMs?: number;
+  pollTimeoutMs?: number;
+}
+
+export interface StartAgentDeps {
+  tmux?: TmuxManager;
+  runtime?: InteractiveAgentRuntime;
+  registry?: AgentRegistry;
+  /** Called for non-fatal events (e.g., replacing an orphan tmux session). */
+  onWarning?: (message: string) => void;
+}
+
+export interface StopAgentDeps {
+  tmux?: Pick<TmuxManager, "killSession">;
+  runtime?: InteractiveAgentRuntime;
+  registry?: Pick<AgentRegistry, "lookup">;
+  killProcess?: (pid: number, signal: NodeJS.Signals) => void;
+}
+
+export interface StopAgentResult {
+  agentName: string;
+  pid: number;
+  runtime: AgentRuntimeProvider;
+  runtimeRef: unknown | null;
+}
+
+export interface FocusAgentDeps {
+  runtime?: InteractiveAgentRuntime;
+  registry?: Pick<AgentRegistry, "lookup">;
+  focusManager: {
+    findTerminal(pid: number): Promise<TerminalLocation | null>;
+    focusTerminal(location: TerminalLocation): Promise<boolean>;
+  };
+}
+
+export type FocusAgentResult =
+  | { focused: true }
+  | { focused: false; reason: "terminal-not-found" | "focus-failed" };
+
+export interface SendAgentPromptDeps {
+  runtime?: InteractiveAgentRuntime;
+  registry?: Pick<AgentRegistry, "lookup">;
+  focusManager: {
+    findTerminal(pid: number): Promise<TerminalLocation | null>;
+  };
+  writer?: (location: TerminalLocation, text: string) => Promise<void>;
+}
+
+/**
+ * Orchestrate `agent start`: ensure the configured runtime is available,
+ * create the runtime session, detect the agent PID, and register the entry.
+ * Callers are responsible for user input validation before invoking this.
+ */
+export async function startAgent(
+  opts: StartAgentOptions,
+  deps: StartAgentDeps = {},
+): Promise<RegistryEntry> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const agent = AGENTS[opts.type];
+  const intervalMs = opts.pollIntervalMs ?? DEFAULT_PID_POLL_INTERVAL_MS;
+  const timeoutMs = opts.pollTimeoutMs ?? DEFAULT_PID_POLL_TIMEOUT_MS;
+  const provider = opts.runtimeProvider ?? deps.runtime?.provider ?? "tmux";
+  const tmux = provider === "tmux" ? (deps.tmux ?? new TmuxManager()) : undefined;
+  const runtime = resolveStartRuntime(provider, { ...deps, tmux });
+
+  const availability = await runtime.isAvailable();
+  if (!availability.ok) {
+    if (provider === "tmux") throw new TmuxUnavailableError();
+    throw new AgentRuntimeUnavailableError(provider, availability.reason, availability.detail);
+  }
+
+  registry.prune();
+  const existing = registry.lookup(opts.name);
+  if (existing) {
+    throw new AgentNameInUseError(opts.name, existing.pid);
+  }
+
+  if (provider === "tmux" && tmux && (await tmux.sessionExists(opts.name))) {
+    deps.onWarning?.(
+      `tmux session "${opts.name}" already exists but has no live registry entry — it will be replaced.`,
+    );
+  }
+
+  const result = await runtime.startAgent({
+    name: opts.name,
+    cwd: opts.cwd,
+    kind: agentRuntimeKind(opts.type, provider),
+    args: [],
+    timeoutMs,
+    ...(provider === "tmux"
+      ? {
+          command: agent.command,
+          matches: agent.matches,
+          pollIntervalMs: intervalMs,
+        }
+      : {}),
+  });
+
+  const entry: RegistryEntry = {
+    name: opts.name,
+    type: opts.type,
+    pid: result.pid,
+    runtime: runtime.provider,
+    runtimeRef: result.runtimeRef,
+    cwd: opts.cwd,
+    startedAt: new Date().toISOString(),
+    sessionId: "",
+    sessionFilePath: "",
+    pinned: false,
+  };
+  registry.register(entry);
+  return entry;
+}
+
+export async function stopAgent(
+  agent: Pick<AgentInfo, "name" | "pid">,
+  deps: StopAgentDeps = {},
+): Promise<StopAgentResult> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const registryEntry = registry.lookup(agent.name);
+  const runtime = resolveRuntimeForEntry(registryEntry, deps);
+  const runtimeRef = registryEntry?.runtimeRef ?? null;
+
+  await runtime.stop({
+    agent,
+    runtimeRef,
+    killProcess: deps.killProcess,
+  });
+
+  return {
+    agentName: agent.name,
+    pid: agent.pid,
+    runtime: runtime.provider,
+    runtimeRef,
+  };
+}
+
+export async function focusAgent(
+  agent: Pick<AgentInfo, "name" | "pid">,
+  deps: FocusAgentDeps,
+): Promise<FocusAgentResult> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const registryEntry = registry.lookup(agent.name);
+  const runtime = resolveRuntimeForEntry(registryEntry, deps);
+  if (runtime.provider === "tmux") {
+    const location = await deps.focusManager.findTerminal(agent.pid);
+    if (!location) return { focused: false, reason: "terminal-not-found" };
+
+    const focused = await deps.focusManager.focusTerminal(location);
+    return focused ? { focused: true } : { focused: false, reason: "focus-failed" };
+  }
+
+  const focused = await runtime.focus({
+    agent,
+    runtimeRef: registryEntry?.runtimeRef ?? null,
+    focusManager: deps.focusManager,
+  });
+
+  if (focused) return { focused: true };
+  return { focused: false, reason: "focus-failed" };
+}
+
+export async function sendAgentPrompt(
+  agent: Pick<AgentInfo, "name" | "pid">,
+  prompt: string,
+  deps: SendAgentPromptDeps,
+): Promise<void> {
+  const registry = deps.registry ?? AgentRegistry.default();
+  const registryEntry = registry.lookup(agent.name);
+  const runtime = resolveRuntimeForEntry(registryEntry, deps);
+
+  await runtime.send(
+    {
+      agent,
+      runtimeRef: registryEntry?.runtimeRef ?? null,
+      prompt,
+    },
+    {
+      focusManager: deps.focusManager,
+      writer: deps.writer,
+    },
+  );
+}
+
+function resolveStartRuntime(
+  provider: AgentRuntimeProvider,
+  deps: StartAgentDeps,
+): InteractiveAgentRuntime {
+  if (deps.runtime && deps.runtime.provider === provider) {
+    return deps.runtime;
+  }
+  if (provider === "tmux") return new TmuxAgentRuntime(deps.tmux);
+  return createInteractiveRuntime(provider);
+}
+
+function resolveRuntimeForEntry(
+  registryEntry: RegistryEntry | null,
+  deps: { runtime?: InteractiveAgentRuntime; tmux?: Pick<TmuxManager, "killSession"> },
+): InteractiveAgentRuntime {
+  if (isHerdrRegistryEntry(registryEntry)) {
+    return deps.runtime?.provider === "herdr" ? deps.runtime : createInteractiveRuntime("herdr");
+  }
+  if (deps.runtime?.provider === "tmux") return deps.runtime;
+  return deps.tmux
+    ? new TmuxAgentRuntime(deps.tmux as TmuxManager)
+    : createInteractiveRuntime("tmux");
+}
+
+function isHerdrRegistryEntry(
+  entry: unknown,
+): entry is RegistryEntry & { runtime: "herdr"; runtimeRef: unknown } {
+  return (
+    typeof entry === "object" &&
+    entry !== null &&
+    (entry as { runtime?: unknown }).runtime === "herdr" &&
+    "runtimeRef" in entry
+  );
+}
+
+function agentRuntimeKind(type: StartableAgentType, provider: AgentRuntimeProvider): string {
+  if (provider === "tmux") return type;
+  return {
+    claude: "claude",
+    codex: "codex",
+    copilot: "copilot",
+    gemini_cli: "gemini",
+    grok_cli: "grok",
+    opencode: "opencode",
+    pi: "pi",
+  }[type];
+}

package/src/runtime/RuntimeFactory.ts

@@ -0,0 +1,13 @@
+import type { AgentRuntimeProvider } from "../utils/AgentRegistry.js";
+import { HerdrAgentRuntime } from "./herdr/HerdrAgentRuntime.js";
+import { TmuxAgentRuntime } from "./tmux/TmuxAgentRuntime.js";
+import type { InteractiveAgentRuntime } from "./types.js";
+
+function createHerdrRuntime(): InteractiveAgentRuntime {
+  return new HerdrAgentRuntime();
+}
+
+export function createInteractiveRuntime(provider: AgentRuntimeProvider): InteractiveAgentRuntime {
+  if (provider === "herdr") return createHerdrRuntime();
+  return new TmuxAgentRuntime();
+}

package/src/runtime/errors.ts

@@ -0,0 +1,50 @@
+import type { AgentRuntimeProvider } from "../utils/AgentRegistry.js";
+
+export class TmuxUnavailableError extends Error {
+  constructor() {
+    super("tmux is not installed or not in PATH.");
+    this.name = "TmuxUnavailableError";
+  }
+}
+
+export class AgentNameInUseError extends Error {
+  constructor(
+    public agentName: string,
+    public pid: number,
+  ) {
+    super(`Agent "${agentName}" is already running (PID ${pid}).`);
+    this.name = "AgentNameInUseError";
+  }
+}
+
+export class AgentPidPollTimeoutError extends Error {
+  constructor(
+    public agentName: string,
+    public command: string,
+    public timeoutMs: number,
+  ) {
+    super(`Agent process not found after ${timeoutMs / 1000}s.`);
+    this.name = "AgentPidPollTimeoutError";
+  }
+}
+
+export class AgentRuntimeUnavailableError extends Error {
+  constructor(
+    public provider: AgentRuntimeProvider,
+    public reason: string,
+    public detail: string,
+  ) {
+    super(`${provider} runtime is unavailable (${reason}): ${detail}`);
+    this.name = "AgentRuntimeUnavailableError";
+  }
+}
+
+export class AgentTerminalNotFoundError extends Error {
+  constructor(
+    public agentName: string,
+    public pid: number,
+  ) {
+    super(`Cannot find terminal for agent "${agentName}" (PID: ${pid}).`);
+    this.name = "AgentTerminalNotFoundError";
+  }
+}

package/src/runtime/herdr/HerdrAgentDiscovery.ts

@@ -0,0 +1,178 @@
+import type { AgentInfo, AgentType } from "../../adapters/AgentAdapter.js";
+import { HerdrCliClient, type HerdrCommandRunner } from "./HerdrCliClient.js";
+import type { HerdrRuntimeRef } from "./HerdrRuntimeRef.js";
+
+export interface HerdrAgentPane {
+  agent: string;
+  agentSessionId?: string;
+  cwd?: string;
+  paneId: string;
+  workspaceId?: string;
+  tabId?: string;
+  foregroundPids?: number[];
+  shellPid?: number;
+}
+
+export async function fetchHerdrAgentPanes(runner?: HerdrCommandRunner): Promise<HerdrAgentPane[]> {
+  const client = new HerdrCliClient(runner);
+  const response = await client.runJson(["pane", "list"]);
+  return enrichHerdrAgentPanes(client, extractHerdrAgentPanes(response));
+}
+
+export function extractHerdrAgentPanes(value: unknown): HerdrAgentPane[] {
+  const snapshot = getObject(value, ["result", "snapshot"]);
+  const rawPanes = getArray(value, ["result", "panes"]) ?? snapshot?.agents;
+  if (!Array.isArray(rawPanes)) return [];
+
+  const panes: HerdrAgentPane[] = [];
+  for (const rawPane of rawPanes) {
+    if (!rawPane || typeof rawPane !== "object" || Array.isArray(rawPane)) continue;
+    const pane = rawPane as Record<string, unknown>;
+    const agent = nonEmptyString(pane.agent);
+    const paneId = nonEmptyString(pane.pane_id);
+    if (!agent || !paneId) continue;
+
+    const session = getObject(pane, ["agent_session"]);
+    const agentSessionId = nonEmptyString(session?.value);
+    const cwd = nonEmptyString(pane.cwd);
+    const workspaceId = nonEmptyString(pane.workspace_id);
+    const tabId = nonEmptyString(pane.tab_id);
+
+    panes.push({
+      agent,
+      paneId,
+      ...(agentSessionId ? { agentSessionId } : {}),
+      ...(cwd ? { cwd } : {}),
+      ...(workspaceId ? { workspaceId } : {}),
+      ...(tabId ? { tabId } : {}),
+    });
+  }
+
+  return panes;
+}
+
+export function findMatchingHerdrPane(
+  agent: Pick<AgentInfo, "type" | "projectPath" | "sessionId" | "pid">,
+  panes: readonly HerdrAgentPane[],
+): HerdrAgentPane | null {
+  if (agent.sessionId) {
+    const sessionMatches = panes.filter((pane) => pane.agentSessionId === agent.sessionId);
+    if (sessionMatches.length === 1) return sessionMatches[0]!;
+    if (sessionMatches.length > 1) return null;
+  }
+
+  const foregroundPidMatches = panes.filter((pane) => pane.foregroundPids?.includes(agent.pid));
+  if (foregroundPidMatches.length === 1) return foregroundPidMatches[0]!;
+  if (foregroundPidMatches.length > 1) return null;
+
+  const shellPidMatches = panes.filter((pane) => pane.shellPid === agent.pid);
+  if (shellPidMatches.length === 1) return shellPidMatches[0]!;
+  if (shellPidMatches.length > 1) return null;
+
+  const cwdMatches = panes.filter(
+    (pane) => pane.cwd === agent.projectPath && herdrAgentMatchesType(pane.agent, agent.type),
+  );
+  return cwdMatches.length === 1 ? cwdMatches[0]! : null;
+}
+
+export function herdrPaneToRuntimeRef(pane: HerdrAgentPane, agentName: string): HerdrRuntimeRef {
+  return {
+    session: "default",
+    paneId: pane.paneId,
+    agentName,
+    ...(pane.workspaceId ? { workspaceId: pane.workspaceId } : {}),
+    ...(pane.tabId ? { tabId: pane.tabId } : {}),
+  };
+}
+
+function herdrAgentMatchesType(herdrAgent: string, agentType: AgentType): boolean {
+  const normalized = herdrAgent.toLowerCase();
+  const candidates: Record<AgentType, readonly string[]> = {
+    claude: ["claude"],
+    codex: ["codex"],
+    copilot: ["copilot"],
+    gemini_cli: ["gemini", "gemini_cli"],
+    grok_cli: ["grok", "grok_cli"],
+    opencode: ["opencode"],
+    pi: ["pi"],
+    other: ["other"],
+  };
+  return candidates[agentType]?.includes(normalized) ?? false;
+}
+
+async function enrichHerdrAgentPanes(
+  client: HerdrCliClient,
+  panes: HerdrAgentPane[],
+): Promise<HerdrAgentPane[]> {
+  return Promise.all(
+    panes.map(async (pane) => {
+      try {
+        const response = await client.runJson(["pane", "process-info", "--pane", pane.paneId]);
+        return {
+          ...pane,
+          ...extractPaneProcessIds(response),
+        };
+      } catch {
+        return pane;
+      }
+    }),
+  );
+}
+
+function extractPaneProcessIds(value: unknown): Pick<HerdrAgentPane, "foregroundPids" | "shellPid"> {
+  const processInfo = getObject(value, ["result", "process_info"]);
+  if (!processInfo) return {};
+
+  const foregroundProcesses = processInfo.foreground_processes;
+  const foregroundPids: number[] = [];
+  if (Array.isArray(foregroundProcesses)) {
+    for (const foregroundProcess of foregroundProcesses) {
+      if (
+        !foregroundProcess ||
+        typeof foregroundProcess !== "object" ||
+        Array.isArray(foregroundProcess)
+      )
+        continue;
+      const pid = positiveIntegerOrNull((foregroundProcess as { pid?: unknown }).pid);
+      if (pid !== null) foregroundPids.push(pid);
+    }
+  }
+  const shellPid = positiveIntegerOrNull(processInfo.shell_pid);
+
+  return {
+    ...(foregroundPids.length > 0 ? { foregroundPids } : {}),
+    ...(shellPid !== null ? { shellPid } : {}),
+  };
+}
+
+function getArray(value: unknown, path: 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 Array.isArray(current) ? current : null;
+}
+
+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 nonEmptyString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim() ? value : undefined;
+}
+
+function positiveIntegerOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : null;
+}