@descryy/mcp 0.6.0 → 0.7.0

package/dist/browser/tool-support.js

@@ -1,11 +1,7 @@
-/**
- * What the seven browser tools share.
- *
- * Kept in one place because the parts that repeat are the parts that must not
- * drift: how a dead session is reported, how consent is checked, and how a
- * reply is stamped. Seven copies of a refusal is seven chances for one of
- * them to say something slightly different about the same state.
- */
+/** What the seven browser tools share — kept in one place because the parts that repeat
+ *  are the parts that must not drift: how a dead session is reported, how consent is
+ *  checked, how a reply is stamped. Seven copies of a refusal is seven chances for one to
+ *  say something slightly different about the same state. */
 import { answer } from "../tools/kit.js";
 import { evidenceNotes, evidenceReport } from "./evidence.js";
 import { graphWriteNotes, writeBrowserObservations, NO_GRAPH_WRITE } from "./graph-write.js";
@@ -31,15 +27,9 @@ export function browserStamp(ctx) {
         };
     }
 }
-/**
- * Every browser reply, stamped identically.
- *
- * `resolutionFloor: 4` on a successful observation, and that is not
- * generosity: R4 is "observed at runtime", and a page element this call
- * actually saw is the definition of it. A refusal or a failure observed
- * nothing, so it stamps R0 — the floor has to describe the evidence behind
- * *this* reply, not the tool's best case.
- */
+/** Every browser reply, stamped identically. `resolutionFloor: 4` on success — R4 is
+ *  "observed at runtime", exactly what this call saw; a refusal/failure observed nothing,
+ *  so stamps R0 — describing this reply's evidence, not the tool's best case. */
 export function browserAnswer(options) {
     const stamp = browserStamp(options.ctx);
     const observed = (options.state ?? "ok") === "ok";
@@ -60,14 +50,9 @@ export function browserAnswer(options) {
         ...(options.fitToBudget === undefined ? {} : { fitToBudget: options.fitToBudget }),
     });
 }
