@descryy/mcp 0.11.5 → 0.11.7

package/dist/render.d.ts

@@ -0,0 +1,623 @@
+/**
+ * The one way an engine answer becomes an MCP tool result.
+ *
+ * ## Why this file exists rather than each tool formatting its own reply
+ *
+ * `QueryResult` carries three things a caller would rather not think about: a
+ * staleness stamp (§27.3), a `truncated` flag, and `notes` — the plain-words
+ * disclosures that populate the five result states' `refused`/`empty`/`failed`/
+ * `timed_out` cases. The engine computes all three correctly today. Every one of
+ * them is one careless `return result.data` away from never reaching a user.
+ *
+ * So the tool handler's return type is `QueryResult`, not content. A handler
+ * *cannot* build a reply; it can only produce an answer, and this module is the
+ * only thing that turns an answer into frames. Rule 7 — honest degradation, no
+ * silent doing-less — becomes a property of the type system rather than of
+ * whoever writes the next tool.
+ *
+ * ## `ai-tool-contract.md` §2 — the frozen envelope
+ *
+ * This module used to ship a two-value `status: "ok" | "not_analysable"`. The
+ * contract froze five: `ok` / `empty` / `refused` / `failed` / `timed_out`
+ * (§1), plus `class`, `toolVersion`, `budget` and a structured `truncated`
+ * object (§2). `AnswerStatus`/`renderAnswer`'s old two-state shape is gone
+ * rather than kept alongside the new one — two envelope shapes on the wire is
+ * the thing DEC-277's "one process mints" reasoning exists to avoid one layer
+ * up, applied here to a type rather than a decision number.
+ *
+ * ## Four invariants, asserted rather than documented (§2.1)
+ *
+ * `render.ts` already enforced the first two; the other two are new.
+ *
+ * 1. `truncated != null` with empty `disclosures` → throw.
+ * 2. `state` in `{refused, failed, timed_out}` with empty `disclosures` → throw.
+ * 3. `state == "refused"` with no verbatim reason in `disclosures` → throw (§4).
+ * 4. `class == "action"` returning anything other than a handshake envelope on
+ *    the first call → throw (§7) — enforced in `action-handshake.ts` and
+ *    `server.ts`, not here: this module never sees a mint, only a redeemed run.
+ *
+ * ## A fifth invariant, B6: a truncated answer must carry real counts
+ *
+ * `result.truncated === true` with no `answer.truncatedDetail` used to fall
+ * back to a sentinel, `{shown: -1, total: -1}` — chosen to be "unmistakably
+ * fake," except that it is a number, so it passes any presence check and then
+ * poisons whatever arithmetic reads `total - shown`. A field that lies is
+ * worse than a field that is absent, which is the same argument the five
+ * result states rest on. So the sentinel is gone: a tool that sets
+ * `result.truncated` without a `truncatedDetail` is a programming error,
+ * thrown in every environment except production, where the envelope instead
+ * reports `truncated: null` plus a disclosure naming the gap — degraded
+ * honestly rather than dishonestly precise. See `capped()` in `./capped.ts`
+ * for how a tool is meant to avoid ever hitting this.
+ */
+import { type ReliabilityClass, type ReportCategory } from "@descryy/ir";
+import type { ResultState, SignalTypeCount, ToolClass } from "@descryy/ir";
+import type { GraphFreshness, GraphStamp, QueryResult } from "@descryy/core";
+import type { DisclosureLedger } from "./disclosure-ledger.ts";
+export type { ResultState } from "@descryy/ir";
+/**
+ * MK-5 — which of the sixteen tools states a conclusion about the user's code
+ * versus which reports a fact about the graph.
+ *
+ * Lives here rather than in `@descryy/ir`: `tool-surface.ts`'s own header
+ * scopes that file to exactly `ResultState` and `ToolClass` ("and nothing
+ * else"), because those two cross into the pipeline and the desktop surface.
+ * This distinction is agent-mode-only (`plugin-and-mcp-surface.md` §3 PL-1),
+ * so a third shared union there would be scope creep the file's own doc
+ * disclaims. `kit.ts` imports it from here rather than the reverse, because
+ * `kit.ts` already depends on this module for `ToolAnswer`/`TruncationDetail`
+ * — defining it in `kit.ts` instead would make this module import back from
+ * `kit.ts` and cycle.
+ *
+ * - `conclusion` — the output is a statement about the user's code
+ *   (`validate`, `contracts`, `cross_pr`). Never raw candidates: an
+ *   already-adjudicated result carrying the category and the disclosure
+ *   sentence as one payload.
+ * - `evidence` — the output is a fact the graph computed, already carrying
+ *   its own resolution and qualification. The other thirteen.
+ */
+export declare const TOOL_TIERS: readonly ["conclusion", "evidence"];
+export type ToolTier = (typeof TOOL_TIERS)[number];
+/**
+ * MK-6 — a conclusion produced through this server must not carry the same
+ * badge as one produced by the app's full governance pipeline
+ * (`plugin-and-mcp-surface.md` §3 PL-4). Every value here is a fact about
+ * *this server*, not about any one call, so it is one constant reused on
+ * every envelope rather than a per-tool computation.
+ */
+export interface Provenance {
+    readonly surface: "mcp";
+    readonly adjudicatedBy: "descry";
+    readonly presentedBy: "host-agent";
+    /** MK-11: the G1–G5 governance pipeline does not run in this surface. */
+    readonly governancePipeline: false;
+}
+export interface TruncationDetail {
+    /** How many of the primary collection are in this reply. */
+    readonly shown: number;
+    /** The count before the cap — §5.5: "the count before the cap". */
+    readonly total: number;
+    /** A cursor to fetch the rest. `null` until pagination exists to redeem one. */
+    readonly more: string | null;
+}
+/**
+ * What a tool that actually watched a running application declares about what
+ * it saw — G4's `E`, and by its presence G3's precondition.
+ *
+ * **Presence is the claim, not the count.** A tool constructs this only on a
+ * path where an execution really ran and evidence really came back; omitting
+ * it is how every other tool says "nothing was witnessed here", which is the
+ * safe default and the one thirty-one of the thirty-three tools take. The two
+ * that declare it are `observe_runtime` and `observe_tests` — the two that
+ * run something.
+ *
+ * `E` is a count of *channels*, not of records: six console messages are one
+ * signal type, a console message plus a network response are two
+ * (`@descryy/ir`'s {@link RUNTIME_SIGNAL_TYPES}). Compute it with that
+ * package's `independentSignalTypes` rather than counting here — the clamp to
+ * the six declared channels is its job, and a second implementation of it is a
+ * second place for the vocabulary to drift.
+ *
+ * There is deliberately no `M` field — see `deriveEnvelopeCategory`.
+ */
+export interface WitnessedEvidence {
+    readonly independentSignalTypes: SignalTypeCount;
+}
+export interface ToolAnswer<T> {
+    readonly result: QueryResult<T>;
+    /**
+     * Present only on a path that observed a real running application. Absent
+     * everywhere else, which is what makes `unconfirmed` the default for a
+     * graph-only answer rather than something each tool must remember to ask
+     * for. See {@link WitnessedEvidence} and `AnswerEnvelope.reportCategory`.
+     */
+    readonly runtimeEvidence?: WitnessedEvidence;
+    /**
+     * One of the five result states (§1). Omitted means `"ok"` — the common
+     * case, and the one that needs no tool-author ceremony.
+     *
+     * `"empty"` is a claim a tool must *earn* (§1.3b): reach for it only when
+     * the search ran against a population known to be real (an `analysed`/`ran`
+     * flag already true, a resolved node, a read that completed). Default to
+     * `"refused"` when that is not established — never to `"ok"` with a quietly
+     * empty collection, which is the exact defect §1 exists to close.
+     */
+    readonly state?: ResultState;
+    /**
+     * Is this a claim about a *name* or about a *shape*? §11A.5 gives R2 two
+     * different caps depending on the answer, so it is required rather than
+     * defaulted — see `reliabilityCap`.
+     */
+    readonly nameLevel: boolean;
+    /** One line the agent reads first. The payload is underneath it. */
+    readonly headline: string;
+    /**
+     * Present only when the tool already computed `shown`/`total` for its
+     * primary list at the return site (most do, for the "N further… capped at
+     * limit" note). `null` falls back to a bare boolean-shaped truncation with
+     * no counts — still non-null per invariant 1, just less informative.
+     */
+    readonly truncatedDetail?: TruncationDetail;
+    /**
+     * §5.4's `refusals` field, populated by a tool whose *own call* produced a
+     * fresh population of `UnresolvedRef` rows to summarise — as opposed to
+     * `refusal_fetch`, which pages the whole graph's stored ledger. `analyze`
+     * is the one tool that fits today: a run reads sources and the refs it
+     * could not resolve are this call's own result, not a read of prior state.
+     * Omit when the tool has no such population, or when it summarised zero
+     * rows — an empty summary carries no exemplar or handle to show.
+     */
+    readonly refusalSummary?: {
+        readonly count: number;
+        readonly exemplar: string;
+        readonly handle: string;
+    };
+    /**
+     * How this tool shrinks its own reply when the rendered result would exceed
+     * `MAX_REPLY_BYTES`. Called with the bytes available for `data` alone, every
+     * other cost already subtracted; called again with a corrected figure if the
+     * first attempt still comes in over.
+     *
+     * Optional, and absent means today's behaviour — the reply is rendered at
+     * whatever size it comes to. A tool whose payload is already bounded (a node
+     * `limit`, a single verdict) needs no hook; a tool whose reply grows with the
+     * user's repository does, and `get_git_diff` is the one that proved it.
+     */
+    readonly fitToBudget?: (budgetBytes: number) => ReplyFit<T>;
+}
+/**
+ * The ceiling on one rendered tool result, serialized — `content` frame and
+ * `structuredContent` envelope together, which is what a host actually
+ * receives and counts.
+ *
+ * A starting value, not a measurement, in this repo's usual sense: the one
+ * hard number behind it is a real failure, `get_git_diff` on an ordinary
+ * 48-file branch diff returning 84,516 characters and being rejected outright
+ * by the host before the caller saw any of it. 60,000 sits well under the
+ * smallest size observed to fail, with room for the narrated frame that
+ * repeats the disclosures alongside the envelope.
+ *
+ * Shared rather than per-tool on purpose: `get_git_diff` is the tool that hit
+ * this, twice, but nothing about the failure was specific to diffs. Any tool
+ * adopts the ceiling by implementing `ToolAnswer.fitToBudget`.
+ */
+export declare const MAX_REPLY_BYTES = 60000;
+/**
+ * A tool's own answer to "make this fit in `budgetBytes`".
+ *
+ * Only the tool can shrink its payload honestly — which field is droppable,
+ * what the caller must be told about the drop, and what re-request would
+ * recover it are all facts about that tool. So the ceiling is enforced here
+ * and the shrinking is delegated, rather than this module truncating a shape
+ * it does not understand.
+ */
+export interface ReplyFit<T> {
+    readonly data: T;
+    /**
+     * Disclosures naming exactly what the budget withheld — appended to the
+     * tool's own notes. Must be non-empty whenever anything was withheld or
+     * dropped: a reply shrunk in silence is the failure rule 7 exists to stop.
+     */
+    readonly notes: readonly string[];
+    /** Set when items left the reply entirely, not merely lost their payload. */
+    readonly truncatedDetail?: TruncationDetail;
+}
+export interface McpContent {
+    readonly type: "text";
+    readonly text: string;
+}
+export interface CallToolResult {
+    readonly content: readonly McpContent[];
+    readonly structuredContent: Record<string, unknown>;
+    readonly isError?: boolean;
+}
+/**
+ * The machine-readable envelope. Shape is stable across every tool.
+ *
+ * `T` is the tool's own `data` type — every tool exports one (`ImpactData`,
+ * `ScopeData`, …) and types its handler against it, so `tsc` rejects a handler
+ * that returns a shape the declaration does not name. The parameter defaults
+ * to `unknown` so a caller handling any tool's reply generically still type
+ * checks; a caller that knows which tool it called writes
+ * `AnswerEnvelope<ImpactData>` and gets the shape.
+ */
+export interface AnswerEnvelope<T = unknown> {
+    readonly tool: string;
+    /** Contract §6, rule 8. A behaviour change is a version bump; recorded with the run. */
+    readonly toolVersion: string;
+    /**
+     * B10 — this call's own id in `Session#recordedCalls()`, minted before
+     * rendering (`Session#allocateCallId`) so it can be carried here rather
+     * than only discovered after the fact. A caller reads this off a real
+     * reply and cites it in `verify_claim`'s `callId` — the positive path that
+     * was previously unreachable because the id used to be minted only when
+     * `Session#recordCall` ran, one step after the envelope that would have
+     * carried it was already built and sent. Not recorded here — `verify_claim`
+     * itself is excluded from `Session#recordCall` (MK-12) and every other
+     * path still records under this same value, so the id an agent reads is
+     * always the id `recordedCall` will actually find.
+     */
+    readonly callId: string;
+    readonly state: ResultState;
+    /** DEC-278's three classes — §6's retry table reads this. */
+    readonly class: ToolClass;
+    readonly headline: string;
+    /** `null` on `failed` (§2.2: always). May carry disambiguation, never an answer, on `refused`. */
+    readonly data: T | null;
+    readonly graph: {
+        readonly commitSha: string | null;
+        readonly builtAt: string | null;
+        readonly irSchemaVersion: number;
+        /** `null` — never absent — when the graph was not consulted at all (§3). */
+        readonly resolutionFloor: number | null;
+        readonly reliabilityCap: ReliabilityClass;
+        /**
+         * Lane "map-freshness" item 1: whether this graph still matches the
+         * repository on disk, distinct from `commitSha`/`builtAt` alone — a
+         * caller reading only the stamp has no way to tell "built five minutes
+         * ago" from "built five hundred commits ago" without running git itself.
+         * `null` only when `commitSha` is `null` (an empty graph has nothing to
+         * be fresh or stale relative to). Otherwise never absent, and `unknown`
+         * — never `current` — when this could not be determined (not a git
+         * repository, or git itself unavailable here); see `computeGraphFreshness`
+         * (`@descryy/core`) for how it is computed.
+         */
+        readonly freshness: {
+            readonly status: "current" | "behind" | "unknown";
+            /** `null` when `status !== "behind"`, or when `behind` but the exact
+             *  count could not be determined (history rewritten since the build) —
+             *  never a substitute for `0`. */
+            readonly commitsSince: number | null;
+            /** Count of indexed files that differ from the build, or `null` when
+             *  `status !== "behind"`. The files themselves are named in `disclosures`
+             *  (up to 5), not repeated here. */
+            readonly changedIndexedFiles: number | null;
+        } | null;
+    };
+    readonly truncated: TruncationDetail | null;
+    /**
+     * §5.4. `null` unless the answering tool supplied `refusalSummary` — see
+     * that field's own doc for which tools have a population to summarise.
+     */
+    readonly refusals: {
+        readonly count: number;
+        readonly exemplar: string;
+        readonly handle: string;
+    } | null;
+    readonly budget: {
+        readonly elapsedMs: number;
+        readonly limitMs: number;
+    };
+    /** Never empty when the answer is degraded, truncated or refused/failed/timed-out. */
+    readonly disclosures: readonly string[];
+    /**
+     * N2 step 3 — a machine-readable qualifier on this reply, not a sixth
+     * `state`: `true` means the running server's in-memory configuration no
+     * longer matches `.descry/config.json` on disk (another session's edit, a
+     * `link_workspace` call, a hand edit), so everything else in this envelope
+     * — including `graph` and `reportCategory` — reflects the stale, running
+     * configuration rather than what is on disk now. A caller can branch on
+     * this directly instead of pattern-matching prose in `disclosures`, where
+     * the same fact is also stated in full for a human reader.
+     */
+    readonly configStale: boolean;
+    /**
+     * MK-8/MK-11 — §19's five categories, settled for this surface: a
+     * `conclusion`-tier tool states its verdict in `headline`'s own plain words
+     * rather than through this apparatus (it is a fact, not a hypothesis), so
+     * this is `null` there. For an `evidence`-tier tool: `refused` maps to the
+     * direct equivalent, `not analysable` ("could not look" vs. "cannot
+     * establish this here" are the same statement); `failed`/`timed_out` carry
+     * no claim at all, so `null`; `ok`/`empty` go through G3/G4.
+     *
+     * **A graph-only answer short-circuits at G3 and is `unconfirmed`** — a
+     * structural fact with no runtime corroboration is never `confirmed` by
+     * construction, whatever its resolution.
+     *
+     * **An answer that watched a running application does not.** MK-8 was
+     * written when nothing in this surface could witness anything, and its
+     * "descry-runtime's loop does not run inside an MCP call" was true then;
+     * `observe_runtime` composes descry-runtime, boots or attaches to a real
+     * application and writes R4 edges, so it is now false for exactly the tools
+     * that do. Such a tool declares {@link ToolAnswer.runtimeEvidence} and G4
+     * runs on what it actually saw. Reporting a witnessed result more weakly
+     * than the evidence under it inverts rule 2's whole purpose, which is why
+     * this is a defect rather than conservatism.
+     *
+     * `confirmed` stays unreachable from here regardless — DEC-334 reserves it
+     * for a result that passed the full governance pipeline, "on every surface,
+     * meaning the same thing everywhere", and that pipeline does not run in an
+     * MCP call (`provenance.governancePipeline` says so on every reply). So
+     * `strongly supported` is this surface's ceiling, and it is reached by
+     * evidence rather than granted.
+     */
+    readonly reportCategory: ReportCategory | null;
+    /**
+     * **Existence** — how strongly the evidence says the failure is *real*, read from what was
+     * observed and never capped by how well the code resolved
+     * (`documents/plans/gate_loosening.md` §3.3).
+     *
+     * `reportCategory` above answers a different question — how strongly the *cause* may be
+     * stated — and rule 3's cap governs it alone. The two separate exactly where it matters: a
+     * reply whose graph resolved nothing (R0) caps to `unconfirmed` however much was witnessed,
+     * because at R0 no cause has been established. That is a true statement about the cause and
+     * a misleading one about the failure, and this field is the second half.
+     *
+     * Null wherever no evidence reading was taken at all — conclusion-tier tools, faults, and
+     * refusals. A refusal is a fact about Descry, never about the application, so it declares no
+     * existence rather than declaring `unconfirmed`, which would read as "we looked and found
+     * nothing."
+     *
+     * `confirmed` is unreachable here for the same reason it is above: `M` is not offered on this
+     * surface, so `strongly supported` is the ceiling.
+     */
+    readonly existenceCategory: ReportCategory | null;
+    /** MK-6. Constant for this server — see `Provenance`'s own doc. */
+    readonly provenance: Provenance;
+}
+/**
+ * The envelope, declared for a host to validate against — MCP's `outputSchema`.
+ *
+ * ## Why this exists at all
+ *
+ * Every reply from this server carries `structuredContent`, and until this was
+ * added a host had no way to check what it received. `tools/list` already ships
+ * `class`, `tier` and `toolVersion` on the same reasoning — a fact about the
+ * reply that an external client cannot otherwise read — and this is the
+ * standard-shaped member of that group rather than a fourth non-standard field.
+ *
+ * ## `data` is deliberately open, and that is a disclosed gap
+ *
+ * The envelope's thirteen fields are uniform across all thirty-three tools, so they
+ * are described exactly. `data` is not: its shape is `ImpactData`, `ScopeData`
+ * and thirty-one others, and nothing today derives a JSON Schema from those
+ * TypeScript types. Hand-writing thirty-three schemas would put a second description
+ * of each shape in a second place with nothing checking the two agree — the
+ * drift this repo has already paid for once with the tool count in prose, and
+ * a schema that is confidently wrong about `data` is worse for a validating
+ * host than one that declines to describe it.
+ *
+ * So `data` is `{}` — "anything" — and this paragraph is the disclosure rather
+ * than a silent omission (rule 7). Tightening it is real work with a real
+ * prerequisite: a generator from the handler types, or the schemas checked
+ * against recorded replies. Until then the promise made here is exactly the
+ * promise kept.
+ *
+ * ## The enums are read, not restated
+ *
+ * `state`, `class`, `reportCategory` and `reliabilityCap` build their `enum`
+ * from the exported vocabulary arrays. A restated list is a second source of
+ * truth that goes stale in silence; spread from the array, adding a report
+ * category and forgetting the schema is a red test instead.
+ */
+export declare const ANSWER_ENVELOPE_SCHEMA: Record<string, unknown>;
+/**
+ * The other shape a `tools/call` can return — `renderToolError`'s, now
+ * narrowed to the two cases where no tool was ever resolved (`name` not a
+ * string, or a name the registry does not have): there is no `ToolDefinition`
+ * to draw a real envelope from. A bad argument against a *resolved* tool goes
+ * through `renderRefusedInput` instead and is a real `state: "refused"`
+ * envelope — see that function's doc.
+ *
+ * Declared rather than quietly excluded. A schema that admitted only the
+ * envelope would be one the server itself violates on this narrower path.
+ * Declaring a union that is true beats declaring a single shape that is tidy.
+ */
+export declare const TOOL_ERROR_SCHEMA: Record<string, unknown>;
+/**
+ * What every tool declares as its `outputSchema`: the envelope or the argument
+ * error, discriminated by their required fields.
+ *
+ * One shared constant rather than a per-tool object because the shape genuinely
+ * is shared — the only per-tool part is `data`, which is open. When `data`
+ * becomes describable this becomes a function of the tool.
+ */
+export declare const TOOL_OUTPUT_SCHEMA: Record<string, unknown>;
+export declare class DisclosureError extends Error {
+    constructor(message: string);
+}
+export interface RenderOptions {
+    readonly toolVersion: string;
+    readonly toolClass: ToolClass;
+    /** MK-5/MK-8 — which report-category rule applies. See `ToolTier`. */
+    readonly toolTier: ToolTier;
+    readonly elapsedMs: number;
+    readonly limitMs: number;
+    /**
+     * B10 — the id this call will be recorded under, minted by
+     * `Session#allocateCallId()` before `renderAnswer` runs so it can be
+     * threaded into the envelope's own `callId`. Optional so every direct
+     * `renderAnswer` call in a test — none of which has a session's id
+     * sequence to draw from, and none of which asserts on `callId` — keeps
+     * compiling unchanged; a random id fills the gap there. `server.ts` is the
+     * one caller for which this matters and it always supplies a real one.
+     */
+    readonly callId?: string;
+    /**
+     * Set only when this call arrived under a retired tool name. Both halves are
+     * carried because the disclosure names both: what the caller said, and what
+     * answered. See `tools/aliases.ts` for why retired names dispatch at all.
+     */
+    readonly aliasedFrom?: string;
+    readonly aliasedTo?: string;
+    /**
+     * This connection's record of which standing disclosures it has already been
+     * given in full. Optional: a caller with no session to dedupe within (every
+     * direct `renderAnswer` in a test, every non-server consumer) gets the full
+     * sentence every time, which is the safe default — a short reference to a
+     * paragraph nobody was shown is worse than the repetition.
+     */
+    readonly disclosureLedger?: DisclosureLedger;
+    /**
+     * Overrides `MAX_REPLY_BYTES`. Exists so a test can prove the fitting
+     * behaviour against a small, deterministic ceiling rather than by generating
+     * 60KB of real data — the ceiling's *value* is a starting number, but the
+     * mechanism reacting to it must be checkable exactly.
+     */
+    readonly maxReplyBytes?: number;
+    /**
+     * The real graph's current state, for the one caller that has no `result`
+     * to read it from: `renderHandshake`. Every other envelope function gets
+     * `commitSha`/`builtAt`/`irSchemaVersion` from the tool's own `result.stamp`
+     * because a tool that ran read the graph; a handshake mint never runs the
+     * tool at all, so without this it had no honest source for those fields and
+     * hardcoded an empty graph regardless of what was actually stored —
+     * `narrate()` then told a caller sitting on a fully analysed repository that
+     * nothing had been analysed. `server.ts` supplies the session's own
+     * `provider().baseStamp()` here; a direct call in a test may omit it and
+     * gets the same "nothing known" default `renderHandshake` always had.
+     */
+    readonly graphStamp?: Omit<GraphStamp, "resolutionFloor">;
+    /**
+     * Lane "map-freshness" item 1 — computed once per call in `server.ts`
+     * (`Session#checkFreshness()`, which needs a live git read and so, like
+     * `configDrift`, must not be done by an envelope function itself) and
+     * folded into both the machine-readable `AnswerEnvelope.graph.freshness`
+     * and, when not `current`, a plain-words disclosure naming up to 5 changed
+     * files. Optional so every direct `renderAnswer` call in a test compiles
+     * unchanged; omitted (rather than defaulted to "current") reports `null`
+     * when the stored graph is non-empty, which reads as "not checked" via
+     * `freshnessField`'s own fallback — never a false `current`.
+     */
+    readonly freshness?: GraphFreshness;
+    /**
+     * Lane "map-freshness" items 2-3 — plain-words notes from an automatic
+     * build (empty graph) or refresh (behind, within budget) that ran in
+     * `server.ts` before this tool call, e.g. "code map built automatically
+     * for this answer (took 4.2s)". Ordered ahead of every other disclosure
+     * (see `build()` below) — a caller needs to know the map just changed
+     * before it needs anything else about what the answer covers.
+     */
+    readonly autoNotes?: readonly string[];
+    /**
+     * N2 steps 2-3 — computed once per call in `server.ts` (it requires a
+     * fresh read of `.descry/config.json`, which no envelope function should
+     * do itself) and threaded through so every reply, not only `analyze`'s,
+     * carries both the prose (`note`, folded into `disclosures`) and the
+     * machine-readable flag (`AnswerEnvelope.configStale`). Optional so every
+     * direct call in a test — none of which has a session's on-disk config to
+     * check against — keeps compiling and defaults to "not stale".
+     */
+    readonly configDrift?: {
+        readonly stale: boolean;
+        readonly note: string | undefined;
+    };
+    /**
+     * Arguments a redeeming `confirmToken` call supplied that conflicted with the ones frozen when
+     * the token was minted, and so were not used (`action-handshake.ts`). Threaded the same way
+     * `configDrift` is — computed by `server.ts`, which is the only caller that knows a handshake
+     * happened — and folded into `disclosures` here so rule 7's label reaches the caller rather
+     * than living only in a tool description they did not read. Absent or empty on every other
+     * path, including the two correct redemption shapes (token alone, or arguments re-sent
+     * unchanged), which discarded nothing and must therefore say nothing.
+     */
+    readonly discardedArgs?: readonly string[];
+}
+export declare function renderAnswer<T>(tool: string, answer: ToolAnswer<T>, options: RenderOptions): CallToolResult;
+/**
+ * A malformed call the server cannot even attribute to one tool — the RPC
+ * named no string tool, or named a tool that does not exist in the registry.
+ *
+ * Returned as a tool result with `isError`, not as a JSON-RPC error, which is
+ * what the MCP spec asks for: protocol errors are for malformed protocol, tool
+ * errors are for tools, and an agent can act on the second only if it arrives as
+ * content it can read.
+ *
+ * Deliberately outside the five-state envelope, and narrowly so: there is no
+ * resolved `ToolDefinition` here to draw `toolVersion`/`class`/`tier` from, so
+ * no real envelope can be built — inventing placeholder values for them would
+ * be worse than the bare shape. Once a tool *is* identified, a bad argument
+ * against it is `renderRefusedInput`'s case, not this one — see that
+ * function's doc for why the two are different claims.
+ */
+export declare function renderToolError(tool: string, message: string): CallToolResult;
+/**
+ * `state: "refused"` — the call named a real, resolved tool, but its input
+ * was wrong, so the tool never ran (`ToolInputError`, thrown by a tool's own
+ * argument reading, or by the dispatcher's own shape check on `arguments`
+ * once a tool is known).
+ *
+ * This used to fall through to `renderToolError`'s bare `{tool, status,
+ * message}` shape — measured as a real defect (a live `observe_runtime` call
+ * with a malformed `profile` field returned that bare shape instead of an
+ * envelope), because unlike the two cases `renderToolError` still covers, a
+ * `ToolDefinition` *is* available here: `toolVersion`, `class` and `tier` are
+ * all real, so a real envelope can be built rather than invented. "The tool
+ * was never run because its input was wrong" is a fact about this call, not
+ * about the code being examined — exactly what `state: "refused"` already
+ * means everywhere else in this file, so it is rendered the same way rather
+ * than through a second, parallel shape.
+ *
+ * `data` is always `null` (§2.2): nothing ran, so there is nothing to stamp.
+ * `isError` stays `true` for the same reason `renderFailed`/`renderTimedOut`
+ * set it — a generic client that only reads the transport-level signal still
+ * sees a failure; an AI-layer-aware caller additionally gets the real
+ * `state`/`disclosures`/`reportCategory` to reason about.
+ */
+export declare function renderRefusedInput(tool: string, message: string, options: RenderOptions): CallToolResult;
+/**
+ * `state: "failed"` — §1.1: "promoted from a transport error to a result."
+ *
+ * An unexpected/internal error, not a bad argument (`renderToolError` still
+ * handles those). `data` is always `null` here (§2.2): the tool does not know
+ * what happened, and anything it returned would be a guess about its own
+ * fault. `isError` stays `true` so a generic MCP client that only reads the
+ * transport-level signal still treats this as a failure; an AI-layer-aware
+ * caller additionally gets `state: "failed"` in `structuredContent` to reason
+ * about rather than a bare `{tool, status, message}` shape.
+ *
+ * `headline` is optional and exists for the *explained* half of "failed": a
+ * `ConfigError` (and any sibling raised specifically to be read, not merely
+ * caught) already carries a full written reason, and burying that behind a
+ * generic "X failed." while the real sentence sits only in `disclosures` is
+ * the bug 13.3.5 names — a caller reading just the headline learns nothing.
+ * An unexplained internal fault has no such sentence to offer, so it keeps
+ * the opaque default.
+ */
+export declare function renderFailed(tool: string, message: string, options: RenderOptions, headline?: string): CallToolResult;
+/**
+ * The one legitimate producer of a pending-handshake payload — §7's mint call.
+ *
+ * `class == "action"` returning anything other than this shape on an
+ * unconfirmed first call is invariant 4 (§2.1): "throw." This function is
+ * where that shape is produced, so the throw lives at the one call site that
+ * builds anything else for an action tool's first call — `server.ts`'s
+ * dispatch loop calls this and only this when `resolveActionDispatch` returns
+ * `{kind: "handshake"}`, never `tool.run`.
+ *
+ * `state: "ok"` deliberately: a mint is not a refusal, a failure or an empty
+ * result — it is a successful "here is what I would do", and the *pending*
+ * flag inside `data` is what tells a caller nothing was performed yet.
+ */
+export declare function renderHandshake(tool: string, token: string, willDo: string, options: RenderOptions): CallToolResult;
+/**
+ * `state: "timed_out"` — the call ran out of its declared budget.
+ *
+ * §6: "not a silent truncation and never a `failed`". `data` is `null` here
+ * because none of the registered tools currently produce genuine partial
+ * results mid-run (none checks `ctx.signal` internally yet — a disclosed gap,
+ * not a silent one, named in the returned disclosure); the envelope shape
+ * supports a populated partial `data` the day a tool does.
+ */
+export declare function renderTimedOut(tool: string, options: RenderOptions): CallToolResult;
+//# sourceMappingURL=render.d.ts.map

package/dist/render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"render.d.ts","sourceRoot":"","sources":["../src/render.ts"],"names":[],"mappings":"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"}