agent-yes 1.231.0 → 1.232.0

package/ts/channels/browser.ts

@@ -0,0 +1,287 @@
+// Browser channel client: `import AyChannel from "agent-yes/channels"`.
+//
+// The frontend counterpart to the CLI. It joins the SAME WebRTC mesh as any
+// `ay ch sync` peer using the isomorphic ChannelPeer (peer.ts) wired to the
+// browser's native RTCPeerConnection + WebSocket, persists to LocalStorage
+// (store.browser.ts), and renders a self-contained floating chat window (Shadow
+// DOM) so an agent and a human can talk on the same page — with no server ever
+// storing a message.
+//
+//   const ch = new AyChannel("ay://ch/s.agent-yes.com/<room>#e1.<S>");
+//   await ch.start();
+//   ch.on("message", render);
+//   ch.mount();                 // floating widget, or ch.mount(el) to embed
+//   await ch.send("hello");
+
+import { deriveChannelId, deriveRoom, parseChannelLink, secretFromTopic } from "./link.ts";
+import { hlcSend } from "./hlc.ts";
+import { makeOp, type Role } from "./op.ts";
+import { maxHlc, renderThread, type Message } from "./store.ts";
+import { randomHex } from "../../lab/ui/e2e.js";
+import { ChannelPeer } from "./peer.ts";
+import { LocalStorageStore } from "./store.browser.ts";
+
+export interface AyChannelInfo {
+  /** A channel invite link (ay://ch/… or https://…/w/#ch=…). If given, room/sighost/s are parsed from it. */
+  link?: string;
+  room?: string;
+  sighost?: string;
+  /** Secret S (64-hex). */
+  s?: string;
+  name?: string;
+  role?: Role;
+  /** Stable author id; auto-generated + persisted per channel if omitted. */
+  author?: string;
+}
+
+type Events = "message" | "peers" | "ready";
+
+export class AyChannel {
+  readonly room: string;
+  readonly sighost: string;
+  readonly s: string;
+  channelId = "";
+  name: string;
+  role: Role;
+  author = "";
+  private store?: LocalStorageStore;
+  private peer?: ChannelPeer;
+  private listeners = new Map<Events, Set<(arg: any) => void>>();
+  private started = false;
+  private peers = 0;
+
+  /**
+   * Build a channel whose identity is DERIVED from a topic string (e.g. the page
+   * URL) — same topic ⇒ same room, no invite needed. Public to anyone with the
+   * topic (see secretFromTopic). This is what the page bookmarklet uses.
+   */
+  static async fromTopic(
+    topic: string,
+    opts?: { sighost?: string; name?: string; role?: Role },
+  ): Promise<AyChannel> {
+    const s = await secretFromTopic(topic);
+    const sighost = opts?.sighost ?? "s.agent-yes.com";
+    const room = await deriveRoom(s);
+    return new AyChannel({ room, sighost, s, name: opts?.name, role: opts?.role });
+  }
+
+  constructor(info: string | AyChannelInfo) {
+    const o = typeof info === "string" ? { link: info } : info;
+    const link = o.link ? parseChannelLink(o.link) : null;
+    this.room = o.room ?? link?.room ?? "";
+    this.sighost = o.sighost ?? link?.sighost ?? "s.agent-yes.com";
+    this.s = o.s ?? link?.s ?? "";
+    if (!this.room || !this.s) throw new Error("AyChannel: need a link or {room, s}");
+    this.name = o.name ?? "guest";
+    this.role = o.role ?? "human";
+    if (o.author) this.author = o.author;
+  }
+
+  /** Derive identity, open the LocalStorage replica, and join the mesh. */
+  async start(): Promise<void> {
+    if (this.started) return;
+    this.started = true;
+    this.channelId = await deriveChannelId(this.s);
+    this.store = new LocalStorageStore(this.channelId);
+    this.loadIdentity();
+    this.peer = new ChannelPeer({
+      room: this.room,
+      sighost: this.sighost,
+      s: this.s,
+      rtc: (globalThis as any).RTCPeerConnection,
+      WebSocketImpl: (globalThis as any).WebSocket,
+      store: this.store,
+      onOp: () => this.emit("message", undefined),
+      onPeers: (n) => {
+        this.peers = n;
+        this.emit("peers", n);
+      },
+    });
+    await this.peer.start();
+    this.emit("ready", undefined);
+  }
+
+  /** Identity is stable per channel across reloads (a returning tab keeps its author id). */
+  private loadIdentity(): void {
+    const key = `ay29ch-id:${this.channelId}`;
+    let saved: { author: string; name: string; role: Role } | null = null;
+    try {
+      saved = JSON.parse(localStorage.getItem(key) || "null");
+    } catch {
+      /* ignore */
+    }
+    // Author is stable across reloads; name/role fall back to the saved ones only
+    // when the caller left them at their defaults.
+    this.author ||= saved?.author || randomHex(8);
+    if (saved?.name && this.name === "guest") this.name = saved.name;
+    if (saved?.role && this.role === "human") this.role = saved.role;
+    try {
+      localStorage.setItem(
+        key,
+        JSON.stringify({ author: this.author, name: this.name, role: this.role }),
+      );
+    } catch {
+      /* ignore */
+    }
+  }
+
+  /** The rendered thread (folded messages, ordered). */
+  async messages(): Promise<Message[]> {
+    return renderThread(await (this.store?.all() ?? Promise.resolve([])));
+  }
+
+  /** The current confirmed-peer count (presence). */
+  peerCount(): number {
+    return this.peers;
+  }
+
+  /** Post a message: persist locally + broadcast to the mesh. */
+  async send(text: string): Promise<void> {
+    if (!this.store || !this.peer) throw new Error("AyChannel: call start() first");
+    const t = text.trim();
+    if (!t) return;
+    const ops = await this.store.all();
+    const hlc = hlcSend(maxHlc(ops), Date.now(), this.author);
+    const op = makeOp({
+      author: this.author,
+      name: this.name,
+      role: this.role,
+      hlc,
+      kind: "msg",
+      body: t,
+    });
+    await this.peer.publish(op); // append + broadcast
+    this.emit("message", undefined);
+  }
+
+  on(evt: Events, cb: (arg: any) => void): this {
+    (this.listeners.get(evt) ?? this.listeners.set(evt, new Set()).get(evt)!).add(cb);
+    return this;
+  }
+  off(evt: Events, cb: (arg: any) => void): this {
+    this.listeners.get(evt)?.delete(cb);
+    return this;
+  }
+  private emit(evt: Events, arg: any): void {
+    for (const cb of this.listeners.get(evt) ?? []) {
+      try {
+        cb(arg);
+      } catch {
+        /* a listener throwing must not break delivery */
+      }
+    }
+  }
+
+  close(): void {
+    this.peer?.close();
+    this.widget?.remove();
+  }
+
+  // --- floating chat widget -------------------------------------------------
+  // DOM globals (document/HTMLElement) aren't in the Node/Bun type lib this
+  // package compiles against, so DOM access here is intentionally loosely typed;
+  // this method only ever runs in a browser.
+
+  private widget?: any;
+
+  /**
+   * Render the floating chat window. With no target it mounts a fixed-position
+   * bubble in the corner; pass an element to embed it there. Auto-calls start().
+   */
+  mount(target?: any, opts?: { open?: boolean }): any {
+    if (this.widget) return this.widget;
+    const doc: any = (globalThis as any).document;
+    const host = doc.createElement("div");
+    host.setAttribute("data-aychannel", this.channelId || this.room);
+    const root = host.attachShadow({ mode: "open" });
+    root.innerHTML = WIDGET_HTML;
+    this.widget = host;
+    (target ?? doc.body).appendChild(host);
+
+    const list = root.getElementById("list")!;
+    const input = root.getElementById("input") as any;
+    const form = root.getElementById("form") as any;
+    const badge = root.getElementById("peers")!;
+    const panel = root.getElementById("panel")!;
+    const toggle = root.getElementById("toggle")!;
+
+    const esc = (s: string) =>
+      s.replace(/[&<>"]/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;" })[c]!);
+    const render = async () => {
+      const msgs = await this.messages();
+      list.innerHTML = msgs
+        .map((m) => {
+          const mine = m.author === this.author;
+          const time = new Date(m.ms).toLocaleTimeString([], {
+            hour: "2-digit",
+            minute: "2-digit",
+          });
+          const body = m.deleted ? "<i>message deleted</i>" : esc(m.text);
+          return `<div class="msg ${mine ? "mine" : ""} ${m.role}"><div class="meta">${esc(m.name)} · ${time}</div><div class="body">${body}</div></div>`;
+        })
+        .join("");
+      list.scrollTop = list.scrollHeight;
+    };
+
+    form.addEventListener("submit", (e: any) => {
+      e.preventDefault();
+      const text = input.value;
+      input.value = "";
+      void this.send(text);
+    });
+    toggle.addEventListener("click", () => panel.classList.toggle("open"));
+    if (opts?.open) panel.classList.add("open");
+    this.on("message", () => void render());
+    this.on("peers", () => (badge.textContent = String(this.peers)));
+
+    void (async () => {
+      if (!this.started) await this.start();
+      await render();
+      badge.textContent = String(this.peers);
+    })();
+
+    return host;
+  }
+}
+
+// Self-contained styles + markup for the Shadow DOM widget (no external assets).
+const WIDGET_HTML = `
+<style>
+  :host { all: initial; }
+  * { box-sizing: border-box; font-family: system-ui, -apple-system, sans-serif; }
+  #toggle {
+    position: fixed; right: 20px; bottom: 20px; z-index: 2147483000;
+    width: 52px; height: 52px; border-radius: 50%; border: none; cursor: pointer;
+    background: #4f46e5; color: #fff; font-size: 22px; box-shadow: 0 4px 16px rgba(0,0,0,.3);
+  }
+  #panel {
+    position: fixed; right: 20px; bottom: 84px; z-index: 2147483000;
+    width: min(360px, 92vw); height: min(520px, 70vh); display: none;
+    flex-direction: column; background: #1b1d24; color: #e6e6ea; border-radius: 14px;
+    box-shadow: 0 12px 40px rgba(0,0,0,.45); overflow: hidden; border: 1px solid #2c2f3a;
+  }
+  #panel.open { display: flex; }
+  header { padding: 12px 14px; background: #23262f; display: flex; align-items: center; gap: 8px; }
+  header .title { font-weight: 600; font-size: 14px; }
+  header .peers { margin-left: auto; font-size: 12px; opacity: .8; background: #4f46e5; border-radius: 10px; padding: 1px 8px; }
+  #list { flex: 1; overflow-y: auto; padding: 12px; display: flex; flex-direction: column; gap: 8px; }
+  .msg { max-width: 82%; }
+  .msg .meta { font-size: 11px; opacity: .6; margin-bottom: 2px; }
+  .msg .body { background: #2c2f3a; padding: 7px 10px; border-radius: 10px; font-size: 13px; line-height: 1.35; white-space: pre-wrap; word-break: break-word; }
+  .msg.agent .body { border-left: 3px solid #10b981; }
+  .msg.mine { align-self: flex-end; text-align: right; }
+  .msg.mine .body { background: #4f46e5; color: #fff; }
+  #form { display: flex; gap: 6px; padding: 10px; border-top: 1px solid #2c2f3a; }
+  #input { flex: 1; background: #23262f; border: 1px solid #363a46; color: #e6e6ea; border-radius: 8px; padding: 8px 10px; font-size: 13px; }
+  #form button { background: #4f46e5; color: #fff; border: none; border-radius: 8px; padding: 0 14px; cursor: pointer; font-size: 13px; }
+</style>
+<button id="toggle" title="Chat">💬</button>
+<section id="panel">
+  <header><span class="title">Channel</span><span class="peers" id="peers">0</span></header>
+  <div id="list"></div>
+  <form id="form"><input id="input" placeholder="Message…" autocomplete="off" /><button type="submit">Send</button></form>
+</section>
+`;
+
+export default AyChannel;
+export * from "./index.ts";

