provider

func AnswerOffer ¶

func AnswerOffer(ask string, yes bool) bool

AnswerOffer answers an open offer and reports whether one was still open.

FALSE IS A REAL ANSWER AND NOT A FAILURE: the lane came good while the person was reaching for the key, or the request finished, or the offer aged out. A surface that is told false draws nothing and says nothing, because the thing it would have said is no longer true.

The rescue runs OUTSIDE the lock. It starts a request, and a registry held across that would be a lock held across a handshake.

func ApplyAttribution ¶

func ApplyAttribution(header http.Header)

ApplyAttribution writes this binary's attribution set onto a request's headers.

IT IS EXPORTED BECAUSE THIS PACKAGE HAS NOT ALWAYS BEEN THE ONLY ONE THAT POSTS TO THE ROUTER. v1's microphone client reached /audio/transcriptions on its own — that package is gone now, and transcribe.go is the one transcription transport — but it spent a release writing out its own half of this set by hand — a referer and the old title spelling, with no X-OpenRouter-Title and no categories at all — so every word a person spoke to v1 was attributed as an unclassified app while every word they typed was attributed correctly.

So: a package that talks to OpenRouter calls this. It does not write header names and it does not carry the values.

func BaseTakesLaneChoice ¶

func BaseTakesLaneChoice() bool

BaseTakesLaneChoice reports whether the base this process is talking to has said it will carry a routing preference.

It is what a SURFACE asks — internal/tui3's lane row, so that `pinned: X` never stands on a screen as a claim about a request that did not carry it — and it takes no argument because a panel holds no client and so has no base URL of its own to name.

func CacheControlRejected ¶

func CacheControlRejected(model string) bool

CacheControlRejected reports that this model's endpoint has refused a cache breakpoint. Like ReasoningMandatory it is learned rather than published, so it is empty until some call has been told no — which is exactly what a surface should show: a fact when there is one, and nothing when there is not.

func CacheKeyFrom ¶

func CacheKeyFrom(ctx context.Context) string

CacheKeyFrom returns the run's stable cache key, empty when unset.

func CallNodeFrom ¶

func CallNodeFrom(ctx context.Context) string

CallNodeFrom is the node WithCallNode named, empty when nothing did.

func ContextSafetyTokens ¶

func ContextSafetyTokens(window int) int

ContextSafetyTokens leaves room for tokenizer and chat-template differences. It grows with small windows and is bounded on million-token models.

func DecodeJSONObject ¶

func DecodeJSONObject(text string, destination any) error

DecodeJSONObject accepts the small formatting failures common at provider boundaries: a code fence, or a sentence wrapped around an otherwise valid object. It still requires the selected object itself to be strict JSON.

It lives here rather than beside any one caller because those failures are a property of the boundary, not of the pass that happens to be crossing it. The head learned this first — a router that silently falls back to a model without structured-output support answers in prose — and the planner paid for not knowing it: every contract call on a fenced-JSON model returned "invalid character 'B' looking for beginning of value", the money was spent, and the leaf ran with no working method and said nothing about it. One extractor, one tolerance, every structured call.

func Emit ¶

func Emit(ctx context.Context, kind StreamEventKind, delta string)

Emit hands one event to whatever observer is listening on this context, stamped with the room the turn is answering for.

It is the door for the boundaries no adapter can report: a TOOL CALL is something the caller above the client does, and until this existed the only way to tell a surface about one was to invent a second channel beside the token feed. Everything the surface needs to interleave the two — order, and the room key — is already the property of this one.

Nothing listening is the ordinary case (every headless run), and it costs one context lookup. The observer contract is unchanged and still synchronous: a caller emitting from inside a read loop is paying for it in that loop.

func EmitEvent ¶

func EmitEvent(ctx context.Context, event StreamEvent)

EmitEvent is Emit for a kind that carries more than a string — today only StreamToolCallForming, whose call index, id and name are fields. The Session is stamped here from the context, so a caller never sets it and cannot set it to the wrong room.

func EmitReasoning ¶

func EmitReasoning(ctx context.Context, field, delta string, details json.RawMessage)

EmitReasoning is the test-double and adapter-neutral door for a reasoning delta whose wire identity must survive beyond the display event.

func EmptyAtCeiling ¶

func EmptyAtCeiling(response *ai.Response, ceiling int) bool

EmptyAtCeiling is the one answer shape that says more room would change the result: no text, a "length" finish, and the whole ceiling spent. It is deliberately narrower than "blank" — a refusal or a cut stream also has no text, but neither of those is cured by a larger max_tokens. It is the signature of a thinking pass that ate the answer, and it is defined once so the adapter's recovery, the reflex's, and the bill that journals a paid call all call the same thing empty.

func Evidence ¶

func Evidence(err error) taxonomy.Evidence

Evidence reads one failed request into the vocabulary the response boundary reasons in, and DECIDES NOTHING.

── WHY IT IS HERE AND NOT AT THE CALL SITE ─────────────────────────────────

A 404 used to be classified by three unrelated rules: internal/taxonomy's `classOf`, this file's `refusalKind`, and internal/session's `providerCouldNotServe`. Each was correct about the half it had been told, each grew a special case every time a wave met a new shape — #835 added `Evidence.Routing` to work around a fourth — and the class that mattered most fell through all of them: an account's privacy setting reached a person as `the request itself was refused`, with two other machines idle.

So the split is the other way round now. THIS TRANSPORT KNOWS FACTS and says them: what status it wore, who refused, whether a list emptied the set, whose list it was, whether the model is still carried, whether the request fitted. ONE FUNCTION TURNS FACTS INTO A MOVE (taxonomy.Classify), and it is the only place in the build that may. A law test holds the line (internal/provider/classifier_law_test.go).

