bopodev-api 0.1.23 → 0.1.25

package/package.json

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

package/src/app.ts

@@ -7,6 +7,7 @@ import { nanoid } from "nanoid";
 import type { AppContext } from "./context";
 import { createAgentsRouter } from "./routes/agents";
 import { createAuthRouter } from "./routes/auth";
+import { createAttentionRouter } from "./routes/attention";
 import { createCompaniesRouter } from "./routes/companies";
 import { createGoalsRouter } from "./routes/goals";
 import { createGovernanceRouter } from "./routes/governance";
@@ -46,7 +47,15 @@ export function createApp(ctx: AppContext) {
       },
       credentials: true,
       methods: ["GET", "POST", "PUT", "DELETE", "OPTIONS"],
-      allowedHeaders: ["content-type", "x-company-id", "authorization", "x-client-trace-id", "x-bopo-actor-token"]
+      allowedHeaders: [
+        "content-type",
+        "x-company-id",
+        "authorization",
+        "x-client-trace-id",
+        "x-bopo-actor-token",
+        "x-request-id",
+        "x-bopodev-run-id"
+      ]
     })
   );
   app.use(express.json());
@@ -106,6 +115,7 @@ export function createApp(ctx: AppContext) {
   });
 
   app.use("/auth", createAuthRouter(ctx));
+  app.use("/attention", createAttentionRouter(ctx));
   app.use("/companies", createCompaniesRouter(ctx));
   app.use("/projects", createProjectsRouter(ctx));
   app.use("/issues", createIssuesRouter(ctx));

package/src/http.ts

@@ -4,6 +4,45 @@ export function sendOk<T>(res: Response, data: T) {
   return res.status(200).json({ ok: true, data });
 }
 
+export function sendOkValidated(
+  res: Response,
+  schema: {
+    safeParse: (value: unknown) => {
+      success: boolean;
+      data?: unknown;
+      error?: { issues?: Array<{ path?: unknown[]; message?: string }> };
+    };
+  },
+  data: unknown,
+  resourceName: string
+) {
+  const normalized = normalizeContractData(data);
+  const parsed = schema.safeParse(normalized);
+  if (!parsed.success) {
+    return sendError(
+      res,
+      `Contract mismatch for ${resourceName}: ${(parsed.error?.issues ?? [])
+        .map((issue) => `${(issue.path ?? []).join(".") || "<root>"} ${issue.message ?? "Invalid value"}`)
+        .join("; ")}`,
+      500
+    );
+  }
+  return sendOk(res, parsed.data ?? normalized);
+}
+
 export function sendError(res: Response, message: string, code = 400) {
   return res.status(code).json({ ok: false, error: message });
 }
+
+function normalizeContractData(value: unknown) {
+  const serialized = JSON.stringify(value, (_key, entry) => {
+    if (entry instanceof Date) {
+      return entry.toISOString();
+    }
+    return entry;
+  });
+  if (serialized === undefined) {
+    return value;
+  }
+  return JSON.parse(serialized);
+}

package/src/lib/comment-recipients.ts

