bopodev-api 0.1.7 → 0.1.9

package/src/scripts/onboard-seed.ts

@@ -0,0 +1,314 @@
+import { pathToFileURL } from "node:url";
+import { mkdir } from "node:fs/promises";
+import {
+  bootstrapDatabase,
+  createAgent,
+  createCompany,
+  createIssue,
+  createProject,
+  listAgents,
+  listCompanies,
+  listIssues,
+  listProjects,
+  updateIssue,
+  updateAgent,
+  updateCompany
+} from "bopodev-db";
+import { normalizeRuntimeConfig, runtimeConfigToDb, runtimeConfigToStateBlobPatch } from "../lib/agent-config";
+import { resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
+
+export interface OnboardSeedSummary {
+  companyId: string;
+  companyName: string;
+  companyCreated: boolean;
+  ceoCreated: boolean;
+  ceoProviderType: AgentProvider;
+  ceoMigrated: boolean;
+}
+
+const DEFAULT_COMPANY_NAME_ENV = "BOPO_DEFAULT_COMPANY_NAME";
+const DEFAULT_COMPANY_ID_ENV = "BOPO_DEFAULT_COMPANY_ID";
+const DEFAULT_AGENT_PROVIDER_ENV = "BOPO_DEFAULT_AGENT_PROVIDER";
+type AgentProvider = "codex" | "claude_code" | "shell";
+const CEO_BOOTSTRAP_SUMMARY = "ceo bootstrap heartbeat";
+const STARTUP_PROJECT_NAME = "Leadership Setup";
+const CEO_STARTUP_TASK_TITLE = "Set up CEO operating files and hire founding engineer";
+const CEO_STARTUP_TASK_MARKER = "[bopohq:onboarding:ceo-startup:v1]";
+
+export async function ensureOnboardingSeed(input: {
+  dbPath?: string;
+  companyName: string;
+  companyId?: string;
+  agentProvider?: AgentProvider;
+}): Promise<OnboardSeedSummary> {
+  const companyName = input.companyName.trim();
+  if (companyName.length === 0) {
+    throw new Error("BOPO_DEFAULT_COMPANY_NAME is required for onboarding seed.");
+  }
+  const agentProvider = parseAgentProvider(input.agentProvider) ?? "shell";
+
+  const { db, client } = await bootstrapDatabase(input.dbPath);
+
+  try {
+    const companies = await listCompanies(db);
+    let companyRow =
+      (input.companyId ? companies.find((entry) => entry.id === input.companyId) : undefined) ??
+      companies.find((entry) => entry.name === companyName);
+    let companyCreated = false;
+
+    if (!companyRow) {
+      const createdCompany = await createCompany(db, { name: companyName });
+      companyRow = {
+        id: createdCompany.id,
+        name: createdCompany.name,
+        mission: createdCompany.mission ?? null,
+        createdAt: new Date()
+      };
+      companyCreated = true;
+    } else if (companyRow.name !== companyName) {
+      companyRow = (await updateCompany(db, { id: companyRow.id, name: companyName })) ?? companyRow;
+    }
+
+    const companyId = companyRow.id;
+    const resolvedCompanyName = companyRow.name;
+    const defaultRuntimeCwd = await resolveDefaultRuntimeCwdForCompany(db, companyId);
+    await mkdir(defaultRuntimeCwd, { recursive: true });
+    const defaultRuntimeConfig = normalizeRuntimeConfig({
+      defaultRuntimeCwd,
+      runtimeConfig: {
+        runtimeEnv: resolveSeedRuntimeEnv(agentProvider)
+      }
+    });
+    const agents = await listAgents(db, companyId);
+    const existingCeo = agents.find((agent) => agent.role === "CEO" || agent.name === "CEO");
+    let ceoCreated = false;
+    let ceoMigrated = false;
+    let ceoProviderType: AgentProvider = parseAgentProvider(existingCeo?.providerType) ?? agentProvider;
+
+    let ceoId = existingCeo?.id ?? null;
+
+    if (!existingCeo) {
+      const ceo = await createAgent(db, {
+        companyId,
+        role: "CEO",
+        name: "CEO",
+        providerType: agentProvider,
+        heartbeatCron: "*/5 * * * *",
+        monthlyBudgetUsd: "100.0000",
+        canHireAgents: true,
+        ...runtimeConfigToDb(defaultRuntimeConfig),
+        initialState: runtimeConfigToStateBlobPatch(defaultRuntimeConfig)
+      });
+      ceoId = ceo.id;
+      ceoCreated = true;
+      ceoProviderType = agentProvider;
+    } else if (isBootstrapCeoRuntime(existingCeo.providerType, existingCeo.stateBlob)) {
+      const nextState = {
+        ...stripRuntimeFromState(existingCeo.stateBlob),
+        ...runtimeConfigToStateBlobPatch(defaultRuntimeConfig)
+      };
+      await updateAgent(db, {
+        companyId,
+        id: existingCeo.id,
+        providerType: agentProvider,
+        ...runtimeConfigToDb(defaultRuntimeConfig),
+        stateBlob: nextState
+      });
+      ceoMigrated = true;
+      ceoProviderType = agentProvider;
+      ceoId = existingCeo.id;
+    } else {
+      ceoId = existingCeo.id;
+    }
+
+    if (ceoId) {
+      const startupProjectId = await ensureStartupProject(db, companyId);
+      await ensureCeoStartupTask(db, {
+        companyId,
+        projectId: startupProjectId,
+        ceoId
+      });
+    }
+
+    return {
+      companyId,
+      companyName: resolvedCompanyName,
+      companyCreated,
+      ceoCreated,
+      ceoProviderType,
+      ceoMigrated
+    };
+  } finally {
+    const maybeClose = (client as { close?: () => Promise<void> }).close;
+    if (maybeClose) {
+      await maybeClose.call(client);
+    }
+  }
+}
+
+async function ensureStartupProject(db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"], companyId: string) {
+  const projects = await listProjects(db, companyId);
+  const existing = projects.find((project) => project.name === STARTUP_PROJECT_NAME);
+  if (existing) {
+    return existing.id;
+  }
+  const created = await createProject(db, {
+    companyId,
+    name: STARTUP_PROJECT_NAME,
+    description: "Initial leadership onboarding and operating setup."
+  });
+  return created.id;
+}
+
+async function ensureCeoStartupTask(
+  db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"],
+  input: { companyId: string; projectId: string; ceoId: string }
+) {
+  const issues = await listIssues(db, input.companyId);
+  const existing = issues.find(
+    (issue) =>
+      issue.assigneeAgentId === input.ceoId &&
+      issue.title === CEO_STARTUP_TASK_TITLE &&
+      typeof issue.body === "string" &&
+      issue.body.includes(CEO_STARTUP_TASK_MARKER)
+  );
+  const body = [
+    CEO_STARTUP_TASK_MARKER,
+    "",
+    "Stand up your leadership operating baseline before taking on additional delivery work.",
+    "",
+    "1. Create the folder `agents/ceo/` in the repository workspace.",
+    "2. Author these files with your own voice and responsibilities:",
+    "   - `agents/ceo/AGENTS.md`",
+    "   - `agents/ceo/HEARTBEAT.md`",
+    "   - `agents/ceo/SOUL.md`",
+    "   - `agents/ceo/TOOLS.md`",
+    "3. Save your operating-file reference on your own agent record via `PUT /agents/:agentId`.",
+    "   - Supported simple body: `{ \"bootstrapPrompt\": \"Primary operating reference: agents/ceo/AGENTS.md ...\" }`",
+    "   - If using `runtimeConfig`, only `runtimeConfig.bootstrapPrompt` is supported there.",
+    "   - Use a temp JSON file or heredoc with `curl --data @file`; do not hand-escape multiline JSON.",
+    "4. To inspect your own agent record, use `GET /agents` and filter by your agent id. Do not call `GET /agents/:agentId`.",
+    "   - `GET /agents` may be wrapped as `{ \"ok\": true, \"data\": [...] }` or returned as a raw array.",
+    "   - Shape-safe filter: `jq -er --arg id \"$BOPOHQ_AGENT_ID\" '(.data? // .) | if type==\"array\" then . else [] end | map(select(.id == $id))[0] | {id,name,role,bootstrapPrompt}'`",
+    "5. Heartbeat-assigned issues are already claimed for the current run. Do not call a checkout endpoint; update status with `PUT /issues/:issueId` only.",
+    "6. After your operating files are active, submit a hire request for a Founding Engineer via `POST /agents` using supported fields:",
+    "   - `name`, `role`, `providerType`, `heartbeatCron`, `monthlyBudgetUsd`",
+    "   - optional `managerAgentId`, `bootstrapPrompt`, `runtimeConfig`, `canHireAgents`",
+    "   - `requestApproval: true` and `sourceIssueId`",
+    "7. Do not use unsupported hire fields such as `adapterType`, `adapterConfig`, or `reportsTo`.",
+    "",
+    "Safety checks before requesting hire:",
+    "- Do not request duplicates if a Founding Engineer already exists.",
+    "- Do not request duplicates if a pending approval for the same role is already open.",
+    "- Do not assume `python` is installed in the runtime shell; prefer direct headers, `node`, or `jq` when scripting.",
+    "- Shell commands run under `zsh`; avoid Bash-only features such as `local -n`, `declare -n`, `mapfile`, and `readarray`."
+  ].join("\n");
+  if (existing) {
+    if (existing.body !== body) {
+      await updateIssue(db, {
+        companyId: input.companyId,
+        id: existing.id,
+        body
+      });
+    }
+    return existing.id;
+  }
+
+  const startupIssue = await createIssue(db, {
+    companyId: input.companyId,
+    projectId: input.projectId,
+    title: CEO_STARTUP_TASK_TITLE,
+    body,
+    status: "todo",
+    priority: "high",
+    assigneeAgentId: input.ceoId,
+    labels: ["onboarding", "leadership", "agent-setup"],
+    tags: ["ceo-startup"]
+  });
+  return startupIssue.id;
+}
+
+async function main() {
+  const companyName = process.env[DEFAULT_COMPANY_NAME_ENV]?.trim() ?? "";
+  const companyId = process.env[DEFAULT_COMPANY_ID_ENV]?.trim() || undefined;
+  const agentProvider = parseAgentProvider(process.env[DEFAULT_AGENT_PROVIDER_ENV]) ?? undefined;
+  const result = await ensureOnboardingSeed({
+    dbPath: process.env.BOPO_DB_PATH,
+    companyName,
+    companyId,
+    agentProvider
+  });
+  // eslint-disable-next-line no-console
+  console.log(JSON.stringify(result));
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  void main();
+}
+
+function parseAgentProvider(value: unknown): AgentProvider | null {
+  if (value === "codex" || value === "claude_code" || value === "shell") {
+    return value;
+  }
+  return null;
+}
+
+function resolveSeedRuntimeEnv(agentProvider: AgentProvider): Record<string, string> {
+  if (agentProvider !== "codex") {
+    return {};
+  }
+  const key = (process.env.BOPO_OPENAI_API_KEY ?? process.env.OPENAI_API_KEY)?.trim();
+  if (!key) {
+    return {};
+  }
+  return {
+    OPENAI_API_KEY: key
+  };
+}
+
+function isBootstrapCeoRuntime(providerType: string, stateBlob: string | null) {
+  if (providerType !== "shell") {
+    return false;
+  }
+  const runtime = parseRuntimeFromState(stateBlob);
+  if (!runtime || runtime.command !== "echo") {
+    return false;
+  }
+  const args = Array.isArray(runtime.args) ? runtime.args.map((entry) => String(entry).toLowerCase()) : [];
+  return args.some((entry) => entry.includes(CEO_BOOTSTRAP_SUMMARY));
+}
+
+function parseRuntimeFromState(stateBlob: string | null): { command?: string; args?: string[] } | null {
+  if (!stateBlob) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(stateBlob) as { runtime?: { command?: unknown; args?: unknown } };
+    const runtime = parsed.runtime;
+    if (!runtime || typeof runtime !== "object") {
+      return null;
+    }
+    return {
+      command: typeof runtime.command === "string" ? runtime.command : undefined,
+      args: Array.isArray(runtime.args) ? runtime.args.map((entry) => String(entry)) : undefined
+    };
+  } catch {
+    return null;
+  }
+}
+
+function stripRuntimeFromState(stateBlob: string | null) {
+  if (!stateBlob) {
+    return {};
+  }
+  try {
+    const parsed = JSON.parse(stateBlob) as Record<string, unknown>;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return {};
+    }
+    const { runtime: _runtime, ...rest } = parsed;
+    return rest;
+  } catch {
+    return {};
+  }
+}

