papercliped 1.1.0-beta.2 → 2.2.0

package/dist/public-api/routes.js

@@ -0,0 +1,251 @@
+import { tools } from "../tools.js";
+import { buildPublicOpenApi } from "./openapi.js";
+import { assessHealth, BRIDGE_SILENT_MS, latestPerNode } from "./health.js";
+import { AUTH_FAILURE_REASONS, ERROR_CLASSES, PUBLIC_SCHEMA_VERSION, PUBLIC_WINDOWS, } from "./types.js";
+const REPO_CACHE_MS = 3_600_000;
+async function githubRepo(repo) {
+    const r = await fetch(`https://api.github.com/repos/${repo}`, { headers: { accept: "application/vnd.github+json", "user-agent": "papercliped-bridge" }, signal: AbortSignal.timeout(5000) });
+    if (!r.ok)
+        throw new Error(`github ${r.status}`);
+    const j = (await r.json());
+    const n = (v) => (typeof v === "number" && Number.isFinite(v) && v >= 0 ? Math.floor(v) : 0);
+    return { stars: n(j.stargazers_count), forks: n(j.forks_count), openIssues: n(j.open_issues_count) };
+}
+const WINDOW_SPEC = {
+    "1h": { span: 3_600_000, bucket: 300_000 }, // 12 buckets of 5 minutes
+    "24h": { span: 86_400_000, bucket: 3_600_000 }, // 24 hourly buckets
+    "7d": { span: 7 * 86_400_000, bucket: 6 * 3_600_000 }, // 28 buckets of 6 hours
+};
+const CACHE_MS = 30_000;
+const RATE_PER_MIN = 60;
+const TOOL_NAMES = new Set(tools.map((t) => t.name));
+const iso = (ms) => new Date(ms).toISOString();
+const zero = (keys) => Object.fromEntries(keys.map((k) => [k, 0]));
+const ENDPOINTS = [
+    { path: "/api/public/v1/info", description: "This document: version, endpoints, limits." },
+    { path: "/api/public/v1/openapi.json", description: "OpenAPI description of this public API." },
+    { path: "/api/public/v1/status", description: "Is the service up: ok, degraded or down." },
+    { path: "/api/public/v1/stats?window=1h|24h|7d", description: "Aggregate users, connections, sign-ins, requests, errors and load." },
+    { path: "/api/public/v1/series?window=1h|24h|7d", description: "The same numbers over time, in fixed buckets." },
+    { path: "/api/public/v1/errors?window=1h|24h|7d", description: "Error mix by class and sign-in failures by reason." },
+    { path: "/api/public/v1/repo", description: "GitHub stars, forks and open issues of the project (cached for an hour)." },
+    { path: "/api/public/stats", description: "Legacy: total users and live connections." },
+];
+/**
+ * GET /api/public/v1/*: system-level numbers anyone may read. Aggregate only (see types.ts), cached for 30 s, rate-limited
+ * per client address, CORS-open for GET with no credentials.
+ */
+export class PublicApiRoutes {
+    o;
+    now;
+    startedAt;
+    cache = new Map();
+    repoState = { at: 0, v: null, inflight: null };
+    constructor(o) {
+        this.o = o;
+        this.now = o.now ?? Date.now;
+        this.startedAt = o.startedAt ?? this.now();
+    }
+    ip(req) {
+        const hops = this.o.proxyHops ?? 0;
+        if (hops > 0) {
+            const parts = String(req.headers["x-forwarded-for"] ?? "").split(",").map((x) => x.trim()).filter(Boolean);
+            if (parts.length >= hops)
+                return parts[parts.length - hops];
+        }
+        return req.socket.remoteAddress ?? "unknown";
+    }
+    send(res, status, body, extra = {}) {
+        res.writeHead(status, {
+            "Content-Type": "application/json",
+            "Access-Control-Allow-Origin": "*",
+            "Access-Control-Allow-Methods": "GET, OPTIONS",
+            "Access-Control-Max-Age": "86400",
+            "X-Content-Type-Options": "nosniff",
+            "Cache-Control": status === 200 ? `public, max-age=${CACHE_MS / 1000}` : "no-store",
+            ...extra,
+        });
+        res.end(JSON.stringify(body));
+        return true;
+    }
+    async cached(key, build) {
+        const hit = this.cache.get(key);
+        if (hit && this.now() - hit.at < CACHE_MS)
+            return hit.body;
+        const body = await build();
+        this.cache.set(key, { at: this.now(), body });
+        return body;
+    }
+    async handle(req, res, url) {
+        const path = url.pathname.replace(/\/+$/, "");
+        if (!path.startsWith("/api/public/v1"))
+            return false;
+        if (req.method === "OPTIONS") {
+            res.writeHead(204, { "Access-Control-Allow-Origin": "*", "Access-Control-Allow-Methods": "GET, OPTIONS", "Access-Control-Max-Age": "86400" });
+            res.end();
+            return true;
+        }
+        if (req.method !== "GET" && req.method !== "HEAD")
+            return this.send(res, 405, { error: "Only GET is allowed" }, { Allow: "GET, OPTIONS" });
+        if (!(await this.o.store.hit(`pubapi:${this.ip(req)}`, RATE_PER_MIN, 60_000)))
+            return this.send(res, 429, { error: `Rate limit: ${RATE_PER_MIN} requests per minute` }, { "Retry-After": "60" });
+        const route = path.slice("/api/public/v1".length) || "/";
+        const w = url.searchParams.get("window") ?? "24h";
+        const needsWindow = route === "/stats" || route === "/series" || route === "/errors";
+        if (needsWindow && !PUBLIC_WINDOWS.includes(w))
+            return this.send(res, 400, { error: `window must be one of ${PUBLIC_WINDOWS.join(", ")}` });
+        const win = w;
+        try {
+            if (route === "/info")
+                return this.send(res, 200, this.info());
+            if (route === "/openapi.json")
+                return this.send(res, 200, buildPublicOpenApi(this.o.publicUrl ?? `${url.protocol}//${req.headers.host ?? "localhost"}`, this.o.version));
+            if (route === "/repo")
+                return this.send(res, 200, await this.repo());
+            if (route === "/status")
+                return this.send(res, 200, await this.cached("status", () => this.status()));
+            if (route === "/stats")
+                return this.send(res, 200, await this.cached(`stats:${win}`, () => this.stats(win)));
+            if (route === "/series")
+                return this.send(res, 200, await this.cached(`series:${win}`, () => this.series(win)));
+            if (route === "/errors")
+                return this.send(res, 200, await this.cached(`errors:${win}`, () => this.errors(win)));
+        }
+        catch {
+            return this.send(res, 503, { error: "Statistics are temporarily unavailable" });
+        }
+        return this.send(res, 404, { error: "Not found", endpoints: ENDPOINTS.map((e) => e.path) });
+    }
+    info() {
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, service: "papercliped", version: this.o.version, docs: this.o.docsUrl, endpoints: ENDPOINTS, windows: PUBLIC_WINDOWS, rateLimit: { requestsPerMinute: RATE_PER_MIN }, cacheSeconds: CACHE_MS / 1000 };
+    }
+    /** Stale-while-revalidate: always answers at once; refreshes from GitHub at most once an hour (and after a failure, after 10 min). */
+    async repo() {
+        const name = this.o.repo ?? "OpenSourcx/papercliped";
+        const st = this.repoState;
+        const age = this.now() - st.at;
+        const due = !st.v ? true : st.v.stars == null ? age > 600_000 : age > REPO_CACHE_MS;
+        if (due && !st.inflight) {
+            st.inflight = (async () => {
+                try {
+                    const n = await (this.o.repoFetcher ?? githubRepo)(name);
+                    st.v = { schemaVersion: PUBLIC_SCHEMA_VERSION, repo: name, url: `https://github.com/${name}`, ...n, fetchedAt: iso(this.now()) };
+                }
+                catch {
+                    st.v = st.v?.stars != null ? st.v : { schemaVersion: PUBLIC_SCHEMA_VERSION, repo: name, url: `https://github.com/${name}`, stars: null, forks: null, openIssues: null, fetchedAt: null };
+                }
+                finally {
+                    st.at = this.now();
+                    st.inflight = null;
+                }
+            })();
+            if (!st.v)
+                await st.inflight; // the very first request waits (up to the 5 s timeout)
+        }
+        return st.v;
+    }
+    uptime = () => Math.max(0, Math.round((this.now() - this.startedAt) / 1000));
+    /** Service health over the last hour, from tool-call totals and the bridges' own health reports. */
+    async health() {
+        const to = this.now() + 1;
+        const [totals, samples] = await Promise.all([this.o.store.auditTotals("tool", to - 3_600_000, to), this.o.store.nodeSamples(to - 15 * 60_000)]);
+        const nodes = latestPerNode(samples, this.now());
+        const fresh = nodes.filter((n) => n.ageMs <= BRIDGE_SILENT_MS);
+        const h = assessHealth({
+            count: totals.count,
+            faults: totals.faults,
+            p95: totals.p95,
+            dbPingMs: nodes[0]?.dbPingMs ?? null,
+            loopLagP99Ms: Math.max(0, ...fresh.map((n) => n.loopLagP99Ms)),
+            slowMs: this.o.slowMs ?? 2000,
+            recentDbFailed: samples.slice(0, 3).length > 0 && samples.slice(0, 3).every((x) => x.dbPingMs == null),
+            bridgeSilentMs: nodes.length ? Math.min(...nodes.map((n) => n.ageMs)) : null,
+        });
+        // This process is answering, so "no bridge has reported yet" (e.g. a fresh start) is not an outage.
+        const status = h.state === "critical" ? "down" : h.state === "degraded" && !(h.reasons.length === 1 && h.reasons[0].startsWith("no bridge")) ? "degraded" : "ok";
+        const lead = fresh[0];
+        return { status, load: { eventLoopLagP99Ms: lead ? Math.round(lead.loopLagP99Ms) : null, dbPingMs: lead?.dbPingMs != null ? Math.round(lead.dbPingMs) : null, memoryMb: lead ? Math.round(lead.rssMb) : null, bridgesReporting: fresh.length } };
+    }
+    async status() {
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, status: (await this.health()).status, version: this.o.version, uptimeSeconds: this.uptime(), checkedAt: iso(this.now()) };
+    }
+    failuresByReason(failures) {
+        const out = zero(AUTH_FAILURE_REASONS);
+        for (const [key, n] of Object.entries(failures)) {
+            const reason = key.split(":")[1];
+            out[AUTH_FAILURE_REASONS.includes(reason) ? reason : "other"] += n;
+        }
+        return out;
+    }
+    byClass(rows) {
+        const out = zero(ERROR_CLASSES);
+        for (const r of rows)
+            out[ERROR_CLASSES.includes(r.key) ? r.key : "other"] += r.count;
+        return out;
+    }
+    async stats(win) {
+        const { span } = WINDOW_SPEC[win];
+        const to = this.now() + 1;
+        const from = to - span;
+        const S = this.o.store;
+        const [totals, byTool, toolErrors, httpErrors, users, active, counts, live, health] = await Promise.all([
+            S.auditTotals("tool", from, to),
+            S.auditBreakdown("tool", "name", from, to, 100),
+            S.auditBreakdown("tool", "errorClass", from, to, 50),
+            S.auditBreakdown("http", "errorClass", from, to, 50),
+            S.countAccounts(),
+            S.auditActiveUsers(from, to),
+            S.userEventCounts(from, to),
+            S.liveGrantCount(),
+            this.health(),
+        ]);
+        const started = counts.byKind.started ?? 0;
+        const completed = counts.byKind.completed ?? 0;
+        const failures = this.failuresByReason(counts.failures);
+        const failed = Object.values(failures).reduce((a, b) => a + b, 0);
+        const errorClasses = this.byClass([...toolErrors.filter((r) => r.key && r.key !== "null").map((r) => ({ key: r.key, count: r.errors || r.count })), ...httpErrors.filter((r) => r.key && r.key !== "null").map((r) => ({ key: r.key, count: r.errors || r.count }))]);
+        const tools = {};
+        for (const r of byTool)
+            if (TOOL_NAMES.has(r.key))
+                tools[r.key] = r.count; // only catalogue names, never other keys
+        return {
+            schemaVersion: PUBLIC_SCHEMA_VERSION,
+            window: win,
+            windowSeconds: span / 1000,
+            generatedAt: iso(this.now()),
+            service: { version: this.o.version, uptimeSeconds: this.uptime(), status: health.status },
+            users: { total: users, active, new: counts.byKind.joined ?? 0 },
+            connections: { live },
+            auth: { flowsStarted: started, flowsCompleted: completed, flowsFailed: failed, successRate: started > 0 ? Math.min(1, completed / started) : null, failuresByReason: failures },
+            requests: {
+                count: totals.count,
+                errors: totals.errors,
+                faults: totals.faults,
+                successRate: totals.count ? (totals.count - totals.errors) / totals.count : null,
+                latencyMs: { p50: Math.round(totals.p50), p95: Math.round(totals.p95), p99: Math.round(totals.p99) },
+                callsPerMinute: Math.round((totals.count / (span / 60_000)) * 100) / 100,
+                byTool: tools,
+            },
+            errors: { total: Object.values(errorClasses).reduce((a, b) => a + b, 0), byClass: errorClasses },
+            load: health.load,
+        };
+    }
+    async series(win) {
+        const { span, bucket } = WINDOW_SPEC[win];
+        const to = this.now() + 1;
+        const from = to - span;
+        const [calls, flows] = await Promise.all([this.o.store.auditSeries("tool", from, to, bucket), this.o.store.userEventSeries(from, to, bucket)]);
+        const start = Math.floor(from / bucket) * bucket;
+        const buckets = [];
+        for (let t = start; t < to; t += bucket) {
+            const c = calls.find((x) => x.t === t);
+            const f = flows.find((x) => x.t === t);
+            buckets.push({ t: iso(t), requests: c?.count ?? 0, errors: c?.errors ?? 0, faults: c?.faults ?? 0, p95Ms: Math.round(c?.p95 ?? 0), authCompleted: f?.completed ?? 0, authFailed: f?.failed ?? 0, newUsers: f?.joined ?? 0 });
+        }
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, window: win, bucketSeconds: bucket / 1000, generatedAt: iso(this.now()), buckets };
+    }
+    async errors(win) {
+        const s = await this.cached(`stats:${win}`, () => this.stats(win));
+        return { schemaVersion: PUBLIC_SCHEMA_VERSION, window: win, generatedAt: s.generatedAt, requests: s.requests.count, errorRate: s.requests.count ? s.requests.errors / s.requests.count : null, byClass: s.errors.byClass, authFailuresByReason: s.auth.failuresByReason };
+    }
+}

