bopodev-api 0.1.1

package/src/routes/agents.ts

@@ -0,0 +1,305 @@
+import { Router } from "express";
+import { z } from "zod";
+import { appendAuditEvent, createAgent, createApprovalRequest, deleteAgent, getApprovalRequest, listAgents, updateAgent } from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import { requireBoardRole, requirePermission } from "../middleware/request-actor";
+import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import {
+  publishOfficeOccupantForAgent,
+  publishOfficeOccupantForApproval
+} from "../realtime/office-space";
+import { isApprovalRequired } from "../services/governance-service";
+
+const createAgentSchema = z.object({
+  managerAgentId: z.string().optional(),
+  role: z.string().min(1),
+  name: z.string().min(1),
+  providerType: z.enum(["claude_code", "codex", "http", "shell"]),
+  heartbeatCron: z.string().default("*/5 * * * *"),
+  monthlyBudgetUsd: z.number().nonnegative().default(30),
+  canHireAgents: z.boolean().default(false),
+  requestApproval: z.boolean().default(true),
+  runtimeCommand: z.string().optional(),
+  runtimeArgs: z.array(z.string()).optional(),
+  runtimeCwd: z.string().optional(),
+  runtimeTimeoutMs: z.number().int().positive().max(600000).optional()
+});
+
+const updateAgentSchema = z
+  .object({
+    managerAgentId: z.string().nullable().optional(),
+    role: z.string().min(1).optional(),
+    name: z.string().min(1).optional(),
+    providerType: z.enum(["claude_code", "codex", "http", "shell"]).optional(),
+    status: z.enum(["idle", "running", "paused", "terminated"]).optional(),
+    heartbeatCron: z.string().min(1).optional(),
+    monthlyBudgetUsd: z.number().nonnegative().optional(),
+    canHireAgents: z.boolean().optional(),
+    runtimeCommand: z.string().optional(),
+    runtimeArgs: z.array(z.string()).optional(),
+    runtimeCwd: z.string().optional(),
+    runtimeTimeoutMs: z.number().int().positive().max(600000).optional()
+  })
+  .refine((payload) => Object.keys(payload).length > 0, "At least one field must be provided.");
+
+function toAgentResponse(agent: Record<string, unknown>) {
+  return {
+    ...agent,
+    monthlyBudgetUsd:
+      typeof agent.monthlyBudgetUsd === "number" ? agent.monthlyBudgetUsd : Number(agent.monthlyBudgetUsd ?? 0),
+    usedBudgetUsd: typeof agent.usedBudgetUsd === "number" ? agent.usedBudgetUsd : Number(agent.usedBudgetUsd ?? 0)
+  };
+}
+
+export function createAgentsRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.get("/", async (req, res) => {
+    const rows = await listAgents(ctx.db, req.companyId!);
+    return sendOk(
+      res,
+      rows.map((row) => toAgentResponse(row as unknown as Record<string, unknown>))
+    );
+  });
+
+  router.post("/", async (req, res) => {
+    const requireCreate = requirePermission("agents:write");
+    requireCreate(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = createAgentSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    if (parsed.data.requestApproval && isApprovalRequired("hire_agent")) {
+      const approvalId = await createApprovalRequest(ctx.db, {
+        companyId: req.companyId!,
+        action: "hire_agent",
+        payload: parsed.data
+      });
+      const approval = await getApprovalRequest(ctx.db, req.companyId!, approvalId);
+      if (approval) {
+        ctx.realtimeHub?.publish(
+          createGovernanceRealtimeEvent(req.companyId!, {
+            type: "approval.created",
+            approval: serializeStoredApproval(approval)
+          })
+        );
+        await publishOfficeOccupantForApproval(ctx.db, ctx.realtimeHub, req.companyId!, approvalId);
+      }
+      return sendOk(res, { queuedForApproval: true, approvalId });
+    }
+
+    const agent = await createAgent(ctx.db, {
+      companyId: req.companyId!,
+      managerAgentId: parsed.data.managerAgentId,
+      role: parsed.data.role,
+      name: parsed.data.name,
+      providerType: parsed.data.providerType,
+      heartbeatCron: parsed.data.heartbeatCron,
+      monthlyBudgetUsd: parsed.data.monthlyBudgetUsd.toFixed(4),
+      canHireAgents: parsed.data.canHireAgents,
+      initialState: {
+        runtime: {
+          command: parsed.data.runtimeCommand,
+          args: parsed.data.runtimeArgs,
+          cwd: parsed.data.runtimeCwd,
+          timeoutMs: parsed.data.runtimeTimeoutMs
+        }
+      }
+    });
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "agent.hired",
+      entityType: "agent",
+      entityId: agent.id,
+      payload: agent
+    });
+    await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, agent.id);
+    return sendOk(res, toAgentResponse(agent as unknown as Record<string, unknown>));
+  });
+
+  router.put("/:agentId", async (req, res) => {
+    const requireUpdate = requirePermission("agents:write");
+    requireUpdate(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = updateAgentSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    const existingAgent = (await listAgents(ctx.db, req.companyId!)).find((row) => row.id === req.params.agentId);
+    if (!existingAgent) {
+      return sendError(res, "Agent not found.", 404);
+    }
+
+    const hasRuntimePatch =
+      parsed.data.runtimeCommand !== undefined ||
+      parsed.data.runtimeArgs !== undefined ||
+      parsed.data.runtimeCwd !== undefined ||
+      parsed.data.runtimeTimeoutMs !== undefined;
+
+    let stateBlobPatch: Record<string, unknown> | undefined;
+    if (hasRuntimePatch) {
+      const existingState = (() => {
+        try {
+          const parsedState = JSON.parse(existingAgent.stateBlob ?? "{}") as Record<string, unknown>;
+          return typeof parsedState === "object" && parsedState !== null ? parsedState : {};
+        } catch {
+          return {};
+        }
+      })();
+      const existingRuntime =
+        typeof existingState.runtime === "object" && existingState.runtime !== null
+          ? (existingState.runtime as Record<string, unknown>)
+          : {};
+      stateBlobPatch = {
+        ...existingState,
+        runtime: {
+          ...existingRuntime,
+          ...(parsed.data.runtimeCommand === undefined ? {} : { command: parsed.data.runtimeCommand }),
+          ...(parsed.data.runtimeArgs === undefined ? {} : { args: parsed.data.runtimeArgs }),
+          ...(parsed.data.runtimeCwd === undefined ? {} : { cwd: parsed.data.runtimeCwd }),
+          ...(parsed.data.runtimeTimeoutMs === undefined ? {} : { timeoutMs: parsed.data.runtimeTimeoutMs })
+        }
+      };
+    }
+
+    const agent = await updateAgent(ctx.db, {
+      companyId: req.companyId!,
+      id: req.params.agentId,
+      managerAgentId: parsed.data.managerAgentId,
+      role: parsed.data.role,
+      name: parsed.data.name,
+      providerType: parsed.data.providerType,
+      status: parsed.data.status,
+      heartbeatCron: parsed.data.heartbeatCron,
+      monthlyBudgetUsd:
+        typeof parsed.data.monthlyBudgetUsd === "number" ? parsed.data.monthlyBudgetUsd.toFixed(4) : undefined,
+      canHireAgents: parsed.data.canHireAgents,
+      stateBlob: stateBlobPatch
+    });
+    if (!agent) {
+      return sendError(res, "Agent not found.", 404);
+    }
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "agent.updated",
+      entityType: "agent",
+      entityId: agent.id,
+      payload: agent
+    });
+    await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, agent.id);
+    return sendOk(res, toAgentResponse(agent as unknown as Record<string, unknown>));
+  });
+
+  router.delete("/:agentId", async (req, res) => {
+    requireBoardRole(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const deleted = await deleteAgent(ctx.db, req.companyId!, req.params.agentId);
+    if (!deleted) {
+      return sendError(res, "Agent not found.", 404);
+    }
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "agent.deleted",
+      entityType: "agent",
+      entityId: req.params.agentId,
+      payload: { id: req.params.agentId }
+    });
+    await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, req.params.agentId);
+    return sendOk(res, { deleted: true });
+  });
+
+  router.post("/:agentId/pause", async (req, res) => {
+    requirePermission("agents:lifecycle")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const agent = await updateAgent(ctx.db, {
+      companyId: req.companyId!,
+      id: req.params.agentId,
+      status: "paused"
+    });
+    if (!agent) {
+      return sendError(res, "Agent not found.", 404);
+    }
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "agent.paused",
+      entityType: "agent",
+      entityId: agent.id,
+      payload: { id: agent.id, status: agent.status }
+    });
+    await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, agent.id);
+    return sendOk(res, toAgentResponse(agent as unknown as Record<string, unknown>));
+  });
+
+  router.post("/:agentId/resume", async (req, res) => {
+    requirePermission("agents:lifecycle")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const agent = await updateAgent(ctx.db, {
+      companyId: req.companyId!,
+      id: req.params.agentId,
+      status: "idle"
+    });
+    if (!agent) {
+      return sendError(res, "Agent not found.", 404);
+    }
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "agent.resumed",
+      entityType: "agent",
+      entityId: agent.id,
+      payload: { id: agent.id, status: agent.status }
+    });
+    await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, agent.id);
+    return sendOk(res, toAgentResponse(agent as unknown as Record<string, unknown>));
+  });
+
+  router.post("/:agentId/terminate", async (req, res) => {
+    requireBoardRole(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const agent = await updateAgent(ctx.db, {
+      companyId: req.companyId!,
+      id: req.params.agentId,
+      status: "terminated"
+    });
+    if (!agent) {
+      return sendError(res, "Agent not found.", 404);
+    }
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "agent.terminated",
+      entityType: "agent",
+      entityId: agent.id,
+      payload: { id: agent.id, status: agent.status }
+    });
+    await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, agent.id);
+    return sendOk(res, toAgentResponse(agent as unknown as Record<string, unknown>));
+  });
+
+  return router;
+}

