@josfox/jos 4.1.0 → 5.0.0

package/examples/03-flow-gate.jos

@@ -0,0 +1,83 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "flow"
+  },
+  "id": "tour.flow-gate",
+  "meta": {
+    "name": "tour.flow-gate",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Build, wait for a person to approve the build, then publish",
+    "success_criteria": [
+      {
+        "exit": 0
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "build": {
+        "engine": "shell",
+        "run": [
+          "echo",
+          "built"
+        ],
+        "description": "Make the artifact",
+        "intention": {
+          "objective": "Make the artifact",
+          "success_criteria": [
+            {
+              "stdout_contains": "built"
+            }
+          ]
+        }
+      },
+      "publish": {
+        "engine": "shell",
+        "run": [
+          "echo",
+          "published"
+        ],
+        "description": "Runs only after a person approved build",
+        "intention": {
+          "objective": "Publish the approved build",
+          "success_criteria": [
+            {
+              "stdout_contains": "published"
+            }
+          ]
+        }
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "build",
+          "publish"
+        ],
+        "gates": {
+          "build": {
+            "kind": "human"
+          }
+        }
+      },
+      "build-only": {
+        "steps": [
+          "build"
+        ]
+      }
+    }
+  }
+}

package/examples/04-use-template/README.md

@@ -0,0 +1,22 @@
+# 04 · use, a template and a digest
+
+`lib/greeting.jos` is a `template`: its slot `name` is declared as a JSON Schema in `execution.inputs`
+(a string of letters and spaces, 1 to 64 characters). `use.jos` is a flow that uses it twice, `ana` and `leo`, each
+with its own `with`, and pins the template's content in `requires[].digest` (its `art_`).
+
+Run from the folder that holds `04-use-template/`:
+
+| Command | Result |
+|---|---|
+| `jos run 04-use-template/use.jos --library 04-use-template/lib` | `use` resolves `tour.greeting@^1.0.0` in the library folder, the digest matches, both steps run; prints `hello, Leo` (the output of the last step); exit 0 |
+| `jos run 04-use-template/use.jos` | no library given: the pinned artifact is not found, `/requires/0: not satisfied`; nothing runs; exit 5 |
+| `jos run 04-use-template/lib/greeting.jos --with '{"name":"Ana"}'` | the template run directly, instantiated with `--with`; prints `hello, Ana`; exit 0 |
+| `jos run 04-use-template/lib/greeting.jos` | no value for the required slot: `/with: required 'name'`; exit 2 |
+| `jos ids 04-use-template/lib/greeting.jos` | the template's `art_`, the value pinned in `use.jos` |
+
+Change anything in `lib/greeting.jos` (for example `hello` to `hi`) and run `use.jos` with the library again: the
+template's `art_` no longer equals the digest, the run is refused (exit 5). Put the text back, or pin the new
+`art_` (`jos ids`), and it runs.
+
+The same `use` also resolves from a `.jos/` folder above the document (`.jos/templates/`, `.jos/flows/`, …), nearest
+level first, before the library.

package/examples/04-use-template/lib/greeting.jos

@@ -0,0 +1,56 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "template"
+  },
+  "id": "tour.greeting",
+  "meta": {
+    "name": "tour.greeting",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Greet {{ name }} by name",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "{{ name }}"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "inputs": {
+      "type": "object",
+      "required": [
+        "name"
+      ],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 64,
+          "pattern": "^[A-Za-z ]+$"
+        }
+      }
+    },
+    "run": [
+      "echo",
+      "hello, {{ name }}"
+    ],
+    "env": [
+      "PATH"
+    ]
+  }
+}

package/examples/04-use-template/use.jos

@@ -0,0 +1,64 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "flow"
+  },
+  "id": "tour.use-template",
+  "meta": {
+    "name": "tour.use-template",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Greet two people with one template, pinned by its digest",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "Leo"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "ana": {
+        "use": "tour.greeting@^1.0.0",
+        "with": {
+          "name": "Ana"
+        }
+      },
+      "leo": {
+        "use": "tour.greeting@^1.0.0",
+        "with": {
+          "name": "Leo"
+        }
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "ana",
+          "leo"
+        ]
+      }
+    }
+  },
+  "requires": [
+    {
+      "kind": "artifact",
+      "name": "tour.greeting",
+      "version": "^1.0.0",
+      "digest": "art_7ed518676186fe910bc5441ba4ae0126b6ebdeaedec7ef14b7a96422da764210"
+    }
+  ]
+}

package/examples/05-sealed/.jos/manifest.jos

