extproc

type Config struct {
	// IngestURL is the base URL for the tapes ingest server.
	IngestURL string
	// ListenAddr is the gRPC TCP listen address.
	ListenAddr string
	// MetricsAddr is the HTTP metrics/health listen address.
	MetricsAddr string
	// ProviderMapFile is the path to the provider mapping YAML file.
	ProviderMapFile string
	// MaxInflight is the dispatch semaphore capacity.
	MaxInflight int
	// GRPCMaxRecvBytes is the gRPC server's maximum receive message size.
	GRPCMaxRecvBytes int
	// DispatchByteBudget bounds the total marshalled payload bytes in flight to ingest.
	DispatchByteBudget int64
	// RawResponseMode selects whether the dispatch envelope carries the
	// verbatim upstream response bytes, the adapter's reduction, or both.
	// Zero value is RawResponseOff, so a Config built by a test or an
	// older caller keeps the historical wire shape.
	RawResponseMode RawResponseMode
}

type ContextObserver interface {
	OnAcceptedContext(provider string, requestID string, ctx OutcomeContext)
	OnDropContext(provider string, reason DropReason, requestID string, ctx OutcomeContext)
}

type DispatchObserver interface {
	OnDispatchLatency(provider string, requestID string, seconds float64)
	OnInflight(n int)
}

type DispatchedSessionEnvelope struct {
	OrgID                  string         `json:"org_id"`
	AuthSubject            string         `json:"auth_subject"`
	HarnessID              string         `json:"harness_id"`
	HarnessSessionID       string         `json:"harness_session_id,omitempty"`
	HarnessVersion         string         `json:"harness_version,omitempty"`
	Cwd                    string         `json:"cwd,omitempty"`
	Name                   string         `json:"name,omitempty"`
	ParentHarnessSessionID string         `json:"parent_harness_session_id,omitempty"`
	HarnessMetadata        map[string]any `json:"harness_metadata,omitempty"`
}

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

type DropReason string

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

type Observer interface {
	OnAccepted(provider string, requestID string)
	OnDrop(provider string, reason DropReason, requestID string)
}

type OutcomeContext struct {
	Method string
	Path   string
	// ThreadID is the harness sub-thread identifier (e.g. a Claude Code
	// subagent agent-id), "" for main-thread calls. It is high-cardinality
	// and surfaced ONLY in structured logs via logAttrs — never folded into
	// a metric label set. Metrics read the bounded fields below directly
	// through normalizers (see Metrics.ObserveTerminal), so this field is
	// invisible to the metrics path.
	ThreadID            string
	Endpoint            string
	Model               string
	ModelFamily         string
	Stream              string
	ContentType         string
	ContentEncoding     string
	UpstreamStatus      int
	UpstreamStatusClass string
	RequestBytes        int
	ResponseBytes       int
	ElapsedSeconds      float64
}

type Processor struct {
	extprocv3.UnimplementedExternalProcessorServer
	// contains filtered or unexported fields
}

type RawLaneObserver interface {
	// OnRawResponseAttached fires when verbatim bytes go on the wire.
	// shape is "dual" or "raw_only".
	OnRawResponseAttached(provider, shape string)
	// OnRawResponseSkipped fires when the mode wanted bytes but they were
	// withheld. The row lands fidelity:reduced.
	OnRawResponseSkipped(provider, reason string)
	// OnRawResponseFallback fires when a raw-only turn kept its reduction
	// because ingest could not have produced one.
	OnRawResponseFallback(provider, reason string)
}

type RawResponseMode string

type TurnEnvelope struct {
	Provider  string            `json:"provider"`
	AgentName string            `json:"agent_name,omitempty"`
	Request   json.RawMessage   `json:"request"`
	Response  *llm.ChatResponse `json:"response"`

	// RawResponse is the upstream response body exactly as it arrived on
	// the wire — still under whatever Content-Encoding the upstream used.
	// encoding/json renders it as standard padded base64.
	//
	// It is NOT the decoded bytes: tapes stores the column byte-faithfully
	// and decodes only to reduce, so decompressing here would make the
	// stored bytes something the upstream never sent.
	RawResponse []byte `json:"raw_response,omitempty"`

	// RawResponseEncoding is the Content-Encoding describing RawResponse.
	// Empty means identity. Ingest needs it to decode before reducing;
	// without it the bytes are unreducible archive.
	RawResponseEncoding string `json:"raw_response_encoding,omitempty"`

	// RawResponseWithheld says this adapter captured verbatim bytes for the
	// turn and chose not to send them — always because including them would
	// have pushed the envelope past ingest's body limit, and a turn without
	// its bytes beats no turn at all.
	//
	// Only the producer can know this. An envelope with no raw_response is
	// otherwise the same envelope whether the bytes never existed or were
	// dropped on the way out, and those are opposite operational facts: the
	// first says which adapters are deployed, the second says a limit bit and
	// wants tuning. Ingest folds this into raw_response_dropped; the field is
	// spelled differently on purpose, because that column is the union of "the
	// producer withheld" and "ingest capped" and this is only the first.
	//
	// It is set at exactly the two places bytes are withheld after being
	// captured — the pre-dispatch transport-budget decision, and
	// enforceBodyLimit's post-marshal strip — and nowhere else. In particular
	// it is NOT set when the mode never asked for bytes: mode=off captured
	// nothing to withhold, and marking those turns would report the whole
	// fleet as losing bytes it never had.
	//
	// Invariant, relied on by ingest, which honors the marker only when no
	// bytes arrived: withheld implies raw_response absent. Both writers below
	// clear the bytes in the same breath as setting this.
	RawResponseWithheld bool `json:"raw_response_withheld,omitempty"`

	// No omitempty: it has no effect on a non-pointer struct, and meta is
	// always sent.
	Meta TurnMeta `json:"meta"`
	// Session is the optional session-tracking block. Present
	// (non-nil) when the inbound request carried any X-Tapes-*
	// header; nil otherwise. omitempty keeps the wire shape stable
	// for tapes-ingest endpoints that don't know about session
	// blocks yet.
	Session *DispatchedSessionEnvelope `json:"session,omitempty"`
	// contains filtered or unexported fields
}

type TurnMeta struct {
	RequestID   string `json:"request_id,omitempty"`
	ContentType string `json:"content_type,omitempty"`

	// ThreadID is the harness's sub-thread identifier for this call
	// (e.g. Claude Code's subagent agent-id), "" for main-thread
	// calls. Resolved harness-neutrally by headers.ThreadID.
	ThreadID string `json:"thread_id,omitempty"`

	Method              string  `json:"method,omitempty"`
	Path                string  `json:"path,omitempty"`
	Endpoint            string  `json:"endpoint,omitempty"`
	Model               string  `json:"model,omitempty"`
	ModelFamily         string  `json:"model_family,omitempty"`
	Stream              string  `json:"stream,omitempty"`
	ContentEncoding     string  `json:"content_encoding,omitempty"`
	UpstreamStatus      int     `json:"upstream_status,omitempty"`
	UpstreamStatusClass string  `json:"upstream_status_class,omitempty"`
	RequestBytes        int     `json:"request_bytes,omitempty"`
	ResponseBytes       int     `json:"response_bytes,omitempty"`
	ElapsedSeconds      float64 `json:"elapsed_seconds,omitempty"`
}