@av-pi-studio/protocol 0.0.115 → 0.0.116

package/fixtures/external-clients/README.md

@@ -0,0 +1,94 @@
+# External-client wire fixtures
+
+Canonical JSON frames for every Pi Studio wire message that a client **outside this repository**
+consumes or sends (first consumer: the Rust Pi Studio Dashboard). They are the machine-checkable
+contract the Zod-only protocol cannot give: many list/stat/orchestration responses have no schema.
+
+- **Location (published):** `packages/protocol/fixtures/external-clients/` — shipped in the
+  `@av-pi-studio/protocol` npm package under `fixtures/external-clients/`. The path is part of the
+  contract; external vendoring scripts reference it verbatim.
+- **Consumer workflow:** copy this directory into your repo (record the pi-studio version or git
+  commit you copied from) and deserialize every fixture with your own types in your own tests.
+- **Enforcement here:** `src/external-fixtures.test.ts` (this package, no daemon) and
+  `packages/server/src/daemon/external-fixtures-e2e.test.ts` (an in-process dev daemon) fail when a
+  fixture is malformed, unlisted, schema-invalid, or no longer matches what the daemon really sends.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `manifest.json` | `{"formatVersion": N, "messages": [{"file","type","direction","response?","exception?"}]}` — lists every fixture; a file not in the manifest (or vice versa) fails the test |
+| `<type>[.<variant>].json` | One fixture per message type; a type with materially different shapes gets one file per variant (`agent_stream.tool_call.partial.json`, `agent_ui_request.confirm.json`) |
+| `CHANGELOG.md` | Dated entries for every breaking change (see below) |
+| `.signatures.json` | Generated shape signatures used by the breaking-change guard — never edit by hand |
+
+## Fixture format
+
+```jsonc
+{
+  "type": "agent_session_stats_response",       // the message `type`
+  "direction": "server_to_client",              // | "client_to_server" | "http" (health)
+  "description": "…",
+  "since": "0.0.115",                           // pi-studio version that introduced this shape
+  "stage": 1,                                   // informational (dashboard staging)
+  "requiresFeature": null,                      // e.g. "extensionUi": a status.features flag
+  "volatile": ["/message/requestId", "/message/payload/sessionId"],  // JSON Pointers into `frame`
+  "frame": { … }                                // the COMPLETE frame as sent on the socket
+}
+```
+
+- `frame` is the full top-level frame: `{"type":"session","message":{…}}` for session messages, the
+  bare `{"type":"status","payload":…}` / `{"type":"ping"}` / `{"type":"pong"}` forms for the rest.
+  For `health` (HTTP) it is `{status, contentType, body}`.
+- `volatile` lists JSON Pointers whose **values** change per run (ids, timestamps, counters, paths,
+  model names). Their presence and JSON type are still part of the contract; only the value is not
+  compared. Every other value is literal and compared exactly against the live daemon.
+- Arrays hold **one representative element**; the daemon may send more. `null` and an absent key
+  are different: a field shown as `null` is emitted as `null`.
+- `status.server_info.features` pins only a few stable flags; the daemon may send more.
+- Timestamps use the form the daemon emits: epoch milliseconds for `pong`, `agent_ui_*` and
+  `list_agents_response.lastActivity`; ISO-8601 strings for `agent_stream.timestamp` and
+  `agent_archived.archivedAt`.
+- Fixtures contain **no secrets**: no real tokens, passwords, hosts or home paths — use obviously
+  fake literals. The Layer A test scans for secret-looking keys.
+
+### Manifest `response` and `exception`
+
+- A `client_to_server` entry carries `response`: the fixture the daemon must answer with when the
+  request is sent (never `rpc_error`).
+- `exception` marks a fixture that **no daemon code path emits today** (schema only). It is
+  validated against its Zod schema but has no live-output check. A message with no Zod schema can
+  never be an exception. Current exceptions: `agent_status`, `agent_ui_resolved.cancelled`.
+- The tool-permission family (`agent_permission_*`, `agent.permission.respond.*`) was retired in
+  sprint-086 and deliberately has no fixtures.
+
+## Compatibility rule ("bump + note")
+
+These files are the published contract for clients outside this repo. Therefore:
+
+- **Additive change** — a new optional field, a new variant file, a new message: add or extend the
+  fixture. Nothing else is required; the live test accepts extra daemon fields.
+- **Breaking change** — a field removed, renamed or retyped (including narrowing, or optional →
+  required), a variant file removed, or a `requiresFeature` changed. Allowed only with **all** of:
+  1. the fixture edited in the same commit as the daemon/schema change;
+  2. `formatVersion` in `manifest.json` incremented **and** a dated entry in `CHANGELOG.md` naming
+     the changed file(s) and the migration for consumers;
+  3. a `COMPAT(...)` note if an older daemon still emits the old shape (MAIN-SCOPE § 9 already
+     forbids breaking wire changes — this makes the consequence mechanical for external readers).
+
+The signature guard enforces (2): it fails when a leaf path that existed in `.signatures.json` is
+missing or has a different JSON type in the current fixtures, unless `formatVersion` is higher than
+the recorded one and `CHANGELOG.md` mentions the file. Added leaves always pass.
+
+## Adding or changing a fixture
+
+1. Print a candidate from a real dev daemon (not run in CI):
+   `npm run build:server && node packages/server/scripts/record-external-fixtures.ts`
+   (`--write <dir>` writes `{ "frame": … }` candidates, never overwriting without `--force`).
+2. Author/edit `<type>[.<variant>].json` with the metadata above; canonicalize ids to fake values and
+   list every per-run value in `volatile`.
+3. Add it to `manifest.json` (with `response` for requests).
+4. Run `npx vitest run packages/protocol/src/external-fixtures.test.ts` and
+   `npx vitest run packages/server/src/daemon/external-fixtures-e2e.test.ts`.
+5. Regenerate signatures: `npm run fixtures:update -w @av-pi-studio/protocol`.
+6. Breaking change? Bump `formatVersion` first and add the `CHANGELOG.md` entry (rule above).

