agent-yes 1.237.0 → 1.238.0

package/ts/serve.ts

@@ -184,7 +184,7 @@ async function loadOrCreateToken(tokenFlag?: string): Promise<string> {
 
 // Read the serve token WITHOUT creating one — `ay serve status` must be a pure
 // read (creating a token as a side effect of asking "is it running?" is wrong).
-async function loadTokenReadOnly(): Promise<string | null> {
+export async function loadTokenReadOnly(): Promise<string | null> {
   try {
     return (await readFile(tokenPath(), "utf-8")).trim();
   } catch {
@@ -241,7 +241,12 @@ function authorizeRequest(req: Request, expectedToken: string): AuthResult | nul
 // a cross-origin report page can reach the daemon — the token is still required to
 // get a 200, and no cookies are involved, so `*` leaks nothing.
 function isTermCorsPath(p: string): boolean {
-  return /^\/api\/(tail|size)\/.+$/.test(p) || p === "/api/send";
+  return (
+    /^\/api\/(tail|size)\/.+$/.test(p) ||
+    p === "/api/send" ||
+    /^\/api\/resize\/.+$/.test(p) ||
+    p.startsWith("/api/widget/")
+  );
 }
 
 function withTermCors(req: Request, res: Response | undefined): Response | undefined {
@@ -291,24 +296,34 @@ async function scopedGate(
   p: string,
 ): Promise<Response | null> {
   const forbid = (m: string) => new Response(m, { status: 403 });
+  const needs = (cap: string) => (scope.caps.includes(cap) ? null : forbid(`scoped token lacks '${cap}'`));
   const m = /^\/api\/(?:tail|size)\/(.+)$/.exec(p);
   if (method === "GET" && m) {
-    return (await scopedKeywordOk(decodeURIComponent(m[1]!), scope))
-      ? null
-      : forbid("scoped token: not bound to this agent");
+    return (
+      needs("tail") ??
+      ((await scopedKeywordOk(decodeURIComponent(m[1]!), scope))
+        ? null
+        : forbid("scoped token: not bound to this agent"))
+    );
   }
   if (method === "POST" && p === "/api/send") {
-    if (!scope.canSend) return forbid("scoped token is read-only");
-    return null; // pid binding enforced in the /api/send handler (it has the body)
+    return needs("send"); // pid binding enforced in the /api/send handler (it has the body)
   }
   // Interactive viewers may renegotiate the agent's PTY size (drag-to-resize) —
-  // send-capable scope only, bound pid. The keyword is in the path, so bind here.
+  // needs the resize cap, bound pid. The keyword is in the path, so bind here.
   const rz = /^\/api\/resize\/(.+)$/.exec(p);
   if (method === "POST" && rz) {
-    if (!scope.canSend) return forbid("scoped token is read-only");
-    return (await scopedKeywordOk(decodeURIComponent(rz[1]!), scope))
-      ? null
-      : forbid("scoped token: not bound to this agent");
+    return (
+      needs("resize") ??
+      ((await scopedKeywordOk(decodeURIComponent(rz[1]!), scope))
+        ? null
+        : forbid("scoped token: not bound to this agent"))
+    );
+  }
+  // Widget sensor routes: require the 'read' cap; the widget-route handlers do the
+  // fine-grained viewer-binding (and the 'screenshot' cap check for that kind).
+  if (p.startsWith("/api/widget/")) {
+    return needs("read");
   }
   return forbid("scoped token: route not permitted");
 }
@@ -318,20 +333,65 @@ async function scopedGate(
  * master token file, resolve the keyword to a concrete pid, and sign. Used by
  * `ay term mint`. Throws if there's no serve token or the agent can't be resolved.
  */
+const TERMINAL_CAPS = new Set(["tail", "size", "send", "resize"]);
+
 export async function mintScopedTermToken(
-  keyword: string,
-  opts: { ttlSec: number; canSend: boolean },
-): Promise<{ token: string; pid: string; exp: number; canSend: boolean }> {
+  target: string,
+  opts: { ttlSec: number; caps?: string[]; canSend?: boolean },
+): Promise<{ token: string; sub: string; pid: string; exp: number; caps: string[] }> {
   const master = await loadTokenReadOnly();
   if (!master)
     throw new Error(
       "no serve token at ~/.agent-yes/.serve-token — run `ay serve` once on this host to create it",
     );
-  const rec = await resolveOne(keyword, defaultOpts({ all: true }));
-  const pid = String(rec.pid);
+  const caps = opts.caps ?? (opts.canSend ? ["tail", "size", "send", "resize"] : ["tail", "size"]);
+  // A terminal-cap token binds to a concrete pid (resolve it); a widget-only token
+  // (read/screenshot) binds to the target verbatim (a viewer id, or "*" for any).
+  let sub = target;
+  if (target !== "*" && caps.some((c) => TERMINAL_CAPS.has(c))) {
+    const rec = await resolveOne(target, defaultOpts({ all: true }));
+    sub = String(rec.pid);
+  }
   const exp = Math.floor(Date.now() / 1000) + Math.max(1, Math.floor(opts.ttlSec));
-  const token = mintTermToken(master, { pid, canSend: opts.canSend, exp });
-  return { token, pid, exp, canSend: opts.canSend };
+  const token = mintTermToken(master, { pid: sub, caps, exp });
+  return { token, sub, pid: sub, exp, caps };
+}
+
+// ── Widget sensor broker (`ay widget`) ──────────────────────────────────────
+// The daemon is a STATELESS broker between the CLI (`ay widget read …`) and an
+// in-page AyWidget: it correlates a command with its result and forwards the
+// payload, but stores no page data. A widget registers on mount, holds an SSE
+// poll for commands, and POSTs results; a CLI read enqueues a command and awaits
+// the matching result. All in-memory — one daemon per process.
+interface WidgetViewer {
+  id: string;
+  url: string;
+  title: string;
+  caps: string[]; // what the page author opted into (selection/dom/screenshot)
+  lastSeen: number;
+}
+const widgetViewers = new Map<string, WidgetViewer>();
+const widgetPushers = new Map<string, (cmd: unknown) => void>(); // viewerId → active poll push
+const widgetWaiters = new Map<string, (r: { ok: boolean; data?: unknown; error?: string }) => void>();
+let widgetCmdSeq = 0;
+const WIDGET_TTL_MS = 30_000; // a viewer with no poll heartbeat this long is offline
+
+function widgetNewId(): string {
+  return "v_" + randomBytes(4).toString("hex");
+}
+function widgetLive(): WidgetViewer[] {
+  const now = Date.now();
+  for (const [id, v] of widgetViewers) if (now - v.lastSeen >= WIDGET_TTL_MS) widgetViewers.delete(id);
+  return [...widgetViewers.values()];
+}
+/** Resolve a `<viewer>` selector: exact id, then id-prefix / url / title substring. */
+function widgetResolve(sel: string): string | null {
+  if (widgetViewers.has(sel) && Date.now() - widgetViewers.get(sel)!.lastSeen < WIDGET_TTL_MS)
+    return sel;
+  const hit = widgetLive().find(
+    (v) => v.id.startsWith(sel) || v.url.includes(sel) || v.title.includes(sel),
+  );
+  return hit?.id ?? null;
 }
 
 const defaultOpts = (overrides: Partial<CommonOpts> = {}): CommonOpts => ({
@@ -2869,6 +2929,161 @@ export async function cmdServe(rest: string[]): Promise<number> {
       }
     }
 
+    // ── Widget sensor broker routes (`ay widget`) ───────────────────────────
+    // A scoped token binds to one viewer id (scope.pid); "*" means any. Enforce
+    // that binding on the per-viewer routes (scopedGate already required 'read').
+    const scopedSub = authResult.kind === "scoped" ? authResult.scope.pid : null;
+    const boundOk = (vid: string) => !scopedSub || scopedSub === "*" || scopedSub === vid;
+
+    // POST /api/widget/register {id?, url, title, caps} → { viewerId }
+    if (req.method === "POST" && p === "/api/widget/register") {
+      let b: { id?: string; url?: string; title?: string; caps?: string[] };
+      try {
+        b = (await req.json()) as typeof b;
+      } catch {
+        return new Response("invalid JSON body", { status: 400 });
+      }
+      // A scoped token pins the id to its subject (so a page can't register as
+      // another viewer); "*"/master lets the widget pick (its provided id or a new one).
+      const id =
+        scopedSub && scopedSub !== "*"
+          ? scopedSub
+          : typeof b.id === "string" && b.id
+            ? b.id
+            : widgetNewId();
+      widgetViewers.set(id, {
+        id,
+        url: String(b.url ?? ""),
+        title: String(b.title ?? ""),
+        caps: Array.isArray(b.caps) ? b.caps.filter((c) => typeof c === "string") : [],
+        lastSeen: Date.now(),
+      });
+      return Response.json({ viewerId: id });
+    }
+
+    // GET /api/widget/list → live viewers (id, url, title, caps, age)
+    if (req.method === "GET" && p === "/api/widget/list") {
+      const now = Date.now();
+      return Response.json(
+        widgetLive().map((v) => ({
+          id: v.id,
+          url: v.url,
+          title: v.title,
+          caps: v.caps,
+          age: Math.round((now - v.lastSeen) / 1000),
+        })),
+      );
+    }
+
+    // GET /api/widget/poll/:viewerId  (SSE) — the widget's command channel + heartbeat
+    const pollM = /^\/api\/widget\/poll\/(.+)$/.exec(p);
+    if (req.method === "GET" && pollM) {
+      const vid = decodeURIComponent(pollM[1]!);
+      if (!boundOk(vid)) return new Response("token not bound to this viewer", { status: 403 });
+      const enc = new TextEncoder();
+      let hb: ReturnType<typeof setInterval> | null = null;
+      const stream = new ReadableStream({
+        start(controller) {
+          const push = (obj: unknown) => {
+            try {
+              controller.enqueue(enc.encode(`data: ${JSON.stringify(obj)}\n\n`));
+            } catch {
+              /* stream closed */
+            }
+          };
+          widgetPushers.set(vid, push);
+          const touch = () => {
+            const v = widgetViewers.get(vid);
+            if (v) v.lastSeen = Date.now();
+          };
+          touch();
+          hb = setInterval(() => {
+            try {
+              controller.enqueue(enc.encode(": ping\n\n"));
+              touch();
+            } catch {
+              /* closed */
+            }
+          }, 15_000);
+          const cleanup = () => {
+            if (hb) clearInterval(hb);
+            if (widgetPushers.get(vid) === push) widgetPushers.delete(vid);
+          };
+          req.signal.addEventListener("abort", cleanup);
+        },
+        cancel() {
+          if (hb) clearInterval(hb);
+        },
+      });
+      return new Response(stream, {
+        headers: {
+          "Content-Type": "text/event-stream",
+          "Cache-Control": "no-cache",
+          Connection: "keep-alive",
+        },
+      });
+    }
+
+    // POST /api/widget/result {cmdId, ok, data?, error?} — widget → CLI result
+    if (req.method === "POST" && p === "/api/widget/result") {
+      let b: { cmdId?: string; ok?: boolean; data?: unknown; error?: string };
+      try {
+        b = (await req.json()) as typeof b;
+      } catch {
+        return new Response("invalid JSON body", { status: 400 });
+      }
+      const resolve = b.cmdId ? widgetWaiters.get(b.cmdId) : undefined;
+      if (resolve) {
+        widgetWaiters.delete(b.cmdId!);
+        resolve({ ok: b.ok === true, data: b.data, error: b.error });
+      }
+      return Response.json({ ok: true });
+    }
+
+    // POST /api/widget/read {viewer, kind, args?} — CLI issues a read to a viewer
+    if (req.method === "POST" && p === "/api/widget/read") {
+      let b: { viewer?: string; kind?: string; args?: unknown };
+      try {
+        b = (await req.json()) as typeof b;
+      } catch {
+        return new Response("invalid JSON body", { status: 400 });
+      }
+      if (!b.viewer || !b.kind) return new Response("missing viewer/kind", { status: 400 });
+      // A scoped token needs the 'screenshot' cap for that kind (scopedGate already
+      // required 'read'); the master token is unrestricted.
+      if (
+        authResult.kind === "scoped" &&
+        b.kind === "screenshot" &&
+        !authResult.scope.caps.includes("screenshot")
+      )
+        return new Response("scoped token lacks 'screenshot'", { status: 403 });
+      const vid = widgetResolve(b.viewer);
+      if (!vid) return new Response(`no online viewer matching "${b.viewer}"`, { status: 404 });
+      if (!boundOk(vid)) return new Response("token not bound to this viewer", { status: 403 });
+      const push = widgetPushers.get(vid);
+      if (!push) return new Response("viewer offline", { status: 409 });
+      const cmdId = `c${++widgetCmdSeq}_${Date.now()}`;
+      const result = await new Promise<{ ok: boolean; data?: unknown; error?: string }>((resolve) => {
+        const timer = setTimeout(() => {
+          widgetWaiters.delete(cmdId);
+          resolve({ ok: false, error: "timeout" });
+        }, 10_000);
+        widgetWaiters.set(cmdId, (r) => {
+          clearTimeout(timer);
+          resolve(r);
+        });
+        push({ cmdId, kind: b.kind, args: b.args ?? {} });
+      });
+      const v = widgetViewers.get(vid);
+      return Response.json({
+        viewer: vid,
+        url: v?.url ?? "",
+        ts: Math.floor(Date.now() / 1000),
+        kind: b.kind,
+        ...(result.ok ? { data: result.data } : { error: result.error ?? "failed" }),
+      });
+    }
+
     // GET /api/tail/:keyword  — SSE streaming
     const tailM = /^\/api\/tail\/(.+)$/.exec(p);
     if (req.method === "GET" && tailM) {

package/ts/subcommands.ts

@@ -366,6 +366,8 @@ const SUBCOMMANDS = new Set([
   "ch",
   "channels",
   "term",
+  "widget",
+  "mint",
   "serve",
   "schedule",
   "remote",
@@ -491,6 +493,14 @@ export async function runSubcommand(argv: string[]): Promise<number | null> {
         const { cmdTerm } = await import("./terminal.ts");
         return cmdTerm(rest);
       }
+      case "widget": {
+        const { cmdWidget } = await import("./widget.ts");
+        return cmdWidget(rest);
+      }
+      case "mint": {
+        const { cmdMint } = await import("./widget.ts");
+        return cmdMint(rest);
+      }
       case "serve": {
         const { cmdServe } = await import("./serve.ts");
         return cmdServe(rest);
@@ -628,6 +638,8 @@ export async function cmdHelp(managerCommands = true): Promise<number> {
       `  ay msgs [keyword] [--in|--out]      inter-agent message log (sent + received)\n` +
       `  ay ch mk|join|send|read|tail <topic>  local-first E2E channels: AI ↔ humans on a topic (ay ch help)\n` +
       `  ay term embed <pid>                 <script> to embed a live read-only agent terminal in a page (ay term help)\n` +
+      `  ay widget ls | read selection|dom   read an opted-in page widget's context (selection/DOM) (ay widget help)\n` +
+      `  ay mint <target> --caps ...         mint a scoped, short-TTL capability token (embeddable in a page)\n` +
       `  ay key <keyword> <key...>           send raw keystrokes (down/up/enter/esc/…) — drives menus\n` +
       `  ay select <keyword> <N>             pick option N of a needs_input selection menu\n` +
       `  ay attach <keyword>                 interactive attach (detach: Ctrl-\\)\n` +

package/ts/termToken.spec.ts

@@ -9,12 +9,34 @@ describe("termToken", () => {
     const tok = mintTermToken(MASTER, { pid: "4242", canSend: false, exp: now + 900 });
     expect(isTermToken(tok)).toBe(true);
     const scope = verifyTermToken(MASTER, tok, now);
-    expect(scope).toEqual({ pid: "4242", canSend: false, exp: now + 900 });
+    expect(scope).toEqual({ pid: "4242", canSend: false, caps: ["tail", "size"], exp: now + 900 });
   });
 
-  it("round-trips an interactive token (canSend true)", () => {
+  it("round-trips an interactive token (canSend true → send/resize caps)", () => {
     const tok = mintTermToken(MASTER, { pid: "7", canSend: true, exp: now + 60 });
-    expect(verifyTermToken(MASTER, tok, now)?.canSend).toBe(true);
+    const scope = verifyTermToken(MASTER, tok, now);
+    expect(scope?.canSend).toBe(true);
+    expect(scope?.caps).toEqual(["tail", "size", "send", "resize"]);
+  });
+
+  it("carries an explicit caps array (widget read/screenshot)", () => {
+    const tok = mintTermToken(MASTER, { pid: "v_ab12", caps: ["read", "screenshot"], exp: now + 60 });
+    const scope = verifyTermToken(MASTER, tok, now);
+    expect(scope?.caps).toEqual(["read", "screenshot"]);
+    expect(scope?.canSend).toBe(false); // no "send" cap
+    expect(scope?.pid).toBe("v_ab12");
+  });
+
+  it("verifies a legacy {p,w,x} token (pre-caps format) into derived caps", () => {
+    // hand-build a legacy payload to prove backward-compat with live phase-2 tokens
+    const legacy = Buffer.from(JSON.stringify({ p: "9", w: 1, x: now + 60 })).toString("base64url");
+    const body = `ayt1.${legacy}`;
+    const { createHmac, createHash } = require("crypto");
+    const key = createHash("sha256").update("ay/term/token/v1\n" + MASTER).digest();
+    const sig = createHmac("sha256", key).update(body).digest().toString("base64url");
+    const scope = verifyTermToken(MASTER, `${body}.${sig}`, now);
+    expect(scope?.pid).toBe("9");
+    expect(scope?.caps).toEqual(["tail", "size", "send", "resize"]);
   });
 
   it("rejects a token signed with a different master (forgery)", () => {

package/ts/termToken.ts

@@ -17,17 +17,29 @@
 // delivers short-TTL + read-only + single-session, which is what embeds need.)
 import { createHash, createHmac, timingSafeEqual } from "crypto";
 
+/** Capability vocabulary a scoped token can carry (see scopedGate in serve.ts). */
+export type Cap = "tail" | "size" | "send" | "resize" | "read" | "screenshot";
+
 export interface TermScope {
-  /** The agent pid this token is bound to (resolved to a concrete pid at mint time). */
+  /** Subject the token is bound to: an agent pid (terminal) or a viewer id (widget). */
   pid: string;
-  /** Interactive: may also write to this pid's stdin (/api/send). Read-only when false. */
+  /** Convenience mirror of caps.includes("send") — interactive terminal write. */
   canSend: boolean;
+  /** Full capability list this token grants for its subject. */
+  caps: string[];
   /** Expiry, epoch seconds. */
   exp: number;
 }
 
 const PREFIX = "ayt1";
 
+const CAPS_READONLY: Cap[] = ["tail", "size"];
+const CAPS_INTERACTIVE: Cap[] = ["tail", "size", "send", "resize"];
+/** Derive caps for a legacy `{w}` token (pre-caps format): w=1 ⇒ interactive. */
+function legacyCaps(w: unknown): string[] {
+  return w === 1 ? [...CAPS_INTERACTIVE] : [...CAPS_READONLY];
+}
+
 /** Dedicated HMAC key derived from the master token (so the token isn't signed with the raw master). */
 function keyFor(masterToken: string): Buffer {
   return createHash("sha256")
@@ -40,10 +52,19 @@ export function isTermToken(tok: unknown): tok is string {
   return typeof tok === "string" && tok.startsWith(PREFIX + ".");
 }
 
-/** Mint a scoped token bound to `scope.pid`, signed with the master token. */
-export function mintTermToken(masterToken: string, scope: TermScope): string {
+/**
+ * Mint a scoped token bound to `scope.pid` (the subject), signed with the master
+ * token. `caps` is authoritative; if omitted it derives from `canSend` (terminal
+ * back-compat). Emits the caps-format payload `{s, c, x}` (verified alongside the
+ * legacy `{p, w, x}`).
+ */
+export function mintTermToken(
+  masterToken: string,
+  scope: { pid: string; exp: number; caps?: string[]; canSend?: boolean },
+): string {
+  const caps = scope.caps ?? (scope.canSend ? [...CAPS_INTERACTIVE] : [...CAPS_READONLY]);
   const payload = Buffer.from(
-    JSON.stringify({ p: scope.pid, w: scope.canSend ? 1 : 0, x: Math.floor(scope.exp) }),
+    JSON.stringify({ s: scope.pid, c: caps, x: Math.floor(scope.exp) }),
   ).toString("base64url");
   const body = `${PREFIX}.${payload}`;
   const sig = createHmac("sha256", keyFor(masterToken)).update(body).digest().toString("base64url");
@@ -73,13 +94,19 @@ export function verifyTermToken(
   }
   // constant-time compare; length check first (timingSafeEqual throws on mismatch)
   if (got.length !== expected.length || !timingSafeEqual(got, expected)) return null;
-  let obj: { p?: unknown; w?: unknown; x?: unknown };
+  let obj: { s?: unknown; p?: unknown; w?: unknown; c?: unknown; x?: unknown };
   try {
     obj = JSON.parse(Buffer.from(parts[1]!, "base64url").toString("utf-8"));
   } catch {
     return null;
   }
-  if (typeof obj.p !== "string" || !obj.p) return null;
+  // subject: new tokens use `s`, legacy tokens use `p`
+  const sub = typeof obj.s === "string" && obj.s ? obj.s : obj.p;
+  if (typeof sub !== "string" || !sub) return null;
   if (typeof obj.x !== "number" || !Number.isFinite(obj.x) || obj.x <= nowSec) return null; // expired
-  return { pid: obj.p, canSend: obj.w === 1, exp: obj.x };
+  // caps: new tokens carry `c`; legacy tokens derive from `w`
+  const caps = Array.isArray(obj.c)
+    ? (obj.c.filter((x) => typeof x === "string") as string[])
+    : legacyCaps(obj.w);
+  return { pid: sub, canSend: caps.includes("send"), caps, exp: obj.x };
 }

package/ts/widget.ts

@@ -0,0 +1,207 @@
+// `ay widget` — read what a viewer is looking at, through an opted-in page widget.
+//
+// Agent-side CLI over the daemon's widget broker (serve.ts /api/widget/*). The
+// page embeds `new AyWidget({sensors:[…]})` (widget/browser.ts); this reads it:
+//   ay widget ls                         # online viewers
+//   ay widget read selection <viewer>    # what the viewer has selected
+//   ay widget read dom <viewer> --selector <css>
+// Complements rechrome (rech drives any page; this reads an author-opted-in page,
+// cross-origin / WebRTC-remote, no extension). Verb `read` matches `ay read`/`tail`.
+
+type FlagSpec = Record<string, "bool" | "value">;
+
+function parseFlags(
+  args: string[],
+  known: FlagSpec,
+): { flags: Record<string, string | boolean>; positional: string[] } {
+  const flags: Record<string, string | boolean> = {};
+  const positional: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (!a.startsWith("-") || a === "-") {
+      positional.push(a);
+      continue;
+    }
+    const eq = a.indexOf("=");
+    const name = eq === -1 ? a.replace(/^--?/, "") : a.slice(a.startsWith("--") ? 2 : 1, eq);
+    const kind = known[name];
+    if (!kind) throw new Error(`unknown flag ${a}`);
+    if (kind === "bool") {
+      if (eq !== -1) throw new Error(`--${name} takes no value`);
+      flags[name] = true;
+    } else {
+      const v = eq !== -1 ? a.slice(eq + 1) : args[++i];
+      if (v === undefined) throw new Error(`${a} requires a value`);
+      flags[name] = v;
+    }
+  }
+  return { flags, positional };
+}
+
+/** Resolve the local daemon base URL + token (flags override discovery). */
+async function daemonTarget(
+  flags: Record<string, string | boolean>,
+): Promise<{ base: string; token: string }> {
+  const { resolveLocalServeUrl, loadTokenReadOnly } = await import("./serve.ts");
+  const base = typeof flags.base === "string" ? flags.base : await resolveLocalServeUrl();
+  if (!base)
+    throw new Error(
+      "no running ay serve daemon found — start `ay serve` or pass --base <url> (e.g. http://127.0.0.1:PORT)",
+    );
+  const token = typeof flags.token === "string" ? flags.token : ((await loadTokenReadOnly()) ?? "");
+  if (!token) throw new Error("no serve token — pass --token or run `ay serve` once");
+  return { base: base.replace(/\/+$/, ""), token };
+}
+
+function withTok(url: string, token: string): string {
+  return `${url}${url.includes("?") ? "&" : "?"}token=${encodeURIComponent(token)}`;
+}
+
+async function cmdWidgetLs(args: string[]): Promise<number> {
+  const { flags } = parseFlags(args, { json: "bool", base: "value", token: "value" });
+  const { base, token } = await daemonTarget(flags);
+  const res = await fetch(withTok(`${base}/api/widget/list`, token), {
+    headers: { accept: "application/json" },
+  });
+  if (!res.ok) throw new Error(`widget list failed: ${res.status} ${await res.text()}`);
+  const list = (await res.json()) as Array<{
+    id: string;
+    url: string;
+    title: string;
+    caps: string[];
+    age: number;
+  }>;
+  if (flags.json) {
+    process.stdout.write(JSON.stringify(list, null, 2) + "\n");
+    return 0;
+  }
+  if (!list.length) {
+    process.stderr.write("no online widgets (a page must embed AyWidget and start() it)\n");
+    return 0;
+  }
+  for (const v of list) {
+    process.stdout.write(
+      `${v.id.padEnd(12)}  ${(v.title || "(untitled)").slice(0, 28).padEnd(28)}  ` +
+        `caps:${v.caps.join(",") || "-"}  ${v.age}s  ${v.url}\n`,
+    );
+  }
+  return 0;
+}
+
+async function cmdWidgetRead(args: string[]): Promise<number> {
+  const { flags, positional } = parseFlags(args, {
+    selector: "value",
+    all: "bool",
+    text: "bool",
+    html: "bool",
+    json: "bool",
+    base: "value",
+    token: "value",
+  });
+  const kind = positional[0];
+  const viewer = positional[1];
+  if (!kind || !viewer)
+    throw new Error("usage: ay widget read <selection|dom> <viewer> [--selector <css>] [--all] [--text|--html]");
+  const cmdArgs: Record<string, unknown> = {};
+  if (kind === "dom") {
+    if (typeof flags.selector !== "string") throw new Error("dom read needs --selector <css>");
+    cmdArgs.selector = flags.selector;
+    cmdArgs.all = flags.all === true;
+  }
+  const { base, token } = await daemonTarget(flags);
+  const res = await fetch(withTok(`${base}/api/widget/read`, token), {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ viewer, kind, args: cmdArgs }),
+  });
+  const body = (await res.json().catch(() => ({}))) as any;
+  if (!res.ok) throw new Error(`widget read failed: ${res.status} ${JSON.stringify(body)}`);
+  if (body.error) {
+    process.stderr.write(`read ${kind} @ ${body.viewer ?? viewer}: ${body.error}\n`);
+    return 1;
+  }
+  // Plain-text shortcut for selection unless --json/--html asked for the envelope.
+  if (kind === "selection" && !flags.json) {
+    process.stdout.write((flags.html ? body.data?.html : body.data?.text) ?? "");
+    process.stdout.write("\n");
+    return 0;
+  }
+  process.stdout.write(JSON.stringify(flags.json ? body : body.data, null, 2) + "\n");
+  return 0;
+}
+
+function widgetHelp(): number {
+  process.stdout.write(
+    `ay widget — read an opted-in page widget's context (selection / DOM)\n\n` +
+      `Usage:\n` +
+      `  ay widget ls [--json]\n` +
+      `  ay widget read selection <viewer> [--text|--html|--json]\n` +
+      `  ay widget read dom <viewer> --selector <css> [--all] [--json]\n\n` +
+      `  <viewer> = an id, or a url/title substring (see \`ay widget ls\`).\n` +
+      `  Common flags: --base <daemon-url>  --token <tok>  (default: the local daemon).\n` +
+      `  The page must embed \`new AyWidget({sensors:[...]}).start()\` and the token must\n` +
+      `  carry the 'read' cap (ay mint <viewer> --caps read) — or use the master token.\n`,
+  );
+  return 0;
+}
+
+export async function cmdWidget(args: string[]): Promise<number> {
+  const sub = args[0];
+  const rest = args.slice(1);
+  switch (sub) {
+    case "ls":
+    case "list":
+      return cmdWidgetLs(rest);
+    case "read":
+      return cmdWidgetRead(rest);
+    case undefined:
+    case "help":
+    case "--help":
+    case "-h":
+      return widgetHelp();
+    default:
+      process.stderr.write(`ay widget: unknown subcommand "${sub}"\n\n`);
+      widgetHelp();
+      return 1;
+  }
+}
+
+// ── `ay mint` — the general scoped-token minter (ay term mint is an alias) ────
+function parseTtlSec(s: string): number {
+  const m = /^(\d+)(s|m|h)?$/.exec(s.trim());
+  if (!m) throw new Error(`bad --ttl "${s}" (use e.g. 900, 30s, 15m, 2h)`);
+  const mult = m[2] === "h" ? 3600 : m[2] === "m" ? 60 : 1;
+  return Number(m[1]) * mult;
+}
+
+const KNOWN_CAPS = new Set(["tail", "size", "send", "resize", "read", "screenshot"]);
+
+export async function cmdMint(args: string[]): Promise<number> {
+  const { flags, positional } = parseFlags(args, {
+    caps: "value",
+    ttl: "value",
+    json: "bool",
+  });
+  const target = positional[0];
+  if (!target || positional.length > 1)
+    throw new Error("usage: ay mint <pid|viewer|url|*> --caps tail,send,read,screenshot [--ttl 15m] [--json]");
+  if (typeof flags.caps !== "string")
+    throw new Error("--caps is required, e.g. --caps read  or  --caps tail,send");
+  const caps = flags.caps.split(",").map((c) => c.trim()).filter(Boolean);
+  const bad = caps.filter((c) => !KNOWN_CAPS.has(c));
+  if (bad.length) throw new Error(`unknown cap(s): ${bad.join(", ")} (valid: ${[...KNOWN_CAPS].join(", ")})`);
+  const ttlSec = parseTtlSec(typeof flags.ttl === "string" ? flags.ttl : "15m");
+  const { mintScopedTermToken } = await import("./serve.ts");
+  const r = await mintScopedTermToken(target, { ttlSec, caps });
+  if (flags.json === true) {
+    process.stdout.write(JSON.stringify(r) + "\n");
+    return 0;
+  }
+  process.stdout.write(r.token + "\n");
+  process.stderr.write(
+    `\n  Scoped token for ${r.sub === "*" ? "ANY subject" : r.sub}, caps [${r.caps.join(", ")}], ` +
+      `expires ${new Date(r.exp * 1000).toISOString()}.\n` +
+      `  It grants ONLY those caps for that subject — safe to embed in a page (not the master token).\n`,
+  );
+  return 0;
+}

package/ts/widgets.ts

@@ -12,3 +12,5 @@ export { AyTerminal } from "./terminal/browser.ts";
 export type { AyTerminalInfo } from "./terminal/browser.ts";
 export { AyChannel } from "./channels/browser.ts";
 export type { AyChannelInfo } from "./channels/browser.ts";
+export { AyWidget } from "./widget/browser.ts";
+export type { AyWidgetInfo } from "./widget/browser.ts";