Typed human-input requests — the pause/resume primitive an extension uses to ask the operator for structured values in the middle of a run.
An extension calls request! with a title and a vector of typed fields.
The call BLOCKS the calling thread, publishes a :human-input/request
channel event so the mounted channel can draw a dialog, and returns once a
channel calls submit! / cancel! or the request times out. Every
request carries a finite :timeout-ms — a headless or wedged channel can
never pin an extension thread forever.
Field types are a CLOSED set (see field-types): extension-supplied type
names are looked up, never keyword-minted. Coercion and validation live in
one place, so the value an extension receives already matches the declared
type: a :checkbox yields a boolean, a :multiselect a vector of declared
option values, a :select one declared option value.
Secrets never travel as plaintext. A :password field resolves to an opaque
vis-secret:<uuid> handle; the plaintext stays in a process-local vault and
is readable only through reveal-secret from the trusted extension side.
Handles are what land in logs, transcripts and wire payloads, so a leaked
event is worthless.
Typed human-input requests — the pause/resume primitive an extension uses to ask the operator for structured values in the middle of a run. An extension calls [[request!]] with a title and a vector of typed fields. The call BLOCKS the calling thread, publishes a `:human-input/request` channel event so the mounted channel can draw a dialog, and returns once a channel calls [[submit!]] / [[cancel!]] or the request times out. Every request carries a finite `:timeout-ms` — a headless or wedged channel can never pin an extension thread forever. Field types are a CLOSED set (see [[field-types]]): extension-supplied type names are looked up, never `keyword`-minted. Coercion and validation live in one place, so the value an extension receives already matches the declared type: a `:checkbox` yields a boolean, a `:multiselect` a vector of declared option values, a `:select` one declared option value. Secrets never travel as plaintext. A `:password` field resolves to an opaque `vis-secret:<uuid>` handle; the plaintext stays in a process-local vault and is readable only through [[reveal-secret]] from the trusted extension side. Handles are what land in logs, transcripts and wire payloads, so a leaked event is worthless.
(answer->wire answer)Wire projection of a request! answer: snake_case string keys, JSON-safe
values. :password values stay opaque handles.
Wire projection of a [[request!]] answer: snake_case string keys, JSON-safe values. `:password` values stay opaque handles.
(cancel! request-id)(cancel! request-id reason)Cancel pending request request-id on the operator's behalf. Returns true
when it was pending AND dismissable.
A request declared :is-cancellable false refuses here, so EVERY surface is
refused alike — the TUI dialog, the companion app, any extension API. The
only ways out of such a request are an accepted answer, its timeout, and
cancel-all!.
Cancel pending request `request-id` on the operator's behalf. Returns true when it was pending AND dismissable. A request declared `:is-cancellable false` refuses here, so EVERY surface is refused alike — the TUI dialog, the companion app, any extension API. The only ways out of such a request are an accepted answer, its timeout, and [[cancel-all!]].
(cancel-all!)(cancel-all! reason)Cancel every pending request. Returns how many were released. Used when a
channel detaches or the session shuts down, so no thread stays parked — this
one ignores :is-cancellable, because nothing is left to answer with.
Cancel every pending request. Returns how many were released. Used when a channel detaches or the session shuts down, so no thread stays parked — this one ignores `:is-cancellable`, because nothing is left to answer with.
(coerce-value {:keys [type] :as field} value)Coerce and validate one raw value against normalized field. Returns
[:ok coerced] or [:error message].
Coerce and validate one raw `value` against normalized `field`. Returns `[:ok coerced]` or `[:error message]`.
(coerce-values fields values)Coerce a raw field id -> value map against a request's fields. Returns
{:is-accepted true :values …} or {:is-accepted false :errors {id msg}}.
:password values are replaced with opaque vault handles.
Coerce a raw `field id -> value` map against a request's `fields`. Returns
`{:is-accepted true :values …}` or `{:is-accepted false :errors {id msg}}`.
`:password` values are replaced with opaque vault handles.Requests wait five minutes unless the caller asks for something else.
Requests wait five minutes unless the caller asks for something else.
Wire type name -> internal field-type keyword. Closed set.
Wire type name -> internal field-type keyword. Closed set.
(forget-secret! handle)Drop the plaintext behind handle. Returns true when something was dropped.
Drop the plaintext behind `handle`. Returns true when something was dropped.
(forget-secrets!)Empty the vault. Returns how many plaintexts were dropped.
Empty the vault. Returns how many plaintexts were dropped.
Upper bound on :timeout-ms. One hour — long enough for a human who stepped
away, short enough that a forgotten dialog cannot pin a thread for a day.
Upper bound on `:timeout-ms`. One hour — long enough for a human who stepped away, short enough that a forgotten dialog cannot pin a thread for a day.
(normalize-field field)Validate one field spec and return its internal form. Throws ex-info with
:type :vis/human-input-invalid-field on a bad spec.
Three names, three jobs, and every field ends up with all three:
:name is how the answer is KEYED — the key the extension reads back out
of :values (:id is the historical alias, accepted and still emitted).:label is how the field is SHOWN. Never blank: a field without one
shows its :name, so no surface ever draws a bare, unlabelled input.:description is the prose under that label, rendered in italic by every
dialog (:help is its legacy alias).Validate one field spec and return its internal form. Throws `ex-info` with
`:type :vis/human-input-invalid-field` on a bad spec.
Three names, three jobs, and every field ends up with all three:
- `:name` is how the answer is KEYED — the key the extension reads back out
of `:values` (`:id` is the historical alias, accepted and still emitted).
- `:label` is how the field is SHOWN. Never blank: a field without one
shows its `:name`, so no surface ever draws a bare, unlabelled input.
- `:description` is the prose under that label, rendered in italic by every
dialog (`:help` is its legacy alias).(normalize-request request)Validate a human-input request spec and return its internal form. Throws
ex-info with :type :vis/human-input-invalid-request (or
:vis/human-input-invalid-field) on a bad spec.
Validate a human-input request spec and return its internal form. Throws `ex-info` with `:type :vis/human-input-invalid-request` (or `:vis/human-input-invalid-field`) on a bad spec.
(pending-request request-id)The pending request request-id, as a view, or nil.
The pending request `request-id`, as a view, or nil.
(pending-requests)Snapshot of the currently pending requests, oldest first. Views only.
Snapshot of the currently pending requests, oldest first. Views only.
(request! request)Ask the operator for typed values and BLOCK until they answer.
request is a spec map — :title, :fields, optional :description,
:submit-label, :cancel-label, :is-cancellable, :timeout-ms,
:channel-ids (string keys from the Python boundary work too).
Every field carries :name, :type, :label and an optional
:description. :name keys the answer in :values, :label is what the
dialog shows above the input, and :description is the italic line under
that label — see normalize-field.
Publishes a :human-input/request channel event, waits for submit! /
cancel!, and always returns a map, either
:is-submitted true, :reason "submitted", plus :request-id and :values
or
:is-submitted false, :reason "cancelled"/"timeout"/…, plus :request-id
:password values in :values are opaque handles — see reveal-secret.
Ask the operator for typed values and BLOCK until they answer. `request` is a spec map — `:title`, `:fields`, optional `:description`, `:submit-label`, `:cancel-label`, `:is-cancellable`, `:timeout-ms`, `:channel-ids` (string keys from the Python boundary work too). Every field carries `:name`, `:type`, `:label` and an optional `:description`. `:name` keys the answer in `:values`, `:label` is what the dialog shows above the input, and `:description` is the italic line under that label — see [[normalize-field]]. Publishes a `:human-input/request` channel event, waits for [[submit!]] / [[cancel!]], and always returns a map, either :is-submitted true, :reason "submitted", plus :request-id and :values or :is-submitted false, :reason "cancelled"/"timeout"/…, plus :request-id `:password` values in `:values` are opaque handles — see [[reveal-secret]].
(request->view request)The channel/wire-facing projection of a pending request: the spec a dialog needs, and nothing a channel must not see (no promise, no submitted values).
The channel/wire-facing projection of a pending request: the spec a dialog needs, and nothing a channel must not see (no promise, no submitted values).
(request-json! request-json)The strings-only seam a Python extension crosses: a JSON request object in, a
JSON answer object out. Blocks exactly like request!.
Channel routing is host-side — a channel_id/channel_ids key is dropped
rather than minting keywords from guest data, so a Python extension always
reaches the channels the host picked.
The strings-only seam a Python extension crosses: a JSON request object in, a JSON answer object out. Blocks exactly like [[request!]]. Channel routing is host-side — a `channel_id`/`channel_ids` key is dropped rather than minting keywords from guest data, so a Python extension always reaches the channels the host picked.
(reveal-secret handle)Return the plaintext behind a vis-secret: handle, or nil when the handle is
unknown/forgotten. Trusted-side only: never hand the result to a channel, a
log, or the model.
Return the plaintext behind a `vis-secret:` handle, or nil when the handle is unknown/forgotten. Trusted-side only: never hand the result to a channel, a log, or the model.
(secret-handle? value)True when value is an opaque handle minted by a :password field.
True when `value` is an opaque handle minted by a `:password` field.
(submit! request-id values)Resolve pending request request-id with a raw field id -> value map.
Returns {:is-accepted false :errors {field-id message}} when a value fails
its field's validation — the request stays pending so the dialog can show the
errors inline. Returns {:is-accepted true} once the waiter is released, and
{:is-accepted false :reason "unknown"} for an already-settled request.
Resolve pending request `request-id` with a raw `field id -> value` map.
Returns `{:is-accepted false :errors {field-id message}}` when a value fails
its field's validation — the request stays pending so the dialog can show the
errors inline. Returns `{:is-accepted true}` once the waiter is released, and
`{:is-accepted false :reason "unknown"}` for an already-settled request.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 |