agent-block-0.39.0 is not a library.

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.

┌─────────────────────────────────────────────┐
│              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

# 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

# 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:

-- 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:

{ "prompt": "…", "context": "…", "result": "/tmp/run.json",
  "labels": { "job": "drain", "run": "drain-1757300000" } }

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:

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:

<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 requires: 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:

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.

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:

agent-block mcp --project .

{
  "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.

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

# 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

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)

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 (filesystem + TCP) and a seccomp filter (io_uring). It is off by default.

# 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:

Linux only. On other platforms --sandbox is a startup error, never a silent no-op.
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.
io_uring cannot be used inside the sandbox, including by dependencies that would otherwise pick it up opportunistically.
TCP is a single on/off switch — no per-host or per-port granularity. This is an execution boundary, not a policy engine.
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.

# 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):

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.

# 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):

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

-- 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:

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.

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.

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:

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

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

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

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.

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 or http://www.apache.org/licenses/LICENSE-2.0)
MIT license (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.

agent-block 0.39.0