@skaile/forge-agent-runtime 0.0.0-stage → 1.1.0

package/dist/shared/forge-agent-runtime.B1LZr0Sl.mjs

@@ -0,0 +1,538 @@
+import { EventEmitter } from 'node:events';
+import { spawn } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import net from 'node:net';
+import { join, resolve, basename } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createConsola } from 'consola';
+import { createColors } from 'picocolors';
+import { AgentClient } from '@skaile/workspaces/sdk/client';
+import { WebSocketClientTransport } from '@skaile/workspaces/sdk/transport/ws/client';
+import { registryCredentialEnv } from '@skaile/forge-settings/server';
+
+const pc = createColors(true);
+const consolaWithFancy = createConsola;
+const log = consolaWithFancy({
+  fancy: false,
+  defaults: { tag: pc.bold(pc.cyan("agent-process")) }
+});
+const BASE_PORT = 9100;
+let nextPort = BASE_PORT;
+async function isPortFree(port) {
+  return new Promise((resolve2) => {
+    const server = net.createServer();
+    server.once("error", () => resolve2(false));
+    server.once("listening", () => {
+      server.close(() => resolve2(true));
+    });
+    server.listen(port);
+  });
+}
+async function allocatePort() {
+  for (let i = 0; i < 100; i++) {
+    const port = nextPort++;
+    if (nextPort > BASE_PORT + 500) nextPort = BASE_PORT;
+    if (await isPortFree(port)) return port;
+  }
+  throw new Error("Could not find a free port for skaile serve");
+}
+function dialHost(host) {
+  if (!host) return "127.0.0.1";
+  return host.includes(":") && !host.startsWith("[") ? `[${host}]` : host;
+}
+function resolveSkaileCmd() {
+  try {
+    return fileURLToPath(import.meta.resolve("@skaile/workspaces/cli"));
+  } catch {
+  }
+  try {
+    const entryDir = fileURLToPath(new URL(".", import.meta.url));
+    const cliSubpath = join("node_modules", "@skaile", "workspaces", "dist", "cli", "index.js");
+    let dir = entryDir;
+    for (let i = 0; i < 8; i++) {
+      const candidate = join(dir, cliSubpath);
+      if (existsSync(candidate)) return candidate;
+      const parent = resolve(dir, "..");
+      if (parent === dir) break;
+      dir = parent;
+    }
+  } catch {
+  }
+  return "skaile";
+}
+function resolveBunCmd() {
+  const exec = basename(process.execPath).toLowerCase();
+  if (exec === "bun" || exec === "bun.exe") return process.execPath;
+  return "bun";
+}
+function resolveCliInterpreter(jsEntry) {
+  try {
+    const firstLine = readFileSync(jsEntry, "utf8").split("\n", 1)[0] ?? "";
+    if (/\bbun\b/.test(firstLine)) return resolveBunCmd();
+  } catch {
+  }
+  return process.execPath;
+}
+class ProcessManagerClientTransport {
+  constructor(manager, id) {
+    this.manager = manager;
+    this.id = id;
+  }
+  get connected() {
+    return this.manager.isConnected(this.id);
+  }
+  async connect() {
+  }
+  async disconnect() {
+    await this.manager.shutdown(this.id);
+  }
+  send(command) {
+    this.manager.sendCommand(this.id, command);
+  }
+  onMessage(handler) {
+    this.manager.on(`event:${this.id}`, handler);
+    return () => this.manager.off(`event:${this.id}`, handler);
+  }
+  onDisconnect(_handler) {
+    return () => {
+    };
+  }
+}
+class AgentProcessManager extends EventEmitter {
+  processes = /* @__PURE__ */ new Map();
+  constructor() {
+    super();
+    this.setMaxListeners(100);
+    const cleanup = () => {
+      for (const [id] of this.processes) {
+        try {
+          this.shutdownSync(id);
+        } catch {
+        }
+      }
+    };
+    process.on("exit", cleanup);
+    process.on("SIGTERM", cleanup);
+    process.on("SIGINT", cleanup);
+  }
+  /**
+   * Spawn a `skaile serve` subprocess and connect via WebSocket transport.
+   * Resolves when the subprocess is ready and transport is connected.
+   */
+  async create(id, config) {
+    log.info(
+      `[${id}] Creating session \u2014 harness=${config.harness ?? "omp"} model=${config.model ?? "(registry default)"}`
+    );
+    log.debug(`[${id}]   projectDir=${config.projectDir}`);
+    if (this.processes.has(id)) {
+      log.info(`[${id}] Shutting down existing process`);
+      await this.shutdown(id);
+    }
+    if (config.systemPrompt) {
+      const skaileDir = join(config.projectDir, ".skaile");
+      if (!existsSync(skaileDir)) mkdirSync(skaileDir, { recursive: true });
+      const systemPromptFile = join(skaileDir, "system-prompt.md");
+      writeFileSync(systemPromptFile, config.systemPrompt);
+      log.debug(`[${id}] Wrote system prompt (${config.systemPrompt.length} chars)`);
+    }
+    const credentials = config.registry ? registryCredentialEnv(config.registry, { env: config.credentialEnv }) : { env: {}, deliveries: [] };
+    for (const delivery of credentials.deliveries) {
+      if (delivery.names.length > 0) {
+        log.debug(`[${id}]   ${delivery.providerId} credential from ${delivery.source}`);
+      } else if (delivery.error) {
+        log.warn(`[${id}]   ${delivery.providerId} credential not delivered: ${delivery.error}`);
+      }
+    }
+    const env = {
+      ...config.credentialEnv ?? process.env,
+      ...credentials.env,
+      ...config.env ?? {}
+    };
+    if (config.sshKeyPath) {
+      env.GIT_SSH_COMMAND = `ssh -i ${config.sshKeyPath} -o StrictHostKeyChecking=no`;
+    }
+    if (config.harnessSessionId) {
+      env.SKAILE_RESUME_SESSION_ID = config.harnessSessionId;
+      log.debug(`[${id}]   SKAILE_RESUME_SESSION_ID=${config.harnessSessionId}`);
+    }
+    if (config.wsAuthToken) env.SKAILE_WS_AUTH_TOKEN = config.wsAuthToken;
+    const skaileCmd = resolveSkaileCmd();
+    const interpreter = skaileCmd.endsWith(".js") ? resolveCliInterpreter(skaileCmd) : null;
+    const MAX_PORT_ATTEMPTS = 3;
+    let managed;
+    let transport;
+    let port = 0;
+    for (let attempt = 1; attempt <= MAX_PORT_ATTEMPTS; attempt++) {
+      port = await allocatePort();
+      log.debug(`[${id}] Allocated port ${port} (attempt ${attempt}/${MAX_PORT_ATTEMPTS})`);
+      const args = ["serve", "--project-dir", config.projectDir, "--port", String(port)];
+      if (config.host) args.push("--host", config.host);
+      if (config.harness) args.push("--harness", config.harness);
+      if (config.model) args.push("--model", config.model);
+      if (config.providers && config.providers.length > 0)
+        args.push("--providers", config.providers.join(","));
+      log.debug(
+        `[${id}] Spawning: ${interpreter ? `${interpreter} ${skaileCmd}` : skaileCmd} ${args.join(" ")}`
+      );
+      const child = interpreter ? spawn(interpreter, [skaileCmd, ...args], { env, stdio: ["pipe", "pipe", "pipe"] }) : spawn(skaileCmd, args, { env, stdio: ["pipe", "pipe", "pipe"] });
+      transport = new WebSocketClientTransport({
+        url: `ws://${dialHost(config.host)}:${port}`,
+        ...config.wsAuthToken ? { auth: config.wsAuthToken } : {},
+        reconnect: { maxAttempts: 3, baseMs: 1e3, maxMs: 1e4 },
+        onLog: (line) => log.debug(`[${id}] ${line}`)
+      });
+      managed = {
+        child,
+        port,
+        transport,
+        config,
+        status: "starting",
+        stderrBuffer: []
+      };
+      this.processes.set(id, managed);
+      child.stdout?.on("data", (chunk) => {
+        for (const line of chunk.toString().split("\n")) {
+          const trimmed = line.trim();
+          if (trimmed && !trimmed.includes("listening on port")) {
+            log.info(`[${id}] [stdout] ${trimmed}`);
+          }
+        }
+      });
+      child.stderr?.on("data", (chunk) => {
+        const line = chunk.toString().trim();
+        if (line) {
+          managed.stderrBuffer.push(line);
+          if (managed.stderrBuffer.length > 30) managed.stderrBuffer.shift();
+          log.warn(`[${id}] [stderr] ${line}`);
+        }
+      });
+      log.debug(`[${id}] Waiting for subprocess ready signal...`);
+      try {
+        await this.waitForReady(id, managed, 2e4);
+      } catch (err) {
+        const portConflict = managed.stderrBuffer.some((l) => l.includes("EADDRINUSE"));
+        try {
+          if (managed.child.exitCode === null) managed.child.kill("SIGKILL");
+        } catch {
+        }
+        this.processes.delete(id);
+        if (portConflict && attempt < MAX_PORT_ATTEMPTS) {
+          log.warn(`[${id}] Port ${port} already in use \u2014 retrying on a fresh port`);
+          continue;
+        }
+        throw err;
+      }
+      log.info(`[${id}] Subprocess ready on port ${port}`);
+      managed.child.on("exit", (code, signal) => {
+        const prev = managed.status;
+        managed.status = "stopped";
+        if (prev !== "stopped") {
+          log.warn(`[${id}] Process exited unexpectedly (code=${code}, signal=${signal})`);
+          const stderr = managed.stderrBuffer.slice(-5).join("\n");
+          if (stderr) log.debug(`[${id}] Last stderr: ${stderr}`);
+          this.emit(`error:${id}`, {
+            type: "error",
+            error: `Agent process exited (code=${code}, signal=${signal})${stderr ? `: ${stderr}` : ""}`
+          });
+        } else {
+          log.debug(`[${id}] Process exited cleanly (code=${code})`);
+        }
+        this.processes.delete(id);
+      });
+      break;
+    }
+    await transport.connect();
+    managed.status = "connected";
+    log.info(`[${id}] WebSocket connected`);
+    managed.unsubMessage = transport.onMessage((event) => {
+      if (event.type === "error") {
+        log.warn(`[${id}] \u2190 error: ${event.message}`);
+      } else {
+        log.info(`[${id}] \u2190 ${event.type}`);
+      }
+      this.emit(`event:${id}`, event);
+    });
+    managed.unsubDisconnect = transport.onDisconnect(() => {
+      if (managed.status === "connected") {
+        log.warn(`[${id}] WebSocket disconnected unexpectedly`);
+        managed.status = "disconnected";
+      }
+    });
+  }
+  /**
+   * Send a prompt to the agent subprocess.
+   */
+  async prompt(id, message) {
+    log.info(`[${id}] Sending prompt (${message.length} chars)`);
+    const managed = this.processes.get(id);
+    if (!managed?.transport.connected) {
+      throw new Error(`No active connection for session ${id}`);
+    }
+    managed.transport.send({ type: "prompt", prompt: message });
+  }
+  /**
+   * Cancel the current agent operation.
+   */
+  async cancel(id) {
+    log.info(`[${id}] Cancelling`);
+    const managed = this.processes.get(id);
+    if (managed?.transport.connected) {
+      managed.transport.send({ type: "cancel" });
+    }
+  }
+  /**
+   * Gracefully shut down a subprocess.
+   */
+  async shutdown(id) {
+    const managed = this.processes.get(id);
+    if (!managed) return;
+    log.info(`[${id}] Shutting down (port ${managed.port})`);
+    managed.status = "stopped";
+    managed.unsubMessage?.();
+    managed.unsubDisconnect?.();
+    await managed.transport.disconnect();
+    if (managed.child.exitCode === null) {
+      managed.child.kill("SIGTERM");
+      await new Promise((resolve2) => {
+        const timeout = setTimeout(() => {
+          try {
+            managed.child.kill("SIGKILL");
+          } catch {
+          }
+          resolve2();
+        }, 5e3);
+        managed.child.on("exit", () => {
+          clearTimeout(timeout);
+          resolve2();
+        });
+      });
+    }
+    this.processes.delete(id);
+  }
+  /**
+   * Check if a subprocess is connected and ready.
+   */
+  isConnected(id) {
+    const managed = this.processes.get(id);
+    return managed?.status === "connected" && managed.transport.connected;
+  }
+  /**
+   * Check if a session exists (regardless of connection state).
+   */
+  has(id) {
+    return this.processes.has(id);
+  }
+  /**
+   * Send any AgentCommand to the managed process.
+   * Used internally by ProcessManagerClientTransport.
+   */
+  sendCommand(id, command) {
+    const managed = this.processes.get(id);
+    if (!managed?.transport.connected) {
+      throw new Error(`No active connection for session ${id}`);
+    }
+    managed.transport.send(command);
+  }
+  /**
+   * Create an AgentClient for a managed session.
+   * Uses ProcessManagerClientTransport so there is no second subscription
+   * on the underlying WebSocket transport. Disposing the client will
+   * gracefully shut down the subprocess via manager.shutdown().
+   *
+   * Throws if the session does not exist. The session must be connected
+   * (isConnected() === true) before any commands can be sent.
+   */
+  createAgentClient(id) {
+    if (!this.processes.has(id)) {
+      throw new Error(`No managed session '${id}'`);
+    }
+    return new AgentClient(new ProcessManagerClientTransport(this, id));
+  }
+  // ── Internal ────────────────────────────────────────────────────────
+  shutdownSync(id) {
+    const managed = this.processes.get(id);
+    if (!managed) return;
+    managed.status = "stopped";
+    managed.unsubMessage?.();
+    managed.unsubDisconnect?.();
+    try {
+      managed.transport.disconnect();
+    } catch {
+    }
+    try {
+      managed.child.kill("SIGTERM");
+    } catch {
+    }
+    this.processes.delete(id);
+  }
+  waitForReady(id, managed, timeoutMs) {
+    return new Promise((resolve2, reject) => {
+      const timer = setTimeout(() => {
+        reject(
+          new Error(
+            `skaile serve did not become ready within ${timeoutMs}ms. stderr: ${managed.stderrBuffer.slice(-3).join(" | ")}`
+          )
+        );
+      }, timeoutMs);
+      const onData = (chunk) => {
+        const text = chunk.toString();
+        if (text.includes("listening on port")) {
+          clearTimeout(timer);
+          managed.child.stdout?.off("data", onData);
+          resolve2();
+        }
+      };
+      managed.child.stdout?.on("data", onData);
+      managed.child.on("exit", (code) => {
+        clearTimeout(timer);
+        managed.child.stdout?.off("data", onData);
+        reject(
+          new Error(
+            `skaile serve exited during startup (code=${code}). stderr: ${managed.stderrBuffer.join(" | ")}`
+          )
+        );
+      });
+    });
+  }
+}
+
+class ProcessManagerAdapter {
+  processManager = new AgentProcessManager();
+  emitter = new EventEmitter();
+  processKey = null;
+  status = "disconnected";
+  constructor() {
+    this.emitter.setMaxListeners(20);
+  }
+  async connect(config) {
+    this.processKey = config.projectDir;
+    await this.processManager.create(this.processKey, {
+      projectDir: config.projectDir,
+      harness: config.harness,
+      registry: config.registry,
+      providers: config.providers,
+      credentialEnv: config.credentialEnv,
+      model: config.model,
+      env: config.env,
+      systemPrompt: config.systemPrompt,
+      maxTurns: config.maxTurns,
+      agentDir: config.agentDir,
+      harnessSessionId: config.harnessSessionId,
+      host: config.host,
+      wsAuthToken: config.wsAuthToken
+    });
+    this.status = "idle";
+    this.processManager.on(`event:${this.processKey}`, (event) => {
+      this._pushEvent(event);
+      if (event.type === "status") {
+        const phase = event.phase;
+        if (phase === "thinking" || phase === "working") {
+          this.status = "running";
+        } else if (phase === "idle") {
+          this.status = "idle";
+        }
+      }
+      if (event.type === "finished" || event.type === "turn_end" || event.type === "agent_end") {
+        this.status = "idle";
+      }
+      if (event.type === "message_start" && event.message?.role === "assistant") {
+        this.status = "running";
+      }
+      if (event.type === "error") {
+        this.status = "error";
+      }
+    });
+    this.processManager.on(`error:${this.processKey}`, (err) => {
+      this.status = "error";
+      this._pushEvent({
+        type: "error",
+        error: err.error || String(err)
+      });
+    });
+  }
+  async sendCommand(command) {
+    if (!this.processKey || !this.processManager.isConnected(this.processKey)) {
+      throw new Error("ProcessManagerAdapter: not connected \u2014 call connect() first");
+    }
+    this.processManager.sendCommand(this.processKey, command);
+  }
+  async *listen() {
+    const queue = [];
+    let resolve = null;
+    let done = false;
+    const onEvent = (event) => {
+      queue.push(event);
+      resolve?.();
+      resolve = null;
+    };
+    const onDone = () => {
+      done = true;
+      resolve?.();
+      resolve = null;
+    };
+    this.emitter.on("_event", onEvent);
+    this.emitter.on("_done", onDone);
+    try {
+      while (true) {
+        while (queue.length > 0) {
+          yield queue.shift();
+        }
+        if (done) break;
+        await new Promise((res) => {
+          resolve = res;
+          if (queue.length > 0 || done) {
+            res();
+            resolve = null;
+          }
+        });
+      }
+    } finally {
+      this.emitter.off("_event", onEvent);
+      this.emitter.off("_done", onDone);
+    }
+  }
+  async abort() {
+    if (this.processKey && this.processManager.isConnected(this.processKey)) {
+      this.processManager.sendCommand(this.processKey, { type: "cancel" });
+      this.status = "idle";
+    }
+  }
+  isConnected() {
+    return !!this.processKey && this.processManager.isConnected(this.processKey);
+  }
+  getStatus() {
+    return this.status;
+  }
+  async disconnect() {
+    this.emitter.emit("_done");
+    if (this.processKey) {
+      await this.processManager.shutdown(this.processKey).catch(() => {
+      });
+      this.processKey = null;
+    }
+    this.status = "disconnected";
+  }
+  /**
+   * Internal: push an event into the async iterable queue.
+   * Exposed with underscore prefix for test injection.
+   */
+  _pushEvent(event) {
+    this.emitter.emit("_event", event);
+  }
+  /**
+   * Set a custom process key (used by apps that namespace keys as 'userId:slug:mode').
+   * Must be called before `connect()`.
+   */
+  setProcessKey(key) {
+    this.processKey = key;
+  }
+  /**
+   * Access the underlying AgentProcessManager for advanced use cases
+   * (e.g. createAgentClient() needed by SessionDispatcher construction).
+   */
+  getProcessManager() {
+    return this.processManager;
+  }
+}
+
+export { AgentProcessManager as A, ProcessManagerAdapter as P };

