bopodev-api 0.1.8 → 0.1.10

package/src/routes/agents.ts

@@ -1,8 +1,27 @@
 import { Router } from "express";
+import { mkdir } from "node:fs/promises";
 import { z } from "zod";
-import { appendAuditEvent, createAgent, createApprovalRequest, deleteAgent, getApprovalRequest, listAgents, updateAgent } from "bopodev-db";
+import { executeAgentRuntime } from "bopodev-agent-sdk";
+import { AgentCreateRequestSchema, AgentUpdateRequestSchema } from "bopodev-contracts";
+import {
+  appendAuditEvent,
+  createAgent,
+  createApprovalRequest,
+  deleteAgent,
+  getApprovalRequest,
+  listAgents,
+  updateAgent
+} from "bopodev-db";
 import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
+import {
+  normalizeRuntimeConfig,
+  parseRuntimeConfigFromAgentRow,
+  requiresRuntimeCwd,
+  runtimeConfigToDb,
+  runtimeConfigToStateBlobPatch
+} from "../lib/agent-config";
+import { hasText, resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requireBoardRole, requirePermission } from "../middleware/request-actor";
 import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
@@ -12,37 +31,74 @@ import {
 } from "../realtime/office-space";
 import { isApprovalRequired } from "../services/governance-service";
 
