---
domain: node
last_rule_review_commit: 495996fee4b55eabef58505f73ab23848794eeef
last_rule_updated_at: 2026-08-06
---

# Node

## Responsibility

Node connects to Edge and executes provider requests. It owns transport handlers, provider adapter construction, local run tracking, runtime config swaps, provider tunnels, and execution event translation. For an approved execution preset, Node also owns bounded request-scoped workspace/file/command execution behind a dedicated typed Edge-Node boundary.

## Owned paths

- `apps/node/cmd/node/`
- `apps/node/internal/bootstrap/`
- `apps/node/internal/node/`
- `apps/node/internal/router/`
- `apps/node/internal/transport/`
- `apps/node/internal/adapters/`
- `apps/node/internal/store/`

## Required patterns

- Translate protobuf messages to `packages/go/execution` types in `runtime_bridge.go`.
- Use `adapter + target` for internal provider selection.
- Treat `session_id` as opaque correlation. Never use it to reuse or resume execution state.
- Track cancellation by a non-empty run id and always deregister completed runs.
- Admit only capabilities, transport status, and Ollama API provider commands before provider lookup.
- Keep normalized run streams separate from raw provider tunnel frames.
- Build replacement adapter registries before a live config swap; let in-flight work finish against its captured provider.
- Base local concurrency on adapter capability. Edge remains the owner of distributed provider-pool admission and leases.
- Preserve standard inference, structured tools, usage, provider lifecycle, reconnect, and tunnel behavior.
- Regenerate bindings from protobuf source; never edit generated files.
- Keep request-scoped workspace execution separate from provider `RunRequest`, `packages/go/execution`, caller metadata, and the closed provider `NodeCommand` allowlist.
- Admit workspace operations only for an operator-approved root and immutable request binding. Enforce path/symlink containment, fixed cwd, environment allowlist, bounded process group/output/timeout/cancel, and terminal cleanup.

## Prohibited ownership

Node must not implement persistent host programs, interactive terminals, conversation resume, unbounded or caller-selected host command execution, caller-selected filesystem roots, or quota/status scraping. The only workspace mutation exception is the bounded request-scoped executor admitted by an Edge-owned execution preset; it must not become a reusable shell/session service. Node must not accept direct scheduling from Control Plane or Client.

## Contracts and verification

- `agent-contract/inner/execution-runtime.md`
- `agent-contract/inner/edge-node-runtime-wire.md`
- Follow the testing domain rule after changes to run, cancel, command, refresh, reconnect, adapter, tunnel, or transport paths.