package/dist/public-api/types.js

@@ -0,0 +1,14 @@
+/**
+ * The public, aggregate-only Papercliped API (GET /api/public/v1/*). These types are the contract: consumers (the website's
+ * status page, the separate domain service and its dashboard) can import or copy them. Additive changes keep
+ * `schemaVersion`; anything breaking bumps it and gets a new path (/v2).
+ *
+ * Aggregate only, by design: no usernames, aliases, account/grant ids, Paperclip hosts, app names, IPs, tokens or free text,
+ * and no per-user or per-tenant breakdown. Categories are fixed lists, never values taken from user data.
+ */
+export const PUBLIC_SCHEMA_VERSION = 1;
+export const PUBLIC_WINDOWS = ["1h", "24h", "7d"];
+/** Why a sign-in or connect flow failed. Anything the bridge records outside this list is counted as `other`. */
+export const AUTH_FAILURE_REASONS = ["bad_credentials", "rate_limited", "denied", "expired", "unreachable", "invalid_instance", "too_many_attempts", "other"];
+/** Error classes of tool calls and protocol requests. Anything else is counted as `other`. */
+export const ERROR_CLASSES = ["invalid_input", "insufficient_scope", "read_only", "upstream_4xx", "upstream_5xx", "upstream_unreachable", "rate_limited", "unauthorized", "internal", "other"];

