@getsnare/mcp 0.1.0

package/README.md

@@ -0,0 +1,100 @@
+# @getsnare/mcp
+
+Snare's MCP server. Point any MCP client at it to read and act on issues, events, traces and fix runs — or to run a Snare on your own machine, with your own model.
+
+## Install
+
+You need a Snare token. Make one at [snare.dev/settings/api-tokens](https://snare.dev/settings/api-tokens).
+
+### Claude Code
+
+```bash
+claude mcp add snare --env SNARE_API_TOKEN=snr_... -- npx -y @getsnare/mcp
+```
+
+### Cursor, Windsurf, Codex, opencode
+
+Add this to the client's MCP config file:
+
+```json
+{
+  "mcpServers": {
+    "snare": {
+      "command": "npx",
+      "args": ["-y", "@getsnare/mcp"],
+      "env": { "SNARE_API_TOKEN": "snr_..." }
+    }
+  }
+}
+```
+
+### Over HTTP
+
+For clients that take a URL instead of a command:
+
+```
+https://snare.dev/api/mcp
+```
+
+Send the token as `Authorization: Bearer snr_...`.
+
+## What it can do
+
+| Set | Tools |
+| --- | --- |
+| `issues` | List, search, read, comment, assign, change status and severity, merge, split, see who is in the workspace |
+| `events` | Occurrences with their stacks, traces, session recordings, affected users |
+| `snares` | Launch a fix run, watch it, answer its questions, steer it, stop it, read its diff, check what is left on the plan |
+| `local` | Run a Snare here, on your own agent |
+| `feedback` | Bug reports and feature requests from your users |
+| `memory` | Project rules, standing instructions, what Snare has learned |
+| `workspace` | Projects and how the workspace is doing |
+| `setup` | Install the SDK |
+
+All of them are on by default. Narrow it with `SNARE_MCP_TOOLSETS` when you want a smaller catalogue:
+
+```
+SNARE_MCP_TOOLSETS=issues,events
+SNARE_MCP_TOOLSETS=all
+```
+
+Every tool's description is text the model reads on every turn, so narrowing leaves more room for the problem you are working on. Turning a set off means the model cannot see it at all — it will say Snare cannot do that, rather than that you switched it off.
+
+## Permissions
+
+A token carries scopes, and the server only registers tools that token can use. A read-only token sees read-only tools; the rest are not offered at all, so the model never picks one it will be refused for.
+
+Two tools spend a Snare from your plan: `launch_snare` and `start_local_snare`. The token page marks both scopes.
+
+Pick scopes when you make the token. **Read only** suits an agent that answers questions about production. **Triage** adds commenting, assigning and status changes without spending anything.
+
+## Running a Snare locally
+
+`start_local_snare` runs Snare's fix loop against the repository you have open, using your own model.
+
+Snare decides the stages, checks each answer against that stage's contract, scores the result and meters the run. Your agent does the reading and the editing. It is the same loop as a cloud run — the model and the machine are yours.
+
+Your agent calls `start_local_snare`, then `local_snare_step` in a loop until the run reports `done`. Each instruction says what to do and what to send back.
+
+Three things to know before you start one:
+
+- **It changes files in your working tree.** Commit or stash first.
+- **It spends a Snare** from your plan, the same as a cloud run.
+- **Snare cannot enforce its safety rules on your machine.** In its own sandbox they block a command before it runs. Here they are instructions to your agent. Snare will not ask your agent to do something it would have blocked, but it cannot stop your agent doing it anyway.
+
+Snare Lite and investigations do not run locally yet. Use `launch_snare` for those.
+
+## Configuration
+
+| Variable | Default |
+| --- | --- |
+| `SNARE_API_TOKEN` | required |
+| `SNARE_MCP_TOOLSETS` | `all` |
+| `SNARE_BASE_URL` | `https://snare.dev/api/v1` |
+| `SNARE_DASHBOARD_URL` | derived from `SNARE_BASE_URL` |
+
+Each has a command-line equivalent (`--token`, `--toolsets`, `--base-url`, `--dashboard-url`) which takes precedence.
+
+## Licence
+
+MIT

package/dist/bin/snare-mcp.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/snare-mcp.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { buildConfig, ConfigError } from "../src/config.js";
+import { createSnareMcpServer } from "../src/server.js";
+/**
+ * The stdio server.
+ *
+ * NOTHING MAY BE WRITTEN TO STDOUT EXCEPT PROTOCOL TRAFFIC. A single stray
+ * `console.log` corrupts the JSON-RPC stream, and the failure surfaces in the
+ * client as "the server disconnected" with no indication of why. Every message
+ * here goes to stderr, which clients show in their log panel.
+ *
+ * A CONFIG PROBLEM EXITS WITH ONE SENTENCE, not a stack. This is the first
+ * thing a new user hits, usually inside a client that shows them one line, and
+ * "SNARE_API_TOKEN is not set — get one at ..." is worth more than forty lines
+ * of frames.
+ */
+function readArg(name) {
+    const prefix = `--${name}=`;
+    const inline = process.argv.find((arg) => arg.startsWith(prefix));
+    if (inline)
+        return inline.slice(prefix.length);
+    const index = process.argv.indexOf(`--${name}`);
+    return index >= 0 ? process.argv[index + 1] : undefined;
+}
+async function main() {
+    // Argv beats env, so a client that pins a token in its own config file wins
+    // over whatever happens to be in the shell that launched it.
+    const config = buildConfig({
+        token: readArg("token") ?? process.env.SNARE_API_TOKEN,
+        baseUrl: readArg("base-url") ?? process.env.SNARE_BASE_URL,
+        dashboardUrl: readArg("dashboard-url") ?? process.env.SNARE_DASHBOARD_URL,
+        toolsets: readArg("toolsets") ?? process.env.SNARE_MCP_TOOLSETS,
+    });
+    const { server, identity } = await createSnareMcpServer(config);
+    // stderr, always. See the header.
+    console.error(`snare-mcp ready${identity.organization ? ` for ${identity.organization.name}` : ""} ` +
+        `(${identity.scopes.length} scopes, sets: ${config.toolsets.join(", ")})`);
+    await server.connect(new StdioServerTransport());
+}
+main().catch((err) => {
+    if (err instanceof ConfigError) {
+        console.error(err.message);
+        process.exit(1);
+    }
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/src/client.d.ts

@@ -0,0 +1,37 @@
+import type { McpConfig } from "./config.js";
+/**
+ * The only way this package talks to Snare.
+ *
+ * NO DATABASE, EVER. This server runs on a customer's machine. A database
+ * driver in this process would mean shipping a production connection string to
+ * everybody who runs `npx`, and the trust boundary would be "whatever the code
+ * remembers not to select" rather than a token with scopes on it. Everything
+ * goes through `/api/v1`, which is the same door the dashboard, the mobile app
+ * and any CI script use.
+ *
+ * WHICH ALSO MEANS THE TWO CANNOT DRIFT. There is no second implementation of
+ * "what an issue looks like" to keep in step with the API's, because there is
+ * no second implementation.
+ */
+/** A refusal from the API, carrying the machine-readable code the routes return. */
+export declare class SnareApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+export type FetchLike = (input: string, init: RequestInit) => Promise<Response>;
+export declare class SnareClient {
+    private readonly config;
+    private readonly fetchImpl;
+    constructor(config: McpConfig, fetchImpl?: FetchLike);
+    get dashboardUrl(): string;
+    get<T>(path: string, query?: Record<string, string | number | boolean | undefined>): Promise<T>;
+    post<T>(path: string, body?: unknown, options?: {
+        timeoutMs?: number;
+        retry?: boolean;
+    }): Promise<T>;
+    patch<T>(path: string, body?: unknown): Promise<T>;
+    put<T>(path: string, body?: unknown): Promise<T>;
+    delete<T>(path: string, body?: unknown): Promise<T>;
+    private request;
+}

package/dist/src/client.js

@@ -0,0 +1,137 @@
+/**
+ * The only way this package talks to Snare.
+ *
+ * NO DATABASE, EVER. This server runs on a customer's machine. A database
+ * driver in this process would mean shipping a production connection string to
+ * everybody who runs `npx`, and the trust boundary would be "whatever the code
+ * remembers not to select" rather than a token with scopes on it. Everything
+ * goes through `/api/v1`, which is the same door the dashboard, the mobile app
+ * and any CI script use.
+ *
+ * WHICH ALSO MEANS THE TWO CANNOT DRIFT. There is no second implementation of
+ * "what an issue looks like" to keep in step with the API's, because there is
+ * no second implementation.
+ */
+/** A refusal from the API, carrying the machine-readable code the routes return. */
+export class SnareApiError extends Error {
+    status;
+    code;
+    constructor(status, code, message) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.name = "SnareApiError";
+    }
+}
+/**
+ * Statuses worth trying again.
+ *
+ * A 5xx is the server having a bad moment and a 429 is a rate limit that will
+ * pass. Everything else — a bad request, a missing scope, a row that is not
+ * there — will fail identically the second time, and retrying it turns one
+ * clear refusal into three and a longer wait before the model sees it.
+ */
+function retryable(status) {
+    return status === 429 || status >= 500;
+}
+const ATTEMPTS = 3;
+export class SnareClient {
+    config;
+    fetchImpl;
+    constructor(config, fetchImpl = globalThis.fetch) {
+        this.config = config;
+        this.fetchImpl = fetchImpl;
+    }
+    get dashboardUrl() {
+        return this.config.dashboardUrl;
+    }
+    get(path, query) {
+        return this.request("GET", withQuery(path, query));
+    }
+    post(path, body, options) {
+        return this.request("POST", path, body, options);
+    }
+    patch(path, body) {
+        return this.request("PATCH", path, body);
+    }
+    put(path, body) {
+        return this.request("PUT", path, body);
+    }
+    delete(path, body) {
+        return this.request("DELETE", path, body);
+    }
+    async request(method, path, body, options) {
+        const url = `${this.config.baseUrl}${path}`;
+        const timeoutMs = options?.timeoutMs ?? this.config.requestTimeoutMs;
+        // Retrying is right for a stateless read and wrong for a call that is
+        // already a long poll: a local run's step holds for up to twenty-five
+        // seconds by design, so three attempts against a slow or unreachable
+        // orchestrator is a tool call that hangs for two minutes and then reports
+        // a failure the first attempt already knew about. Measured, not guessed —
+        // a live pass against a stopped orchestrator produced exactly that.
+        const attempts = options?.retry === false ? 1 : ATTEMPTS;
+        let lastError = null;
+        for (let attempt = 1; attempt <= attempts; attempt += 1) {
+            let response;
+            try {
+                response = await this.fetchImpl(url, {
+                    method,
+                    headers: {
+                        authorization: `Bearer ${this.config.token}`,
+                        "content-type": "application/json",
+                        // Named so a customer reading their own audit log can tell a call
+                        // from their editor apart from one from a CI script.
+                        "user-agent": "snare-mcp",
+                    },
+                    ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+            }
+            catch (err) {
+                // A network failure or a timeout. Retried like a 5xx, and reported
+                // without the underlying message, which is usually a DNS error nobody
+                // can act on.
+                lastError = new SnareApiError(0, "unreachable", "Could not reach Snare.");
+                if (attempt === attempts)
+                    throw lastError;
+                await backoff(attempt);
+                continue;
+            }
+            if (response.ok) {
+                if (response.status === 204)
+                    return undefined;
+                return (await response.json());
+            }
+            const payload = (await response.json().catch(() => null));
+            lastError = new SnareApiError(response.status, payload?.code ?? "unknown", 
+            // The server's own sentence, because the routes are written to be read:
+            // a missing scope names the scope, a conflict says what is in the way.
+            // Inventing a message here would replace a specific one with a generic.
+            payload?.error ?? `Snare answered ${response.status}.`);
+            if (!retryable(response.status) || attempt === attempts)
+                throw lastError;
+            await backoff(attempt);
+        }
+        throw lastError ?? new SnareApiError(0, "unknown", "Could not reach Snare.");
+    }
+}
+function backoff(attempt) {
+    // 200ms, then 400ms. Short on purpose: a person is waiting on the other end
+    // of this, and a retry schedule measured in seconds turns a transient blip
+    // into an agent that appears to have hung.
+    return new Promise((resolve) => setTimeout(resolve, 200 * 2 ** (attempt - 1)));
+}
+function withQuery(path, query) {
+    if (!query)
+        return path;
+    const params = new URLSearchParams();
+    for (const [key, value] of Object.entries(query)) {
+        // Undefined means "not asked for" and must not become the string
+        // "undefined", which every one of these routes would reject as a bad value.
+        if (value === undefined)
+            continue;
+        params.set(key, String(value));
+    }
+    const encoded = params.toString();
+    return encoded ? `${path}?${encoded}` : path;
+}

package/dist/src/config.d.ts

@@ -0,0 +1,84 @@
+import { type Toolset } from "./toolsets.js";
+/**
+ * What the server needs to know before it can do anything.
+ *
+ * ONE OBJECT, PASSED IN, NEVER READ FROM `process.env` DEEPER IN. The stdio
+ * binary reads the environment; the remote transport reads a request header.
+ * Anything below this file that reached for `process.env` would work in one of
+ * those and silently do nothing in the other, and the failure would look like a
+ * broken token rather than a missing branch.
+ */
+export interface McpConfig {
+    /** Where the API lives, without a trailing slash. */
+    baseUrl: string;
+    /** The `snr_` token. Never logged, never included in an error message. */
+    token: string;
+    /** Which groups of tools to register. See `toolsets.ts`. */
+    toolsets: Toolset[];
+    /** How long any one API call may take. */
+    requestTimeoutMs: number;
+    /** Where a person opens what a tool is describing. */
+    dashboardUrl: string;
+}
+export declare const DEFAULT_BASE_URL = "https://snare.dev/api/v1";
+export declare const DEFAULT_DASHBOARD_URL = "https://snare.dev";
+/**
+ * How long a call may take.
+ *
+ * Thirty seconds rather than the default none. Every tool here is one HTTP
+ * round trip to a route that does a handful of queries, so a call still running
+ * after thirty seconds is a call that is not coming back — and an MCP client
+ * with no timeout of its own will sit on it forever, which reads to the person
+ * watching as the agent having stopped.
+ *
+ * The local-run step tool overrides this: it deliberately blocks for up to
+ * twenty-five seconds on the server side before answering, so its own ceiling
+ * has to be higher than that or the poll would time out exactly when it worked.
+ */
+export declare const DEFAULT_TIMEOUT_MS = 30000;
+export declare class ConfigError extends Error {
+}
+/**
+ * Builds a config, or explains what is missing.
+ *
+ * THE MESSAGE MATTERS MORE THAN THE VALIDATION. This is the first thing a new
+ * user hits, usually inside a client that shows them one line of stderr, so a
+ * missing token says which variable to set and where to get one rather than
+ * throwing a stack trace about an undefined property.
+ */
+export declare function buildConfig(input: {
+    token?: string | undefined;
+    baseUrl?: string | undefined;
+    dashboardUrl?: string | undefined;
+    toolsets?: string | undefined;
+    requestTimeoutMs?: number | undefined;
+}): McpConfig;
+/**
+ * Which groups to turn on.
+ *
+ * An unknown name is refused rather than ignored. Ignoring it means somebody
+ * who typed `issue` instead of `issues` gets the default set, sees roughly the
+ * tools they expected, and never finds out their configuration did nothing.
+ */
+export declare function parseToolsets(raw: string | undefined): Toolset[];
+/**
+ * What a caller gets without asking: everything.
+ *
+ * IT USED TO BE FOUR SETS, on the reasoning that every registered tool is
+ * schema a model reads on every single turn, so a catalogue nobody is going to
+ * call costs context that could have gone on the bug. That reasoning is sound
+ * and it was still the wrong default, for a reason only visible once an agent
+ * used it: a model cannot tell "Snare does not do this" from "that set is not
+ * switched on", and it says the first. Asked what people were requesting, an
+ * agent answered that Snare has no feature-request surface at all — a false
+ * statement about the product, made confidently, to a customer. Another could
+ * not assign an issue because the tool for finding who to assign to was in a
+ * set nobody turns on.
+ *
+ * The cost of the old default was paid by everybody who did not know to change
+ * it, and it was paid in wrong answers. The cost of this one is context, on the
+ * turns where a set goes unused, and it is one environment variable to reclaim:
+ * `SNARE_MCP_TOOLSETS=issues,events` narrows it to whatever a caller actually
+ * wants.
+ */
+export declare const DEFAULT_TOOLSETS: readonly Toolset[];

package/dist/src/config.js

@@ -0,0 +1,103 @@
+import { TOOLSETS } from "./toolsets.js";
+export const DEFAULT_BASE_URL = "https://snare.dev/api/v1";
+export const DEFAULT_DASHBOARD_URL = "https://snare.dev";
+/**
+ * How long a call may take.
+ *
+ * Thirty seconds rather than the default none. Every tool here is one HTTP
+ * round trip to a route that does a handful of queries, so a call still running
+ * after thirty seconds is a call that is not coming back — and an MCP client
+ * with no timeout of its own will sit on it forever, which reads to the person
+ * watching as the agent having stopped.
+ *
+ * The local-run step tool overrides this: it deliberately blocks for up to
+ * twenty-five seconds on the server side before answering, so its own ceiling
+ * has to be higher than that or the poll would time out exactly when it worked.
+ */
+export const DEFAULT_TIMEOUT_MS = 30_000;
+export class ConfigError extends Error {
+}
+/**
+ * Builds a config, or explains what is missing.
+ *
+ * THE MESSAGE MATTERS MORE THAN THE VALIDATION. This is the first thing a new
+ * user hits, usually inside a client that shows them one line of stderr, so a
+ * missing token says which variable to set and where to get one rather than
+ * throwing a stack trace about an undefined property.
+ */
+export function buildConfig(input) {
+    const token = input.token?.trim();
+    if (!token) {
+        throw new ConfigError("No Snare token. Set SNARE_API_TOKEN to a token from https://snare.dev/settings/api-tokens.");
+    }
+    if (!token.startsWith("snr_")) {
+        // Caught here rather than at the first 401, because "that token is not
+        // usable" from the server is deliberately vague and would send somebody
+        // looking for a revoked token when they had actually pasted a project key.
+        throw new ConfigError('That does not look like a Snare token. They begin with "snr_".');
+    }
+    const baseUrl = (input.baseUrl?.trim() || DEFAULT_BASE_URL).replace(/\/$/, "");
+    const dashboardUrl = (input.dashboardUrl?.trim() || deriveDashboardUrl(baseUrl)).replace(/\/$/, "");
+    return {
+        token,
+        baseUrl,
+        dashboardUrl,
+        toolsets: parseToolsets(input.toolsets),
+        requestTimeoutMs: input.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS,
+    };
+}
+/**
+ * The dashboard is the API's base with the API path taken off.
+ *
+ * Derived rather than required, so somebody pointing this at a staging
+ * deployment sets one variable instead of two and cannot set them
+ * inconsistently. `SNARE_DASHBOARD_URL` overrides it for the case where they
+ * really are on different hosts.
+ */
+function deriveDashboardUrl(baseUrl) {
+    return baseUrl.replace(/\/api\/v1$/, "") || DEFAULT_DASHBOARD_URL;
+}
+/**
+ * Which groups to turn on.
+ *
+ * An unknown name is refused rather than ignored. Ignoring it means somebody
+ * who typed `issue` instead of `issues` gets the default set, sees roughly the
+ * tools they expected, and never finds out their configuration did nothing.
+ */
+export function parseToolsets(raw) {
+    const value = raw?.trim();
+    if (!value)
+        return [...DEFAULT_TOOLSETS];
+    if (value === "all")
+        return [...TOOLSETS];
+    const names = value
+        .split(",")
+        .map((name) => name.trim())
+        .filter(Boolean);
+    const unknown = names.filter((name) => !TOOLSETS.includes(name));
+    if (unknown.length > 0) {
+        throw new ConfigError(`Unknown tool set: ${unknown.join(", ")}. Pick from ${TOOLSETS.join(", ")}, or "all".`);
+    }
+    return names;
+}
+/**
+ * What a caller gets without asking: everything.
+ *
+ * IT USED TO BE FOUR SETS, on the reasoning that every registered tool is
+ * schema a model reads on every single turn, so a catalogue nobody is going to
+ * call costs context that could have gone on the bug. That reasoning is sound
+ * and it was still the wrong default, for a reason only visible once an agent
+ * used it: a model cannot tell "Snare does not do this" from "that set is not
+ * switched on", and it says the first. Asked what people were requesting, an
+ * agent answered that Snare has no feature-request surface at all — a false
+ * statement about the product, made confidently, to a customer. Another could
+ * not assign an issue because the tool for finding who to assign to was in a
+ * set nobody turns on.
+ *
+ * The cost of the old default was paid by everybody who did not know to change
+ * it, and it was paid in wrong answers. The cost of this one is context, on the
+ * turns where a set goes unused, and it is one environment variable to reclaim:
+ * `SNARE_MCP_TOOLSETS=issues,events` narrows it to whatever a caller actually
+ * wants.
+ */
+export const DEFAULT_TOOLSETS = [...TOOLSETS];

package/dist/src/format.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Turning a record into the text a model reads.
+ *
+ * THIS FILE IS WHY THE TOOLS ARE USABLE. The difference between a tool an agent
+ * uses well and one it uses badly is mostly the shape of what comes back. Raw
+ * JSON rows make a model rebuild the domain on every call: it has to work out
+ * that `IN_PROGRESS` is a status, that `null` in one field means nobody and in
+ * another means zero, and that 11747 is seconds. Every one of those is a chance
+ * to get it wrong in a sentence somebody then reads.
+ *
+ * So every response is text, led by one line saying what it is, with the
+ * structured facts underneath in a fixed shape. The rules below are the same
+ * ones the product's own UI follows, for the same reasons — they are in
+ * CLAUDE.md and they are not arbitrary.
+ */
+/**
+ * No value, and visibly not zero.
+ *
+ * An em dash rather than "none", "null" or an empty string: a reader (human or
+ * model) has to be able to tell "nobody is assigned" from "zero people are
+ * assigned", and every text form of absence collides with some real value
+ * somewhere.
+ */
+export declare const DASH = "\u2014";
+/** Sentence case for an enum. `IN_PROGRESS` is a column value, "In progress" is language. */
+export declare function label(value: string | null | undefined): string;
+/**
+ * A duration in human units, never a clock and never raw seconds.
+ *
+ * Two units at most: "3 hrs 15 min", not "3 hrs 15 min 47 s". The third unit is
+ * always noise at the scale the second one is already showing, and a reader
+ * skimming a list stops at the first two anyway.
+ */
+export declare function duration(seconds: number | null | undefined): string;
+/**
+ * How far away a moment is, in either direction.
+ *
+ * The ISO timestamp is always alongside it: this is the part somebody reads,
+ * that is the part they compute with.
+ *
+ * THE FUTURE IS A REAL CASE HERE and used to be clamped to zero, which rendered
+ * every one of them as "just now". Not everything this formats has happened:
+ * a billing period ends, a trial expires, a question's window closes. "This
+ * period ends 2026-10-07 (just now)" is a sentence that contradicts itself, and
+ * the reader it misleads is the one deciding whether they can afford to start
+ * a run.
+ */
+export declare function ago(iso: string | null | undefined, now?: Date): string;
+/**
+ * A moment, to the minute, without the machine punctuation.
+ *
+ * `2026-09-06 08:52` rather than `2026-09-06T08:52:58.296Z`. The `T`, the
+ * seconds and the milliseconds are three pieces of precision no answer about an
+ * issue has ever needed, and in a column of forty rows they are most of the
+ * width. Always UTC, because a server-rendered local time is a time in a
+ * timezone the reader cannot see.
+ */
+export declare function stamp(iso: string | null | undefined): string;
+/**
+ * A moment AND how long ago it was: `2026-09-06 08:52 UTC (1 d ago)`.
+ *
+ * For detail cards, where there is room for both and both get used. "Last seen"
+ * answers two different questions — is this still happening, and exactly when
+ * did it last happen — and a bare timestamp only answers the second, leaving
+ * the model to do date arithmetic in prose. It gets that wrong often enough
+ * that giving it the answer is worth the twelve characters.
+ *
+ * `ago()` alone is not enough here for the opposite reason: "3 d ago" cannot be
+ * quoted into a report, correlated with a deploy, or compared with anything.
+ */
+export declare function when(iso: string | null | undefined, now?: Date): string;
+/**
+ * A quantity that agrees with its noun: "1 occurrence", "4 occurrences".
+ *
+ * `count()` above covers "12 of 340 issues". This covers the plain case, which
+ * was being written inline as `${n} issues` in six places and produced
+ * "1 occurrences", "1 issues" and "1 sessions" in real output. A model reading
+ * that is fine; a person reading the sentence the model then writes is reading
+ * a mistake the product made, and the fix is one function rather than six
+ * ternaries nobody will remember to add the seventh time.
+ */
+export declare function quantity(amount: number, noun: string, plural?: string): string;
+/**
+ * A count that says what it is out of.
+ *
+ * "12 of 340 issues", never "12". A list that does not say what it is a slice of
+ * is a list whose answer changes meaning depending on something the reader
+ * cannot see, and an agent reporting "there are 12 open issues" from a page of
+ * 12 has said something false.
+ */
+export declare function count(shown: number, total: number, noun: string, plural?: string): string;
+/** `Label: value`, with absence rendered as the dash rather than omitted. */
+export declare function line(name: string, value: string | number | null | undefined): string;
+/** A block of `Label: value` lines, blanks dropped, in the order given. */
+export declare function facts(entries: Array<[string, string | number | null | undefined]>): string;
+/**
+ * A tool's whole answer: one summary line, a blank, then the body.
+ *
+ * The summary exists so a model that reads nothing else still knows what it got.
+ * It is also what a client renders in a collapsed tool-call row, which is the
+ * only thing many readers will ever see of this.
+ */
+export declare function toolText(summary: string, ...blocks: Array<string | null | undefined>): string;
+/** A bulleted list, or a sentence saying there is nothing. */
+export declare function bullets(items: readonly string[], emptyMessage: string): string;
+/**
+ * Truncates a long free-text field for a list row.
+ *
+ * A stack trace or a comment thread pasted whole into a fifty-row listing is
+ * the single easiest way to fill a context window with something nobody asked
+ * for. Detail calls return the whole thing; lists return this.
+ */
+export declare function clip(text: string | null | undefined, max?: number): string;
+/** A percentage from a 0-1 score, or the dash. Confidence and similarity both use this. */
+export declare function percent(value: number | null | undefined): string;
+/**
+ * A whole number with thousands separators.
+ *
+ * `50000` and `49953` next to each other in one sentence are two five-digit
+ * runs a reader has to count digits to tell apart, and a model asked to
+ * summarise "47 of 50000 used, 49953 left" reported it back as "49,953 of 50k
+ * used" — the opposite of the truth, on a line about somebody's bill.
+ */
+export declare function num(value: number | null | undefined): string;
+/** Money, always with the unit, because a bare number here reads as anything. */
+export declare function usd(value: number | null | undefined): string;