fix(opencode): surface provider APIErrors instead of silent _Done_ (#205)

* fix(opencode): surface provider APIErrors instead of silent _Done_

The OpenCode SDK returns HTTP 200 even when the underlying provider call
failed: the failure is stashed on `data.info.error` (e.g. Anthropic
APIError when an image in session history exceeds 2000px) and the
assistant message ends up with zero text parts. The adapter only looked
at the top-level `result.error`, so the kernel silently fell back to
`_Done_` and hid the real failure from the user.

- Detect `data.info.error` on prompt responses and throw with the
  provider error name, status code, and message.
- When the error is the Anthropic "image dimensions exceed max allowed
  size" case, best-effort `session.revert` the poisoned turn so the
  thread is not permanently stuck failing every subsequent prompt.

* chore: bump version to 0.1.37

* fix(opencode): treat MessageAbortedError as non-fatal and fire-and-forget revert

Addresses Codex review on PR #205:
- P1: skip throw when info.error.name is MessageAbortedError so a user's
  stop does not race ahead of the kernel's graceful stop path and flip
  the run into a failed state.
- P2: dispatch tryRevertOversizedImageTurn asynchronously instead of
  awaiting it, so a slow/hung revert cannot delay surfacing the original
  provider error to the user.

---------

Co-authored-by: Kai Liu <kailiu@mmini.tail90d2d5.ts.net>

Author: LIU9293

package.json

@@ -1,6 +1,6 @@
 {
   "name": "ode",
-  "version": "0.1.36",
+  "version": "0.1.37",
   "description": "Coding anywhere with your coding agents connected",
   "module": "packages/core/index.ts",
   "type": "module",

packages/agents/opencode/client.ts

@@ -43,6 +43,110 @@ export function buildOpenCodeCommand(
   return formatShellCommand(args);
 }
 
+/**
+ * Shape of the OpenCode assistant-message `error` field. Matches the SDK's
+ * `ApiError | ProviderAuthError | UnknownError | MessageOutputLengthError |
+ * MessageAbortedError` union (see @opencode-ai/sdk types).
+ */
+type OpenCodeInfoError = {
+  name?: string;
+  data?: {
+    message?: string;
+    statusCode?: number;
+    providerID?: string;
+    responseBody?: string;
+    [key: string]: unknown;
+  };
+};
+
+export function extractInfoError(data: Record<string, unknown>): OpenCodeInfoError | null {
+  const info = data.info as Record<string, unknown> | undefined;
+  const error = info?.error;
+  if (!error || typeof error !== "object") return null;
+  return error as OpenCodeInfoError;
+}
+
+export function formatInfoError(error: OpenCodeInfoError): string {
+  const name = error.name ?? "UnknownError";
+  const message = error.data?.message;
+  const statusCode = error.data?.statusCode;
+  const statusSuffix = statusCode ? ` (status ${statusCode})` : "";
+  if (message) {
+    return `OpenCode ${name}${statusSuffix}: ${message}`;
+  }
+  return `OpenCode ${name}${statusSuffix}`;
+}
+
+/**
+ * `MessageAbortedError` is produced by the OpenCode server when a run is
+ * cancelled (e.g. the user typed `stop` and the kernel called
+ * `session.abort`). It is a normal, non-fatal outcome: the kernel's stop
+ * path at packages/core/kernel/request-run.ts is responsible for publishing
+ * the final text. Treat it as a soft failure so we don't race ahead of the
+ * stop handling with a failed-run status.
+ */
+export function isAbortError(error: OpenCodeInfoError): boolean {
+  return error.name === "MessageAbortedError";
+}
+
+/**
+ * Detect the Anthropic "image dimensions exceed max allowed size" error. A
+ * single oversized screenshot stuck in session history would otherwise break
+ * every subsequent turn in the thread, because the full history is replayed
+ * on every prompt. See thread `C0AUUDD0VDX:1776966674.077239` for the
+ * original report.
+ */
+export function isOversizedImageError(error: OpenCodeInfoError): boolean {
+  if (error.name !== "APIError") return false;
+  const haystacks: string[] = [];
+  if (typeof error.data?.message === "string") haystacks.push(error.data.message);
+  if (typeof error.data?.responseBody === "string") haystacks.push(error.data.responseBody);
+  const blob = haystacks.join(" ").toLowerCase();
+  if (!blob) return false;
+  return (
+    blob.includes("image dimensions exceed") ||
+    blob.includes("2000 pixels") ||
+    blob.includes("many-image requests")
+  );
+}
+
+async function tryRevertOversizedImageTurn(
+  client: Awaited<ReturnType<typeof getSessionClient>>,
+  sessionId: string,
+  data: Record<string, unknown>,
+  directory: string
+): Promise<void> {
+  try {
+    const info = data.info as { id?: string; parentID?: string } | undefined;
+    // Prefer reverting to the parent user message so the failed assistant
+    // turn plus its oversized-image tool output are removed; fall back to
+    // the assistant message id if parent is missing.
+    const messageID = info?.parentID ?? info?.id;
+    if (!messageID) {
+      log.warn("Oversized-image error detected but could not locate message id to revert", {
+        sessionId,
+      });
+      return;
+    }
+    log.warn("Reverting session turn that triggered oversized-image APIError", {
+      sessionId,
+      messageID,
+    });
+    await client.session.revert({
+      sessionID: sessionId,
+      messageID,
+      directory: directory || undefined,
+    });
+  } catch (err) {
+    // Revert is best-effort: if it fails we still want the original API
+    // error to surface to the user rather than swallowing it here.
+    log.warn("Failed to revert session after oversized-image APIError", {
+      sessionId,
+      error: String(err),
+    });
+  }
+}
+
 export async function createSession(
   workingPath: string,
   env?: SessionEnvironment
@@ -188,9 +292,32 @@ export async function sendMessage(
         throw new Error("OpenCode returned empty response");
       }
 
+      // The SDK returns 200 OK even when the underlying provider call failed:
+      // the failure is stashed on `data.info.error` (ApiError, ProviderAuthError, ...)
+      // and the assistant message ends up with zero text parts. Without this check
+      // the kernel would silently fall back to "_Done_" (see
+      // packages/core/kernel/request-run.ts:847) and hide the real failure from
+      // the user.
+      const data = result.data as Record<string, unknown>;
+      const infoError = extractInfoError(data);
+      if (infoError && !isAbortError(infoError)) {
+        // If the error was caused by an oversized image in the session
+        // history, try to revert the poisoned turn so subsequent messages
+        // in this thread are not permanently broken. Fire-and-forget: we
+        // do NOT await here, so a slow/hung revert cannot delay the user
+        // from seeing the original API failure.
+        if (isOversizedImageError(infoError)) {
+          void tryRevertOversizedImageTurn(client, activeSessionId, data, workingPath);
+        }
+        throw new Error(formatInfoError(infoError));
+      }
+      // MessageAbortedError falls through: the assistant message is empty
+      // because the user stopped the run. The kernel's stop path handles
+      // this gracefully, so surfacing it as a thrown error here would just
+      // race the stop handler and flip the run into a "failed" state.
+
       // Extract text from response in a few known shapes.
       const messages: OpenCodeMessage[] = [];
-      const data = result.data as Record<string, unknown>;
 
       const pushText = (value: unknown): void => {
         if (typeof value !== "string") return;

packages/agents/test/opencode-client.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "bun:test";
+import {
+  extractInfoError,
+  formatInfoError,
+  isAbortError,
+  isOversizedImageError,
+} from "../opencode/client";
+
+describe("opencode info-error detection", () => {
+  it("returns null when no error is present", () => {
+    expect(extractInfoError({})).toBeNull();
+    expect(extractInfoError({ info: {} })).toBeNull();
+    expect(extractInfoError({ info: { error: null } })).toBeNull();
+  });
+
+  it("extracts an APIError from info.error", () => {
+    const err = extractInfoError({
+      info: {
+        error: {
+          name: "APIError",
+          data: { message: "boom", statusCode: 400, isRetryable: false },
+        },
+      },
+    });
+    expect(err).toEqual({
+      name: "APIError",
+      data: { message: "boom", statusCode: 400, isRetryable: false },
+    });
+  });
+
+  it("formats info errors with name, status code, and message", () => {
+    expect(
+      formatInfoError({
+        name: "APIError",
+        data: { message: "quota exceeded", statusCode: 429 },
+      })
+    ).toBe("OpenCode APIError (status 429): quota exceeded");
+  });
+
+  it("formats info errors that are missing a message", () => {
+    expect(formatInfoError({ name: "UnknownError", data: {} })).toBe("OpenCode UnknownError");
+  });
+
+  it("detects the oversized-image Anthropic APIError", () => {
+    expect(
+      isOversizedImageError({
+        name: "APIError",
+        data: {
+          message:
+            "messages.9.content.18.image.source.base64.data: At least one of the image dimensions exceed max allowed size for many-image requests: 2000 pixels",
+          statusCode: 400,
+        },
+      })
+    ).toBe(true);
+  });
+
+  it("does not misclassify unrelated APIErrors as image errors", () => {
+    expect(
+      isOversizedImageError({
+        name: "APIError",
+        data: { message: "rate limit reached", statusCode: 429 },
+      })
+    ).toBe(false);
+  });
+
+  it("does not treat non-API errors as image errors", () => {
+    expect(
+      isOversizedImageError({
+        name: "ProviderAuthError",
+        data: { message: "image dimensions exceed 2000 pixels" },
+      })
+    ).toBe(false);
+  });
+
+  it("flags MessageAbortedError as a non-fatal abort", () => {
+    expect(isAbortError({ name: "MessageAbortedError", data: {} })).toBe(true);
+  });
+
+  it("does not flag provider failures as aborts", () => {
+    expect(isAbortError({ name: "APIError", data: { message: "boom" } })).toBe(false);
+    expect(isAbortError({ name: "ProviderAuthError", data: {} })).toBe(false);
+  });
+});