src/inbox-report.ts

Functions

Imports

It imports src/agents.ts, src/inbox.ts, src/scope.ts. Imported by src/inbox.ts, src/routes.ts.

Source

1import { checkScope } from "./scope";
2import type { Agent } from "./agents";
3import type { InboxItem } from "./inbox";
4
5// WHAT AN APP REPORTS ABOUT ITSELF TO THE INBOX (job_84e901d8eb71; design
6// capsid/research/design-inbox-report.md, Dustin's answers 2026-10-10). Some things that
7// need Dustin live only in an app's own database (Carrel's AI drafts waiting). Capsid does
8// not read that database; the app posts its present state to POST /ops/inbox/report with
9// its own scoped key, and the inbox reads the last report back as kind "report".
10//
11// - The key must hold the write grant on the namespace the report names, through
12//   checkScope (one enforcement point, test/scope.test.ts). A report for any other namespace
13//   is refused.
14// - A report replaces the last one whole and expires after 6 hours: an app that stops
15//   reporting stops being counted, because a stale "needs you" is worse than none.
16// - No severity field: a reported item always counts as needs-you, so an app cannot quiet
17//   its own badge (Dustin, decision 3).
18// - The items are the app's words. A link must stay on the app's own origin (its ops_sites
19//   row), and capsid_run_improve action status fences the title as external before an agent reads it.
20// - One report per minute per key, fail closed: this is a write path.
21
22const INBOX_REPORT_PATH = "/ops/inbox/report";
23const REPORT_PREFIX = "inbox:report:";
24const REPORT_RATE_PREFIX = "inbox:report-rate:";
25export const REPORT_TTL_SECONDS = 6 * 3600;
26// KV's smallest expiry, which is also the rate window.
27const REPORT_RATE_SECONDS = 60;
28export const MAX_REPORT_ITEMS = 20;
29export const MAX_REPORT_TITLE = 200;
30export const MAX_INBOX_REPORT_BYTES = 16384;
31
32export interface StoredReport {
33  namespace: string;
34  reported_at: string;
35  reported_by: string;
36  items: InboxItem[];
37}
38
39export type Checked<T> = { ok: true; value: T } | { ok: false; refusal: string };
40
41const ITEM_KEYS = new Set(["title", "link", "since"]);
42const BODY_KEYS = new Set(["namespace", "items"]);
43
44/**
45 * The report a body describes, or why it is refused. `origin` is the namespace's site
46 * origin (https://host) or null when it serves no site, in which case no item may carry
47 * a link. Anything outside the contract refuses the whole report, so a half-read report
48 * is never stored.
49 */
50export function parseReport(body: unknown, origin: string | null, now: Date): Checked<{ namespace: string; items: InboxItem[] }> {
51  const refuse = (refusal: string): Checked<never> => ({ ok: false, refusal });
52  if (!body || typeof body !== "object" || Array.isArray(body)) return refuse("the body must be a JSON object { namespace, items }");
53  const record = body as Record<string, unknown>;
54  for (const key of Object.keys(record)) if (!BODY_KEYS.has(key)) return refuse(`unknown field '${key}': a report has namespace and items only (no severity: a reported item always counts as needs-you)`);
55  if (typeof record.namespace !== "string" || record.namespace === "") return refuse("namespace is required");
56  if (!Array.isArray(record.items)) return refuse("items must be an array (send [] to clear the app's report)");
57  if (record.items.length > MAX_REPORT_ITEMS) return refuse(`at most ${MAX_REPORT_ITEMS} items; got ${record.items.length}`);
58  const items: InboxItem[] = [];
59  for (const [i, raw] of record.items.entries()) {
60    const at = `item ${i + 1}`;
61    if (!raw || typeof raw !== "object" || Array.isArray(raw)) return refuse(`${at} must be an object { title, link?, since? }`);
62    const item = raw as Record<string, unknown>;
63    for (const key of Object.keys(item)) if (!ITEM_KEYS.has(key)) return refuse(`${at} has unknown field '${key}'`);
64    if (typeof item.title !== "string" || item.title.trim() === "") return refuse(`${at} needs a title`);
65    if (item.title.length > MAX_REPORT_TITLE) return refuse(`${at}'s title is over ${MAX_REPORT_TITLE} characters`);
66    let link: string | null = null;
67    if (item.link !== undefined && item.link !== null) {
68      if (typeof item.link !== "string") return refuse(`${at}'s link must be a string`);
69      const own = linkRefusal(item.link, origin);
70      if (own) return refuse(`${at}: ${own}`);
71      link = item.link;
72    }
73    let since = now.toISOString();
74    if (item.since !== undefined) {
75      const parsed = typeof item.since === "string" ? Date.parse(item.since) : NaN;
76      if (!Number.isFinite(parsed)) return refuse(`${at}'s since must be an ISO time`);
77      since = new Date(parsed).toISOString();
78    }
79    items.push({ title: item.title.trim(), kind: "report", link, since });
80  }
81  return { ok: true, value: { namespace: record.namespace, items } };
82}
83
84/** Why `link` is not on the app's own origin, or null. */
85function linkRefusal(link: string, origin: string | null): string | null {
86  if (origin === null) return "this namespace serves no site, so its report items may not carry a link";
87  let url: URL;
88  try {
89    url = new URL(link);
90  } catch {
91    return `link '${link}' is not a URL`;
92  }
93  if (url.protocol !== "https:" || url.username || url.password || url.origin !== origin) return `link must be an https URL on the app's own origin ${origin}`;
94  return null;
95}
96
97/** Why `agent` may not report for `namespace`, or null. */
98export function reportCallerRefusal(agent: Agent, namespace: string): string | null {
99  return checkScope(agent, { tool: INBOX_REPORT_PATH, grant: "write", namespace });
100}
101
102/**
103 * Spend the key's one report this minute, or say why not. Fails closed: a counter that
104 * cannot be read or written refuses, because an unbounded write path is the thing the
105 * limit exists to stop.
106 */
107export async function spendReportRate(kv: KVNamespace, actor: string): Promise<{ ok: true } | { ok: false; status: 429 | 503; refusal: string }> {
108  const key = `${REPORT_RATE_PREFIX}${actor}`;
109  try {
110    if ((await kv.get(key)) !== null) return { ok: false, status: 429, refusal: `one report per minute per key; ${actor} already reported this minute` };
111    await kv.put(key, "1", { expirationTtl: REPORT_RATE_SECONDS });
112  } catch (err) {
113    return { ok: false, status: 503, refusal: `the report rate limit could not be read, so the report is refused: ${err instanceof Error ? err.message : String(err)}` };
114  }
115  return { ok: true };
116}
117
118export async function storeReport(kv: KVNamespace, report: StoredReport): Promise<void> {
119  await kv.put(`${REPORT_PREFIX}${report.namespace}`, JSON.stringify(report), { expirationTtl: REPORT_TTL_SECONDS });
120}
121
122/** A stored report's items, or none when it is missing, malformed or older than the
123 *  expiry. KV's own expiry removes the value; the age check here holds the same line
124 *  for a value KV has not dropped yet. */
125export function reportItems(raw: string | null, now: Date): InboxItem[] {
126  if (!raw) return [];
127  let parsed: Partial<StoredReport>;
128  try {
129    parsed = JSON.parse(raw) as Partial<StoredReport>;
130  } catch {
131    return [];
132  }
133  const at = Date.parse(parsed.reported_at ?? "");
134  if (!Number.isFinite(at) || now.getTime() - at > REPORT_TTL_SECONDS * 1000) return [];
135  return Array.isArray(parsed.items) ? parsed.items.filter((i) => i && i.kind === "report" && typeof i.title === "string") : [];
136}
137
138/** Every namespace's live report, read for the inbox. A failed list reads as none. */
139export async function readReports(kv: KVNamespace, now: Date): Promise<Map<string, InboxItem[]>> {
140  const out = new Map<string, InboxItem[]>();
141  try {
142    const listed = await kv.list({ prefix: REPORT_PREFIX });
143    for (const { name } of listed.keys) {
144      const items = reportItems(await kv.get(name), now);
145      if (items.length) out.set(name.slice(REPORT_PREFIX.length), items);
146    }
147  } catch {
148    // none: the shell renders without what it cannot read
149  }
150  return out;
151}