Jaiph

Jaiph is a language and runtime for defining and orchestrating AI agent workflows.

It allows you to combine agentic workflows with strict checks and script calls. It comes with built-in Docker sandboxing for agentic workflows, and a set of tooling to make your development faster and more efficient.

Running a workflow

./path/to/main.jh "first" "second" "third"

Jaiph runs the default workflow in the file and binds invocation arguments to its parameters. Run artifacts and step output go under .jaiph/runs/.

.jaiph/ is the Jaiph working directory in your project—the recommended place for workflow files. Run jaiph init so the project is configured correctly.

Language

Combine prompts with strict checks. Compose rule, script, ensure, and prompt in one executable flow so checks and AI steps stay in the same pipeline. This way you can enforce structure over non-deterministic agent responses. See Grammar and Getting started (jaiph.org/getting-started).

Embed and run scripts in the language of your choice. Define them with fence lang tags providing the runtime: ```node, ```python3, ```ruby, ```pwsh etc.

Async calls. run async wf() returns a Handle<T> that resolves on first read. Capture with const h = run async wf() and read the handle when you need the value. Unresolved handles are implicitly joined before the parent workflow completes. Supports recover and catch composition for async error handling.

Agent inbox pattern (channels). Use inbox channels as a way to pass messages between workflows. Declare channels at top level with channel <name> [-> workflow] — routes are declared inline on the channel, not inside workflow bodies. Send with channel_ref <- ... (channel_ref can be local or imported, e.g. shared.findings). See Inbox & Dispatch.

Failure recovery. ensure … catch and run … catch handle failures inline: when a rule or script fails, the recovery body runs once. For automatic repair-and-retry, use run … recover — a loop that retries the target after each repair attempt (configurable limit, default 10). Both catch and recover work in workflows. See Grammar.

Runtime

Docker sandboxing. Workflows run inside Docker by default for local development, providing filesystem and process isolation for agent and shell actions. Disable with JAIPH_UNSAFE=true. See Sandboxing.

Hooks. Attach shell automation to workflow and step lifecycle events via ~/.jaiph/hooks.json or <project>/.jaiph/hooks.json. See Hooks.

Custom agent backends. Point agent.command to any executable — a shell script, a Python wrapper, or your own CLI tool — and Jaiph will pipe the prompt via stdin and capture raw stdout as the response. No JSON stream protocol required; just read stdin and print your answer.

Artifacts library. Publish files from inside the sandbox to a host-readable location with the built-in jaiphlang/artifacts library (artifacts.save). Works identically in Docker and on the host. See Libraries.

Configuration. Control behavior with config { ... } blocks at the module level or inside individual workflows for per-workflow overrides, plus environment variables (env wins precedence). See Configuration and CLI reference.

Testing Jaiph workflows. Test workflows with executable *.test.jh suites, mocks, and assertions to cover deterministic and agent-assisted paths. See Testing.

Formatting. jaiph format rewrites .jh files to a canonical style — consistent whitespace and indentation. See CLI reference.

Samples

Jaiph source code is built mostly with real Jaiph workflows. The .jaiph/docs_parity.jh workflow runs documentation maintenance checks, changelog updates, and cross-doc consistency guards. The .jaiph/engineer.jh workflow implements a queue-driven engineering loop that picks work, implements changes, verifies CI, and updates queue state.

Jaiph workflows

config { ... }

Optional runtime options (agent backend/flags, logs, runtime, module metadata). Allowed at the top level (module-wide) and inside individual workflows (per-workflow overrides for agent.* and run.* keys only; runtime.* and module.* are module-level only). Environment variables override config values. See Configuration.

import "file.jh" as alias · const name = value / local name = value

Import other modules and define module-scoped variables (prefer const for new code) shared by rules, scripts, and workflows in the same file. Values can be single-line "..." strings, triple-quoted """...""" multiline strings, or bare tokens.

rule name() { ... } · rule name(params) { ... } · workflow name() { ... } · workflow name(params) { ... } · script name = `cmd` · script name = ```[lang] ... ```

rule is for reusable checks (Jaiph structured steps; used with ensure), workflow orchestrates Jaiph steps only, and script holds bash (or any language via a fence lang tag like ```node, ```python3, or a custom shebang) invoked with run. Rules and workflows require parentheses on every definition — even when parameterless (e.g. workflow default() { … }). Named parameters go inside the parentheses; the compiler validates call-site arity when the callee declares params. Any fence tag is valid — it maps directly to #!/usr/bin/env <tag>. Scripts run in full isolation — only positional arguments and essential Jaiph variables (JAIPH_SCRIPTS, JAIPH_WORKSPACE) are inherited; module-scoped variables are not visible. Reuse shell helpers with import script or small named script blocks in the same module. Scripts are emitted as separate executable files under scripts/ (within the run build output tree; see CLI reference).