package/dist/server.js

@@ -111,6 +111,10 @@ export function createHttpServer(config, http, opts = {}) {
                 const host = req.headers.host ?? `${http.host}:${http.port}`;
                 return json(res, 200, buildOpenApi(http.oauth?.issuer ?? http.publicUrl ?? `http://${host}`));
             }
+            if (opts.publicApi && (await opts.publicApi.handle(req, res, url)))
+                return;
+            if (opts.web && (await opts.web.handle(req, res, url)))
+                return;
             if (opts.site && (await opts.site.handle(req, res, url)))
                 return;
             if (opts.manage && (await opts.manage.handle(req, res, url)))

package/dist/site/landing.js

@@ -57,7 +57,7 @@ export function landingBody() {
   <p class="sub2">Pick what you would let Claude do, then see what happens when it tries.</p>
   <div class="seg" role="group" aria-label="Access level">
     <button type="button" data-l="read" aria-pressed="true">Read only</button>
-    <button type="button" data-l="control" aria-pressed="false">Full control (beta)</button>
+    <button type="button" data-l="control" aria-pressed="false">Full control</button>
   </div>
   <div class="chat" id="chat" aria-live="polite"></div>
 </section>
@@ -65,7 +65,7 @@ export function landingBody() {
 <section class="band"><div class="big">Papercliped, not Paperclipped.<small>The little clip that connects your AI to the Paperclip you already run. No lock-in, and you can disconnect in one click.</small></div></section>
 
 <section class="cards" style="margin-top:34px">
-  <div class="card"><h2>You choose the access</h2><p>Read only by default. Full control (beta) is opt-in, every time you connect.</p></div>
+  <div class="card"><h2>You choose the access</h2><p>Read only by default. Full control is opt-in, every time you connect.</p></div>
   <div class="card"><h2>Your keys stay sealed</h2><p>Your Paperclip key is stored encrypted and is never shown to the AI app.</p></div>
   <div class="card"><h2>Optionally anonymous</h2><p>Appear as an alias like Ann02 in the operator's logs instead of your username.</p></div>
   <div class="card"><h2>Manage it yourself</h2><p>Beta users get a page to see every connected app, change its access and disconnect it.</p></div>
@@ -136,7 +136,7 @@ const SCRIPT_TEXT = `
       ["me", "Pause the Web Engineer."],
       ["ai", "Done. The Web Engineer is paused. I will tell you before I do anything destructive.", "Change agents", true],
       ["me", "Terminate the Mail Officer."],
-      ["ai", "That needs Admin access, which you did not give me. I can pause it instead.", "Terminate agents", false]
+      ["ai", "Terminating can't be undone, so I will check first: do you want me to terminate the Mail Officer?", "Terminate agents", true]
     ]
   };
   function show(l) {

package/dist/site/markdown.js

@@ -1,4 +1,5 @@
-import { esc } from "../oauth/pages.js";
+// No imports, so the website (web/) can reuse this renderer as is.
+const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
 /**
  * A deliberately small Markdown renderer for the project's own pages (docs, privacy, terms). Everything is HTML-escaped first;
  * only a fixed set of constructs produces tags, and links are limited to http(s), mailto and same-site paths.

package/dist/site/site.js

@@ -7,12 +7,24 @@ import { LANDING_CSS, LANDING_SCRIPT, landingBody } from "./landing.js";
 import { renderMarkdown } from "./markdown.js";
 const NAV = [
     { slug: "getting-started", title: "Getting started" },
+    { slug: "what-is-papercliped", title: "What is Papercliped?" },
     { slug: "signup", title: "Create your account" },
-    { slug: "manage", title: "Manage connections (beta)" },
+    { slug: "connect-your-paperclip", title: "Set up your Paperclip" },
+    { slug: "other-ai-apps", title: "Any AI app (MCP)" },
+    { slug: "chatgpt", title: "ChatGPT setup" },
     { slug: "permissions", title: "Permissions" },
+    { slug: "manage", title: "Manage connections" },
+    { slug: "paperclip-plugin", title: "Paperclip plugin" },
     { slug: "anonymous-mode", title: "Anonymous mode" },
+    { slug: "self-hosting", title: "Run it yourself" },
+    { slug: "tools", title: "Tool reference" },
+    { slug: "manage-api", title: "Manage API" },
+    { slug: "public-api", title: "Public API and status" },
+    { slug: "environment", title: "Environment variables" },
+    { slug: "cli", title: "Command line" },
+    { slug: "limits-and-errors", title: "Limits and errors" },
     { slug: "security", title: "Security" },
-    { slug: "chatgpt", title: "ChatGPT setup" },
+    { slug: "faq", title: "FAQ" },
     { slug: "troubleshooting", title: "Troubleshooting" },
 ];
 const CLIP = `<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M21.44 11.05l-9.19 9.19a6 6 0 0 1-8.49-8.49l9.19-9.19a4 4 0 0 1 5.66 5.66l-9.2 9.19a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>`;
@@ -53,7 +65,7 @@ export class SiteRoutes {
     constructor(o) {
         this.o = o;
         const dir = o.dir ?? new URL("../../site/", import.meta.url);
-        const fill = (md) => md.replaceAll("{{URL}}", o.url).replaceAll("{{CONTACT}}", o.contact).replaceAll("{{DATE}}", o.effective);
+        const fill = (md) => md.replaceAll("{{MCP}}", o.mcpUrl ?? o.url).replaceAll("{{URL}}", o.url).replaceAll("{{CONTACT}}", o.contact).replaceAll("{{DATE}}", o.effective);
         const load = (rel) => renderMarkdown(fill(readFileSync(new URL(rel, dir), "utf8")));
         this.pages.set("/privacy", { title: "Privacy", html: load("privacy.md") });
         this.pages.set("/terms", { title: "Terms", html: load("terms.md") });
@@ -62,7 +74,7 @@ export class SiteRoutes {
     }
     layout(title, body, current, script) {
         const nav = `<nav aria-label="Main"><a href="/docs/getting-started"${current.startsWith("/docs") ? " aria-current=page" : ""}>Docs</a><a href="/privacy"${current === "/privacy" ? " aria-current=page" : ""}>Privacy</a><a href="/terms"${current === "/terms" ? " aria-current=page" : ""}>Terms</a><a href="https://github.com/OpenSourcx/papercliped" rel="noopener noreferrer">GitHub</a></nav>`;
-        return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light"><title>${esc(title)} · Papercliped</title>${FAVICON_LINK}<meta name="description" content="Connect Claude and ChatGPT to your Paperclip: control agents, sync and get reports, with permissions you choose."><style>${CSS}${script?.css ?? ""}</style></head><body><header><a class="brand" href="/">${CLIP}<span>Papercliped</span></a>${nav}</header>${body}<footer>Papercliped ${esc(VERSION)} (beta) · <a href="/privacy">Privacy</a> · <a href="/terms">Terms</a> · <a href="/docs/security">Security</a></footer>${script ? `<script nonce="${script.nonce}">${script.code}</script>` : ""}</body></html>`;
+        return `<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light"><title>${esc(title)} · Papercliped</title>${FAVICON_LINK}<meta name="description" content="Connect Claude and ChatGPT to your Paperclip: control agents, sync and get reports, with permissions you choose."><style>${CSS}${script?.css ?? ""}</style></head><body><header><a class="brand" href="/">${CLIP}<span>Papercliped</span></a>${nav}</header>${body}<footer>Papercliped ${esc(VERSION)} · <a href="/privacy">Privacy</a> · <a href="/terms">Terms</a> · <a href="/docs/security">Security</a></footer>${script ? `<script nonce="${script.nonce}">${script.code}</script>` : ""}</body></html>`;
     }
     doc(path) {
         const p = this.pages.get(path);

package/dist/telemetry/recorder.js

@@ -157,7 +157,7 @@ export class SystemSampler {
     }
 }
 /**
- * Writes this bridge process's health to the database every 30 s, so the separate panel can show it and notice when it STOPS
+ * Writes this bridge process's health to the database every 30 s, so the public status API and the operator dashboard can show it and notice when it STOPS
  * (asleep on a free tier, crashed, or cut off from the database). Failures are swallowed: reporting must never hurt the bridge.
  */
 export class NodeReporter {

package/dist/tools.js

@@ -389,6 +389,43 @@ export const tools = [
         },
     }),
     // ───────────────────────────── escape hatch ─────────────────────────────
