Documentation
¶
Overview ¶
Package session mounts the Hanzo Cloud /v1/code/sessions/* surface: the registry of live coding-agent runs launched by `hanzo code <agent>`. It is what console.hanzo.ai lists and drives — every claude/codex/dev process, on every machine, shown as a session you can watch (over its ttyd terminal tunnel) and steer.
Org isolation is enforced SERVER-SIDE on every request: the org is principal.Org(c) — the value minted from the VALIDATED bearer owner claim — and NEVER a client header. One SQLite file per org ({DataDir}/orgs/{slug}/ session.db), every query filtered WHERE org=?, so one org can never see or mutate another's sessions. Project is the LINK to the deployable projects.Project a run belongs to (a column, filterable), not a second partition: the console default is the org-wide "what's running" view.
Surface (all org-scoped; /v1 only):
POST /v1/code/sessions register/announce a run -> Session (201) GET /v1/code/sessions[?live&status=&project=&host=&agent=] list -> [Session] GET /v1/code/sessions/:id session detail -> Session PATCH /v1/code/sessions/:id heartbeat/status/terminalURL -> Session DELETE /v1/code/sessions/:id forget a session POST /v1/code/sessions/:id/events record a hook event -> Event (201) GET /v1/code/sessions/:id/events list events -> [Event]
Index ¶
- func Mount(app cloud.Router, deps cloud.Deps) error
- func Shutdown() error
- type Event
- type Filter
- type Patch
- type Session
- type Store
- func (s *Store) AddEvent(ctx context.Context, e Event) error
- func (s *Store) Close() error
- func (s *Store) Create(ctx context.Context, x Session) error
- func (s *Store) Delete(ctx context.Context, org, id string) error
- func (s *Store) Get(ctx context.Context, org, id string) (Session, error)
- func (s *Store) List(ctx context.Context, org string, f Filter) ([]Session, error)
- func (s *Store) ListEvents(ctx context.Context, org, sessionID string) ([]Event, error)
- func (s *Store) Update(ctx context.Context, org, id string, now int64, p Patch) (Session, error)
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Event ¶
type Event struct {
ID string
SessionID string
Org string
Kind string // notification | stop | error | log
Message string
CreatedAt int64
}
Event is one lifecycle signal a session's agent emits — sourced from Claude Code's Notification/Stop hooks (needs-input, turn-done) — so the console and the @hanzo Slack relay learn state changes without scraping the terminal.
type Filter ¶
Filter narrows a session list. Empty fields do not constrain. Live selects only sessions that have not ended (the console's default "what's running").
type Patch ¶
Patch is the mutable subset of a session. A nil field leaves the column unchanged, so a heartbeat that only refreshes updated_at need not resend the terminal URL.
type Session ¶
type Session struct {
ID string
Org string
Project string
User string
Agent string // claude | codex | dev
Model string
Host string
Cwd string
TerminalURL string
Status string
StartedAt int64
UpdatedAt int64
EndedAt int64 // 0 while live
}
Session is one live (or ended) coding-agent run launched by `hanzo code <agent>`. It is the value console.hanzo.ai lists and drives: the registry row that says a claude/codex/dev process is running on some machine, against some Hanzo model, in some working directory, reachable at TerminalURL.
Org is the physical tenant boundary (one sessions.db per org, filtered WHERE org=? on every query). Project is the LINK to the deployable projects.Project the run belongs to (principal.Project, "" = none) — so a project view can filter its own sessions without a second registry.
TerminalURL is the ttyd web-terminal endpoint the launcher publishes once its ZT (or zrok) tunnel is up; empty until the mirror is ready. Status is the lifecycle column the console polls: starting → running → waiting (needs input) → ended | error.
type Store ¶
type Store struct {
// contains filtered or unexported fields
}
Store is one org's SQLite file. Every method filters WHERE org=?, so a query in one org's store can never reach another org's rows.
func (*Store) AddEvent ¶
AddEvent records one lifecycle event against an existing org-scoped session. It first confirms the session exists in this org (so an event can never be filed against another tenant's id), then inserts.
func (*Store) Close ¶
Close releases the org's SQLite handle; the OrgStore cache calls it on eviction and on Shutdown.
func (*Store) Delete ¶
Delete removes one org-scoped session and its events. Returns errNotFound when the id is absent.
func (*Store) List ¶
List returns the org's sessions, newest first, narrowed by f. The org predicate leads every query; f only ANDs further, so a filter can never widen past the tenant boundary.
func (*Store) ListEvents ¶
ListEvents returns a session's events oldest-first, org-scoped.
Source Files