@@ -0,0 +1,53 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "directory"
+  },
+  "id": "tour.sealed",
+  "meta": {
+    "name": "tour.sealed",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Run only while this folder is exactly as it was sealed",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_contains": "sealed folder ran"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "orchestration": {
+    "definitions": {
+      "say": {
+        "engine": "shell",
+        "run": [
+          "echo",
+          "the sealed folder ran"
+        ]
+      }
+    },
+    "flows": {
+      "main": {
+        "steps": [
+          "say"
+        ]
+      }
+    }
+  },
+  "integrity": {
+    "hash": "sha256:621c560a601e2274e1e3009f226e8b3cd3934eff0adb32f62e6b95018ad945eb"
+  }
+}

package/examples/05-sealed/README.md

@@ -0,0 +1,25 @@
+# 05 · a sealed folder
+
+A folder with a `.jos/manifest.jos` is itself a `.jos` document (kind `directory`). This one is sealed: its
+`integrity.hash` is the hash jos-core computes over everything in `.jos/` (the manifest with `integrity.hash`
+blanked, and every other file; `replays/`, `logs/` and `dev/` are not counted). `jos run` recomputes it before
+anything starts.
+
+| Command | Result |
+|---|---|
+| `jos run 05-sealed` | the hash matches: prints `the sealed folder ran`; exit 0. The ledger of the run goes to `05-sealed/.jos/replays/` (not counted in the hash) |
+| `jos ids 05-sealed` | `directory: sha256:… (sealed, matches)` |
+
+To see the seal refuse a change, edit the text `the sealed folder ran` in `.jos/manifest.jos` (or add any file
+under `.jos/`) and run it again:
+
+```
+$ jos run 05-sealed
+…
+✖ Intention NOT met (code 3: blocked) (run_…)
+  integrity: declared hash does not match the directory hash (SPEC-2.0 §9.3)
+```
+
+Exit 3, and nothing ran. `jos ids 05-sealed` now says `sealed, does NOT match`. Undo the edit and it runs again.
+
+What the seal covers is `.jos/` only: this README, next to `.jos/`, is not part of the hash.

package/examples/06-requires.jos

@@ -0,0 +1,42 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.requires",
+  "meta": {
+    "name": "tour.requires",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Charge a card through the payments service",
+    "success_criteria": [
+      {
+        "exit": 0
+      }
+    ]
+  },
+  "guardrails": {
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "echo",
+      "charged"
+    ],
+    "env": [
+      "PATH"
+    ]
+  },
+  "requires": [
+    {
+      "kind": "service",
+      "name": "payments"
+    }
+  ]
+}

package/examples/07-sandbox.jos

@@ -0,0 +1,39 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.sandbox",
+  "meta": {
+    "name": "tour.sandbox",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "Run a step that must not reach the network or files outside its folder",
+    "success_criteria": [
+      {
+        "exit": 0
+      }
+    ]
+  },
+  "guardrails": {
+    "limit": {
+      "seconds": 10,
+      "output_bytes": 65536,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "echo",
+      "confined"
+    ],
+    "env": [
+      "PATH"
+    ]
+  },
+  "security": {
+    "tier": "sandbox"
+  }
+}

package/examples/08-ids-ledger-meter.md

@@ -0,0 +1,26 @@
+# 08 · identities, the ledger and the meter
+
+Every `jos run` (not `--dry-run`) leaves a hash-chained ledger. These commands read what jos-core recorded; none of
+them runs a document or writes anything.
+
+```
+jos ids 01-hello.jos 05-sealed        # art_ (content), ent_ (name), and the directory hash of a folder
+jos run 01-hello.jos                  # note the run id it prints: run_…
+jos runs                              # the runs in ~/.jos/runs, newest first: id, start, code, document, art_
+jos ledger verify run_…               # every entry's hash recomputed, chain continuous, run ended
+jos meter run_…                       # steps, attempts, time; tokens and cost when an engine reported them
+```
+
+What to expect:
+
+| Command | Result |
+|---|---|
+| `jos ids 01-hello.jos` | `artifact: art_40762df5…`: the same value on every machine and in both reference kernels; `entity: ent_…` from `atom:tour.hello` |
+| `jos runs` | `✓ run_…  <start>  code 0 (done)` and, below it, `tour.hello  art_…`; a ledger that does not verify is listed with `⚠` and the reason |
+| `jos ledger verify run_…` | `✓ LEDGER VERIFIED`, with the number of entries and the head hash; exit 0. Change one byte of the run's `ledger.jsonl` and it is `✖ LEDGER DOES NOT VERIFY`, `Reason: hash_mismatch`, exit 1 |
+| `jos meter run_…` | `Code: 0`, `Steps: tour.hello`, `Engines: shell`, `Time: … ms`, `Tokens in: not reported`, `Cost: not reported` (the shell engine reports neither; never shown as 0) |
+
+`jos ledger verify` and `jos meter` also take the path of a `ledger.jsonl` or of a run folder. A run id is looked up
+in `.jos/replays/` of the folders above the current directory (that is where `05-sealed` keeps its runs: run the
+command from inside `05-sealed/`, or pass the path), then in `~/.jos/runs/`. Add `--json` to any of them for the
+machine-readable form.

