body-os

OS-011 &body.os reference implementation for the [&] Protocol ecosystem.

Typed perception of the host OS (cwd, env, filesystem snapshot, process list), typed action execution with destructive-edge authorization, StateHash-anchored replay, InteractionTrace recording — the OS-subtype counterpart to body-browser, completing the &body.* primitive family.

Status

Library: production-ready
Simulator backend: 12/12 OS-011 §9 conformance tests pass
MCP server: shipped — 7 tools on the body-os namespace (ensure_session + 6 OS-011 operations), 12 MCP unit tests covering the destructive-action authorization gate
ComputerUse backend (Claude Computer Use / OpenClaw): skeleton — subprocess wiring pending

MCP surface

body_os_ensure_session  — create or re-bind a session by id
body_os_perceive        — typed OS observation (cwd, env, fs, processes)
body_os_affordances     — policy-filtered AffordanceSet
body_os_encode_state    — deterministic StateHash
body_os_act             — execute one TypedAction (destructive ones need auth)
body_os_dry_run         — predicted outcome (no mutation)
body_os_replay          — fail-fast replay with destructive re-authorization

Every tool takes a session_id so multiple agents can drive independent host sessions concurrently. Sessions are supervised under BodyOs.SessionSupervisor and addressed through the BodyOs.SessionRegistry.

Safety: the destructive-action authorization gate at the Session boundary is necessary but not sufficient. For a real ComputerUse backend, combine it with a sandboxed execution environment (containers, jails, restricted filesystems). The two are complementary, not redundant.

The contract (OS-011 §11)

Identical six-operation surface as body-browser, but with the OS action set:

operation	input	output	deterministic
`perceive`	`PerceptionQuery`	`EnvironmentObservation`	✅
`affordances`	`ScopeQuery?`	`AffordanceSet`	✅
`encode_state`	`PerceptionQuery`	`StateHash`	✅
`act`	`TypedAction`	`ActionOutcome`	❌ side-effecting
`replay`	`InteractionTrace`	`ReplayResult`	❌ side-effecting
`dry_run`	`TypedAction`	`PredictedOutcome`	✅

OS action types (OS-011 v0.1, 11 types)

shell_exec  file_read  file_write  file_edit  file_delete
keyboard_input  mouse_click  mouse_drag
screen_capture  process_spawn  process_signal

Destructive subset (require authorization block, fresh per replay):

shell_exec  file_write  file_edit  file_delete
keyboard_input  mouse_click  mouse_drag
process_spawn  process_signal

Only file_read and screen_capture are strictly read-only.

StateHash stable fields

sha256(canonical_json({cwd, env_summary, fs_snapshot_hash, process_list_hash}))

fs_snapshot_hash hashes each entry's {path, kind, size, permissions, content_hash} — fresh refs dropped.
process_list_hash hashes each entry's {command, state} — raw pids dropped.

Five invariants (all enforced by `BodyOs.Session`)

#	invariant	where
I1	perceive-before-act	`Session.check_ref_freshness/2`
I2	affordance-bounded action	`Session.check_affordance/4`
I3	policy-filtered affordances	`Session.apply_policy/2`
I4	deterministic state encoding	`BodyOs.StateHash.of/1`
I5	replay fail-fast + destructive re-auth	`BodyOs.Replay.execute/3`

Quick start

alias BodyOs.Backend.Simulator
alias BodyOs.Backend.Simulator.{FsNode, Proc}
alias BodyOs.Session

fs = %{
  "/home/user/hello.txt" => %FsNode{kind: "file", size: 5, content: "hello"}
}

{:ok, s} = Session.start_link(
  backend: {Simulator,
    cwd: "/home/user",
    fs: fs,
    processes: %{},
    env: %{"USER" => "user"}
  },
  agent_id: "demo",
  provider: "body-os-simulator"
)

{:ok, obs} = Session.perceive(s)
{:ok, aset} = Session.affordances(s)
{:ok, hash} = Session.encode_state(s)

# Destructive action REQUIRES authorization block.
{:ok, outcome} = Session.act(s, %{
  "type" => "file_delete",
  "target" => "@fs1/g1",
  "authorization" => %{
    "policy_id" => "delegatic://my-workspace/ops",
    "approved_by" => "supervisor@co",
    "approved_at" => DateTime.utc_now() |> DateTime.to_iso8601(),
    "authorization_token" => "sha256:..."
  }
})

Wiring to Graphonomous

Every recorded trace carries provenance.capability == "&body.os". Submit via Graphonomous's act(action: "store_trace", interaction_trace: ...); retrieve for replay via retrieve(action: "replay", trace_id: "...").

Running the conformance suite

mix deps.get
mix test

Twelve tests, 1:1 with OS-011 §9. A real-host backend (Claude Computer Use, OpenClaw, …) must pass the same suite to claim OS-011 conformance for the os subtype.

Safety note

The ComputerUse backend (when wired) will execute real shell commands, real file writes, and real process signals on the host. Sandbox strongly (containers, jails, restricted filesystems) AND rely on the authorization block gate — the two are complementary, not redundant.

References

opensentience.org/docs/spec/OS-011-EMBODIMENT.md — normative spec
AmpersandBoxDesign/docs/registry/body.os.md — registry entry
PULSE/manifests/body-os.embodiment.json — loop manifest
Sibling: body-browser/ — &body.browser reference implementation

License

Apache-2.0