stagent 0.1.0

package/src/lib/agents/runtime/codex-app-server-client.ts

@@ -0,0 +1,289 @@
+import { spawn, type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+import net from "node:net";
+
+type JsonRpcId = number;
+
+interface JsonRpcRequest {
+  id: JsonRpcId;
+  method: string;
+  params?: unknown;
+}
+
+interface JsonRpcResponse {
+  id: JsonRpcId;
+  result?: unknown;
+  error?: { code?: number; message?: string; data?: unknown };
+}
+
+interface JsonRpcNotification {
+  method: string;
+  params?: unknown;
+}
+
+type JsonRpcMessage = JsonRpcRequest | JsonRpcResponse | JsonRpcNotification;
+
+export interface CodexAppServerClientOptions {
+  env?: Record<string, string>;
+  cwd?: string;
+}
+
+export class CodexAppServerClient {
+  private readonly child: ChildProcessByStdio<null, Readable, Readable>;
+  private readonly socket: WebSocket;
+  private readonly pending = new Map<
+    JsonRpcId,
+    {
+      resolve: (value: unknown) => void;
+      reject: (error: Error) => void;
+    }
+  >();
+  private nextId = 1;
+  private closed = false;
+
+  onNotification?: (notification: JsonRpcNotification) => void;
+  onRequest?: (request: JsonRpcRequest) => void;
+  onProcessError?: (error: Error) => void;
+
+  private constructor(
+    child: ChildProcessByStdio<null, Readable, Readable>,
+    socket: WebSocket
+  ) {
+    this.child = child;
+    this.socket = socket;
+    this.bindEvents();
+  }
+
+  static async connect(
+    options: CodexAppServerClientOptions = {}
+  ): Promise<CodexAppServerClient> {
+    const port = await reservePort();
+    const listenUrl = `ws://127.0.0.1:${port}`;
+    const child = spawn(
+      "codex",
+      ["app-server", "--listen", listenUrl],
+      {
+        cwd: options.cwd,
+        env: {
+          ...process.env,
+          ...(options.env ?? {}),
+        },
+        stdio: ["ignore", "pipe", "pipe"],
+      }
+    );
+
+    const socket = await connectWebSocket(listenUrl, child);
+    return new CodexAppServerClient(child, socket);
+  }
+
+  async request<T>(method: string, params?: unknown): Promise<T> {
+    const id = this.nextId++;
+
+    const payload: JsonRpcRequest = { id, method, params };
+    this.socket.send(JSON.stringify(payload));
+
+    return new Promise<T>((resolve, reject) => {
+      this.pending.set(id, {
+        resolve: (value) => resolve(value as T),
+        reject,
+      });
+    });
+  }
+
+  respond(id: JsonRpcId, result: unknown): void {
+    if (this.closed) return;
+    this.socket.send(JSON.stringify({ id, result }));
+  }
+
+  reject(id: JsonRpcId, message: string): void {
+    if (this.closed) return;
+    this.socket.send(
+      JSON.stringify({
+        id,
+        error: { message },
+      })
+    );
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+
+    try {
+      this.socket.close();
+    } catch {
+      // Ignore close races.
+    }
+
+    this.child.kill("SIGTERM");
+    await waitForProcessExit(this.child, 1000).catch(() => {
+      this.child.kill("SIGKILL");
+    });
+  }
+
+  private bindEvents(): void {
+    this.socket.addEventListener("message", (event) => {
+      const raw =
+        typeof event.data === "string"
+          ? event.data
+          : Buffer.from(event.data as ArrayBuffer).toString("utf8");
+      this.handleMessage(raw);
+    });
+
+    this.socket.addEventListener("error", () => {
+      this.rejectAllPending(new Error("Codex app server socket error"));
+    });
+
+    this.socket.addEventListener("close", () => {
+      if (!this.closed) {
+        this.rejectAllPending(new Error("Codex app server socket closed"));
+      }
+    });
+
+    const handleProcessFailure = (error: Error) => {
+      if (this.closed) return;
+      this.onProcessError?.(error);
+      this.rejectAllPending(error);
+    };
+
+    this.child.once("error", handleProcessFailure);
+    this.child.once("exit", (code, signal) => {
+      if (this.closed) return;
+      handleProcessFailure(
+        new Error(
+          `Codex app server exited unexpectedly (code=${code ?? "null"}, signal=${signal ?? "null"})`
+        )
+      );
+    });
+  }
+
+  private handleMessage(raw: string): void {
+    let message: JsonRpcMessage;
+
+    try {
+      message = JSON.parse(raw) as JsonRpcMessage;
+    } catch {
+      return;
+    }
+
+    if ("id" in message && ("result" in message || "error" in message) && !("method" in message)) {
+      const pending = this.pending.get(message.id);
+      if (!pending) return;
+      this.pending.delete(message.id);
+
+      if (message.error) {
+        pending.reject(
+          new Error(message.error.message || "Codex app server request failed")
+        );
+      } else {
+        pending.resolve(message.result);
+      }
+      return;
+    }
+
+    if (
+      "id" in message &&
+      "method" in message &&
+      typeof message.method === "string"
+    ) {
+      this.onRequest?.(message as JsonRpcRequest);
+      return;
+    }
+
+    if ("method" in message && typeof message.method === "string") {
+      this.onNotification?.(message as JsonRpcNotification);
+    }
+  }
+
+  private rejectAllPending(error: Error): void {
+    for (const pending of this.pending.values()) {
+      pending.reject(error);
+    }
+    this.pending.clear();
+  }
+}
+
+async function reservePort(): Promise<number> {
+  return new Promise<number>((resolve, reject) => {
+    const server = net.createServer();
+    server.unref();
+    server.on("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      if (!address || typeof address === "string") {
+        server.close();
+        reject(new Error("Failed to reserve loopback port"));
+        return;
+      }
+
+      const { port } = address;
+      server.close((error) => {
+        if (error) {
+          reject(error);
+          return;
+        }
+        resolve(port);
+      });
+    });
+  });
+}
+
+async function connectWebSocket(
+  url: string,
+  child: ChildProcessByStdio<null, Readable, Readable>
+): Promise<WebSocket> {
+  const deadline = Date.now() + 10_000;
+  let lastError: Error | null = null;
+
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(`Codex app server exited before accepting connections (code=${child.exitCode})`);
+    }
+
+    try {
+      const socket = await new Promise<WebSocket>((resolve, reject) => {
+        const ws = new WebSocket(url);
+        const onOpen = () => {
+          cleanup();
+          resolve(ws);
+        };
+        const onError = () => {
+          cleanup();
+          ws.close();
+          reject(new Error("Codex app server websocket connection failed"));
+        };
+        const cleanup = () => {
+          ws.removeEventListener("open", onOpen);
+          ws.removeEventListener("error", onError);
+        };
+
+        ws.addEventListener("open", onOpen);
+        ws.addEventListener("error", onError);
+      });
+
+      return socket;
+    } catch (error) {
+      lastError =
+        error instanceof Error ? error : new Error(String(error));
+      await new Promise((resolve) => setTimeout(resolve, 150));
+    }
+  }
+
+  throw lastError ?? new Error("Timed out connecting to Codex app server");
+}
+
+async function waitForProcessExit(
+  child: ChildProcessByStdio<null, Readable, Readable>,
+  timeoutMs: number
+): Promise<void> {
+  if (child.exitCode !== null) return;
+
+  await Promise.race([
+    new Promise<void>((resolve) => {
+      child.once("exit", () => resolve());
+    }),
+    new Promise<void>((_, reject) => {
+      setTimeout(() => reject(new Error("Timed out waiting for Codex app server to exit")), timeoutMs);
+    }),
+  ]);
+}

