@ai-devkit/agent-manager 0.31.0 → 0.33.0

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>;
+}