bopodev-api 0.1.12 → 0.1.14

package/src/services/heartbeat-service.ts

@@ -1,4 +1,5 @@
 import { mkdir } from "node:fs/promises";
+import { resolve } from "node:path";
 import { and, desc, eq, inArray, sql } from "drizzle-orm";
 import { nanoid } from "nanoid";
 import { resolveAdapter } from "bopodev-agent-sdk";
@@ -11,16 +12,41 @@ import {
   type ExecutionOutcome
 } from "bopodev-contracts";
 import type { BopoDb } from "bopodev-db";
-import { agents, appendActivity, companies, goals, heartbeatRuns, issues, projects } from "bopodev-db";
+import {
+  agents,
+  appendActivity,
+  appendHeartbeatRunMessages,
+  companies,
+  goals,
+  heartbeatRuns,
+  issueAttachments,
+  issues,
+  projects
+} from "bopodev-db";
 import { appendAuditEvent, appendCost } from "bopodev-db";
 import { parseRuntimeConfigFromAgentRow } from "../lib/agent-config";
+import { resolveProjectWorkspacePath } from "../lib/instance-paths";
 import { getProjectWorkspaceMap, hasText, resolveAgentFallbackWorkspace } from "../lib/workspace-policy";
 import type { RealtimeHub } from "../realtime/hub";
+import { createHeartbeatRunsRealtimeEvent } from "../realtime/heartbeat-runs";
 import { publishOfficeOccupantForAgent } from "../realtime/office-space";
 import { checkAgentBudget } from "./budget-service";
+import { appendDurableFact, loadAgentMemoryContext, persistHeartbeatMemory } from "./memory-file-service";
+import { calculateModelPricedUsdCost } from "./model-pricing";
+import { runPluginHook } from "./plugin-runtime";
 
 type HeartbeatRunTrigger = "manual" | "scheduler";
 type HeartbeatRunMode = "default" | "resume" | "redo";
