bopodev-api 0.1.34 → 0.1.36

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;
+  });
+}

package/src/services/plugin-jobs-service.ts

@@ -0,0 +1,74 @@
+import type { PluginManifestV2 } from "bopodev-contracts";
+import { PluginInvocationResultSchema, PluginManifestV2Schema } from "bopodev-contracts";
+import type { BopoDb } from "bopodev-db";
+import { appendPluginRun, listCompanyPluginConfigs } from "bopodev-db";
+import { pluginWorkerHost } from "./plugin-worker-host";
+
+const lastJobRun = new Map<string, number>();
+
+function shouldRunJob(companyId: string, pluginId: string, jobKey: string) {
+  const key = `${companyId}:${pluginId}:${jobKey}`;
+  const now = Date.now();
+  const previous = lastJobRun.get(key) ?? 0;
+  if (now - previous < 55_000) {
+    return false;
+  }
+  lastJobRun.set(key, now);
+  return true;
+}
+
+export async function runPluginJobSweep(db: BopoDb, companyId: string) {
+  const rows = await listCompanyPluginConfigs(db, companyId);
+  for (const row of rows) {
+    if (!row.enabled) continue;
+    const manifest = parseManifest(row.manifestJson);
+    if (!manifest || manifest.jobs.length === 0) continue;
+    for (const job of manifest.jobs) {
+      if (!shouldRunJob(companyId, row.pluginId, job.jobKey)) continue;
+      const startedAt = Date.now();
+      try {
+        const result = await pluginWorkerHost.invoke(manifest, {
+          method: "plugin.job",
+          params: {
+            companyId,
+            pluginId: row.pluginId,
+            jobKey: job.jobKey,
+            schedule: job.schedule
+          }
+        });
+        const validated = PluginInvocationResultSchema.parse(result);
+        await appendPluginRun(db, {
+          companyId,
+          runId: null,
+          pluginId: row.pluginId,
+          hook: `job:${job.jobKey}`,
+          status: validated.status,
+          durationMs: Date.now() - startedAt,
+          diagnosticsJson: JSON.stringify(validated.diagnostics ?? {}),
+          error: validated.status === "failed" || validated.status === "blocked" ? validated.summary : null
+        });
+      } catch (error) {
+        await appendPluginRun(db, {
+          companyId,
+          runId: null,
+          pluginId: row.pluginId,
+          hook: `job:${job.jobKey}`,
+          status: "failed",
+          durationMs: Date.now() - startedAt,
+          error: String(error)
+        });
+      }
+    }
+  }
+}
+
+function parseManifest(value: string | null | undefined): PluginManifestV2 | null {
+  if (!value) return null;
+  try {
+    const parsed = JSON.parse(value) as unknown;
+    const result = PluginManifestV2Schema.safeParse(parsed);
+    return result.success ? result.data : null;
+  } catch {
+    return null;
+  }
+}

package/src/services/plugin-manifest-loader.ts

@@ -1,6 +1,7 @@
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { existsSync, readdirSync } from "node:fs";
 import { resolve } from "node:path";
-import { PluginManifestSchema, type PluginManifest } from "bopodev-contracts";
+import { PluginManifestSchema, PluginManifestV2Schema, type PluginManifest } from "bopodev-contracts";
 
 export type FilesystemPluginManifestLoadResult = {
   manifests: PluginManifest[];
@@ -29,7 +30,7 @@ export async function loadFilesystemPluginManifests(): Promise<FilesystemPluginM
     }
     try {
       const parsed = JSON.parse(raw) as unknown;
-      const manifest = PluginManifestSchema.parse(parsed);
+      const manifest = normalizeFilesystemManifest(manifestPath, PluginManifestSchema.parse(parsed));
       manifests.push(manifest);
     } catch (error) {
       warnings.push(`Invalid plugin manifest at '${manifestPath}': ${String(error)}`);
@@ -40,7 +41,24 @@ export async function loadFilesystemPluginManifests(): Promise<FilesystemPluginM
 }
 
 export function resolvePluginManifestsDir() {
-  return process.env.BOPO_PLUGIN_MANIFESTS_DIR || resolve(process.cwd(), "plugins");
+  if (process.env.BOPO_PLUGIN_MANIFESTS_DIR) {
+    return process.env.BOPO_PLUGIN_MANIFESTS_DIR;
+  }
+  const localPlugins = resolve(process.cwd(), "plugins");
+  if (directoryHasPluginManifests(localPlugins)) {
+    return localPlugins;
+  }
+  const repoRootPlugins = resolve(process.cwd(), "..", "..", "plugins");
+  if (directoryHasPluginManifests(repoRootPlugins)) {
+    return repoRootPlugins;
+  }
+  if (existsSync(localPlugins)) {
+    return localPlugins;
+  }
+  if (existsSync(repoRootPlugins)) {
+    return repoRootPlugins;
+  }
+  return localPlugins;
 }
 
 export async function writePluginManifestToFilesystem(manifest: PluginManifest) {
@@ -53,6 +71,29 @@ export async function writePluginManifestToFilesystem(manifest: PluginManifest)
   return manifestPath;
 }
 