+    // ───────────────────────────── Papercliped itself ─────────────────────────────
+    tool({
+        name: "papercliped_service_status",
+        title: "Papercliped service status",
+        description: "Is the hosted Papercliped service working? Returns its status (ok, degraded, down), version and aggregate 24-hour numbers (requests, success rate, latency, sign-ins). Public data only; does not touch Paperclip.",
+        access: "read",
+        schema: z.object({ window: z.enum(["1h", "24h", "7d"]).optional().describe("Time window for the numbers (default 24h)") }),
+        run: async (_c, i) => {
+            const base = paperclipedUrl();
+            const get = async (path) => {
+                let r;
+                try {
+                    r = await fetch(`${base}${path}`, { headers: { accept: "application/json" }, signal: AbortSignal.timeout(8000) });
+                }
+                catch {
+                    throw new Error(`Cannot reach Papercliped's status API at ${base}`);
+                }
+                if (!r.ok)
+                    throw new Error(`Cannot reach Papercliped's status API at ${base} (HTTP ${r.status})`);
+                return (await r.json());
+            };
+            const w = i.window ?? "24h";
+            const [status, stats] = await Promise.all([get("/api/public/v1/status"), get(`/api/public/v1/stats?window=${w}`)]);
+            return {
+                service: base,
+                status: status.status,
+                version: status.version,
+                uptimeSeconds: status.uptimeSeconds,
+                window: w,
+                users: stats.users,
+                liveConnections: stats.connections?.live,
+                requests: { count: stats.requests?.count, successRate: stats.requests?.successRate, latencyMs: stats.requests?.latencyMs },
+                signIns: { started: stats.auth?.flowsStarted, completed: stats.auth?.flowsCompleted, successRate: stats.auth?.successRate },
+                statusPage: `${base}/status`,
+            };
+        },
+    }),
     tool({
         name: "paperclip_api_request",
         title: "Raw API request",
@@ -397,8 +434,8 @@ export const tools = [
         schema: z.object({
             method: z.enum(["GET", "POST", "PATCH", "PUT", "DELETE"]),
             path: z.string().startsWith("/").describe("Path after /api, e.g. /companies"),
-            query: z.record(z.union([z.string(), z.number(), z.boolean()])).optional(),
-            body: z.record(z.unknown()).optional(),
+            query: z.record(z.string(), z.union([z.string(), z.number(), z.boolean()])).optional(),
+            body: z.record(z.string(), z.unknown()).optional(),
             confirm: z.boolean().optional().describe("Required true for non-GET calls"),
         }),
         run: (c, i) => {
@@ -410,3 +447,12 @@ export const tools = [
     }),
 ];
 export const toolsByName = new Map(tools.map((t) => [t.name, t]));
+/** Where papercliped_service_status looks (PAPERCLIPED_URL; https, or http on localhost for development). */
+function paperclipedUrl() {
+    const raw = (process.env.PAPERCLIPED_URL ?? "").trim() || "https://papercliped.co";
+    const u = new URL(raw);
+    const loop = ["localhost", "127.0.0.1", "[::1]"].includes(u.hostname);
+    if (u.protocol !== "https:" && !(u.protocol === "http:" && loop))
+        throw new ToolInputError("PAPERCLIPED_URL must be an https address");
+    return u.origin;
+}

package/dist/web/csp.js

@@ -0,0 +1,16 @@
+/**
+ * The Content-Security-Policy for the website (web/). The bridge sends it with every page, and `vite preview` sends the same
+ * one so the website's route check catches violations: everything from our own origin, nothing inline, no third parties.
+ */
+export const SITE_CSP = [
+    "default-src 'none'",
+    "script-src 'self'",
+    "style-src 'self'",
+    "font-src 'self'",
+    "img-src 'self' data:",
+    "connect-src 'self'",
+    "manifest-src 'self'",
+    "frame-ancestors 'none'",
+    "base-uri 'none'",
+    "form-action 'self'",
+].join("; ");

package/dist/web/hosts.js

@@ -0,0 +1,23 @@
+const ROLES = ["marketing", "docs", "api", "forum"];
+const HOST = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)+(:\d{1,5})?$/;
+export function parseHosts(raw) {
+    const map = { marketing: [], docs: [], api: [], forum: [] };
+    for (const part of (raw ?? "").split(";").map((s) => s.trim()).filter(Boolean)) {
+        const [role, list] = part.split("=");
+        const r = role?.trim().toLowerCase();
+        if (!ROLES.includes(r))
+            throw new Error(`PUBLIC_HOSTS: unknown role "${role}" (use ${ROLES.join(", ")})`);
+        for (const h of (list ?? "").split(",").map((s) => s.trim().toLowerCase()).filter(Boolean)) {
+            if (!HOST.test(h))
+                throw new Error(`PUBLIC_HOSTS: "${h}" is not a host name`);
+            if (ROLES.some((x) => map[x].includes(h)))
+                throw new Error(`PUBLIC_HOSTS: "${h}" is listed twice`);
+            map[r].push(h);
+        }
+    }
+    return map;
+}
+export function roleOf(map, host) {
+    const h = (host ?? "").toLowerCase();
+    return ROLES.find((r) => map[r].includes(h)) ?? null;
+}

package/dist/web/routes.js

@@ -0,0 +1,132 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { extname, join, normalize, sep } from "node:path";
+import { SITE_CSP } from "./csp.js";
+import { roleOf } from "./hosts.js";
+/** Paths the bridge itself serves on every host; the website never answers them. */
+const PROTOCOL = /^\/(mcp|actions\/|openapi\.json$|register$|authorize|token$|revoke$|\.well-known\/|api\/|manage$|healthz$|readyz$)/;
+const TYPES = {
+    ".html": "text/html; charset=utf-8", ".js": "text/javascript; charset=utf-8", ".css": "text/css; charset=utf-8", ".json": "application/json",
+    ".svg": "image/svg+xml", ".png": "image/png", ".ico": "image/x-icon", ".woff2": "font/woff2", ".xml": "application/xml; charset=utf-8",
+    ".txt": "text/plain; charset=utf-8", ".md": "text/plain; charset=utf-8", ".webmanifest": "application/manifest+json",
+};
+const HEADERS = { "X-Content-Type-Options": "nosniff", "Referrer-Policy": "strict-origin-when-cross-origin", "X-Frame-Options": "DENY" };
+/**
+ * Serves the React website and does the host routing:
+ *   marketing host  → the site; /docs/* moves to the docs host when there is one
+ *   docs host       → the docs landing at / and each page at /<page>; old /docs/* and /topics/* links redirect there;
+ *                     other pages go to the marketing host
+ *   api host        → protocol endpoints only (handled elsewhere); pages redirect to the marketing host
+ *   forum host      → redirects to the forum
+ * Hosts not in PUBLIC_HOSTS (and a bridge with no PUBLIC_HOSTS) get the whole site, as before.
+ */
+export class WebAppRoutes {
+    o;
+    index;
+    routes;
+    /** Doc page slugs ("permissions", "faq"…), from the /docs/<slug> entries in routes.json. */
+    docSlugs;
+    constructor(o) {
+        this.o = o;
+        this.index = readFileSync(join(o.dir, "index.html"), "utf8");
+        this.routes = new Set(JSON.parse(readFileSync(join(o.dir, "routes.json"), "utf8")));
+        this.docSlugs = new Set([...this.routes].filter((r) => r.startsWith("/docs/")).map((r) => r.slice("/docs/".length)));
+    }
+    /** Finds web/dist next to the package, or WEB_DIST. Null when the website isn't built (then the bridge's own pages are used). */
+    static locate(env, fallback) {
+        const dir = env.WEB_DIST?.trim() || fallback;
+        return existsSync(join(dir, "index.html")) && existsSync(join(dir, "routes.json")) ? dir : null;
+    }
+    canonical(role) {
+        return this.o.hosts[role][0];
+    }
+    redirect(res, to, permanent = true) {
+        res.writeHead(permanent ? 301 : 302, { Location: to, "Cache-Control": permanent ? "public, max-age=3600" : "no-store", ...HEADERS });
+        res.end();
+        return true;
+    }
+    /** The page shell, with the host map for the app's links (see web/src/lib/hosts.ts). */
+    shell(res, status, head) {
+        const map = JSON.stringify({ marketing: this.canonical("marketing"), docs: this.canonical("docs") }).replace(/"/g, "&quot;");
+        res.writeHead(status, { "Content-Type": "text/html; charset=utf-8", "Cache-Control": "no-cache", "Content-Security-Policy": SITE_CSP, ...HEADERS });
+        res.end(head ? undefined : this.index.replace('<meta name="pcl-hosts" content="{}" />', `<meta name="pcl-hosts" content="${map}" />`));
+        return true;
+    }
+    file(res, path, head) {
+        let rel;
+        try {
+            rel = normalize(decodeURIComponent(path)).replace(/^([/\\])+/, "");
+        }
+        catch {
+            return false;
+        }
+        if (!rel || rel.split(/[/\\]/).includes("..") || rel === "index.html" || rel === "routes.json")
+            return false;
+        const full = join(this.o.dir, rel);
+        if (!full.startsWith(this.o.dir.endsWith(sep) ? this.o.dir : this.o.dir + sep))
+            return false;
+        let st;
+        try {
+            st = statSync(full);
+        }
+        catch {
+            return false;
+        }
+        if (!st.isFile())
+            return false;
+        const immutable = rel.startsWith("assets" + sep) || rel.startsWith("assets/") || rel.startsWith("fonts");
+        res.writeHead(200, {
+            "Content-Type": TYPES[extname(full).toLowerCase()] ?? "application/octet-stream",
+            "Content-Length": String(st.size),
+            "Cache-Control": immutable ? "public, max-age=31536000, immutable" : "public, max-age=3600",
+            ...(rel.endsWith(".html") ? { "Content-Security-Policy": SITE_CSP } : {}),
+            ...(immutable && rel.startsWith("fonts") ? { "Access-Control-Allow-Origin": "*" } : {}),
+            ...HEADERS,
+        });
+        res.end(head ? undefined : readFileSync(full));
+        return true;
+    }
+    async handle(req, res, url) {
+        if (req.method !== "GET" && req.method !== "HEAD")
+            return false;
+        const head = req.method === "HEAD";
+        const raw = url.pathname;
+        const path = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
+        if (PROTOCOL.test(path))
+            return false;
+        const host = String(req.headers.host ?? "").toLowerCase();
+        const role = roleOf(this.o.hosts, host);
+        const q = url.search;
+        const mk = this.canonical("marketing");
+        const docs = this.canonical("docs");
+        const isDocs = /^\/(docs|topics)(\/|$)/.test(path);
+        const docsRest = isDocs ? path.replace(/^\/(docs|topics)\/?/, "") : "";
+        if (role === "forum")
+            return this.redirect(res, this.o.forumUrl || (mk ? `https://${mk}/community` : "/"), false);
+        if (role === "api")
+            return mk ? this.redirect(res, `https://${mk}${path === "/" ? "/" : path}${q}`, false) : false;
+        if (role === "marketing" && mk && host !== mk)
+            return this.redirect(res, `https://${mk}${raw}${q}`); // www → apex
+        if (role === "docs") {
+            if (isDocs)
+                return this.redirect(res, `/${docsRest}${q}`); // old /docs/x and /topics/x links
+            if (path === "/" || this.docSlugs.has(path.slice(1)))
+                return this.shell(res, 200, head);
+            if (this.routes.has(path) && mk)
+                return this.redirect(res, `https://${mk}${path}${q}`);
+        }
+        else if (isDocs) {
+            // Marketing (or unlisted) host: docs move to the docs host when there is one. /topics is an old spelling.
+            if (docs)
+                return this.redirect(res, `https://${docs}/${docsRest}${q}`);
+            if (/^\/topics(\/|$)/.test(path))
+                return this.redirect(res, `/docs${docsRest ? `/${docsRest}` : ""}${q}`);
+        }
+        if (path !== "/" && this.file(res, raw, head))
+            return true;
+        if (this.routes.has(path))
+            return this.shell(res, 200, head);
+        if (extname(path))
+            return false; // a missing file: let the bridge answer 404
+        return this.shell(res, 404, head); // the app shows its not-found page
+    }
+}