@app-vitals/agent-runtime 0.0.0-stage → 0.1.0

package/entrypoint.integration.test.ts

@@ -0,0 +1,315 @@
+/**
+ * agent/src/runtime/entrypoint.integration.test.ts
+ *
+ * Integration tests for the startup sequence in entrypoint.ts.
+ * Uses RecordedShipwrightConfigClient (cassette-backed) — no real HTTP.
+ * Isolation contract: no mock.module(), no global overrides.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import type { AgentConfigResponse } from "@app-vitals/agent-admin";
+import type { EntrypointDeps } from "./entrypoint.ts";
+import { runEntrypoint } from "./entrypoint.ts";
+import type { ShipwrightConfigClient } from "./shipwright-config-client.ts";
+import { RecordedShipwrightConfigClient } from "./shipwright-config-client.ts";
+
+// ─── Test fixtures ─────────────────────────────────────────────────────────────
+
+const SAMPLE_CONFIG: AgentConfigResponse = {
+  env: {
+    ANTHROPIC_MODEL: "claude-sonnet-4-6",
+    CUSTOM_VAR: "custom-value",
+  },
+  allowedTools: ["Read", "Write", "Bash"],
+  plugins: [{ marketplace: "my-market", plugin: "my-plugin" }],
+  repos: [],
+  reviewAuthorAllowlist: [],
+  patchAuthorAllowlist: [],
+  restrictSlackToMembers: false,
+  memberEmails: [],
+  autoPostReviews: true,
+  allowSelfReview: false,
+  minConfidence: 75,
+  maxFindings: 5,
+  cleanupMergedWorktrees: true,
+  cleanupAfterDays: 14,
+};
+
+// ─── Temp dir helpers ──────────────────────────────────────────────────────────
+
+const TMP_BASE = "/tmp/test-entrypoint-home";
+let testHome: string;
+let testClaudeTarget: string;
+
+beforeEach(() => {
+  const id = `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  testHome = `${TMP_BASE}-${id}`;
+  testClaudeTarget = `${testHome}/dot-claude`;
+  mkdirSync(testHome, { recursive: true });
+  mkdirSync(testClaudeTarget, { recursive: true });
+});
+
+afterEach(() => {
+  if (existsSync(testHome)) {
+    rmSync(testHome, { recursive: true, force: true });
+  }
+});
+
+// ─── Helpers ───────────────────────────────────────────────────────────────────
+
+interface SpawnCall {
+  cmd: string;
+  args: string[];
+}
+
+interface SetupGitHubAuthCall {
+  called: boolean;
+}
+
+function makeDeps(
+  configClient: ShipwrightConfigClient,
+  overrides: Partial<EntrypointDeps> = {},
+): {
+  deps: EntrypointDeps;
+  spawnCalls: SpawnCall[];
+  appliedEnv: Record<string, string>;
+  symlinkCalls: Array<{ target: string; linkPath: string }>;
+  githubAuthCalled: SetupGitHubAuthCall;
+  miseCalls: string[][];
+  pluginCalls: string[];
+  exitCodes: number[];
+} {
+  const spawnCalls: SpawnCall[] = [];
+  const appliedEnv: Record<string, string> = {};
+  const symlinkCalls: Array<{ target: string; linkPath: string }> = [];
+  const githubAuthCalled: SetupGitHubAuthCall = { called: false };
+  const miseCalls: string[][] = [];
+  const pluginCalls: string[] = [];
+  const exitCodes: number[] = [];
+
+  const deps: EntrypointDeps = {
+    agentId: "test-agent-id",
+    apiUrl: "https://api.test.com",
+    apiKey: "test-key",
+    agentHome: testHome,
+    configClient,
+    applyEnv: (env: Record<string, string>) => {
+      Object.assign(appliedEnv, env);
+    },
+    symlinkDotClaude: (target: string, linkPath: string) => {
+      symlinkCalls.push({ target, linkPath });
+    },
+    setupGitHubAuth: async () => {
+      githubAuthCalled.called = true;
+    },
+    runMiseStartup: async (_home: string, _execFn) => {
+      miseCalls.push(["runMiseStartup", _home]);
+      return Promise.resolve();
+    },
+    installPlugins: async (_execFn, _cwd, plugins) => {
+      pluginCalls.push(...(plugins ?? []).map((p) => p.plugin));
+      return Promise.resolve();
+    },
+    spawnAgentServer: (cmd: string, args: string[]) => {
+      spawnCalls.push({ cmd, args });
+    },
+    exit: (code: number) => {
+      exitCodes.push(code);
+    },
+    ...overrides,
+  };
+
+  return {
+    deps,
+    spawnCalls,
+    appliedEnv,
+    symlinkCalls,
+    githubAuthCalled,
+    miseCalls,
+    pluginCalls,
+    exitCodes,
+  };
+}
+
+// ─── Tests ────────────────────────────────────────────────────────────────────
+
+describe("runEntrypoint — happy path", () => {
+  it("exports the specialty to the server process when the config carries one (ARD-6.1)", async () => {
+    const configClient = new RecordedShipwrightConfigClient({
+      ...SAMPLE_CONFIG,
+      typeName: "specialist",
+    });
+    const { deps, appliedEnv } = makeDeps(configClient);
+    await runEntrypoint(deps);
+    expect(appliedEnv.SHIPWRIGHT_AGENT_TYPE).toBe("specialist");
+  });
+
+  it("does not set SHIPWRIGHT_AGENT_TYPE when the config has no typeName (ARD-6.1)", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, appliedEnv } = makeDeps(configClient);
+    await runEntrypoint(deps);
+    expect(appliedEnv.SHIPWRIGHT_AGENT_TYPE).toBeUndefined();
+  });
+
+  it("fetches config and applies env vars from the bundle", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, appliedEnv } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(appliedEnv.ANTHROPIC_MODEL).toBe("claude-sonnet-4-6");
+    expect(appliedEnv.CUSTOM_VAR).toBe("custom-value");
+  });
+
+  it("symlinks ~/.claude to $AGENT_HOME/dot-claude", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, symlinkCalls } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(symlinkCalls.length).toBe(1);
+    expect(symlinkCalls[0].target).toBe(join(testHome, "dot-claude"));
+  });
+
+  it("calls setupGitHubAuth", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, githubAuthCalled } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(githubAuthCalled.called).toBe(true);
+  });
+
+  it("calls runMiseStartup with agentHome", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, miseCalls } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(miseCalls.length).toBe(1);
+    expect(miseCalls[0][1]).toBe(testHome);
+  });
+
+  it("calls installPlugins with plugins from config", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, pluginCalls } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(pluginCalls).toContain("my-plugin");
+  });
+
+  it("spawns the agent server after setup completes", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, spawnCalls } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(spawnCalls.length).toBe(1);
+    expect(spawnCalls[0].args[1]).toContain("index.ts");
+  });
+
+  it("does not call exit on success", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, exitCodes } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(exitCodes.length).toBe(0);
+  });
+});
+
+describe("runEntrypoint — missing required vars", () => {
+  it("exits non-zero when agentId is missing", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, exitCodes } = makeDeps(configClient, { agentId: undefined });
+
+    await runEntrypoint(deps);
+
+    expect(exitCodes.length).toBe(1);
+    expect(exitCodes[0]).not.toBe(0);
+  });
+
+  it("exits non-zero when apiUrl is missing", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, exitCodes } = makeDeps(configClient, { apiUrl: undefined });
+
+    await runEntrypoint(deps);
+
+    expect(exitCodes.length).toBe(1);
+    expect(exitCodes[0]).not.toBe(0);
+  });
+
+  it("exits non-zero when apiKey is missing", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    const { deps, exitCodes } = makeDeps(configClient, { apiKey: undefined });
+
+    await runEntrypoint(deps);
+
+    expect(exitCodes.length).toBe(1);
+    expect(exitCodes[0]).not.toBe(0);
+  });
+
+  it("does not fetch config when required vars are missing", async () => {
+    const configClient = new RecordedShipwrightConfigClient(SAMPLE_CONFIG);
+    let fetchCalled = false;
+    const trackingClient: ShipwrightConfigClient = {
+      getConfig: async (agentId: string) => {
+        fetchCalled = true;
+        return configClient.getConfig(agentId);
+      },
+    };
+    const { deps } = makeDeps(trackingClient, { agentId: undefined });
+
+    await runEntrypoint(deps);
+
+    expect(fetchCalled).toBe(false);
+  });
+});
+
+describe("runEntrypoint — config with empty env", () => {
+  it("handles config with no env vars gracefully", async () => {
+    const emptyConfig: AgentConfigResponse = {
+      env: {},
+      allowedTools: [],
+      plugins: [],
+      repos: [],
+      reviewAuthorAllowlist: [],
+      patchAuthorAllowlist: [],
+      restrictSlackToMembers: false,
+      memberEmails: [],
+      autoPostReviews: true,
+      allowSelfReview: false,
+      minConfidence: 75,
+      maxFindings: 5,
+      cleanupMergedWorktrees: true,
+      cleanupAfterDays: 14,
+    };
+    const configClient = new RecordedShipwrightConfigClient(emptyConfig);
+    const { deps, exitCodes, spawnCalls } = makeDeps(configClient);
+
+    await runEntrypoint(deps);
+
+    expect(exitCodes.length).toBe(0);
+    expect(spawnCalls.length).toBe(1);
+    expect(spawnCalls[0].args[1]).toContain("index.ts");
+  });
+});
+
+describe("runEntrypoint — startup timeout", () => {
+  it("exits non-zero when startup exceeds startupTimeoutMs", async () => {
+    const hangingClient: ShipwrightConfigClient = {
+      getConfig: () => new Promise(() => {}), // never resolves
+    };
+    const { deps, exitCodes } = makeDeps(hangingClient, {
+      startupTimeoutMs: 50, // 50ms for fast test
+    });
+
+    await runEntrypoint(deps);
+
+    expect(exitCodes.length).toBe(1);
+    expect(exitCodes[0]).not.toBe(0);
+  });
+});

package/entrypoint.ts

@@ -0,0 +1,154 @@
+/**
+ * agent/src/runtime/entrypoint.ts
+ *
+ * Container startup sequence for the Shipwright agent.
+ *
+ * Sequence:
+ *   1. Validate required env vars (fail fast with clear log on missing)
+ *   2. Fetch agent config from GET /agents/:id/config
+ *   3. Apply env vars from config bundle to process.env
+ *   4. Symlink ~/.claude → $AGENT_HOME/dot-claude
+ *   5. Setup GitHub auth
+ *   6. Run mise startup (install tools, prepend shims to PATH)
+ *   7. Install plugins from config
+ *   8. Spawn the agent server process
+ *
+ * Dependency-injected for testability — pass real deps in production,
+ * doubles in tests.
+ */
+
+import { join } from "node:path";
+import type { AgentPlugin } from "@app-vitals/agent-admin";
+import type { ShipwrightConfigClient } from "./shipwright-config-client.ts";
+
+// ─── Types ────────────────────────────────────────────────────────────────────
+
+type ExecFn = (
+  cmd: string,
+  args: string[],
+  opts: { cwd: string },
+) => Promise<{ stdout: string; exitCode: number }>;
+
+export interface EntrypointDeps {
+  agentId: string | undefined;
+  apiUrl: string | undefined;
+  apiKey: string | undefined;
+  agentHome: string;
+  configClient: ShipwrightConfigClient;
+  applyEnv: (env: Record<string, string>) => void;
+  symlinkDotClaude: (target: string, linkPath: string) => void;
+  setupGitHubAuth: () => Promise<void>;
+  runMiseStartup: (home: string, execFn?: ExecFn) => Promise<void>;
+  installPlugins: (
+    execFn?: ExecFn,
+    cwd?: string,
+    plugins?: AgentPlugin[],
+  ) => Promise<void>;
+  spawnAgentServer: (cmd: string, args: string[]) => void;
+  exit: (code: number) => void;
+  startupTimeoutMs?: number;
+}
+
+// ─── Main entrypoint ──────────────────────────────────────────────────────────
+
+// 180s, not 60s: `mise install` during startup can take well over a minute on a
+// cold or contended node (e.g. during a GKE node rotation), and the original 60s
+// budget crash-looped agents that were otherwise healthy. Overridable per-agent
+// via SHIPWRIGHT_STARTUP_TIMEOUT_MS. Keep this aligned with the manifest
+// startupProbe grace window in admin/src/agent-manifest.ts.
+const DEFAULT_STARTUP_TIMEOUT_MS = 180_000;
+
+export async function runEntrypoint(deps: EntrypointDeps): Promise<void> {
+  const {
+    agentId,
+    apiUrl,
+    apiKey,
+    agentHome,
+    configClient,
+    applyEnv,
+    symlinkDotClaude,
+    setupGitHubAuth,
+    runMiseStartup,
+    installPlugins,
+    spawnAgentServer,
+    exit,
+    startupTimeoutMs = DEFAULT_STARTUP_TIMEOUT_MS,
+  } = deps;
+
+  // ─── Step 1: Validate required vars ─────────────────────────────────────────
+
+  const missing: string[] = [];
+  if (!agentId) missing.push("SHIPWRIGHT_AGENT_ID (or --agent-id)");
+  if (!apiUrl) missing.push("SHIPWRIGHT_API_URL (or --api-url)");
+  if (!apiKey) missing.push("SHIPWRIGHT_AGENT_API_KEY (or --api-key)");
+
+  if (missing.length > 0) {
+    for (const m of missing) {
+      console.error(`[entrypoint] FATAL: missing required variable: ${m}`);
+    }
+    exit(1);
+    return;
+  }
+
+  // ─── Steps 2–8: run startup sequence with a hard deadline ────────────────────
+
+  const timeoutError = new Error(
+    `[entrypoint] FATAL: startup sequence did not complete within ${startupTimeoutMs}ms`,
+  );
+
+  const startup = async () => {
+    // Step 2: Fetch config from Shipwright API
+    let config: Awaited<ReturnType<ShipwrightConfigClient["getConfig"]>>;
+    try {
+      config = await configClient.getConfig(agentId as string);
+      console.log(
+        `[entrypoint] fetched config for agent ${agentId}: ${Object.keys(config.env).length} env vars, ${config.plugins.length} plugins`,
+      );
+    } catch (err) {
+      console.error(
+        `[entrypoint] FATAL: failed to fetch agent config: ${(err as Error).message}`,
+      );
+      exit(1);
+      return;
+    }
+
+    // Step 3: Apply env vars
+    applyEnv(config.env);
+    // ARD-6.1: hand the specialty to the server process (inherits our env) so
+    // ensureAgentHome() can pick type-specific workspace templates.
+    if (config.typeName) {
+      applyEnv({ SHIPWRIGHT_AGENT_TYPE: config.typeName });
+    }
+
+    // Step 4: Symlink ~/.claude → $AGENT_HOME/dot-claude
+    const dotClaudeTarget = join(agentHome, "dot-claude");
+    const dotClaudeLinkPath = join(process.env.HOME ?? "/root", ".claude");
+    symlinkDotClaude(dotClaudeTarget, dotClaudeLinkPath);
+
+    // Step 5: GitHub auth
+    await setupGitHubAuth();
+
+    // Step 6: Mise startup
+    await runMiseStartup(agentHome);
+
+    // Step 7: Install plugins
+    await installPlugins(undefined, undefined, config.plugins);
+
+    // Step 8: Spawn agent server
+    spawnAgentServer("bun", ["run", join(import.meta.dir, "..", "index.ts")]);
+  };
+
+  let deadlineTimer: ReturnType<typeof setTimeout> | undefined;
+  const deadline = new Promise<never>((_, reject) => {
+    deadlineTimer = setTimeout(() => reject(timeoutError), startupTimeoutMs);
+  });
+
+  try {
+    await Promise.race([startup(), deadline]);
+  } catch (err) {
+    console.error((err as Error).message);
+    exit(1);
+  } finally {
+    clearTimeout(deadlineTimer);
+  }
+}

