Effects

An effect is the only way guest code touches the world. The catalog below is the entire host surface — small and stable by design. Everything else a program uses (the any client, LLM adapters, memory, the conversation loop) is itself guest Python loaded with use(). Provider keys ride effects too, as credentials.

The catalog

http.* derives its capability from the route (below); every other syscall's capability is its own name.

Ergonomic shims sit on top: now(), rand(), env(...), uuid4() as globals, and proxied datetime / time / os.environ modules whose "what time is it" calls route through the same effects. The present is always a record — datetime.now() and time.time() are real time.now records. Randomness is not one record per draw: random, secrets and uuid run on a stream seeded from the trace header's seed, so a replay re-derives every value.

Pythonic surface

r = http.get("https://api.github.com/repos/anyproto/any",
             headers={"Accept": "application/vnd.github+json"}, timeout=20)
if r.status == 200:
    print(r.json()["stargazers_count"])   # print() is the output channel

print() is the model-facing output channel: each call is captured as a structured value in the cell's result and is the primary input to its digest. http.* mirrors the requests idiom (params=, headers=, json=); a call returns the response as data, including 3xx when redirects are manual. The host decides text versus bytes from the response itself: a binary body comes back as a Blob handle on .blob (.text raises), and a Blob passed as a request body or inside json is expanded by the host at send time while the trace keeps only the reference.

Read or mutate is a boundary fact

Every record carries meta.class of read or mutate. For HTTP the class and the required capability derive from (method, url) against a route table scoped to the any server's base URL:

Guest code cannot declare its own class. A @span(kind="getter") facade whose span contains a mutate is a legible inconsistency a viewer can flag; the log never lets the label override the boundary fact. Reads are safe to re-execute; mutates are not, and replay tooling relies on that distinction.

The pipeline

Every effect call, no exceptions, flows through one path:

normalize → key → capability check → replay/mock consult → execute → record → return

• Normalize produces the canonical input — the payload as JSON with sorted keys; sha256 over the effect name and that JSON is the record's key.
• Capability check consults the active grant set before anything runs. The runtime ships a permissive default; a denial is recorded as error.type: "capability_denied".
• Record always — success, error, denial, mock. A failure is data in the record and a typed EffectError ("<type>: <message>") raised into the guest, so a cell may catch it and nothing is silently swallowed.

Why it matters. The guest-side facade (http.get, print()) holds zero authority — bypassing it gains nothing. Classification, secrets and recording all happen on the host side of one serialized crossing. The cage and its syscalls never change; everything the agent is lives above the boundary as deployed code.

Fan-out

Cells are single-threaded. http.get_many(items) carries a list of requests across the boundary once as a batch effect; the host runs each item as its own effect call and appends one record per item in input order, so strict replay stays deterministic. A per-item failure is an EffectError value in that slot, never a whole-batch exception. Looping the same effect sequentially is correct-but-slow, never wrong.

Introspecting your own run

effects.of(cell) returns a scope's immediate children — bare effect records plus child span-end rows — and effects.get(seq) resolves one full record; both take run= to read a past run. effects.runs(...) finds runs by program, status or cost, and effects.query(pipeline) aggregates over every recorded run. This is how the agent answers "why did you do that?" from inside a conversation; the human-side equivalent is anyrt trace show on Traces and replay.