package/fixtures/external-clients/agent_archived.json

@@ -0,0 +1,17 @@
+{
+  "type": "agent_archived",
+  "direction": "server_to_client",
+  "description": "An agent was archived (soft delete).",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/archivedAt"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_archived",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "archivedAt": "2026-01-01T00:00:00.000Z"
+    }
+  }
+}

package/fixtures/external-clients/agent_deleted.json

@@ -0,0 +1,16 @@
+{
+  "type": "agent_deleted",
+  "direction": "server_to_client",
+  "description": "An agent was deleted.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_deleted",
+      "agentId": "00000000-0000-4000-8000-000000000001"
+    }
+  }
+}

package/fixtures/external-clients/agent_session_stats_request.json

@@ -0,0 +1,17 @@
+{
+  "type": "agent_session_stats_request",
+  "direction": "client_to_server",
+  "description": "Poll session statistics for one live agent.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/requestId", "/message/agentId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_session_stats_request",
+      "requestId": "req-1",
+      "agentId": "agent-1"
+    }
+  }
+}

package/fixtures/external-clients/agent_session_stats_response.json

@@ -0,0 +1,30 @@
+{
+  "type": "agent_session_stats_response",
+  "direction": "server_to_client",
+  "description": "Session statistics. payload is passthrough; the dev daemon's stable subset is pinned, a real Pi agent adds more fields.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": [
+    "/message/payload/sessionId",
+    "/message/payload/totalMessages",
+    "/message/requestId",
+    "/message/payload/model",
+    "/message/payload/tokens/total"
+  ],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_session_stats_response",
+      "payload": {
+        "sessionId": "00000000-0000-4000-8000-000000000001",
+        "totalMessages": 22,
+        "tokens": {
+          "total": 0
+        },
+        "model": "mock-model"
+      },
+      "requestId": "req-1"
+    }
+  }
+}

package/fixtures/external-clients/agent_status.json

