@descryy/mcp 0.1.0

package/dist/tools/impact.js

@@ -0,0 +1,229 @@
+/**
+ * `impact` — "what breaks if I change this, what covers it, have we seen it before?"
+ *
+ * §18's tool-name list is deliberately not a build list ("the tool names are
+ * implementation details") — but three of the functions it names were already
+ * built and correct in the query layer with no MCP tool ever calling them:
+ * `impactOf` (blast radius — find_dependents/find_callers/find_usages),
+ * `testsCovering` (find_tests) and `rootCauseSearch` (find_related_incidents,
+ * find_fix_patterns). This wires all three under one call, the same way
+ * `validate` bundles env, rollback and the config graph — a developer asking
+ * "what does changing this touch" wants the blast radius, what already tests
+ * it and what has broken near it before in one answer, not three round trips.
+ *
+ * A fourth, `traceApi` (find_dependencies read the other direction, or "how
+ * does this reach that"), runs only when a second node is given — it answers
+ * a different question (a path between two specific symbols) and forcing it
+ * into every call would mean walking the graph for a question nobody asked.
+ *
+ * ## Direction, and why the default is structural rather than data-carrying
+ *
+ * `propagation` already owns PROPAGATES_TO/READS/WRITES/RETURNS — what data
+ * carries. This tool defaults to CALLS, IMPORTS, IMPLEMENTS, INHERITS,
+ * USES_API and SERVES_API — what structure depends on what. The two tools
+ * answer different questions over the same primitives; a caller after "who
+ * calls this" should never have to remember that CALLS lives in a tool named
+ * for propagation.
+ */
+import { impactOf, rootCauseSearch, testsCovering, traceApi } from "@descryy/core";
+import { briefNode, optionalBoolean, optionalEnum, optionalInteger, optionalString, optionalStringArray, ToolInputError, } from "./kit.js";
+import { resolveOneNode } from "./lookup.js";
+/** Structural edges — what depends on what, never what data carries. */
+const STRUCTURAL_EDGE_TYPES = [
+    "CALLS",
+    "IMPORTS",
+    "IMPLEMENTS",
+    "INHERITS",
+    "USES_API",
+    "SERVES_API",
+];
+const SCHEMA = {
+    type: "object",
+    properties: {
+        nodeId: { type: "string", description: "Graph node id to start from." },
+        symbol: {
+            type: "string",
+            description: "Symbol name to start from, when you do not have a node id. Ambiguity is reported rather " +
+                "than guessed at — narrow it with \"file\".",
+        },
+        file: {
+            type: "string",
+            description: "Repository-relative path, to disambiguate \"symbol\" or to start from a file.",
+        },
+        to: {
+            type: "string",
+            description: "A second node id, symbol or path — when given, also traces a path from the start node to " +
+                "this one (find_api_contract's \"how does this reach that\" question).",
+        },
+        edgeTypes: {
+            type: "array",
+            items: { type: "string" },
+            description: "Restrict the blast-radius walk. Defaults to CALLS, IMPORTS, IMPLEMENTS, INHERITS, " +
+                "USES_API and SERVES_API — structural edges. For data-flow, use \"propagation\" instead.",
+        },
+        direction: {
+            type: "string",
+            enum: ["in", "out"],
+            description: "Which way to walk. Default \"in\" — what depends on this symbol (the blast radius). " +
+                "\"out\" answers a different question — what this symbol reaches — and is what a caller " +
+                "in one repository needs to walk toward a route served by another.",
+        },
+        crossApiEndpoint: {
+            type: "boolean",
+            description: "At an API_ENDPOINT node, also follow the USES_API/SERVES_API edge the walk's own " +
+                "direction would not otherwise see, reaching the API_ROUTE that serves it on the other " +
+                "side of the join (DEC-138: the walk otherwise stops at the shared endpoint). Off by " +
+                "default.",
+        },
+        maxDepth: { type: "integer", minimum: 1, description: "Hop limit on the blast radius. Default unbounded." },
+        limit: {
+            type: "integer",
+            minimum: 1,
+            description: "Cap on nodes in the reply. Default 25 — MK-9: the prior default of 100 cost ~5.6k tokens " +
+                "per call in this surface's own serialized envelope; 25 lands near ~1.6k, matching the " +
+                "default cap `validate`/`contracts` already use. A capped reply always discloses shown/total " +
+                "(§5.5); raise this explicitly when the full set is needed.",
+        },
+    },
+    additionalProperties: false,
+};
+async function run(args, ctx) {
+    const nodeId = optionalString(args, "nodeId");
+    const symbol = optionalString(args, "symbol");
+    const file = optionalString(args, "file");
+    const to = optionalString(args, "to");
+    const edgeTypes = optionalStringArray(args, "edgeTypes");
+    const direction = optionalEnum(args, "direction", ["in", "out"]);
+    const crossApiEndpoint = optionalBoolean(args, "crossApiEndpoint") ?? false;
+    const maxDepth = optionalInteger(args, "maxDepth", 1);
+    const limit = optionalInteger(args, "limit", 1) ?? 25;
+    if (nodeId === undefined && symbol === undefined && file === undefined) {
+        throw new ToolInputError('give one of "nodeId", "symbol" or "file"');
+    }
+    const provider = ctx.session.provider();
+    const found = resolveOneNode(ctx.session, { nodeId, symbol, file });
+    if (found.node === null) {
+        const base = provider.baseStamp();
+        return {
+            result: {
+                data: { candidates: found.candidates.map(briefNode) },
+                stamp: { commitSha: base.commitSha, graphBuiltAt: base.graphBuiltAt, irSchemaVersion: base.irSchemaVersion, resolutionFloor: 0 },
+                truncated: false,
+                notes: found.notes,
+            },
+            nameLevel: true,
+            state: "refused",
+            headline: found.headline,
+        };
+    }
+    const walked = edgeTypes ?? STRUCTURAL_EDGE_TYPES;
+    ctx.progress(direction === "out" ? `Finding what ${found.node.name} reaches` : `Finding what depends on ${found.node.name}`);
+    const impact = impactOf(provider, [found.node.id], {
+        types: walked,
+        ...(direction === undefined ? {} : { direction }),
+        ...(crossApiEndpoint ? { crossApiEndpoint } : {}),
+        ...(maxDepth === undefined ? {} : { maxDepth }),
+    });
+    const affected = impact.data.filter((entry) => entry.node.id !== found.node?.id);
+    const shownAffected = affected.slice(0, limit);
+    ctx.progress(`Finding tests covering ${found.node.name}`);
+    const tests = testsCovering(provider, found.node.id, maxDepth === undefined ? {} : { maxDepth });
+    ctx.progress(`Checking for related incidents and fix patterns`);
+    const related = rootCauseSearch(provider, found.node.id);
+    let path = null;
+    const pathNotes = [];
+    if (to !== undefined) {
+        const target = resolveOneNode(ctx.session, { symbol: to, file: undefined });
+        if (target.node === null) {
+            pathNotes.push(`"to" (${JSON.stringify(to)}) did not resolve: ${target.headline}`);
+        }
+        else {
+            ctx.progress(`Tracing a path to ${target.node.name}`);
+            const traced = traceApi(provider, found.node.id, target.node.id, { direction: "both" });
+            path = { to: briefNode(target.node), hops: traced.data.hops, nodes: traced.data.path.map(briefNode) };
+            pathNotes.push(...traced.notes);
+        }
+    }
+    const present = new Set();
+    for (const edge of [...provider.outgoing(found.node.id), ...provider.incoming(found.node.id)]) {
+        if (walked.includes(edge.type))
+            present.add(edge.type);
+    }
+    const absent = walked.filter((type) => !present.has(type));
+    const analysed = present.size > 0;
+    const notes = [...found.notes, ...impact.notes, ...tests.notes, ...related.notes, ...pathNotes];
+    if (shownAffected.length < affected.length) {
+        notes.push(`${affected.length - shownAffected.length} further affected node(s) exist but are not listed — ` +
+            `the reply is capped at ${limit}.`);
+    }
+    if (absent.length > 0) {
+        notes.push(`No ${absent.join(", ")} edge touches this node, so ${absent.length === 1 ? "that type" : "those types"} ` +
+            "contributed nothing to the blast radius.");
+    }
+    if (!analysed) {
+        notes.push(`None of the requested edge types (${walked.join(", ")}) appear on any edge touching this node. ` +
+            "That is not a finding that nothing depends on it — a producer for these edges may not run in " +
+            "this graph. This probe is local to one node and does not choose between the causes.");
+    }
+    const resolutionFloor = Math.min(impact.stamp.resolutionFloor, tests.stamp.resolutionFloor, related.stamp.resolutionFloor);
+    return {
+        result: {
+            data: {
+                from: briefNode(found.node),
+                affected: shownAffected.map((entry) => ({
+                    ...briefNode(entry.node),
+                    depth: entry.depth,
+                    score: Number(entry.score.toFixed(4)),
+                })),
+                affectedTotal: affected.length,
+                coveringTests: tests.data.map(briefNode),
+                related: related.data.map((m) => ({ ...briefNode(m.incident), via: m.via })),
+                path,
+                analysed,
+                edgeTypesWalked: walked,
+                edgeTypesPresent: [...present].sort(),
+            },
+            stamp: { ...impact.stamp, resolutionFloor },
+            // `impact.truncated` is the query layer's own internal cap; it says
+            // nothing about this tool's own `limit` slice of `affected`, which can
+            // cap further still — the same gap history.ts had (P27).
+            truncated: impact.truncated || tests.truncated || related.truncated || shownAffected.length < affected.length,
+            notes,
+        },
+        nameLevel: false,
+        ...(analysed ? (affected.length === 0 ? { state: "empty" } : {}) : { state: "refused" }),
+        // `affected` is the primary collection this tool exists to report — tests/
+        // related can also be independently capped, but a single shown/total pair
+        // cannot honestly describe three different lists, so this covers the one
+        // §4's TruncationDetail doc calls "the primary collection" and leaves the
+        // other two to the boolean above and their own prose notes.
+        ...(shownAffected.length < affected.length
+            ? { truncatedDetail: { shown: shownAffected.length, total: affected.length, more: null } }
+            : {}),
+        headline: !analysed
+            ? `${found.node.name}'s blast radius was not analysed: the graph holds no ${walked.join("/")} edge ` +
+                "touching it. This is not a finding that nothing depends on it."
+            : direction === "out"
+                ? `${found.node.name} reaches ${affected.length} node(s); ${tests.data.length} test(s) cover it` +
+                    `${related.data.length > 0 ? `; ${related.data.length} related incident(s)/fix(es)` : ""}.`
+                : `${found.node.name} affects ${affected.length} node(s); ${tests.data.length} test(s) cover it` +
+                    `${related.data.length > 0 ? `; ${related.data.length} related incident(s)/fix(es)` : ""}.`,
+    };
+}
+export const impactTool = {
+    name: "impact",
+    class: "read",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "Blast radius, test coverage and prior incidents for a symbol",
+    description: "Given a symbol, report what depends on it (blast radius over CALLS/IMPORTS/IMPLEMENTS/" +
+        "INHERITS/USES_API/SERVES_API), which tests cover it, and any incidents or fix patterns " +
+        "linked to it by a graph edge. Pass \"to\" to also trace a path to a second symbol. Pass " +
+        "\"direction\": \"out\" to instead ask what a symbol reaches, and \"crossApiEndpoint\": true " +
+        "with it to walk from a frontend caller across a shared API_ENDPOINT into the backend " +
+        "API_ROUTE that serves it. For data flow (what a value reaches, not what depends on a " +
+        "symbol), use \"propagation\" instead.",
+    inputSchema: SCHEMA,
+    run,
+};
+//# sourceMappingURL=impact.js.map

