worktrust 0.11.0 → 0.11.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -644,12 +644,203 @@ export function availableActions(report ) {
644
644
  };
645
645
  }
646
646
 
647
+ /**
648
+ * The report a session or a start means: its adapter in its mode (release 19: one adapter may be reported twice, structured
649
+ * and terminal). An absent mode is structured, as every report before release 19 was.
650
+ */
651
+ export function reportFor (reports , adapter , mode ) {
652
+ const want = mode ?? "structured";
653
+ return reports?.find((r) => r.adapter === adapter && r.mode === want) ?? null;
654
+ }
655
+
647
656
  /** A model may be named only if the computer listed it; null asks for the agent's own default. */
648
657
  export function isModelReported(report , model ) {
649
658
  if (model === null) return true;
650
659
  return report.models !== null && report.models.includes(model);
651
660
  }
652
661
 
662
+ // ---- packages/remote-protocol/src/transfer.ts
663
+ /**
664
+ * FILES FROM THE PHONE, AND A LOCAL PREVIEW BACK (owner, 2026-11-07 22:50). docs/remote-agents/PROTOCOL.md "Attachments"
665
+ * and "Local preview". Everything here is sealed: the relay sees the types, their timing and size classes, never a name,
666
+ * a byte of a file or of a picture.
667
+ *
668
+ * ATTACHMENTS. An image, a PDF or a document travels in chunks of at most 512 KiB (`attachment.put`), each naming the whole
669
+ * file's size, its chunk count and its SHA-256; the computer keeps the chunks apart, joins them when all arrived, checks the
670
+ * hash and that the bytes are what the type says (a PNG starts like a PNG), and only then writes ONE file into the
671
+ * session's project at `.worktrust/inbox/<session_id>/<safe name>` (mode 0600, never executable). `attachment.stored`
672
+ * answers every chunk with the count received (a measured progress) and, once whole, the file's path relative to the
673
+ * project, which a later `agent.start` / `agent.prompt` names by its id (`attachments`), so the agent is told to read it.
674
+ * Caps: 25 MB a file, 100 MB a session. `attachment.clear` deletes the session's inbox.
675
+ *
676
+ * LOCAL PREVIEW. The phone's "Deploy" segment is a LOCAL preview, never a production deploy: `preview.render` asks the
677
+ * computer to render a page of a dev server on 127.0.0.1 at a port the person granted for that project at the keyboard
678
+ * (`worktrust remote preview allow <port>`), or a built HTML file in the project the person granted, at a phone, tablet or
679
+ * desktop viewport, with the person's own installed Chrome or Chromium (headless; nothing is installed). The answer is a
680
+ * PNG in chunks (`preview.image`) and its record (`preview.rendered`: the page's title and HTTP status as the computer saw
681
+ * them). `preview.targets` lists what is granted and whether something listens. Never a URL the phone writes, never
682
+ * another host, never a port forward.
683
+ */
684
+
685
+ export const ATTACHMENT_CHUNK_BYTES = 524_288;
686
+ export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
687
+ export const MAX_SESSION_ATTACHMENT_BYTES = 100 * 1024 * 1024;
688
+ export const MAX_ATTACHMENT_CHUNKS = Math.ceil(MAX_ATTACHMENT_BYTES / ATTACHMENT_CHUNK_BYTES);
689
+ export const ATTACHMENT_TYPES = [
690
+ "image/png", "image/jpeg", "image/heic", "image/webp", "application/pdf", "text/plain", "text/markdown", "text/csv",
691
+ "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
692
+ "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
693
+ ] ;
694
+
695
+ export const MAX_ATTACHMENTS_PER_PROMPT = 20;
696
+
697
+ export const PREVIEW_VIEWPORTS = { mobile: { width: 390, height: 844 }, tablet: { width: 820, height: 1180 }, desktop: { width: 1440, height: 900 } } ;
698
+ export const PREVIEW_CHUNK_BYTES = 524_288;
699
+ export const MAX_PREVIEW_BYTES = 8 * 1024 * 1024;
700
+ export const MAX_PREVIEW_CHUNKS = Math.ceil(MAX_PREVIEW_BYTES / PREVIEW_CHUNK_BYTES);
701
+ /** A path on the granted dev server: starts with one slash, URL characters only, never `//` (another host). */
702
+ export const PREVIEW_PATH = /^\/(?!\/)[A-Za-z0-9._~!$&'()*+,;=:@%\/?#-]{0,299}$/;
703
+
704
+ export const TRANSFER_COMMAND_SPECS = {
705
+ "attachment.put": object({
706
+ attachment_id: id("att"),
707
+ name: text(200, 1),
708
+ content_type: oneOf(ATTACHMENT_TYPES),
709
+ size: int(1, MAX_ATTACHMENT_BYTES),
710
+ sha256: b64({ exact: 32 }),
711
+ chunk: int(0, MAX_ATTACHMENT_CHUNKS - 1),
712
+ chunks: int(1, MAX_ATTACHMENT_CHUNKS),
713
+ data: b64({ max: ATTACHMENT_CHUNK_BYTES }),
714
+ }),
715
+ "attachment.clear": object({}),
716
+ "preview.targets": object({ project_id: id("prj") }),
717
+ "preview.render": object({
718
+ preview_id: id("pvw"),
719
+ project_id: id("prj"),
720
+ target: oneOf(["port", "file"]),
721
+ port: nullable(int(1, 65_535)),
722
+ /** For a port: the path on that server ("/" by default). For a file: its path inside the project. */
723
+ path: text(300, 1),
724
+ viewport: oneOf(["mobile", "tablet", "desktop"]),
725
+ full_page: bool(),
726
+ }),
727
+ } ;
728
+
729
+ export const TRANSFER_EVENT_SPECS = {
730
+ "attachment.stored": object({
731
+ attachment_id: id("att"),
732
+ received: int(0, MAX_ATTACHMENT_CHUNKS),
733
+ chunks: int(1, MAX_ATTACHMENT_CHUNKS),
734
+ /** Once whole and checked: the file's path relative to the project; null while chunks are still coming. */
735
+ path: nullable(text(400, 1)),
736
+ size: int(1, MAX_ATTACHMENT_BYTES),
737
+ content_type: oneOf(ATTACHMENT_TYPES),
738
+ }),
739
+ "attachment.cleared": object({ removed: int(0) }),
740
+ "preview.targets": object({
741
+ project_id: id("prj"),
742
+ ports: list(object({ port: int(1, 65_535), listening: bool() }), 20),
743
+ files: list(text(300, 1), 50),
744
+ browser: bool(),
745
+ }),
746
+ "preview.image": object({ preview_id: id("pvw"), chunk: int(0, MAX_PREVIEW_CHUNKS - 1), chunks: int(1, MAX_PREVIEW_CHUNKS), data: b64({ max: PREVIEW_CHUNK_BYTES }) }),
747
+ "preview.rendered": object({
748
+ preview_id: id("pvw"),
749
+ project_id: id("prj"),
750
+ viewport: oneOf(["mobile", "tablet", "desktop"]),
751
+ width: int(1, 4096),
752
+ height: int(1, 16_384),
753
+ /** The page's own <title>, or null. */
754
+ title: nullable(text(300, 1)),
755
+ /** The dev server's HTTP status as the computer read it; null for a file. */
756
+ http_status: nullable(int(100, 599)),
757
+ bytes: int(1, MAX_PREVIEW_BYTES),
758
+ sha256: b64({ exact: 32 }),
759
+ chunks: int(1, MAX_PREVIEW_CHUNKS),
760
+ }),
761
+ } ;
762
+
763
+ export const attachmentRule = (a ) =>
764
+ a.chunk >= a.chunks ? "a chunk past the count" : a.chunks !== Math.ceil(a.size / ATTACHMENT_CHUNK_BYTES) ? "a chunk count that is not the size's" : null;
765
+ export const previewRule = (r ) =>
766
+ r.target === "port" ? (r.port === null || !PREVIEW_PATH.test(r.path) ? "a port and a path on it" : null) : r.port !== null || !/^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+\.html?$/.test(r.path) ? "a project file, an .html one, and no port" : null;
767
+
768
+ // ---- packages/remote-protocol/src/live-preview.ts
769
+ /**
770
+ * THE LIVE PREVIEW (release 19, 2026-11-09; owner's preview option A): the session's granted dev page (or built file), live
771
+ * and touchable on the phone. The computer runs the person's own Chrome headless in a throw-away profile, drives it over
772
+ * the DevTools protocol through a PIPE (never a debugging port), and sends what it draws as JPEG frames on the session's
773
+ * transient lane (envelopes.ts: never journaled, never buffered, newest wins); the phone's taps, scrolls and typed text
774
+ * go back as these commands and are applied to the page.
775
+ *
776
+ * What a phone may say is closed: a granted target and a PATH on it (never a URL or a host), a viewport preset, a tap or a
777
+ * scroll at page coordinates inside the viewport, literal text, one of three keys, follow or stop. The computer holds the
778
+ * page to the granted origin: every navigation or request elsewhere, a file:// page, a download, a popup and a permission
779
+ * prompt is blocked and counted in `blocked`, never followed. One live preview per computer; it stops when nobody follows
780
+ * it (the computer's timeout) or the session closes, and the browser and its profile are removed.
781
+ */
782
+
783
+ export const LIVE_VIEWPORTS = ["mobile", "tablet", "desktop"] ;
784
+
785
+ /** The keys a phone may press in a live page, besides typing literal text. */
786
+ export const LIVE_KEYS = ["Enter", "Backspace", "Tab"] ;
787
+ export const MAX_LIVE_TEXT = 1000;
788
+ /** A frame's JPEG, at most (a sealed body holds 1 MiB of plaintext; base64 grows it by a third). */
789
+ export const MAX_FRAME_BYTES = 393_216;
790
+ export const LIVE_BLOCK_KINDS = ["navigation", "request", "popup", "download", "permission", "file"] ;
791
+ export const LIVE_STATES = ["starting", "live", "stopped", "failed"] ;
792
+ export const LIVE_REASONS = ["no_browser", "not_listening", "not_granted", "busy", "unfollowed", "closed", "browser_exited", "stopped", "failed"] ;
793
+
794
+ const x = int(0, 4095);
795
+ const y = int(0, 16_383);
796
+
797
+ export const LIVE_COMMAND_SPECS = {
798
+ /** Start the session project's granted port (with a path on it) or granted file, in a viewport preset. */
799
+ "preview.live_start": object({ target: oneOf(["port", "file"]), port: nullable(int(1, 65_535)), path: text(300, 1), viewport: oneOf(LIVE_VIEWPORTS) }),
800
+ /** One touch: a tap or a scroll at page coordinates, literal text, or one allowed key. */
801
+ "preview.live_input": union("kind", {
802
+ tap: object({ kind: oneOf(["tap"]), x, y }),
803
+ scroll: object({ kind: oneOf(["scroll"]), x, y, dy: int(-4000, 4000) }),
804
+ text: object({ kind: oneOf(["text"]), text: text(MAX_LIVE_TEXT, 1) }),
805
+ key: object({ kind: oneOf(["key"]), key: oneOf(LIVE_KEYS) }),
806
+ }),
807
+ /** Another preset, live (the page stays; its viewport changes). */
808
+ "preview.live_viewport": object({ viewport: oneOf(LIVE_VIEWPORTS) }),
809
+ /** true: keep it going (renewed, the computer's own timeout); false: stop it now. */
810
+ "preview.live_follow": object({ follow: bool() }),
811
+ } ;
812
+
813
+ const counts = object({ navigation: int(0), request: int(0), popup: int(0), download: int(0), permission: int(0), file: int(0) });
814
+
815
+ export const LIVE_EVENT_SPECS = {
816
+ /** The live preview's state, on every change: ordered and kept like any session event (small, no picture). */
817
+ "preview.live": object({
818
+ state: oneOf(LIVE_STATES),
819
+ viewport: oneOf(LIVE_VIEWPORTS),
820
+ width: int(1, 4096),
821
+ height: int(1, 16_384),
822
+ /** The page's own <title> and its path on the granted origin, as the computer read them; null when unknown. */
823
+ title: nullable(text(300, 1)),
824
+ path: nullable(text(300, 1)),
825
+ /** What the computer refused the page, counted since the start. */
826
+ blocked: counts,
827
+ reason: nullable(oneOf(LIVE_REASONS)),
828
+ }),
829
+ /** One frame as the browser drew it, JPEG; only ever on the transient lane (envelopes.ts). */
830
+ "preview.frame": object({ width: int(1, 4096), height: int(1, 16_384), data: b64({ max: MAX_FRAME_BYTES }) }),
831
+ } ;
832
+
833
+ export const NO_BLOCKS = { navigation: 0, request: 0, popup: 0, download: 0, permission: 0, file: 0 };
834
+
835
+ /** A port and a path on it, or a granted .html file and no port: never a URL, a host, a scheme or `..`. */
836
+ export const liveStartRule = (r ) =>
837
+ r.target === "port" ? (r.port === null || !PREVIEW_PATH.test(r.path) ? "a port and a path on it" : null)
838
+ : r.port !== null || !/^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+\.html?$/.test(r.path) ? "a project file, an .html one, and no port" : null;
839
+
840
+ /** Text a page may be typed: printable, no control character (a newline is the Enter key). */
841
+ // eslint-disable-next-line no-control-regex
842
+ export const liveTextOk = (t ) => !/[\u0000-\u001f\u007f-\u009f]/.test(t);
843
+
653
844
  // ---- packages/remote-protocol/src/attention.ts
654
845
  /**
655
846
  * "NEEDS YOU" AND "FOLLOW". A session's activity in five words:
@@ -1439,112 +1630,6 @@ export function deliveryHops(r )
1439
1630
  return { to_relay_ms: span(r.sent_at, r.relay_ack_seen_at), on_computer_ms: span(r.received_at, r.accepted_at) };
1440
1631
  }
1441
1632
 
1442
- // ---- packages/remote-protocol/src/transfer.ts
1443
- /**
1444
- * FILES FROM THE PHONE, AND A LOCAL PREVIEW BACK (owner, 2026-11-07 22:50). docs/remote-agents/PROTOCOL.md "Attachments"
1445
- * and "Local preview". Everything here is sealed: the relay sees the types, their timing and size classes, never a name,
1446
- * a byte of a file or of a picture.
1447
- *
1448
- * ATTACHMENTS. An image, a PDF or a document travels in chunks of at most 512 KiB (`attachment.put`), each naming the whole
1449
- * file's size, its chunk count and its SHA-256; the computer keeps the chunks apart, joins them when all arrived, checks the
1450
- * hash and that the bytes are what the type says (a PNG starts like a PNG), and only then writes ONE file into the
1451
- * session's project at `.worktrust/inbox/<session_id>/<safe name>` (mode 0600, never executable). `attachment.stored`
1452
- * answers every chunk with the count received (a measured progress) and, once whole, the file's path relative to the
1453
- * project, which a later `agent.start` / `agent.prompt` names by its id (`attachments`), so the agent is told to read it.
1454
- * Caps: 25 MB a file, 100 MB a session. `attachment.clear` deletes the session's inbox.
1455
- *
1456
- * LOCAL PREVIEW. The phone's "Deploy" segment is a LOCAL preview, never a production deploy: `preview.render` asks the
1457
- * computer to render a page of a dev server on 127.0.0.1 at a port the person granted for that project at the keyboard
1458
- * (`worktrust remote preview allow <port>`), or a built HTML file in the project the person granted, at a phone, tablet or
1459
- * desktop viewport, with the person's own installed Chrome or Chromium (headless; nothing is installed). The answer is a
1460
- * PNG in chunks (`preview.image`) and its record (`preview.rendered`: the page's title and HTTP status as the computer saw
1461
- * them). `preview.targets` lists what is granted and whether something listens. Never a URL the phone writes, never
1462
- * another host, never a port forward.
1463
- */
1464
-
1465
- export const ATTACHMENT_CHUNK_BYTES = 524_288;
1466
- export const MAX_ATTACHMENT_BYTES = 25 * 1024 * 1024;
1467
- export const MAX_SESSION_ATTACHMENT_BYTES = 100 * 1024 * 1024;
1468
- export const MAX_ATTACHMENT_CHUNKS = Math.ceil(MAX_ATTACHMENT_BYTES / ATTACHMENT_CHUNK_BYTES);
1469
- export const ATTACHMENT_TYPES = [
1470
- "image/png", "image/jpeg", "image/heic", "image/webp", "application/pdf", "text/plain", "text/markdown", "text/csv",
1471
- "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
1472
- "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
1473
- ] ;
1474
-
1475
- export const MAX_ATTACHMENTS_PER_PROMPT = 20;
1476
-
1477
- export const PREVIEW_VIEWPORTS = { mobile: { width: 390, height: 844 }, tablet: { width: 820, height: 1180 }, desktop: { width: 1440, height: 900 } } ;
1478
- export const PREVIEW_CHUNK_BYTES = 524_288;
1479
- export const MAX_PREVIEW_BYTES = 8 * 1024 * 1024;
1480
- export const MAX_PREVIEW_CHUNKS = Math.ceil(MAX_PREVIEW_BYTES / PREVIEW_CHUNK_BYTES);
1481
- /** A path on the granted dev server: starts with one slash, URL characters only, never `//` (another host). */
1482
- export const PREVIEW_PATH = /^\/(?!\/)[A-Za-z0-9._~!$&'()*+,;=:@%\/?#-]{0,299}$/;
1483
-
1484
- export const TRANSFER_COMMAND_SPECS = {
1485
- "attachment.put": object({
1486
- attachment_id: id("att"),
1487
- name: text(200, 1),
1488
- content_type: oneOf(ATTACHMENT_TYPES),
1489
- size: int(1, MAX_ATTACHMENT_BYTES),
1490
- sha256: b64({ exact: 32 }),
1491
- chunk: int(0, MAX_ATTACHMENT_CHUNKS - 1),
1492
- chunks: int(1, MAX_ATTACHMENT_CHUNKS),
1493
- data: b64({ max: ATTACHMENT_CHUNK_BYTES }),
1494
- }),
1495
- "attachment.clear": object({}),
1496
- "preview.targets": object({ project_id: id("prj") }),
1497
- "preview.render": object({
1498
- preview_id: id("pvw"),
1499
- project_id: id("prj"),
1500
- target: oneOf(["port", "file"]),
1501
- port: nullable(int(1, 65_535)),
1502
- /** For a port: the path on that server ("/" by default). For a file: its path inside the project. */
1503
- path: text(300, 1),
1504
- viewport: oneOf(["mobile", "tablet", "desktop"]),
1505
- full_page: bool(),
1506
- }),
1507
- } ;
1508
-
1509
- export const TRANSFER_EVENT_SPECS = {
1510
- "attachment.stored": object({
1511
- attachment_id: id("att"),
1512
- received: int(0, MAX_ATTACHMENT_CHUNKS),
1513
- chunks: int(1, MAX_ATTACHMENT_CHUNKS),
1514
- /** Once whole and checked: the file's path relative to the project; null while chunks are still coming. */
1515
- path: nullable(text(400, 1)),
1516
- size: int(1, MAX_ATTACHMENT_BYTES),
1517
- content_type: oneOf(ATTACHMENT_TYPES),
1518
- }),
1519
- "attachment.cleared": object({ removed: int(0) }),
1520
- "preview.targets": object({
1521
- project_id: id("prj"),
1522
- ports: list(object({ port: int(1, 65_535), listening: bool() }), 20),
1523
- files: list(text(300, 1), 50),
1524
- browser: bool(),
1525
- }),
1526
- "preview.image": object({ preview_id: id("pvw"), chunk: int(0, MAX_PREVIEW_CHUNKS - 1), chunks: int(1, MAX_PREVIEW_CHUNKS), data: b64({ max: PREVIEW_CHUNK_BYTES }) }),
1527
- "preview.rendered": object({
1528
- preview_id: id("pvw"),
1529
- project_id: id("prj"),
1530
- viewport: oneOf(["mobile", "tablet", "desktop"]),
1531
- width: int(1, 4096),
1532
- height: int(1, 16_384),
1533
- /** The page's own <title>, or null. */
1534
- title: nullable(text(300, 1)),
1535
- /** The dev server's HTTP status as the computer read it; null for a file. */
1536
- http_status: nullable(int(100, 599)),
1537
- bytes: int(1, MAX_PREVIEW_BYTES),
1538
- sha256: b64({ exact: 32 }),
1539
- chunks: int(1, MAX_PREVIEW_CHUNKS),
1540
- }),
1541
- } ;
1542
-
1543
- export const attachmentRule = (a ) =>
1544
- a.chunk >= a.chunks ? "a chunk past the count" : a.chunks !== Math.ceil(a.size / ATTACHMENT_CHUNK_BYTES) ? "a chunk count that is not the size's" : null;
1545
- export const previewRule = (r ) =>
1546
- r.target === "port" ? (r.port === null || !PREVIEW_PATH.test(r.path) ? "a port and a path on it" : null) : r.port !== null || !/^(?!\/)(?!.*\.\.)[A-Za-z0-9._/-]+\.html?$/.test(r.path) ? "a project file, an .html one, and no port" : null;
1547
-
1548
1633
  // ---- packages/remote-protocol/src/state-machine.ts
1549
1634
  /**
1550
1635
  * DELIVERY AND EXECUTION, AS A PURE FUNCTION. One command's state, from the phone's draft to its end:
@@ -1696,57 +1781,308 @@ export function confirmationOf(state ) {
1696
1781
  export const shouldResend = (state , now , expiresAt ) =>
1697
1782
  (state === "SUBMITTED_TO_RELAY" || state === "UNKNOWN_DELIVERY") && now < expiresAt;
1698
1783
 
1699
- // ---- packages/remote-protocol/src/control.ts
1784
+ // ---- packages/remote-protocol/src/control.ts
1785
+ /**
1786
+ * PAUSE, RESUME AND STOP, AS ASKED AND AS SEEN. A control request is not its effect: "pause requested" is what the
1787
+ * phone did, "paused" is what the computer reported. The UI shows the one it knows.
1788
+ *
1789
+ * none -> pause_requested -> paused | unable_to_pause
1790
+ * paused -> resume_requested -> none
1791
+ * any (but stopped) -> stop_requested -> stopped
1792
+ *
1793
+ * Stop wins: once requested, a pause or a resume is not offered and a late `paused` does not hide the stop.
1794
+ * `unable_to_pause` is the computer saying this agent cannot pause (command.rejected for agent.pause); it is shown,
1795
+ * and stop is still offered.
1796
+ */
1797
+
1798
+ export const CONTROL_STATES = ["none", "pause_requested", "paused", "resume_requested", "stop_requested", "stopped", "unable_to_pause"] ;
1799
+
1800
+ export function controlTransition(state , input ) {
1801
+ if (state === "stopped") return state;
1802
+ const stopping = state === "stop_requested";
1803
+ switch (input) {
1804
+ case "stop_sent":
1805
+ return "stop_requested";
1806
+ case "stopped_observed":
1807
+ return "stopped";
1808
+ case "pause_sent":
1809
+ return state === "none" || state === "unable_to_pause" ? "pause_requested" : state;
1810
+ case "paused_observed":
1811
+ return stopping ? state : "paused";
1812
+ case "pause_refused":
1813
+ return state === "pause_requested" ? "unable_to_pause" : state;
1814
+ case "resume_sent":
1815
+ return state === "paused" ? "resume_requested" : state;
1816
+ case "resumed_observed":
1817
+ return stopping ? state : "none";
1818
+ case "resume_refused":
1819
+ return state === "resume_requested" ? "paused" : state;
1820
+ case "run_ended":
1821
+ return stopping ? state : "none";
1822
+ }
1823
+ }
1824
+
1825
+ /** Which control buttons exist right now: the adapter's own capabilities, the run's state and the control state. */
1826
+ export function controlsOffered(actions , delivery , control ) {
1827
+ const live = !isTerminal(delivery) && DELIVERY_RANK[delivery] >= DELIVERY_RANK.RELAY_ACKNOWLEDGED;
1828
+ const stopping = control === "stop_requested" || control === "stopped";
1829
+ const running = delivery === "RUNNING" || delivery === "WAITING_APPROVAL";
1830
+ return {
1831
+ pause: actions.pause && live && !stopping && running && (control === "none"),
1832
+ resume: actions.resume && live && !stopping && (delivery === "PAUSED" || control === "paused"),
1833
+ stop: actions.stop && live && !stopping,
1834
+ };
1835
+ }
1836
+
1837
+ // ---- packages/remote-protocol/src/crypto/keys.ts
1838
+ /**
1839
+ * REMOTE DEVICE KEYS. Each computer and each phone install has its own pair: Ed25519 to sign, X25519 to agree keys.
1840
+ * They are NOT the computer's measurement key: a different key, a different store entry, a different audience. A
1841
+ * stolen remote key cannot sign a measurement, and a measurement key cannot steer an agent; every signature here is
1842
+ * also domain-separated ("worktrust-remote/v1/..."), so a signature made for one purpose verifies for no other.
1843
+ *
1844
+ * A FINGERPRINT FOR PEOPLE. 80 bits of SHA-256 over both public keys, as sixteen Crockford base32 characters in four
1845
+ * groups (no I, L, O or U to misread). Shown on the computer's screen and on the phone when a phone is confirmed at
1846
+ * the computer's keyboard, so a compromised issuer cannot slip in a key of its own unnoticed.
1847
+ */
1848
+
1849
+ export function generateDeviceKeys(random ) {
1850
+ return { ed25519: random(KEY_BYTES), x25519: random(KEY_BYTES) };
1851
+ }
1852
+
1853
+ export function publicKeysOf(secret ) {
1854
+ return { ed25519_pub: toBase64Url(ed25519PublicKey(secret.ed25519)), x25519_pub: toBase64Url(x25519PublicKey(secret.x25519)) };
1855
+ }
1856
+
1857
+ /** For a store that holds strings (expo-secure-store, the CLI's credential store). */
1858
+ export const exportSecretKeys = (secret ) => ({
1859
+ ed25519: toBase64Url(secret.ed25519),
1860
+ x25519: toBase64Url(secret.x25519),
1861
+ });
1862
+
1863
+ export function importSecretKeys(stored ) {
1864
+ const ed = fromBase64Url(stored.ed25519);
1865
+ const x = fromBase64Url(stored.x25519);
1866
+ return ed?.length === KEY_BYTES && x?.length === KEY_BYTES ? { ed25519: ed, x25519: x } : null;
1867
+ }
1868
+
1869
+ const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
1870
+ const FINGERPRINT_DOMAIN = utf8Encode("worktrust-remote/v1/fingerprint\n");
1871
+
1872
+ function base32Groups(bytes ) {
1873
+ let bits = 0;
1874
+ let acc = 0;
1875
+ let out = "";
1876
+ for (const b of bytes) {
1877
+ acc = (acc << 8) | b;
1878
+ bits += 8;
1879
+ while (bits >= 5) {
1880
+ bits -= 5;
1881
+ out += CROCKFORD[(acc >> bits) & 31] ;
1882
+ }
1883
+ acc &= (1 << bits) - 1;
1884
+ }
1885
+ return out.match(/.{1,4}/g) .join("-");
1886
+ }
1887
+
1888
+ function decodeKey(text ) {
1889
+ const bytes = fromBase64Url(text);
1890
+ if (bytes?.length !== KEY_BYTES) throw new TypeError("a public key is 32 bytes of base64url");
1891
+ return bytes;
1892
+ }
1893
+
1894
+ /** "ABCD-EFGH-JKMN-PQRS" for one device's public keys. */
1895
+ export function deviceFingerprint(keys ) {
1896
+ const digest = sha256(concatBytes(FINGERPRINT_DOMAIN, decodeKey(keys.ed25519_pub), decodeKey(keys.x25519_pub)));
1897
+ return base32Groups(digest.subarray(0, 10));
1898
+ }
1899
+
1900
+ // ---- packages/remote-protocol/src/crypto/jws.ts
1901
+ /**
1902
+ * COMPACT SIGNED TOKENS: JWS (RFC 7515) with EdDSA over Ed25519 (RFC 8037), so the gateway can verify an assertion
1903
+ * with any standard library, and so can the phone and the computer with this package. Three token types, told apart
1904
+ * by `typ` and never interchangeable:
1905
+ * wt-remote-binding+jwt the Passport app binds a device's remote keys to an account
1906
+ * wt-remote-auth+jwt the Passport app authorizes one device at the gateway for five minutes
1907
+ * wt-remote-approval+jwt a phone decides one pending approval
1908
+ * The verifier fixes alg, typ and the key set before it looks at the token: a token cannot choose how it is checked.
1909
+ * Header and payload are canonical JSON, so one claim set has one signing input.
1910
+ */
1911
+
1912
+ export const TOKEN_TYPES = ["wt-remote-binding+jwt", "wt-remote-auth+jwt", "wt-remote-approval+jwt"] ;
1913
+
1914
+ export const MAX_TOKEN_CHARS = 4096;
1915
+
1916
+ /** Public keys by key id: the issuer's keys (pinned in the app and CLI builds), or a phone's bound key. */
1917
+
1918
+ export function signToken(typ , kid , claims , secret ) {
1919
+ const header = toBase64Url(utf8Encode(canonicalJson({ alg: "EdDSA", kid, typ })));
1920
+ const payload = toBase64Url(utf8Encode(canonicalJson(claims)));
1921
+ const signature = ed25519Sign(utf8Encode(`${header}.${payload}`), secret);
1922
+ return `${header}.${payload}.${toBase64Url(signature)}`;
1923
+ }
1924
+
1925
+ const decodeJson = (part ) => {
1926
+ const bytes = fromBase64Url(part);
1927
+ const text = bytes === null ? null : utf8Decode(bytes);
1928
+ return text === null ? undefined : parseJson(text);
1929
+ };
1930
+
1931
+ export function verifyToken(token , typ , keys ) {
1932
+ if (token.length > MAX_TOKEN_CHARS) return refuse("shape", "token: too long");
1933
+ const parts = token.split(".");
1934
+ if (parts.length !== 3) return refuse("shape", "token: not three parts");
1935
+ const [h, p, s] = parts ;
1936
+ const header = decodeJson(h);
1937
+ if (typeof header !== "object" || header === null || Array.isArray(header)) return refuse("shape", "token: header");
1938
+ const hd = header ;
1939
+ if (Object.keys(hd).sort().join(",") !== "alg,kid,typ") return refuse("shape", "token: header fields");
1940
+ if (hd.alg !== "EdDSA") return refuse("shape", "token: alg");
1941
+ if (hd.typ !== typ) return refuse("shape", "token: typ");
1942
+ if (typeof hd.kid !== "string" || !Object.hasOwn(keys, hd.kid)) return refuse("unknown_key", "token: kid");
1943
+ const key = keys[hd.kid] ;
1944
+ const signature = fromBase64Url(s);
1945
+ if (key.length !== KEY_BYTES || signature === null) return refuse("signature", "token: signature encoding");
1946
+ if (!ed25519Verify(signature, utf8Encode(`${h}.${p}`), key)) return refuse("signature", "token: signature");
1947
+ const claims = decodeJson(p);
1948
+ if (typeof claims !== "object" || claims === null || Array.isArray(claims)) return refuse("shape", "token: payload");
1949
+ // The signed bytes must BE the canonical encoding, so one claim set has exactly one valid token form.
1950
+ if (toBase64Url(utf8Encode(canonicalJson(claims))) !== p) return refuse("shape", "token: payload not canonical");
1951
+ if (toBase64Url(utf8Encode(canonicalJson(hd))) !== h) return refuse("shape", "token: header not canonical");
1952
+ return accept({ kid: hd.kid, claims: claims });
1953
+ }
1954
+
1955
+ /** iat/exp checks shared by every token kind; seconds, with the protocol's skew. */
1956
+ export function checkTimes(iat , exp , nowMs , maxLifetimeS , skewMs ) {
1957
+ if (exp <= iat) return refuse("lifetime", "token: exp not after iat");
1958
+ if (exp - iat > maxLifetimeS) return refuse("lifetime", "token: lives too long");
1959
+ if (iat * 1000 > nowMs + skewMs) return refuse("not_yet_valid", "token: issued in the future");
1960
+ if (exp * 1000 + skewMs < nowMs) return refuse("expired", "token: expired");
1961
+ return accept(true);
1962
+ }
1963
+
1964
+ // ---- packages/remote-protocol/src/crypto/binding.ts
1965
+ /**
1966
+ * A REMOTE KEY BINDING: the Passport app's signed word that these public keys belong to this device of this account.
1967
+ * The person approves the device in app.worktrust.io, signed in with a second factor; the app signs
1968
+ * { iss, aud, sub, device_id, kind, ed25519_pub, x25519_pub, iat, exp, jti }
1969
+ * with a WorkTrust issuer key. `sub` is an opaque account reference for the remote system (an HMAC of the owner id
1970
+ * under a Passport secret, prefixed usr_), never the Passport owner id, so the relay's records join to nothing else.
1971
+ *
1972
+ * Endpoints verify bindings against the issuer's public keys PINNED in the app and CLI builds, never against a key the
1973
+ * relay hands them. The relay cannot forge a binding. The issuer alone cannot add a controller either: a new phone is
1974
+ * pending on the computer until the person confirms its fingerprint at the computer's keyboard (handshake.ts).
1975
+ */
1976
+
1977
+ export const DEVICE_KINDS = ["phone", "computer"] ;
1978
+
1979
+ export const BINDING_CLAIMS_SPEC = object({
1980
+ iss: oneOf([PASSPORT_ISSUER]),
1981
+ aud: oneOf([GATEWAY_AUDIENCE]),
1982
+ sub: id("usr"),
1983
+ device_id: id("dev"),
1984
+ kind: oneOf(DEVICE_KINDS),
1985
+ ed25519_pub: b64({ exact: 32 }),
1986
+ x25519_pub: b64({ exact: 32 }),
1987
+ iat: int(0),
1988
+ exp: int(0),
1989
+ jti: id("jti"),
1990
+ });
1991
+
1992
+ /** For the Passport app: validate, then sign. */
1993
+ export function issueBinding(claims , issuerSecret , kid ) {
1994
+ const checked = validate(BINDING_CLAIMS_SPEC, claims, "$binding");
1995
+ if (!checked.ok) throw new TypeError(checked.detail);
1996
+ if (claims.exp - claims.iat > MAX_BINDING_LIFETIME_S || claims.exp <= claims.iat) throw new RangeError("binding lifetime");
1997
+ return signToken("wt-remote-binding+jwt", kid, claims, issuerSecret);
1998
+ }
1999
+
2000
+ export function verifyBinding(token , expect ) {
2001
+ const verified = verifyToken(token, "wt-remote-binding+jwt", expect.issuerKeys);
2002
+ if (!verified.ok) return refuse(verified.code === "shape" ? "binding" : verified.code, verified.detail);
2003
+ const shaped = validate(BINDING_CLAIMS_SPEC, verified.value.claims, "$binding");
2004
+ if (!shaped.ok) return refuse("binding", shaped.detail);
2005
+ const b = shaped.value;
2006
+ const times = checkTimes(b.iat, b.exp, expect.now, MAX_BINDING_LIFETIME_S, CLOCK_SKEW_MS);
2007
+ if (!times.ok) return times;
2008
+ if (expect.kind !== undefined && b.kind !== expect.kind) return refuse("binding", "$binding.kind: not the expected kind");
2009
+ if (expect.deviceId !== undefined && b.device_id !== expect.deviceId) return refuse("wrong_device", "$binding.device_id");
2010
+ if (expect.sub !== undefined && b.sub !== expect.sub) return refuse("account_mismatch", "$binding.sub");
2011
+ if (expect.isRevoked?.(b)) return refuse("revoked", "$binding: revoked");
2012
+ return accept(b);
2013
+ }
2014
+
2015
+ /** The signing key a verified binding names, as bytes. */
2016
+ export const bindingSigningKey = (b ) => fromBase64Url(b.ed25519_pub) ;
2017
+ export const bindingAgreementKey = (b ) => fromBase64Url(b.x25519_pub) ;
2018
+ export const bindingFingerprint = (b ) =>
2019
+ deviceFingerprint({ ed25519_pub: b.ed25519_pub, x25519_pub: b.x25519_pub });
2020
+
2021
+ // ---- packages/remote-protocol/src/crypto/endorse.ts
1700
2022
  /**
1701
- * PAUSE, RESUME AND STOP, AS ASKED AND AS SEEN. A control request is not its effect: "pause requested" is what the
1702
- * phone did, "paused" is what the computer reported. The UI shows the one it knows.
1703
- *
1704
- * none -> pause_requested -> paused | unable_to_pause
1705
- * paused -> resume_requested -> none
1706
- * any (but stopped) -> stop_requested -> stopped
2023
+ * A PHONE ADDS A BROWSER (owner, 2026-11-09: "your phone approves a new browser"; docs/remote-agents/PROTOCOL.md §A phone
2024
+ * endorses a browser). Like linking a messenger's web client: the browser shows a QR code with its issuer binding (its
2025
+ * keys, its device id, its account), a one-time nonce and a short expiry; a CONFIRMED phone scans it, asks the device
2026
+ * unlock, and sends each chosen computer a sealed, signed `browser.endorse` command carrying exactly those three. The
2027
+ * computer adds the browser as a controller only if it allowed endorsements at its keyboard (`worktrust remote phones
2028
+ * allow-endorse on`), the sender is a controller confirmed there or by a scanned QR (never one added by endorsement), the
2029
+ * binding verifies for the computer's OWN account, the endorsement is in time and its nonce was never spent.
1707
2030
  *
1708
- * Stop wins: once requested, a pause or a resume is not offered and a late `paused` does not hide the stop.
1709
- * `unable_to_pause` is the computer saying this agent cannot pause (command.rejected for agent.pause); it is shown,
1710
- * and stop is still offered.
2031
+ * The QR holds one link, everything in the fragment, which no browser sends to a server:
2032
+ * https://app.worktrust.io/remote/endorse#v=1&b=<binding>&n=<16-byte nonce>&e=<expiry, unix s>
2033
+ * This file is the only reader and writer of that link and the one check both the phone and the computer run.
1711
2034
  */
1712
2035
 
1713
- export const CONTROL_STATES = ["none", "pause_requested", "paused", "resume_requested", "stop_requested", "stopped", "unable_to_pause"] ;
2036
+ export const ENDORSE_VERSION = 1;
2037
+ /** Five minutes at most from the browser showing it to the computer taking it. */
2038
+ export const ENDORSE_LIFETIME_S = 300;
2039
+ export const ENDORSE_LINK_BASE = "https://app.worktrust.io/remote/endorse";
1714
2040
 
1715
- export function controlTransition(state , input ) {
1716
- if (state === "stopped") return state;
1717
- const stopping = state === "stop_requested";
1718
- switch (input) {
1719
- case "stop_sent":
1720
- return "stop_requested";
1721
- case "stopped_observed":
1722
- return "stopped";
1723
- case "pause_sent":
1724
- return state === "none" || state === "unable_to_pause" ? "pause_requested" : state;
1725
- case "paused_observed":
1726
- return stopping ? state : "paused";
1727
- case "pause_refused":
1728
- return state === "pause_requested" ? "unable_to_pause" : state;
1729
- case "resume_sent":
1730
- return state === "paused" ? "resume_requested" : state;
1731
- case "resumed_observed":
1732
- return stopping ? state : "none";
1733
- case "resume_refused":
1734
- return state === "resume_requested" ? "paused" : state;
1735
- case "run_ended":
1736
- return stopping ? state : "none";
2041
+ /** What travels: the QR's three fields, and the sealed `browser.endorse` payload, the same three. */
2042
+ export const ENDORSEMENT_SPEC = object({ binding: token(4096), nonce: b64({ exact: 16 }), expires_at: int(0) });
2043
+
2044
+ /** The browser makes one for its own binding: a fresh nonce, five minutes. */
2045
+ export function createEndorsement(binding , nowMs , random ) {
2046
+ return { binding, nonce: toBase64Url(random(16)), expires_at: Math.floor(nowMs / 1000) * 1000 + ENDORSE_LIFETIME_S * 1000 };
2047
+ }
2048
+
2049
+ export function encodeEndorseLink(e , base = ENDORSE_LINK_BASE) {
2050
+ return `${base}#v=${ENDORSE_VERSION}&b=${encodeURIComponent(e.binding)}&n=${e.nonce}&e=${Math.floor(e.expires_at / 1000)}`;
2051
+ }
2052
+
2053
+ export function decodeEndorseLink(link ) {
2054
+ if (typeof link !== "string" || link.length > 6000) return refuse("shape", "$link");
2055
+ const hash = link.indexOf("#");
2056
+ if (hash < 0 || link.slice(0, hash) !== ENDORSE_LINK_BASE) return refuse("shape", "$link: not a WorkTrust browser link");
2057
+ const raw = {};
2058
+ for (const part of link.slice(hash + 1).split("&")) {
2059
+ const eq = part.indexOf("=");
2060
+ const key = eq > 0 ? part.slice(0, eq) : "";
2061
+ if (!["v", "b", "n", "e"].includes(key) || Object.hasOwn(raw, key)) return refuse("shape", "$link: an unknown or repeated key");
2062
+ try { raw[key] = decodeURIComponent(part.slice(eq + 1)); } catch { return refuse("shape", "$link: encoding"); }
1737
2063
  }
2064
+ if (raw.v !== String(ENDORSE_VERSION) || !/^[1-9][0-9]{0,11}$/.test(raw.e ?? "")) return refuse("shape", "$link: version or expiry");
2065
+ const shaped = validate(ENDORSEMENT_SPEC, { binding: raw.b, nonce: raw.n, expires_at: Number(raw.e) * 1000 }, "$endorsement");
2066
+ return shaped.ok ? accept(shaped.value) : refuse("shape", shaped.detail);
1738
2067
  }
1739
2068
 
1740
- /** Which control buttons exist right now: the adapter's own capabilities, the run's state and the control state. */
1741
- export function controlsOffered(actions , delivery , control ) {
1742
- const live = !isTerminal(delivery) && DELIVERY_RANK[delivery] >= DELIVERY_RANK.RELAY_ACKNOWLEDGED;
1743
- const stopping = control === "stop_requested" || control === "stopped";
1744
- const running = delivery === "RUNNING" || delivery === "WAITING_APPROVAL";
1745
- return {
1746
- pause: actions.pause && live && !stopping && running && (control === "none"),
1747
- resume: actions.resume && live && !stopping && (delivery === "PAUSED" || control === "paused"),
1748
- stop: actions.stop && live && !stopping,
1749
- };
2069
+ /**
2070
+ * THE CHECK, on the phone before it asks the unlock and on the computer before it adds anyone: the binding verifies against
2071
+ * the pinned issuer keys as a controller (kind phone), for `account` (the checker's own binding's `sub`: a phone of account
2072
+ * A never endorses a browser of account B, and a computer never takes a browser of another account), and the endorsement
2073
+ * is in time and never lives longer than five minutes. Single use is the computer's spent-nonce list, not this function.
2074
+ */
2075
+ export function checkEndorsement(input , o ) {
2076
+ const shaped = validate(ENDORSEMENT_SPEC, input, "$endorsement");
2077
+ if (!shaped.ok) return refuse("shape", shaped.detail);
2078
+ const e = shaped.value;
2079
+ if (e.expires_at <= o.now) return refuse("expired", "$endorsement.expires_at");
2080
+ if (e.expires_at > o.now + ENDORSE_LIFETIME_S * 1000 + CLOCK_SKEW_MS) return refuse("lifetime", "$endorsement.expires_at");
2081
+ const bound = verifyBinding(e.binding, { issuerKeys: o.issuerKeys, now: o.now, kind: "phone" });
2082
+ if (!bound.ok) return refuse(bound.code, bound.detail);
2083
+ if (bound.value.sub !== o.account) return refuse("account_mismatch", "$endorsement.binding.sub");
2084
+ const keys = { ed25519_pub: bound.value.ed25519_pub, x25519_pub: bound.value.x25519_pub };
2085
+ return accept({ device_id: bound.value.device_id, fingerprint: deviceFingerprint(keys), keys, binding: bound.value, nonce: e.nonce, expires_at: e.expires_at });
1750
2086
  }
1751
2087
 
1752
2088
  // ---- packages/remote-protocol/src/commands.ts
@@ -1788,6 +2124,11 @@ export const COMMAND_PAYLOAD_SPECS = {
1788
2124
  prompt: nullable(text(MAX_PROMPT_CHARS, 1)),
1789
2125
  /** The session's name on the phone's project tree (2026-11-07), sealed; renameable with session.rename. */
1790
2126
  name: optional(nullable(text(MAX_SESSION_NAME, 1))),
2127
+ /**
2128
+ * Which of the adapter's reports to start (release 19, 2026-11-09): `terminal` runs the agent in a terminal session the
2129
+ * person can also attach at the desk. Absent means structured, as before.
2130
+ */
2131
+ mode: optional(oneOf(ADAPTER_MODES)),
1791
2132
  }),
1792
2133
  /**
1793
2134
  * A new turn for an agent that waits for input. Sent while a turn runs, it waits (command.queued) and runs when the turn
@@ -1830,7 +2171,11 @@ export const COMMAND_PAYLOAD_SPECS = {
1830
2171
  /** A new name for the session (2026-11-07); answered with device.inventory, which lists every session by name. */
1831
2172
  "session.rename": object({ name: text(MAX_SESSION_NAME, 1) }),
1832
2173
  /** The last lines of a terminal session's screen, answered with agent.screen. */
1833
- "screen.read": object({ lines: int(1, 2000) }),
2174
+ /**
2175
+ * `follow` (release 19, 2026-11-09): true asks the computer to send the screen again whenever it changes (agent.screen,
2176
+ * coalesced) for a while (the computer's limit, renewed by every read that follows), false stops it. Absent: one read.
2177
+ */
2178
+ "screen.read": object({ lines: int(1, 2000), follow: optional(bool()) }),
1834
2179
  /** Ask for a device.inventory; `refresh_models` runs the agents' own model listers first. */
1835
2180
  "inventory.get": object({ refresh_models: bool() }),
1836
2181
  /** This computer's remote settings, each optional. Pausing from the phone is soft; `worktrust remote disable` at the
@@ -1846,11 +2191,19 @@ export const COMMAND_PAYLOAD_SPECS = {
1846
2191
  "pairing.revoke": object({}),
1847
2192
  /** Files from the phone and a local preview back (transfer.ts, 2026-11-07). */
1848
2193
  ...TRANSFER_COMMAND_SPECS,
2194
+ /** The live preview (release 19, live-preview.ts): session commands. */
2195
+ ...LIVE_COMMAND_SPECS,
1849
2196
  /**
1850
2197
  * One new, empty project folder named `name` inside the root `root_id` (2026-11-07), granted as a project; `git init`
1851
2198
  * in it only when the person enabled that for the root at the keyboard. Answered with project.created.
1852
2199
  */
1853
2200
  "project.create": object({ name: text(100, 1), root_id: id("rot") }),
2201
+ /**
2202
+ * A confirmed phone adds a browser it scanned as a controller of this computer (2026-11-09, crypto/endorse.ts): the
2203
+ * browser's issuer binding, the QR's one-time nonce and its expiry. Taken only when the computer allowed endorsements at
2204
+ * its keyboard, from a phone confirmed there or by a scanned QR, for the computer's own account, in time, nonce unspent.
2205
+ */
2206
+ "browser.endorse": ENDORSEMENT_SPEC,
1854
2207
  /** A release: a bundle of tasks in one project (release.ts). Ids are minted by the phone, once. */
1855
2208
  "release.create": object({
1856
2209
  release_id: id("rel"),
@@ -1895,7 +2248,7 @@ export const COMMAND_PAYLOAD_SPECS = {
1895
2248
  export const COMMAND_TYPES = Object.keys(COMMAND_PAYLOAD_SPECS) ;
1896
2249
 
1897
2250
  export const RELEASE_COMMANDS = new Set (["release.create", "release.add_task", "release.reorder", "release.cancel_task", "release.start", "release.list", "pipeline.start", "pipeline.cancel"]);
1898
- export const DEVICE_COMMANDS = new Set (["inventory.get", "device.configure", "pairing.revoke", "project.create", "preview.targets", "preview.render", ...RELEASE_COMMANDS]);
2251
+ export const DEVICE_COMMANDS = new Set (["inventory.get", "device.configure", "pairing.revoke", "project.create", "browser.endorse", "preview.targets", "preview.render", ...RELEASE_COMMANDS]);
1899
2252
  export const commandScope = (type ) => (DEVICE_COMMANDS.has(type) ? "device" : "session");
1900
2253
 
1901
2254
  /** Commands whose acceptance starts a run with steps, approvals and an end (state-machine.ts follows those through
@@ -1922,11 +2275,16 @@ export const COMMAND_TTL_MS = {
1922
2275
  "session.close": 5 * MINUTE,
1923
2276
  "session.rename": 5 * MINUTE,
1924
2277
  "project.create": 10 * MINUTE,
2278
+ "browser.endorse": 5 * MINUTE,
1925
2279
  "attachment.put": 60 * MINUTE,
1926
2280
  "attachment.clear": 10 * MINUTE,
1927
2281
  "preview.targets": 1 * MINUTE,
1928
2282
  "preview.render": 2 * MINUTE,
1929
2283
  "screen.read": 1 * MINUTE,
2284
+ "preview.live_start": 2 * MINUTE,
2285
+ "preview.live_input": 1 * MINUTE,
2286
+ "preview.live_viewport": 1 * MINUTE,
2287
+ "preview.live_follow": 1 * MINUTE,
1930
2288
  "inventory.get": 5 * MINUTE,
1931
2289
  "device.configure": 10 * MINUTE,
1932
2290
  "pairing.revoke": 24 * 60 * MINUTE,
@@ -1960,6 +2318,8 @@ export function validateCommandPayload (type , value
1960
2318
  if (type === "device.configure" && Object.keys(payload).length === 0) return refuse("payload", "$payload: names no setting");
1961
2319
  if (type === "attachment.put") { const bad = attachmentRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
1962
2320
  if (type === "preview.render") { const bad = previewRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
2321
+ if (type === "preview.live_start") { const bad = liveStartRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
2322
+ if (type === "preview.live_input") { const i = payload ; if (i.kind === "text" && !liveTextOk(i.text)) return refuse("payload", "$payload.text: literal text, no control character"); }
1963
2323
  if (type === "project.create" && !projectNameOk((payload ).name))
1964
2324
  return refuse("payload", "$payload.name: one folder name of [A-Za-z0-9._-], not starting with a dot");
1965
2325
  if (type === "release.reorder") {
@@ -2071,6 +2431,7 @@ export const REJECT_REASONS = [
2071
2431
  "conflict", // a command id reused for different bytes
2072
2432
  "busy", // the agent is mid-turn and the command needs it idle (a release: its tasks still run, or no slot for a pipeline)
2073
2433
  "unreviewed", // the project's pipeline file was not reviewed at the keyboard, or changed since (2026-11-07)
2434
+ "not_allowed", // the computer did not allow it at its keyboard (a browser endorsement without allow-endorse), or the sender may not (2026-11-09)
2074
2435
  ] ;
2075
2436
 
2076
2437
  export const FAIL_REASONS = ["agent_exited", "adapter_error", "not_ready", "timeout", "internal"] ;
@@ -2124,6 +2485,8 @@ export const EVENT_BODY_SPECS = {
2124
2485
  project_label: nullable(label(256)),
2125
2486
  /** The name the phone gave it (agent.start's name, a release task's label), or null. */
2126
2487
  name: optional(nullable(label(100))),
2488
+ /** `terminal` for a session in a terminal the desk can attach (release 19); absent means structured. */
2489
+ mode: optional(oneOf(ADAPTER_MODES)),
2127
2490
  }),
2128
2491
  "command.device_received": object({}),
2129
2492
  /** started_at: the computer's clock when the acceptance began a turn (usage.ts); absent for any other acceptance. */
@@ -2227,6 +2590,8 @@ export const EVENT_BODY_SPECS = {
2227
2590
  task_id: optional(nullable(id("tsk"))),
2228
2591
  /** Background jobs its agent reports still running (2026-11-08: "ready, but a job is still running"); absent when it cannot tell. */
2229
2592
  background_jobs: optional(int(0, 99)),
2593
+ /** `terminal` for a terminal session (release 19); absent means structured. */
2594
+ mode: optional(oneOf(ADAPTER_MODES)),
2230
2595
  }),
2231
2596
  100,
2232
2597
  ),
@@ -2243,6 +2608,8 @@ export const EVENT_BODY_SPECS = {
2243
2608
  "agents.active": AGENTS_ACTIVE_SPEC,
2244
2609
  /** Attachments (session) and the local preview (device), transfer.ts. */
2245
2610
  ...TRANSFER_EVENT_SPECS,
2611
+ /** The live preview (release 19, live-preview.ts): its state, and its frames on the transient lane only. */
2612
+ ...LIVE_EVENT_SPECS,
2246
2613
  } ;
2247
2614
 
2248
2615
  export const DEVICE_EVENT_TYPES = Object.keys(EVENT_BODY_SPECS) ;
@@ -2317,7 +2684,8 @@ export function validateEventBody (type , value
2317
2684
  const r = validateAdapterReport(report);
2318
2685
  if (!r.ok) return refuse("payload", `$body.adapters: ${r.detail}`);
2319
2686
  }
2320
- if (new Set(inv.adapters.map((a) => a.adapter)).size !== inv.adapters.length) return refuse("payload", "$body.adapters: an adapter twice");
2687
+ // One report per (adapter, mode) since release 19: Claude Code structured and in a terminal are two reports.
2688
+ if (new Set(inv.adapters.map((a) => `${a.adapter}/${a.mode}`)).size !== inv.adapters.length) return refuse("payload", "$body.adapters: an adapter twice");
2321
2689
  }
2322
2690
  return checked;
2323
2691
  }
@@ -2393,6 +2761,20 @@ export const COMMAND_ENVELOPE_SPEC = object({
2393
2761
  authorization: b64({ exact: 64 }),
2394
2762
  });
2395
2763
 
2764
+ /**
2765
+ * THE TRANSIENT LANE (release 19, 2026-11-09). A pushed terminal screen (agent.screen with no command) is news only
2766
+ * until the next one: the computer keeps none, the relay buffers and records none, and a phone that reconnects asks for
2767
+ * the screen again (screen.read). It travels beside the session's ordered stream, never in it: its `event_seq` is the
2768
+ * lane's own number (rising per session; a computer starts it from its clock, so a restart never goes back), it never
2769
+ * moves the stream's cursor, and a phone applies one only when its number is above the last transient one it applied.
2770
+ * So the stream stays gap-free for every phone, whoever followed. Only the types below may take the lane.
2771
+ */
2772
+ export const EVENT_LANES = ["transient"] ;
2773
+ export const TRANSIENT_EVENT_TYPES = new Set (["agent.screen", "preview.frame"]);
2774
+ /** Types that may ONLY travel on the transient lane (a live preview's frames: never journaled, never replayed). */
2775
+ export const TRANSIENT_ONLY_TYPES = new Set (["preview.frame"]);
2776
+ export const isTransientEvent = (e ) => e.lane === "transient";
2777
+
2396
2778
  export const EVENT_ENVELOPE_SPEC = object({
2397
2779
  protocol_version: version,
2398
2780
  session_id: nullable(id("ses")),
@@ -2405,6 +2787,8 @@ export const EVENT_ENVELOPE_SPEC = object({
2405
2787
  command_id: nullable(id("cmd")),
2406
2788
  /** The content-free push hint (attention.ts). */
2407
2789
  notify: oneOf(NOTIFY_HINTS),
2790
+ /** Absent: the session's ordered stream. `transient`: beside it (EVENT_LANES above), kept by nobody. */
2791
+ lane: optional(oneOf(EVENT_LANES)),
2408
2792
  body_ciphertext: sealed(),
2409
2793
  });
2410
2794
 
@@ -2529,6 +2913,9 @@ export function validateEventEnvelope(value ) {
2529
2913
  if (!COMMAND_RECEIPT_EVENTS.has(type) && DEVICE_SCOPED_EVENTS.has(type) !== (e.session_id === null))
2530
2914
  return refuse("shape", "$event.session_id: a session event names a session, a device event none");
2531
2915
  if (COMMAND_RECEIPT_EVENTS.has(type) && e.command_id === null) return refuse("shape", "$event.command_id: a receipt names its command");
2916
+ if (isTransientEvent(e) && (!TRANSIENT_EVENT_TYPES.has(type) || e.command_id !== null || e.session_id === null || e.notify !== "none"))
2917
+ return refuse("shape", "$event.lane: only a pushed screen or frame, of a session, without a command or a push hint, is transient");
2918
+ if (TRANSIENT_ONLY_TYPES.has(type) && !isTransientEvent(e)) return refuse("shape", "$event.lane: a live preview's frame travels on the transient lane only");
2532
2919
  return checked;
2533
2920
  }
2534
2921
 
@@ -2651,11 +3038,12 @@ export function replayAfter (
2651
3038
  * A START IS CHECKED TWICE. The phone offers only what the computer reported; the computer checks again on receipt,
2652
3039
  * against its own current report, because a report the phone saw may be old and a phone may be wrong. A start that
2653
3040
  * names a model the adapter did not list, a permission mode it does not offer, or a resume id where the adapter
2654
- * cannot resume, is refused (command.rejected) and nothing is started.
3041
+ * cannot resume, is refused (command.rejected) and nothing is started; so is a start whose mode (structured, terminal) is not
3042
+ * the report's own (release 19).
2655
3043
  */
2656
3044
 
2657
3045
  export function checkStart(payload , report ) {
2658
- if (!report || report.adapter !== payload.adapter || !report.installed || !report.capabilities.start) return "unsupported";
3046
+ if (!report || report.adapter !== payload.adapter || report.mode !== (payload.mode ?? "structured") || !report.installed || !report.capabilities.start) return "unsupported";
2659
3047
  if (!isModelReported(report, payload.model)) return "unknown_model";
2660
3048
  if (!report.capabilities.permission_modes.includes(payload.permission_mode)) return "unsupported";
2661
3049
  if (payload.resume !== null && !report.capabilities.resume_by_id) return "unsupported";
@@ -2767,190 +3155,6 @@ export function readSteeredLedger(textValue )
2767
3155
  return { byRef, unreadable, pipelines };
2768
3156
  }
2769
3157
 
2770
- // ---- packages/remote-protocol/src/crypto/keys.ts
2771
- /**
2772
- * REMOTE DEVICE KEYS. Each computer and each phone install has its own pair: Ed25519 to sign, X25519 to agree keys.
2773
- * They are NOT the computer's measurement key: a different key, a different store entry, a different audience. A
2774
- * stolen remote key cannot sign a measurement, and a measurement key cannot steer an agent; every signature here is
2775
- * also domain-separated ("worktrust-remote/v1/..."), so a signature made for one purpose verifies for no other.
2776
- *
2777
- * A FINGERPRINT FOR PEOPLE. 80 bits of SHA-256 over both public keys, as sixteen Crockford base32 characters in four
2778
- * groups (no I, L, O or U to misread). Shown on the computer's screen and on the phone when a phone is confirmed at
2779
- * the computer's keyboard, so a compromised issuer cannot slip in a key of its own unnoticed.
2780
- */
2781
-
2782
- export function generateDeviceKeys(random ) {
2783
- return { ed25519: random(KEY_BYTES), x25519: random(KEY_BYTES) };
2784
- }
2785
-
2786
- export function publicKeysOf(secret ) {
2787
- return { ed25519_pub: toBase64Url(ed25519PublicKey(secret.ed25519)), x25519_pub: toBase64Url(x25519PublicKey(secret.x25519)) };
2788
- }
2789
-
2790
- /** For a store that holds strings (expo-secure-store, the CLI's credential store). */
2791
- export const exportSecretKeys = (secret ) => ({
2792
- ed25519: toBase64Url(secret.ed25519),
2793
- x25519: toBase64Url(secret.x25519),
2794
- });
2795
-
2796
- export function importSecretKeys(stored ) {
2797
- const ed = fromBase64Url(stored.ed25519);
2798
- const x = fromBase64Url(stored.x25519);
2799
- return ed?.length === KEY_BYTES && x?.length === KEY_BYTES ? { ed25519: ed, x25519: x } : null;
2800
- }
2801
-
2802
- const CROCKFORD = "0123456789ABCDEFGHJKMNPQRSTVWXYZ";
2803
- const FINGERPRINT_DOMAIN = utf8Encode("worktrust-remote/v1/fingerprint\n");
2804
-
2805
- function base32Groups(bytes ) {
2806
- let bits = 0;
2807
- let acc = 0;
2808
- let out = "";
2809
- for (const b of bytes) {
2810
- acc = (acc << 8) | b;
2811
- bits += 8;
2812
- while (bits >= 5) {
2813
- bits -= 5;
2814
- out += CROCKFORD[(acc >> bits) & 31] ;
2815
- }
2816
- acc &= (1 << bits) - 1;
2817
- }
2818
- return out.match(/.{1,4}/g) .join("-");
2819
- }
2820
-
2821
- function decodeKey(text ) {
2822
- const bytes = fromBase64Url(text);
2823
- if (bytes?.length !== KEY_BYTES) throw new TypeError("a public key is 32 bytes of base64url");
2824
- return bytes;
2825
- }
2826
-
2827
- /** "ABCD-EFGH-JKMN-PQRS" for one device's public keys. */
2828
- export function deviceFingerprint(keys ) {
2829
- const digest = sha256(concatBytes(FINGERPRINT_DOMAIN, decodeKey(keys.ed25519_pub), decodeKey(keys.x25519_pub)));
2830
- return base32Groups(digest.subarray(0, 10));
2831
- }
2832
-
2833
- // ---- packages/remote-protocol/src/crypto/jws.ts
2834
- /**
2835
- * COMPACT SIGNED TOKENS: JWS (RFC 7515) with EdDSA over Ed25519 (RFC 8037), so the gateway can verify an assertion
2836
- * with any standard library, and so can the phone and the computer with this package. Three token types, told apart
2837
- * by `typ` and never interchangeable:
2838
- * wt-remote-binding+jwt the Passport app binds a device's remote keys to an account
2839
- * wt-remote-auth+jwt the Passport app authorizes one device at the gateway for five minutes
2840
- * wt-remote-approval+jwt a phone decides one pending approval
2841
- * The verifier fixes alg, typ and the key set before it looks at the token: a token cannot choose how it is checked.
2842
- * Header and payload are canonical JSON, so one claim set has one signing input.
2843
- */
2844
-
2845
- export const TOKEN_TYPES = ["wt-remote-binding+jwt", "wt-remote-auth+jwt", "wt-remote-approval+jwt"] ;
2846
-
2847
- export const MAX_TOKEN_CHARS = 4096;
2848
-
2849
- /** Public keys by key id: the issuer's keys (pinned in the app and CLI builds), or a phone's bound key. */
2850
-
2851
- export function signToken(typ , kid , claims , secret ) {
2852
- const header = toBase64Url(utf8Encode(canonicalJson({ alg: "EdDSA", kid, typ })));
2853
- const payload = toBase64Url(utf8Encode(canonicalJson(claims)));
2854
- const signature = ed25519Sign(utf8Encode(`${header}.${payload}`), secret);
2855
- return `${header}.${payload}.${toBase64Url(signature)}`;
2856
- }
2857
-
2858
- const decodeJson = (part ) => {
2859
- const bytes = fromBase64Url(part);
2860
- const text = bytes === null ? null : utf8Decode(bytes);
2861
- return text === null ? undefined : parseJson(text);
2862
- };
2863
-
2864
- export function verifyToken(token , typ , keys ) {
2865
- if (token.length > MAX_TOKEN_CHARS) return refuse("shape", "token: too long");
2866
- const parts = token.split(".");
2867
- if (parts.length !== 3) return refuse("shape", "token: not three parts");
2868
- const [h, p, s] = parts ;
2869
- const header = decodeJson(h);
2870
- if (typeof header !== "object" || header === null || Array.isArray(header)) return refuse("shape", "token: header");
2871
- const hd = header ;
2872
- if (Object.keys(hd).sort().join(",") !== "alg,kid,typ") return refuse("shape", "token: header fields");
2873
- if (hd.alg !== "EdDSA") return refuse("shape", "token: alg");
2874
- if (hd.typ !== typ) return refuse("shape", "token: typ");
2875
- if (typeof hd.kid !== "string" || !Object.hasOwn(keys, hd.kid)) return refuse("unknown_key", "token: kid");
2876
- const key = keys[hd.kid] ;
2877
- const signature = fromBase64Url(s);
2878
- if (key.length !== KEY_BYTES || signature === null) return refuse("signature", "token: signature encoding");
2879
- if (!ed25519Verify(signature, utf8Encode(`${h}.${p}`), key)) return refuse("signature", "token: signature");
2880
- const claims = decodeJson(p);
2881
- if (typeof claims !== "object" || claims === null || Array.isArray(claims)) return refuse("shape", "token: payload");
2882
- // The signed bytes must BE the canonical encoding, so one claim set has exactly one valid token form.
2883
- if (toBase64Url(utf8Encode(canonicalJson(claims))) !== p) return refuse("shape", "token: payload not canonical");
2884
- if (toBase64Url(utf8Encode(canonicalJson(hd))) !== h) return refuse("shape", "token: header not canonical");
2885
- return accept({ kid: hd.kid, claims: claims });
2886
- }
2887
-
2888
- /** iat/exp checks shared by every token kind; seconds, with the protocol's skew. */
2889
- export function checkTimes(iat , exp , nowMs , maxLifetimeS , skewMs ) {
2890
- if (exp <= iat) return refuse("lifetime", "token: exp not after iat");
2891
- if (exp - iat > maxLifetimeS) return refuse("lifetime", "token: lives too long");
2892
- if (iat * 1000 > nowMs + skewMs) return refuse("not_yet_valid", "token: issued in the future");
2893
- if (exp * 1000 + skewMs < nowMs) return refuse("expired", "token: expired");
2894
- return accept(true);
2895
- }
2896
-
2897
- // ---- packages/remote-protocol/src/crypto/binding.ts
2898
- /**
2899
- * A REMOTE KEY BINDING: the Passport app's signed word that these public keys belong to this device of this account.
2900
- * The person approves the device in app.worktrust.io, signed in with a second factor; the app signs
2901
- * { iss, aud, sub, device_id, kind, ed25519_pub, x25519_pub, iat, exp, jti }
2902
- * with a WorkTrust issuer key. `sub` is an opaque account reference for the remote system (an HMAC of the owner id
2903
- * under a Passport secret, prefixed usr_), never the Passport owner id, so the relay's records join to nothing else.
2904
- *
2905
- * Endpoints verify bindings against the issuer's public keys PINNED in the app and CLI builds, never against a key the
2906
- * relay hands them. The relay cannot forge a binding. The issuer alone cannot add a controller either: a new phone is
2907
- * pending on the computer until the person confirms its fingerprint at the computer's keyboard (handshake.ts).
2908
- */
2909
-
2910
- export const DEVICE_KINDS = ["phone", "computer"] ;
2911
-
2912
- export const BINDING_CLAIMS_SPEC = object({
2913
- iss: oneOf([PASSPORT_ISSUER]),
2914
- aud: oneOf([GATEWAY_AUDIENCE]),
2915
- sub: id("usr"),
2916
- device_id: id("dev"),
2917
- kind: oneOf(DEVICE_KINDS),
2918
- ed25519_pub: b64({ exact: 32 }),
2919
- x25519_pub: b64({ exact: 32 }),
2920
- iat: int(0),
2921
- exp: int(0),
2922
- jti: id("jti"),
2923
- });
2924
-
2925
- /** For the Passport app: validate, then sign. */
2926
- export function issueBinding(claims , issuerSecret , kid ) {
2927
- const checked = validate(BINDING_CLAIMS_SPEC, claims, "$binding");
2928
- if (!checked.ok) throw new TypeError(checked.detail);
2929
- if (claims.exp - claims.iat > MAX_BINDING_LIFETIME_S || claims.exp <= claims.iat) throw new RangeError("binding lifetime");
2930
- return signToken("wt-remote-binding+jwt", kid, claims, issuerSecret);
2931
- }
2932
-
2933
- export function verifyBinding(token , expect ) {
2934
- const verified = verifyToken(token, "wt-remote-binding+jwt", expect.issuerKeys);
2935
- if (!verified.ok) return refuse(verified.code === "shape" ? "binding" : verified.code, verified.detail);
2936
- const shaped = validate(BINDING_CLAIMS_SPEC, verified.value.claims, "$binding");
2937
- if (!shaped.ok) return refuse("binding", shaped.detail);
2938
- const b = shaped.value;
2939
- const times = checkTimes(b.iat, b.exp, expect.now, MAX_BINDING_LIFETIME_S, CLOCK_SKEW_MS);
2940
- if (!times.ok) return times;
2941
- if (expect.kind !== undefined && b.kind !== expect.kind) return refuse("binding", "$binding.kind: not the expected kind");
2942
- if (expect.deviceId !== undefined && b.device_id !== expect.deviceId) return refuse("wrong_device", "$binding.device_id");
2943
- if (expect.sub !== undefined && b.sub !== expect.sub) return refuse("account_mismatch", "$binding.sub");
2944
- if (expect.isRevoked?.(b)) return refuse("revoked", "$binding: revoked");
2945
- return accept(b);
2946
- }
2947
-
2948
- /** The signing key a verified binding names, as bytes. */
2949
- export const bindingSigningKey = (b ) => fromBase64Url(b.ed25519_pub) ;
2950
- export const bindingAgreementKey = (b ) => fromBase64Url(b.x25519_pub) ;
2951
- export const bindingFingerprint = (b ) =>
2952
- deviceFingerprint({ ed25519_pub: b.ed25519_pub, x25519_pub: b.x25519_pub });
2953
-
2954
3158
  // ---- packages/remote-protocol/src/crypto/assertion.ts
2955
3159
  /**
2956
3160
  * THE GATEWAY'S ADMISSION TICKET. The gateway holds no Passport credential and reads no Passport database: it trusts