Documentation
¶
Overview ¶
Package httpapi is the HTTP adapter over app.App, mounted on the webhook listener's loopback server, which also hosts the optional pprof handler (ADR pprof-debug-endpoint).
It serves two unrelated things, and the split is the point:
The terminal, pop-up terminal and agent-workspace control planes under /api/terminal/ are the Wails frontend's own transport, not an agent surface. They authenticate with a per-run bearer token because each of them spawns a process (ADR terminal-transport, ADR a-workspace-declares-its-own-authority), and their data planes are raw WebSocket mounts outside the operations table.
/api/status and /api/version are the liveness probe — the plain-GET way to ask whether the app is up and which build it is, which a shell script or a health check needs and JSON-RPC is the wrong shape for. Beside them sits the one call a chat makes about itself, POST /api/sessions/end, guarded by the token its own launch handed it rather than the frontend's (ADR a-scheduled-chat-ends-itself-through-a-capability-token-its-launch-handed-it).
What is *not* here any more is the agent-facing control surface this package began as (ADR agent-http-api). Inbox, feeds, profiles, actions, source refresh and flow dry runs are tools on the MCP server now (cmd/desktop/internal/adapter/mcpsrv, ADR mcp-replaces-the-agent-facing-http-api), and so is the self-description the OpenAPI document used to provide.
Index ¶
- Constants
- func MintTerminalToken() (string, error)
- func PTYStreamHandler(core *app.App, token string, origins []string, log zerolog.Logger) (string, http.Handler)
- func PprofHandler(cpuProfile http.Handler) http.Handler
- func TerminalStreamHandler(core *app.App, token string, origins []string, log zerolog.Logger) (string, http.Handler)
- type Controller
- func (ctrl *Controller) AgentMCPCatalogue(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentMCPImport(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentMCPRemove(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSchedulePreview(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentScheduleRun(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentScheduleRuns(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionActivity(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionClose(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionDelete(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionEnd(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionRename(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionResize(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionResume(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionStart(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionStartFirstRun(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessions(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSessionsAll(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSharedSkillsReveal(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSkillPackages(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentSkillPackagesReveal(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentWorkspaceCreate(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentWorkspaceDelete(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentWorkspaceOpen(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentWorkspaceOpenInEditor(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentWorkspaceReveal(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentWorkspaceUpdate(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) AgentWorkspaces(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) Handler() http.Handler
- func (ctrl *Controller) PopupTerminalClose(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) PopupTerminalList(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) PopupTerminalOpen(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) PopupTerminalResize(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) Status(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalAttach(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalClosePane(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalCloseWindow(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalDetach(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalImagePaths(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalImageUpload(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalKill(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalListWindows(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalMoveWindow(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalNewAgentWindow(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalNewWindow(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalPaneForeground(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalPaste(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalRenameWindow(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalResize(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalResizePane(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalSelectPane(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalSelectWindow(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalSplitPane(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalStart(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalWindowForeground(w http.ResponseWriter, r *http.Request) error
- func (ctrl *Controller) TerminalZoomPane(w http.ResponseWriter, r *http.Request) error
- type ErrResp
- type Op
- type Options
Constants ¶
const ( // TerminalPathPrefix is the control plane's path space. Everything under it // authenticates and answers CORS; nothing else on this API does. TerminalPathPrefix = "/api/terminal/" // TerminalStreamPath is where the data-plane WebSocket is mounted. It sits // under the prefix above but is not an operation: ServeMux's longest match // routes it to its own raw handler instead of through the errchain table. TerminalStreamPath = "/api/terminal/stream" )
const AgentWorkspacesPathPrefix = TerminalPathPrefix + "agents/"
The agent-workspace control plane sits under TerminalPathPrefix for exactly the reason the pop-up surface does: starting a session spawns an agent CLI, which is arbitrary command execution just as a pop-up shell is (ADR terminal-transport), and mounting it here is what gives it the terminal bearer token and CORS policy without a second rule. Sessions are tmux sessions named agentws-<terminal id> and ride the shared tmux data plane at TerminalStreamPath (ADR agent-workspace-sessions-are-tmux-sessions) — there is no agent-specific stream. Start and Resume attach server-side and return the active window id alongside the session name, so the area never has to drive the generic /api/terminal/attach control route to reach its own sessions.
const ( // PTYStreamPath is the data plane's mount path, under TerminalPathPrefix so // the bearer token and CORS policy already guarding the terminal surface // cover it (ADR ephemeral-popup-terminals point 4). PTYStreamPath = "/api/terminal/pty/stream" )
The ptyterm data plane, shared by every caller that addresses a terminal by id (ADR ptyterm-terminals-are-caller-addressed) — today the pop-up, and a workspace session once phase 5 lands. One socket carries exactly one terminal — the id is in the query string, not in every frame — so output is a byte payload behind a single tag and xterm.js writes it without a decode step.
server -> client
0x00 Output [0x00][raw bytes]
0x01 Exit [0x01][JSON {reason}]
client -> server
0x10 Input [0x10][raw bytes]
const PathPrefix = "/api/"
PathPrefix is where App mounts this handler on the webhook listener.
const (
PopupTerminalPathPrefix = "/api/terminal/popup/"
)
The pop-up surface sits under TerminalPathPrefix so the bearer token and the CORS policy that guard the terminal control plane cover it without a second rule — a PTY is arbitrary command execution just as tmux is (ADR terminal-transport). What is behind it is not a tmux session and is addressed by id rather than by slug, so it is its own path space rather than more verbs on the tmux one.
const PprofPathPrefix = "/debug/pprof/"
PprofPathPrefix is where PprofHandler mounts on the shared loopback server.
Variables ¶
This section is empty.
Functions ¶
func MintTerminalToken ¶
MintTerminalToken returns a fresh per-run bearer token for the terminal surface. It is minted in the composition root, held in memory, never logged and never persisted (ADR terminal-transport).
func PTYStreamHandler ¶
func PTYStreamHandler(core *app.App, token string, origins []string, log zerolog.Logger) (string, http.Handler)
PTYStreamHandler returns the mount path and the raw handler for the ptyterm data plane. Like the tmux stream it is mounted on its own rather than joining the operations table: the errchain cannot frame a hijacked socket.
func PprofHandler ¶
PprofHandler serves net/http/pprof on a private mux. cpuProfile replaces the standard CPU handler when continuous profiling needs to share the profiler.
func TerminalStreamHandler ¶
func TerminalStreamHandler(core *app.App, token string, origins []string, log zerolog.Logger) (string, http.Handler)
TerminalStreamHandler returns the mount prefix and the raw handler for the data plane. It is mounted by its own App.MountAPI call rather than joining the operations table: the errchain cannot frame a hijacked socket (ADR terminal-transport).
Types ¶
type Controller ¶
type Controller struct {
// contains filtered or unexported fields
}
func New ¶
New builds the controller. The liveness routes are deliberately unauthenticated behind the loopback bind (ADR agent-http-api).
func (*Controller) AgentMCPCatalogue ¶
func (ctrl *Controller) AgentMCPCatalogue(w http.ResponseWriter, r *http.Request) error
AgentMCPCatalogue lists the merged MCP catalogue: shipped entries plus the user's mcps.yaml, a user id shadowing a shipped one of the same name.
func (*Controller) AgentMCPImport ¶
func (ctrl *Controller) AgentMCPImport(w http.ResponseWriter, r *http.Request) error
AgentMCPImport parses pasted MCP JSON into mcps.yaml and returns the refreshed catalogue.
func (*Controller) AgentMCPRemove ¶
func (ctrl *Controller) AgentMCPRemove(w http.ResponseWriter, r *http.Request) error
AgentMCPRemove deletes a user-declared server from mcps.yaml and returns the refreshed catalogue. Shipped entries are refused — a workspace disables one by dropping the id from its own mcps: list.
func (*Controller) AgentSchedulePreview ¶
func (ctrl *Controller) AgentSchedulePreview(w http.ResponseWriter, r *http.Request) error
func (*Controller) AgentScheduleRun ¶
func (ctrl *Controller) AgentScheduleRun(w http.ResponseWriter, r *http.Request) error
func (*Controller) AgentScheduleRuns ¶
func (ctrl *Controller) AgentScheduleRuns(w http.ResponseWriter, r *http.Request) error
func (*Controller) AgentSessionActivity ¶
func (ctrl *Controller) AgentSessionActivity(w http.ResponseWriter, r *http.Request) error
AgentSessionActivity classifies each of a workspace's live sessions from its captured tmux pane: ready, active, or approval — approval is the highest-urgency state. A session with no live tmux session is omitted rather than reported dead; its row's terminalId already carries that.
func (*Controller) AgentSessionClose ¶
func (ctrl *Controller) AgentSessionClose(w http.ResponseWriter, r *http.Request) error
AgentSessionClose ends a session's live terminal and reports whether there was one to close. The record is untouched, so it still lists afterward.
func (*Controller) AgentSessionDelete ¶
func (ctrl *Controller) AgentSessionDelete(w http.ResponseWriter, r *http.Request) error
AgentSessionDelete ends any live terminal and deletes a session's record.
func (*Controller) AgentSessionEnd ¶
func (ctrl *Controller) AgentSessionEnd(w http.ResponseWriter, r *http.Request) error
AgentSessionEnd ends the calling chat's own session. The bearer is the token the launch handed that process, not the terminal token: a chat holds a capability over itself and nothing else, which is why this route sits beside the liveness probe rather than under the token-guarded terminal prefix.
func (*Controller) AgentSessionRename ¶
func (ctrl *Controller) AgentSessionRename(w http.ResponseWriter, r *http.Request) error
AgentSessionRename sets a session's display name. The record is the only thing touched — a live tmux session keeps its agentws-<terminal id> name.
func (*Controller) AgentSessionResize ¶
func (ctrl *Controller) AgentSessionResize(w http.ResponseWriter, r *http.Request) error
AgentSessionResize votes a size for a session's attached control client — the same renegotiation the Code view's panes cast on a host resize.
func (*Controller) AgentSessionResume ¶
func (ctrl *Controller) AgentSessionResume(w http.ResponseWriter, r *http.Request) error
AgentSessionResume reattaches a session's live terminal if it still has one, or relaunches it — resuming the agent's own conversation when it has a resume form (resumeAttempted), and starting fresh with a notice when it does not (spec §6.2).
func (*Controller) AgentSessionStart ¶
func (ctrl *Controller) AgentSessionStart(w http.ResponseWriter, r *http.Request) error
AgentSessionStart launches a new, named session in a workspace: rendering its command template into a command line and opening it on a Hive-owned PTY.
func (*Controller) AgentSessionStartFirstRun ¶
func (ctrl *Controller) AgentSessionStartFirstRun(w http.ResponseWriter, r *http.Request) error
AgentSessionStartFirstRun opens the seeded Hive workspace on the first-run interview. The workspace, the name and the prompt are the app's, so the request carries nothing.
func (*Controller) AgentSessions ¶
func (ctrl *Controller) AgentSessions(w http.ResponseWriter, r *http.Request) error
AgentSessions lists a workspace's sessions without regenerating its artifacts, unlike AgentWorkspaceOpen.
func (*Controller) AgentSessionsAll ¶
func (ctrl *Controller) AgentSessionsAll(w http.ResponseWriter, r *http.Request) error
AgentSessionsAll lists every session across every workspace, most recently opened first — the cross-workspace read the Recents list uses, unlike AgentSessions which scopes to one workspace.
func (*Controller) AgentSharedSkillsReveal ¶
func (ctrl *Controller) AgentSharedSkillsReveal(w http.ResponseWriter, r *http.Request) error
AgentSharedSkillsReveal opens the shared skills directory, where a skill a package can select is authored.
func (*Controller) AgentSkillPackages ¶
func (ctrl *Controller) AgentSkillPackages(w http.ResponseWriter, r *http.Request) error
AgentSkillPackages lists the skill packages a workspace can enable, each with the names its glob patterns currently select.
func (*Controller) AgentSkillPackagesReveal ¶
func (ctrl *Controller) AgentSkillPackagesReveal(w http.ResponseWriter, r *http.Request) error
AgentSkillPackagesReveal opens skills.yml, where packages are defined.
func (*Controller) AgentWorkspaceCreate ¶
func (ctrl *Controller) AgentWorkspaceCreate(w http.ResponseWriter, r *http.Request) error
AgentWorkspaceCreate makes a directory under the root with a fresh manifest and returns its view.
func (*Controller) AgentWorkspaceDelete ¶
func (ctrl *Controller) AgentWorkspaceDelete(w http.ResponseWriter, r *http.Request) error
AgentWorkspaceDelete ends every live terminal a workspace's sessions hold, deletes the workspace directory, and removes the session records (ADR deleting-a-workspace-deletes-its-directory).
func (*Controller) AgentWorkspaceOpen ¶
func (ctrl *Controller) AgentWorkspaceOpen(w http.ResponseWriter, r *http.Request) error
AgentWorkspaceOpen regenerates a workspace's disposable artifacts and returns its sessions. It is the only call that writes into a workspace.
func (*Controller) AgentWorkspaceOpenInEditor ¶
func (ctrl *Controller) AgentWorkspaceOpenInEditor(w http.ResponseWriter, r *http.Request) error
AgentWorkspaceOpenInEditor launches the configured editor (Settings › General) on the workspace directory.
func (*Controller) AgentWorkspaceReveal ¶
func (ctrl *Controller) AgentWorkspaceReveal(w http.ResponseWriter, r *http.Request) error
AgentWorkspaceReveal opens the workspace directory in the OS file manager.
func (*Controller) AgentWorkspaceUpdate ¶
func (ctrl *Controller) AgentWorkspaceUpdate(w http.ResponseWriter, r *http.Request) error
AgentWorkspaceUpdate rewrites the editable fields of a workspace's manifest in place — comments and keys the editor does not own survive.
func (*Controller) AgentWorkspaces ¶
func (ctrl *Controller) AgentWorkspaces(w http.ResponseWriter, r *http.Request) error
AgentWorkspaces lists every recognized workspace under the configured root.
func (*Controller) Handler ¶
func (ctrl *Controller) Handler() http.Handler
func (*Controller) PopupTerminalClose ¶
func (ctrl *Controller) PopupTerminalClose(w http.ResponseWriter, r *http.Request) error
PopupTerminalClose ends a terminal and every process in it.
func (*Controller) PopupTerminalList ¶
func (ctrl *Controller) PopupTerminalList(w http.ResponseWriter, r *http.Request) error
PopupTerminalList answers the open terminals, oldest first.
func (*Controller) PopupTerminalOpen ¶
func (ctrl *Controller) PopupTerminalOpen(w http.ResponseWriter, r *http.Request) error
PopupTerminalOpen launches a terminal and returns it.
func (*Controller) PopupTerminalResize ¶
func (ctrl *Controller) PopupTerminalResize(w http.ResponseWriter, r *http.Request) error
PopupTerminalResize sets the terminal's size. Nothing else is attached to these PTYs, so this is applied rather than voted on.
func (*Controller) Status ¶
func (ctrl *Controller) Status(w http.ResponseWriter, r *http.Request) error
func (*Controller) TerminalAttach ¶
func (ctrl *Controller) TerminalAttach(w http.ResponseWriter, r *http.Request) error
TerminalAttach opens the control client for a session slug and returns its windows.
func (*Controller) TerminalClosePane ¶
func (ctrl *Controller) TerminalClosePane(w http.ResponseWriter, r *http.Request) error
TerminalClosePane kills one pane of an attached session.
func (*Controller) TerminalCloseWindow ¶
func (ctrl *Controller) TerminalCloseWindow(w http.ResponseWriter, r *http.Request) error
TerminalCloseWindow kills one window of an attached session.
func (*Controller) TerminalDetach ¶
func (ctrl *Controller) TerminalDetach(w http.ResponseWriter, r *http.Request) error
TerminalDetach closes the control client, leaving the tmux session running.
func (*Controller) TerminalImagePaths ¶
func (ctrl *Controller) TerminalImagePaths(w http.ResponseWriter, r *http.Request) error
func (*Controller) TerminalImageUpload ¶
func (ctrl *Controller) TerminalImageUpload(w http.ResponseWriter, r *http.Request) error
func (*Controller) TerminalKill ¶
func (ctrl *Controller) TerminalKill(w http.ResponseWriter, r *http.Request) error
TerminalKill kills the tmux session behind a slug, leaving the hive session itself alone.
func (*Controller) TerminalListWindows ¶
func (ctrl *Controller) TerminalListWindows(w http.ResponseWriter, r *http.Request) error
TerminalListWindows answers several sessions' window sets without attaching, so the sidebar can show windows for sessions this webview is not attached to. It takes the whole set rather than one slug because the caller is a sweep: per-slug, each unattached session cost two tmux spawns and the sidebar spawned twice as many processes as it had rows, all at once.
func (*Controller) TerminalMoveWindow ¶
func (ctrl *Controller) TerminalMoveWindow(w http.ResponseWriter, r *http.Request) error
TerminalMoveWindow moves one window of an attached session to a position in its window order.
func (*Controller) TerminalNewAgentWindow ¶
func (ctrl *Controller) TerminalNewAgentWindow(w http.ResponseWriter, r *http.Request) error
func (*Controller) TerminalNewWindow ¶
func (ctrl *Controller) TerminalNewWindow(w http.ResponseWriter, r *http.Request) error
TerminalNewWindow creates a window and returns its id.
func (*Controller) TerminalPaneForeground ¶
func (ctrl *Controller) TerminalPaneForeground(w http.ResponseWriter, r *http.Request) error
TerminalPaneForeground reports whether closing a pane would kill work.
func (*Controller) TerminalPaste ¶
func (ctrl *Controller) TerminalPaste(w http.ResponseWriter, r *http.Request) error
func (*Controller) TerminalRenameWindow ¶
func (ctrl *Controller) TerminalRenameWindow(w http.ResponseWriter, r *http.Request) error
TerminalRenameWindow renames one window of an attached session.
func (*Controller) TerminalResize ¶
func (ctrl *Controller) TerminalResize(w http.ResponseWriter, r *http.Request) error
TerminalResize renegotiates the control client's size.
func (*Controller) TerminalResizePane ¶
func (ctrl *Controller) TerminalResizePane(w http.ResponseWriter, r *http.Request) error
TerminalResizePane sets a pane's size in cells.
func (*Controller) TerminalSelectPane ¶
func (ctrl *Controller) TerminalSelectPane(w http.ResponseWriter, r *http.Request) error
TerminalSelectPane makes one pane, or its neighbour in a direction, the window's active pane.
func (*Controller) TerminalSelectWindow ¶
func (ctrl *Controller) TerminalSelectWindow(w http.ResponseWriter, r *http.Request) error
TerminalSelectWindow makes one window the session's active window.
func (*Controller) TerminalSplitPane ¶
func (ctrl *Controller) TerminalSplitPane(w http.ResponseWriter, r *http.Request) error
TerminalSplitPane splits one pane of an attached session and returns the new pane's id.
func (*Controller) TerminalStart ¶
func (ctrl *Controller) TerminalStart(w http.ResponseWriter, r *http.Request) error
TerminalStart spawns the tmux session behind a slug so it can be attached to.
func (*Controller) TerminalWindowForeground ¶
func (ctrl *Controller) TerminalWindowForeground(w http.ResponseWriter, r *http.Request) error
TerminalWindowForeground reports whether closing a window would kill work.
func (*Controller) TerminalZoomPane ¶
func (ctrl *Controller) TerminalZoomPane(w http.ResponseWriter, r *http.Request) error
TerminalZoomPane toggles a pane between filling its window and its place in the layout.
type ErrResp ¶
ErrResp documents one non-success status an operation can return, and when. The error body is always the shared {kind, message, fields?} shape.
type Op ¶
type Op struct {
Method string
Path string
Summary string
Request any
Response any
Status int // success status; 0 means 200
Errors []ErrResp // documented non-success statuses beyond the generic default
Handler errchain.HandlerFunc
}
Op is one HTTP operation. The operations table is what the mux is built from, and Summary/Request/Response/Errors document each route where it is declared. They no longer feed a generated document: the agent-facing surface this adapter used to describe is the MCP server's now (ADR mcp-replaces-the-agent-facing-http-api), and what is left here is the Wails frontend's own transport plus the liveness probe — consumers that read hand-written clients, not an OpenAPI spec.
Source Files