@descryy/mcp 0.11.5 → 0.11.7

package/dist/tools/prove-reach.d.ts

@@ -0,0 +1,74 @@
+/**
+ * `prove_reach` — closes RG-10's loop. "Rename that column and these screens go blank" is
+ * three claims, made in order, each on evidence the last one didn't have:
+ *
+ *  1. **Predict** — from a node (typically a `DATABASE_COLUMN`), walk `reachablePages`
+ *     (`@descryy/core`) to whatever `PAGE`/`COMPONENT` nodes the data reaches, and propose a
+ *     navigate-only journey to them, exactly as `predict_reach` already does — this tool calls
+ *     the identical pure planner (`../planner/predict-then-propose.ts#predictThenPropose`), never
+ *     a second implementation. Nothing runs yet: a caller who has not yet approved the drive gets
+ *     back the prediction, the proposal and a confirmation token, and this tool's `describeAction`
+ *     is what mints that token — the dispatcher (`../action-handshake.ts`) never calls `run` at
+ *     all until the second call arrives, so "nothing runs" is structural, not a promise this file
+ *     keeps by convention.
+ *  2. **Approve and drive** — a second call, `confirmToken` in hand, drives the exact proposed
+ *     scenario for real via `../browser/scenario-runner.ts#replayScenario`, in a browser session
+ *     the caller already started and consented (`browser({ verb: "start_session" })`). Never boots an app,
+ *     never widens the journey beyond what was proposed: the scenario driven is the one frozen at
+ *     mint time, byte for byte.
+ *  3. **Prove** — correlates which of the predicted pages the drive's own step results actually
+ *     reached (`../planner/predict-then-propose.ts#visitedPageIds` + `#proveOrDisprove`) — a page
+ *     counts as visited only when the exact navigate URL built from its own route name replayed
+ *     as `"ran"`, never a guess from proximity.
+ *  4. **Conclude** — routes the real, walked graph path (`#combinedGraphPath`, never a synthesised
+ *     one) and the runtime evidence the drive actually observed (console errors, failed requests)
+ *     through the same finding funnel `draw_conclusion` uses — `reportCategory`, `@descryy/ir`,
+ *     `packages/ir/src/finding.ts` — so the reply carries a governed category, not a raw tally the
+ *     caller has to interpret. A drive that reached every predicted page cleanly, with nothing
+ *     wrong observed, reports so honestly: `hasRuntimeEvidence` is false and the category is
+ *     `unconfirmed` by G3's own precondition, not "confirmed" because the pages loaded.
+ *
+ * **class: "action"**, gated only when there is something to drive: a node that reaches nothing,
+ * or reaches only non-path-shaped pages/components with no navigate step to propose, has nothing
+ * to approve, so `describeAction` returns `undefined` and this reports the prediction immediately
+ * — same discipline as `predict_reach`'s own empty case, never a gate for its own sake.
+ */
+import { type ProvenReach } from "../planner/predict-then-propose.ts";
+import type { JourneyCandidateNode } from "../planner/propose-journey.ts";
+import type { Scenario } from "../scenarios/index.ts";
+import { type BriefNode, type NodeCandidates, type ToolDefinition } from "./kit.ts";
+export interface DriveResult {
+    readonly outcome: "passed" | "failed" | "unresolved" | "unverified";
+    readonly steps: readonly {
+        readonly url: string;
+        readonly status: string;
+    }[];
+    readonly consoleErrorCount: number;
+    readonly failedRequestCount: number;
+}
+export interface ProveReachReport {
+    readonly from: BriefNode;
+    readonly reachedPages: readonly BriefNode[];
+    readonly proposal: {
+        readonly scenario: Scenario;
+        readonly reachedNotProposed: readonly JourneyCandidateNode[];
+    } | null;
+    /** Null until a real drive ran — this call's own drive, never a caller-supplied one (that join
+     *  is `predict_reach`'s `observedNodeIds`, a different, evidence-already-in-hand path). */
+    readonly drive: DriveResult | null;
+    readonly proof: ProvenReach | null;
+    /** The governed finding — null only when nothing was driven, because a category about a drive
+     *  that never happened would be a claim this tool has no evidence for. */
+    readonly conclusion: {
+        readonly failurePoint: string;
+        readonly category: string;
+        readonly reliabilityClass: string;
+        readonly resolution: number;
+        readonly independentSignalTypes: number;
+        readonly directMechanismEvidence: boolean;
+        readonly hasRuntimeEvidence: boolean;
+    } | null;
+}
+export type ProveReachData = ProveReachReport | NodeCandidates;
+export declare const proveReachTool: ToolDefinition;
+//# sourceMappingURL=prove-reach.d.ts.map

