dirpush 0.0.0 → 0.1.0

package/src/audit.ts

@@ -0,0 +1,229 @@
+/**
+ * Measures what a listing is actually worth, without AI: the rel attribute on outbound product links of real
+ * listing pages, whether those pages are indexable, and which bot check guards the submit form.
+ * Every verdict carries the page it was measured on.
+ */
+import { locs } from "./listings";
+import { normalizeUrl, type Directory } from "./registry";
+
+const UA = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130 Safari/537.36";
+export type Rel = "dofollow" | "nofollow" | "ugc" | "sponsored" | "mixed" | "unknown";
+export type LinkAudit = {
+  rel: Rel;
+  method: "own_listing" | "sample_listing" | "platform_rule" | "none";
+  evidence: string | null; // the listing page the rel was read on
+  samples: number; // listing pages that had outbound product links
+  noindex: boolean | null; // listing page tells search engines not to index it
+  claimed: "dofollow" | "nofollow" | null; // what the directory's own text says
+  bot_check: "recaptcha" | "turnstile" | "hcaptcha" | "math" | "none" | "unknown";
+  checked_at: string;
+};
+
+async function get(url: string, timeout = 15000) {
+  try {
+    const r = await fetch(url, { redirect: "follow", headers: { "user-agent": UA, accept: "text/html,application/xhtml+xml,application/xml" }, signal: AbortSignal.timeout(timeout) });
+    const ct = r.headers.get("content-type") ?? "";
+    const body = r.ok && /html|xml|text/.test(ct) ? (await r.text()).slice(0, 2_000_000) : (await r.body?.cancel(), "");
+    return { status: r.status, url: r.url, body, robots: r.headers.get("x-robots-tag") ?? "" };
+  } catch {
+    return { status: 0, url, body: "", robots: "" };
+  }
+}
+
+// Hosts that are never "the product's website" on a listing page.
+const NOISE = /(^|\.)(twitter|x|facebook|linkedin|instagram|youtube|youtu|tiktok|pinterest|reddit|discord|t|telegram|medium|google|googletagmanager|googleapis|gstatic|doubleclick|apple|microsoft|cloudflare|gravatar|wp|wordpress|w3|schema|ahrefs|semrush|producthunt|github|gitlab|vercel|netlify|stripe|paypal|buymeacoffee|ko-fi|patreon|substack|beehiiv|mailchimp|typeform|tally|notion|calendly|cal|crisp|intercom|hotjar|plausible|umami|fonts|jsdelivr|unpkg|cdnjs)\.[a-z.]+$/;
+
+/** rel of each outbound link on a page, keyed by host; nofollow wins over ugc/sponsored when combined. */
+export function outboundRels(html: string, pageHost: string) {
+  const out: { host: string; href: string; rel: Exclude<Rel, "mixed" | "unknown">; visit: boolean }[] = [];
+  for (const m of html.matchAll(/<a\b([^>]*)>([\s\S]{0,600}?)<\/a>/gi)) {
+    const attrs = m[1]!;
+    const label = m[2]!.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    const href = /\bhref\s*=\s*["']([^"']+)["']/i.exec(attrs)?.[1];
+    if (!href || !/^https?:\/\//i.test(href)) continue;
+    let host: string;
+    try { host = new URL(href).hostname.toLowerCase().replace(/^www\./, ""); } catch { continue; }
+    if (host === pageHost || host.endsWith(`.${pageHost}`) || pageHost.endsWith(`.${host}`) || NOISE.test(host)) continue;
+    const rel = (/\brel\s*=\s*["']([^"']*)["']/i.exec(attrs)?.[1] ?? "").toLowerCase();
+    // The listing's "go to the product" link: visit/website wording, or a ref/utm parameter naming the directory.
+    const visit = /\b(visit|website|try|get started|go to|open|homepage|view site|official)\b/i.test(label) || /visit|website|outbound|external-link/i.test(attrs) || /[?&](ref|utm_source|via|source)=/i.test(href);
+    out.push({ host, href, visit, rel: /nofollow/.test(rel) ? "nofollow" : /sponsored/.test(rel) ? "sponsored" : /ugc/.test(rel) ? "ugc" : "dofollow" });
+  }
+  return out;
+}
+
+export const isNoindex = (html: string, header: string) =>
+  /noindex/i.test(header) || /<meta[^>]+name=["'](robots|googlebot)["'][^>]+content=["'][^"']*noindex/i.test(html) || /<meta[^>]+content=["'][^"']*noindex[^"']*["'][^>]+name=["'](robots|googlebot)["']/i.test(html);
+
+export function botCheck(html: string): LinkAudit["bot_check"] {
+  if (!html) return "unknown";
+  if (/challenges\.cloudflare\.com\/turnstile|cf-turnstile/i.test(html)) return "turnstile";
+  if (/hcaptcha\.com|h-captcha/i.test(html)) return "hcaptcha";
+  if (/google\.com\/recaptcha|recaptcha\/api|g-recaptcha|grecaptcha/i.test(html)) return "recaptcha";
+  if (/what is \d+\s*[+\-x×*]\s*\d+|anti-?spam (question|check)|solve.{0,20}(sum|math)/i.test(html)) return "math";
+  return "none";
+}
+
+/** What the directory says about its links, from the registry's own notes and conditions. */
+export function claimedRel(text: string): LinkAudit["claimed"] {
+  const t = text.toLowerCase();
+  const no = /no-?follow/.test(t), dof = /do-?follow/.test(t);
+  if (dof && !no) return "dofollow";
+  if (no && !dof) return "nofollow";
+  if (dof && no) return /free[^.]{0,60}no-?follow|no-?follow[^.]{0,40}free/.test(t) ? "nofollow" : "dofollow";
+  return null;
+}
+
+// Paths that look like a single product's page on a directory.
+const PRODUCT_PATH = /\/(tools?|products?|p|startups?|listings?|apps?|software|items?|launch(es)?|projects?|ai|saas|companies|company|directory|site|sites|s)\/[^/?#]{2,}\/?$/i;
+
+async function sampleListings(site: string, max = 4) {
+  const origin = new URL(site).origin;
+  const robots = (await get(`${origin}/robots.txt`, 8000)).body;
+  const queue = [...robots.matchAll(/^sitemap:\s*(\S+)/gim)].map((m) => m[1]!);
+  if (!queue.length) queue.push(`${origin}/sitemap.xml`);
+  const found: string[] = [];
+  for (let i = 0; i < queue.length && i < 6 && found.length < 40; i++) {
+    const xml = (await get(queue[i]!, 12000)).body;
+    const urls = locs(xml);
+    if (/<sitemapindex/i.test(xml)) {
+      // Prefer child sitemaps that sound like products.
+      queue.push(...urls.sort((a, b) => Number(/tool|product|startup|listing|app|item|launch|project/i.test(b)) - Number(/tool|product|startup|listing|app|item|launch|project/i.test(a))));
+    } else found.push(...urls.filter((u) => PRODUCT_PATH.test(new URL(u, origin).pathname)));
+  }
+  // Spread the picks across the list: newest and oldest listings can differ.
+  const step = Math.max(1, Math.floor(found.length / max));
+  return [...new Set(found.filter((_, i) => i % step === 0))].slice(0, max);
+}
+
+const tally = (rels: Rel[]): Rel => {
+  const kinds = new Set(rels);
+  if (!kinds.size) return "unknown";
+  if (kinds.size === 1) return rels[0]!;
+  // A page with both is usually "dofollow for paid/featured, nofollow for the rest": call it mixed.
+  return "mixed";
+};
+
+export async function auditDirectory(d: Directory, ownListings: { url: string; productHost: string }[], playbook = ""): Promise<LinkAudit> {
+  const today = new Date().toISOString().slice(0, 10);
+  const site = normalizeUrl(d.website).domain;
+  const claimed = claimedRel([d.cost.notes ?? "", ...d.submission.conditions, playbook].join(" "));
+  const submit = d.submission_url ? await get(d.submission_url) : null;
+  const base = { claimed, bot_check: submit ? botCheck(submit.body) : ("unknown" as const), checked_at: today };
+
+  // GitHub renders every user-content link with rel="nofollow".
+  if (/^github\.com$|\.github\.io$/.test(site) && /github\.com/.test(d.website))
+    return { ...base, rel: "nofollow", method: "platform_rule", evidence: d.website, samples: 0, noindex: false };
+
+  // 1. Our own live listings: the exact link we got.
+  for (const own of ownListings) {
+    const page = await get(own.url);
+    const links = outboundRels(page.body, site).filter((l) => l.host === own.productHost || l.host.endsWith(`.${own.productHost}`));
+    // The URL stays on the submission: the shared registry never names a product.
+    if (links.length) return { ...base, rel: tally(links.map((l) => l.rel)), method: "own_listing", evidence: null, samples: 1, noindex: isNoindex(page.body, page.robots) };
+  }
+
+  // 2. Other products' listing pages from the sitemap: the dominant rel on outbound product links.
+  const rels: Rel[] = [];
+  let evidence: string | null = null, noindex: boolean | null = null, samples = 0;
+  for (const url of await sampleListings(d.website)) {
+    const page = await get(url);
+    // Only pages with a visit-style link to one external product count as listings.
+    const links = outboundRels(page.body, site).filter((l) => l.visit);
+    const hosts = new Set(links.map((l) => l.host));
+    if (!links.length || hosts.size > 3) continue; // none, or a page of many products (a category page)
+    const counts = new Map<string, number>();
+    for (const l of links) counts.set(l.host, (counts.get(l.host) ?? 0) + 1);
+    const top = [...counts].sort((a, b) => b[1] - a[1])[0]![0];
+    rels.push(tally(links.filter((l) => l.host === top).map((l) => l.rel)));
+    evidence ??= url;
+    noindex ??= isNoindex(page.body, page.robots);
+    samples++;
+  }
+  return { ...base, rel: tally(rels), method: samples ? "sample_listing" : "none", evidence, samples, noindex };
+}
+
+const NOT_LISTING = /^(c|cat|category|categories|tag|tags|topics?|collections?|directories|blog|posts?|news|articles?|guides?|alternatives?|compare|vs|best|top|page|search|login|log-in|signin|sign-in|signup|sign-up|register|account|dashboard|pricing|plans|about|contact|submit|add|faq|help|docs|terms|privacy|legal|cookies?|sitemap|rss|feed|advertise|sponsor|newsletter|api|users?|u|profile|makers?|authors?|en|de|fr|es|it)$/i;
+
+// ---- browser pass: real Chrome via agent-browser, for pages a plain fetch can't read -------------------------
+
+type Anchor = { href: string; rel: string; text: string; cls: string };
+type Rendered = { finalUrl: string; anchors: Anchor[]; robots: string; challenge: boolean };
+
+/** Renders a page in a throwaway, logged-out browser session and returns its links. Read-only. */
+export function renderAnchors(url: string, session: string): Rendered | null {
+  const ab = (...args: string[]) => Bun.spawnSync(["agent-browser", "--session", session, ...args], { stderr: "pipe", timeout: 60_000 });
+  if (ab("open", url).exitCode) return null;
+  ab("wait", "2500");
+  const script = `JSON.stringify({ finalUrl: location.href,
+    robots: (document.querySelector('meta[name=robots]') || {}).content || "",
+    challenge: /just a moment|checking your browser|verify you are human|ci siamo quasi/i.test(document.title + " " + document.body.innerText.slice(0, 400)),
+    anchors: [...document.querySelectorAll("a[href]")].slice(0, 600).map(a => ({ href: a.href, rel: a.rel || "", text: (a.innerText || a.getAttribute("aria-label") || "").trim().slice(0, 60), cls: String(a.className || "").slice(0, 120) })) })`;
+  const out = ab("eval", script);
+  try {
+    let v = JSON.parse(out.stdout.toString());
+    if (typeof v === "string") v = JSON.parse(v);
+    return v as Rendered;
+  } catch {
+    return null;
+  }
+}
+
+const relOfAttr = (rel: string): Exclude<Rel, "mixed" | "unknown"> =>
+  /nofollow/i.test(rel) ? "nofollow" : /sponsored/i.test(rel) ? "sponsored" : /ugc/i.test(rel) ? "ugc" : "dofollow";
+const hostOf = (u: string) => { try { return new URL(u).hostname.toLowerCase().replace(/^www\./, ""); } catch { return ""; } };
+
+/** Same rules as the fetch audit, applied to rendered pages: listing links from the homepage, visit links on each. */
+export function auditDirectoryBrowser(d: Directory, session: string): { link: LinkAudit; note: string } {
+  const today = new Date().toISOString().slice(0, 10);
+  const site = normalizeUrl(d.website).domain;
+  const base = { claimed: d.link?.claimed ?? null, bot_check: d.link?.bot_check ?? ("unknown" as const), checked_at: today };
+  const home = renderAnchors(d.website, session);
+  if (!home) return { link: { ...base, rel: "unknown", method: "none", evidence: null, samples: 0, noindex: null }, note: "homepage did not load" };
+  if (home.challenge) return { link: { ...base, rel: "unknown", method: "none", evidence: null, samples: 0, noindex: null }, note: "bot challenge on the homepage" };
+  // Listing pages are the biggest family of internal links sharing a path pattern. Which family is the listings
+  // (vs categories or tags) is tested, not guessed: the right one has a single "visit" link per page.
+  const groups = new Map<string, string[]>();
+  for (const h of new Set(home.anchors.map((a) => a.href.split(/[?#]/)[0]!))) {
+    const host = hostOf(h);
+    if (!(host === site || host.endsWith(`.${site}`))) continue;
+    const parts = new URL(h).pathname.split("/").filter(Boolean);
+    if (!parts.length || parts.some((p) => NOT_LISTING.test(p))) continue;
+    const key = `/${parts.slice(0, -1).join("/")}${parts.length > 1 ? "/" : ""}*`;
+    groups.set(key, [...(groups.get(key) ?? []), h]);
+  }
+  const families = [...groups].filter(([, urls]) => urls.length >= 5).sort((a, b) => b[1].length - a[1].length).slice(0, 3);
+  const listings = families.flatMap(([, urls]) => urls);
+  const rels: Rel[] = [];
+  let evidence: string | null = null, noindex: boolean | null = null, samples = 0;
+  const read = (url: string) => {
+    const page = renderAnchors(url, session);
+    if (!page || page.challenge) return false;
+    const outbound = page.anchors.filter((a) => {
+      const host = hostOf(a.href);
+      return !!host && host !== site && !host.endsWith(`.${site}`) && !site.endsWith(`.${host}`) && !NOISE.test(host);
+    });
+    // A button that says Visit/Website is the listing's own link; ref-tagged links alone may be sidebar promos.
+    const worded = outbound.filter((a) => /\b(visit|website|try|get started|go to|open|homepage|view site|official)\b/i.test(a.text) || /visit|website|outbound|external-link/i.test(a.cls));
+    const links = worded.length ? worded : outbound.filter((a) => /[?&](ref|utm_source|via|source)=/i.test(a.href));
+    const hosts = new Set(links.map((l) => hostOf(l.href)));
+    if (!links.length || hosts.size > 3) return false;
+    const counts = new Map<string, number>();
+    for (const l of links) counts.set(hostOf(l.href), (counts.get(hostOf(l.href)) ?? 0) + 1);
+    const top = [...counts].sort((x, y) => y[1] - x[1])[0]![0];
+    rels.push(tally(links.filter((l) => hostOf(l.href) === top).map((l) => relOfAttr(l.rel))));
+    evidence ??= page.finalUrl;
+    noindex ??= /noindex/i.test(page.robots);
+    samples++;
+    return true;
+  };
+  for (const [, urls] of families) {
+    const step = Math.max(1, Math.floor(urls.length / 4));
+    const spread = urls.filter((_, i) => i % step === 0);
+    if (!spread.slice(0, 2).map(read).some(Boolean)) continue; // not this family
+    for (const url of spread.slice(2, 4)) read(url);
+    break;
+  }
+  const note = !listings.length ? "no listing-like link families on the homepage" : samples ? `${samples} listing page${samples === 1 ? "" : "s"} read` : `tried ${families.length} link famil${families.length === 1 ? "y" : "ies"}, no page with a single visit link`;
+  return { link: { ...base, rel: tally(rels), method: samples ? "sample_listing" : "none", evidence, samples, noindex }, note };
+}

package/src/browser.ts

@@ -0,0 +1,123 @@
+/**
+ * The agents' browser: a dedicated, real Google Chrome profile (data/browser-profile) with remote debugging on
+ * a local port. Any agent that can run shell commands drives it with agent-browser (`scripts/ab` attaches to it);
+ * the CLI starts it and handles secrets, so passwords never pass through a model.
+ *
+ * Google services other than sign-in are unreachable from this profile: a PAC script sends them to a dead proxy.
+ * That holds for every client attached over CDP, not only for one wrapper.
+ */
+import { randomBytes } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { HOME } from "./db";
+
+export const BROWSER_PORT = Number(process.env.LAUNCH_BROWSER_PORT ?? 9222);
+export const PROFILE = join(HOME, "data/browser-profile");
+const CHROME = process.env.LAUNCH_CHROME ?? "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome";
+const BASE = `http://127.0.0.1:${BROWSER_PORT}`;
+/** One agent-browser session for secret handling, attached to the same Chrome. */
+const SECRETS_SESSION = "dirpush-secrets";
+
+/** Same list as scripts/ab: the profile is signed into the human's Google account; only sign-in pages may load. */
+export const BLOCKED_HOSTS = [
+  "mail.google.com", "gmail.com", "www.gmail.com", "inbox.google.com",
+  "drive.google.com", "drive.usercontent.google.com", "docs.google.com", "sheets.google.com", "slides.google.com", "forms.google.com",
+  "photos.google.com", "keep.google.com", "calendar.google.com", "contacts.google.com",
+  "myaccount.google.com", "security.google.com", "myactivity.google.com", "passwords.google.com",
+  "pay.google.com", "payments.google.com", "wallet.google.com", "takeout.google.com", "admin.google.com",
+  "script.google.com", "console.cloud.google.com", "cloud.google.com", "console.developers.google.com",
+  "chromewebstore.google.com", "chrome.google.com",
+];
+
+export function pacScript(hosts = BLOCKED_HOSTS) {
+  return `function FindProxyForURL(url, host) { var b = ${JSON.stringify(hosts)}; for (var i = 0; i < b.length; i++) if (host === b[i]) return "PROXY 127.0.0.1:9"; return "DIRECT"; }`;
+}
+
+type Target = { id: string; type: string; url: string; title: string; webSocketDebuggerUrl?: string };
+const json = async <T>(path: string) => (await fetch(`${BASE}${path}`, { signal: AbortSignal.timeout(1500) })).json() as Promise<T>;
+
+export async function browserStatus() {
+  try {
+    const v = await json<{ Browser: string }>("/json/version");
+    const pages = (await json<Target[]>("/json/list")).filter((t) => t.type === "page");
+    return { running: true, port: BROWSER_PORT, browserUrl: BASE, chrome: v.Browser, pages: pages.map((p) => ({ title: p.title.slice(0, 80), url: p.url.slice(0, 200) })) };
+  } catch {
+    return { running: false, port: BROWSER_PORT, browserUrl: BASE };
+  }
+}
+
+export async function startBrowser() {
+  const now = await browserStatus();
+  if (now.running) return { ...now, started: false };
+  if (!existsSync(CHROME)) throw new Error(`Google Chrome not found at ${CHROME} (set LAUNCH_CHROME)`);
+  const pac = `data:application/x-ns-proxy-autoconfig;base64,${Buffer.from(pacScript()).toString("base64")}`;
+  // Plain Chrome, headed, no automation flags: Google sign-in and bot checks see a normal browser. The keychain
+  // flags match agent-browser and scripts/google-login: the profile's cookies are encrypted with that key, so
+  // without them every saved session would be unreadable.
+  Bun.spawn([CHROME, `--user-data-dir=${PROFILE}`, `--remote-debugging-port=${BROWSER_PORT}`, `--proxy-pac-url=${pac}`, "--use-mock-keychain", "--password-store=basic", "--no-first-run", "--no-default-browser-check"], {
+    stdout: "ignore", stderr: "ignore", stdin: "ignore",
+  }).unref();
+  for (let i = 0; i < 40; i++) {
+    await Bun.sleep(250);
+    const s = await browserStatus();
+    if (s.running) return { ...s, started: true };
+  }
+  throw new Error(`Chrome did not open port ${BROWSER_PORT}. Is this profile already open without remote debugging? Quit that window and retry.`);
+}
+
+export async function stopBrowser() {
+  const s = await browserStatus();
+  if (!s.running) return { stopped: false, running: false };
+  const { webSocketDebuggerUrl } = await json<{ webSocketDebuggerUrl: string }>("/json/version");
+  await new Promise<void>((resolve) => {
+    const ws = new WebSocket(webSocketDebuggerUrl);
+    ws.onopen = () => ws.send(JSON.stringify({ id: 1, method: "Browser.close" }));
+    ws.onclose = ws.onerror = () => resolve();
+    setTimeout(resolve, 3000);
+  });
+  return { stopped: true };
+}
+
+function ab(args: string[], stdin?: string) {
+  const p = Bun.spawnSync(["agent-browser", "--session", SECRETS_SESSION, "--cdp", String(BROWSER_PORT), ...args], { stdin: stdin === undefined ? "ignore" : Buffer.from(stdin), stdout: "pipe", stderr: "pipe", timeout: 60_000 });
+  const out = p.stdout.toString().trim();
+  if (p.exitCode !== 0) throw new Error(`agent-browser ${args[0]} failed: ${(p.stderr.toString() || out).trim().slice(0, 300)}`);
+  return out;
+}
+
+/** The open tab on `site`'s host (the one the agent is working in); the most recently active one if several. */
+async function pageOn(site: string) {
+  const host = new URL(site.includes("://") ? site : `https://${site}`).hostname.replace(/^www\./, "");
+  if (!(await browserStatus()).running) throw new Error("the browser is not running: launch browser start");
+  const page = (await json<Target[]>("/json/list")).find((t) => t.type === "page" && /^https?:/.test(t.url) && new URL(t.url).hostname.replace(/^www\./, "").endsWith(host));
+  if (!page) throw new Error(`no open tab on ${host}; open the login/sign-up page first`);
+  ab(["tab", page.id]);
+  return page;
+}
+
+/** Fills a saved login (agent-browser vault) into the open tab on that site. The password never leaves the vault. */
+export async function vaultLogin(name: string) {
+  const meta = JSON.parse(ab(["auth", "show", name, "--json"])) as { data?: { profile?: { url?: string } } };
+  const url = meta.data?.profile?.url;
+  if (!url) throw new Error(`vault entry ${name} has no login URL`);
+  const page = await pageOn(url);
+  ab(["auth", "login", name]);
+  return { vault: name, page: page.url.slice(0, 200), filled: true };
+}
+
+/**
+ * New account password: generated here, typed into every given field of the open tab on `url`'s site, checked,
+ * then saved to the vault as `name`. Returns no secret.
+ */
+export async function newPassword(name: string, url: string, username: string, selectors: string[]) {
+  if (!selectors.length) throw new Error("pass the password field selector(s), e.g. 'input[type=password]'");
+  const page = await pageOn(url);
+  const pw = randomBytes(18).toString("base64");
+  for (const s of selectors) ab(["fill", s, pw]);
+  // A fill can "succeed" on a selector that matched nothing; never save a password the site didn't get.
+  const lengths = JSON.parse(ab(["eval", `JSON.stringify(${JSON.stringify(selectors)}.map((s) => document.querySelector(s)?.value.length ?? -1))`]));
+  const got = (typeof lengths === "string" ? JSON.parse(lengths) : lengths) as number[];
+  if (got.some((n) => n !== pw.length)) throw new Error(`password fields not filled (lengths ${got.join(", ")}); nothing saved`);
+  ab(["auth", "save", name, "--url", url, "--username", username, "--password-stdin"], pw);
+  return { vault: name, username, fields: selectors.length, page: page.url.slice(0, 200), saved: true };
+}

package/src/capabilities.ts

@@ -0,0 +1,62 @@
+/**
+ * What the agent working this workspace can actually use: a browser driver, an email tool for verification
+ * links and codes, anything else. The CLI detects what it can see (binaries on PATH); the agent records the rest
+ * (its own MCP/connector tools) during setup, because only the agent knows which tools its harness gives it.
+ * Stored in workspace/capabilities.yaml; no secrets.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { z } from "zod";
+import { WORKSPACE } from "./workspace";
+
+export const Capabilities = z.object({
+  checked_at: z.string().optional(),
+  checked_by: z.string().optional(), // agent/harness that recorded it, e.g. "claude-code"
+  browser: z
+    .object({
+      tool: z.string().default("agent-browser"),
+      notes: z.string().optional(),
+    })
+    .default({ tool: "agent-browser" }),
+  email: z
+    .object({
+      available: z.boolean(),
+      // How to reach it, in the agent's own words: "Executor Gmail app (tools.gmail.search, readMessage)",
+      // "claude.ai Gmail connector", "IMAP via himalaya CLI"…
+      tool: z.string().optional(),
+      address: z.string().optional(), // the inbox it reads; should match identity.yaml email
+      read_only: z.boolean().optional(), // true when the tool cannot send/delete/forward
+      notes: z.string().optional(),
+    })
+    .default({ available: false }),
+  notes: z.string().optional(),
+});
+export type Capabilities = z.infer<typeof Capabilities>;
+
+export const CAPABILITIES = join(WORKSPACE, "capabilities.yaml");
+
+export async function loadCapabilities(): Promise<Capabilities | null> {
+  if (!existsSync(CAPABILITIES)) return null;
+  return Capabilities.parse(Bun.YAML.parse(await Bun.file(CAPABILITIES).text()) ?? {});
+}
+
+/** Shallow-merges per section, so `set --input '{"email":{...}}'` leaves the browser entry alone. */
+export async function saveCapabilities(patch: Record<string, unknown>, by?: string) {
+  const prev = (await loadCapabilities()) ?? Capabilities.parse({});
+  const merged: Record<string, unknown> = { ...prev };
+  for (const [k, v] of Object.entries(patch)) {
+    const old = (prev as Record<string, unknown>)[k];
+    merged[k] = v && typeof v === "object" && !Array.isArray(v) && old && typeof old === "object" ? { ...old, ...v } : v;
+  }
+  const next = Capabilities.parse({ ...merged, checked_at: new Date().toISOString().slice(0, 10), ...(by && { checked_by: by }) });
+  await Bun.write(CAPABILITIES, Bun.YAML.stringify(next, null, 2));
+  return next;
+}
+
+/** What the CLI can see without the agent: browser driver binaries on PATH. */
+export function detect() {
+  const which = (bin: string) => Bun.which(bin);
+  const ab = which("agent-browser");
+  const version = ab ? Bun.spawnSync([ab, "--version"], { stdout: "pipe", stderr: "ignore" }).stdout.toString().trim() : null;
+  return { agentBrowser: ab ? { path: ab, version } : null };
+}