@moondeck/station 0.0.0-stage → 1.0.0

package/lib/agents/registry.ts

@@ -0,0 +1,182 @@
+/**
+ * Agent adapter registry (ADR-021).
+ *
+ * A small module-level registry so adding an agent kind is mechanical and
+ * needs no uai-core change: an adapter module calls `register()` at load,
+ * declaring its `kind`, display `label`, the models it can drive, an
+ * optional `defaultModel`, and a `create()` that builds an `AgentSession`.
+ *
+ * The host derives two things from the registry:
+ *   - `factoryFor(kind)` — used by the real agent factory to construct a
+ *     session for a roster entry by its `kind`.
+ *   - `capabilities()` — the `agentKinds` slice of the `host.capabilities`
+ *     frame, computed straight from the registered adapters.
+ *
+ * Registration is side-effect-on-import: importing `./claude` and `./codex`
+ * runs their `register()` calls (see `factory.ts`, which imports them).
+ */
+
+import type { AgentSessionFactory } from "./types";
+
+/** A registered agent adapter — metadata plus the session factory. */
+export interface RegisteredAdapter {
+  /** Host-advertised agent kind ("claude" | "codex" | "gemini" | …). */
+  kind: string;
+  /** Display name for the cloud picker. */
+  label: string;
+  /** Models this adapter can drive (CLI `--model` / `-c model=` values). */
+  supportedModels(): string[];
+  /** Preferred model when the user doesn't pick one. */
+  defaultModel?: string;
+  /** Reasoning levels this adapter can drive (CLI effort values). */
+  supportedEfforts(): string[];
+  /** Preferred effort when the user doesn't pick one. */
+  defaultEffort?: string;
+  /** Restricted profiles this adapter can enforce by construction. */
+  executionProfiles?: Array<{
+    id: string;
+    mechanism: string;
+    defaultModel?: string;
+    defaultEffort?: string;
+  }>;
+  /**
+   * Whether this kind is usable on THIS host right now — i.e. its credentials
+   * are present (ADR-044 P2). Gates advertisement: an unavailable kind is left
+   * out of `capabilities()` so the cloud's task picker doesn't offer an LLM the
+   * host can't actually run. Omit (or return true) to always advertise; the
+   * session factory stays permissive regardless.
+   */
+  available?: () => boolean;
+  /** Builds an AgentSession for a roster entry of this kind. */
+  create: AgentSessionFactory["create"];
+}
+
+/** One entry of the `host.capabilities` frame's `agentKinds`. */
+export interface AgentKindCapability {
+  kind: string;
+  label: string;
+  supportedModels: string[];
+  defaultModel?: string;
+  supportedEfforts: string[];
+  defaultEffort?: string;
+  executionProfiles?: Array<{
+    id: string;
+    mechanism: string;
+    defaultModel?: string;
+    defaultEffort?: string;
+  }>;
+}
+
+const adapters = new Map<string, RegisteredAdapter>();
+
+/** Listeners fired after any registry mutation (manual re-advertise hook). */
+const changeListeners = new Set<() => void>();
+
+/**
+ * ADR-131 D3: a second source of "usable on this host" beyond the adapter's
+ * own `available()`, which only sees the host's default credential. The host
+ * agent installs the engine-account store here so a kind with a stored
+ * (workspace- or host-scoped) account is advertised even when the owner never
+ * signed in to it. Installed by main.ts; absent in unit tests.
+ */
+let advertisementFallback: (kind: string) => boolean = () => false;
+
+export function setAdvertisementFallback(
+  fallback: ((kind: string) => boolean) | null,
+): void {
+  advertisementFallback = fallback ?? (() => false);
+}
+
+/**
+ * ADR-154 §10: on cloud credentials the runner holds no engine credential of
+ * its own, so availability and the fallback above say nothing: the kinds a
+ * leased task can run are advertised, and only those (`CLOUD_CREDENTIAL_KINDS`:
+ * the leased lanes and the Managed Engine). Null while the runner runs its
+ * tasks on its own credentials. Installed by main.ts.
+ */
+let leasedKinds: () => ReadonlySet<string> | null = () => null;
+
+export function setLeasedAdvertisement(
+  source: (() => ReadonlySet<string> | null) | null,
+): void {
+  leasedKinds = source ?? (() => null);
+}
+
+/**
+ * Register (or replace) an adapter for a kind. Called at module load by the
+ * adapter modules. Replacing is allowed so a later import wins deterministically.
+ */
+export function register(adapter: RegisteredAdapter): void {
+  adapters.set(adapter.kind, adapter);
+  for (const listener of changeListeners) listener();
+}
+
+/** Every registered adapter, in insertion order. */
+export function list(): RegisteredAdapter[] {
+  return [...adapters.values()];
+}
+
+/** The session factory for a kind, or undefined if no adapter is registered. */
+export function factoryFor(kind: string): AgentSessionFactory | undefined {
+  const adapter = adapters.get(kind);
+  return adapter ? { create: adapter.create } : undefined;
+}
+
+/** Whether the adapter declares an engine-enforced execution profile. */
+export function supportsExecutionProfile(kind: string, profileId: string): boolean {
+  return Boolean(
+    adapters
+      .get(kind)
+      ?.executionProfiles?.some((profile) => profile.id === profileId),
+  );
+}
+
+/**
+ * The `agentKinds` capability slice, derived from the registered adapters.
+ * Each adapter's `supportedModels()` / `supportedEfforts()` is evaluated here.
+ */
+export function capabilities(): AgentKindCapability[] {
+  const leased = leasedKinds();
+  return list()
+    .filter((adapter) =>
+      leased !== null
+        ? leased.has(adapter.kind)
+        : (adapter.available?.() ?? true) || advertisementFallback(adapter.kind),
+    )
+    .map((adapter) => {
+      const out: AgentKindCapability = {
+        kind: adapter.kind,
+        label: adapter.label,
+        supportedModels: adapter.supportedModels(),
+        supportedEfforts: adapter.supportedEfforts(),
+      };
+      if (adapter.defaultModel !== undefined) {
+        out.defaultModel = adapter.defaultModel;
+      }
+      if (adapter.defaultEffort !== undefined) {
+        out.defaultEffort = adapter.defaultEffort;
+      }
+      if (adapter.executionProfiles && adapter.executionProfiles.length > 0) {
+        out.executionProfiles = adapter.executionProfiles.map((profile) => ({
+          ...profile,
+        }));
+      }
+      return out;
+    });
+}
+
+/**
+ * Subscribe to registry changes (adapter added/replaced). Returns an
+ * unsubscribe. Used to re-send the capability frame on change.
+ */
+export function onChange(listener: () => void): () => void {
+  changeListeners.add(listener);
+  return () => changeListeners.delete(listener);
+}
+
+/** Test/maintenance hook: drop all adapters and listeners. */
+export function reset(): void {
+  adapters.clear();
+  changeListeners.clear();
+  advertisementFallback = () => false;
+}