package/dist/tools/prove-reach.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prove-reach.d.ts","sourceRoot":"","sources":["../../src/tools/prove-reach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAeH,OAAO,EAML,KAAK,WAAW,EACjB,MAAM,oCAAoC,CAAC;AAC5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AAG1E,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAC;AACtD,OAAO,EAML,KAAK,SAAS,EACd,KAAK,cAAc,EAEnB,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAIlB,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,QAAQ,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAC;IACpE,QAAQ,CAAC,KAAK,EAAE,SAAS;QAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC7E,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,YAAY,EAAE,SAAS,SAAS,EAAE,CAAC;IAC5C,QAAQ,CAAC,QAAQ,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;QAAC,QAAQ,CAAC,kBAAkB,EAAE,SAAS,oBAAoB,EAAE,CAAA;KAAE,GAAG,IAAI,CAAC;IACxH;+FAC2F;IAC3F,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAAC;IACnC;8EAC0E;IAC1E,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;QAC5B,QAAQ,CAAC,sBAAsB,EAAE,MAAM,CAAC;QACxC,QAAQ,CAAC,uBAAuB,EAAE,OAAO,CAAC;QAC1C,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;KACtC,GAAG,IAAI,CAAC;CACV;AAED,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAqQ/D,eAAO,MAAM,cAAc,EAAE,cAa5B,CAAC"}

package/dist/tools/prove-reach.js

