@av-pi-studio/protocol 0.0.116 → 0.0.118

package/dist/messages.js

@@ -22,8 +22,15 @@ export const wireTimestampSchema = z.union([z.number(), isoTimestampSchema]);
 // ===========================================================================
 // Handshake
 // ===========================================================================
-/** Client kinds that may connect. Desktop connects as `browser` (TODO(verify) MAIN-SCOPE). */
+/**
+ * Client kinds that may connect. The enum is CLOSED on purpose: a daemon up to 0.0.117 fails `hello`
+ * validation on an unknown value (silently on a relay connection), so a new kind of client must
+ * connect as one of these and say what it is through `hello.platform`. The desktop app connects as
+ * `browser` with `platform: "desktop"`.
+ */
 export const clientTypeSchema = z.enum(["mobile", "browser", "cli", "mcp"]);
+/** Longest `hello.platform` the daemon keeps; anything longer is dropped, not rejected. */
+export const PLATFORM_MAX_LENGTH = 32;
 /**
  * Client → Server handshake. Must be the first frame on a connection. `capabilities` advertises
  * the `CLIENT_CAPS.*` flags the client supports (a string→boolean map; see client-capabilities.ts).
@@ -33,6 +40,12 @@ export const helloSchema = z.object({
     clientId: z.string(),
     clientType: clientTypeSchema,
     protocolVersion: z.number(),
+    /**
+     * Free-form, lowercase platform label (`"desktop"`). Informational: nothing branches on it. An
+     * over-long or non-string value is DROPPED (the handshake still succeeds), and daemons that
+     * predate the field ignore it, so it is safe to send to any daemon.
+     */
+    platform: z.string().max(PLATFORM_MAX_LENGTH).optional().catch(undefined),
     appVersion: z.string().optional(),
     capabilities: z.record(z.string(), z.boolean()).optional(),
 });
@@ -1074,6 +1087,8 @@ export const daemonClientInfoSchema = z
     clientId: z.string(),
     clientType: z.string(),
     appVersion: z.string().optional(),
+    /** The hello's `platform`, when the client sent one. */
+    platform: z.string().optional(),
     connectedAt: z.number(),
     remoteAddress: z.string().optional(),
     transport: z.enum(["direct", "relay"]),
@@ -1654,6 +1669,26 @@ export const agentTodosUpdateSchema = z
 })
     .passthrough();
 // ===========================================================================
