bopodev-api 0.1.34 → 0.1.35

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

@@ -4,7 +4,7 @@ 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 { createAgent, createCompany, createGoal, createProject, updateAgent, updateGoal } from "bopodev-db";
 import { normalizeRuntimeConfig, runtimeConfigToDb, runtimeConfigToStateBlobPatch } from "../lib/agent-config";
 import {
   resolveAgentMemoryRootPath,
@@ -16,16 +16,22 @@ 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";
+export const EXPORT_SCHEMA = "bopo/company-export/v1";
 
-const BopoExportYamlSchema = z.object({
+const goalLevelSchema = z.enum(["company", "project", "agent"]);
+const goalStatusSchema = z.enum(["draft", "active", "completed", "archived"]);
+
+export 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() })),
+  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({
@@ -37,9 +43,27 @@ const BopoExportYamlSchema = z.object({
       managerSlug: z.string().nullable().optional(),
       providerType: z.string().min(1),
       heartbeatCron: z.string().min(1),
-      canHireAgents: z.boolean().optional()
+      canHireAgents: z.boolean().optional(),
+      canAssignAgents: z.boolean().optional(),
+      canCreateIssues: z.boolean().optional(),
+      bootstrapPrompt: z.string().nullable().optional(),
+      monthlyBudgetUsd: z.union([z.string(), z.number()]).optional()
     })
   ),
+  goals: z
+    .record(
+      z.string(),
+      z.object({
+        level: goalLevelSchema,
+        title: z.string().min(1),
+        description: z.string().nullable().optional(),
+        status: goalStatusSchema.optional(),
+        projectSlug: z.string().nullable().optional(),
+        parentGoalSlug: z.string().nullable().optional(),
+        ownerAgentSlug: z.string().nullable().optional()
+      })
+    )
+    .optional(),
   routines: z
     .record(
       z.string(),
@@ -62,6 +86,13 @@ const BopoExportYamlSchema = z.object({
     .optional()
 });
 
+export type BopoExportDoc = z.infer<typeof BopoExportYamlSchema>;
+
+export type ParsedCompanyPackage = {
+  doc: BopoExportDoc;
+  entries: Record<string, string>;
+};
+
 export class CompanyFileImportError extends Error {
   constructor(message: string) {
     super(message);
@@ -77,7 +108,7 @@ function normalizeZipPath(key: string): string | null {
   return t;
 }
 
-function decodeZipEntries(buffer: Buffer): Record<string, string> {
+export function decodeZipEntries(buffer: Buffer): Record<string, string> {
   let raw: Record<string, Uint8Array>;
   try {
     raw = unzipSync(new Uint8Array(buffer));
@@ -99,6 +130,30 @@ function decodeZipEntries(buffer: Buffer): Record<string, string> {
   return out;
 }
 
+/** Parse and validate a company zip; throws CompanyFileImportError on failure. */
+export function parseCompanyZipBuffer(buffer: Buffer): ParsedCompanyPackage {
+  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}).`);
+  }
+  return { doc, entries };
+}
+
 const PROVIDER_TYPES = new Set([
   "claude_code",
   "codex",
@@ -118,36 +173,60 @@ 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.');
+function formatMonthlyBudgetUsdFromManifest(raw: string | number | undefined): string {
+  if (raw === undefined) {
+    return "100.0000";
   }
-  let parsedYaml: unknown;
-  try {
-    parsedYaml = yamlParse(yamlText);
-  } catch {
-    throw new CompanyFileImportError(".bopo.yaml is not valid YAML.");
+  if (typeof raw === "number" && Number.isFinite(raw)) {
+    return raw.toFixed(4);
   }
-  const parsed = BopoExportYamlSchema.safeParse(parsedYaml);
-  if (!parsed.success) {
-    throw new CompanyFileImportError(`Invalid export manifest: ${parsed.error.message}`);
+  const s = String(raw).trim();
+  if (!s) {
+    return "100.0000";
   }
-  const doc = parsed.data;
-  if (doc.schema !== EXPORT_SCHEMA) {
-    throw new CompanyFileImportError(`Unsupported export schema '${doc.schema}' (expected ${EXPORT_SCHEMA}).`);
+  const n = Number(s);
+  return Number.isFinite(n) ? n.toFixed(4) : "100.0000";
+}
+
+function sortGoalSlugsForImport(
+  goals: Record<string, { parentGoalSlug?: string | null | undefined }>
+): string[] {
+  const slugs = Object.keys(goals);
+  const slugSet = new Set(slugs);
+  const remaining = new Set(slugs);
+  const order: string[] = [];
+  while (remaining.size > 0) {
+    const ready = [...remaining].filter((slug) => {
+      const p = goals[slug]?.parentGoalSlug?.trim();
+      if (!p) {
+        return true;
+      }
+      if (!slugSet.has(p)) {
+        throw new CompanyFileImportError(`Goal '${slug}' references unknown parent goal slug '${p}'.`);
+      }
+      return !remaining.has(p);
+    });
+    if (ready.length === 0) {
+      throw new CompanyFileImportError("Circular goal parent chain in manifest.");
+    }
+    ready.sort((a, b) => a.localeCompare(b));
+    for (const s of ready) {
+      order.push(s);
+      remaining.delete(s);
+    }
   }
+  return order;
+}
 
-  const created = await createCompany(db, {
-    name: doc.company.name,
-    mission: doc.company.mission ?? null
-  });
-  const companyId = created.id;
+/**
+ * Seeds projects, agents, workspace files, goals, and routines for an existing company.
+ * Does not create the company row or call ensureCompanyBuiltinTemplateDefaults.
+ */
+export async function seedOperationalDataFromPackage(db: BopoDb, companyId: string, parsed: ParsedCompanyPackage): Promise<void> {
+  const { doc, entries } = parsed;
   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"]);
@@ -183,7 +262,11 @@ export async function importCompanyFromZipBuffer(db: BopoDb, buffer: Buffer): Pr
       }
       const defaultRt = normalizeRuntimeConfig({
         defaultRuntimeCwd: cwd,
-        runtimeConfig: { runtimeModel: undefined, runtimeEnv: {} }
+        runtimeConfig: {
+          runtimeModel: undefined,
+          runtimeEnv: {},
+          bootstrapPrompt: a.bootstrapPrompt?.trim() || undefined
+        }
       });
       const createdAgent = await createAgent(db, {
         companyId,
@@ -195,8 +278,10 @@ export async function importCompanyFromZipBuffer(db: BopoDb, buffer: Buffer): Pr
         name: a.name,
         providerType: coerceProviderType(a.providerType),
         heartbeatCron: a.heartbeatCron,
-        monthlyBudgetUsd: "100.0000",
+        monthlyBudgetUsd: formatMonthlyBudgetUsdFromManifest(a.monthlyBudgetUsd),
         canHireAgents: a.canHireAgents ?? false,
+        canAssignAgents: a.canAssignAgents ?? true,
+        canCreateIssues: a.canCreateIssues ?? true,
         ...runtimeConfigToDb(defaultRt),
         initialState: runtimeConfigToStateBlobPatch(defaultRt)
       });
@@ -246,6 +331,54 @@ export async function importCompanyFromZipBuffer(db: BopoDb, buffer: Buffer): Pr
     }
   }
 
+  const goalsManifest = doc.goals ?? {};
+  const goalSlugToId = new Map<string, string>();
+  for (const slug of sortGoalSlugsForImport(goalsManifest)) {
+    const g = goalsManifest[slug]!;
+    const level = g.level;
+    const projectSlug = g.projectSlug?.trim() || null;
+    const projectId = projectSlug ? projectSlugToId.get(projectSlug) ?? null : null;
+    if (level === "project" && !projectId) {
+      throw new CompanyFileImportError(`Goal '${slug}' (project level) references unknown project slug '${projectSlug ?? ""}'.`);
+    }
+    if (level === "company" && projectId) {
+      throw new CompanyFileImportError(`Goal '${slug}' is company-level but specifies a project.`);
+    }
+    const parentSlug = g.parentGoalSlug?.trim() || null;
+    const parentGoalId = parentSlug ? goalSlugToId.get(parentSlug) ?? null : null;
+    if (parentSlug && !parentGoalId) {
+      throw new CompanyFileImportError(`Goal '${slug}' references unknown parent goal slug '${parentSlug}'.`);
+    }
+    const ownerSlug = g.ownerAgentSlug?.trim() || null;
+    const ownerAgentId = ownerSlug ? agentSlugToId.get(ownerSlug) ?? null : null;
+    if (ownerSlug && !ownerAgentId) {
+      throw new CompanyFileImportError(`Goal '${slug}' references unknown owner agent slug '${ownerSlug}'.`);
+    }
+    const agentLevelProjectId = level === "agent" ? projectId : null;
+    if (level === "agent" && g.projectSlug?.trim() && !projectId) {
+      throw new CompanyFileImportError(`Goal '${slug}' (agent level) references unknown project slug '${g.projectSlug.trim()}'.`);
+    }
+
+    const created = await createGoal(db, {
+      companyId,
+      projectId: level === "project" ? projectId : agentLevelProjectId,
+      parentGoalId,
+      ownerAgentId,
+      level,
+      title: g.title,
+      description: g.description?.trim() || undefined
+    });
+    goalSlugToId.set(slug, created.id);
+    const st = g.status?.trim();
+    if (st && st !== "draft") {
+      await updateGoal(db, {
+        companyId,
+        id: created.id,
+        status: st
+      });
+    }
+  }
+
   const routines = doc.routines ?? {};
   for (const [, r] of Object.entries(routines)) {
     const projectId = projectSlugToId.get(r.projectSlug);
@@ -266,7 +399,7 @@ export async function importCompanyFromZipBuffer(db: BopoDb, buffer: Buffer): Pr
     for (const t of r.triggers) {
       await addWorkLoopTrigger(db, {
         companyId,
-        workLoopId: loop.id,
+        routineId: loop.id,
         cronExpression: t.cronExpression,
         timezone: t.timezone?.trim() || "UTC",
         label: t.label ?? null,
@@ -274,6 +407,52 @@ export async function importCompanyFromZipBuffer(db: BopoDb, buffer: Buffer): Pr
       });
     }
   }
+}
+
+export function assertManifestHasCeoAgent(doc: BopoExportDoc): void {
+  const hasCeo = Object.values(doc.agents).some((a) => (a.roleKey ?? "").trim().toLowerCase() === "ceo");
+  if (!hasCeo) {
+    throw new CompanyFileImportError("Company package must include an agent with roleKey 'ceo'.");
+  }
+}
+
+export function summarizeCompanyPackageForPreview(parsed: ParsedCompanyPackage): {
+  companyName: string;
+  counts: {
+    projects: number;
+    agents: number;
+    goals: number;
+    routines: number;
+    skillFiles: number;
+  };
+  hasCeo: boolean;
+} {
+  const doc = parsed.doc;
+  const skillFiles = Object.keys(parsed.entries).filter((k) => k.startsWith("skills/") && !k.endsWith("/")).length;
+  const hasCeo = Object.values(doc.agents).some((a) => (a.roleKey ?? "").trim().toLowerCase() === "ceo");
+  return {
+    companyName: doc.company.name,
+    counts: {
+      projects: Object.keys(doc.projects).length,
+      agents: Object.keys(doc.agents).length,
+      goals: Object.keys(doc.goals ?? {}).length,
+      routines: Object.keys(doc.routines ?? {}).length,
+      skillFiles
+    },
+    hasCeo
+  };
+}
 
+export async function importCompanyFromZipBuffer(db: BopoDb, buffer: Buffer): Promise<{ companyId: string; name: string }> {
+  const parsed = parseCompanyZipBuffer(buffer);
+  const doc = parsed.doc;
+
+  const created = await createCompany(db, {
+    name: doc.company.name,
+    mission: doc.company.mission ?? null
+  });
+  const companyId = created.id;
+  await ensureCompanyBuiltinTemplateDefaults(db, companyId);
+  await seedOperationalDataFromPackage(db, companyId, parsed);
   return { companyId, name: doc.company.name };
 }

package/src/services/governance-service.ts

@@ -4,6 +4,8 @@ import {
   AGENT_ROLE_LABELS,
   AgentCreateRequestSchema,
   AgentRoleKeySchema,
+  PluginInstallSourceTypeSchema,
+  PluginManifestV2Schema,
   TemplateManifestDefault,
   TemplateManifestSchema
 } from "bopodev-contracts";
@@ -13,6 +15,7 @@ import {
   approvalRequests,
   agents,
   appendAuditEvent,
+  appendPluginInstall,
   createAgent,
   createGoal,
   createIssue,
@@ -28,6 +31,7 @@ import {
   projects,
   eq,
   updateProjectWorkspace,
+  markPluginInstallsSuperseded,
   updatePluginConfig
 } from "bopodev-db";
 import {
@@ -44,6 +48,8 @@ import {
 } from "../lib/instance-paths";
 import { assertRuntimeCwdForCompany, hasText, resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
 import { appendDurableFact } from "./memory-file-service";
+import { writePackagedPluginManifestToFilesystem } from "./plugin-manifest-loader";
+import { registerPluginManifest } from "./plugin-runtime";
 import { applyTemplateManifest } from "./template-apply-service";
 
 const approvalGatedActions = new Set([
@@ -97,7 +103,14 @@ const grantPluginCapabilitiesPayloadSchema = z.object({
   enabled: z.boolean().optional(),
   priority: z.number().int().min(0).max(1000).optional(),
   grantedCapabilities: z.array(z.string().min(1)).default([]),
-  config: z.record(z.string(), z.unknown()).default({})
+  capabilityNamespaces: z.array(z.string().min(1)).default([]),
+  config: z.record(z.string(), z.unknown()).default({}),
+  sourceType: PluginInstallSourceTypeSchema.optional(),
+  sourceRef: z.string().optional(),
+  integrity: z.string().optional(),
+  buildHash: z.string().optional(),
+  manifestJson: z.string().optional(),
+  install: z.boolean().default(true)
 });
 const applyTemplatePayloadSchema = z.object({
   templateId: z.string().min(1),
@@ -311,6 +324,8 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
       heartbeatCron: parsed.data.heartbeatCron,
       monthlyBudgetUsd: parsed.data.monthlyBudgetUsd.toFixed(4),
       canHireAgents: parsed.data.canHireAgents,
+      canAssignAgents: parsed.data.canAssignAgents,
+      canCreateIssues: parsed.data.canCreateIssues,
       ...runtimeConfigToDb(runtimeConfig),
       initialState: runtimeConfigToStateBlobPatch(runtimeConfig)
     });
@@ -556,13 +571,52 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
     if (!parsed.success) {
       throw new GovernanceError("Approval payload for plugin capability grant is invalid.");
     }
+    if (parsed.data.manifestJson) {
+      let rawManifest: unknown;
+      try {
+        rawManifest = JSON.parse(parsed.data.manifestJson);
+      } catch {
+        throw new GovernanceError("Plugin install manifest JSON is invalid.");
+      }
+      const manifestParsed = PluginManifestV2Schema.safeParse(rawManifest);
+      if (!manifestParsed.success) {
+        throw new GovernanceError("Plugin install manifest payload failed validation.");
+      }
+      await writePackagedPluginManifestToFilesystem(manifestParsed.data, {
+        sourceType: parsed.data.sourceType ?? "registry",
+        sourceRef: parsed.data.sourceRef,
+        integrity: parsed.data.integrity,
+        buildHash: parsed.data.buildHash
+      });
+      await registerPluginManifest(db, manifestParsed.data);
+      await markPluginInstallsSuperseded(db, {
+        companyId,
+        pluginId: parsed.data.pluginId
+      });
+      await appendPluginInstall(db, {
+        companyId,
+        pluginId: parsed.data.pluginId,
+        pluginVersion: manifestParsed.data.version,
+        sourceType: parsed.data.sourceType ?? "registry",
+        sourceRef: parsed.data.sourceRef ?? null,
+        integrity: parsed.data.integrity ?? null,
+        buildHash: parsed.data.buildHash ?? null,
+        artifactPath: manifestParsed.data.install?.artifactPath ?? null,
+        manifestJson: JSON.stringify(manifestParsed.data),
+        status: "active"
+      });
+    }
+    const configWithNamespaces = {
+      ...parsed.data.config,
+      _grantedCapabilityNamespaces: parsed.data.capabilityNamespaces
+    };
     await updatePluginConfig(db, {
       companyId,
       pluginId: parsed.data.pluginId,
       enabled: parsed.data.enabled,
       priority: parsed.data.priority,
       grantedCapabilitiesJson: JSON.stringify(parsed.data.grantedCapabilities),
-      configJson: JSON.stringify(parsed.data.config)
+      configJson: JSON.stringify(configWithNamespaces)
     });
     return {
       applied: true,
@@ -572,7 +626,8 @@ async function applyApprovalAction(db: BopoDb, companyId: string, action: string
         pluginId: parsed.data.pluginId,
         enabled: parsed.data.enabled ?? null,
         priority: parsed.data.priority ?? null,
-        grantedCapabilities: parsed.data.grantedCapabilities
+        grantedCapabilities: parsed.data.grantedCapabilities,
+        capabilityNamespaces: parsed.data.capabilityNamespaces
       }
     };
   }

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

@@ -723,6 +723,8 @@ export async function runHeartbeatForAgent(
         agentId: agent.id,
         heartbeatRunId: runId,
         canHireAgents: agent.canHireAgents,
+        canAssignAgents: agent.canAssignAgents ?? true,
+        canCreateIssues: agent.canCreateIssues ?? true,
         wakeContext: options?.wakeContext
       }),
       ...(linkedMaterialized.root ? { BOPODEV_MATERIALIZED_LINKED_SKILLS_ROOT: linkedMaterialized.root } : {})
@@ -4077,6 +4079,8 @@ function buildHeartbeatRuntimeEnv(input: {
   agentId: string;
   heartbeatRunId: string;
   canHireAgents: boolean;
+  canAssignAgents: boolean;
+  canCreateIssues: boolean;
   wakeContext?: HeartbeatWakeContext;
 }) {
   const companyWorkspaceRoot = resolveCompanyWorkspaceRootPath(input.companyId);
@@ -4085,6 +4089,7 @@ function buildHeartbeatRuntimeEnv(input: {
   const apiBaseUrl = resolveControlPlaneApiBaseUrl();
   // agents:write is required for PUT /agents/:self (bootstrapPrompt, runtimeConfig). Route handlers
   // still forbid agents from updating other agents' rows and from POST /agents unless canHireAgents.
+  // Issue create/assignee changes for agent actors are gated by canCreateIssues / canAssignAgents (see issues routes).
   const actorPermissions = ["issues:write", "agents:write"].join(",");
   const actorHeaders = JSON.stringify({
     "x-company-id": input.companyId,
@@ -4115,6 +4120,8 @@ function buildHeartbeatRuntimeEnv(input: {
     BOPODEV_REQUEST_HEADERS_JSON: actorHeaders,
     BOPODEV_REQUEST_APPROVAL_DEFAULT: "true",
     BOPODEV_CAN_HIRE_AGENTS: input.canHireAgents ? "true" : "false",
+    BOPODEV_CAN_ASSIGN_AGENTS: input.canAssignAgents ? "true" : "false",
+    BOPODEV_CAN_CREATE_ISSUES: input.canCreateIssues ? "true" : "false",
     ...(input.wakeContext?.reason ? { BOPODEV_WAKE_REASON: input.wakeContext.reason } : {}),
     ...(input.wakeContext?.commentId ? { BOPODEV_WAKE_COMMENT_ID: input.wakeContext.commentId } : {}),
     ...(input.wakeContext?.issueIds?.length ? { BOPODEV_LINKED_ISSUE_IDS: input.wakeContext.issueIds.join(",") } : {}),

package/src/services/plugin-artifact-installer.ts

@@ -0,0 +1,115 @@
+import { createHash, randomUUID } from "node:crypto";
+import { mkdtemp, mkdir, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { PluginManifestV2Schema, type PluginManifestV2 } from "bopodev-contracts";
+import { buildPluginArtifactInstallDir, ensurePluginArtifactsDir, sanitizeArtifactSegment } from "./plugin-artifact-store";
+
+const execFileAsync = promisify(execFile);
+
+type NpmPackResultRow = {
+  filename: string;
+  integrity?: string;
+};
+
+export async function installPluginArtifactFromNpm(input: { packageName: string; version?: string }) {
+  const packageRef = input.version?.trim() ? `${input.packageName}@${input.version.trim()}` : input.packageName.trim();
+  if (!packageRef) {
+    throw new Error("packageName is required.");
+  }
+  const artifactsRoot = await ensurePluginArtifactsDir();
+  const tempRoot = await mkdtemp(resolve(tmpdir(), "bopo-plugin-pack-"));
+  try {
+    const { stdout } = await execFileAsync("npm", ["pack", packageRef, "--json"], {
+      cwd: tempRoot,
+      maxBuffer: 5 * 1024 * 1024
+    });
+    const parsed = JSON.parse(stdout.trim()) as NpmPackResultRow[] | NpmPackResultRow;
+    const row = Array.isArray(parsed) ? parsed[0] : parsed;
+    if (!row?.filename) {
+      throw new Error("npm pack did not return a filename.");
+    }
+    const tarballPath = resolve(tempRoot, row.filename);
+    const tarball = await readFile(tarballPath);
+    const buildHash = createHash("sha256").update(tarball).digest("hex");
+    const installDir = buildPluginArtifactInstallDir({
+      pluginId: sanitizeArtifactSegment(input.packageName),
+      version: input.version?.trim() || "latest",
+      buildHash
+    });
+    await mkdir(installDir, { recursive: true });
+    await execFileAsync("tar", ["-xzf", tarballPath, "-C", installDir], {
+      maxBuffer: 5 * 1024 * 1024
+    });
+    const packageRoot = resolve(installDir, "package");
+    const packageJsonRaw = await readFile(resolve(packageRoot, "package.json"), "utf8");
+    const packageJsonParsed = JSON.parse(packageJsonRaw) as Record<string, unknown>;
+    const manifestPath = resolveManifestPath(packageRoot, packageJsonParsed);
+    const manifestRaw = await readFile(manifestPath, "utf8");
+    const manifestParsed = PluginManifestV2Schema.parse(JSON.parse(manifestRaw) as unknown);
+    const normalizedManifest = normalizeManifestEntrypoints(packageRoot, manifestParsed, {
+      packageName: input.packageName.trim(),
+      packageRef,
+      integrity: row.integrity,
+      buildHash,
+      artifactPath: packageRoot
+    });
+    return {
+      manifest: normalizedManifest,
+      packageRoot,
+      packageRef,
+      buildHash,
+      integrity: row.integrity
+    };
+  } finally {
+    await rm(tempRoot, { recursive: true, force: true });
+    await mkdir(artifactsRoot, { recursive: true });
+  }
+}
+
+function resolveManifestPath(packageRoot: string, packageJson: Record<string, unknown>) {
+  const bopo = packageJson.bopo;
+  if (typeof bopo === "object" && bopo !== null) {
+    const maybe = (bopo as Record<string, unknown>).pluginManifest;
+    if (typeof maybe === "string" && maybe.trim()) {
+      return resolve(packageRoot, maybe);
+    }
+  }
+  const legacy = packageJson.bopoPluginManifest;
+  if (typeof legacy === "string" && legacy.trim()) {
+    return resolve(packageRoot, legacy);
+  }
+  return resolve(packageRoot, "plugin.json");
+}
+
+function normalizeManifestEntrypoints(
+  packageRoot: string,
+  manifest: PluginManifestV2,
+  input: {
+    packageName: string;
+    packageRef: string;
+    integrity?: string;
+    buildHash: string;
+    artifactPath: string;
+  }
+): PluginManifestV2 {
+  return {
+    ...manifest,
+    apiVersion: "2",
+    entrypoints: {
+      worker: resolve(packageRoot, manifest.entrypoints.worker),
+      ui: manifest.entrypoints.ui ? resolve(packageRoot, manifest.entrypoints.ui) : undefined
+    },
+    install: {
+      sourceType: "registry",
+      sourceRef: input.packageRef,
+      integrity: input.integrity,
+      buildHash: input.buildHash || randomUUID(),
+      installedAt: new Date().toISOString(),
+      artifactPath: input.artifactPath,
+      packageName: input.packageName
+    }
+  };
+}

package/src/services/plugin-artifact-store.ts

@@ -0,0 +1,28 @@
+import { mkdir, rm } from "node:fs/promises";
+import { resolve } from "node:path";
+
+export function resolvePluginArtifactsDir() {
+  return process.env.BOPO_PLUGIN_ARTIFACTS_DIR || resolve(process.cwd(), ".bopo", "plugin-artifacts");
+}
+
+export async function ensurePluginArtifactsDir() {
+  const dir = resolvePluginArtifactsDir();
+  await mkdir(dir, { recursive: true });
+  return dir;
+}
+
+export function sanitizeArtifactSegment(value: string) {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "-");
+}
+
+export function buildPluginArtifactInstallDir(input: { pluginId: string; version: string; buildHash: string }) {
+  const root = resolvePluginArtifactsDir();
+  const plugin = sanitizeArtifactSegment(input.pluginId);
+  const version = sanitizeArtifactSegment(input.version);
+  const hash = sanitizeArtifactSegment(input.buildHash.slice(0, 16));
+  return resolve(root, plugin, `${version}-${hash}`);
+}
+
+export async function removePluginArtifactInstallDir(path: string) {
+  await rm(path, { recursive: true, force: true });
+}

package/src/services/plugin-capability-policy.ts

@@ -0,0 +1,31 @@
+import { PLUGIN_CAPABILITY_RISK, type PluginCapabilityNamespace } from "bopodev-contracts";
+
+const LEGACY_HIGH_RISK = new Set(["network", "queue_publish", "issue_write", "write_memory"]);
+
+export type PluginTrustLevel = "dev_local" | "verified" | "restricted";
+
+function resolveTrustLevel(): PluginTrustLevel {
+  const raw = process.env.BOPO_PLUGIN_TRUST_LEVEL;
+  if (raw === "dev_local" || raw === "verified" || raw === "restricted") {
+    return raw;
+  }
+  return "verified";
+}
+
+export function legacyCapabilitiesRequireApproval(capabilities: string[]) {
+  return capabilities.some((cap) => LEGACY_HIGH_RISK.has(cap));
+}
+
+export function namespacedCapabilitiesRequireApproval(capabilities: PluginCapabilityNamespace[]) {
+  const trustLevel = resolveTrustLevel();
+  return capabilities.some((cap) => {
+    const risk = PLUGIN_CAPABILITY_RISK[cap];
+    if (risk === "restricted") {
+      return true;
+    }
+    if (risk === "elevated") {
+      return trustLevel !== "dev_local";
+    }
+    return false;
+  });
+}