package/lib/agents/session-state.ts

@@ -0,0 +1,197 @@
+/**
+ * Durable agent-session state used by live roster reconciliation.
+ *
+ * The orchestrator normally owns a live AgentSession and closes it through the
+ * adapter. After a host restart, however, a removed agent can exist only as a
+ * host_agent_sessions row. These helpers stop that persisted runner
+ * without deleting its row or generation directory, and clear Codex's durable
+ * thread id when launch settings change.
+ */
+
+
+import { isOwnedInternalConnectionRuntime } from "../internal-connections";
+import { spawn } from "node:child_process";
+import { and, eq } from "drizzle-orm";
+
+import { getDb, schema } from "../db";
+import { taskWorkspaceDir } from "../env";
+import {
+  appendContainedFile,
+  hostPathParts,
+  WorkspaceDirectoryMissingError,
+} from "../task-environment/workspace-files";
+import type { TaskEnvironmentHandle } from "../task-environment/types";
+import { isEnvironmentTransportProvider } from "../task-environment/types";
+import {
+  stopMachinePredecessorStrict,
+  type MachineSessionEnvironment,
+} from "./machine-durable";
+
+/** Durable-session ids persisted for one task, including rows marked closed.
+ * A crash can land after markClosed but before its stop reaches the runner. */
+export function persistedAgentIds(taskId: string): string[] {
+  return getDb()
+    .select({ agentId: schema.hostAgentSessions.agentId })
+    .from(schema.hostAgentSessions)
+    .where(eq(schema.hostAgentSessions.taskId, taskId))
+    .all()
+    .map((row) => row.agentId);
+}
+
+/**
+ * A changed model/engine/effort starts a fresh Codex thread. The channel
+ * transcript is the durable memory; resuming a thread created under the old
+ * launch settings can make the replacement keep using the old model.
+ */
+export function clearPersistedCodexThread(
+  taskId: string,
+  agentId: string,
+): void {
+  getDb()
+    .update(schema.hostAgentSessions)
+    .set({ codexThreadId: null, updatedAt: Date.now() })
+    .where(
+      and(
+        eq(schema.hostAgentSessions.taskId, taskId),
+        eq(schema.hostAgentSessions.agentId, agentId),
+      ),
+    )
+    .run();
+}
+
+/**
+ * Stop a persisted runner that has no in-memory AgentSession (boot recovery).
+ * The session directory and DB row deliberately remain for diagnostics.
+ */
+export async function stopPersistedAgentSession(
+  taskId: string,
+  agentId: string,
+  environment: TaskEnvironmentHandle<unknown>,
+): Promise<string | null> {
+  const db = getDb();
+  const row = db
+    .select()
+    .from(schema.hostAgentSessions)
+    .where(
+      and(
+        eq(schema.hostAgentSessions.taskId, taskId),
+        eq(schema.hostAgentSessions.agentId, agentId),
+      ),
+    )
+    .get();
+  if (!row) return null;
+
+  if (isEnvironmentTransportProvider(environment.descriptor.locator.provider)) {
+    await stopMachinePredecessorStrict(
+      environment as MachineSessionEnvironment,
+      row.sessionDir,
+    );
+  } else {
+    // Never through a link the task put in the session's place (#cb3j0z).
+    const root = taskWorkspaceDir(taskId);
+    let parts: string[] | null;
+    try {
+      parts = hostPathParts(root, row.sessionDir);
+    } catch {
+      // Not below the task's workspace: no runner of this task reads it.
+      parts = null;
+    }
+    if (parts !== null) {
+      try {
+        await appendContainedFile(root, [...parts, "inbox.jsonl"], Buffer.from('{"__uai":"stop"}\n'));
+      } catch (err) {
+        // A removed generation directory proves there is no runner left to
+        // read it. Permission, I/O, and other failures are not proof: retry
+        // them.
+        if (!(err instanceof WorkspaceDirectoryMissingError)) throw err;
+      }
+    }
+  }
+
+  db.update(schema.hostAgentSessions)
+    .set({ status: "closed", updatedAt: Date.now() })
+    .where(
+      and(
+        eq(schema.hostAgentSessions.taskId, taskId),
+        eq(schema.hostAgentSessions.agentId, agentId),
+        eq(schema.hostAgentSessions.sessionDir, row.sessionDir),
+      ),
+    )
+    .run();
+  return row.sessionDir;
+}
+
+/** Remove internal runner generations only after the caller has proven every
+ * covered anchored process stopped. The persisted compatibility key survives
+ * restart and binds this deletion to the run and credential being cleaned. */
+export async function purgeInternalAgentSessionState(
+  request: { taskId: string; runEpoch: number; credentialIds?: readonly string[] },
+  environments: readonly TaskEnvironmentHandle<unknown>[],
+  removeDirectory: (root: string, path: string) => Promise<void> = removeInternalSessionDirectory,
+): Promise<void> {
+  const db = getDb();
+  const rows = db.select().from(schema.hostAgentSessions).where(eq(schema.hostAgentSessions.taskId, request.taskId)).all();
+  for (const row of rows) {
+    let key: unknown;
+    try { key = JSON.parse(row.attachCompatibilityKey ?? "null"); } catch { continue; }
+    if (!Array.isArray(key) || key[1] !== "lease-v1" || !Number.isSafeInteger(key[2]) || key[2] > request.runEpoch || key.at(-1) !== "custom-internal" ||
+      (request.credentialIds && !request.credentialIds.includes(key[3] as string))) continue;
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(row.agentId)) throw new Error("unsupported");
+    if (!environments.length) throw new Error("unsupported");
+    // Owned-runtime workspaces are host mounts; they persist even after the
+    // container disappears. Delete through host directory FDs, not exec into
+    // a container which may already be stopped/absent.
+    if (environments.some(e => e.descriptor.taskId !== request.taskId || !isOwnedInternalConnectionRuntime(e.descriptor.locator.provider))) throw new Error("unsupported");
+    const root = taskWorkspaceDir(request.taskId);
+    await removeDirectory(root, `${root}/.moondeck/sessions/${row.agentId}`);
+    db.delete(schema.hostAgentSessions).where(and(eq(schema.hostAgentSessions.taskId, row.taskId), eq(schema.hostAgentSessions.agentId, row.agentId), eq(schema.hostAgentSessions.sessionDir, row.sessionDir))).run();
+  }
+}
+
+/** FD-relative tree removal. A task can
+ * replace entries concurrently; links are never followed, and a race fails
+ * closed for the cleanup coordinator to retry. No provider text is read. */
+export const INTERNAL_SESSION_UNLINK_HELPER = String.raw`
+import os, stat, sys
+root, absolute = sys.argv[1:3]
+prefix = root.rstrip("/") + "/"
+if not absolute.startswith(prefix): raise RuntimeError()
+parts = absolute[len(prefix):].split("/")
+if not parts or any(p in ("", ".", "..") for p in parts): raise RuntimeError()
+flags = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW
+fds = []
+def remove(parent, name):
+    try: info = os.stat(name, dir_fd=parent, follow_symlinks=False)
+    except FileNotFoundError: return
+    if not stat.S_ISDIR(info.st_mode): raise RuntimeError()
+    child = os.open(name, flags, dir_fd=parent)
+    try:
+        for entry in os.listdir(child):
+            info = os.stat(entry, dir_fd=child, follow_symlinks=False)
+            if stat.S_ISDIR(info.st_mode): remove(child, entry)
+            else: os.unlink(entry, dir_fd=child)
+    finally: os.close(child)
+    os.rmdir(name, dir_fd=parent)
+try:
+    current = os.open("/", flags); fds.append(current)
+    for p in root.split("/") + parts[:-1]:
+        if not p: continue
+        current = os.open(p, flags, dir_fd=current); fds.append(current)
+    remove(current, parts[-1])
+    try: os.stat(parts[-1], dir_fd=current, follow_symlinks=False)
+    except FileNotFoundError: sys.exit(0)
+    raise RuntimeError()
+except FileNotFoundError: sys.exit(0)
+finally:
+    for fd in reversed(fds): os.close(fd)
+`;
+function removeInternalSessionDirectory(root: string, path: string): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn("/usr/bin/python3", ["-I", "-", root, path], { stdio: ["pipe", "ignore", "ignore"], env: { PATH: "/usr/bin:/bin" } });
+    const timer = setTimeout(() => { proc.kill("SIGKILL"); reject(new Error("unsupported")); }, 10_000);
+    proc.on("error", () => { clearTimeout(timer); reject(new Error("unsupported")); });
+    proc.on("exit", code => { clearTimeout(timer); if (code === 0) resolve(); else reject(new Error("unsupported")); });
+    proc.stdin.on("error", () => {});
+    proc.stdin.end(INTERNAL_SESSION_UNLINK_HELPER);
+  });
+}

