fix(httpapi): add unknown error references (#28629)

packages/core/src/util/error.ts

@@ -65,5 +65,6 @@ export abstract class NamedError extends Error {
 
   public static readonly Unknown = NamedError.create("UnknownError", {
     message: Schema.String,
+    ref: Schema.optional(Schema.String),
   })
 }

packages/opencode/src/server/routes/instance/httpapi/middleware/error.ts

@@ -26,12 +26,15 @@ export const errorLayer = HttpRouter.middleware<{ handles: unknown }>()((effect)
         return Effect.succeed(HttpServerResponse.jsonUnsafe(error.toObject(), { status: 400 }))
       }
 
-      log.error("failed", { error, cause: Cause.pretty(cause) })
+      const ref = `err_${crypto.randomUUID().slice(0, 8)}`
+
+      log.error("failed", { ref, error, cause: Cause.pretty(cause) })
 
       return Effect.succeed(
         HttpServerResponse.jsonUnsafe(
           new NamedError.Unknown({
             message: "Unexpected server error. Check server logs for details.",
+            ref,
           }).toObject(),
           { status: 500 },
         ),

packages/opencode/test/server/httpapi-error-middleware.test.ts

@@ -10,6 +10,14 @@ import { testEffect } from "../lib/effect"
 
 const it = testEffect(Layer.mergeAll(NodeHttpServer.layerTest, NodeServices.layer))
 
+function expectUnknownErrorBody(body: unknown) {
+  expect(body).toMatchObject({
+    name: "UnknownError",
+    data: { message: "Unexpected server error. Check server logs for details." },
+  })
+  expect((body as { data?: { ref?: unknown } }).data?.ref).toMatch(/^err_[0-9a-f-]{8}$/)
+}
+
 describe("HttpApi error middleware", () => {
   it.live("returns a safe body for unknown 500 defects", () =>
     Effect.gen(function* () {
@@ -23,10 +31,7 @@ describe("HttpApi error middleware", () => {
       const body = yield* response.json
 
       expect(response.status).toBe(500)
-      expect(body).toEqual({
-        name: "UnknownError",
-        data: { message: "Unexpected server error. Check server logs for details." },
-      })
+      expectUnknownErrorBody(body)
       expect(JSON.stringify(body)).not.toContain("secret stack marker")
     }),
   )
@@ -43,10 +48,7 @@ describe("HttpApi error middleware", () => {
       const body = yield* response.json
 
       expect(response.status).toBe(500)
-      expect(body).toEqual({
-        name: "UnknownError",
-        data: { message: "Unexpected server error. Check server logs for details." },
-      })
+      expectUnknownErrorBody(body)
       expect(JSON.stringify(body)).not.toContain("secret named marker")
     }),
   )
@@ -84,10 +86,7 @@ describe("HttpApi error middleware", () => {
       const body = yield* response.json
 
       expect(response.status).toBe(500)
-      expect(body).toEqual({
-        name: "UnknownError",
-        data: { message: "Unexpected server error. Check server logs for details." },
-      })
+      expectUnknownErrorBody(body)
     }),
   )
 })