# KHY Mobile Agent Protocol (v1.0)

This guide defines the mobile-facing protocol for KHY-OS under the "local super-admin + remote SSH operator + mobile-safe translator" vision.

## 1. Design Goals

- Local data sovereignty: never send full source files or plaintext credentials to mobile.
- Risk-tier authorization: risky operations must generate approval tickets.
- Mobile-first streaming: concise, structured payloads for card-based rendering.
- Tri-end continuity: local desktop, mobile, and remote SSH session must share the same redaction and approval pipeline.

## 2. Canonical Schemas

Schema files:
- `backend/src/contracts/mobile/approval-ticket.schema.json`
- `backend/src/contracts/mobile/mobile-stream-event.schema.json`
- `backend/src/contracts/mobile/device-handover-snapshot.schema.json`

## 3. Outbound Stream Envelope

All mobile push events must conform to `mobile-stream-event.schema.json`.

Required top-level fields:
- `version`, `event_id`, `trace_id`, `sequence`, `ts`
- `stream`, `kind`, `severity`, `title`, `payload`
- `redaction_applied`

Supported `kind`:
- `status`
- `batch_step`
- `approval_ticket`
- `diff_preview`
- `test_result`
- `handover_snapshot`
- `task_state`
- `final_summary`

## 4. Approval Ticket Contract

Use `approval-ticket.schema.json` for high-risk actions.

Minimum required fields:
- `ticket_id`
- `risk_level`
- `requested_action`
- `target`
- `reason`
- `impact_summary`
- `command_preview`
- `expires_at`
- `choices` (`approve`, `reject`, `edit_then_approve`)

## 5. Cross-Device Handover Contract

Use `device-handover-snapshot.schema.json` when user switches between mobile, local terminal, and remote SSH environments.

Snapshot must include:
- Recent key actions (up to 3)
- Running background tasks
- Pending approvals
- Remaining todos

Recommended remote metadata (when applicable):
- Active SSH host alias
- Remote workspace path
- Remote session health (`connected` / `reconnecting` / `disconnected`)

## 6. Redaction Rules (Mandatory)

Before sending any payload to mobile:
- Replace secret-like values (`password`, `token`, `secret`, private keys) with masked form.
- For code changes, send diff excerpts only.
- For logs, send tail summary only (recommended max: last 10 lines).

## 7. Minimal Examples

### 7.1 `approval_ticket` stream event

```json
{
  "version": "1.0",
  "event_id": "ev_6jk4m9p2r1",
  "trace_id": "tr_20260516_6e9a3f21",
  "sequence": 25,
  "ts": "2026-05-16T10:31:12Z",
  "stream": "ops",
  "kind": "approval_ticket",
  "severity": "warn",
  "title": "High-risk operation approval",
  "payload": {
    "ticket_id": "ap_h8k2m9q1v4",
    "risk_level": "high",
    "requested_action": "Kill high-memory process",
    "target": "chromium-render (PID 892)",
    "reason": "Memory usage remains above threshold for 120s.",
    "impact_summary": "Process termination may lose unsaved renderer state.",
    "command_preview": ["kill -9 892"],
    "expires_at": "2026-05-16T10:35:00Z",
    "choices": ["approve", "reject", "edit_then_approve"]
  },
  "redaction_applied": true
}
```

### 7.2 `handover_snapshot` stream event

```json
{
  "version": "1.0",
  "event_id": "ev_91dzk2q4m6",
  "trace_id": "tr_20260516_6e9a3f21",
  "sequence": 42,
  "ts": "2026-05-16T11:00:00Z",
  "stream": "sync",
  "kind": "handover_snapshot",
  "severity": "info",
  "title": "Session handover snapshot",
  "payload": {
    "recent_actions": [
      "Killed stuck python training process (PID 882).",
      "Switched model to claude-3.5-sonnet and reran tests.",
      "Auth patch applied; git commit still pending."
    ],
    "background_tasks": [
      "npm run dev (PID 1024, port 8080)"
    ],
    "pending_approvals": [],
    "todos": [
      "Commit auth patch"
    ]
  },
  "redaction_applied": true
}
```
