api

package
v1.0.0 Latest Latest
Warning

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

Go to latest
Published: Sep 16, 2026 License: MIT Imports: 56 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func RegisterLauncherAuthRoutes

func RegisterLauncherAuthRoutes(mux *http.ServeMux, opts LauncherAuthRouteOpts)

RegisterLauncherAuthRoutes registers /api/auth/login|logout|status|setup.

func SaveCatalog

func SaveCatalog(provider, apiBase, apiKey string, models []CatalogModel) error

SaveCatalog persists a fetched model list for a given provider+key combination. If a catalog with the same key already exists, it is updated.

Types

type BinaryView

type BinaryView struct {
	Name     string `json:"name"`
	Path     string `json:"path"`
	Resolved bool   `json:"resolved"`
}

type CapabilityView

type CapabilityView struct {
	ID             string          `json:"id"`
	Title          string          `json:"title"`
	Summary        string          `json:"summary"`
	Local          bool            `json:"local"`
	Network        bool            `json:"network"`
	ExternalWrites bool            `json:"external_writes"`
	Provider       string          `json:"provider"`
	CostKnown      bool            `json:"cost_known"`
	RequestSchema  json.RawMessage `json:"request_schema,omitempty"`
	// ToolName is what the agent calls this capability in chat, so a person can
	// see the connection between a capability here and a tool the agent used.
	ToolName string `json:"tool_name"`
	// NeedsApproval is the host's judgement, computed once so every surface
	// agrees. Unknown cost, external writes, and network reach each mean a
	// person should see the call before it runs.
	NeedsApproval bool `json:"needs_approval"`
}

type CatalogEntry

type CatalogEntry = modelservice.CatalogEntry

CatalogEntry is a saved list of upstream models fetched for a specific provider+key combination.

type CatalogModel

type CatalogModel = modelservice.CatalogModel

CatalogModel represents a single model entry in a saved catalog.

type CatalogStore

type CatalogStore = modelservice.CatalogStore

CatalogStore holds all saved model catalogs.

type Handler

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

Handler serves HTTP API requests.

func NewHandler

func NewHandler(configPath string) *Handler

NewHandler creates an instance of the API handler.

func (*Handler) EnsurePicoChannel

func (h *Handler) EnsurePicoChannel() (bool, error)

EnsurePicoChannel enables the Pico channel with sane defaults if it isn't already configured. Returns true when the config was modified.

func (*Handler) RegisterRoutes

func (h *Handler) RegisterRoutes(mux *http.ServeMux)

RegisterRoutes binds all API endpoint handlers to the ServeMux.

func (*Handler) RestartGateway

func (h *Handler) RestartGateway() (int, error)

RestartGateway restarts the gateway process. This is a non-blocking operation that stops the current gateway (if running) and starts a new one. Returns the PID of the new gateway process or an error.

func (*Handler) SetDebug

func (h *Handler) SetDebug(debug bool)

func (*Handler) SetServerAccessOptions

func (h *Handler) SetServerAccessOptions(allowLocalhostBypass bool, trustedProxyCIDRs []string)

func (*Handler) SetServerBindHost

func (h *Handler) SetServerBindHost(hostInput string, explicit bool)

SetServerBindHost stores the launcher's effective bind host. When explicit is true, hostInput is the normalized -host / FACET_STUDIO_LAUNCHER_HOST value.

func (*Handler) SetServerOptions

func (h *Handler) SetServerOptions(port int, public bool, publicExplicit bool, allowedCIDRs []string)

SetServerOptions stores current backend listen options for fallback behavior.

func (*Handler) Shutdown

func (h *Handler) Shutdown()

Shutdown gracefully shuts down the handler, stopping the gateway if it was started by this handler.

func (*Handler) StopGateway

func (h *Handler) StopGateway()

StopGateway stops the gateway process if it was started by this handler. This method is called during application shutdown to ensure the gateway subprocess is properly terminated. It only stops processes that were started by this handler, not processes that were attached to from existing instances.

func (*Handler) TryAutoStartGateway

func (h *Handler) TryAutoStartGateway()

TryAutoStartGateway checks whether gateway start preconditions are met and starts it when possible. Intended to be called by the backend at startup.

type InvokeResult

type InvokeResult struct {
	OK         bool               `json:"ok"`
	Module     string             `json:"module"`
	Capability string             `json:"capability"`
	DurationMS int64              `json:"duration_ms"`
	Error      *modproto.Error    `json:"error,omitempty"`
	Execution  modproto.Execution `json:"execution"`
	Warnings   []string           `json:"warnings"`
	// HostWarnings are the host's own findings about this invocation, kept
	// separate from the module's so a reader can tell who is complaining.
	HostWarnings []string        `json:"host_warnings"`
	Result       json.RawMessage `json:"result,omitempty"`
	Stderr       string          `json:"stderr,omitempty"`
	At           time.Time       `json:"at"`
}