package/src/server.ts

@@ -1,5 +1,8 @@
 import { createServer } from "node:http";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
 import { sql } from "drizzle-orm";
+import { config as loadDotenv } from "dotenv";
 import { bootstrapDatabase } from "bopodev-db";
 import { checkRuntimeCommandHealth } from "bopodev-agent-sdk";
 import type { RuntimeCommandHealth } from "bopodev-agent-sdk";
@@ -9,6 +12,8 @@ import { loadOfficeSpaceRealtimeSnapshot } from "./realtime/office-space";
 import { attachRealtimeHub } from "./realtime/hub";
 import { createHeartbeatScheduler } from "./worker/scheduler";
 
+loadApiEnv();
+
 async function main() {
   const dbPath = process.env.BOPO_DB_PATH;
   const port = Number(process.env.PORT ?? 4020);
@@ -60,8 +65,9 @@ async function main() {
   });
 
   const defaultCompanyId = process.env.BOPO_DEFAULT_COMPANY_ID;
-  if (defaultCompanyId) {
-    createHeartbeatScheduler(db, defaultCompanyId, realtimeHub);
+  const schedulerCompanyId = await resolveSchedulerCompanyId(db, defaultCompanyId ?? null);
+  if (schedulerCompanyId) {
+    createHeartbeatScheduler(db, schedulerCompanyId, realtimeHub);
   }
 }
 
