MAP Agent Runtime

This repository defines MAP Agent ABI 1.0, a portable Lua 5.4 agent package, and a reference desktop runtime. Portability covers Lua source, configuration, and serialized state; a Lua VM or its execution stack is never migrated.

The repository has three deliberately independent parts:

• spec/ — the normative ABI, package, security, and management RPC;
• prototype/ — a Rust reference implementation for Linux/macOS;
• conformance/ — black-box fixtures and portable vectors.

Project status

This is an early reference prototype. It currently provides the Lua 5.4 sandbox, lifecycle and quota enforcement, state serialization, persistent agent installation/update/removal, deterministic framing helpers, an unsigned development packer, a Unix-socket management daemon and CLI clients, and a monotonic scheduler with a fixed shared executor pool and per-agent metrics. It also accepts didactic single-file map-sketch/1 programs and persists a transactional resource graph for agents, objects, and channels. See the local daemon walkthrough.

TLS transport, COSE signature verification, trust store, and the complete black-box conformance adapter are specified but not implemented yet. Do not use the prototype to run untrusted agents in production.

Quick start

Install a Rust toolchain, then:

cargo test --manifest-path prototype/Cargo.toml
cargo run --manifest-path prototype/Cargo.toml -- info
python3 conformance/run.py

The shortest agent is a single main.lua; no manifest or returned ABI table is required:

-- `state` contains the data owned by the agent. The runtime can serialize it.
state = { count = 0 }

-- `setup` is called once whenever the agent starts.
function setup()
  print("hello")
end

-- `loop` is called periodically. `dt` is the elapsed time in milliseconds.
function loop(dt)
  -- Read and change persistent data through `state`.
  state.count = state.count + 1

  -- Ask the runtime to checkpoint `state` after this callback succeeds.
  save()
end

Install the development CLI once from this checkout:

cargo install --path prototype

This installs the map command in Cargo's binary directory (normally $HOME/.cargo/bin, which the Rust installer usually adds to PATH). You do not need to repeat cargo run --manifest-path ... after installation.

Run or package the file directly. The CLI creates .map/project.json beside the source to keep a stable UUID and advances its revision after each successful package build:

map run main.lua --ticks 3
map pack main.lua agent.map

Sketches also expose object { ... } for passive internal tools, channel(name) for local callbacks, and reserved entry points for graph-backed environmental objects and neighbors. The existing directory-plus-manifest ABI remains supported for advanced agents.

Run the editable counter fixture and print its logs and state after each tick:

map run conformance/agents/counter --ticks 3

Build a package in development mode:

map pack conformance/agents/counter ./counter.map

Install the package into a persistent data directory, run it, and inspect it:

map install ./runtime-data ./counter.map
map list ./runtime-data
map run-installed ./runtime-data 018f6d4a-89ab-7def-8123-456789abcdef --ticks 3
map get ./runtime-data 018f6d4a-89ab-7def-8123-456789abcdef

run-installed checkpoints on stop. Running it again restores the previous counter. Removal requires the explicit --confirm flag. Update uses update DATA PACKAGE and requires the same UUID and state_schema, plus a strictly higher revision.

The current packer produces an unsigned development envelope. The local management daemon accepts these development packages over its Unix transport. The future network transport will require signed packages and reject them.

Start with the first-agent tutorial, continue through the four runnable examples, and use the programming-model and CLI guides as references. The roadmap separates implemented, current, and planned capabilities. Embedded work is tracked in the ESP-IDF implementation checklist.

Contributing and security

Contributions are welcome; read CONTRIBUTING.md before opening a substantial change. Report vulnerabilities privately according to SECURITY.md. The prototype is not ready to execute untrusted agents in production.

License

Unless explicitly stated otherwise, MAP Core is available under the Apache License 2.0 or the MIT License, at your option.