probe

package
v0.34.0 Latest Latest
Warning

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

Go to latest
Published: Oct 9, 2026 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package probe makes an agent's startup model probe survive a slow agent.

The probe opens a fresh ACP session purely to learn the agent's model list, and it runs immediately after the agent process starts. That is a race: an agent command like

fir --mode acp --mcp-config <big mcp.json> --wait-mcp

blocks until every MCP server is up, which can take well past any single fixed deadline. Losing the race produced three faces of the same failure in production —

probe: new session: context deadline exceeded
probe: new session: peer disconnected before response
probe: new session: context canceled

— on roughly three startups in seven. The one-shot probe treated a slow-but-healthy agent as a permanently broken one.

Models therefore retries with exponential backoff inside a larger overall budget, so readiness is waited for rather than sampled once. It stays best-effort: the model list drives cosmetic surfaces — a status-line segment, a model menu — so exhausting the budget must be logged and tolerated, never fatal. A relay that refuses to serve messages because a menu is not ready has a worse bug than the one this package fixes.

Every relay in this family needs this, and each needs it at the same moment: immediately after client.Start, off the critical path, in a goroutine. It lives here rather than in a relay so the retry policy, its tuning and the "did we even ask yet?" bookkeeping (see Tracker) have exactly one implementation.

Retrying is safe because ProbeModels is idempotent — it returns early once the model list is cached, so a retry that races a concurrently-created real session costs nothing.

One cost is accepted and must not be "optimised" away: ProbeModels creates a throwaway session in a temp dir and drops its sink, and ACP has no session/delete, so that session stays idle inside the agent for the agent's lifetime. It buys a model list that is correct from the first interaction instead of from the first conversation.

Index

Constants

View Source
const (
	DefaultBudget  = 5 * time.Minute
	DefaultAttempt = 30 * time.Second
	DefaultInitial = time.Second
	DefaultMax     = 15 * time.Second
)

Default tuning. The budget is generous because the failure it covers is "MCP servers are still starting", which is measured in minutes on a cold machine; the cost of waiting is only a late emoji.

Variables

This section is empty.

Functions

func Models

func Models(ctx context.Context, cfg Config) error

Models probes the agent for its model list, retrying a failing probe with exponential backoff until it succeeds, the budget runs out, or ctx is cancelled.

It returns nil once the agent has been probed. The error from the final attempt is returned when the budget is exhausted, and ctx's error when cancelled; callers are expected to log either and carry on with an empty model list.

Config.Tracker, if set, is updated on every exit so a concurrent reader can tell "not asked yet" from "asked, and the answer was no models".

Types

type Config

type Config struct {
	// Prober is the agent to probe.
	Prober Prober

	// Tracker, when non-nil, records this run's outcome so a concurrent
	// reader can distinguish "not asked yet" from "asked, no models".
	Tracker *Tracker

	// Budget bounds the total time spent across all attempts.
	// Default DefaultBudget.
	Budget time.Duration

	// Attempt bounds a single probe RPC. Default DefaultAttempt.
	Attempt time.Duration

	// Initial and Max bound the exponential backoff between attempts.
	// Defaults DefaultInitial / DefaultMax.
	Initial, Max time.Duration

	// Logf receives one line per failed attempt. Optional.
	Logf func(format string, args ...any)

	// Now and After are injection points for tests, defaulting to
	// time.Now and time.After. They exist so the retry loop can be
	// exercised on a fake clock with no sleeping and no wall-clock
	// polling.
	Now   func() time.Time
	After func(d time.Duration) <-chan time.Time
}

Config tunes Models. The zero value of every field is usable.

type Prober

type Prober interface {
	ProbeModels(ctx context.Context) error
}

Prober is the slice of acp-kit's *client.AgentProc that this package needs. Narrow by design: it keeps the retry policy testable without a live agent subprocess.

type Status

type Status int32

Status says how far the model probe has got. It exists because "Models() is empty" answers two different questions with one value: nobody has asked the agent yet, or the agent was asked and genuinely has no models (no provider authenticated). Only the second is the user's problem to fix, so a relay that renders the empty list must be able to tell them apart.

const (
	// StatusPending: no attempt has finished. Either the probe has not
	// been started or it is still retrying.
	StatusPending Status = iota

	// StatusProbed: ProbeModels returned nil. The agent has been asked,
	// so an empty model list is the agent's real answer.
	StatusProbed

	// StatusFailed: the budget was exhausted, or the context was
	// cancelled, without a successful probe.
	StatusFailed
)

Probe states. The zero value is StatusPending, so a Tracker that has never run reports the truth.

func (Status) String

func (s Status) String() string

String implements fmt.Stringer.

type Tracker

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

Tracker records the outcome of a probe so another goroutine — a chat handler rendering a model menu, typically — can ask what happened. Its zero value is a usable Tracker in StatusPending, and all methods are safe for concurrent use.

func (*Tracker) Status

func (t *Tracker) Status() Status

Status returns the last recorded probe state.

Jump to

Keyboard shortcuts

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