package/ts/channels/hlc.ts

@@ -0,0 +1,67 @@
+// Hybrid Logical Clock (HLC) for ay channels.
+//
+// A channel is a grow-only set of immutable ops replicated across peers with no
+// coordinator (see store.ts). To display those ops in a stable, causally-sensible
+// order every replica must agree on, each op carries an HLC timestamp: a wall
+// clock reading fused with a per-node counter so that (a) order roughly tracks
+// real time, (b) concurrent ops from different nodes get a deterministic
+// tie-break, and (c) an op always sorts AFTER every op its author had already
+// seen when it was created (causality).
+//
+// The timestamp is encoded as a FIXED-WIDTH, lexicographically-sortable string
+//   "<ms:15><SEP><ctr:6><SEP><node>"
+// so a plain string compare reproduces the numeric HLC order — which lets the
+// jsonl store and the wire protocol sort without parsing. This module is
+// dependency-free and isomorphic (Node + browser).
+
+const MS_WIDTH = 15; // ms since epoch; 15 digits lasts past year 33000
+const CTR_WIDTH = 6; // per-ms counter; 10^6 ops sharing one ms is astronomically safe
+const SEP = "."; // 0x2e < '0' (0x30) so, with fixed widths, it never reorders fields
+
+export interface Hlc {
+  ms: number;
+  ctr: number;
+  node: string;
+}
+
+/** Encode an HLC as its sortable string form. */
+export function formatHlc(ms: number, ctr: number, node: string): string {
+  if (ms < 0 || ctr < 0) throw new Error("hlc: negative component");
+  if (ms >= 10 ** MS_WIDTH || ctr >= 10 ** CTR_WIDTH) throw new Error("hlc: component overflow");
+  return `${String(ms).padStart(MS_WIDTH, "0")}${SEP}${String(ctr).padStart(CTR_WIDTH, "0")}${SEP}${node}`;
+}
+
+/** Parse a sortable HLC string back into its components. Throws on malformed input. */
+export function parseHlc(s: string): Hlc {
+  const parts = s.split(SEP);
+  if (parts.length < 3) throw new Error("hlc: malformed");
+  const ms = Number(parts[0]);
+  const ctr = Number(parts[1]);
+  // node ids never contain SEP, but be defensive if one ever does.
+  const node = parts.slice(2).join(SEP);
+  if (!Number.isInteger(ms) || !Number.isInteger(ctr) || !node) throw new Error("hlc: malformed");
+  return { ms, ctr, node };
+}
+
+/**
+ * Numeric HLC comparison. Equivalent to a plain string compare of the sortable
+ * form (that's the point of the fixed-width encoding), but exposed explicitly so
+ * callers reading structured HLCs don't have to reconstruct the string.
+ */
+export function compareHlc(a: string, b: string): number {
+  return a < b ? -1 : a > b ? 1 : 0;
+}
+
+/**
+ * Produce the HLC for a new local op. `prevMax` is the greatest HLC this replica
+ * has already stored (from ANY author — see store.maxHlc); passing it makes the
+ * result monotonic across process restarts and causally after everything seen,
+ * with no separate clock-state file to persist. `physNow` is the wall clock
+ * (Date.now()); `node` is this participant's stable id.
+ */
+export function hlcSend(prevMax: string | null, physNow: number, node: string): string {
+  const prev = prevMax ? parseHlc(prevMax) : { ms: 0, ctr: 0 };
+  if (physNow > prev.ms) return formatHlc(physNow, 0, node);
+  // wall clock hasn't advanced past what we've seen — keep the ms, bump the counter
+  return formatHlc(prev.ms, prev.ctr + 1, node);
+}

