HTTP/SSE client for the long-lived gateway daemon.
Interactive channels call this facade instead of gateway.state directly. It
discover-or-starts the one daemon for the current DB, then speaks the same
HTTP/SSE API every other client uses. This is the thin-client half of the
gateway-daemon plan: token refresh, turn execution, and live streaming happen
in ONE process.
HTTP/SSE client for the long-lived gateway daemon. Interactive channels call this facade instead of `gateway.state` directly. It discover-or-starts the one daemon for the current DB, then speaks the same HTTP/SSE API every other client uses. This is the thin-client half of the gateway-daemon plan: token refresh, turn execution, and live streaming happen in ONE process.
(abandon-draft! sid workspace-id reason)Permanently abandon workspace-id IN THE DAEMON. The target may be current or
parked, but not pinned to another session.
Permanently abandon `workspace-id` IN THE DAEMON. The target may be current or parked, but not pinned to another session.
(add-filesystem-root! sid path)Add path as an extra filesystem root for sid IN THE DAEMON, returning the
refreshed session-workspace-info. The daemon owns the session's DB, so the
new root is what every channel reads back (fixing the local-only mutation that
never reached the running session).
Add `path` as an extra filesystem root for `sid` IN THE DAEMON, returning the refreshed `session-workspace-info`. The daemon owns the session's DB, so the new root is what every channel reads back (fixing the local-only mutation that never reached the running session).
(assign-project! sid pid)Assign a session to a project (nil clears / removes from project). Returns the soul.
Assign a session to a project (nil clears / removes from project). Returns the soul.
(cancel-current-turn! sid)Tid-less cancel: kill whatever turn currently holds sid's :current-turn
slot in the daemon. For callers that lost (or never learned) the gateway
turn id. Returns the parsed body ({"status" "cancelling", "turn_id" tid});
throws on HTTP error (409 when the session is idle).
Tid-less cancel: kill whatever turn currently holds `sid`'s `:current-turn`
slot in the daemon. For callers that lost (or never learned) the gateway
turn id. Returns the parsed body (`{"status" "cancelling", "turn_id" tid}`);
throws on HTTP error (409 when the session is idle).(change-root! sid path)Repoint sid's PRIMARY filesystem root to path IN THE DAEMON, returning the
refreshed session-workspace-info (whose :id is the newly pinned workspace).
Repoint `sid`'s PRIMARY filesystem root to `path` IN THE DAEMON, returning the refreshed `session-workspace-info` (whose `:id` is the newly pinned workspace).
(compatibility)This client's verdict on the daemon it last probed — the SAME pure comparison
the gateway runs on us (protocol/verdict), so the two halves never
disagree about which one is out of date.
This client's verdict on the daemon it last probed — the SAME pure comparison the gateway runs on us ([[protocol/verdict]]), so the two halves never disagree about which one is out of date.
(create-draft! sid label blank?)Create and enter a named draft for sid IN THE DAEMON. Any current draft is
stashed first. Pass blank? to start from an empty tree.
Create and enter a named draft for `sid` IN THE DAEMON. Any current draft is stashed first. Pass `blank?` to start from an empty tree.
(ensure-gateway!)(ensure-gateway! {:keys [port host]})Return a fresh daemon registry entry for the current DB, auto-starting the
detached gateway if needed. :memory is a programmer error for this client;
headless one-shots stay in-process and should not call here.
Optional :port/:host overrides the bind used WHEN THIS CALL SPAWNS a fresh
daemon (e.g. vis channels web --port); a fresh daemon already registered for
the DB is a singleton and is attached to as-is, so the override is moot there.
Freshness is DEBOUNCED: the full HTTP /healthz probe (via probe-entry?)
runs at most once per entry-probe-ttl-ms. Within that window a cached entry
whose pid is still alive is trusted directly, so the TUI's chatty poll loop
stops paying for a doubled HTTP round-trip (and its JSON/reflection churn) on
every gateway call.
Return a fresh daemon registry entry for the current DB, auto-starting the detached gateway if needed. `:memory` is a programmer error for this client; headless one-shots stay in-process and should not call here. Optional `:port`/`:host` overrides the bind used WHEN THIS CALL SPAWNS a fresh daemon (e.g. `vis channels web --port`); a fresh daemon already registered for the DB is a singleton and is attached to as-is, so the override is moot there. Freshness is DEBOUNCED: the full HTTP /healthz probe (via `probe-entry?`) runs at most once per `entry-probe-ttl-ms`. Within that window a cached entry whose pid is still alive is trusted directly, so the TUI's chatty poll loop stops paying for a doubled HTTP round-trip (and its JSON/reflection churn) on every gateway call.
(ensure-gateway-serving! path)(ensure-gateway-serving! path opts)Like ensure-gateway!, but tries to GUARANTEE the returned daemon actually
serves path. When ensure-gateway! attaches to an already-running daemon
that 404s on path (started from a classpath missing the extension that owns
it), respawn a fresh daemon from THIS process — whose classpath, by
construction, carries the route. This is what lets vis channels web
self-heal instead of parking on a /ui that 404s.
Optional opts ({:port :host}) overrides the bind used when THIS call has
to spawn a fresh daemon (the vis channels web --port/--host flags); it is
moot when a fresh daemon is already registered for the DB.
The respawn is NON-DESTRUCTIVE. A blind POST /v1/admin/stop is refcount-blind: it would abort every in-flight turn and kill every session's background resources. So we force-restart the stale daemon ONLY when it is idle — no OTHER clients and no running turn. Otherwise we leave it untouched and surface a clear error. A transport blip on the probe (not a real 404) never triggers a restart. Returns the entry.
Like [[ensure-gateway!]], but tries to GUARANTEE the returned daemon actually
serves `path`. When [[ensure-gateway!]] attaches to an already-running daemon
that 404s on `path` (started from a classpath missing the extension that owns
it), respawn a fresh daemon from THIS process — whose classpath, by
construction, carries the route. This is what lets `vis channels web`
self-heal instead of parking on a `/ui` that 404s.
Optional `opts` (`{:port :host}`) overrides the bind used when THIS call has
to spawn a fresh daemon (the `vis channels web --port/--host` flags); it is
moot when a fresh daemon is already registered for the DB.
The respawn is NON-DESTRUCTIVE. A blind POST /v1/admin/stop is refcount-blind:
it would abort every in-flight turn and kill every session's background
resources. So we force-restart the stale daemon ONLY when it is idle — no OTHER
clients and no running turn. Otherwise we leave it untouched and surface a clear
error. A transport blip on the probe (not a real 404) never triggers a restart.
Returns the entry.(ensure-project-for-root! root)(ensure-project-for-root! root name)POST /v1/projects/actions/ensure — get-or-create the project bound to canonical
workspace root (a project IS a TUI tab set). name seeds a fresh project.
Returns the project.
POST /v1/projects/actions/ensure — get-or-create the project bound to canonical workspace `root` (a project IS a TUI tab set). `name` seeds a fresh project. Returns the project.
(iteration-attachment-bytes sid iid idx)Raw bytes (a byte-array) of ONE outbound artifact — iteration iid, its 0-based
idx in the iteration's ordered attachment list — fetched from the daemon's
attachment byte endpoint, or nil (404 / no bytes). The lazy-fetch companion to
a live iteration.completed attachment descriptor: a client sees {:index :media_type …} on the frame, then pulls the bytes here. HISTORY resolves the
same way (the trace iteration's :id + attachment index).
Raw bytes (a byte-array) of ONE outbound artifact — iteration `iid`, its 0-based
`idx` in the iteration's ordered attachment list — fetched from the daemon's
attachment byte endpoint, or nil (404 / no bytes). The lazy-fetch companion to
a live `iteration.completed` attachment descriptor: a client sees `{:index
:media_type …}` on the frame, then pulls the bytes here. HISTORY resolves the
same way (the trace iteration's `:id` + attachment index).(list-drafts sid)Active/stashed DRAFTS for sid's repo IN THE DAEMON, newest first, in the
canonical wire shape [{"workspace_id" "label" "root" "repo_root" "fork_ms" "is_current"}]. The gateway is the source of truth for parked
drafts, so every channel reads the SAME list here (web picker, TUI drafts view).
Active/stashed DRAFTS for `sid`'s repo IN THE DAEMON, newest first, in the
canonical wire shape `[{"workspace_id" "label" "root" "repo_root"
"fork_ms" "is_current"}]`. The gateway is the source of truth for parked
drafts, so every channel reads the SAME list here (web picker, TUI drafts view).(list-projects)(list-projects {:keys [owner archived?]})GET /v1/projects — projects are CROSS-CHANNEL. opts: :owner (string),
:archived? (bool). Returns the :projects vector.
GET /v1/projects — projects are CROSS-CHANNEL. `opts`: :owner (string), :archived? (bool). Returns the :projects vector.
(list-resources sid)Vector of the session's live resource DATA maps from the daemon's registry
(string-keyed, same shape resources/list-resources returns in-process).
Vector of the session's live resource DATA maps from the daemon's registry (string-keyed, same shape `resources/list-resources` returns in-process).
(list-resources-cached sid)Footer-frequency read: the session's resource list served from a per-sid cache that NEVER blocks the caller. A stale (or cold) entry kicks a background single-flight refresh and this returns the last-known value immediately (nil before the first success). Keeping the daemon HTTP round-trip OFF the render thread is what stops a busy daemon from stalling every TUI frame.
Footer-frequency read: the session's resource list served from a per-sid cache that NEVER blocks the caller. A stale (or cold) entry kicks a background single-flight refresh and this returns the last-known value immediately (nil before the first success). Keeping the daemon HTTP round-trip OFF the render thread is what stops a busy daemon from stalling every TUI frame.
(mux-subscribe! sid sink cursor)Add sid's sink to the ONE process-wide multiplexed event stream, starting
at cursor (its current-seq for a live-only stream). The connection is
(re)opened only when the session set changes; multiple local listeners for
the SAME session share one cursor and one remote subscription. Returns a
zero-arg cleanup fn. Every sink sees gateway.connected / gateway.disconnected
on connection changes, exactly like the per-session subscribe!.
Add `sid`'s `sink` to the ONE process-wide multiplexed event stream, starting at `cursor` (its `current-seq` for a live-only stream). The connection is (re)opened only when the session set changes; multiple local listeners for the SAME session share one cursor and one remote subscription. Returns a zero-arg cleanup fn. Every sink sees gateway.connected / gateway.disconnected on connection changes, exactly like the per-session [[subscribe!]].
(mux-unsubscribe! sid)(mux-unsubscribe! sid sub-id)Drop one local listener from the multiplexed stream and reconnect only when the last listener for that sid is gone (or tear the connection down when it was the last watched session).
Drop one local listener from the multiplexed stream and reconnect only when the last listener for that sid is gone (or tear the connection down when it was the last watched session).
(pairing-info)Connection details for the daemon registered for the current DB, so a caller
can build a companion pairing QR on demand (not only at --pair boot time).
Returns {:running? :host :port :token :loopback?}; :running? is false when no
fresh daemon is registered, and :loopback? flags a 127.0.0.1/::1/localhost
bind that a phone can never reach.
Connection details for the daemon registered for the current DB, so a caller
can build a companion pairing QR on demand (not only at `--pair` boot time).
Returns {:running? :host :port :token :loopback?}; `:running?` is false when no
fresh daemon is registered, and `:loopback?` flags a 127.0.0.1/::1/localhost
bind that a phone can never reach.(provider-auth-cancel! provider-id flow-id)Forget an abandoned flow. Idempotent.
Forget an abandoned flow. Idempotent.
(provider-auth-complete! provider-id flow-id redirect-url)Finish a pkce flow with the redirect URL the user pasted back.
Finish a `pkce` flow with the redirect URL the user pasted back.
(provider-auth-poll! provider-id flow-id)Read a device flow's verdict: pending, ok, or error. Never blocks.
Read a `device` flow's verdict: `pending`, `ok`, or `error`. Never blocks.
(provider-auth-start! provider-id)Begin OAuth for provider-id. Returns the string-keyed wire flow
(flow_id, kind, url, user_code, verification_uri, interval_ms,
instructions) or nil when the daemon refused.
Begin OAuth for `provider-id`. Returns the string-keyed wire flow (`flow_id`, `kind`, `url`, `user_code`, `verification_uri`, `interval_ms`, `instructions`) or nil when the daemon refused.
(provider-auth-submit-key! provider-id flow-id api-key)Finish an api-key flow: hand the key the user typed to the DAEMON, which
persists it in ITS OWN config. The calling process never writes the
credential — same boundary as OAuth.
Finish an `api-key` flow: hand the key the user typed to the DAEMON, which persists it in ITS OWN config. The calling process never writes the credential — same boundary as OAuth.
(provider-logout! provider-id)Clear provider-id's persisted credentials IN THE DAEMON.
Clear `provider-id`'s persisted credentials IN THE DAEMON.
(provider-models provider-id show-all?)GET /v1/providers/:id/models — the LIVE model catalog resolved DAEMON-side,
where the gateway owns OAuth token resolution. A thin client NEVER builds a
token-resolving svar router to list models; it asks the daemon, which runs
the svar/models! probe (and any token refresh) against its own credential.
Returns the engine-shaped {:models [id …] :hidden-count n}.
GET /v1/providers/:id/models — the LIVE model catalog resolved DAEMON-side,
where the gateway owns OAuth token resolution. A thin client NEVER builds a
token-resolving svar router to list models; it asks the daemon, which runs
the `svar/models!` probe (and any token refresh) against its own credential.
Returns the engine-shaped `{:models [id …] :hidden-count n}`.(reconcile-running-turns!)Clients do not sweep. Only the daemon may reconcile its own startup orphans.
Clients do not sweep. Only the daemon may reconcile its own startup orphans.
(release-session! sid)Release a session VIEW when the owning channel exits: tell the daemon to
stop the session's background resources (background shell children, REPLs) and drop
its live runtime, then release the process-level client lease. This is NOT
a per-session delete (the transcript stays resumable) and never sends daemon
shutdown; the daemon stops itself only when refcount AND running-turn-count
hit zero. Best-effort and never daemon-spawning — if no fresh daemon is
registered there is nothing to release against.
Release a session VIEW when the owning channel exits: tell the daemon to stop the session's background resources (background `shell` children, REPLs) and drop its live runtime, then release the process-level client lease. This is NOT a per-session delete (the transcript stays resumable) and never sends daemon shutdown; the daemon stops itself only when refcount AND running-turn-count hit zero. Best-effort and never daemon-spawning — if no fresh daemon is registered there is nothing to release against.
(release-session-runtime! sid)Release a session's live RUNTIME on the daemon WITHOUT touching the process
client lease: stop its background resources (background shell children, managed REPLs)
and drop its loop/env, keeping the transcript resumable. Used when ONE view of
a session closes (e.g. a single TUI tab) while the owning process stays
connected — so the whole-process refcount lease is left intact and the daemon
is never nudged toward self-reap while other tabs remain open. Best-effort and
never daemon-spawning — nothing to release against when no fresh daemon is
registered.
Release a session's live RUNTIME on the daemon WITHOUT touching the process client lease: stop its background resources (background `shell` children, managed REPLs) and drop its loop/env, keeping the transcript resumable. Used when ONE view of a session closes (e.g. a single TUI tab) while the owning process stays connected — so the whole-process refcount lease is left intact and the daemon is never nudged toward self-reap while other tabs remain open. Best-effort and never daemon-spawning — nothing to release against when no fresh daemon is registered.
(remove-filesystem-root! sid path)Remove path from sid's extra filesystem roots IN THE DAEMON, returning the
refreshed session-workspace-info.
Remove `path` from `sid`'s extra filesystem roots IN THE DAEMON, returning the refreshed `session-workspace-info`.
(reorder-project-sessions! pid session-ids)Persist a project's manual session order in one gateway call. Loose named sessions are adopted atomically; guests owned by another project are not moved.
Persist a project's manual session order in one gateway call. Loose named sessions are adopted atomically; guests owned by another project are not moved.
(resource-logs sid rid)Captured output lines for a background via its daemon-side logs-fn, or nil.
Captured output lines for a background via its daemon-side logs-fn, or nil.
(restart-resource! sid rid)Run the resource's restart-fn in the daemon. Returns the restart result map.
Run the resource's restart-fn in the daemon. Returns the restart result map.
(resume-draft! sid workspace-id)Switch sid INTO the stashed draft workspace-id IN THE DAEMON (stashing any
current draft first), returning the refreshed session-workspace-info.
Switch `sid` INTO the stashed draft `workspace-id` IN THE DAEMON (stashing any current draft first), returning the refreshed `session-workspace-info`.
(router)GET /v1/router — the unified router dialog payload assembled by the gateway:
{"providers" [{"id" … "label" … "base_url" … "models" [...] "status" {"is_authenticated" …} "limits" {…}} …]}. Returned VERBATIM with
snake_case STRING keys — NO keyword restoration. Consumers read the string
keys directly ((get status "is_authenticated")).
GET /v1/router — the unified router dialog payload assembled by the gateway:
`{"providers" [{"id" … "label" … "base_url" … "models" [...]
"status" {"is_authenticated" …} "limits" {…}} …]}`. Returned VERBATIM with
snake_case STRING keys — NO keyword restoration. Consumers read the string
keys directly (`(get status "is_authenticated")`).(search-session-ids query)GET /v1/sessions/actions/search?q= — soul-id STRINGS whose transcript (user request +
assistant text) matches query. Blank query → []. The heavy assistant text
never crosses the wire; callers union these ids into a local title filter.
GET /v1/sessions/actions/search?q= — soul-id STRINGS whose transcript (user request + assistant text) matches `query`. Blank query → []. The heavy assistant text never crosses the wire; callers union these ids into a local title filter.
(search-session-matches query)GET /v1/sessions/actions/search?q= — like search-session-ids but each hit is
TAGGED with WHERE it matched and carries up to a handful of snippets:
[{:id str :in-request? bool :in-reply? bool :request-snippet str :reply-snippet str :hits [{:side :request|:reply :snippet str :at ms}]}].
:in-request? = the user's own request matched; :in-reply? = assistant reply
text matched. Blank query → []. Heavy assistant text never crosses the wire.
GET /v1/sessions/actions/search?q= — like `search-session-ids` but each hit is
TAGGED with WHERE it matched and carries up to a handful of snippets:
`[{:id str :in-request? bool :in-reply? bool :request-snippet str
:reply-snippet str :hits [{:side :request|:reply :snippet str :at ms}]}]`.
`:in-request?` = the user's own request matched; `:in-reply?` = assistant reply
text matched. Blank query → []. Heavy assistant text never crosses the wire.(session-model-cached sid)Footer-frequency read of the session's model pref served from a per-sid
cache that NEVER blocks the caller (issue #29, gateway leg: this used to
be a live session-model HTTP round-trip per footer frame). A stale (or
cold) entry kicks a background single-flight refresh and this returns the
last-known value immediately (nil before the first success).
set-session-model! writes through, so a pick made in THIS client shows
on the very next frame.
Footer-frequency read of the session's model pref served from a per-sid cache that NEVER blocks the caller (issue #29, gateway leg: this used to be a live `session-model` HTTP round-trip per footer frame). A stale (or cold) entry kicks a background single-flight refresh and this returns the last-known value immediately (nil before the first success). `set-session-model!` writes through, so a pick made in THIS client shows on the very next frame.
(set-session-model! sid provider model)PATCH the session's model pref in the daemon. Writes the returned pref
straight through into the session-model-cached snapshot so the footer
chip flips on the very next frame instead of waiting out the cache TTL.
PATCH the session's model pref in the daemon. Writes the returned pref straight through into the `session-model-cached` snapshot so the footer chip flips on the very next frame instead of waiting out the cache TTL.
(sse-event-action event wanted-turn-id)Pure classifier for one parsed SSE event while blocking on wanted-turn-id.
Returns [action event']:
:terminal — the wanted turn reached a terminal event (return event')
:forward — hand to on-event (own-turn progress OR a sibling turn's
queue-mirror event — see wire/queue-mirror-event-types),
then keep reading
:skip — another turn's non-queue event, drop it.
A turn.queued.deleted for the WANTED turn is terminal too: the queued
record was pulled back into an editor before it ever ran, so a cancelled
terminal is synthesized instead of blocking on a turn that never starts.
Pure classifier for one parsed SSE event while blocking on `wanted-turn-id`.
Returns `[action event']`:
:terminal — the wanted turn reached a terminal event (return `event'`)
:forward — hand to on-event (own-turn progress OR a sibling turn's
queue-mirror event — see `wire/queue-mirror-event-types`),
then keep reading
:skip — another turn's non-queue event, drop it.
A `turn.queued.deleted` for the WANTED turn is terminal too: the queued
record was pulled back into an editor before it ever ran, so a cancelled
terminal is synthesized instead of blocking on a turn that never starts.(stash-draft! sid)Park sid's current draft IN THE DAEMON (non-destructive), returning the
refreshed session-workspace-info — now back on trunk.
Park `sid`'s current draft IN THE DAEMON (non-destructive), returning the refreshed `session-workspace-info` — now back on trunk.
(stop-resource! sid rid)Run the resource's stop-fn in the daemon and unregister it. Returns the
daemon's stop result map ({:result "stopped"|"unknown"|… :id …}).
Run the resource's stop-fn in the daemon and unregister it. Returns the
daemon's stop result map (`{:result "stopped"|"unknown"|… :id …}`).(subscribe! sid sub-id sink cursor)Remote equivalent of gateway.state/subscribe!: start a background SSE reader
that replays cursor then calls sink for every live event. Returns an empty
replay vector because the gateway's SSE endpoint itself handles replay before
live delivery.
Remote equivalent of gateway.state/subscribe!: start a background SSE reader that replays `cursor` then calls `sink` for every live event. Returns an empty replay vector because the gateway's SSE endpoint itself handles replay before live delivery.
(transcript-html sid)The gateway-rendered STANDALONE HTML transcript for sid — the canonical
transcript->html, the HTML sibling of transcript-md. Returns the string,
or nil on a non-2xx.
The gateway-rendered STANDALONE HTML transcript for `sid` — the canonical `transcript->html`, the HTML sibling of `transcript-md`. Returns the string, or nil on a non-2xx.
(transcript-md sid)The gateway-rendered user/assistant dialog Markdown for sid — the canonical
transcript->md :dialog. Returns the string, or nil on a non-2xx.
The gateway-rendered user/assistant dialog Markdown for `sid` — the canonical `transcript->md :dialog`. Returns the string, or nil on a non-2xx.
(turn-trace sid tid)Canonical wire iterations of ONE persisted turn (nil when the id is unknown to the daemon).
Canonical wire iterations of ONE persisted turn (nil when the id is unknown to the daemon).
cljdoc builds & hosts documentation for Clojure/Script libraries
| Ctrl+k | Jump to recent docs |
| ← | Move to previous article |
| → | Move to next article |
| Ctrl+/ | Jump to the search field |