your-attention 0.1.0 → 0.1.1

package/dist/src/cloudflare/worker.js

@@ -0,0 +1,189 @@
+// The Cloudflare build. MODE "single" serves one inbox, for a person who
+// deploys their own. MODE "hosted" serves many: each inbox is created with an
+// invite code, lives at an unguessable /i/<id>/ address, and is one Durable
+// Object that hibernates when nobody uses it.
+import { PIN_ITERATIONS, pinKeyError } from '../core/pin.js';
+import { inviteId } from '../core/telemetry.js';
+import { InboxObject, RegistryObject } from './inbox-object.js';
+
+                      
+                                
+                                   
+                  
+                  
+                                                                                                           
+                       
+                
+                                                                                     
+                       
+                                                               
+                              
+                                                       
+                               
+                             
+                                                 
+                                    
+                                                                                                               
+                           
+                                                                    
+                      
+                                                                                               
+                           
+                                                                        
+                                     
+ 
+
+/** Invite codes shorter than this are refused before any lookup, so guessing one takes too long to try. */
+const MIN_INVITE_LENGTH = 20;
+
+const json = (data         , status = 200)           => Response.json(data, { status, headers: { 'cache-control': 'no-store' } });
+
+function hex(bytes        )         {
+  return [...crypto.getRandomValues(new Uint8Array(bytes))].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+const tooMany = ()           => json({ error: 'too many requests, try again in a minute' }, 429);
+
+/** The routes a hosted inbox never serves: it sends events over the WebSocket only. The Worker answers them itself, so a client that retries one does not wake the inbox object. */
+const SOCKET_ONLY = new Set(['/v1/events', '/v1/stream', '/v1/poll']);
+
+/** When each client that keeps asking for a stream was last named in the log, so a retry loop costs one line a minute. */
+const refusedAt = new Map                ();
+
+/** Refuse a stream route, and name the client behind it once a minute: a client that ignores the refusal is the only way it is found. */
+function refuseStream(req         , url     , id        )           {
+  const agent = url.searchParams.get('agent') ?? '';
+  const instance = url.searchParams.get('instance') ?? '';
+  const key = `${id}:${url.pathname}:${agent}:${instance}`;
+  const now = Date.now();
+  const last = refusedAt.get(key);
+  if (last === undefined || now - last >= 60_000) {
+    if (refusedAt.size >= 1000) refusedAt.clear();
+    refusedAt.set(key, now);
+    console.log(JSON.stringify({ event: 'stream_refused', inbox: id.slice(0, 8), path: url.pathname, agent, instance, ip: clientAddress(req) }));
+  }
+  return json({ error: 'this inbox serves events over the WebSocket at /v1/ws only' }, 410);
+}
+
+/** Whether a request carries a token. The inbox checks the token; the Worker only picks the limiter. */
+const signedIn = (req         )          => /^Bearer /.test(req.headers.get('authorization') ?? '') || /(^|;\s*)ya_token=/.test(req.headers.get('cookie') ?? '');
+const clientAddress = (req         )         => req.headers.get('cf-connecting-ip') ?? 'unknown';
+
+/** Count a request before it costs anything else. Signed-in calls count per inbox and address, so a stranger cannot use up the owner's budget. */
+async function allowed(env     , req         , inbox        )                   {
+  const anon = !signedIn(req);
+  const limiter = anon ? env.ANON_LIMITER : env.LIMITER;
+  return !limiter || (await limiter.limit({ key: anon ? `anon:${clientAddress(req)}` : `${inbox}:${clientAddress(req)}` })).success;
+}
+
+/** Send a request to the inbox object, with the path the inbox expects. `prefix` is the inbox's own address, which its sign-in cookie is scoped to. */
+async function toInbox(env     , name        , req         , path        , search        , prefix = '/')                    {
+  const stub = env.INBOX.get(env.INBOX.idFromName(name));
+  const res = await stub.fetch(new Request(`https://inbox${path}${search}`, req));
+  const set = res.headers.get('set-cookie');
+  if (prefix === '/' || !set) return res;
+  const scoped = new Response(res.body, res);
+  scoped.headers.set('set-cookie', set.replace(/;\s*Path=\/(?=;|$)/i, `; Path=${prefix}`));
+  return scoped;
+}
+
+/** Hosted inbox addresses are 20 random hex digits and 12 digits of an HMAC over them. */
+async function addressTag(secret        , random        )                  {
+  const key = await crypto.subtle.importKey('raw', new TextEncoder().encode(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+  const mac = new Uint8Array(await crypto.subtle.sign('HMAC', key, new TextEncoder().encode(random)));
+  return [...mac.slice(0, 6)].map((b) => b.toString(16).padStart(2, '0')).join('');
+}
+
+export async function newAddress(secret        )                  {
+  const random = hex(10);
+  return random + (await addressTag(secret, random));
+}
+
+export async function validAddress(secret        , id        )                   {
+  if (!/^[0-9a-f]{32}$/.test(id)) return false;
+  const want = await addressTag(secret, id.slice(0, 20));
+  let diff = 0;
+  for (let i = 0; i < 12; i++) diff |= want.charCodeAt(i) ^ id.charCodeAt(20 + i);
+  return diff === 0;
+}
+
+/** The owner token this isolate has given its inbox, so single mode sends it once per isolate instead of once per request. */
+let adoptedOwner                    ;
+
+/** Serve the built-in page and its files. Assets serve index.html at "/", and answer "/index.html" with a redirect to "/". */
+function asset(env     , req         , path        )                    {
+  const url = new URL(req.url);
+  return env.ASSETS.fetch(new Request(new URL(path, url.origin), req));
+}
+
+const LANDING = `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Your Attention</title><style>body{font:16px system-ui,sans-serif;max-width:560px;margin:64px auto;padding:0 16px;background:#f6f6f4;color:#1d1d1b}
+@media (prefers-color-scheme: dark){body{background:#141413;color:#ececea}}input,button{font:inherit;padding:8px 12px}</style></head>
+<body><h1>Your Attention</h1><p>One inbox for the questions your coding agents ask you. Create an inbox with an invite code. This browser stays signed in to it. Bookmark the address it opens: in another browser, the address shows how to sign in, and it does not sign anyone in by itself.</p>
+<form id="f"><input id="code" placeholder="Invite code" autocomplete="off" required> <button>Create my inbox</button>
+<p><label>PIN <input id="pin" type="password" inputmode="numeric" pattern="[0-9]{4}" maxlength="4" autocomplete="new-password" placeholder="4 digits" size="6"></label> <label>Again <input id="pin2" type="password" inputmode="numeric" pattern="[0-9]{4}" maxlength="4" autocomplete="new-password" placeholder="4 digits" size="6"></label></p>
+<p>The inbox page asks for the PIN in each new tab, so someone who gets the address or a sign-in link still cannot answer your agents' cards. Leave it empty to skip, and the page asks again when it opens. <label><input type="checkbox" id="never"> Never ask me for a PIN</label></p>
+<p>Usage counts: a hosted inbox always sends the operator of this service, once a day, how many cards were posted and answered, pairing requests, page opens, and how many agents, agent processes and tokens connected, with an id made from your invite code. There is no off switch. It never sends card text, answers, agent names or addresses. To keep even these counts to yourself, run the inbox on your laptop. <a href="https://github.com/elecnix/your-attention#usage-counts">What the counts contain</a>.</p></form><p id="out"></p>
+<script type="module">import{newPinKey}from'./pin-key.js';document.getElementById('f').onsubmit=async(e)=>{e.preventDefault();const v=(id)=>document.getElementById(id).value,out=document.getElementById('out');
+if(v('pin')!==v('pin2')){out.textContent='The two PINs differ.';return}if(v('pin')&&!/^[0-9]{4}$/.test(v('pin'))){out.textContent='A PIN is 4 digits.';return}
+const pin=v('pin')?{pin:await newPinKey(v('pin'),${PIN_ITERATIONS})}:{neverAsk:document.getElementById('never').checked};
+const r=await fetch('new',{method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({invite:v('code'),...pin})});const d=await r.json();
+if(d.unlock){try{sessionStorage.setItem('ya-unlock:'+new URL(d.url).pathname,d.unlock)}catch{}}if(d.login){location.href=d.login}else{out.textContent=d.error}}</script></body></html>`;
+
+export default {
+  async fetch(req         , env     )                    {
+    const url = new URL(req.url);
+    if (env.MODE !== 'hosted') {
+      if (url.pathname.startsWith('/v1/')) {
+        if (!(await allowed(env, req, 'main'))) return tooMany();
+        if (env.OWNER_TOKEN && adoptedOwner !== env.OWNER_TOKEN) {
+          const init = await env.INBOX.get(env.INBOX.idFromName('main')).fetch('https://inbox/_init', { method: 'POST', body: JSON.stringify({ ownerToken: env.OWNER_TOKEN }) });
+          if (!init.ok) return json(await init.json().catch(() => ({ error: 'the inbox did not start' })), init.status);
+          adoptedOwner = env.OWNER_TOKEN;
+        }
+        return toInbox(env, 'main', req, url.pathname, url.search);
+      }
+      return asset(env, req, url.pathname);
+    }
+
+    if (url.pathname === '/') return new Response(LANDING, { headers: { 'content-type': 'text/html; charset=utf-8' } });
+    // The landing page derives the PIN's key with the module the inbox page uses, so the PIN never leaves the browser.
+    if (url.pathname === '/pin-key.js') return asset(env, req, url.pathname);
+    const secret = env.INBOX_ID_SECRET;
+    if (!secret) return json({ error: 'hosted mode needs the INBOX_ID_SECRET secret' }, 500);
+    if (url.pathname === '/new' && req.method === 'POST') {
+      if (!(await allowed(env, req, ''))) return tooMany();
+      if (Number(req.headers.get('content-length') ?? 0) > 1024) return json({ error: 'body too large' }, 413);
+      const { invite, pin, neverAsk } = (await req.json().catch(() => ({})))                                                          ;
+      const pinError = pin === undefined ? undefined : pinKeyError(pin);
+      if (pinError) return json({ error: `pin: ${pinError}` }, 400);
+      const code = String(invite ?? '').trim().slice(0, 200);
+      const redeemed = code.length >= MIN_INVITE_LENGTH ? (await (await env.REGISTRY.get(env.REGISTRY.idFromName('invites')).fetch('https://registry/redeem', { method: 'POST', body: JSON.stringify({ code }) })).json())                    : { ok: false };
+      if (!redeemed.ok) return json({ error: 'That invite code is not valid.' }, 403);
+      const id = await newAddress(secret);
+      await env.INVITES.put(`inbox:${id}`, String(Date.now()));
+      const init = { usage: { invite: await inviteId(code) }, pin, neverAsk: neverAsk === true };
+      const res = await env.INBOX.get(env.INBOX.idFromName(id)).fetch('https://inbox/_init', { method: 'POST', body: JSON.stringify(init) });
+      const { owner, unlock } = (await res.json())                                      ;
+      const base = `${url.origin}/i/${id}/`;
+      // The landing page keeps `unlock` in the tab's session storage, so the inbox opens unlocked in that tab only.
+      return json({ url: base, login: `${base}#token=${owner}`, ...(unlock ? { unlock } : {}) }, 201);
+    }
+    const m = /^\/i\/([0-9a-f]{32})(\/.*)?$/.exec(url.pathname);
+    if (!m) return json({ error: 'not found' }, 404);
+    const id = m[1] ?? '';
+    // The page finds the API next to its own address, so the address must end with a slash.
+    if (m[2] === undefined) return Response.redirect(`${url.origin}/i/${id}/${url.search}`, 301);
+    const rest = m[2];
+    // Only the Worker can sign an address, so a guessed one reaches no Durable Object and no KV read.
+    if (!(await validAddress(secret, id))) return json({ error: 'no inbox at this address' }, 404);
+    if (rest.startsWith('/v1/')) {
+      if (!(await allowed(env, req, id))) return tooMany();
+      if (req.method === 'GET' && SOCKET_ONLY.has(rest)) return refuseStream(req, url, id);
+      return toInbox(env, id, req, rest, url.search, `/i/${id}/`);
+    }
+    return asset(env, req, rest);
+  },
+};
+
+export { InboxObject, RegistryObject };

package/dist/src/core/crypto.js

@@ -0,0 +1,23 @@
+// Ids, secrets and hashes, with Web Crypto only.
+
+const hex = (bytes            )         => [...bytes].map((b) => b.toString(16).padStart(2, '0')).join('');
+
+export function randomId(bytes = 8)         {
+  return hex(crypto.getRandomValues(new Uint8Array(bytes)));
+}
+
+/** A six-digit code the person compares on both screens when pairing. */
+export function pairingCode()         {
+  const n = crypto.getRandomValues(new Uint32Array(1))[0] ?? 0;
+  return String(n % 1_000_000).padStart(6, '0');
+}
+
+export async function sha256(text        )                  {
+  const digest = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+  return hex(new Uint8Array(digest));
+}
+
+/** A token secret: the token id, a dot, and 32 random bytes. */
+export function newSecret(id        )         {
+  return `${id}.${randomId(32)}`;
+}

package/dist/src/core/diagrams.js

@@ -0,0 +1,225 @@
+// Mermaid diagrams on a card: a ```mermaid block in its text or recommendation, or a
+// Mermaid("...") statement in its body. The inbox checks each one with the platform's
+// checker before it takes the card, so the person never sees a diagram the page cannot draw.
+import { InboxError } from './inbox.js';
+
+/** Resolves to mermaid's error for a diagram it cannot draw, or to undefined when it can. */
+                               
+                                                
+                                                                               
+                  
+ 
+
+                          
+                                                                
+                
+                 
+ 
+
+/** The errors of the diagrams a card shows, by source. */
+                                                              
+
+export const MAX_DIAGRAMS = 20;
+/** A fence line that opens a Mermaid block. web/markdown.js draws the same blocks. */
+export const MERMAID_FENCE = /^```\s*mermaid(\s|$)/i;
+
+function markdownDiagrams(field        , src                    )            {
+  if (!src) return [];
+  // The page's Markdown reader opens a fence at any line that starts with ``` and closes it at the next one.
+  const lines = String(src).replace(/\r\n/g, '\n').split('\n');
+  const found            = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (!/^```/.test(lines[i] )) continue;
+    const start = i;
+    const code           = [];
+    for (i++; i < lines.length && !/^```/.test(lines[i] ); i++) code.push(lines[i] );
+    if (MERMAID_FENCE.test(lines[start] )) found.push({ where: `${field}, the diagram on line ${start + 1}`, source: code.join('\n') });
+  }
+  return found;
+}
+
+// The page draws a body with OpenUI, so the inbox reads the body as @openuidev/browser-bundle 0.2.1 does:
+// it takes the code out of ``` fences when the body has them, drops // and # comments, then reads tokens.
+// Each function below follows the bundle function its comment names. A Mermaid call they miss draws as its source.
+
+/** The end of a double-quoted string that starts at i, or i. (bQ) */
+function quoted(e        , i        )         {
+  if (e[i] !== '"') return i;
+  let r = i + 1;
+  while (r < e.length) {
+    if (e[r] === '\\') r += 2;
+    else if (e[r] === '"') return r + 1;
+    else r++;
+  }
+  return r;
+}
+
+/** The code inside ``` fences, or the body when it has none. (qHt) */
+function unfence(e        )         {
+  const fence = (i        ) => e[i] === '`' && e[i + 1] === '`' && e[i + 2] === '`';
+  const blocks           = [];
+  let r = 0;
+  while (r < e.length) {
+    let open = -1;
+    while (r < e.length) {
+      const q = quoted(e, r);
+      if (q > r) { r = q; continue; }
+      if (fence(r)) { open = r; break; }
+      r++;
+    }
+    if (open === -1) break;
+    let n = open + 3;
+    while (n < e.length && e[n] !== '\n') n++;
+    if (n >= e.length) { blocks.push(e.slice(open + 3).replace(/^[^\n]*\n?/, '')); break; }
+    n++;
+    let close = -1;
+    let i = n;
+    while (i < e.length) {
+      const q = quoted(e, i);
+      if (q > i) { i = q; continue; }
+      if (fence(i)) { close = i; break; }
+      i++;
+    }
+    if (close !== -1) { blocks.push(e.slice(n, close)); r = close + 3; } else { blocks.push(e.slice(n)); r = e.length; }
+  }
+  if (blocks.length) return blocks.join('\n');
+  if (!e.startsWith('```')) return e;
+  let a = 3;
+  while (a < e.length && e[a] !== '\n') a++;
+  const rest = e.slice(a < e.length ? a + 1 : 3);
+  const last = rest.lastIndexOf('```');
+  return last !== -1 ? rest.slice(0, last) : rest;
+}
+
+/** The body without // and # comments, which end at the line's end outside a string. (VHt) */
+function uncomment(e        )         {
+  let inside                 = false;
+  return e.split('\n').map((line) => {
+    for (let a = 0; a < line.length; a++) {
+      const c = line[a];
+      if (inside) {
+        if (c === '\\' && a + 1 < line.length) { a++; continue; }
+        if (c === inside) inside = false;
+        continue;
+      }
+      if (c === '"' || c === "'") { inside = c; continue; }
+      if ((c === '/' && line[a + 1] === '/') || c === '#') return line.slice(0, a).trimEnd();
+    }
+    return line;
+  }).join('\n');
+}
+
+                                                                                              
+
+/** The tokens the statements read: strings with OpenUI's escapes, names, and the punctuation around calls. (pQ) */
+function tokens(e        )          {
+  const out          = [];
+  const word = (c                    ) => !!c && /[A-Za-z0-9_]/.test(c);
+  let r = 0;
+  while (r < e.length) {
+    const c = e[r] ;
+    if (c === ' ' || c === '\t' || c === '\r') { r++; continue; }
+    if (c === '\n') { out.push({ t: 'nl' }); r++; continue; }
+    if (c === '(' || c === ')' || c === ',') { out.push({ t: c }); r++; continue; }
+    if (c === '=') {
+      if (e[r + 1] === '=') { out.push({ t: 'other' }); r += 2; } else { out.push({ t: '=' }); r++; }
+      continue;
+    }
+    if (c === '"') {
+      // A string JSON cannot read keeps its text as written, and one with no closing quote gets one.
+      const at = r;
+      let closed = false;
+      for (r++; r < e.length;) {
+        if (e[r] === '\\') r += 2;
+        else if (e[r] === '"') { r++; closed = true; break; } else r++;
+      }
+      const raw = e.slice(at, r);
+      let v        ;
+      try { v = String(JSON.parse(closed ? raw : `${raw}"`)); } catch { v = raw.replace(/^"|"$/g, ''); }
+      out.push({ t: 'str', v });
+      continue;
+    }
+    if (c === "'") {
+      let v = '';
+      for (r++; r < e.length;) {
+        if (e[r] === '\\') {
+          r++;
+          if (r < e.length) { const x = e[r] ; v += x === 'n' ? '\n' : x === 't' ? '\t' : x; r++; }
+        } else if (e[r] === "'") { r++; break; } else v += e[r++];
+      }
+      out.push({ t: 'str', v });
+      continue;
+    }
+    if ((c === '$' || c === '@') && /[A-Za-z_]/.test(e[r + 1] ?? '')) {
+      for (r++; word(e[r]); r++);
+      out.push({ t: 'other' });
+      continue;
+    }
+    if (/[A-Za-z_]/.test(c)) {
+      const at = r;
+      for (; word(e[r]); r++);
+      out.push({ t: 'name', v: e.slice(at, r) });
+      continue;
+    }
+    out.push({ t: 'other' });
+    r++;
+  }
+  return out;
+}
+
+function bodyDiagrams(body                    )            {
+  if (!body) return [];
+  const list = tokens(uncomment(unfence(String(body).trim())).trim());
+  const found            = [];
+  let statement                    ;
+  let depth = 0;
+  for (let i = 0; i < list.length; i++) {
+    const k = list[i] ;
+    const at = (j        ) => list[j]?.t;
+    if (k.t === '(') depth++;
+    else if (k.t === ')') depth = Math.max(0, depth - 1);
+    // A statement starts a line with its name and =, outside any open call.
+    if (depth === 0 && k.t === 'name' && (i === 0 || at(i - 1) === 'nl') && at(i + 1) === '=') statement = k.v;
+    if (k.t !== 'name' || k.v !== 'Mermaid' || at(i + 1) !== '(') continue;
+    const where = statement ? `body, statement ${statement}` : `body, diagram ${found.length + 1}`;
+    const arg = list[i + 2];
+    if (arg?.t !== 'str' || (at(i + 3) !== ')' && at(i + 3) !== ',')) throw new InboxError(400, `${where}: Mermaid takes the diagram source as a string, such as Mermaid("flowchart TD\\n  A --> B")`);
+    found.push({ where, source: arg.v });
+  }
+  return found;
+}
+
+/** Every diagram the page draws for these fields, in the order the card shows them. */
+export function findDiagrams(fields                                                                                               )            {
+  return [...markdownDiagrams('text', fields.text), ...markdownDiagrams('recommendation', fields.recommendation), ...bodyDiagrams(fields.body)];
+}
+
+/** Check each diagram once, and reject the card with mermaid's own words for each one it cannot draw. */
+export async function checkDiagrams(found           , check                          )                           {
+  const checked                  = new Map();
+  if (!found.length) return checked;
+  if (!check) throw new InboxError(400, 'this inbox cannot check Mermaid diagrams, so it takes no card with one');
+  if (found.length > MAX_DIAGRAMS) throw new InboxError(400, `a card shows at most ${MAX_DIAGRAMS} diagrams`);
+  for (const d of found) if (!checked.has(d.source)) checked.set(d.source, await check(d.source));
+  const bad = found.filter((d) => checked.get(d.source) !== undefined);
+  if (bad.length) throw new InboxError(400, bad.map((d) => diagramMessage(d.where, check.version, checked.get(d.source) ?? '', 'the inbox did not take the card')).join('\n\n'));
+  return checked;
+}
+
+/** What the agent reads about one diagram that does not draw: where it is, what happened to the card, and mermaid's own words. */
+export function diagramMessage(where        , version        , error        , outcome        )         {
+  return `The Mermaid diagram in ${where} does not parse, so ${outcome}. Mermaid ${version} says:\n${error}`;
+}
+
+/** What the agent reads about a body the page would draw only in part, one fault a line. */
+export function bodyProblemsMessage(problems          , outcome         )         {
+  return `the page cannot draw all of this body${outcome ? `, ${outcome}` : ''}:\n- ${problems.join('\n- ')}`;
+}
+
+/** The card commits with no await after its check, so a diagram missing from the check means the card changed meanwhile. */
+export function requireChecked(found           , checked                             )       {
+  for (const d of found) {
+    if (!checked?.has(d.source)) throw new InboxError(409, `${d.where}: the inbox did not check this diagram before the card changed. Post the card again`);
+    if (checked.get(d.source) !== undefined) throw new InboxError(400, `${d.where}: mermaid cannot parse this diagram`);
+  }
+}

package/dist/src/core/expr.js

@@ -0,0 +1,125 @@
+// A small expression language for priority rules, such as
+//   kind == "blocked" || waitMinutes > 30 && tags.topic == "release"
+// It parses its own grammar and never calls eval, so a rule can read card
+// properties and nothing else, on every platform, including Workers.
+//
+//   or      := and ("||" and)*
+//   and     := not ("&&" not)*
+//   not     := "!" not | compare
+//   compare := sum (("==" | "!=" | "<" | "<=" | ">" | ">=" | "in") sum)?
+//   sum     := product (("+" | "-") product)*
+//   product := unary (("*" | "/") unary)*
+//   unary   := "-" unary | primary
+//   primary := number | string | true | false | null | name ("." name)* | "(" or ")"
+
+                                                                                                    
+           
+                          
+                              
+                                 
+                                               
+
+const MAX_LENGTH = 500;
+const TOKEN = /\s*(?:(\d+(?:\.\d+)?)|("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')|(\|\||&&|==|!=|<=|>=|[<>!()+\-*/.])|([A-Za-z_][A-Za-z0-9_]*))/y;
+
+function tokenize(src        )           {
+  if (src.length > MAX_LENGTH) throw new Error(`a rule is at most ${MAX_LENGTH} characters`);
+  const out           = [];
+  TOKEN.lastIndex = 0;
+  while (TOKEN.lastIndex < src.length) {
+    if (/^\s*$/.test(src.slice(TOKEN.lastIndex))) break;
+    // A failed sticky match resets lastIndex, so keep the position first.
+    const at = TOKEN.lastIndex;
+    const m = TOKEN.exec(src);
+    if (!m) throw new Error(`unexpected character at ${at + (/^\s*/.exec(src.slice(at))?.[0].length ?? 0) + 1}`);
+    out.push(m[1] ?? m[2] ?? m[3] ?? m[4] ?? '');
+  }
+  return out;
+}
+
+export function parse(src        )       {
+  const toks = tokenize(src);
+  let i = 0;
+  const peek = ()                     => toks[i];
+  const take = (t         )         => {
+    const v = toks[i];
+    if (v === undefined || (t !== undefined && v !== t)) throw new Error(t ? `expected ${t}` : 'unexpected end of rule');
+    i++;
+    return v;
+  };
+  const left = (next            , ops          )       => {
+    let a = next();
+    while (ops.includes(peek() ?? '')) { const op = take(); a = { t: 'bin', op, a, b: next() }; }
+    return a;
+  };
+  const primary = ()       => {
+    const v = take();
+    if (v === '(') { const e = or(); take(')'); return e; }
+    if (/^\d/.test(v)) return { t: 'lit', v: Number(v) };
+    if (v[0] === '"' || v[0] === "'") return { t: 'lit', v: v.slice(1, -1).replace(/\\(.)/g, '$1') };
+    if (v === 'true' || v === 'false') return { t: 'lit', v: v === 'true' };
+    if (v === 'null') return { t: 'lit', v: null };
+    if (!/^[A-Za-z_]/.test(v) || v === 'in') throw new Error(`unexpected ${v}`);
+    const p = [v];
+    while (peek() === '.') { take('.'); const n = take(); if (!/^[A-Za-z_]/.test(n)) throw new Error(`unexpected ${n}`); p.push(n); }
+    return { t: 'path', p };
+  };
+  const unary = ()       => (peek() === '-' ? (take(), { t: 'neg', a: unary() }) : primary());
+  const product = ()       => left(unary, ['*', '/']);
+  const sum = ()       => left(product, ['+', '-']);
+  const compare = ()       => {
+    const a = sum();
+    const op = peek();
+    if (op && ['==', '!=', '<', '<=', '>', '>=', 'in'].includes(op)) { take(); return { t: 'bin', op, a, b: sum() }; }
+    return a;
+  };
+  const not = ()       => (peek() === '!' ? (take(), { t: 'not', a: not() }) : compare());
+  const and = ()       => left(not, ['&&']);
+  function or()       { return left(and, ['||']); }
+  const tree = or();
+  if (i < toks.length) throw new Error(`unexpected ${toks[i]}`);
+  return tree;
+}
+
+function get(scope       , path          )        {
+  let v        = scope;
+  for (const k of path) {
+    if (v === null || typeof v !== 'object' || Array.isArray(v) || !Object.hasOwn(v, k)) return undefined;
+    v = (v                         )[k];
+  }
+  return v;
+}
+
+function run(n      , scope       )        {
+  switch (n.t) {
+    case 'lit': return n.v;
+    case 'path': return get(scope, n.p);
+    case 'not': return !run(n.a, scope);
+    case 'neg': return -Number(run(n.a, scope));
+    case 'bin': {
+      if (n.op === '&&') return Boolean(run(n.a, scope)) && Boolean(run(n.b, scope));
+      if (n.op === '||') return Boolean(run(n.a, scope)) || Boolean(run(n.b, scope));
+      const a = run(n.a, scope);
+      const b = run(n.b, scope);
+      switch (n.op) {
+        case '==': return a === b;
+        case '!=': return a !== b;
+        case '<': return Number(a) < Number(b);
+        case '<=': return Number(a) <= Number(b);
+        case '>': return Number(a) > Number(b);
+        case '>=': return Number(a) >= Number(b);
+        case '+': return typeof a === 'string' || typeof b === 'string' ? `${a ?? ''}${b ?? ''}` : Number(a) + Number(b);
+        case '-': return Number(a) - Number(b);
+        case '*': return Number(a) * Number(b);
+        case '/': return Number(a) / Number(b);
+        case 'in': return Array.isArray(b) ? b.includes(a) : b !== null && typeof b === 'object' ? Object.hasOwn(b, String(a)) : typeof b === 'string' && b.includes(String(a));
+      }
+    }
+  }
+  throw new Error('unknown expression');
+}
+
+/** Whether `rule` holds for `scope`. A rule that fails to parse throws. */
+export function test(rule        , scope                       )          {
+  return Boolean(run(parse(rule), scope));
+}

package/dist/src/core/file-links.js

@@ -0,0 +1,48 @@
+// The file: addresses a card names. The laptop inbox serves a file to the owner's page only when its card names it,
+// so the agent that posted the card chooses what is exposed. web/markdown.js links the same addresses.
+const FILE_URL = /file:\/\/[^\s<>()[\]`]+/g;
+const URL_TAIL = /[.,;:!?'"*_]+$/;
+
+/** The decoded path of a file: address on this machine, or undefined for another host or an address that is not one. */
+export function fileLinkPath(url        )                     {
+  if (!/^file:\/\//.test(url)) return undefined;
+  try {
+    const u = new URL(url);
+    return u.host ? undefined : decodeURIComponent(u.pathname);
+  } catch {
+    return undefined;
+  }
+}
+
+/** Every path the text names with a file: address, anywhere in it. A bare address ends before the punctuation that may close
+ * a sentence, and the target of a Markdown link ends at its parenthesis, so before one the address is kept whole as well. */
+export function fileLinkPaths(text        )           {
+  const paths = new Set        ();
+  for (const m of text.matchAll(FILE_URL)) {
+    const urls = [m[0].replace(URL_TAIL, '')];
+    if (text[m.index + m[0].length] === ')') urls.push(m[0]);
+    for (const url of urls) {
+      const p = fileLinkPath(url);
+      if (p !== undefined) paths.add(p);
+    }
+  }
+  return [...paths];
+}
+
+/** The path that the rest of a folder ticket's address names under `folder`, or undefined when it would leave the folder.
+ * Each segment decodes on its own, so an encoded slash or backslash never splits one. A segment that is empty, starts with
+ * a dot, or contains a slash, a backslash or a NUL is refused. That covers `..`, an absolute path, and hidden files such as `.env`. */
+export function folderFilePath(folder        , rest        )                     {
+  const names           = [];
+  for (const segment of rest.split('/')) {
+    let name        ;
+    try {
+      name = decodeURIComponent(segment);
+    } catch {
+      return undefined;
+    }
+    if (!name || name.startsWith('.') || /[/\\\0]/.test(name)) return undefined;
+    names.push(name);
+  }
+  return `${folder.replace(/\/+$/, '')}/${names.join('/')}`;
+}