bopodev-api 0.1.30 → 0.1.32

package/src/services/company-file-import-service.ts

@@ -0,0 +1,279 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { unzipSync } from "fflate";
+import { parse as yamlParse } from "yaml";
+import { z } from "zod";
+import type { BopoDb } from "bopodev-db";
+import { createAgent, createCompany, createProject } from "bopodev-db";
+import { normalizeRuntimeConfig, runtimeConfigToDb, runtimeConfigToStateBlobPatch } from "../lib/agent-config";
+import {
+  resolveAgentMemoryRootPath,
+  resolveAgentOperatingPath,
+  resolveCompanyProjectsWorkspacePath
+} from "../lib/instance-paths";
+import { resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
+import { ensureBuiltinPluginsRegistered } from "./plugin-runtime";
+import { ensureCompanyBuiltinTemplateDefaults } from "./template-catalog";
+import { addWorkLoopTrigger, createWorkLoop } from "./work-loop-service/work-loop-service";
+
+const EXPORT_SCHEMA = "bopo/company-export/v1";
+
+const BopoExportYamlSchema = z.object({
+  schema: z.string(),
+  company: z.object({
+    name: z.string().min(1),
+    mission: z.string().nullable().optional(),
+    slug: z.string().optional()
+  }),
+  projects: z.record(z.string(), z.object({ name: z.string().min(1), description: z.string().nullable().optional(), status: z.string().optional() })),
+  agents: z.record(
+    z.string(),
+    z.object({
+      name: z.string().min(1),
+      role: z.string().min(1),
+      roleKey: z.string().nullable().optional(),
+      title: z.string().nullable().optional(),
+      capabilities: z.string().nullable().optional(),
+      managerSlug: z.string().nullable().optional(),
+      providerType: z.string().min(1),
+      heartbeatCron: z.string().min(1),
+      canHireAgents: z.boolean().optional()
+    })
+  ),
+  routines: z
+    .record(
+      z.string(),
+      z.object({
+        title: z.string().min(1),
+        description: z.string().nullable().optional(),
+        projectSlug: z.string().min(1),
+        assigneeAgentSlug: z.string().min(1),
+        triggers: z
+          .array(
+            z.object({
+              cronExpression: z.string().min(1),
+              timezone: z.string().optional(),
+              label: z.string().nullable().optional()
+            })
+          )
+          .min(1)
+      })
+    )
+    .optional()
+});
+
+export class CompanyFileImportError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "CompanyFileImportError";
+  }
+}
+
+function normalizeZipPath(key: string): string | null {
+  const t = key.replace(/\\/g, "/").replace(/^\/+/, "");
+  if (!t || t.includes("..")) {
+    return null;
+  }
+  return t;
+}
+
+function decodeZipEntries(buffer: Buffer): Record<string, string> {
+  let raw: Record<string, Uint8Array>;
+  try {
+    raw = unzipSync(new Uint8Array(buffer));
+  } catch {
+    throw new CompanyFileImportError("Archive is not a valid zip file.");
+  }
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(raw)) {
+    const path = normalizeZipPath(k);
+    if (!path || path.endsWith("/")) {
+      continue;
+    }
+    try {
+      out[path] = new TextDecoder("utf8", { fatal: false }).decode(v);
+    } catch {
+      /* skip binary */
+    }
+  }
+  return out;
+}
+
+const PROVIDER_TYPES = new Set([
+  "claude_code",
+  "codex",
+  "cursor",
+  "opencode",
+  "gemini_cli",
+  "openai_api",
+  "anthropic_api",
+  "openclaw_gateway",
+  "http",
+  "shell"
+]);
+
+type AgentProvider = NonNullable<Parameters<typeof createAgent>[1]["providerType"]>;
+
+function coerceProviderType(raw: string): AgentProvider {
+  return PROVIDER_TYPES.has(raw) ? (raw as AgentProvider) : "shell";
+}
+
+export async function importCompanyFromZipBuffer(db: BopoDb, buffer: Buffer): Promise<{ companyId: string; name: string }> {
+  const entries = decodeZipEntries(buffer);
+  const yamlText = entries[".bopo.yaml"] ?? entries["bopo.yaml"];
+  if (!yamlText?.trim()) {
+    throw new CompanyFileImportError('Zip must contain a ".bopo.yaml" manifest at the archive root.');
+  }
+  let parsedYaml: unknown;
+  try {
+    parsedYaml = yamlParse(yamlText);
+  } catch {
+    throw new CompanyFileImportError(".bopo.yaml is not valid YAML.");
+  }
+  const parsed = BopoExportYamlSchema.safeParse(parsedYaml);
+  if (!parsed.success) {
+    throw new CompanyFileImportError(`Invalid export manifest: ${parsed.error.message}`);
+  }
+  const doc = parsed.data;
+  if (doc.schema !== EXPORT_SCHEMA) {
+    throw new CompanyFileImportError(`Unsupported export schema '${doc.schema}' (expected ${EXPORT_SCHEMA}).`);
+  }
+
+  const created = await createCompany(db, {
+    name: doc.company.name,
+    mission: doc.company.mission ?? null
+  });
+  const companyId = created.id;
+  const cwd = await resolveDefaultRuntimeCwdForCompany(db, companyId);
+  await mkdir(cwd, { recursive: true });
+  await ensureBuiltinPluginsRegistered(db, [companyId]);
+  await ensureCompanyBuiltinTemplateDefaults(db, companyId);
+
+  const projectSlugToId = new Map<string, string>();
+  const projectStatuses = new Set(["planned", "active", "paused", "blocked", "completed", "archived"]);
+  for (const [projectSlug, p] of Object.entries(doc.projects)) {
+    const st = p.status?.trim();
+    const status = st && projectStatuses.has(st) ? (st as "planned") : "planned";
+    const row = await createProject(db, {
+      companyId,
+      name: p.name,
+      description: p.description ?? null,
+      status
+    });
+    if (row) {
+      projectSlugToId.set(projectSlug, row.id);
+    }
+  }
+
+  const agentSlugToId = new Map<string, string>();
+  const agentEntries = Object.entries(doc.agents);
+  const pending = new Map(agentEntries);
+  let guard = 0;
+  while (pending.size > 0 && guard < 500) {
+    guard += 1;
+    let progressed = false;
+    for (const [slug, a] of [...pending.entries()]) {
+      const mgrSlug = a.managerSlug?.trim() || null;
+      let managerId: string | null = null;
+      if (mgrSlug) {
+        managerId = agentSlugToId.get(mgrSlug) ?? null;
+        if (!managerId) {
+          continue;
+        }
+      }
+      const defaultRt = normalizeRuntimeConfig({
+        defaultRuntimeCwd: cwd,
+        runtimeConfig: { runtimeModel: undefined, runtimeEnv: {} }
+      });
+      const createdAgent = await createAgent(db, {
+        companyId,
+        managerAgentId: managerId,
+        role: a.role,
+        roleKey: a.roleKey?.trim() || null,
+        title: a.title?.trim() || null,
+        capabilities: a.capabilities?.trim() || null,
+        name: a.name,
+        providerType: coerceProviderType(a.providerType),
+        heartbeatCron: a.heartbeatCron,
+        monthlyBudgetUsd: "100.0000",
+        canHireAgents: a.canHireAgents ?? false,
+        ...runtimeConfigToDb(defaultRt),
+        initialState: runtimeConfigToStateBlobPatch(defaultRt)
+      });
+      agentSlugToId.set(slug, createdAgent.id);
+      pending.delete(slug);
+      progressed = true;
+    }
+    if (!progressed) {
+      throw new CompanyFileImportError("Could not resolve agent manager chain (circular or missing manager slug).");
+    }
+  }
+
+  const companyRoot = resolveCompanyProjectsWorkspacePath(companyId);
+  for (const [path, text] of Object.entries(entries)) {
+    if (path === ".bopo.yaml" || path === "bopo.yaml" || path === "COMPANY.md" || path === "README.md") {
+      continue;
+    }
+    if (path.startsWith("projects/") && path.endsWith("/PROJECT.md")) {
+      continue;
+    }
+    if (path.startsWith("tasks/") && path.endsWith("/TASK.md")) {
+      continue;
+    }
+    if (path.startsWith("agents/")) {
+      const parts = path.split("/").filter(Boolean);
+      if (parts.length < 3) {
+        continue;
+      }
+      const agentSlug = parts[1]!;
+      const agentId = agentSlugToId.get(agentSlug);
+      if (!agentId) {
+        continue;
+      }
+      const rest = parts.slice(2).join("/");
+      const isMemory = rest.startsWith("memory/");
+      const relativePath = isMemory ? rest.slice("memory/".length) : rest;
+      const base = isMemory ? resolveAgentMemoryRootPath(companyId, agentId) : resolveAgentOperatingPath(companyId, agentId);
+      const dest = join(base, relativePath);
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, text, "utf8");
+      continue;
+    }
+    if (path.startsWith("skills/")) {
+      const dest = join(companyRoot, path);
+      await mkdir(dirname(dest), { recursive: true });
+      await writeFile(dest, text, "utf8");
+    }
+  }
+
+  const routines = doc.routines ?? {};
+  for (const [, r] of Object.entries(routines)) {
+    const projectId = projectSlugToId.get(r.projectSlug);
+    const assigneeId = agentSlugToId.get(r.assigneeAgentSlug);
+    if (!projectId || !assigneeId) {
+      continue;
+    }
+    const loop = await createWorkLoop(db, {
+      companyId,
+      projectId,
+      title: r.title,
+      description: r.description?.trim() || null,
+      assigneeAgentId: assigneeId
+    });
+    if (!loop) {
+      continue;
+    }
+    for (const t of r.triggers) {
+      await addWorkLoopTrigger(db, {
+        companyId,
+        workLoopId: loop.id,
+        cronExpression: t.cronExpression,
+        timezone: t.timezone?.trim() || "UTC",
+        label: t.label ?? null,
+        enabled: true
+      });
+    }
+  }
+
+  return { companyId, name: doc.company.name };
+}