package/examples/10-ollama.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.ollama",
+  "meta": {
+    "name": "tour.ollama",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 300,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "url=http://localhost:11434\nif ! command -v curl >/dev/null 2>&1; then echo \"curl is not installed: cannot check $url\" >&2; exit 3; fi\nif ! curl -sf --max-time 3 -o /dev/null \"$url/api/tags\"; then\n  echo \"Ollama is not answering on $url: nothing was sent.\" >&2\n  echo \"Start it (ollama serve, or the Ollama app), then run this again.\" >&2\n  exit 3\nfi\ncommand -v ollama >/dev/null 2>&1 || { echo \"Ollama answers on $url but the ollama command is not on PATH\" >&2; exit 4; }\nexec ollama run \"${OLLAMA_MODEL:-llama3.2}\" \"$1\"",
+      "10-ollama",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "HOME",
+      "OLLAMA_MODEL"
+    ]
+  }
+}

package/examples/11-openai.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.openai",
+  "meta": {
+    "name": "tour.openai",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 180,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "if [ -z \"$OPENAI_API_KEY\" ]; then\n  echo \"OPENAI_API_KEY is not set: no request was sent.\" >&2\n  echo \"Store the key once:  jos secrets set OPENAI_API_KEY --stdin\" >&2\n  echo \"Then run:            jos secrets exec --only OPENAI_API_KEY -- jos run 11-openai.jos\" >&2\n  exit 3\nfi\ncommand -v curl >/dev/null 2>&1 || { echo \"curl is not installed\" >&2; exit 4; }\nmodel=\"${OPENAI_MODEL:-gpt-5-mini}\"\nbody=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], input: process.argv[2] }))' \"$model\" \"$1\") || exit 4\nresp=$(printf \"Authorization: Bearer %s\\n\" \"$OPENAI_API_KEY\" | curl -sS --max-time 150 -H @- -H \"Content-Type: application/json\" -d \"$body\" https://api.openai.com/v1/responses) || { echo \"the request failed (curl exit $?)\" >&2; exit 5; }\nprintf %s \"$resp\" | node -e 'let s = \"\";\nprocess.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => {\n  const key = process.env[process.argv[1]] || \"\";\n  const clean = (t) => { let x = String(t); if (key) x = x.split(key).join(\"[key]\"); return x.replace(/(sk-|AIza)[A-Za-z0-9_*-]{6,}/g, \"[key]\"); };\n  let j;\n  try { j = JSON.parse(s); } catch (e) { console.error(\"the API did not answer JSON: \" + clean(s.slice(0, 300))); process.exit(6); }\n  if (j.error) { console.error(\"API error: \" + clean(j.error.message || JSON.stringify(j.error))); process.exit(6); }\n  const text = (j.output || []).flatMap((o) => o.content || []).filter((c) => c.type === \"output_text\").map((c) => c.text).join(\"\");\n  if (!text) { console.error(\"no text in the answer: \" + clean(JSON.stringify(j).slice(0, 300))); process.exit(6); }\n  console.log(text);\n});' OPENAI_API_KEY",
+      "11-openai",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "OPENAI_API_KEY",
+      "OPENAI_MODEL"
+    ]
+  }
+}