package/lib/agents/skill-index-preamble.fixture.ts

@@ -0,0 +1,26 @@
+/**
+ * ADR-166: the preamble an indexed agent's engine receives, from the real
+ * builder, for the per-engine adapter tests (claude, codex, grok).
+ */
+import { buildSystemPreamble } from "../orchestrator";
+import type { RosterAgent } from "./types";
+
+export const INDEXED_SKILLS: NonNullable<RosterAgent["skills"]> = [
+  { name: "Brand voice", type: "document", value: "Plain and warm." },
+  { name: "Design tokens", type: "document", value: "The scales." },
+];
+
+/** The skills pointer every engine must carry for an indexed agent. */
+export const INDEX_POINTER = /Your skills are indexed at `\/workspace\/\.moondeck\/agents\/[\w-]+\/SKILL\.md`: "Brand voice" and "Design tokens"\. Read the index at the start\. Before work a skill covers, or an action the index names, read that file in full with `cat`/;
+
+export function indexedPreamble(agent: RosterAgent): string {
+  const withSkills = { ...agent, skills: INDEXED_SKILLS };
+  return buildSystemPreamble(
+    [withSkills],
+    withSkills,
+    [{ slug: "repo", defaultPrompt: "" } as never],
+    undefined,
+    "/workspace",
+    "task/x",
+  );
+}