package/src/routes/companies.ts

@@ -0,0 +1,58 @@
+import { Router } from "express";
+import { z } from "zod";
+import { createCompany, deleteCompany, listCompanies, updateCompany } from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+
+const createCompanySchema = z.object({
+  name: z.string().min(1),
+  mission: z.string().optional()
+});
+
+const updateCompanySchema = z
+  .object({
+    name: z.string().min(1).optional(),
+    mission: z.string().optional()
+  })
+  .refine((payload) => Object.keys(payload).length > 0, "At least one field must be provided.");
+
+export function createCompaniesRouter(ctx: AppContext) {
+  const router = Router();
+
+  router.get("/", async (_req, res) => {
+    const companies = await listCompanies(ctx.db);
+    return sendOk(res, companies);
+  });
+
+  router.post("/", async (req, res) => {
+    const parsed = createCompanySchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const company = await createCompany(ctx.db, parsed.data);
+    return sendOk(res, company);
+  });
+
+  router.put("/:companyId", async (req, res) => {
+    const parsed = updateCompanySchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    const company = await updateCompany(ctx.db, { id: req.params.companyId, ...parsed.data });
+    if (!company) {
+      return sendError(res, "Company not found.", 404);
+    }
+    return sendOk(res, company);
+  });
+
+  router.delete("/:companyId", async (req, res) => {
+    const deleted = await deleteCompany(ctx.db, req.params.companyId);
+    if (!deleted) {
+      return sendError(res, "Company not found.", 404);
+    }
+    return sendOk(res, { deleted: true });
+  });
+
+  return router;
+}

