worktrust 0.11.0 → 0.11.1

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:
@@ -1788,6 +1873,11 @@ export const COMMAND_PAYLOAD_SPECS = {
1788
1873
  prompt: nullable(text(MAX_PROMPT_CHARS, 1)),
1789
1874
  /** The session's name on the phone's project tree (2026-11-07), sealed; renameable with session.rename. */
1790
1875
  name: optional(nullable(text(MAX_SESSION_NAME, 1))),
1876
+ /**
1877
+ * Which of the adapter's reports to start (release 19, 2026-11-09): `terminal` runs the agent in a terminal session the
1878
+ * person can also attach at the desk. Absent means structured, as before.
1879
+ */
1880
+ mode: optional(oneOf(ADAPTER_MODES)),
1791
1881
  }),
1792
1882
  /**
1793
1883
  * 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 +1920,11 @@ export const COMMAND_PAYLOAD_SPECS = {
1830
1920
  /** A new name for the session (2026-11-07); answered with device.inventory, which lists every session by name. */
1831
1921
  "session.rename": object({ name: text(MAX_SESSION_NAME, 1) }),
1832
1922
  /** The last lines of a terminal session's screen, answered with agent.screen. */
1833
- "screen.read": object({ lines: int(1, 2000) }),
1923
+ /**
1924
+ * `follow` (release 19, 2026-11-09): true asks the computer to send the screen again whenever it changes (agent.screen,
1925
+ * coalesced) for a while (the computer's limit, renewed by every read that follows), false stops it. Absent: one read.
1926
+ */
1927
+ "screen.read": object({ lines: int(1, 2000), follow: optional(bool()) }),
1834
1928
  /** Ask for a device.inventory; `refresh_models` runs the agents' own model listers first. */
1835
1929
  "inventory.get": object({ refresh_models: bool() }),
1836
1930
  /** This computer's remote settings, each optional. Pausing from the phone is soft; `worktrust remote disable` at the
@@ -1846,6 +1940,8 @@ export const COMMAND_PAYLOAD_SPECS = {
1846
1940
  "pairing.revoke": object({}),
1847
1941
  /** Files from the phone and a local preview back (transfer.ts, 2026-11-07). */
1848
1942
  ...TRANSFER_COMMAND_SPECS,
1943
+ /** The live preview (release 19, live-preview.ts): session commands. */
1944
+ ...LIVE_COMMAND_SPECS,
1849
1945
  /**
1850
1946
  * One new, empty project folder named `name` inside the root `root_id` (2026-11-07), granted as a project; `git init`
1851
1947
  * in it only when the person enabled that for the root at the keyboard. Answered with project.created.
@@ -1927,6 +2023,10 @@ export const COMMAND_TTL_MS = {
1927
2023
  "preview.targets": 1 * MINUTE,
1928
2024
  "preview.render": 2 * MINUTE,
1929
2025
  "screen.read": 1 * MINUTE,
2026
+ "preview.live_start": 2 * MINUTE,
2027
+ "preview.live_input": 1 * MINUTE,
2028
+ "preview.live_viewport": 1 * MINUTE,
2029
+ "preview.live_follow": 1 * MINUTE,
1930
2030
  "inventory.get": 5 * MINUTE,
1931
2031
  "device.configure": 10 * MINUTE,
1932
2032
  "pairing.revoke": 24 * 60 * MINUTE,
@@ -1960,6 +2060,8 @@ export function validateCommandPayload (type , value
1960
2060
  if (type === "device.configure" && Object.keys(payload).length === 0) return refuse("payload", "$payload: names no setting");
1961
2061
  if (type === "attachment.put") { const bad = attachmentRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
1962
2062
  if (type === "preview.render") { const bad = previewRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
2063
+ if (type === "preview.live_start") { const bad = liveStartRule(payload ); if (bad) return refuse("payload", `$payload: ${bad}`); }
2064
+ 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
2065
  if (type === "project.create" && !projectNameOk((payload ).name))
1964
2066
  return refuse("payload", "$payload.name: one folder name of [A-Za-z0-9._-], not starting with a dot");
1965
2067
  if (type === "release.reorder") {
@@ -2124,6 +2226,8 @@ export const EVENT_BODY_SPECS = {
2124
2226
  project_label: nullable(label(256)),
2125
2227
  /** The name the phone gave it (agent.start's name, a release task's label), or null. */