+// File transfer completion (sprint-096, features/desktop-client-protocol-followups.md § 2)
+// ===========================================================================
+// The `file_*` request/response RPCs and the binary frames carry no schemas of their own; this push
+// does because its two consumers (the SDK's `upload()` and external clients) both branch on `ok`.
+// Sent only to the session whose `file_upload_request` carried `ack: true`.
+/**
+ * Sent once to the uploading session after the target file was closed (`ok: true`) or the upload
+ * failed (`ok: false`, `error`). A partial file is left on disk after a failure.
+ */
+export const fileUploadCompleteSchema = z
+    .object({
+    type: z.literal("file_upload_complete"),
+    transferId: z.string(),
+    stream: z.number().int().nonnegative(),
+    ok: z.boolean(),
+    bytesWritten: z.number().int().nonnegative(),
+    error: z.string().optional(),
+})
+    .passthrough();
+// ===========================================================================
 // RPC error
 // ===========================================================================
 export const rpcErrorSchema = z.object({
@@ -1775,6 +1810,7 @@ export const sessionMessageSchema = z.discriminatedUnion("type", [
     agentTodosListRequestSchema,
     agentTodosListResponseSchema,
     agentTodosUpdateSchema,
+    fileUploadCompleteSchema,
     rpcErrorSchema,
 ]);
 /**

package/fixtures/external-clients/.signatures.json

@@ -323,6 +323,44 @@
       "/message/type": "string",
       "/type": "string"
     },
+    "capture_terminal_request.json": {
+      "/message/requestId": "string",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "capture_terminal_response.json": {
+      "/message/ok": "boolean",
+      "/message/requestId": "string",
+      "/message/screen": "string",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "create_terminal_request.json": {
+      "/message/cols": "number",
+      "/message/cwd": "string",
+      "/message/name": "string",
+      "/message/requestId": "string",
+      "/message/rows": "number",
+      "/message/shell": "string",
+      "/message/type": "string",
+      "/message/workspaceId": "string",
+      "/type": "string"
+    },
+    "create_terminal_response.json": {
+      "/message/requestId": "string",
+      "/message/terminal/closed": "boolean",
+      "/message/terminal/cols": "number",
+      "/message/terminal/cwd": "string",
+      "/message/terminal/name": "string",
+      "/message/terminal/rows": "number",
+      "/message/terminal/shell": "string",
+      "/message/terminal/slot": "number",
+      "/message/terminal/workspaceId": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
     "daemon_log_lines.json": {
       "/message/dropped": "number",
       "/message/lines/0/level": "string",
@@ -477,6 +515,58 @@
       "/message/type": "string",
       "/type": "string"
     },
+    "file_download_request.json": {
+      "/message/requestId": "string",
+      "/message/stream": "number",
+      "/message/token": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "file_download_response.json": {
+      "/message/ok": "boolean",
+      "/message/requestId": "string",
+      "/message/stream": "number",
+      "/message/transferId": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "file_download_token_request.json": {
+      "/message/path": "string",
+      "/message/requestId": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "file_download_token_response.json": {
+      "/message/expiresAt": "number",
+      "/message/ok": "boolean",
+      "/message/requestId": "string",
+      "/message/token": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "file_upload_complete.json": {
+      "/message/bytesWritten": "number",
+      "/message/ok": "boolean",
+      "/message/stream": "number",
+      "/message/transferId": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "file_upload_request.json": {
+      "/message/ack": "boolean",
+      "/message/path": "string",
+      "/message/requestId": "string",
+      "/message/transferId": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "file_upload_response.json": {
+      "/message/ok": "boolean",
+      "/message/requestId": "string",
+      "/message/stream": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
     "health.json": {
       "/body/status": "string",
       "/contentType": "string",
@@ -490,6 +580,15 @@
       "/protocolVersion": "number",
       "/type": "string"
     },
+    "hello.platform.json": {
+      "/appVersion": "string",
+      "/capabilities/reasoning_merge_enum": "boolean",
+      "/clientId": "string",
+      "/clientType": "string",
+      "/platform": "string",
+      "/protocolVersion": "number",
+      "/type": "string"
+    },
     "interrupt_agent.json": {
       "/message/agentId": "string",
       "/message/requestId": "string",
@@ -503,6 +602,19 @@
       "/message/type": "string",
       "/type": "string"
     },
+    "kill_terminal_request.json": {
+      "/message/requestId": "string",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "kill_terminal_response.json": {
+      "/message/ok": "boolean",
+      "/message/requestId": "string",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
     "list_agents_request.json": {
       "/message/requestId": "string",
       "/message/type": "string",
@@ -522,6 +634,24 @@
       "/message/type": "string",
       "/type": "string"
     },
+    "list_terminals_request.json": {
+      "/message/requestId": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "list_terminals_response.json": {
+      "/message/requestId": "string",
+      "/message/terminals/0/closed": "boolean",
+      "/message/terminals/0/cols": "number",
+      "/message/terminals/0/cwd": "string",
+      "/message/terminals/0/name": "string",
+      "/message/terminals/0/rows": "number",
+      "/message/terminals/0/shell": "string",
+      "/message/terminals/0/slot": "number",
+      "/message/terminals/0/workspaceId": "string",
+      "/message/type": "string",
+      "/type": "string"
+    },
     "ping.json": {
       "/clientSentAt": "number",
       "/requestId": "string",
@@ -534,6 +664,20 @@
       "/serverSentAt": "number",
       "/type": "string"
     },
+    "rename_terminal_request.json": {
+      "/message/name": "string",
+      "/message/requestId": "string",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "rename_terminal_response.json": {
+      "/message/ok": "boolean",
+      "/message/requestId": "string",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
     "rpc_error.json": {
       "/message/code": "string",
       "/message/message": "string",
@@ -554,6 +698,36 @@
       "/payload/status": "string",
       "/payload/version": "string",
       "/type": "string"
+    },
+    "subscribe_terminal_request.json": {
+      "/message/cols": "number",
+      "/message/requestId": "string",
+      "/message/rows": "number",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "subscribe_terminal_response.json": {
+      "/message/cols": "number",
+      "/message/ok": "boolean",
+      "/message/requestId": "string",
+      "/message/restoreMode": "string",
+      "/message/rows": "number",
+      "/message/slot": "number",
+      "/message/type": "string",
+      "/type": "string"
+    },
+    "terminals_update.json": {
+      "/message/terminals/0/closed": "boolean",
+      "/message/terminals/0/cols": "number",
+      "/message/terminals/0/cwd": "string",
+      "/message/terminals/0/name": "string",
+      "/message/terminals/0/rows": "number",
+      "/message/terminals/0/shell": "string",
+      "/message/terminals/0/slot": "number",
+      "/message/terminals/0/workspaceId": "string",
+      "/message/type": "string",
+      "/type": "string"
     }
   }
 }

package/fixtures/external-clients/CHANGELOG.md

@@ -16,3 +16,31 @@ Stage 2 fixtures, gated by `requiresFeature: "daemonObservability"` (pi-studio 0
 `daemon_status_unsubscribe_request`/`_response`, `daemon_status_update`,
 `daemon_logs_subscribe_request`/`_response`, `daemon_logs_unsubscribe_request`/`_response` and
 `daemon_log_lines`. New files only; no existing fixture changed, no migration.
+
+## Additive — 2026-11-14 (formatVersion stays 1)
+
+`hello.platform.json` (pi-studio 0.0.118): a `hello` variant carrying the new optional
+`platform` string. New file only; no existing fixture changed, no migration. `daemon_status`
+client entries may now also carry `platform` — a field present only when the client sent one, so
+the existing `daemon_status_*` fixtures are unchanged.
+
+## Additive — 2026-11-14 (formatVersion stays 1)
+
+File-transfer and terminal fixtures (pi-studio 0.0.118): `file_download_token_request`/`_response`,
+`file_download_request`/`_response`, `file_upload_request`/`_response`, `file_upload_complete`
+(`requiresFeature: "fileTransferAck"`, as is the upload request, which now shows `ack: true`),
+`create_terminal_request`/`_response`, `subscribe_terminal_request`/`_response`,
+`list_terminals_request`/`_response`, `rename_terminal_request`/`_response`,
+`capture_terminal_request`/`_response`, `kill_terminal_request`/`_response` and `terminals_update`.
+New files only; no existing fixture changed, no migration. The binary frames are fixtured separately
+(next entry).
+
+## Additive — 2026-11-14, binary frames (`binary/`, its own formatVersion 1)
+
+`binary/` (pi-studio 0.0.118): `manifest.json` (`formatVersion` 1, independent of the JSON
+manifest's) plus nine frame fixtures — file transfer `Begin`/`Chunk`/`End`/`Error` and terminal
+`Output`/`Input`/`Resize`/`Snapshot`/`Restore` — each a complete frame as `hex` with its `decoded`
+form. New files in a new subdirectory only: `manifest.json`, its `formatVersion` and every JSON
+fixture are untouched, no migration. A consumer that vendors this directory wholesale needs no
+change; one that lists top-level `*.json` against `manifest.json` is unaffected because the new
+files are not top-level.

package/fixtures/external-clients/README.md

@@ -61,6 +61,58 @@ contract the Zod-only protocol cannot give: many list/stat/orchestration respons
   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.
+- File-transfer and terminal fixtures (since 0.0.118) cover the JSON control frames only: the
+  `file_download_*`/`file_upload_*` RPCs, `file_upload_complete` (gated by `fileTransferAck`, as is
+  the `ack` upload request) and the `*_terminal_*` RPCs plus the `terminals_update` broadcast.
+  Most of these have no Zod schema, so Layer B is their guard. Download tokens appear as the literal
+  `"FAKE"` (volatile). The binary frames are fixtured separately, see "Binary frames" below.
+
+## Binary frames
+
+File-transfer and terminal data travel in binary frames, not JSON. Their fixtures live in the
+**`binary/` subdirectory** (since 0.0.118), with their own manifest and their own `formatVersion`
+(starting at 1), so `manifest.json` and the JSON `formatVersion` are untouched. They are in a
+subdirectory on purpose: a consumer that checks "every top-level `*.json` is listed in
+`manifest.json`" (the Rust dashboard's vendored-fixture test does) would fail on top-level binary
+files. A plain `rsync -a --delete` of this directory carries `binary/` along harmlessly.
+
+| File | Purpose |
+|---|---|
+| `binary/manifest.json` | `{"formatVersion": 1, "frames": [{"file","family","opcode","direction"}]}` — lists the nine frame fixtures; the test fails on an unlisted or missing file |
+| `binary/<family>.<opcode>.json` | One fixture per frame: `file_transfer.{begin,chunk,end,error}`, `terminal.{output,input,resize,snapshot,restore}` |
+
+```jsonc
+{
+  "family": "file_transfer",   // | "terminal"
+  "opcode": "Chunk",
+  "direction": "both",         // | "server_to_client" | "client_to_server"
+  "description": "…",
+  "since": "0.0.118",
+  "hex": "11 03 68 65 6c 6c 6f",             // the COMPLETE frame: opcode, stream/slot, payload
+  "decoded": { "opcode": "Chunk", "stream": 3, "dataHex": "68 65 6c 6c 6f" }
+}
+```
+
+- Frame layout is `[opcode][stream or slot][payload]`. File-transfer opcodes: `Begin` 0x10,
+  `Chunk` 0x11, `End` 0x12, `Error` 0x13. Terminal opcodes: `Output` 0x01, `Input` 0x02,
+  `Resize` 0x03, `Snapshot` 0x04, `Restore` 0x05. File-transfer frames are valid in **both**
+  directions (a download is daemon → client, an upload client → daemon).
+- `decoded` is the typed frame. Raw payloads (`Chunk`, `Output`, `Input`, `Snapshot`, `Restore`)
+  appear as `dataHex`; `Begin` carries its metadata object, `End` an `ok` boolean, `Error` a
+  `message`, `Resize` `rows` and `cols`.
+- **How to use them.** Decode every `hex` with your own codec and compare with `decoded`; encode
+  `decoded` with your own codec and compare with `hex`. For `Begin` and `Resize`, whose payload is
+  JSON, compare the *parsed* payload rather than the bytes: key order and whitespace are not part of
+  the contract (the fixtures show what the TypeScript codec writes). `Snapshot` and `Restore`
+  payloads are opaque to the codec; the bytes shown are stand-ins.
+- Layer A for binary frames is `src/external-binary-fixtures.test.ts`: it decodes each `hex` with the
+  real codec, encodes `decoded` back to the same bytes, checks the first byte against a table of the
+  wire opcode values, and fails on an unlisted or missing file. There is no live-daemon layer.
+- **Breaking-change rule.** A change to an existing frame's `hex` (a different opcode byte, header
+  or payload encoding) or to the `decoded` shape is breaking: bump `formatVersion` in
+  `binary/manifest.json` and add a dated `CHANGELOG.md` entry naming the file. A new frame fixture
+  is additive. This rule is enforced by review and by the round-trip test (a codec edit that moves
+  the bytes fails it); there is no signature guard for binary fixtures.
 
 ## Compatibility rule ("bump + note")
 

package/fixtures/external-clients/binary/file_transfer.begin.json

@@ -0,0 +1,18 @@
+{
+  "family": "file_transfer",
+  "opcode": "Begin",
+  "direction": "both",
+  "description": "Opens a transfer: JSON metadata after the two-byte header. Sent by the daemon before a download and by the client before an upload. `transferId` ties an upload to its `file_upload_request`; `totalBytes` is optional.",
+  "since": "0.0.118",
+  "hex": "10 03 7b 22 74 72 61 6e 73 66 65 72 49 64 22 3a 22 74 72 61 6e 73 66 65 72 2d 31 22 2c 22 66 69 6c 65 4e 61 6d 65 22 3a 22 68 65 6c 6c 6f 2e 74 78 74 22 2c 22 6d 69 6d 65 54 79 70 65 22 3a 22 74 65 78 74 2f 70 6c 61 69 6e 22 2c 22 74 6f 74 61 6c 42 79 74 65 73 22 3a 35 7d",
+  "decoded": {
+    "opcode": "Begin",
+    "stream": 3,
+    "meta": {
+      "transferId": "transfer-1",
+      "fileName": "hello.txt",
+      "mimeType": "text/plain",
+      "totalBytes": 5
+    }
+  }
+}

package/fixtures/external-clients/binary/file_transfer.chunk.json

@@ -0,0 +1,13 @@
+{
+  "family": "file_transfer",
+  "opcode": "Chunk",
+  "direction": "both",
+  "description": "Raw file bytes after the header. Senders cut chunks at 32 KiB; the codec accepts any length.",
+  "since": "0.0.118",
+  "hex": "11 03 68 65 6c 6c 6f",
+  "decoded": {
+    "opcode": "Chunk",
+    "stream": 3,
+    "dataHex": "68 65 6c 6c 6f"
+  }
+}

package/fixtures/external-clients/binary/file_transfer.end.json

@@ -0,0 +1,13 @@
+{
+  "family": "file_transfer",
+  "opcode": "End",
+  "direction": "both",
+  "description": "Completion marker: one payload byte, 1 = ok, 0 = aborted. The daemon sends no End after an Error.",
+  "since": "0.0.118",
+  "hex": "12 03 01",
+  "decoded": {
+    "opcode": "End",
+    "stream": 3,
+    "ok": true
+  }
+}

package/fixtures/external-clients/binary/file_transfer.error.json

@@ -0,0 +1,13 @@
+{
+  "family": "file_transfer",
+  "opcode": "Error",
+  "direction": "both",
+  "description": "Aborts a transfer: UTF-8 message after the header. The daemon sends it on a download read error (message `read_failed`) and a client sends it to cancel an upload; no End follows.",
+  "since": "0.0.118",
+  "hex": "13 03 72 65 61 64 5f 66 61 69 6c 65 64",
+  "decoded": {
+    "opcode": "Error",
+    "stream": 3,
+    "message": "read_failed"
+  }
+}

package/fixtures/external-clients/binary/manifest.json

@@ -0,0 +1,59 @@
+{
+  "formatVersion": 1,
+  "frames": [
+    {
+      "file": "file_transfer.begin.json",
+      "family": "file_transfer",
+      "opcode": "Begin",
+      "direction": "both"
+    },
+    {
+      "file": "file_transfer.chunk.json",
+      "family": "file_transfer",
+      "opcode": "Chunk",
+      "direction": "both"
+    },
+    {
+      "file": "file_transfer.end.json",
+      "family": "file_transfer",
+      "opcode": "End",
+      "direction": "both"
+    },
+    {
+      "file": "file_transfer.error.json",
+      "family": "file_transfer",
+      "opcode": "Error",
+      "direction": "both"
+    },
+    {
+      "file": "terminal.output.json",
+      "family": "terminal",
+      "opcode": "Output",
+      "direction": "server_to_client"
+    },
+    {
+      "file": "terminal.input.json",
+      "family": "terminal",
+      "opcode": "Input",
+      "direction": "client_to_server"
+    },
+    {
+      "file": "terminal.resize.json",
+      "family": "terminal",
+      "opcode": "Resize",
+      "direction": "client_to_server"
+    },
+    {
+      "file": "terminal.snapshot.json",
+      "family": "terminal",
+      "opcode": "Snapshot",
+      "direction": "server_to_client"
+    },
+    {
+      "file": "terminal.restore.json",
+      "family": "terminal",
+      "opcode": "Restore",
+      "direction": "server_to_client"
+    }
+  ]
+}

package/fixtures/external-clients/binary/terminal.input.json

@@ -0,0 +1,13 @@
+{
+  "family": "terminal",
+  "opcode": "Input",
+  "direction": "client_to_server",
+  "description": "Keystrokes for one slot, passed through verbatim to the PTY.",
+  "since": "0.0.118",
+  "hex": "02 01 6c 73 0d",
+  "decoded": {
+    "opcode": "Input",
+    "slot": 1,
+    "dataHex": "6c 73 0d"
+  }
+}

package/fixtures/external-clients/binary/terminal.output.json

@@ -0,0 +1,13 @@
+{
+  "family": "terminal",
+  "opcode": "Output",
+  "direction": "server_to_client",
+  "description": "Terminal output bytes for one subscribed slot, passed through verbatim (here: green text, then a CRLF).",
+  "since": "0.0.118",
+  "hex": "01 01 1b 5b 33 32 6d 6f 6b 1b 5b 30 6d 0d 0a",
+  "decoded": {
+    "opcode": "Output",
+    "slot": 1,
+    "dataHex": "1b 5b 33 32 6d 6f 6b 1b 5b 30 6d 0d 0a"
+  }
+}

package/fixtures/external-clients/binary/terminal.resize.json

@@ -0,0 +1,14 @@
+{
+  "family": "terminal",
+  "opcode": "Resize",
+  "direction": "client_to_server",
+  "description": "Window size for one slot: UTF-8 JSON `{rows, cols}` after the header.",
+  "since": "0.0.118",
+  "hex": "03 01 7b 22 72 6f 77 73 22 3a 32 34 2c 22 63 6f 6c 73 22 3a 38 30 7d",
+  "decoded": {
+    "opcode": "Resize",
+    "slot": 1,
+    "rows": 24,
+    "cols": 80
+  }
+}

package/fixtures/external-clients/binary/terminal.restore.json

@@ -0,0 +1,13 @@
+{
+  "family": "terminal",
+  "opcode": "Restore",
+  "direction": "server_to_client",
+  "description": "Reflowable-tier restore, sent only to a client that advertised `terminal_reflowable_snapshot`: a serialization of the daemon screen model. The payload is opaque to the codec; the text here is a stand-in.",
+  "since": "0.0.118",
+  "hex": "05 01 72 65 73 74 6f 72 65 2d 70 61 79 6c 6f 61 64",
+  "decoded": {
+    "opcode": "Restore",
+    "slot": 1,
+    "dataHex": "72 65 73 74 6f 72 65 2d 70 61 79 6c 6f 61 64"
+  }
+}

package/fixtures/external-clients/binary/terminal.snapshot.json

@@ -0,0 +1,13 @@
+{
+  "family": "terminal",
+  "opcode": "Snapshot",
+  "direction": "server_to_client",
+  "description": "Raw-tier restore for a subscription that did not negotiate `terminal_reflowable_snapshot`: the screen as bytes to replay. The payload is opaque to the codec.",
+  "since": "0.0.118",
+  "hex": "04 01 24 20",
+  "decoded": {
+    "opcode": "Snapshot",
+    "slot": 1,
+    "dataHex": "24 20"
+  }
+}

package/fixtures/external-clients/capture_terminal_request.json

@@ -0,0 +1,17 @@
+{
+  "type": "capture_terminal_request",
+  "direction": "client_to_server",
+  "description": "One-shot screen text of a terminal; does not subscribe.",
+  "since": "0.0.118",
+  "stage": 3,
+  "requiresFeature": null,
+  "volatile": ["/message/requestId", "/message/slot"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "capture_terminal_request",
+      "requestId": "req-1",
+      "slot": 1
+    }
+  }
+}

package/fixtures/external-clients/capture_terminal_response.json

@@ -0,0 +1,19 @@
+{
+  "type": "capture_terminal_response",
+  "direction": "server_to_client",
+  "description": "Current screen text; `ok:false` with an empty `screen` when the slot does not exist.",
+  "since": "0.0.118",
+  "stage": 3,
+  "requiresFeature": null,
+  "volatile": ["/message/requestId", "/message/slot", "/message/screen"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "capture_terminal_response",
+      "slot": 1,
+      "ok": true,
+      "screen": "$ ",
+      "requestId": "req-1"
+    }
+  }
+}

package/fixtures/external-clients/create_terminal_request.json

@@ -0,0 +1,22 @@
+{
+  "type": "create_terminal_request",
+  "direction": "client_to_server",
+  "description": "Spawn a PTY terminal. `shell`, `cwd`, `name`, `cols` and `rows` are optional.",
+  "since": "0.0.118",
+  "stage": 3,
+  "requiresFeature": null,
+  "volatile": ["/message/requestId", "/message/cwd"],
+  "frame": {
+    "type": "session",
+    "message": {
+      "type": "create_terminal_request",
+      "requestId": "req-1",
+      "workspaceId": "workspace-1",
+      "cwd": "/tmp/pi-studio-fixture",
+      "shell": "/bin/sh",
+      "name": "terminal-1",
+      "cols": 80,
+      "rows": 24
+    }
+  }
+}