package/ts/channels/index.ts

@@ -0,0 +1,10 @@
+// Public surface of the channels core — imported by the CLI (ts/channels.ts),
+// the serve daemon (Phase 2), and re-exported as the npm `agent-yes/channels`
+// subpath + browser lib (Phase 3). Only isomorphic, dependency-free modules are
+// re-exported here; the Node-only jsonl backend (store.node.ts) is imported
+// directly by Node callers so a browser bundle never pulls in `fs`.
+
+export * from "./hlc.ts";
+export * from "./op.ts";
+export * from "./store.ts";
+export * from "./link.ts";

package/ts/channels/link.ts

@@ -0,0 +1,103 @@
+// Channel identity + invite links — pure, isomorphic, native-free (kept off
+// node-datachannel like webrtcLink.ts, so parsing/derivation never loads the
+// WebRTC addon and stays unit-testable).
+//
+// A channel's shared secret S is the same `e1.<64hex>` value the WebRTC share
+// links use (e2e.js). Everything else is derived from S so peers who hold it
+// agree without exchanging anything the server can read:
+//   - channelId : names the LOCAL replica file/key; topic-blind, cwd-portable.
+//   - room      : the signaling rendezvous name (server sees only this + authToken).
+// The topic string is a purely local label — it never appears in a link and
+// never leaves the machine.
+
+import { parseSecret, validateS } from "../../lab/ui/e2e.js";
+
+export const CH_DEFAULT_SIGHOST = "s.agent-yes.com";
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const subtle = globalThis.crypto.subtle;
+const enc = new TextEncoder();
+
+async function sha256Hex(input: string): Promise<string> {
+  const digest = new Uint8Array(await subtle.digest("SHA-256", enc.encode(input)));
+  let s = "";
+  for (const b of digest) s += b.toString(16).padStart(2, "0");
+  return s;
+}
+
+/** Local replica id: `sha256("ay/ch/id\n" + S)[:16]`. Topic-blind. */
+export async function deriveChannelId(s: string): Promise<string> {
+  return (await sha256Hex(`ay/ch/id\n${validateS(s)}`)).slice(0, 16);
+}
+
+/** Signaling rendezvous name: `"c" + sha256("ay/ch/room\n" + S)[:12]`. */
+export async function deriveRoom(s: string): Promise<string> {
+  return "c" + (await sha256Hex(`ay/ch/room\n${validateS(s)}`)).slice(0, 12);
+}
+
+/**
+ * Deterministic channel secret from a public topic string (e.g. a page URL) —
+ * `sha256("ay/ch/topic/v1\n" + topic)`, a full 64-hex S. Everyone who derives
+ * from the SAME topic gets the SAME channel, so a page can "join by its URL" with
+ * no invite exchange (the bookmarklet + `ay ch mk --topic`).
+ *
+ * SECURITY: this makes the channel PUBLIC to anyone who knows the topic (topic =
+ * membership). Message contents still stay E2E from the signaling server, but it
+ * is NOT a private channel — use a random secret (the default) for those.
+ */
+export async function secretFromTopic(topic: string): Promise<string> {
+  return sha256Hex(`ay/ch/topic/v1\n${topic}`);
+}
+
+export interface ChannelLink {
+  sighost: string;
+  room: string;
+  /** The raw 64-hex secret S (marker stripped). */
+  s: string;
+}
+
+/** True if `str` looks like a channel invite link. */
+export function isChannelLink(str: string): boolean {
+  return str.startsWith("ay://ch/") || (/^https?:\/\//.test(str) && str.includes("#ch="));
+}
+
+/**
+ * Format a channel invite:
+ *   ay://ch/<sighost>/<room>#e1.<64hex>
+ * The secret rides the fragment; on the https form it is never sent to a server.
+ */
+export function formatChannelLink(link: ChannelLink): string {
+  return `ay://ch/${link.sighost}/${link.room}#e1.${validateS(link.s)}`;
+}
+
+/** Browser-console form: https://<host>/w/#ch=<room>:e1.<64hex>[@<sighost>]. */
+export function formatChannelWebLink(link: ChannelLink, webHost = "agent-yes.com"): string {
+  const at = link.sighost === CH_DEFAULT_SIGHOST ? "" : `@${link.sighost}`;
+  return `https://${webHost}/w/#ch=${link.room}:e1.${validateS(link.s)}${at}`;
+}
+
+/**
+ * Parse either invite form back into { sighost, room, s }. Returns null if the
+ * string isn't a recognizable channel link; throws (via parseSecret) if the
+ * secret slot is present but malformed — never silently downgrades.
+ */
+export function parseChannelLink(link: string): ChannelLink | null {
+  const ay = /^ay:\/\/ch\/([^/]+)\/([^#]+)#(.+)$/.exec(link);
+  if (ay) {
+    const { s } = parseSecret(ay[3]!);
+    if (!HEX64.test(s)) throw new Error("malformed channel link");
+    return { sighost: ay[1]!, room: ay[2]!, s };
+  }
+  if (/^https?:\/\//.test(link) && link.includes("#ch=")) {
+    const frag = link.split("#ch=")[1] ?? "";
+    const at = frag.split("@");
+    const sighost = at[1] || CH_DEFAULT_SIGHOST;
+    const seg = at[0]!;
+    const i = seg.indexOf(":");
+    if (i < 0) return null;
+    const { s } = parseSecret(seg.slice(i + 1));
+    if (!HEX64.test(s)) throw new Error("malformed channel link");
+    return { sighost, room: seg.slice(0, i), s };
+  }
+  return null;
+}

package/ts/channels/op.ts

@@ -0,0 +1,89 @@
+// The immutable op — the single record type replicated through a channel.
+//
+// Every message, edit, delete, reaction, and presence beat is one Op, appended
+// to every replica's log and merged as a grow-only set (store.ts). Ops are
+// content-independent of transport: the same shape lands in the CLI's jsonl and
+// the browser's LocalStorage, and travels verbatim inside the E2E sealed frame.
+//
+// Identity: `id = "<author>@<hlc>"`. An author's HLCs are strictly monotonic and
+// never reused, so (author, hlc) is globally unique WITHOUT a content hash — a
+// retransmit of the same op yields the same id and dedups for free. (Phase 3
+// ed25519 `sig` will bind the body to this id so a peer can't forge a different
+// body under an author's id; until then, channel-secret possession = trust.)
+//
+// Dependency-free and isomorphic (Node + browser).
+
+export type OpKind = "msg" | "edit" | "delete" | "reaction" | "presence";
+export type Role = "agent" | "human";
+
+export interface Op {
+  /** `<author>@<hlc>` — globally unique dedupe key. */
+  id: string;
+  /** Stable per-participant id (registry `author`); the HLC node + identity. */
+  author: string;
+  /** Display name at send time. */
+  name: string;
+  role: Role;
+  /** Sortable Hybrid Logical Clock (hlc.ts). */
+  hlc: string;
+  kind: OpKind;
+  /** msg/edit: text. reaction: the emoji/label. presence: status. Absent for delete. */
+  body?: string;
+  /** edit/delete/reaction: the target op id being amended. */
+  ref?: string;
+  /** Phase 3: ed25519 signature over `id` (author authenticity). */
+  sig?: string;
+}
+
+const KINDS: ReadonlySet<string> = new Set(["msg", "edit", "delete", "reaction", "presence"]);
+const ROLES: ReadonlySet<string> = new Set(["agent", "human"]);
+
+/** Deterministic op id from author + hlc (no content hash needed — see file header). */
+export function opId(author: string, hlc: string): string {
+  return `${author}@${hlc}`;
+}
+
+/** Construct a well-formed op, filling `id` and dropping empty optional fields. */
+export function makeOp(fields: {
+  author: string;
+  name: string;
+  role: Role;
+  hlc: string;
+  kind: OpKind;
+  body?: string;
+  ref?: string;
+}): Op {
+  const op: Op = {
+    id: opId(fields.author, fields.hlc),
+    author: fields.author,
+    name: fields.name,
+    role: fields.role,
+    hlc: fields.hlc,
+    kind: fields.kind,
+  };
+  if (fields.body !== undefined) op.body = fields.body;
+  if (fields.ref) op.ref = fields.ref;
+  return op;
+}
+
+/**
+ * Validate an op arriving from an untrusted source (peer wire, disk, storage).
+ * Fail-closed: a malformed op is dropped, never coerced. Also enforces that `id`
+ * matches `author@hlc` so a peer can't smuggle a colliding id.
+ */
+export function isValidOp(x: unknown): x is Op {
+  if (!x || typeof x !== "object") return false;
+  const o = x as Record<string, unknown>;
+  if (typeof o.author !== "string" || !o.author) return false;
+  if (typeof o.name !== "string") return false;
+  if (typeof o.hlc !== "string" || !o.hlc) return false;
+  if (typeof o.kind !== "string" || !KINDS.has(o.kind)) return false;
+  if (typeof o.role !== "string" || !ROLES.has(o.role)) return false;
+  if (o.body !== undefined && typeof o.body !== "string") return false;
+  if (o.ref !== undefined && typeof o.ref !== "string") return false;
+  if (o.sig !== undefined && typeof o.sig !== "string") return false;
+  if (o.id !== opId(o.author, o.hlc)) return false;
+  // amendments must target something
+  if ((o.kind === "edit" || o.kind === "delete" || o.kind === "reaction") && !o.ref) return false;
+  return true;
+}