04 - Built-in modules and operation catalog

Status: archive. Not the current specification.

Status: target design, not implemented. The shipped server uses endpoint ids and one policy engine; see README section 1 for what exists and section 2 for what does not.

Part of Server SDK v2. Generated tables: the table bodies below are produced by python -m agent_sandbox.server describe --markdown and verified by the drift test (R5); edit the @op declarations, not the tables. Legacy bindings are exactly today's routes (41 HTTP endpoints plus the PTY WebSocket make the "42 endpoints" of the current server). v2.1: package ops/ renamed builtin/ (IF-03); default registry is 105 ops (50 non-agent + 35 generic agent + 5 x 4 adapter ops); effects, explicit-only flags and the agent catalog are the target catalog. The in-flight code is mapped in the parity ledger of 07 section 6.

1. Modules and groups

"Enabled" is the legacy default of a server with no policy. A server with a policy has exactly what its allow rules mount; groups are only used when a rule or ABX_SERVER_ENABLED_GROUPS says so.

Legacy path jail. The legacy server already confines file paths to ABX_SERVER_BASE_DIR (comma list; default the process home/app dirs) through _resolve_safe_path. presets.legacy_compat() therefore carries PathScope(roots=BASE_DIRS) on every files.* op and on cwd of command ops; this is not an optional detail (see review round 2, finding F2.1). Under legacy_compat, a violation keeps the v1 status and body as recorded from HEAD by the v1 fixture generator (IF-04: not every v1 message contains "traversal"; the fixtures, not this prose, are normative) and gains code: policy.path_not_allowed. legacy_compat is loud and unsafe (03 section 4); legacy_diff(server) reports which of the 40 legacy op ids (plus POST /commands/{name} = 41 routes) the effective policy no longer mounts, so "I added a policy and my routes vanished" is visible (B-6).

2. Effects and limits legend

Effects: R=read, W=write, D=delete, X=exec, N=net, A=admin. Limit keys: bytes=max_bytes, ent=max_entries, to=timeout, out=max_output_bytes, cpu, mem, proc, rate, conc (rate and concurrency apply to every op).

3. core

4. files (group file_ops) - path-scoped

• The "twin" ops exist because their legacy request/response shapes differ slightly and old clients use both. deprecated metadata points new code to files.download/files.upload.
• (v2.1, B-7, one rule) A policy mounts exactly what it names, and files.download / files.download_stream are a family: the allow() of one of the two without the other produces the lint warn config.download_family_split (the legacy /files/download-stream route would 404 under an allow(download, stat, list) that the author believed served downloads). The download_only, files_readonly and readonly presets name all four read ops (list stat download download_stream). Every statement mounting a path op needs a PathScope (03 section 3, scope-required).
• Handlers use *at() calls on a parent fd (open_parent_beneath, unlink_beneath) for delete/move/upload (IS-F2); non-regular files are refused (IS-F4).

5. commands and process (group process) - command-scoped

commands.run is the shell execution op. It is not the home of user-defined commands (custom.*): the in-flight design's server.commands.* naming for custom commands is retired (reconciliation in 10).

6. terminal (group terminal)

7. system (group system)

8. devtools (group dev_tools, default off)

9. browser (group browser, default off)

UrlScope (v2.1, replaces the glob-over-string design that IS-U1 broke): strict parser, compares the parsed hostname, schemes, ports, paths, block_private (RFC 1918, loopback, link-local, CGNAT incl. 100.100.100.200, ULA, IPv4-mapped IPv6). Chromium does its own DNS so rebinding is only mitigated by platform egress policy - documented as a limit. Literal hosts first; wildcard host suffixes (*.example.com) are deferred.

10. custom and ext (group commands)

POST /commands/{name} is a wire alias (02 section 5): it resolves to custom.<name> before authorization.

11. agents

Specified in 05-agents-api.md. The default registry holds 105 ops (spike ebxp.catalog, tests_catalog.py): 50 non-agent ops + 35 generic agents.* ops (3 non-wire + 32 that mirror the official SDK) + 5 adapters x 4 per-adapter ops (agents.<a>.run, .install, .sessions.create, .sessions.send_event; adapters codex, claude_code, qwen_code, cursor, qoder; the last three are flagged experimental).

Cancel is not an op: it is the input event type agent.session.input.cancel of send_event. Generic agents.sessions.create/send_event additionally require the selected adapter's op (two-level gate, 05 section 4). agents.<a>.** is accepted as selector sugar for "everything of adapter a that is not explicit-only" (IF-29 mitigation). The registry-size row of the in-flight 152-op plan is superseded: wire-shaped ops replaced the 12 + 5 x 18 family (05 section 3 records why per-adapter ops are kept and what generation does about them).

12. Group golden lists (no privilege creep)

group:<name> expands to exactly:

A new built-in op joins a group only through an edit to the golden snapshot file (tests/golden/groups.json) in the same change; the reviewer checklist asks whether enabling the group on an existing server would newly expose the op (for example process.stdin and files.watch are new and join process and file_ops because their effects are covered by the existing group's trust level). (v2.1) Membership never carries an explicit-only op; system.env.set left group:system (the legacy ABX_SERVER_ENABLED_GROUPS=system no longer mounts it; the compat preset documents the opt-in).

13. Behavioural contracts shared by all built-ins

1. Handlers never take raw paths; they use ctx.paths and ctx.open.
2. No handler spawns a shell unless the op says so and the policy admitted shell=True.
3. Handlers that list or search re-check entries; handlers that stream honour ctx.limits and ctx.deadline.
4. Responses keep every legacy key; new keys are additive. Legacy result shapes are pinned by the existing 308 tests plus contract tests.
5. Each op has: a unit test, a policy-bypass test (if it touches paths/commands), and a client/server contract test generated from the catalog.
6. "Complete" is defined as: every envd-facing client module method has a server-plane op or a justified asymmetry entry in 07 section 6; nothing in the legacy server lacks an op ID.