package/dist/tools/impact.js.map

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

package/dist/tools/index.d.ts

@@ -0,0 +1,33 @@
+/**
+ * The commands of blueprint §1.11, in the order a developer meets them.
+ *
+ * `analyze` first because nothing else works without it, then the three
+ * questions asked of an existing graph, then `contracts` — which is declared,
+ * described and honestly unavailable. See `contracts.ts` for why it is here
+ * rather than omitted.
+ */
+import type { ToolDefinition } from "./kit.ts";
+export declare const TOOLS: readonly ToolDefinition[];
+export declare const TOOLS_BY_NAME: ReadonlyMap<string, ToolDefinition>;
+export { ToolInputError } from "./kit.ts";
+export type { BriefNode, NodeCandidates, Progress, ToolContext, ToolDefinition, } from "./kit.ts";
+export { resolveOneNode } from "./lookup.ts";
+export { TOOL_TIERS } from "../render.ts";
+export type { ToolTier } from "../render.ts";
+export type { AnalyzeData, SourceRun } from "./analyze.ts";
+export type { ContractPathFinding, ContractShapeMismatchReport, ContractShapeStatus, ContractsData, } from "./contracts.ts";
+export type { BlockedCheck, CrossPrData, CrossPrEmptyDiff, CrossPrGitFailure, CrossPrReport, HiddenDependencyCheck, HiddenDependencyFinding, OverlapCheck, OverlapReportChecked, SupersededCheck, } from "./cross-pr.ts";
+export type { GitDiffData, GitDiffEntry } from "./git-diff.ts";
+export type { GitHistoryCommit, GitHistoryData } from "./git-history.ts";
+export type { CoChangedFile, HistoryData, HistoryFile, HistoryFileResolved, HistoryFileUnresolved, HistoryReport } from "./history.ts";
+export type { ImpactData, ImpactedNode, ImpactReport, RelatedNode, TracedPath } from "./impact.ts";
+export type { LinkWorkspaceData, LinkedRepo } from "./link-workspace.ts";
+export type { AffectedNode, PrAnalysisData, PrAnalysisEmptyDiff, PrAnalysisGitFailure, PrAnalysisRange, PrAnalysisReport, PrAnalysisUnresolved, } from "./pr-analysis.ts";
+export type { PropagationData, PropagationReport, ReachedNode } from "./propagation.ts";
+export type { QuestionsData } from "./questions.ts";
+export type { RefusalFetchData, RefusalFetchPageData, RefusalFetchSummaryData, RefusalFetchSummaryItem, } from "./refusal-fetch.ts";
+export type { ScopeData, ScopeNotSeeded, ScopeReport, ScopeTierCount, ScopedNodeReport } from "./scope.ts";
+export type { SimilarIncidentReport, SimilarIncidentSignalReport, SimilarIncidentsData, } from "./similar-incidents.ts";
+export type { ConfigDependencyReport, EnvFindingReport, ValidateData } from "./validate.ts";
+export type { VerificationStatusData, VerificationStatusExercisedItem, } from "./verification-status.ts";
+//# sourceMappingURL=index.d.ts.map

