Jaiph

Running a workflow

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

Arguments are bound to named parameters declared on the default workflow (e.g. workflow default(task) → ${task}). When you call a workflow, it executes the workflow default entrypoint.

By convention, keep Jaiph workflow files in <project_root>/.jaiph/ so workspace-root detection and agent setup stay predictable. Jaiph stores run artifacts in .jaiph/runs/ (step .out/.err logs plus run_summary.jsonl, an append-only JSONL event stream for reporting). Keep those out of git: jaiph init writes .jaiph/.gitignore (listing runs and tmp) so ephemeral data stays untracked while workflows remain committable. See the CLI reference for event types, field requirements, and correlation rules.

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).

Use Bash (or any language) in scripts. Command pipelines, checks, and background jobs belong in script definitions; workflows and rules call them with run. Use fence lang tags (```node, ```python3, ```ruby, etc.) to select an interpreter without writing a shebang line — any tag is valid, mapping directly to #!/usr/bin/env <tag>. If no tag is present, add a manual #! shebang as the first body line. For trivial one-off commands, use inline scripts: run `echo ok`() — no named block needed.

Async calls. For async managed work, use run async wf() — Jaiph fans out the workflows concurrently and implicitly joins them before the parent workflow completes.

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 … recover and run … recover handle failures inline: when a rule or script fails, the recovery body runs once (like a catch clause). For retries, use explicit recursion. Both forms work in workflows and rules. See Grammar.

Runtime

Reporting server. Run jaiph report --workspace . to open a local read-only dashboard on .jaiph/runs: run history, step tree, log previews, raw .out/.err streaming, and an aggregate view, with live updates while workflows append run_summary.jsonl. See Reporting server.

Docker sandboxing. Enable isolated execution with Docker for stronger containment of agent and shell actions. Configure in config { runtime.* }. 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.

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. Imports, config, and channels are hoisted to the top; all other definitions (const, rules, scripts, workflows, tests) keep their source-file order. Use --check in CI to catch drift without modifying files, and --indent <n> to set spaces per level. Formatting is idempotent; comments, shebangs, and intentional blank lines between steps are preserved. Comments before hoisted constructs move with them. Multiline string and script bodies are emitted verbatim — inner lines are never re-indented. 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). Allowed at the top level (module-wide) and inside individual workflows (per-workflow overrides for agent.* and run.* keys). 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_LIB, JAIPH_SCRIPTS, JAIPH_WORKSPACE) are inherited; module-scoped variables are not visible. Use source "$JAIPH_LIB/…" for shared utilities. Scripts are emitted as separate executable files under scripts/ (within the run build output tree; see CLI reference).

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

ensure executes a rule (with optional args); recover handles failure inline (runs once, like a catch clause); 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. For ensure / run to rules and workflows, explicit return "value" (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 Step output contract.

run async ref(args)

Run a workflow or script concurrently. All async steps are implicitly joined before the workflow completes; failures are aggregated. Workflows only — capture (const x = run async ...) is not supported. See Grammar.

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

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

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

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

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. 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).