Tool Execution Domain
Problem
Section titled “Problem”Tool execution used to hide the side-effect location behind execute(args).
That made host execution an implicit default and prevented cancellation from
crossing into tool code.
Tools separate the envelope from the side-effect domain. ToolContract owns
admission, claims, quota, contract validation, retry, and ledger settlement.
Tool.execution is a sibling fact that declares whether a tool is
deterministic or external. External tools also declare access (read or
write) and the domain: host, sandbox, workspace, or remote. Host execution is
never implicit.
Deterministic tools declare execution: { kind: "deterministic" }. External
tools declare execution: { kind: "external", access, domain }. The tool
registry rejects tools that omit execution metadata. Backend facades also
boot-validate ExecutionDomainDeclaration entries so external tools cannot
reference an undeclared execution locus.
In this release ExecutionDomain is a declared locus marker, not a dispatcher.
Actual execution still happens inside the tool closure or generated
WorkspaceEnv tool. The declaration exists so admission, boot validation, and
ledger audit all see the same symbolic locus without putting execution inside
the claim contract.
@agent-os/sandbox is bounded stateless execution-domain algebra.
@agent-os/workspace-env is a stable fs+exec actuator. Provider adapters choose
the real execution domain: Cloudflare Sandbox declares sandbox; local Node
fs/shell declares host with an explicit environment allowlist. These are
adjacent execution surfaces, not one merged abstraction and not carrier
packages.
Non-Goals
Section titled “Non-Goals”This concept does not define durable reconnect, provider billing cancellation, workspace-session lifecycle, or product-specific workspace projections.