2126
2228
  name: optional(nullable(label(100))),
2229
+ /** `terminal` for a session in a terminal the desk can attach (release 19); absent means structured. */
2230
+ mode: optional(oneOf(ADAPTER_MODES)),
2127
2231
  }),
2128
2232
  "command.device_received": object({}),
2129
2233
  /** started_at: the computer's clock when the acceptance began a turn (usage.ts); absent for any other acceptance. */
@@ -2227,6 +2331,8 @@ export const EVENT_BODY_SPECS = {
2227
2331
  task_id: optional(nullable(id("tsk"))),
2228
2332
  /** Background jobs its agent reports still running (2026-11-08: "ready, but a job is still running"); absent when it cannot tell. */
2229
2333
  background_jobs: optional(int(0, 99)),
2334
+ /** `terminal` for a terminal session (release 19); absent means structured. */
2335
+ mode: optional(oneOf(ADAPTER_MODES)),
2230
2336
  }),
2231
2337
  100,
2232
2338
  ),
@@ -2243,6 +2349,8 @@ export const EVENT_BODY_SPECS = {
2243
2349
  "agents.active": AGENTS_ACTIVE_SPEC,
2244
2350
  /** Attachments (session) and the local preview (device), transfer.ts. */
2245
2351
  ...TRANSFER_EVENT_SPECS,
2352
+ /** The live preview (release 19, live-preview.ts): its state, and its frames on the transient lane only. */
2353
+ ...LIVE_EVENT_SPECS,
2246
2354
  } ;
2247
2355
 
2248
2356
  export const DEVICE_EVENT_TYPES = Object.keys(EVENT_BODY_SPECS) ;
@@ -2317,7 +2425,8 @@ export function validateEventBody (type , value
2317
2425
  const r = validateAdapterReport(report);
2318
2426
  if (!r.ok) return refuse("payload", `$body.adapters: ${r.detail}`);
2319
2427
  }
2320
- if (new Set(inv.adapters.map((a) => a.adapter)).size !== inv.adapters.length) return refuse("payload", "$body.adapters: an adapter twice");
2428
+ // One report per (adapter, mode) since release 19: Claude Code structured and in a terminal are two reports.
2429
+ if (new Set(inv.adapters.map((a) => `${a.adapter}/${a.mode}`)).size !== inv.adapters.length) return refuse("payload", "$body.adapters: an adapter twice");
2321
2430
  }
2322
2431
  return checked;
2323
2432
  }
@@ -2393,6 +2502,20 @@ export const COMMAND_ENVELOPE_SPEC = object({
2393
2502
  authorization: b64({ exact: 64 }),
2394
2503
  });
2395
2504
 
