Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,6 +27,11 @@ Same exit-code convention. JSON shape: `{"tool","command","file","ok",
notices like `[SEAL]`); on runtime error it holds lines revealed *before*
the error, and `error` carries `line`/`col`/`code`/`message`. `--sandbox`
confines execution; `--json` composes with plain `run`/`check` too.
A sandboxed run denies every file read until the invoker grants one:
`run --sandbox --allow-read DIR scroll.god` (repeatable). The scroll's
permission manifest still narrows the grant, so the run may read only
what both the host and the scroll allow. See
`docs/accountable-agent.md` for the worked demo.

## Share scrolls

Expand Down
1 change: 1 addition & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ All notable changes to the God Code engine are recorded here, that the generatio
## Unreleased

### Added
- **🕊️ The accountable agent.** The first flagship demo, and the small engine change it needed: a sandboxed run denied every file read until now, so an agent that reads one folder could not run sandboxed at all. New `godcode run --sandbox --allow-read DIR scroll.god` (repeatable) grants the host reads under the named folders only, and the scroll's permission manifest still narrows the grant, so the run may read only what both the host and the scroll allow. Using `--allow-read` without `--sandbox` is a usage error, since a plain run is unbound by the host. New example `examples/accountable_agent.god` with its entrusted folder `examples/accountable_agent_data`: it declares one read permission, fingerprints every file in the folder, and reveals the count, the total characters, and a fingerprint of the whole report, deterministically, so anyone can re-run it and compare. Documented in `docs/accountable-agent.md`, repo `AGENTS.md`, and `docs/sandbox.md`, with the worked checks (with the grant it runs, without it refused, reaching past the folder refused) kept honest by 8 new tests in `tests/test_accountable_agent.py`.
- **🕊️ The MCP server.** `godcode mcp` serves God Code to any MCP client (Claude Code, Cursor, Codex, and the rest) over stdio, one JSON-RPC message per line, with protocol version negotiation and silence for notifications. It carries the eleven agent tools (`check`, `run`, `consult`, `intent`, `anchor_verify`, `ledger_verify`, `permissions`, `explain`, `get_schema`, plus new `format` and `list_scrolls`), and it holds one rule the plain bridge does not: runs through it are always sandboxed, so a client asking for an unsandboxed run still gets a sandboxed one, and the result says so. Tool work runs muted, so stdout carries exactly one protocol message per line and an engine notice can never break a client's parsing; the sandboxed tool path is muted the same way, which also heals the plain bridge. Documented in `docs/mcp.md`, `docs/agentics.md`, and repo `AGENTS.md`. New tests in `tests/test_mcp.py`; the tool-count tests now expect eleven tools.
- **🕊️ The October 2026 machine interfaces.** God Code's `--json` shapes are frozen under dated schemas, so an agent can parse every output without guessing. New `godcode explain scroll.god [--json]`: a static reading of any scroll that runs nothing, reporting the tongue, the rites and their declared intents, the declared names, the reveals, the seals (including `ANCHOR` seals on a chain), the summoned verbs, the `CONSULT` questions, the imports, and the permission manifest, in warm plain words for humans and one JSON document for agents. New `godcode ledger verify --json`: the covenant chain and anchor chain attestation as one JSON document. New `godcode schema [name]`: list or print the four dated schemas (`check`, `run`, `explain`, `ledger-verify`), shipped inside the installed package and resolvable through `importlib.resources`. The agent bridge gains two tools, `explain` and `get_schema` (nine tools in all). The full contract, exit codes, and the stability promise (additive fields may appear, required fields never change meaning, breaking changes ship under a new dated schema) live in `docs/machine-interfaces.md`. New tests in `tests/test_machine_interfaces.py`; repo `AGENTS.md` documents the read-before-you-run workflow.
- **🕊️ God Code speaks Igbo and Nigerian Pidgin.** The third and fourth tongues. A scroll that opens with `# tongue: ig` writes its keywords in Igbo (BIDO OKIKE for BEGIN CREATION, GOSI for REVEAL, Ọ BỤRỤ and MGBE AHỤ for IF and THEN, NWAA and JIDE for TRY and CATCH, and the rest), and one that opens with `# tongue: pg` (or the standard code `pcm`) writes them in Nigerian Pidgin (OYA KREASHON, TALK and BE for DECLARE and AS, SHOW for REVEAL, DEN for THEN, HOLD for CATCH, COMOT for ASCEND). Igbo words work with or without their dotted vowels (`DỊKA` and `DIKA` both speak), and Pidgin keeps the words it shares with English (IF, TRY, AND, RETURN). Two-word phrases now join whenever both words sit side by side on one line, even when one is an English keyword or a plain name, so `FINISH IF` closes an IF in Pidgin and `Ọ BỤRỤ` opens one in Igbo; Setswana and isiZulu closers behave exactly as before. The mappings live in `godcode/tongues.py`; the playground's lite engine knows both tongues (Igbo in its undotted spelling), the language server offers their completions, hover docs, and block snippets (hover now reads dotted words), and the VS Code extension paints their keywords and ships four starter snippets (`ndewo`, `oburu`, `howfar`, `ifden`). Documented in `docs/TONGUES.md` (both word tables and honest first-edition notes), `docs/LANGUAGE_REFERENCE.md` §1, repo `AGENTS.md`, the site landing card, and two new lessons on the learn page. New examples `examples/first_blessing_ig.god` and `examples/first_blessing_pg.god`, also offered as playground samples. 25 new tests in `tests/test_tongues_igbo_pidgin.py`; the VS Code snippet count in `tests/test_lsp_tongues.py` rises from 27 to 31
Expand Down
94 changes: 94 additions & 0 deletions docs/accountable-agent.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,94 @@
# The accountable agent