@@ -0,0 +1,105 @@
+export type CommentRecipientType = "agent" | "board" | "member";
+
+export type CommentRecipientInput = {
+  recipientType: CommentRecipientType;
+  recipientId?: string | null;
+};
+
+export type PersistedCommentRecipient = {
+  recipientType: CommentRecipientType;
+  recipientId: string | null;
+  deliveryStatus: "pending" | "dispatched" | "failed" | "skipped";
+  dispatchedRunId: string | null;
+  dispatchedAt: string | null;
+  acknowledgedAt: string | null;
+};
+
+export function dedupeCommentRecipients(recipients: CommentRecipientInput[]) {
+  const result: Array<{ recipientType: CommentRecipientType; recipientId: string | null }> = [];
+  const seen = new Set<string>();
+  for (const recipient of recipients) {
+    const recipientId = recipient.recipientId?.trim() ? recipient.recipientId.trim() : null;
+    if (recipient.recipientType !== "board" && !recipientId) {
+      continue;
+    }
+    const key = `${recipient.recipientType}:${recipientId ?? "__all__"}`;
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    result.push({
+      recipientType: recipient.recipientType,
+      recipientId
+    });
+  }
+  return result;
+}
+
+export function normalizeRecipientsForPersistence(
+  recipients: Array<{ recipientType: CommentRecipientType; recipientId: string | null }>
+): PersistedCommentRecipient[] {
+  return recipients.map((recipient) => ({
+    recipientType: recipient.recipientType,
+    recipientId: recipient.recipientId ?? null,
+    // Non-agent recipients are terminal at creation time; they are not dispatch targets.
+    deliveryStatus: recipient.recipientType === "agent" ? "pending" : "skipped",
+    dispatchedRunId: null,
+    dispatchedAt: null,
+    acknowledgedAt: null
+  }));
+}
+
+export function parseIssueCommentRecipients(raw: string | null): PersistedCommentRecipient[] {
+  if (!raw) {
+    return [];
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (!Array.isArray(parsed)) {
+      return [];
+    }
+    return parsed
+      .map((entry) => {
+        if (!entry || typeof entry !== "object") {
+          return null;
+        }
+        const candidate = entry as Record<string, unknown>;
+        const recipientTypeRaw = String(candidate.recipientType ?? "").trim();
+        if (recipientTypeRaw !== "agent" && recipientTypeRaw !== "board" && recipientTypeRaw !== "member") {
+          return null;
+        }
+        const deliveryStatusRaw = String(candidate.deliveryStatus ?? "").trim();
+        const deliveryStatus =
+          deliveryStatusRaw === "pending" ||
+          deliveryStatusRaw === "dispatched" ||
+          deliveryStatusRaw === "failed" ||
+          deliveryStatusRaw === "skipped"
+            ? deliveryStatusRaw
+            : "pending";
+        const recipientId =
+          typeof candidate.recipientId === "string" && candidate.recipientId.trim().length > 0
+            ? candidate.recipientId.trim()
+            : null;
+        return {
+          recipientType: recipientTypeRaw as CommentRecipientType,
+          recipientId,
+          deliveryStatus,
+          dispatchedRunId:
+            typeof candidate.dispatchedRunId === "string" && candidate.dispatchedRunId.trim().length > 0
+              ? candidate.dispatchedRunId.trim()
+              : null,
+          dispatchedAt:
+            typeof candidate.dispatchedAt === "string" && candidate.dispatchedAt.trim().length > 0
+              ? candidate.dispatchedAt.trim()
+              : null,
+          acknowledgedAt:
+            typeof candidate.acknowledgedAt === "string" && candidate.acknowledgedAt.trim().length > 0
+              ? candidate.acknowledgedAt.trim()
+              : null
+        } satisfies PersistedCommentRecipient;
+      })
+      .filter(Boolean) as PersistedCommentRecipient[];
+  } catch {
+    return [];
+  }
+}

package/src/lib/hiring-delegate.ts

@@ -2,6 +2,7 @@ type AgentLike = {
   id: string;
   name: string;
   role: string;
+  roleKey?: string | null;
   status: string;
   canHireAgents?: boolean | null;
 };
@@ -12,6 +13,7 @@ export type HiringDelegateResolution =
         agentId: string;
         name: string;
         role: string;
+        roleKey?: string | null;
       };
       reason: "ceo_with_hiring_capability" | "first_hiring_capable_agent";
     }
@@ -32,18 +34,16 @@ export function resolveHiringDelegate(agents: AgentLike[]): HiringDelegateResolu
   }
   const normalized = eligible.map((agent) => ({
     ...agent,
-    normalizedRole: agent.role.trim().toLowerCase(),
     normalizedName: agent.name.trim().toLowerCase()
   }));
