@moondeck/station 0.0.0-stage → 1.0.0

package/lib/agents/durable-proc.ts

@@ -0,0 +1,334 @@
+import { StringDecoder } from "node:string_decoder";
+import { agentOutputSource } from "./output-source";
+/**
+ * DurableProcess (ADR-061) — LineProcess's durable twin. Instead of holding
+ * the agent CLI's pipes, it talks to the in-container runner
+ * (runner/runner.mjs) through two append-only JSONL files on the
+ * task-workspace bind mount:
+ *
+ *   writeLine()  → append to <sessionDir>/inbox.jsonl
+ *   onLine()     ← poll-tail <sessionDir>/outbox.jsonl from a byte offset
+ *
+ * The CLI's lifetime is decoupled from this object: dropping it (host
+ * restart) leaves the runner and CLI running; `attach()` with the persisted
+ * outbox offset resumes exactly where consumption stopped. `close()` is the
+ * real teardown — it sends the runner a stop control.
+ *
+ * Exit is observed via the runner's `{"__uai":"exit"}` meta line, with a
+ * stale-heartbeat check as the backstop for a killed container. Meta lines
+ * never reach onLine handlers — adapters see the same protocol stream
+ * LineProcess gave them.
+ */
+
+import { fileURLToPath } from "node:url";
+
+import {
+  appendContainedFile,
+  containedModifiedAt,
+  NotARegularFileError,
+  readContainedFrom,
+  WorkspacePathRefusedError,
+} from "../task-environment/workspace-files";
+
+import type { ExitHandler, LineHandler } from "./proc";
+
+const POLL_MS = 75;
+/** Runner beats every 5 s; 25 s of silence without an exit meta = dead. */
+const HEARTBEAT_STALE_MS = 25_000;
+/** After close(), how long to wait for the exit meta before giving up. */
+const CLOSE_GRACE_MS = 8_000;
+
+/** Host-side absolute path of the bundled in-container runner script. */
+export function runnerScriptPath(): string {
+  return fileURLToPath(new URL("../../runner/runner.mjs", import.meta.url));
+}
+
+export interface DurableProcessOptions {
+  /** Session dir as seen FROM THE HOST (on the workspace bind mount). */
+  hostSessionDir: string;
+  /** The same directory as the task's workspace root and its components
+   *  below it: every file in it is reached never through a link the task
+   *  put there (#cb3j0z). It exists before the runner is launched. */
+  sessionFiles: { root: string; parts: readonly string[] };
+  /** Settles once that directory has been made, where only the task's
+   *  runtime can make it (macOS, #cb3j0z): no inbox write, the stop
+   *  included, is attempted before. Absent: it exists already. */
+  ready?: Promise<void>;
+  /** Provider-owned detached launch. Omit to attach to an existing runner. */
+  launch?: () => Promise<{
+    exitCode: number | null;
+    stderr: Uint8Array;
+  }>;
+  /** Resume consumption from this outbox byte offset (attach path). */
+  initialOutboxOffset?: number;
+  /** Called after each poll batch whose lines were delivered — persist this
+   *  offset so a host restart resumes here instead of replaying. */
+  onOffsetAdvance?: (offset: number) => void;
+  /** Called the moment close() is requested (before the runner has actually
+   *  died) — lets the owner mark the session unattachable immediately, so a
+   *  re-create during the teardown grace window spawns fresh instead of
+   *  attaching to a dying runner. */
+  onCloseRequested?: () => void;
+  /** Mirrors LineProcess: log raw traffic when UAI_DEBUG_AGENTS is set. */
+  debugLabel?: string;
+}
+
+interface RunnerMeta {
+  __uai: string;
+  code?: number | null;
+  stderrTail?: string;
+}
+
+export class DurableProcess {
+  readonly durableSessionDir: string;
+  private readonly root: string;
+  private readonly outbox: readonly string[];
+  private readonly inbox: readonly string[];
+  private readonly heartbeat: readonly string[];
+
+  private readonly decoder = new StringDecoder("utf8");
+  private lineOffset = 0;
+  private readonly lineHandlers = new Set<LineHandler>();
+  private readonly exitHandlers = new Set<ExitHandler>();
+
+  private offset: number;
+  private lineBuf = "";
+  private stderrBuf = "";
+  private closed = false;
+  private detached = false;
+  private sawSpawnMeta = false;
+  private readonly startedAt = Date.now();
+  private poller: ReturnType<typeof setInterval> | null = null;
+  private closeTimer: ReturnType<typeof setTimeout> | null = null;
+  private inboxChain: Promise<void> = Promise.resolve();
+  private readonly onOffsetAdvance: ((offset: number) => void) | null;
+  private readonly onCloseRequested: (() => void) | null;
+  private readonly debug: string | null;
+
+  constructor(opts: DurableProcessOptions) {
+    this.durableSessionDir = opts.hostSessionDir;
+    this.root = opts.sessionFiles.root;
+    this.outbox = [...opts.sessionFiles.parts, "outbox.jsonl"];
+    this.inbox = [...opts.sessionFiles.parts, "inbox.jsonl"];
+    this.heartbeat = [...opts.sessionFiles.parts, "heartbeat"];
+    this.offset = opts.initialOutboxOffset ?? 0;
+    this.lineOffset = this.offset;
+    this.onOffsetAdvance = opts.onOffsetAdvance ?? null;
+    this.onCloseRequested = opts.onCloseRequested ?? null;
+    if (opts.ready) {
+      this.inboxChain = opts.ready.then(
+        () => undefined,
+        () => undefined,
+      );
+    }
+    this.debug =
+      opts.debugLabel && process.env.UAI_DEBUG_AGENTS ? opts.debugLabel : null;
+
+    if (opts.launch) {
+      void opts.launch().then(
+        (result) => {
+          const stderr = Buffer.from(result.stderr).toString("utf8");
+          if (stderr) this.stderrBuf = (this.stderrBuf + stderr).slice(-8192);
+          if (result.exitCode !== 0) this.finish(null);
+        },
+        (error: unknown) => {
+          this.stderrBuf = (
+            this.stderrBuf +
+            (error instanceof Error ? error.message : String(error))
+          ).slice(-8192);
+          this.finish(null);
+        },
+      );
+    } else {
+      this.sawSpawnMeta = true; // attach: the runner pre-exists
+    }
+
+    this.poller = setInterval(() => this.poll(), POLL_MS);
+  }
+
+  private log(msg: string): void {
+    console.error(`[uai-agent ${this.debug}] ${msg}`);
+  }
+
+  // ---- outbox tail ---------------------------------------------------------
+
+  private poll(): void {
+    if (this.closed || this.detached) return;
+    const before = this.offset;
+    try {
+      for (;;) {
+        const read = readContainedFrom(this.root, this.outbox, this.offset, 256 * 1024);
+        if (read === null) break; // outbox not created yet
+        if (read.bytes.length === 0) break;
+        this.offset += read.bytes.length;
+        this.lineBuf += this.decoder.write(read.bytes);
+        this.drainLines();
+        if (this.offset >= read.size) break;
+      }
+    } catch (error) {
+      if (error instanceof WorkspacePathRefusedError || error instanceof NotARegularFileError) {
+        // A link, or anything but a regular file, where the outbox is: the
+        // task broke its own session, and it ends (#cb3j0z).
+        this.finish(null);
+        return;
+      }
+      // Anything else may pass: the heartbeat decides, below.
+    }
+    if (this.offset !== before && this.onOffsetAdvance && !this.closed) {
+      try {
+        this.onOffsetAdvance(this.lineOffset);
+      } catch {
+        // Persistence hiccup — the next batch retries with a larger offset.
+      }
+    }
+    this.checkLiveness();
+  }
+
+  private drainLines(): void {
+    let nl: number;
+    while ((nl = this.lineBuf.indexOf("\n")) >= 0) {
+      const rawLine = this.lineBuf.slice(0, nl);
+      this.lineOffset += Buffer.byteLength(rawLine) + 1;
+      const line = rawLine.trim();
+      this.lineBuf = this.lineBuf.slice(nl + 1);
+      if (line.length === 0) continue;
+      if (line.startsWith('{"__uai"')) {
+        this.handleMeta(line);
+        continue;
+      }
+      if (this.debug) this.log(`<- ${line.slice(0, 1000)}`);
+      for (const h of this.lineHandlers) {
+        try {
+          agentOutputSource.run(this.durableSessionDir + ":" + this.lineOffset, () => h(line));
+        } catch {
+          // A broken handler must not wedge the tail loop.
+        }
+      }
+    }
+  }
+
+  private handleMeta(line: string): void {
+    let meta: RunnerMeta;
+    try {
+      meta = JSON.parse(line) as RunnerMeta;
+    } catch {
+      return;
+    }
+    if (meta.__uai === "spawn") {
+      this.sawSpawnMeta = true;
+    } else if (meta.__uai === "exit") {
+      if (typeof meta.stderrTail === "string" && meta.stderrTail) {
+        this.stderrBuf = meta.stderrTail.slice(-8192);
+      }
+      if (this.debug) this.log(`exit meta: code ${meta.code ?? null}`);
+      this.finish(typeof meta.code === "number" ? meta.code : null);
+    }
+  }
+
+  /** Backstop: no exit meta, but the runner stopped beating → it's gone. */
+  private checkLiveness(): void {
+    if (!this.sawSpawnMeta) {
+      // Runner never wrote anything; give the spawn a grace window.
+      if (Date.now() - this.startedAt > HEARTBEAT_STALE_MS) this.finish(null);
+      return;
+    }
+    let beat: number | null = null;
+    try {
+      beat = containedModifiedAt(this.root, this.heartbeat);
+    } catch {
+      beat = null;
+    }
+    if (beat !== null) {
+      if (Date.now() - beat > HEARTBEAT_STALE_MS) this.finish(null);
+    } else if (Date.now() - this.startedAt > HEARTBEAT_STALE_MS) {
+      this.finish(null);
+    }
+  }
+
+  private finish(code: number | null): void {
+    if (this.closed) return;
+    this.closed = true;
+    if (this.poller) clearInterval(this.poller);
+    if (this.closeTimer) clearTimeout(this.closeTimer);
+    for (const h of this.exitHandlers) h(code);
+  }
+
+  // ---- LineProcess-compatible surface ---------------------------------------
+
+  onLine(handler: LineHandler): void {
+    this.lineHandlers.add(handler);
+  }
+
+  onExit(handler: ExitHandler): void {
+    this.exitHandlers.add(handler);
+  }
+
+  /**
+   * Serialise `value` as one JSONL line appended to the runner's inbox.
+   * A runner-filtered metadata line immediately before it supplies the local
+   * timestamp without changing the protocol frame forwarded to the CLI. Old
+   * runners already ignore unknown `__uai` lines, so attached sessions remain
+   * wire-compatible across the host update.
+   *
+   * `__uai` MUST stay the first key of the metadata object. Both runners filter
+   * with `line.startsWith('{"__uai"')` — a byte prefix, not a parse — so
+   * serialising the keys in any other order emits `{"ts":…`, which the runner
+   * then forwards to the CLI's stdin as a user turn. No type in this file
+   * expresses that, and a `toEqual` assertion cannot see it; the raw-prefix
+   * check in `durable-proc.test.ts` is what pins it.
+   */
+  writeLine(value: unknown): void {
+    if (this.closed || this.detached) return;
+    const json = JSON.stringify(value);
+    const inputMeta = JSON.stringify({ __uai: "input", ts: Date.now() });
+    if (this.debug) this.log(`-> ${json.slice(0, 1000)}`);
+    // Chain appends so concurrent writes can't interleave bytes.
+    this.inboxChain = this.inboxChain
+      .then(() => appendContainedFile(this.root, this.inbox, Buffer.from(`${inputMeta}\n${json}\n`)))
+      .catch(() => {
+        // Disk error — liveness checks will surface a dead session.
+      });
+  }
+
+  get stderrTail(): string {
+    return this.stderrBuf;
+  }
+
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  /** Consumed-outbox byte offset — persist this to survive host restarts. */
+  get outboxOffset(): number {
+    return this.lineOffset;
+  }
+
+  /**
+   * Stop consuming WITHOUT touching the runner — the host-restart path in
+   * miniature (a replaced consumer, a shutting-down host). The CLI lives on;
+   * a later attach() resumes from the persisted offset.
+   */
+  detach(): void {
+    if (this.detached || this.closed) return;
+    this.detached = true;
+    if (this.poller) clearInterval(this.poller);
+    if (this.closeTimer) clearTimeout(this.closeTimer);
+  }
+
+  /** Real teardown: ask the runner to stop its CLI, then observe the exit. */
+  async close(): Promise<void> {
+    if (this.closed || this.detached) return;
+    try {
+      this.onCloseRequested?.();
+    } catch {
+      // Bookkeeping only — never blocks the teardown itself.
+    }
+    try {
+      await this.inboxChain;
+      await appendContainedFile(this.root, this.inbox, Buffer.from('{"__uai":"stop"}\n'));
+    } catch {
+      // Inbox unwritable — fall through to the grace timer.
+    }
+    this.closeTimer = setTimeout(() => this.finish(null), CLOSE_GRACE_MS);
+  }
+}