package/src/routes/goals.ts

@@ -0,0 +1,134 @@
+import { Router } from "express";
+import { z } from "zod";
+import { appendAuditEvent, createApprovalRequest, createGoal, deleteGoal, getApprovalRequest, listGoals, updateGoal } from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import { requirePermission } from "../middleware/request-actor";
+import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import { isApprovalRequired } from "../services/governance-service";
+
+const createGoalSchema = z.object({
+  projectId: z.string().optional(),
+  parentGoalId: z.string().optional(),
+  level: z.enum(["company", "project", "agent"]),
+  title: z.string().min(1),
+  description: z.string().optional(),
+  activateNow: z.boolean().default(false)
+});
+
+const updateGoalSchema = z
+  .object({
+    projectId: z.string().nullable().optional(),
+    parentGoalId: z.string().nullable().optional(),
+    level: z.enum(["company", "project", "agent"]).optional(),
+    title: z.string().min(1).optional(),
+    description: z.string().nullable().optional(),
+    status: z.enum(["draft", "active", "completed", "archived"]).optional()
+  })
+  .refine((payload) => Object.keys(payload).length > 0, "At least one field must be provided.");
+
+export function createGoalsRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.get("/", async (req, res) => {
+    return sendOk(res, await listGoals(ctx.db, req.companyId!));
+  });
+
+  router.post("/", async (req, res) => {
+    requirePermission("goals:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = createGoalSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    if (parsed.data.activateNow && isApprovalRequired("activate_goal")) {
+      const approvalId = await createApprovalRequest(ctx.db, {
+        companyId: req.companyId!,
+        action: "activate_goal",
+        payload: parsed.data
+      });
+      const approval = await getApprovalRequest(ctx.db, req.companyId!, approvalId);
+      if (approval) {
+        ctx.realtimeHub?.publish(
+          createGovernanceRealtimeEvent(req.companyId!, {
+            type: "approval.created",
+            approval: serializeStoredApproval(approval)
+          })
+        );
+      }
+      return sendOk(res, { queuedForApproval: true, approvalId });
+    }
+
+    const goal = await createGoal(ctx.db, {
+      companyId: req.companyId!,
+      projectId: parsed.data.projectId,
+      parentGoalId: parsed.data.parentGoalId,
+      level: parsed.data.level,
+      title: parsed.data.title,
+      description: parsed.data.description
+    });
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "goal.created",
+      entityType: "goal",
+      entityId: goal.id,
+      payload: goal
+    });
+    return sendOk(res, goal);
+  });
+
+  router.put("/:goalId", async (req, res) => {
+    requirePermission("goals:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = updateGoalSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+
+    const goal = await updateGoal(ctx.db, { companyId: req.companyId!, id: req.params.goalId, ...parsed.data });
+    if (!goal) {
+      return sendError(res, "Goal not found.", 404);
+    }
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "goal.updated",
+      entityType: "goal",
+      entityId: goal.id,
+      payload: goal
+    });
+    return sendOk(res, goal);
+  });
+
+  router.delete("/:goalId", async (req, res) => {
+    requirePermission("goals:write")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const deleted = await deleteGoal(ctx.db, req.companyId!, req.params.goalId);
+    if (!deleted) {
+      return sendError(res, "Goal not found.", 404);
+    }
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "goal.deleted",
+      entityType: "goal",
+      entityId: req.params.goalId,
+      payload: { id: req.params.goalId }
+    });
+    return sendOk(res, { deleted: true });
+  });
+
+  return router;
+}

