bopodev-api 0.1.24 → 0.1.26

package/src/routes/agents.ts

@@ -6,7 +6,13 @@ import {
   getAdapterModels,
   runAdapterEnvironmentTest
 } from "bopodev-agent-sdk";
-import { AgentCreateRequestSchema, AgentUpdateRequestSchema } from "bopodev-contracts";
+import {
+  AGENT_ROLE_LABELS,
+  AgentCreateRequestSchema,
+  AgentRoleKeySchema,
+  AgentSchema,
+  AgentUpdateRequestSchema
+} from "bopodev-contracts";
 import {
   appendAuditEvent,
   createAgent,
@@ -18,7 +24,7 @@ import {
   updateAgent
 } from "bopodev-db";
 import type { AppContext } from "../context";
-import { sendError, sendOk } from "../http";
+import { sendError, sendOk, sendOkValidated } from "../http";
 import {
   normalizeRuntimeConfig,
   parseRuntimeConfigFromAgentRow,
@@ -33,6 +39,7 @@ import { assertRuntimeCwdForCompany, hasText, resolveDefaultRuntimeCwdForCompany
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requireBoardRole, requirePermission } from "../middleware/request-actor";
 import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import { publishAttentionSnapshot } from "../realtime/attention";
 import {
   publishOfficeOccupantForAgent,
   publishOfficeOccupantForApproval
@@ -84,6 +91,8 @@ const runtimePreflightSchema = z.object({
 const UPDATE_AGENT_ALLOWED_KEYS = new Set([
   "managerAgentId",
   "role",
+  "roleKey",
+  "title",
   "name",
   "providerType",
   "status",
@@ -129,6 +138,10 @@ function providerRequiresNamedModel(providerType: string) {
   return providerType !== "http" && providerType !== "shell";
 }
 
+const agentResponseSchema = AgentSchema.extend({
+  stateBlob: z.string().optional()
+});
+
 function ensureNamedRuntimeModel(providerType: string, runtimeModel: string | undefined) {
   if (!providerRequiresNamedModel(providerType)) {
     return true;
@@ -142,9 +155,11 @@ export function createAgentsRouter(ctx: AppContext) {
 
   router.get("/", async (req, res) => {
     const rows = await listAgents(ctx.db, req.companyId!);
-    return sendOk(
+    return sendOkValidated(
       res,
-      rows.map((row) => toAgentResponse(row as unknown as Record<string, unknown>))
+      agentResponseSchema.array(),
+      rows.map((row) => toAgentResponse(row as unknown as Record<string, unknown>)),
+      "agents.list"
     );
   });
 
@@ -155,6 +170,7 @@ export function createAgentsRouter(ctx: AppContext) {
         id: row.id,
         name: row.name,
         role: row.role,
+        roleKey: row.roleKey,
         status: row.status,
         canHireAgents: row.canHireAgents
       }))
@@ -170,8 +186,7 @@ export function createAgentsRouter(ctx: AppContext) {
     return sendOk(
       res,
       rows.map((row) => {
-        const normalizedRole = row.role.trim().toLowerCase();
-        const isLeadership = normalizedRole === "ceo" || Boolean(row.canHireAgents);
+        const isLeadership = row.roleKey === "ceo" || Boolean(row.canHireAgents);
         const issues: string[] = [];
         const hasBootstrapPrompt = hasText(row.bootstrapPrompt);
         if (isLeadership && !hasBootstrapPrompt) {
@@ -184,6 +199,7 @@ export function createAgentsRouter(ctx: AppContext) {
           agentId: row.id,
           name: row.name,
           role: row.role,
+          roleKey: row.roleKey,
           providerType: row.providerType,
           canHireAgents: Boolean(row.canHireAgents),
           isLeadership,
@@ -366,7 +382,8 @@ export function createAgentsRouter(ctx: AppContext) {
     const shouldRequestApproval = (parsed.data.requestApproval || req.actor?.type === "agent") && isApprovalRequired("hire_agent");
     if (shouldRequestApproval) {
       const duplicate = await findDuplicateHireRequest(ctx.db, req.companyId!, {
-        role: parsed.data.role,
+        role: parsed.data.role ?? "",
+        roleKey: parsed.data.roleKey ?? null,
         managerAgentId: parsed.data.managerAgentId ?? null
       });
       if (duplicate) {
@@ -397,6 +414,7 @@ export function createAgentsRouter(ctx: AppContext) {
           })
         );
         await publishOfficeOccupantForApproval(ctx.db, ctx.realtimeHub, req.companyId!, approvalId);
+        await publishAttentionSnapshot(ctx.db, ctx.realtimeHub, req.companyId!);
       }
       return sendOk(res, { queuedForApproval: true, approvalId });
     }
@@ -404,7 +422,9 @@ export function createAgentsRouter(ctx: AppContext) {
     const agent = await createAgent(ctx.db, {
       companyId: req.companyId!,
       managerAgentId: parsed.data.managerAgentId,
-      role: parsed.data.role,
+      role: resolveAgentRoleText(parsed.data.role, parsed.data.roleKey, parsed.data.title),
+      roleKey: normalizeRoleKey(parsed.data.roleKey),
+      title: normalizeTitle(parsed.data.title),
       name: parsed.data.name,
       providerType: parsed.data.providerType,
       heartbeatCron: parsed.data.heartbeatCron,
@@ -543,7 +563,16 @@ export function createAgentsRouter(ctx: AppContext) {
         companyId: req.companyId!,
         id: req.params.agentId,
         managerAgentId: parsed.data.managerAgentId,
-        role: parsed.data.role,
+        role:
+          parsed.data.role !== undefined || parsed.data.roleKey !== undefined || parsed.data.title !== undefined
+            ? resolveAgentRoleText(
+                parsed.data.role ?? existingAgent.role,
+                parsed.data.roleKey ?? existingAgent.roleKey,
+                parsed.data.title ?? existingAgent.title
+              )
+            : undefined,
+        roleKey: parsed.data.roleKey !== undefined ? normalizeRoleKey(parsed.data.roleKey) : undefined,
+        title: parsed.data.title !== undefined ? normalizeTitle(parsed.data.title) : undefined,
         name: parsed.data.name,
         providerType: parsed.data.providerType,
         status: parsed.data.status,
@@ -715,14 +744,15 @@ function enforceRuntimeCwdPolicy(companyId: string, runtime: ReturnType<typeof n
 async function findDuplicateHireRequest(
   db: AppContext["db"],
   companyId: string,
-  input: { role: string; managerAgentId: string | null }
+  input: { role: string; roleKey: string | null; managerAgentId: string | null }
 ) {
   const role = input.role.trim();
+  const roleKey = normalizeRoleKey(input.roleKey);
   const managerAgentId = input.managerAgentId ?? null;
   const agents = await listAgents(db, companyId);
   const existingAgent = agents.find(
     (agent) =>
-      agent.role === role &&
+      ((roleKey && agent.roleKey === roleKey) || (!roleKey && role.length > 0 && agent.role === role)) &&
       (agent.managerAgentId ?? null) === managerAgentId &&
       agent.status !== "terminated"
   );
@@ -732,6 +762,10 @@ async function findDuplicateHireRequest(
       return false;
     }
     const payload = parseApprovalPayload(approval.payloadJson);
+    const payloadRoleKey = normalizeRoleKey(payload.roleKey);
+    if (roleKey && payloadRoleKey) {
+      return payloadRoleKey === roleKey && (payload.managerAgentId ?? null) === managerAgentId;
+    }
     return payload.role === role && (payload.managerAgentId ?? null) === managerAgentId;
   });
   if (!existingAgent && !pendingApproval) {
@@ -743,11 +777,12 @@ async function findDuplicateHireRequest(
   };
 }
 
-function parseApprovalPayload(payloadJson: string): { role?: string; managerAgentId?: string | null } {
+function parseApprovalPayload(payloadJson: string): { role?: string; roleKey?: string | null; managerAgentId?: string | null } {
   try {
     const parsed = JSON.parse(payloadJson) as Record<string, unknown>;
     return {
       role: typeof parsed.role === "string" ? parsed.role : undefined,
+      roleKey: typeof parsed.roleKey === "string" ? parsed.roleKey : null,
       managerAgentId: typeof parsed.managerAgentId === "string" ? parsed.managerAgentId : null
     };
   } catch {
@@ -780,6 +815,40 @@ function providerSupportsSkillInjection(providerType: string) {
   return providerType === "codex" || providerType === "cursor" || providerType === "opencode" || providerType === "claude_code";
 }
 
+function normalizeRoleKey(input: string | null | undefined) {
+  const normalized = input?.trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  const parsed = AgentRoleKeySchema.safeParse(normalized);
+  return parsed.success ? parsed.data : null;
+}
+
+function normalizeTitle(input: string | null | undefined) {
+  const normalized = input?.trim();
+  return normalized ? normalized : null;
+}
+
+function resolveAgentRoleText(
+  legacyRole: string | undefined,
+  roleKeyInput: string | null | undefined,
+  titleInput: string | null | undefined
+) {
+  const normalizedLegacy = legacyRole?.trim();
+  if (normalizedLegacy) {
+    return normalizedLegacy;
+  }
+  const normalizedTitle = normalizeTitle(titleInput);
+  if (normalizedTitle) {
+    return normalizedTitle;
+  }
+  const roleKey = normalizeRoleKey(roleKeyInput);
+  if (roleKey) {
+    return AGENT_ROLE_LABELS[roleKey];
+  }
+  return AGENT_ROLE_LABELS.general;
+}
+
 function resolveAuditActor(actor: { type: "board" | "member" | "agent"; id: string } | undefined) {
   if (!actor) {
     return { actorType: "human" as const, actorId: null as string | null };

package/src/routes/attention.ts

@@ -0,0 +1,112 @@
+import { Router } from "express";
+import { z } from "zod";
+import { sendError, sendOkValidated } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import type { AppContext } from "../context";
+import {
+  clearBoardAttentionDismissed,
+  listBoardAttentionItems,
+  markBoardAttentionAcknowledged,
+  markBoardAttentionDismissed,
+  markBoardAttentionResolved,
+  markBoardAttentionSeen
+} from "../services/attention-service";
+import { BoardAttentionListResponseSchema } from "bopodev-contracts";
+import { createAttentionRealtimeEvent } from "../realtime/attention";
+
+const itemParamsSchema = z.object({
+  itemKey: z.string().min(1)
+});
+
+export function createAttentionRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  // Canonical board action queue endpoint for Inbox and board attention UX.
+  router.get("/", async (req, res) => {
+    const actorId = req.actor?.id ?? "local-board";
+    const items = await listBoardAttentionItems(ctx.db, req.companyId!, actorId);
+    return sendOkValidated(res, BoardAttentionListResponseSchema, { actorId, items }, "attention.list");
+  });
+
+  router.post("/:itemKey/seen", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionSeen(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.seen");
+  });
+
+  router.post("/:itemKey/acknowledge", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionAcknowledged(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.acknowledge");
+  });
+
+  router.post("/:itemKey/dismiss", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionDismissed(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.dismiss");
+  });
+
+  router.post("/:itemKey/undismiss", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await clearBoardAttentionDismissed(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionUpdate(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.undismiss");
+  });
+
+  router.post("/:itemKey/resolve", async (req, res) => {
+    const parsed = itemParamsSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markBoardAttentionResolved(ctx.db, req.companyId!, actorId, parsed.data.itemKey);
+    await publishAttentionResolve(ctx, req.companyId!, actorId, parsed.data.itemKey);
+    return sendOkValidated(res, z.object({ ok: z.literal(true) }), { ok: true }, "attention.resolve");
+  });
+
+  return router;
+}
+
+async function publishAttentionUpdate(ctx: AppContext, companyId: string, actorId: string, itemKey: string) {
+  const items = await listBoardAttentionItems(ctx.db, companyId, actorId);
+  const item = items.find((entry) => entry.key === itemKey);
+  if (!item) {
+    return;
+  }
+  ctx.realtimeHub?.publish(
+    createAttentionRealtimeEvent(companyId, {
+      type: "attention.updated",
+      item
+    })
+  );
+}
+
+async function publishAttentionResolve(ctx: AppContext, companyId: string, actorId: string, itemKey: string) {
+  await publishAttentionUpdate(ctx, companyId, actorId, itemKey);
+  ctx.realtimeHub?.publish(
+    createAttentionRealtimeEvent(companyId, {
+      type: "attention.resolved",
+      key: itemKey
+    })
+  );
+}

package/src/routes/companies.ts

@@ -2,9 +2,10 @@ import { mkdir } from "node:fs/promises";
 import type { NextFunction, Request, Response } from "express";
 import { Router } from "express";
 import { z } from "zod";
+import { CompanySchema } from "bopodev-contracts";
 import { createAgent, createCompany, deleteCompany, listCompanies, updateCompany } from "bopodev-db";
 import type { AppContext } from "../context";
-import { sendError, sendOk } from "../http";
+import { sendError, sendOk, sendOkValidated } from "../http";
 import { normalizeRuntimeConfig, resolveRuntimeModelForProvider, runtimeConfigToDb, runtimeConfigToStateBlobPatch } from "../lib/agent-config";
 import { buildDefaultCeoBootstrapPrompt } from "../lib/ceo-bootstrap-prompt";
 import { resolveOpencodeRuntimeModel } from "../lib/opencode-model";
@@ -37,14 +38,19 @@ export function createCompaniesRouter(ctx: AppContext) {
   const router = Router();
 
   router.get("/", async (req, res) => {
-    const companies = await listCompanies(ctx.db);
+    const companies = (await listCompanies(ctx.db)).map((company) => ({
+      ...company,
+      createdAt: company.createdAt instanceof Date ? company.createdAt.toISOString() : String(company.createdAt)
+    }));
     if (req.actor?.type === "board") {
-      return sendOk(res, companies);
+      return sendOkValidated(res, CompanySchema.array(), companies, "companies.list");
     }
     const visibleCompanyIds = new Set(req.actor?.companyIds ?? []);
-    return sendOk(
+    return sendOkValidated(
       res,
-      companies.filter((company) => visibleCompanyIds.has(company.id))
+      CompanySchema.array(),
+      companies.filter((company) => visibleCompanyIds.has(company.id)),
+      "companies.list.filtered"
     );
   });
 
@@ -91,6 +97,8 @@ export function createCompaniesRouter(ctx: AppContext) {
     await createAgent(ctx.db, {
       companyId: company.id,
       role: "CEO",
+      roleKey: "ceo",
+      title: "CEO",
       name: "CEO",
       providerType,
       heartbeatCron: "*/5 * * * *",

package/src/routes/goals.ts

@@ -1,11 +1,13 @@
 import { Router } from "express";
 import { z } from "zod";
+import { GoalSchema } from "bopodev-contracts";
 import { appendAuditEvent, createApprovalRequest, createGoal, deleteGoal, getApprovalRequest, listGoals, updateGoal } from "bopodev-db";
 import type { AppContext } from "../context";
-import { sendError, sendOk } from "../http";
+import { sendError, sendOk, sendOkValidated } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
 import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import { publishAttentionSnapshot } from "../realtime/attention";
 import { isApprovalRequired } from "../services/governance-service";
 
 const createGoalSchema = z.object({
@@ -33,7 +35,12 @@ export function createGoalsRouter(ctx: AppContext) {
   router.use(requireCompanyScope);
 
   router.get("/", async (req, res) => {
-    return sendOk(res, await listGoals(ctx.db, req.companyId!));
+    return sendOkValidated(
+      res,
+      GoalSchema.array(),
+      await listGoals(ctx.db, req.companyId!),
+      "goals.list"
+    );
   });
 
   router.post("/", async (req, res) => {
@@ -60,6 +67,7 @@ export function createGoalsRouter(ctx: AppContext) {
             approval: serializeStoredApproval(approval)
           })
         );
+        await publishAttentionSnapshot(ctx.db, ctx.realtimeHub, req.companyId!);
       }
       return sendOk(res, { queuedForApproval: true, approvalId });
     }

package/src/routes/governance.ts

@@ -1,6 +1,7 @@
 import { Router } from "express";
 import { z } from "zod";
 import {
+  addIssueComment,
   appendAuditEvent,
   clearApprovalInboxDismissed,
   countPendingApprovalRequests,
@@ -15,6 +16,7 @@ import { sendError, sendOk } from "../http";
 import { requireCompanyScope } from "../middleware/company-scope";
 import { requirePermission } from "../middleware/request-actor";
 import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import { publishAttentionSnapshot } from "../realtime/attention";
 import {
   publishOfficeOccupantForAgent,
   publishOfficeOccupantForApproval
@@ -34,6 +36,9 @@ export function createGovernanceRouter(ctx: AppContext) {
   const router = Router();
   router.use(requireCompanyScope);
 
+  // Deprecated compatibility shim:
+  // board queue consumers should use /attention as the canonical source.
+  // Keep this endpoint until all downstream consumers migrate.
   router.get("/approvals", async (req, res) => {
     const approvals = await listApprovalRequests(ctx.db, req.companyId!);
     return sendOk(
@@ -200,10 +205,41 @@ export function createGovernanceRouter(ctx: AppContext) {
           approval: serializeStoredApproval(approval)
         })
       );
+      await publishAttentionSnapshot(ctx.db, ctx.realtimeHub, req.companyId!);
       await publishOfficeOccupantForApproval(ctx.db, ctx.realtimeHub, req.companyId!, approval.id);
       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) {
@@ -226,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.";
+}