Documentation
¶
Overview ¶
Package agentsessionsd is the agentsessionsd server: it serves the Sessions API over TCP. cmd/agentsessionsd calls Main; an in-tree daemon build that hosts more than the stock daemon calls it with Options: WithToolExecutors for host tool executors, and WithHarnessBackends for harnesses served on a backend this module does not link, which keeps that backend's flags and client setup in the build's own module. The package is internal to this module and is not an API for programs outside it. With -registry-addr it also serves HarnessRegistry on a separate literal-loopback operator listener. The admin API is never registered on the Sessions port; neither listener provides authentication or TLS.
This binary serves the reference echo harness by default and adds the conversational chat harness when -model is set, each on its own filesystem-only local backend. -harness name=address registers a STATELESS_REPLAY harness running elsewhere without rebuilding; it requires -model, so a remote harness's model calls never fall through to the built-in echo stub. A REQUIRES_MEMORY_SNAPSHOT harness needs a backend that owns its sandbox, which a build adds with WithHarnessBackends. Unknown harnesses are refused rather than substituted.
With -model set it drives a real OpenAI-compatible endpoint; without one it uses the built-in echo model, so the quickstart runs with no key. The API key comes from the environment rather than a flag, because a flag would put the credential in the process list and shell history.
Both listeners are plaintext and unauthenticated; project is a filter, not a tenancy boundary. A local or same-pod process can administer the operator listener. Do not expose it to an untrusted network. See docs/security.md.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var ErrUsage = errors.New("usage")
ErrUsage wraps a command-line error. Run has already printed the error and the usage, so a main reports it with exit status 2, as flag.ExitOnError would.
Functions ¶
func CheckDialAddress ¶ added in v0.3.0
CheckDialAddress refuses an address the daemon's gRPC dialers cannot reach, with the rules -harness addresses follow. A HarnessBackends build uses it for its own address flags.
func Main ¶
func Main(opts ...Option)
Main runs the server with os.Args and exits with the conventional status: 0 on success or -h, 2 when the arguments cannot be parsed (an unknown or malformed flag, a positional argument; see Run's ErrUsage), and 1 otherwise, including a configuration error in flags that parsed.
func Run ¶
Run parses args (without the program name) and serves until SIGINT or SIGTERM. -h returns flag.ErrHelp. A flag that does not parse and positional arguments wrap ErrUsage. A configuration check after parsing (a -harness with no -model, a -registry-addr that is not a literal loopback address, a HarnessBackends refusal, and the like) returns a plain error, which Main prints and reports with status 1.
Types ¶
type HarnessBackends ¶ added in v0.3.0
type HarnessBackends interface {
// RegisterFlags adds the build's flags to Run's flag set. A flag that does not parse is a usage
// error, as for Run's own flags.
RegisterFlags(fs *flag.FlagSet)
// Harnesses checks the parsed flags and returns the names of the harnesses they configure, or
// none. It must have no side effect: an error refuses the start before anything is dialed or
// opened.
Harnesses() ([]string, error)
// Backends builds one backend for each name Harnesses returned. Run calls closeBackends, when
// it is not nil, once: after the server stops or when a later startup step fails.
Backends(logger *slog.Logger) (backends map[string]placement.Backend, closeBackends func(), err error)
}
HarnessBackends lets a daemon build serve static harnesses on a backend this module does not link, such as a sandbox or cloud backend; integrations/substrate/cmd/agentsessionsd is one. The build owns that backend's flags and client setup, so they stay in its own module.
Run calls RegisterFlags before it parses the command line and Harnesses after. When Harnesses names any harness, Run checks the names the way it checks -harness ones (each needs -model, and none may be a built-in or -harness name), then calls Backends, all before it opens the journal. The harnesses are static entries, reserved in the journal like the built-in ones, and get no host tool executor.
type Option ¶
type Option func(*options)
Option configures Run.
func WithHarnessBackends ¶ added in v0.3.0
func WithHarnessBackends(h HarnessBackends) Option
WithHarnessBackends adds the harnesses h configures. Without it the daemon serves only the built-in harnesses, -harness entries and registered ones.
func WithToolExecutors ¶
func WithToolExecutors(f ToolExecutorFunc) Option
WithToolExecutors installs host tool executors for CONTROLLER_MEDIATED and approved REQUIRES_APPROVAL tool calls. Without it or -tool-executors no harness has one, and such a call fails the turn. Combining the option and flag is a startup configuration error. Only -harness entries are asked: the built-in harnesses and those registered through HarnessRegistry get no executor.
The executor runs only after the controller's own gate: a REQUIRES_APPROVAL call still parks the turn until an Approve decision, and a denied call never reaches it. Resume re-drives an interrupted call that is not approval-gated only for tools in ToolExecutor.DurableDedup.
type ToolExecutor ¶ added in v0.3.0
type ToolExecutor struct {
// Call runs CONTROLLER_MEDIATED and approved REQUIRES_APPROVAL calls. Nil means the harness has
// no executor, and DurableDedup is ignored.
Call controller.ToolFunc
// DurableDedup declares the tools Call durably deduplicates, as controller.WithDurableDedup.
// Nil declares none: Resume then refuses an interrupted call that has no recorded result
// (controller.ErrUnansweredToolCall) instead of re-running it.
DurableDedup func(tool string) bool
}
ToolExecutor is one -harness entry's host tool executor.
type ToolExecutorFunc ¶
type ToolExecutorFunc func(harness string, sessions *client.Client) (ToolExecutor, error)
ToolExecutorFunc returns the host tool executor for the named -harness, or one with a nil Call for none. sessions is a client of this daemon's own Sessions listener, for an executor that drives other sessions (a tool that runs a turn in a child session, say); it connects on first use. sessions is not usable until Run serves; do not call it while building the executor.
Run asks for every -harness once, at startup, before it opens the journal. An error stops Run with that error, so an executor that cannot be built (bad configuration, say) fails the start instead of failing later on a call that may already have been approved.
Source Files