InvokeResult is one normalized invocation, shaped for rendering.

type LauncherAuthRouteOpts

type LauncherAuthRouteOpts struct {
	SessionCookie string
	SecureCookie  func(*http.Request) bool
	// PasswordStore enables password login. It must be non-nil for auth to work.
	PasswordStore PasswordStore
	// StoreError holds the error returned when opening the password store. When
	// non-nil and PasswordStore is nil, auth endpoints fail closed with a
	// recovery message.
	StoreError error
}

LauncherAuthRouteOpts configures dashboard auth handlers.

type LogBuffer

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

LogBuffer is a thread-safe ring buffer that stores the most recent N log lines. It supports incremental reads via LinesSince and tracks a runID that increments whenever the buffer is reset or cleared so clients can detect log history resets.

func NewLogBuffer

func NewLogBuffer(capacity int) *LogBuffer

NewLogBuffer creates a LogBuffer with the given capacity.

func (*LogBuffer) Append

func (b *LogBuffer) Append(line string)

Append adds a line to the buffer. If the buffer is full, the oldest line is evicted.

func (*LogBuffer) Clear

func (b *LogBuffer) Clear()

Clear removes all buffered lines and increments the runID so clients treat subsequent reads as a new log stream.

func (*LogBuffer) LinesSince

func (b *LogBuffer) LinesSince(offset int) (lines []string, total int, runID int)

LinesSince returns lines appended after the given offset, the current total count, and the runID. If offset >= total, no lines are returned. If offset is too old (evicted), all buffered lines are returned.

func (*LogBuffer) Reset

func (b *LogBuffer) Reset()

Reset clears the buffer and increments the runID. Call this when starting a new gateway process.

func (*LogBuffer) RunID

func (b *LogBuffer) RunID() int

RunID returns the current run identifier.

type ModuleView

type ModuleView struct {
	Module       string                 `json:"module"`
	Name         string                 `json:"name"`
	Version      string                 `json:"version"`
	Binary       string                 `json:"binary"`
	Capabilities []CapabilityView       `json:"capabilities"`
	Overlays     int                    `json:"overlays"`
	Skills       int                    `json:"skills"`
	Permissions  PermissionsView        `json:"permissions"`
	Requirements []modproto.Requirement `json:"requirements"`
	Warnings     []string               `json:"warnings"`
	// HostWarnings are the host's own findings about this module -- a stale
	// digest, a cost claim that contradicts a declaration -- kept apart from
	// what the module said about itself, so a reader can tell who is
	// complaining and which they can act on.
	HostWarnings []string `json:"host_warnings"`
	// Enabled is false when the user has turned this module off. It stays
	// listed with its capabilities, because there has to be something to turn
	// back on.
	Enabled bool   `json:"enabled"`
	Error   string `json:"error,omitempty"`
	// Dir is the install directory name, carried so a module that could not
	// describe itself can still be REMOVED. Such a module has no module id --
	// the id comes from the descriptor it failed to produce -- so without this
	// the cockpit can report the breakage and offer no way to clear it.
	Dir string `json:"dir,omitempty"`
}

ModuleView is a descriptor flattened for the cockpit.

type PasswordStore

type PasswordStore interface {
	IsInitialized(ctx context.Context) (bool, error)
	SetPassword(ctx context.Context, plain string) error
	VerifyPassword(ctx context.Context, plain string) (bool, error)
}

PasswordStore is the interface for dashboard password persistence. Implemented by dashboardauth.Store and launcherconfig.PasswordStore.

type PermissionsView

type PermissionsView struct {
	FilesystemRead  []string     `json:"filesystem_read"`
	FilesystemWrite []string     `json:"filesystem_write"`
	Network         []string     `json:"network"`
	Credentials     []string     `json:"credentials"`
	PaidProviders   []string     `json:"paid_providers"`
	Publish         bool         `json:"publish"`
	Subprocess      []BinaryView `json:"subprocess"`
}

PermissionsView is what a module DECLARED it may need. It is a request, never a grant: installing a module grants nothing, and the host authorizes per invocation.

type ProviderCatalogSyncInput

type ProviderCatalogSyncInput = modelservice.ProviderCatalogSyncInput

ProviderCatalogSyncInput is the complete server-owned connection description supplied to a catalog driver. It is never populated from request fields.

Jump to

Keyboard shortcuts

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