bopodev-api 0.1.12 → 0.1.14

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 BopoDev contributors
+Copyright (c) 2026 Bopo
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bopodev-api",
-  "version": "0.1.12",
+  "version": "0.1.14",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -13,16 +13,18 @@
     "dotenv": "^17.0.1",
     "drizzle-orm": "^0.44.5",
     "express": "^5.1.0",
+    "multer": "^2.1.1",
     "nanoid": "^5.1.5",
     "ws": "^8.19.0",
     "zod": "^4.1.5",
-    "bopodev-contracts": "0.1.12",
-    "bopodev-db": "0.1.12",
-    "bopodev-agent-sdk": "0.1.12"
+    "bopodev-db": "0.1.14",
+    "bopodev-contracts": "0.1.14",
+    "bopodev-agent-sdk": "0.1.14"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
     "@types/express": "^5.0.3",
+    "@types/multer": "^2.1.0",
     "@types/ws": "^8.18.1",
     "tsx": "^4.20.5"
   },

package/src/app.ts

@@ -13,6 +13,7 @@ import { createHeartbeatRouter } from "./routes/heartbeats";
 import { createIssuesRouter } from "./routes/issues";
 import { createObservabilityRouter } from "./routes/observability";
 import { createProjectsRouter } from "./routes/projects";
+import { createPluginsRouter } from "./routes/plugins";
 import { sendError } from "./http";
 import { attachRequestActor } from "./middleware/request-actor";
 
