@desplega.ai/agent-swarm 1.74.4 → 1.76.0

package/src/http/task-templates.ts

@@ -0,0 +1,51 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { listTaskTemplates } from "../be/db";
+import { TaskTemplateKindSchema } from "../types";
+import { route } from "./route-def";
+import { json } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const listTemplates = route({
+  method: "get",
+  path: "/api/task-templates",
+  pattern: ["api", "task-templates"],
+  summary: "List task templates ('To start' bucket)",
+  tags: ["Task Templates"],
+  query: z.object({
+    category: z.string().optional(),
+    /** v2 hook — v1 callers always pass `kind=task` (or omit). */
+    kind: TaskTemplateKindSchema.optional(),
+    /** Case-insensitive LIKE match against `title` OR `description`. */
+    query: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "Task template list" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleTaskTemplates(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listTemplates.match(req.method, pathSegments)) {
+    const parsed = await listTemplates.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const templates = listTaskTemplates({
+      category: parsed.query.category,
+      kind: parsed.query.kind,
+      query: parsed.query.query,
+    });
+    json(res, { templates });
+    return true;
+  }
+
+  return false;
+}

package/src/http/tasks.ts

@@ -7,10 +7,12 @@ import {
   failTask,
   getAllTasks,
   getDb,
+  getLeadAgent,
   getLogsByTaskId,
   getPausedTasksForAgent,
   getTaskById,
   getTasksCount,
+  getUserById,
   pauseTask,
   resumeTask,
   updateAgentStatusFromCapacity,
@@ -20,7 +22,13 @@ import {
 } from "../be/db";
 import { createTaskWithSiblingAwareness } from "../tasks/sibling-awareness";
 import { telemetry } from "../telemetry";
-import { ProviderNameSchema } from "../types";
+import {
+  type AgentTaskSource,
+  AgentTaskSourceSchema,
+  type AgentTaskStatus,
+  AgentTaskStatusSchema,
+  ProviderNameSchema,
+} from "../types";
 import { route } from "./route-def";
 import { json, jsonError } from "./utils";
 
@@ -33,16 +41,22 @@ const listTasks = route({
   summary: "List tasks with filters",
   tags: ["Tasks"],
   query: z.object({
+    /** Single status, or comma-separated list (e.g. "failed,cancelled"). */
     status: z.string().optional(),
     agentId: z.string().optional(),
     scheduleId: z.string().optional(),
     search: z.string().optional(),
     includeHeartbeat: z.enum(["true", "false"]).optional(),
+    /** ISO 8601 — return only tasks created on/after this timestamp. */
+    createdAfter: z.string().datetime().optional(),
+    /** Comma-separated source filter (e.g. `ui,slack`). Omit to include all. */
+    source: z.string().optional(),
     limit: z.coerce.number().int().optional(),
     offset: z.coerce.number().int().optional(),
   }),
   responses: {
     200: { description: "Paginated task list" },
+    400: { description: "Validation error (e.g. unknown status token)" },
   },
 });
 
@@ -62,9 +76,10 @@ const createTask = route({
     offeredTo: z.string().optional(),
     dir: z.string().optional(),
     parentTaskId: z.string().optional(),
-    source: z.string().optional(),
+    source: AgentTaskSourceSchema.optional(),
     outputSchema: z.record(z.string(), z.unknown()).optional(),
     contextKey: z.string().optional(),
+    requestedByUserId: z.string().optional(),
   }),
   responses: {
     201: { description: "Task created" },
@@ -239,12 +254,53 @@ export async function handleTasks(
   if (listTasks.match(req.method, pathSegments)) {
     const parsed = await listTasks.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
+
+    // Multi-status CSV: split on `,` and validate each token against the
+    // canonical enum. Empty / single-status callers still work.
+    let status: AgentTaskStatus | AgentTaskStatus[] | undefined;
+    if (parsed.query.status) {
+      const tokens = parsed.query.status
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      const validated: AgentTaskStatus[] = [];
+      for (const tok of tokens) {
+        const result = AgentTaskStatusSchema.safeParse(tok);
+        if (!result.success) {
+          jsonError(res, `Invalid status token: ${tok}`, 400);
+          return true;
+        }
+        validated.push(result.data);
+      }
+      status = validated.length === 1 ? validated[0] : validated;
+    }
+
+    let source: AgentTaskSource[] | undefined;
+    if (parsed.query.source) {
+      const tokens = parsed.query.source
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+      const validated: AgentTaskSource[] = [];
+      for (const tok of tokens) {
+        const result = AgentTaskSourceSchema.safeParse(tok);
+        if (!result.success) {
+          jsonError(res, `Invalid source token: ${tok}`, 400);
+          return true;
+        }
+        validated.push(result.data);
+      }
+      if (validated.length > 0) source = validated;
+    }
+
     const filters = {
-      status: (parsed.query.status as import("../types").AgentTaskStatus) || undefined,
+      status,
       agentId: parsed.query.agentId || undefined,
       scheduleId: parsed.query.scheduleId || undefined,
       search: parsed.query.search || undefined,
       includeHeartbeat: parsed.query.includeHeartbeat === "true" || undefined,
+      createdAfter: parsed.query.createdAfter || undefined,
+      source,
       limit: parsed.query.limit,
       offset: parsed.query.offset,
     };
@@ -258,9 +314,32 @@ export async function handleTasks(
     const parsed = await createTask.parse(req, res, pathSegments, queryParams);
     if (!parsed) return true;
 
+    // Tolerant `requestedByUserId`: prevent the deleted-user race from
+    // becoming a 500 — if the referenced user doesn't exist, log and drop
+    // the field rather than letting the FK fail at INSERT.
+    let requestedByUserId = parsed.body.requestedByUserId || undefined;
+    if (requestedByUserId && !getUserById(requestedByUserId)) {
+      console.warn(
+        `[tasks] requestedByUserId ${requestedByUserId} does not exist — coercing to NULL`,
+      );
+      requestedByUserId = undefined;
+    }
+
+    // Default agent for ingress-created tasks: when no explicit `agentId` is
+    // provided, route to the lead so the task has an owner immediately
+    // (regardless of whether it's a root or a follow-up under a parentTaskId).
+    // Without this, UI composer follow-ups land unassigned and never get
+    // picked up. Mirrors Slack's pattern (slack/actions.ts uses lead?.id when
+    // there's no working agent).
+    let defaultAgentId = parsed.body.agentId || undefined;
+    if (!defaultAgentId) {
+      const lead = getLeadAgent();
+      if (lead) defaultAgentId = lead.id;
+    }
+
     try {
       const task = createTaskWithSiblingAwareness(parsed.body.task, {
-        agentId: parsed.body.agentId || undefined,
+        agentId: defaultAgentId,
         creatorAgentId: myAgentId || undefined,
         taskType: parsed.body.taskType || undefined,
         tags: parsed.body.tags || undefined,
@@ -269,9 +348,10 @@ export async function handleTasks(
         offeredTo: parsed.body.offeredTo || undefined,
         dir: parsed.body.dir || undefined,
         parentTaskId: parsed.body.parentTaskId || undefined,
-        source: (parsed.body.source as import("../types").AgentTaskSource) || "api",
+        source: parsed.body.source || "api",
         outputSchema: parsed.body.outputSchema || undefined,
         contextKey: parsed.body.contextKey || undefined,
+        requestedByUserId,
       });
 
       ensure({

package/src/http/users.ts

@@ -0,0 +1,134 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import { z } from "zod";
+import { createUser, getAllUsers, getUserById, updateUser } from "../be/db";
+import { route } from "./route-def";
+import { json, jsonError } from "./utils";
+
+// ─── Route Definitions ───────────────────────────────────────────────────────
+
+const listUsers = route({
+  method: "get",
+  path: "/api/users",
+  pattern: ["api", "users"],
+  summary: "List all users",
+  tags: ["Users"],
+  responses: {
+    200: { description: "List of users" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
+const createUserRoute = route({
+  method: "post",
+  path: "/api/users",
+  pattern: ["api", "users"],
+  summary: "Create a new user",
+  tags: ["Users"],
+  body: z.object({
+    name: z.string().min(1),
+    email: z.string().optional(),
+    role: z.string().optional(),
+    notes: z.string().optional(),
+    slackUserId: z.string().optional(),
+    linearUserId: z.string().optional(),
+    githubUsername: z.string().optional(),
+    gitlabUsername: z.string().optional(),
+    emailAliases: z.array(z.string()).optional(),
+    preferredChannel: z.string().optional(),
+    timezone: z.string().optional(),
+  }),
+  responses: {
+    200: { description: "User created" },
+    400: { description: "Validation error" },
+    401: { description: "Unauthorized" },
+  },
+  auth: { apiKey: true },
+});
+
+const updateUserRoute = route({
+  method: "put",
+  path: "/api/users/{id}",
+  pattern: ["api", "users", null],
+  summary: "Update an existing user (partial — at least one field required)",
+  tags: ["Users"],
+  params: z.object({ id: z.string() }),
+  body: z
+    .object({
+      name: z.string().min(1).optional(),
+      email: z.string().optional(),
+      role: z.string().optional(),
+      notes: z.string().optional(),
+      slackUserId: z.string().optional(),
+      linearUserId: z.string().optional(),
+      githubUsername: z.string().optional(),
+      gitlabUsername: z.string().optional(),
+      emailAliases: z.array(z.string()).optional(),
+      preferredChannel: z.string().optional(),
+      timezone: z.string().optional(),
+    })
+    .refine((v) => Object.keys(v).length > 0, {
+      message: "At least one field must be provided",
+    }),
+  responses: {
+    200: { description: "User updated" },
+    400: { description: "Validation error or empty body" },
+    401: { description: "Unauthorized" },
+    404: { description: "User not found" },
+  },
+  auth: { apiKey: true },
+});
+
+// ─── Handler ─────────────────────────────────────────────────────────────────
+
+export async function handleUsers(
+  req: IncomingMessage,
+  res: ServerResponse,
+  pathSegments: string[],
+  queryParams: URLSearchParams,
+): Promise<boolean> {
+  if (listUsers.match(req.method, pathSegments)) {
+    const parsed = await listUsers.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    const users = getAllUsers();
+    json(res, { users });
+    return true;
+  }
+
+  if (createUserRoute.match(req.method, pathSegments)) {
+    const parsed = await createUserRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+    try {
+      const user = createUser(parsed.body);
+      json(res, { user });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to create user", 500);
+    }
+    return true;
+  }
+
+  if (updateUserRoute.match(req.method, pathSegments)) {
+    const parsed = await updateUserRoute.parse(req, res, pathSegments, queryParams);
+    if (!parsed) return true;
+
+    // 404 if user not found before update — keeps the contract honest.
+    if (!getUserById(parsed.params.id)) {
+      jsonError(res, "User not found", 404);
+      return true;
+    }
+
+    try {
+      const user = updateUser(parsed.params.id, parsed.body);
+      if (!user) {
+        jsonError(res, "User not found", 404);
+        return true;
+      }
+      json(res, { user });
+    } catch (err) {
+      jsonError(res, err instanceof Error ? err.message : "Failed to update user", 500);
+    }
+    return true;
+  }
+
+  return false;
+}

package/src/prompts/memories.ts

@@ -0,0 +1,62 @@
+/**
+ * Plan: thoughts/taras/plans/2026-05-05-memory-rater-v1.5/step-5.md §5
+ *
+ * Worker-side rendering of the "Relevant Past Knowledge" memories block that
+ * gets appended to a task's initial prompt. Pure string manipulation — no DB
+ * imports — so this file stays inside the worker-side boundary enforced by
+ * scripts/check-db-boundary.sh.
+ *
+ * The conditional hint at the end is gated on `MEMORY_RATERS` containing
+ * `explicit-self`. When the gate is closed (the default), the rendered
+ * prompt is byte-identical to pre-rater builds — strict backward compat.
+ */
+
+export type RelevantMemory = {
+  id: string;
+  name: string;
+  content: string;
+  similarity: number;
+};
+
+const SIMILARITY_THRESHOLD = 0.4;
+
+const RATE_TOOL_HINT = `
+
+When a memory above genuinely helps you solve this task — or actively
+misleads you — call \`memory_rate\` with the memory id and useful=true/false.
+This trains the swarm to surface better memories next time. Use sparingly:
+2-5 ratings per task is plenty.`;
+
+/**
+ * Render the memories prompt section. Returns `null` when there are no
+ * memories with `similarity > 0.4` — the caller should then skip the
+ * append entirely (matching pre-step-5 behaviour).
+ */
+export function renderMemoriesPrompt(memories: RelevantMemory[]): string | null {
+  const useful = memories.filter((m) => m.similarity > SIMILARITY_THRESHOLD);
+  if (useful.length === 0) return null;
+
+  const memoryContext = useful
+    .map((m) => `- **${m.name}** (id: ${m.id}): ${m.content.substring(0, 300)}`)
+    .join("\n");
+
+  let prompt = `\n\n### Relevant Past Knowledge\n\nThese memories from your previous sessions may be useful. Use \`memory-get\` with the memory ID to retrieve full details.\n\n${memoryContext}\n`;
+
+  if (isExplicitSelfRaterEnabled()) {
+    prompt += RATE_TOOL_HINT;
+  }
+
+  return prompt;
+}
+
+/**
+ * Exported for tests. Reads `MEMORY_RATERS` lazily so a test can flip the
+ * env var between renders without re-importing the module.
+ */
+export function isExplicitSelfRaterEnabled(): boolean {
+  const ratersEnabled = (process.env.MEMORY_RATERS ?? "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return ratersEnabled.includes("explicit-self");
+}

package/src/providers/claude-adapter.ts

@@ -11,6 +11,7 @@ import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import type {
   CostData,
+  CredStatus,
   ProviderAdapter,
   ProviderEvent,
   ProviderResult,
@@ -18,6 +19,22 @@ import type {
   ProviderSessionConfig,
 } from "./types";
 
+/**
+ * Predicate used by the worker boot loop and the credential-status endpoint.
+ * The claude harness needs EITHER `CLAUDE_CODE_OAUTH_TOKEN` (preferred) or
+ * `ANTHROPIC_API_KEY` — both are listed as missing when neither is present.
+ */
+export function checkClaudeCredentials(env: Record<string, string | undefined>): CredStatus {
+  if (env.CLAUDE_CODE_OAUTH_TOKEN || env.ANTHROPIC_API_KEY) {
+    return { ready: true, missing: [], satisfiedBy: "env" };
+  }
+  return {
+    ready: false,
+    missing: ["CLAUDE_CODE_OAUTH_TOKEN", "ANTHROPIC_API_KEY"],
+    hint: "Set either CLAUDE_CODE_OAUTH_TOKEN or ANTHROPIC_API_KEY (one is enough).",
+  };
+}
+
 /** Task file data written to /tmp for hook to read */
 interface TaskFileData {
   taskId: string;
@@ -177,6 +194,11 @@ class ClaudeSession implements ProviderSession {
         ENABLE_PROMPT_CACHING_1H: "1",
         ...(config.env || process.env),
         TASK_FILE: taskFilePath,
+        // Belt-and-braces: TASK_FILE on disk can disappear mid-session (race
+        // with task lifecycle), which silently drops the Stop-hook memory
+        // rater. The hook prefers these env vars when present. See PR #444.
+        AGENT_SWARM_TASK_ID: config.taskId,
+        AGENT_SWARM_AGENT_ID: config.agentId,
       } as Record<string, string>,
       stdout: "pipe",
       stderr: "pipe",

package/src/providers/claude-managed-adapter.ts

@@ -64,6 +64,7 @@ import { computeClaudeManagedCostUsd } from "./claude-managed-models";
 import { createClaudeManagedSwarmEventHandler } from "./claude-managed-swarm-events";
 import type {
   CostData,
+  CredStatus,
   ProviderAdapter,
   ProviderEvent,
   ProviderResult,
@@ -71,6 +72,29 @@ import type {
   ProviderSessionConfig,
 } from "./types";
 
+/**
+ * Managed-agents needs all four bootstrap values. Unlike vanilla claude there
+ * is no oauth fallback — the SDK requires the API key, agent id, environment
+ * id, and a public MCP base URL the cloud sandbox can reach.
+ */
+export function checkClaudeManagedCredentials(env: Record<string, string | undefined>): CredStatus {
+  const required = [
+    "ANTHROPIC_API_KEY",
+    "MANAGED_AGENT_ID",
+    "MANAGED_ENVIRONMENT_ID",
+    "MCP_BASE_URL",
+  ] as const;
+  const missing = required.filter((key) => !env[key]);
+  if (missing.length === 0) {
+    return { ready: true, missing: [], satisfiedBy: "env" };
+  }
+  return {
+    ready: false,
+    missing,
+    hint: "Run `bun run src/cli.tsx claude-managed-setup` once to provision MANAGED_AGENT_ID and MANAGED_ENVIRONMENT_ID, then set ANTHROPIC_API_KEY and MCP_BASE_URL (must be HTTPS-public).",
+  };
+}
+
 // Re-export the type aliases at module level so adjacent files / tests can use
 // the short names without re-discovering the long Beta-prefixed ones. Kept on
 // `void` lines so unused-import lints stay quiet for the type imports above.

package/src/providers/codex-adapter.ts

@@ -45,6 +45,7 @@
  * `Turn`, events, or items — the SDK already exports them as a tagged union.
  */
 
+import { existsSync as nodeExistsSync } from "node:fs";
 import os from "node:os";
 import { join } from "node:path";
 import {
@@ -73,6 +74,8 @@ import { resolveCodexPrompt } from "./codex-skill-resolver";
 import { createCodexSwarmEventHandler } from "./codex-swarm-events";
 import type {
   CostData,
+  CredCheckOptions,
+  CredStatus,
   ProviderAdapter,
   ProviderEvent,
   ProviderResult,
@@ -83,6 +86,45 @@ import type {
 /** Alias for the SDK's (unexported) `CodexConfigObject` type. */
 type CodexConfig = NonNullable<CodexOptions["config"]>;
 
+/**
+ * Codex satisfies its credential requirement by ANY of:
+ *   1. `~/.codex/auth.json` already exists on disk (the canonical state once
+ *      `codex login` has run).
+ *   2. `OPENAI_API_KEY` is set — the entrypoint will run
+ *      `codex login --with-api-key` to materialise auth.json on the next boot.
+ *   3. `CODEX_OAUTH` is set in the env (typically pulled from swarm_config) —
+ *      the entrypoint restores it to disk.
+ *
+ * Cases 2/3 return `satisfiedBy: 'side-effect-pending'` because the worker
+ * process can't proceed until the entrypoint side-effect has materialised the
+ * file. The boot loop treats this as ready (the side-effect is the
+ * entrypoint's job, and re-running it is idempotent).
+ */
+export function checkCodexCredentials(
+  env: Record<string, string | undefined>,
+  opts: CredCheckOptions = {},
+): CredStatus {
+  const homeDir = opts.homeDir ?? env.HOME ?? "/root";
+  const existsSync = opts.fs?.existsSync ?? nodeExistsSync;
+  const authFile = `${homeDir}/.codex/auth.json`;
+  if (existsSync(authFile)) {
+    return { ready: true, missing: [], satisfiedBy: "file" };
+  }
+  if (env.OPENAI_API_KEY || env.CODEX_OAUTH) {
+    return {
+      ready: true,
+      missing: [],
+      satisfiedBy: "side-effect-pending",
+      hint: "Credential present in env; entrypoint will materialise ~/.codex/auth.json on next boot.",
+    };
+  }
+  return {
+    ready: false,
+    missing: ["OPENAI_API_KEY", "CODEX_OAUTH", authFile],
+    hint: "Set OPENAI_API_KEY (entrypoint runs `codex login --with-api-key`), or store CODEX_OAUTH in swarm_config, or place a pre-authenticated `~/.codex/auth.json` in the worker home.",
+  };
+}
+
 /**
  * Shape returned by `GET /api/agents/:id/mcp-servers?resolveSecrets=true`.
  * Mirrors `pi-mono-adapter.ts:430-439` and `claude-adapter.ts:59-72`, plus
@@ -648,7 +690,7 @@ class CodexSession implements ProviderSession {
           // `contextPercent` is on a 0-100 scale across all providers — claude
           // emits `(used / total) * 100`, pi-mono passes through `usage.percent`
           // which is already 0-100. The dashboard at
-          // new-ui/src/pages/tasks/[id]/page.tsx renders it via `.toFixed(0)`
+          // ui/src/pages/tasks/[id]/page.tsx renders it via `.toFixed(0)`
           // expecting an integer percent, so a 0-1 fraction would render as
           // "0%" instead of e.g. "40%".
           this.emit({

package/src/providers/devin-adapter.ts

@@ -24,6 +24,7 @@ import { getOrCreatePlaybook } from "./devin-playbooks";
 import { resolveDevinPrompt } from "./devin-skill-resolver";
 import type {
   CostData,
+  CredStatus,
   ProviderAdapter,
   ProviderEvent,
   ProviderResult,
@@ -32,6 +33,23 @@ import type {
   ProviderTraits,
 } from "./types";
 
+/**
+ * Devin requires both an API key and an org id — there is no file-based
+ * fallback like the local-CLI providers offer.
+ */
+export function checkDevinCredentials(env: Record<string, string | undefined>): CredStatus {
+  const required = ["DEVIN_API_KEY", "DEVIN_ORG_ID"] as const;
+  const missing = required.filter((key) => !env[key]);
+  if (missing.length === 0) {
+    return { ready: true, missing: [], satisfiedBy: "env" };
+  }
+  return {
+    ready: false,
+    missing,
+    hint: "Set DEVIN_API_KEY and DEVIN_ORG_ID. Both come from app.devin.ai → Settings → API.",
+  };
+}
+
 /** Default polling interval in milliseconds. */
 const DEFAULT_POLL_INTERVAL_MS = 15_000;
 

package/src/providers/index.ts

@@ -1,5 +1,12 @@
+export {
+  checkProviderCredentials,
+  REQUIRED_CRED_VARS_BY_PROVIDER,
+  type SupportedProvider,
+} from "../commands/provider-credentials";
 export type {
   CostData,
+  CredCheckOptions,
+  CredStatus,
   ProviderAdapter,
   ProviderEvent,
   ProviderResult,

package/src/providers/opencode-adapter.ts

@@ -18,6 +18,8 @@ import { fetchInstalledMcpServers } from "../utils/mcp-server-fetcher";
 import { scrubSecrets } from "../utils/secret-scrubber";
 import type {
   CostData,
+  CredCheckOptions,
+  CredStatus,
   ProviderAdapter,
   ProviderEvent,
   ProviderResult,
@@ -26,6 +28,64 @@ import type {
   ProviderTraits,
 } from "./types";
 
+/**
+ * Map opencode model strings to the env var that satisfies them. Opencode
+ * uses the same `provider/model-id` shape as pi-mono — the prefix tells us
+ * which key the user must supply.
+ */
+function opencodeModelToCredKey(modelStr: string | undefined): string | null {
+  if (!modelStr) return null;
+  if (modelStr.includes("/")) {
+    const provider = modelStr.slice(0, modelStr.indexOf("/")).toLowerCase();
+    if (provider === "anthropic") return "ANTHROPIC_API_KEY";
+    if (provider === "openrouter") return "OPENROUTER_API_KEY";
+    if (provider === "openai") return "OPENAI_API_KEY";
+  }
+  return null;
+}
+
+/**
+ * Opencode is satisfied by ANY of:
+ *   1. `~/.local/share/opencode/auth.json` exists (the file `opencode auth login`
+ *      writes).
+ *   2. `MODEL_OVERRIDE` resolves to a provider-prefixed model — only that
+ *      provider's key is required.
+ *   3. Otherwise any one of OPENROUTER_API_KEY / ANTHROPIC_API_KEY /
+ *      OPENAI_API_KEY suffices.
+ */
+export function checkOpencodeCredentials(
+  env: Record<string, string | undefined>,
+  opts: CredCheckOptions = {},
+): CredStatus {
+  const homeDir = opts.homeDir ?? env.HOME ?? "/root";
+  const probe = opts.fs?.existsSync ?? existsSync;
+  const authFile = `${homeDir}/.local/share/opencode/auth.json`;
+  if (probe(authFile)) {
+    return { ready: true, missing: [], satisfiedBy: "file" };
+  }
+
+  const requiredKey = opencodeModelToCredKey(env.MODEL_OVERRIDE);
+  if (requiredKey) {
+    if (env[requiredKey]) {
+      return { ready: true, missing: [], satisfiedBy: "env" };
+    }
+    return {
+      ready: false,
+      missing: [requiredKey, authFile],
+      hint: `MODEL_OVERRIDE=${env.MODEL_OVERRIDE} requires ${requiredKey}; or run \`opencode auth login\` to create ${authFile}.`,
+    };
+  }
+
+  if (env.OPENROUTER_API_KEY || env.ANTHROPIC_API_KEY || env.OPENAI_API_KEY) {
+    return { ready: true, missing: [], satisfiedBy: "env" };
+  }
+  return {
+    ready: false,
+    missing: ["OPENROUTER_API_KEY", "ANTHROPIC_API_KEY", "OPENAI_API_KEY", authFile],
+    hint: "Set one of OPENROUTER_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY (any one suffices), or run `opencode auth login` to create ~/.local/share/opencode/auth.json.",
+  };
+}
+
 function isAssistantMessage(msg: unknown): msg is AssistantMessage {
   return (
     typeof msg === "object" &&