package/src/lib/agents/runtime/index.ts

@@ -0,0 +1,167 @@
+import {
+  DEFAULT_AGENT_RUNTIME,
+  getRuntimeCapabilities,
+  getRuntimeCatalogEntry,
+  listRuntimeCatalog,
+  resolveAgentRuntime,
+  type AgentRuntimeId,
+} from "./catalog";
+import { claudeRuntimeAdapter } from "./claude";
+import { openAICodexRuntimeAdapter } from "./openai-codex";
+import { getProfile } from "@/lib/agents/profiles/registry";
+import { resolveProfileRuntimePayload } from "@/lib/agents/profiles/compatibility";
+import type {
+  AgentRuntimeAdapter,
+  RuntimeConnectionResult,
+  RuntimeSummary,
+  TaskAssistInput,
+} from "./types";
+import type { ProfileTestReport } from "@/lib/agents/profiles/test-types";
+import type { TaskAssistResponse } from "./task-assist-types";
+import {
+  enforceBudgetGuardrails,
+  enforceTaskBudgetGuardrails,
+} from "@/lib/settings/budget-guardrails";
+
+const runtimeRegistry: Record<AgentRuntimeId, AgentRuntimeAdapter> = {
+  "claude-code": claudeRuntimeAdapter,
+  "openai-codex-app-server": openAICodexRuntimeAdapter,
+};
+
+function getRuntimeAdapter(runtimeId?: string | null): AgentRuntimeAdapter {
+  return runtimeRegistry[resolveAgentRuntime(runtimeId)];
+}
+
+function assertCapability(
+  runtimeId: string | null | undefined,
+  capability: keyof AgentRuntimeAdapter["metadata"]["capabilities"]
+): AgentRuntimeAdapter {
+  const resolvedRuntime = resolveAgentRuntime(runtimeId);
+  const adapter = runtimeRegistry[resolvedRuntime];
+
+  if (!adapter.metadata.capabilities[capability]) {
+    throw new Error(
+      `Runtime "${resolvedRuntime}" does not support ${capability}`
+    );
+  }
+
+  return adapter;
+}
+
+export function getRuntimeSummary(
+  runtimeId: string | null | undefined = DEFAULT_AGENT_RUNTIME
+): RuntimeSummary {
+  const resolvedRuntime = resolveAgentRuntime(runtimeId);
+  return {
+    runtime: runtimeRegistry[resolvedRuntime].metadata,
+    capabilities: getRuntimeCapabilities(resolvedRuntime),
+  };
+}
+
+export function listRuntimeSummaries(): RuntimeSummary[] {
+  return listRuntimeCatalog().map((runtime) => ({
+    runtime,
+    capabilities: runtime.capabilities,
+  }));
+}
+
+export async function executeTaskWithRuntime(
+  taskId: string,
+  runtimeId?: string | null
+): Promise<void> {
+  await enforceTaskBudgetGuardrails(taskId, { failTaskOnBlock: true });
+  return getRuntimeAdapter(runtimeId).executeTask(taskId);
+}
+
+export async function resumeTaskWithRuntime(
+  taskId: string,
+  runtimeId?: string | null
+): Promise<void> {
+  await enforceTaskBudgetGuardrails(taskId, {
+    isResume: true,
+    failTaskOnBlock: true,
+  });
+  const adapter = assertCapability(runtimeId, "resume");
+  return adapter.resumeTask(taskId);
+}
+
+export async function cancelTaskWithRuntime(
+  taskId: string,
+  runtimeId?: string | null
+): Promise<void> {
+  const adapter = assertCapability(runtimeId, "cancel");
+  return adapter.cancelTask(taskId);
+}
+
+export async function runTaskAssistWithRuntime(
+  input: TaskAssistInput,
+  runtimeId?: string | null
+): Promise<TaskAssistResponse> {
+  await enforceBudgetGuardrails({
+    runtimeId: resolveAgentRuntime(runtimeId),
+    activityType: "task_assist",
+  });
+  const adapter = assertCapability(runtimeId, "taskAssist");
+  if (!adapter.runTaskAssist) {
+    throw new Error(`Runtime "${adapter.metadata.id}" does not implement task assist`);
+  }
+  return adapter.runTaskAssist(input);
+}
+
+export async function runProfileTestsWithRuntime(
+  profileId: string,
+  runtimeId?: string | null
+): Promise<ProfileTestReport> {
+  const resolvedRuntime = resolveAgentRuntime(runtimeId);
+  const profile = getProfile(profileId);
+  if (!profile) {
+    throw new Error(`Profile "${profileId}" not found`);
+  }
+
+  const payload = resolveProfileRuntimePayload(profile, resolvedRuntime);
+  if (!payload.supported) {
+    return {
+      profileId,
+      profileName: profile.name,
+      runtimeId: resolvedRuntime,
+      results: [],
+      totalPassed: 0,
+      totalFailed: 0,
+      unsupported: true,
+      unsupportedReason:
+        payload.reason ??
+        `${profile.name} does not support ${getRuntimeCatalogEntry(resolvedRuntime).label}`,
+    };
+  }
+
+  const adapter = getRuntimeAdapter(resolvedRuntime);
+  if (!adapter.metadata.capabilities.profileTests || !adapter.runProfileTests) {
+    return {
+      profileId,
+      profileName: profile.name,
+      runtimeId: resolvedRuntime,
+      results: [],
+      totalPassed: 0,
+      totalFailed: 0,
+      unsupported: true,
+      unsupportedReason: `${adapter.metadata.label} does not support profile smoke tests yet`,
+    };
+  }
+
+  await enforceBudgetGuardrails({
+    runtimeId: resolvedRuntime,
+    activityType: "profile_test",
+  });
+
+  return adapter.runProfileTests(profileId);
+}
+
+export async function testRuntimeConnection(
+  runtimeId?: string | null
+): Promise<RuntimeConnectionResult> {
+  const adapter = assertCapability(runtimeId, "authHealthCheck");
+  if (!adapter.testConnection) {
+    throw new Error(`Runtime "${adapter.metadata.id}" does not implement health checks`);
+  }
+  return adapter.testConnection();
+}