agent-yes 1.276.0 → 1.277.1

package/lab/ui/lab/index.md

@@ -19,7 +19,7 @@ That sounds like tooling. It is closer to a change of category.
 
 ## Why that is not a small difference
 
-Every agent CLI ships with the same assumption baked in: *a human is sitting right here.* It asks
+Every agent CLI ships with the same assumption baked in: _a human is sitting right here._ It asks
 before it edits. It draws a full-screen TUI for eyes that are watching. It dies when the terminal
 closes. Those are reasonable defaults, and they are also a ceiling — they cap an agent at exactly
 one person's attention, and attention is the scarcest thing in the building.
@@ -27,7 +27,7 @@ one person's attention, and attention is the scarcest thing in the building.
 agent-yes removes the assumption in the least invasive way available: it does not fork the CLIs, it
 does not need their APIs, and it does not wait for a vendor to ship a daemon mode. It runs the real
 binary in a pseudo-terminal and answers the questions a human would have answered. The terminal
-*is* the integration surface.
+_is_ the integration surface.
 
 What follows is the interesting part. Once one agent no longer needs a human in the loop, each
 capability forces the next:
@@ -48,16 +48,16 @@ because paying those bills honestly is more interesting than the original trick.
 The system reads cleanly top-down, and the
 [interactive architecture map](https://agent-yes.com/architecture.html) draws the same boxes as a graph:
 
-| Plane | What lives there |
-| --- | --- |
-| **① Agent core** | The PTY wrapper. Spawns any agent CLI, matches ready / enter / fatal patterns, restarts on crash, resumes sessions, propagates terminal size. Rust is the primary binary; TypeScript is the reference implementation. |
-| **② Local fabric** | `pids.jsonl` (every agent, both runtimes), a FIFO per pid for stdin, a raw PTY log per agent for stdout. Files, not a daemon. |
-| **③ Exposure** | One transport-agnostic handler, `apiFetch(req) → Response`. HTTP and the WebRTC bridge are both just callers; port tunnels and libp2p peers fold in next. |
-| **④ Trust & discovery** | Signaling that is a rendezvous only, an HKDF key split so the relay never holds a key, and signed capability tokens that carry their own scope. |
-| **⑤ Reach surfaces** | The browser console, the CLI on another box, embeddable widgets, a system tray, peers. |
+| Plane                   | What lives there                                                                                                                                                                                                      |
+| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **① Agent core**        | The PTY wrapper. Spawns any agent CLI, matches ready / enter / fatal patterns, restarts on crash, resumes sessions, propagates terminal size. Rust is the primary binary; TypeScript is the reference implementation. |
+| **② Local fabric**      | `pids.jsonl` (every agent, both runtimes), a FIFO per pid for stdin, a raw PTY log per agent for stdout. Files, not a daemon.                                                                                         |
+| **③ Exposure**          | One transport-agnostic handler, `apiFetch(req) → Response`. HTTP and the WebRTC bridge are both just callers; port tunnels and libp2p peers fold in next.                                                             |
+| **④ Trust & discovery** | Signaling that is a rendezvous only, an HKDF key split so the relay never holds a key, and signed capability tokens that carry their own scope.                                                                       |
+| **⑤ Reach surfaces**    | The browser console, the CLI on another box, embeddable widgets, a system tray, peers.                                                                                                                                |
 
 The seam that holds it together is plane ③. Because `Bun.serve` and the WebRTC bridge already call
-the *same in-process* `apiFetch`, a new transport is a new caller and never a new control plane.
+the _same in-process_ `apiFetch`, a new transport is a new caller and never a new control plane.
 That is what turns "three stacks" back into one system.
 
 ## What is actually true today
@@ -81,12 +81,12 @@ about the four places the current system is still cluttered.
 
 ## The ecosystem
 
-agent-yes is the fleet. Around it sit tools that give the fleet somewhere to *reach* — each a
+agent-yes is the fleet. Around it sit tools that give the fleet somewhere to _reach_ — each a
 standalone CLI in its own right, each usable without the others:
 
-| | |
-| --- | --- |
-| **[agent-yes](https://github.com/snomiao/agent-yes)** | run, watch, message and delegate to a fleet of AI coding agents |
+|                                                         |                                                                                                                                    |
+| ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| **[agent-yes](https://github.com/snomiao/agent-yes)**   | run, watch, message and delegate to a fleet of AI coding agents                                                                    |
 | **[slack-term](https://github.com/snomiao/slack-term)** | the human-comms surface — read and write Slack from a terminal, with a confirm gate built for operators who are sometimes machines |
 
 The connective tissue is a shared stance rather than a shared library: file-based state over

package/lab/ui/lab/posts/2026-06-15-e2ee-share-links.html

@@ -3,148 +3,144 @@ title: End-to-end encryption for agent-yes share links
 tag: Security
 summary: How share links stay private even if the signaling relay is compromised: an HKDF key split, AES-256-GCM with per-connection keys, and a fail-closed handshake.
 ---
+
 <p class="lede">
-        agent-yes share links now run an end-to-end-encrypted protocol. The signaling server that
-        introduces your browser to your machine never sees a key — so even if it is fully
-        compromised, it cannot read your terminal, type into your agents, or spawn new ones.
-      </p>
+  agent-yes share links now run an end-to-end-encrypted protocol. The signaling server that
+  introduces your browser to your machine never sees a key — so even if it is fully compromised, it
+  cannot read your terminal, type into your agents, or spawn new ones.
+</p>
 
-      <h2>What a share link does</h2>
-      <p>
-        When you run <code>ay serve --webrtc</code>, your machine connects to a tiny Cloudflare
-        signaling server and waits for a browser to open the printed link on
-        <code>agent-yes.com</code>. The signaling server is only a <em>matchmaker</em>: it relays
-        the WebRTC handshake (SDP + ICE) so the two sides can find each other, then your terminal
-        traffic flows <strong>peer-to-peer</strong> over an encrypted WebRTC DataChannel — it never
-        passes through the server. The room link looks like:
-      </p>
-      <pre><code>https://agent-yes.com/#&lt;room&gt;:e1.&lt;secret&gt;</code></pre>
+<h2>What a share link does</h2>
+<p>
+  When you run <code>ay serve --webrtc</code>, your machine connects to a tiny Cloudflare signaling
+  server and waits for a browser to open the printed link on <code>agent-yes.com</code>. The
+  signaling server is only a <em>matchmaker</em>: it relays the WebRTC handshake (SDP + ICE) so the
+  two sides can find each other, then your terminal traffic flows <strong>peer-to-peer</strong> over
+  an encrypted WebRTC DataChannel — it never passes through the server. The room link looks like:
+</p>
+<pre><code>https://agent-yes.com/#&lt;room&gt;:e1.&lt;secret&gt;</code></pre>
 
-      <h2>The threat: "what if the matchmaker is hacked?"</h2>
-      <p>
-        Previously, the link's token did double duty — it was both the value the server used to
-        match peers <em>and</em> the only shared secret. That meant the server
-        <em>saw the secret</em>. A compromised signaling server could therefore impersonate a
-        browser or man-in-the-middle the connection, and a breach would expose <em>every</em> user's
-        token at once. The bar we want instead:
-      </p>
-      <div class="note">
-        A fully compromised signaling server (or an active network attacker who can rewrite the
-        relayed handshake) may slow you down or learn metadata — but must
-        <strong>never</strong> read terminal I/O, inject input, spawn agents, or recover any key.
-      </div>
+<h2>The threat: "what if the matchmaker is hacked?"</h2>
+<p>
+  Previously, the link's token did double duty — it was both the value the server used to match
+  peers <em>and</em> the only shared secret. That meant the server <em>saw the secret</em>. A
+  compromised signaling server could therefore impersonate a browser or man-in-the-middle the
+  connection, and a breach would expose <em>every</em> user's token at once. The bar we want
+  instead:
+</p>
+<div class="note">
+  A fully compromised signaling server (or an active network attacker who can rewrite the relayed
+  handshake) may slow you down or learn metadata — but must
+  <strong>never</strong> read terminal I/O, inject input, spawn agents, or recover any key.
+</div>
 
-      <h2>One secret, two derived keys (the HKDF split)</h2>
-      <p>
-        The link still carries one 32-byte secret <code>S</code>. We run it through HKDF-SHA256 to
-        derive two unrelated values:
-      </p>
-      <pre><code>authToken = HKDF(S, "ay/ay-e2e-1/auth")   →  the ONLY value the server sees
+<h2>One secret, two derived keys (the HKDF split)</h2>
+<p>
+  The link still carries one 32-byte secret <code>S</code>. We run it through HKDF-SHA256 to derive
+  two unrelated values:
+</p>
+<pre><code>authToken = HKDF(S, "ay/ay-e2e-1/auth")   →  the ONLY value the server sees
 e2e keys  = HKDF(S, "ay/ay-e2e-1/key/…")  →  never leave your machine or browser</code></pre>
-      <p>
-        HKDF is one-way, so from <code>authToken</code> the server cannot recover <code>S</code> or
-        the encryption keys. The actual terminal frames are sealed with AES-256-GCM under keys the
-        server has never seen. Because the link is pasted directly between the two endpoints, both
-        sides already share <code>S</code> without the server ever being told it.
-      </p>
+<p>
+  HKDF is one-way, so from <code>authToken</code> the server cannot recover <code>S</code> or the
+  encryption keys. The actual terminal frames are sealed with AES-256-GCM under keys the server has
+  never seen. Because the link is pasted directly between the two endpoints, both sides already
+  share <code>S</code> without the server ever being told it.
+</p>
 
-      <h2>The subtle part nobody gets right: nonce reuse</h2>
-      <p>
-        AES-GCM is catastrophic if a <code>(key, nonce)</code> pair ever repeats — it leaks
-        plaintext <em>and</em> lets an attacker forge messages. The naive design (one key per room
-        plus a per-connection counter) reuses nonces across reconnects, host restarts, and multiple
-        browsers in the same room. Our fix: derive the encryption keys
-        <strong>per connection</strong> by folding the live DTLS handshake fingerprint into HKDF as
-        the salt. Every session and every peer therefore gets fresh keys, so a counter that restarts
-        at 0 is always paired with a never-before-used key. We also use
-        <strong>directional keys</strong>
-        (host→client and client→host are different keys), so the two senders never share a nonce
-        space.
-      </p>
+<h2>The subtle part nobody gets right: nonce reuse</h2>
+<p>
+  AES-GCM is catastrophic if a <code>(key, nonce)</code> pair ever repeats — it leaks plaintext
+  <em>and</em> lets an attacker forge messages. The naive design (one key per room plus a
+  per-connection counter) reuses nonces across reconnects, host restarts, and multiple browsers in
+  the same room. Our fix: derive the encryption keys <strong>per connection</strong> by folding the
+  live DTLS handshake fingerprint into HKDF as the salt. Every session and every peer therefore gets
+  fresh keys, so a counter that restarts at 0 is always paired with a never-before-used key. We also
+  use
+  <strong>directional keys</strong>
+  (host→client and client→host are different keys), so the two senders never share a nonce space.
+</p>
 
-      <h2>Binding to the real connection (anti-MITM), done right</h2>
-      <p>
-        We hash both peers' DTLS fingerprints — plus the handshake role and ICE ufrag — from the
-        negotiated session, and use that hash as <strong>both</strong> the HKDF salt for the keys
-        <strong>and</strong> the authenticated data on every frame. On top of that, the channel runs
-        a mandatory, bidirectional <strong>key-confirmation handshake</strong> (each side sends a
-        fresh challenge nonce and must see it echoed back) that has to complete in
-        <em>both</em> directions before a single byte of terminal I/O is processed. If a relay sat
-        in the middle, the fingerprints differ, the keys differ, confirmation fails, and the
-        connection <span class="no">closes</span> — there is no "connected but unverified" window
-        and no silent fallback.
-      </p>
+<h2>Binding to the real connection (anti-MITM), done right</h2>
+<p>
+  We hash both peers' DTLS fingerprints — plus the handshake role and ICE ufrag — from the
+  negotiated session, and use that hash as <strong>both</strong> the HKDF salt for the keys
+  <strong>and</strong> the authenticated data on every frame. On top of that, the channel runs a
+  mandatory, bidirectional <strong>key-confirmation handshake</strong> (each side sends a fresh
+  challenge nonce and must see it echoed back) that has to complete in <em>both</em> directions
+  before a single byte of terminal I/O is processed. If a relay sat in the middle, the fingerprints
+  differ, the keys differ, confirmation fails, and the connection <span class="no">closes</span> —
+  there is no "connected but unverified" window and no silent fallback.
+</p>
 
-      <h2>Replay, reordering, and forged aborts</h2>
-      <p>
-        The DataChannel is reliable and ordered, and we add a mandatory monotonic frame counter,
-        128-bit random request ids, and per-stream sequence numbers. So a captured frame can't be
-        replayed to re-run a command, a stale "abort" can't cancel a fresh request, and a truncated
-        stream can't masquerade as a complete response.
-      </p>
+<h2>Replay, reordering, and forged aborts</h2>
+<p>
+  The DataChannel is reliable and ordered, and we add a mandatory monotonic frame counter, 128-bit
+  random request ids, and per-stream sequence numbers. So a captured frame can't be replayed to
+  re-run a command, a stale "abort" can't cancel a fresh request, and a truncated stream can't
+  masquerade as a complete response.
+</p>
 
-      <h2>Fail closed, always</h2>
-      <p>
-        Encrypted links carry a version marker (<code>#room:e1.&lt;secret&gt;</code>). The grammar
-        is strict: anything that looks like a marker but isn't exactly <code>e1.</code> + 64 hex is
-        rejected, never quietly treated as a legacy link. Legacy plaintext is hard-disabled in the
-        client, the host refuses to bridge a plaintext channel for an encrypted room, and on any
-        version skew, missing marker, bad tag, fingerprint mismatch, or confirmation timeout we
-        <span class="no">refuse</span> rather than downgrade.
-      </p>
+<h2>Fail closed, always</h2>
+<p>
+  Encrypted links carry a version marker (<code>#room:e1.&lt;secret&gt;</code>). The grammar is
+  strict: anything that looks like a marker but isn't exactly <code>e1.</code> + 64 hex is rejected,
+  never quietly treated as a legacy link. Legacy plaintext is hard-disabled in the client, the host
+  refuses to bridge a plaintext channel for an encrypted room, and on any version skew, missing
+  marker, bad tag, fingerprint mismatch, or confirmation timeout we
+  <span class="no">refuse</span> rather than downgrade.
+</p>
 
-      <h2>One implementation, no dependencies</h2>
-      <p>
-        The crypto is a single WebCrypto module shared by both ends — the browser imports it, and
-        the host (running on Bun, which ships WebCrypto) bundles the exact same file. One
-        implementation means the two sides can't drift apart, and there are no new dependencies. A
-        test suite pins the key derivation, the frame format, and every fail-closed path.
-      </p>
+<h2>One implementation, no dependencies</h2>
+<p>
+  The crypto is a single WebCrypto module shared by both ends — the browser imports it, and the host
+  (running on Bun, which ships WebCrypto) bundles the exact same file. One implementation means the
+  two sides can't drift apart, and there are no new dependencies. A test suite pins the key
+  derivation, the frame format, and every fail-closed path.
+</p>
 
-      <h2>What a hacked server gets — and doesn't</h2>
-      <table>
-        <tr>
-          <th></th>
-          <th>Before</th>
-          <th>Now</th>
-        </tr>
-        <tr>
-          <td>Read your terminal I/O</td>
-          <td class="no">possible (sees the secret)</td>
-          <td class="ok">no — keys never reach the server</td>
-        </tr>
-        <tr>
-          <td>Inject input / spawn agents</td>
-          <td class="no">possible</td>
-          <td class="ok">no — frames it forges fail decryption</td>
-        </tr>
-        <tr>
-          <td>Harvest every user's secret in a breach</td>
-          <td class="no">yes (stores raw tokens)</td>
-          <td class="ok">no — only one-way authTokens</td>
-        </tr>
-        <tr>
-          <td>DoS / see metadata (rooms, timing, IPs)</td>
-          <td class="no">yes</td>
-          <td class="no">still yes</td>
-        </tr>
-      </table>
+<h2>What a hacked server gets — and doesn't</h2>
+<table>
+  <tr>
+    <th></th>
+    <th>Before</th>
+    <th>Now</th>
+  </tr>
+  <tr>
+    <td>Read your terminal I/O</td>
+    <td class="no">possible (sees the secret)</td>
+    <td class="ok">no — keys never reach the server</td>
+  </tr>
+  <tr>
+    <td>Inject input / spawn agents</td>
+    <td class="no">possible</td>
+    <td class="ok">no — frames it forges fail decryption</td>
+  </tr>
+  <tr>
+    <td>Harvest every user's secret in a breach</td>
+    <td class="no">yes (stores raw tokens)</td>
+    <td class="ok">no — only one-way authTokens</td>
+  </tr>
+  <tr>
+    <td>DoS / see metadata (rooms, timing, IPs)</td>
+    <td class="no">yes</td>
+    <td class="no">still yes</td>
+  </tr>
+</table>
 
-      <h2>What changed for you</h2>
-      <p>
-        Old share links rotate to a fresh encrypted room automatically on upgrade — re-open the new
-        printed link (or <code>rm ~/.agent-yes/.share-room</code> to force a rotation). The
-        signaling server got one small additive change (it pins a protocol version) but still never
-        sees a key.
-      </p>
+<h2>What changed for you</h2>
+<p>
+  Old share links rotate to a fresh encrypted room automatically on upgrade — re-open the new
+  printed link (or <code>rm ~/.agent-yes/.share-room</code> to force a rotation). The signaling
+  server got one small additive change (it pins a protocol version) but still never sees a key.
+</p>
 
-      <h2>Honest limitations</h2>
-      <p>
-        End-to-end encryption protects the <em>channel</em>, not the <em>capability</em>: anyone you
-        hand the full link to gets control, so treat it like an SSH key. The server can still deny
-        service and observe metadata (which rooms exist, connection timing, IPs via ICE). The
-        channel binding uses DTLS fingerprints from the SDP rather than a true RFC 5705 keying
-        exporter (a limitation of the host's WebRTC stack today), and the secret still sits in your
-        browser's local storage until it ages out. Forward secrecy / rekeying, and the separate
-        codehost transport, are future work.
-      </p>
+<h2>Honest limitations</h2>
+<p>
+  End-to-end encryption protects the <em>channel</em>, not the <em>capability</em>: anyone you hand
+  the full link to gets control, so treat it like an SSH key. The server can still deny service and
+  observe metadata (which rooms exist, connection timing, IPs via ICE). The channel binding uses
+  DTLS fingerprints from the SDP rather than a true RFC 5705 keying exporter (a limitation of the
+  host's WebRTC stack today), and the secret still sits in your browser's local storage until it
+  ages out. Forward secrecy / rekeying, and the separate codehost transport, are future work.
+</p>