-/**
- * Look a session up, or describe exactly why it cannot be used.
- *
- * The three dead states are deliberately not collapsed into one. "You never
- * had this session", "it timed out five minutes ago, here is what it saw" and
- * "the browser crashed" are three different things for a caller to do next,
- * and only the last of them is a `failed`.
- */
+/** Looks a session up, or says exactly why it can't be used. The three dead states stay
+ *  apart — "never had it", "timed out, here's what it saw", "crashed" send a caller to
+ *  three different things; only the last is `failed`. */
 export async function useSession(registry, sessionId) {
     const used = await registry.use(sessionId);
     if (used.ok)
@@ -82,8 +67,7 @@ export async function useSession(registry, sessionId) {
     return {
         ok: false,
         dead: {
-            // A crash is something breaking; a reap is Descry having tidied up. The
-            // five states exist to keep those apart.
+            // A crash is something breaking; a reap is Descry tidying up — the five states keep those apart.
             state: used.kind === "crashed" ? "failed" : "refused",
             headline: used.kind === "crashed" ? `Browser session ${sessionId} crashed.` : `Browser session ${sessionId} is gone.`,
             notes: [used.reason, ...carried],
@@ -91,19 +75,9 @@ export async function useSession(registry, sessionId) {
         },
     };
 }
-/**
- * Drain what the page has said, relate it to the graph, and produce both the
- * payload and the disclosures in one place.
- *
- * Every evidence-bearing browser tool goes through this rather than draining
- * for itself. Two reasons, and the second is the one that matters: a tool
- * that drained without correlating would be a tool through which the R4 write
- * silently does not happen, and nothing about its reply would look different.
- *
- * A repository with no graph correlates nothing and says so. That is a real
- * state — a developer can drive a browser against an app they have never
- * analysed — and it must not look like "we looked and found no connection".
- */
+/** Drains page evidence, relates it to the graph, and returns both in one place — every
+ *  evidence-bearing tool routes through this so the R4 write can't silently not happen.
+ *  No graph correlates nothing and says so; that's real, not "found no connection". */
 export async function observeAndCorrelate(ctx, entry) {
     const observation = await entry.page.drainEvidence();
     const evidence = evidenceReport(observation);
@@ -116,10 +90,8 @@ export async function observeAndCorrelate(ctx, entry) {
                 driver: ctx.session.store().driver,
                 repo: ctx.session.config.repo,
                 runId: entry.runId,
-                // An edge records the commit the observed application was built from,
-                // so a later reader can tell whether the code moved under the
-                // observation. Absent that, the observation is still real but cannot
-                // be dated against the source, so it is not written at all.
+                // An edge records the commit the app was built from, so a reader can tell if code
+                // moved since. Without it, the observation is real but undatable against source, so not written.
                 commitSha: commitSha ?? "",
                 repoRoot: ctx.session.repoPath,
                 requests: observation.requests,
@@ -139,27 +111,9 @@ export function emptyEvidence() {
 export function reportOf(observation) {
     return evidenceReport(observation);
 }
-/**
- * Is `url` inside the origin this session was consented for?
- *
- * The consent ruling's one hard bound. Checked here rather than in each verb
- * so that a future eighth tool cannot forget it.
- */
-/**
- * Does this session's environment profile permit changing the application?
- *
- * Read off the profile the session was opened under — DEC-270's
- * `safetyLevel`, the same field `observe_runtime` consults. Deliberately not
- * a per-tool flag: two independent notions of "safe" is how a runtime run and
- * a browser run end up disagreeing about the same environment.
- *
- * A session opened with no profile returns null here, and the session's own
- * consent is then the only authorization — which is a real authorization,
- * granted explicitly at `browser_start_session` against a named origin. The
- * two are independent and both must pass: consent answers *may Descry drive a
- * browser against this target at all*, the profile answers *may it mutate*,
- * and neither excuses the other.
- */
+/** Does the session's environment profile permit changing the application? Reads DEC-270's
+ *  `safetyLevel` (same field `observe_runtime` consults), not a per-tool flag — two "safe"
+ *  notions could disagree. No profile ⇒ null; consent and profile are independent, both must pass. */
 export function mutationRefusal(entry) {
     if (entry.profile === null)
         return null;
@@ -170,6 +124,8 @@ export function mutationRefusal(entry) {
         "browser_navigate and browser_snapshot read the page and remain available. This is a fact about the " +
         "profile you supplied, not about the page — the session's own consent is intact and does not override it.");
 }
+/** Is `url` inside the origin this session was consented for? The consent ruling's one
+ *  hard bound — checked here, not in each verb, so a future eighth tool can't forget it. */
 export function withinConsent(entry, url) {
     try {
         return new URL(url).origin === entry.consentedOrigin;

package/dist/browser/tool-support.js.map

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

package/dist/browser/url-scheme.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Which URL schemes `browser_start_session` may open (A-F7). `file:`/`data:` resolve
+ * `.origin` to `"null"`, so same-origin containment passes for every local file (e.g.
+ * `file:///etc/passwd` reads back as inside consent). Only http:/https: trusted by
+ * default; opt in extras via `DESCRY_ALLOW_BROWSER_URL_SCHEMES`. */
+export declare const ALLOW_BROWSER_URL_SCHEMES_ENV_VAR = "DESCRY_ALLOW_BROWSER_URL_SCHEMES";
+export type UrlSchemeDecision = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+export declare function checkUrlScheme(url: URL): UrlSchemeDecision;
+//# sourceMappingURL=url-scheme.d.ts.map

package/dist/browser/url-scheme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-scheme.d.ts","sourceRoot":"","sources":["../../src/browser/url-scheme.ts"],"names":[],"mappings":"AAAA;;;;oEAIoE;AAEpE,eAAO,MAAM,iCAAiC,qCAAqC,CAAC;AAepF,MAAM,MAAM,iBAAiB,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAOlH,wBAAgB,cAAc,CAAC,GAAG,EAAE,GAAG,GAAG,iBAAiB,CAa1D"}

package/dist/browser/url-scheme.js

@@ -0,0 +1,38 @@
+/**
+ * Which URL schemes `browser_start_session` may open (A-F7). `file:`/`data:` resolve
+ * `.origin` to `"null"`, so same-origin containment passes for every local file (e.g.
+ * `file:///etc/passwd` reads back as inside consent). Only http:/https: trusted by
+ * default; opt in extras via `DESCRY_ALLOW_BROWSER_URL_SCHEMES`. */
+export const ALLOW_BROWSER_URL_SCHEMES_ENV_VAR = "DESCRY_ALLOW_BROWSER_URL_SCHEMES";
+const DEFAULT_ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+function operatorAllowedSchemes() {
+    const raw = process.env[ALLOW_BROWSER_URL_SCHEMES_ENV_VAR];
+    if (raw === undefined || raw.trim() === "")
+        return DEFAULT_ALLOWED_SCHEMES;
+    const extra = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s !== "")
+        .map((s) => (s.endsWith(":") ? s : `${s}:`));
+    return new Set([...DEFAULT_ALLOWED_SCHEMES, ...extra]);
+}
+/** The one exception: `about:blank` carries no content (no hazard like `file:`/`data:`)
+ *  and is the standard pre-navigation target for browser automation. Other `about:`
+ *  URLs (`about:config`, …) can expose browser-internal state and are excluded. */
+const INERT_TARGET = "about:blank";
+export function checkUrlScheme(url) {
+    if (url.href === INERT_TARGET)
+        return { allowed: true };
+    const allowed = operatorAllowedSchemes();
+    if (allowed.has(url.protocol))
+        return { allowed: true };
+    return {
+        allowed: false,
+        reason: `"${url.href}" uses the "${url.protocol}" scheme, which this tool does not open by default. Same-origin ` +
+            "containment (the check every other browser tool relies on) does not hold for a file: or data: URL — " +
+            'both resolve to the origin "null", so a session opened on one would treat every local file as inside ' +
+            `consent. Only http: and https: are allowed by default; set ${ALLOW_BROWSER_URL_SCHEMES_ENV_VAR} ` +
+            '(e.g. "file") in this server\'s own environment to add a scheme deliberately.',
+    };
+}
+//# sourceMappingURL=url-scheme.js.map

package/dist/browser/url-scheme.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-scheme.js","sourceRoot":"","sources":["../../src/browser/url-scheme.ts"],"names":[],"mappings":"AAAA;;;;oEAIoE;AAEpE,MAAM,CAAC,MAAM,iCAAiC,GAAG,kCAAkC,CAAC;AAEpF,MAAM,uBAAuB,GAAG,IAAI,GAAG,CAAC,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAE7D,SAAS,sBAAsB;IAC7B,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iCAAiC,CAAC,CAAC;IAC3D,IAAI,GAAG,KAAK,SAAS,IAAI,GAAG,CAAC,IAAI,EAAE,KAAK,EAAE;QAAE,OAAO,uBAAuB,CAAC;IAC3E,MAAM,KAAK,GAAG,GAAG;SACd,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;SACpB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC;SACvB,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAC/C,OAAO,IAAI,GAAG,CAAC,CAAC,GAAG,uBAAuB,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAID;;mFAEmF;AACnF,MAAM,YAAY,GAAG,aAAa,CAAC;AAEnC,MAAM,UAAU,cAAc,CAAC,GAAQ;IACrC,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACxD,MAAM,OAAO,GAAG,sBAAsB,EAAE,CAAC;IACzC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,QAAQ,CAAC;QAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC;IACxD,OAAO;QACL,OAAO,EAAE,KAAK;QACd,MAAM,EACJ,IAAI,GAAG,CAAC,IAAI,eAAe,GAAG,CAAC,QAAQ,kEAAkE;YACzG,sGAAsG;YACtG,uGAAuG;YACvG,8DAA8D,iCAAiC,GAAG;YAClG,+EAA+E;KAClF,CAAC;AACJ,CAAC"}

package/dist/cancellation.d.ts

@@ -1,53 +1,18 @@
-/**
- * What a tool does when the caller has already gone.
- *
- * `notifications/cancelled` makes the *server* stop waiting and suppress the
- * response. It cannot make the work stop, and for the tools that hold
- * something real — a browser, an application, a test runner — the work
- * continuing after the reply is discarded is the whole problem: a Chromium
- * nothing will ever close, an application still being driven, a scenario
- * still clicking through a live system on behalf of a caller who cancelled.
- *
- * So `ctx.signal` is checked at the points where a tool is about to *start*
- * something, and whatever the tool already started is released. Three rules
- * hold everywhere it is used:
- *
- * 1. **Release what this call started, and nothing else.** A cancelled verb
- *    does not close the session `browser_start_session` opened, and a
- *    cancelled run does not kill a process it merely attached to. Cancellation
- *    stops the work it was asked to stop; tearing down a caller's own state
- *    because one call was cancelled is a second failure, not a cleanup.
- * 2. **Keep the evidence.** Nothing witnessed before the cancellation is
- *    thrown away. Evidence captured and then dropped is worse than evidence
- *    never captured, because nothing discloses it.
- * 3. **Never let a cancelled run render as a clean one.** A check that stopped
- *    a third of the way through has not passed, and the reply says so even
- *    though nobody is expected to read it — the reply is suppressed only when
- *    the cancellation arrived over the wire, and this same path is reachable
- *    when a signal is aborted for any other reason.
- *
- * The state is `refused`: cancellation is a fact about Descry — it stopped
- * looking — and never a fact about the user's code. `empty` would say the run
- * looked and found nothing, which is the one thing it must not say.
- */
+/** What a tool does when the caller has already gone. `notifications/cancelled` stops the
+ *  server from waiting, not the work itself — a browser or process would keep running
+ *  unless released. Three rules: release only what this call started (never a caller's own
+ *  state), keep evidence already witnessed, never render a cancelled run as clean. State is
+ *  `refused` (a fact about Descry stopping) not `empty` (which would falsely say it looked and found nothing). */
 /** The reply state for a call that stopped because its signal was aborted. */
 export declare const CANCELLED_STATE: "refused";
 export declare function cancellationHeadline(what: string): string;
-/**
- * @param stopped What this call stopped doing, in the caller's terms.
- * @param released What it tore down, when it had started something. Omitted
- * when there was nothing to release — claiming a teardown that did not happen
- * is the same class of false statement as hiding one that did.
- */
+/** @param stopped What this call stopped doing, in the caller's terms.
+ *  @param released What it tore down, if anything — omitted when nothing was released;
+ *  claiming a teardown that didn't happen is as false as hiding one that did. */
 export declare function cancellationNotes(stopped: string, released?: string): readonly string[];
-/**
- * A promise that settles when the signal aborts, and a way to stop listening.
- *
- * The disposal half is the point. `Promise.race` leaves the losing promise
- * pending forever, so a listener added per call and never removed accumulates
- * on a signal that outlives the call — the standard leak this shape exists to
- * avoid. Callers race and then dispose in a `finally`.
- */
+/** A promise that settles when the signal aborts, plus a way to stop listening.
+ *  `Promise.race` leaves the loser pending forever, so an unremoved listener leaks on a
+ *  signal that outlives the call — callers race then dispose in a `finally`. */
 export declare function whenAborted(signal: AbortSignal): {
     readonly promise: Promise<void>;
     dispose(): void;

package/dist/cancellation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAG,SAAkB,CAAC;AAElD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAMvF;AAED;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,IAAI,IAAI,CAAA;CAAE,CAgBrG"}
+{"version":3,"file":"cancellation.d.ts","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAAA;;;;kHAIkH;AAElH,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAG,SAAkB,CAAC;AAElD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;iFAEiF;AACjF,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAMvF;AAED;;gFAEgF;AAChF,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,GAAG;IAAE,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,IAAI,CAAC,CAAC;IAAC,OAAO,IAAI,IAAI,CAAA;CAAE,CAgBrG"}

package/dist/cancellation.js

@@ -1,46 +1,16 @@
-/**
- * What a tool does when the caller has already gone.
- *
- * `notifications/cancelled` makes the *server* stop waiting and suppress the
- * response. It cannot make the work stop, and for the tools that hold
- * something real — a browser, an application, a test runner — the work
- * continuing after the reply is discarded is the whole problem: a Chromium
- * nothing will ever close, an application still being driven, a scenario
- * still clicking through a live system on behalf of a caller who cancelled.
- *
- * So `ctx.signal` is checked at the points where a tool is about to *start*
- * something, and whatever the tool already started is released. Three rules
- * hold everywhere it is used:
- *
- * 1. **Release what this call started, and nothing else.** A cancelled verb
- *    does not close the session `browser_start_session` opened, and a
- *    cancelled run does not kill a process it merely attached to. Cancellation
- *    stops the work it was asked to stop; tearing down a caller's own state
- *    because one call was cancelled is a second failure, not a cleanup.
- * 2. **Keep the evidence.** Nothing witnessed before the cancellation is
- *    thrown away. Evidence captured and then dropped is worse than evidence
- *    never captured, because nothing discloses it.
- * 3. **Never let a cancelled run render as a clean one.** A check that stopped
- *    a third of the way through has not passed, and the reply says so even
- *    though nobody is expected to read it — the reply is suppressed only when
- *    the cancellation arrived over the wire, and this same path is reachable
- *    when a signal is aborted for any other reason.
- *
- * The state is `refused`: cancellation is a fact about Descry — it stopped
- * looking — and never a fact about the user's code. `empty` would say the run
- * looked and found nothing, which is the one thing it must not say.
- */
+/** What a tool does when the caller has already gone. `notifications/cancelled` stops the
+ *  server from waiting, not the work itself — a browser or process would keep running
+ *  unless released. Three rules: release only what this call started (never a caller's own
+ *  state), keep evidence already witnessed, never render a cancelled run as clean. State is
+ *  `refused` (a fact about Descry stopping) not `empty` (which would falsely say it looked and found nothing). */
 /** The reply state for a call that stopped because its signal was aborted. */
 export const CANCELLED_STATE = "refused";
 export function cancellationHeadline(what) {
     return `The call was cancelled; ${what}.`;
 }
-/**
- * @param stopped What this call stopped doing, in the caller's terms.
- * @param released What it tore down, when it had started something. Omitted
- * when there was nothing to release — claiming a teardown that did not happen
- * is the same class of false statement as hiding one that did.
- */
+/** @param stopped What this call stopped doing, in the caller's terms.
+ *  @param released What it tore down, if anything — omitted when nothing was released;
+ *  claiming a teardown that didn't happen is as false as hiding one that did. */
 export function cancellationNotes(stopped, released) {
     return [
         `This call was cancelled before it finished. ${stopped} Nothing here is a finding about your ` +
@@ -48,14 +18,9 @@ export function cancellationNotes(stopped, released) {
         ...(released === undefined ? [] : [released]),
     ];
 }
-/**
- * A promise that settles when the signal aborts, and a way to stop listening.
- *
- * The disposal half is the point. `Promise.race` leaves the losing promise
- * pending forever, so a listener added per call and never removed accumulates
- * on a signal that outlives the call — the standard leak this shape exists to
- * avoid. Callers race and then dispose in a `finally`.
- */
+/** A promise that settles when the signal aborts, plus a way to stop listening.
+ *  `Promise.race` leaves the loser pending forever, so an unremoved listener leaks on a
+ *  signal that outlives the call — callers race then dispose in a `finally`. */
 export function whenAborted(signal) {
     if (signal.aborted)
         return { promise: Promise.resolve(), dispose: () => { } };

package/dist/cancellation.js.map

@@ -1 +1 @@
-{"version":3,"file":"cancellation.js","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,SAAkB,CAAC;AAElD,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,2BAA2B,IAAI,GAAG,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,QAAiB;IAClE,OAAO;QACL,+CAA+C,OAAO,wCAAwC;YAC5F,oDAAoD;QACtD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAE7E,IAAI,OAAO,GAAe,GAAG,EAAE,GAAE,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,OAAO,GAAG,GAAG,EAAE;YACb,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IACH,OAAO;QACL,OAAO;QACP,OAAO,EAAE,GAAG,EAAE;YACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"cancellation.js","sourceRoot":"","sources":["../src/cancellation.ts"],"names":[],"mappings":"AAAA;;;;kHAIkH;AAElH,8EAA8E;AAC9E,MAAM,CAAC,MAAM,eAAe,GAAG,SAAkB,CAAC;AAElD,MAAM,UAAU,oBAAoB,CAAC,IAAY;IAC/C,OAAO,2BAA2B,IAAI,GAAG,CAAC;AAC5C,CAAC;AAED;;iFAEiF;AACjF,MAAM,UAAU,iBAAiB,CAAC,OAAe,EAAE,QAAiB;IAClE,OAAO;QACL,+CAA+C,OAAO,wCAAwC;YAC5F,oDAAoD;QACtD,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC;KAC9C,CAAC;AACJ,CAAC;AAED;;gFAEgF;AAChF,MAAM,UAAU,WAAW,CAAC,MAAmB;IAC7C,IAAI,MAAM,CAAC,OAAO;QAAE,OAAO,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC,EAAE,CAAC;IAE7E,IAAI,OAAO,GAAe,GAAG,EAAE,GAAE,CAAC,CAAC;IACnC,MAAM,OAAO,GAAG,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,EAAE;QAC5C,OAAO,GAAG,GAAG,EAAE;YACb,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;IAC5D,CAAC,CAAC,CAAC;IACH,OAAO;QACL,OAAO;QACP,OAAO,EAAE,GAAG,EAAE;YACZ,MAAM,CAAC,mBAAmB,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QAC/C,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/capped.d.ts

@@ -1,41 +1,17 @@
-/**
- * `capped(items, limit) → { shown, detail }` — B6's fix, part 2.
- *
- * `render.ts`'s envelope carries a `truncated` field precisely so a caller
- * does not have to guess whether a short list is short because that is all
- * there was, or because the reply was cut. Before this helper existed, three
- * tools computed that cut three different ways: one sliced and remembered to
- * report `shown`/`total` by hand, one sliced and forgot, one never sliced at
- * all but discarded rows anyway. Two of the three left `render.ts` with
- * nothing to report and it filled the gap with a sentinel
- * (`{shown:-1,total:-1}`) that is worse than reporting nothing, because it
- * passes a presence check and then poisons arithmetic.
- *
- * This is the fix: the slice and the fact that a slice happened are computed
- * together, in one call, so a tool cannot hold one without the other. A tool
- * that caps a list calls this instead of `.slice(0, limit)`, and then has a
- * `detail` sitting right next to `shown` with nothing further to remember.
- */
+/** `capped(items, limit) → { shown, detail }`, B6's fix. Three tools used to compute a list cut
+ *  three different ways; two left `render.ts` filling the gap with a `{shown:-1,total:-1}`
+ *  sentinel — worse than nothing, since it passes a presence check and poisons arithmetic. Now the
+ *  slice and the fact it happened are computed together, so a tool can't hold one without the other. */
 import type { TruncationDetail } from "./render.ts";
 export interface Capped<T> {
     /** The first `limit` items, in their original order. */
     readonly shown: readonly T[];
-    /**
-     * `null` when nothing was withheld — `shown` already holds everything
-     * `items` had. Non-null exactly when `shown.length < items.length`, and
-     * carries the same `{shown, total}` shape `render.ts` puts on the wire, so
-     * a tool can pass it straight through as `truncatedDetail`.
-     */
+    /** `null` when nothing was withheld; otherwise the same `{shown, total}` shape `render.ts` puts
+     *  on the wire, so a tool can pass it straight through as `truncatedDetail`. */
     readonly detail: TruncationDetail | null;
 }
-/**
- * Slice `items` to `limit` and report what that cost in the same call.
- *
- * A negative or fractional `limit` is treated as zero rather than thrown —
- * the callers here already validate `limit` as a positive integer at the
- * schema boundary (`optionalInteger(..., 1)`), so a non-positive value
- * reaching this function is defensive, not an expected input to reject
- * loudly.
- */
+/** Slices `items` to `limit` and reports the cost in the same call. A negative/fractional `limit`
+ *  is treated as zero rather than thrown — defensive only, callers already validate at the schema
+ *  boundary. */
 export declare function capped<T>(items: readonly T[], limit: number): Capped<T>;
 //# sourceMappingURL=capped.d.ts.map

package/dist/capped.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capped.d.ts","sourceRoot":"","sources":["../src/capped.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC1C;AAED;;;;;;;;GAQG;AACH,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAKvE"}
+{"version":3,"file":"capped.d.ts","sourceRoot":"","sources":["../src/capped.ts"],"names":[],"mappings":"AAAA;;;wGAGwG;AAExG,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,MAAM,CAAC,CAAC;IACvB,wDAAwD;IACxD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B;oFACgF;IAChF,QAAQ,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI,CAAC;CAC1C;AAED;;gBAEgB;AAChB,wBAAgB,MAAM,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,EAAE,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,CAKvE"}

package/dist/capped.js

@@ -1,30 +1,10 @@
-/**
- * `capped(items, limit) → { shown, detail }` — B6's fix, part 2.
- *
- * `render.ts`'s envelope carries a `truncated` field precisely so a caller
- * does not have to guess whether a short list is short because that is all
- * there was, or because the reply was cut. Before this helper existed, three
- * tools computed that cut three different ways: one sliced and remembered to
- * report `shown`/`total` by hand, one sliced and forgot, one never sliced at
- * all but discarded rows anyway. Two of the three left `render.ts` with
- * nothing to report and it filled the gap with a sentinel
- * (`{shown:-1,total:-1}`) that is worse than reporting nothing, because it
- * passes a presence check and then poisons arithmetic.
- *
- * This is the fix: the slice and the fact that a slice happened are computed
- * together, in one call, so a tool cannot hold one without the other. A tool
- * that caps a list calls this instead of `.slice(0, limit)`, and then has a
- * `detail` sitting right next to `shown` with nothing further to remember.
- */
-/**
- * Slice `items` to `limit` and report what that cost in the same call.
- *
- * A negative or fractional `limit` is treated as zero rather than thrown —
- * the callers here already validate `limit` as a positive integer at the
- * schema boundary (`optionalInteger(..., 1)`), so a non-positive value
- * reaching this function is defensive, not an expected input to reject
- * loudly.
- */
+/** `capped(items, limit) → { shown, detail }`, B6's fix. Three tools used to compute a list cut
+ *  three different ways; two left `render.ts` filling the gap with a `{shown:-1,total:-1}`
+ *  sentinel — worse than nothing, since it passes a presence check and poisons arithmetic. Now the
+ *  slice and the fact it happened are computed together, so a tool can't hold one without the other. */
+/** Slices `items` to `limit` and reports the cost in the same call. A negative/fractional `limit`
+ *  is treated as zero rather than thrown — defensive only, callers already validate at the schema
+ *  boundary. */
 export function capped(items, limit) {
     const bound = Number.isFinite(limit) && limit > 0 ? Math.floor(limit) : 0;
     const shown = items.slice(0, bound);

package/dist/capped.js.map

@@ -1 +1 @@
-{"version":3,"file":"capped.js","sourceRoot":"","sources":["../src/capped.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAgBH;;;;;;;;GAQG;AACH,MAAM,UAAU,MAAM,CAAI,KAAmB,EAAE,KAAa;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACjE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;AACrF,CAAC"}
+{"version":3,"file":"capped.js","sourceRoot":"","sources":["../src/capped.ts"],"names":[],"mappings":"AAAA;;;wGAGwG;AAYxG;;gBAEgB;AAChB,MAAM,UAAU,MAAM,CAAI,KAAmB,EAAE,KAAa;IAC1D,MAAM,KAAK,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC1E,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;IACjE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,CAAC;AACrF,CAAC"}

package/dist/disclosure-ledger.d.ts

@@ -1,35 +1,11 @@
 /**
- * Which standing disclosures this connection has already been given in full.
- *
- * The tax it removes was measured, not supposed: the R0/class-C reliability
- * sentence is 354 characters — ~88 tokens — and appeared byte-for-byte
- * identical on the large majority of one session's thirty-odd tool calls.
- * Nothing about it was wrong; it was simply the same paragraph, re-billed to
- * the caller's context window every call, and the loop this server is built
- * for (edit, re-check, edit again) is the one that pays it most.
- *
- * ## What the ledger is allowed to shorten, and what it is not
- *
- * Only the *argument* for a cap. The floor and the class it caps to stay on
- * every reply, first or fiftieth, in `graph.resolutionFloor` /
- * `graph.reliabilityCap` and in the short disclosure itself. Rule 7 is about
- * what reaches the user, and a reply that stopped naming its own cap after
- * the first call would be a reply that silently does less.
- *
- * ## Per connection, deliberately not per process
- *
- * "Already disclosed" is a fact about one conversation. A ledger shared across
- * connections would let the *second* client's first call inherit the first
- * client's history — that client would receive the short form of a sentence it
- * has never seen, which is the exact failure this is supposed to avoid, only
- * harder to notice. So one ledger is created per `createMcpServer`, and it
- * lives as long as that server does.
- */
+ * Tracks disclosures this connection has already seen in full. Measured: the
+ * R0/class-C sentence is ~354 chars (~88 tokens), repeated on most of a 30-call
+ * session. Only the *argument* shortens — floor/cap stay on every reply (rule 7).
+ * Per connection, not per process — a second client can't inherit the first's history. */
 export interface DisclosureLedger {
-    /**
-     * `true` the first time this key is seen on this connection, `false` after.
-     * Records the sighting — calling it is what marks the key as disclosed.
-     */
+    /** `true` the first time this key is seen on this connection, `false` after —
+     *  calling it is what marks the key as disclosed. */
     firstSighting(key: string): boolean;
     /** Keys disclosed in full so far. For tests and diagnostics. */
     disclosed(): readonly string[];

package/dist/disclosure-ledger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"disclosure-ledger.d.ts","sourceRoot":"","sources":["../src/disclosure-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,gEAAgE;IAChE,SAAS,IAAI,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CAUzD"}
+{"version":3,"file":"disclosure-ledger.d.ts","sourceRoot":"","sources":["../src/disclosure-ledger.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAE1F,MAAM,WAAW,gBAAgB;IAC/B;yDACqD;IACrD,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;IACpC,gEAAgE;IAChE,SAAS,IAAI,SAAS,MAAM,EAAE,CAAC;CAChC;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CAUzD"}

package/dist/disclosure-ledger.js

@@ -1,30 +1,8 @@
 /**
- * Which standing disclosures this connection has already been given in full.
- *
- * The tax it removes was measured, not supposed: the R0/class-C reliability
- * sentence is 354 characters — ~88 tokens — and appeared byte-for-byte
- * identical on the large majority of one session's thirty-odd tool calls.
- * Nothing about it was wrong; it was simply the same paragraph, re-billed to
- * the caller's context window every call, and the loop this server is built
- * for (edit, re-check, edit again) is the one that pays it most.
- *
- * ## What the ledger is allowed to shorten, and what it is not
- *
- * Only the *argument* for a cap. The floor and the class it caps to stay on
- * every reply, first or fiftieth, in `graph.resolutionFloor` /
- * `graph.reliabilityCap` and in the short disclosure itself. Rule 7 is about
- * what reaches the user, and a reply that stopped naming its own cap after
- * the first call would be a reply that silently does less.
- *
- * ## Per connection, deliberately not per process
- *
- * "Already disclosed" is a fact about one conversation. A ledger shared across
- * connections would let the *second* client's first call inherit the first
- * client's history — that client would receive the short form of a sentence it
- * has never seen, which is the exact failure this is supposed to avoid, only
- * harder to notice. So one ledger is created per `createMcpServer`, and it
- * lives as long as that server does.
- */
+ * Tracks disclosures this connection has already seen in full. Measured: the
+ * R0/class-C sentence is ~354 chars (~88 tokens), repeated on most of a 30-call
+ * session. Only the *argument* shortens — floor/cap stay on every reply (rule 7).
+ * Per connection, not per process — a second client can't inherit the first's history. */
 export function createDisclosureLedger() {
     const seen = new Set();
     return {

package/dist/disclosure-ledger.js.map

@@ -1 +1 @@
-{"version":3,"file":"disclosure-ledger.js","sourceRoot":"","sources":["../src/disclosure-ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAYH,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO;QACL,aAAa,CAAC,GAAG;YACf,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;QACD,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"disclosure-ledger.js","sourceRoot":"","sources":["../src/disclosure-ledger.ts"],"names":[],"mappings":"AAAA;;;;0FAI0F;AAU1F,MAAM,UAAU,sBAAsB;IACpC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO;QACL,aAAa,CAAC,GAAG;YACf,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,KAAK,CAAC;YAChC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACd,OAAO,IAAI,CAAC;QACd,CAAC;QACD,SAAS,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,IAAI,CAAC;KAC3B,CAAC;AACJ,CAAC"}