ensure ref() · ensure ref(args) catch (name) { ... } · run ref() · run ref(args) catch (name) { ... } · run `body`(args)

ensure executes a rule (with optional args); catch handles failure inline (runs once); run calls another workflow or module script (managed step — same value/log contract as ensure). Parentheses are required on all call sites — even when passing zero arguments (e.g. run setup()). Arguments can be quoted strings or bare identifiers: run greet(name) is equivalent to run greet("${name}"). run `body`(args) embeds a one-off shell command directly without a named script definition — supports arguments and capture. Use triple backticks for multiline: run ```...```(args).

prompt "..." · prompt myVar · prompt """ ... """ · const name = prompt "..." returns "{ field: type }"

Sends a prompt to the configured agent. The body can be a single-line string, a bare identifier, or a triple-quoted """ block for multiline text. Triple backticks are reserved for scripts. Optionally validates structured JSON output and exposes captured variables.

const name = … · const name = ensure ref() · const name = run ref()

Bind or capture step values. All captures require the const keyword. All bindings are immutable — a name bound by a parameter, const, capture, or script cannot be rebound in the same scope. For ensure / run to rules and workflows, explicit return "value", return identifier (or return run ref() / return ensure ref()) feeds the variable; for run to a script, capture follows stdout. const RHS has stricter rules (no $(...) — use run to a script). A call-like RHS must use the keyword explicitly — e.g. const x = run helper(arg), not const x = helper(arg) (compile error with a correction hint). See Immutable bindings and Step output contract.

run async ref(args) · const h = run async ref(args)

Run a workflow or script concurrently. Returns a Handle<T> that resolves on first non-passthrough read (interpolation, passing as arg to run, comparison, conditional). Passthrough (capture, re-assignment) does not force resolution. Unresolved handles are implicitly joined at workflow exit. Supports recover (retry loop) and catch (single-shot) composition: run async foo() recover(err) { … }. Workflows only. See Grammar and Spec: Async Handles.

fail "reason" · fail """..."""

fail aborts with stderr + non-zero exit. Use triple quotes for multiline messages.

ensure ref() catch (err) { … } · run ref() catch (err) { … }

Failure recovery: when the target fails, the recovery body runs once (like a catch clause). catch requires explicit bindings in parentheses. Works in both workflows and rules.

run ref() recover (err) { … }

Repair-and-retry loop: when the target fails, the repair body runs and the target is retried automatically. Stops on success or when the retry limit is exhausted (default 10, configurable via run.recover_limit). recover requires explicit bindings. Workflows only. See Language.

match var { "lit" => … ⏎ /re/ => … ⏎ _ => … }

Pattern match on a string value. The subject is a bare identifier (no $ or ${}). Arms are tested top-to-bottom; first match wins. Patterns: string literal (exact), regex, or _ wildcard. Arms are newline-delimited — commas between or after arms are rejected. Usable as a statement, expression (const x = match var { … }), or with return (return match var { … }). Exactly one _ wildcard arm is required. Arm bodies support single-line strings, triple-quoted """…""" multiline strings, fail, run ref(…), and ensure ref(…). These forms execute at runtime: fail aborts the workflow, run/ensure execute the target and capture its return value. The return keyword and inline scripts are forbidden inside arm bodies.

log "message" · log """...""" · logerr "message"

Emit informational or error output to the run tree while keeping workflow execution explicit and auditable. Use triple quotes for multiline messages. Terminal and tree text use echo -e-style backslash escapes; structured LOG / LOGERR payloads keep the raw message string.

channel <name> [-> workflow] · channel_ref <- ...

Declare channels at top level with optional inline routing (channel findings -> analyst) and send messages between workflows. Routes belong on the channel declaration, not inside workflow bodies. channel_ref supports local and imported refs (for example findings, shared.findings). Undefined refs fail validation. See Inbox & Dispatch.

Jaiph tests

test "description" { ... }

Defines a test case; files named *.test.jh execute as test suites. See Testing.

mock prompt "..." · mock prompt { /pattern/ => "response", _ => "default" }

Stub prompt calls with fixed responses or pattern-based dispatch so tests stay deterministic.

mock workflow · mock rule · mock script

Replace workflow, rule, or script implementations in tests for isolation and targeted assertions.

const name = run alias.workflow() · run alias.workflow() · allow_failure

Runs an imported workflow through the test harness with explicit run and optional const capture (same managed semantics as run in .jh files): capture prefers an explicit return from the callee, otherwise combined output with internal event lines stripped. Add allow_failure when the test expects a non-zero exit. See Testing.

expect_equal · expect_contain · expect_not_contain

Core assertion helpers for exact matches and substring checks (snake_case).