package/dist/tools/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAkBH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAE/C,eAAO,MAAM,KAAK,EAAE,SAAS,cAAc,EAiB1C,CAAC;AAEF,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,EAAE,cAAc,CAE7D,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAC1C,YAAY,EACV,SAAS,EACT,cAAc,EACd,QAAQ,EACR,WAAW,EACX,cAAc,GACf,MAAM,UAAU,CAAC;AAClB,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC1C,YAAY,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAO7C,YAAY,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAC3D,YAAY,EACV,mBAAmB,EACnB,2BAA2B,EAC3B,mBAAmB,EACnB,aAAa,GACd,MAAM,gBAAgB,CAAC;AACxB,YAAY,EACV,YAAY,EACZ,WAAW,EACX,gBAAgB,EAChB,iBAAiB,EACjB,aAAa,EACb,qBAAqB,EACrB,uBAAuB,EACvB,YAAY,EACZ,oBAAoB,EACpB,eAAe,GAChB,MAAM,eAAe,CAAC;AACvB,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/D,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AACzE,YAAY,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW,EAAE,mBAAmB,EAAE,qBAAqB,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AACvI,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACnG,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACzE,YAAY,EACV,YAAY,EACZ,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,oBAAoB,GACrB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACxF,YAAY,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AACpD,YAAY,EACV,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,SAAS,EAAE,cAAc,EAAE,WAAW,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAC3G,YAAY,EACV,qBAAqB,EACrB,2BAA2B,EAC3B,oBAAoB,GACrB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,sBAAsB,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC5F,YAAY,EACV,sBAAsB,EACtB,+BAA+B,GAChC,MAAM,0BAA0B,CAAC"}

