bopodev-api 0.1.7 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bopodev-api",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -10,14 +10,15 @@
   "dependencies": {
     "cors": "^2.8.5",
     "cron-parser": "^5.3.1",
+    "dotenv": "^17.0.1",
     "drizzle-orm": "^0.44.5",
     "express": "^5.1.0",
     "nanoid": "^5.1.5",
     "ws": "^8.19.0",
     "zod": "^4.1.5",
-    "bopodev-agent-sdk": "0.1.7",
-    "bopodev-db": "0.1.7",
-    "bopodev-contracts": "0.1.7"
+    "bopodev-agent-sdk": "0.1.9",
+    "bopodev-contracts": "0.1.9",
+    "bopodev-db": "0.1.9"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",
@@ -29,6 +30,8 @@
     "dev": "PORT=${API_PORT:-4020} tsx watch src/server.ts",
     "start": "PORT=${API_PORT:-4020} tsx src/server.ts",
     "db:init": "tsx src/scripts/db-init.ts",
+    "onboard:seed": "tsx src/scripts/onboard-seed.ts",
+    "workspaces:backfill": "tsx src/scripts/backfill-project-workspaces.ts",
     "build": "tsc -p tsconfig.json",
     "lint": "tsc -p tsconfig.json --noEmit",
     "typecheck": "tsc -p tsconfig.json --noEmit"

package/src/lib/agent-config.ts

@@ -0,0 +1,255 @@
+import { AgentRuntimeConfigSchema, type AgentRuntimeConfig, type ThinkingEffort } from "bopodev-contracts";
+
+export type LegacyRuntimeFields = {
+  runtimeCommand?: string;
+  runtimeArgs?: string[];
+  runtimeCwd?: string;
+  runtimeTimeoutMs?: number;
+  runtimeModel?: string;
+  runtimeThinkingEffort?: ThinkingEffort;
+  bootstrapPrompt?: string;
+  runtimeTimeoutSec?: number;
+  interruptGraceSec?: number;
+  runPolicy?: {
+    sandboxMode?: "workspace_write" | "full_access";
+    allowWebSearch?: boolean;
+  };
+  runtimeEnv?: Record<string, string>;
+};
+
+export type NormalizedRuntimeConfig = {
+  runtimeCommand?: string;
+  runtimeArgs: string[];
+  runtimeCwd?: string;
+  runtimeEnv: Record<string, string>;
+  runtimeModel?: string;
+  runtimeThinkingEffort: ThinkingEffort;
+  bootstrapPrompt?: string;
+  runtimeTimeoutSec: number;
+  interruptGraceSec: number;
+  runPolicy: {
+    sandboxMode: "workspace_write" | "full_access";
+    allowWebSearch: boolean;
+  };
+};
+
+export function requiresRuntimeCwd(providerType: string) {
+  return providerType === "codex" || providerType === "claude_code" || providerType === "shell";
+}
+
+export function normalizeRuntimeConfig(input: {
+  runtimeConfig?: Partial<AgentRuntimeConfig>;
+  legacy?: LegacyRuntimeFields;
+  defaultRuntimeCwd?: string;
+}): NormalizedRuntimeConfig {
+  const runtimeConfig = input.runtimeConfig ?? {};
+  const legacy = input.legacy ?? {};
+  const merged: Record<string, unknown> = { ...runtimeConfig };
+
+  if (legacy.runtimeCommand !== undefined) {
+    merged.runtimeCommand = legacy.runtimeCommand;
+  }
+  if (legacy.runtimeArgs !== undefined) {
+    merged.runtimeArgs = legacy.runtimeArgs;
+  }
+  if (legacy.runtimeCwd !== undefined) {
+    merged.runtimeCwd = legacy.runtimeCwd;
+  }
+  if (legacy.runtimeModel !== undefined) {
+    merged.runtimeModel = legacy.runtimeModel;
+  }
+  if (legacy.runtimeThinkingEffort !== undefined) {
+    merged.runtimeThinkingEffort = legacy.runtimeThinkingEffort;
+  }
+  if (legacy.bootstrapPrompt !== undefined) {
+    merged.bootstrapPrompt = legacy.bootstrapPrompt;
+  }
+  if (legacy.interruptGraceSec !== undefined) {
+    merged.interruptGraceSec = legacy.interruptGraceSec;
+  }
+  if (legacy.runtimeEnv !== undefined) {
+    merged.runtimeEnv = legacy.runtimeEnv;
+  }
+  if (legacy.runPolicy !== undefined) {
+    merged.runPolicy = legacy.runPolicy;
+  }
+
+  const parsed = AgentRuntimeConfigSchema.partial().parse({
+    ...merged,
+    runtimeTimeoutSec:
+      runtimeConfig.runtimeTimeoutSec ??
+      legacy.runtimeTimeoutSec ??
+      toSeconds(legacy.runtimeTimeoutMs) ??
+      undefined
+  });
+  return {
+    runtimeCommand: parsed.runtimeCommand?.trim() || undefined,
+    runtimeArgs: parsed.runtimeArgs ?? [],
+    runtimeCwd: parsed.runtimeCwd?.trim() || input.defaultRuntimeCwd || undefined,
+    runtimeEnv: parsed.runtimeEnv ?? {},
+    runtimeModel: parsed.runtimeModel?.trim() || undefined,
+    runtimeThinkingEffort: parsed.runtimeThinkingEffort ?? "auto",
+    bootstrapPrompt: parsed.bootstrapPrompt?.trim() || undefined,
+    runtimeTimeoutSec: Math.max(0, parsed.runtimeTimeoutSec ?? 0),
+    interruptGraceSec: Math.max(0, parsed.interruptGraceSec ?? 15),
+    runPolicy: {
+      sandboxMode: parsed.runPolicy?.sandboxMode ?? "workspace_write",
+      allowWebSearch: parsed.runPolicy?.allowWebSearch ?? false
+    }
+  };
+}
+
+export function parseRuntimeConfigFromAgentRow(agent: Record<string, unknown>): NormalizedRuntimeConfig {
+  const fallback = parseRuntimeFromStateBlob(agent.stateBlob);
+  const runtimeArgs = parseStringArray(agent.runtimeArgsJson) ?? fallback.args ?? [];
+  const runtimeEnv = parseStringRecord(agent.runtimeEnvJson) ?? fallback.env ?? {};
+  const runPolicy = parseRunPolicy(agent.runPolicyJson);
+  const timeoutSecFromColumn = toNumber(agent.runtimeTimeoutSec);
+  const timeoutSec =
+    timeoutSecFromColumn && timeoutSecFromColumn > 0
+      ? timeoutSecFromColumn
+      : (toSeconds(fallback.timeoutMs) ?? 0);
+
+  return {
+    runtimeCommand: toText(agent.runtimeCommand) ?? fallback.command,
+    runtimeArgs,
+    runtimeCwd: toText(agent.runtimeCwd) ?? fallback.cwd,
+    runtimeEnv,
+    runtimeModel: toText(agent.runtimeModel),
+    runtimeThinkingEffort: parseThinkingEffort(agent.runtimeThinkingEffort),
+    bootstrapPrompt: toText(agent.bootstrapPrompt),
+    runtimeTimeoutSec: Math.max(0, timeoutSec),
+    interruptGraceSec: Math.max(0, toNumber(agent.interruptGraceSec) ?? 15),
+    runPolicy
+  };
+}
+
+export function runtimeConfigToDb(runtime: NormalizedRuntimeConfig) {
+  return {
+    runtimeCommand: runtime.runtimeCommand ?? null,
+    runtimeArgsJson: JSON.stringify(runtime.runtimeArgs),
+    runtimeCwd: runtime.runtimeCwd ?? null,
+    runtimeEnvJson: JSON.stringify(runtime.runtimeEnv),
+    runtimeModel: runtime.runtimeModel ?? null,
+    runtimeThinkingEffort: runtime.runtimeThinkingEffort,
+    bootstrapPrompt: runtime.bootstrapPrompt ?? null,
+    runtimeTimeoutSec: runtime.runtimeTimeoutSec,
+    interruptGraceSec: runtime.interruptGraceSec,
+    runPolicyJson: JSON.stringify(runtime.runPolicy)
+  };
+}
+
+export function runtimeConfigToStateBlobPatch(runtime: NormalizedRuntimeConfig) {
+  return {
+    runtime: {
+      command: runtime.runtimeCommand,
+      args: runtime.runtimeArgs,
+      cwd: runtime.runtimeCwd,
+      env: runtime.runtimeEnv,
+      timeoutMs: runtime.runtimeTimeoutSec > 0 ? runtime.runtimeTimeoutSec * 1000 : undefined
+    },
+    promptTemplate: runtime.bootstrapPrompt
+  };
+}
+
+function parseRuntimeFromStateBlob(raw: unknown) {
+  if (typeof raw !== "string" || !raw.trim()) {
+    return {} as {
+      command?: string;
+      args?: string[];
+      cwd?: string;
+      env?: Record<string, string>;
+      timeoutMs?: number;
+    };
+  }
+  try {
+    const parsed = JSON.parse(raw) as {
+      runtime?: {
+        command?: unknown;
+        args?: unknown;
+        cwd?: unknown;
+        env?: unknown;
+        timeoutMs?: unknown;
+      };
+    };
+    const runtime = parsed.runtime ?? {};
+    return {
+      command: typeof runtime.command === "string" ? runtime.command : undefined,
+      args: Array.isArray(runtime.args) ? runtime.args.map((entry) => String(entry)) : undefined,
+      cwd: typeof runtime.cwd === "string" ? runtime.cwd : undefined,
+      env: toRecord(runtime.env),
+      timeoutMs: toNumber(runtime.timeoutMs)
+    };
+  } catch {
+    return {};
+  }
+}
+
+function parseStringArray(raw: unknown) {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    return Array.isArray(parsed) ? parsed.map((entry) => String(entry)) : null;
+  } catch {
+    return null;
+  }
+}
+
+function parseStringRecord(raw: unknown) {
+  if (typeof raw !== "string") {
+    return null;
+  }
+  try {
+    return toRecord(JSON.parse(raw));
+  } catch {
+    return null;
+  }
+}
+
+function parseRunPolicy(raw: unknown) {
+  const parsed = parseStringRecord(raw) as { sandboxMode?: unknown; allowWebSearch?: unknown } | null;
+  return {
+    sandboxMode: parsed?.sandboxMode === "full_access" ? "full_access" : "workspace_write",
+    allowWebSearch: Boolean(parsed?.allowWebSearch)
+  } as const;
+}
+
+function parseThinkingEffort(raw: unknown): ThinkingEffort {
+  return raw === "low" || raw === "medium" || raw === "high" ? raw : "auto";
+}
+
+function toRecord(value: unknown) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return undefined;
+  }
+  return Object.fromEntries(
+    Object.entries(value).filter(([, item]) => typeof item === "string")
+  ) as Record<string, string>;
+}
+
+function toText(value: unknown) {
+  return typeof value === "string" && value.trim().length > 0 ? value : undefined;
+}
+
+function toNumber(value: unknown) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return value;
+  }
+  if (typeof value === "string") {
+    const parsed = Number(value);
+    if (Number.isFinite(parsed)) {
+      return parsed;
+    }
+  }
+  return undefined;
+}
+
+function toSeconds(milliseconds: unknown) {
+  const parsedMs = toNumber(milliseconds);
+  if (parsedMs === undefined) {
+    return undefined;
+  }
+  return Math.max(0, Math.floor(parsedMs / 1000));
+}