package/dist/shared/forge-agent-runtime.DlNAoPjs.d.mts

@@ -0,0 +1,122 @@
+import { AIProviderRegistryView } from '@skaile/forge-settings/server';
+
+/**
+ * AgentAdapter — canonical interface for forge agent harnesses.
+ *
+ * Every harness (omp, claude-sdk, codex, …) runs behind an adapter that
+ * implements this interface. Apps depend only on this contract, not the
+ * concrete adapter type.
+ *
+ * Lifecycle:
+ *   1. Call `connect(config)` — spawns the subprocess or initialises the SDK client.
+ *   2. Call `sendCommand(cmd)` to dispatch prompts and control commands.
+ *   3. Call `listen()` to consume the async event stream.
+ *   4. Call `abort()` to cancel an in-flight turn.
+ *   5. Call `disconnect()` to tear down cleanly.
+ *
+ * Adapters are STATEFUL: one instance per active agent session.
+ */
+
+/** Input to the agent: a natural-language prompt or a control message. */
+interface AgentCommand {
+    type: string;
+    [key: string]: unknown;
+}
+/** Output from the agent: any typed event from the skaile protocol. */
+interface AgentEvent {
+    type: string;
+    [key: string]: unknown;
+}
+/** Observable lifecycle state of an adapter instance. */
+type AgentStatus = "idle" | "running" | "error" | "disconnected";
+/**
+ * Configuration passed to `AgentAdapter.connect()`.
+ *
+ * All fields mirror `AgentProcessConfig` from `agent-process.ts`
+ * so the ProcessManagerAdapter can pass them through unchanged.
+ */
+interface AgentAdapterConfig {
+    /** Working directory for the agent (--project-dir) */
+    projectDir: string;
+    /** Bridge harness type (omp, claude-sdk). Defaults to 'omp'. */
+    harness?: string;
+    /**
+     * The AI provider registry the session runs against. The adapter resolves
+     * each enabled entry's credential reference and delivers it through the
+     * child environment.
+     */
+    registry?: AIProviderRegistryView;
+    /**
+     * Registry entry ids the session is restricted to (`--providers a,b`).
+     * Absent or empty: the session sees the whole registry. `registry` should
+     * already be narrowed to the same ids so only their credentials are delivered.
+     */
+    providers?: string[];
+    /**
+     * The layered environment `env:` references resolve against and the child
+     * env is based on; defaults to `process.env`.
+     */
+    credentialEnv?: Record<string, string | undefined>;
+    /** Model selection as `"<providerId>/<modelId>"`, a bare model id, or `@role` */
+    model?: string;
+    /** Environment variables injected into the subprocess */
+    env?: Record<string, string>;
+    /** System prompt written to .skaile/system-prompt.md before spawn */
+    systemPrompt?: string;
+    /** Max agentic turns */
+    maxTurns?: number;
+    /** GitAgent definition directory */
+    agentDir?: string;
+    /** OMP harness session ID for native resume */
+    harnessSessionId?: string;
+    /** Address the subprocess binds and the client dials. Absent: runtime default bind, dial `127.0.0.1`. */
+    host?: string;
+    /** Bearer token the subprocess WebSocket requires and the client presents. Absent: no authentication. */
+    wsAuthToken?: string;
+}
+/**
+ * Canonical interface for all forge agent harnesses.
+ *
+ * Implementations wrap the `AgentProcessManager` pattern used by the existing
+ * forge apps, exposing a minimal async API that higher-level managers consume.
+ */
+interface AgentAdapter {
+    /**
+     * Connect to the agent harness and prepare it for commands.
+     * Must be called once before `sendCommand` or `listen`.
+     */
+    connect(config: AgentAdapterConfig): Promise<void>;
+    /**
+     * Send a command to the connected agent.
+     * Throws if `connect()` has not been called or the session has disconnected.
+     */
+    sendCommand(command: AgentCommand): Promise<void>;
+    /**
+     * Return an async iterable of agent events.
+     * The iterable completes when the adapter disconnects.
+     *
+     * Callers can use `for await (const event of adapter.listen()) { ... }` or
+     * subscribe via an EventEmitter bridge (see BaseAgentManager).
+     */
+    listen(): AsyncIterable<AgentEvent>;
+    /**
+     * Cancel the current in-flight agent turn.
+     * No-op if the agent is idle.
+     */
+    abort(): Promise<void>;
+    /**
+     * Whether the adapter is connected and the agent is ready to receive commands.
+     */
+    isConnected(): boolean;
+    /**
+     * Observable lifecycle state.
+     */
+    getStatus(): AgentStatus;
+    /**
+     * Tear down the adapter: disconnect, stop subprocess if applicable, release resources.
+     * Safe to call multiple times.
+     */
+    disconnect(): Promise<void>;
+}
+
+export type { AgentEvent as A, AgentAdapter as a, AgentAdapterConfig as b, AgentCommand as c, AgentStatus as d };