> ## Documentation Index
> Fetch the complete documentation index at: https://docs.skrmir.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Probe Architecture v0

> Control-plane/data-plane split, Probe internal modules, and bounded authority rules.

# Probe Architecture v0

## Scope

Defines the v0 architecture of the Probe runtime in AIOS, including control-plane boundaries, internal modules, session supervision loops, adapter roles, and bounded self-heal authority.

## Terminology

* **Control plane**: Gateway-owned policy, routing, desired-state, approval, and audit authority.
* **Data plane**: Probe-owned local execution and forwarding runtime.
* **Worker Sandbox**: isolated execution unit hosting coding tools, SSH/PTY runtime, mounts, and workspace dependencies.
* **Adapter**: protocol translation boundary for channel or agent integration.

## Normative Spec

### System Layering

AIOS v0 MUST use this layered model:

1. **Gateway** as the only control plane.
2. **Probe** as the host-side data-plane runtime.
3. **Worker Sandbox** as the execution plane for session and task runtime.

### Gateway Responsibilities

Gateway MUST own:

* DevBox and session specification
* scheduling and lease issuance
* authentication, authorization, approval, and sandbox policy decisions
* desired-state writes
* metadata-only audit and trace
* capability registry and global recovery/archive policy

### Probe Responsibilities

Probe MUST own:

* execution of authorized Gateway intent
* Worker Sandbox lifecycle on the local host
* maintenance of `ssh_remote` and `dialog` channels
* supervision of channel adapters and agent adapters
* health, heartbeat, event, and observed-phase reporting
* bounded local self-heal only

Probe MUST NOT own:

* global routing authority
* global approval policy
* desired-state authorship
* cross-host placement changes

### Worker Sandbox Responsibilities

Worker Sandbox MUST contain the execution environment for:

* `codex`
* `claude_code`
* `opencode`
* SSH/PTY runtime
* workspace filesystem, dependencies, tools, and local helper contracts

### Internal Probe Modules

The Probe architecture SHOULD include these modules:

* Host Runtime Manager
* Lease Guard
* Session Supervisor
* Workspace Bridge
* SSH Remote Broker
* Dialog Forwarder
* Adapter Host
* Health Reporter
* Snapshot Client
* Local Self-Heal Executor
* Event Emitter
* Capability Reporter

### Channel Model

* Top-level channels MUST remain `ssh_remote` and `dialog` only.
* `ssh_remote` MUST support `ide_primary` and `terminal_fallback`.
* `dialog` MUST use forward-only delivery with metadata-only persistence.

### Supervision Loops

The architecture SHOULD expose these supervision loops:

1. Gateway reconcile loop.
2. Gateway lease loop.
3. Gateway scheduler loop.
4. Probe session supervision loop.
5. Probe channel supervision loop.
6. Probe self-heal loop.

### Self-heal Boundary

Probe local self-heal MAY perform only bounded local actions such as reconnect, restart, remount, rebind, and local endpoint refresh.

Probe MUST NOT:

* change host placement
* override policy
* bypass platform approval
* rewrite desired state
* silently terminate or archive runtime

## Examples

### Responsibility split

| Layer          | Owns                                                   | Does not own                           |
| -------------- | ------------------------------------------------------ | -------------------------------------- |
| Gateway        | desired state, routing, approval, audit                | local runtime process control          |
| Probe          | local runtime execution, channel forwarding, heartbeat | global policy and scheduling authority |
| Worker Sandbox | coding tools and isolated workspace runtime            | control-plane decisions                |

### Probe internal composition

```text theme={null}
Gateway
  -> Probe
     -> Session Supervisor
     -> SSH Remote Broker
     -> Dialog Forwarder
     -> Adapter Host
     -> Worker Sandbox
```

## Error & Recovery

* Lease expiry MUST immediately fence local state-changing operations.
* Adapter faults MUST remain locally isolated and MUST NOT collapse unrelated sessions.
* Repeated local recovery failure MUST escalate back to Gateway.

## Security & Audit

* Gateway-to-Probe transport SHOULD be authenticated and traceable.
* Metadata-only audit MUST capture approval references, reasons, and recovery trails.
* DevBox-internal coding-tool commands remain outside AIOS secondary approval.

## Status

Current status: `draft`

Source discussions:

* `docs/maintainers/conversation-records/agent-platform/2026-03-24-probe-agent-architecture-complete-proposal.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-p0-freeze-result-accepted.md`
* `docs/maintainers/conversation-records/agent-platform/2026-03-24-p1-freeze-result-accepted.md`

## Changelog

* 2026-03-24: Initial formal Probe architecture specification created from frozen proposal.

## Related Pages

* [DevBox Lifecycle v0](/en/agent-platform/architecture/devbox-lifecycle/index)
* [Gateway to Probe Command Contract v0](/en/agent-platform/contracts/gateway-to-probe-command-v0/index)
* [Channel Contract v0](/en/agent-platform/contracts/channel-v0/index)