package/lib/agents/factory.ts

@@ -0,0 +1,57 @@
+/**
+ * realAgentFactory — builds a real AgentSession per roster agent, resolving
+ * the adapter from the plug-in registry by `agent.kind` (ADR-021).
+ *
+ * Importing this module pulls in `./claude` and `./codex` purely for their
+ * side effect: each calls `register()` at load, populating the registry.
+ * Adding a kind is then "drop a module + import it for its side effect" — no
+ * change here. Unknown kinds fail loudly so a typo in a roster surfaces as an
+ * error rather than silently falling back to the wrong CLI.
+ *
+ * Adapters run their CLI through the task environment's provider-owned
+ * session surface; the agent's `model` (if set) is passed through. Swapping
+ * mock ⇄ real is changing which factory the orchestrator is constructed with
+ * — see `getOrchestrator`.
+ */
+
+// Side-effect imports: register the built-in adapters with the registry.
+import "./claude";
+import "./codex";
+import "./kimi";
+import "./grok";
+import "./cursor";
+import "./opencode";
+import "./uai";
+
+import { agentClisReady } from "../standard-image";
+import { factoryFor, supportsExecutionProfile } from "./registry";
+import type { AgentSession, AgentSessionFactory } from "./types";
+
+export const realAgentFactory: AgentSessionFactory = {
+  create: async (args): Promise<AgentSession> => {
+    const factory = factoryFor(args.agent.kind);
+    if (!factory) {
+      throw new Error(
+        `no agent adapter registered for kind "${args.agent.kind}"`,
+      );
+    }
+    if (
+      args.executionProfile &&
+      !supportsExecutionProfile(args.agent.kind, args.executionProfile)
+    ) {
+      throw new Error(
+        `agent adapter "${args.agent.kind}" cannot enforce execution profile "${args.executionProfile}"`,
+      );
+    }
+    // Don't spawn a CLI until the shared-volume agent CLIs are reconciled:
+    // at boot the CLI auto-upgrade briefly removes then reinstalls codex/claude,
+    // and a resume that races that window dies with "No codex executable found
+    // for nodejs X". Post-boot this is already resolved (instant).
+    // Fail closed: the maintenance commands have their own process timeouts
+    // and settle this latch even on failure. A second timeout here would let a
+    // CLI spawn enter the shared volume while boot reconciliation still owns
+    // its remove/reinstall window.
+    await agentClisReady;
+    return factory.create(args);
+  },
+};