package/dist/tools/index.js

@@ -0,0 +1,47 @@
+/**
+ * The commands of blueprint §1.11, in the order a developer meets them.
+ *
+ * `analyze` first because nothing else works without it, then the three
+ * questions asked of an existing graph, then `contracts` — which is declared,
+ * described and honestly unavailable. See `contracts.ts` for why it is here
+ * rather than omitted.
+ */
+import { analyzeTool } from "./analyze.js";
+import { contractsTool } from "./contracts.js";
+import { crossPrTool } from "./cross-pr.js";
+import { gitDiffTool } from "./git-diff.js";
+import { gitHistoryTool } from "./git-history.js";
+import { historyTool } from "./history.js";
+import { impactTool } from "./impact.js";
+import { linkWorkspaceTool } from "./link-workspace.js";
+import { prAnalysisTool } from "./pr-analysis.js";
+import { propagationTool } from "./propagation.js";
+import { questionsTool } from "./questions.js";
+import { refusalFetchTool } from "./refusal-fetch.js";
+import { scopeTool } from "./scope.js";
+import { similarIncidentsTool } from "./similar-incidents.js";
+import { validateTool } from "./validate.js";
+import { verificationStatusTool } from "./verification-status.js";
+export const TOOLS = [
+    analyzeTool,
+    linkWorkspaceTool,
+    scopeTool,
+    prAnalysisTool,
+    crossPrTool,
+    propagationTool,
+    impactTool,
+    historyTool,
+    contractsTool,
+    validateTool,
+    similarIncidentsTool,
+    questionsTool,
+    refusalFetchTool,
+    verificationStatusTool,
+    gitDiffTool,
+    gitHistoryTool,
+];
+export const TOOLS_BY_NAME = new Map(TOOLS.map((tool) => [tool.name, tool]));
+export { ToolInputError } from "./kit.js";
+export { resolveOneNode } from "./lookup.js";
+export { TOOL_TIERS } from "../render.js";
+//# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAClD,OAAO,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAGlE,MAAM,CAAC,MAAM,KAAK,GAA8B;IAC9C,WAAW;IACX,iBAAiB;IACjB,SAAS;IACT,cAAc;IACd,WAAW;IACX,eAAe;IACf,UAAU;IACV,WAAW;IACX,aAAa;IACb,YAAY;IACZ,oBAAoB;IACpB,aAAa;IACb,gBAAgB;IAChB,sBAAsB;IACtB,WAAW;IACX,cAAc;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,aAAa,GAAwC,IAAI,GAAG,CACvE,KAAK,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CACvC,CAAC;AAEF,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAQ1C,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC"}