+export async function writePackagedPluginManifestToFilesystem(
+  manifest: PluginManifest,
+  input: {
+    sourceType: "builtin" | "registry" | "local_path" | "archive_url";
+    sourceRef?: string;
+    integrity?: string;
+    buildHash?: string;
+  }
+) {
+  const nextManifest = {
+    ...manifest,
+    apiVersion: "2",
+    install: {
+      sourceType: input.sourceType,
+      sourceRef: input.sourceRef,
+      integrity: input.integrity,
+      buildHash: input.buildHash,
+      installedAt: new Date().toISOString()
+    }
+  } as PluginManifest;
+  return writePluginManifestToFilesystem(nextManifest);
+}
+
 export async function deletePluginManifestFromFilesystem(pluginId: string) {
   const pluginRoot = resolvePluginManifestsDir();
   const safeDirName = sanitizePluginDirectoryName(pluginId);
@@ -63,3 +104,37 @@ export async function deletePluginManifestFromFilesystem(pluginId: string) {
 function sanitizePluginDirectoryName(pluginId: string) {
   return pluginId.replace(/[^a-zA-Z0-9._-]/g, "-");
 }
+
+function directoryHasPluginManifests(dir: string) {
+  if (!existsSync(dir)) {
+    return false;
+  }
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    return entries.some((entry) => entry.isDirectory() && existsSync(resolve(dir, entry.name, "plugin.json")));
+  } catch {
+    return false;
+  }
+}
+
+function normalizeFilesystemManifest(manifestPath: string, manifest: PluginManifest): PluginManifest {
+  const pluginDir = resolve(manifestPath, "..");
+  const parsedV2 = PluginManifestV2Schema.safeParse(manifest);
+  if (!parsedV2.success) {
+    return manifest;
+  }
+  const v2 = parsedV2.data;
+  const worker = resolve(pluginDir, v2.entrypoints.worker);
+  const ui = v2.entrypoints.ui ? resolve(pluginDir, v2.entrypoints.ui) : undefined;
+  return {
+    ...v2,
+    runtime: {
+      ...v2.runtime,
+      entrypoint: v2.runtime.type === "stdio" || v2.runtime.type === "http" ? resolve(pluginDir, v2.runtime.entrypoint) : v2.runtime.entrypoint
+    },
+    entrypoints: {
+      worker,
+      ui
+    }
+  };
+}

package/src/services/plugin-rpc.ts

@@ -0,0 +1,102 @@
+import { EventEmitter } from "node:events";
+
+export type PluginRpcRequest = {
+  jsonrpc: "2.0";
+  id: string;
+  method: string;
+  params?: unknown;
+};
+
+export type PluginRpcSuccess = {
+  jsonrpc: "2.0";
+  id: string;
+  result: unknown;
+};
+
+export type PluginRpcFailure = {
+  jsonrpc: "2.0";
+  id: string;
+  error: {
+    code: number;
+    message: string;
+    data?: unknown;
+  };
+};
+
+export type PluginRpcResponse = PluginRpcSuccess | PluginRpcFailure;
+
+export function createPluginRpcRequest(method: string, params: unknown, id: string): PluginRpcRequest {
+  return {
+    jsonrpc: "2.0",
+    id,
+    method,
+    params
+  };
+}
+
+export function encodePluginRpcMessage(value: PluginRpcRequest | PluginRpcResponse): string {
+  return `${JSON.stringify(value)}\n`;
+}
+
+export function decodePluginRpcMessage(line: string): PluginRpcResponse | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(line) as unknown;
+  } catch {
+    return null;
+  }
+  if (!parsed || typeof parsed !== "object") {
+    return null;
+  }
+  const obj = parsed as Record<string, unknown>;
+  if (obj.jsonrpc !== "2.0" || typeof obj.id !== "string") {
+    return null;
+  }
+  if ("result" in obj) {
+    return {
+      jsonrpc: "2.0",
+      id: obj.id,
+      result: obj.result
+    };
+  }
+  if ("error" in obj && obj.error && typeof obj.error === "object") {
+    const err = obj.error as Record<string, unknown>;
+    if (typeof err.code === "number" && typeof err.message === "string") {
+      return {
+        jsonrpc: "2.0",
+        id: obj.id,
+        error: {
+          code: err.code,
+          message: err.message,
+          data: err.data
+        }
+      };
+    }
+  }
+  return null;
+}
+
+export class PluginRpcLineBuffer extends EventEmitter<{
+  message: [PluginRpcResponse];
+}> {
+  private buffer = "";
+
+  push(chunk: string) {
+    this.buffer += chunk;
+    while (true) {
+      const idx = this.buffer.indexOf("\n");
+      if (idx === -1) {
+        break;
+      }
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (!line) {
+        continue;
+      }
+      const parsed = decodePluginRpcMessage(line);
+      if (parsed) {
+        this.emit("message", parsed);
+      }
+    }
+  }
+}