The facts themselves were all decided at the refusal door, once, on the way past ([markRefusal], [apiError]); nothing is re-read from a sentence here. What is NOT on this evidence is everything the transport cannot see — whether a stream guard cut, how many attempts this model has had, whether the caller has another model — and those are the caller's to add before it classifies.

func FailedLane ¶ added in v0.3.0

func FailedLane(err error) string

FailedLane is the upstream lane a failed call names, "" when the failure implicates nobody — the wire fact a retry turns into a lane to avoid. A 5xx relayed from a named upstream names that provider, a cut stream names the provider the stream named; a router's own refusal carries no provider name, a transport fault names no machine, and an empty name is a fact the retry keeps: the retry goes where it always went.

func FinishReason ¶

func FinishReason(response *ai.Response) string

FinishReason reports the provider's own word for how a completion ended, or "" when it never said. It reads the first choice because that is the only one the adapter assembles: the streaming path builds exactly one, and single responses are requested with n=1.

func ImageExtension ¶

func ImageExtension(data []byte, declared string) string

ImageExtension names an image from its bytes, using the provider's declared type only when the bytes do not identify a supported format. The saved suffix must describe what a file contains even when a provider mislabels its reply.

func InstallLaneProber ¶

func InstallLaneProber(c *Client, waiting lanes.ProbeGate) bool

InstallLaneProber wires this client's transport into the registry's prober, and reports whether it did.

waiting is the caller's own answer to "is anybody waiting on this model right now" — the λ of the design, which only a surface can know. Nil is "always", which is the right reading for a headless run that probes at all.

IT REFUSES A CLIENT WHOSE BASE WILL NOT CARRY A DEMAND. A probe's whole body is a `provider.only`, and a probe without it measures whatever endpoint happened to answer, which is a number worse than none. Since issue #433 that is the base's own answer and never its hostname: a base nobody has asked is wired, because the asking is the sending — and nothing is ever bought there until a lane exists to name, which is the real floor (Client.ProbeLanes reads the frontier and an empty one buys nothing).

func InstallRouting ¶

func InstallRouting(strategy RoutingStrategy)

InstallRouting states the routing row this process's clients answer to, for every client that is handed no RoutingSource of its own. The empty strategy is NOBODY HAVING WRITTEN ONE and puts the knob back to exactly that, which is what an unwritten row resolves to — DefaultRouting, the same answer for every call.

func IsConnectionUnavailable ¶

func IsConnectionUnavailable(err error) bool

IsConnectionUnavailable distinguishes a spent connection wait from a model failure. There is no underlying provider error for a fallback to repair.

func KeyExpiredFrom ¶

func KeyExpiredFrom(err error) bool

KeyExpiredFrom keeps the expiry fact after the engine wire has flattened a refusal into text, so hosted and local conversations refresh the same reading.

func LaneGuardOn ¶

func LaneGuardOn() bool

LaneGuardOn reports whether the speed guard is on.

func LaneSheetCertain ¶

func LaneSheetCertain(base string) bool

LaneSheetCertain reports whether base is KNOWN to publish a lane sheet without anybody having to ask it: the shipped router, recognised by its hostname.