package/dist/tools/kit.d.ts

@@ -0,0 +1,183 @@
+/**
+ * What every tool is handed and what every tool may return.
+ *
+ * The return type is `ToolAnswer`, never content. A tool produces an *answer*;
+ * `render.ts` is the only thing that turns an answer into a reply, and it
+ * attaches the staleness stamp, the reliability cap and the disclosures on the
+ * way. A tool physically cannot ship a result with the caveats stripped off.
+ */
+import type { ResolutionLevel, ResultState, ToolClass } from "@descryy/ir";
+import type { ToolAnswer, ToolTier, TruncationDetail } from "../render.ts";
+import type { Session } from "../session.ts";
+/**
+ * Streaming narration — §22.2's primary UX, at the protocol level.
+ *
+ * A no-op when the client did not send a progress token, which is the common
+ * case for a scripted call. Tools call it unconditionally; deciding whether
+ * anybody is listening is not their job.
+ */
+export type Progress = (message: string, current?: number, total?: number) => void;
+export interface ToolContext {
+    readonly session: Session;
+    readonly progress: Progress;
+    readonly signal: AbortSignal;
+}
+export interface ToolDefinition {
+    readonly name: string;
+    readonly title: string;
+    readonly description: string;
+    /**
+     * DEC-278's three classes, and the assignment for all fourteen endpoints is
+     * tabulated in `ai-tool-contract.md` §8 rather than re-derived here.
+     *
+     * The line is deliberately **not** "does it write bytes". It is *can this
+     * call's effect change a later finding without the developer having said
+     * so.* `analyze` re-derives from code already on disk and `link_workspace`
+     * records where that code is, so neither can introduce a claim the
+     * repository does not already contain — both are `stateful-read`.
+     * `questions` writes a `ConfirmedFact`: human testimony that becomes a graph
+     * input, feeds `humanAsserted`, and is capped at reliability class B by
+     * DEC-223 precisely because it rests on one unaudited assertion. It is the
+     * only `action`, and the only class §4's two-call handshake gates.
+     *
+     * Required, and deliberately given no default — the same reasoning as
+     * `reliabilityCap`'s `nameLevel`. A tool author who has not thought about
+     * which class they are in is exactly the author who would inherit the wrong
+     * one, and the wrong one here is a mutating endpoint silently treated as
+     * pure.
+     *
+     * The type lives in `@descryy/ir` because the desktop lane and the AI layer
+     * read the same three names; restating the union here would be a second
+     * source of truth for one vocabulary.
+     */
+    readonly class: ToolClass;
+    /**
+     * MK-5 — does this tool's output state a conclusion about the user's code,
+     * or report a fact about the graph? Required and undefaulted, the same
+     * reasoning as `class` just above: three tools (`validate`, `contracts`,
+     * `cross_pr`) already refuse rather than over-claim and never return raw
+     * candidates — an author who has not thought about which one theirs is
+     * would be exactly the author to leave it defaulted to the safer-sounding
+     * one. See `ToolTier`'s own doc in `../render.ts` for why the type lives
+     * there and not here.
+     */
+    readonly tier: ToolTier;
+    /**
+     * Contract §6, rule 8. Every tool starts at `"1.0.0"` — none has shipped a
+     * behaviour change yet — and a future bump is what invalidates the golden
+     * investigations that depended on the old behaviour (`ai-layer-plan.md` §9
+     * layer 4).
+     */
+    readonly version: string;
+    readonly inputSchema: Record<string, unknown>;
+    run(args: Record<string, unknown>, ctx: ToolContext): Promise<ToolAnswer<unknown>>;
+    /**
+     * Required when, and only when, `class === "action"` — `action-handshake.ts`
+     * throws at mint time if an action-class tool omits it (a registry bug, not
+     * a caller mistake). Absent on `read`/`stateful-read` tools; TypeScript
+     * cannot express "required iff this other field equals X", so it stays
+     * optional here and the constraint is enforced at the one call site that
+     * needs it, `tool-classes.test.ts` for the static half.
+     *
+     * Returns the plain-English "willDo" description of what confirming this
+     * call would do, or `undefined` when *this particular call* has nothing to
+     * confirm — `questions` with no `answer` argument is a pure read of the
+     * open-question queue, and gating that behind a token would make the tool
+     * unable to answer the first question asked of it.
+     */
+    describeAction?(args: Record<string, unknown>, ctx: ToolContext): string | undefined | Promise<string | undefined>;
+}
+/**
+ * An argument the caller can fix.
+ *
+ * Distinct from a thrown `Error`, which is a bug here. This becomes an `isError`
+ * tool result the agent can read and retry from; a bug becomes a JSON-RPC
+ * internal error, which it cannot.
+ */
+export declare class ToolInputError extends Error {
+    constructor(message: string);
+}
+export declare function optionalString(args: Record<string, unknown>, key: string): string | undefined;
+export declare function requiredString(args: Record<string, unknown>, key: string): string;
+export declare function optionalStringArray(args: Record<string, unknown>, key: string): readonly string[] | undefined;
+export declare function optionalInteger(args: Record<string, unknown>, key: string, min: number): number | undefined;
+export declare function optionalEnum<T extends string>(args: Record<string, unknown>, key: string, allowed: readonly T[]): T | undefined;
+export declare function optionalBoolean(args: Record<string, unknown>, key: string): boolean | undefined;
+/**
+ * Wrap data that did not come from the query layer in the same envelope.
+ *
+ * `analyze` is the case: it writes rather than reads, so it has no
+ * `QueryResult`, and it would be the natural place for the disclosure discipline
+ * to leak. It uses this instead, so its reply carries the same stamp and the
+ * same rules as every query's.
+ */
+export declare function answer<T>(options: {
+    readonly headline: string;
+    readonly data: T;
+    readonly resolutionFloor: ResolutionLevel;
+    readonly commitSha: string | null;
+    readonly graphBuiltAt: number | null;
+    readonly irSchemaVersion: number;
+    readonly notes: readonly string[];
+    readonly truncated?: boolean;
+    readonly truncatedDetail?: TruncationDetail;
+    readonly nameLevel: boolean;
+    /** One of the five result states (`ai-tool-contract.md` §1). Omitted means `"ok"`. */
+    readonly state?: ResultState;
+    /** §5.4 — see `render.ts`'s `ToolAnswer.refusalSummary` doc for which callers have one. */
+    readonly refusalSummary?: {
+        readonly count: number;
+        readonly exemplar: string;
+        readonly handle: string;
+    };
+}): ToolAnswer<T>;
+/**
+ * An IR node as it appears in a tool reply.
+ *
+ * The four optional fields are optional in the payload too, not `null` — a
+ * node with no file omits the key rather than carrying an empty one, which is
+ * what keeps a 1,000-node reply affordable. A caller must therefore test for
+ * presence, not for null.
+ *
+ * `language` is the IR node's own field passed through verbatim. Nothing here
+ * or above reads it, branches on it, or knows any value it can take (rule 1);
+ * it travels because a developer reading the reply is entitled to see which
+ * adapter's evidence a row rests on.
+ */
+export interface BriefNode {
+    readonly id: string;
+    readonly type: string;
+    readonly name: string;
+    readonly file?: string;
+    /** Start line only — a reply carries where to look, not how much to read. */
+    readonly line?: number;
+    readonly language?: string;
+    readonly resolution: number;
+}
+/**
+ * What a tool returns when the symbol, path or id it was given resolved to
+ * nothing, or to more than one thing.
+ *
+ * Shared by `impact` and `propagation`, because both go through
+ * `resolveOneNode` and both refuse the same way: no answer is computed, and
+ * the candidates come back so the caller can narrow rather than guess. An
+ * empty `candidates` means nothing matched at all; two or more means the name
+ * was ambiguous. One is impossible — that is the case that resolves.
+ */
+export interface NodeCandidates {
+    readonly candidates: readonly BriefNode[];
+}
+/** Trim an IR node down to what an agent needs, so a 1,000-node reply stays readable. */
+export declare function briefNode(node: {
+    id: string;
+    type: string;
+    name: string;
+    file: string | null;
+    range: {
+        startLine: number;
+        endLine: number;
+    } | null;
+    language: string | null;
+    resolution: number;
+}): BriefNode;
+//# sourceMappingURL=kit.d.ts.map