-  const ceo =
-    normalized.find((agent) => agent.normalizedRole === "ceo") ??
-    normalized.find((agent) => agent.normalizedName === "ceo");
+  const ceo = normalized.find((agent) => agent.roleKey === "ceo") ?? normalized.find((agent) => agent.normalizedName === "ceo");
   if (ceo) {
     return {
       delegate: {
         agentId: ceo.id,
         name: ceo.name,
-        role: ceo.role
+        role: ceo.role,
+        roleKey: ceo.roleKey ?? null
       },
       reason: "ceo_with_hiring_capability"
     };
@@ -53,7 +53,8 @@ export function resolveHiringDelegate(agents: AgentLike[]): HiringDelegateResolu
     delegate: {
       agentId: fallback.id,
       name: fallback.name,
-      role: fallback.role
+      role: fallback.role,
+      roleKey: fallback.roleKey ?? null
     },
     reason: "first_hiring_capable_agent"
   };

package/src/lib/instance-paths.ts

@@ -78,6 +78,17 @@ export function resolveAgentMemoryRootPath(companyId: string, agentId: string) {
   return join(resolveAgentFallbackWorkspacePath(companyId, agentId), "memory");
 }
 
+export function resolveCompanyMemoryRootPath(companyId: string) {
+  const safeCompanyId = assertPathSegment(companyId, "companyId");
+  return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId, "memory");
+}
+
+export function resolveProjectMemoryRootPath(companyId: string, projectId: string) {
+  const safeCompanyId = assertPathSegment(companyId, "companyId");
+  const safeProjectId = assertPathSegment(projectId, "projectId");
+  return join(resolveBopoInstanceRoot(), "workspaces", safeCompanyId, "projects", safeProjectId, "memory");
+}
+
 export function resolveAgentDurableMemoryPath(companyId: string, agentId: string) {
   return join(resolveAgentMemoryRootPath(companyId, agentId), "life");
 }

package/src/realtime/attention.ts

@@ -0,0 +1,47 @@
+import type { RealtimeEventEnvelope, RealtimeMessage } from "bopodev-contracts";
+import type { BopoDb } from "bopodev-db";
+import { listBoardAttentionItems } from "../services/attention-service";
+import type { RealtimeHub } from "./hub";
+
+const DEFAULT_ACTOR_ID = "local-board";
+
+export async function loadAttentionRealtimeSnapshot(
+  db: BopoDb,
+  companyId: string
+): Promise<Extract<RealtimeMessage, { kind: "event" }>> {
+  const items = await listBoardAttentionItems(db, companyId, DEFAULT_ACTOR_ID);
+  return createAttentionRealtimeEvent(companyId, {
+    type: "attention.snapshot",
+    items
+  });
+}
+
+export function createAttentionRealtimeEvent(
+  companyId: string,
+  event: Extract<RealtimeEventEnvelope, { channel: "attention" }>["event"]
+): Extract<RealtimeMessage, { kind: "event" }> {
+  return {
+    kind: "event",
+    companyId,
+    channel: "attention",
+    event
+  };
+}
+
+export async function publishAttentionSnapshot(
+  db: BopoDb,
+  realtimeHub: RealtimeHub | undefined,
+  companyId: string,
+  actorId = DEFAULT_ACTOR_ID
+) {
+  if (!realtimeHub) {
+    return;
+  }
+  const items = await listBoardAttentionItems(db, companyId, actorId);
+  realtimeHub.publish(
+    createAttentionRealtimeEvent(companyId, {
+      type: "attention.snapshot",
+      items
+    })
+  );
+}

package/src/realtime/governance.ts

