callerr

package
v0.73.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 7, 2026 License: MIT Imports: 17 Imported by: 0

Documentation

Overview

Package callerr classifies the outcome of one upstream tool call into the call-error taxonomy of Spec 113-c: an error_class (what failed), a fault_domain (whose fault it is) and, when known, the upstream HTTP status.

The classifier is pure: it reads typed errors and a small set of Facts the dispatch site collected (a per-call transport recorder, the cancellation state of the caller's context). It never inspects error message text, except for a short, documented last-resort list (see fallbackNetwork / fallbackTimeout) that applies only when the typed chain is known to have been lost.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func BeginDispatch

func BeginDispatch(ctx context.Context) context.Context

BeginDispatch returns the ctx to hand to the upstream call: it carries a transport call recorder (FR-042), which is also remembered on the note so Observe can read its facts.

func NoteOutcome

func NoteOutcome(ctx context.Context, o Outcome)

NoteOutcome records an explicit outcome for paths that fail without a typed error (a server with no client, rejected arguments). A no-op without a note.

func Observe

func Observe(ctx context.Context, result interface{}, err error)

Observe classifies a finished dispatch and notes the outcome. result is the manager's untyped return; only an mcp.CallToolResult (pointer or value) is read. A success clears any earlier outcome. A no-op when ctx carries no note.

func WithNote

func WithNote(ctx context.Context) context.Context

WithNote returns a ctx carrying a FRESH note. It deliberately shadows any note already on ctx: a code_execution sub-call is derived from its parent's context but is a separate call with its own outcome.

Types

type Class

type Class string

Class is the error_class vocabulary (FR-040).

const (
	ClassNetwork           Class = "network"
	ClassTimeout           Class = "timeout"
	ClassHTTP              Class = "http"
	ClassJSONRPC           Class = "jsonrpc"
	ClassToolError         Class = "tool_error"
	ClassSessionTerminated Class = "session_terminated"
	ClassAuth              Class = "auth"
	ClassProxyPolicy       Class = "proxy_policy"
	ClassProxyInternal     Class = "proxy_internal"
	ClassCancelled         Class = "cancelled"
)

type Domain

type Domain string

Domain is the fault_domain vocabulary.

const (
	DomainUpstream Domain = "upstream"
	DomainProxy    Domain = "proxy"
	DomainClient   Domain = "client"
)

type Facts

type Facts struct {
	// Dispatched is true once the request was handed to the mcp-go client
	// (set by core.Client for every transport, not inferred from HTTP).
	Dispatched bool
	// HTTPRequests is how many HTTP requests the call produced (0 for stdio).
	HTTPRequests int
	// ResponseReceived is true when any HTTP response was observed.
	ResponseReceived bool
	// HTTPStatus is the status of the last HTTP response, 0 if none.
	HTTPStatus int
	// CallerCancelled is true when the caller's own context was cancelled.
	CallerCancelled bool
}

Facts are the observations a dispatch site makes about one call.

func FactsFromRecorder

func FactsFromRecorder(s proxytransport.CallRecorderSnapshot, callerCancelled bool) Facts

FactsFromRecorder builds Facts from a transport recorder snapshot.

type Note

type Note struct {
	// contains filtered or unexported fields
}

Note is the per-call classification holder.

type Outcome

type Outcome struct {
	Class      Class
	Domain     Domain
	HTTPStatus int // upstream HTTP status when known, else 0
	// contains filtered or unexported fields
}

Outcome is the classification of one failed call.

func Classify

func Classify(result *mcp.CallToolResult, err error, f Facts) (Outcome, bool)

Classify maps a dispatch result onto an Outcome. The bool is false when the call succeeded (nil error and not an isError result).

Rules, first match wins (FR-041).

func InternalOutcome

func InternalOutcome() Outcome

InternalOutcome is the catch-all for a proxy-side failure.

func OutcomeFrom

func OutcomeFrom(ctx context.Context) (Outcome, bool)

OutcomeFrom returns the outcome noted on ctx, if any.

func UnavailableOutcome

func UnavailableOutcome() Outcome

UnavailableOutcome is the outcome of a call that could not be made because the upstream is not connected.

func ValidationOutcome

func ValidationOutcome() Outcome

ValidationOutcome is the outcome of mcpproxy rejecting a call's arguments before dispatch (Spec 085): the client's fault.

func (Outcome) AuditClass

func (o Outcome) AuditClass() audit.ErrorClass

AuditClass maps the outcome onto the frozen Spec 107 audit `error_class` vocabulary (FR-047), so the audit line and the activity record agree. It is total: any Outcome, including the zero value, maps to a member.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL