Skip to main content

​
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

​
Probe internal composition

​
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.