2505
+ /**
2506
+ * THE TRANSIENT LANE (release 19, 2026-11-09). A pushed terminal screen (agent.screen with no command) is news only
2507
+ * until the next one: the computer keeps none, the relay buffers and records none, and a phone that reconnects asks for
2508
+ * the screen again (screen.read). It travels beside the session's ordered stream, never in it: its `event_seq` is the
2509
+ * lane's own number (rising per session; a computer starts it from its clock, so a restart never goes back), it never
2510
+ * moves the stream's cursor, and a phone applies one only when its number is above the last transient one it applied.
2511
+ * So the stream stays gap-free for every phone, whoever followed. Only the types below may take the lane.
2512
+ */
2513
+ export const EVENT_LANES = ["transient"] ;
2514
+ export const TRANSIENT_EVENT_TYPES = new Set (["agent.screen", "preview.frame"]);
2515
+ /** Types that may ONLY travel on the transient lane (a live preview's frames: never journaled, never replayed). */
2516
+ export const TRANSIENT_ONLY_TYPES = new Set (["preview.frame"]);
2517
+ export const isTransientEvent = (e ) => e.lane === "transient";
2518
+
2396
2519
  export const EVENT_ENVELOPE_SPEC = object({
2397
2520
  protocol_version: version,
2398
2521
  session_id: nullable(id("ses")),
@@ -2405,6 +2528,8 @@ export const EVENT_ENVELOPE_SPEC = object({
2405
2528
  command_id: nullable(id("cmd")),
2406
2529
  /** The content-free push hint (attention.ts). */
2407
2530
  notify: oneOf(NOTIFY_HINTS),
2531
+ /** Absent: the session's ordered stream. `transient`: beside it (EVENT_LANES above), kept by nobody. */
2532
+ lane: optional(oneOf(EVENT_LANES)),
2408
2533
  body_ciphertext: sealed(),
2409
2534
  });
2410
2535
 
@@ -2529,6 +2654,9 @@ export function validateEventEnvelope(value ) {
2529
2654
  if (!COMMAND_RECEIPT_EVENTS.has(type) && DEVICE_SCOPED_EVENTS.has(type) !== (e.session_id === null))
2530
2655
  return refuse("shape", "$event.session_id: a session event names a session, a device event none");
2531
2656
  if (COMMAND_RECEIPT_EVENTS.has(type) && e.command_id === null) return refuse("shape", "$event.command_id: a receipt names its command");
2657
+ if (isTransientEvent(e) && (!TRANSIENT_EVENT_TYPES.has(type) || e.command_id !== null || e.session_id === null || e.notify !== "none"))
2658
+ return refuse("shape", "$event.lane: only a pushed screen or frame, of a session, without a command or a push hint, is transient");
2659
+ 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
2660
  return checked;
2533
2661
  }
2534
2662
 
@@ -2651,11 +2779,12 @@ export function replayAfter (
2651
2779
  * A START IS CHECKED TWICE. The phone offers only what the computer reported; the computer checks again on receipt,
2652
2780
  * against its own current report, because a report the phone saw may be old and a phone may be wrong. A start that
2653
2781
  * 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.
2782
+ * cannot resume, is refused (command.rejected) and nothing is started; so is a start whose mode (structured, terminal) is not
2783
+ * the report's own (release 19).
2655
2784
  */
2656
2785
 
2657
2786
  export function checkStart(payload , report ) {
2658
- if (!report || report.adapter !== payload.adapter || !report.installed || !report.capabilities.start) return "unsupported";
2787
+ if (!report || report.adapter !== payload.adapter || report.mode !== (payload.mode ?? "structured") || !report.installed || !report.capabilities.start) return "unsupported";
2659
2788
  if (!isModelReported(report, payload.model)) return "unknown_model";
2660
2789
  if (!report.capabilities.permission_modes.includes(payload.permission_mode)) return "unsupported";
2661
2790
  if (payload.resume !== null && !report.capabilities.resume_by_id) return "unsupported";
package/remote-run.mjs CHANGED
@@ -22,10 +22,14 @@ import { inventory as listAgents, offered } from "./remote-inventory.mjs";
22
22
  const inventory = (o) => offered(listAgents(o), loadSettings());
23
23
  import { createApprovals } from "./remote-approvals.mjs";
24
24
  import { createSessions } from "./remote-sessions.mjs";
25
+ import { createTerminalSessions, withTerminal } from "./remote-terminal-sessions.mjs";
26
+ import { createTmux, NO_TMUX, writeTmuxConfig } from "./remote-adapter-terminal.mjs";
27
+ import { detectScreen } from "./remote-screen-states.mjs";
25
28
  import { createReleases } from "./remote-releases.mjs";
26
29
  import { createPipelines } from "./remote-pipeline.mjs";
27
30
  import { createAttachments } from "./remote-attachments.mjs";
28
31
  import { createPreview } from "./remote-preview.mjs";
32
+ import { createLivePreview } from "./remote-live-preview.mjs";
29
33
  import { appendPipelineMark } from "./remote-steered.mjs";
30
34
  import { createDaemonCore } from "./remote-daemon.mjs";
31
35
  import { connectGateway, webSocketAvailable } from "./remote-transport.mjs";
@@ -117,7 +121,10 @@ export async function runDaemon({ say = (l) => process.stdout.write(`${l}\n`) }
117
121
  const attachments = createAttachments({ journal, now: Date.now, emit: (...a) => core.emit(...a), log,
118
122
  sessionProject: (id) => { const s = journal.session(id); return s ? loadProjects().find((p) => p.project_id === s.project_id) ?? null : null; } });
119
123
  const preview = createPreview({ emit: (...a) => core.emit(...a), projects: loadProjects, grants: loadPreviewGrants, env: () => agentEnv(loadSettings()), log });
120
- const core = createDaemonCore({ local, issuerKeys: keysOf, journal, projectSecret: keys.projectSecret, attachments, preview, now: Date.now, random, log, send: (f) => transport?.send(f) ?? false, inventory: (refresh) => inventory({ env: agentEnv(loadSettings()), refresh }), online: () => transport?.ready() ?? false, approvals: null });
124
+ // The live preview (release 19): the session's granted page, live, over the browser's pipe; one per computer.
125
+ const live = createLivePreview({ emit: (...a) => core.emit(...a), grants: loadPreviewGrants, env: () => agentEnv(loadSettings()), log, now: Date.now,
126
+ sessionProject: (id) => { const s = journal.session(id); return s ? loadProjects().find((p) => p.project_id === s.project_id) ?? null : null; } });
127
+ const core = createDaemonCore({ local, issuerKeys: keysOf, journal, projectSecret: keys.projectSecret, attachments, preview, live, now: Date.now, random, log, send: (f) => transport?.send(f) ?? false, inventory: (refresh) => inventory({ env: agentEnv(loadSettings()), refresh }), online: () => transport?.ready() ?? false, approvals: null });
121
128
  const ctx = { journal, now: Date.now, random, deviceId: identity.device_id, emit: core.emit, paused: () => loadSettings().paused !== null || !loadSettings().enabled, phoneOnline: core.phoneOnline, controllers: core.controllers };
122
129
  const approvals = createApprovals(ctx);
123
130
  const socket = await approvals.listen(runDir);
@@ -127,6 +134,13 @@ export async function runDaemon({ say = (l) => process.stdout.write(`${l}\n`) }
127
134
  onTaskEnded: (id, outcome) => releases.taskEnded(id, outcome), onActivity: () => releases?.activity(),
128
135
  onSessionsChanged: () => core.emit(null, "device.inventory", core.inventoryBody(false)), attachments });
129
136
  ctx.onApprovalOpened = sessions.onApprovalOpened; ctx.onApprovalSettled = sessions.onApprovalSettled;
137
+ // Terminal sessions (release 19, off until `worktrust remote terminal on`): Claude Code in tmux on WorkTrust's own socket.
138
+ const tmuxFile = listAgents({ env: agentEnv(loadSettings()) }).files.tmux;
139
+ const tmux = tmuxFile ? createTmux({ file: tmuxFile, config: writeTmuxConfig(runDir), env: agentEnv(loadSettings()) }) : NO_TMUX;
140
+ const terminal = createTerminalSessions({ journal, now: Date.now, emit: core.emit, settings: loadSettings, projects: loadProjects, inventory: () => inventory({ env: agentEnv(loadSettings()) }),
141
+ tmux, claudeFile: () => listAgents({ env: agentEnv(loadSettings()) }).files["claude-code"], replay: core.replay, running: () => sessions.runningCount(), detect: (lines) => detectScreen("claude-code", lines), approvals,
142
+ onSessionsChanged: () => core.emit(null, "device.inventory", core.inventoryBody(false)) });
143
+ const registry = withTerminal(sessions, terminal);
130
144
  // Releases and pipelines (2026-11-07): one queue for every release's tasks, the reviewed pipeline of each project.
131
145
  const pipelines = createPipelines({ journal, now: Date.now, random, emit: core.emit, projects: loadProjects, reviews: loadPipelineReviews, log, logDir: remotePath("pipelines"),
132
146
  markLedger: appendPipelineMark, env: (prepend) => stageEnv(loadSettings(), prepend), onEnded: (p) => releases?.pipelineEnded(p), commandOf });
@@ -136,7 +150,7 @@ export async function runDaemon({ say = (l) => process.stdout.write(`${l}\n`) }
136
150
  ctx.plan = (session, op, args) => releases.plan(session, op, args);
137
151
  releases.recover(); // tasks an earlier daemon left running: interrupted, never run again
138
152
  pipelines.recover(); // and its pipeline runs
139
- core.attach(sessions, approvals, releases);
153
+ core.attach(registry, approvals, releases);
140
154
 
141
155
  const dispatchFrame = async (frame) => {
142
156
  if (frame.frame === "hello") core.receiveHello(frame.hello);
@@ -161,7 +175,8 @@ export async function runDaemon({ say = (l) => process.stdout.write(`${l}\n`) }
161
175
  stopping = true;
162
176
  approvals.close();
163
177
  await pipelines.stopAll();
164
- await sessions.stopAll();
178
+ await live.stopAll(); // the browser ended, its profile removed
179
+ await registry.stopAll(); // the structured agents; a terminal session lives on in tmux
165
180
  transport.close();
166
181
  release();
167
182
  process.exit(code);
@@ -0,0 +1,79 @@
1
+ /**
2
+ * A TERMINAL DIALOG, ANSWERED FROM A PHONE BY ITS SCREEN'S HASH (release 19, 2026-11-09; PRIOR-ART-ANALYSIS.md 2.3).
3
+ *
4
+ * When a terminal session's screen shows a permission dialog (remote-screen-states.mjs, claudeCodeDialog), the computer:
5
+ * 1. classifies what the dialog names (a command, a file) with its own policy (remote-policy.mjs). A dialog it cannot
6
+ * read, or of a class a phone may not decide, is never asked: it waits for the person at the computer;
7
+ * 2. asks through remote-approvals.mjs (the only sender of agent.approval_required), the action's input being the
8
+ * dialog's region exactly as drawn, so the hash the phone signs covers the very screen text it showed;
9
+ * 3. when a PHONE decided (never on a timeout, a lost phone or a session that ended), reads the screen again and presses
10
+ * the answer key only if the dialog's region still hashes the same, the key coming from the agent's allow-list
11
+ * (SCREEN_ANSWERS) and only where the dialog offers it (approve: the cursor on "1. Yes"; deny: an option with Esc).
12
+ * A changed dialog presses nothing and is asked again.
13
+ * One question per dialog: the same region is not asked twice; a dialog answered at the desk withdraws its question.
14
+ * Offered only where the adapter reports `approvals: "screen"`, which needs fixtures recorded from the real agent.
15
+ */
16
+ import { createHash } from "node:crypto";
17
+ import { isAbsolute, join } from "node:path";
18
+ import { classifyAction, phoneMayDecide } from "./remote-policy.mjs";
19
+ import { SCREEN_ANSWERS, screenDialog } from "./remote-screen-states.mjs";
20
+
21
+ const MAX_SHOWN = 16_000;
22
+ /** The dialog's region, hashed as drawn (lines joined with \n). */
23
+ export const regionHash = (region) => createHash("sha256").update(region.join("\n")).digest("base64url");
24
+
25
+ /** The dialog as an approval action: classified from what it names, shown (and hashed) as the screen draws it. */
26
+ export function screenAction(agent, dialog, projectPath) {
27
+ const args = dialog.tool === "Bash" ? { command: dialog.target ?? "" }
28
+ : dialog.tool && dialog.target ? { file_path: isAbsolute(dialog.target) ? dialog.target : join(projectPath, dialog.target) } : {};
29
+ const { action, reason } = classifyAction(agent, dialog.tool ?? "ScreenDialog", args, projectPath);
30
+ const shown = dialog.region.join("\n");
31
+ if (shown.length > MAX_SHOWN) return { action: { ...action, class: "other", input: `${shown.slice(0, MAX_SHOWN - 40)} [cut: too long to show exactly]` }, reason: "the dialog is too long to show exactly" };
32
+ return { action: { ...action, input: shown }, reason };
33
+ }
34
+
35
+ // ctx: { approvals, emit, tmux, report() (the terminal report), agent }
36
+ export function createScreenApprovals(ctx) {
37
+ const note = (s, text) => ctx.emit(s.session_id, "agent.output_delta", { stream: "tool", offset: 0, text }, s.command_id);
38
+
39
+ /** After a phone's decision: the screen again, the same hash, then the agent's own answer key, or nothing. */
40
+ async function answer(s, ask) {
41
+ if (ask.decision === null || s.closed) return; // no phone decided: nothing is pressed
42
+ ask.answering = true;
43
+ const cap = await ctx.tmux.capture(s.tmux, 100);
44
+ const now = cap ? screenDialog(ctx.agent, cap.lines) : null;
45
+ if (!now || regionHash(now.region) !== ask.hash) {
46
+ s.screenAsked = null; // the dialog now on the screen is asked again
47
+ note(s, "The dialog on the screen changed before your answer reached it: nothing was pressed.");
48
+ return;
49
+ }
50
+ const keys = ask.decision === "approve" ? (now.approve ? SCREEN_ANSWERS[ctx.agent].approve : null) : now.dismiss ? SCREEN_ANSWERS[ctx.agent].deny : null;
51
+ if (!keys) { note(s, "This dialog does not offer that answer here: nothing was pressed. Answer it at the computer."); return; }
52
+ for (const key of keys) await ctx.tmux.sendKey(s.tmux, key);
53
+ }
54
+
55
+ return {
56
+ answer,
57
+ /** One look at the screen (remote-terminal-sessions.mjs): a new dialog is asked once; a dialog gone withdraws its question. */
58
+ consider(s, lines) {
59
+ const dialog = ctx.report()?.capabilities.approvals === "screen" && Object.hasOwn(SCREEN_ANSWERS, ctx.agent) ? screenDialog(ctx.agent, lines) : null;
60
+ if (!dialog) {
61
+ if (s.screenAsk && !s.screenAsk.answering) ctx.approvals.withdraw(s.session_id, "the dialog was answered at the computer");
62
+ s.screenAsked = null;
63
+ return;
64
+ }
65
+ const hash = regionHash(dialog.region);
66
+ if (s.screenAsk?.hash === hash || s.screenAsked === hash) return;
67
+ if (s.screenAsk && !s.screenAsk.answering) ctx.approvals.withdraw(s.session_id, "the dialog changed on the screen");
68
+ s.screenAsked = hash;
69
+ const preset = screenAction(ctx.agent, dialog, s.projectPath);
70
+ if (!phoneMayDecide(preset.action)) { note(s, `This dialog is answered at the computer: ${preset.reason ?? "a phone may not decide it"}.`); return; }
71
+ const ask = { hash, decision: null, answering: false };
72
+ s.screenAsk = ask;
73
+ ctx.approvals.request(s, preset.action.tool, { screen: preset.action.input }, { ...preset, onPhone: (decision) => { ask.decision = decision; } })
74
+ .then(() => answer(s, ask))
75
+ .catch(() => {})
76
+ .finally(() => { if (s.screenAsk === ask) s.screenAsk = null; });
77
+ },
78
+ };
79
+ }