Handle native structured-format incompatibility and preserve failure evidence

This commit is contained in:
2026-10-10 00:01:02 +01:00
parent 16389b8270
commit a1c0eb4a72
21 changed files with 800 additions and 42 deletions
+9
View File
@@ -32,6 +32,12 @@ type Connection struct {
done chan error
models map[string]map[string]string
responses map[string][]byte
formatChecked bool
formatSupported bool
FormatProbe *FormatProbe
LastHTTPStatus int
LastHTTPOperation string
MessageReadbackDiagnostic string
}
// Reference records only our ephemeral loopback service credentials, never provider auth.
@@ -210,6 +216,8 @@ func (c *Connection) Close() {
}
func (c *Connection) Native(ctx context.Context, method, path string, body any) ([]byte, error) {
c.LastHTTPStatus = 0
c.LastHTTPOperation = strings.ToUpper(method) + " " + path
u, err := url.Parse(c.URL + path)
if err != nil {
return nil, err
@@ -241,6 +249,7 @@ func (c *Connection) Native(ctx context.Context, method, path string, body any)
return nil, fmt.Errorf("OpenCode native API request failed")
}
defer response.Body.Close()
c.LastHTTPStatus = response.StatusCode
if response.StatusCode < 200 || response.StatusCode >= 300 {
// The stage adapter stores bounded, redacted failure evidence separately;
// the public error string remains free of provider bodies and credentials.
+90
View File
@@ -0,0 +1,90 @@
package opencode
import (
"context"
"encoding/json"
"fmt"
"strings"
)
// FormatProbe is retained, deny-all and no-inference. Some native releases
// accept a format on POST but reject their own stored user message on GET.
type FormatProbe struct {
SessionID string `json:"session_id"`
Supported bool `json:"supported"`
Diagnostic string `json:"diagnostic,omitempty"`
Response string `json:"response,omitempty"`
}
func (c *Connection) supportsFormat(ctx context.Context, format json.RawMessage) (bool, error) {
if c.formatChecked {
return c.formatSupported, nil
}
created, err := c.Native(ctx, "post", "/session", map[string]any{"title": "Pipelines structured-format compatibility probe (no inference)", "permission": []map[string]string{{"permission": "*", "pattern": "*", "action": "deny"}}})
if err != nil {
return false, err
}
var session struct {
ID string `json:"id"`
}
if json.Unmarshal(created, &session) != nil || !sessionID.MatchString(session.ID) {
return false, fmt.Errorf("invalid structured-format probe session")
}
c.FormatProbe = &FormatProbe{SessionID: session.ID}
posted, err := c.Native(ctx, "post", "/session/"+session.ID+"/message", map[string]any{"noReply": true, "format": format, "parts": []map[string]string{{"type": "text", "text": "Compatibility probe only. No reply, inference or tool execution requested."}}})
if err != nil {
c.FormatProbe.Response = string(posted)
return false, err
}
data, err := c.Native(ctx, "get", "/session/"+session.ID+"/message", nil)
if err != nil {
// Downgrade only this specific readback incompatibility, never an auth,
// network or unrelated HTTP failure. Do not alter the stored probe.
c.FormatProbe.Response = string(data)
if !strings.Contains(err.Error(), "HTTP 400") || !strings.Contains(string(data), "Expected OutputFormat") {
return false, err
}
c.FormatProbe.Diagnostic = "native format readback incompatibility; explicit format omitted, strict local JSON validation remains enabled"
c.FormatProbe.Response = string(data)
c.formatChecked = true
return false, nil
}
var messages []json.RawMessage
if json.Unmarshal(data, &messages) != nil || len(messages) == 0 {
return false, fmt.Errorf("invalid structured-format probe readback")
}
c.formatChecked = true
c.formatSupported = true
c.FormatProbe.Supported = true
return true, nil
}
// ExecutionError exposes a safe classification, not arbitrary provider messages,
// prompts or credentials. Full redacted responses belong in failure evidence.
func ExecutionError(data json.RawMessage) error {
var failure struct {
Name string `json:"name"`
Tag string `json:"_tag"`
Data struct {
StatusCode int `json:"statusCode"`
} `json:"data"`
}
if json.Unmarshal(data, &failure) != nil {
return fmt.Errorf("OpenCode agent reported an execution error")
}
name := failure.Name
if name == "" {
name = failure.Tag
}
if name == "StructuredOutputError" {
return fmt.Errorf("StructuredOutputError: Model did not produce structured output; inspect retained response for tool-call markup or result-envelope mismatch")
}
safeNames := map[string]bool{"APIError": true, "ProviderAuthError": true, "ContextOverflowError": true, "MessageAbortedError": true, "OutputLengthError": true, "UnknownError": true, "ServiceUnavailableError": true}
if !safeNames[name] {
return fmt.Errorf("OpenCode agent reported an execution error")
}
if failure.Data.StatusCode >= 400 && failure.Data.StatusCode <= 599 {
return fmt.Errorf("OpenCode agent execution error: %s (HTTP %d)", name, failure.Data.StatusCode)
}
return fmt.Errorf("OpenCode agent execution error: %s", name)
}
+92
View File
@@ -0,0 +1,92 @@
package opencode
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"strings"
"testing"
)
func TestNativeFormatProbeDowngradesOnlyReadbackIncompatibility(t *testing.T) {
for _, status := range []int{200, 400, 401, 500} {
t.Run(http.StatusText(status), func(t *testing.T) {
probes, generations := 0, 0
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
w.Header().Set("Content-Type", "application/json")
switch r.Method + " " + r.URL.Path {
case "POST /session":
probes++
var body struct{ Permission []map[string]string }
json.NewDecoder(r.Body).Decode(&body)
if len(body.Permission) != 1 || body.Permission[0]["action"] != "deny" {
t.Fatal("probe has tools", body)
}
w.Write([]byte(`{"id":"ses_probe"}`))
case "POST /session/ses_probe/message":
var body struct {
NoReply bool `json:"noReply"`
}
json.NewDecoder(r.Body).Decode(&body)
if !body.NoReply {
t.Fatal("probe requested inference")
}
w.Write([]byte(`{}`))
case "GET /session/ses_probe/message":
w.WriteHeader(status)
if status == 200 {
w.Write([]byte(`[{"info":{"role":"user","format":{"type":"json_schema"}}}]`))
} else {
w.Write([]byte(`{"name":"BadRequest","data":{"message":"Expected OutputFormatJsonSchema at info.format"}}`))
}
case "POST /session/ses_primary/message":
generations++
var body map[string]json.RawMessage
json.NewDecoder(r.Body).Decode(&body)
if (len(body["format"]) > 0) != (status == 200) {
t.Error("incorrect format compatibility mode", string(body["format"]))
}
w.Write([]byte(`{"info":{"role":"assistant","finish":"stop","time":{"completed":1},"structured":{"outcome":"success","output":{"value":9}}},"parts":[]}`))
default:
t.Error("unexpected operation", r.Method, r.URL.Path)
}
}))
defer srv.Close()
c := &Connection{Backend: "v1", URL: srv.URL, models: map[string]map[string]string{"ses_primary": {"providerID": "test", "modelID": "test"}}, responses: map[string][]byte{}}
body := map[string]any{"prompt": "task", "format": map[string]any{"type": "json_schema", "schema": map[string]any{"type": "object"}, "retryCount": 0}}
data, err := c.Call(context.Background(), "post", "/api/session/ses_primary/generate", body)
if status == 401 || status == 500 {
if err == nil || generations != 0 {
t.Fatal("unrelated failure silently downgraded", err, generations)
}
return
}
if err != nil || !strings.Contains(string(data), "value") || generations != 1 {
t.Fatal(err, string(data), generations)
}
if c.FormatProbe == nil || c.FormatProbe.SessionID != "ses_probe" || c.FormatProbe.Supported != (status == 200) {
t.Fatal("probe evidence lost", c.FormatProbe)
}
if _, err = c.Call(context.Background(), "post", "/api/session/ses_primary/generate", body); err != nil || probes != 1 {
t.Fatal("capability probe was not cached", err, probes)
}
})
}
}
func TestNativeStructuredFailureIsClearAndDoesNotReplayGeneration(t *testing.T) {
response := []byte(`{"info":{"role":"assistant","finish":"stop","time":{"completed":1},"error":{"name":"StructuredOutputError","data":{"message":"Model did not produce structured output; secret-token"}}},"parts":[{"type":"text","text":"<|DSML|invoke name=\"StructuredOutput\">not JSON</|DSML|invoke>"}]}`)
_, err := messageText(response)
if err == nil || !strings.Contains(err.Error(), "StructuredOutputError: Model did not produce structured output") || strings.Contains(err.Error(), "secret-token") {
t.Fatal(err)
}
if _, partialErr := messageText([]byte(strings.Replace(string(response), `"completed":1`, `"completed":0`, 1))); partialErr == nil || !strings.Contains(partialErr.Error(), "StructuredOutputError") {
t.Fatal("incomplete timestamp hid provider failure", partialErr)
}
c := &Connection{Backend: "v1", responses: map[string][]byte{"ses_failure": response}}
retained, err := c.Call(context.Background(), "post", "/api/experimental/session/ses_failure/wait", nil)
if err == nil || string(retained) != string(response) {
t.Fatal("wait failure discarded provider response", err, string(retained))
}
}
+22 -2
View File
@@ -52,11 +52,31 @@ func TestStableNativeSessionContractLive(t *testing.T) {
if len(session.Permission) != 3 || session.Permission[2]["permission"] != "bash" {
t.Fatal("scoped native permission contract not retained", string(data))
}
// Validate the real native JSON-schema request without provider inference.
_, err = c.Native(ctx, "post", "/session/"+result.Data.ID+"/message", map[string]any{"noReply": true, "format": map[string]any{"type": "json_schema", "retryCount": 0, "schema": map[string]any{"type": "object", "required": []string{"outcome", "output"}, "additionalProperties": false, "properties": map[string]any{"outcome": map[string]any{"type": "string", "enum": []string{"success", "error"}}, "output": map[string]any{"type": "object"}}}}, "parts": []map[string]string{{"type": "text", "text": "No inference; validate structured format."}}})
// Validate the complete POST -> retained GET contract, not merely POST
// acceptance. The probe itself never runs a model or tools.
format, _ := json.Marshal(map[string]any{"type": "json_schema", "retryCount": 0, "schema": map[string]any{"type": "object", "required": []string{"outcome", "output"}, "additionalProperties": false, "properties": map[string]any{"outcome": map[string]any{"type": "string", "enum": []string{"success", "error"}}, "output": map[string]any{"type": "object", "additionalProperties": true}}}})
supported, err := c.supportsFormat(ctx, format)
if err != nil {
t.Fatal("native format capability probe failed", err)
}
payload := map[string]any{"noReply": true, "parts": []map[string]string{{"type": "text", "text": "No inference; validate retained message readback."}}}
if supported {
payload["format"] = json.RawMessage(format)
}
_, err = c.Native(ctx, "post", "/session/"+result.Data.ID+"/message", payload)
if err != nil {
t.Fatal("native schema request rejected", err)
}
if _, err = c.Native(ctx, "get", "/session/"+result.Data.ID+"/message", nil); err != nil {
t.Fatal("effective format breaks retained-message readback", err)
}
t.Logf("schema mode supported: %v; retained compatibility probe: %s", supported, c.FormatProbe.SessionID)
if !supported {
recovered, exportErr := c.Messages(ctx, c.FormatProbe.SessionID)
if exportErr != nil || !json.Valid(recovered) || c.MessageReadbackDiagnostic == "" {
t.Fatal("cannot recover old format-bearing messages via read-only export", exportErr, string(recovered))
}
}
ref, err := c.Reference()
if err != nil {
t.Fatal(err)
+76
View File
@@ -0,0 +1,76 @@
package opencode
import (
"bytes"
"context"
"encoding/json"
"fmt"
"os/exec"
"strings"
)
type boundedOutput struct {
bytes.Buffer
overflow bool
limit int
}
func (b *boundedOutput) Write(p []byte) (int, error) {
n := len(p)
remaining := b.limit - b.Len()
if n > remaining {
b.overflow = true
p = p[:remaining]
}
_, _ = b.Buffer.Write(p)
return n, nil
}
// Messages preserves old sessions with native OutputFormat readback failures:
// the CLI export reads the local stored data without that HTTP encoder. It does
// not regenerate, repair the database, delete history or change conversations.
func (c *Connection) Messages(ctx context.Context, id string) ([]byte, error) {
if !sessionID.MatchString(id) {
return nil, fmt.Errorf("invalid session ID")
}
c.MessageReadbackDiagnostic = ""
data, err := c.Native(ctx, "get", "/session/"+id+"/message", nil)
if err == nil {
return data, nil
}
if !strings.Contains(err.Error(), "HTTP 400") || !strings.Contains(string(data), "Expected OutputFormat") {
return data, err
}
if ctx.Err() != nil {
return data, ctx.Err()
}
executable := c.Executable
if executable == "" {
executable = Executable()
}
cmd := exec.CommandContext(ctx, executable, "export", id)
cmd.Dir = c.Directory
stdout, stderr := &boundedOutput{limit: MaxResponse}, &boundedOutput{limit: 8 << 10}
cmd.Stdout = stdout
cmd.Stderr = stderr
if exportErr := cmd.Run(); exportErr != nil {
if ctx.Err() != nil {
return data, ctx.Err()
}
return data, fmt.Errorf("%w; read-only native export fallback failed", err)
}
if stdout.overflow {
return data, fmt.Errorf("%w; native export exceeds 1 MiB evidence limit", err)
}
var exported struct {
Info struct {
ID string `json:"id"`
} `json:"info"`
Messages json.RawMessage `json:"messages"`
}
if json.Unmarshal(stdout.Bytes(), &exported) != nil || exported.Info.ID != id || len(exported.Messages) == 0 || exported.Messages[0] != '[' {
return data, fmt.Errorf("%w; native export returned invalid or mismatched session evidence", err)
}
c.MessageReadbackDiagnostic = "Native HTTP message readback rejected stored OutputFormat (HTTP 400); read-only CLI export recovered the original messages without modifying the session."
return exported.Messages, nil
}
+46
View File
@@ -0,0 +1,46 @@
package opencode
import (
"context"
"encoding/json"
"net/http"
"net/http/httptest"
"os"
"path/filepath"
"strings"
"testing"
)
func TestOldFormatReadbackRecoveredWithoutRewritingSession(t *testing.T) {
for _, wrongID := range []bool{false, true} {
bin := filepath.Join(t.TempDir(), "opencode")
id := "ses_old"
if wrongID {
id = "ses_unrelated"
}
export := `{"info":{"id":"` + id + `"},"messages":[{"info":{"role":"assistant","error":{"name":"StructuredOutputError"}},"parts":[{"type":"text","text":"original DSML evidence"}]}]}`
if err := os.WriteFile(bin, []byte("#!/bin/sh\n[ \"$1\" = export ] || exit 8\n[ \"$2\" = ses_old ] || exit 9\necho '"+export+"'\n"), 0700); err != nil {
t.Fatal(err)
}
srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
if r.Method != "GET" {
t.Error("evidence reader changed stored session", r.Method)
}
w.Header().Set("Content-Type", "application/json")
w.WriteHeader(400)
w.Write([]byte(`{"name":"BadRequest","data":{"message":"Expected OutputFormatJsonSchema at info.format"}}`))
}))
c := &Connection{Backend: "v1", URL: srv.URL, Executable: bin}
data, err := c.Messages(context.Background(), "ses_old")
srv.Close()
if wrongID {
if err == nil {
t.Fatal("unrelated session export accepted")
}
continue
}
if err != nil || !json.Valid(data) || !strings.Contains(string(data), "original DSML evidence") || c.MessageReadbackDiagnostic == "" {
t.Fatal(err, string(data))
}
}
}
+23 -7
View File
@@ -36,11 +36,14 @@ func messageText(data []byte) (string, error) {
} `json:"info"`
Parts []struct{ Type, Text string } `json:"parts"`
}
if json.Unmarshal(data, &message) != nil || message.Info.Role != "assistant" || message.Info.Time.Completed == 0 {
if json.Unmarshal(data, &message) != nil || message.Info.Role != "assistant" {
return "", fmt.Errorf("OpenCode returned no completed assistant result")
}
if len(message.Info.Error) > 0 && string(message.Info.Error) != "null" {
return "", fmt.Errorf("OpenCode agent reported an execution error")
return "", ExecutionError(message.Info.Error)
}
if message.Info.Time.Completed == 0 {
return "", fmt.Errorf("OpenCode returned no completed assistant result")
}
if len(message.Info.Structured) > 0 && string(message.Info.Structured) != "null" && (message.Info.Finish == "stop" || message.Info.Finish == "tool-calls") {
return string(message.Info.Structured), nil
@@ -159,7 +162,17 @@ func (c *Connection) Call(ctx context.Context, method, path string, body any) ([
}
payload := map[string]any{"model": c.models[id], "parts": []map[string]string{{"type": "text", "text": text}}}
if len(request.Format) > 0 {
payload["format"] = request.Format
supported, err := c.supportsFormat(ctx, request.Format)
if err != nil {
var evidence []byte
if c.FormatProbe != nil {
evidence = []byte(c.FormatProbe.Response)
}
return evidence, fmt.Errorf("native structured-format compatibility check: %w", err)
}
if supported {
payload["format"] = request.Format
}
}
response, err := c.Native(ctx, "post", "/session/"+id+"/message", payload)
if err != nil {
@@ -176,11 +189,14 @@ func (c *Connection) Call(ctx context.Context, method, path string, body any) ([
return json.Marshal(map[string]any{"data": map[string]string{"text": result}})
case "wait":
_, err := messageText(c.responses[id])
return nil, err
case "message":
data, err := c.Native(ctx, "get", "/session/"+id+"/message", nil)
if err != nil {
return nil, err
return c.responses[id], err
}
return nil, nil
case "message":
data, err := c.Messages(ctx, id)
if err != nil {
return data, err
}
var messages []struct {
Info json.RawMessage `json:"info"`
+20 -1
View File
@@ -18,11 +18,18 @@ func TestNativeSessionModelPermissionsGenerationAndAbort(t *testing.T) {
}
switch r.Method + " " + r.URL.Path {
case "POST /session":
var raw map[string]json.RawMessage
json.NewDecoder(r.Body).Decode(&raw)
if strings.Contains(string(raw["title"]), "compatibility probe") {
w.Write([]byte(`{"id":"ses_probe"}`))
return
}
var body struct {
Model map[string]string
Permission []map[string]string
}
json.NewDecoder(r.Body).Decode(&body)
data, _ := json.Marshal(raw)
json.Unmarshal(data, &body)
if body.Model["id"] != "model" || body.Model["providerID"] != "provider" || body.Permission[0]["action"] != "deny" || body.Permission[1]["permission"] != "bash" {
t.Error("model or scoped permissions lost", body)
}
@@ -43,6 +50,18 @@ func TestNativeSessionModelPermissionsGenerationAndAbort(t *testing.T) {
}
prompted = true
w.Write([]byte(`{"info":{"role":"assistant","finish":"stop","time":{"completed":1}},"parts":[{"type":"text","text":"result"}]}`))
case "POST /session/ses_probe/message":
var body struct {
NoReply bool `json:"noReply"`
Format map[string]any
}
json.NewDecoder(r.Body).Decode(&body)
if !body.NoReply || body.Format["retryCount"] != float64(0) {
t.Error("probe requested inference or retries", body)
}
w.Write([]byte(`{}`))
case "GET /session/ses_probe/message":
w.Write([]byte(`[{"info":{"role":"user"}}]`))
case "GET /session/ses_native/message":
w.Write([]byte(`[{"info":{"role":"assistant","finish":"stop","time":{"completed":1}},"parts":[{"type":"text","text":"result"}]}]`))
case "POST /session/ses_native/abort":