Orb P0 S3: GET /api/device/v1/events SSE (name-keyed upserts, resume, revoke closes, demo stops on switch-off)

changelog.d/tsk-22jk4c-device-state-owner-filter.md

@@ -0,0 +1,3 @@
+### Fixed
+
+- `GET /api/device/v1/state` now filters pending decisions by device owner, preventing a device paired to one owner from seeing another owner's pending decisions through a shared (no `user_id`) agent.

changelog.d/tsk-3nh2c4-device-v1-events.md

@@ -0,0 +1,13 @@
+### Added
+
+- `GET /api/device/v1/events` (scope `agents:read`, device bearer) emits
+  Server-Sent Events of owner-filtered agent state changes: `agent.upsert`
+  (name-keyed, full object including `avatar: {hue, hash}`), `agent.remove`,
+  `decision.open`, `decision.close`, `agent.recap`, and a `snapshot` event
+  when the client's `Last-Event-ID` is older than stream history. Heartbeat
+  is a comment line `: ping` every 15 seconds.
+
+### Security
+
+- Revoking the device or losing the `agents:read` scope closes open SSE
+  streams immediately (re-checked on every loop tick).

changelog.d/tsk-3vxguh-lock-widgets-pure-status.md

@@ -0,0 +1,4 @@
+### Fixed
+
+- `/auth/lock-widgets` now returns an empty string for an agent's status when no live container is present, instead of falling back to the configured `status` value. This keeps the pre-auth console endpoint pure and prevents config-derived status leakage before sign-in.
+- `GET /api/device/v1/state` `demo` flag now uses the existing `_demo_enabled` helper instead of reading the env flag directly, matching the rest of the lock-screen demo paths.

changelog.d/tsk-aa5qck-agent-avatars-module.md

@@ -0,0 +1,3 @@
+### Changed
+
+- Extracted avatar slug and avatar directory logic from `tinyagentos/routes/auth.py` into a new `tinyagentos/agent_avatars.py` module, and added `avatar_source_path` and `avatar_hash` helpers.

changelog.d/tsk-ypsu2z-device-v1-state.md

@@ -0,0 +1,7 @@
+### Added
+
+- GET `/api/device/v1/state` (device bearer, scope `agents:read`): returns the owner-filtered agent list for the paired device, plus `server.version`, `time`, and `demo` flag. Server-side string caps (name 48, status 120, `last_recap` 180, question 280, option 40) with trailing ellipsis. `avatar.hash` is the first 16 hex chars of the avatar image SHA-256, or null when no image is installed.
+
+### Security
+
+- `/api/device/v1/state` is registered in the device-bearer allowlist (`_DEVICE_BEARER_PATHS`) and is CSRF-exempt like the other device-bearer routes. Only a `taosdev_...` bearer with the `agents:read` scope may reach it; missing scope returns 403 with `device_scope_missing`.

docs/agent-coordination.md

@@ -993,6 +993,18 @@ approval channel for privileged grants. Device scoped tokens do not expire and
 cannot be self-rotated; the only revocation is `DELETE /api/devices/{id}` from
 a session.
 
+The device-bearer self-service allowlist in `tinyagentos/auth_middleware.py`
+covers:
+
+- `PATCH /api/devices/{id}/push-token` — scope `push:register`
+- `GET /api/decisions`, `GET /api/decisions/{id}`, `GET /api/decisions/{id}/history` — scope `agents:read`
+- `POST /api/decisions/{id}/answer` — scope `decisions:answer`
+- `POST /api/library/ingest` — scope `library:ingest`
+- `POST /api/projects/{slug}/files/upload` — scope `files:upload`
+- `POST /api/chat/messages` — scope `chat:send`
+- `POST /api/device/v1/voice`, `POST /api/device/v1/voice/tts` — scope `voice:stt` / `voice:tts`
+- `GET /api/device/v1/state` — scope `agents:read` (owner-filtered agent list)
+
 ## Share destinations (device bearer)
 
 `GET /api/share/destinations` lets a paired device DISCOVER share destinations. It is

docs/routes.d/16-device-v1.md

@@ -5,3 +5,93 @@ are bearer-authenticated. The following routes are public (no bearer token):
 
 - `POST /api/devices/pair-requests`
 - `GET /api/devices/pair-requests/{pair_request_id}`
