Unify structured call completion and retain typed failures

This commit is contained in:
2026-11-16 14:27:54 +00:00
parent e98e525b5c
commit c2c8050bc8
18 changed files with 313 additions and 186 deletions

View File

@@ -50,17 +50,13 @@ type Exchange struct {
}
type Response struct {
Exchange *Exchange `json:"-"`
Execution outcomes.ExecutionCounts `json:"execution"`
Content json.RawMessage `json:"content,omitempty"`
Provider string `json:"provider,omitempty"`
Model string `json:"model,omitempty"`
PromptTokens int `json:"prompt_tokens,omitempty"`
CompletionTokens int `json:"completion_tokens,omitempty"`
TotalTokens int `json:"total_tokens,omitempty"`
Prompt PromptMetadata `json:"prompt"`
Prepared *PreparedSnapshot `json:"prepared,omitempty"`
FinalContent string `json:"final_content,omitempty"`
Exchange *Exchange `json:"-"`
Execution outcomes.ExecutionCounts `json:"execution"`
Content json.RawMessage `json:"content,omitempty"`
Model string `json:"model,omitempty"`
Prompt PromptMetadata `json:"prompt"`
Prepared *PreparedSnapshot `json:"prepared,omitempty"`
FinalContent string `json:"final_content,omitempty"`
}
// PreparedSnapshot is the exact rendered request snapshot. Its messages may
@@ -81,8 +77,7 @@ type CacheControl struct {
TTL string `json:"ttl,omitempty"`
}
// CallRecord brackets one logical operation, including preparation. Content
// is present only when a model returned it; consumers must protect it.
// CallRecord brackets one logical operation, including preparation.
type CallRecord struct {
RequestedPromptID string `json:"requested_prompt_id,omitempty"`
CallID uint64 `json:"call_id"`
@@ -90,8 +85,6 @@ type CallRecord struct {
Prompt PromptMetadata `json:"prompt"`
Started time.Time `json:"started"`
Finished time.Time `json:"finished,omitempty"`
Prepared *PreparedSnapshot `json:"prepared,omitempty"`
FinalContent string `json:"final_content,omitempty"`
Failure FailureKind `json:"failure,omitempty"`
}

View File

@@ -14,10 +14,8 @@ const (
FailureRuntime FailureKind = "runtime"
)
// Failure exposes a safe message while retaining the typed cause for callers.
// The cause must not be serialized or formatted directly in user artifacts.
// Failure exposes an operator-facing message and retains the typed cause.
type Failure struct {
Kind FailureKind // Retained until the adapter switches to reason-based classification.
Class FailureClass
Reason outcomes.ReasonCode
Message string
@@ -26,12 +24,12 @@ type Failure struct {
// FailureClass determines whether domain processing may safely skip a model
// operation or must stop the run. Parent cancellation always stops the run.
type FailureClass string
type FailureClass = outcomes.FailureClass
const (
FailureRecoverable FailureClass = "recoverable"
FailureFatal FailureClass = "fatal"
FailureCanceled FailureClass = "canceled"
FailureRecoverable = outcomes.FailureRecoverable
FailureFatal = outcomes.FailureFatal
FailureCanceled = outcomes.FailureCanceled
)
func (f *Failure) Error() string { return f.Message }
@@ -42,7 +40,22 @@ func IsRecoverable(err error) bool {
return errors.As(err, &failure) && failure.Class == FailureRecoverable
}
// RecordFailure retains the error chain for processing and sets the compact
// reason used by reports. An absent reason does not change recoverability.
func RecordFailure(operation *outcomes.Operation, err error) {
operation.Cause = err
operation.FailureClass = FailureFatal
operation.FailureReason = outcomes.ReasonInternalFailure
var failure *Failure
if errors.As(err, &failure) {
operation.FailureClass = failure.Class
if failure.Reason != "" {
operation.FailureReason = failure.Reason
}
}
}
func IsMalformedError(err error) bool {
var failure *Failure
return errors.As(err, &failure) && failure.Kind == FailureMalformedOutput
return errors.As(err, &failure) && failure.Reason == outcomes.ReasonInvalidOutputExhausted
}

View File

@@ -9,11 +9,11 @@ import (
func TestFailureClassificationKeepsCauseAndSafeMessage(t *testing.T) {
cause := errors.New("provider token secret-value")
malformed := &Failure{Kind: FailureMalformedOutput, Message: "malformed structured output", Cause: cause}
malformed := &Failure{Class: FailureRecoverable, Reason: outcomes.ReasonInvalidOutputExhausted, Message: "malformed structured output", Cause: cause}
if !IsMalformedError(malformed) || !errors.Is(malformed, cause) || malformed.Error() != "malformed structured output" {
t.Fatalf("malformed classification: %v", malformed)
}
runtime := &Failure{Kind: FailureRuntime, Message: "structured model call failed", Cause: cause}
runtime := &Failure{Class: FailureFatal, Message: "structured model call failed", Cause: cause}
if IsMalformedError(runtime) || IsMalformedError(cause) || IsMalformedError(nil) || !errors.Is(runtime, cause) || runtime.Error() != "structured model call failed" {
t.Fatalf("runtime classification: %v", runtime)
}