@@ -0,0 +1,17 @@
+{
+  "type": "agent_status",
+  "direction": "server_to_client",
+  "description": "Agent status message. Defined by agentStatusMessageSchema but no daemon code path emits it today.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_status",
+      "agentId": "agent-1",
+      "status": "idle"
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.assistant_message.json

@@ -0,0 +1,29 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a assistant_message event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": [
+    "/message/agentId",
+    "/message/seq",
+    "/message/timestamp",
+    "/message/event/messageId"
+  ],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 2,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "assistant_message",
+        "messageId": "00000000-0000-4000-8000-000000000002",
+        "text": "echo: hello",
+        "final": true
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.compaction.json

@@ -0,0 +1,29 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "Context compaction lifecycle event (this one is the started phase).",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": "compactionEvents",
+  "volatile": [
+    "/message/agentId",
+    "/message/seq",
+    "/message/timestamp",
+    "/message/event/compactionId"
+  ],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 26,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "compaction",
+        "compactionId": "00000000-0000-4000-8000-000000000002",
+        "phase": "started",
+        "reason": "manual"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.error.json

@@ -0,0 +1,22 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a error event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/seq", "/message/timestamp"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 21,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "error",
+        "message": "mock stream error"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.reasoning.json

@@ -0,0 +1,22 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a reasoning event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/seq", "/message/timestamp"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 12,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "reasoning",
+        "text": "mock reasoning"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.tool_call.json

@@ -0,0 +1,27 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a tool_call event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/seq", "/message/timestamp", "/message/event/callId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 6,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "tool_call",
+        "callId": "00000000-0000-4000-8000-000000000002",
+        "status": "running",
+        "tool": {
+          "kind": "shell",
+          "command": "npm test"
+        }
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.tool_call.partial.json

@@ -0,0 +1,28 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "Ephemeral in-flight tool output snapshot: broadcast WITHOUT seq, never persisted or replayed; supersedes earlier output by callId.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/timestamp", "/message/event/callId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "tool_call",
+        "callId": "00000000-0000-4000-8000-000000000002",
+        "status": "running",
+        "partial": true,
+        "tool": {
+          "kind": "shell",
+          "command": "npm test",
+          "output": "> running suite A"
+        }
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.turn_canceled.json

@@ -0,0 +1,22 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a turn_canceled event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/seq", "/message/timestamp", "/message/event/turnId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 25,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "turn_canceled",
+        "turnId": "00000000-0000-4000-8000-000000000002"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.turn_completed.json

@@ -0,0 +1,22 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a turn_completed event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/seq", "/message/timestamp", "/message/event/turnId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 3,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "turn_completed",
+        "turnId": "00000000-0000-4000-8000-000000000002"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.turn_failed.json

@@ -0,0 +1,23 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a turn_failed event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/seq", "/message/timestamp", "/message/event/turnId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 18,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "turn_failed",
+        "turnId": "00000000-0000-4000-8000-000000000002",
+        "error": "mock turn failure"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.turn_started.json

@@ -0,0 +1,22 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a turn_started event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": ["/message/agentId", "/message/seq", "/message/timestamp", "/message/event/turnId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 1,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "turn_started",
+        "turnId": "00000000-0000-4000-8000-000000000002"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_stream.user_message.json

@@ -0,0 +1,28 @@
+{
+  "type": "agent_stream",
+  "direction": "server_to_client",
+  "description": "agent_stream frame carrying a user_message event.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": null,
+  "volatile": [
+    "/message/agentId",
+    "/message/seq",
+    "/message/timestamp",
+    "/message/event/messageId"
+  ],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_stream",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "seq": 0,
+      "timestamp": "2026-01-01T00:00:00.000Z",
+      "event": {
+        "kind": "user_message",
+        "messageId": "00000000-0000-4000-8000-000000000002",
+        "text": "hello"
+      }
+    }
+  }
+}

package/fixtures/external-clients/agent_timeline_reset.json

@@ -0,0 +1,17 @@
+{
+  "type": "agent_timeline_reset",
+  "direction": "server_to_client",
+  "description": "The agent's timeline was replaced (after a fork); clients must refetch it. No Zod schema.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": "forkTimelineSync",
+  "volatile": ["/message/agentId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_timeline_reset",
+      "agentId": "00000000-0000-4000-8000-000000000001",
+      "reason": "fork"
+    }
+  }
+}

package/fixtures/external-clients/agent_ui_list_request.json