The first flagship demo: an agent given exactly one folder, and
nothing else. It is the wedge in miniature. The agent states its
intent, receives narrow permission, runs safely, and leaves a report
anyone can re-run and check.

## What it does

`examples/accountable_agent.god` reads every file in
`examples/accountable_agent_data`, fingerprints each file with
`SHA256`, and reveals one line per file, the file count, the total
characters, and a fingerprint of the whole report. Run it twice and
every revealed line matches, because the scroll reads no clock, no
network, and no changing value.

## The two locks

Accountability here is two locks that must both open, not one:

1. **The scroll's permission manifest.** The scroll declares a single
power at the top:
`DECLARE PERMISSION TO READ "accountable_agent_data"`. The path is
relative to the scroll, so it means the folder beside the scroll.
Anything the scroll did not declare is refused, even on a plain
run where the host is open.
2. **The host grant.** A sandboxed run denies every file read until
the invoker grants one. `--allow-read` names the folder the host
allows, and it may be repeated for more than one folder. The
scroll cannot widen its own cage: the effective read set is the
host grant intersected with the manifest.

Read what a scroll may touch before running it. It runs nothing:

```bash
godcode permissions examples/accountable_agent.god
```

Run the demo from the repo root, sandboxed, with exactly the one
grant:

```bash
godcode run --sandbox --allow-read examples/accountable_agent_data examples/accountable_agent.god
```

## The three checks

Each check is kept honest by a test in
`tests/test_accountable_agent.py`:

- **With the grant, it runs.** The revealed report fingerprint is
recomputed from the files in the test, not copied from a past run.
- **Without the grant, it is refused.** The same sandboxed run with
no `--allow-read` exits nonzero and says the power is withheld.
- **Reaching past the folder is refused.** A scroll that keeps the
same manifest but points at another folder is stopped, under the
sandbox by the host grant and on a plain run by the manifest.

`--allow-read` without `--sandbox` is a usage error: a plain run is
unbound by the host, so a host grant there would mean nothing, and
the manifest is already doing the narrowing.

## The Spirit's counsel

