httpapi

Documentation

Overview

Package httpapi implements hugen's native HTTP API — the session-stateful agent protocol over HTTP + SSE that an external gateway (and the hub UI, and the A2A bridge) drives. It is the ONE interaction surface for hub-mode hugen: many interfaces can drive one session at once (the runtime's multi-subscriber fanout), reads stream over SSE and writes are discrete POSTs.

It is a manager.Adapter sibling of pkg/adapter/tui, mounted by the `hugen serve` run mode. See design/008-integration/spec-http-api.md.

This file is the H1 skeleton: the agent card (/v1/agent), health probes, the two listener modes (shared auth mux vs a dedicated port), and the fail-closed boot gate (D4). Forwarded-user-token identity (H2) and the session surface (H3–H6) land next.

Index

• type Adapter
  • func New(opts ...Option) *Adapter
  • func (a *Adapter) Name() string
  • func (a *Adapter) Run(ctx context.Context, host adapter.Host) error
• type ArtifactStore
• type Option
  • func WithAgentIdentity(name, desc string) Option
  • func WithAllowOpen(v bool) Option
  • func WithArtifactStore(s ArtifactStore) Option
  • func WithBaseURL(u string) Option
  • func WithDevUI(v bool) Option
  • func WithIssuer(url string) Option
  • func WithListenPort(p int) Option
  • func WithLogger(l *slog.Logger) Option
  • func WithSharedMux(m *http.ServeMux) Option
  • func WithSkillManager(m skillManager) Option
  • func WithSkillsRefresher(fn SkillsRefresher) Option
  • func WithTaskController(c taskController) Option
  • func WithTaskStore(s taskReader) Option
  • func WithToolProviderLister(fn ToolProviderLister) Option
  • func WithToolProviderReloader(fn ToolProviderReloader) Option
  • func WithVerifier(f VerifyFunc) Option
• type SkillsRefresher
• type ToolProviderLister
• type ToolProviderReloader
• type VerifiedUser
• type VerifyFunc

Types

type Adapter

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

Adapter is the native HTTP API adapter. It implements manager.Adapter (via the pkg/adapter alias) and is wired into the runtime's adapter slice exactly like the TUI and A2A adapters.

func New

func New(opts ...Option) *Adapter

New constructs the HTTP API adapter. Callers select a listener mode via WithSharedMux or WithListenPort; New defaults neither (the cmd layer decides from HUGEN_API_PORT).

func (*Adapter) Name

func (a *Adapter) Name() string

Name implements manager.Adapter.

func (*Adapter) Run

func (a *Adapter) Run(ctx context.Context, host adapter.Host) error

Run implements manager.Adapter. It mounts the card + health probes and serves until ctx cancels. Shared mode registers handlers on the runtime's mux and blocks on ctx; dedicated mode owns an http.Server on listenPort and shuts it down gracefully.

type ArtifactStore

type ArtifactStore interface {
	List(rootID string) ([]protocol.ArtifactRef, error)
	Path(rootID, id string) (string, error)
	Ingest(rootID, srcPath, name string) (protocol.ArtifactRef, error)
}

ArtifactStore is the artifact surface the H6 endpoints need. The cmd layer wires it from core.Artifacts (Store.List/Path + Extension.Ingest). rootID is the root session id (== the API {id}).

type Option

type Option func(*Adapter)

Option configures an Adapter.

func WithAgentIdentity

func WithAgentIdentity(name, desc string) Option

WithAgentIdentity overrides the card's name/description.

func WithAllowOpen

func WithAllowOpen(v bool) Option

WithAllowOpen permits serving with no issuer configured (local dev). Without it, Run fails closed when no issuer is set (D4).

func WithArtifactStore

func WithArtifactStore(s ArtifactStore) Option

WithArtifactStore enables the H6 artifact endpoints (list / download / ingest). nil leaves them returning 501.

func WithBaseURL

func WithBaseURL(u string) Option

WithBaseURL sets the public base URL the card advertises.

func WithDevUI

func WithDevUI(v bool) Option

WithDevUI serves the built-in browser dev client at /ui. Off by default (HUGEN_API_DEV_UI). It has no auth (EventSource), so enable it only on an allow-open dev endpoint.

func WithIssuer

func WithIssuer(url string) Option

WithIssuer sets the hub OIDC issuer used to verify forwarded user tokens (H2). When empty, the endpoint is unauthenticated and Run fails closed unless WithAllowOpen is also set.

func WithListenPort

func WithListenPort(p int) Option

WithListenPort selects dedicated-listener mode on the given port. Ignored when WithSharedMux is also set.

func WithLogger

func WithLogger(l *slog.Logger) Option

WithLogger sets the adapter logger (defaults to host.Logger() in Run).

func WithSharedMux

func WithSharedMux(m *http.ServeMux) Option

WithSharedMux selects shared-listener mode: mount on the supplied mux (the runtime's auth/callback mux) and rely on its already-running http.Server.

func WithSkillManager

func WithSkillManager(m skillManager) Option

WithSkillManager enables the skills-panel endpoints (list / export / install). Without it they return 501.

func WithSkillsRefresher

func WithSkillsRefresher(fn SkillsRefresher) Option

WithSkillsRefresher enables POST /v1/skills/refresh backed by fn. Without it the endpoint returns 501 (no marketplace configured).

func WithTaskController

func WithTaskController(c taskController) Option

WithTaskController enables the task-lifecycle write endpoints (cancel / delete). nil leaves them returning 501.

func WithTaskStore

func WithTaskStore(s taskReader) Option

WithTaskStore enables GET /v1/sessions/{id}/tasks — the per-session scheduled- task list. nil leaves the endpoint returning an empty list.

func WithToolProviderLister

func WithToolProviderLister(fn ToolProviderLister) Option

WithToolProviderLister enables GET /v1/tool-providers.

func WithToolProviderReloader

func WithToolProviderReloader(fn ToolProviderReloader) Option

WithToolProviderReloader enables POST /v1/tool-providers/reload.

func WithVerifier

func WithVerifier(f VerifyFunc) Option

WithVerifier installs the forwarded-user-token verifier (H2). Without it the endpoint runs in allow-open dev mode — every request is the local dev user.

type SkillsRefresher

type SkillsRefresher func(ctx context.Context) (any, error)

SkillsRefresher runs one marketplace reconcile pass and returns a compact, JSON-marshalable outcome. The cmd layer wires it from the runtime reconciler (Core.RefreshSkills); nil leaves the endpoint returning 501.

type ToolProviderLister

type ToolProviderLister func(ctx context.Context) (any, error)

ToolProviderLister returns the agent's managed tool providers as a JSON-marshalable value. nil ⇒ GET /v1/tool-providers returns 501.

type ToolProviderReloader

type ToolProviderReloader func(ctx context.Context) (any, error)

ToolProviderReloader reconciles the root ToolManager's managed providers from the re-fetched agent config and returns a compact outcome. nil ⇒ 501.

type VerifiedUser

type VerifiedUser struct {
	UserID string `json:"user_id"`
	Name   string `json:"name,omitempty"`
	Role   string `json:"role,omitempty"`
}

VerifiedUser is the end-user identity a request carries once its forwarded token is verified — the SAME shape hugr's auth.me returns. It becomes the session OwnerID + ParticipantInfo (H3).

type VerifyFunc

type VerifyFunc func(ctx context.Context, rawToken string) (VerifiedUser, error)

VerifyFunc verifies a raw forwarded user token and returns the identity. A non-nil error (or empty UserID) ⇒ 401. The concrete implementation (verify against hugr's authority via auth.me) is built in the cmd layer so this package stays free of the query-engine / identity deps — D1.