package/dist/tools/kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"kit.d.ts","sourceRoot":"","sources":["../../src/tools/kit.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE3E,OAAO,KAAK,EAAE,UAAU,EAAE,QAAQ,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAE7C;;;;;;GAMG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;AAEnF,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;CAC9B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B;;;;;;;;;OASG;IACH,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9C,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAC;IACnF;;;;;;;;;;;;;OAaG;IACH,cAAc,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACpH;AAED;;;;;;GAMG;AACH,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,EAAE,MAAM;CAI5B;AAOD,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAK7F;AAED,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAIjF;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,GACV,SAAS,MAAM,EAAE,GAAG,SAAS,CAO/B;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAOpB;AAED,wBAAgB,YAAY,CAAC,CAAC,SAAS,MAAM,EAC3C,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,SAAS,CAAC,EAAE,GACpB,CAAC,GAAG,SAAS,CAOf;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAK/F;AAID;;;;;;;GAOG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,OAAO,EAAE;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IACjB,QAAQ,CAAC,eAAe,EAAE,eAAe,CAAC;IAC1C,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,gBAAgB,CAAC;IAC5C,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC;IAC7B,2FAA2F;IAC3F,QAAQ,CAAC,cAAc,CAAC,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC1G,GAAG,UAAU,CAAC,CAAC,CAAC,CAoBhB;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,CAAC;CAC3C;AAED,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,IAAI,EAAE;IAC9B,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,KAAK,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IACrD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;CACpB,GAAG,SAAS,CAUZ"}

