bopodev-api 0.1.12 → 0.1.13

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,39 @@ 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 { runPluginHook } from "./plugin-runtime";
 
 type HeartbeatRunTrigger = "manual" | "scheduler";
 type HeartbeatRunMode = "default" | "resume" | "redo";
+type HeartbeatProviderType =
+  | "claude_code"
+  | "codex"
+  | "cursor"
+  | "opencode"
+  | "openai_api"
+  | "anthropic_api"
+  | "http"
+  | "shell";
 
 type ActiveHeartbeatRun = {
   companyId: string;
@@ -87,7 +111,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 +138,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 +256,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 +291,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 +315,12 @@ export async function runHeartbeatForAgent(
         sourceRunId: options?.sourceRunId ?? null
       }
     });
+    publishHeartbeatRunStatus(options?.realtimeHub, {
+      companyId,
+      runId,
+      status: "started",
+      message: "Heartbeat started."
+    });
   }
 
   if (!budgetCheck.allowed) {
@@ -318,14 +370,149 @@ 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 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);
+    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 +534,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 +571,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 +646,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 +674,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 +719,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,14 +762,78 @@ 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 parsedOutcome = ExecutionOutcomeSchema.safeParse(execution.outcome);
     executionOutcome = parsedOutcome.success ? parsedOutcome.data : null;
+    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.tokenInput > 0 || execution.tokenOutput > 0 || execution.usdCost > 0) {
       await appendCost(db, {
@@ -613,6 +922,23 @@ export async function runHeartbeatForAgent(
       });
     }
 
+    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 +947,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 +1056,8 @@ export async function runHeartbeatForAgent(
         diagnostics: {
           stateParseError,
           requestId: options?.requestId,
-          trigger: runTrigger
+          trigger: runTrigger,
+          pluginFailures: pluginFailureSummary
         }
       }
     });
@@ -655,6 +1067,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,
@@ -688,6 +1117,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 +1146,8 @@ export async function runHeartbeatForAgent(
         diagnostics: {
           stateParseError,
           requestId: options?.requestId,
-          trigger: runTrigger
+          trigger: runTrigger,
+          pluginFailures: pluginFailureSummary
         }
       }
     });
@@ -731,6 +1168,7 @@ export async function runHeartbeatForAgent(
       });
     }
   } finally {
+    await transcriptWriteQueue;
     unregisterActiveHeartbeatRun(runId);
     try {
       await releaseClaimedIssues(db, companyId, issueIds);
@@ -899,9 +1337,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 +1368,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 +1449,7 @@ async function buildHeartbeatContext(
       managerAgentId: input.managerAgentId
     },
     state: input.state,
+    memoryContext: input.memoryContext,
     runtime: input.runtime,
     goalContext: {
       companyGoals: activeCompanyGoals,
@@ -983,7 +1465,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 +1599,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 +1834,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 +1922,7 @@ class AdapterExecutionCancelledError extends Error {
 }
 
 function resolveAdapterWatchdogTimeoutMs(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   runtime:
     | {
         timeoutMs?: number;
@@ -1331,7 +1939,7 @@ function resolveAdapterWatchdogTimeoutMs(
 }
 
 function estimateProviderExecutionBudgetMs(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   runtime:
     | {
         timeoutMs?: number;
@@ -1351,32 +1959,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(
@@ -1550,7 +2152,7 @@ function resolveClaudeApiKey() {
 }
 
 function summarizeRuntimeLaunch(
-  providerType: "claude_code" | "codex" | "cursor" | "opencode" | "http" | "shell",
+  providerType: HeartbeatProviderType,
   runtime:
     | {
         command?: string;
@@ -1636,7 +2238,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) {