Per-eval / per-call runtime knobs for the loop: Python-sandbox eval timeouts
(with clamping and a shell-timeout-aware widener), the svar/ask-code! stream
watchdog defaults, and the dynamic vars the loop binds per call.
A LEAF — depends on nothing else in the engine, so the loop and its tests read these settings from one place instead of carrying them in the loop namespace.
Per-eval / per-call runtime knobs for the loop: Python-sandbox eval timeouts (with clamping and a shell-timeout-aware widener), the `svar/ask-code!` stream watchdog defaults, and the dynamic vars the loop binds per call. A LEAF — depends on nothing else in the engine, so the loop and its tests read these settings from one place instead of carrying them in the loop namespace.
Park hook installed by the innermost enclosing timeout wall: (fn [thunk]).
Every wall in this engine counts WALL-CLOCK time, so a legitimate block —
above all a human-input pause waiting on the operator — otherwise dies at
the wall with a bare Timeout (120s) while the dialog is still up. Code
about to park on a human answer calls park-blocking-wall; every
enclosing wall then stops its clock until the thunk returns.
Park hook installed by the innermost enclosing timeout wall: `(fn [thunk])`. Every wall in this engine counts WALL-CLOCK time, so a legitimate block — above all a `human-input` pause waiting on the operator — otherwise dies at the wall with a bare `Timeout (120s)` while the dialog is still up. Code about to park on a human answer calls [[park-blocking-wall]]; every enclosing wall then stops its clock until the thunk returns.
Dynamic timeout in milliseconds for Python code evaluation.
Dynamic timeout in milliseconds for Python code evaluation.
Dynamic context for RLM debug logging.
Dynamic context for RLM debug logging.
Default inter-chunk idle timeout for Vis svar/ask-code! calls (ms).
Fires when the transport itself goes silent — not one byte, not even an
SSE keepalive comment. 300s = CODEX PARITY with
DEFAULT_STREAM_IDLE_TIMEOUT_MS. Model-progress silence while keepalives
continue is different and does not time out by default; see
ASK_CODE_SEMANTIC_TIMEOUT_MS.
Default inter-chunk idle timeout for Vis `svar/ask-code!` calls (ms). Fires when the transport itself goes silent — not one byte, not even an SSE keepalive comment. 300s = CODEX PARITY with `DEFAULT_STREAM_IDLE_TIMEOUT_MS`. Model-progress silence while keepalives continue is different and does not time out by default; see `ASK_CODE_SEMANTIC_TIMEOUT_MS`.
Default model/progress timeout for Vis svar/ask-code! streams (ms).
Disabled by default. A provider can keep its transport healthy with SSE keepalives while legitimately emitting no model-visible event during a long encrypted-reasoning phase. Treating that silence as failure loses healthy turns, as the transport's 300s idle watchdog already catches truly silent or wedged connections.
Callers that require a bounded model-progress gap can opt in with
:semantic-timeout-ms; explicit nil also disables it per call.
Default model/progress timeout for Vis `svar/ask-code!` streams (ms). Disabled by default. A provider can keep its transport healthy with SSE keepalives while legitimately emitting no model-visible event during a long encrypted-reasoning phase. Treating that silence as failure loses healthy turns, as the transport's 300s idle watchdog already catches truly silent or wedged connections. Callers that require a bounded model-progress gap can opt in with `:semantic-timeout-ms`; explicit nil also disables it per call.
Default time-to-first-token timeout for Vis svar/ask-code! calls (ms).
300s = CODEX PARITY. The Codex CLI has NO separate first-token budget:
its single stream_idle_timeout_ms (default
DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000) governs the wait for the
FIRST event exactly like every later transport gap. Matching that 300s
budget avoids hanging up first on a queued or cold-starting provider; a
genuinely dead connection still fails on its own transport error. Model-
progress silence is a separate, opt-in semantic watchdog below.
Default time-to-first-token timeout for Vis `svar/ask-code!` calls (ms). 300s = CODEX PARITY. The Codex CLI has NO separate first-token budget: its single `stream_idle_timeout_ms` (default `DEFAULT_STREAM_IDLE_TIMEOUT_MS = 300_000`) governs the wait for the FIRST event exactly like every later transport gap. Matching that 300s budget avoids hanging up first on a queued or cold-starting provider; a genuinely dead connection still fails on its own transport error. Model- progress silence is a separate, opt-in semantic watchdog below.
(await-wall fut deadline timeout-value)Wait for fut until the CURRENT value of deadline passes, re-reading the
atom on every wake so a park that MOVED the wall extends the wait instead of
expiring. Returns timeout-value once the wall is really reached.
Wait for `fut` until the CURRENT value of `deadline` passes, re-reading the atom on every wake so a park that MOVED the wall extends the wait instead of expiring. Returns `timeout-value` once the wall is really reached.
(clamp-eval-timeout-ms candidate)Clamp a candidate eval timeout to [MIN_EVAL_TIMEOUT_MS, MAX_EVAL_TIMEOUT_MS].
Clamp a candidate eval timeout to [MIN_EVAL_TIMEOUT_MS, MAX_EVAL_TIMEOUT_MS].
Default timeout in milliseconds for code evaluation in the Python sandbox.
Default timeout in milliseconds for code evaluation in the Python sandbox.
Default per-command / per-wait budget of the shell tool — declared here, and
read by foundation.shell, so ONE number governs both the tool and the
watchdog above it.
It matters here because it used to EQUAL the 120s eval watchdog. A shell
call that named no timeout therefore raced a watchdog that had already
started, and the watchdog always won: the turn got a bare Timeout (120s)
with NO output instead of shell's own envelope (partial stdout, timed_out
true, a killed process tree). The widener below now floors the watchdog above
this budget whenever an eval calls the shell at all.
Default per-command / per-wait budget of the `shell` tool — declared here, and read by `foundation.shell`, so ONE number governs both the tool and the watchdog above it. It matters here because it used to EQUAL the 120s eval watchdog. A `shell` call that named no timeout therefore raced a watchdog that had already started, and the watchdog always won: the turn got a bare `Timeout (120s)` with NO output instead of shell's own envelope (partial stdout, `timed_out` true, a killed process tree). The widener below now floors the watchdog above this budget whenever an eval calls the shell at all.
(eval-timeout-ms-for-code base-timeout-ms code)Eval watchdog for ONE Python block: the configured base, raised so it sits a grace period ABOVE the longest bounded call the block makes.
Eval watchdog for ONE Python block: the configured base, raised so it sits a grace period ABOVE the longest bounded call the block makes.
(explicit-shell-timeout-secs code)Best-effort scan for an EXPLICIT timeout override in Python code, in seconds.
Reads timeout_secs / timeout (seconds) and timeout_ms (milliseconds,
rounded up) — repl_eval and MCP calls spell their budget in ms, and leaving
that spelling out let a deliberately long call die at the default watchdog.
The real tool still owns validation/clamping; this only prevents the outer
watchdog from preempting a longer requested budget.
Best-effort scan for an EXPLICIT timeout override in Python code, in seconds. Reads `timeout_secs` / `timeout` (seconds) and `timeout_ms` (milliseconds, rounded up) — `repl_eval` and MCP calls spell their budget in ms, and leaving that spelling out let a deliberately long call die at the default watchdog. The real tool still owns validation/clamping; this only prevents the outer watchdog from preempting a longer requested budget.
Floor for an eval that reaches the NETWORK through the HTTP shims (requests,
httpx, urllib3, urlopen).
A request's budget is invisible to a text scan in the way that matters: the
shim's own per-call default is 30s, the block usually loops over N hosts, and
the helper doing the fetching is typically defined in an EARLIER block. So a
perfectly ordinary crawl raced the 120s watchdog, and the watchdog won — a
bare Timeout (120s) for work that was progressing normally, which is the
defect DEFAULT_SHELL_TIMEOUT_SECS describes, spelled in sockets.
Unlike shell's, this floor does NOT drop when the block spells a literal
timeout=: that number bounds ONE request, never the loop around it.
Floor for an eval that reaches the NETWORK through the HTTP shims (`requests`, `httpx`, `urllib3`, `urlopen`). A request's budget is invisible to a text scan in the way that matters: the shim's own per-call default is 30s, the block usually loops over N hosts, and the helper doing the fetching is typically defined in an EARLIER block. So a perfectly ordinary crawl raced the 120s watchdog, and the watchdog won — a bare `Timeout (120s)` for work that was progressing normally, which is the defect `DEFAULT_SHELL_TIMEOUT_SECS` describes, spelled in sockets. Unlike shell's, this floor does NOT drop when the block spells a literal `timeout=`: that number bounds ONE request, never the loop around it.
(implicit-call-budget-secs code)Seconds an eval is entitled to purely from WHICH bounded calls it makes, when none of them names a number. A timeout that is a variable, an expression, or simply the tool's default is invisible to a text scan, so without this floor the watchdog silently preempts a call that owns a longer budget and answers timeouts itself.
A shell call the scan cannot read may legally own the FULL cap — a ten-minute
wait — so that is its floor. When the block DOES spell a second budget out the
scan already reads it, and the floor drops back to shell's default so a second,
unannotated call in the same block still cannot race the watchdog.
An HTTP call keeps its floor either way: a literal timeout= bounds ONE
request, and the block is almost always a LOOP of them.
Seconds an eval is entitled to purely from WHICH bounded calls it makes, when none of them names a number. A timeout that is a variable, an expression, or simply the tool's default is invisible to a text scan, so without this floor the watchdog silently preempts a call that owns a longer budget and answers timeouts itself. A `shell` call the scan cannot read may legally own the FULL cap — a ten-minute `wait` — so that is its floor. When the block DOES spell a second budget out the scan already reads it, and the floor drops back to shell's default so a second, unannotated call in the same block still cannot race the watchdog. An HTTP call keeps its floor either way: a literal `timeout=` bounds ONE request, and the block is almost always a LOOP of them.
Hard ceiling for :eval-timeout-ms.
Hard ceiling for :eval-timeout-ms.
Hard ceiling foundation.shell clamps EVERY run / wait budget to: ten
minutes. Declared here so the widener below can floor the eval watchdog above
the LONGEST budget a shell call may legally own, not merely above the default.
A budget that is a variable or an expression is invisible to a text scan, so
flooring at the 120s default let the watchdog preempt a legal ten-minute wait
with a bare Timeout (120s) instead of shell's own envelope — the same defect
DEFAULT_SHELL_TIMEOUT_SECS describes, one spelling further out.
Hard ceiling `foundation.shell` clamps EVERY `run` / `wait` budget to: ten minutes. Declared here so the widener below can floor the eval watchdog above the LONGEST budget a shell call may legally own, not merely above the default. A budget that is a variable or an expression is invisible to a text scan, so flooring at the 120s default let the watchdog preempt a legal ten-minute wait with a bare `Timeout (120s)` instead of shell's own envelope — the same defect `DEFAULT_SHELL_TIMEOUT_SECS` describes, one spelling further out.
(native-tool-timeout-ms input)Return the outer wall-clock deadline for a native handler. Always sits a short
grace period ABOVE the tool's own budget — an explicit timeout_ms, otherwise
the 30-second fallback — so a tool whose internal timeout equals the fallback
(e.g. repl_eval's 30s default) still gets to produce its STRUCTURED timeout
result before the wall fires. Capped at MAX_EVAL_TIMEOUT_MS.
Return the outer wall-clock deadline for a native handler. Always sits a short grace period ABOVE the tool's own budget — an explicit `timeout_ms`, otherwise the 30-second fallback — so a tool whose internal timeout equals the fallback (e.g. repl_eval's 30s default) still gets to produce its STRUCTURED timeout result before the wall fires. Capped at `MAX_EVAL_TIMEOUT_MS`.
Wall-clock fallback for Clojure-native tool handlers when the caller does not
request a timeout_ms — 30 seconds. Calls expected to take longer must
explicitly request a timeout or use a background workflow. Slow synchronous
SETUP (e.g. a cold project-REPL boot) runs OUTSIDE this wall via the loop's
:vis/outside-tool-wall hook, so it never bills against this budget.
Wall-clock fallback for Clojure-native tool handlers when the caller does not request a `timeout_ms` — 30 seconds. Calls expected to take longer must explicitly request a timeout or use a background workflow. Slow synchronous SETUP (e.g. a cold project-REPL boot) runs OUTSIDE this wall via the loop's `:vis/outside-tool-wall` hook, so it never bills against this budget.
(park-blocking-wall thunk)Run thunk with every enclosing timeout wall parked. With no wall installed
(plain JVM call, tests) this is just (thunk).
Run `thunk` with every enclosing timeout wall parked. With no wall installed (plain JVM call, tests) this is just `(thunk)`.
(parkable-wall start timeout-ms)One MOVABLE wall clock for a bounded execution that began at start with
timeout-ms of budget.
Returns {:deadline <atom epoch-ms> :park (fn [thunk])}.
park is RE-ENTRANT: nested parks each push the deadline out to
MAX_EVAL_TIMEOUT_MS and only the OUTERMOST exit restores the base
budget, so an inner park returning cannot collapse the clock while an outer
park is still live. It also COMPOSES with the park inherited from
*blocking-wall-park*, so parking an inner wall parks every enclosing one
too — a native tool that asks the operator a question must not be killed by
the Python eval watchdog wrapped around it.
One MOVABLE wall clock for a bounded execution that began at `start` with
`timeout-ms` of budget.
Returns `{:deadline <atom epoch-ms> :park (fn [thunk])}`.
`park` is RE-ENTRANT: nested parks each push the deadline out to
[[MAX_EVAL_TIMEOUT_MS]] and only the OUTERMOST exit restores the base
budget, so an inner park returning cannot collapse the clock while an outer
park is still live. It also COMPOSES with the park inherited from
[[*blocking-wall-park*]], so parking an inner wall parks every enclosing one
too — a native tool that asks the operator a question must not be killed by
the Python eval watchdog wrapped around it.Floor for an eval that calls run_tests. A test run carries its OWN multi-
minute budget (the Clojure pack's 290s nREPL deadline) and answers a timeout
with a STRUCTURED test result; a direct tool call parks the native wall for
exactly that reason. Called from python_execution it must not die earlier at
the generic 120s watchdog and lose the run's result.
Floor for an eval that calls `run_tests`. A test run carries its OWN multi- minute budget (the Clojure pack's 290s nREPL deadline) and answers a timeout with a STRUCTURED test result; a direct tool call parks the native wall for exactly that reason. Called from `python_execution` it must not die earlier at the generic 120s watchdog and lose the run's result.
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 |