@@ -77,6 +83,34 @@ async function hasCodexAgentsConfigured(db: Awaited<ReturnType<typeof bootstrapD
   return (result.rows ?? []).length > 0;
 }
 
+async function resolveSchedulerCompanyId(
+  db: Awaited<ReturnType<typeof bootstrapDatabase>>["db"],
+  configuredCompanyId: string | null
+) {
+  if (configuredCompanyId) {
+    const configured = await db.execute(sql`
+      SELECT id
+      FROM companies
+      WHERE id = ${configuredCompanyId}
+      LIMIT 1
+    `);
+    if ((configured.rows ?? []).length > 0) {
+      return configuredCompanyId;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`[startup] BOPO_DEFAULT_COMPANY_ID='${configuredCompanyId}' was not found; using first available company.`);
+  }
+
+  const fallback = await db.execute(sql`
+    SELECT id
+    FROM companies
+    ORDER BY created_at ASC
+    LIMIT 1
+  `);
+  const id = fallback.rows?.[0]?.id;
+  return typeof id === "string" && id.length > 0 ? id : null;
+}
+
 function emitCodexPreflightWarning(health: RuntimeCommandHealth) {
   const red = process.stderr.isTTY ? "\x1b[31m" : "";
   const yellow = process.stderr.isTTY ? "\x1b[33m" : "";
@@ -90,3 +124,12 @@ function emitCodexPreflightWarning(health: RuntimeCommandHealth) {
     process.stderr.write(`  Details: ${JSON.stringify(health)}\n`);
   }
 }