package/src/services/heartbeat-service/heartbeat-run.ts

@@ -669,7 +669,9 @@ export async function runHeartbeatForAgent(
       },
       failClosed: false
     });
-    const isCommentOrderWake = options?.wakeContext?.reason === "issue_comment_recipient";
+    const isCommentOrderWake =
+      options?.wakeContext?.reason === "issue_comment_recipient" ||
+      options?.wakeContext?.reason === "loop_execution";
     const heartbeatIdlePolicy = resolveHeartbeatIdlePolicy();
     const workItems = isCommentOrderWake ? [] : await claimIssuesForAgent(db, companyId, agentId, runId);
     const wakeWorkItems = await loadWakeContextWorkItems(db, companyId, options?.wakeContext?.issueIds);
@@ -1941,7 +1943,10 @@ function resolveExecutionWorkItems(
   wakeContextItems: IssueWorkItemRow[],
   wakeContext?: HeartbeatWakeContext
 ) {
-  if (wakeContext?.reason === "issue_comment_recipient" && wakeContextItems.length > 0) {
+  if (
+    (wakeContext?.reason === "issue_comment_recipient" || wakeContext?.reason === "loop_execution") &&
+    wakeContextItems.length > 0
+  ) {
     return wakeContextItems;
   }
   return mergeContextWorkItems(assigned, wakeContextItems);

package/src/services/memory-file-service.ts

@@ -1,5 +1,5 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import type { AgentMemoryContext } from "bopodev-agent-sdk";
 import {
   isInsidePath,
@@ -184,6 +184,76 @@ export async function appendDurableFact(input: {
   return targetFile;
 }
 
+export async function listCompanyMemoryFiles(input: { companyId: string; maxFiles?: number }) {
+  const root = resolveCompanyMemoryRootPath(input.companyId);
+  await mkdir(root, { recursive: true });
+  const maxFiles = Math.max(1, Math.min(MAX_OBSERVABILITY_FILES, input.maxFiles ?? 100));
+  const files = await walkFiles(root, maxFiles);
+  return files.map((filePath) => ({
+    path: filePath,
+    relativePath: relative(root, filePath),
+    memoryRoot: root
+  }));
+}
+
+export async function readCompanyMemoryFile(input: { companyId: string; relativePath: string }) {
+  const root = resolveCompanyMemoryRootPath(input.companyId);
+  await mkdir(root, { recursive: true });
+  const candidate = resolve(root, input.relativePath);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested memory path is outside of memory root.");
+  }
+  const info = await stat(candidate);
+  if (!info.isFile()) {
+    throw new Error("Requested memory path is not a file.");
+  }
+  if (info.size > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("Requested memory file exceeds size limit.");
+  }
+  const content = await readFile(candidate, "utf8");
+  return {
+    path: candidate,
+    relativePath: relative(root, candidate),
+    content,
+    sizeBytes: info.size
+  };
+}
+
+export async function listProjectMemoryFiles(input: { companyId: string; projectId: string; maxFiles?: number }) {
+  const root = resolveProjectMemoryRootPath(input.companyId, input.projectId);
+  await mkdir(root, { recursive: true });
+  const maxFiles = Math.max(1, Math.min(MAX_OBSERVABILITY_FILES, input.maxFiles ?? 100));
+  const files = await walkFiles(root, maxFiles);
+  return files.map((filePath) => ({
+    path: filePath,
+    relativePath: relative(root, filePath),
+    memoryRoot: root
+  }));
+}
+
+export async function readProjectMemoryFile(input: { companyId: string; projectId: string; relativePath: string }) {
+  const root = resolveProjectMemoryRootPath(input.companyId, input.projectId);
+  await mkdir(root, { recursive: true });
+  const candidate = resolve(root, input.relativePath);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested memory path is outside of memory root.");
+  }
+  const info = await stat(candidate);
+  if (!info.isFile()) {
+    throw new Error("Requested memory path is not a file.");
+  }
+  if (info.size > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("Requested memory file exceeds size limit.");
+  }
+  const content = await readFile(candidate, "utf8");
+  return {
+    path: candidate,
+    relativePath: relative(root, candidate),
+    content,
+    sizeBytes: info.size
+  };
+}
+
 export async function listAgentMemoryFiles(input: {
   companyId: string;
   agentId: string;
@@ -227,6 +297,40 @@ export async function readAgentMemoryFile(input: {
   };
 }
 
+export async function writeAgentMemoryFile(input: {
+  companyId: string;
+  agentId: string;
+  relativePath: string;
+  content: string;
+}) {
+  const root = resolveAgentMemoryRootPath(input.companyId, input.agentId);
+  await mkdir(root, { recursive: true });
+  const normalizedRel = input.relativePath.trim();
+  if (!normalizedRel || normalizedRel.includes("..")) {
+    throw new Error("Invalid relative path.");
+  }
+  const candidate = resolve(root, normalizedRel);
+  if (!isInsidePath(root, candidate)) {
+    throw new Error("Requested memory path is outside of memory root.");
+  }
+  const bytes = Buffer.byteLength(input.content, "utf8");
+  if (bytes > MAX_OBSERVABILITY_FILE_BYTES) {
+    throw new Error("Content exceeds size limit.");
+  }
+  const parent = dirname(candidate);
+  if (!isInsidePath(root, parent)) {
+    throw new Error("Invalid parent directory.");
+  }
+  await mkdir(parent, { recursive: true });
+  await writeFile(candidate, input.content, { encoding: "utf8" });
+  const info = await stat(candidate);
+  return {
+    path: candidate,
+    relativePath: relative(root, candidate),
+    sizeBytes: info.size
+  };
+}
+
 function collapseWhitespace(value: string) {
   return value.replace(/\s+/g, " ").trim();
 }

package/src/services/template-apply-service.ts

@@ -9,6 +9,7 @@ import {
   updatePluginConfig
 } from "bopodev-db";
 import { interpolateTemplateManifest, buildTemplatePreview } from "./template-preview-service";
+import { addWorkLoopTrigger, createWorkLoop } from "./work-loop-service";
 
 export class TemplateApplyError extends Error {
   constructor(message: string) {
@@ -123,6 +124,38 @@ export async function applyTemplateManifest(
     });
   }
 
+  const firstProjectId =
+    renderedManifest.projects.length > 0
+      ? projectIdByKey.get(renderedManifest.projects[0]!.key) ?? null
+      : Array.from(projectIdByKey.values())[0] ?? null;
+  for (const job of renderedManifest.recurrence) {
+    if (job.targetType !== "agent") {
+      continue;
+    }
+    const assigneeAgentId = agentIdByKey.get(job.targetKey) ?? null;
+    if (!assigneeAgentId || !firstProjectId) {
+      continue;
+    }
+    const title =
+      job.instruction?.trim() && job.instruction.trim().length > 0
+        ? job.instruction.trim()
+        : `Recurring work: ${job.targetKey}`;
+    const loop = await createWorkLoop(db, {
+      companyId: input.companyId,
+      projectId: firstProjectId,
+      title,
+      description: job.instruction?.trim() || null,
+      assigneeAgentId
+    });
+    if (loop) {
+      await addWorkLoopTrigger(db, {
+        companyId: input.companyId,
+        workLoopId: loop.id,
+        cronExpression: job.cron
+      });
+    }
+  }
+
   const install = await createTemplateInstall(db, {
     companyId: input.companyId,
     templateId: input.templateId,

package/src/services/template-catalog.ts

@@ -28,8 +28,9 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
   {
     slug: "founder-startup-basic",
     name: "Founder Startup Basic",
-    description: "Baseline operating company for solo founders launching and shipping with AI agents.",
-    version: "1.0.1",
+    description:
+      "Baseline operating company for solo founders launching and shipping with AI agents. Aligns with Bopo company file export (.bopo.yaml, projects/, agents/, tasks/) so operators can download a zip, edit markdown in git, and import a new company from the archive.",
+    version: "1.0.2",
     status: "published",
     visibility: "company",
     variables: [
@@ -117,7 +118,11 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
               "",
               "Quality bar:",
               "- Be concise, specific, and execution-ready.",
-              "- Do not produce generic plans without owners, dates, and measurable outcomes."
+              "- Do not produce generic plans without owners, dates, and measurable outcomes.",
+              "",
+              "Portable company files:",
+              "- Under workspace Templates → Export, the app can produce a zip with .bopo.yaml and per-agent markdown under agents/<slug>/.",
+              "- That tree can be edited in git and re-imported to create another company; keep those files consistent with how you actually run."
             ].join("\n")
           }
         },
@@ -237,8 +242,9 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
   {
     slug: "marketing-content-engine",
     name: "Marketing Content Engine",
-    description: "Content marketing operating template for publishing, distribution, and analytics loops.",
-    version: "1.0.1",
+    description:
+      "Content marketing operating template for publishing, distribution, and analytics loops. Uses the same Bopo company zip layout as file export/import so marketing orgs can be versioned in git and cloned via archive import.",
+    version: "1.0.2",
     status: "published",
     visibility: "company",
     variables: [
@@ -318,7 +324,11 @@ const builtinTemplateDefinitions: BuiltinTemplateDefinition[] = [
               "",
               "Escalation:",
               "- Escalate major brand/positioning shifts, compliance-sensitive claims, or budget overrun risks.",
-              "- If dependencies block publication, create unblock issues within 24h."
+              "- If dependencies block publication, create unblock issues within 24h.",
+              "",
+              "Portable company files:",
+              "- Under workspace Templates → Export, leaders can download a zip with .bopo.yaml and agent markdown under agents/<slug>/.",
+              "- That folder tree can be edited in git and re-imported to stand up a new company; keep exported docs aligned with campaigns you actually ship."
             ].join("\n")
           }
         },
@@ -514,6 +524,9 @@ export async function ensureCompanyBuiltinTemplateDefaults(db: BopoDb, companyId
       await updateTemplate(db, {
         companyId,
         id: template.id,
+        name: definition.name,
+        description: definition.description,
+        variablesJson: JSON.stringify(variables),
         currentVersion: definition.version
       });
     }

package/src/services/work-loop-service/index.ts

@@ -0,0 +1,2 @@
+export * from "./loop-cron";
+export * from "./work-loop-service";