IT IS A HINT AND NEVER A REFUSAL. This build used to decide whether the endpoints page was fetched at all by this very substring test, so a binary driven through CODEAF_BASE_URL at a proxy, a mirror, a self-hosted router or the router reached by its IP silently got no sheet, an empty frontier and no lane behaviour whatever — nothing errored and nothing logged a refusal, the feature was simply absent (issue #373). A ROUTER IS RECOGNISABLE BY WHAT IT ANSWERS AND NEVER BY A SUBSTRING OF WHERE IT LIVES: every base is wired, and the sheet learns from the base's own first answer whether there is a page there (lanes.ErrNoSheetHere). What this hostname buys is only that the one base everybody already knows about skips straight to "serves", so the shipped path is unchanged in behaviour and pays not one extra round trip.

IT IS THE BASE URL AND NEVER THE MODEL ID, which is where it parts company with [Client.shippedRouterHint]. That one is also true of a client whose model is spelled `openrouter/...` behind somebody's own gateway, and it is right to be: the ledger still learns from what that gateway serves. But the sheet is fetched FROM THE BASE URL, so the base is the thing a hint can be about.

func LaneTalkAsk ¶

func LaneTalkAsk(model string, now time.Time) lanes.Request

LaneTalkAsk is the request A CONVERSATION'S OWN TURN makes, with nothing yet typed into it: one model, a person waiting, an answer they will read.

It gives the picker the same value of waiting and quality requirement as a conversation. The row is a preview: the actual request adds its prompt, cache lineage and learned work size before deciding where to send it.

The prompt's own length is left out and so is its cache prefix: neither is known before somebody has typed. Output size is unknown too: no workload class or reasoning setting has been selected for this preview.

func LeafCacheKey ¶

func LeafCacheKey(run, leaf string) string

LeafCacheKey derives one leaf's affinity key from its run's. It is a pure function of the two identities — no clock, no counter, no attempt number — so every turn of one leaf produces the same key and a retried leaf rejoins the prefix its first attempt warmed.

func LoadQuirks ¶

func LoadQuirks(dir string)

LoadQuirks seeds the process from a profile directory and names the file later discoveries are written to. Empty dir means ~/.codeaf, which is where every other durable codeaf fact lives.

It is called once at startup, before any request is shaped. Calling it twice re-reads the file, which is harmless: the memo only ever grows, and a fact learned in memory is never dropped by a read.

func LostItsThread ¶

func LostItsThread(text string) bool

LostItsThread judges text that has ALREADY streamed — a reply a person stopped by hand — by the same tests the live guard runs, read once over its tail. It exists for the one road junk still had into the transcript: the guard cuts a stream it wins the race against, and a person who stopped the stream first was handed the soup as their own kept reply, replayed on every request after (internal/session's keepPartial). Nothing here is a second opinion — it is the same window, the same floor, the same compressor.

func MachineryLeak ¶

func MachineryLeak(request *ai.Request, response *ai.Response) bool

MachineryLeak reports that a reply is the model's own tool grammar written as text: the request declared tools, the answer called none, and the content is symbol-dense text that spells a declared tool's name fenced in symbol runes.

IT NEVER SPEAKS WHERE A FENCE IS OPEN. A reply that carries ``` anywhere is showing code on purpose — a person asked what a tool call looks like, and the honest answer is symbol-dense and names a tool. The cost of that conservatism is one failure mode deliberately kept: a leak that happens to emit a code fence goes uncut and the person sees it — which is exactly the old behaviour, not a regression.

func ModelsTried ¶

func ModelsTried(ctx context.Context) []string

ModelsTried names every model this question has been put to, in the order it was put to them. It is the FACT a caller choosing the next model reads instead of counting its own hops.

A context with no record answers nothing, which a caller must read as "no model has been ruled out" rather than as an error: a build with no chain, a call made outside a turn, and `--one-model` all arrive here, and each of them wants the move to be ABSENT rather than broken.

func NodeFrom ¶

func NodeFrom(ctx context.Context) string

NodeFrom is the subject in force for ctx, empty when none was said — which reads as the conversation.

func NoteAnswerCut ¶

func NoteAnswerCut(model, lane string, spent int) bool

NoteAnswerCut records that a model ran out of room mid-answer on one lane, and reports whether that is wider than anything already known. Only a wider cut is worth a write: a model that cuts on every call of a lane costs the profile one save, not one per call.

The figure recorded is what the model actually SPENT, never what it was allowed — a provider that stops short of the ceiling has told us where its own wall is, and that is the more useful of the two numbers.

func NoteReasoningDisableIgnored ¶

func NoteReasoningDisableIgnored(model string)

NoteReasoningDisableIgnored remembers that a model accepted the disable but still spent an answer-sized ceiling without returning any answer. The provider adapter cannot infer this from the HTTP exchange alone: the caller owns the promise that the requested ceiling was large enough for its answer.

func NoteServedWindow ¶

func NoteServedWindow(model string, tokens int) bool

NoteServedWindow records that a model REFUSED a prompt of this many tokens for being too long, and reports whether that narrows what was already known.

It is the one way a published window is ever contradicted, and the evidence bar is deliberately high: not a slow answer, not a bad answer, but the endpoint saying in as many words that the request would not fit. Anything less is a claim this process cannot check, and a ceiling built on a guess is how a model with real room gets folded like a small one.

Only a NARROWER figure is worth a write, so a session that keeps overrunning the same wall costs the profile one save rather than one per turn.

func OnPhase ¶

func OnPhase(fn func(PhaseNews)) (previous func(PhaseNews))

OnPhase registers the reader every phase change is told to and hands back the one that was there, so a surface that opens over another can put it back when it closes. A nil function unregisters.

func PersonAtTheDoor ¶

func PersonAtTheDoor() bool

PersonAtTheDoor reports whether a typed command owns this process.

func PinNow ¶

func PinNow(model string) (demanded, standDown string)

PinNow is that answer and the other half of it, read together: the machine a request for model will demand, and the machine a person's row still names after the wire has stopped asking for it ([retirePinnedLane]).

TOGETHER FOR [lanePinFor]'s REASON ONE LAYER UP. The two are one fact about one moment — is the row on the wire, and if it is not, whose name is still on the screen — and a surface that asked them as two questions could draw a machine's name beside a sentence saying nothing is asking for that machine, or draw neither.

AND IT IS THE ONE DOOR EVERY SURFACE THAT NAMES THE PIN COMES THROUGH (internal/tui3's laneInForce). The chip, the model row's tail and the fold's mark were drawn from the SETTINGS ROW while the wire asked this file, so a pairing the wire retired mid-session left `@morph` on the model word over three turns another machine answered (issue #1022). The model is folded here, by [lanePinFor], under the same normaliser the retirement was written with — a surface folding a spelling of its own would rebuild that disagreement one layer down.

A BASE THAT WILL NOT CARRY A LANE CHOICE AT ALL ANSWERS NEITHER, and that is deliberate: no request demands the machine, so nothing may name it, and what a person reads about that is the base's own sentence (UncarriedPinLine) rather than this one.

func PinnedFor ¶

func PinnedFor(model string) string

func PlanPauseSentence ¶

func PlanPauseSentence(reset, overflowDoor string) string

PlanPauseSentence is the one person-facing sentence for a temporarily spent subscription window, shared by live status, the final row, and connection.

func ProseAnswerAsked ¶

func ProseAnswerAsked(ctx context.Context) bool

ProseAnswerAsked reports the mark above. It is exported for MessageReasoningFrom's reason: a Completer test double has to be able to assert the same contract the real adapter reads, without learning this package's private context key.

func ReasoningBudgetRefused ¶

func ReasoningBudgetRefused(model string) bool

ReasoningBudgetRefused reports that this model's endpoint rejected a thinking budget. Like the fact above it is learned rather than published — no catalog row says it — so it is empty until some call has been told no.

func ReasoningDisableIgnored ¶

func ReasoningDisableIgnored(model string) bool

ReasoningDisableIgnored reports that a model accepted the disable but still consumed the caller's whole answer budget before returning any text.

func ReasoningMandatory ¶

func ReasoningMandatory(model string) bool

ReasoningMandatory reports that this model's endpoint has refused to have its reasoning turned off. It is learned rather than published — no catalog field says it — so it is empty until some call has been told no, and then it stays known across processes (see LoadQuirks). A surface should show exactly that: a fact when there is one, and nothing when there is not.

func ReasoningUnavoidable ¶

func ReasoningUnavoidable(model string) bool

ReasoningUnavoidable reports either observed way a model has shown that its thinking pass cannot be removed. Callers that reserve a small answer budget need the combined fact; request encoding still reads the two facts separately because only a rejected disable must be omitted from the wire.

func RepinLane ¶

func RepinLane(pin LanePin)

RepinLane is SetLanePin as A PERSON'S ACT: the picker, `/model @cloudflare`, the `lane` row in the settings panel — anywhere somebody has just said, in their own words, which machine they want.

IT FORGETS EVERY REFUSAL WHATEVER THE ROW SAYS, and that is the whole difference from the setter above. Re-choosing the SAME lane is a row that did not change and an instruction that did, and it is the exact keystroke the manual promises works: "pinning again puts it straight back". A build that compared rows here would answer a person who had just re-pinned coreweave with silence, and go on routing their model on auto — which is the sentence on their screen made into a lie.

AND IT FORGETS WHAT THE ACCOUNT WAS BELIEVED TO EXCLUDE about that machine (internal/lane's account.go), for the same reason and before the lock is taken — a neighbouring package is never called under this file's lock. A person who has just re-chosen the machine the router said their account cannot reach may have changed the setting, and the next request is how to find out.

func Report ¶

func Report(ctx context.Context, reading Reading)

Report records how a unit of work turned out. It is the call site's half of the contract, and it is idempotent: the first reading wins, so an error path that reports and then falls through to a shared return cannot overwrite what it already said. A call nobody reports on stays unverified, which is the honest answer rather than a missing one.

func RetiredPinLine ¶

func RetiredPinLine(lane string) string

retiredPinLine is the whole sentence, and it is spelled ONCE, here.

Two surfaces say it — the status line while the answer is in flight (internal/tui3's laneRider) and the conversation, which keeps it — and a sentence spelled in two places is a sentence that gets reworded in one. The machine is named the way the person spelled it when they pinned it, because that is the row they will go and look at. RetiredPinLine is that sentence for a surface that has to draw it beside its own furniture (internal/tui3's laneRider). It is exported rather than copied for the reason the two words above it are constants: three packages would otherwise spell one sentence, and a sentence spelled in three places is a sentence that gets reworded in one.

func RetiredPinTail ¶

func RetiredPinTail(lane string) string

RetiredPinTail is the same fact in the room a SETTINGS ROW has for it: `(morph cannot serve this model)`, drawn after the word `auto` on the row whose machine is no longer being asked for (internal/tui3's laneWord).

IT IS A THIRD GRAIN OF ONE FACT AND NOT A THIRD CLAIM, which is the same licence the rider and the parked line already take ([retirePinnedLane]): the sentence a person reads in the conversation says what happened and what happens next, and a row they come back to look at has one line to say why the machine they wrote down is not the machine answering. It is spelled here so that all three move together the day the wording moves.

func RetryAvoidFrom ¶ added in v0.3.0

func RetryAvoidFrom(ctx context.Context) []string

RetryAvoidFrom is the list of lanes the caller has asked this call's bodies to ignore, nil when the call is not a retry after a named failure. It is the read side of WithRetryAvoid, exported for the layer that composes the retry and asserts what it stamped.

func RoleFrom ¶

func RoleFrom(ctx context.Context) lanes.Role

RoleFrom is the role in force for ctx, [lane.RoleUnknown] when none was said.

func RoutingRefusal ¶

func RoutingRefusal(err error) bool

RoutingRefusal reports that an error is the router saying NOTHING IT CAN REACH will serve this request as it stands — and that somewhere else still can: another machine once the list comes off, another model after that. It is the typed fact APIError.Routing carries, asked from anywhere in a chain.

A SPENT LADDER IS NOT ONE. RefusalError is what the endpoint ladder returns once it has relaxed the request, dropped the ceiling and walked the fallback models without an answer; it wraps the router's last refusal, and reading THAT as somewhere left to go would send a caller round the whole ladder again to be told the same thing. What it carries is a diagnosis for a person.

func RunCacheKey ¶

func RunCacheKey(task, model string) string

RunCacheKey derives a run's cache key from the run's own identity rather than from a clock or a random source. Two requests inside one run must produce the same key or the affinity is worthless, and deriving it from the task and model also lets a repeated identical run reuse the warm prefix instead of paying to write it again.

func ServedWindow ¶

func ServedWindow(model string) int

ServedWindow answers the narrowest prompt this model has ever been refused for, in tokens, and zero when it has never been refused for length.

ZERO MEANS NOTHING WAS LEARNED, which is the honest reading and the one that leaves the model card's own figure standing alone. A caller must not read it as "this model has no window" — that is the emptiness law applied to a measurement, and internal/session's TrustedWindowFor is written to it.

func SessionFrom ¶

func SessionFrom(ctx context.Context) string

SessionFrom is the conversation in force for ctx, empty when none was said.

func SetLaneGuard ¶

func SetLaneGuard(on bool)

SetLaneGuard turns the speed guard on or off, and it is the ONE switch: it moves the rescue and the probe together, because both are the same promise to a person — that this build may spend a little extra to keep an answer moving — and a row that turned off half of it would be a row nobody could reason about.

OFF IS A PURSE THAT REFUSES EVERYTHING rather than a flag the race consults. The purse is already the one gate every rescue passes through ([hedgeRace.affords]), so a purse that says no is the whole of "do not rescue" with no second path to keep in step — and it is written onto the plan where every arm of the question reads it (waitplan.go). The probe reads the flag directly, because a probe is not priced in dollars: it is gated on whether anybody is waiting.

func SetLanePin ¶

func SetLanePin(pin LanePin)

SetLanePin states which machine this process's conversation asked for. It is called from wherever the routing row is resolved — the surface, once, at launch — and again by the picker when somebody pins from it.

func SetPaymentRequiredHook ¶

func SetPaymentRequiredHook(call func(string)) func()

SetPaymentRequiredHook connects any client's 402 to the local chat door. The returned function removes only this registration when that door closes.

func SetPersonAtTheDoor ¶

func SetPersonAtTheDoor(here bool)

SetPersonAtTheDoor states whether somebody typed the command this process is running. It is what lets a headless command's calls — its planning pass and the nodes the session's executor runs for it, whose roles are not ones a person reads — carry the talk pin under `simple` and count as watched (internal/session's someoneIsWatching), without the command opening a conversation it does not have. Tests hand it false again.

func SharedTransport ¶

func SharedTransport() *http.Transport

SharedTransport is the process-wide connection pool for provider traffic. One pool rather than one per client: the clients (talk, work, boost, media, vision) all address the same account at the same host, and a pool each would mean a handshake each.

func StatusOf ¶

func StatusOf(err error) (int, bool)

StatusOf returns the HTTP status a provider failure carried, including the status in the legacy `API error (N)` spelling. The fallback is centralized here because an in-band or wrapped failure can lose its structured status; retry and response boundaries must still make the same decision.

func Streaming ¶

func Streaming(ctx context.Context) bool

Streaming reports whether a call made on this context is served over the event stream. It is what tells an empty finish reason apart: no terminal frame on a stream is a dropped connection, while a single response that omitted the field is just an endpoint being terse.

func SummaryOutputReserve ¶

func SummaryOutputReserve(profile ReasoningProfile, answer int) int

SummaryOutputReserve is the space a summary chunk must leave behind its prompt when the catalog publishes a floor above the summarizer's low ask. The provider's wire sizing uses the same reasoningCeiling calculation.

func UncarriedPinLine ¶

func UncarriedPinLine(lane, base string) string

UncarriedPinLine is that sentence for a surface that has to draw it beside its own furniture, exported for RetiredPinLine's reason: a sentence spelled in two packages is a sentence that gets reworded in one.

func UnclosedJSONObject ¶

func UnclosedJSONObject(text string) (string, bool)

UnclosedJSONObject answers the one question a truncated reply raises: did the model BEGIN an object and get cut off, or did it never start one?

The two failures arrive at the same door and want opposite repairs. A reply that opened a brace and ran out of room is half bought — the expensive tokens are already in hand — and the right move is to ask for the rest of it. A reply with no brace anywhere spent its whole ceiling on something else (prose, or private deliberation) and there is nothing to continue; that one is asked again. Telling them apart is a structural reading of the text and never of the finish reason, which is the same law DecodeJSONObject is written under.

It returns the text from the first unterminated brace to the end, which is exactly the prefix a continuation is appended to. It answers false whenever a complete object is present, so a caller that has already decoded never reaches it, and false when no brace was ever opened.

func UnmeteredReceiptsFrom ¶

func UnmeteredReceiptsFrom(ctx context.Context) bool

UnmeteredReceiptsFrom reports whether WithUnmeteredReceipts armed ctx.

func ValueOfTimeFrom ¶

func ValueOfTimeFrom(ctx context.Context) (float64, bool)

ValueOfTimeFrom answers what a second is worth on the calls made under ctx, and whether anybody said. It is the read half of WithValueOfTime, exported so a surface can assert what its own calls will ask for.

func WidestAnswerCut ¶

func WidestAnswerCut(model, lane string) int

WidestAnswerCut answers what this model has been seen to spend before being cut off on this lane, zero when it has never been cut off here. Zero means "nothing was learned", which is the honest reading and the one that leaves the derived ceiling standing alone.

func WireLaneSheet ¶

func WireLaneSheet(base, key string)

WireLaneSheet points the live lane sheet at a base, with the bearer a fetch should carry. It is the one door through which internal/lane is handed a transport, and it is exported because two callers need it and a second spelling of it would drift: NewClient wires the base its client talks to, and the process's own beat (cmd/codeaf's lanebeat.go) wires the base the settings name, because on three headless doors the beat starts before any client exists and a beat over an unwired sheet fetches nothing at all.

Wiring is not a fetch — it hands the sheet a base, a bearer and something that can open a connection, and nothing goes to the network until a beat calls Refresh. Wiring the same base twice is harmless: the sheet keeps what that base already answered, and forgets it only when the base itself moves.

EVERY NON-EMPTY ROUTER BASE IS WIRED. Whether there is an endpoints page at it is the base's own to say, once, and the sheet remembers (LaneSheetCertain says why the hostname is a hint here and not the decision). A connected direct service never comes through this door because it owns one road and must not repoint the default account's process sheet.

func WithBilling ¶

func WithBilling(ctx context.Context, sink BillingSink) context.Context

WithBilling arms one piece of work's banking. Like the transcript sink it belongs to the work rather than to the client, because one client serves every node in the process.

func WithCacheKey ¶

func WithCacheKey(ctx context.Context, key string) context.Context

WithCacheKey pins one run's provider affinity. It is set once, at the top of a run, and inherited by every nested worker and synthesis call through the ordinary context tree, which is exactly the property a prefix cache needs: one run is one cache lineage, and no request-time randomness can split it.

func WithCall ¶

func WithCall(ctx context.Context, class CallClass) context.Context

WithCall opens a slot for one unit of work and stamps what kind of call it is. The class named here loses to an override set further out — see WithCallClass.

func WithCallAttempt ¶

func WithCallAttempt(ctx context.Context, class CallClass, attempt int) context.Context

WithCallAttempt opens a slot for a retry. The attempt number is how a caller asks for escalation without knowing anything about the panel: attempt 1 means "whatever you chose last time was not good enough", and it is the router's job to decide what that costs.

func WithCallClass ¶

func WithCallClass(ctx context.Context, class CallClass) context.Context

WithCallClass overrides the class every call opened under ctx belongs to.

It exists for the one case where the same code means two different things: a fan-out at the top of a plan is drawing the whole graph from the goal, while the same function inside an expansion is splitting one oversized node against a far narrower premise. Those are different populations, and a ledger that pooled them would learn the average of two things it could have known separately.

func WithCallHorizon ¶

func WithCallHorizon(ctx context.Context, calls int) context.Context

WithCallHorizon states roughly how many more model calls the work under ctx expects to make. It sizes exploration and nothing else: a three-call errand should never pay to find out whether a lane it has not used is quicker, and a five-hundred-call swarm should find out early (Part II §7 of the design).

func WithCallNode ¶

func WithCallNode(ctx context.Context, node string) context.Context

WithCallNode names the work a call belongs to — a plan node's key, a task's id — so a log full of leaf calls can be read one node at a time. It is separate from the tag because the two are known in different places: the tag is a fact about the code making the call, the node a fact about the work.

func WithCallProgress ¶

func WithCallProgress(ctx context.Context, watcher CallWatcher) context.Context

WithCallProgress attaches the one callback this package makes about a call while the call is still running: going out, parked on a provider's pacing, thinking, writing, and how it ended.

WHAT REPORTS IS EVERY STREAMED CALL THAT RUNS UNDER A WAITING CONTROLLER, and that is the honest bound rather than "every call". The report is opened at [Client.completeWithMessagesStreaming], so anything that never reaches that door says nothing; and what fills it comes through a [streamWatch], which is installed from one site — hedge.go's startArm, under [Client.raceFor]'s gate — so a build with no controller installed (`internal/lane`'s seam, which a shipped binary always fills) reports nothing either. A watcher attached to a call that cannot report is SILENT rather than wrong; if that empty state ever becomes a real door rather than a test's, the fix is to give the bare stream loop a watch, not to feed this from somewhere else.

IT IS CALLED SYNCHRONOUSLY FROM THE READ LOOP AND MUST DO NO WORK. See the type's own doc; the same law WithPacingNotice states in patience.go.

A nil watcher is nobody listening and the context comes back unchanged, so a caller with a conditional surface may pass what it has.

func WithCallShape ¶

func WithCallShape(ctx context.Context, class CallClass, attempt int, shape string) context.Context

WithCallShape opens a slot and names the sub-population this call belongs to within its class.

A class is the grain ability varies at across *kinds of work*; a shape is the grain it varies at within one kind. It exists for exactly one class today. `exec.leaf` covers every leaf the executor runs, and arm B measured what that costs: five leaves that exhausted their budget on one oversized task moved the single global leaf rating far enough to reroute the leaves of every other task, including two where the demoted model had never once failed. A rating is only transferable between calls drawn from the same population, and leaves are not one population.

The shape is the call site's to name because only it knows: the router sees a conversation, the scheduler sees the node the conversation is for. Empty means the class is not divided, which is every planning call — those are already one request against one schema, which is as narrow as a population gets.

func WithCallTag ¶

func WithCallTag(ctx context.Context, tag string) context.Context

WithCallTag names what a call is FOR — "turn", "leaf", "compile", "gate", "reflex" — for the one reader that cannot work it out for itself: a person reading the log a fortnight later.

It rides the context for the reason patience does (patience.go): the adapter underneath is shared by every agent in the process, so the call is the only thing that knows whose call it is.

A call that sets no tag is not untagged if it opened a routing slot: the tag falls back to that slot's class, shortened to its own last word (callTag), so `plan.brief` reads as "brief" without anybody spelling "brief" twice.

func WithConfiguredEffortRung ¶

func WithConfiguredEffortRung(ctx context.Context, rung effort.Rung) context.Context

WithConfiguredEffortRung carries a rung a PERSON chose — a dialled conversation, a task somebody set, the install's own default. It is sent even when the catalog cannot vouch for the model, which is the difference WithConfiguredReasoningEffort draws and the reason it exists: an operator's choice is worth one round-trip to discover an endpoint refuses it, and a harness's guess is not.

func WithConfiguredReasoningEffort ¶

func WithConfiguredReasoningEffort(ctx context.Context, effort Effort) context.Context

WithConfiguredReasoningEffort carries an operator-configured effort, which is sent even when the catalog cannot vouch for the model.

func WithContextBudget ¶

func WithContextBudget(ctx context.Context, budget ContextBudget) context.Context

func WithDiscardedUsage ¶

func WithDiscardedUsage(ctx context.Context, observe func(model, tag string, response *ai.Response)) context.Context

WithDiscardedUsage observes a paid response superseded by an internal retry. The final response keeps its own usage: summing attempts into it would make its context size and cache counts describe a different request. Observers compose so the ledger and each budget owner can retain their own accounting. A full WithBilling owner already receives every attempt; ledger observers must defer to that owner, while budget observers still need this notice.

func WithEffortRung ¶

func WithEffortRung(ctx context.Context, rung effort.Rung) context.Context

WithEffortRung carries a rung the HARNESS chose for one phase — a sentinel's yes-or-no, a standing check. The catalog gate drops it on a model that cannot be vouched for, so a default depth can never break a run on an unknown model.

func WithExpectedAnswer ¶

func WithExpectedAnswer(ctx context.Context, tokens int) context.Context

WithExpectedAnswer says how many output tokens this answer is expected to run to. It is the sunk cost in the watch's commitment rule and nothing else.

func WithFirstPrompt ¶

func WithFirstPrompt(ctx context.Context) context.Context

WithFirstPrompt marks this call as a profile's first prompt: nobody has chosen a talk model yet, so a stall must name `/model` instead of sitting silent. Set by the session when [config.FirstPrompt] is true.

func WithHedgeReport ¶

func WithHedgeReport(ctx context.Context, slot *HedgeReport) context.Context

WithHedgeReport asks the adapter to write down, in the caller's own slot, what the race did to the calls made under ctx.

func WithLaneChoice ¶

func WithLaneChoice(ctx context.Context, choice lanes.Choice) context.Context

WithLaneChoice carries one request's lane choice to the transport.

func WithLeafCacheKey ¶

func WithLeafCacheKey(ctx context.Context, leaf string) context.Context

WithLeafCacheKey narrows the run's affinity to one leaf.

A routing key is not a cache: it is the answer to "which replica should serve this?", and a provider with an automatic prefix cache can only hit when the same replica sees the same bytes twice. The run key gets the first half of that right — every turn of every leaf of one run asks for one destination — and the second half wrong, because the six leaves of a fan-out run CONCURRENTLY with six different transcripts. They are then six growing, unrelated prefixes competing for one replica's cache, which is what the ledgers showed: cache reads quantized in 256-token steps, a third of the re-sent dollars missing a cache that a stable prompt should have hit.

Narrowing to the leaf splits those six lineages apart. What it gives up is the shared head — the system message and the tool block, which every leaf of a run really does share byte for byte — now written cold once per leaf instead of once per run. That trade is not close: the head is a few thousand tokens written once per leaf, and the tail it protects is the whole transcript re-sent on every turn of that leaf. On Anthropic-family endpoints it is not even a trade, because their cache is content-addressed and the explicit breakpoint on the head is shared across leaves whatever the routing key says.

The leaf key is derived FROM the run key rather than replacing it, so a run's requests still share a namespace a provider or an operator can see, and a leaf with no run key set stays unkeyed rather than inventing a lineage of its own.

func WithMessageReasoning ¶

func WithMessageReasoning(ctx context.Context, reasoning []MessageReasoning) context.Context

WithMessageReasoning attaches the sidecar for one request. The slice is copied because a request may outlive the transcript lock that assembled it.

func WithModelsTried ¶

func WithModelsTried(ctx context.Context) context.Context

WithModelsTried opens the record for one question. Opening it twice on one chain of contexts keeps the OUTER one, so a turn's record survives every child context its calls and errands derive.

func WithNode ¶

func WithNode(ctx context.Context, subject string) context.Context

WithNode says which subject the calls made under ctx are about — a task node's own identity, and nothing at all for the conversation itself.

func WithPacingNotice ¶

func WithPacingNotice(ctx context.Context, notice func(bool)) context.Context

WithPacingNotice attaches the one callback the retry loop makes: true when a call parks on a provider's pacing, false when it stops being parked — because it got through, or because it gave up.

It is a bool and not a reason, and that is the contract rather than a shortcut. What is upstream of this is a surface drawing a queue, and a surface has no use for a status code; what it needs is whether the thing is moving. The word a person eventually reads is chosen where the words live (internal/session's task_contract.go), not here.

The notice is called from the sending goroutine, synchronously, so it must not work: the one live implementation sets a field and announces, which is the budget it has.

ITS SIBLING IS WithCallProgress (callprogress.go), which carries the other half of a call's life — it went out, it is writing, it ended — under the very same law about doing no work. This one is about the wait BEFORE the request reaches a machine; that one begins where this one ends.

func WithPatientRateLimits ¶

func WithPatientRateLimits(ctx context.Context) context.Context

WithPatientRateLimits marks every call made under ctx as one that MAY WAIT for a window when there is nowhere else to send the request: the bounded 429 patience in retry.go stops applying, the wait is the window the machine itself named (capped at maxProviderWait), and the context is still the only thing that ends the call.

IT IS NOT PERMISSION TO ASK THE SAME MACHINE AGAIN WHILE ANOTHER IS FREE. A patient call walks the machines exactly as a watched one does and reaches a wait by the same road — every machine it may use being held at once.

It says nothing about faults. A timeout, a torn connection and a 500 keep the short patience they always had, here as everywhere: those are the provider failing, and repeating a failure is not patience.

func WithPlanOverflowGuard ¶

func WithPlanOverflowGuard(ctx context.Context) context.Context

WithPlanOverflowGuard gives every request belonging to one turn the same one-shot billing decision. Repair, relaxation, hedge and model-hop re-entry all derive contexts from this one, so none can buy a second metered attempt after another road has already taken the separately authorised overflow.

func WithProseAnswer ¶

func WithProseAnswer(ctx context.Context) context.Context

WithProseAnswer marks a call whose words are A REPLY SOMEBODY READS rather than a value something parses. It is what turns the promotion on.

func WithReasoningEffort ¶

func WithReasoningEffort(ctx context.Context, effort Effort) context.Context

WithReasoningEffort scopes a harness phase default to one call. The harness sets it around the calls whose job is routing or phrasing rather than thinking. EffortNone is itself a request — "send nothing, let the model use its own default" — and it shadows any effort set further out, which is how an inner phase escapes a run-wide economy like EffortOff.

func WithReceiptPending ¶

func WithReceiptPending(ctx context.Context, pending ReceiptPending) context.Context

WithReceiptPending arms one piece of work to be told about every receipt queued on its behalf and when each was answered (ReceiptPending). It changes nothing about how a receipt is fetched or banked: the money still reaches the work through WithReconcile alone.

func WithReconcile ¶

func WithReconcile(ctx context.Context, sink ReconcileSink) context.Context

WithReconcile arms one piece of work for a receipt that arrives after its call has already ended. It is separate from WithBilling so an ordinary usage block and a late receipt can never both bank the same call.

func WithRequiredReasoningEffort ¶

func WithRequiredReasoningEffort(ctx context.Context, effort Effort) context.Context

WithRequiredReasoningEffort carries an effort that is part of the call's correctness rather than an optional economy. A reflex with a tiny answer cap is the measured case: silently dropping its disable leaves a reasoning model no tokens in which to answer, so an unknown catalog row must not erase it.

func WithRetryAvoid ¶ added in v0.3.0

func WithRetryAvoid(ctx context.Context, lanes []string) context.Context

WithRetryAvoid asks every request made under ctx to carry the named lanes in its routing preferences' ignore list. Names are trimmed, deduplicated and emptied of blanks; a list that holds nothing changes nothing.

func WithRole ¶

func WithRole(ctx context.Context, role lanes.Role) context.Context

WithRole says who the calls made under ctx are for.

func WithRoutingIntent ¶

func WithRoutingIntent(ctx context.Context, intent RoutingIntent) context.Context

WithRoutingIntent states who is waiting on the calls made under ctx.

IT IS SAID AND NEVER INFERRED. "Nobody is watching this stream" is close to the answer but is not it: a tool that asks a model something takes the observer off the context and the person is still sitting there waiting for the turn it belongs to. Only the call site knows whether anybody is waiting, so only the call site may say — and a call that says nothing keeps the behaviour it has always had.

func WithServedEndpoint ¶

func WithServedEndpoint(ctx context.Context, slot *ServedEndpoint) context.Context

WithServedEndpoint asks the adapter to write down, in the caller's own slot, which endpoint answered each call made under ctx.

func WithSession ¶

func WithSession(ctx context.Context, key string) context.Context

WithSession says which conversation the calls made under ctx belong to.

func WithStreamObserver ¶

func WithStreamObserver(ctx context.Context, observer StreamObserver) context.Context

WithStreamObserver asks the adapter to stream this completion while still returning the ordinary accumulated response to its existing caller.

func WithStreamSession ¶

func WithStreamSession(ctx context.Context, session string) context.Context

WithStreamSession stamps the room a turn is answering for. The caller that owns the turn (the head, one per turn) sets this on the turn's context before making the provider call; every StreamEvent that call emits carries it, so a consumer fed by more than one room can tell them apart.

func WithThinkingWall ¶

func WithThinkingWall(ctx context.Context, wall time.Duration) context.Context

WithThinkingWall carries the wall one completion runs under, so the thinking pass in front of its answer is told how long it has ([Client.wallBudget]).

It keeps whatever effort is already on the context and adds only the wall, and it is applied by the wall itself — last, on the context the completion is actually sent with — because an effort set further in would shadow it.

func WithUnmeteredReceipts ¶

func WithUnmeteredReceipts(ctx context.Context) context.Context

WithUnmeteredReceipts arms one piece of work to have an answer that arrived whole but carried no usage block settled the way a cut one is ([Client.settle]): its receipt is asked for by generation id, or it is told as a call nobody could price. Without it such an answer is billed nowhere and said nowhere, which is every other caller's behaviour, left alone on purpose.

IT IS OPT-IN BECAUSE IT IS NEW MONEY ON AN OLD ROAD. A program's model API arms it (internal/provider/modelapi): its runs are held to a dollar ceiling and read as one account, and true-myth's call 7483768e of 2026-09-23 — a 200 on kimi-k2.6 after nearly eight seconds with no usage block — was in no book at all. A direct service is untouched either way, because settle stops at one: its missing usage block is a subscription's silence, not a charge.

func WithValueOfTime ¶

func WithValueOfTime(ctx context.Context, seconds float64) context.Context

WithValueOfTime states what a second is worth to whoever is waiting on the calls made under ctx, in SECONDS PER DOLLAR.

It is the companion of WithRoutingIntent and it is written under the same law: IT IS SAID AND NEVER INFERRED. The intent says whether somebody is waiting; this says what their wait costs, which is a thing only the graph knows — a chat turn is worth a person's attention ([lane.AttentionValue]), a node on a task's critical path is worth the whole task, and a node with slack off the path is worth nothing at all. [lane.Lambda] is the table that answers it; this is how the answer travels.

A call that says nothing keeps the behaviour it has always had: interactive calls are worth a person's attention, background calls are worth nothing, and a `price` routing row is worth nothing whatever anybody said.

func WithoutBabbleGuard ¶

func WithoutBabbleGuard(ctx context.Context) context.Context

WithoutBabbleGuard takes the degeneration guard off every call made under ctx. The silence watchdog has no switch and is not affected: a request that produced nothing in ninety seconds has failed by any reading, and there is no preference under which sitting on it is the answer.

It rides the context for the reason patience.go's seams do — the adapter is shared by every agent in the process, so a field on the client would make a task node's setting the conversation's.

func WithoutPatientRateLimits ¶

func WithoutPatientRateLimits(ctx context.Context) context.Context

WithoutPatientRateLimits takes the patience off every call made under ctx, whatever an outer context granted: a 429 on every machine the request may use is handed straight back. A crew seat asks this way, because its answer to "not yet" is its next route or its next model, never a wait — a pool at its daily limit that is waited on a minute at a time holds a task for as long as the limit lasts.

AND IT NEVER WAITS ON THE SAME MACHINE AFTER A 429: a free move to another machine is still made at once, but the wait that would follow — the machine's named window, or our doubling — is not sat out; the refusal is handed back instead ([handsBackRateLimits]).

func WithoutStream ¶

func WithoutStream(ctx context.Context) context.Context

WithoutStream takes the observer back off a context, for a call made inside a surface's own context that is not the surface's conversation.

The observer is installed once, on the process's serving context, so anything that borrows that context to ask a model something inherits a live typewriter pointed at the transcript — and a call whose answer is a LABEL rather than a reply would type its label into the room as if somebody were saying it. The head's room-naming clerk is the first such caller (head/scribe.go); a background summarizer would be the second.

A typed nil is stored rather than the key being removed, because a context value cannot be unset — and the reader below already treats a nil observer as "do not stream", which is exactly what this means.