# PumaClaw v1 Architecture

PumaClaw is a **secure mobile control surface for OpenClaw**. Operators use it to start and stop sessions, watch live state, approve risky actions, export audit logs, and lock down access without exposing the agent runtime.

v1 ships three layers: a mobile operator console, a control-plane API, and a Gateway adapter that speaks the OpenClaw operator protocol (optionally in front of a NemoClaw / OpenShell sandbox).

## Goals

| Goal | v1 behavior |
| --- | --- |
| Mobile-first control | Progressive web app at `/app` sized for phone operators |
| Verified sessions | Device + operator identity bound to every mutating action |
| Command-level approvals | Pending queue with approve / deny / timeout |
| Emergency lockout | Instant freeze of session writes and gateway mutations |
| Auditability | Append-only audit log exportable as JSON |
| OpenClaw fit | Adapter maps PumaClaw actions to Gateway operator RPC |
| Safe demo | Fully usable without a live Gateway (demo control plane) |

## System context

```text
┌──────────────────────┐
│  Operator phone      │
│  PumaClaw PWA (/app) │
└──────────┬───────────┘
           │ HTTPS REST  /api/v1/*
           │ (demo local store when API unavailable)
           ▼
┌──────────────────────┐       WebSocket (operator scopes)
│  PumaClaw control    │──────────────────────────────────┐
│  plane               │                                  │
│  sessions · approvals│                                  ▼
│  devices · audit     │                       ┌─────────────────────┐
│  lockout · policy    │                       │ OpenClaw Gateway    │
└──────────────────────┘                       │ sessions / approvals│
                                               │ pairing / exec      │
                                               └──────────┬──────────┘
                                                          │
                                               ┌──────────▼──────────┐
                                               │ Optional NemoClaw / │
                                               │ OpenShell sandbox   │
                                               │ policy + inference  │
                                               └─────────────────────┘
```

## Components

### 1. Operator console (`/app`)

Mobile PWA that implements the day-to-day operator jobs:

- Session roster and start / pause / stop
- Live health strip (latency, queue depth, sandbox health, access mode)
- Approval inbox with one-tap resolve
- Device trust view
- Audit export
- Emergency lockout / unlock

The console prefers the HTTP control plane. On static hosts without Functions (for example `python -m http.server`), it falls back to an equivalent in-browser demo store so the product remains evaluable.

### 2. Control plane (`/api/v1`)

REST surface with stable resource shapes:

| Resource | Purpose |
| --- | --- |
| `GET /api/v1/health` | Control-plane readiness |
| `GET|POST /api/v1/sessions` | List / create sessions |
| `POST /api/v1/sessions/:id/{start,pause,stop}` | Lifecycle |
| `GET /api/v1/approvals` | Pending and recent approvals |
| `POST /api/v1/approvals/:id/{approve,deny}` | Resolve |
| `GET /api/v1/devices` | Trusted / pending devices |
| `POST /api/v1/devices/:id/{trust,revoke}` | Device trust |
| `GET /api/v1/audit` | Audit events |
| `POST /api/v1/lockout` | Engage or clear lockout |
| `GET /api/v1/status` | Aggregated operator dashboard snapshot |

Every mutating request carries an operator identity header (`X-PumaClaw-Operator`) and is risk-scored before execution. High-risk actions require an explicit confirmation token (`X-PumaClaw-Confirm: 1`) when lockout is clear; during lockout only unlock and read paths remain available.

### 3. Policy engine

`risk-policy` classifies actions:

| Action | Risk | Notes |
| --- | --- | --- |
| List / read | low | Always allowed for trusted operators |
| Start / pause session | medium | Confirm recommended |
| Approve network / exec | high | Confirm required |
| Stop session | high | Confirm required |
| Revoke device | high | Confirm required |
| Engage lockout | critical | Confirm required; freezes writes |

### 4. Gateway adapter

`gateway-adapter` translates control-plane intents into OpenClaw Gateway operator calls when a gateway URL is configured:

| PumaClaw intent | Gateway mapping |
| --- | --- |
| List sessions | `sessions.list` + `sessions.subscribe` |
| Start / stop | session lifecycle + `chat.send` / cancel paths |
| Approval inbox | `exec.approval.list` + approval events |
| Approve / deny | `exec.approval.resolve` / approval resolve RPC |
| Device trust | `device.pair.*` / node pairing surfaces |

v1 keeps the adapter pluggable. Demo mode uses an in-memory simulator that emits realistic latency, approvals, and sandbox health so partners can evaluate UX without a Gateway.

### 5. Discovery and auth stubs

Existing public discovery (`.well-known/*`, OAuth metadata, MCP card) continues to advertise the site. OAuth scopes already reserved for product APIs:

- `pumaclaw.discovery:read`
- `pumaclaw.sessions:read`
- `pumaclaw.sessions:write`

v1 APIs are early-access style: operator identity is demonstrated via headers in demo mode; production token exchange remains behind the published OAuth endpoints.

## Trust model

1. **Device** — trusted phone identity (demo devices seeded; live path pairs via Gateway device pairing).
2. **Operator** — human role bound to the device session.
3. **Action risk** — policy class for the requested mutation.
4. **Runtime posture** — sandbox health and lockout state from the control plane / NemoClaw path.

An action runs only when device + operator are trusted, risk checks pass, and lockout is not engaged (except unlock).

## Data model (v1)

```text
Session { id, name, mode, state, gatewayId, sandbox, startedAt, updatedAt }
Approval { id, sessionId, kind, summary, risk, status, createdAt, resolvedAt, resolver }
Device { id, label, platform, trusted, lastSeenAt }
AuditEvent { id, at, actor, action, target, risk, result, detail }
Lockout { engaged, reason, engagedAt, engagedBy }
```

## Deployment

| Mode | Behavior |
| --- | --- |
| Static / local preview | Console + client demo store |
| Cloudflare Pages | Console + `functions/api/v1/*` demo control plane |
| Connected | Same API + Gateway adapter pointed at a private OpenClaw URL |

## Non-goals for v1

- Full native iOS / Android store apps (PWA first)
- Multi-tenant hosted SaaS identity
- Replacing NemoClaw / OpenShell policy enforcement
- Public unauthenticated mutation APIs

## Related docs

- [API documentation](./api.md)
- [Operator skill](../.well-known/agent-skills/pumaclaw-operator/SKILL.md)
- OpenClaw Gateway clients: https://docs.openclaw.ai/gateway/clients
- NVIDIA NemoClaw overview: https://docs.nvidia.com/nemoclaw/