Configuration

This page is the authoritative inventory of Jaiph configuration keys: every key, its value type, default, environment-variable equivalent, and precedence. For environment-variable details (defaults, scopes) see Environment variables. For the CLI flags that front-end the same knobs see CLI.

Configuration sources, in priority order:

1. Environment variables — locked once observed by the host CLI; see Locked variables.
2. Def-level config { … } — applies for the duration of that def.
3. Module-level config { … } — applies to all defs in that file unless overridden.
4. Built-in defaults — lowest priority.

Config block syntax

Value syntax

Global rule: Every Jaiph string position accepts three equivalent forms:

All three resolve identically at runtime. The only interpolation Jaiph understands is ${name} / ${name.field} — shell expansion forms (${var:-default}, ${var//…}, ${#var}) are not. Written as a bare config value they fail with E_PARSE (config value must be a quoted string, bare identifier, or true/false); written inside a double-quoted config value they are stored as literal text and never expanded.

String config values support the same ${identifier} interpolation as orchestration strings (log, prompt, return, etc.). A bare identifier or bare ${name} on the RHS is sugar for a single ${identifier} reference (for example agent.model = model, agent.model = ${model}, and agent.model = "${model}" are all equivalent).

Interpolation scope:

Interpolation runs when the config scope is applied (def entry for def-level keys; CLI startup for module-level keys). Environment variables still win over in-file config when locked.

Agent keys

Run keys

Module keys

Informational metadata only; does not affect execution. Allowed in module-level config only — any module.* key inside a def-level config is E_PARSE.

Script env keys (use + --env)

The trusted_envs config key is removed (E_PARSE unknown config key). Scripts are sterile by default: a script subprocess receives only process mechanics, the JAIPH_* script contract keys, and the host keys its own declaration requests with a use clause — and a use key crosses only when the operator granted it with --env KEY[=VALUE]:

script release use GITHUB_TOKEN NPM_TOKEN = 'gh release create …'

jaiph run --env GITHUB_TOKEN --env NPM_TOKEN publish.jh

The use request lives on a script declaration (named script, export script, or import script … as alias use KEY) or on a named prompt definition (prompt analyze(log) use GITHUB_TOKEN = …) — never on defs, call or prompt sites, or anonymous prompt steps. Anonymous prompt subprocesses keep the fail-closed scrubPromptEnv allowlist and never receive --env secrets in their child env; a named prompt’s granted use keys are injected into its agent subprocess on top of that scrub. That is spawn-env, not a sandbox — see Why Jaiph. Recipe: Pass a host key to a script. Also Language — Subprocess environment and Environment variables.

Precedence

Agent and run keys

Scoping across nested calls

After any nested call returns, the caller’s scope is restored exactly as before.

Locked variables

When the host CLI builds the runner environment, any of these variables already present in process.env gets a matching ${NAME}_LOCKED=1 flag set on the child env. The runtime refuses to overwrite a locked value from later metadata merges.

Locked names: JAIPH_AGENT_BACKEND, JAIPH_AGENT_MODEL, JAIPH_AGENT_COMMAND, JAIPH_AGENT_TRUSTED_WORKSPACE, JAIPH_AGENT_CURSOR_FLAGS, JAIPH_AGENT_CLAUDE_FLAGS, JAIPH_RUNS_DIR, JAIPH_DEBUG.

Import trust boundary

agent.command and agent.backend are execution-binary keys — they determine which process runs prompt steps. To prevent a third-party .jh library from silently redirecting execution to a different binary, these two keys may only be set from the entry module’s config {} block (module-level or def-level). Imported modules that declare agent.command or agent.backend in their config {} are silently ignored for these keys.

agent.trusted_workspace, agent.cursor_flags, agent.claude_flags, and run.logs_dir carry the same entry-module-only restriction. They shape the agent trust path (passed to Cursor as --trust), the agent argv (cursor_flags / claude_flags are appended to the invocation), and the run directory — so an imported module setting them could redirect trust, alter the agent command line, or move run logs for its own prompt steps. Imported modules that declare these keys in their config {} are silently ignored for them.

Host secrets carry a related boundary: a script — imported or local — receives a host key only through its own use clause and an explicit operator --env grant, so a library cannot pull host secrets into its steps without the operator naming each key on the command line (see Script env keys).

The remaining config keys (agent.model, run.debug) are not restricted and follow the normal scoping rules for cross-module calls.

Advanced unlock (use with caution): to allow an imported module to override an entry-module-only key, set the matching environment variable before the run:

The matching ${NAME}_LOCKED=1 flag still applies on top — a locked key cannot be changed regardless of the source.

Config-to-env mapping

Variables with no in-file equivalent: JAIPH_CODEX_API_URL (codex endpoint), JAIPH_PROMPT_RETRY / JAIPH_PROMPT_RETRY_DELAYS (prompt-retry schedule), OPENAI_API_KEY (codex credential). Full inventory in Environment variables.

Backend selection

Backend-specific flags come from agent.cursor_flags / agent.claude_flags (or the matching env vars). There is no per-prompt backend override.

Credential pre-flight

Before jaiph run spawns the runner, the host CLI runs a credential pre-flight (src/cli/run/preflight-credentials.ts). It collects the distinct backend(s) declared in the entry file’s module-level config block and each def-level block, plus the effective default (JAIPH_AGENT_BACKEND env, or cursor when unset). Deeper per-import overrides resolved at runtime are not followed.

Hard errors exit non-zero with no runner launched. Warnings go to stderr and the run proceeds. Skip cases: entry file declares no explicit backend and uses no prompt step → no pre-flight; jaiph run --raw → no pre-flight.

Every error and warning names the backend, the model when agent.model is set, the entry .jh file, the config scope, and the concrete remedy. The config scope is one of module config, def <name>, JAIPH_AGENT_BACKEND env, or default.

Model resolution

Resolution order for a prompt step:

For the Claude backend, when agent.model is set and agent.claude_flags does not already contain --model, Jaiph passes --model <value> to the Claude CLI automatically. When agent.claude_flags already contains its own --model, Jaiph does not add a second one, so the model in agent.claude_flags is the one the Claude CLI receives. When both are set this way, the PROMPT_START / PROMPT_END records still carry model_reason: explicit with the agent.model value, even though the Claude CLI ran with the model from agent.claude_flags.

PROMPT_START / PROMPT_END records in run_summary.jsonl carry model (resolved string, or null when the backend auto-selects) and model_reason (explicit, flags, backend-default, or none for a custom agent command, which has no model concept).

Prompt retry on transport failure

NodeWorkflowRuntime retries transport-failed prompt invocations on an escalating backoff schedule before propagating the failure to any enclosing recover / catch.

Total worst-case wall-clock: ~2h41m.

Only transport failures are retried (non-zero exit from cursor/claude, codex HTTP error, spawn failure). Deterministic post-processing failures — invalid JSON, schema validation — fail on the first attempt and return { ok: false }.

Each attempt emits its own PROMPT_START / PROMPT_END and STEP_START / STEP_END. Each failure logs a LOGERR line; the final termination logs another. The captured value reflects the successful attempt.

jaiph test defaults JAIPH_PROMPT_RETRY=0. Backoff sleep is interruptible: run abort, SIGINT, or SIGTERM cancels the pending wait without further backend calls.

Prompt watchdog timeouts

The retry backoff above handles a backend that fails. A separate set of watchdogs handles a backend that hangs — it never exits, so without them the runtime would block on the subprocess indefinitely (no commit, no queue progress, no retry). Each prompt invocation installs three independent layers over the spawned backend process:

Set any variable to 0 to disable that layer. The idle timer resets on every chunk of backend output, so a slow-but-active run is bounded only by the absolute cap.

The completion-grace layer specifically addresses the known claude -p failure mode where the CLI streams its final answer (and the terminal result event) but the process never exits — often because a descendant it spawned is still holding the output pipe open. When a watchdog fires it terminates the backend’s whole process tree (via killProcessTree; see Architecture) with SIGTERM, escalating to SIGKILL after 5s, and tears down the runtime’s handles on the child’s stdio so a lingering descendant cannot keep the run alive. On Windows the tree is force-killed with taskkill /T on the first signal, so the SIGKILL escalation is a no-op.

Overall run timeout and step cap

The prompt watchdogs above bound a single backend call. Jaiph also has two controls that bound the whole run, and both are off by default, so existing runs behave as before.

JAIPH_RUN_TIMEOUT sets a parent-enforced wall-clock cap, in seconds, for a run. Without this cap, the only automatic stop is a manual Ctrl-C, because the host spawn installs only SIGINT and SIGTERM handlers and the prompt watchdogs cover a single backend call. When the cap is reached, the parent terminates the run child’s whole process group with SIGTERM and escalates to SIGKILL after a short grace period (via killProcessTree; see Architecture), so the run stops without a manual Ctrl-C, and the failure footer shows E_RUN_TIMEOUT. Set it to 0, leave it empty, or give it an invalid value to disable it, which restores the earlier behaviour where only a manual SIGINT or SIGTERM stops a run.

JAIPH_MAX_STEPS sets an optional max-step circuit breaker in the runtime. When you set it to a positive integer, the runtime counts every executed step across the whole run, and it counts loop iterations and nested or recursive calls but skips trivia. Once the count goes past the cap, the runtime logs E_MAX_STEPS, aborts the run, and returns a failure, so a runaway program stops on its own without a manual signal. Set it to 0, leave it empty, or give it an invalid value to disable the breaker.

Leaf step idle output

The prompt watchdogs bound a single backend call, and the run timeout and step cap bound the whole run. A separate watchdog bounds one leaf step by how long it stays silent. A leaf step is a script step or a prompt step, and the watchdog watches its stdout and stderr. It catches a script step that the prompt watchdogs never see, such as an overnight npm run test:ci that stops producing output but never exits. The runtime checks for silence on a poll interval set by JAIPH_STEP_IDLE_WARN_CHECK_MS (default 5000 milliseconds, floor 250).

JAIPH_STEP_IDLE_WARN_SEC (default 180 seconds; 0 disables) sets how long a leaf step can go without any stdout or stderr before the runtime emits a LOGWARN. The warning repeats on the same cadence while the step stays silent, so at 180 seconds, then 360, then 540, and so on. Any new output resets the clock. The warning does not fail the step, and it only surfaces a stalled backend or a long-running command.

JAIPH_STEP_IDLE_KILL_SEC (default 3600 seconds, one hour; 0 disables) sets a hard limit for a script step. When a script step goes that long without any stdout or stderr, the runtime emits a LOGERR naming the step and how long it was silent, terminates the step’s subprocess with SIGTERM and then SIGKILL (via killProcessTreeEscalating; see Architecture), and fails the step. Any new output resets this clock too. The warn cadence and the kill limit run off the same idle clock but fire independently. The kill applies to script steps only, because a prompt step’s backend is already bounded by the prompt watchdogs above, so a prompt step still gets the idle warnings but is never killed by this limit.

Custom agent commands

agent.command is consumed by the cursor backend only. For claude and codex, Jaiph always invokes the Claude CLI or the codex HTTP path, regardless of agent.command.

When agent.backend = "cursor" and agent.command’s basename is anything other than cursor-agent, Jaiph treats it as a custom agent command:

Custom commands still participate in PROMPT_START / PROMPT_END, write artifacts, and apply returns schema validation when configured.

Test runner

jaiph test does not call resolveRuntimeEnv. The test runner spreads process.env, then sets JAIPH_TEST_MODE, JAIPH_WORKSPACE, JAIPH_RUNS_DIR (ephemeral), JAIPH_SCRIPTS, and mock fields (JAIPH_MOCK_RESPONSES_JSON, JAIPH_MOCK_PROMPT_ARMS_JSON). JAIPH_*_LOCKED flags are not set unless inherited from the parent env. NodeWorkflowRuntime still applies in-file config via applyMetadataScope with the same lock rules.

Inspecting effective config at runtime

Agent and run settings are visible inside defs and scripts as JAIPH_* environment variables. In orchestration strings, ${IDENT} resolves against def bindings first, then against the process environment.

Created by jaiph init

jaiph init creates .jaiph/bootstrap.jh, .jaiph/SKILL.md, and .jaiph/.gitignore. There is no separate config file — config { … } blocks live in program source. See CLI — jaiph init.

Related

• Environment variables — every variable Jaiph reads.
• CLI — flags that front-end these config knobs.
• Deploy jaiph — wrap jaiph in an image or pod for outer isolation.
• Grammar — config block syntax in the formal grammar.