The demo declares its intent on the `survey` rite. At invocation the
Spirit discerns the intent from what the rite does ("Controlled data
access") and counsels when it drifts from the declared words. That
counsel is printed, and it never fails the run: drift is advice, not
a verdict. The `--json` report carries the discernment in its
`intents` array, beside the `permissions` block, so an agent host can
read both without parsing prose.

## What this does not prove

- The sandbox is in-process, not operating-system isolation. It is a
cooperative audit of the tree-walking interpreter. A hostile
program that escapes the interpreter is not contained by it. See
`docs/sandbox.md` for the honest limits.
- The host grant is the invoker's own act. Granting a folder the
scroll should not see is the invoker's mistake, and no manifest
can repair it, because the manifest can only narrow, never widen.
- The report fingerprint proves the report matches the files as read
at run time. It does not prove the files themselves are true.
- The demo writes nothing and seals nothing, so its proof is the
re-run: same folder, same lines. A sealed replayable receipt is
the next step, and this scroll is built ready for it, with no
changing values in its output.

## What comes next

The other two flagship demos follow the same shape: the covenant
contract (a savings circle expressed as rites with declared intent,
sealed on the ledger) and the first-program path (ten minutes in the
playground, from first line to shared link).
2 changes: 1 addition & 1 deletion docs/sandbox.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ The sandbox withholds this power: the rite ASK would speak with the outer world.

| Field | Default | Meaning |
|---|---|---|
| `allow_read_paths` | `None` (deny all) | Directories the creation may read files from. No file-reading rites exist yet; enforced if any are added. |
| `allow_read_paths` | `None` (deny all) | Directories the creation may read files from. The CLI sets it with `run --sandbox --allow-read DIR` (repeatable); the scroll's permission manifest still narrows the grant. |
| `allow_write` | `False` | Filesystem writes. No file-writing rites exist yet; enforced if any are added. |
| `allow_network` | `False` | Network access. The `HTTP_GET` rite (see §13) is the one network rite: when network is denied it is withheld and raises instead of reaching out. |
| `allow_subprocess` | `False` | Spawning subprocesses. No subprocess rites exist yet; enforced if any are added. |
Expand Down
3 changes: 3 additions & 0 deletions examples/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ runs as-is. Just pick one.

## The four examples

- `examples/accountable_agent.god`. The accountable agent flagship demo: an agent given exactly one folder, `examples/accountable_agent_data`, and nothing else. It declares one read permission, fingerprints every file, and reports the count. Read its manifest first, then run it sandboxed with the one host grant. See `docs/accountable-agent.md`.
`godcode permissions examples/accountable_agent.god`
`godcode run --sandbox --allow-read examples/accountable_agent_data examples/accountable_agent.god`
- `examples/file_reporter.god`. Walks a directory, lists every file it finds, and reveals a total. Shows off the file builtins (LIST_DIR, READ_FILE, FILE_EXISTS).
`godcode run examples/file_reporter.god`
- `examples/sales_summary.god`. Reads a JSON sales ledger from `examples/data/sales.json`, computes totals and averages, and writes a plain-text summary to `examples/data/sales_report.txt`. Shows off JSON parsing, WHILE loops, and file output.
Expand Down
57 changes: 57 additions & 0 deletions examples/accountable_agent.god
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
# The accountable agent.
#
# The first flagship demo: an agent given exactly one folder, and
# nothing else. It declares the one power it may use, reads every file
# in the entrusted folder, fingerprints each one, and reports the
# count. It cannot read, write, or reach anything outside that folder:
# the host grant and the scroll's own permission narrow each other,
# and either one refusing stops the run.
#
# Read what it may touch first (runs nothing):
# godcode permissions examples/accountable_agent.god
#
# Run it from the repo root, sandboxed, with the host granting
# exactly the entrusted folder:
# godcode run --sandbox --allow-read examples/accountable_agent_data examples/accountable_agent.god
#
# Without the host grant the same run is refused. With the grant, a
# scroll that reaches past the folder is refused too. Run it twice
# and every line matches: the report is deterministic, so anyone can
# re-run it and compare, and it is ready to be sealed as a replayable
# receipt. See docs/accountable-agent.md.

BEGIN CREATION
DECLARE PERMISSION TO READ "accountable_agent_data"

DECLARE INTENT "to read only the entrusted folder and report every file in it honestly" ON survey
DEFINE RITE survey(dir)
DECLARE entries AS LIST_DIR(dir)
DECLARE total_files AS 0
DECLARE total_chars AS 0
DECLARE ledger AS ""
DECLARE i AS 0
WHILE i < LEN(entries) DO
DECLARE name AS entries[i]
DECLARE text AS READ_FILE(dir + "/" + name)
DECLARE chars AS LEN(text)
DECLARE fingerprint AS SHA256(text)
REVEAL("{name} holds {chars} characters, fingerprinted {fingerprint}.")
DECLARE ledger AS ledger + name + "=" + fingerprint + ";"
DECLARE total_files AS total_files + 1
DECLARE total_chars AS total_chars + chars
DECLARE i AS i + 1
ENDWHILE
REVEAL("Files counted: {total_files}")
REVEAL("Total characters: {total_chars}")
REVEAL("Report fingerprint: " + SHA256(ledger))
RETURN total_files
END RITE

DECLARE data_dir AS "examples/accountable_agent_data"
IF FILE_EXISTS(data_dir) THEN
DECLARE counted AS survey(data_dir)
REVEAL("Surveyed {counted} files. Nothing outside the entrusted folder was touched.")
ELSE
REVEAL("The entrusted folder is missing. Nothing to report.")
ENDIF
END CREATION
2 changes: 2 additions & 0 deletions examples/accountable_agent_data/field-notes-1.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Morning count: 12 baskets of sorghum, 7 of millet.
The rains held. The storehouse door was latched at dusk.
2 changes: 2 additions & 0 deletions examples/accountable_agent_data/field-notes-2.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Second field: 19 rows weeded, 4 left for tomorrow.
Two hands short. The work continues at first light.
2 changes: 2 additions & 0 deletions examples/accountable_agent_data/market-prices.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
Sorghum 42 per bag. Millet 38 per bag. Maize 35 per bag.
Prices taken at the gate, before noon.
17 changes: 17 additions & 0 deletions godcode/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,12 @@ def cmd_run(args: argparse.Namespace) -> int:
# --- v3: sandbox commands ---
if getattr(args, "sandbox", False):
return _cmd_run_sandboxed(args)
if getattr(args, "allow_read", None):
print("godcode: --allow-read only has meaning with --sandbox. "
"A plain run is unbound by the host, and the scroll's own "
"permission manifest still narrows it.",
file=sys.stderr)
return 2
# --- end v3: sandbox commands ---

# --- v3: agentics --json ---
Expand Down Expand Up @@ -111,9 +117,13 @@ def _cmd_run_sandboxed(args: argparse.Namespace) -> int:
return 1

source_dir = str(Path(args.file).resolve().parent)
read_grants = tuple(
str(Path(path).resolve())
for path in (getattr(args, "allow_read", None) or []))
policy = SandboxPolicy.strict(
source_dir=source_dir,
timeout_seconds=args.sandbox_timeout,
allow_read_paths=read_grants or None,
)
if getattr(args, "json", False):
# Machine-readable report; stdout carries exactly one JSON document.
Expand Down Expand Up @@ -1048,6 +1058,13 @@ def build_parser() -> argparse.ArgumentParser:
metavar="SECS",
help="Wall-clock grant for --sandbox runs "
"(default: 5.0 seconds)")
p_run.add_argument("--allow-read", action="append", default=[],
metavar="DIR",
help="With --sandbox, grant the run host reads "
"under DIR (repeatable). The scroll's "
"permission manifest still narrows the "
"grant: the run may read only what both "
"the host and the scroll allow.")
# --- end v3: sandbox commands ---
# --- v3: agentics --json ---
p_run.add_argument("--json", action="store_true",
Expand Down
8 changes: 8 additions & 0 deletions godcode/sandbox.py
Original file line number Diff line number Diff line change
Expand Up @@ -105,16 +105,24 @@ def strict(
*,
source_dir: str | None = None,
timeout_seconds: float | None = 5.0,
allow_read_paths: tuple[str, ...] | None = None,
) -> "SandboxPolicy":
"""The CLI's strict policy: deny everything, bless the stdlib.

Scroll imports are allowed from the bundled stdlib scrolls and,
when given, the creation's own directory — nothing else.
Filesystem reads stay denied unless the invoker names them:
``allow_read_paths`` grants host reads under those trees only,
and the scroll's own permission manifest still narrows the
grant, so the effective read set is host grant intersect
manifest. The invoker's grant is the invoker's own act, never
the creation's: a scroll cannot widen its own cage.
"""
paths = [_stdlib_scrolls_dir()]
if source_dir:
paths.append(str(source_dir))
return cls(
allow_read_paths=allow_read_paths,
allowed_import_paths=tuple(paths),
timeout_seconds=timeout_seconds,
)
Expand Down
2 changes: 1 addition & 1 deletion site/playground/engine.json

Large diffs are not rendered by default.

Loading