bopodev-agent-sdk 0.1.24 → 0.1.26

package/src/adapters.ts

@@ -11,7 +11,12 @@ import type {
   HeartbeatContext
 } 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 +29,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 +51,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 +170,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 +459,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 +530,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 +574,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 +966,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 +1042,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 +1059,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 +1087,9 @@ export async function runDirectApiWork(
       stderrPreview: runtime.error,
       stdoutPreview: runtime.responsePreview
     },
+    ...(failure.providerUsageLimited
+      ? { dispositionHint: buildProviderUsageLimitedDispositionHint(provider, failure.detail) }
+      : {}),
     nextState: context.state
   };
 }
@@ -1042,6 +1215,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 +1302,7 @@ export async function runProviderWork(
       tokenInput,
       tokenOutput,
       usdCost,
+      finalRunOutput: runtime.finalRunOutput,
       usage,
       pricingProviderType,
       pricingModelId,
@@ -1128,11 +1336,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 +1354,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 +1383,9 @@ export async function runProviderWork(
       stderrPreview: toPreview(runtime.stderr),
       transcript: runtime.transcript
     },
+    ...(failure.providerUsageLimited
+      ? { dispositionHint: buildProviderUsageLimitedDispositionHint(provider, failure.detail) }
+      : {}),
     nextState: context.state
   };
 }
@@ -1220,7 +1435,7 @@ export async function runCursorWork(
   if (
     !runtime.ok &&
     resumeState.resumeSessionId &&
-    !isRateLimitedRuntimeFailure(runtime) &&
+    !isProviderUsageLimitedRuntimeFailure(runtime) &&
     isUnknownSessionError(runtime.stderr, runtime.stdout)
   ) {
     const retry = withResolvedRuntimeUsage(
@@ -1331,7 +1546,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 +1646,7 @@ export async function runGeminiCliWork(
   if (
     !runtime.ok &&
     resumeState.resumeSessionId &&
-    !isRateLimitedRuntimeFailure(runtime) &&
+    !isProviderUsageLimitedRuntimeFailure(runtime) &&
     isGeminiUnknownSessionError(runtime.stdout, runtime.stderr)
   ) {
     const retry = withResolvedRuntimeUsage(
@@ -1535,6 +1755,7 @@ export function toProviderResult(
       forcedKill: boolean;
     }>;
     parsedUsage?: RuntimeParsedUsage;
+    finalRunOutput?: AdapterExecutionResult["finalRunOutput"];
     structuredOutputSource?: "stdout" | "stderr";
     structuredOutputDiagnostics?: {
       stdoutJsonObjectCount: number;
@@ -1550,6 +1771,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 +1849,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 +1894,7 @@ export function toProviderResult(
       tokenInput: usageTokenInputTotal(runtime.parsedUsage),
       tokenOutput,
       usdCost,
+      finalRunOutput: runtime.finalRunOutput,
       usage,
       pricingProviderType,
       pricingModelId,
@@ -1670,11 +1929,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 +1947,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 +1977,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 +1990,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 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 "runtime exited without diagnostic output.";
+  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) {
@@ -2291,12 +2627,15 @@ export function createPrompt(context: HeartbeatContext) {
   const agentGoals = context.goalContext?.agentGoals.length
     ? context.goalContext.agentGoals.map((goal) => `- ${goal}`).join("\n")
     : "- No active agent goals";
+  const isCommentOrderRun = context.wakeContext?.reason === "issue_comment_recipient";
   const workItems = context.workItems.length
     ? context.workItems
         .map((item) =>
           [
             `- [${item.issueId}] ${item.title}`,
             `  Project: ${item.projectName ?? item.projectId}`,
+            item.parentIssueId ? `  Parent issue: ${item.parentIssueId}` : null,
+            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,
@@ -2316,6 +2655,25 @@ export function createPrompt(context: HeartbeatContext) {
         )
         .join("\n")
     : "- No assigned work";
+  const wakeContextLines = context.wakeContext
+    ? [
+        "Wake context:",
+        `- Reason: ${context.wakeContext.reason ?? "unspecified"}`,
+        `- Trigger comment: ${context.wakeContext.commentId ?? "none"}`,
+        `- Comment order: ${context.wakeContext.commentBody ?? "none"}`,
+        `- Linked issues: ${context.wakeContext.issueIds?.length ? context.wakeContext.issueIds.join(", ") : "none"}`
+      ].join("\n")
+    : "";
+  const commentOrderDirectives =
+    isCommentOrderRun
+      ? [
+          "Comment-order directives:",
+          "- The triggering comment is the primary order for this run.",
+          "- Treat linked issue details as read-only context unless explicitly asked for broader issue updates.",
+          "- Do not rerun full issue backlogs/checklists by default.",
+          "- Apply only the requested delta from the comment unless explicitly asked to do more."
+        ].join("\n")
+      : "";
   const memoryContext = context.memoryContext;
   const memoryTacitNotes = memoryContext?.tacitNotes?.trim()
     ? memoryContext.tacitNotes.trim()
@@ -2353,20 +2711,32 @@ export function createPrompt(context: HeartbeatContext) {
     "- You are running inside a BopoDev heartbeat for local repository work.",
     "- Use BopoDev-specific injected skills only (bopodev-control-plane, bopodev-create-agent, para-memory-files) when relevant.",
     "- Ignore unrelated third-party control-plane skills even if they exist in the runtime environment.",
-    "- Prefer completing assigned issue work in this repository over non-essential coordination tasks.",
-    "- Keep command usage minimal and task-focused; avoid broad repository scans unless strictly required for the assigned issue.",
+    isCommentOrderRun
+      ? "- Prioritize the triggering comment order over general issue backlog work."
+      : "- Prefer completing assigned issue work in this repository over non-essential coordination tasks.",
+    isCommentOrderRun
+      ? "- Keep command usage narrowly focused on the comment request and required context."
+      : "- Keep command usage minimal and task-focused; avoid broad repository scans unless strictly required for the assigned issue.",
     "- Shell commands run under zsh on macOS; avoid Bash-only features such as `local -n`, `declare -n`, `mapfile`, and `readarray`.",
     "- Prefer POSIX/zsh-compatible shell snippets, direct `curl` headers, and `jq`.",
     "- Prefer heredoc/stdin payloads (for example `curl --data-binary @- <<'JSON' ... JSON`) so cleanup is not blocked by runtime policy.",
     "- 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.",
-    "- 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 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, 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");
 
@@ -2385,9 +2755,13 @@ ${projectGoals}
 Agent goals:
 ${agentGoals}
 
-Assigned issues:
+${isCommentOrderRun ? "Linked issue context (read-only):" : "Assigned issues:"}
 ${workItems}
 
+${wakeContextLines}
+
+${commentOrderDirectives}
+
 Memory context:
 - Memory root: ${memoryContext?.memoryRoot ?? "Unavailable"}
 - Tacit notes:
@@ -2401,8 +2775,8 @@ ${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"}
+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"}]}
 `;
 }