@@ -1,4 +1,10 @@
-import type { ApprovalRequest, RealtimeEventEnvelope, RealtimeMessage } from "bopodev-contracts";
+import {
+  ApprovalActionSchema,
+  ApprovalRequestSchema,
+  type ApprovalRequest,
+  type RealtimeEventEnvelope,
+  type RealtimeMessage
+} from "bopodev-contracts";
 import { listApprovalRequests, type BopoDb } from "bopodev-db";
 
 export async function loadGovernanceRealtimeSnapshot(db: BopoDb, companyId: string): Promise<Extract<RealtimeMessage, { kind: "event" }>> {
@@ -33,13 +39,15 @@ export function serializeStoredApproval(approval: {
   createdAt: Date;
   resolvedAt: Date | null;
 }): ApprovalRequest {
+  const actionParsed = ApprovalActionSchema.safeParse(approval.action);
+  const statusParsed = ApprovalRequestSchema.shape.status.safeParse(approval.status);
   return {
     id: approval.id,
     companyId: approval.companyId,
     requestedByAgentId: approval.requestedByAgentId,
-    action: approval.action as ApprovalRequest["action"],
+    action: actionParsed.success ? actionParsed.data : "override_budget",
     payload: parsePayload(approval.payloadJson),
-    status: approval.status as ApprovalRequest["status"],
+    status: statusParsed.success ? statusParsed.data : "pending",
     createdAt: approval.createdAt.toISOString(),
     resolvedAt: approval.resolvedAt?.toISOString() ?? null
   };

package/src/realtime/heartbeat-runs.ts

@@ -1,8 +1,17 @@
 import type {
   HeartbeatRunRealtimeEvent,
+  HeartbeatRunTranscriptEventKind,
+  HeartbeatRunTranscriptSignalLevel,
+  HeartbeatRunTranscriptSource,
   RealtimeEventEnvelope,
   RealtimeMessage
 } from "bopodev-contracts";
+import {
+  HeartbeatRunSchema,
+  HeartbeatRunTranscriptEventKindSchema,
+  HeartbeatRunTranscriptSignalLevelSchema,
+  HeartbeatRunTranscriptSourceSchema
+} from "bopodev-contracts";
 import { listHeartbeatRunMessagesForRuns, listHeartbeatRuns, type BopoDb } from "bopodev-db";
 
 export function createHeartbeatRunsRealtimeEvent(
@@ -33,20 +42,13 @@ export async function loadHeartbeatRunsRealtimeSnapshot(
         id: message.id,
         runId: message.runId,
         sequence: message.sequence,
-        kind: message.kind as
-          | "system"
-          | "assistant"
-          | "thinking"
-          | "tool_call"
-          | "tool_result"
-          | "result"
-          | "stderr",
+        kind: parseTranscriptKind(message.kind),
         label: message.label,
         text: message.text,
         payload: message.payloadJson,
-        signalLevel: (message.signalLevel as "high" | "medium" | "low" | "noise" | null) ?? undefined,
+        signalLevel: parseTranscriptSignalLevel(message.signalLevel),
         groupKey: message.groupKey,
-        source: (message.source as "stdout" | "stderr" | "trace_fallback" | null) ?? undefined,
+        source: parseTranscriptSource(message.source),
         createdAt: message.createdAt.toISOString()
       })),
       nextCursor: result.nextCursor
@@ -57,7 +59,7 @@ export async function loadHeartbeatRunsRealtimeSnapshot(
     type: "runs.snapshot",
     runs: runs.map((run) => ({
       runId: run.id,
-      status: run.status as "started" | "completed" | "failed" | "skipped",
+      status: parseRunStatus(run.status),
       message: run.message ?? null,
       startedAt: run.startedAt.toISOString(),
       finishedAt: run.finishedAt?.toISOString() ?? null
@@ -76,3 +78,23 @@ function createRealtimeEvent(
     ...envelope
   };
 }
+
+function parseRunStatus(value: string) {
+  const parsed = HeartbeatRunSchema.shape.status.safeParse(value);
+  return parsed.success ? parsed.data : "failed";
+}
+
+function parseTranscriptKind(value: string): HeartbeatRunTranscriptEventKind {
+  const parsed = HeartbeatRunTranscriptEventKindSchema.safeParse(value);
+  return parsed.success ? parsed.data : "system";
+}
+
+function parseTranscriptSignalLevel(value: string | null): HeartbeatRunTranscriptSignalLevel | undefined {
+  const parsed = HeartbeatRunTranscriptSignalLevelSchema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+}
+
+function parseTranscriptSource(value: string | null): HeartbeatRunTranscriptSource | undefined {
+  const parsed = HeartbeatRunTranscriptSourceSchema.safeParse(value);
+  return parsed.success ? parsed.data : undefined;
+}

package/src/realtime/hub.ts

@@ -140,7 +140,7 @@ function canSubscribeToCompany(
 ) {
   const deploymentMode = resolveDeploymentMode();
   const tokenSecret = process.env.BOPO_AUTH_TOKEN_SECRET?.trim() || "";
-  const tokenIdentity = tokenSecret ? verifyActorToken(readRealtimeTokenFromUrl(requestUrl), tokenSecret) : null;
+  const tokenIdentity = tokenSecret ? verifyActorToken(readRealtimeToken(requestUrl, headers), tokenSecret) : null;
   if (tokenIdentity) {
     if (tokenIdentity.type === "board") {
       return true;
@@ -169,7 +169,11 @@ function canSubscribeToCompany(
   return actorCompanies.includes(companyId);
 }
 
-function readRealtimeTokenFromUrl(requestUrl: string | undefined) {
+function readRealtimeToken(requestUrl: string | undefined, headers: Record<string, string | string[] | undefined>) {
+  const fromProtocol = readRealtimeTokenFromSubprotocolHeader(readHeader(headers, "sec-websocket-protocol"));
+  if (fromProtocol) {
+    return fromProtocol;
+  }
   if (!requestUrl) {
     return null;
   }
@@ -178,6 +182,34 @@ function readRealtimeTokenFromUrl(requestUrl: string | undefined) {
   return token && token.length > 0 ? token : null;
 }
 
+function readRealtimeTokenFromSubprotocolHeader(value: string | undefined) {
+  if (!value) {
+    return null;
+  }
+  const protocolEntries = value
+    .split(",")
+    .map((entry) => entry.trim())
+    .filter((entry) => entry.length > 0);
+  for (const protocol of protocolEntries) {
+    if (!protocol.startsWith("bopo-token.")) {
+      continue;
+    }
+    const encodedToken = protocol.slice("bopo-token.".length);
+    if (!encodedToken) {
+      continue;
+    }
+    try {
+      const decoded = decodeURIComponent(encodedToken).trim();
+      if (decoded) {
+        return decoded;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
 function readHeader(headers: Record<string, string | string[] | undefined>, name: string) {
   const value = headers[name];
   if (Array.isArray(value)) {

package/src/realtime/office-space.ts

@@ -1,5 +1,6 @@
 import { and, desc, eq } from "drizzle-orm";
 import type { OfficeOccupant, RealtimeEventEnvelope, RealtimeMessage } from "bopodev-contracts";
+import { AGENT_ROLE_LABELS, AgentRoleKeySchema } from "bopodev-contracts";
 import {
   agents,
   approvalRequests,
@@ -376,7 +377,7 @@ function deriveHireCandidateOccupant(approval: {
 
   const payload = parsePayload(approval.payloadJson);
   const name = typeof payload.name === "string" ? payload.name : "Pending hire";
-  const role = typeof payload.role === "string" ? payload.role : null;
+  const role = resolvePayloadRoleLabel(payload);
   const providerType =
     typeof payload.providerType === "string" ? normalizeProviderType(payload.providerType) : null;
 
@@ -431,6 +432,7 @@ function normalizeProviderType(value: string): OfficeOccupant["providerType"] {
     value === "codex" ||
     value === "cursor" ||
     value === "opencode" ||
+    value === "gemini_cli" ||
     value === "openai_api" ||
     value === "anthropic_api" ||
     value === "http" ||
@@ -446,6 +448,20 @@ function formatActionLabel(action: string) {
     .join(" ");
 }
 
+function resolvePayloadRoleLabel(payload: Record<string, unknown>) {
+  const title = typeof payload.title === "string" ? payload.title.trim() : "";
+  if (title) {
+    return title;
+  }
+  const roleKeyValue = typeof payload.roleKey === "string" ? payload.roleKey.trim().toLowerCase() : "";
+  const parsedRoleKey = roleKeyValue ? AgentRoleKeySchema.safeParse(roleKeyValue) : null;
+  if (parsedRoleKey?.success) {
+    return AGENT_ROLE_LABELS[parsedRoleKey.data];
+  }
+  const role = typeof payload.role === "string" ? payload.role.trim() : "";
+  return role || null;
+}
+
 function parsePayload(payloadJson: string): Record<string, unknown> {
   try {
     const parsed = JSON.parse(payloadJson) as unknown;