package/src/routes/governance.ts

@@ -0,0 +1,208 @@
+import { Router } from "express";
+import { z } from "zod";
+import {
+  appendAuditEvent,
+  clearApprovalInboxDismissed,
+  getApprovalRequest,
+  listApprovalInboxStates,
+  listApprovalRequests,
+  markApprovalInboxDismissed,
+  markApprovalInboxSeen
+} from "bopodev-db";
+import type { AppContext } from "../context";
+import { sendError, sendOk } from "../http";
+import { requireCompanyScope } from "../middleware/company-scope";
+import { requirePermission } from "../middleware/request-actor";
+import { createGovernanceRealtimeEvent, serializeStoredApproval } from "../realtime/governance";
+import {
+  publishOfficeOccupantForAgent,
+  publishOfficeOccupantForApproval
+} from "../realtime/office-space";
+import { GovernanceError, resolveApproval } from "../services/governance-service";
+
+const resolveSchema = z.object({
+  approvalId: z.string().min(1),
+  status: z.enum(["approved", "rejected", "overridden"])
+});
+const inboxMutationSchema = z.object({
+  approvalId: z.string().min(1)
+});
+const RESOLVED_APPROVAL_INBOX_WINDOW_DAYS = 30;
+
+export function createGovernanceRouter(ctx: AppContext) {
+  const router = Router();
+  router.use(requireCompanyScope);
+
+  router.get("/approvals", async (req, res) => {
+    const approvals = await listApprovalRequests(ctx.db, req.companyId!);
+    return sendOk(
+      res,
+      approvals.map((approval) => ({
+        ...approval,
+        payload: parsePayload(approval.payloadJson)
+      }))
+    );
+  });
+
+  router.get("/inbox", async (req, res) => {
+    const actorId = req.actor?.id ?? "local-board";
+    const [approvals, inboxStates] = await Promise.all([
+      listApprovalRequests(ctx.db, req.companyId!),
+      listApprovalInboxStates(ctx.db, req.companyId!, actorId)
+    ]);
+    const now = Date.now();
+    const resolvedWindowMs = RESOLVED_APPROVAL_INBOX_WINDOW_DAYS * 24 * 60 * 60 * 1000;
+    const inboxStateByApprovalId = new Map(inboxStates.map((state) => [state.approvalId, state]));
+    const items = approvals
+      .filter((approval) => {
+        if (approval.status === "pending") {
+          return true;
+        }
+        if (!approval.resolvedAt) {
+          return false;
+        }
+        return now - approval.resolvedAt.getTime() <= resolvedWindowMs;
+      })
+      .map((approval) => {
+        const inboxState = inboxStateByApprovalId.get(approval.id);
+        return {
+          approval: serializeStoredApproval(approval),
+          seenAt: inboxState?.seenAt?.toISOString() ?? null,
+          dismissedAt: inboxState?.dismissedAt?.toISOString() ?? null,
+          isPending: approval.status === "pending"
+        };
+      });
+
+    return sendOk(res, {
+      actorId,
+      resolvedWindowDays: RESOLVED_APPROVAL_INBOX_WINDOW_DAYS,
+      items
+    });
+  });
+
+  router.post("/inbox/:approvalId/seen", async (req, res) => {
+    const parsed = inboxMutationSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const approval = await getApprovalRequest(ctx.db, req.companyId!, parsed.data.approvalId);
+    if (!approval) {
+      return sendError(res, "Approval request not found.", 404);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markApprovalInboxSeen(ctx.db, {
+      companyId: req.companyId!,
+      actorId,
+      approvalId: approval.id
+    });
+    return sendOk(res, { ok: true });
+  });
+
+  router.post("/inbox/:approvalId/dismiss", async (req, res) => {
+    const parsed = inboxMutationSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const approval = await getApprovalRequest(ctx.db, req.companyId!, parsed.data.approvalId);
+    if (!approval) {
+      return sendError(res, "Approval request not found.", 404);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await markApprovalInboxDismissed(ctx.db, {
+      companyId: req.companyId!,
+      actorId,
+      approvalId: approval.id
+    });
+    return sendOk(res, { ok: true });
+  });
+
+  router.post("/inbox/:approvalId/undismiss", async (req, res) => {
+    const parsed = inboxMutationSchema.safeParse(req.params);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    const approval = await getApprovalRequest(ctx.db, req.companyId!, parsed.data.approvalId);
+    if (!approval) {
+      return sendError(res, "Approval request not found.", 404);
+    }
+    const actorId = req.actor?.id ?? "local-board";
+    await clearApprovalInboxDismissed(ctx.db, {
+      companyId: req.companyId!,
+      actorId,
+      approvalId: approval.id
+    });
+    return sendOk(res, { ok: true });
+  });
+
+  router.post("/resolve", async (req, res) => {
+    requirePermission("governance:resolve")(req, res, () => {});
+    if (res.headersSent) {
+      return;
+    }
+    const parsed = resolveSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return sendError(res, parsed.error.message, 422);
+    }
+    let resolution;
+    try {
+      resolution = await resolveApproval(ctx.db, req.companyId!, parsed.data.approvalId, parsed.data.status);
+    } catch (error) {
+      if (error instanceof GovernanceError) {
+        return sendError(res, error.message, 422);
+      }
+      throw error;
+    }
+
+    await appendAuditEvent(ctx.db, {
+      companyId: req.companyId!,
+      actorType: "human",
+      eventType: "governance.approval_resolved",
+      entityType: "approval_request",
+      entityId: parsed.data.approvalId,
+      payload: resolution
+    });
+
+    if (resolution.execution.applied && resolution.execution.entityType && resolution.execution.entityId) {
+      await appendAuditEvent(ctx.db, {
+        companyId: req.companyId!,
+        actorType: "human",
+        eventType:
+          resolution.execution.entityType === "agent" ? "agent.hired_from_approval" : "goal.activated_from_approval",
+        entityType: resolution.execution.entityType,
+        entityId: resolution.execution.entityId,
+        payload: resolution.execution.entity ?? { id: resolution.execution.entityId }
+      });
+    }
+
+    const approval = await getApprovalRequest(ctx.db, req.companyId!, parsed.data.approvalId);
+    if (approval) {
+      ctx.realtimeHub?.publish(
+        createGovernanceRealtimeEvent(req.companyId!, {
+          type: "approval.resolved",
+          approval: serializeStoredApproval(approval)
+        })
+      );
+      await publishOfficeOccupantForApproval(ctx.db, ctx.realtimeHub, req.companyId!, approval.id);
+      if (approval.requestedByAgentId) {
+        await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, approval.requestedByAgentId);
+      }
+    }
+
+    if (resolution.execution.entityType === "agent" && resolution.execution.entityId) {
+      await publishOfficeOccupantForAgent(ctx.db, ctx.realtimeHub, req.companyId!, resolution.execution.entityId);
+    }
+
+    return sendOk(res, resolution);
+  });
+
+  return router;
+}
+
+function parsePayload(payloadJson: string) {
+  try {
+    const parsed = JSON.parse(payloadJson) as unknown;
+    return typeof parsed === "object" && parsed !== null ? parsed : {};
+  } catch {
+    return {};
+  }
+}