bopodev-agent-sdk 0.1.25 → 0.1.27

package/src/runtime.ts

@@ -3,6 +3,7 @@ import { access, cp, lstat, mkdir, mkdtemp, readdir, rm, symlink } from "node:fs
 import { homedir, tmpdir } from "node:os";
 import { delimiter, dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
+import { AgentFinalRunOutputSchema, type AgentFinalRunOutput } from "bopodev-contracts";
 import type { AgentRuntimeConfig } from "./types";
 
 type LocalProvider = "claude_code" | "codex" | "cursor" | "opencode" | "gemini_cli";
@@ -32,6 +33,15 @@ type UsageSourceResolution = {
   source?: "stdout" | "stderr";
 };
 
+type FinalRunOutputParseError = "missing" | "malformed" | "schema_mismatch";
+
+type FinalRunOutputResolution = {
+  finalRunOutput?: AgentFinalRunOutput;
+  source?: "stdout" | "stderr";
+  error?: FinalRunOutputParseError;
+  detail?: string;
+};
+
 type CursorParsedStream = {
   usage: ParsedUsageRecord;
   sessionId?: string;
@@ -58,6 +68,8 @@ export interface RuntimeExecutionOutput {
     usdCost?: number;
     summary?: string;
   };
+  finalRunOutput?: AgentFinalRunOutput;
+  finalRunOutputSource?: "stdout" | "stderr";
   structuredOutputSource?: "stdout" | "stderr";
   structuredOutputDiagnostics?: {
     stdoutJsonObjectCount: number;
@@ -73,6 +85,8 @@ export interface RuntimeExecutionOutput {
       | "json_missing"
       | "json_on_stderr_only"
       | "schema_or_shape_mismatch";
+    finalRunOutputStatus?: "valid" | "missing" | "malformed" | "schema_mismatch";
+    finalRunOutputError?: string;
     claudeStopReason?: string;
     claudeResultSubtype?: string;
     claudeSessionId?: string;
@@ -141,6 +155,16 @@ function providerDefaultArgs(provider: "claude_code" | "codex", config?: AgentRu
   return ["exec", "--full-auto", "--skip-git-repo-check"];
 }
 
+function shouldPassCodexReasoningEffortFlag(config?: AgentRuntimeConfig): boolean {
+  const raw = (
+    config?.env?.BOPO_CODEX_PASS_REASONING_EFFORT ?? process.env.BOPO_CODEX_PASS_REASONING_EFFORT ??
+    ""
+  )
+    .trim()
+    .toLowerCase();
+  return raw === "1" || raw === "true" || raw === "yes";
+}
+
 function providerConfigArgs(provider: "claude_code" | "codex", config?: AgentRuntimeConfig) {
   const args: string[] = [];
   if (provider === "codex") {
@@ -151,7 +175,12 @@ function providerConfigArgs(provider: "claude_code" | "codex", config?: AgentRun
       // Codex JSON events carry usage metrics we need for reliable cost accounting.
       args.push("--json");
     }
-    if (config?.thinkingEffort && config.thinkingEffort !== "auto") {
+    // Many `codex` builds reject `--reasoning-effort`; only pass when explicitly enabled.
+    if (
+      shouldPassCodexReasoningEffortFlag(config) &&
+      config?.thinkingEffort &&
+      config.thinkingEffort !== "auto"
+    ) {
       args.push("--reasoning-effort", config.thinkingEffort);
     }
     if (config?.runPolicy?.allowWebSearch) {
@@ -380,6 +409,7 @@ export async function executePromptRuntime(
         const stdoutUsage = parseStructuredUsage(stdout);
         const stderrUsage = parseStructuredUsage(stderr);
         const usageResolution = resolveUsageSource(stdoutUsage, stderrUsage);
+        const finalRunOutputResolution = resolveFinalRunOutput(stdout, stderr);
         return {
           ok: true,
           code: attemptResult.code,
@@ -390,6 +420,8 @@ export async function executePromptRuntime(
           attemptCount: attempts.length,
           attempts,
           parsedUsage: usageResolution.usage,
+          finalRunOutput: finalRunOutputResolution.finalRunOutput,
+          finalRunOutputSource: finalRunOutputResolution.source,
           structuredOutputSource: usageResolution.source,
           structuredOutputDiagnostics: {
             stdoutJsonObjectCount: extractJsonObjectBlocks(stdout).length,
@@ -401,6 +433,12 @@ export async function executePromptRuntime(
             lastStdoutLine: tailLine(stdout),
             lastStderrLine: tailLine(stderr),
             likelyCause: classifyStructuredOutputLikelyCause(stdout, stderr, stdoutUsage, stderrUsage),
+            finalRunOutputStatus: finalRunOutputResolution.finalRunOutput
+              ? "valid"
+              : finalRunOutputResolution.error,
+            ...(finalRunOutputResolution.detail
+              ? { finalRunOutputError: finalRunOutputResolution.detail }
+              : {}),
             ...(claudeStream?.stopReason ? { claudeStopReason: claudeStream.stopReason } : {}),
             ...(claudeStream?.resultSubtype ? { claudeResultSubtype: claudeStream.resultSubtype } : {}),
             ...(claudeStream?.sessionId ? { claudeSessionId: claudeStream.sessionId } : {}),
@@ -439,6 +477,7 @@ export async function executePromptRuntime(
     const stdoutUsage = parseStructuredUsage(stdout);
     const stderrUsage = parseStructuredUsage(stderr);
     const usageResolution = resolveUsageSource(stdoutUsage, stderrUsage);
+    const finalRunOutputResolution = resolveFinalRunOutput(stdout, stderr);
     return {
       ok: false,
       code: lastResult?.code ?? null,
@@ -450,6 +489,8 @@ export async function executePromptRuntime(
       attempts,
       failureType: classifyFailure(lastResult?.timedOut ?? false, lastResult?.spawnErrorCode, lastResult?.code ?? null),
       parsedUsage: usageResolution.usage,
+      finalRunOutput: finalRunOutputResolution.finalRunOutput,
+      finalRunOutputSource: finalRunOutputResolution.source,
       structuredOutputSource: usageResolution.source,
       structuredOutputDiagnostics: {
         stdoutJsonObjectCount: extractJsonObjectBlocks(stdout).length,
@@ -461,6 +502,10 @@ export async function executePromptRuntime(
         lastStdoutLine: tailLine(stdout),
         lastStderrLine: tailLine(stderr),
         likelyCause: classifyStructuredOutputLikelyCause(stdout, stderr, stdoutUsage, stderrUsage),
+        finalRunOutputStatus: finalRunOutputResolution.finalRunOutput
+          ? "valid"
+          : finalRunOutputResolution.error,
+        ...(finalRunOutputResolution.detail ? { finalRunOutputError: finalRunOutputResolution.detail } : {}),
         ...(claudeStream?.stopReason ? { claudeStopReason: claudeStream.stopReason } : {}),
         ...(claudeStream?.resultSubtype ? { claudeResultSubtype: claudeStream.resultSubtype } : {}),
         ...(claudeStream?.sessionId ? { claudeSessionId: claudeStream.sessionId } : {}),
@@ -1320,6 +1365,24 @@ export function containsRateLimitFailure(text: string) {
   );
 }
 
+export function containsUsageLimitHardStopFailure(text: string) {
+  const normalized = text.toLowerCase();
+  return (
+    normalized.includes("api usage limits") ||
+    normalized.includes("you have reached your specified api usage limits") ||
+    normalized.includes("you will regain access on") ||
+    normalized.includes("regain access on") ||
+    normalized.includes("insufficient_quota") ||
+    normalized.includes("billing_hard_limit_reached") ||
+    normalized.includes("exceeded your current quota") ||
+    normalized.includes("usage limit reached")
+  );
+}
+
+export function containsProviderUsageLimitFailure(text: string) {
+  return containsUsageLimitHardStopFailure(text);
+}
+
 export async function checkRuntimeCommandHealth(
   command: string,
   options?: { cwd?: string; timeoutMs?: number; env?: Record<string, string> }
@@ -3240,6 +3303,241 @@ function extractJsonObjectBlocks(text: string) {
   return blocks;
 }
 
+export function parseAgentFinalRunOutput(text: string): {
+  output?: AgentFinalRunOutput;
+  error?: FinalRunOutputParseError;
+  detail?: string;
+} {
+  const candidates = extractFinalRunOutputCandidates(text);
+  if (candidates.length === 0) {
+    return { error: "missing", detail: "No final JSON object was found in runtime output." };
+  }
+  let sawMalformedJson = false;
+  let lastSchemaError = "";
+  for (let index = candidates.length - 1; index >= 0; index -= 1) {
+    const candidate = candidates[index] ?? "";
+    try {
+      const parsed = JSON.parse(candidate) as unknown;
+      const normalizedCandidate = normalizeAgentFinalRunOutputCandidate(parsed);
+      const validated = AgentFinalRunOutputSchema.safeParse(normalizedCandidate ?? parsed);
+      if (validated.success) {
+        const canonical = toCanonicalFinalRunOutput(validated.data);
+        if (!isPromptTemplateFinalRunOutput(canonical)) {
+          return { output: canonical };
+        }
+      } else {
+        lastSchemaError = formatFinalRunOutputSchemaError(validated.error);
+      }
+      const legacyOutput = toLegacyFinalRunOutput(parsed);
+      if (legacyOutput) {
+        return { output: legacyOutput };
+      }
+    } catch (error) {
+      sawMalformedJson = true;
+      lastSchemaError = error instanceof Error ? error.message : String(error);
+    }
+  }
+  return {
+    error: sawMalformedJson ? "malformed" : "schema_mismatch",
+    detail: lastSchemaError || "Final JSON object did not match the required schema."
+  };
+}
+
+function extractFinalRunOutputCandidates(text: string) {
+  const candidates: string[] = [];
+  const trimmed = text.trim();
+  if (looksLikeFinalRunOutputText(trimmed)) {
+    candidates.push(trimmed);
+  }
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+    if (looksLikeFinalRunOutputText(line)) {
+      candidates.push(line);
+    }
+    const parsed = parseJsonRecord(line);
+    if (!parsed) {
+      continue;
+    }
+    candidates.push(...collectPotentialFinalOutputStrings(parsed));
+  }
+  for (const block of extractJsonObjectBlocks(text)) {
+    if (looksLikeFinalRunOutputText(block)) {
+      candidates.push(block);
+    }
+  }
+  return Array.from(new Set(candidates.map((value) => value.trim()).filter(Boolean)));
+}
+
+function normalizeAgentFinalRunOutputCandidate(parsed: unknown): AgentFinalRunOutput | null {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return null;
+  }
+  const record = parsed as Record<string, unknown>;
+  const employeeComment =
+    typeof record.employee_comment === "string" && record.employee_comment.trim().length > 0
+      ? record.employee_comment.trim()
+      : null;
+  if (!employeeComment) {
+    return null;
+  }
+  const results = normalizeStringList(record.results);
+  const errors = normalizeStringList(record.errors);
+  const artifacts = normalizeArtifactList(record.artifacts);
+  return {
+    employee_comment: employeeComment,
+    results,
+    errors,
+    artifacts
+  };
+}
+
+function normalizeStringList(value: unknown) {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    return trimmed ? [trimmed] : [];
+  }
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => (typeof entry === "string" ? entry.trim() : ""))
+    .filter((entry): entry is string => Boolean(entry));
+}
+
+function normalizeArtifactList(value: unknown): AgentFinalRunOutput["artifacts"] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value
+    .map((entry) => normalizeArtifactEntry(entry))
+    .filter((entry): entry is AgentFinalRunOutput["artifacts"][number] => Boolean(entry));
+}
+
+function normalizeArtifactEntry(value: unknown): AgentFinalRunOutput["artifacts"][number] | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return null;
+  }
+  const record = value as Record<string, unknown>;
+  const pathCandidate =
+    (typeof record.path === "string" && record.path.trim()) ||
+    (typeof record.relativePath === "string" && record.relativePath.trim()) ||
+    (typeof record.absolutePath === "string" && record.absolutePath.trim()) ||
+    "";
+  if (!pathCandidate) {
+    return null;
+  }
+  const explicitKind = typeof record.kind === "string" && record.kind.trim() ? record.kind.trim() : "";
+  return {
+    kind: explicitKind || inferArtifactKind(pathCandidate),
+    path: pathCandidate
+  };
+}
+
+function inferArtifactKind(path: string) {
+  const normalized = path.toLowerCase();
+  if (/\.[a-z0-9]{1,10}$/i.test(normalized)) {
+    return "file";
+  }
+  if (normalized.endsWith("/") || normalized.includes("/dist") || normalized.includes("/build")) {
+    return "directory";
+  }
+  return "artifact";
+}
+
+function collectPotentialFinalOutputStrings(value: unknown, depth = 0): string[] {
+  if (depth > 6 || value === null || value === undefined) {
+    return [];
+  }
+  if (typeof value === "string") {
+    return looksLikeFinalRunOutputText(value) ? [value.trim()] : [];
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((entry) => collectPotentialFinalOutputStrings(entry, depth + 1));
+  }
+  if (typeof value === "object") {
+    return Object.values(value).flatMap((entry) => collectPotentialFinalOutputStrings(entry, depth + 1));
+  }
+  return [];
+}
+
+function looksLikeFinalRunOutputText(value: string) {
+  const trimmed = value.trim();
+  if (!trimmed.startsWith("{") || !trimmed.endsWith("}")) {
+    return false;
+  }
+  return trimmed.includes("\"employee_comment\"") || trimmed.includes("\"summary\"");
+}
+
+function formatFinalRunOutputSchemaError(output: {
+  issues: Array<{
+    path: PropertyKey[];
+    message: string;
+  }>;
+}) {
+  const issue = output.issues[0];
+  if (!issue) {
+    return "Final JSON object did not match the required schema.";
+  }
+  const path = issue.path.length > 0 ? `${issue.path.join(".")}: ` : "";
+  return `${path}${issue.message}`;
+}
+
+function toCanonicalFinalRunOutput(output: AgentFinalRunOutput): AgentFinalRunOutput {
+  return {
+    employee_comment: output.employee_comment,
+    results: output.results,
+    errors: output.errors,
+    artifacts: output.artifacts
+  };
+}
+
+function isPromptTemplateFinalRunOutput(output: AgentFinalRunOutput) {
+  return (
+    output.employee_comment.trim().toLowerCase() === "markdown update to the manager" &&
+    output.results.length === 1 &&
+    output.results[0]?.trim().toLowerCase() === "short concrete outcome" &&
+    output.errors.length === 0 &&
+    output.artifacts.length === 1 &&
+    output.artifacts[0]?.kind === "file" &&
+    output.artifacts[0]?.path === "relative/path"
+  );
+}
+
+function toLegacyFinalRunOutput(parsed: unknown): AgentFinalRunOutput | undefined {
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return undefined;
+  }
+  const record = parsed as Record<string, unknown>;
+  const summary = typeof record.summary === "string" ? record.summary.trim() : "";
+  if (!summary) {
+    return undefined;
+  }
+  return {
+    employee_comment: summary,
+    results: [summary],
+    errors: [],
+    artifacts: []
+  };
+}
+
+function resolveFinalRunOutput(stdout: string, stderr: string): FinalRunOutputResolution {
+  const stdoutResolution = parseAgentFinalRunOutput(stdout);
+  if (stdoutResolution.output) {
+    return { finalRunOutput: stdoutResolution.output, source: "stdout" };
+  }
+  const stderrResolution = parseAgentFinalRunOutput(stderr);
+  if (stderrResolution.output) {
+    return { finalRunOutput: stderrResolution.output, source: "stderr" };
+  }
+  return {
+    error: stdoutResolution.error ?? stderrResolution.error ?? "missing",
+    detail: stdoutResolution.detail ?? stderrResolution.detail ?? "No final JSON object was found in runtime output."
+  };
+}
+
 function tryParseUsage(candidate: string) {
   try {
     const parsed = JSON.parse(candidate) as Record<string, unknown>;

package/src/types.ts

@@ -1,4 +1,4 @@
-import type { ExecutionOutcome, ProviderType } from "bopodev-contracts";
+import type { AgentFinalRunOutput, ExecutionOutcome, ProviderType } from "bopodev-contracts";
 
 export type AgentProviderType = ProviderType;
 
@@ -21,6 +21,8 @@ export interface AgentWorkItem {
     fileSizeBytes: number;
     relativePath: string;
     absolutePath: string;
+    /** API-relative path, e.g. `/issues/{issueId}/attachments/{id}/download` */
+    downloadPath?: string;
   }>;
 }
 
@@ -41,11 +43,20 @@ export interface AgentMemoryContext {
   dailyNotes: string[];
 }
 
+export type HeartbeatPromptMode = "full" | "compact";
+
 export interface HeartbeatContext {
   companyId: string;
   agentId: string;
   providerType: AgentProviderType;
   heartbeatRunId: string;
+  /** Controls how much issue/memory text is inlined in the heartbeat prompt. Default when omitted: full. */
+  promptMode?: HeartbeatPromptMode;
+  /**
+   * When true, emit a minimal idle prompt (no assigned work). Set by the API when
+   * `BOPO_HEARTBEAT_IDLE_POLICY=micro_prompt` and there are no work items.
+   */
+  idleMicroPrompt?: boolean;
   company: {
     name: string;
     mission?: string | null;
@@ -95,12 +106,20 @@ export interface AdapterExecutionResult {
   tokenInput: number;
   tokenOutput: number;
   usdCost: number;
+  finalRunOutput?: AgentFinalRunOutput;
   usage?: AdapterNormalizedUsage;
   pricingProviderType?: string | null;
   pricingModelId?: string | null;
   outcome?: ExecutionOutcome;
   nextState?: AgentState;
   trace?: AdapterTrace;
+  dispositionHint?: {
+    kind: "provider_usage_limited";
+    persistStatus: "skipped";
+    pauseAgent: boolean;
+    notifyBoard: boolean;
+    message: string;
+  };
 }
 
 export interface AgentAdapter {