bopodev-api 0.1.25 → 0.1.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bopodev-api",
-  "version": "0.1.25",
+  "version": "0.1.26",
   "license": "MIT",
   "type": "module",
   "files": [
@@ -17,9 +17,9 @@
     "nanoid": "^5.1.5",
     "ws": "^8.19.0",
     "zod": "^4.1.5",
-    "bopodev-contracts": "0.1.25",
-    "bopodev-db": "0.1.25",
-    "bopodev-agent-sdk": "0.1.25"
+    "bopodev-db": "0.1.26",
+    "bopodev-agent-sdk": "0.1.26",
+    "bopodev-contracts": "0.1.26"
   },
   "devDependencies": {
     "@types/cors": "^2.8.19",

package/src/routes/governance.ts

@@ -1,6 +1,7 @@
 import { Router } from "express";
 import { z } from "zod";
 import {
+  addIssueComment,
   appendAuditEvent,
   clearApprovalInboxDismissed,
   countPendingApprovalRequests,
@@ -209,6 +210,36 @@ export function createGovernanceRouter(ctx: AppContext) {
       if (approval.requestedByAgentId) {
         await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, approval.requestedByAgentId);
       }
+      if (parsed.data.status === "approved" && resolution.action === "hire_agent" && resolution.execution.applied) {
+        const hireContext = parseHireApprovalCommentContext(approval.payloadJson);
+        if (hireContext.issueIds.length > 0) {
+          const commentBody = buildHireApprovalIssueComment(hireContext.roleLabel);
+          try {
+            for (const issueId of hireContext.issueIds) {
+              await addIssueComment(ctx.db, {
+                companyId: req.companyId!,
+                issueId,
+                body: commentBody,
+                authorType: auditActor.actorType === "agent" ? "agent" : "human",
+                authorId: auditActor.actorId
+              });
+            }
+          } catch (error) {
+            await appendAuditEvent(ctx.db, {
+              companyId: req.companyId!,
+              actorType: "system",
+              actorId: null,
+              eventType: "governance.hire_approval_comment_failed",
+              entityType: "approval_request",
+              entityId: approval.id,
+              payload: {
+                error: String(error),
+                issueIds: hireContext.issueIds
+              }
+            });
+          }
+        }
+      }
     }
 
     if (resolution.execution.entityType === "agent" && resolution.execution.entityId) {
@@ -231,11 +262,58 @@ function resolveAuditActor(actor: { type: "board" | "member" | "agent"; id: stri
   return { actorType: "human" as const, actorId: actor.id };
 }
 
-function parsePayload(payloadJson: string) {
+function parsePayload(payloadJson: string): Record<string, unknown> {
   try {
     const parsed = JSON.parse(payloadJson) as unknown;
-    return typeof parsed === "object" && parsed !== null ? parsed : {};
+    return typeof parsed === "object" && parsed !== null ? (parsed as Record<string, unknown>) : {};
   } catch {
     return {};
   }
 }
+
+function parseHireApprovalCommentContext(payloadJson: string) {
+  const payload = parsePayload(payloadJson);
+  const issueIds = normalizeSourceIssueIds(
+    typeof payload.sourceIssueId === "string" ? payload.sourceIssueId : undefined,
+    Array.isArray(payload.sourceIssueIds) ? payload.sourceIssueIds : undefined
+  );
+  const roleLabel = resolveHireRoleLabel(payload);
+  return { issueIds, roleLabel };
+}
+
+function normalizeSourceIssueIds(sourceIssueId?: string, sourceIssueIds?: unknown[]) {
+  const normalized = new Set<string>();
+  for (const entry of [sourceIssueId, ...(sourceIssueIds ?? [])]) {
+    if (typeof entry !== "string") {
+      continue;
+    }
+    const trimmed = entry.trim();
+    if (trimmed.length > 0) {
+      normalized.add(trimmed);
+    }
+  }
+  return Array.from(normalized);
+}
+
+function resolveHireRoleLabel(payload: Record<string, unknown>) {
+  const title = typeof payload.title === "string" ? payload.title.trim() : "";
+  if (title.length > 0) {
+    return title;
+  }
+  const role = typeof payload.role === "string" ? payload.role.trim() : "";
+  if (role.length > 0) {
+    return role;
+  }
+  const roleKey = typeof payload.roleKey === "string" ? payload.roleKey.trim() : "";
+  if (roleKey.length > 0) {
+    return roleKey.replace(/_/g, " ");
+  }
+  return null;
+}
+
+function buildHireApprovalIssueComment(roleLabel: string | null) {
+  if (roleLabel) {
+    return `Approved hiring of ${roleLabel}.`;
+  }
+  return "Approved hiring request.";
+}

package/src/routes/observability.ts

@@ -1,4 +1,6 @@
 import { Router } from "express";
+import { readFile, stat } from "node:fs/promises";
+import { basename, isAbsolute, resolve } from "node:path";
 import { z } from "zod";
 import {
   getHeartbeatRun,
@@ -15,6 +17,7 @@ import {
 } from "bopodev-db";
 import type { AppContext } from "../context";
 import { sendError, sendOk } from "../http";
+import { isInsidePath, resolveCompanyWorkspaceRootPath } from "../lib/instance-paths";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
 import { listAgentMemoryFiles, loadAgentMemoryContext, readAgentMemoryFile } from "../services/memory-file-service";
@@ -113,10 +116,12 @@ export function createObservabilityRouter(ctx: AppContext) {
         .filter((run) => (agentFilter ? run.agentId === agentFilter : true))
         .map((run) => {
           const details = runDetailsByRunId.get(run.id);
-          const outcome = details?.outcome ?? null;
+          const report = toRecord(details?.report);
+          const outcome = details?.outcome ?? report?.outcome ?? null;
           return {
-            ...serializeRunRow(run, outcome),
-            outcome
+            ...serializeRunRow(run, details),
+            outcome,
+            report: report ?? null
           };
         })
     );
@@ -138,7 +143,7 @@ export function createObservabilityRouter(ctx: AppContext) {
     const trace = toRecord(details?.trace);
     const traceTranscript = Array.isArray(trace?.transcript) ? trace.transcript : [];
     return sendOk(res, {
-      run: serializeRunRow(run, details?.outcome ?? null),
+      run: serializeRunRow(run, details),
       details,
       transcript: {
         hasPersistedMessages: transcriptResult.items.length > 0,
@@ -148,6 +153,46 @@ export function createObservabilityRouter(ctx: AppContext) {
     });
   });
 
+  router.get("/heartbeats/:runId/artifacts/:artifactIndex/download", async (req, res) => {
+    const companyId = req.companyId!;
+    const runId = req.params.runId;
+    const rawArtifactIndex = Number(req.params.artifactIndex);
+    const artifactIndex = Number.isFinite(rawArtifactIndex) ? Math.floor(rawArtifactIndex) : NaN;
+    if (!Number.isInteger(artifactIndex) || artifactIndex < 0) {
+      return sendError(res, "Artifact index must be a non-negative integer.", 422);
+    }
+    const [run, auditRows] = await Promise.all([getHeartbeatRun(ctx.db, companyId, runId), listAuditEvents(ctx.db, companyId, 500)]);
+    if (!run) {
+      return sendError(res, "Run not found", 404);
+    }
+    const details = buildRunDetailsMap(auditRows).get(runId) ?? null;
+    const report = toRecord(details?.report);
+    const artifacts = Array.isArray(report?.artifacts)
+      ? report.artifacts.filter((entry) => typeof entry === "object" && entry !== null)
+      : [];
+    const artifact = (artifacts[artifactIndex] ?? null) as Record<string, unknown> | null;
+    if (!artifact) {
+      return sendError(res, "Artifact not found.", 404);
+    }
+    const resolvedPath = resolveRunArtifactAbsolutePath(companyId, artifact);
+    if (!resolvedPath) {
+      return sendError(res, "Artifact path is invalid.", 422);
+    }
+    let stats: Awaited<ReturnType<typeof stat>>;
+    try {
+      stats = await stat(resolvedPath);
+    } catch {
+      return sendError(res, "Artifact not found on disk.", 404);
+    }
+    if (!stats.isFile()) {
+      return sendError(res, "Artifact is not a file.", 422);
+    }
+    const buffer = await readFile(resolvedPath);
+    res.setHeader("content-type", "application/octet-stream");
+    res.setHeader("content-disposition", `inline; filename="${encodeURIComponent(basename(resolvedPath))}"`);
+    return res.send(buffer);
+  });
+
   router.get("/heartbeats/:runId/messages", async (req, res) => {
     const companyId = req.companyId!;
     const runId = req.params.runId;
@@ -359,6 +404,85 @@ function toRecord(value: unknown) {
   return typeof value === "object" && value !== null ? (value as Record<string, unknown>) : null;
 }
 
+function resolveRunArtifactAbsolutePath(companyId: string, artifact: Record<string, unknown>) {
+  const companyWorkspaceRoot = resolveCompanyWorkspaceRootPath(companyId);
+  const absolutePathRaw = normalizeAbsoluteArtifactPath(
+    typeof artifact.absolutePath === "string" ? artifact.absolutePath.trim() : ""
+  );
+  const relativePathRaw = normalizeWorkspaceRelativeArtifactPath(
+    typeof artifact.relativePath === "string"
+      ? artifact.relativePath.trim()
+      : typeof artifact.path === "string"
+        ? artifact.path.trim()
+        : "",
+    companyId
+  );
+  const candidate = relativePathRaw
+    ? resolve(companyWorkspaceRoot, relativePathRaw)
+    : absolutePathRaw
+      ? absolutePathRaw
+      : "";
+  if (!candidate) {
+    return null;
+  }
+  const resolved = isAbsolute(candidate) ? resolve(candidate) : resolve(companyWorkspaceRoot, candidate);
+  if (!isInsidePath(companyWorkspaceRoot, resolved)) {
+    return null;
+  }
+  return resolved;
+}
+
+function normalizeAbsoluteArtifactPath(value: string) {
+  const trimmed = value.trim();
+  if (!trimmed || !isAbsolute(trimmed)) {
+    return "";
+  }
+  return resolve(trimmed);
+}
+
+function normalizeWorkspaceRelativeArtifactPath(value: string, companyId: string) {
+  const trimmed = value.trim();
+  if (!trimmed) {
+    return "";
+  }
+  const unixSeparated = trimmed.replace(/\\/g, "/");
+  if (isAbsolute(unixSeparated)) {
+    return "";
+  }
+  const parts: string[] = [];
+  for (const part of unixSeparated.split("/")) {
+    if (!part || part === ".") {
+      continue;
+    }
+    if (part === "..") {
+      if (parts.length > 0 && parts[parts.length - 1] !== "..") {
+        parts.pop();
+      } else {
+        parts.push(part);
+      }
+      continue;
+    }
+    parts.push(part);
+  }
+  const normalized = parts.join("/");
+  if (!normalized) {
+    return "";
+  }
+  const workspaceScopedMatch = normalized.match(/(?:^|\/)workspace\/([^/]+)\/(.+)$/);
+  if (!workspaceScopedMatch) {
+    return normalized;
+  }
+  const scopedCompanyId = workspaceScopedMatch[1];
+  const scopedRelativePath = workspaceScopedMatch[2];
+  if (!scopedCompanyId || !scopedRelativePath) {
+    return "";
+  }
+  if (scopedCompanyId !== companyId) {
+    return "";
+  }
+  return scopedRelativePath;
+}
+
 function serializeRunRow(
   run: {
   id: string;
@@ -369,14 +493,27 @@ function serializeRunRow(
   finishedAt: Date | null;
   message: string | null;
   },
-  outcome: unknown
+  details: Record<string, unknown> | null | undefined
 ) {
-  const runType = resolveRunType(run, outcome);
+  const runType = resolveRunType(run, details);
+  const report = toRecord(details?.report);
+  const publicStatusRaw = typeof report?.finalStatus === "string" ? report.finalStatus : null;
+  const publicStatus =
+    publicStatusRaw === "completed" || publicStatusRaw === "failed"
+      ? publicStatusRaw
+      : run.status === "started"
+        ? "started"
+        : run.status === "failed"
+          ? "failed"
+          : run.status === "completed"
+            ? "completed"
+            : "failed";
   return {
     id: run.id,
     companyId: run.companyId,
     agentId: run.agentId,
     status: run.status,
+    publicStatus,
     startedAt: run.startedAt.toISOString(),
     finishedAt: run.finishedAt?.toISOString() ?? null,
     message: run.message ?? null,
@@ -389,14 +526,25 @@ function resolveRunType(
     status: string;
     message: string | null;
   },
-  outcome: unknown
+  details: Record<string, unknown> | null | undefined
 ): "work" | "no_assigned_work" | "budget_skip" | "overlap_skip" | "other_skip" | "failed" | "running" {
   if (run.status === "started") {
     return "running";
   }
-  if (run.status === "failed") {
+  const report = toRecord(details?.report);
+  const completionReason = typeof report?.completionReason === "string" ? report.completionReason : null;
+  if (run.status === "failed" || completionReason === "runtime_error" || completionReason === "provider_unavailable") {
     return "failed";
   }
+  if (completionReason === "no_assigned_work") {
+    return "no_assigned_work";
+  }
+  if (completionReason === "budget_hard_stop") {
+    return "budget_skip";
+  }
+  if (completionReason === "overlap_in_progress") {
+    return "overlap_skip";
+  }
   const normalizedMessage = (run.message ?? "").toLowerCase();
   if (normalizedMessage.includes("already in progress")) {
     return "overlap_skip";
@@ -407,7 +555,7 @@ function resolveRunType(
   if (isNoAssignedWorkMessage(run.message)) {
     return "no_assigned_work";
   }
-  if (isNoAssignedWorkOutcome(outcome)) {
+  if (isNoAssignedWorkOutcome(details?.outcome)) {
     return "no_assigned_work";
   }
   if (run.status === "skipped") {

package/src/scripts/onboard-seed.ts

@@ -26,7 +26,6 @@ import { normalizeRuntimeConfig, runtimeConfigToDb, runtimeConfigToStateBlobPatc
 import {
   normalizeAbsolutePath,
   normalizeCompanyWorkspacePath,
-  resolveAgentFallbackWorkspacePath,
   resolveProjectWorkspacePath
 } from "../lib/instance-paths";
 import { buildDefaultCeoBootstrapPrompt } from "../lib/ceo-bootstrap-prompt";
@@ -305,15 +304,15 @@ async function ensureCeoStartupTask(
       typeof issue.body === "string" &&
       issue.body.includes(CEO_STARTUP_TASK_MARKER)
   );
-  const ceoWorkspaceRoot = resolveAgentFallbackWorkspacePath(input.companyId, input.ceoId);
-  const ceoOperatingFolder = `${ceoWorkspaceRoot}/operating`;
-  const ceoTmpFolder = `${ceoWorkspaceRoot}/tmp`;
+  const companyScopedCeoRoot = `workspace/${input.companyId}/agents/${input.ceoId}`;
+  const ceoOperatingFolder = `${companyScopedCeoRoot}/operating`;
+  const ceoTmpFolder = `${companyScopedCeoRoot}/tmp`;
   const body = [
     CEO_STARTUP_TASK_MARKER,
     "",
     "Stand up your leadership operating baseline before taking on additional delivery work.",
     "",
-    `1. Create your operating folder at \`${ceoOperatingFolder}/\` (system path, outside project workspaces).`,
+    `1. Create your operating folder at \`${ceoOperatingFolder}/\`.`,
     "2. Author these files with your own voice and responsibilities:",
     `   - \`${ceoOperatingFolder}/AGENTS.md\``,
     `   - \`${ceoOperatingFolder}/HEARTBEAT.md\``,
@@ -335,7 +334,7 @@ async function ensureCeoStartupTask(
     "7. Do not use unsupported hire fields such as `adapterType`, `adapterConfig`, or `reportsTo`.",
     "",
     "Safety checks before requesting hire:",
-    "- Do not write operating/system files under any project workspace folder.",
+    `- Keep operating/system files inside \`workspace/${input.companyId}/agents/${input.ceoId}/\` only.`,
     "- 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.",
     "- For control-plane calls, prefer direct header env vars (`BOPODEV_COMPANY_ID`, `BOPODEV_ACTOR_TYPE`, `BOPODEV_ACTOR_ID`, `BOPODEV_ACTOR_COMPANIES`, `BOPODEV_ACTOR_PERMISSIONS`) instead of parsing `BOPODEV_REQUEST_HEADERS_JSON`.",

package/src/services/attention-service.ts

@@ -219,6 +219,7 @@ export async function listBoardAttentionItems(db: BopoDb, companyId: string, act
     const key = `comment:${comment.id}`;
     const body = comment.body.trim().replace(/\s+/g, " ");
     const summaryBody = body.length > 140 ? `${body.slice(0, 137)}...` : body;
+    const conciseUsageLimitSummary = summarizeUsageLimitBoardComment(body);
     items.push(
       withState(
         {
@@ -226,8 +227,8 @@ export async function listBoardAttentionItems(db: BopoDb, companyId: string, act
           category: "board_mentioned_comment",
           severity: "warning",
           requiredActor: "board",
-          title: "Board input requested on issue comment",
-          contextSummary: `${comment.issueTitle}: ${summaryBody}`,
+          title: conciseUsageLimitSummary ? "Provider usage limit reached" : "Board input requested on issue comment",
+          contextSummary: conciseUsageLimitSummary ?? summaryBody,
           actionLabel: "Open issue thread",
           actionHref: `/issues/${comment.issueId}`,
           impactSummary: "The team is waiting for board clarification to continue confidently.",
@@ -250,6 +251,26 @@ export async function listBoardAttentionItems(db: BopoDb, companyId: string, act
   return dedupeItems(items).sort(compareAttentionItems);
 }
 
+function summarizeUsageLimitBoardComment(body: string) {
+  const normalized = body.replace(/\s+/g, " ").trim();
+  if (!normalized) {
+    return null;
+  }
+  const providerMatch = normalized.match(
+    /\b(claude[_\s-]*code|codex|cursor|openai[_\s-]*api|anthropic[_\s-]*api|gemini[_\s-]*cli|opencode)\b(?=.*\busage limit reached\b)/i
+  );
+  if (!providerMatch) {
+    return null;
+  }
+  const providerToken = providerMatch[1];
+  if (!providerToken) {
+    return null;
+  }
+  const rawProvider = providerToken.toLowerCase().replace(/[_-]+/g, " ").replace(/\s+/g, " ").trim();
+  const providerLabel = rawProvider.charAt(0).toUpperCase() + rawProvider.slice(1);
+  return `${providerLabel} usage limit reached.`;
+}
+
 export async function markBoardAttentionSeen(db: BopoDb, companyId: string, actorId: string, itemKey: string) {
   await markAttentionInboxSeen(db, { companyId, actorId, itemKey });
 }

package/src/services/governance-service.ts

@@ -39,7 +39,6 @@ import {
 import { resolveOpencodeRuntimeModel } from "../lib/opencode-model";
 import {
   normalizeCompanyWorkspacePath,
-  resolveAgentFallbackWorkspacePath,
   resolveProjectWorkspacePath
 } from "../lib/instance-paths";
 import { assertRuntimeCwdForCompany, hasText, resolveDefaultRuntimeCwdForCompany } from "../lib/workspace-policy";
@@ -770,14 +769,14 @@ function resolveAgentDisplayTitle(title: string | null | undefined, roleKeyInput
 }
 
 function buildAgentStartupTaskBody(companyId: string, agentId: string) {
-  const agentWorkspaceRoot = resolveAgentFallbackWorkspacePath(companyId, agentId);
-  const agentOperatingFolder = `${agentWorkspaceRoot}/operating`;
+  const companyScopedAgentRoot = `workspace/${companyId}/agents/${agentId}`;
+  const agentOperatingFolder = `${companyScopedAgentRoot}/operating`;
   return [
     AGENT_STARTUP_TASK_MARKER,
     "",
     `Create your operating baseline before starting feature delivery work.`,
     "",
-    `1. Create your operating folder at \`${agentOperatingFolder}/\` (system path, outside project workspaces).`,
+    `1. Create your operating folder at \`${agentOperatingFolder}/\`.`,
     "2. Author these files with your own responsibilities and working style:",
     `   - \`${agentOperatingFolder}/AGENTS.md\``,
     `   - \`${agentOperatingFolder}/HEARTBEAT.md\``,
@@ -787,7 +786,7 @@ function buildAgentStartupTaskBody(companyId: string, agentId: string) {
     "4. Post an issue comment summarizing completed setup artifacts.",
     "",
     "Safety checks:",
-    "- Do not write operating/system files under any project workspace folder.",
+    `- Keep operating files inside \`workspace/${companyId}/agents/${agentId}/\` only.`,
     "- Do not overwrite another agent's operating folder.",
     "- Keep content original to your role and scope."
   ].join("\n");