api

Documentation

Index

• func RegisterConfirmBridge()
• type Server
  • func New(cfg config.APIConfig, version string, submit Submitter, actions SessionActions) *Server
  • func (s *Server) Addr() string
  • func (s *Server) Start() error
  • func (s *Server) Stop(ctx context.Context) error
• type SessionActions
• type Submitter

Functions

func RegisterConfirmBridge

func RegisterConfirmBridge()

RegisterConfirmBridge wires confirm.Gate to the event hub. Call once at startup, only when API-driven confirmation is enabled. It overrides any previously registered confirm UI (e.g. the TUI popup), which is the intended behaviour in headless mode where no TUI is rendered.

Types

type Server

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

Server is the REST API exposed by pk when api.enabled is true. It runs alongside the TUI (or alone, in headless mode) and surfaces the agent's events to HTTP clients.

Lifecycle:

• New constructs the server but does not bind any socket.
• Start binds the TCP listener (so port-in-use errors surface synchronously to the caller) and runs http.Serve in a goroutine.
• Stop initiates a graceful shutdown bounded by the provided context. In-flight requests are allowed to finish within the context's deadline; afterwards they are forcibly closed.

func New

func New(cfg config.APIConfig, version string, submit Submitter, actions SessionActions) *Server

New constructs a server configured for cfg.Port. The actual bind happens in Start so that:

• The caller controls when traffic starts flowing.
• Bind errors (port in use) are reported synchronously rather than getting lost in a goroutine.

version is the pk version string (embedded from pk.version at build time and held in main.go) which the /info endpoint surfaces. submit is the closure /prompt uses to start an agent turn — see Submitter. actions bundles the side-effecting closures for the session-action endpoints (/session/clear, /context/pack, /engine/unload) — see SessionActions; a zero value disables those routes (501).

func (*Server) Addr

func (s *Server) Addr() string

Addr returns the bound TCP address (e.g. "127.0.0.1:8080") after Start has succeeded, or the empty string before. Useful in tests that bind on :0 to pick a free port.

func (*Server) Start

func (s *Server) Start() error

Start binds the TCP listener and runs http.Serve in a goroutine. Returns after a successful bind so the caller knows the port is usable. A non-nil error means the bind failed and the server is not running.

Serve errors that occur after the goroutine has started (e.g. socket closed by Stop) are absorbed; the http.ErrServerClosed sentinel is expected during shutdown and is not surfaced.

func (*Server) Stop

func (s *Server) Stop(ctx context.Context) error

Stop initiates graceful shutdown. In-flight requests are given until ctx's deadline to finish; afterwards they are closed. Returns ctx.Err() if the deadline elapsed.

type SessionActions

type SessionActions struct {
	Clear  func() (string, error)
	Pack   func() (string, error)
	Unload func() (string, error)
	// RAGIndex rebuilds the RAG index from scratch (mirror of /rag-index);
	// RAGUpdate re-embeds only changed files (mirror of /rag-update). Both
	// run asynchronously server-side — the closure returns after launching.
	RAGIndex  func() (string, error)
	RAGUpdate func() (string, error)
}

SessionActions bundles the side-effecting operations the API exposes that mirror TUI slash commands:

• Clear → /session/clear (mirror of /clear)
• Pack → /context/pack (mirror of /pack)
• Unload → /engine/unload (mirror of /unload)

main.go supplies implementations bound to the live pablo.App + engine, so the api package itself stays free of any pablo/handlers dependency — the same decoupling pattern as Submitter.

Each implementation returns a short human-readable message and an error. A nil func means the action is not wired: the handler answers 501 Not Implemented, which keeps a zero-value SessionActions usable in tests that don't exercise these routes.

type Submitter

type Submitter func(prompt string) (events <-chan state.Event, ok bool)

Submitter is the function the API calls to start an agent turn. main.go provides the implementation (it has access to the live pablo.App and the openai.Client); the api package therefore stays free of any pablo dependency.

The submitter:

• acquires the agent lock and returns ok=false if another turn is already running (the API maps this to 409 Conflict);
• subscribes a per-turn event channel BEFORE starting the agent goroutine, guaranteeing the first event is never missed;
• returns immediately — the agent runs asynchronously and publishes events on the returned channel until a terminal event closes it.