# Edge Phase Report

Date: 2026-03-20

This phase focused on turning `dashboard-edge` from a thin remote stub into a real execution-plane service with a stable protocol and a native runtime skeleton.

## Completed

### 1. Execution-plane service extracted

- `dashboard-edge` now exists as a standalone deployable service.
- It owns node identity, heartbeat, node resources, command delivery, logs, workspace, and monitor packet handling.

### 2. Protocol stabilized

- Heartbeat, node self, node resources, and monitor packets now share a versioned node protocol.
- Node identity fields are consistent across backend and edge.
- Central backend stores node `capabilities`, `resources`, and `last_seen_at`.

### 3. Monitor packets are first-class

- Edge can expose stored monitor packets.
- Backend can poll and persist those packets after command delivery.
- Startup recovery can backfill pending edge conversations from recent logs.

### 4. Runtime abstraction introduced

- Edge execution now routes through `EdgeRuntimeBackend`.
- Docker execution is behind the runtime backend abstraction.
- Native execution has a real skeleton instead of a pure stub.

### 5. Native executor skeleton implemented

- Native runtime can launch a local child process.
- It manages stdout capture, log persistence, process status, command delivery, and resource snapshot reporting.
- Dashboard chat URL and native launch command are configurable through environment variables.

### 6. Node management is operational

- Nodes can be registered, tested, refreshed, and displayed with protocol/resource data.
- The `local-edge` node is now a usable test target.
- A separate `local-edge-native` node is now running against a real native launcher on port `8011`.

### 7. Deploy / migrate flow is now explicit

- A dedicated `POST /api/bots/{bot_id}/deploy` flow now handles cross-node migration and redeploy.
- Basic bot editing no longer accepts execution-target or image switching fields.
- The node home page now exposes a real deploy / migrate modal instead of a design-only placeholder.

### 8. Native launcher defaults are wired

- `dashboard-edge` now auto-detects the local `nanobot-v0.1.4-post5` virtualenv when `EDGE_NATIVE_COMMAND` is not explicitly configured.
- Native bot startup now passes per-bot `--config` and `--workspace`, so instances no longer fall back to the global `~/.nanobot/config.json`.
- A dedicated `scripts/dev-edge-native.sh` helper starts a native edge node as `local-edge-native`.

## Still To Do

### 1. Real native bot contract

- Validate a real Bot lifecycle on `local-edge-native` without disrupting the existing `local-edge` Docker regression target.
- Verify the dashboard channel injection path during a full assistant turn, not only node health and capability probing.
- Continue validating per-bot dashboard port or URL selection when multiple native bots run on one node.

### 2. Deploy flow hardening

- Add richer preflight validation and clearer failure surfacing for edge reachability before switching a Bot.
- Consider a deploy preview / diff step for workspace sync and image changes.
- Extend the flow when a single node eventually supports multiple runtime profiles.

### 3. Node-level resource telemetry

- Improve native runtime resource accounting with more precise metrics.
- Consider node heartbeat frequency and health thresholds.

### 4. Reverse-connect transport

- The design still prefers node-initiated connection to the central backend for remote machines.
- That transport is not fully implemented yet.

### 5. Full remote native rollout

- The native skeleton is in place, but real remote native nodes still need end-to-end validation.
- Existing test bot `unis_bot_a01` can be used as a regression target when those pieces are connected.

## Verification

- Backend and edge Python modules compile cleanly.
- `dashboard-edge` can report protocol-versioned node identity and resources.
- `local-edge` is already visible and testable from the central dashboard.
- `local-edge-native` is registered, online, and reports `runtime.native=true` with the real launcher command.
- Frontend build passes with the deploy / migrate modal wired into the active node home page.

## Notes

- `direct` remains the local fallback path.
- `edge` is now the intended execution-plane abstraction for both Docker and future Native nodes.
- The long-term goal remains: central dashboard as control plane, `dashboard-edge` as execution plane.