+
+function loadApiEnv() {
+  const sourceDir = dirname(fileURLToPath(import.meta.url));
+  const repoRoot = resolve(sourceDir, "../../../");
+  const candidates = [resolve(repoRoot, ".env.local"), resolve(repoRoot, ".env")];
+  for (const path of candidates) {
+    loadDotenv({ path, override: false, quiet: true });
+  }
+}

package/src/services/governance-service.ts

@@ -1,7 +1,26 @@
 import { and, eq } from "drizzle-orm";
+import { mkdir } from "node:fs/promises";
 import { z } from "zod";
+import { AgentCreateRequestSchema } from "bopodev-contracts";
 import type { BopoDb } from "bopodev-db";
-import { approvalRequests, createAgent, createGoal, goals, projects } from "bopodev-db";
+import {
+  approvalRequests,
+  createAgent,
+  createGoal,
+  createIssue,
+  createProject,
+  goals,
+  listIssues,
+  listProjects,
+  projects
+} from "bopodev-db";
+import {
+  normalizeRuntimeConfig,
+  requiresRuntimeCwd,
+  runtimeConfigToDb,
+  runtimeConfigToStateBlobPatch
+} from "../lib/agent-config";
+import { hasText, resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
 
 const approvalGatedActions = new Set([
   "hire_agent",
@@ -11,18 +30,23 @@ const approvalGatedActions = new Set([
   "terminate_agent"
 ]);
 
-const hireAgentPayloadSchema = 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().min(1),
-  monthlyBudgetUsd: z.number().nonnegative(),
-  canHireAgents: z.boolean().default(false),
+const hireAgentPayloadSchema = AgentCreateRequestSchema.extend({
   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 activateGoalPayloadSchema = z.object({
@@ -32,6 +56,8 @@ const activateGoalPayloadSchema = z.object({
   title: z.string().min(1),
   description: z.string().optional()
 });
+const AGENT_STARTUP_PROJECT_NAME = "Agent Onboarding";
+const AGENT_STARTUP_TASK_MARKER = "[bopohq:onboarding:agent-startup:v1]";
 
 export class GovernanceError extends Error {
   constructor(message: string) {
@@ -132,6 +158,30 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
     if (!parsed.success) {
       throw new GovernanceError("Approval payload for agent hiring is invalid.");
     }
+    const defaultRuntimeCwd = await resolveDefaultRuntimeCwdForCompany(db, 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)) {
+      throw new GovernanceError("Approval payload for agent hiring is missing runtime working directory.");
+    }
+    if (requiresRuntimeCwd(parsed.data.providerType) && hasText(runtimeConfig.runtimeCwd)) {
+      await mkdir(runtimeConfig.runtimeCwd!, { recursive: true });
+    }
 
     const agent = await createAgent(db, {
       companyId,
@@ -142,15 +192,11 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
       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)
     });
+    const startupProjectId = await ensureAgentStartupProject(db, companyId);
+    await ensureAgentStartupIssue(db, companyId, startupProjectId, agent.id, agent.role, agent.name);
 
     return {
       applied: true,
@@ -227,3 +273,83 @@ function parsePayload(payloadJson: string) {
     return {};
   }
 }
+
+async function ensureAgentStartupProject(db: BopoDb, companyId: string) {
+  const projects = await listProjects(db, companyId);
+  const existing = projects.find((project) => project.name === AGENT_STARTUP_PROJECT_NAME);
+  if (existing) {
+    return existing.id;
+  }
+  const created = await createProject(db, {
+    companyId,
+    name: AGENT_STARTUP_PROJECT_NAME,
+    description: "Operating baseline tasks for newly approved hires."
+  });
+  return created.id;
+}
+
+async function ensureAgentStartupIssue(
+  db: BopoDb,
+  companyId: string,
+  projectId: string,
+  agentId: string,
+  role: string,
+  name: string
+) {
+  const title = `Set up ${role} operating files`;
+  const body = buildAgentStartupTaskBody(name, agentId);
+  const existingIssues = await listIssues(db, companyId);
+  const existing = existingIssues.find(
+    (issue) =>
+      issue.assigneeAgentId === agentId &&
+      issue.title === title &&
+      typeof issue.body === "string" &&
+      issue.body.includes(AGENT_STARTUP_TASK_MARKER)
+  );
+  if (existing) {
+    return existing.id;
+  }
+  const created = await createIssue(db, {
+    companyId,
+    projectId,
+    title,
+    body,
+    status: "todo",
+    priority: "high",
+    assigneeAgentId: agentId,
+    labels: ["onboarding", "agent-setup"],
+    tags: ["agent-startup"]
+  });
+  return created.id;
+}
+
+function buildAgentStartupTaskBody(agentName: string, agentId: string) {
+  const slug = slugifyAgentPath(agentName || agentId);
+  return [
+    AGENT_STARTUP_TASK_MARKER,
+    "",
+    `Create your operating baseline before starting feature delivery work.`,
+    "",
+    `1. Create the folder \`agents/${slug}/\` in the repository workspace.`,
+    "2. Author these files with your own responsibilities and working style:",
+    `   - \`agents/${slug}/AGENTS.md\``,
+    `   - \`agents/${slug}/HEARTBEAT.md\``,
+    `   - \`agents/${slug}/SOUL.md\``,
+    `   - \`agents/${slug}/TOOLS.md\``,
+    `3. Update your own agent runtime config via \`PUT /agents/:agentId\` and set \`runtimeConfig.bootstrapPrompt\` to reference \`agents/${slug}/AGENTS.md\` as your primary guide.`,
+    "4. Post an issue comment summarizing completed setup artifacts.",
+    "",
+    "Safety checks:",
+    "- Do not overwrite another agent's folder.",
+    "- Keep content original to your role and scope."
+  ].join("\n");
+}
+
+function slugifyAgentPath(value: string) {
+  const base = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return base || "agent";
+}
+