package/examples/12-gemini.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.gemini",
+  "meta": {
+    "name": "tour.gemini",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 180,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "if [ -z \"$GEMINI_API_KEY\" ]; then\n  echo \"GEMINI_API_KEY is not set: no request was sent.\" >&2\n  echo \"Store the key once:  jos secrets set GEMINI_API_KEY --stdin\" >&2\n  echo \"Then run:            jos secrets exec --only GEMINI_API_KEY -- jos run 12-gemini.jos\" >&2\n  exit 3\nfi\ncommand -v curl >/dev/null 2>&1 || { echo \"curl is not installed\" >&2; exit 4; }\nmodel=\"${GEMINI_MODEL:-gemini-2.5-flash}\"\nbody=$(node -e 'process.stdout.write(JSON.stringify({ contents: [{ parts: [{ text: process.argv[2] }] }] }))' \"$model\" \"$1\") || exit 4\nresp=$(printf \"x-goog-api-key: %s\\n\" \"$GEMINI_API_KEY\" | curl -sS --max-time 150 -H @- -H \"Content-Type: application/json\" -d \"$body\" \"https://generativelanguage.googleapis.com/v1beta/models/$model:generateContent\") || { echo \"the request failed (curl exit $?)\" >&2; exit 5; }\nprintf %s \"$resp\" | node -e 'let s = \"\";\nprocess.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => {\n  const key = process.env[process.argv[1]] || \"\";\n  const clean = (t) => { let x = String(t); if (key) x = x.split(key).join(\"[key]\"); return x.replace(/(sk-|AIza)[A-Za-z0-9_*-]{6,}/g, \"[key]\"); };\n  let j;\n  try { j = JSON.parse(s); } catch (e) { console.error(\"the API did not answer JSON: \" + clean(s.slice(0, 300))); process.exit(6); }\n  if (j.error) { console.error(\"API error: \" + clean(j.error.message || JSON.stringify(j.error))); process.exit(6); }\n  const text = ((j.candidates || [])[0] || { content: { parts: [] } }).content.parts.map((p) => p.text || \"\").join(\"\");\n  if (!text) { console.error(\"no text in the answer: \" + clean(JSON.stringify(j).slice(0, 300))); process.exit(6); }\n  console.log(text);\n});' GEMINI_API_KEY",
+      "12-gemini",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "GEMINI_API_KEY",
+      "GEMINI_MODEL"
+    ]
+  }
+}

package/examples/13-anthropic.jos

@@ -0,0 +1,47 @@
+{
+  "jos": {
+    "version": "2.0.0",
+    "kind": "atom"
+  },
+  "id": "tour.anthropic",
+  "meta": {
+    "name": "tour.anthropic",
+    "version": "1.0.0"
+  },
+  "intention": {
+    "objective": "In one sentence: what is a declared intention?",
+    "success_criteria": [
+      {
+        "exit": 0
+      },
+      {
+        "stdout_matches": "\\S"
+      }
+    ]
+  },
+  "guardrails": {
+    "avoid": [
+      "rm -rf"
+    ],
+    "limit": {
+      "seconds": 180,
+      "output_bytes": 1048576,
+      "retries": 0
+    }
+  },
+  "execution": {
+    "engine": "shell",
+    "run": [
+      "/bin/sh",
+      "-c",
+      "if [ -z \"$ANTHROPIC_API_KEY\" ]; then\n  echo \"ANTHROPIC_API_KEY is not set: no request was sent.\" >&2\n  echo \"Store the key once:  jos secrets set ANTHROPIC_API_KEY --stdin\" >&2\n  echo \"Then run:            jos secrets exec --only ANTHROPIC_API_KEY -- jos run 13-anthropic.jos\" >&2\n  exit 3\nfi\ncommand -v curl >/dev/null 2>&1 || { echo \"curl is not installed\" >&2; exit 4; }\nmodel=\"${ANTHROPIC_MODEL:-claude-opus-5-5}\"\nbody=$(node -e 'process.stdout.write(JSON.stringify({ model: process.argv[1], max_tokens: 1024, messages: [{ role: \"user\", content: process.argv[2] }] }))' \"$model\" \"$1\") || exit 4\nresp=$(printf \"x-api-key: %s\\n\" \"$ANTHROPIC_API_KEY\" | curl -sS --max-time 150 -H @- -H \"anthropic-version: 2023-06-01\" -H \"Content-Type: application/json\" -d \"$body\" https://api.anthropic.com/v1/messages) || { echo \"the request failed (curl exit $?)\" >&2; exit 5; }\nprintf %s \"$resp\" | node -e 'let s = \"\";\nprocess.stdin.on(\"data\", (d) => { s += d; }).on(\"end\", () => {\n  const key = process.env[process.argv[1]] || \"\";\n  const clean = (t) => { let x = String(t); if (key) x = x.split(key).join(\"[key]\"); return x.replace(/(sk-|AIza)[A-Za-z0-9_*-]{6,}/g, \"[key]\"); };\n  let j;\n  try { j = JSON.parse(s); } catch (e) { console.error(\"the API did not answer JSON: \" + clean(s.slice(0, 300))); process.exit(6); }\n  if (j.error) { console.error(\"API error: \" + clean(j.error.message || JSON.stringify(j.error))); process.exit(6); }\n  const text = (j.content || []).filter((c) => c.type === \"text\").map((c) => c.text).join(\"\");\n  if (!text) { console.error(\"no text in the answer: \" + clean(JSON.stringify(j).slice(0, 300))); process.exit(6); }\n  console.log(text);\n});' ANTHROPIC_API_KEY",
+      "13-anthropic",
+      "In one sentence: what is a declared intention?"
+    ],
+    "env": [
+      "PATH",
+      "ANTHROPIC_API_KEY",
+      "ANTHROPIC_MODEL"
+    ]
+  }
+}