@@ -0,0 +1,274 @@
+/**
+ * `prove_reach` — closes RG-10's loop. "Rename that column and these screens go blank" is
+ * three claims, made in order, each on evidence the last one didn't have:
+ *
+ *  1. **Predict** — from a node (typically a `DATABASE_COLUMN`), walk `reachablePages`
+ *     (`@descryy/core`) to whatever `PAGE`/`COMPONENT` nodes the data reaches, and propose a
+ *     navigate-only journey to them, exactly as `predict_reach` already does — this tool calls
+ *     the identical pure planner (`../planner/predict-then-propose.ts#predictThenPropose`), never
+ *     a second implementation. Nothing runs yet: a caller who has not yet approved the drive gets
+ *     back the prediction, the proposal and a confirmation token, and this tool's `describeAction`
+ *     is what mints that token — the dispatcher (`../action-handshake.ts`) never calls `run` at
+ *     all until the second call arrives, so "nothing runs" is structural, not a promise this file
+ *     keeps by convention.
+ *  2. **Approve and drive** — a second call, `confirmToken` in hand, drives the exact proposed
+ *     scenario for real via `../browser/scenario-runner.ts#replayScenario`, in a browser session
+ *     the caller already started and consented (`browser({ verb: "start_session" })`). Never boots an app,
+ *     never widens the journey beyond what was proposed: the scenario driven is the one frozen at
+ *     mint time, byte for byte.
+ *  3. **Prove** — correlates which of the predicted pages the drive's own step results actually
+ *     reached (`../planner/predict-then-propose.ts#visitedPageIds` + `#proveOrDisprove`) — a page
+ *     counts as visited only when the exact navigate URL built from its own route name replayed
+ *     as `"ran"`, never a guess from proximity.
+ *  4. **Conclude** — routes the real, walked graph path (`#combinedGraphPath`, never a synthesised
+ *     one) and the runtime evidence the drive actually observed (console errors, failed requests)
+ *     through the same finding funnel `draw_conclusion` uses — `reportCategory`, `@descryy/ir`,
+ *     `packages/ir/src/finding.ts` — so the reply carries a governed category, not a raw tally the
+ *     caller has to interpret. A drive that reached every predicted page cleanly, with nothing
+ *     wrong observed, reports so honestly: `hasRuntimeEvidence` is false and the category is
+ *     `unconfirmed` by G3's own precondition, not "confirmed" because the pages loaded.
+ *
+ * **class: "action"**, gated only when there is something to drive: a node that reaches nothing,
+ * or reaches only non-path-shaped pages/components with no navigate step to propose, has nothing
+ * to approve, so `describeAction` returns `undefined` and this reports the prediction immediately
+ * — same discipline as `predict_reach`'s own empty case, never a gate for its own sake.
+ */
+import { directMechanismEvidence, evidencePrecondition, humanAssertedOnPath, independentSignalTypes, minimumResolution, reportCategory, } from "@descryy/ir";
+import { combinedGraphPath, predictThenPropose, proveOrDisprove, visitedPageIds, } from "../planner/predict-then-propose.js";
+import { browserAnswer, mutationRefusal, useSession, withinConsent } from "../browser/tool-support.js";
+import { mutates, replayScenario } from "../browser/scenario-runner.js";
+import { answer, briefNode, requiredString, optionalString, ToolInputError, } from "./kit.js";
+import { resolveOneNode } from "./lookup.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        nodeId: { type: "string", description: "Node to predict reach from — typically a data column." },
+        symbol: {
+            type: "string",
+            description: "Start symbol if no node id. Ambiguous matches are refused.",
+        },
+        file: { type: "string", description: "Path, to disambiguate \"symbol\"." },
+        targetUrl: {
+            type: "string",
+            description: "REQUIRED. Base URL — origin sessionId was consented for.",
+        },
+        sessionId: {
+            type: "string",
+            description: "REQUIRED. Session id from browser's start_session. Never widens consent beyond it.",
+        },
+        name: { type: "string", description: "Name for the proposed scenario. Default \"predicted-journey\"." },
+        confirmToken: {
+            type: "string",
+            description: "First call predicts only. Arguments frozen when the token was minted; a changed field is discarded and disclosed.",
+        },
+    },
+    required: ["targetUrl", "sessionId"],
+    additionalProperties: false,
+};
+/** Resolves the start node and computes the identical prediction `predict_reach` would, from the
+ *  same pure planner. Shared by `describeAction` and `run` so the two can never compute two
+ *  different predictions for what a caller reads as one call. */
+function prepare(args, ctx) {
+    const nodeIdArg = optionalString(args, "nodeId");
+    const symbol = optionalString(args, "symbol");
+    const file = optionalString(args, "file");
+    const targetUrl = requiredString(args, "targetUrl");
+    const sessionId = requiredString(args, "sessionId");
+    const name = optionalString(args, "name") ?? "predicted-journey";
+    if (nodeIdArg === undefined && symbol === undefined && file === undefined) {
+        throw new ToolInputError('give one of "nodeId", "symbol" or "file"');
+    }
+    const found = resolveOneNode(ctx.session, { nodeId: nodeIdArg, symbol, file });
+    if (found.node === null) {
+        return { ok: false, candidates: found.candidates.map(briefNode), headline: found.headline, notes: found.notes };
+    }
+    const provider = ctx.session.provider();
+    const base = provider.baseStamp();
+    const predicted = predictThenPropose(provider, found.node.id, { targetUrl, name, savedAtCommit: base.commitSha ?? "" });
+    return { ok: true, value: { node: found.node, predicted, targetUrl, sessionId } };
+}
+function drivable(predicted) {
+    return predicted.proposal !== null && predicted.proposal.scenario.steps.length > 0;
+}
+function emptyReport(node, predicted) {
+    return {
+        from: node === null ? { id: "", type: "", name: "", resolution: 0 } : briefNode(node),
+        reachedPages: predicted === null ? [] : predicted.reachedPages.map((n) => ({ id: n.id, type: n.type, name: n.name, resolution: 0 })),
+        proposal: predicted?.proposal === null || predicted === null
+            ? null
+            : { scenario: predicted.proposal.scenario, reachedNotProposed: predicted.proposal.reachedNotProposed },
+        drive: null,
+        proof: null,
+        conclusion: null,
+    };
+}
+async function describeAction(args, ctx) {
+    const prep = prepare(args, ctx);
+    if (!prep.ok)
+        return undefined; // nothing resolvable — run() reports the refusal immediately, no gate
+    const { node, predicted, sessionId } = prep.value;
+    if (!drivable(predicted))
+        return undefined; // nothing to drive — run() reports the prediction alone
+    const steps = predicted.proposal.scenario.steps.length;
+    const pageNames = predicted.reachedPages.map((p) => p.name);
+    return (`drive ${steps} navigate step(s) in browser session "${sessionId}", toward ${predicted.reachedPages.length} ` +
+        `predicted page/component reached from ${node.name} (${pageNames.slice(0, 5).join(", ")}${pageNames.length > 5 ? ", …" : ""}), ` +
+        "then correlate what the drive actually reached — and any console error or failed request observed while " +
+        "it ran — into a governed finding via the same gate draw_conclusion uses.");
+}
+async function run(args, ctx) {
+    const prep = prepare(args, ctx);
+    const base = ctx.session.provider().baseStamp();
+    if (!prep.ok) {
+        return {
+            result: { data: { candidates: prep.candidates }, stamp: { ...base, resolutionFloor: 0 }, truncated: false, notes: prep.notes },
+            nameLevel: true,
+            state: "refused",
+            headline: prep.headline,
+        };
+    }
+    const { node, predicted, targetUrl, sessionId } = prep.value;
+    const notes = [...predicted.notes];
+    if (!drivable(predicted)) {
+        return answer({
+            headline: predicted.proposal === null
+                ? `${node.name} reaches no PAGE or COMPONENT this graph can walk to. Not a claim it reaches none in the running application — see notes.`
+                : `${node.name} reaches ${predicted.reachedPages.length} page/component, but none has a path-shaped route name — nothing to drive or prove.`,
+            state: "empty",
+            nameLevel: true,
+            resolutionFloor: 0,
+            commitSha: base.commitSha,
+            graphBuiltAt: base.graphBuiltAt,
+            irSchemaVersion: base.irSchemaVersion,
+            commitSpread: base.commitSpread,
+            repoCount: base.repoCount,
+            notes,
+            data: emptyReport(node, predicted),
+        });
+    }
+    // A non-empty proposal only reaches this line once the two-call handshake has already
+    // approved it — `describeAction` above gates every other case. Drive it, exactly as proposed.
+    const scenario = predicted.proposal.scenario;
+    const found = await useSession(ctx.session.browserSessions(), sessionId);
+    if (!found.ok) {
+        return browserAnswer({
+            ctx,
+            state: found.dead.state,
+            headline: found.dead.headline,
+            notes: [...notes, ...found.dead.notes],
+            data: emptyReport(node, predicted),
+        });
+    }
+    const { entry } = found;
+    if (!withinConsent(entry, targetUrl)) {
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `The predicted journey targets ${targetUrl}, outside this session's consent.`,
+            notes: [
+                ...notes,
+                `This session was consented for ${entry.consentedOrigin} only. Start a session against that origin to drive this prediction.`,
+            ],
+            data: emptyReport(node, predicted),
+        });
+    }
+    const refusedForSafety = mutationRefusal(entry);
+    if (refusedForSafety !== null && mutates(scenario)) {
+        // Dead in practice — proposeJourney only ever emits navigate steps — kept for the day a
+        // future planner proposes more, so a readOnly profile still refuses rather than driving.
+        return browserAnswer({
+            ctx,
+            state: "refused",
+            headline: `${entry.profile?.name ?? "This environment"} is read-only.`,
+            notes: [...notes, refusedForSafety],
+            data: emptyReport(node, predicted),
+        });
+    }
+    if (entry.page.currentUrl() !== scenario.targetUrl) {
+        await entry.page.navigate(scenario.targetUrl);
+    }
+    ctx.progress(`Driving the predicted journey from ${node.name}`);
+    const replay = await replayScenario(ctx, ctx.session.browserSessions(), sessionId, scenario, process.env, ctx.session.credentialStore);
+    const visited = visitedPageIds(predicted, targetUrl, replay.steps.map((s) => ({ url: s.url, status: s.status })));
+    const proof = proveOrDisprove(predicted, { visitedNodeIds: visited });
+    // The hypothesis's own structural mechanism — every page the walk predicted, not only the ones
+    // this one drive happened to confirm — so the finding's graphPath describes what the graph
+    // claims propagates, and the runtime evidence below is what says whether it broke anything.
+    const graphPath = combinedGraphPath(predicted, predicted.reachedPages.map((p) => p.id));
+    const runtimeEvidence = [
+        ...replay.evidence.consoleErrors.map((e) => ({ signal: "browser-console", detail: e.text, directMechanism: false })),
+        ...replay.evidence.failedRequests.map((r) => {
+            const reached = replay.graph.reached.find((n) => n.via.method === r.method && n.via.url === r.url);
+            return {
+                signal: "network",
+                detail: `${r.method} ${r.url} failed${r.status === null ? "" : ` (status ${r.status})`}`,
+                ...(reached === undefined ? {} : { nodeId: reached.nodeId, directMechanism: reached.nodeId === node.id }),
+            };
+        }),
+    ];
+    const hasRuntimeEvidence = evidencePrecondition(runtimeEvidence);
+    const resolution = minimumResolution(graphPath);
+    const humanAsserted = humanAssertedOnPath(graphPath);
+    const eSignals = independentSignalTypes(runtimeEvidence);
+    const mMechanism = directMechanismEvidence(runtimeEvidence, node.id);
+    const gated = reportCategory({
+        hasRuntimeEvidence,
+        independentSignalTypes: eSignals,
+        directMechanismEvidence: mMechanism,
+        resolution,
+        // Name-level throughout — a route path is read off a node's qualified name, same as
+        // predict_reach's own cap, never a type-checked shape.
+        nameLevel: true,
+        humanAsserted,
+    });
+    const proofNotes = [
+        `Drove the proposed journey for real: ${proof.proven.length} of ${predicted.reachedPages.length} predicted ` +
+            `page(s)/component(s) confirmed reached, ${proof.disproven.length} not reached by this drive.`,
+        hasRuntimeEvidence
+            ? `${runtimeEvidence.length} runtime observation(s) fed the gate — ${replay.evidence.consoleErrors.length} console error(s), ` +
+                `${replay.evidence.failedRequests.length} failed request(s).`
+            : "No console error or failed request was observed during this drive, so G3's evidence precondition fails " +
+                "and this reports unconfirmed regardless of the graph path — reaching a page cleanly is not evidence it broke.",
+    ];
+    return browserAnswer({
+        ctx,
+        headline: `"${node.name}": ${gated.category} (reliability ${gated.reliabilityClass}). Drove ${scenario.steps.length} step(s), ` +
+            `${proof.proven.length} predicted page(s) confirmed reached, ${proof.disproven.length} not.`,
+        notes: [...notes, ...proofNotes, ...replay.notes],
+        data: {
+            from: briefNode(node),
+            reachedPages: predicted.reachedPages.map((n) => ({ id: n.id, type: n.type, name: n.name, resolution: 0 })),
+            proposal: { scenario: predicted.proposal.scenario, reachedNotProposed: predicted.proposal.reachedNotProposed },
+            drive: {
+                outcome: replay.outcome,
+                steps: replay.steps.map((s) => ({ url: s.url, status: s.status })),
+                consoleErrorCount: replay.evidence.consoleErrors.length,
+                failedRequestCount: replay.evidence.failedRequests.length,
+            },
+            proof,
+            conclusion: {
+                failurePoint: node.id,
+                category: gated.category,
+                reliabilityClass: gated.reliabilityClass,
+                resolution,
+                independentSignalTypes: eSignals,
+                directMechanismEvidence: mMechanism,
+                hasRuntimeEvidence,
+            },
+        },
+    });
+}
+export const proveReachTool = {
+    name: "prove_reach",
+    class: "action",
+    tier: "conclusion",
+    version: "1.0.0",
+    title: "Predict which pages a data change reaches, then drive a real browser to prove or disprove it",
+    description: "Predicts which pages a data change reaches, then on a confirming call drives that journey " +
+        "for real and gates the result. Gated; acts on the running app. A clean page load reports " +
+        "unconfirmed, not proof of no bug.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=prove-reach.js.map

package/dist/tools/prove-reach.js.map

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

package/dist/tools/questions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `questions` — lets a human answer an open refusal question in this conversation.
+ * DEC-242: a refusal carries `attrs.blockedBy`+`refusalClass`. DEC-243: grouped into
+ * one question per pair; a dedicated read+write tool, not folded into `link_workspace`.
+ * DEC-223: a recorded answer caps at reliability class B regardless of anything else. */
+import type { RefusalDropCounts, RefusalQuestion } from "@descryy/core";
+import type { ConfirmedFact } from "@descryy/ir";
+import { type ToolDefinition } from "./kit.ts";
+/** Both halves of one conversation: the queue, and the answer that just shrank it.
+ *  Read and write together so a caller doesn't need two calls. */
+export interface QuestionsData {
+    /** The `ConfirmedFact` written by this call, or null when none given. A human
+     *  assertion, not a graph fact — capped at reliability class B (DEC-223) when
+     *  later used to mint an edge. */
+    readonly recorded: ConfirmedFact | null;
+    /** Rows a human could resolve, grouped by `blockedBy` — DEC-242's `value-unknown`
+     *  class only. A reader-capability gap or per-call value never appears here. */
+    readonly questions: readonly RefusalQuestion[];
+    /** Every refusal-ledger row, classified or not. The outer denominator. */
+    readonly totalRefusalRows: number;
+    /** Of those, how many carry `attrs.blockedBy`/`refusalClass` at all. The gap vs
+     *  `totalRefusalRows` is unclassified rows — never askable, not "still open". */
+    readonly classifiedRows: number;
+    /** Rows a stored confirmed fact already answers, so they are not listed as questions. */
+    readonly alreadyAnswered: number;
+    /** Rows dropped by refusal class, per DEC-242's own rule. */
+    readonly dropped: RefusalDropCounts;
+}
+export declare const questionsTool: ToolDefinition;
+//# sourceMappingURL=questions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"questions.d.ts","sourceRoot":"","sources":["../../src/tools/questions.ts"],"names":[],"mappings":"AAAA;;;;yFAIyF;AAGzF,OAAO,KAAK,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACxE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAGjD,OAAO,EAOL,KAAK,cAAc,EACpB,MAAM,UAAU,CAAC;AAIlB;kEACkE;AAClE,MAAM,WAAW,aAAa;IAC5B;;sCAEkC;IAClC,QAAQ,CAAC,QAAQ,EAAE,aAAa,GAAG,IAAI,CAAC;IACxC;oFACgF;IAChF,QAAQ,CAAC,SAAS,EAAE,SAAS,eAAe,EAAE,CAAC;IAC/C,0EAA0E;IAC1E,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC;qFACiF;IACjF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,yFAAyF;IACzF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,6DAA6D;IAC7D,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;CACrC;AAqQD,eAAO,MAAM,aAAa,EAAE,cAY3B,CAAC"}

package/dist/tools/questions.js

@@ -0,0 +1,230 @@
+/**
+ * `questions` — lets a human answer an open refusal question in this conversation.
+ * DEC-242: a refusal carries `attrs.blockedBy`+`refusalClass`. DEC-243: grouped into
+ * one question per pair; a dedicated read+write tool, not folded into `link_workspace`.
+ * DEC-223: a recorded answer caps at reliability class B regardless of anything else. */
+import { applyConfirmedFacts, counts, groupRefusalsIntoQuestions } from "@descryy/core";
+import { writeConfirmedFact } from "../session.js";
+import { answer, optionalEnum, optionalString, requiredString, ToolInputError, } from "./kit.js";
+import { capBySize, sizeCapNote } from "../capped.js";
+const SCHEMA = {
+    type: "object",
+    properties: {
+        answer: {
+            type: "object",
+            description: "Record a value for one question. Omit to just list what's open.",
+            properties: {
+                blockedBy: {
+                    type: "string",
+                    description: "Must equal a question's own \"blockedBy\" field exactly.",
+                },
+                value: { type: "string" },
+                environment: {
+                    type: "string",
+                    description: "Optional. A different environment is a new fact, not a replacement.",
+                },
+                confirmedBy: {
+                    type: "string",
+                    description: "Default \"user\".",
+                },
+                scope: {
+                    type: "string",
+                    enum: ["repo", "workspace"],
+                    description: "repo (default) or every linked repository, if the value is the same everywhere.",
+                },
+            },
+            required: ["blockedBy", "value"],
+            additionalProperties: false,
+        },
+        // Declared here, not only in the prose — `tool-schema-prose.test.ts` holds the
+        // registry to keeping documented and declared params in sync (a documented-but-
+        // undeclared param was once silently rejected under additionalProperties:false).
+        confirmToken: {
+            type: "string",
+            description: "Arguments frozen when the token was minted; a different \"answer\" is discarded and disclosed.",
+        },
+    },
+    additionalProperties: false,
+};
+/** The `answer` arg, read+validated once — shared by `describeAction` so mint and run
+ *  refuse identically (DEC-387: a `scope:"workspace"` answer was once described as
+ *  workspace-wide then refused on redemption). Reads only `config.workspace`, writes nothing. */
+function readAnswer(answerArg, session) {
+    if (typeof answerArg !== "object" || answerArg === null) {
+        throw new ToolInputError('"answer" must be an object');
+    }
+    const a = answerArg;
+    const blockedBy = requiredString(a, "blockedBy");
+    const value = requiredString(a, "value");
+    const environment = optionalString(a, "environment");
+    const confirmedBy = optionalString(a, "confirmedBy") ?? "user";
+    const scope = optionalEnum(a, "scope", ["repo", "workspace"]) ?? "repo";
+    if (scope === "workspace" && session.config.workspace === undefined) {
+        throw new ToolInputError('scope "workspace" needs a configured workspace, and this repository has none. Call ' +
+            '"link_workspace" first, or record this answer with scope "repo".');
+    }
+    return { blockedBy, value, environment, confirmedBy, scope };
+}
+function fitQuestions(rest, questions, budgetBytes) {
+    const scaffoldBytes = Buffer.byteLength(JSON.stringify({ ...rest, questions: [] }), "utf8");
+    const fit = capBySize(questions, budgetBytes, scaffoldBytes);
+    const notes = fit.droppedForSize === 0 ? [] : [sizeCapNote("open question", fit.shown.length, questions.length, fit.droppedForSize)];
+    return {
+        data: { ...rest, questions: fit.shown },
+        notes,
+        ...(fit.droppedForSize === 0
+            ? {}
+            : { truncatedDetail: { shown: fit.shown.length, total: questions.length, more: null } }),
+    };
+}
+async function run(args, ctx) {
+    const { session } = ctx;
+    const notes = [];
+    // `confirmedFacts` is readonly and loaded once at session start; merged locally below instead of a mid-call disk reload.
+    let facts = session.config.confirmedFacts;
+    let recorded = null;
+    const answerArg = args["answer"];
+    if (answerArg !== undefined) {
+        if (typeof answerArg !== "object" || answerArg === null) {
+            throw new ToolInputError('"answer" must be an object');
+        }
+        const { blockedBy, value, environment, confirmedBy, scope } = readAnswer(answerArg, session);
+        // `confirmedAtCommit`: repo's commit at answer time, so a later mint can tell if
+        // code moved since. Best-effort — no git history means no value, an absence not
+        // a guess; must never fail the recording because the disclosure couldn't.
+        const confirmedAtCommit = await session
+            .root()
+            .then((r) => r.commitSha)
+            .catch(() => undefined);
+        recorded = {
+            repo: session.config.repo,
+            blockedBy,
+            value,
+            ...(environment === undefined ? {} : { environment }),
+            confirmedBy,
+            confirmedAt: new Date().toISOString(),
+            ...(confirmedAtCommit === undefined ? {} : { confirmedAtCommit }),
+            scope,
+            // Stamped on the fact, not looked up at read time — a fact must not reach
+            // further because its repo was later re-linked into a different workspace.
+            ...(scope === "workspace" && session.config.workspace !== undefined
+                ? { workspace: session.config.workspace }
+                : {}),
+        };
+        ctx.progress(`Recording an answer for ${blockedBy}${environment === undefined ? "" : ` (${environment})`}`);
+        const written = await writeConfirmedFact(session.repoPath, recorded);
+        const sameKey = (f) => f.repo === recorded?.repo && f.blockedBy === recorded.blockedBy && f.environment === recorded.environment;
+        facts = [...facts.filter((f) => !sameKey(f)), recorded];
+        notes.push(written.replaced === null
+            ? `Recorded a new answer for "${blockedBy}"${environment === undefined ? "" : ` in "${environment}"`}.`
+            : `Replaced the previous answer for "${blockedBy}"` +
+                `${environment === undefined ? "" : ` in "${environment}"`} (was "${written.replaced.value}", ` +
+                `confirmed ${written.replaced.confirmedAt}).`);
+    }
+    ctx.progress("Reading the refusal ledger");
+    const provider = session.provider();
+    const { refs, truncated } = provider.unresolvedRefs();
+    const total = counts(session.store().driver).unresolvedRefs;
+    // Plus workspace-scoped facts from `link_workspace` siblings. `applyConfirmedFacts`
+    // decides which actually reach this repo — this call only supplies candidates.
+    const { answered, stillOpen } = applyConfirmedFacts(refs, [...facts, ...(session.config.linkedFacts ?? [])], session.config.repo, session.config.workspace);
+    const grouped = groupRefusalsIntoQuestions(session.config.repo, stillOpen);
+    if (truncated) {
+        notes.push("The classified-refusal read was capped and some rows were not examined — this list may be " +
+            "incomplete. Re-run with a narrower scope, or treat this as a lower bound.");
+    }
+    if (total > refs.length) {
+        notes.push(`${total - refs.length} of ${total} refusal-ledger row(s) carry no classification at all yet ` +
+            "(no adapter has set attrs.blockedBy/refusalClass for them) — never askable, not counted " +
+            "above, and not the same population as \"still open\".");
+    }
+    if (answered.length > 0) {
+        notes.push(`${answered.length} previously-open row(s) are already answered by a stored confirmed fact and ` +
+            "are not listed as questions.");
+        // Named, never folded in — "answered here" vs "answered elsewhere as workspace-wide"
+        // are different facts, and only the second carries the risk `scope` makes deliberate.
+        const elsewhere = answered.filter((a) => a.fromAnotherRepo);
+        if (elsewhere.length > 0) {
+            const repos = [...new Set(elsewhere.flatMap((a) => a.facts.map((f) => f.repo)))].sort();
+            notes.push(`${elsewhere.length} of those are answered only by workspace-scoped fact(s) recorded in ` +
+                `${repos.join(", ")}, not in ${session.config.repo}. They apply here because whoever ` +
+                `recorded them declared scope "workspace", not because this tool matched on the name.`);
+        }
+    }
+    for (const [cls, count] of Object.entries(grouped.dropped)) {
+        if (cls === "value-unknown")
+            continue; // never dropped under its own class name
+        notes.push(`${count} row(s) are "${cls}" — DEC-242's own rule: not askable, never surfaced here.`);
+    }
+    const headline = grouped.questions.length === 0
+        ? recorded !== null
+            ? `Answer recorded. No open questions remain in ${session.config.repo}.`
+            : `No open questions in ${session.config.repo}. ${refs.length} classified refusal row(s) examined.`
+        : `${grouped.questions.length} open question(s) in ${session.config.repo}, covering ` +
+            `${grouped.questions.reduce((n, q) => n + q.sites.length, 0)} call site(s).`;
+    return answer({
+        headline,
+        // Name-level fact (expression present or not, same class as a missing env var).
+        // `UnresolvedRef` carries no resolution level (refusals aren't edges, DEC-223),
+        // so R0 is the honest floor — same choice `link_workspace` makes, same reason.
+        nameLevel: true,
+        resolutionFloor: 0,
+        commitSha: provider.baseStamp().commitSha,
+        graphBuiltAt: provider.baseStamp().graphBuiltAt,
+        irSchemaVersion: provider.baseStamp().irSchemaVersion,
+        commitSpread: provider.baseStamp().commitSpread,
+        repoCount: provider.baseStamp().repoCount,
+        // Empty only for a pure read finding nothing open (`classifiedRows` is real).
+        // An answer that happens to empty the queue is a write, not an empty search.
+        ...(recorded === null && grouped.questions.length === 0 ? { state: "empty" } : {}),
+        notes,
+        data: {
+            recorded,
+            questions: grouped.questions,
+            totalRefusalRows: total,
+            classifiedRows: refs.length,
+            alreadyAnswered: answered.length,
+            dropped: grouped.dropped,
+        },
+        fitToBudget: (budgetBytes) => fitQuestions({
+            recorded,
+            totalRefusalRows: total,
+            classifiedRows: refs.length,
+            alreadyAnswered: answered.length,
+            dropped: grouped.dropped,
+        }, grouped.questions, budgetBytes),
+    });
+}
+/** §7's handshake gate. `undefined` = nothing to confirm (pure read must stay
+ *  answerable on the first call). Only a write-bound call describes itself, so
+ *  `resolveActionDispatch` mints a token for that call alone. */
+function describeAction(args, ctx) {
+    const answerArg = args["answer"];
+    // No `answer` = pure read, nothing to confirm — gating it would block the first
+    // question ever asked. Other shapes reuse `readAnswer`, so an invalid call is
+    // refused here rather than described and minted.
+    if (answerArg === undefined)
+        return undefined;
+    const { blockedBy, value, environment, scope } = readAnswer(answerArg, ctx.session);
+    return (`record a ConfirmedFact: "${blockedBy}" = "${value}"` +
+        (typeof environment === "string" ? ` (environment: ${environment})` : "") +
+        // Reach is part of what's approved — a workspace answer affects repos the
+        // approver isn't looking at; §7's handshake exists so nothing runs undescribed.
+        (scope === "workspace"
+            ? " — reaching EVERY repository in this workspace, not just this one,"
+            : " — in this repository only,") +
+        " capped at reliability class B (DEC-223) once used.");
+}
+export const questionsTool = {
+    name: "questions",
+    class: "action",
+    tier: "evidence",
+    version: "1.0.0",
+    title: "See and answer open refusal-ledger questions",
+    description: "List open questions a human can resolve. \"answer\" records a value, capped at reliability " +
+        "B. Gated: first call returns a token; confirmToken records it.",
+    inputSchema: SCHEMA,
+    run,
+    describeAction,
+};
+//# sourceMappingURL=questions.js.map