+
+### GET /api/device/v1/state
+
+**Scope:** `agents:read` (device bearer).
+
+Returns the owner-filtered agent list for the paired device, plus the server
+version, current time, and demo flag.
+
+**Response 200:**
+
+All string fields are server-side capped with a trailing ellipsis when they
+exceed the limit: `name` 48, `status` 120, `last_recap` 180, `question` 280,
+each `option` 40.
+
+```json
+{
+  "agents": [
+    {
+      "name": "alice-agent",
+      "status": "running",
+      "framework": "openclaw",
+      "avatar": {
+        "hue": 123,
+        "hash": "abc123def4567890"
+      },
+      "attention": true,
+      "last_recap": "recapped message...",
+      "decision": {
+        "id": "",
+        "question": "Ship it?",
+        "options": ["Approve", "Deny"]
+      }
+    }
+  ],
+  "server": {
+    "version": "1.0.0-beta.55"
+  },
+  "time": 1727640000.123,
+  "demo": false
+}
+```
+
+**Error codes:**
+
+- `401` -- missing or invalid device bearer.
+- `403` -- FastAPI's wrapper: `{"detail": {"error": "device_scope_missing", "scope": "agents:read"}}` when the device token lacks the required scope.
+
+### GET /api/device/v1/events
+
+**Scope:** `agents:read` (device bearer).
+
+Server-Sent Events stream of owner-filtered agent state changes for the
+paired device. The stream emits one event per change and a heartbeat comment
+every 15 seconds. Events are name-keyed: every event's data carries the
+agent `name` key.
+
+**Event names and data shapes:**
+
+- `agent.upsert` -- an agent appeared or its object changed. Data is the
+  full agent object (same shape as one `agents[]` entry of the state body,
+  including `avatar: {hue, hash}`). Emitted on connect for every current
+  agent so a fresh client can build state from typed events alone.
+- `agent.remove` -- an agent disappeared. Data: `{"name": "<agent name>"}`.
+- `decision.open` -- a pending decision appeared for an agent. Data:
+  `{"name": "<agent name>", "decision": {...}}`.
+- `decision.close` -- an agent's pending decision was resolved. Data:
+  `{"name": "<agent name>"}`.
+- `agent.recap` -- an agent's `last_recap` changed. Data:
+  `{"name": "<agent name>", "last_recap": "<text>"}`.
+- `snapshot` -- full state body, sent only when the client's `Last-Event-ID`
+  is older than the stream's current history. Data is the same shape as the
+  state endpoint response.
+
+**Heartbeat:**
+
+A comment line `: ping` is emitted every 15 seconds (configurable via
+`_HEARTBEAT_INTERVAL_S`). Each heartbeat carries an increasing `id:` field.
+
+**Resume and snapshot behaviour:**
+
+The client may send `Last-Event-ID` to resume. If the ID is older than what
+the stream still holds, the server sends one `snapshot` event and then
+continues with typed events from the current state. Fresh connects (no
+`Last-Event-ID` or `Last-Event-ID: 0`) start directly with typed
+`agent.upsert` events and do not receive a snapshot.
+
+**Close-on-revoke:**
+
+The stream re-checks the device bearer token on every loop tick. If the
+device is revoked or the scope is lost, the stream closes immediately.

docs/routes.md

@@ -419,3 +419,93 @@ are bearer-authenticated. The following routes are public (no bearer token):
 
 - `POST /api/devices/pair-requests`
 - `GET /api/devices/pair-requests/{pair_request_id}`