-const createAgentSchema = z.object({
-  managerAgentId: z.string().optional(),
-  role: z.string().min(1),
-  name: z.string().min(1),
-  providerType: z.enum(["claude_code", "codex", "http", "shell"]),
-  heartbeatCron: z.string().default("*/5 * * * *"),
-  monthlyBudgetUsd: z.number().nonnegative().default(30),
-  canHireAgents: z.boolean().default(false),
-  requestApproval: z.boolean().default(true),
+const legacyRuntimeConfigSchema = z.object({
   runtimeCommand: z.string().optional(),
   runtimeArgs: z.array(z.string()).optional(),
   runtimeCwd: z.string().optional(),
-  runtimeTimeoutMs: z.number().int().positive().max(600000).optional()
+  runtimeTimeoutMs: z.number().int().positive().max(600000).optional(),
+  runtimeModel: z.string().optional(),
+  runtimeThinkingEffort: z.enum(["auto", "low", "medium", "high"]).optional(),
+  bootstrapPrompt: z.string().optional(),
+  runtimeTimeoutSec: z.number().int().nonnegative().optional(),
+  interruptGraceSec: z.number().int().nonnegative().optional(),
+  runtimeEnv: z.record(z.string(), z.string()).optional(),
+  runPolicy: z
+    .object({
+      sandboxMode: z.enum(["workspace_write", "full_access"]).optional(),
+      allowWebSearch: z.boolean().optional()
+    })
+    .optional()
+});
+
+const createAgentSchema = AgentCreateRequestSchema.extend({
+  ...legacyRuntimeConfigSchema.shape
+});
+
+const updateAgentSchema = AgentUpdateRequestSchema.extend({
+  ...legacyRuntimeConfigSchema.shape
 });
 
-const updateAgentSchema = z
-  .object({
-    managerAgentId: z.string().nullable().optional(),
-    role: z.string().min(1).optional(),
-    name: z.string().min(1).optional(),
-    providerType: z.enum(["claude_code", "codex", "http", "shell"]).optional(),
-    status: z.enum(["idle", "running", "paused", "terminated"]).optional(),
-    heartbeatCron: z.string().min(1).optional(),
-    monthlyBudgetUsd: z.number().nonnegative().optional(),
-    canHireAgents: z.boolean().optional(),
-    runtimeCommand: z.string().optional(),
-    runtimeArgs: z.array(z.string()).optional(),
-    runtimeCwd: z.string().optional(),
-    runtimeTimeoutMs: z.number().int().positive().max(600000).optional()
-  })
-  .refine((payload) => Object.keys(payload).length > 0, "At least one field must be provided.");
+const runtimePreflightSchema = z.object({
+  providerType: z.enum(["claude_code", "codex", "http", "shell"]),
+  runtimeConfig: z.record(z.string(), z.unknown()).optional(),
+  ...legacyRuntimeConfigSchema.shape
+});
+const CODEX_AUTH_REQUIRED_RE =
+  /(not\s+logged\s+in|login\s+required|authentication\s+required|unauthorized|invalid(?:\s+or\s+missing)?\s+api(?:[_\s-]?key)?|openai[_\s-]?api[_\s-]?key|api[_\s-]?key.*required|missing bearer|missing bearer or basic authentication)/i;
+const UPDATE_AGENT_ALLOWED_KEYS = new Set([
+  "managerAgentId",
+  "role",
+  "name",
+  "providerType",
+  "status",
+  "heartbeatCron",
+  "monthlyBudgetUsd",
+  "canHireAgents",
+  "runtimeConfig",
+  "runtimeCommand",
+  "runtimeArgs",
+  "runtimeCwd",
+  "runtimeTimeoutMs",
+  "runtimeModel",
+  "runtimeThinkingEffort",
+  "bootstrapPrompt",
+  "runtimeTimeoutSec",
+  "interruptGraceSec",
+  "runtimeEnv",
+  "runPolicy"
+]);
+const UPDATE_RUNTIME_CONFIG_ALLOWED_KEYS = new Set([
+  "runtimeCommand",
+  "runtimeArgs",
+  "runtimeCwd",
+  "runtimeEnv",
+  "runtimeModel",
+  "runtimeThinkingEffort",
+  "bootstrapPrompt",
+  "runtimeTimeoutSec",
+  "interruptGraceSec",
+  "runPolicy"
+]);
 
 function toAgentResponse(agent: Record<string, unknown>) {
   return {
@@ -65,22 +121,195 @@ export function createAgentsRouter(ctx: AppContext) {
     );
   });
 
+  router.get("/runtime-default-cwd", async (req, res) => {
+    const runtimeCwd = await resolveDefaultRuntimeCwdForCompany(ctx.db, req.companyId!);
+    await mkdir(runtimeCwd, { recursive: true });
+    return sendOk(res, { runtimeCwd });
+  });
+
+  router.post("/runtime-preflight", async (req, res) => {
+    const parsed = runtimePreflightSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const defaultRuntimeCwd = await resolveDefaultRuntimeCwdForCompany(ctx.db, req.companyId!);
+    const runtimeConfig = normalizeRuntimeConfig({
+      runtimeConfig: parsed.data.runtimeConfig,
+      legacy: {
+        runtimeCommand: parsed.data.runtimeCommand,
+        runtimeArgs: parsed.data.runtimeArgs,
+        runtimeCwd: parsed.data.runtimeCwd,
+        runtimeTimeoutMs: parsed.data.runtimeTimeoutMs,
+        runtimeModel: parsed.data.runtimeModel,
+        runtimeThinkingEffort: parsed.data.runtimeThinkingEffort,
+        bootstrapPrompt: parsed.data.bootstrapPrompt,
+        runtimeTimeoutSec: parsed.data.runtimeTimeoutSec,
+        interruptGraceSec: parsed.data.interruptGraceSec,
+        runtimeEnv: parsed.data.runtimeEnv,
+        runPolicy: parsed.data.runPolicy
+      },
+      defaultRuntimeCwd
+    });
+
+    const checks: Array<{
+      code: string;
+      level: "info" | "warn" | "error";
+      message: string;
+      detail?: string;
+      hint?: string;
+    }> = [];
+
+    if (parsed.data.providerType !== "codex") {
+      return sendOk(res, {
+        status: "pass",
+        testedAt: new Date().toISOString(),
+        checks: [
+          {
+            code: "preflight_not_required",
+            level: "info",
+            message: "Preflight probe is currently required only for Codex runtime."
+          }
+        ]
+      });
+    }
+
+    if (!runtimeConfig.runtimeCwd) {
+      checks.push({
+        code: "codex_cwd_missing",
+        level: "error",
+        message: "Runtime working directory is required for Codex preflight."
+      });
+      return sendOk(res, { status: "fail", testedAt: new Date().toISOString(), checks });
+    }
+
+    await mkdir(runtimeConfig.runtimeCwd, { recursive: true });
+
+    const timeoutMs =
+      runtimeConfig.runtimeTimeoutSec > 0 ? Math.min(runtimeConfig.runtimeTimeoutSec * 1000, 45_000) : 45_000;
+    const probe = await executeAgentRuntime("codex", "Respond with hello.", {
+      command: runtimeConfig.runtimeCommand,
+      args: runtimeConfig.runtimeArgs,
+      cwd: runtimeConfig.runtimeCwd,
+      env: runtimeConfig.runtimeEnv,
+      model: runtimeConfig.runtimeModel,
+      thinkingEffort: runtimeConfig.runtimeThinkingEffort,
+      runPolicy: runtimeConfig.runPolicy,
+      timeoutMs,
+      retryCount: 0
+    });
+
+    if (probe.ok) {
+      const summary = (probe.parsedUsage?.summary ?? "").trim();
+      const hasHello = /\bhello\b/i.test(summary || probe.stdout);
+      checks.push({
+        code: hasHello ? "codex_hello_probe_passed" : "codex_hello_probe_unexpected_output",
+        level: hasHello ? "info" : "warn",
+        message: hasHello ? "Codex preflight probe succeeded." : "Codex probe succeeded but response was unexpected.",
+        ...(summary ? { detail: summary.slice(0, 240) } : {})
+      });
+    } else {
+      const detail = `${probe.stderr || ""}\n${probe.stdout || ""}`.trim().slice(0, 500);
+      if (probe.failureType === "spawn_error") {
+        checks.push({
+          code: "codex_command_unresolvable",
+          level: "error",
+          message: "Codex command is not executable from this runtime configuration.",
+          detail,
+          hint: "Install Codex CLI or set runtime command to an executable path."
+        });
+      } else if (probe.timedOut) {
+        checks.push({
+          code: "codex_hello_probe_timed_out",
+          level: "warn",
+          message: "Codex preflight timed out.",
+          detail,
+          hint: "Retry preflight. If this repeats, check runtime command/cwd and local Codex health."
+        });
+      } else if (CODEX_AUTH_REQUIRED_RE.test(detail)) {
+        checks.push({
+          code: "codex_auth_required",
+          level: "warn",
+          message: "Codex authentication is not ready for this runtime.",
+          detail,
+          hint: "Run `codex login` locally or set a global `BOPO_OPENAI_API_KEY`/`OPENAI_API_KEY`."
+        });
+      } else {
+        checks.push({
+          code: "codex_hello_probe_failed",
+          level: "error",
+          message: "Codex preflight failed.",
+          detail,
+          hint: "Run `codex exec --json -` manually in the runtime directory with prompt `Respond with hello.`."
+        });
+      }
+    }
+
+    const status =
+      checks.some((check) => check.level === "error")
+        ? "fail"
+        : checks.some((check) => check.level === "warn")
+          ? "warn"
+          : "pass";
+    return sendOk(res, {
+      status,
+      testedAt: new Date().toISOString(),
+      checks
+    });
+  });
+
   router.post("/", async (req, res) => {
     const requireCreate = requirePermission("agents:write");
     requireCreate(req, res, () => {});
     if (res.headersSent) {
       return;
     }
+    if (req.actor?.type === "agent") {
+      const companyAgents = await listAgents(ctx.db, req.companyId!);
+      const requestingAgent = companyAgents.find((row) => row.id === req.actor?.id);
+      if (!requestingAgent) {
+        return sendError(res, "Requesting agent not found.", 403);
+      }
+      if (!requestingAgent.canHireAgents) {
+        return sendError(res, "This agent is not allowed to create new agents.", 403);
+      }
+    }
     const parsed = createAgentSchema.safeParse(req.body);
     if (!parsed.success) {
       return sendError(res, parsed.error.message, 422);
     }
+    const defaultRuntimeCwd = await resolveDefaultRuntimeCwdForCompany(ctx.db, req.companyId!);
+    const runtimeConfig = normalizeRuntimeConfig({
+      runtimeConfig: parsed.data.runtimeConfig,
+      legacy: {
+        runtimeCommand: parsed.data.runtimeCommand,
+        runtimeArgs: parsed.data.runtimeArgs,
+        runtimeCwd: parsed.data.runtimeCwd,
+        runtimeTimeoutMs: parsed.data.runtimeTimeoutMs,
+        runtimeModel: parsed.data.runtimeModel,
+        runtimeThinkingEffort: parsed.data.runtimeThinkingEffort,
+        bootstrapPrompt: parsed.data.bootstrapPrompt,
+        runtimeTimeoutSec: parsed.data.runtimeTimeoutSec,
+        interruptGraceSec: parsed.data.interruptGraceSec,
+        runtimeEnv: parsed.data.runtimeEnv,
+        runPolicy: parsed.data.runPolicy
+      },
+      defaultRuntimeCwd
+    });
+    if (requiresRuntimeCwd(parsed.data.providerType) && !hasText(runtimeConfig.runtimeCwd)) {
+      return sendError(res, "Runtime working directory is required for this runtime provider.", 422);
+    }
+    if (requiresRuntimeCwd(parsed.data.providerType) && hasText(runtimeConfig.runtimeCwd)) {
+      await mkdir(runtimeConfig.runtimeCwd!, { recursive: true });
+    }
 
     if (parsed.data.requestApproval && isApprovalRequired("hire_agent")) {
       const approvalId = await createApprovalRequest(ctx.db, {
         companyId: req.companyId!,
         action: "hire_agent",
-        payload: parsed.data
+        payload: {
+          ...parsed.data,
+          runtimeConfig
+        }
       });
       const approval = await getApprovalRequest(ctx.db, req.companyId!, approvalId);
       if (approval) {
@@ -104,14 +333,8 @@ export function createAgentsRouter(ctx: AppContext) {
       heartbeatCron: parsed.data.heartbeatCron,
       monthlyBudgetUsd: parsed.data.monthlyBudgetUsd.toFixed(4),
       canHireAgents: parsed.data.canHireAgents,
-      initialState: {
-        runtime: {
-          command: parsed.data.runtimeCommand,
-          args: parsed.data.runtimeArgs,
-          cwd: parsed.data.runtimeCwd,
-          timeoutMs: parsed.data.runtimeTimeoutMs
-        }
-      }
+      ...runtimeConfigToDb(runtimeConfig),
+      initialState: runtimeConfigToStateBlobPatch(runtimeConfig)
     });
 
     await appendAuditEvent(ctx.db, {
@@ -132,6 +355,15 @@ export function createAgentsRouter(ctx: AppContext) {
     if (res.headersSent) {
       return;
     }
+    const unsupportedKeys = listUnsupportedAgentUpdateKeys(req.body);
+    if (unsupportedKeys.length > 0) {
+      return sendError(
+        res,
+        `Unsupported agent update fields: ${unsupportedKeys.join(", ")}. Supported fields: ${Array.from(UPDATE_AGENT_ALLOWED_KEYS).join(", ")}.`,
+        422
+      );
+    }
+
     const parsed = updateAgentSchema.safeParse(req.body);
     if (!parsed.success) {
       return sendError(res, parsed.error.message, 422);
@@ -141,39 +373,56 @@ export function createAgentsRouter(ctx: AppContext) {
     if (!existingAgent) {
       return sendError(res, "Agent not found.", 404);
     }
-
-    const hasRuntimePatch =
+    const defaultRuntimeCwd = await resolveDefaultRuntimeCwdForCompany(ctx.db, req.companyId!);
+    const existingRuntime = parseRuntimeConfigFromAgentRow(existingAgent as unknown as Record<string, unknown>);
+    const effectiveProviderType = parsed.data.providerType ?? existingAgent.providerType;
+    const hasRuntimeInput =
+      parsed.data.runtimeConfig !== undefined ||
       parsed.data.runtimeCommand !== undefined ||
       parsed.data.runtimeArgs !== undefined ||
       parsed.data.runtimeCwd !== undefined ||
-      parsed.data.runtimeTimeoutMs !== undefined;
-
-    let stateBlobPatch: Record<string, unknown> | undefined;
-    if (hasRuntimePatch) {
-      const existingState = (() => {
-        try {
-          const parsedState = JSON.parse(existingAgent.stateBlob ?? "{}") as Record<string, unknown>;
-          return typeof parsedState === "object" && parsedState !== null ? parsedState : {};
-        } catch {
-          return {};
-        }
-      })();
-      const existingRuntime =
-        typeof existingState.runtime === "object" && existingState.runtime !== null
-          ? (existingState.runtime as Record<string, unknown>)
-          : {};
-      stateBlobPatch = {
-        ...existingState,
-        runtime: {
-          ...existingRuntime,
-          ...(parsed.data.runtimeCommand === undefined ? {} : { command: parsed.data.runtimeCommand }),
-          ...(parsed.data.runtimeArgs === undefined ? {} : { args: parsed.data.runtimeArgs }),
-          ...(parsed.data.runtimeCwd === undefined ? {} : { cwd: parsed.data.runtimeCwd }),
-          ...(parsed.data.runtimeTimeoutMs === undefined ? {} : { timeoutMs: parsed.data.runtimeTimeoutMs })
-        }
-      };
+      parsed.data.runtimeTimeoutMs !== undefined ||
+      parsed.data.runtimeModel !== undefined ||
+      parsed.data.runtimeThinkingEffort !== undefined ||
+      parsed.data.bootstrapPrompt !== undefined ||
+      parsed.data.runtimeTimeoutSec !== undefined ||
+      parsed.data.interruptGraceSec !== undefined ||
+      parsed.data.runtimeEnv !== undefined ||
+      parsed.data.runPolicy !== undefined;
+    const nextRuntime = {
+      ...existingRuntime,
+      ...(hasRuntimeInput
+        ? normalizeRuntimeConfig({
+            runtimeConfig: {
+              ...existingRuntime,
+              ...(parsed.data.runtimeConfig ?? {})
+            },
+            legacy: {
+              runtimeCommand: parsed.data.runtimeCommand,
+              runtimeArgs: parsed.data.runtimeArgs,
+              runtimeCwd: parsed.data.runtimeCwd,
+              runtimeTimeoutMs: parsed.data.runtimeTimeoutMs,
+              runtimeModel: parsed.data.runtimeModel,
+              runtimeThinkingEffort: parsed.data.runtimeThinkingEffort,
+              bootstrapPrompt: parsed.data.bootstrapPrompt,
+              runtimeTimeoutSec: parsed.data.runtimeTimeoutSec ?? existingRuntime.runtimeTimeoutSec,
+              interruptGraceSec: parsed.data.interruptGraceSec,
+              runtimeEnv: parsed.data.runtimeEnv,
+              runPolicy: parsed.data.runPolicy
+            }
+          })
+        : {})
+    };
+    if (!nextRuntime.runtimeCwd && defaultRuntimeCwd) {
+      nextRuntime.runtimeCwd = defaultRuntimeCwd;
+    }
+    const effectiveRuntimeCwd = nextRuntime.runtimeCwd ?? "";
+    if (requiresRuntimeCwd(effectiveProviderType) && !hasText(effectiveRuntimeCwd)) {
+      return sendError(res, "Runtime working directory is required for this runtime provider.", 422);
+    }
+    if (requiresRuntimeCwd(effectiveProviderType) && hasText(effectiveRuntimeCwd)) {
+      await mkdir(effectiveRuntimeCwd, { recursive: true });
     }
-
     const agent = await updateAgent(ctx.db, {
       companyId: req.companyId!,
       id: req.params.agentId,
@@ -186,7 +435,8 @@ export function createAgentsRouter(ctx: AppContext) {
       monthlyBudgetUsd:
         typeof parsed.data.monthlyBudgetUsd === "number" ? parsed.data.monthlyBudgetUsd.toFixed(4) : undefined,
       canHireAgents: parsed.data.canHireAgents,
-      stateBlob: stateBlobPatch
+      ...runtimeConfigToDb(nextRuntime),
+      stateBlob: runtimeConfigToStateBlobPatch(nextRuntime)
     });
     if (!agent) {
       return sendError(res, "Agent not found.", 404);
@@ -303,3 +553,22 @@ export function createAgentsRouter(ctx: AppContext) {
 
   return router;
 }
+
+function listUnsupportedAgentUpdateKeys(payload: unknown) {
+  if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+    return [] as string[];
+  }
+  const body = payload as Record<string, unknown>;
+  const unsupported = Object.keys(body)
+    .filter((key) => !UPDATE_AGENT_ALLOWED_KEYS.has(key))
+    .sort();
+  const runtimeConfig = body.runtimeConfig;
+  if (runtimeConfig && typeof runtimeConfig === "object" && !Array.isArray(runtimeConfig)) {
+    for (const key of Object.keys(runtimeConfig as Record<string, unknown>).sort()) {
+      if (!UPDATE_RUNTIME_CONFIG_ALLOWED_KEYS.has(key)) {
+        unsupported.push(`runtimeConfig.${key}`);
+      }
+    }
+  }
+  return unsupported;
+}

package/src/routes/heartbeats.ts

@@ -1,7 +1,7 @@
 import { Router } from "express";
 import { z } from "zod";
 import { and, eq } from "drizzle-orm";
-import { agents } from "bopodev-db";
+import { agents, heartbeatRuns } from "bopodev-db";
 import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";
@@ -42,7 +42,26 @@ export function createHeartbeatRouter(ctx: AppContext) {
       trigger: "manual",
       realtimeHub: ctx.realtimeHub
     });
-    return sendOk(res, { runId, requestId: req.requestId });
+    if (!runId) {
+      return sendError(res, "Heartbeat could not be started for this agent.", 409);
+    }
+    const [runRow] = await ctx.db
+      .select({ id: heartbeatRuns.id, status: heartbeatRuns.status, message: heartbeatRuns.message })
+      .from(heartbeatRuns)
+      .where(and(eq(heartbeatRuns.companyId, req.companyId!), eq(heartbeatRuns.id, runId)))
+      .limit(1);
+    const invokeStatus =
+      runRow?.status === "skipped" && String(runRow.message ?? "").includes("already in progress")
+        ? "skipped_overlap"
+        : runRow?.status === "skipped"
+          ? "skipped"
+          : "started";
+    return sendOk(res, {
+      runId,
+      requestId: req.requestId,
+      status: invokeStatus,
+      message: runRow?.message ?? null
+    });
   });
 
   router.post("/sweep", async (req, res) => {