@@ -62,6 +63,7 @@ export function createApp(ctx: AppContext) {
   app.use("/governance", createGovernanceRouter(ctx));
   app.use("/heartbeats", createHeartbeatRouter(ctx));
   app.use("/observability", createObservabilityRouter(ctx));
+  app.use("/plugins", createPluginsRouter(ctx));
 
   app.use((error: unknown, _req: Request, res: Response, _next: NextFunction) => {
     if (error instanceof RepositoryValidationError) {

package/src/lib/agent-config.ts

@@ -39,10 +39,39 @@ export function requiresRuntimeCwd(providerType: string) {
     providerType === "claude_code" ||
     providerType === "cursor" ||
     providerType === "opencode" ||
+    providerType === "gemini_cli" ||
     providerType === "shell"
   );
 }
 
+export function resolveDefaultRuntimeModelForProvider(providerType: string | undefined) {
+  const normalizedProviderType = providerType?.trim() ?? "";
+  if (normalizedProviderType === "claude_code") {
+    return "claude-sonnet-4-6";
+  }
+  if (normalizedProviderType === "codex") {
+    return "gpt-5.3-codex";
+  }
+  if (normalizedProviderType === "opencode") {
+    return "opencode/big-pickle";
+  }
+  if (normalizedProviderType === "gemini_cli") {
+    return "gemini-2.5-pro";
+  }
+  return undefined;
+}
+
+export function resolveRuntimeModelForProvider(
+  providerType: string | undefined,
+  runtimeModel: string | undefined
+) {
+  const normalizedRuntimeModel = runtimeModel?.trim() || undefined;
+  if (normalizedRuntimeModel) {
+    return normalizedRuntimeModel;
+  }
+  return resolveDefaultRuntimeModelForProvider(providerType);
+}
+
 export function normalizeRuntimeConfig(input: {
   runtimeConfig?: Partial<AgentRuntimeConfig>;
   legacy?: LegacyRuntimeFields;
@@ -116,12 +145,15 @@ export function parseRuntimeConfigFromAgentRow(agent: Record<string, unknown>):
       ? timeoutSecFromColumn
       : (toSeconds(fallback.timeoutMs) ?? 0);
 
+  const providerType = toText(agent.providerType);
+  const runtimeModel = resolveRuntimeModelForProvider(providerType, toText(agent.runtimeModel) ?? fallback.model);
+
   return {
     runtimeCommand: toText(agent.runtimeCommand) ?? fallback.command,
     runtimeArgs,
     runtimeCwd: toText(agent.runtimeCwd) ?? fallback.cwd,
     runtimeEnv,
-    runtimeModel: toText(agent.runtimeModel),
+    runtimeModel,
     runtimeThinkingEffort: parseThinkingEffort(agent.runtimeThinkingEffort),
     bootstrapPrompt: toText(agent.bootstrapPrompt),
     runtimeTimeoutSec: Math.max(0, timeoutSec),
@@ -165,6 +197,7 @@ function parseRuntimeFromStateBlob(raw: unknown) {
       args?: string[];
       cwd?: string;
       env?: Record<string, string>;
+      model?: string;
       timeoutMs?: number;
     };
   }
@@ -175,6 +208,7 @@ function parseRuntimeFromStateBlob(raw: unknown) {
         args?: unknown;
         cwd?: unknown;
         env?: unknown;
+        model?: unknown;
         timeoutMs?: unknown;
       };
     };
@@ -184,6 +218,7 @@ function parseRuntimeFromStateBlob(raw: unknown) {
       args: Array.isArray(runtime.args) ? runtime.args.map((entry) => String(entry)) : undefined,
       cwd: typeof runtime.cwd === "string" ? runtime.cwd : undefined,
       env: toRecord(runtime.env),
+      model: typeof runtime.model === "string" && runtime.model.trim().length > 0 ? runtime.model.trim() : undefined,
       timeoutMs: toNumber(runtime.timeoutMs)
     };
   } catch {

package/src/lib/instance-paths.ts

@@ -62,6 +62,18 @@ export function resolveAgentFallbackWorkspacePath(companyId: string, agentId: st
   return join(resolveBopoInstanceRoot(), "workspaces", companyId, "agents", agentId);
 }
 
+export function resolveAgentMemoryRootPath(companyId: string, agentId: string) {
+  return join(resolveAgentFallbackWorkspacePath(companyId, agentId), "memory");
+}
+
+export function resolveAgentDurableMemoryPath(companyId: string, agentId: string) {
+  return join(resolveAgentMemoryRootPath(companyId, agentId), "life");
+}
+
+export function resolveAgentDailyMemoryPath(companyId: string, agentId: string) {
+  return join(resolveAgentMemoryRootPath(companyId, agentId), "memory");
+}
+
 export function resolveStorageRoot() {
   return join(resolveBopoInstanceRoot(), "data", "storage");
 }

package/src/lib/opencode-model.ts

@@ -0,0 +1,11 @@
+import type { NormalizedRuntimeConfig } from "./agent-config";
+
+export async function resolveOpencodeRuntimeModel(
+  providerType: string,
+  runtimeConfig: NormalizedRuntimeConfig
+): Promise<string | undefined> {
+  if (providerType !== "opencode") {
+    return runtimeConfig.runtimeModel?.trim() || undefined;
+  }
+  return runtimeConfig.runtimeModel?.trim() || undefined;
+}

package/src/lib/workspace-policy.ts

@@ -5,6 +5,7 @@ import {
   isInsidePath,
   normalizeAbsolutePath,
   resolveAgentFallbackWorkspacePath,
+  resolveAgentMemoryRootPath,
   resolveCompanyProjectsWorkspacePath
 } from "./instance-paths";
 
@@ -73,3 +74,7 @@ export function ensureRuntimeWorkspaceCompatible(projectWorkspacePath: string, r
 export function resolveAgentFallbackWorkspace(companyId: string, agentId: string) {
   return resolveAgentFallbackWorkspacePath(companyId, agentId);
 }
+
+export function resolveAgentMemoryRoot(companyId: string, agentId: string) {
+  return resolveAgentMemoryRootPath(companyId, agentId);
+}

package/src/realtime/heartbeat-runs.ts

@@ -0,0 +1,78 @@
+import type {
+  HeartbeatRunRealtimeEvent,
+  RealtimeEventEnvelope,
+  RealtimeMessage
+} from "bopodev-contracts";
+import { listHeartbeatRunMessagesForRuns, listHeartbeatRuns, type BopoDb } from "bopodev-db";
+
+export function createHeartbeatRunsRealtimeEvent(
+  companyId: string,
+  event: HeartbeatRunRealtimeEvent
+): Extract<RealtimeMessage, { kind: "event" }> {
+  return createRealtimeEvent(companyId, {
+    channel: "heartbeat-runs",
+    event
+  });
+}
+
+export async function loadHeartbeatRunsRealtimeSnapshot(
+  db: BopoDb,
+  companyId: string
+): Promise<Extract<RealtimeMessage, { kind: "event" }>> {
+  const runs = await listHeartbeatRuns(db, companyId, 8);
+  const transcriptsByRunId = await listHeartbeatRunMessagesForRuns(db, {
+    companyId,
+    runIds: runs.map((run) => run.id),
+    perRunLimit: 60
+  });
+  const transcripts = runs.map((run) => {
+    const result = transcriptsByRunId.get(run.id) ?? { items: [], nextCursor: null };
+    return {
+      runId: run.id,
+      messages: result.items.map((message) => ({
+        id: message.id,
+        runId: message.runId,
+        sequence: message.sequence,
+        kind: message.kind as
+          | "system"
+          | "assistant"
+          | "thinking"
+          | "tool_call"
+          | "tool_result"
+          | "result"
+          | "stderr",
+        label: message.label,
+        text: message.text,
+        payload: message.payloadJson,
+        signalLevel: (message.signalLevel as "high" | "medium" | "low" | "noise" | null) ?? undefined,
+        groupKey: message.groupKey,
+        source: (message.source as "stdout" | "stderr" | "trace_fallback" | null) ?? undefined,
+        createdAt: message.createdAt.toISOString()
+      })),
+      nextCursor: result.nextCursor
+    };
+  });
+
+  return createHeartbeatRunsRealtimeEvent(companyId, {
+    type: "runs.snapshot",
+    runs: runs.map((run) => ({
+      runId: run.id,
+      status: run.status as "started" | "completed" | "failed" | "skipped",
+      message: run.message ?? null,
+      startedAt: run.startedAt.toISOString(),
+      finishedAt: run.finishedAt?.toISOString() ?? null
+    })),
+    transcripts
+  });
+}
+
+function createRealtimeEvent(
+  companyId: string,
+  envelope: Extract<RealtimeEventEnvelope, { channel: "heartbeat-runs" }>
+): Extract<RealtimeMessage, { kind: "event" }> {
+  return {
+    kind: "event",
+    companyId,
+    ...envelope
+  };
+}

package/src/realtime/hub.ts

@@ -25,7 +25,7 @@ export function attachRealtimeHub(
 
   wss.on("connection", async (socket, request) => {
     const subscription = getSubscription(request.url);
-    if (!subscription) {
+    if (!subscription || !canSubscribeToCompany(request.headers, subscription.companyId)) {
       socket.close(1008, "Invalid realtime subscription");
       return;
     }
@@ -131,6 +131,42 @@ function getSubscription(requestUrl: string | undefined) {
   };
 }
 
+function canSubscribeToCompany(
+  headers: Record<string, string | string[] | undefined>,
+  companyId: string
+) {
+  const actorType = readHeader(headers, "x-actor-type")?.toLowerCase();
+  const actorCompanies = parseCommaList(readHeader(headers, "x-actor-companies"));
+  const hasActorHeaders = Boolean(actorType || actorCompanies.length > 0);
+  const allowLocalBoardFallback = process.env.NODE_ENV !== "production" && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK !== "0";
+
+  if (!hasActorHeaders) {
+    return allowLocalBoardFallback;
+  }
+  if (actorType === "board") {
+    return true;
+  }
+  return actorCompanies.includes(companyId);
+}
+
+function readHeader(headers: Record<string, string | string[] | undefined>, name: string) {
+  const value = headers[name];
+  if (Array.isArray(value)) {
+    return value[0];
+  }
+  return value;
+}
+
+function parseCommaList(value: string | undefined) {
+  if (!value) {
+    return [] as string[];
+  }
+  return value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+}
+
 function buildSubscriptionKey(companyId: string, channel: RealtimeChannel) {
   return `${companyId}:${channel}`;
 }

package/src/realtime/office-space.ts

@@ -427,7 +427,16 @@ function sortOccupants(occupants: OfficeOccupant[]) {
 }
 
 function normalizeProviderType(value: string): OfficeOccupant["providerType"] {
-  return value === "claude_code" || value === "codex" || value === "http" || value === "shell" ? value : null;
+  return value === "claude_code" ||
+    value === "codex" ||
+    value === "cursor" ||
+    value === "opencode" ||
+    value === "openai_api" ||
+    value === "anthropic_api" ||
+    value === "http" ||
+    value === "shell"
+    ? value
+    : null;
 }
 
 function formatActionLabel(action: string) {

package/src/routes/agents.ts

@@ -14,6 +14,7 @@ import {
   deleteAgent,
   getApprovalRequest,
   listAgents,
+  listApprovalRequests,
   updateAgent
 } from "bopodev-db";
 import type { AppContext } from "../context";
@@ -21,10 +22,12 @@ import { sendError, sendOk } from "../http";
 import {
   normalizeRuntimeConfig,
   parseRuntimeConfigFromAgentRow,
+  resolveRuntimeModelForProvider,
   requiresRuntimeCwd,
   runtimeConfigToDb,
   runtimeConfigToStateBlobPatch
 } from "../lib/agent-config";
+import { resolveOpencodeRuntimeModel } from "../lib/opencode-model";
 import { hasText, resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requireBoardRole, requirePermission } from "../middleware/request-actor";
@@ -63,7 +66,17 @@ const updateAgentSchema = AgentUpdateRequestSchema.extend({
 });
 
 const runtimePreflightSchema = z.object({
-  providerType: z.enum(["claude_code", "codex", "cursor", "opencode", "http", "shell"]),
+  providerType: z.enum([
+    "claude_code",
+    "codex",
+    "cursor",
+    "opencode",
+    "gemini_cli",
+    "openai_api",
+    "anthropic_api",
+    "http",
+    "shell"
+  ]),
   runtimeConfig: z.record(z.string(), z.unknown()).optional(),
   ...legacyRuntimeConfigSchema.shape
 });
@@ -111,6 +124,17 @@ function toAgentResponse(agent: Record<string, unknown>) {
   };
 }
 
+function providerRequiresNamedModel(providerType: string) {
+  return providerType !== "http" && providerType !== "shell";
+}
+
+function ensureNamedRuntimeModel(providerType: string, runtimeModel: string | undefined) {
+  if (!providerRequiresNamedModel(providerType)) {
+    return true;
+  }
+  return hasText(runtimeModel);
+}
+
 export function createAgentsRouter(ctx: AppContext) {
   const router = Router();
   router.use(requireCompanyScope);
@@ -143,7 +167,16 @@ export function createAgentsRouter(ctx: AppContext) {
       runtimeConfig: req.body?.runtimeConfig,
       defaultRuntimeCwd
     });
-    const typedProviderType = providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell";
+    const typedProviderType = providerType as
+      | "claude_code"
+      | "codex"
+      | "cursor"
+      | "opencode"
+      | "gemini_cli"
+      | "openai_api"
+      | "anthropic_api"
+      | "http"
+      | "shell";
     const models = await getAdapterModels(typedProviderType, {
       command: runtimeConfig.runtimeCommand,
       args: runtimeConfig.runtimeArgs,
@@ -245,6 +278,11 @@ export function createAgentsRouter(ctx: AppContext) {
       },
       defaultRuntimeCwd
     });
+    runtimeConfig.runtimeModel = await resolveOpencodeRuntimeModel(parsed.data.providerType, runtimeConfig);
+    runtimeConfig.runtimeModel = resolveRuntimeModelForProvider(parsed.data.providerType, runtimeConfig.runtimeModel);
+    if (!ensureNamedRuntimeModel(parsed.data.providerType, runtimeConfig.runtimeModel)) {
+      return sendError(res, "A named runtime model is required for this provider.", 422);
+    }
     if (requiresRuntimeCwd(parsed.data.providerType) && !hasText(runtimeConfig.runtimeCwd)) {
       return sendError(res, "Runtime working directory is required for this runtime provider.", 422);
     }
@@ -253,6 +291,19 @@ export function createAgentsRouter(ctx: AppContext) {
     }
 
     if (parsed.data.requestApproval && isApprovalRequired("hire_agent")) {
+      const duplicate = await findDuplicateHireRequest(ctx.db, req.companyId!, {
+        role: parsed.data.role,
+        managerAgentId: parsed.data.managerAgentId ?? null
+      });
+      if (duplicate) {
+        return sendOk(res, {
+          queuedForApproval: false,
+          duplicate: true,
+          existingAgentId: duplicate.existingAgentId ?? null,
+          pendingApprovalId: duplicate.pendingApprovalId ?? null,
+          message: duplicateMessage(duplicate)
+        });
+      }
       const approvalId = await createApprovalRequest(ctx.db, {
         companyId: req.companyId!,
         action: "hire_agent",
@@ -363,6 +414,11 @@ export function createAgentsRouter(ctx: AppContext) {
           })
         : {})
     };
+    nextRuntime.runtimeModel = await resolveOpencodeRuntimeModel(effectiveProviderType, nextRuntime);
+    nextRuntime.runtimeModel = resolveRuntimeModelForProvider(effectiveProviderType, nextRuntime.runtimeModel);
+    if (!ensureNamedRuntimeModel(effectiveProviderType, nextRuntime.runtimeModel)) {
+      return sendError(res, "A named runtime model is required for this provider.", 422);
+    }
     if (!nextRuntime.runtimeCwd && defaultRuntimeCwd) {
       nextRuntime.runtimeCwd = defaultRuntimeCwd;
     }
@@ -522,3 +578,56 @@ function listUnsupportedAgentUpdateKeys(payload: unknown) {
   }
   return unsupported;
 }
+
+async function findDuplicateHireRequest(
+  db: AppContext["db"],
+  companyId: string,
+  input: { role: string; managerAgentId: string | null }
+) {
+  const role = input.role.trim();
+  const managerAgentId = input.managerAgentId ?? null;
+  const agents = await listAgents(db, companyId);
+  const existingAgent = agents.find(
+    (agent) =>
+      agent.role === role &&
+      (agent.managerAgentId ?? null) === managerAgentId &&
+      agent.status !== "terminated"
+  );
+  const approvals = await listApprovalRequests(db, companyId);
+  const pendingApproval = approvals.find((approval) => {
+    if (approval.status !== "pending" || approval.action !== "hire_agent") {
+      return false;
+    }
+    const payload = parseApprovalPayload(approval.payloadJson);
+    return payload.role === role && (payload.managerAgentId ?? null) === managerAgentId;
+  });
+  if (!existingAgent && !pendingApproval) {
+    return null;
+  }
+  return {
+    existingAgentId: existingAgent?.id ?? null,
+    pendingApprovalId: pendingApproval?.id ?? null
+  };
+}
+
+function parseApprovalPayload(payloadJson: string): { role?: string; managerAgentId?: string | null } {
+  try {
+    const parsed = JSON.parse(payloadJson) as Record<string, unknown>;
+    return {
+      role: typeof parsed.role === "string" ? parsed.role : undefined,
+      managerAgentId: typeof parsed.managerAgentId === "string" ? parsed.managerAgentId : null
+    };
+  } catch {
+    return {};
+  }
+}
+
+function duplicateMessage(input: { existingAgentId: string | null; pendingApprovalId: string | null }) {
+  if (input.existingAgentId && input.pendingApprovalId) {
+    return `Duplicate hire request blocked: existing agent ${input.existingAgentId} and pending approval ${input.pendingApprovalId}.`;
+  }
+  if (input.existingAgentId) {
+    return `Duplicate hire request blocked: existing agent ${input.existingAgentId}.`;
+  }
+  return `Duplicate hire request blocked: pending approval ${input.pendingApprovalId}.`;
+}

package/src/routes/companies.ts

@@ -3,6 +3,8 @@ import { z } from "zod";
 import { createCompany, deleteCompany, listCompanies, updateCompany } from "bopodev-db";
 import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
+import { ensureCompanyModelPricingDefaults } from "../services/model-pricing";
+import { ensureCompanyBuiltinPluginDefaults } from "../services/plugin-runtime";
 
 const createCompanySchema = z.object({
   name: z.string().min(1),
@@ -30,6 +32,8 @@ export function createCompaniesRouter(ctx: AppContext) {
       return sendError(res, parsed.error.message, 422);
     }
     const company = await createCompany(ctx.db, parsed.data);
+    await ensureCompanyBuiltinPluginDefaults(ctx.db, company.id);
+    await ensureCompanyModelPricingDefaults(ctx.db, company.id);
     return sendOk(res, company);
   });
 

package/src/routes/governance.ts

@@ -163,11 +163,18 @@ export function createGovernanceRouter(ctx: AppContext) {
     });
 
     if (resolution.execution.applied && resolution.execution.entityType && resolution.execution.entityId) {
+      const eventType =
+        resolution.action === "grant_plugin_capabilities"
+          ? "plugin.capabilities_granted_from_approval"
+          : resolution.execution.entityType === "agent"
+          ? "agent.hired_from_approval"
+          : resolution.execution.entityType === "goal"
+            ? "goal.activated_from_approval"
+            : "memory.promoted_from_approval";
       await appendAuditEvent(ctx.db, {
         companyId: req.companyId!,
         actorType: "human",
-        eventType:
-          resolution.execution.entityType === "agent" ? "agent.hired_from_approval" : "goal.activated_from_approval",
+        eventType,
         entityType: resolution.execution.entityType,
         entityId: resolution.execution.entityId,
         payload: resolution.execution.entity ?? { id: resolution.execution.entityId }

package/src/routes/heartbeats.ts

@@ -79,7 +79,8 @@ export function createHeartbeatRouter(ctx: AppContext) {
     const stopResult = await stopHeartbeatRun(ctx.db, req.companyId!, parsed.data.runId, {
       requestId: req.requestId,
       trigger: "manual",
-      actorId: req.actor?.id ?? undefined
+      actorId: req.actor?.id ?? undefined,
+      realtimeHub: ctx.realtimeHub
     });
     if (!stopResult.ok) {
       if (stopResult.reason === "not_found") {