Documentation
¶
Overview ¶
Package interactive serves the shared interactive agent HTTP surface: readiness, metrics and prompt intake, over a per-session cache of long-lived conversations.
Index ¶
Constants ¶
This section is empty.
Variables ¶
var AuthDisabled = Auth{/* contains filtered or unexported fields */}
AuthDisabled is the explicit opt-out: a service built with it serves every route without authentication.
It exists so that a consumer which is deliberately unexposed states that choice in one visible, greppable line rather than inheriting a default. Passing it on a pod that is later exposed serves that surface unauthenticated — the residual risk this design accepts — so grep for it before putting anything in front of the port.
Functions ¶
This section is empty.
Types ¶
type Auth ¶ added in v0.94.0
type Auth struct {
// contains filtered or unexported fields
}
Auth is a service's authentication decision: either the bearer token every gated request must carry, or an explicit opt-out.
The zero value is NOT a usable default — it refuses every gated request. A service built with the zero value authenticates nothing and serves only the exempt routes, which is the fail-closed outcome: a decision left unmade cannot silently open the surface. Build a real decision with NewAuthToken or AuthFromEnv, or state the opt-out with AuthDisabled.
func AuthFromEnv ¶ added in v0.94.0
AuthFromEnv reads the bearer token from the process environment and returns the Auth that requires it.
It returns an error when the variable is unset or empty, so a service that cannot authenticate fails to start rather than serving unauthenticated. The token value is never logged, never returned inside the error and never written anywhere.
func NewAuthToken ¶ added in v0.94.0
NewAuthToken returns the Auth that requires every gated request to present token as its bearer credential. An empty token is not a usable credential: it yields the same fail-closed value as the zero Auth.
type PendingPermission ¶ added in v0.93.0
type PendingPermission struct {
// ID identifies the request. It is generated per request and is the only handle
// a verdict may name.
ID string `json:"id"`
// ToolName is the name of the tool the CLI wants to invoke.
ToolName string `json:"tool_name"`
// Description is the CLI's human-readable description of the invocation.
Description string `json:"description"`
// InputPreview is a preview of the tool input. It is never logged.
InputPreview string `json:"input_preview"`
}
PendingPermission is one permission request currently waiting for a verdict, as served on GET /permission.
type PermissionRegistry ¶ added in v0.93.0
type PermissionRegistry interface {
// DecidePermission registers request as pending and blocks until a verdict is
// posted for it or ctx is cancelled.
DecidePermission(
ctx context.Context,
request claude.PermissionRequest,
) (claude.PermissionDecision, error)
// List returns the requests currently pending. The result is never nil, so the
// endpoint always renders a JSON array.
List() []PendingPermission
// Resolve delivers decision to the pending request named by id and reports
// whether such a request was pending. It never blocks.
Resolve(id string, decision claude.PermissionDecision) bool
}
PermissionRegistry holds the permission requests one service is currently waiting on. It is the PermissionDecider the sessions built for that service consult, so a request raised by a turn appears on that service's endpoint and nowhere else.
func NewPermissionRegistry ¶ added in v0.93.0
func NewPermissionRegistry() PermissionRegistry
NewPermissionRegistry creates an empty registry. Construct one per service and pass the same instance to the session factory and to NewServiceWithPermissions, so a request raised by a session is served by that service's endpoint.
type Service ¶
type Service interface {
// Handler returns the HTTP handler serving GET /readiness, GET /metrics and
// POST /prompt, plus GET and POST /permission when the service was built with a
// permission registry. Every route except /readiness and /metrics requires the
// configured bearer token; those two are exempt because a kubelet probe and a
// Prometheus scrape cannot carry one without the token being written into the pod
// spec and the scrape configuration.
Handler() http.Handler
// Run serves the handler on the configured listen address until ctx is cancelled.
Run(ctx context.Context) error
}
Service serves the interactive agent HTTP surface.
func NewService ¶
func NewService( sessions agentlib.SessionFactory, listen string, providerBaseURL string, registry *prometheus.Registry, auth Auth, ) Service
NewService creates the interactive session service.
sessions supplies one conversation per session id; listen is the address the service binds; providerBaseURL is the endpoint the readiness probe dials (empty means the check is skipped and reported as such); registry is the Prometheus registry the metrics route gathers from — a parameter rather than a library singleton, so each binary keeps its own metrics identity; auth is the authentication every gated route requires, and the zero Auth refuses every gated request. The permission endpoint is not served by this constructor; use NewServiceWithPermissions to serve it.
func NewServiceWithPermissions ¶ added in v0.93.0
func NewServiceWithPermissions( sessions agentlib.SessionFactory, listen string, providerBaseURL string, registry *prometheus.Registry, auth Auth, permissions PermissionRegistry, ) Service
NewServiceWithPermissions creates the interactive session service with the permission endpoint enabled.
permissions is the registry the endpoint serves and the decider the sessions built by the caller's factory consult; the caller constructs it first and passes the one instance to both, which is what makes the endpoint and the sessions resolve through the same registry. A nil permissions is invalid here — use NewService for that. auth is the authentication every gated route requires, and the zero Auth refuses every gated request.
Source Files