bopodev-agent-sdk 0.1.25 → 0.1.27

package/src/adapters.ts

@@ -8,10 +8,16 @@ import type {
   AgentAdapter,
   AgentProviderType,
   AgentRuntimeConfig,
-  HeartbeatContext
+  HeartbeatContext,
+  HeartbeatPromptMode
 } from "./types";
 import { ExecutionOutcomeSchema, type ExecutionOutcome } from "bopodev-contracts";
-import { checkRuntimeCommandHealth, containsRateLimitFailure, executeAgentRuntime, executePromptRuntime } from "./runtime-core";
+import {
+  checkRuntimeCommandHealth,
+  containsUsageLimitHardStopFailure,
+  executeAgentRuntime,
+  executePromptRuntime
+} from "./runtime-core";
 import {
   parseClaudeStreamOutput,
   parseCursorStreamOutput,
@@ -24,6 +30,10 @@ import {
   resolveDirectApiCredentials,
   type DirectApiProvider
 } from "./runtime-http";
+import {
+  classifyProviderFailure as classifyProviderFailureByProvider,
+  normalizeProviderFailureDetail as normalizeProviderFailureDetailByProvider
+} from "./provider-failures";
 import { homedir } from "node:os";
 import { basename, join, resolve } from "node:path";
 
@@ -42,8 +52,39 @@ function toOutcome(outcome: ExecutionOutcome): ExecutionOutcome {
   return ExecutionOutcomeSchema.parse(outcome);
 }
 
-function isRateLimitedRuntimeFailure(runtime: { stdout: string; stderr: string }, detail?: string) {
-  return containsRateLimitFailure(`${detail ?? ""}\n${runtime.stderr}\n${runtime.stdout}`);
+function isProviderUsageLimitedRuntimeFailure(runtime: { stdout: string; stderr: string }, detail?: string) {
+  return containsUsageLimitHardStopFailure(`${detail ?? ""}\n${runtime.stderr}\n${runtime.stdout}`);
+}
+
+function buildProviderUsageLimitedDispositionHint(
+  provider: string,
+  detail: string
+): NonNullable<AdapterExecutionResult["dispositionHint"]> {
+  const normalizedDetail = detail.replace(/\s+/g, " ").trim();
+  const message = normalizedDetail ? `${provider} usage limit reached: ${normalizedDetail}` : `${provider} usage limit reached.`;
+  return {
+    kind: "provider_usage_limited",
+    persistStatus: "skipped",
+    pauseAgent: true,
+    notifyBoard: true,
+    message
+  };
+}
+
+export function normalizeProviderFailureDetail(provider: AgentProviderType, detail: string) {
+  return normalizeProviderFailureDetailByProvider(provider, detail);
+}
+
+export function classifyProviderFailure(
+  provider: AgentProviderType,
+  input: {
+    detail: string;
+    stderr?: string;
+    stdout?: string;
+    failureType?: string | null;
+  }
+): ReturnType<typeof classifyProviderFailureByProvider> {
+  return classifyProviderFailureByProvider(provider, input);
 }
 
 type RuntimeParsedUsage = {
@@ -130,6 +171,53 @@ function usageTokenInputTotal(usage: RuntimeParsedUsage | undefined) {
   return Math.max(0, usage.tokenInput ?? 0);
 }
 
+function resolveFinalRunOutputContractDetail(input: {
+  provider: string;
+  runtime: {
+    structuredOutputDiagnostics?: {
+      finalRunOutputError?: string;
+    };
+  };
+}) {
+  const detail = input.runtime.structuredOutputDiagnostics?.finalRunOutputError?.trim();
+  return detail || `${input.provider} runtime did not return a valid final JSON object.`;
+}
+
+function createContractInvalidResult(input: {
+  context: HeartbeatContext;
+  provider: AgentProviderType;
+  summary: string;
+  tokenInput: number;
+  tokenOutput: number;
+  usdCost: number;
+  usage?: AdapterNormalizedUsage;
+  pricingProviderType?: string | null;
+  pricingModelId?: string | null;
+  trace: NonNullable<AdapterExecutionResult["trace"]>;
+  nextState: HeartbeatContext["state"];
+}): AdapterExecutionResult {
+  return {
+    status: "failed",
+    summary: input.summary,
+    tokenInput: input.tokenInput,
+    tokenOutput: input.tokenOutput,
+    usdCost: input.usdCost,
+    ...(input.usage ? { usage: input.usage } : {}),
+    pricingProviderType: input.pricingProviderType,
+    pricingModelId: input.pricingModelId,
+    outcome: toOutcome({
+      kind: "failed",
+      issueIdsTouched: issueIdsTouched(input.context),
+      actions: [{ type: "runtime.contract", status: "error", detail: input.summary }],
+      blockers: [{ code: "contract_invalid", message: input.summary, retryable: true }],
+      artifacts: [],
+      nextSuggestedState: "blocked"
+    }),
+    trace: input.trace,
+    nextState: input.nextState
+  };
+}
+
 function hasUsageMetrics(usage: RuntimeParsedUsage | undefined) {
   if (!usage) {
     return false;
@@ -372,12 +460,46 @@ export class GenericHeartbeatAdapter implements AgentAdapter {
           nextState: context.state
         };
       }
+      if (!runtime.finalRunOutput) {
+        const usage = toNormalizedUsage(runtime.parsedUsage);
+        const detail = resolveFinalRunOutputContractDetail({ provider: this.providerType, runtime });
+        return createContractInvalidResult({
+          context,
+          provider: this.providerType,
+          summary: `${this.providerType} runtime failed contract validation: ${detail}`,
+          tokenInput: usageTokenInputTotal(runtime.parsedUsage),
+          tokenOutput: runtime.parsedUsage?.tokenOutput ?? 0,
+          usdCost: runtime.parsedUsage?.usdCost ?? 0,
+          ...(usage ? { usage } : {}),
+          pricingProviderType: resolveCanonicalPricingProviderKey(this.providerType),
+          pricingModelId: context.runtime?.model?.trim() || null,
+          trace: {
+            command: runtime.commandUsed ?? context.runtime.command,
+            args: runtime.argsUsed,
+            cwd: context.runtime?.cwd,
+            exitCode: runtime.code,
+            elapsedMs: runtime.elapsedMs,
+            timedOut: runtime.timedOut,
+            failureType: "contract_invalid",
+            timeoutSource: runtime.timedOut ? "runtime" : null,
+            attemptCount: runtime.attemptCount,
+            attempts: runtime.attempts,
+            structuredOutputSource: runtime.structuredOutputSource,
+            structuredOutputDiagnostics: runtime.structuredOutputDiagnostics,
+            stdoutPreview: toPreview(runtime.stdout),
+            stderrPreview: toPreview(runtime.stderr),
+            transcript: runtime.transcript
+          },
+          nextState: context.state
+        });
+      }
       return {
         status: "ok",
         summary: runtime.parsedUsage?.summary ?? `${this.providerType} runtime finished in ${runtime.elapsedMs}ms.`,
         tokenInput: runtime.parsedUsage?.tokenInput ?? 0,
         tokenOutput: runtime.parsedUsage?.tokenOutput ?? 0,
         usdCost: runtime.parsedUsage?.usdCost ?? 0,
+        finalRunOutput: runtime.finalRunOutput,
         outcome: toOutcome({
           kind: "completed",
           issueIdsTouched: issueIdsTouched(context),
@@ -409,23 +531,27 @@ export class GenericHeartbeatAdapter implements AgentAdapter {
     }
 
     const failedUsage = resolveFailedUsage(runtime);
-    const failureDetail = resolveRuntimeFailureDetail(runtime);
-    const rateLimitedFailure = isRateLimitedRuntimeFailure(runtime, failureDetail);
+    const failure = classifyProviderFailure(this.providerType, {
+      detail: resolveRuntimeFailureDetail(runtime, this.providerType),
+      stdout: runtime.stdout,
+      stderr: runtime.stderr,
+      failureType: runtime.failureType
+    });
     return {
       status: "failed",
-      summary: runtime.parsedUsage?.summary ?? `${this.providerType} runtime failed: ${failureDetail}`,
+      summary: runtime.parsedUsage?.summary ?? `${this.providerType} runtime failed: ${failure.detail}`,
       tokenInput: failedUsage.tokenInput,
       tokenOutput: failedUsage.tokenOutput,
       usdCost: failedUsage.usdCost,
       outcome: toOutcome({
         kind: "failed",
         issueIdsTouched: issueIdsTouched(context),
-        actions: [{ type: "runtime.execute", status: "error", detail: failureDetail }],
+        actions: [{ type: "runtime.execute", status: "error", detail: failure.detail }],
         blockers: [
           {
-            code: runtime.failureType ?? "runtime_failed",
-            message: failureDetail,
-            retryable: !rateLimitedFailure
+            code: failure.blockerCode,
+            message: failure.detail,
+            retryable: failure.retryable
           }
         ],
         artifacts: [],
@@ -449,6 +575,9 @@ export class GenericHeartbeatAdapter implements AgentAdapter {
         stderrPreview: toPreview(runtime.stderr),
         transcript: runtime.transcript
       },
+      ...(failure.providerUsageLimited
+        ? { dispositionHint: buildProviderUsageLimitedDispositionHint(this.providerType, failure.detail) }
+        : {}),
       nextState: context.state
     };
   }
@@ -838,12 +967,51 @@ export async function runDirectApiWork(
   const prompt = createPrompt(context);
   const runtime = await executeDirectApiRuntime(provider, prompt, context.runtime);
   if (runtime.ok) {
+    if (!runtime.finalRunOutput) {
+      return createContractInvalidResult({
+        context,
+        provider,
+        summary: `${provider} runtime failed contract validation: ${runtime.summary ?? "Missing final JSON object."}`,
+        tokenInput: runtime.tokenInput ?? 0,
+        tokenOutput: runtime.tokenOutput ?? 0,
+        usdCost: runtime.usdCost ?? 0,
+        usage: {
+          inputTokens: runtime.tokenInput ?? 0,
+          cachedInputTokens: 0,
+          outputTokens: runtime.tokenOutput ?? 0,
+          ...(runtime.usdCost !== undefined ? { costUsd: runtime.usdCost } : {}),
+          ...(runtime.summary ? { summary: runtime.summary } : {})
+        },
+        pricingProviderType: runtime.provider,
+        pricingModelId: runtime.model,
+        trace: {
+          command: runtime.endpoint,
+          cwd: context.runtime?.cwd,
+          exitCode: runtime.statusCode,
+          elapsedMs: runtime.elapsedMs,
+          failureType: "contract_invalid",
+          usageSource: "structured",
+          attemptCount: runtime.attemptCount,
+          attempts: runtime.attempts.map((attempt) => ({
+            attempt: attempt.attempt,
+            code: attempt.statusCode || null,
+            timedOut: attempt.failureType === "timeout",
+            elapsedMs: attempt.elapsedMs,
+            signal: null,
+            forcedKill: false
+          })),
+          stdoutPreview: runtime.responsePreview
+        },
+        nextState: context.state
+      });
+    }
     return {
       status: "ok",
       summary: runtime.summary ?? `${provider} runtime finished in ${runtime.elapsedMs}ms.`,
       tokenInput: runtime.tokenInput ?? 0,
       tokenOutput: runtime.tokenOutput ?? 0,
       usdCost: runtime.usdCost ?? 0,
+      finalRunOutput: runtime.finalRunOutput,
       pricingProviderType: runtime.provider,
       pricingModelId: runtime.model,
       outcome: toOutcome({
@@ -875,12 +1043,15 @@ export async function runDirectApiWork(
       nextState: withProviderMetadata(context, provider, runtime.elapsedMs, runtime.statusCode)
     };
   }
-  const failureDetail = runtime.error ?? "direct API request failed";
-  const rateLimitedFailure =
-    runtime.failureType === "rate_limit" || containsRateLimitFailure(`${failureDetail}\n${runtime.responsePreview ?? ""}`);
+  const failure = classifyProviderFailure(provider, {
+    detail: runtime.error ?? "direct API request failed",
+    stderr: runtime.error,
+    stdout: runtime.responsePreview ?? "",
+    failureType: runtime.failureType
+  });
   return {
     status: "failed",
-    summary: `${provider} runtime failed: ${failureDetail}`,
+    summary: `${provider} runtime failed: ${failure.detail}`,
     tokenInput: 0,
     tokenOutput: 0,
     usdCost: 0,
@@ -889,11 +1060,11 @@ export async function runDirectApiWork(
     outcome: toOutcome({
       kind: "failed",
       issueIdsTouched: issueIdsTouched(context),
-      actions: [{ type: "runtime.execute", status: "error", detail: failureDetail }],
+      actions: [{ type: "runtime.execute", status: "error", detail: failure.detail }],
         blockers: [{
-          code: runtime.failureType ?? "runtime_failed",
-          message: failureDetail,
-          retryable: runtime.failureType !== "auth" && runtime.failureType !== "bad_response" && !rateLimitedFailure
+          code: failure.blockerCode,
+          message: failure.detail,
+          retryable: failure.retryable
         }],
       artifacts: [],
       nextSuggestedState: "blocked"
@@ -917,6 +1088,9 @@ export async function runDirectApiWork(
       stderrPreview: runtime.error,
       stdoutPreview: runtime.responsePreview
     },
+    ...(failure.providerUsageLimited
+      ? { dispositionHint: buildProviderUsageLimitedDispositionHint(provider, failure.detail) }
+      : {}),
     nextState: context.state
   };
 }
@@ -1042,6 +1216,40 @@ export async function runProviderWork(
         nextState: context.state
       };
     }
+    if (!runtime.finalRunOutput) {
+      const usage = toNormalizedUsage(runtime.parsedUsage);
+      const detail = resolveFinalRunOutputContractDetail({ provider, runtime });
+      return createContractInvalidResult({
+        context,
+        provider,
+        summary: `${provider} runtime failed contract validation: ${detail}`,
+        tokenInput: usageTokenInputTotal(runtime.parsedUsage),
+        tokenOutput: runtime.parsedUsage?.outputTokens ?? runtime.parsedUsage?.tokenOutput ?? 0,
+        usdCost: runtime.parsedUsage?.costUsd ?? runtime.parsedUsage?.usdCost ?? 0,
+        ...(usage ? { usage } : {}),
+        pricingProviderType,
+        pricingModelId,
+        trace: {
+          command: runtime.commandUsed ?? context.runtime?.command ?? provider,
+          args: runtime.argsUsed,
+          cwd: context.runtime?.cwd,
+          exitCode: runtime.code,
+          elapsedMs: runtime.elapsedMs,
+          timedOut: runtime.timedOut,
+          failureType: "contract_invalid",
+          timeoutSource: runtime.timedOut ? "runtime" : null,
+          usageSource: "structured",
+          attemptCount: runtime.attemptCount,
+          attempts: runtime.attempts,
+          structuredOutputSource: runtime.structuredOutputSource,
+          structuredOutputDiagnostics: runtime.structuredOutputDiagnostics,
+          stdoutPreview: toPreview(runtime.stdout),
+          stderrPreview: toPreview(runtime.stderr),
+          transcript: runtime.transcript
+        },
+        nextState: context.state
+      });
+    }
     if (provider === "claude_code" && isClaudeRunIncomplete(runtime)) {
       const detail = "Claude run reached max-turns before completing execution for this issue.";
       const usage = toNormalizedUsage(runtime.parsedUsage);
@@ -1095,6 +1303,7 @@ export async function runProviderWork(
       tokenInput,
       tokenOutput,
       usdCost,
+      finalRunOutput: runtime.finalRunOutput,
       usage,
       pricingProviderType,
       pricingModelId,
@@ -1128,11 +1337,15 @@ export async function runProviderWork(
     };
   }
   const failedUsage = resolveFailedUsage(runtime);
-  const failureDetail = resolveRuntimeFailureDetail(runtime);
-  const rateLimitedFailure = isRateLimitedRuntimeFailure(runtime, failureDetail);
+  const failure = classifyProviderFailure(provider, {
+    detail: resolveRuntimeFailureDetail(runtime, provider),
+    stdout: runtime.stdout,
+    stderr: runtime.stderr,
+    failureType: runtime.failureType
+  });
   return {
     status: "failed",
-    summary: runtime.parsedUsage?.summary ?? `${provider} runtime failed: ${failureDetail}`,
+    summary: runtime.parsedUsage?.summary ?? `${provider} runtime failed: ${failure.detail}`,
     tokenInput: failedUsage.tokenInput,
     tokenOutput: failedUsage.tokenOutput,
     usdCost: failedUsage.usdCost,
@@ -1142,12 +1355,12 @@ export async function runProviderWork(
     outcome: toOutcome({
       kind: "failed",
       issueIdsTouched: issueIdsTouched(context),
-      actions: [{ type: "runtime.execute", status: "error", detail: failureDetail }],
+      actions: [{ type: "runtime.execute", status: "error", detail: failure.detail }],
       blockers: [
         {
-          code: runtime.failureType ?? "runtime_failed",
-          message: failureDetail,
-          retryable: !rateLimitedFailure
+          code: failure.blockerCode,
+          message: failure.detail,
+          retryable: failure.retryable
         }
       ],
       artifacts: [],
@@ -1171,6 +1384,9 @@ export async function runProviderWork(
       stderrPreview: toPreview(runtime.stderr),
       transcript: runtime.transcript
     },
+    ...(failure.providerUsageLimited
+      ? { dispositionHint: buildProviderUsageLimitedDispositionHint(provider, failure.detail) }
+      : {}),
     nextState: context.state
   };
 }
@@ -1220,7 +1436,7 @@ export async function runCursorWork(
   if (
     !runtime.ok &&
     resumeState.resumeSessionId &&
-    !isRateLimitedRuntimeFailure(runtime) &&
+    !isProviderUsageLimitedRuntimeFailure(runtime) &&
     isUnknownSessionError(runtime.stderr, runtime.stdout)
   ) {
     const retry = withResolvedRuntimeUsage(
@@ -1331,7 +1547,12 @@ export async function runOpenCodeWork(context: HeartbeatContext): Promise<Adapte
     { provider: "opencode" }
   );
   const parsed = parseOpenCodeOutput(runtime.stdout);
-  if (!runtime.ok && resumeSessionId && !isRateLimitedRuntimeFailure(runtime) && isUnknownSessionError(runtime.stderr, runtime.stdout)) {
+  if (
+    !runtime.ok &&
+    resumeSessionId &&
+    !isProviderUsageLimitedRuntimeFailure(runtime) &&
+    isUnknownSessionError(runtime.stderr, runtime.stdout)
+  ) {
     const retry = await executePromptRuntime(
       context.runtime?.command ?? "opencode",
       prompt,
@@ -1426,7 +1647,7 @@ export async function runGeminiCliWork(
   if (
     !runtime.ok &&
     resumeState.resumeSessionId &&
-    !isRateLimitedRuntimeFailure(runtime) &&
+    !isProviderUsageLimitedRuntimeFailure(runtime) &&
     isGeminiUnknownSessionError(runtime.stdout, runtime.stderr)
   ) {
     const retry = withResolvedRuntimeUsage(
@@ -1535,6 +1756,7 @@ export function toProviderResult(
       forcedKill: boolean;
     }>;
     parsedUsage?: RuntimeParsedUsage;
+    finalRunOutput?: AdapterExecutionResult["finalRunOutput"];
     structuredOutputSource?: "stdout" | "stderr";
     structuredOutputDiagnostics?: {
       stdoutJsonObjectCount: number;
@@ -1550,6 +1772,8 @@ export function toProviderResult(
         | "json_missing"
         | "json_on_stderr_only"
         | "schema_or_shape_mismatch";
+      finalRunOutputStatus?: "valid" | "missing" | "malformed" | "schema_mismatch";
+      finalRunOutputError?: string;
       claudeStopReason?: string;
       claudeResultSubtype?: string;
       claudeSessionId?: string;
@@ -1626,6 +1850,41 @@ export function toProviderResult(
         nextState: applyProviderSessionState(context, provider, sessionUpdate)
       };
     }
+    if (!runtime.finalRunOutput) {
+      const usage = toNormalizedUsage(runtime.parsedUsage);
+      const detail = resolveFinalRunOutputContractDetail({ provider, runtime });
+      return createContractInvalidResult({
+        context,
+        provider,
+        summary: `${provider} runtime failed contract validation: ${detail}`,
+        tokenInput: usageTokenInputTotal(runtime.parsedUsage),
+        tokenOutput: runtime.parsedUsage?.outputTokens ?? runtime.parsedUsage?.tokenOutput ?? 0,
+        usdCost: runtime.parsedUsage?.costUsd ?? runtime.parsedUsage?.usdCost ?? 0,
+        ...(usage ? { usage } : {}),
+        pricingProviderType,
+        pricingModelId,
+        trace: {
+          command: runtime.commandUsed ?? context.runtime?.command ?? provider,
+          args: runtime.argsUsed,
+          cwd: context.runtime?.cwd,
+          exitCode: runtime.code,
+          elapsedMs: runtime.elapsedMs,
+          timedOut: runtime.timedOut,
+          failureType: "contract_invalid",
+          timeoutSource: runtime.timedOut ? "runtime" : null,
+          usageSource: "structured",
+          attemptCount: runtime.attemptCount,
+          attempts: runtime.attempts,
+          session: sessionUpdate,
+          structuredOutputSource: runtime.structuredOutputSource,
+          structuredOutputDiagnostics: runtime.structuredOutputDiagnostics,
+          stdoutPreview: toPreview(runtime.stdout),
+          stderrPreview: toPreview(runtime.stderr),
+          transcript: runtime.transcript
+        },
+        nextState: applyProviderSessionState(context, provider, sessionUpdate)
+      });
+    }
     const tokenOutput = runtime.parsedUsage?.outputTokens ?? runtime.parsedUsage?.tokenOutput ?? 0;
     const usdCost = runtime.parsedUsage?.costUsd ?? runtime.parsedUsage?.usdCost ?? 0;
     const usage = toNormalizedUsage(runtime.parsedUsage);
@@ -1636,6 +1895,7 @@ export function toProviderResult(
       tokenInput: usageTokenInputTotal(runtime.parsedUsage),
       tokenOutput,
       usdCost,
+      finalRunOutput: runtime.finalRunOutput,
       usage,
       pricingProviderType,
       pricingModelId,
@@ -1670,11 +1930,15 @@ export function toProviderResult(
     };
   }
   const failedUsage = resolveFailedUsage(runtime);
-  const failureDetail = resolveRuntimeFailureDetail(runtime);
-  const rateLimitedFailure = isRateLimitedRuntimeFailure(runtime, failureDetail);
+  const failure = classifyProviderFailure(provider, {
+    detail: resolveRuntimeFailureDetail(runtime, provider),
+    stdout: runtime.stdout,
+    stderr: runtime.stderr,
+    failureType: runtime.failureType
+  });
   return {
     status: "failed",
-    summary: runtime.parsedUsage?.summary ?? `${provider} runtime failed: ${failureDetail}`,
+    summary: runtime.parsedUsage?.summary ?? `${provider} runtime failed: ${failure.detail}`,
     tokenInput: failedUsage.tokenInput,
     tokenOutput: failedUsage.tokenOutput,
     usdCost: failedUsage.usdCost,
@@ -1684,12 +1948,12 @@ export function toProviderResult(
     outcome: toOutcome({
       kind: "failed",
       issueIdsTouched: issueIdsTouched(context),
-      actions: [{ type: "runtime.execute", status: "error", detail: failureDetail }],
+      actions: [{ type: "runtime.execute", status: "error", detail: failure.detail }],
       blockers: [
         {
-          code: runtime.failureType ?? "runtime_failed",
-          message: failureDetail,
-          retryable: !rateLimitedFailure
+          code: failure.blockerCode,
+          message: failure.detail,
+          retryable: failure.retryable
         }
       ],
       artifacts: [],
@@ -1714,6 +1978,9 @@ export function toProviderResult(
       stderrPreview: toPreview(runtime.stderr),
       transcript: runtime.transcript
     },
+    ...(failure.providerUsageLimited
+      ? { dispositionHint: buildProviderUsageLimitedDispositionHint(provider, failure.detail) }
+      : {}),
     nextState: applyProviderSessionState(context, provider, sessionUpdate)
   };
 }
@@ -1724,29 +1991,99 @@ export function resolveRuntimeFailureDetail(runtime: {
   code: number | null;
   failureType?: "timeout" | "spawn_error" | "nonzero_exit";
   attempts: Array<{ spawnErrorCode?: string }>;
-}) {
+}, provider?: AgentProviderType) {
   const stderr = runtime.stderr.trim();
+  const normalize = (detail: string) => (provider ? normalizeProviderFailureDetail(provider, detail) : detail);
   if (stderr.length > 0) {
-    return stderr;
+    return normalize(extractStructuredRuntimeErrorDetail(stderr) ?? stderr);
   }
   const lastAttempt = runtime.attempts[runtime.attempts.length - 1];
   if (runtime.failureType === "spawn_error") {
     if (lastAttempt?.spawnErrorCode) {
-      return `failed to launch runtime command (${lastAttempt.spawnErrorCode}). Verify the CLI is installed and on PATH.`;
+      return normalize(`failed to launch runtime command (${lastAttempt.spawnErrorCode}). Verify the CLI is installed and on PATH.`);
     }
-    return "failed to launch runtime command. Verify the CLI is installed and on PATH.";
+    return normalize("failed to launch runtime command. Verify the CLI is installed and on PATH.");
   }
   if (runtime.failureType === "timeout") {
-    return "timed out before completion. Increase runtimeTimeoutSec for this agent/runtime.";
+    return normalize("timed out before completion. Increase runtimeTimeoutSec for this agent/runtime.");
   }
   if (runtime.code !== null) {
-    return `process exited with code ${runtime.code} without stderr output.`;
+    return normalize(`process exited with code ${runtime.code} without stderr output.`);
   }
   const stdout = runtime.stdout.trim();
   if (stdout.length > 0) {
-    return `no stderr output; stdout preview: ${toPreview(stdout, 320)}`;
+    const structuredStdoutDetail = extractStructuredRuntimeErrorDetail(stdout);
+    if (structuredStdoutDetail) {
+      return normalize(structuredStdoutDetail);
+    }
+    return normalize(`no stderr output; stdout preview: ${toPreview(stdout, 320)}`);
   }
-  return "runtime exited without diagnostic output.";
+  return normalize("runtime exited without diagnostic output.");
+}
+
+function extractStructuredRuntimeErrorDetail(text: string) {
+  const normalized = text.trim();
+  if (!normalized) {
+    return null;
+  }
+  const candidatePayloads = collectJsonObjectCandidates(normalized);
+  for (const candidate of candidatePayloads) {
+    try {
+      const parsed = JSON.parse(candidate) as unknown;
+      const detail = extractErrorDetailFromUnknown(parsed);
+      if (detail) {
+        return detail;
+      }
+    } catch {
+      // ignore malformed JSON fragments
+    }
+  }
+  return null;
+}
+
+function collectJsonObjectCandidates(text: string) {
+  const candidates: string[] = [];
+  if (text.startsWith("{") && text.endsWith("}")) {
+    candidates.push(text);
+  }
+  for (const line of text.split(/\r?\n/)) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+      candidates.push(trimmed);
+    }
+  }
+  return candidates;
+}
+
+function extractErrorDetailFromUnknown(value: unknown): string | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const directCandidates = [
+    record.detail,
+    record.message,
+    record.summary,
+    record.reason,
+    record.error,
+    record.description
+  ];
+  for (const candidate of directCandidates) {
+    if (typeof candidate === "string" && candidate.trim()) {
+      return candidate.trim();
+    }
+  }
+  const nestedError = record.error;
+  if (nestedError && typeof nestedError === "object" && !Array.isArray(nestedError)) {
+    const nestedRecord = nestedError as Record<string, unknown>;
+    const nestedCandidates = [nestedRecord.detail, nestedRecord.message, nestedRecord.reason, nestedRecord.description];
+    for (const candidate of nestedCandidates) {
+      if (typeof candidate === "string" && candidate.trim()) {
+        return candidate.trim();
+      }
+    }
+  }
+  return null;
 }
 
 export function parseOpenCodeOutput(stdout: string) {
@@ -2280,8 +2617,66 @@ export function toEnvironmentStatus(checks: AdapterEnvironmentCheck[]): "pass" |
   return "pass";
 }
 
+function resolveHeartbeatPromptModeForPrompt(context: HeartbeatContext): HeartbeatPromptMode {
+  return context.promptMode === "compact" ? "compact" : "full";
+}
+
+/** Max chars per memory section (tacit notes, durable facts block, daily notes block). Env overrides; compact defaults to 8000. */
+function resolveMemorySectionMaxChars(mode: HeartbeatPromptMode): number | null {
+  const raw = process.env.BOPO_HEARTBEAT_PROMPT_MEMORY_MAX_CHARS?.trim();
+  if (raw) {
+    const n = Number.parseInt(raw, 10);
+    if (Number.isFinite(n) && n > 0) {
+      return n;
+    }
+  }
+  if (mode === "compact") {
+    return 8000;
+  }
+  return null;
+}
+
+function clipPromptText(text: string, max: number | null): string {
+  if (!max || text.length <= max) {
+    return text;
+  }
+  return `${text.slice(0, max)}\n…(truncated for prompt size)`;
+}
+
+const HEARTBEAT_JSON_SCHEMA_FOOTER = `At the end of your response, output exactly one JSON object on a single line and nothing else. Use this exact schema:
+{"employee_comment":"markdown update to the manager","results":["short concrete outcome"],"errors":[],"artifacts":[{"kind":"file","path":"relative/path"}]}`;
+
+function buildIdleMicroPrompt(context: HeartbeatContext): string {
+  const bootstrapPrompt = context.runtime?.bootstrapPrompt?.trim();
+  return `${bootstrapPrompt ? `${bootstrapPrompt}\n\n` : ""}Idle heartbeat (micro prompt): agent ${context.agentId} (${context.agent.name}) has no assigned issues this run. Summarize readiness in \`employee_comment\`; leave \`results\` empty unless you completed verifiable work. Use \`BOPODEV_*\` for control-plane API calls when needed.
+
+${HEARTBEAT_JSON_SCHEMA_FOOTER}
+`;
+}
+
+function formatAttachmentLine(
+  attachment: NonNullable<HeartbeatContext["workItems"][number]["attachments"]>[number],
+  mode: HeartbeatPromptMode,
+  apiBase: string
+): string {
+  const base = apiBase.replace(/\/$/, "");
+  const apiUrl = attachment.downloadPath ? `${base}${attachment.downloadPath}` : null;
+  if (mode === "compact" && apiUrl) {
+    return `    - ${attachment.fileName} | api: ${apiUrl} | path: ${attachment.absolutePath} | relative: ${attachment.relativePath}`;
+  }
+  const apiSuffix = apiUrl ? ` | api: ${apiUrl}` : "";
+  return `    - ${attachment.fileName} | path: ${attachment.absolutePath} | relative: ${attachment.relativePath}${apiSuffix}`;
+}
+
 export function createPrompt(context: HeartbeatContext) {
+  const isCommentOrderRunEarly = context.wakeContext?.reason === "issue_comment_recipient";
+  if (context.idleMicroPrompt && context.workItems.length === 0 && !isCommentOrderRunEarly) {
+    return buildIdleMicroPrompt(context);
+  }
   const bootstrapPrompt = context.runtime?.bootstrapPrompt?.trim();
+  const promptMode = resolveHeartbeatPromptModeForPrompt(context);
+  const isCompact = promptMode === "compact";
+  const memoryCap = resolveMemorySectionMaxChars(promptMode);
   const companyGoals = context.goalContext?.companyGoals.length
     ? context.goalContext.companyGoals.map((goal) => `- ${goal}`).join("\n")
     : "- No active company goals";
@@ -2292,6 +2687,8 @@ export function createPrompt(context: HeartbeatContext) {
     ? context.goalContext.agentGoals.map((goal) => `- ${goal}`).join("\n")
     : "- No active agent goals";
   const isCommentOrderRun = context.wakeContext?.reason === "issue_comment_recipient";
+  const controlPlaneApiBaseUrl =
+    context.runtime?.env?.BOPODEV_API_BASE_URL?.trim() || context.runtime?.env?.BOPODEV_API_URL?.trim() || "";
   const workItems = context.workItems.length
     ? context.workItems
         .map((item) =>
@@ -2302,14 +2699,18 @@ export function createPrompt(context: HeartbeatContext) {
             item.childIssueIds?.length ? `  Sub-issues: ${item.childIssueIds.join(", ")}` : null,
             item.status ? `  Status: ${item.status}` : null,
             item.priority ? `  Priority: ${item.priority}` : null,
-            item.body ? `  Body: ${item.body}` : null,
+            isCompact
+              ? `  Body: (omitted — fetch with GET ${controlPlaneApiBaseUrl || "$BOPODEV_API_BASE_URL"}/issues/${item.issueId})`
+              : item.body
+                ? `  Body: ${item.body}`
+                : null,
             item.labels?.length ? `  Labels: ${item.labels.join(", ")}` : null,
             item.tags?.length ? `  Tags: ${item.tags.join(", ")}` : null,
             item.attachments?.length
               ? [
                   "  Attachments:",
                   ...item.attachments.map((attachment) =>
-                    `    - ${attachment.fileName} | path: ${attachment.absolutePath} | relative: ${attachment.relativePath}`
+                    formatAttachmentLine(attachment, promptMode, controlPlaneApiBaseUrl || "http://127.0.0.1:4020")
                   )
                 ].join("\n")
               : null
@@ -2339,22 +2740,36 @@ export function createPrompt(context: HeartbeatContext) {
         ].join("\n")
       : "";
   const memoryContext = context.memoryContext;
-  const memoryTacitNotes = memoryContext?.tacitNotes?.trim()
+  const memoryTacitNotesRaw = memoryContext?.tacitNotes?.trim()
     ? memoryContext.tacitNotes.trim()
     : "No tacit notes were recorded yet.";
-  const memoryDurableFacts =
+  const memoryTacitNotes = clipPromptText(memoryTacitNotesRaw, memoryCap);
+  const memoryDurableFactsRaw =
     memoryContext?.durableFacts && memoryContext.durableFacts.length > 0
       ? memoryContext.durableFacts.map((fact) => `- ${fact}`).join("\n")
       : "- No durable facts available.";
-  const memoryDailyNotes =
+  const memoryDurableFacts = clipPromptText(memoryDurableFactsRaw, memoryCap);
+  const memoryDailyNotesRaw =
     memoryContext?.dailyNotes && memoryContext.dailyNotes.length > 0
       ? memoryContext.dailyNotes.map((note) => `- ${note}`).join("\n")
       : "- No recent daily notes.";
-  const controlPlaneApiBaseUrl =
-    context.runtime?.env?.BOPODEV_API_BASE_URL?.trim() || context.runtime?.env?.BOPODEV_API_URL?.trim() || "";
+  const memoryDailyNotes = clipPromptText(memoryDailyNotesRaw, memoryCap);
   const hasControlPlaneHeaders = Boolean(context.runtime?.env?.BOPODEV_REQUEST_HEADERS_JSON?.trim());
   const safeControlPlaneCurl =
     'curl -sS -H "x-company-id: $BOPODEV_COMPANY_ID" -H "x-actor-type: $BOPODEV_ACTOR_TYPE" -H "x-actor-id: $BOPODEV_ACTOR_ID" -H "x-actor-companies: $BOPODEV_ACTOR_COMPANIES" -H "x-actor-permissions: $BOPODEV_ACTOR_PERMISSIONS" "$BOPODEV_API_BASE_URL/agents"';
+  const compactHydration =
+    isCompact &&
+    (context.workItems.length > 0 ||
+      (context.wakeContext?.issueIds && context.wakeContext.issueIds.length > 0))
+      ? [
+          "Context hydration (compact prompt mode):",
+          "- Load full issue description and attachment list (with `downloadPath` for each file) via GET `$BOPODEV_API_BASE_URL`/issues/{issueId} before substantive work.",
+          "- Use the same actor headers as in the control-plane section below.",
+          `- Example: curl -sS -H "x-company-id: $BOPODEV_COMPANY_ID" -H "x-actor-type: $BOPODEV_ACTOR_TYPE" -H "x-actor-id: $BOPODEV_ACTOR_ID" -H "x-actor-companies: $BOPODEV_ACTOR_COMPANIES" -H "x-actor-permissions: $BOPODEV_ACTOR_PERMISSIONS" "${controlPlaneApiBaseUrl || "$BOPODEV_API_BASE_URL"}/issues/<issueId>"`,
+          ""
+        ].join("\n")
+      : "";
+
   const controlPlaneDirectives = [
     "Control-plane API directives:",
     controlPlaneApiBaseUrl
@@ -2387,21 +2802,26 @@ export function createPrompt(context: HeartbeatContext) {
     "- If payload files are required, write under `agents/<agent-id>/tmp/` (or OS temp via `mktemp`) and do not treat cleanup command failures as task blockers.",
     "- If control-plane API connectivity fails, report the exact failing command/error once and stop retry loops for the same endpoint.",
     "- For write_todos status values, only use: todo, in_progress, blocked, in_review, done, canceled (US spelling, not cancelled).",
-    "- If any command fails, avoid further exploratory commands and still return the required final JSON summary.",
+    "- If any command fails, avoid further exploratory commands and still return the required final JSON object.",
     "- Do not use emojis in issue comments, summaries, or status messages.",
     isCommentOrderRun
       ? "- Do not stop after planning. Execute concrete steps only for the triggering comment order."
       : "- Do not stop after planning. You must execute concrete steps for assigned issues in this run (file edits, API calls, or other verifiable actions).",
-    "- If you cannot complete concrete execution, set summary to include the blocker explicitly instead of claiming success.",
+    "- If you cannot complete concrete execution, explain the blocker plainly in `employee_comment` and add it to `errors` instead of claiming success.",
     "- Treat file memory as source of truth for long-term context: append raw observations to daily notes first, then promote stable patterns to durable facts.",
     "- Avoid writing duplicate durable facts when existing memory already contains the same lesson.",
-    "- Your final output must be only the JSON object below, with no prose before or after it.",
+    "- Your final output must be exactly one JSON object and nothing else.",
+    "- Do not include any fields besides `employee_comment`, `results`, `errors`, and `artifacts`.",
+    "- `employee_comment` must be markdown written like a concise employee updating a manager with concrete actions, outcome, and blocker or next step when relevant.",
+    "- `results` must list concrete completed outcomes as short strings.",
+    "- `errors` must list concrete blockers or failures as short strings and be empty on clean success.",
+    "- `artifacts` must contain objects like {\"kind\":\"file\",\"path\":\"relative/path\"}.",
     "- Do not invent token or cost values; the runtime records usage separately."
   ].join("\n");
 
   return `${bootstrapPrompt ? `${bootstrapPrompt}\n\n` : ""}You are ${context.agent.name} (${context.agent.role}), agent ${context.agentId}.
 Heartbeat run ${context.heartbeatRunId}.
-
+${isCompact ? "Prompt profile: compact (issue bodies are not inlined—use GET /issues/:id to hydrate).\n" : ""}
 Company:
 - Name: ${context.company.name}
 - Mission: ${context.company.mission ?? "No mission set"}
@@ -2414,7 +2834,7 @@ ${projectGoals}
 Agent goals:
 ${agentGoals}
 
-${isCommentOrderRun ? "Linked issue context (read-only):" : "Assigned issues:"}
+${compactHydration}${isCommentOrderRun ? "Linked issue context (read-only):" : "Assigned issues:"}
 ${workItems}
 
 ${wakeContextLines}
@@ -2434,8 +2854,7 @@ ${executionDirectives}
 
 ${controlPlaneDirectives}
 
-At the end of your response, output exactly one JSON object on a single line and nothing else:
-{"summary":"brief outcome and any blocker"}
+${HEARTBEAT_JSON_SCHEMA_FOOTER}
 `;
 }