+type HeartbeatProviderType =
+  | "claude_code"
+  | "codex"
+  | "cursor"
+  | "opencode"
+  | "gemini_cli"
+  | "openai_api"
+  | "anthropic_api"
+  | "http"
+  | "shell";
 
 type ActiveHeartbeatRun = {
   companyId: string;
@@ -87,7 +113,7 @@ export async function stopHeartbeatRun(
   db: BopoDb,
   companyId: string,
   runId: string,
-  options?: { requestId?: string; actorId?: string; trigger?: HeartbeatRunTrigger }
+  options?: { requestId?: string; actorId?: string; trigger?: HeartbeatRunTrigger; realtimeHub?: RealtimeHub }
 ) {
   const runTrigger = options?.trigger ?? "manual";
   const [run] = await db
@@ -114,14 +140,22 @@ export async function stopHeartbeatRun(
     active.cancelRequestedBy = options?.actorId ?? null;
     active.abortController.abort(cancelReason);
   } else {
+    const finishedAt = new Date();
     await db
       .update(heartbeatRuns)
       .set({
         status: "failed",
-        finishedAt: new Date(),
+        finishedAt,
         message: "Heartbeat cancelled by stop request."
       })
       .where(and(eq(heartbeatRuns.companyId, companyId), eq(heartbeatRuns.id, runId)));
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "failed",
+      message: "Heartbeat cancelled by stop request.",
+      finishedAt
+    });
   }
   await appendAuditEvent(db, {
     companyId,
@@ -224,14 +258,22 @@ export async function runHeartbeatForAgent(
     });
     if (!claimed) {
       const skippedRunId = nanoid(14);
+      const skippedAt = new Date();
       await db.insert(heartbeatRuns).values({
         id: skippedRunId,
         companyId,
         agentId,
         status: "skipped",
-        finishedAt: new Date(),
+        finishedAt: skippedAt,
         message: "Heartbeat skipped: another run is already in progress for this agent."
       });
+      publishHeartbeatRunStatus(options?.realtimeHub, {
+        companyId,
+        runId: skippedRunId,
+        status: "skipped",
+        message: "Heartbeat skipped: another run is already in progress for this agent.",
+        finishedAt: skippedAt
+      });
       await appendAuditEvent(db, {
         companyId,
         actorType: "system",
@@ -251,6 +293,12 @@ export async function runHeartbeatForAgent(
       status: "skipped",
       message: "Heartbeat skipped due to budget hard-stop."
     });
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "skipped",
+      message: "Heartbeat skipped due to budget hard-stop."
+    });
   }
 
   if (budgetCheck.allowed) {
@@ -269,6 +317,12 @@ export async function runHeartbeatForAgent(
         sourceRunId: options?.sourceRunId ?? null
       }
     });
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "started",
+      message: "Heartbeat started."
+    });
   }
 
   if (!budgetCheck.allowed) {
@@ -318,14 +372,153 @@ export async function runHeartbeatForAgent(
   let executionSummary = "";
   let executionTrace: unknown = null;
   let executionOutcome: ExecutionOutcome | null = null;
+  let memoryContext: HeartbeatContext["memoryContext"] | undefined;
   let stateParseError: string | null = null;
   let runtimeLaunchSummary: ReturnType<typeof summarizeRuntimeLaunch> | null = null;
+  let primaryIssueId: string | null = null;
+  let primaryProjectId: string | null = null;
+  let transcriptSequence = 0;
+  let transcriptWriteQueue = Promise.resolve();
+  let transcriptLiveCount = 0;
+  let transcriptLiveUsefulCount = 0;
+  let transcriptLiveHighSignalCount = 0;
+  let transcriptPersistFailureReported = false;
+  let pluginFailureSummary: string[] = [];
+
+  const enqueueTranscriptEvent = (event: {
+    kind: string;
+    label?: string;
+    text?: string;
+    payload?: string;
+    signalLevel?: "high" | "medium" | "low" | "noise";
+    groupKey?: string;
+    source?: "stdout" | "stderr" | "trace_fallback";
+  }) => {
+    const sequence = transcriptSequence++;
+    const createdAt = new Date();
+    const messageId = nanoid(14);
+    const signalLevel = normalizeTranscriptSignalLevel(event.signalLevel, event.kind);
+    const groupKey = event.groupKey ?? defaultTranscriptGroupKey(event.kind, event.label);
+    const source = event.source ?? "stdout";
+    transcriptLiveCount += 1;
+    if (isUsefulTranscriptSignal(signalLevel)) {
+      transcriptLiveUsefulCount += 1;
+    }
+    if (signalLevel === "high") {
+      transcriptLiveHighSignalCount += 1;
+    }
+    transcriptWriteQueue = transcriptWriteQueue
+      .then(async () => {
+        await appendHeartbeatRunMessages(db, {
+          companyId,
+          runId,
+          messages: [
+            {
+              id: messageId,
+              sequence,
+              kind: event.kind,
+              label: event.label ?? null,
+              text: event.text ?? null,
+              payloadJson: event.payload ?? null,
+              signalLevel,
+              groupKey,
+              source,
+              createdAt
+            }
+          ]
+        });
+        options?.realtimeHub?.publish(
+          createHeartbeatRunsRealtimeEvent(companyId, {
+            type: "run.transcript.append",
+            runId,
+            messages: [
+              {
+                id: messageId,
+                runId,
+                sequence,
+                kind: normalizeTranscriptKind(event.kind),
+                label: event.label ?? null,
+                text: event.text ?? null,
+                payload: event.payload ?? null,
+                signalLevel,
+                groupKey,
+                source,
+                createdAt: createdAt.toISOString()
+              }
+            ]
+          })
+        );
+      })
+      .catch(async (error) => {
+        if (transcriptPersistFailureReported) {
+          return;
+        }
+        transcriptPersistFailureReported = true;
+        try {
+          await appendAuditEvent(db, {
+            companyId,
+            actorType: "system",
+            eventType: "heartbeat.transcript_persist_failed",
+            entityType: "heartbeat_run",
+            entityId: runId,
+            correlationId: options?.requestId ?? runId,
+            payload: {
+              agentId,
+              sequence,
+              messageId,
+              error: String(error)
+            }
+          });
+        } catch {
+          // Best effort: keep run execution resilient even when observability insert fails.
+        }
+      });
+  };
+  const emitCanonicalResultEvent = (text: string, label: "completed" | "failed") => {
+    const trimmed = text.trim();
+    if (!trimmed) {
+      return;
+    }
+    enqueueTranscriptEvent({
+      kind: "result",
+      label,
+      text: trimmed,
+      signalLevel: "high",
+      groupKey: "result",
+      source: "trace_fallback"
+    });
+  };
 
   try {
+    await runPluginHook(db, {
+      hook: "beforeClaim",
+      context: {
+        companyId,
+        agentId,
+        runId,
+        requestId: options?.requestId,
+        providerType: agent.providerType
+      },
+      failClosed: false
+    });
     const workItems = await claimIssuesForAgent(db, companyId, agentId, runId);
     issueIds = workItems.map((item) => item.id);
+    primaryIssueId = workItems[0]?.id ?? null;
+    primaryProjectId = workItems[0]?.project_id ?? null;
+    await runPluginHook(db, {
+      hook: "afterClaim",
+      context: {
+        companyId,
+        agentId,
+        runId,
+        requestId: options?.requestId,
+        providerType: agent.providerType,
+        workItemCount: workItems.length
+      },
+      failClosed: false
+    });
     await publishOfficeOccupantForAgent(db, options?.realtimeHub, companyId, agentId);
-    const adapter = resolveAdapter(agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell");
+    const adapter = resolveAdapter(agent.providerType as HeartbeatProviderType);
     const parsedState = parseAgentState(agent.stateBlob);
     state = parsedState.state;
     stateParseError = parsedState.parseError;
@@ -347,6 +540,25 @@ export async function runHeartbeatForAgent(
         ...persistedRuntime.runtimeEnv,
         ...heartbeatRuntimeEnv
       },
+      onTranscriptEvent: (event: {
+        kind: string;
+        label?: string;
+        text?: string;
+        payload?: string;
+        signalLevel?: "high" | "medium" | "low" | "noise";
+        groupKey?: string;
+        source?: "stdout" | "stderr" | "trace_fallback";
+      }) => {
+        enqueueTranscriptEvent({
+          kind: event.kind,
+          label: event.label,
+          text: event.text,
+          payload: event.payload,
+          signalLevel: event.signalLevel,
+          groupKey: event.groupKey,
+          source: event.source
+        });
+      },
       model: persistedRuntime.runtimeModel,
       thinkingEffort: persistedRuntime.runtimeThinkingEffort,
       bootstrapPrompt: persistedRuntime.bootstrapPrompt,
@@ -365,15 +577,20 @@ export async function runHeartbeatForAgent(
       ...state,
       runtime: workspaceResolution.runtime
     };
+    memoryContext = await loadAgentMemoryContext({
+      companyId,
+      agentId
+    });
 
-    const context = await buildHeartbeatContext(db, companyId, {
+    let context = await buildHeartbeatContext(db, companyId, {
       agentId,
       agentName: agent.name,
       agentRole: agent.role,
       managerAgentId: agent.managerAgentId,
-      providerType: agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+      providerType: agent.providerType as HeartbeatProviderType,
       heartbeatRunId: runId,
       state,
+      memoryContext,
       runtime: workspaceResolution.runtime,
       workItems
     });
@@ -435,7 +652,7 @@ export async function runHeartbeatForAgent(
     if (
       resolveControlPlanePreflightEnabled() &&
       shouldRequireControlPlanePreflight(
-        agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+        agent.providerType as HeartbeatProviderType,
         workItems.length
       )
     ) {
@@ -463,7 +680,7 @@ export async function runHeartbeatForAgent(
     }
 
     runtimeLaunchSummary = summarizeRuntimeLaunch(
-      agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+      agent.providerType as HeartbeatProviderType,
       workspaceResolution.runtime
     );
     await appendAuditEvent(db, {
@@ -508,6 +725,40 @@ export async function runHeartbeatForAgent(
       abortController: activeRunAbort
     });
 
+    const beforeAdapterHook = await runPluginHook(db, {
+      hook: "beforeAdapterExecute",
+      context: {
+        companyId,
+        agentId,
+        runId,
+        requestId: options?.requestId,
+        providerType: agent.providerType,
+        workItemCount: workItems.length,
+        runtime: {
+          command: workspaceResolution.runtime.command,
+          cwd: workspaceResolution.runtime.cwd
+        }
+      },
+      failClosed: true
+    });
+    if (beforeAdapterHook.blocked) {
+      pluginFailureSummary = beforeAdapterHook.failures;
+      throw new Error(`Plugin policy blocked adapter execution: ${beforeAdapterHook.failures.join(" | ")}`);
+    }
+    if (beforeAdapterHook.promptAppend && beforeAdapterHook.promptAppend.trim().length > 0) {
+      const existingPrompt = context.runtime?.bootstrapPrompt ?? "";
+      const nextPrompt = existingPrompt.trim().length > 0
+        ? `${existingPrompt}\n\n${beforeAdapterHook.promptAppend}`
+        : beforeAdapterHook.promptAppend;
+      context = {
+        ...context,
+        runtime: {
+          ...(context.runtime ?? {}),
+          bootstrapPrompt: nextPrompt
+        }
+      };
+    }
+
     const execution = await executeAdapterWithWatchdog({
       execute: (abortSignal) =>
         adapter.execute({
@@ -517,31 +768,103 @@ export async function runHeartbeatForAgent(
             abortSignal
           }
         }),
-      providerType: agent.providerType as "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+      providerType: agent.providerType as HeartbeatProviderType,
       runtime: workspaceResolution.runtime,
       externalAbortSignal: activeRunAbort.signal
     });
     executionSummary = execution.summary;
+    const afterAdapterHook = await runPluginHook(db, {
+      hook: "afterAdapterExecute",
+      context: {
+        companyId,
+        agentId,
+        runId,
+        requestId: options?.requestId,
+        providerType: agent.providerType,
+        status: execution.status,
+        summary: execution.summary,
+        trace: execution.trace ?? null,
+        outcome: execution.outcome ?? null
+      },
+      failClosed: false
+    });
+    if (afterAdapterHook.failures.length > 0) {
+      pluginFailureSummary = [...pluginFailureSummary, ...afterAdapterHook.failures];
+    }
+    emitCanonicalResultEvent(executionSummary, "completed");
     executionTrace = execution.trace ?? null;
+    const runtimeModelId = resolveRuntimeModelId({
+      runtimeModel: persistedRuntime.runtimeModel,
+      stateBlob: agent.stateBlob
+    });
+    const effectivePricingProviderType = execution.pricingProviderType ?? agent.providerType;
+    const effectivePricingModelId = execution.pricingModelId ?? runtimeModelId;
+    const costDecision = await appendFinishedRunCostEntry({
+      db,
+      companyId,
+      providerType: agent.providerType,
+      runtimeModelId: effectivePricingModelId ?? runtimeModelId,
+      pricingProviderType: effectivePricingProviderType,
+      pricingModelId: effectivePricingModelId,
+      tokenInput: execution.tokenInput,
+      tokenOutput: execution.tokenOutput,
+      issueId: primaryIssueId,
+      projectId: primaryProjectId,
+      agentId,
+      status: execution.status
+    });
+    const executionUsdCost = costDecision.usdCost;
     const parsedOutcome = ExecutionOutcomeSchema.safeParse(execution.outcome);
     executionOutcome = parsedOutcome.success ? parsedOutcome.data : null;
-
-    if (execution.tokenInput > 0 || execution.tokenOutput > 0 || execution.usdCost > 0) {
-      await appendCost(db, {
-        companyId,
-        providerType: agent.providerType,
-        tokenInput: execution.tokenInput,
-        tokenOutput: execution.tokenOutput,
-        usdCost: execution.usdCost.toFixed(6),
-        issueId: workItems[0]?.id ?? null,
-        projectId: workItems[0]?.project_id ?? null,
-        agentId
-      });
+    const persistedMemory = await persistHeartbeatMemory({
+      companyId,
+      agentId,
+      runId,
+      status: execution.status,
+      summary: execution.summary,
+      outcomeKind: executionOutcome?.kind ?? null
+    });
+    await appendAuditEvent(db, {
+      companyId,
+      actorType: "system",
+      eventType: "heartbeat.memory_updated",
+      entityType: "heartbeat_run",
+      entityId: runId,
+      correlationId: options?.requestId ?? runId,
+      payload: {
+        agentId,
+        memoryRoot: persistedMemory.memoryRoot,
+        dailyNotePath: persistedMemory.dailyNotePath,
+        candidateFacts: persistedMemory.candidateFacts
+      }
+    });
+    if (execution.status === "ok") {
+      for (const fact of persistedMemory.candidateFacts) {
+        const targetFile = await appendDurableFact({
+          companyId,
+          agentId,
+          fact,
+          sourceRunId: runId
+        });
+        await appendAuditEvent(db, {
+          companyId,
+          actorType: "system",
+          eventType: "heartbeat.memory_fact_promoted",
+          entityType: "heartbeat_run",
+          entityId: runId,
+          correlationId: options?.requestId ?? runId,
+          payload: {
+            agentId,
+            fact,
+            targetFile
+          }
+        });
+      }
     }
 
     if (
       execution.nextState ||
-      execution.usdCost > 0 ||
+      executionUsdCost > 0 ||
       execution.tokenInput > 0 ||
       execution.tokenOutput > 0 ||
       execution.status !== "skipped"
@@ -550,7 +873,8 @@ export async function runHeartbeatForAgent(
         .update(agents)
         .set({
           stateBlob: JSON.stringify(execution.nextState ?? state),
-          usedBudgetUsd: sql`${agents.usedBudgetUsd} + ${execution.usdCost}`,
+          runtimeModel: effectivePricingModelId ?? persistedRuntime.runtimeModel ?? null,
+          usedBudgetUsd: sql`${agents.usedBudgetUsd} + ${executionUsdCost}`,
           tokenUsage: sql`${agents.tokenUsage} + ${execution.tokenInput + execution.tokenOutput}`,
           updatedAt: new Date()
         })
@@ -561,7 +885,7 @@ export async function runHeartbeatForAgent(
       summary: execution.summary,
       tokenInput: execution.tokenInput,
       tokenOutput: execution.tokenOutput,
-      usdCost: execution.usdCost,
+      usdCost: executionUsdCost,
       trace: executionTrace,
       outcome: executionOutcome
     });
@@ -607,12 +931,29 @@ export async function runHeartbeatForAgent(
           usage: {
             tokenInput: execution.tokenInput,
             tokenOutput: execution.tokenOutput,
-            usdCost: execution.usdCost
+            usdCost: executionUsdCost
           }
         }
       });
     }
 
+    const beforePersistHook = await runPluginHook(db, {
+      hook: "beforePersist",
+      context: {
+        companyId,
+        agentId,
+        runId,
+        requestId: options?.requestId,
+        providerType: agent.providerType,
+        status: execution.status,
+        summary: execution.summary
+      },
+      failClosed: false
+    });
+    if (beforePersistHook.failures.length > 0) {
+      pluginFailureSummary = [...pluginFailureSummary, ...beforePersistHook.failures];
+    }
+
     await db
       .update(heartbeatRuns)
       .set({
@@ -621,6 +962,91 @@ export async function runHeartbeatForAgent(
         message: execution.summary
       })
       .where(eq(heartbeatRuns.id, runId));
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: execution.status === "failed" ? "failed" : "completed",
+      message: execution.summary,
+      finishedAt: new Date()
+    });
+
+    const fallbackMessages = normalizeTraceTranscript(executionTrace);
+    const fallbackHighSignalCount = fallbackMessages.filter((message) => message.signalLevel === "high").length;
+    const shouldAppendFallback =
+      fallbackMessages.length > 0 &&
+      (transcriptLiveCount === 0 ||
+        transcriptLiveUsefulCount < 2 ||
+        transcriptLiveHighSignalCount < 1 ||
+        (transcriptLiveHighSignalCount < 2 && fallbackHighSignalCount > transcriptLiveHighSignalCount));
+    if (shouldAppendFallback) {
+      const createdAt = new Date();
+      const rows: Array<{
+        id: string;
+        sequence: number;
+        kind: "system" | "assistant" | "thinking" | "tool_call" | "tool_result" | "result" | "stderr";
+        label: string | null;
+        text: string | null;
+        payloadJson: string | null;
+        signalLevel: "high" | "medium" | "low" | "noise";
+        groupKey: string | null;
+        source: "trace_fallback";
+        createdAt: Date;
+      }> = fallbackMessages.map((message) => ({
+        id: nanoid(14),
+        sequence: transcriptSequence++,
+        kind: message.kind,
+        label: message.label ?? null,
+        text: message.text ?? null,
+        payloadJson: message.payload ?? null,
+        signalLevel: message.signalLevel,
+        groupKey: message.groupKey ?? null,
+        source: "trace_fallback",
+        createdAt
+      }));
+      await appendHeartbeatRunMessages(db, {
+        companyId,
+        runId,
+        messages: rows
+      });
+      options?.realtimeHub?.publish(
+        createHeartbeatRunsRealtimeEvent(companyId, {
+          type: "run.transcript.append",
+          runId,
+          messages: rows.map((row) => ({
+            id: row.id,
+            runId,
+            sequence: row.sequence,
+            kind: normalizeTranscriptKind(row.kind),
+            label: row.label,
+            text: row.text,
+            payload: row.payloadJson,
+            signalLevel: row.signalLevel ?? undefined,
+            groupKey: row.groupKey ?? undefined,
+            source: row.source ?? undefined,
+            createdAt: row.createdAt.toISOString()
+          }))
+        })
+      );
+    }
+
+    const afterPersistHook = await runPluginHook(db, {
+      hook: "afterPersist",
+      context: {
+        companyId,
+        agentId,
+        runId,
+        requestId: options?.requestId,
+        providerType: agent.providerType,
+        status: execution.status,
+        summary: execution.summary,
+        trace: executionTrace,
+        outcome: executionOutcome
+      },
+      failClosed: false
+    });
+    if (afterPersistHook.failures.length > 0) {
+      pluginFailureSummary = [...pluginFailureSummary, ...afterPersistHook.failures];
+    }
 
     await appendAuditEvent(db, {
       companyId,
@@ -645,7 +1071,8 @@ export async function runHeartbeatForAgent(
         diagnostics: {
           stateParseError,
           requestId: options?.requestId,
-          trigger: runTrigger
+          trigger: runTrigger,
+          pluginFailures: pluginFailureSummary
         }
       }
     });
@@ -655,6 +1082,23 @@ export async function runHeartbeatForAgent(
       classified.type === "cancelled"
         ? "Heartbeat cancelled by stop request."
         : `Heartbeat failed (${classified.type}): ${classified.message}`;
+    emitCanonicalResultEvent(executionSummary, "failed");
+    const pluginErrorHook = await runPluginHook(db, {
+      hook: "onError",
+      context: {
+        companyId,
+        agentId,
+        runId,
+        requestId: options?.requestId,
+        providerType: agent.providerType,
+        error: String(error),
+        summary: executionSummary
+      },
+      failClosed: false
+    });
+    if (pluginErrorHook.failures.length > 0) {
+      pluginFailureSummary = [...pluginFailureSummary, ...pluginErrorHook.failures];
+    }
     if (!executionTrace && classified.type === "cancelled") {
       executionTrace = {
         command: runtimeLaunchSummary?.command ?? null,
@@ -680,6 +1124,24 @@ export async function runHeartbeatForAgent(
         cwd: runtimeLaunchSummary.cwd ?? null
       };
     }
+    const runtimeModelId = resolveRuntimeModelId({
+      runtimeModel: persistedRuntime.runtimeModel,
+      stateBlob: agent.stateBlob
+    });
+    await appendFinishedRunCostEntry({
+      db,
+      companyId,
+      providerType: agent.providerType,
+      runtimeModelId,
+      pricingProviderType: agent.providerType,
+      pricingModelId: runtimeModelId,
+      tokenInput: 0,
+      tokenOutput: 0,
+      issueId: primaryIssueId,
+      projectId: primaryProjectId,
+      agentId,
+      status: "failed"
+    });
     await db
       .update(heartbeatRuns)
       .set({
@@ -688,6 +1150,13 @@ export async function runHeartbeatForAgent(
         message: executionSummary
       })
       .where(eq(heartbeatRuns.id, runId));
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "failed",
+      message: executionSummary,
+      finishedAt: new Date()
+    });
     await appendAuditEvent(db, {
       companyId,
       actorType: "system",
@@ -710,7 +1179,8 @@ export async function runHeartbeatForAgent(
         diagnostics: {
           stateParseError,
           requestId: options?.requestId,
-          trigger: runTrigger
+          trigger: runTrigger,
+          pluginFailures: pluginFailureSummary
         }
       }
     });
@@ -731,6 +1201,7 @@ export async function runHeartbeatForAgent(
       });
     }
   } finally {
+    await transcriptWriteQueue;
     unregisterActiveHeartbeatRun(runId);
     try {
       await releaseClaimedIssues(db, companyId, issueIds);
@@ -899,9 +1370,10 @@ async function buildHeartbeatContext(
     agentName: string;
     agentRole: string;
     managerAgentId: string | null;
-    providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell";
+    providerType: HeartbeatProviderType;
     heartbeatRunId: string;
     state: AgentState;
+    memoryContext?: HeartbeatContext["memoryContext"];
     runtime?: { command?: string; args?: string[]; cwd?: string; timeoutMs?: number };
     workItems: Array<{
       id: string;
@@ -929,6 +1401,48 @@ async function buildHeartbeatContext(
           .where(and(eq(projects.companyId, companyId), inArray(projects.id, projectIds)))
       : [];
   const projectNameById = new Map(projectRows.map((row) => [row.id, row.name]));
+  const projectWorkspaceMap = await getProjectWorkspaceMap(db, companyId, projectIds);
+  const issueIds = input.workItems.map((item) => item.id);
+  const attachmentRows =
+    issueIds.length > 0
+      ? await db
+          .select({
+            id: issueAttachments.id,
+            issueId: issueAttachments.issueId,
+            projectId: issueAttachments.projectId,
+            fileName: issueAttachments.fileName,
+            mimeType: issueAttachments.mimeType,
+            fileSizeBytes: issueAttachments.fileSizeBytes,
+            relativePath: issueAttachments.relativePath
+          })
+          .from(issueAttachments)
+          .where(and(eq(issueAttachments.companyId, companyId), inArray(issueAttachments.issueId, issueIds)))
+      : [];
+  const attachmentsByIssue = new Map<
+    string,
+    Array<{
+      id: string;
+      fileName: string;
+      mimeType: string | null;
+      fileSizeBytes: number;
+      relativePath: string;
+      absolutePath: string;
+    }>
+  >();
+  for (const row of attachmentRows) {
+    const projectWorkspace = projectWorkspaceMap.get(row.projectId) ?? resolveProjectWorkspacePath(companyId, row.projectId);
+    const absolutePath = resolve(projectWorkspace, row.relativePath);
+    const existing = attachmentsByIssue.get(row.issueId) ?? [];
+    existing.push({
+      id: row.id,
+      fileName: row.fileName,
+      mimeType: row.mimeType,
+      fileSizeBytes: row.fileSizeBytes,
+      relativePath: row.relativePath,
+      absolutePath
+    });
+    attachmentsByIssue.set(row.issueId, existing);
+  }
   const goalRows = await db
     .select({
       id: goals.id,
@@ -968,6 +1482,7 @@ async function buildHeartbeatContext(
       managerAgentId: input.managerAgentId
     },
     state: input.state,
+    memoryContext: input.memoryContext,
     runtime: input.runtime,
     goalContext: {
       companyGoals: activeCompanyGoals,
@@ -983,7 +1498,8 @@ async function buildHeartbeatContext(
       status: item.status,
       priority: item.priority,
       labels: parseStringArray(item.labels_json),
-      tags: parseStringArray(item.tags_json)
+      tags: parseStringArray(item.tags_json),
+      attachments: attachmentsByIssue.get(item.id) ?? []
     }))
   };
 }
@@ -1116,6 +1632,131 @@ function readTraceString(trace: unknown, key: string) {
   return typeof value === "string" && value.trim().length > 0 ? value : null;
 }
 
+function normalizeTraceTranscript(trace: unknown) {
+  type NormalizedTranscriptMessage = {
+    kind: "system" | "assistant" | "thinking" | "tool_call" | "tool_result" | "result" | "stderr";
+    label: string | undefined;
+    text: string | undefined;
+    payload: string | undefined;
+    signalLevel: "high" | "medium" | "low" | "noise";
+    groupKey: string | undefined;
+  };
+  if (!trace || typeof trace !== "object") {
+    return [] as NormalizedTranscriptMessage[];
+  }
+  const transcript = (trace as Record<string, unknown>).transcript;
+  if (!Array.isArray(transcript)) {
+    return [];
+  }
+  const normalized: NormalizedTranscriptMessage[] = [];
+  for (const entry of transcript) {
+    if (!entry || typeof entry !== "object") {
+      continue;
+    }
+    const record = entry as Record<string, unknown>;
+    const kind = normalizeTranscriptKind(String(record.kind ?? "system"));
+    const label = typeof record.label === "string" ? record.label : undefined;
+    normalized.push({
+      kind,
+      label: typeof record.label === "string" ? record.label : undefined,
+      text: typeof record.text === "string" ? record.text : undefined,
+      payload: typeof record.payload === "string" ? record.payload : undefined,
+      signalLevel: normalizeTranscriptSignalLevel(
+        typeof record.signalLevel === "string" ? (record.signalLevel as "high" | "medium" | "low" | "noise") : undefined,
+        kind
+      ),
+      groupKey:
+        typeof record.groupKey === "string" && record.groupKey.trim().length > 0
+          ? record.groupKey
+          : defaultTranscriptGroupKey(kind, label)
+    });
+  }
+  return normalized;
+}
+
+function normalizeTranscriptKind(
+  value: string
+): "system" | "assistant" | "thinking" | "tool_call" | "tool_result" | "result" | "stderr" {
+  const normalized = value.trim().toLowerCase();
+  if (
+    normalized === "system" ||
+    normalized === "assistant" ||
+    normalized === "thinking" ||
+    normalized === "tool_call" ||
+    normalized === "tool_result" ||
+    normalized === "result" ||
+    normalized === "stderr"
+  ) {
+    return normalized;
+  }
+  return "system";
+}
+
+function defaultTranscriptGroupKey(kind: string, label?: string) {
+  if (kind === "tool_call" || kind === "tool_result") {
+    return `tool:${(label ?? "unknown").trim().toLowerCase()}`;
+  }
+  if (kind === "result") {
+    return "result";
+  }
+  if (kind === "assistant") {
+    return "assistant";
+  }
+  if (kind === "stderr") {
+    return "stderr";
+  }
+  return "system";
+}
+
+function normalizeTranscriptSignalLevel(
+  value: "high" | "medium" | "low" | "noise" | undefined,
+  kind: string
+): "high" | "medium" | "low" | "noise" {
+  if (value === "high" || value === "medium" || value === "low" || value === "noise") {
+    return value;
+  }
+  if (kind === "tool_call" || kind === "tool_result" || kind === "result") {
+    return "high";
+  }
+  if (kind === "assistant") {
+    return "medium";
+  }
+  if (kind === "stderr") {
+    return "low";
+  }
+  return "noise";
+}
+
+function isUsefulTranscriptSignal(level: "high" | "medium" | "low" | "noise") {
+  return level === "high" || level === "medium";
+}
+
+function publishHeartbeatRunStatus(
+  realtimeHub: RealtimeHub | undefined,
+  input: {
+    companyId: string;
+    runId: string;
+    status: "started" | "completed" | "failed" | "skipped";
+    message?: string | null;
+    startedAt?: Date;
+    finishedAt?: Date;
+  }
+) {
+  if (!realtimeHub) {
+    return;
+  }
+  realtimeHub.publish(
+    createHeartbeatRunsRealtimeEvent(input.companyId, {
+      type: "run.status.updated",
+      runId: input.runId,
+      status: input.status,
+      message: input.message ?? null,
+      startedAt: input.startedAt?.toISOString(),
+      finishedAt: input.finishedAt?.toISOString() ?? null
+    })
+  );
+}
+
 async function resolveRuntimeWorkspaceForWorkItems(
   db: BopoDb,
   companyId: string,
@@ -1226,7 +1867,7 @@ function resolveEffectiveStaleRunThresholdMs(input: {
 
 async function executeAdapterWithWatchdog<T>(input: {
   execute: (abortSignal: AbortSignal) => Promise<T>;
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell";
+  providerType: HeartbeatProviderType;
   externalAbortSignal?: AbortSignal;
   runtime:
     | {
@@ -1314,7 +1955,7 @@ class AdapterExecutionCancelledError extends Error {
 }
 
 function resolveAdapterWatchdogTimeoutMs(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   runtime:
     | {
         timeoutMs?: number;
@@ -1331,7 +1972,7 @@ function resolveAdapterWatchdogTimeoutMs(
 }
 
 function estimateProviderExecutionBudgetMs(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   runtime:
     | {
         timeoutMs?: number;
@@ -1351,32 +1992,26 @@ function estimateProviderExecutionBudgetMs(
 }
 
 function resolveRuntimeAttemptTimeoutMs(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   configuredTimeoutMs: number | undefined
 ) {
   if (Number.isFinite(configuredTimeoutMs) && (configuredTimeoutMs ?? 0) > 0) {
     return Math.floor(configuredTimeoutMs ?? 0);
   }
-  if (providerType === "claude_code") {
-    return 90_000;
-  }
-  if (providerType === "codex") {
-    return 5 * 60 * 1000;
-  }
-  if (providerType === "cursor") {
-    return 30_000;
+  if (providerType === "claude_code" || providerType === "codex" || providerType === "opencode" || providerType === "cursor") {
+    return 15 * 60 * 1000;
   }
-  return 45_000;
+  return 15 * 60 * 1000;
 }
 
 function resolveRuntimeRetryCount(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   configuredRetryCount: number | undefined
 ) {
   if (Number.isFinite(configuredRetryCount)) {
     return Math.max(0, Math.min(2, Math.floor(configuredRetryCount ?? 0)));
   }
-  return providerType === "codex" ? 1 : 0;
+  return providerType === "codex" || providerType === "opencode" ? 1 : 0;
 }
 
 function mergeRuntimeForExecution(
@@ -1520,6 +2155,7 @@ function buildHeartbeatRuntimeEnv(input: {
     BOPODEV_RUN_ID: input.heartbeatRunId,
     BOPODEV_FORCE_MANAGED_CODEX_HOME: "false",
     BOPODEV_API_BASE_URL: apiBaseUrl,
+    BOPODEV_API_URL: apiBaseUrl,
     BOPODEV_ACTOR_TYPE: "agent",
     BOPODEV_ACTOR_ID: input.agentId,
     BOPODEV_ACTOR_COMPANIES: input.companyId,
@@ -1533,7 +2169,9 @@ function buildHeartbeatRuntimeEnv(input: {
 }
 
 function resolveControlPlaneApiBaseUrl() {
-  const configured = resolveControlPlaneProcessEnv("API_BASE_URL") ?? process.env.NEXT_PUBLIC_API_URL;
+  // Agent runtimes must call the control-plane API directly; do not inherit
+  // browser-facing NEXT_PUBLIC_API_URL (can point to non-runtime endpoints).
+  const configured = resolveControlPlaneProcessEnv("API_BASE_URL");
   return normalizeControlPlaneApiBaseUrl(configured) ?? "http://127.0.0.1:4020";
 }
 
@@ -1550,7 +2188,7 @@ function resolveClaudeApiKey() {
 }
 
 function summarizeRuntimeLaunch(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   runtime:
     | {
         command?: string;
@@ -1636,7 +2274,7 @@ function validateControlPlaneRuntimeEnv(runtimeEnv: Record<string, string>, runI
 }
 
 function shouldRequireControlPlanePreflight(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   workItemCount: number
 ) {
   if (workItemCount < 1) {
@@ -1646,7 +2284,8 @@ function shouldRequireControlPlanePreflight(
     providerType === "codex" ||
     providerType === "claude_code" ||
     providerType === "cursor" ||
-    providerType === "opencode"
+    providerType === "opencode" ||
+    providerType === "gemini_cli"
   );
 }
 
@@ -1765,6 +2404,68 @@ function resolveControlPlaneHeaders(runtimeEnv: Record<string, string>):
   return { ok: true, headers: jsonHeadersResult.data };
 }
 
+function resolveRuntimeModelId(input: { runtimeModel?: string; stateBlob?: string | null }) {
+  const runtimeModel = input.runtimeModel?.trim();
+  if (runtimeModel) {
+    return runtimeModel;
+  }
+  if (!input.stateBlob) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(input.stateBlob) as { runtime?: { model?: unknown } };
+    const modelId = parsed.runtime?.model;
+    return typeof modelId === "string" && modelId.trim().length > 0 ? modelId.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+async function appendFinishedRunCostEntry(input: {
+  db: BopoDb;
+  companyId: string;
+  providerType: string;
+  runtimeModelId: string | null;
+  pricingProviderType?: string | null;
+  pricingModelId?: string | null;
+  tokenInput: number;
+  tokenOutput: number;
+  issueId?: string | null;
+  projectId?: string | null;
+  agentId?: string | null;
+  status: "ok" | "failed" | "skipped";
+}) {
+  const pricingDecision = await calculateModelPricedUsdCost({
+    db: input.db,
+    companyId: input.companyId,
+    providerType: input.providerType,
+    pricingProviderType: input.pricingProviderType ?? input.providerType,
+    modelId: input.pricingModelId ?? input.runtimeModelId,
+    tokenInput: input.tokenInput,
+    tokenOutput: input.tokenOutput
+  });
+
+  const shouldPersist = input.status === "ok" || input.status === "failed";
+  if (shouldPersist) {
+    await appendCost(input.db, {
+      companyId: input.companyId,
+      providerType: input.providerType,
+      runtimeModelId: input.runtimeModelId,
+      pricingProviderType: pricingDecision.pricingProviderType,
+      pricingModelId: pricingDecision.pricingModelId,
+      pricingSource: pricingDecision.pricingSource,
+      tokenInput: input.tokenInput,
+      tokenOutput: input.tokenOutput,
+      usdCost: pricingDecision.usdCost.toFixed(6),
+      issueId: input.issueId ?? null,
+      projectId: input.projectId ?? null,
+      agentId: input.agentId ?? null
+    });
+  }
+
+  return pricingDecision;
+}
+
 function isHeartbeatDue(cronExpression: string, lastRunAt: Date | null, now: Date) {
   const normalizedNow = truncateToMinute(now);
   if (!matchesCronExpression(cronExpression, normalizedNow)) {