Skip to content

Latest commit

 

History

History
56 lines (35 loc) · 6.92 KB

why-jaiph.md

File metadata and controls

56 lines (35 loc) · 6.92 KB
title Why Jaiph
permalink /why-jaiph
diataxis explanation

Why Jaiph

Jaiph is a small language and a runtime for jobs that mix AI agents with ordinary scripts. This page explains the problem Jaiph solves, the three parts a program is built from, and the limits Jaiph keeps on purpose. Architecture describes how Jaiph is built, and Language and Grammar describe the syntax.

The problem

When you give an agent a job with several steps, the agent decides the steps again on every run. You can't review the steps before the run or test them, and two runs of the same job can do different things. Jaiph moves the steps into a file. Scripts do the work that has one right answer, and the agent is called only for the steps that need judgment.

A job like that often has to do four different kinds of work in the same flow:

  • Deterministic checks — does this file exist, does the build pass, does the schema match.
  • Real shell — running a build tool, calling a CLI, changing files.
  • AI steps that vary from run to run — asking an agent to summarize a diff, write a fix, or classify a finding.
  • Keeping secrets out of child env and the journal — a script token is not inherited into every subprocess, and credential-shaped values are redacted from the run log. That is not a process sandbox.

You can wire these together in any general-purpose language, but you pay for it in extra code. For each tool you write the argument handling, and for each agent call you write the structured-output handling. Every time, you also decide how to capture stdout, where to put logs, when to retry on failure, and how to fail clearly when the output does not match the structure you expected.

Jaiph makes orchestration the job of the language itself. Over time, people add the same structure to a bash script by hand, so that every step gets captured, every prompt is logged, and every failure ends with a footer that lists the paths to the artifact files. In Jaiph that structure is built in, and the author does not have to write it.

The building blocks

Jaiph is built from three parts, and a program is what you get when you combine them. Two of them are top-level declarations, def and script. The third, prompt, is a step you write inside a def.

  • def — the interpreted procedure. It combines scripts, prompts, other defs, async to overlap work, channels to pass messages, if / match / for for control flow, and recover / catch to handle failures. jaiph run enters at export def main.
  • script — a named block of code you can run (shell, Python, Node, or anything with a shebang line). A def body can also run a 'body'(args) step. Shell you want to reuse belongs in a script. A script does not inherit module-level const bindings, so pass any values it needs as positional arguments.
  • prompt — a task you hand to an AI agent. Jaiph fills in any variables in the body, captures the agent's stdout, and, when you declare a shape with returns "{ field: type }", parses that output and checks it against the shape.

Jaiph records what every step does. Each run leaves files under .jaiph/runs/, which include the captured stdout and stderr of each step and a run_summary.jsonl file that lists the events of the run in order. You can run a program written this way again, read what each step did, and test it. The result of a call stays on disk until a step needs it as text, as Value types explains.

Design commitments

The design makes three commitments, and each one settles many smaller questions:

  1. Strict structure around AI steps. An agent's response can vary from run to run, so the language gives you the surrounding pieces that do not. In a def you can check conditions with scripts before and after a prompt. With prompt … returns "{ … }" you require the agent's output to match a JSON shape, and the step fails if it does not. With recover a failed call runs again after a repair body runs, up to run.recover_limit times, which helps when an agent's output needs a fix before the pipeline can go on.

  2. Spawn-env and journal guardrails, not a sandbox. Jaiph shapes each child env so a host key reaches a script or named-prompt agent only when its declaration uses the key and the operator grants it with --env; credential-shaped values are redacted from the run journal. The grant mechanics — the sterile base set, the prompt scrub, and the reserved names — live in Environment variables — Script subprocess environment, with the step-by-step recipe in Pass a host key to a script. These rules stop accidental inherit and tokens leaking into the journal; they do not isolate the agent. This is not a sandbox: a cursor or claude prompt that can run tools runs as the same user as jaiph and can still reach a key on disk or in another process regardless of child env, while the codex backend talks to an HTTP endpoint and runs no local program. Isolation of the whole run is an outer concern — a container, pod, or a dedicated user you create, not an install-time account. See Deploy jaiph.

  3. No vendor lock-in. You choose a backend with agent.backend, which can be cursor, claude, or codex. The cursor and claude backends call their own command-line tools, and the codex backend calls an HTTP chat-completions endpoint. On the cursor backend, agent.command can name any program that reads stdin and writes stdout, so a wrapper around a local model or a self-hosted endpoint works without implementing Jaiph's stream-json format. A program author does not need a proprietary agent protocol.

What Jaiph is not

It also helps to say what Jaiph is not:

  • Not a general-purpose programming language. A def runs steps in order and has only the control flow it needs, which is if, match, for, recover, and catch. Anything more complex belongs in a script.
  • Not a distributed system. Channels pass messages between defs in the same run, in one process. See Inbox & Dispatch. There is no broker, no cross-process routing, and no retry queue.
  • Not a process sandbox. Sterile script env and the prompt scrub shape child env. They do not confine a tool-using agent. Isolation is Deploy jaiph.
  • Not a replacement for CI. Jaiph runs the same way on your machine and inside a CI container. It does not provide the test matrix, artifact publishing, or environment management that CI platforms do.
  • Not a prompt framework. There is no chain abstraction, no agent class hierarchy, and no built-in memory store. A prompt step calls a backend, and if you want to chain calls, you compose steps yourself.

Jaiph stays small on purpose. A .jh file behaves the way it reads, and the structure around it, which includes logging, testing, and formatting, is the runtime's job rather than the program author's.