package/dist/tools/kit.js

@@ -0,0 +1,117 @@
+/**
+ * What every tool is handed and what every tool may return.
+ *
+ * The return type is `ToolAnswer`, never content. A tool produces an *answer*;
+ * `render.ts` is the only thing that turns an answer into a reply, and it
+ * attaches the staleness stamp, the reliability cap and the disclosures on the
+ * way. A tool physically cannot ship a result with the caveats stripped off.
+ */
+/**
+ * An argument the caller can fix.
+ *
+ * Distinct from a thrown `Error`, which is a bug here. This becomes an `isError`
+ * tool result the agent can read and retry from; a bug becomes a JSON-RPC
+ * internal error, which it cannot.
+ */
+export class ToolInputError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "ToolInputError";
+    }
+}
+// --- argument reading -------------------------------------------------------
+// Hand-written rather than schema-validated. The surface is five tools with
+// about a dozen arguments between them; a validator would be a dependency and a
+// second source of truth for the schemas already declared to the client.
+export function optionalString(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "string")
+        throw new ToolInputError(`"${key}" must be a string`);
+    return value;
+}
+export function requiredString(args, key) {
+    const value = optionalString(args, key);
+    if (value === undefined || value === "")
+        throw new ToolInputError(`"${key}" is required`);
+    return value;
+}
+export function optionalStringArray(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        throw new ToolInputError(`"${key}" must be an array of strings`);
+    }
+    return value;
+}
+export function optionalInteger(args, key, min) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < min) {
+        throw new ToolInputError(`"${key}" must be an integer of at least ${min}`);
+    }
+    return value;
+}
+export function optionalEnum(args, key, allowed) {
+    const value = optionalString(args, key);
+    if (value === undefined)
+        return undefined;
+    if (!allowed.includes(value)) {
+        throw new ToolInputError(`"${key}" must be one of: ${allowed.join(", ")}`);
+    }
+    return value;
+}
+export function optionalBoolean(args, key) {
+    const value = args[key];
+    if (value === undefined || value === null)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new ToolInputError(`"${key}" must be a boolean`);
+    return value;
+}
+// --- building answers -------------------------------------------------------
+/**
+ * Wrap data that did not come from the query layer in the same envelope.
+ *
+ * `analyze` is the case: it writes rather than reads, so it has no
+ * `QueryResult`, and it would be the natural place for the disclosure discipline
+ * to leak. It uses this instead, so its reply carries the same stamp and the
+ * same rules as every query's.
+ */
+export function answer(options) {
+    const result = {
+        data: options.data,
+        stamp: {
+            commitSha: options.commitSha,
+            graphBuiltAt: options.graphBuiltAt,
+            irSchemaVersion: options.irSchemaVersion,
+            resolutionFloor: options.resolutionFloor,
+        },
+        truncated: options.truncated ?? false,
+        notes: options.notes,
+    };
+    return {
+        result,
+        nameLevel: options.nameLevel,
+        headline: options.headline,
+        ...(options.state === undefined ? {} : { state: options.state }),
+        ...(options.truncatedDetail === undefined ? {} : { truncatedDetail: options.truncatedDetail }),
+        ...(options.refusalSummary === undefined ? {} : { refusalSummary: options.refusalSummary }),
+    };
+}
+/** Trim an IR node down to what an agent needs, so a 1,000-node reply stays readable. */
+export function briefNode(node) {
+    return {
+        id: node.id,
+        type: node.type,
+        name: node.name,
+        ...(node.file === null ? {} : { file: node.file }),
+        ...(node.range === null ? {} : { line: node.range.startLine }),
+        ...(node.language === null ? {} : { language: node.language }),
+        resolution: node.resolution,
+    };
+}
+//# sourceMappingURL=kit.js.map