@@ -0,0 +1,17 @@
+{
+  "type": "agent_ui_list_request",
+  "direction": "client_to_server",
+  "description": "Late-join catch-up: list pending dialogs and retained surfaces for one agent (omit agentId for all agents).",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": "extensionUi",
+  "volatile": ["/message/requestId", "/message/agentId"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_ui_list_request",
+      "requestId": "req-1",
+      "agentId": "agent-1"
+    }
+  }
+}

package/fixtures/external-clients/agent_ui_list_response.json

@@ -0,0 +1,50 @@
+{
+  "type": "agent_ui_list_response",
+  "direction": "server_to_client",
+  "description": "Pending dialogs and retained surfaces (each array holds one representative element).",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": "extensionUi",
+  "volatile": [
+    "/message/payload/pending/0/requestId",
+    "/message/payload/pending/0/agentId",
+    "/message/payload/pending/0/createdAt",
+    "/message/payload/surfaces/0/agentId",
+    "/message/payload/surfaces/0/updatedAt",
+    "/message/requestId"
+  ],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_ui_list_response",
+      "payload": {
+        "ok": true,
+        "pending": [
+          {
+            "requestId": "00000000-0000-4000-8000-000000000001",
+            "agentId": "00000000-0000-4000-8000-000000000002",
+            "method": "select",
+            "expectsResponse": true,
+            "payload": {
+              "title": "Pick one",
+              "options": ["a", "b"]
+            },
+            "createdAt": 1767225600000
+          }
+        ],
+        "surfaces": [
+          {
+            "agentId": "00000000-0000-4000-8000-000000000002",
+            "method": "setStatus",
+            "surfaceKey": "status:build",
+            "payload": {
+              "statusText": "building"
+            },
+            "updatedAt": 1767225600000
+          }
+        ]
+      },
+      "requestId": "req-1"
+    }
+  }
+}

package/fixtures/external-clients/agent_ui_request.confirm.json

@@ -0,0 +1,24 @@
+{
+  "type": "agent_ui_request",
+  "direction": "server_to_client",
+  "description": "Answerable dialog: yes/no (expectsResponse true).",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": "extensionUi",
+  "volatile": ["/message/requestId", "/message/agentId", "/message/createdAt"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_ui_request",
+      "requestId": "00000000-0000-4000-8000-000000000001",
+      "agentId": "00000000-0000-4000-8000-000000000002",
+      "method": "confirm",
+      "expectsResponse": true,
+      "payload": {
+        "title": "Proceed?",
+        "message": "Apply the change?"
+      },
+      "createdAt": 1767225600000
+    }
+  }
+}

package/fixtures/external-clients/agent_ui_request.editor.json

@@ -0,0 +1,24 @@
+{
+  "type": "agent_ui_request",
+  "direction": "server_to_client",
+  "description": "Multi-line editor dialog; the dashboard hands this off to the web client.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": "extensionUi",
+  "volatile": ["/message/requestId", "/message/agentId", "/message/createdAt"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_ui_request",
+      "requestId": "00000000-0000-4000-8000-000000000001",
+      "agentId": "00000000-0000-4000-8000-000000000002",
+      "method": "editor",
+      "expectsResponse": true,
+      "payload": {
+        "title": "Edit",
+        "prefill": "text"
+      },
+      "createdAt": 1767225600000
+    }
+  }
+}

package/fixtures/external-clients/agent_ui_request.input.json

@@ -0,0 +1,24 @@
+{
+  "type": "agent_ui_request",
+  "direction": "server_to_client",
+  "description": "Free-text dialog; the dashboard hands this off to the web client.",
+  "since": "0.0.115",
+  "stage": 1,
+  "requiresFeature": "extensionUi",
+  "volatile": ["/message/requestId", "/message/agentId", "/message/createdAt"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "agent_ui_request",
+      "requestId": "00000000-0000-4000-8000-000000000001",
+      "agentId": "00000000-0000-4000-8000-000000000002",
+      "method": "input",
+      "expectsResponse": true,
+      "payload": {
+        "title": "Name",
+        "placeholder": "name"
+      },
+      "createdAt": 1767225600000
+    }
+  }
+}