@tangle-network/agent-app 0.43.26 → 0.43.28

package/bin/preflight.mjs

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+/**
+ * `agent-app-preflight` — run a product's declared secret-liveness probes as a
+ * DEPLOY step and fail the deploy if any critical secret is dead.
+ *
+ * Reads `preflight.config.mjs` from the current working directory (override
+ * with `PREFLIGHT_CONFIG`). That file default-exports the probes, built from
+ * `process.env` at load time — the deploy already has the real secrets in its
+ * environment, which is the one place they can be probed for liveness (CI
+ * cannot hold them). Exit 0 when every critical probe is live, 1 when one is
+ * dead (deploy fails), 2 on a config/usage error.
+ *
+ * Wire it as a step BEFORE `wrangler deploy`:
+ *   agent-app-preflight
+ */
+import { existsSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+import { formatPreflightReport, runPreflight } from '../dist/preflight/index.js'
+
+const configFile = process.env.PREFLIGHT_CONFIG ?? 'preflight.config.mjs'
+
+async function loadProbes() {
+  const path = resolve(process.cwd(), configFile)
+  if (!existsSync(path)) {
+    console.error(`preflight: no config at ${path}`)
+    console.error(
+      `Create ${configFile} default-exporting probes built from process.env — see '@tangle-network/agent-app/preflight'.`,
+    )
+    process.exit(2)
+  }
+  const mod = await import(pathToFileURL(path).href)
+  const exported = mod.default ?? mod.probes
+  const resolved = typeof exported === 'function' ? await exported() : exported
+  const probes = Array.isArray(resolved) ? resolved : resolved?.probes
+  if (!Array.isArray(probes) || probes.length === 0) {
+    console.error(`preflight: ${configFile} must default-export a non-empty array of probes (or { probes }).`)
+    process.exit(2)
+  }
+  return probes
+}
+
+const probes = await loadProbes()
+const report = await runPreflight(probes)
+console.log(formatPreflightReport(report))
+process.exit(report.ok ? 0 : 1)

package/dist/chunk-NYATNLRK.js

@@ -0,0 +1,99 @@
+// src/theme-contract/index.ts
+import { existsSync, readFileSync, readdirSync } from "fs";
+import { join, relative } from "path";
+import { fileURLToPath } from "url";
+var SOURCE_RE = /\.(ts|tsx|js|jsx|mjs|cjs)$/;
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".next", "coverage"]);
+var DANGEROUS_UTILITIES = [
+  { suffix: "surface-container-highest", varName: "--secondary" },
+  { suffix: "surface-container-high", varName: "--popover" },
+  { suffix: "surface-container", varName: "--card" },
+  { suffix: "card-foreground", varName: "--card-foreground" },
+  { suffix: "popover-foreground", varName: "--popover-foreground" },
+  { suffix: "card", varName: "--card" },
+  { suffix: "popover", varName: "--popover" }
+];
+var UTILITY_PREFIXES = "bg|text|border|ring|fill|stroke";
+function buildUtilityRe(suffix) {
+  return new RegExp(`(?<![\\w-])(?:${UTILITY_PREFIXES})-${suffix}(?![\\w-])`, "g");
+}
+function walkSources(dir) {
+  let entries;
+  try {
+    entries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  return entries.flatMap((e) => {
+    if (e.isDirectory()) return SKIP_DIRS.has(e.name) ? [] : walkSources(join(dir, e.name));
+    return SOURCE_RE.test(e.name) && !e.name.endsWith(".d.ts") ? [join(dir, e.name)] : [];
+  });
+}
+function definedVars(cssFiles) {
+  const defs = /* @__PURE__ */ new Set();
+  for (const file of cssFiles) {
+    let css;
+    try {
+      css = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    for (const m of css.matchAll(/^\s*(--[a-z0-9-]+)\s*:/gim)) if (m[1]) defs.add(m[1]);
+  }
+  return defs;
+}
+function defaultTokensCss() {
+  const candidates = ["../theme/tokens.css", "./theme/tokens.css"].map(
+    (rel) => fileURLToPath(new URL(rel, import.meta.url))
+  );
+  return candidates.find((p) => existsSync(p)) ?? candidates[0];
+}
+function checkThemeContract(opts) {
+  const tokensCss = opts.tokensCss ?? defaultTokensCss();
+  const defined = definedVars([tokensCss, ...opts.extraTokensCss ?? []]);
+  const allow = new Set(opts.allowlist ?? []);
+  const isDefined = (name) => defined.has(name) || allow.has(name);
+  const files = opts.srcDirs.flatMap(walkSources);
+  const utilityMatchers = DANGEROUS_UTILITIES.map((u) => ({ ...u, re: buildUtilityRe(u.suffix) }));
+  const seenVar = /* @__PURE__ */ new Map();
+  const seenUtility = /* @__PURE__ */ new Map();
+  for (const file of files) {
+    let text;
+    try {
+      text = readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const where = displayPath(file);
+    for (const m of text.matchAll(/var\(\s*(--[a-z0-9-]+)/gi)) {
+      const name = m[1];
+      if (!name || isDefined(name) || seenVar.has(name)) continue;
+      seenVar.set(name, where);
+    }
+    for (const u of utilityMatchers) {
+      if (isDefined(u.varName)) continue;
+      const key = `${u.varName}::${u.suffix}`;
+      if (seenUtility.has(key)) continue;
+      u.re.lastIndex = 0;
+      if (u.re.test(text)) seenUtility.set(key, `${where} (via ${firstUtilityHit(text, u.suffix)})`);
+    }
+  }
+  const missing = [
+    ...[...seenVar].map(([varName, referencedIn]) => ({ varName, referencedIn })),
+    ...[...seenUtility].map(([key, referencedIn]) => ({ varName: key.split("::")[0], referencedIn }))
+  ];
+  return { ok: missing.length === 0, missing };
+}
+function firstUtilityHit(text, suffix) {
+  const m = buildUtilityRe(suffix).exec(text);
+  return m?.[0] ?? `<utility>-${suffix}`;
+}
+function displayPath(file) {
+  const rel = relative(process.cwd(), file);
+  return rel && !rel.startsWith("..") ? rel : file;
+}
+
+export {
+  checkThemeContract
+};
+//# sourceMappingURL=chunk-NYATNLRK.js.map

package/dist/chunk-NYATNLRK.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/theme-contract/index.ts"],"sourcesContent":["/**\n * Exportable theme-token contract checker — the incident guard for the\n * invisible-popover class of bugs.\n *\n * The failure mode (tax-agent's transparent model dropdown; the whole\n * `bg-surface-container-*` family): a consumer app ships a component that\n * references a theme token — either as `var(--popover)` or as a Tailwind class\n * like `bg-surface-container-high` that the agent-app preset maps to\n * `hsl(var(--popover))` — but the app's OWN build never emits that custom\n * property (it forgot `import '@tangle-network/agent-app/styles'`, or dropped a\n * token in its local tokens.css). CSS resolves the missing var to nothing, the\n * surface paints transparent, and NOTHING errors. It ships invisible.\n *\n * `tests/theme/tokens-contract.test.ts` guards agent-app's OWN components. This\n * module lifts that walking logic into a function every CONSUMER app can run\n * against ITS OWN source in CI, comparing references to the tokens.css agent-app\n * ships plus any extra CSS the app defines.\n *\n * ── What each check covers (scope is deliberately honest) ────────────────────\n *\n *  1. var(--…) check — COMPLETE. Every `var(--name)` literal in the scanned\n *     source (inline styles, `bg-[var(--name)]` arbitrary Tailwind values, CSS\n *     template strings) is matched and compared against the defined token set.\n *     This is exact: a `var(--x)` reference is unambiguous. It is a raw-text\n *     scan (no AST), so a `var(--x)` written inside a comment or string literal\n *     counts too — deliberate: it keeps the single-source logic identical to the\n *     agent-app self-test, and a dangling `var(--x)` in a comment is a smell\n *     worth surfacing. Suppress a deliberate one with `allowlist`.\n *\n *  2. Tailwind-utility check — INTENTIONALLY PARTIAL. Bare classes like\n *     `bg-card` carry no `var(--)` and so are invisible to check 1; Tailwind\n *     resolves them to `hsl(var(--card))` at build via the preset. Fully\n *     resolving arbitrary Tailwind config is out of scope (it would mean\n *     re-implementing Tailwind). Instead we check the SPECIFIC known-dangerous\n *     families that have actually shipped invisible: the MD3 surface ladder\n *     (`surface-container` / `-high` / `-highest`) and the `card` / `popover`\n *     elevation pairs — exactly the utilities the agent-app tailwind-preset\n *     registers onto elevation tokens (see src/theme/tailwind-preset.ts, the\n *     source of truth for this mapping). The canvas/sequence aliases\n *     (`--bg-input`, `--text-primary`, …) are consumed as `bg-[var(--…)]`\n *     arbitrary values and so are already covered fully by check 1 — they need\n *     no entry here.\n *\n * Node-only (reads the filesystem) → this lives in the `./theme-contract`\n * subpath, NOT `./theme`, which must stay browser-clean (it's in the\n * browser-safe manifest test).\n */\n\nimport { type Dirent, existsSync, readFileSync, readdirSync } from 'node:fs'\nimport { join, relative } from 'node:path'\nimport { fileURLToPath } from 'node:url'\n\nexport interface ThemeContractOptions {\n  /** Consumer source directories to scan for token references (recursively). */\n  srcDirs: string[]\n  /**\n   * Path to the base tokens.css whose `--name:` definitions are the ground\n   * truth. Defaults to the tokens.css agent-app ships (`./styles`) — the set a\n   * consumer gets from `import '@tangle-network/agent-app/styles'`.\n   */\n  tokensCss?: string\n  /**\n   * Additional CSS files whose `--name:` definitions also count as defined —\n   * the app's own overrides/extensions layered on top of the base tokens.\n   */\n  extraTokensCss?: string[]\n  /**\n   * Token names (e.g. `--my-app-accent`) to treat as always-defined, suppressing\n   * them from the missing list. For app-specific vars defined outside any CSS\n   * the checker can see (injected at runtime, from a third-party stylesheet, …).\n   */\n  allowlist?: string[]\n}\n\nexport interface ThemeContractMiss {\n  /** The undefined custom property, e.g. `--popover`. */\n  varName: string\n  /**\n   * Where it was referenced: `path/to/file.tsx`, or\n   * `path/to/file.tsx (via bg-surface-container-high)` when the reference is a\n   * Tailwind utility that resolves to the token rather than a literal var().\n   */\n  referencedIn: string\n}\n\nexport interface ThemeContractResult {\n  ok: boolean\n  missing: ThemeContractMiss[]\n}\n\n/** Source extensions scanned for token references. */\nconst SOURCE_RE = /\\.(ts|tsx|js|jsx|mjs|cjs)$/\nconst SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', '.next', 'coverage'])\n\n/**\n * Known-dangerous Tailwind utility families and the elevation token each\n * resolves to, mirroring src/theme/tailwind-preset.ts. Ordered longest-suffix\n * first so `surface-container-highest` is matched before `surface-container`.\n * The negative look-around in {@link buildUtilityRe} makes ordering belt-and-\n * suspenders rather than load-bearing.\n */\nconst DANGEROUS_UTILITIES: ReadonlyArray<{ suffix: string; varName: string }> = [\n  { suffix: 'surface-container-highest', varName: '--secondary' },\n  { suffix: 'surface-container-high', varName: '--popover' },\n  { suffix: 'surface-container', varName: '--card' },\n  { suffix: 'card-foreground', varName: '--card-foreground' },\n  { suffix: 'popover-foreground', varName: '--popover-foreground' },\n  { suffix: 'card', varName: '--card' },\n  { suffix: 'popover', varName: '--popover' },\n]\n\n/** Tailwind color-utility prefixes that can carry a background/text/border color. */\nconst UTILITY_PREFIXES = 'bg|text|border|ring|fill|stroke'\n\n/**\n * Match a whole utility class for `suffix`, tolerant of variants (`hover:`,\n * `dark:`) and opacity (`/95`) but not of longer siblings: the trailing\n * `(?![\\w-])` stops `bg-surface-container` from matching inside\n * `bg-surface-container-high`, and `bg-card` from matching inside\n * `bg-card-foreground`.\n */\nfunction buildUtilityRe(suffix: string): RegExp {\n  return new RegExp(`(?<![\\\\w-])(?:${UTILITY_PREFIXES})-${suffix}(?![\\\\w-])`, 'g')\n}\n\n/** Recursively collect scannable source files under a directory. */\nfunction walkSources(dir: string): string[] {\n  let entries: Dirent[]\n  try {\n    entries = readdirSync(dir, { withFileTypes: true })\n  } catch {\n    return []\n  }\n  return entries.flatMap((e) => {\n    if (e.isDirectory()) return SKIP_DIRS.has(e.name) ? [] : walkSources(join(dir, e.name))\n    return SOURCE_RE.test(e.name) && !e.name.endsWith('.d.ts') ? [join(dir, e.name)] : []\n  })\n}\n\n/**\n * Every `--name:` DEFINITION across the given CSS files. A definition is\n * `--name:` at the start of a (trimmed) line; RHS references like\n * `hsl(var(--card))` are mid-line and are never counted as definitions.\n */\nfunction definedVars(cssFiles: string[]): Set<string> {\n  const defs = new Set<string>()\n  for (const file of cssFiles) {\n    let css: string\n    try {\n      css = readFileSync(file, 'utf8')\n    } catch {\n      continue\n    }\n    for (const m of css.matchAll(/^\\s*(--[a-z0-9-]+)\\s*:/gim)) if (m[1]) defs.add(m[1])\n  }\n  return defs\n}\n\n/**\n * Default tokens.css: the one agent-app ships as `./styles`. Resolved relative\n * to this module's URL, but tolerant of where the bundler lands the running\n * code — tsup code-splits shared logic into a chunk at the dist ROOT, so the\n * tokens.css sits one directory DIFFERENTLY depending on layout:\n *   - source (src/theme-contract/index.ts) → ../theme/tokens.css  (src/theme)\n *   - split chunk    (dist/contract-*.js)  → ./theme/tokens.css   (dist/theme)\n *   - unsplit entry  (dist/theme-contract/index.js) → ../theme/tokens.css\n * Probe both and return the one that exists; fall back to the first for a\n * sensible error path if neither is present.\n */\nfunction defaultTokensCss(): string {\n  const candidates = ['../theme/tokens.css', './theme/tokens.css'].map((rel) =>\n    fileURLToPath(new URL(rel, import.meta.url)),\n  )\n  return candidates.find((p) => existsSync(p)) ?? candidates[0]!\n}\n\n/**\n * Check that every theme token a consumer's source references is actually\n * defined in the CSS that consumer ships. Returns the full missing set; the\n * caller decides how to fail (the bin exits non-zero on any miss).\n */\nexport function checkThemeContract(opts: ThemeContractOptions): ThemeContractResult {\n  const tokensCss = opts.tokensCss ?? defaultTokensCss()\n  const defined = definedVars([tokensCss, ...(opts.extraTokensCss ?? [])])\n  const allow = new Set(opts.allowlist ?? [])\n  const isDefined = (name: string) => defined.has(name) || allow.has(name)\n\n  const files = opts.srcDirs.flatMap(walkSources)\n  const utilityMatchers = DANGEROUS_UTILITIES.map((u) => ({ ...u, re: buildUtilityRe(u.suffix) }))\n\n  // Dedupe by varName (literal check) and by varName+utility (utility check),\n  // keeping the FIRST referencing file — enough to locate the offender without\n  // drowning the report when one token is referenced across many files.\n  const seenVar = new Map<string, string>()\n  const seenUtility = new Map<string, string>()\n\n  for (const file of files) {\n    let text: string\n    try {\n      text = readFileSync(file, 'utf8')\n    } catch {\n      continue\n    }\n    const where = displayPath(file)\n\n    // Check 1 — literal var(--…) references.\n    for (const m of text.matchAll(/var\\(\\s*(--[a-z0-9-]+)/gi)) {\n      const name = m[1]\n      if (!name || isDefined(name) || seenVar.has(name)) continue\n      seenVar.set(name, where)\n    }\n\n    // Check 2 — known-dangerous Tailwind utility classes.\n    for (const u of utilityMatchers) {\n      if (isDefined(u.varName)) continue\n      const key = `${u.varName}::${u.suffix}`\n      if (seenUtility.has(key)) continue\n      u.re.lastIndex = 0\n      if (u.re.test(text)) seenUtility.set(key, `${where} (via ${firstUtilityHit(text, u.suffix)})`)\n    }\n  }\n\n  const missing: ThemeContractMiss[] = [\n    ...[...seenVar].map(([varName, referencedIn]) => ({ varName, referencedIn })),\n    ...[...seenUtility].map(([key, referencedIn]) => ({ varName: key.split('::')[0]!, referencedIn })),\n  ]\n  return { ok: missing.length === 0, missing }\n}\n\n/** The literal utility class (with prefix) first seen in `text` for `suffix`, for the report. */\nfunction firstUtilityHit(text: string, suffix: string): string {\n  const m = buildUtilityRe(suffix).exec(text)\n  return m?.[0] ?? `<utility>-${suffix}`\n}\n\n/** Path relative to cwd when it stays inside it, else the path as given — for readable reports. */\nfunction displayPath(file: string): string {\n  const rel = relative(process.cwd(), file)\n  return rel && !rel.startsWith('..') ? rel : file\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-Q4TKVF3L.js

@@ -0,0 +1,240 @@
+// src/preflight/index.ts
+var DEFAULT_TIMEOUT_MS = 1e4;
+function nowMs() {
+  return typeof performance !== "undefined" ? performance.now() : Date.now();
+}
+function isAbortLike(err) {
+  return err instanceof Error && (err.name === "TimeoutError" || err.name === "AbortError");
+}
+function sanitizeUpstreamMessage(input) {
+  const message = input instanceof Error ? input.message : String(input);
+  return message.replace(/Bearer\s+[^\s]+/gi, "Bearer [redacted]").replace(/\b(?:sk|pk|tc)[_-][A-Za-z0-9_-]{8,}\b/g, "[redacted-key]");
+}
+function snippet(body) {
+  const trimmed = body.trim();
+  if (!trimmed) return "";
+  const clipped = trimmed.length > 180 ? `${trimmed.slice(0, 180)}\u2026` : trimmed;
+  return `: ${sanitizeUpstreamMessage(clipped)}`;
+}
+async function runHttp(call) {
+  let response;
+  try {
+    response = await call.fetchImpl(call.url, {
+      method: call.method,
+      headers: call.headers,
+      body: call.body,
+      signal: AbortSignal.timeout(call.timeoutMs)
+    });
+  } catch (err) {
+    if (isAbortLike(err)) return { kind: "timeout", timeoutMs: call.timeoutMs };
+    return { kind: "network", message: sanitizeUpstreamMessage(err) };
+  }
+  let bodyText = "";
+  try {
+    bodyText = await response.text();
+  } catch {
+    bodyText = "";
+  }
+  return { kind: "status", status: response.status, bodyText };
+}
+function classifyAuthed(outcome, ctx) {
+  switch (outcome.kind) {
+    case "status": {
+      const { status, bodyText } = outcome;
+      if (status >= 200 && status < 300) return { ok: true, detail: `${status} OK` };
+      if (status === 401 || status === 403) {
+        return {
+          ok: false,
+          detail: `DEAD KEY \u2014 ${ctx.endpoint} returned ${status}; rotate ${ctx.keyLabel}`
+        };
+      }
+      if (status === 503) {
+        return {
+          ok: false,
+          detail: `UPSTREAM DOWN \u2014 ${ctx.endpoint} returned 503; ${ctx.keyLabel} still looks valid, retry or check the provider (do NOT rotate)`
+        };
+      }
+      return { ok: false, detail: `UNEXPECTED ${status} from ${ctx.endpoint}${snippet(bodyText)}` };
+    }
+    case "timeout":
+      return {
+        ok: false,
+        detail: `TIMEOUT after ${outcome.timeoutMs}ms reaching ${ctx.endpoint} \u2014 check ${ctx.urlLabel}`
+      };
+    case "network":
+      return {
+        ok: false,
+        detail: `UNREACHABLE ${ctx.endpoint} (${outcome.message}) \u2014 check ${ctx.urlLabel}`
+      };
+  }
+}
+function trimTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function routerChatProbe(config) {
+  const keyLabel = config.keySecret ?? "the router API key";
+  const urlLabel = config.urlSecret ?? "the router base URL";
+  return {
+    name: config.name ?? "router-chat",
+    critical: config.critical,
+    run: async () => {
+      const base = trimTrailingSlash(config.baseUrl);
+      const endpoint = `${base}/chat/completions`;
+      const outcome = await runHttp({
+        fetchImpl: config.fetchImpl ?? fetch,
+        url: endpoint,
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${config.apiKey}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({
+          model: config.model,
+          messages: [{ role: "user", content: "ping" }],
+          max_tokens: 1
+        }),
+        timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+      });
+      return classifyAuthed(outcome, { endpoint, keyLabel, urlLabel });
+    }
+  };
+}
+function sandboxAuthProbe(config) {
+  const keyLabel = config.keySecret ?? "the sandbox API key";
+  const urlLabel = config.urlSecret ?? "the sandbox base URL";
+  return {
+    name: config.name ?? "sandbox-auth",
+    critical: config.critical,
+    run: async () => {
+      const base = trimTrailingSlash(config.baseUrl);
+      const endpoint = `${base}/v1/sandboxes?limit=1`;
+      const outcome = await runHttp({
+        fetchImpl: config.fetchImpl ?? fetch,
+        url: endpoint,
+        method: "GET",
+        headers: { Authorization: `Bearer ${config.apiKey}` },
+        timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+      });
+      return classifyAuthed(outcome, { endpoint, keyLabel, urlLabel });
+    }
+  };
+}
+function statusMatches(status, expect) {
+  if (expect === void 0) return status >= 200 && status < 400;
+  if (Array.isArray(expect)) return expect.includes(status);
+  return status === expect;
+}
+function describeExpected(expect) {
+  if (expect === void 0) return "2xx/3xx";
+  if (Array.isArray(expect)) return expect.join(" or ");
+  return String(expect);
+}
+function httpHeadProbe(config) {
+  const urlLabel = config.urlSecret ?? `the URL for ${config.name}`;
+  return {
+    name: config.name,
+    critical: config.critical,
+    run: async () => {
+      const outcome = await runHttp({
+        fetchImpl: config.fetchImpl ?? fetch,
+        url: config.url,
+        method: "HEAD",
+        timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS
+      });
+      switch (outcome.kind) {
+        case "status": {
+          if (statusMatches(outcome.status, config.expectStatus)) {
+            return { ok: true, detail: `${outcome.status} OK` };
+          }
+          return {
+            ok: false,
+            detail: `UNEXPECTED ${outcome.status} from ${config.url} (expected ${describeExpected(config.expectStatus)}) \u2014 check ${urlLabel}`
+          };
+        }
+        case "timeout":
+          return {
+            ok: false,
+            detail: `TIMEOUT after ${outcome.timeoutMs}ms reaching ${config.url} \u2014 check ${urlLabel}`
+          };
+        case "network":
+          return {
+            ok: false,
+            detail: `UNREACHABLE ${config.url} (${outcome.message}) \u2014 check ${urlLabel}`
+          };
+      }
+    }
+  };
+}
+async function runOne(probe) {
+  const critical = probe.critical ?? true;
+  const start = nowMs();
+  try {
+    const result = await probe.run();
+    return {
+      name: probe.name,
+      ok: result.ok,
+      critical,
+      latencyMs: Math.round(nowMs() - start),
+      detail: result.detail
+    };
+  } catch (err) {
+    return {
+      name: probe.name,
+      ok: false,
+      critical,
+      latencyMs: Math.round(nowMs() - start),
+      detail: `probe threw: ${sanitizeUpstreamMessage(err)}`
+    };
+  }
+}
+async function runPreflight(probes) {
+  const start = nowMs();
+  const verdicts = await Promise.all(probes.map(runOne));
+  const failed = verdicts.filter((v) => !v.ok);
+  const criticalFailures = failed.filter((v) => v.critical).length;
+  return {
+    ok: criticalFailures === 0,
+    probes: verdicts,
+    passed: verdicts.length - failed.length,
+    failed: failed.length,
+    criticalFailures,
+    durationMs: Math.round(nowMs() - start)
+  };
+}
+function formatPreflightReport(report) {
+  const header = { status: "STATUS", name: "PROBE", latency: "LATENCY", detail: "DETAIL" };
+  const rows = report.probes.map((p) => ({
+    status: p.ok ? "PASS" : p.critical ? "FAIL" : "WARN",
+    name: p.name,
+    latency: `${p.latencyMs}ms`,
+    detail: p.detail ?? ""
+  }));
+  const statusW = Math.max(header.status.length, ...rows.map((r) => r.status.length));
+  const nameW = Math.max(header.name.length, ...rows.map((r) => r.name.length));
+  const latencyW = Math.max(header.latency.length, ...rows.map((r) => r.latency.length));
+  const line = (r) => `${r.status.padEnd(statusW)}  ${r.name.padEnd(nameW)}  ${r.latency.padStart(latencyW)}  ${r.detail}`.trimEnd();
+  const out = [
+    line(header),
+    `${"-".repeat(statusW)}  ${"-".repeat(nameW)}  ${"-".repeat(latencyW)}  ------`,
+    ...rows.map(line),
+    ""
+  ];
+  if (report.ok) {
+    const warn = report.failed > 0 ? ` (${report.failed} non-critical warning(s))` : "";
+    out.push(`Preflight PASSED \u2014 ${report.passed}/${report.probes.length} probe(s) live${warn}`);
+  } else {
+    const dead = report.probes.filter((p) => !p.ok && p.critical).map((p) => p.name).join(", ");
+    out.push(`Preflight FAILED \u2014 ${report.criticalFailures} critical probe(s) dead: ${dead}`);
+    out.push("Rotate the secret named in each FAIL row above, then redeploy.");
+  }
+  return out.join("\n");
+}
+
+export {
+  routerChatProbe,
+  sandboxAuthProbe,
+  httpHeadProbe,
+  runPreflight,
+  formatPreflightReport
+};
+//# sourceMappingURL=chunk-Q4TKVF3L.js.map

package/dist/chunk-Q4TKVF3L.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/preflight/index.ts"],"sourcesContent":["/**\n * `/preflight` — deploy-time secret-liveness probes.\n *\n * WHY THIS EXISTS: on 2026-07-15 four secrets were simultaneously dead in one\n * production day — a dead `SANDBOX_API_KEY`, a stale `SANDBOX_API_URL`, and a\n * dead LiteLLM router key + URL. Each one was present in `wrangler secret list`\n * (so nothing looked wrong) yet invalid against its live endpoint, and nothing\n * anywhere checked liveness. CI cannot hold production secrets, so this binds\n * at DEPLOY time instead: a product declares a handful of probes built from its\n * real env, the deploy workflow runs `agent-app-preflight` as a step, and a\n * dead secret fails the deploy with a message that names exactly which secret\n * to rotate.\n *\n * A probe is `{ name, run, critical? }`; `run()` returns `{ ok, detail? }`.\n * The standard builders (`routerChatProbe`, `sandboxAuthProbe`, `httpHeadProbe`)\n * each take explicit config — they read nothing global — so the same probe runs\n * identically in a deploy step, a test, or a local check. `runPreflight` fans\n * the probes out, times each, and folds them into a pass/fail report: any\n * failed CRITICAL probe fails the whole run (probes are critical by default).\n *\n * Server-only: probes carry live API keys and hit live endpoints. This subpath\n * must never reach a browser bundle.\n */\n\n/** One probe's outcome. `detail` should name the secret to rotate on failure. */\nexport interface PreflightProbeResult {\n  ok: boolean\n  detail?: string\n}\n\n/**\n * A liveness probe. `run` performs one cheap live call and maps the result to\n * `{ ok, detail }`. `critical` defaults to `true` — a failed critical probe\n * fails the whole preflight (and the deploy).\n */\nexport interface PreflightProbe {\n  name: string\n  run: () => Promise<PreflightProbeResult>\n  critical?: boolean\n}\n\n/** Per-probe verdict enriched with the resolved criticality and measured latency. */\nexport interface PreflightProbeVerdict {\n  name: string\n  ok: boolean\n  critical: boolean\n  latencyMs: number\n  detail?: string\n}\n\n/** Aggregate of every probe verdict plus the overall pass/fail decision. */\nexport interface PreflightReport {\n  /** `false` if any critical probe failed. */\n  ok: boolean\n  probes: PreflightProbeVerdict[]\n  passed: number\n  failed: number\n  criticalFailures: number\n  durationMs: number\n}\n\n/** Deploy-time deadline for a single probe. Cold upstreams are slow; a dead\n *  endpoint should still fail fast, so 10s is the ceiling, not the target. */\nconst DEFAULT_TIMEOUT_MS = 10_000\n\nfunction nowMs(): number {\n  return typeof performance !== 'undefined' ? performance.now() : Date.now()\n}\n\nfunction isAbortLike(err: unknown): boolean {\n  return err instanceof Error && (err.name === 'TimeoutError' || err.name === 'AbortError')\n}\n\n/** Strip bearer tokens / key material before an upstream string is surfaced in\n *  a report (deploy logs are not always private). */\nfunction sanitizeUpstreamMessage(input: unknown): string {\n  const message = input instanceof Error ? input.message : String(input)\n  return message\n    .replace(/Bearer\\s+[^\\s]+/gi, 'Bearer [redacted]')\n    .replace(/\\b(?:sk|pk|tc)[_-][A-Za-z0-9_-]{8,}\\b/g, '[redacted-key]')\n}\n\nfunction snippet(body: string): string {\n  const trimmed = body.trim()\n  if (!trimmed) return ''\n  const clipped = trimmed.length > 180 ? `${trimmed.slice(0, 180)}…` : trimmed\n  return `: ${sanitizeUpstreamMessage(clipped)}`\n}\n\ntype ProbeOutcome =\n  | { kind: 'status'; status: number; bodyText: string }\n  | { kind: 'timeout'; timeoutMs: number }\n  | { kind: 'network'; message: string }\n\ninterface HttpProbeCall {\n  fetchImpl: typeof fetch\n  url: string\n  method: string\n  headers?: Record<string, string>\n  body?: string\n  timeoutMs: number\n}\n\n/** One live HTTP call, folded to a probe outcome. Never throws: a timeout, a\n *  DNS/connection failure, and any thrown error all become an outcome so the\n *  probe can classify them into an actionable detail. */\nasync function runHttp(call: HttpProbeCall): Promise<ProbeOutcome> {\n  let response: Response\n  try {\n    response = await call.fetchImpl(call.url, {\n      method: call.method,\n      headers: call.headers,\n      body: call.body,\n      signal: AbortSignal.timeout(call.timeoutMs),\n    })\n  } catch (err) {\n    if (isAbortLike(err)) return { kind: 'timeout', timeoutMs: call.timeoutMs }\n    return { kind: 'network', message: sanitizeUpstreamMessage(err) }\n  }\n  let bodyText = ''\n  try {\n    bodyText = await response.text()\n  } catch {\n    bodyText = ''\n  }\n  return { kind: 'status', status: response.status, bodyText }\n}\n\ninterface AuthedClassifyContext {\n  /** Full endpoint reached, for the message. */\n  endpoint: string\n  /** How to name the API-key secret when the endpoint reports auth failure. */\n  keyLabel: string\n  /** How to name the URL secret when the endpoint is unreachable. */\n  urlLabel: string\n}\n\n/**\n * Shared classification for an authed liveness endpoint (router, sandbox):\n * 2xx → live; 401/403 → the KEY is dead, name it; 503 → the UPSTREAM is down,\n * the key still looks valid, don't rotate; timeout / unreachable → the URL is\n * likely stale, name it; anything else → an unexpected status with a snippet.\n */\nfunction classifyAuthed(outcome: ProbeOutcome, ctx: AuthedClassifyContext): PreflightProbeResult {\n  switch (outcome.kind) {\n    case 'status': {\n      const { status, bodyText } = outcome\n      if (status >= 200 && status < 300) return { ok: true, detail: `${status} OK` }\n      if (status === 401 || status === 403) {\n        return {\n          ok: false,\n          detail: `DEAD KEY — ${ctx.endpoint} returned ${status}; rotate ${ctx.keyLabel}`,\n        }\n      }\n      if (status === 503) {\n        return {\n          ok: false,\n          detail: `UPSTREAM DOWN — ${ctx.endpoint} returned 503; ${ctx.keyLabel} still looks valid, retry or check the provider (do NOT rotate)`,\n        }\n      }\n      return { ok: false, detail: `UNEXPECTED ${status} from ${ctx.endpoint}${snippet(bodyText)}` }\n    }\n    case 'timeout':\n      return {\n        ok: false,\n        detail: `TIMEOUT after ${outcome.timeoutMs}ms reaching ${ctx.endpoint} — check ${ctx.urlLabel}`,\n      }\n    case 'network':\n      return {\n        ok: false,\n        detail: `UNREACHABLE ${ctx.endpoint} (${outcome.message}) — check ${ctx.urlLabel}`,\n      }\n  }\n}\n\nfunction trimTrailingSlash(url: string): string {\n  return url.replace(/\\/+$/, '')\n}\n\n// --- Standard probe builders --------------------------------------------------\n\nexport interface RouterChatProbeConfig {\n  /** LLM router base URL (LiteLLM / OpenAI-compatible), e.g. `https://router…`. */\n  baseUrl: string\n  apiKey: string\n  /** A cheap model id available on the router. */\n  model: string\n  /** Probe name in the report. Default `'router-chat'`. */\n  name?: string\n  /** Default `true`. */\n  critical?: boolean\n  /** Env-var name of the API key, named verbatim in a dead-key failure. */\n  keySecret?: string\n  /** Env-var name of the base URL, named verbatim in an unreachable failure. */\n  urlSecret?: string\n  /** Per-probe deadline. Default 10s. */\n  timeoutMs?: number\n  /** Injection seam for tests; defaults to global `fetch`. */\n  fetchImpl?: typeof fetch\n}\n\n/**\n * Probe an OpenAI-compatible LLM router with one cheap `POST /chat/completions`\n * (`max_tokens: 1`). 200 → live; 401/403 → dead router key; 503 → upstream\n * provider down (key still valid); timeout / unreachable → check the router URL.\n */\nexport function routerChatProbe(config: RouterChatProbeConfig): PreflightProbe {\n  const keyLabel = config.keySecret ?? 'the router API key'\n  const urlLabel = config.urlSecret ?? 'the router base URL'\n  return {\n    name: config.name ?? 'router-chat',\n    critical: config.critical,\n    run: async () => {\n      const base = trimTrailingSlash(config.baseUrl)\n      const endpoint = `${base}/chat/completions`\n      const outcome = await runHttp({\n        fetchImpl: config.fetchImpl ?? fetch,\n        url: endpoint,\n        method: 'POST',\n        headers: {\n          Authorization: `Bearer ${config.apiKey}`,\n          'Content-Type': 'application/json',\n        },\n        body: JSON.stringify({\n          model: config.model,\n          messages: [{ role: 'user', content: 'ping' }],\n          max_tokens: 1,\n        }),\n        timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n      })\n      return classifyAuthed(outcome, { endpoint, keyLabel, urlLabel })\n    },\n  }\n}\n\nexport interface SandboxAuthProbeConfig {\n  /** Sandbox API base URL. */\n  baseUrl: string\n  apiKey: string\n  /** Probe name in the report. Default `'sandbox-auth'`. */\n  name?: string\n  /** Default `true`. */\n  critical?: boolean\n  /** Env-var name of the API key, named verbatim in a dead-key failure. */\n  keySecret?: string\n  /** Env-var name of the base URL, named verbatim in an unreachable failure. */\n  urlSecret?: string\n  /** Per-probe deadline. Default 10s. */\n  timeoutMs?: number\n  /** Injection seam for tests; defaults to global `fetch`. */\n  fetchImpl?: typeof fetch\n}\n\n/**\n * Probe the sandbox API with a cheap authed `GET /v1/sandboxes?limit=1`.\n * 200 → live; 401/403 → dead sandbox key; 503 → sandbox platform down (key\n * still valid); timeout / unreachable → check the sandbox URL.\n */\nexport function sandboxAuthProbe(config: SandboxAuthProbeConfig): PreflightProbe {\n  const keyLabel = config.keySecret ?? 'the sandbox API key'\n  const urlLabel = config.urlSecret ?? 'the sandbox base URL'\n  return {\n    name: config.name ?? 'sandbox-auth',\n    critical: config.critical,\n    run: async () => {\n      const base = trimTrailingSlash(config.baseUrl)\n      const endpoint = `${base}/v1/sandboxes?limit=1`\n      const outcome = await runHttp({\n        fetchImpl: config.fetchImpl ?? fetch,\n        url: endpoint,\n        method: 'GET',\n        headers: { Authorization: `Bearer ${config.apiKey}` },\n        timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n      })\n      return classifyAuthed(outcome, { endpoint, keyLabel, urlLabel })\n    },\n  }\n}\n\nexport interface HttpHeadProbeConfig {\n  /** Probe name in the report. */\n  name: string\n  /** URL to `HEAD`. */\n  url: string\n  /**\n   * Accepted status(es). A single number requires an exact match; an array\n   * requires membership. Omitted → any 2xx/3xx (the host is up and the path\n   * resolves) counts as live.\n   */\n  expectStatus?: number | number[]\n  /** Default `true`. */\n  critical?: boolean\n  /** Env-var name of the URL, named verbatim in a failure. */\n  urlSecret?: string\n  /** Per-probe deadline. Default 10s. */\n  timeoutMs?: number\n  /** Injection seam for tests; defaults to global `fetch`. */\n  fetchImpl?: typeof fetch\n}\n\nfunction statusMatches(status: number, expect?: number | number[]): boolean {\n  if (expect === undefined) return status >= 200 && status < 400\n  if (Array.isArray(expect)) return expect.includes(status)\n  return status === expect\n}\n\nfunction describeExpected(expect?: number | number[]): string {\n  if (expect === undefined) return '2xx/3xx'\n  if (Array.isArray(expect)) return expect.join(' or ')\n  return String(expect)\n}\n\n/**\n * Probe a plain reachability endpoint (e.g. a platform base URL) with a `HEAD`.\n * Confirms the URL is live and resolving — the class of failure behind a stale\n * platform URL that still sits in the secret store.\n */\nexport function httpHeadProbe(config: HttpHeadProbeConfig): PreflightProbe {\n  const urlLabel = config.urlSecret ?? `the URL for ${config.name}`\n  return {\n    name: config.name,\n    critical: config.critical,\n    run: async () => {\n      const outcome = await runHttp({\n        fetchImpl: config.fetchImpl ?? fetch,\n        url: config.url,\n        method: 'HEAD',\n        timeoutMs: config.timeoutMs ?? DEFAULT_TIMEOUT_MS,\n      })\n      switch (outcome.kind) {\n        case 'status': {\n          if (statusMatches(outcome.status, config.expectStatus)) {\n            return { ok: true, detail: `${outcome.status} OK` }\n          }\n          return {\n            ok: false,\n            detail: `UNEXPECTED ${outcome.status} from ${config.url} (expected ${describeExpected(config.expectStatus)}) — check ${urlLabel}`,\n          }\n        }\n        case 'timeout':\n          return {\n            ok: false,\n            detail: `TIMEOUT after ${outcome.timeoutMs}ms reaching ${config.url} — check ${urlLabel}`,\n          }\n        case 'network':\n          return {\n            ok: false,\n            detail: `UNREACHABLE ${config.url} (${outcome.message}) — check ${urlLabel}`,\n          }\n      }\n    },\n  }\n}\n\n// --- Runner + report ----------------------------------------------------------\n\nasync function runOne(probe: PreflightProbe): Promise<PreflightProbeVerdict> {\n  const critical = probe.critical ?? true\n  const start = nowMs()\n  try {\n    const result = await probe.run()\n    return {\n      name: probe.name,\n      ok: result.ok,\n      critical,\n      latencyMs: Math.round(nowMs() - start),\n      detail: result.detail,\n    }\n  } catch (err) {\n    return {\n      name: probe.name,\n      ok: false,\n      critical,\n      latencyMs: Math.round(nowMs() - start),\n      detail: `probe threw: ${sanitizeUpstreamMessage(err)}`,\n    }\n  }\n}\n\n/**\n * Run every probe (concurrently), time each, and fold into a report. The run\n * fails (`ok: false`) iff a critical probe fails; a failed non-critical probe\n * is a warning that does not block the deploy.\n */\nexport async function runPreflight(probes: PreflightProbe[]): Promise<PreflightReport> {\n  const start = nowMs()\n  const verdicts = await Promise.all(probes.map(runOne))\n  const failed = verdicts.filter((v) => !v.ok)\n  const criticalFailures = failed.filter((v) => v.critical).length\n  return {\n    ok: criticalFailures === 0,\n    probes: verdicts,\n    passed: verdicts.length - failed.length,\n    failed: failed.length,\n    criticalFailures,\n    durationMs: Math.round(nowMs() - start),\n  }\n}\n\ninterface FormatRow {\n  status: string\n  name: string\n  latency: string\n  detail: string\n}\n\n/** Render a report as an aligned, operator-readable table + verdict line. Pure\n *  (no I/O) so it is trivially testable and reusable by the bin. */\nexport function formatPreflightReport(report: PreflightReport): string {\n  const header: FormatRow = { status: 'STATUS', name: 'PROBE', latency: 'LATENCY', detail: 'DETAIL' }\n  const rows: FormatRow[] = report.probes.map((p) => ({\n    status: p.ok ? 'PASS' : p.critical ? 'FAIL' : 'WARN',\n    name: p.name,\n    latency: `${p.latencyMs}ms`,\n    detail: p.detail ?? '',\n  }))\n  const statusW = Math.max(header.status.length, ...rows.map((r) => r.status.length))\n  const nameW = Math.max(header.name.length, ...rows.map((r) => r.name.length))\n  const latencyW = Math.max(header.latency.length, ...rows.map((r) => r.latency.length))\n  const line = (r: FormatRow): string =>\n    `${r.status.padEnd(statusW)}  ${r.name.padEnd(nameW)}  ${r.latency.padStart(latencyW)}  ${r.detail}`.trimEnd()\n\n  const out: string[] = [\n    line(header),\n    `${'-'.repeat(statusW)}  ${'-'.repeat(nameW)}  ${'-'.repeat(latencyW)}  ------`,\n    ...rows.map(line),\n    '',\n  ]\n  if (report.ok) {\n    const warn = report.failed > 0 ? ` (${report.failed} non-critical warning(s))` : ''\n    out.push(`Preflight PASSED — ${report.passed}/${report.probes.length} probe(s) live${warn}`)\n  } else {\n    const dead = report.probes\n      .filter((p) => !p.ok && p.critical)\n      .map((p) => p.name)\n      .join(', ')\n    out.push(`Preflight FAILED — ${report.criticalFailures} critical probe(s) dead: ${dead}`)\n    out.push('Rotate the secret named in each FAIL row above, then redeploy.')\n  }\n  return out.join('\\n')\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -14,6 +14,7 @@ export { DEFAULT_HARNESS, Harness, KNOWN_HARNESSES, ResolveSessionHarnessInput,
 export { AgentAppConfig, AgentIdentityConfig, AgentIntegrationsConfig, AgentKnowledgeConfig, AgentTaxonomyConfig, AgentUiConfig, KnowledgeLoopConfig, KnowledgeSourceSpec, agentAppConfigJsonSchema, defineAgentApp } from './config/index.js';
 export { D1Like, D1PreparedLike, DrizzleColumnLike, DrizzleSqliteCoreLike, PRESET_MIGRATION_SQL, PRESET_TABLES, PresetBillingOptions, PresetKnowledgeAccessorOptions, PresetToolHandlerOptions, VaultKv, createD1KnowledgeStateAccessor, createPresetDrizzleSchema, createPresetFieldCrypto, createPresetToolHandlers, createPresetWorkspaceKeyManager, createPresetWorkspaceKeyStore } from './preset-cloudflare/index.js';
 export { KeyCrypto, KeyProvisioner, PlanLimit, PlatformBalanceInfo, PlatformBalanceManager, PlatformBalanceManagerOptions, PlatformBillingClient, PlatformIdentity, PlatformProductUsage, SharedBillingState, TcloudKeyClient, WorkspaceKeyManager, WorkspaceKeyManagerOptions, WorkspaceKeyRecord, WorkspaceKeyStore, WorkspaceModelKeyUsage, createPlatformBalanceManager, createTcloudKeyProvisioner, createWorkspaceKeyManager } from './billing/index.js';
+export { HttpHeadProbeConfig, PreflightProbe, PreflightProbeResult, PreflightProbeVerdict, PreflightReport, RouterChatProbeConfig, SandboxAuthProbeConfig, formatPreflightReport, httpHeadProbe, routerChatProbe, runPreflight, sandboxAuthProbe } from './preflight/index.js';
 export { B as BULK_DELETE_MAX_THREADS, C as ChatStoreInputError, t as threadTitleFromMessage } from './core-7qIM7svy.js';
 export { C as ChatFilePart, a as ChatImagePart, b as ChatInteractionPart, c as ChatMessagePart, d as ChatNoticePart, e as ChatPartTime, f as ChatReasoningPart, g as ChatStepFinishPart, h as ChatStepStartPart, i as ChatSubtaskPart, j as ChatTextPart, k as ChatToolPart, l as ChatToolState, m as ChatToolStatus, n as ChatUsageTokens, S as StorableHarnessPartKind, o as isChatInteractionPart, p as isChatStepFinishPart, q as isChatTextPart, r as isChatToolPart, t as toChatMessageParts } from './parts-BcbitSNp.js';
 export { DeriveKeyOptions, createFieldCrypto, decodeHexKey, decryptAesGcm, decryptBytes, decryptWithKey, deriveKey, encryptAesGcm, encryptBytes, encryptWithKey } from './crypto/index.js';
@@ -28,6 +29,7 @@ export { CookieOptions, JsonObject, KvLike, RateLimitResult, RequestContext, Sec
 export { BuildRedactedDocumentOptions, DEFAULT_REDACTION_PATTERNS, RedactForIngestionOptions, RedactedDocSegment, RedactedDocument, RedactionPattern, RedactionSpan, RevealResult, RevealSpanOptions, buildRedactedDocument, detectSpans, maskSpans, redactForIngestion, revealSpan } from './redact/index.js';
 export { ApprovalEvent, ApprovalEventSchema, AssetContentMap, AssetFormat, AssetSpec, AssetStatus, AssetVariant, BrandTokens, BrandTokensSchema, ConversionMetrics, ConversionMetricsSchema, CopyContent, CopyContentSchema, CopyPlatform, EmailBodySection, EmailContent, EmailContentSchema, EmailCtaSection, EmailDividerSection, EmailFeatureSection, EmailHeroSection, EmailSection, EmailTestimonialSection, ImageBackground, ImageContent, ImageContentSchema, ImageImageLayer, ImageLayer, ImageLayerType, ImageLogoLayer, ImageShapeLayer, ImageSlide, ImageTextLayer, VideoCaption, VideoContent, VideoContentSchema, VideoCountdownScene, VideoImageRevealScene, VideoScene, VideoSlideScene, VideoTextAnimationScene, parseAssetSpec, safeParseAssetSpec } from './assets/index.js';
 export { AgentAppTheme, CanvasRenderPalette, darkTheme, lightTheme, themeColor, themeToCssVars } from './theme/index.js';
+export { ThemeContractMiss, ThemeContractOptions, ThemeContractResult, checkThemeContract } from './theme-contract/index.js';
 export { DistributionSummary, LoopTraceEventLike, MissionFlowStep, MissionTraceContext, StepSpanContext, TimedEvent, buildFlowTrace, childSpanContext, composeMissionFlowTrace, createMissionTraceContext, delegationActivityToFlowSpans, loopTraceEventsToFlowSpans, renderHistogram, renderWaterfall, stepActivityFlowTrace, summarize, timedEventsFromLines, traceEnv } from './trace/index.js';
 export { M as MIN_SEQUENCE_CLIP_FRAMES, N as NewSequenceClip, a as NewSequenceDecision, b as NewSequenceTrack, S as SequenceClip, c as SequenceClipMedia, d as SequenceClipPatch, e as SequenceDecision, f as SequenceExportFormat, g as SequenceExportRecord, h as SequenceExportStatus, i as SequenceFrameSnapshot, j as SequenceMediaKind, k as SequenceMeta, l as SequenceStatus, m as SequenceStore, n as SequenceStoreScope, o as SequenceTimeline, p as SequenceTrack, q as SequenceTrackKind, T as TimelineClipBounds, r as TimelineInterval, s as assertClipFitsSequence, t as chooseCaptionPlacement, u as clampClipDuration, v as clampClipStart, w as formatSeconds, x as formatTimecode, y as framesToSeconds, z as secondsToFrames, A as snapshotFrame, B as trackIntervals } from './store-gckrNq-g.js';
 export { A as AddCaptionOperation, C as CaptionTargetResolution, a as CreateTrackOperation, D as DeleteClipOperation, E as ExtendSequenceOperation, M as MoveClipOperation, P as PlaceClipOperation, Q as QueueExportOperation, S as SEQUENCE_OPERATION_TYPES, b as SequenceApplyResult, c as SequenceOperation, d as SequenceOperationContext, e as SequenceOperationType, f as SequencePlan, g as SetClipDisabledOperation, h as SetClipTextOperation, i as SplitClipOperation, T as TrimClipOperation, j as applySequenceOperation, k as applySequenceOperations, l as assertSequenceMediaUrl, m as captionTrackNameForLanguage, n as lastClipEndFrame, p as parseSequenceOperations, r as resolveCaptionPlacement, o as resolveCaptionTarget, q as resolvePlaceClipTrack, v as validateAddCaption, s as validateCreateTrack, t as validateDeleteClip, u as validateExtendSequence, w as validateMoveClip, x as validatePlaceClip, y as validateQueueExport, z as validateSequenceOperation, B as validateSequenceOperations, F as validateSetClipDisabled, G as validateSetClipText, H as validateSplitClip, I as validateTrimClip } from './apply-Gk4raT2j.js';

package/dist/index.js

@@ -1,4 +1,63 @@
+import {
+  checkThemeContract
+} from "./chunk-NYATNLRK.js";
 import "./chunk-UAKFCMWK.js";
+import {
+  DEFAULT_SEQUENCES_MCP_DESCRIPTION,
+  MAX_CAPTION_BATCH,
+  SEQUENCE_EXPORT_FORMATS,
+  SEQUENCE_MCP_TOOLS,
+  SEQUENCE_MEDIA_KINDS,
+  SEQUENCE_OPERATION_TYPES,
+  SEQUENCE_TRACK_KINDS,
+  applySequenceOperation,
+  applySequenceOperations,
+  assertSequenceMediaUrl,
+  buildCaptionChunks,
+  buildContactSheetManifest,
+  buildEdl,
+  buildOtio,
+  buildSequencesMcpServerEntry,
+  buildSrt,
+  buildVtt,
+  captionCoverage,
+  captionTrackNameForLanguage,
+  createSequencesMcpHandler,
+  findSequenceMcpTool,
+  lastClipEndFrame,
+  normalizeLanguageTag,
+  parseSequenceOperations,
+  planLanguageFanout,
+  resolveCaptionPlacement,
+  resolveCaptionTarget,
+  resolvePlaceClipTrack,
+  validateAddCaption,
+  validateCreateTrack,
+  validateDeleteClip,
+  validateExtendSequence,
+  validateMoveClip,
+  validatePlaceClip,
+  validateQueueExport,
+  validateSequenceOperation,
+  validateSequenceOperations,
+  validateSetClipDisabled,
+  validateSetClipText,
+  validateSplitClip,
+  validateTrimClip
+} from "./chunk-NEOV2NQ3.js";
+import {
+  MIN_SEQUENCE_CLIP_FRAMES,
+  assertClipFitsSequence,
+  chooseCaptionPlacement,
+  clampClipDuration,
+  clampClipStart,
+  formatSeconds,
+  formatTimecode,
+  framesToSeconds,
+  secondsToFrames,
+  snapshotFrame,
+  trackIntervals
+} from "./chunk-ZYBWGSAZ.js";
 import {
   CANVAS_ELEMENT_KINDS,
   CANVAS_MCP_TOOLS,
@@ -83,61 +142,10 @@ import {
   safeParseAssetSpec
 } from "./chunk-5PTGEJZL.js";
 import {
-  DEFAULT_SEQUENCES_MCP_DESCRIPTION,
-  MAX_CAPTION_BATCH,
-  SEQUENCE_EXPORT_FORMATS,
-  SEQUENCE_MCP_TOOLS,
-  SEQUENCE_MEDIA_KINDS,
-  SEQUENCE_OPERATION_TYPES,
-  SEQUENCE_TRACK_KINDS,
-  applySequenceOperation,
-  applySequenceOperations,
-  assertSequenceMediaUrl,
-  buildCaptionChunks,
-  buildContactSheetManifest,
-  buildEdl,
-  buildOtio,
-  buildSequencesMcpServerEntry,
-  buildSrt,
-  buildVtt,
-  captionCoverage,
-  captionTrackNameForLanguage,
-  createSequencesMcpHandler,
-  findSequenceMcpTool,
-  lastClipEndFrame,
-  normalizeLanguageTag,
-  parseSequenceOperations,
-  planLanguageFanout,
-  resolveCaptionPlacement,
-  resolveCaptionTarget,
-  resolvePlaceClipTrack,
-  validateAddCaption,
-  validateCreateTrack,
-  validateDeleteClip,
-  validateExtendSequence,
-  validateMoveClip,
-  validatePlaceClip,
-  validateQueueExport,
-  validateSequenceOperation,
-  validateSequenceOperations,
-  validateSetClipDisabled,
-  validateSetClipText,
-  validateSplitClip,
-  validateTrimClip
-} from "./chunk-NEOV2NQ3.js";
-import {
-  MIN_SEQUENCE_CLIP_FRAMES,
-  assertClipFitsSequence,
-  chooseCaptionPlacement,
-  clampClipDuration,
-  clampClipStart,
-  formatSeconds,
-  formatTimecode,
-  framesToSeconds,
-  secondsToFrames,
-  snapshotFrame,
-  trackIntervals
-} from "./chunk-ZYBWGSAZ.js";
+  HubExecClient,
+  invokeIntegrationHub,
+  resolveIntegrationAction
+} from "./chunk-L2TG5DBW.js";
 import "./chunk-7LNGJDNA.js";
 import {
   DEFAULT_MISSION_STEP_KINDS,
@@ -187,6 +195,13 @@ import {
   createTcloudKeyProvisioner,
   createWorkspaceKeyManager
 } from "./chunk-G3HCU7TA.js";
+import {
+  formatPreflightReport,
+  httpHeadProbe,
+  routerChatProbe,
+  runPreflight,
+  sandboxAuthProbe
+} from "./chunk-Q4TKVF3L.js";
 import {
   BULK_DELETE_MAX_THREADS,
   ChatStoreInputError,
@@ -277,11 +292,6 @@ import {
   resolveToolId,
   resolveToolName
 } from "./chunk-ATRJULKZ.js";
-import {
-  HubExecClient,
-  invokeIntegrationHub,
-  resolveIntegrationAction
-} from "./chunk-L2TG5DBW.js";
 import {
   createKnowledgeLoop,
   createReviewerDecider,
@@ -550,6 +560,7 @@ export {
   captionCoverage,
   captionTrackNameForLanguage,
   checkRateLimit,
+  checkThemeContract,
   childSpanContext,
   chooseCaptionPlacement,
   clampClipDuration,
@@ -642,12 +653,14 @@ export {
   findPreset,
   findSequenceMcpTool,
   flattenHistory,
+  formatPreflightReport,
   formatSeconds,
   formatTimecode,
   framesToSeconds,
   getClient,
   getPartKey,
   handleAppToolRequest,
+  httpHeadProbe,
   instantiateTemplate,
   interactionFromWireRequest,
   interactionPartKey,
@@ -742,10 +755,13 @@ export {
   restrictTaxonomy,
   revealSpan,
   reviewCandidate,
+  routerChatProbe,
   runToolLoop as runAppToolLoop,
+  runPreflight,
   runSandboxPrompt,
   runSandboxToolPathSetup,
   safeParseAssetSpec,
+  sandboxAuthProbe,
   sandboxToolBinDir,
   sandboxToolPath,
   sandboxToolRootDir,

package/dist/preflight/index.d.ts

@@ -0,0 +1,141 @@
+/**
+ * `/preflight` — deploy-time secret-liveness probes.
+ *
+ * WHY THIS EXISTS: on 2026-07-15 four secrets were simultaneously dead in one
+ * production day — a dead `SANDBOX_API_KEY`, a stale `SANDBOX_API_URL`, and a
+ * dead LiteLLM router key + URL. Each one was present in `wrangler secret list`
+ * (so nothing looked wrong) yet invalid against its live endpoint, and nothing
+ * anywhere checked liveness. CI cannot hold production secrets, so this binds
+ * at DEPLOY time instead: a product declares a handful of probes built from its
+ * real env, the deploy workflow runs `agent-app-preflight` as a step, and a
+ * dead secret fails the deploy with a message that names exactly which secret
+ * to rotate.
+ *
+ * A probe is `{ name, run, critical? }`; `run()` returns `{ ok, detail? }`.
+ * The standard builders (`routerChatProbe`, `sandboxAuthProbe`, `httpHeadProbe`)
+ * each take explicit config — they read nothing global — so the same probe runs
+ * identically in a deploy step, a test, or a local check. `runPreflight` fans
+ * the probes out, times each, and folds them into a pass/fail report: any
+ * failed CRITICAL probe fails the whole run (probes are critical by default).
+ *
+ * Server-only: probes carry live API keys and hit live endpoints. This subpath
+ * must never reach a browser bundle.
+ */
+/** One probe's outcome. `detail` should name the secret to rotate on failure. */
+interface PreflightProbeResult {
+    ok: boolean;
+    detail?: string;
+}
+/**
+ * A liveness probe. `run` performs one cheap live call and maps the result to
+ * `{ ok, detail }`. `critical` defaults to `true` — a failed critical probe
+ * fails the whole preflight (and the deploy).
+ */
+interface PreflightProbe {
+    name: string;
+    run: () => Promise<PreflightProbeResult>;
+    critical?: boolean;
+}
+/** Per-probe verdict enriched with the resolved criticality and measured latency. */
+interface PreflightProbeVerdict {
+    name: string;
+    ok: boolean;
+    critical: boolean;
+    latencyMs: number;
+    detail?: string;
+}
+/** Aggregate of every probe verdict plus the overall pass/fail decision. */
+interface PreflightReport {
+    /** `false` if any critical probe failed. */
+    ok: boolean;
+    probes: PreflightProbeVerdict[];
+    passed: number;
+    failed: number;
+    criticalFailures: number;
+    durationMs: number;
+}
+interface RouterChatProbeConfig {
+    /** LLM router base URL (LiteLLM / OpenAI-compatible), e.g. `https://router…`. */
+    baseUrl: string;
+    apiKey: string;
+    /** A cheap model id available on the router. */
+    model: string;
+    /** Probe name in the report. Default `'router-chat'`. */
+    name?: string;
+    /** Default `true`. */
+    critical?: boolean;
+    /** Env-var name of the API key, named verbatim in a dead-key failure. */
+    keySecret?: string;
+    /** Env-var name of the base URL, named verbatim in an unreachable failure. */
+    urlSecret?: string;
+    /** Per-probe deadline. Default 10s. */
+    timeoutMs?: number;
+    /** Injection seam for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Probe an OpenAI-compatible LLM router with one cheap `POST /chat/completions`
+ * (`max_tokens: 1`). 200 → live; 401/403 → dead router key; 503 → upstream
+ * provider down (key still valid); timeout / unreachable → check the router URL.
+ */
+declare function routerChatProbe(config: RouterChatProbeConfig): PreflightProbe;
+interface SandboxAuthProbeConfig {
+    /** Sandbox API base URL. */
+    baseUrl: string;
+    apiKey: string;
+    /** Probe name in the report. Default `'sandbox-auth'`. */
+    name?: string;
+    /** Default `true`. */
+    critical?: boolean;
+    /** Env-var name of the API key, named verbatim in a dead-key failure. */
+    keySecret?: string;
+    /** Env-var name of the base URL, named verbatim in an unreachable failure. */
+    urlSecret?: string;
+    /** Per-probe deadline. Default 10s. */
+    timeoutMs?: number;
+    /** Injection seam for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Probe the sandbox API with a cheap authed `GET /v1/sandboxes?limit=1`.
+ * 200 → live; 401/403 → dead sandbox key; 503 → sandbox platform down (key
+ * still valid); timeout / unreachable → check the sandbox URL.
+ */
+declare function sandboxAuthProbe(config: SandboxAuthProbeConfig): PreflightProbe;
+interface HttpHeadProbeConfig {
+    /** Probe name in the report. */
+    name: string;
+    /** URL to `HEAD`. */
+    url: string;
+    /**
+     * Accepted status(es). A single number requires an exact match; an array
+     * requires membership. Omitted → any 2xx/3xx (the host is up and the path
+     * resolves) counts as live.
+     */
+    expectStatus?: number | number[];
+    /** Default `true`. */
+    critical?: boolean;
+    /** Env-var name of the URL, named verbatim in a failure. */
+    urlSecret?: string;
+    /** Per-probe deadline. Default 10s. */
+    timeoutMs?: number;
+    /** Injection seam for tests; defaults to global `fetch`. */
+    fetchImpl?: typeof fetch;
+}
+/**
+ * Probe a plain reachability endpoint (e.g. a platform base URL) with a `HEAD`.
+ * Confirms the URL is live and resolving — the class of failure behind a stale
+ * platform URL that still sits in the secret store.
+ */
+declare function httpHeadProbe(config: HttpHeadProbeConfig): PreflightProbe;
+/**
+ * Run every probe (concurrently), time each, and fold into a report. The run
+ * fails (`ok: false`) iff a critical probe fails; a failed non-critical probe
+ * is a warning that does not block the deploy.
+ */
+declare function runPreflight(probes: PreflightProbe[]): Promise<PreflightReport>;
+/** Render a report as an aligned, operator-readable table + verdict line. Pure
+ *  (no I/O) so it is trivially testable and reusable by the bin. */
+declare function formatPreflightReport(report: PreflightReport): string;
+
+export { type HttpHeadProbeConfig, type PreflightProbe, type PreflightProbeResult, type PreflightProbeVerdict, type PreflightReport, type RouterChatProbeConfig, type SandboxAuthProbeConfig, formatPreflightReport, httpHeadProbe, routerChatProbe, runPreflight, sandboxAuthProbe };

package/dist/preflight/index.js

@@ -0,0 +1,15 @@
+import {
+  formatPreflightReport,
+  httpHeadProbe,
+  routerChatProbe,
+  runPreflight,
+  sandboxAuthProbe
+} from "../chunk-Q4TKVF3L.js";
+export {
+  formatPreflightReport,
+  httpHeadProbe,
+  routerChatProbe,
+  runPreflight,
+  sandboxAuthProbe
+};
+//# sourceMappingURL=index.js.map

package/dist/preflight/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/teams-react/index.js

@@ -1,12 +1,12 @@
-import {
-  MembersPanel
-} from "../chunk-GNL3MG5J.js";
 import {
   InvitationsPanel
 } from "../chunk-7C64WKAH.js";
 import {
   InviteAcceptPage
 } from "../chunk-VCPZ3HTN.js";
+import {
+  MembersPanel
+} from "../chunk-GNL3MG5J.js";
 import "../chunk-63CE7FEZ.js";
 export {
   InvitationsPanel,

package/dist/theme-contract/cli.d.ts

@@ -0,0 +1 @@
+#!/usr/bin/env node

package/dist/theme-contract/cli.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+import {
+  checkThemeContract
+} from "../chunk-NYATNLRK.js";
+
+// src/theme-contract/cli.ts
+function parseArgs(argv) {
+  const out = { srcDirs: [], extraCss: [], allow: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i];
+    const take = () => {
+      const v = argv[++i];
+      if (v === void 0) fail(`${flag} needs a value`);
+      return v;
+    };
+    switch (flag) {
+      case "--src":
+        out.srcDirs.push(take());
+        break;
+      case "--extra-css":
+        out.extraCss.push(take());
+        break;
+      case "--allow":
+        out.allow.push(take());
+        break;
+      case "--tokens":
+        out.tokens = take();
+        break;
+      case "-h":
+      case "--help":
+        printUsage();
+        process.exit(0);
+        break;
+      default:
+        fail(`unknown argument: ${flag}`);
+    }
+  }
+  return out;
+}
+function printUsage() {
+  process.stdout.write(
+    "Usage: agent-app-theme-check --src <dir> [--src <dir>\u2026] [--extra-css <file>\u2026] [--tokens <file>] [--allow <--var>\u2026]\n"
+  );
+}
+function fail(msg) {
+  process.stderr.write(`agent-app-theme-check: ${msg}
+`);
+  printUsage();
+  process.exit(2);
+}
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.srcDirs.length === 0) fail("at least one --src <dir> is required");
+  const { ok, missing } = checkThemeContract({
+    srcDirs: args.srcDirs,
+    tokensCss: args.tokens,
+    extraTokensCss: args.extraCss,
+    allowlist: args.allow
+  });
+  if (ok) {
+    process.stdout.write(`theme contract OK \u2014 every referenced token is defined (${args.srcDirs.join(", ")})
+`);
+    process.exit(0);
+  }
+  process.stderr.write(
+    `theme contract FAILED \u2014 ${missing.length} token reference(s) resolve to nothing (surface ships transparent):
+
+`
+  );
+  for (const m of missing) process.stderr.write(`  ${m.varName}
+    referenced in ${m.referencedIn}
+`);
+  process.stderr.write(
+    "\nDefine these in your tokens.css (or `import '@tangle-network/agent-app/styles'`),\npass the defining CSS via --extra-css, or suppress a deliberately-external one with --allow.\n"
+  );
+  process.exit(1);
+}
+main();
+//# sourceMappingURL=cli.js.map

package/dist/theme-contract/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/theme-contract/cli.ts"],"sourcesContent":["#!/usr/bin/env node\n/**\n * agent-app-theme-check — CI guard against the invisible-surface incident class.\n *\n * A consumer app runs this over its own source; it fails (exit 1) when a\n * component references a theme token — `var(--popover)` or a preset-mapped\n * utility like `bg-surface-container-high` — that the app's shipped CSS never\n * defines, which would paint that surface transparent with no error at runtime.\n *\n *   agent-app-theme-check --src src --src packages/ui/src \\\n *     --extra-css src/app-tokens.css\n *\n * Flags (all repeatable except --tokens):\n *   --src <dir>         source dir to scan for token references (required, 1+)\n *   --extra-css <file>  extra CSS whose --name: definitions also count as defined\n *   --tokens <file>     override the base tokens.css (defaults to the one\n *                       agent-app ships as `@tangle-network/agent-app/styles`)\n *   --allow <--var>     suppress a token name from the missing report\n *\n * Wire it as a CI step: `\"theme-check\": \"agent-app-theme-check --src src\"`.\n */\n\nimport { checkThemeContract } from './index'\n\ninterface ParsedArgs {\n  srcDirs: string[]\n  extraCss: string[]\n  allow: string[]\n  tokens?: string\n}\n\nfunction parseArgs(argv: string[]): ParsedArgs {\n  const out: ParsedArgs = { srcDirs: [], extraCss: [], allow: [] }\n  for (let i = 0; i < argv.length; i++) {\n    const flag = argv[i]\n    const take = () => {\n      const v = argv[++i]\n      if (v === undefined) fail(`${flag} needs a value`)\n      return v!\n    }\n    switch (flag) {\n      case '--src':\n        out.srcDirs.push(take())\n        break\n      case '--extra-css':\n        out.extraCss.push(take())\n        break\n      case '--allow':\n        out.allow.push(take())\n        break\n      case '--tokens':\n        out.tokens = take()\n        break\n      case '-h':\n      case '--help':\n        printUsage()\n        process.exit(0)\n        break\n      default:\n        fail(`unknown argument: ${flag}`)\n    }\n  }\n  return out\n}\n\nfunction printUsage(): void {\n  process.stdout.write(\n    'Usage: agent-app-theme-check --src <dir> [--src <dir>…] ' +\n      '[--extra-css <file>…] [--tokens <file>] [--allow <--var>…]\\n',\n  )\n}\n\nfunction fail(msg: string): never {\n  process.stderr.write(`agent-app-theme-check: ${msg}\\n`)\n  printUsage()\n  process.exit(2)\n}\n\nfunction main(): void {\n  const args = parseArgs(process.argv.slice(2))\n  if (args.srcDirs.length === 0) fail('at least one --src <dir> is required')\n\n  const { ok, missing } = checkThemeContract({\n    srcDirs: args.srcDirs,\n    tokensCss: args.tokens,\n    extraTokensCss: args.extraCss,\n    allowlist: args.allow,\n  })\n\n  if (ok) {\n    process.stdout.write(`theme contract OK — every referenced token is defined (${args.srcDirs.join(', ')})\\n`)\n    process.exit(0)\n  }\n\n  process.stderr.write(\n    `theme contract FAILED — ${missing.length} token reference(s) resolve to nothing (surface ships transparent):\\n\\n`,\n  )\n  for (const m of missing) process.stderr.write(`  ${m.varName}\\n    referenced in ${m.referencedIn}\\n`)\n  process.stderr.write(\n    '\\nDefine these in your tokens.css (or `import \\'@tangle-network/agent-app/styles\\'`),\\n' +\n      'pass the defining CSS via --extra-css, or suppress a deliberately-external one with --allow.\\n',\n  )\n  process.exit(1)\n}\n\nmain()\n"],"mappings":";;;;;;AA+BA,SAAS,UAAU,MAA4B;AAC7C,QAAM,MAAkB,EAAE,SAAS,CAAC,GAAG,UAAU,CAAC,GAAG,OAAO,CAAC,EAAE;AAC/D,WAAS,IAAI,GAAG,IAAI,KAAK,QAAQ,KAAK;AACpC,UAAM,OAAO,KAAK,CAAC;AACnB,UAAM,OAAO,MAAM;AACjB,YAAM,IAAI,KAAK,EAAE,CAAC;AAClB,UAAI,MAAM,OAAW,MAAK,GAAG,IAAI,gBAAgB;AACjD,aAAO;AAAA,IACT;AACA,YAAQ,MAAM;AAAA,MACZ,KAAK;AACH,YAAI,QAAQ,KAAK,KAAK,CAAC;AACvB;AAAA,MACF,KAAK;AACH,YAAI,SAAS,KAAK,KAAK,CAAC;AACxB;AAAA,MACF,KAAK;AACH,YAAI,MAAM,KAAK,KAAK,CAAC;AACrB;AAAA,MACF,KAAK;AACH,YAAI,SAAS,KAAK;AAClB;AAAA,MACF,KAAK;AAAA,MACL,KAAK;AACH,mBAAW;AACX,gBAAQ,KAAK,CAAC;AACd;AAAA,MACF;AACE,aAAK,qBAAqB,IAAI,EAAE;AAAA,IACpC;AAAA,EACF;AACA,SAAO;AACT;AAEA,SAAS,aAAmB;AAC1B,UAAQ,OAAO;AAAA,IACb;AAAA,EAEF;AACF;AAEA,SAAS,KAAK,KAAoB;AAChC,UAAQ,OAAO,MAAM,0BAA0B,GAAG;AAAA,CAAI;AACtD,aAAW;AACX,UAAQ,KAAK,CAAC;AAChB;AAEA,SAAS,OAAa;AACpB,QAAM,OAAO,UAAU,QAAQ,KAAK,MAAM,CAAC,CAAC;AAC5C,MAAI,KAAK,QAAQ,WAAW,EAAG,MAAK,sCAAsC;AAE1E,QAAM,EAAE,IAAI,QAAQ,IAAI,mBAAmB;AAAA,IACzC,SAAS,KAAK;AAAA,IACd,WAAW,KAAK;AAAA,IAChB,gBAAgB,KAAK;AAAA,IACrB,WAAW,KAAK;AAAA,EAClB,CAAC;AAED,MAAI,IAAI;AACN,YAAQ,OAAO,MAAM,+DAA0D,KAAK,QAAQ,KAAK,IAAI,CAAC;AAAA,CAAK;AAC3G,YAAQ,KAAK,CAAC;AAAA,EAChB;AAEA,UAAQ,OAAO;AAAA,IACb,gCAA2B,QAAQ,MAAM;AAAA;AAAA;AAAA,EAC3C;AACA,aAAW,KAAK,QAAS,SAAQ,OAAO,MAAM,KAAK,EAAE,OAAO;AAAA,oBAAuB,EAAE,YAAY;AAAA,CAAI;AACrG,UAAQ,OAAO;AAAA,IACb;AAAA,EAEF;AACA,UAAQ,KAAK,CAAC;AAChB;AAEA,KAAK;","names":[]}

package/dist/theme-contract/index.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Exportable theme-token contract checker — the incident guard for the
+ * invisible-popover class of bugs.
+ *
+ * The failure mode (tax-agent's transparent model dropdown; the whole
+ * `bg-surface-container-*` family): a consumer app ships a component that
+ * references a theme token — either as `var(--popover)` or as a Tailwind class
+ * like `bg-surface-container-high` that the agent-app preset maps to
+ * `hsl(var(--popover))` — but the app's OWN build never emits that custom
+ * property (it forgot `import '@tangle-network/agent-app/styles'`, or dropped a
+ * token in its local tokens.css). CSS resolves the missing var to nothing, the
+ * surface paints transparent, and NOTHING errors. It ships invisible.
+ *
+ * `tests/theme/tokens-contract.test.ts` guards agent-app's OWN components. This
+ * module lifts that walking logic into a function every CONSUMER app can run
+ * against ITS OWN source in CI, comparing references to the tokens.css agent-app
+ * ships plus any extra CSS the app defines.
+ *
+ * ── What each check covers (scope is deliberately honest) ────────────────────
+ *
+ *  1. var(--…) check — COMPLETE. Every `var(--name)` literal in the scanned
+ *     source (inline styles, `bg-[var(--name)]` arbitrary Tailwind values, CSS
+ *     template strings) is matched and compared against the defined token set.
+ *     This is exact: a `var(--x)` reference is unambiguous. It is a raw-text
+ *     scan (no AST), so a `var(--x)` written inside a comment or string literal
+ *     counts too — deliberate: it keeps the single-source logic identical to the
+ *     agent-app self-test, and a dangling `var(--x)` in a comment is a smell
+ *     worth surfacing. Suppress a deliberate one with `allowlist`.
+ *
+ *  2. Tailwind-utility check — INTENTIONALLY PARTIAL. Bare classes like
+ *     `bg-card` carry no `var(--)` and so are invisible to check 1; Tailwind
+ *     resolves them to `hsl(var(--card))` at build via the preset. Fully
+ *     resolving arbitrary Tailwind config is out of scope (it would mean
+ *     re-implementing Tailwind). Instead we check the SPECIFIC known-dangerous
+ *     families that have actually shipped invisible: the MD3 surface ladder
+ *     (`surface-container` / `-high` / `-highest`) and the `card` / `popover`
+ *     elevation pairs — exactly the utilities the agent-app tailwind-preset
+ *     registers onto elevation tokens (see src/theme/tailwind-preset.ts, the
+ *     source of truth for this mapping). The canvas/sequence aliases
+ *     (`--bg-input`, `--text-primary`, …) are consumed as `bg-[var(--…)]`
+ *     arbitrary values and so are already covered fully by check 1 — they need
+ *     no entry here.
+ *
+ * Node-only (reads the filesystem) → this lives in the `./theme-contract`
+ * subpath, NOT `./theme`, which must stay browser-clean (it's in the
+ * browser-safe manifest test).
+ */
+interface ThemeContractOptions {
+    /** Consumer source directories to scan for token references (recursively). */
+    srcDirs: string[];
+    /**
+     * Path to the base tokens.css whose `--name:` definitions are the ground
+     * truth. Defaults to the tokens.css agent-app ships (`./styles`) — the set a
+     * consumer gets from `import '@tangle-network/agent-app/styles'`.
+     */
+    tokensCss?: string;
+    /**
+     * Additional CSS files whose `--name:` definitions also count as defined —
+     * the app's own overrides/extensions layered on top of the base tokens.
+     */
+    extraTokensCss?: string[];
+    /**
+     * Token names (e.g. `--my-app-accent`) to treat as always-defined, suppressing
+     * them from the missing list. For app-specific vars defined outside any CSS
+     * the checker can see (injected at runtime, from a third-party stylesheet, …).
+     */
+    allowlist?: string[];
+}
+interface ThemeContractMiss {
+    /** The undefined custom property, e.g. `--popover`. */
+    varName: string;
+    /**
+     * Where it was referenced: `path/to/file.tsx`, or
+     * `path/to/file.tsx (via bg-surface-container-high)` when the reference is a
+     * Tailwind utility that resolves to the token rather than a literal var().
+     */
+    referencedIn: string;
+}
+interface ThemeContractResult {
+    ok: boolean;
+    missing: ThemeContractMiss[];
+}
+/**
+ * Check that every theme token a consumer's source references is actually
+ * defined in the CSS that consumer ships. Returns the full missing set; the
+ * caller decides how to fail (the bin exits non-zero on any miss).
+ */
+declare function checkThemeContract(opts: ThemeContractOptions): ThemeContractResult;
+
+export { type ThemeContractMiss, type ThemeContractOptions, type ThemeContractResult, checkThemeContract };

package/dist/theme-contract/index.js

@@ -0,0 +1,7 @@
+import {
+  checkThemeContract
+} from "../chunk-NYATNLRK.js";
+export {
+  checkThemeContract
+};
+//# sourceMappingURL=index.js.map

package/dist/theme-contract/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-app",
-  "version": "0.43.26",
+  "version": "0.43.28",
   "packageManager": "pnpm@10.33.4",
   "description": "Application-shell framework for Tangle agent products: a bounded tool loop, the structured agent→app tool side channel, integration-hub client, per-workspace billing, and crypto — composed over the Tangle agent substrate through typed seams.",
   "keywords": [
@@ -30,8 +30,12 @@
   "types": "./dist/index.d.ts",
   "files": [
     "dist",
+    "bin",
     ".claude/skills"
   ],
+  "bin": {
+    "agent-app-theme-check": "./dist/theme-contract/cli.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -138,6 +142,11 @@
       "import": "./dist/billing/index.js",
       "default": "./dist/billing/index.js"
     },
+    "./preflight": {
+      "types": "./dist/preflight/index.d.ts",
+      "import": "./dist/preflight/index.js",
+      "default": "./dist/preflight/index.js"
+    },
     "./chat-store": {
       "types": "./dist/chat-store/index.d.ts",
       "import": "./dist/chat-store/index.js",
@@ -359,6 +368,11 @@
       "import": "./dist/theme/tailwind-preset.js",
       "default": "./dist/theme/tailwind-preset.js"
     },
+    "./theme-contract": {
+      "types": "./dist/theme-contract/index.d.ts",
+      "import": "./dist/theme-contract/index.js",
+      "default": "./dist/theme-contract/index.js"
+    },
     "./styles": "./dist/theme/tokens.css"
   },
   "scripts": {