feat(go): add core/status with sentinel classification and close error boundary leaks

[apascal07]

Backports the error rework from the Go V2 branch (#5814, section 8) to main as a minor release: one error type instead of two, sentinel classification so callers branch with errors.Is instead of matching message text, and a flow HTTP boundary that no longer returns internal failure detail to clients. All existing code keeps compiling and behaving the same, except where noted in Compatibility and Behavior changes.

The core/status package

core split error handling across two unrelated types: GenkitError (internal, stack-capturing) and UserFacingError (safe to return over HTTP). They shared no interface, neither wrapped a cause, and the only way to distinguish failure modes was matching message text.

Before: two unrelated types, and no way to tell one failure from another except by its text.

core.NewError(core.INVALID_ARGUMENT, "model %q not found", name)
core.NewPublicError(core.INVALID_ARGUMENT, "unsupported content type", nil)

After: one type, where publicness is a property of the error rather than a second type.

status.Errorf(status.ErrInvalidArgument, "model %q not found", name)
status.PublicErrorf(status.ErrInvalidArgument, "unsupported content type %q", ct)

Every status has a base sentinel (status.ErrNotFound, status.ErrAborted, ...), and packages derive domain sentinels with Subtype, which inherits the status and still matches the parent, so callers branch at either granularity:

var ErrMaxTurnsExceeded = status.ErrAborted.Subtype("max turns exceeded")

if errors.Is(err, ai.ErrMaxTurnsExceeded) { ... } // specific
if errors.Is(err, status.ErrAborted)      { ... } // any abort

The framework ships domain sentinels for the failures callers plausibly branch on, and 187 internal call sites across 39 files now classify against a sentinel rather than raising an unclassified error:

ai.ErrModelNotFound, ai.ErrToolNotFound, ai.ErrMaxTurnsExceeded, ai.ErrToolFailed,
ai.ErrUnsupportedByModel, ai.ErrInvalidPart, ai.ErrUnresolvedToolRequest,
core.ErrConnectionClosed, core.ErrActionCompleted,
streaming.ErrStreamNotFound, streaming.ErrStreamExists, streaming.ErrStreamClosed,
streaming.ErrStreamCompleted, streaming.ErrStreamTimeout,
exp.ErrSnapshotNotFound, exp.ErrNoSessionStore, exp.ErrSessionIDRequired,
status.ErrInvalidSchema, status.ErrInvalidInput, status.ErrInvalidOutput,
status.ErrActionNotFound, status.ErrPanic

status.Errorf has real fmt.Errorf semantics (%w records a cause alongside the sentinel), and go vet treats it as a printf wrapper so format mistakes are machine-checked. The usage pattern the package documents and the framework follows:

// Classify once, where the failure mode is known:
return status.Errorf(ai.ErrToolFailed, "tool %q failed: %w", name, err)

// Add context up the stack with fmt.Errorf; the classification survives:
return fmt.Errorf("agent %q: %w", agentName, err)

// Reclassify only at a boundary where the meaning changes; status.Of
// reports the outermost classification, so the override wins:
return status.Errorf(status.ErrInternal, "store violated the snapshot contract: %w", err)

Error.Unwrap returns a single cause (the sentinel is matched through Is), so stdlib helpers and hand-rolled chain walks in logging and telemetry keep working. status.Of and status.Convert treat a non-nil interface holding a nil *Error as success rather than panicking, since a typed nil is what a func() *status.Error returning no error produces at an error-typed call site.

The HTTP boundary

Flow servers wrote err.Error() verbatim to clients, which leaked raw provider SDK text (project and model resource paths, quota detail), field-by-field schema dumps, and full internal messages on 500s. Meanwhile deliberately public errors always came back as HTTP 500, because wrapHandler's errors.As could never match *UserFacingError; Firebase auth's UNAUTHENTICATED surfaced as 500 instead of 401.

Both the JSON and SSE paths now route through one helper: the HTTP code comes from status.Of, and the message from status.PublicMessage, so a message only leaves the process when the error was built with PublicErrorf. Everything else becomes a generic string derived from the status, and the full error is still logged. GENKIT_ENV=dev is exempt (redacting there only hides the failure from the developer causing it), and the reflection API is untouched, so the Dev UI keeps full messages and stacks.

The rule applied across the framework: a message is public when it describes the caller's request and they can act on it (a stream ID they sent, a malformed body, a bad config value they passed). It is internal when it describes the deployment, even when that would be helpful, because the developer sees it in dev and in the log.

Retry and fallback stop disagreeing about unclassified errors

Both middlewares gate on a status set, and both used to reach that status by asserting for *core.GenkitError first. They drew opposite conclusions when the assertion failed: Retry treated anything that was not a GenkitError as retryable unconditionally, and Fallback refused to consider it at all.

Both now take the status from status.Of, which reports INTERNAL for an unclassified error and CANCELLED for a cancelled context. The default sets are unchanged. Two consequences: a network failure now falls back the same way it already retried, and a cancelled context stops being retried, since CANCELLED is in neither default set.

Compatibility

Every existing symbol survives, and the load-bearing decision is that GenkitError and StatusName are type aliases, not wrapper types:

type StatusName = status.Name
type GenkitError = status.Error

const INVALID_ARGUMENT = status.InvalidArgument // same type, same wire value

An errors.As for *core.GenkitError therefore still matches errors the framework now raises as *status.Error, and []core.StatusName config (Retry.Statuses, Fallback.Statuses) is interchangeable with []status.Name. A wrapper type would have compiled fine and then silently stopped matching. The deprecated constructors preserve their exact old behavior, including NewError's implicit wrapping of a trailing error argument and its Details["stack"].

Before (core)	After (core/status)
GenkitError	status.Error (alias)
UserFacingError, NewPublicError	status.PublicErrorf
NewError	status.Errorf
SchemaValidationError	status.ErrInvalidInput
StatusName + SCREAMING_SNAKE	status.Name (alias) + Go-cased constants
HTTPStatusCode	status.Name.HTTPCode
StatusFromHTTPCode	status.FromHTTPCode
AsGenkitError	status.Convert, status.Of

Two exceptions:

• The GenkitError.ToReflectionError() method is gone (Go cannot declare methods on another package's type through an alias). The package-level core.ToReflectionError(err) still works and is what call sites actually used.
• core/x/streaming moves off UserFacingError to the stream sentinels, so errors.As for *core.UserFacingError no longer matches there. That package documents itself as changing in any minor release.

Behavior changes

All observable differences on main; each is a bug fix or a deliberate tightening.

	Before	After
Public errors over HTTP	always 500	correct code (401, 400, ...)
Unclassified / provider / schema errors over HTTP	full text	generic message, status unchanged
SSE error payload	details: <full error text>	field removed
Unclassified error under Fallback	propagated, no fallback	falls back (INTERNAL)
Cancelled context under Retry	retried to exhaustion	not retried (CANCELLED)

The sample

go/samples/basic-errors demonstrates the whole pattern end to end against a live flow server, with the curl invocations in the package doc: a public INVALID_ARGUMENT that reaches the client, a custom NOT_FOUND subtype that a second flow catches with errors.Is and recovers from rather than propagating, a model-not-found that falls back to the default model, and an unclassified failure whose text the boundary redacts.

basic-agents picks up the same discipline in two places. The banker's transferMoney tool classifies a non-positive amount with status.Errorf rather than a bare fmt.Errorf, so the cause survives the runtime wrapping it as ai.ErrToolFailed and server-side code can still branch on it. The CLI switches on the status carried on the failed turn's output to suggest the right next step (resume, rephrase, wait) instead of parsing the message.

Verification

Go 1.26.3, full go build ./... and go test ./... in go/: 38 packages with tests pass, no failures. core/status alone carries 40 top-level tests, 86 including subtests.

New coverage worth naming:

• core/compat_test.go pins the alias decision: errors.As for *core.GenkitError still matches an error raised as *status.Error, the constants keep their wire values, and the deprecated constructors keep their old behavior including Details["stack"].
• genkit/servers_leak_test.go drives one case per path that used to put internal detail on the wire (relayed provider text, an output-schema dump, an unclassified error from user code) and asserts the client sees only the generic message while the status stays correct.
• core/status/nil_test.go pins that a typed nil *status.Error is inspectable through the error interface rather than panicking.

[gemini-code-assist]

Code Review

This pull request introduces a new canonical error handling package under go/core/status to replace the deprecated core.GenkitError and core.NewError mechanisms, unifying error classification across the codebase using sentinels. The review feedback correctly identifies several potential nil pointer dereference panics that can occur when methods on status.Error (such as Error(), Unwrap(), Is(), Sentinel(), and Stack()) or utility functions like status.Of() and status.PublicMessage() are invoked with typed nil pointers. Implementing the suggested nil checks will make the new error package more robust.