+
+### GET /api/device/v1/state
+
+**Scope:** `agents:read` (device bearer).
+
+Returns the owner-filtered agent list for the paired device, plus the server
+version, current time, and demo flag.
+
+**Response 200:**
+
+All string fields are server-side capped with a trailing ellipsis when they
+exceed the limit: `name` 48, `status` 120, `last_recap` 180, `question` 280,
+each `option` 40.
+
+```json
+{
+  "agents": [
+    {
+      "name": "alice-agent",
+      "status": "running",
+      "framework": "openclaw",
+      "avatar": {
+        "hue": 123,
+        "hash": "abc123def4567890"
+      },
+      "attention": true,
+      "last_recap": "recapped message...",
+      "decision": {
+        "id": "",
+        "question": "Ship it?",
+        "options": ["Approve", "Deny"]
+      }
+    }
+  ],
+  "server": {
+    "version": "1.0.0-beta.55"
+  },
+  "time": 1727640000.123,
+  "demo": false
+}
+```
+
+**Error codes:**
+
+- `401` -- missing or invalid device bearer.
+- `403` -- FastAPI's wrapper: `{"detail": {"error": "device_scope_missing", "scope": "agents:read"}}` when the device token lacks the required scope.
+
+### GET /api/device/v1/events
+
+**Scope:** `agents:read` (device bearer).
+
+Server-Sent Events stream of owner-filtered agent state changes for the
+paired device. The stream emits one event per change and a heartbeat comment
+every 15 seconds. Events are name-keyed: every event's data carries the
+agent `name` key.
+
+**Event names and data shapes:**
+
+- `agent.upsert` -- an agent appeared or its object changed. Data is the
+  full agent object (same shape as one `agents[]` entry of the state body,
+  including `avatar: {hue, hash}`). Emitted on connect for every current
+  agent so a fresh client can build state from typed events alone.
+- `agent.remove` -- an agent disappeared. Data: `{"name": "<agent name>"}`.
+- `decision.open` -- a pending decision appeared for an agent. Data:
+  `{"name": "<agent name>", "decision": {...}}`.
+- `decision.close` -- an agent's pending decision was resolved. Data:
+  `{"name": "<agent name>"}`.
+- `agent.recap` -- an agent's `last_recap` changed. Data:
+  `{"name": "<agent name>", "last_recap": "<text>"}`.
+- `snapshot` -- full state body, sent only when the client's `Last-Event-ID`
+  is older than the stream's current history. Data is the same shape as the
+  state endpoint response.
+
+**Heartbeat:**
+
+A comment line `: ping` is emitted every 15 seconds (configurable via
+`_HEARTBEAT_INTERVAL_S`). Each heartbeat carries an increasing `id:` field.
+
+**Resume and snapshot behaviour:**
+
+The client may send `Last-Event-ID` to resume. If the ID is older than what
+the stream still holds, the server sends one `snapshot` event and then
+continues with typed events from the current state. Fresh connects (no
+`Last-Event-ID` or `Last-Event-ID: 0`) start directly with typed
+`agent.upsert` events and do not receive a snapshot.
+
+**Close-on-revoke:**
+
+The stream re-checks the device bearer token on every loop tick. If the
+device is revoked or the scope is lost, the stream closes immediately.

tests/test_agent_avatars.py

@@ -0,0 +1,45 @@
+"""Tests for tinyagentos.agent_avatars module (avatar_source_path + avatar_hash)."""
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+
+import pytest
+
+from tinyagentos import agent_avatars as aa
+from tinyagentos.agent_avatars import avatar_hash, avatar_source_path
+from tinyagentos.routes.auth import _avatar_slug
+
+
+class TestAvatarSourcePathAndHash:
+
+    def test_no_jpg_returns_none(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(aa, "LOCK_AVATAR_DIR", str(tmp_path))
+        assert avatar_source_path("Some Agent") is None
+        assert avatar_hash("Some Agent") is None
+
+    def test_existing_jpg_returns_path_and_hash(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(aa, "LOCK_AVATAR_DIR", str(tmp_path))
+        name = "Some Agent"
+        slug = _avatar_slug(name)
+        (tmp_path / f"{slug}.jpg").write_bytes(b"one")
+        assert avatar_source_path(name) == tmp_path / f"{slug}.jpg"
+        h = avatar_hash(name)
+        assert isinstance(h, str)
+        assert len(h) == 16
+        assert h == hashlib.sha256(b"one").hexdigest()[:16]
+
+    def test_hash_changes_when_file_changes(self, tmp_path, monkeypatch):
+        monkeypatch.setattr(aa, "LOCK_AVATAR_DIR", str(tmp_path))
+        name = "Some Agent"
+        slug = _avatar_slug(name)
+        p = tmp_path / f"{slug}.jpg"
+        p.write_bytes(b"one")
+        first = avatar_hash(name)
+        p.write_bytes(b"two")
+        second = avatar_hash(name)
+        assert first != second
+
+    def test_imported_slug_matches_module_slug(self):
+        name = "Some Agent"
+        assert _avatar_slug(name) == aa._avatar_slug(name)