# agent-block
Single-purpose agent building block with built-in mesh communication.
## What is agent-block?
A headless agent runtime. Each agent runs as a single process, executes its task, then exits. No rich interactive TUI, no sub-agent orchestration — orchestration belongs to the caller (shell, A2A, CI, etc.).
agent-block handles the infrastructure that individual agents shouldn't have to — mesh connectivity (A2A), MCP server management, LLM API access — so that Lua code focuses purely on domain logic.
Think of it like Envoy for agents: the process itself is simple, but the communication layer is fully capable.
## Design Decisions
- **Single run** — One process, one task, one exit. Orchestration belongs to the caller (shell, A2A, CI, etc.), not inside the agent
- **Headless** — No terminal UI. Agents are composed via A2A/mesh protocols, not interactive prompts
- **Runtime owns the protocol** — Mesh, MCP, and HTTP are provided by the runtime. Lua code never deals with connection management or wire formats
- **Lua for logic, Rust for plumbing** — Domain logic in Lua. VM, networking, and protocol handling in Rust
### Design documentation lives in the code
Settled design is written into the code's own documentation and nowhere else:
Rust crate and module docs (`//!`) plus item docs, and the `---` module headers of
the embedded Lua libraries. There is no separate design document tree — a document
beside the code drifts and goes unread, a module doc is compiled, linted and read
with the code it describes.
The entry points for the kernel are the module docs of
`crates/agent-block-core/src/knl/mod.rs` (the kernel's invariants),
`crates/agent-block-core/src/bridge/knl.rs` (the syscall surface Lua sees) and
`crates/agent-block-core/blocks/lib/knl/init.lua` (the Lua kernel: session, device,
beat, Outcome, shapes). `cargo doc --open` renders the Rust side.
## Architecture
The repository is a Cargo workspace with 4 crates (strict one-way
dependency `bin → core → mcp → types`):
| Crate | Role | Deps |
|---|---|---|
| `agent-block-types` | shared `error` + `obs` (sanitize_url 等) | leaf |
| `agent-block-mcp` | rmcp wrapper + Lua↔JSON converters | types |
| `agent-block-core` | host runtime + Lua stdlib bridge + EventBus | mcp, types |
| `agent-block` (bin) | thin CLI on top of `core` | core, mcp |
Downstream Rust applications can depend on `agent-block-core` (or just
`agent-block-types` for error/obs) without pulling in clap / the CLI.
```text
┌─────────────────────────────────────────────┐
│ agent-block (binary) │
│ │
│ ┌─────────┐ ┌──────────┐ ┌───────────┐ │
│ │ mlua-isle│ │ mesh-sdk │ │ llm-client│ │
│ │ (Lua VM) │ │ (relay) │ │ (API) │ │
│ └────┬─────┘ └────┬─────┘ └─────┬─────┘ │
│ │ │ │ │
│ ─────┴─────────────┴──────────────┴─────── │
│ Lua Stdlib Bridge │
│ mesh.send / mesh.on / llm.chat / fs.read │
│ tool.register / tool.call / log.* / env.* │
│ mcp.connect / mcp.call / mcp.list_tools │
└─────────────────────────────────────────────┘
↕ WebSocket ↕ stdio
┌─────────────────┐ ┌──────────────────┐
│ agent-mesh │ │ MCP Servers │
│ relay │ │ (outline-mcp) │
└─────────────────┘ └──────────────────┘
```
## Installation
```sh
# From crates.io
cargo install agent-block
# Prebuilt binaries (GitHub Releases, built by cargo-dist for
# linux x86_64 / macOS x86_64 + aarch64 / windows x86_64).
# Handy in CI where a cargo build is too slow:
curl --proto '=https' --tlsv1.2 -LsSf \
https://github.com/ynishi/agent-block/releases/latest/download/agent-block-installer.sh | sh
```
Windows PowerShell: use `agent-block-installer.ps1` from the same release.
Per-platform archives (`agent-block-<target>.tar.xz` / `.zip`) with sha256
checksums are attached to each release for direct download.
## Usage
```sh
# Basic
agent-block --script crates/agent-block/examples/hello.lua
# A registered block, by name (see "Blocks and libraries" below)
agent-block --block summarize --prompt "Summarise the README"
# With project context
agent-block --script scripts/test_fcloop.lua --project .
# With mesh
ANTHROPIC_API_KEY=... agent-block --script my_agent.lua --relay ws://localhost:9090/ws
# Pass a prompt and system context from the CLI
agent-block --script my_agent.lua \
--prompt "Summarise the README" \
-c "You are a concise technical writer."
```
CLI flags `--prompt` and `-c / --context` inject the `_PROMPT` and `_CONTEXT` Lua globals
into the script. Use them with `agent.run`:
```lua
-- my_agent.lua
local agent = require("agent")
local result = agent.run({
prompt = _PROMPT, -- nil when --prompt is omitted (agent.run will error — expected)
system = _CONTEXT, -- nil when -c is omitted (system prompt is optional)
})
print(result.content)
```
Neither takes an environment variable, and neither does `--result`. They are
what ONE run is, and an environment variable is inherited: a block that starts
another `agent-block` would be handing its child its own prompt and its own
result file to write over.
A caller with all of them to pass writes a file instead:
```json
{ "prompt": "…", "context": "…", "result": "/tmp/run.json",
"labels": { "job": "drain", "run": "drain-1757300000" } }
```
```sh
agent-block -s block.lua --config run.json
```
The file is the lowest of three layers — **file, then environment (for the
knobs that have one), then argument** — so a flag always wins over it. What
belongs to the host rather than to a run (where the databases live, the
sandbox, `AGENT_BLOCK_HOME`) stays an environment variable read from the
project's `.env`, which is that half's config file already.
### What the exit code says
It says whether the process finished, not whether the work succeeded:
| Exit | The script |
|---|---|
| `0` | ran and returned. Whatever it returned, including a value that says the work failed |
| `75` | called `job.defer(reason)`: it looked at what it needs, did not find it, and did not start (sysexits `EX_TEMPFAIL`; the job manager records this run as `deferred`) |
| `1` | raised, or never got to run — a source that could not be read, a mesh that would not connect, two flags that contradict each other |
| `2` | was never named: the command line itself did not parse (clap's own code, printed as a usage error) |
A block that reports failure in its return value exits `0`, so a caller
testing `$?` alone will not see it. Two ways to be seen: raise (`error(...)`,
which is exit `1`), or return the JSON and have the caller read `ok` out of
the `--result` file. The file is written only when the script returns — a
raise leaves it absent, so a caller that reads it must handle that.
`75` is a value a shell testing "non-zero means broken" will get wrong. It
is the one exit code that means nothing broke:
```sh
agent-block -s block.lua --result out.json
case $? in
0) ;; # ran; read `ok` out of out.json
75) exit 0 ;; # dependency was not there; nothing was done
*) exit 1 ;; # it raised, or never got to run
esac
```
## Blocks and libraries
Two directories, two jobs, at three tiers:
```text
<project>/.agent-block/blocks/… the project's own, kept out of the way
<project>/.agent-block/lib/… (`agent-block vendor` writes here)
<project>/blocks/<name>.lua | <name>/init.lua entry points — run by name
<project>/lib/<name>.lua | <name>/init.lua modules — require("<name>")
~/.agent-block/blocks/… the user's blocks, every project
~/.agent-block/lib/… the user's modules, every project
(`$AGENT_BLOCK_HOME` moves the pair)
```
A **block** is a script the host runs for the one value it returns. It is
callable by name — `agent-block --block <name>` from a shell, `run_block` over
MCP — and the two surfaces share one registry:
`<project>/.agent-block/blocks/`, then `<project>/blocks/`, then
`$AGENT_BLOCK_HOME/blocks/`, the nearer tier winning a clash. A **module** is
what a block `require`s: `script_dir` → `<project>/.agent-block/lib/` →
`<project>/lib/` → `$AGENT_BLOCK_HOME/lib/` → embedded, first hit wins.
Nothing crosses: a file in `blocks/` cannot be required, a file in `lib/` is
never run by name, so a helper dropped beside a block does not become a
callable block by accident.
The ends of that order are the two halves of one rule. `.agent-block/` is the
project's own directory — versioned with it, beside its `.gitignore` — and is
where `agent-block vendor` puts a copy of something embedded, so it is searched
first. `~/.agent-block/` is last because a file there changes **every project
on the machine**: it is the shared fallback for what every project should have,
and never the place to make one project behave.
The working shape is a script that grows a library:
```text
blocks/summarize.lua write it, run it: agent-block -b summarize
lib/summarize_util.lua pull the reusable part out; require("summarize_util")
~/.agent-block/lib/summarize_util.lua mv it here when a second project wants it
crates/agent-block-core/blocks/lib/… upstream, once it is general (EMBEDDED_LIBS)
```
Going the other way — starting from something embedded and making it the
project's — is [Overriding a block or a
module](#overriding-a-block-or-a-module).
The file and its `require` name never change on the way up; each tier
resolves the same name. `--project` names the project root only (`.env`, the
sandbox write root, the kernel database) — it is not a library path.
## Serving blocks over MCP
`agent-block mcp` serves the registered blocks to an MCP client as one
`run_block` tool. The same scripts the CLI runs become callable from an agent
that speaks MCP, without that agent knowing where they live:
```sh
agent-block mcp --project .
```
```json
{
"mcpServers": {
"agent-block": {
"command": "agent-block",
"args": ["mcp", "--project", "/abs/path/to/project"]
}
}
}
```
That serves `<project>/.agent-block/blocks/`, `<project>/blocks/` and
`~/.agent-block/blocks/`; `--block-dir <dir>` (repeatable) adds a directory
that lives elsewhere.
A block runs against its own model with its own credentials, so its LLM turns
never enter the calling agent's context — only its return value does. That is
the point of the mode: a caller strong at planning and review hands the loop
off and gets one value back.
**The contract is one line: a block returns a JSON string.**
```lua
-- blocks/summarize.lua
-- Summarize the prompt. Returns { ok, text }.
local agent = require("agent")
local r = agent.run({ prompt = _PROMPT, system = _CONTEXT })
return std.json.encode({ ok = r.ok, text = r.text })
```
The host stringifies whatever the chunk evaluates to, and a Lua table
stringifies to `table: 0x…` — hence `std.json.encode`. `_PROMPT` / `_CONTEXT`
carry the tool's `prompt` / `context` arguments, exactly as the CLI flags do.
| Surface | Meaning |
|---|---|
| tool `run_block` | run one registered block; `block` is an enum of the registered names |
| tools `jobs_list` / `runs_list` / `run_get` / `job_run` / `run_stop` | the job manager's verbs, as a client of `agent-block serve` (`--serve-url`; see below) |
| resource `agent-block://guide` | the authoring contract, in full |
| resource `agent-block://blocks` | the registry as JSON |
| resource `agent-block://blocks/<name>` | one block's source |
A block is `<name>.lua` or `<name>/init.lua` directly inside a block root;
nothing deeper, and nothing under `lib/`, is callable. The roots themselves are
resolved and re-scanned per request — a new block is callable as soon as the
file lands, without restarting the server, and that includes a file dropped into
`<project>/.agent-block/blocks/` while the server is up: it is served on the
next request. A block's leading `--` comment is what the caller reads
as its description, so it is worth writing.
A Lua error comes back as a failed tool call carrying the message. A block that
ran and concluded "no" should return normally and say so in its JSON: the two
are different events and only the block knows which happened.
Because stdio transport owns stdout, this mode writes its logs to stderr, which
is where MCP clients surface server logs — including the `ab.obs` lines.
## Running blocks on a schedule
`agent-block serve` is a thin job manager: a block that has a `job.toml`
beside it runs on that interval, each run in a process of its own, and the
manager keeps the record.
```toml
# blocks/drain/job.toml — beside blocks/drain/init.lua
every = "2m" # since the previous run ended; omit to run only on request
timeout = "10m" # the run's process group is killed at this; default 10m
prompt = "..." # _PROMPT in the block; optional
context = "..." # _CONTEXT; optional
```
```sh
agent-block serve --project . # 127.0.0.1:7788, tick 5s, at most 4 live runs
```
A run is `agent-block -s <block>` started in the block's project root, so it
loads that project's `.env` and writes to that project's own session log —
labelled `job=<name>` and `run=<run_id>` (`--label`), which is how one run is
found among all of them (`knl.views.sessions`). The value the block returns —
the same JSON string `run_block` hands an MCP caller — is written under
`~/.agent-block/runs/<job>/` (`--result`, which any `agent-block -s` run can
use) and is on the run's record as `result`,
whole up to 64 KiB and pointed at past it. The manager itself decides nothing it cannot
read back: every start and end is a record on its own log
(`~/.agent-block/serve.sqlite`), `every` counts from the previous end, one
run per job is live at a time, a run the manager did not survive is closed
as `lost` on the next start, and a restart continues the same record (each
start opens a session of its own and reads across all of them). Adding
the file adds the job; removing it removes the job; there is nothing to
write for a service manager beyond the one unit that runs `serve` itself
(`docs/runbooks/job-serve.md` has systemd and launchd units). A run inherits
the manager's environment, and under a service manager that is a short
`PATH` without the user's toolchains — a block that runs `cargo` or
`agent-block` finds them from a shell and, under the manager, only if the
unit says where; the runbook's units set it.
The listener answers with a bearer token (`~/.agent-block/serve.token`,
minted on first start) on every request:
| Route | Meaning |
|---|---|
| `GET /jobs` | the declarations, each with its last end and live run |
| `GET /runs?job=&limit=` | runs, newest first, each with the value the block returned (`result`) |
| `GET /runs/<id>` | one run, with the tail of its stderr |
| `POST /jobs/<name>/runs` | ask for a run now; the next tick starts it (202) |
| `DELETE /runs/<id>` | ask a live run to stop; the next tick kills its group (202) |
```sh
curl -H "Authorization: Bearer $(cat ~/.agent-block/serve.token)" http://127.0.0.1:7788/jobs
```
Loopback is the default and a tunnel (`ssh -L`, a mesh VPN) is how it is
reached from elsewhere; `--bind 0.0.0.0:7788` is the opt-in to a wider bind,
behind the same token. `Host` and `Origin` must name a loopback host or the
bound address — a loopback bind on its own does not stop a page in a local
browser from reaching it.
## Sandbox mode (Linux)
`--sandbox` wraps the whole process in an OS-level execution boundary built from
[Landlock](https://landlock.io/) (filesystem + TCP) and a seccomp filter (io_uring).
It is off by default.
```sh
# Confine writes; TCP stays open
agent-block --sandbox --script my_agent.lua --project .
# Same, plus extra writable paths and no TCP at all
AGENT_BLOCK_SANDBOX_FS_RW=/opt/cache:/srv/data \
AGENT_BLOCK_SANDBOX_TCP=0 \
agent-block --sandbox --script my_agent.lua
```
| Flag / Env var | Default | Effect |
|---|---|---|
| `--sandbox` / `AGENT_BLOCK_SANDBOX` | off | Install the boundary at startup |
| `AGENT_BLOCK_SANDBOX_FS_RW` | *(empty)* | `:`-separated extra writable paths |
| `AGENT_BLOCK_SANDBOX_TCP` | `true` | `0` / `false` / `no` / `off` denies TCP bind + connect |
What it enforces:
- **Reads and executes are unrestricted.** PATH lookups, shared libraries and
ordinary tooling keep working — the boundary is about mutation, not secrecy.
- **Writes are denied** except under the project root (`--project`), the
agent-block state dir (`AGENT_BLOCK_HOME`, default `$HOME/.agent-block`),
`/tmp`, `/dev/null`, `/dev/urandom`, `/dev/tty`, and anything listed in
`AGENT_BLOCK_SANDBOX_FS_RW`. Allowlist entries that do not exist are skipped.
- **io_uring is denied** (`io_uring_setup` / `_enter` / `_register` return `EPERM`),
since a ring bypasses the syscall-level view a seccomp filter has.
- **Child processes inherit it.** Landlock rulesets and seccomp filters survive
`fork`/`execve`, so `sh.exec` payloads and `mcp.connect` servers run inside the
same boundary with no extra wiring. The Lua `os.*` / `io.*` stdlib is left
intact and caught at the OS layer instead.
- **Fail-closed startup.** If the sandbox is requested but the kernel enforces
nothing, the process exits with an error instead of running unconfined, and
an unresolvable `--project` path is a startup error (it is the primary write
grant). A partial enforcement of the default rights on older Landlock ABIs
logs a warning naming what was dropped and continues — except an explicitly
requested TCP denial (`AGENT_BLOCK_SANDBOX_TCP=0`), which aborts startup on
kernels older than 6.7 rather than silently failing open.
Operational notes:
- **A build target outside `--project` needs an explicit grant.** The default
write allowlist is only the project root, `AGENT_BLOCK_HOME`, `/tmp` and
`/dev/{null,urandom,tty}`, so when the directory being worked on is not under
`--project` (e.g. the checkout driving the run differs from the repo being
built), add that checkout to `AGENT_BLOCK_SANDBOX_FS_RW`.
- **Toolchain cache dirs must be writable too.** `~/.cargo` is not in the
default allowlist, so cargo fails creating its registry cache
(`Permission denied`). Either list it in `AGENT_BLOCK_SANDBOX_FS_RW` or point
the cache at an allowed path with `CARGO_HOME=/tmp/cargo` — the latter works
from cold, since TCP stays open and downloads still succeed.
KNOWN LIMITATIONS:
1. **Linux only.** On other platforms `--sandbox` is a startup error, never a
silent no-op.
2. **UDP and DNS are not restricted.** Landlock's network rights cover TCP
bind/connect only, so `AGENT_BLOCK_SANDBOX_TCP=0` does not stop UDP traffic
(DNS included) or unix-domain sockets.
3. **io_uring cannot be used inside the sandbox**, including by dependencies
that would otherwise pick it up opportunistically.
4. **TCP is a single on/off switch** — no per-host or per-port granularity. This
is an execution boundary, not a policy engine.
5. **The io_uring deny only exists on x86_64 / aarch64.** On other Linux
architectures no seccomp filter is compiled and the deny is skipped with a
warning; the Landlock filesystem boundary still applies.
## MCP Echo Harness
A self-contained reference MCP server for smoke-testing the agent-block MCP client bridge.
Exposes tools, resources, prompts, logging, and sampling over stdio or HTTP.
```sh
# stdio (default) — connect via mcp.connect("echo", "target/debug/examples/echo_mcp_server", {})
cargo run --example echo_mcp_server
# HTTP on an ephemeral port — prints ECHO_MCP_URL=http://127.0.0.1:<port>/mcp
cargo run --example echo_mcp_server -- --transport http --port 0
# Also emit 5 log notifications (1-second intervals) and attempt a sampling round-trip
cargo run --example echo_mcp_server -- --transport http --port 0 --emit-logs --request-sampling
```
Verify from Lua (requires the server to be running with `--transport http`):
```lua
local url = os.getenv("ECHO_MCP_URL")
mcp.connect_http("echo", url)
print(mcp.list_tools("echo")) -- 2 tools: echo, slow_echo
print(mcp.list_resources("echo")) -- 2 resources: text://hello, text://note
print(mcp.list_prompts("echo")) -- 1 prompt: greet
-- call slow_echo to exercise progress notifications
mcp.on_progress("echo", function(tok, prog, total, msg)
print("progress", prog, total, msg)
end)
print(mcp.call("echo", "slow_echo", { msg = "hi", steps = 3 }))
```
See `crates/agent-block/examples/verify_echo_harness.lua` for the full verification script.
## MCP Resource Subscribe Smoke Server
A standalone binary example for shell-level smoke-testing the Resource Subscribe API
(`mcp.subscribe_resource` / `mcp.on_resource_update`). Starts an HTTP MCP server with
`resources.subscribe` capability enabled and fires at least one `notify_resource_updated`
event after each subscribe call.
```sh
# Ephemeral port — prints SUBSCRIBE_TEST_SERVER_URL=http://127.0.0.1:<port>/mcp
cargo run --example subscribe_test_server
# Fixed port
cargo run --example subscribe_test_server -- --port 7878
# Periodic notify every 500 ms (instead of single fire on subscribe)
cargo run --example subscribe_test_server -- --port 0 --interval 500
```
Shell smoke (requires the server URL printed above):
```sh
export MCP_HTTP_URL="$(cargo run --example subscribe_test_server 2>/dev/null \
| grep SUBSCRIBE_TEST_SERVER_URL | cut -d= -f2-)"
agent-block -s tests/fixtures/mcp_on_resource_update_callback.lua
# Expect: SUBSCRIBE_OK, RESOURCE_UPDATE_EV_OK, UPDATE_HITS=1, FIXTURE_DONE
```
See `docs/runbooks/e2e-mcp-resource-subscribe.md` for the full positive/negative verification
procedure (Step 2 = shell positive, Step 3 = negative against a server without subscribe
capability).
## Lua API
### llm.*
- `llm.chat(messages, opts)` — LLM call (Anthropic Messages API)
### tool.*
- `tool.register(name, schema, handler [, meta])` — Register a tool. Optional `meta = { group = "..." }` assigns the tool to a named group for use with `agent.run({ tool_groups = {...} })`.
- `tool.call(name, input)` — Call a registered tool
- `tool.list()` — List registered tool names
- `tool.schema()` — Anthropic tools-format schema array (includes `group` field when set)
### mcp.*
Support status, capability matrix, and the tool-grouping design rationale
live in `docs/architecture/mcp-support.md`.
- `mcp.connect(name, command, args, opts)` — Spawn MCP server over stdio + initialize handshake.
`opts.trace_context` (bool, default `false`) injects `__ab_obs` into `call_tool` arguments;
`opts.cwd` (string) overrides the subprocess working directory (default: project root).
The spawned server is a child process, so — exactly like `sh.exec` children — it does **not**
inherit the host's own credential variables (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
`AGENT_BLOCK_MESH_SECRET_KEY`). A server that legitimately needs one is handed it explicitly:
`mcp.connect(name, cmd, args, { env = { ANTHROPIC_API_KEY = "..." } })` — `opts.env` is a
string→string table applied *after* the removal, and is the only way to pass a stripped
variable through. Every other variable is still inherited (this is not an allowlist); a
non-string `opts.env` value raises an error rather than being dropped.
- `mcp.connect_http(name, url, opts)` — Connect to an MCP server over HTTP transport.
`opts.transport = "sse" | "http"` (default `"http"` = Streamable HTTP; `"sse"` = SSE).
`opts.headers` table is forwarded as request headers.
- `mcp.call(name, tool_name, arguments)` — Call an MCP tool
- `mcp.list_tools(name)` — List available tools
- `mcp.list_resources(name)` — List resources exposed by the server.
Returns `{ ok=true, resources=[{uri, name, description, mimeType, ...}] }`.
- `mcp.list_resource_templates(name)` — List resource URI templates exposed by the server.
Returns `{ ok=true, resource_templates=[{uriTemplate, name, ...}] }`.
- `mcp.read_resource(name, uri)` — Read a resource by URI.
Returns `{ ok=true, contents=[{uri, mimeType, text|blob}] }`.
- `mcp.list_prompts(name)` — List prompt templates exposed by the server.
Returns `{ ok=true, prompts=[{name, description, arguments}] }`.
- `mcp.get_prompt(name, prompt_name, args)` — Retrieve a rendered prompt template.
Returns `{ ok=true, description, messages=[{role, content}] }`.
- `mcp.complete(name, ref, arg_name, arg_value)` — Request completion suggestions (MCP Completion typeahead, Phase 3).
`ref` is `{type="ref/prompt", name=...}` or `{type="ref/resource", uri=...}`.
Returns `{ ok=true, values=[...], total=number?, has_more=bool? }` or `{ ok=false, error=str }`.
- `mcp.on_progress(name, handler)` — Register a per-server progress notification callback.
`handler(token, progress, total, message)` is called for each `notifications/progress`
event from the named server. Handler must be a pure Lua function.
- `mcp.on_log(name, handler)` — Register a per-server log notification callback.
`handler(level, logger, data)` is called for each `notifications/message` event from
the named server. When no handler is registered the notification is forwarded to the
Rust `tracing` target `"lua"` at the corresponding level (debug/info/notice/warning/
error/critical/alert/emergency). Handler must be a pure Lua function.
- `mcp.cancel(name, request_id)` — Send a `notifications/cancelled` notification to the
named server for the given `request_id`. Also fired automatically when `mcp.call` times
out. Explicit use is only needed for manual cancellation flows.
- `mcp.set_sampling_handler(server_name, handler)` — Register a per-server Lua function
to respond to `sampling/createMessage` requests from the MCP server.
`handler(params)` receives the `CreateMessageRequest` table and must return a table
matching `CreateMessageResult` (`{ model, stop_reason, role, content }`).
When no handler is registered the server receives `method_not_found`.
- `mcp.set_elicitation_handler(server_name, fn)` — Register a per-server Lua function to respond
to `elicitation/create` requests originating from the MCP server (server→client, Form variant
only). `fn(server_name, message, schema_json)` must return a table with `action =
"accept"|"decline"|"cancel"` and (for accept) a `content` table conforming to the schema.
Url-variant elicitation requests are always declined without reaching the callback. Handler must
be a pure Lua function.
- `mcp.set_roots_handler(server_name, fn)` — Register a per-server Lua function to respond to
`roots/list` requests originating from the MCP server (server→client direction).
`fn(server_name)` must return a Lua array of root tables, each with at least a `uri` field
and an optional `name` field (e.g. `{ { uri="file:///home/user", name="home" } }`).
When no handler is registered the server receives `method_not_found`. Handler must be a pure
Lua function; C functions and Rust-bound callbacks are not supported.
- `mcp.notify_roots_list_changed(name)` — Send a `notifications/roots/list_changed`
notification to the named server (client→server, fire-and-forget). Use this whenever the
client's set of filesystem roots changes so the server can re-request the updated list via
`roots/list`. Failures are logged at `warn` level and silently discarded.
- `mcp.server_info(name)` — Return the server's `InitializeResult` as a Lua table.
Returns `{ ok=true, server_info={serverInfo, capabilities, ...} }` on success.
Useful for inspecting which MCP capability groups (resources, prompts, tools, etc.)
a server declares. Returns `{ ok=false, error="..." }` if the server is not connected.
- `mcp.ping(name)` — Send a `ping` keepalive request to the named server and measure
round-trip latency. Returns `{ ok=true, latency_ms=N }` on success or
`{ ok=false, error="..." }` on failure (unknown server, timeout, or RPC error).
- `mcp.subscribe_resource(server, uri)` — Send a `resources/subscribe` RPC for the given
resource URI. Returns `{ ok=true }` on success or `{ ok=false, error="..." }` on failure.
Requires the server to declare the `resources.subscribe` capability.
- `mcp.unsubscribe_resource(server, uri)` — Send a `resources/unsubscribe` RPC to stop
receiving change notifications for the given URI. Same return shape as `subscribe_resource`.
- `mcp.on_resource_update(server, callback)` — Register a per-server callback for
`notifications/resources/updated` events. `callback(ev)` where
`ev = { type="resource_update", server, uri }`. Handler must be a pure Lua function.
- `mcp.on_resources_list_changed(server, callback)` — Register a per-server callback for
`notifications/resources/list_changed` events. `callback(ev)` where
`ev = { type="resources_list_changed", server }`.
- `mcp.on_tools_list_changed(server, callback)` — Register a per-server callback for
`notifications/tools/list_changed` events. `callback(ev)` where
`ev = { type="tools_list_changed", server }`.
- `mcp.on_prompts_list_changed(server, callback)` — Register a per-server callback for
`notifications/prompts/list_changed` events. `callback(ev)` where
`ev = { type="prompts_list_changed", server }`.
- `mcp.disconnect(name)` — Disconnect server
### mesh.*
- `mesh.send(agent_id, payload)` — Synchronous send (raises Lua error on failure)
- `mesh.request(agent_id, payload)` — Request-response
- `mesh.agent_id()` — Own AgentId
### std.fs.* (mlua-batteries)
- `std.fs.read(path)`, `std.fs.write(path, content)`, `std.fs.glob(pattern)`, `std.fs.exists(path)`
- `std.fs.walk(dir)`, `std.fs.copy(src, dst)`, `std.fs.mkdir(path)`, `std.fs.remove(path)`
- `std.fs.is_file(path)`, `std.fs.is_dir(path)`, `std.fs.read_binary(path)`, `std.fs.write_binary(path, bytes)`
- `std.fs.tool_specs(opts)` / `std.fs.register_tools(opts)` — the LLM-facing file tools (agent-block): `fs_read` and `fs_edit` (line-addressed, checked against an `expect` of the current text) by default; opt in through `opts.allowed` to `fs_write`, `fs_rollback` and `fs_search_replace`, which addresses an edit by a unique verbatim snippet and carries it out as `fs_edit` with the same checks — the form to offer a model that reconstructs `expect` from memory instead of copying it
### sh.*
- `sh.exec(cmd, opts)` — Execute a shell command. `opts.cwd` (default: project root), `opts.timeout` (seconds, default 30), `opts.label` (a name for the command's process group, see `sh.kill`). On timeout the child's whole process group is SIGKILLed, not left running; the result then says `timed_out = true` beside `error`.
- `sh.kill(label)` — End the process group of the `sh.exec` started with `opts.label = label`, from any coroutine; answers `true` if there was one. SIGTERM first, so a command that is itself an `agent-block` host can forward the end to its own commands, SIGKILL after twice the task grace if the group is still there. The awaiting `sh.exec` returns with `killed = true` beside whatever exit code that left (none for a signalled process, 130 for a nested host that forwarded it). This is how one coroutine ends a command another is awaiting — aborting the awaiting task does not reach a command already running.
- Children inherit the environment **except the host's own credential variables**: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY` and `AGENT_BLOCK_MESH_SECRET_KEY` are removed from every `sh.exec` child, so code the agent runs (including code it just wrote) cannot read the keys the host itself uses.
- A script that legitimately needs an API key must be given its own — pass it under a different variable name, or through the block conf (`api_key` / `api_key_env`). Custom `api_key_env` names are *not* stripped, and this is not an allowlist: every other variable is still inherited.
- The same set is removed from MCP server subprocesses spawned by `mcp.connect`; that path takes an explicit `opts.env` table for servers that need a key (see `mcp.*` above).
### std.json.* (mlua-batteries)
- `std.json.encode(value)`, `std.json.decode(str)`, `std.json.encode_pretty(value)`
### std.env.* (mlua-batteries + agent-block extensions)
- `std.env.get(key)`, `std.env.set(key, value)`, `std.env.get_or(key, default)`, `std.env.home()`
- `std.env.agent_id()`, `std.env.project_root()` — agent-block specific
### std.path.* / std.time.* (mlua-batteries)
- `std.path.join(...)`, `std.path.basename(path)`, `std.path.dirname(path)`
- `std.time.now()`, `std.time.sleep(secs)`, `std.time.measure(fn)`
### std.kv.* (mlua-batteries, SQLite-backed)
- `std.kv.get(ns, key)` — retrieve a value by namespace + key; returns `nil` if absent
- `std.kv.set(ns, key, value)` — store a value (any Lua value, JSON-encoded internally)
- `std.kv.delete(ns, key)` — delete a key; returns `true` if it existed, `false` otherwise
- `std.kv.list(ns, prefix?)` — list keys in a namespace, optionally filtered by prefix
- `std.kv.register_tools()` — register `kv_get`, `kv_set`, `kv_delete`, `kv_list` as LLM-callable tools
Storage: `AGENT_BLOCK_HOME/kv.sqlite` (override via `AGENT_BLOCK_KV_PATH`; `:memory:` supported).
### std.sql.* (mlua-batteries, SQLite-backed)
- `std.sql.execute(sql, params?)` — execute a DML statement; returns `{ affected = N }`
- `std.sql.query(sql, params?)` — execute a query; returns an array of row tables
- `std.sql.register_tools()` — register `sql_execute`, `sql_query` as LLM-callable tools
Storage: `AGENT_BLOCK_HOME/sql.sqlite` (override via `AGENT_BLOCK_SQL_PATH`; `:memory:` supported).
### std.ts.* (agent-block, SQLite-backed TSDB)
- `std.ts.append(series, value, tags?, at?)` — append a data point; `value` is a Lua
number or table (JSON-encoded, losslessly decoded on read); `tags` is an optional
`{key=value}` table; `at` is an optional Unix timestamp in milliseconds (default: now)
- `std.ts.query(series, opts)` — range query; `opts` fields:
- `from`, `to` (integer ms) — time range (default: full range)
- `tags` (table) — AND-filter; each key-value pair uses SQLite `json_extract`
- `agg` (string) — `"count"` | `"sum"` | `"avg"` | `"last"` (optional)
- `bucket_ms` (integer) — bucket width; requires `agg`; produces time-bucketed rows
- `limit`, `offset` (integer) — pagination
- `std.ts.last(series, tags?)` — most-recent data point; same tag AND-filter as `query`
- `std.ts.register_tools()` — register `ts_append`, `ts_query`, `ts_last` as LLM-callable tools
Ordering guarantee: raw-path results (`query` without `agg`) are ordered by `(ts ASC, rowid ASC)`;
`last` and `query` with `agg="last"` resolve same-millisecond ties by `(ts DESC, rowid DESC)` so
the last-appended row always wins. This is a deterministic SQLite rowid tie-breaker — no DDL or
index change is required.
Storage: `AGENT_BLOCK_HOME/ts.sqlite` (override via `AGENT_BLOCK_TS_PATH`; `:memory:` supported).
### Embedded blocks: four layers
The crate's `blocks/` directory is baked into the binary, so `require("agent")` works
after `cargo install` with no path configuration. A filesystem copy of a module in a
`lib/` tier normally wins over the embedded one — but the four layers below differ in
whether that is the intended way to change them.
| layer | modules | how to change it |
|---|---|---|
| kernel + declaration | `knl`, `knl_adapter`, `knl_types`, `lshape` (and `lshape.t` / `.check` / `.reflect` / `.luacats`) | **Sealed** — a filesystem copy fails the run rather than replacing the module. The kernel is one thing across Rust and Lua, held together by declaration tests a Lua-side replacement would pass while meaning something else. Change it upstream. `AGENT_BLOCK_UNSEAL=1` downgrades the refusal to a warning, for work on the kernel itself and not for shipping. |
| shell packs | `policy`, `supervisor` | Do not shadow: a pack is a value you hand to `knl.device` or consult in your own loop, not a registry the host reads. The two are one set — a loop is composed from both — and a model's limits are not a third pack: they go into the seams the kernel already has (`fold` / `filters` / `cost` / `tool_policy`, the loop's predicates, the supervisor's tree) and into what the Port declares (`LLMPort:profile`); see the `policy` module header. For a partial change, delegate through `embedded.<name>`. |
| consumers | `agent`, `coding` | Copy-on-write is the intended way — `agent-block vendor agent` (or `vendor coding`) writes the file the idiom used to have you write by hand, into `.agent-block/lib/`, and it is the module your scripts get. A hand-written `lib/agent/init.lua` in the project root still works and still wins over the user tier. For a partial change, delegate through `embedded.<name>`. `coding.run` is the loop that edits files until a verify command passes; `examples/coding_loop.lua` is a block over it. |
| utilities | `llm_proto` (with `.openai` / `.anthropic`), `mcp_tools`, `session` | Shadowing works, but `knl_adapter` requires `llm_proto` and `mcp_tools`, so replacing either replaces a sealed module's dependency. Prefer delegation. |
Resolution order, highest priority first: the script's own directory →
`project_root/.agent-block/lib/` → `project_root/lib/` → `$AGENT_BLOCK_HOME/lib/` →
embedded. `blocks/` directories are not on it (see
[Blocks and libraries](#blocks-and-libraries)). The seal is checked once at start over
those filesystem roots, before the script runs; the error names the module and the file
that would have replaced it.
Delegation — a shadowing module reaching the one it replaced:
```lua
-- project_root/lib/agent/init.lua
local base = require("embedded.agent")
local M = setmetatable({}, { __index = base })
function M.run(opts) print("OVERRIDE"); return base.run(opts) end
return M
```
`embedded.<name>` resolves from memory and only from memory: every embedded module is
registered a second time under that prefix, ahead of the filesystem roots, so a
`lib/embedded/` directory cannot stand in for it. The alias evaluates the embedded
source under its own name, which means `require("agent")` (yours) and
`require("embedded.agent")` (the base) are two tables — exactly the pair the idiom needs.
It exists for sealed modules too: `require("embedded.knl")` reads the kernel, which is
fine; replacing it is what the seal refuses.
Promotion runs the other way. A module that starts as `project_root/lib/<name>/init.lua`
moves to `~/.agent-block/lib/` when a second project wants it, and becomes an embedded
lib by a change upstream once it proves general — the same file, moved under
`crates/agent-block-core/blocks/` and listed in `EMBEDDED_LIBS`. Projects still carrying
their own copy keep resolving to it until they delete it.
### Overriding a block or a module
Three steps, and the middle one is the only one that is yours:
```sh
agent-block vendor agent # 1. the embedded source, written into this project
$EDITOR .agent-block/lib/agent/init.lua # 2. change it; it is the project's now
# 3. when it proves general, send it upstream
```
`vendor` writes `<project>/.agent-block/lib/<name>/init.lua`, the first tier of the
require path — so the copy is what `require("session")` resolves, in this project
and nowhere else. Every embedded entry goes there, `agent` and `coding` included:
they are modules the scripts that use them `require`, so a copy has to land where
`require` looks. Nothing vendors into `.agent-block/blocks/`, which is for the
project's own entry-point scripts. A module is written whole,
sub-modules included
(`vendor llm_proto` writes `openai.lua` and `anthropic.lua` beside its `init.lua`); you
cannot vendor `llm_proto.openai` on its own, because half a module on disk and half in
memory is two versions of it under one name. Step 3 is a change upstream — a pull request —
and **not** a move to `~/.agent-block/`: a file there answers for every project on the
machine, which is the opposite of what "this project needs it different" means.
```text
agent-block vendor --list what can be vendored, and what this project already has
agent-block vendor --path <dir> write somewhere other than the project root
agent-block vendor --force overwrite a copy that is already there
```
`--list` prints one line per embedded root — name, `lib` (everything the binary
carries is a module to a project), whether it is
`sealed` or a `pack`, and `vendored` when this project has a copy — with sub-modules
folded under the root they belong to (`lshape (+t, check, reflect, luacats)`). An
existing copy is never overwritten without `--force`, because by then it is the
project's own and likely edited.
Two layers answer back. A **sealed** module is refused outright (`knl` is sealed: a
project cannot shadow it) — the copy would only fail the next run; read it with
`require("embedded.knl")`. A **pack** (`policy`, `supervisor`) is written, but with a
warning, because a pack is a value you hand to `knl.device` and not a registry the host
reads, so a whole copy is rarely the change that was meant.
For a partial change — keeping the embedded behaviour and adding to it — do not vendor
at all: shadow and delegate through `embedded.<name>`, as above.
### agent (StdPkg — `require("agent")`)
Built-in ReAct loop module. Available without any path configuration after `cargo install`.
```lua
local agent = require("agent")
local result = agent.run({
prompt = "List files in the current directory and summarise them.",
system = "You are a helpful assistant.", -- optional
model = "claude-haiku-4-5-20251001", -- optional, env ANTHROPIC_MODEL as fallback
max_tokens = 4096, -- per-request token limit
max_iterations = 20, -- loop iteration cap
max_tokens_budget = 50000, -- total token budget (nil = unlimited)
timeout = 120, -- HTTP timeout in seconds
mcp_servers = { -- optional MCP servers to connect
{ name = "outline", command = "outline-mcp", args = {} },
-- HTTP/SSE form: use `url` instead of `command`
{ name = "remote", url = "https://example.com/mcp",
transport_opts = { transport = "sse" } }, -- transport = "sse" | "http" (default "http")
},
sampling = function(params) ... end, -- optional: called for sampling/createMessage
-- from every connected MCP server
-- Anthropic server-side context editing (default ON). Pass `false` to opt out,
-- or pass a full override table (replaces the default entirely).
context_management = true, -- default true; false disables beta header + body
context_management_config = { -- default: trigger 80K, keep 3, clear_at_least 10K
edits = {
{
type = "clear_tool_uses_20250919",
trigger = { type = "input_tokens", value = 80000 },
keep = { type = "tool_uses", value = 3 },
clear_at_least = { type = "input_tokens", value = 10000 },
},
},
},
on_turn = function(info) -- optional per-turn callback
-- info keys: turn_number, content, tool_calls, usage. Returning false
-- stops the run.
print("turn", info.turn_number, "#tools", #info.tool_calls)
end,
extra_tools = {}, -- optional extra Anthropic tool defs
tool_groups = { "outline" }, -- optional; nil = every tool
history = prior, -- optional prior messages (e.g. session.load)
store = "mem", -- optional; where the session log goes.
-- Omitted = the host's own database;
-- "mem" (one in-memory database per run,
-- gone with the process) or
-- { sqlite = <path> } otherwise.
})
if result.ok then
print(result.content)
else
print("error:", result.error)
end
-- result fields: ok, content, usage{input_tokens,output_tokens,total_tokens}, num_turns, error, messages
```
**Correlation ids**
There is no option for them. `agent.run` reads `AGENT_BLOCK_TRACE_ID`, `AGENT_BLOCK_RUN_ID`, `AGENT_BLOCK_AGENT_ID` and `AGENT_BLOCK_AGENT_NAME` off the environment and stamps whichever are set onto the run's seed event as `meta` labels — the same four the HTTP bridge puts on its `ab.obs` `http_request` / `http_response` lines. So the session log is selected by the id the log lines are grepped by:
```lua
session:query("SELECT * FROM events WHERE json_extract(meta, '$.run_id') = ?",
{ std.env.get("AGENT_BLOCK_RUN_ID") })
```
With `AGENT_BLOCK_AGENT_ID` unset the obs lines still carry a per-process id the host makes up, and the seed event carries no `agent_id`; set it and both sides agree.
**Provider Switching**
By default `agent.run` uses the Anthropic Messages API. Pass `provider = "openai"` to route to any OpenAI-compatible endpoint (vLLM, llama.cpp, OpenRouter, RunPod, etc.):
```lua
-- Anthropic (default) — requires ANTHROPIC_API_KEY
local result = agent.run({ prompt = "Hello", model = "claude-haiku-4-5-20251001" })
-- OpenAI — requires OPENAI_API_KEY (or opts.api_key)
local result = agent.run({
prompt = "Hello",
provider = "openai",
model = "gpt-4o-mini",
})
-- Local vLLM / llama.cpp / RunPod — custom base_url
local result = agent.run({
prompt = "Hello",
provider = "openai",
base_url = "http://localhost:8080/v1",
model = "Qwen/Qwen3-0.6B",
api_key = "token-abc123", -- or api_key_env = "MY_KEY"
})
```
Environment variables used per provider:
| provider | default key env | override via |
|--------------|---------------------|------------------------|
| `anthropic` | `ANTHROPIC_API_KEY` | `opts.api_key` / `opts.api_key_env` |
| `openai` | `OPENAI_API_KEY` | `opts.api_key` / `opts.api_key_env` |
`opts.base_url` overrides the endpoint root. Default for `openai` is `https://api.openai.com/v1`.
`cache_control`, `context_management`, and `context_management_config` are Anthropic-only: they are operative when `provider="anthropic"` (or unset) and emit a `warn`-level log message then are ignored when `provider="openai"`.
**Protocol options (`llm_proto`)**
Request building lives in the `llm_proto` package, reached through the provider Port every block's device carries. The vocabulary is OpenAI's; each adapter renames or drops what its provider does not accept, so the same options work on both paths.
```lua
local result = agent.run({
prompt = "...",
-- "auto" | "none" | "required" | { type = "function", name = "grep" }
-- Anthropic spellings ("any", { type = "tool", name = ... }) are accepted too.
tool_choice = "required",
parallel_tool_calls = false,
-- Reasoning / extended thinking. `false` turns it off where that is expressible.
thinking = { effort = "medium" }, -- or { budget_tokens = 8000 }, or true / false
dialect = "vllm", -- openai | vllm | llamacpp | ollama (default: from base_url)
-- Structured outputs (OpenAI shape; mapped to output_config.format on Anthropic).
response_format = { type = "json_schema", json_schema = { name = "out", schema = { ... } } },
-- Sampling and request knobs, forwarded where the provider supports them.
temperature = 0.2, top_p = 0.9, top_k = 40, stop = { "END" }, seed = 7,
max_retries = 2, -- transient failures only (rate limit / overload / 5xx)
})
```
Notable translations:
| you pass | Anthropic | OpenAI | vLLM / llama.cpp / Ollama |
|---|---|---|---|
| `tool_choice = "required"` | `{type="any"}` | `"required"` | as OpenAI (ignored by Ollama) |
| `parallel_tool_calls = false` | `tool_choice.disable_parallel_tool_use` | top-level | top-level |
| `thinking = { effort = ... }` | `{type="adaptive"}` + `output_config.effort` (4.7+) or `{type="enabled", budget_tokens}` (4.5 and earlier) | `reasoning_effort` | `chat_template_kwargs` (+ `reasoning_effort`); Ollama takes `reasoning_effort` only |
| `stop` | `stop_sequences` | `stop` | `stop` |
| `max_tokens` | `max_tokens` | `max_completion_tokens` on o-series / gpt-5, else `max_tokens` | `max_tokens` |
Combinations the API would reject are refused locally instead: forced tool use under manual extended thinking, a thinking budget that does not fit in `max_tokens`, and tools plus reasoning on gpt-5.6+. Values a model cannot accept (`temperature` on reasoning models, `temperature ~= 1` on Claude past Opus 4.6, `top_k` on api.openai.com) are dropped with a `warn` rather than sent.
Responses are normalized to one shape regardless of provider: reasoning arrives as a `thinking` content block whether the server sent `reasoning_content`, `reasoning`, Anthropic thinking blocks, or raw `<think>` tags in the text; `usage` carries `cache_read_input_tokens` / `cache_creation_input_tokens` / `thinking_tokens` on both paths.
Key behaviours:
- MCP servers listed in `mcp_servers` are connected automatically and disconnected on exit (even on error).
- Each entry may use the stdio form `{ name, command, args }` or the HTTP form `{ name, url, transport_opts }`. Both forms can coexist in the same list.
- Pass `sampling = fn` in `agent.run` opts to register a single Lua function as the `sampling/createMessage` handler for every connected MCP server (`mcp.set_sampling_handler` is called per server automatically).
- Pass `enable_resources = true` in `agent.run` opts to automatically register `{server}__mcp_list_resources` and `{server}__mcp_read_resource` as LLM-callable tools for each connected server that declares the `resources` capability. Default `false`. If a server does not declare `resources`, the opt-in is silently skipped (logged at `info`).
- Pass `enable_prompts = true` in `agent.run` opts to automatically register `{server}__mcp_list_prompts` and `{server}__mcp_get_prompt` as LLM-callable tools for each connected server that declares the `prompts` capability. Default `false`. Capability check and silent skip apply the same way as `enable_resources`.
- Pass `on_progress = fn(ev)` in `agent.run` opts to receive progress notifications from all connected MCP servers. The callback is called with an envelope table `{ type="progress", server, token, progress, total, message }`. No capability gate — all servers are registered. User callback errors are swallowed and logged at `warn`.
- Pass `progress_to_log = true` in `agent.run` opts to bridge progress notifications to `log.info` automatically. Ignored when `on_progress` is also set (callback takes priority). Default `false`.
- Pass `on_log = fn(ev)` in `agent.run` opts to receive log notifications from servers that declare the `logging` capability. The callback is called with an envelope table `{ type="log", server, level, logger, data }`. Servers without logging capability are silently skipped (logged at `info`). User callback errors are swallowed and logged at `warn`.
- Pass `log_to_stderr = true` in `agent.run` opts to bridge server log notifications to `log.debug|info|warn|error` automatically. Ignored when `on_log` is also set (callback takes priority). Logging capability gate applies the same way as `on_log`. Default `false`.
- MCP tool names are namespaced as `server_name__tool_name` to avoid collisions.
- MCP tools are automatically assigned to a group for use with `tool_groups`. Group resolution follows this priority: (1) the tool's `_meta.group` field (string, non-empty) declared by the server takes precedence — rmcp serialises `Tool.meta` as `_meta` via `#[serde(rename = "_meta")]`; (2) fallback to the server name. Pass `tool_groups = { "outline" }` (for example) to `agent.run` to include only tools from that MCP server. This aligns with the MCP SEP-986 tool-name prefix grouping guidance and the `mcp__<server>__*` convention used by Claude Code. Tools without an explicit group (e.g. plain registered Lua tools) fall into the `"default"` group.
- Tool dispatch: MCP tools via `mcp.call()`, registered Lua tools via `tool.call()`.
- Never throws — all errors returned as `{ ok=false, error="..." }`.
- Context editing is on by default: once the conversation crosses ~80K input tokens, Anthropic evicts all but the most recent 3 tool-use / tool-result pairs server-side so the loop can keep running. Works on Sonnet 4 / Sonnet 4.5 / Haiku 4.5 / Opus 4 / 4.1 / 4.5. Pass `context_management = false` to disable, or `context_management_config = { edits = { ... } }` to replace the default entirely (the whole table is forwarded as `body.context_management`; no partial merge).
- `on_turn(info)` is handed exactly four keys — `turn_number`, `content`, `tool_calls`, `usage` — and returning `false` from it stops the run. What the server did with context editing is not among them; the response that carried it is in the session log as `llm_response`.
- `agent` is a consumer block: a local `lib/agent/init.lua` in the project root replaces it, and can delegate to the embedded one through `require("embedded.agent")`. See [Embedded blocks: four layers](#embedded-blocks-four-layers).
- No block emits an LLM dump. Each model call is recorded in the session log (`llm_request` / `llm_response` / `llm_call_failed`) instead, and `AGENT_BLOCK_LLM_DUMP` is gone with the layer that read it.
### lshape (Vendored package — `require("lshape")`)
`lshape` is vendored under `blocks/lib/lshape/` so scripts can use schema validation
and LuaCATS generation without external installation.
```lua
local lshape = require("lshape")
local T = lshape.t
local User = T.shape({ name = T.string, age = T.number })
local ok, why = lshape.check.check({ name = "Ada", age = 36 }, User)
assert(ok, why)
```
### Lua kernel (knl — `require("knl")`)
`knl` is the Lua half of a kernel/shell split. Rust owns the **session**: an
append-only event log, a budget the owner granted it, and a scope it is written
under. Lua owns the **beat** — one model call plus the tools that call asks for
— and the **device** it runs against, a frozen bundle of policy (`llm`, `tools`,
`tool_policy`, `fold`, `filters`, `system`, `cost`). `knl.beat(session, device)`
takes the two separately because they differ in owner, lifetime and mutability.
There is no run loop: a caller writes the loop, which is why the primitive is
one beat.
```lua
local kernel = require("knl")
local adapter = require("knl_adapter")
local device = kernel.device({
llm = adapter.anthropic:open({ model = "claude-haiku-4-5-20251001", max_tokens = 1024 }),
tools = adapter.tools({ ... }), -- flat specs or ToolPorts
})
kernel.session({ owner = "u", budget = { amount = 8, tag = "beats" } }, function(s)
s:append({ kind = "msg_user", data = { content = "..." } })
local out -- the loop is yours to write
for _ = 1, 8 do
out = kernel.beat(s, device) -- ok | refused | error | stopped
if not kernel.Outcome.is_ok(out) then break end
if #out.out.tools == 0 then break end -- nothing left to answer
end
local rows = kernel.views.usage(s) -- one SELECT over the log
for _, row in ipairs(rows) do
print(row.calls, row.input_tokens, row.output_tokens)
end
end) -- the bracket closes either way
```
Views come in two tiers. A **built-in view** is a kernel read reached with
`s:view(name, opts?)`, and there are exactly two fixed reads —
`s:events(from)` and `view("tail", { n })`. Everything else is a **query
view**: a named Lua function running one `SELECT` through `s:query(sql,
params?, opts?)` over the published event table. `knl.views.beats` /
`tool_pairs` / `ledger` / `usage` are the four shipped, and a consumer's own
view is a function of the same form — nothing about the four is privileged.
The event table is `events`, and its columns are what `knl.api().schema`
publishes: `position` (the log's global order, and its key), `stream`, `seq`,
`epoch_ms`, `kind`, `schema_version`, `meta` and `data`. A read within one
session orders by `seq`; a read across sessions orders by `position`. The beat
a fact belongs to is a `meta` label, reached with `json_extract(meta,
'$.beat')`. The store underneath is an `eventsdb` SQLite log — one database
per file, opened once per process, so the sessions in it are streams of one
log and a session tree is one transaction. A `knl.sqlite` written by an
earlier release is brought forward on the first open, once.
#### Reading a run from outside
A run's facts land in a session in the project's kernel database, and the
process that wants them back is usually not the one that wrote them — a job
manager, a test, a person after the fact. `agent-block knl export` is that
door: a session id in, JSON Lines out, one record per line, no Lua involved.
```
# The log as it is stored: every kind, upcast to today's shape
agent-block knl export --session <ID> --as events
# The conversation it holds: msg_user / llm_response / tool_call / tool_result,
# one record each, carrying beat / seq / epoch_ms / kind
agent-block knl export --session <ID> --as messages
```
`--store <PATH>` reads some other database; without it the project's own is
used, resolved from `-p/--project` exactly as `knl.open{}` resolves it for a
script that names no `store`. A session that is not there is a one-line
`error:` on stderr and exit `1`, not an empty answer.
The design is in three module docs: `crates/agent-block-core/src/knl/mod.rs`
(the kernel's invariants), `crates/agent-block-core/src/bridge/knl.rs` (the
syscall surface Lua sees) and
`crates/agent-block-core/blocks/lib/knl/init.lua` (this half: beat, device,
Outcome, shapes, views).
### log.*
- `log.info/warn/error/debug(msg)`
## Testing
### Rust (e2e + integration)
```
cargo test --workspace
```
### Lua block unit specs (mlua-lspec)
The whole suite runs in one command:
```
just test-lua # every spec
just test-lua window_spec # one, by filename substring
```
Two kinds of file are picked up: the fixtures under
`crates/agent-block/tests/fixtures/*_test.lua`, and each block's own specs under
`crates/agent-block-core/blocks/lib/<block>/spec/`. Both run with the mlua-lspec
framework (`describe` / `it` / `expect`) and need no API keys and no network.
The embedded blocks expose their pure, I/O-free helpers through a
`_test_helpers()` accessor so a spec can reach them.
What a spec can reach is what needs no kernel: `knl` is a syscall bridge the
pure runner does not have, so a loop that opens a session is covered by the
Rust e2e suite in the full host (`tests/e2e_knl_beat.rs`) and the specs cover
what sits around it. Each spec file's header documents how to run it on its
own.
## License
Licensed under either of
- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE) or <http://www.apache.org/licenses/LICENSE-2.0>)
- MIT license ([LICENSE-MIT](LICENSE-MIT) or <http://opensource.org/licenses/MIT>)
at your option.
### Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted
for inclusion in the work by you, as defined in the Apache-2.0 license, shall be
dual licensed as above, without any additional terms or conditions.