The canonical per-form DISPLAY contract — ONE source of truth for the fields a channel reads to render an executed form, live (via the gateway) and restored (via the DB).
Why this exists: the SAME field set used to be hand-listed in independent
allowlists across the loop, persistence, gateway, progress, and restored display
paths. Now every layer projects the WHOLE set through ->display (outbound) /
<-wire (inbound), so a new display field is a ONE-line change to
display-keys and form-roundtrip-test fails if a boundary stops carrying it.
Transformed fields (:stdout/:error bounded, :silent/:duration_ms
renamed) stay as explicit gateway overrides — they are not carried verbatim, so
they are NOT in this set.
The canonical per-form DISPLAY contract — ONE source of truth for the fields a channel reads to render an executed form, live (via the gateway) and restored (via the DB). Why this exists: the SAME field set used to be hand-listed in independent allowlists across the loop, persistence, gateway, progress, and restored display paths. Now every layer projects the WHOLE set through `->display` (outbound) / `<-wire` (inbound), so a new display field is a ONE-line change to `display-keys` and `form-roundtrip-test` fails if a boundary stops carrying it. Transformed fields (`:stdout`/`:error` bounded, `:silent`/`:duration_ms` renamed) stay as explicit gateway overrides — they are not carried verbatim, so they are NOT in this set.
(->display m)Project canonical display fields from a source map, dropping nils.
Project canonical display fields from a source map, dropping nils.
(<-wire event)Read the canonical display fields back off a gateway WIRE event into a form,
using the literal wire spelling declared beside each engine key in
display-fields. The single inbound projection channels use — the mirror of
->display.
Read the canonical display fields back off a gateway WIRE event into a form, using the literal wire spelling declared beside each engine key in `display-fields`. The single inbound projection channels use — the mirror of `->display`.
(clip-to-wire s)(clip-to-wire s hint)Head-clip one form BODY to MAX_FORM_WIRE_CHARS, announcing what it dropped —
the ONE clip shared by every surface that body reaches: the model's tool
result, the card a channel paints, and the gateway's stdout copy of the same
text. Each used to hand-roll its own cut at its own ceiling, so one printed
output rode a single event twice at sizes an order of magnitude apart.
hint is the calling surface's own advice, appended to the marker — the model
is told to narrow its next read, a human card just says what was dropped. The
cut is util/truncate, so it never splits a surrogate pair. nil for a string
that is blank once trailing space is gone.
Head-clip one form BODY to `MAX_FORM_WIRE_CHARS`, announcing what it dropped — the ONE clip shared by every surface that body reaches: the model's tool result, the card a channel paints, and the gateway's `stdout` copy of the same text. Each used to hand-roll its own cut at its own ceiling, so one printed output rode a single event twice at sizes an order of magnitude apart. `hint` is the calling surface's own advice, appended to the marker — the model is told to narrow its next read, a human card just says what was dropped. The cut is `util/truncate`, so it never splits a surrogate pair. nil for a string that is blank once trailing space is gone.
The canonical engine keys projected by ->display and recovered by <-wire.
The canonical engine keys projected by `->display` and recovered by `<-wire`.
(envelope-duration-ms envelope)Wall-clock ms an executed form took, derived from the timing keys its envelope already carries — nil when the envelope carries no complete pair, so a caller can tell "took no measurable time" from "was never timed".
The ONE derivation of a form's duration: the loop, the CLI trace, the progress projection, the ctx envelope and a DB-restored transcript each used to carry a private copy of this arithmetic.
Wall-clock ms an executed form took, derived from the timing keys its envelope already carries — nil when the envelope carries no complete pair, so a caller can tell "took no measurable time" from "was never timed". The ONE derivation of a form's duration: the loop, the CLI trace, the progress projection, the ctx envelope and a DB-restored transcript each used to carry a private copy of this arithmetic.
Per-block printed-output ceiling. A block's stdout is head-clipped to this
many chars in the tool result — a universal backstop for a runaway print()
that tool-level caps don't catch (the model can print(open-ended composition)). The block's values still live in the sandbox (persistent REPL
vars the model can re-slice and print less of). ~64KB ≈ 16k tokens: generous
for an intentional full-file read, tight enough that one runaway print can't
blow the request.
Per-block printed-output ceiling. A block's stdout is head-clipped to this many chars in the tool result — a universal backstop for a runaway print() that tool-level caps don't catch (the model can `print(open-ended composition)`). The block's values still live in the sandbox (persistent REPL vars the model can re-slice and print less of). ~64KB ≈ 16k tokens: generous for an intentional full-file read, tight enough that one runaway print can't blow the request.
(result-card {:keys [op] :as form})Canonical result CARD descriptor derived only from the form's :stdout:
{:op grep — optional form metadata
:body …markdown… — local projection of printed output
:collapsible? true}
nil means the form printed nothing. A label or operation can never manufacture successful output.
Canonical result CARD descriptor derived only from the form's `:stdout`:
{:op `grep` — optional form metadata
:body …markdown… — local projection of printed output
:collapsible? true}
nil means the form printed nothing. A label or operation can never manufacture
successful output.(stdout-display form)The human-channel DISPLAY for one executed form as {:body}. :stdout is
the only successful output a Python form or !cmd form can publish; an
unprinted Python value never reaches the form, database, or wire.
A wall-clock timeout gets no card of its own: it is an error like any other,
while output printed before the timeout remains the ordinary stdout body.
The body is head-clipped to MAX_FORM_WIRE_CHARS. Returns nil when there is
nothing to show.
This is a pure local projection of the form's :stdout, so live wire and a
database-restored envelope paint the same card without storing or transporting
a rendered string.
The human-channel DISPLAY for one executed form as `{:body}`. `:stdout` is
the only successful output a Python form or `!cmd` form can publish; an
unprinted Python value never reaches the form, database, or wire.
A wall-clock timeout gets no card of its own: it is an error like any other,
while output printed before the timeout remains the ordinary stdout body.
The body is head-clipped to `MAX_FORM_WIRE_CHARS`. Returns nil when there is
nothing to show.
This is a pure local projection of the form's `:stdout`, so live wire and a
database-restored envelope paint the same card without storing or transporting
a rendered string.(with-display form)Attach the cached ruff rendering of a form's Python source when the form did not
author its own :display-code. Result presentation is always derived locally
from canonical facts and is never attached to the form.
Attach the cached ruff rendering of a form's Python source when the form did not author its own `:display-code`. Result presentation is always derived locally from canonical facts and is never attached to the form.
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 |