package/errors.ts

@@ -0,0 +1,61 @@
+/**
+ * agent/src/runtime/errors.ts
+ * Typed HTTP error classes for use across agent service handlers.
+ * Handlers throw these; error middleware maps them to HTTP responses.
+ */
+
+// ─── Base class ───────────────────────────────────────────────────────────────
+
+export class ApiError extends Error {
+  constructor(
+    public readonly statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+// ─── HTTP error subclasses ────────────────────────────────────────────────────
+
+export class NotFoundError extends ApiError {
+  constructor(message = "Not found") {
+    super(404, message);
+    this.name = "NotFoundError";
+  }
+}
+
+export class ConflictError extends ApiError {
+  constructor(message = "Conflict") {
+    super(409, message);
+    this.name = "ConflictError";
+  }
+}
+
+export class BadRequestError extends ApiError {
+  constructor(message = "Bad request") {
+    super(400, message);
+    this.name = "BadRequestError";
+  }
+}
+
+export class ForbiddenError extends ApiError {
+  constructor(message = "Forbidden") {
+    super(403, message);
+    this.name = "ForbiddenError";
+  }
+}
+
+export class UnprocessableEntityError extends ApiError {
+  constructor(message = "Unprocessable entity") {
+    super(422, message);
+    this.name = "UnprocessableEntityError";
+  }
+}
+
+export class BadGatewayError extends ApiError {
+  constructor(message = "Bad gateway") {
+    super(502, message);
+    this.name = "BadGatewayError";
+  }
+}

package/fixtures/chat-service/attachment.json

@@ -0,0 +1,15 @@
+{
+  "getAttachment_success": {
+    "status": 200,
+    "bodyEncoding": "base64",
+    "body": "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNk+A8AAQUBAScY42YAAAAASUVORK5CYII="
+  },
+  "getAttachment_404": {
+    "status": 404,
+    "body": { "error": "no attachment" }
+  },
+  "getAttachment_500": {
+    "status": 500,
+    "body": { "error": "internal server error" }
+  }
+}

package/fixtures/chat-service/messages.json

@@ -0,0 +1,86 @@
+{
+  "claimMessage_success": {
+    "status": 200,
+    "body": {
+      "id": "msg-xyz",
+      "threadId": "thread-abc",
+      "role": "user",
+      "body": "Hello, can you help me?",
+      "claimedBy": "agent-1",
+      "claimedAt": "2026-01-01T00:10:00.000Z",
+      "repliedAt": null,
+      "tokens": null,
+      "costUsd": null,
+      "attachmentFilename": null,
+      "createdAt": "2026-01-01T00:09:00.000Z",
+      "updatedAt": "2026-01-01T00:10:00.000Z"
+    }
+  },
+  "claimMessage_404": {
+    "status": 404,
+    "body": { "error": "no unclaimed messages in thread" }
+  },
+  "claimMessage_500": {
+    "status": 500,
+    "body": { "error": "internal server error" }
+  },
+  "replyToMessage_success": {
+    "status": 201,
+    "body": {
+      "userMessage": {
+        "id": "msg-xyz",
+        "threadId": "thread-abc",
+        "role": "user",
+        "body": "Hello, can you help me?",
+        "claimedBy": "agent-1",
+        "claimedAt": "2026-01-01T00:10:00.000Z",
+        "repliedAt": "2026-01-01T00:11:00.000Z",
+        "tokens": null,
+        "costUsd": null,
+        "attachmentFilename": null,
+        "createdAt": "2026-01-01T00:09:00.000Z",
+        "updatedAt": "2026-01-01T00:11:00.000Z"
+      },
+      "assistantMessage": {
+        "id": "msg-assist-1",
+        "threadId": "thread-abc",
+        "role": "assistant",
+        "body": "Sure, here's how...",
+        "claimedBy": null,
+        "claimedAt": null,
+        "repliedAt": null,
+        "tokens": { "input_tokens": 120, "output_tokens": 42 },
+        "costUsd": 0.0021,
+        "attachmentFilename": null,
+        "createdAt": "2026-01-01T00:11:00.000Z",
+        "updatedAt": "2026-01-01T00:11:00.000Z"
+      }
+    }
+  },
+  "replyToMessage_400": {
+    "status": 400,
+    "body": { "error": "body is required" }
+  },
+  "heartbeat_success": {
+    "status": 200,
+    "body": {
+      "id": "msg-xyz",
+      "threadId": "thread-abc",
+      "role": "user",
+      "body": "Hello, can you help me?",
+      "claimedBy": "agent-1",
+      "claimedAt": "2026-01-01T00:10:00.000Z",
+      "heartbeatAt": "2026-01-01T00:10:30.000Z",
+      "repliedAt": null,
+      "tokens": null,
+      "costUsd": null,
+      "attachmentFilename": null,
+      "createdAt": "2026-01-01T00:09:00.000Z",
+      "updatedAt": "2026-01-01T00:10:30.000Z"
+    }
+  },
+  "heartbeat_404": {
+    "status": 404,
+    "body": { "error": "message not found" }
+  }
+}

package/fixtures/chat-service/threads.json

@@ -0,0 +1,50 @@
+{
+  "listThreads_success": {
+    "status": 200,
+    "body": {
+      "threads": [
+        {
+          "id": "thread-abc",
+          "agentId": "agent-1",
+          "memberId": "member-1",
+          "title": "Test Thread",
+          "createdAt": "2026-01-01T00:00:00.000Z",
+          "updatedAt": "2026-01-01T00:05:00.000Z"
+        },
+        {
+          "id": "thread-def",
+          "agentId": "agent-1",
+          "memberId": null,
+          "title": null,
+          "createdAt": "2026-01-02T00:00:00.000Z",
+          "updatedAt": "2026-01-02T00:05:00.000Z"
+        }
+      ],
+      "total": 2,
+      "limit": 50,
+      "offset": 0
+    }
+  },
+  "listThreads_with_query_params": {
+    "status": 200,
+    "body": {
+      "threads": [
+        {
+          "id": "thread-abc",
+          "agentId": "agent-1",
+          "memberId": "member-1",
+          "title": "Test Thread",
+          "createdAt": "2026-01-01T00:00:00.000Z",
+          "updatedAt": "2026-01-01T00:05:00.000Z"
+        }
+      ],
+      "total": 6,
+      "limit": 10,
+      "offset": 5
+    }
+  },
+  "listThreads_500": {
+    "status": 500,
+    "body": { "error": "internal server error" }
+  }
+}