package/src/lib/instance-paths.ts

@@ -0,0 +1,88 @@
+import { homedir, tmpdir } from "node:os";
+import { isAbsolute, join, relative, resolve } from "node:path";
+
+const DEFAULT_INSTANCE_ID = "default";
+const SAFE_PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
+
+function expandHomePrefix(value: string) {
+  if (value === "~") {
+    return homedir();
+  }
+  if (value.startsWith("~/")) {
+    return resolve(homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function normalizePath(raw: string) {
+  return resolve(expandHomePrefix(raw.trim()));
+}
+
+export function resolveBopoHomeDir() {
+  const configured = process.env.BOPO_HOME?.trim();
+  if (configured) {
+    return normalizePath(configured);
+  }
+  return resolve(homedir(), ".bopodev");
+}
+
+export function resolveBopoInstanceId() {
+  const configured = process.env.BOPO_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
+  if (!SAFE_PATH_SEGMENT_RE.test(configured)) {
+    throw new Error(`Invalid BOPO_INSTANCE_ID '${configured}'.`);
+  }
+  return configured;
+}
+
+export function resolveBopoInstanceRoot() {
+  const configuredRoot = process.env.BOPO_INSTANCE_ROOT?.trim();
+  if (configuredRoot) {
+    return normalizePath(configuredRoot);
+  }
+  if (process.env.NODE_ENV === "test") {
+    return join(tmpdir(), "bopodev-instances", resolveBopoInstanceId());
+  }
+  return join(resolveBopoHomeDir(), "instances", resolveBopoInstanceId());
+}
+
+export function resolveProjectWorkspacePath(companyId: string, projectId: string) {
+  assertPathSegment(companyId, "companyId");
+  assertPathSegment(projectId, "projectId");
+  return join(resolveBopoInstanceRoot(), "workspaces", companyId, "projects", projectId);
+}
+
+export function resolveCompanyProjectsWorkspacePath(companyId: string) {
+  assertPathSegment(companyId, "companyId");
+  return join(resolveBopoInstanceRoot(), "workspaces", companyId);
+}
+
+export function resolveAgentFallbackWorkspacePath(companyId: string, agentId: string) {
+  assertPathSegment(companyId, "companyId");
+  assertPathSegment(agentId, "agentId");
+  return join(resolveBopoInstanceRoot(), "workspaces", companyId, "agents", agentId);
+}
+
+export function resolveStorageRoot() {
+  return join(resolveBopoInstanceRoot(), "data", "storage");
+}
+
+export function normalizeAbsolutePath(value: string) {
+  return normalizePath(value);
+}
+
+export function isInsidePath(parent: string, child: string) {
+  const parentResolved = resolve(parent);
+  const childResolved = resolve(child);
+  if (!isAbsolute(parentResolved) || !isAbsolute(childResolved)) {
+    return false;
+  }
+  const rel = relative(parentResolved, childResolved);
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+function assertPathSegment(value: string, label: string) {
+  const trimmed = value.trim();
+  if (!SAFE_PATH_SEGMENT_RE.test(trimmed)) {
+    throw new Error(`Invalid ${label} for workspace path '${value}'.`);
+  }
+}

package/src/lib/workspace-policy.ts

@@ -0,0 +1,75 @@
+import { and, eq, inArray } from "drizzle-orm";
+import type { BopoDb } from "bopodev-db";
+import { projects } from "bopodev-db";
+import {
+  isInsidePath,
+  normalizeAbsolutePath,
+  resolveAgentFallbackWorkspacePath,
+  resolveCompanyProjectsWorkspacePath
+} from "./instance-paths";
+
+export function hasText(value: string | null | undefined) {
+  return Boolean(value && value.trim().length > 0);
+}
+
+export function parseRuntimeCwd(stateBlob: string | null | undefined) {
+  if (!stateBlob) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(stateBlob) as { runtime?: { cwd?: unknown } };
+    const cwd = parsed.runtime?.cwd;
+    return typeof cwd === "string" ? cwd : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function inferSingleWorkspaceLocalPath(db: BopoDb, companyId: string) {
+  const rows = await db
+    .select({ workspaceLocalPath: projects.workspaceLocalPath })
+    .from(projects)
+    .where(eq(projects.companyId, companyId));
+  const paths = Array.from(
+    new Set(
+      rows
+        .map((row) => row.workspaceLocalPath?.trim() ?? "")
+        .filter((value) => value.length > 0)
+    )
+  );
+  const singlePath = paths.length === 1 ? paths[0] : null;
+  return singlePath ? normalizeAbsolutePath(singlePath) : null;
+}
+
+export async function resolveDefaultRuntimeCwdForCompany(db: BopoDb, companyId: string) {
+  const inferredSingleWorkspace = await inferSingleWorkspaceLocalPath(db, companyId);
+  if (inferredSingleWorkspace) {
+    return inferredSingleWorkspace;
+  }
+  return resolveCompanyProjectsWorkspacePath(companyId);
+}
+
+export async function getProjectWorkspaceMap(db: BopoDb, companyId: string, projectIds: string[]) {
+  if (projectIds.length === 0) {
+    return new Map<string, string | null>();
+  }
+  const rows = await db
+    .select({ id: projects.id, workspaceLocalPath: projects.workspaceLocalPath })
+    .from(projects)
+    .where(and(eq(projects.companyId, companyId), inArray(projects.id, projectIds)));
+  return new Map(rows.map((row) => [row.id, row.workspaceLocalPath ? normalizeAbsolutePath(row.workspaceLocalPath) : null]));
+}
+
+export function ensureRuntimeInsideWorkspace(projectWorkspacePath: string, runtimeCwd: string) {
+  return isInsidePath(normalizeAbsolutePath(projectWorkspacePath), normalizeAbsolutePath(runtimeCwd));
+}
+
+export function ensureRuntimeWorkspaceCompatible(projectWorkspacePath: string, runtimeCwd: string) {
+  const projectPath = normalizeAbsolutePath(projectWorkspacePath);
+  const runtimePath = normalizeAbsolutePath(runtimeCwd);
+  return isInsidePath(projectPath, runtimePath) || isInsidePath(runtimePath, projectPath);
+}
+
+export function resolveAgentFallbackWorkspace(companyId: string, agentId: string) {
+  return resolveAgentFallbackWorkspacePath(companyId, agentId);
+}

package/src/middleware/request-actor.ts

@@ -20,13 +20,28 @@ declare global {
 
 export function attachRequestActor(req: Request, _res: Response, next: NextFunction) {
   const actorTypeHeader = req.header("x-actor-type")?.trim().toLowerCase();
-  const actorType = actorTypeHeader === "agent" || actorTypeHeader === "member" ? actorTypeHeader : "board";
-  const actorId = req.header("x-actor-id")?.trim() || "local-board";
+  const actorTypeFromHeader =
+    actorTypeHeader === "agent" || actorTypeHeader === "member" || actorTypeHeader === "board"
+      ? actorTypeHeader
+      : null;
+  const actorIdHeader = req.header("x-actor-id")?.trim();
   const companyIdsHeader = req.header("x-actor-companies")?.trim();
   const permissionsHeader = req.header("x-actor-permissions")?.trim();
 
   const companyIds = parseCommaList(companyIdsHeader);
   const permissions = parseCommaList(permissionsHeader) ?? [];
+  const hasActorHeaders = Boolean(actorTypeFromHeader || actorIdHeader || companyIds || permissions.length > 0);
+  const allowLocalBoardFallback = process.env.NODE_ENV !== "production" && process.env.BOPO_ALLOW_LOCAL_BOARD_FALLBACK !== "0";
+  const actorType = hasActorHeaders
+    ? actorTypeFromHeader ?? "member"
+    : allowLocalBoardFallback
+      ? "board"
+      : "member";
+  const actorId = hasActorHeaders
+    ? actorIdHeader || "unknown-actor"
+    : allowLocalBoardFallback
+      ? "local-board"
+      : "anonymous-member";
 
   req.actor = {
     type: actorType,
@@ -47,7 +62,7 @@ export function requirePermission(permission: string) {
 }
 
 export function requireBoardRole(req: Request, res: Response, next: NextFunction) {
-  if ((req.actor?.type ?? "board") !== "board") {
+  if (req.actor?.type !== "board") {
     return sendError(res, "Board role required.", 403);
   }
   next();
@@ -55,7 +70,10 @@ export function requireBoardRole(req: Request, res: Response, next: NextFunction
 
 export function canAccessCompany(req: Request, companyId: string) {
   const actor = req.actor;
-  if (!actor || actor.type === "board") {
+  if (!actor) {
+    return false;
+  }
+  if (actor.type === "board") {
     return true;
   }
   return actor.companyIds?.includes(companyId) ?? false;
@@ -63,7 +81,10 @@ export function canAccessCompany(req: Request, companyId: string) {
 
 function hasPermission(req: Request, permission: string) {
   const actor = req.actor;
-  if (!actor || actor.type === "board") {
+  if (!actor) {
+    return false;
+  }
+  if (actor.type === "board") {
     return true;
   }
   return actor.permissions.includes(permission);

package/src/realtime/office-space.ts

@@ -135,6 +135,7 @@ async function loadOfficeOccupantForAgent(db: BopoDb, companyId: string, agentId
       id: agents.id,
       companyId: agents.companyId,
       name: agents.name,
+      avatarSeed: agents.avatarSeed,
       role: agents.role,
       status: agents.status,
       providerType: agents.providerType,
@@ -217,6 +218,7 @@ function deriveAgentOccupant(
     id: string;
     companyId: string;
     name: string;
+    avatarSeed?: string | null;
     role: string;
     status: string;
     providerType: string;
@@ -294,6 +296,7 @@ function deriveAgentOccupant(
       status: "waiting_for_approval",
       taskLabel: `${formatActionLabel(pendingApproval.action)} approval`,
       providerType: normalizeProviderType(agent.providerType),
+      avatarSeed: agent.avatarSeed ?? null,
       focusEntityType: "approval",
       focusEntityId: pendingApproval.id,
       updatedAt: pendingApproval.createdAt.toISOString()
@@ -313,6 +316,7 @@ function deriveAgentOccupant(
       status: "working",
       taskLabel: claimedIssues[0]?.title ?? "Checking in on work",
       providerType: normalizeProviderType(agent.providerType),
+      avatarSeed: agent.avatarSeed ?? null,
       focusEntityType: claimedIssues[0] ? "issue" : "agent",
       focusEntityId: claimedIssues[0]?.id ?? agent.id,
       updatedAt: activeRun.startedAt.toISOString()
@@ -332,6 +336,7 @@ function deriveAgentOccupant(
       status: "paused",
       taskLabel: "Paused",
       providerType: normalizeProviderType(agent.providerType),
+      avatarSeed: agent.avatarSeed ?? null,
       focusEntityType: "agent",
       focusEntityId: agent.id,
       updatedAt: agent.updatedAt.toISOString()
@@ -350,6 +355,7 @@ function deriveAgentOccupant(
     status: "idle",
     taskLabel: nextAssignedIssue ? `Up next: ${nextAssignedIssue.title}` : "Waiting for work",
     providerType: normalizeProviderType(agent.providerType),
+    avatarSeed: agent.avatarSeed ?? null,
     focusEntityType: nextAssignedIssue ? "issue" : "agent",
     focusEntityId: nextAssignedIssue?.id ?? agent.id,
     updatedAt: nextAssignedIssue?.updatedAt.toISOString() ?? agent.updatedAt.toISOString()
@@ -386,6 +392,7 @@ function deriveHireCandidateOccupant(approval: {
     status: "waiting_for_approval",
     taskLabel: "Awaiting hire approval",
     providerType,
+    avatarSeed: null,
     focusEntityType: "approval",
     focusEntityId: approval.id,
     updatedAt: approval.createdAt.toISOString()