@paretools/shared 0.21.1 → 0.22.0

package/dist/compact.d.ts

@@ -0,0 +1,128 @@
+import { z } from "zod";
+/**
+ * Default number of leading lines kept when truncating a stream for compact
+ * output. Matches the budget introduced for `server-process` in PR #1020.
+ */
+export declare const COMPACT_HEAD_LINES = 40;
+/**
+ * Default number of trailing lines kept when truncating a stream for compact
+ * output. Matches the budget introduced for `server-process` in PR #1020.
+ */
+export declare const COMPACT_TAIL_LINES = 10;
+/**
+ * Default hard byte cap applied to each stream after line trimming.
+ * Matches the budget introduced for `server-process` in PR #1020.
+ */
+export declare const COMPACT_BYTE_CAP = 8192;
+/** Options for {@link truncateStream} and {@link compactStreamFields}. */
+export interface TruncateStreamOptions {
+    /** Number of leading lines to keep (default {@link COMPACT_HEAD_LINES}). */
+    headLines?: number;
+    /** Number of trailing lines to keep (default {@link COMPACT_TAIL_LINES}). */
+    tailLines?: number;
+    /** Hard byte cap applied after line trimming (default {@link COMPACT_BYTE_CAP}). */
+    byteCap?: number;
+}
+/** Result of {@link truncateStream}. */
+export interface TruncateStreamResult {
+    /** The (possibly truncated) text. */
+    text: string;
+    /** Whether any truncation (line trimming or byte cap) occurred. */
+    truncated: boolean;
+    /** Total number of lines in the original text (before truncation). */
+    totalLines: number;
+}
+/**
+ * Truncates a stream (stdout/stderr) to a compact budget: the first
+ * `headLines` lines and the last `tailLines` lines with a
+ * `... (N lines omitted) ...` marker in between, followed by a hard byte cap
+ * that appends `... (truncated)` when exceeded.
+ *
+ * Behaviorally identical to the compact truncation shipped for
+ * `server-process` in PR #1020, extracted so every server can share it
+ * (epic #1022).
+ *
+ * Notes:
+ * - Lines are split on `"\n"`; CRLF input keeps its `"\r"` characters and a
+ *   trailing newline counts as one extra (empty) line, mirroring the
+ *   reference implementation.
+ * - The byte cap is applied to the JavaScript string length (UTF-16 code
+ *   units), matching the original implementation.
+ *
+ * @param text - The raw stream text to truncate.
+ * @param opts - Optional budget overrides (see {@link TruncateStreamOptions}).
+ * @returns The truncated text, whether truncation occurred, and the total
+ *   line count of the original text.
+ */
+export declare function truncateStream(text: string, opts?: TruncateStreamOptions): TruncateStreamResult;
+/**
+ * The optional stdout/stderr fields produced by {@link compactStreamFields}.
+ *
+ * Truncation flags are only present (and always `true`) when the
+ * corresponding stream was truncated; total line counts are only present
+ * alongside their flag. Empty streams are omitted entirely.
+ */
+export interface CompactStreamFields {
+    /** Truncated stdout (omitted when the stream is empty). */
+    stdout?: string;
+    /** Truncated stderr (omitted when the stream is empty). */
+    stderr?: string;
+    /** Present (and `true`) only when stdout was truncated. */
+    stdoutTruncated?: true;
+    /** Present (and `true`) only when stderr was truncated. */
+    stderrTruncated?: true;
+    /** Total stdout lines before truncation; present only when stdoutTruncated. */
+    stdoutTotalLines?: number;
+    /** Total stderr lines before truncation; present only when stderrTruncated. */
+    stderrTotalLines?: number;
+}
+/**
+ * Builds the compact stdout/stderr field set used by compact tool results.
+ *
+ * Convenience wrapper around {@link truncateStream} producing the exact
+ * optional-field shape shipped for `server-process` in PR #1020:
+ *
+ * - Empty or `undefined` streams are omitted entirely (no `stdout: ""`).
+ * - `stdoutTruncated`/`stderrTruncated` are set (to `true`) only when the
+ *   corresponding stream was actually truncated — never `false`.
+ * - `stdoutTotalLines`/`stderrTotalLines` are set only when the
+ *   corresponding truncated flag is set.
+ *
+ * Spread the result into a compact result object:
+ * ```ts
+ * const compact = { exitCode, success, ...compactStreamFields(stdout, stderr) };
+ * ```
+ *
+ * @param stdout - Raw stdout text (empty/undefined streams are omitted).
+ * @param stderr - Raw stderr text (empty/undefined streams are omitted).
+ * @param opts - Optional budget overrides (see {@link TruncateStreamOptions}).
+ * @returns An object containing only the fields that apply.
+ */
+export declare function compactStreamFields(stdout: string | undefined, stderr: string | undefined, opts?: TruncateStreamOptions): CompactStreamFields;
+/**
+ * Zod fragment for the compact stream truncation metadata fields.
+ *
+ * Spread into a tool's result schema so `structuredContent` produced with
+ * {@link compactStreamFields} validates:
+ * ```ts
+ * const MyResultSchema = z.object({
+ *   exitCode: z.number(),
+ *   stdout: z.string().optional(),
+ *   stderr: z.string().optional(),
+ *   ...CompactStreamSchemaFields,
+ * });
+ * ```
+ *
+ * Field-compatible with the `server-process` run schema from PR #1020.
+ */
+export declare const CompactStreamSchemaFields: {
+    /** Whether stdout was truncated to the compact output budget (only set when true). */
+    stdoutTruncated: z.ZodOptional<z.ZodBoolean>;
+    /** Whether stderr was truncated to the compact output budget (only set when true). */
+    stderrTruncated: z.ZodOptional<z.ZodBoolean>;
+    /** Total stdout lines before compact truncation (only set when stdoutTruncated). */
+    stdoutTotalLines: z.ZodOptional<z.ZodNumber>;
+    /** Total stderr lines before compact truncation (only set when stderrTruncated). */
+    stderrTotalLines: z.ZodOptional<z.ZodNumber>;
+};
+//# sourceMappingURL=compact.d.ts.map

package/dist/compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compact.d.ts","sourceRoot":"","sources":["../src/compact.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AAErC;;;GAGG;AACH,eAAO,MAAM,gBAAgB,OAAO,CAAC;AAErC,0EAA0E;AAC1E,MAAM,WAAW,qBAAqB;IACpC,4EAA4E;IAC5E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wCAAwC;AACxC,MAAM,WAAW,oBAAoB;IACnC,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;IACnB,sEAAsE;IACtE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,qBAA0B,GAC/B,oBAAoB,CA0BtB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,mBAAmB;IAClC,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,IAAI,CAAC;IACvB,2DAA2D;IAC3D,eAAe,CAAC,EAAE,IAAI,CAAC;IACvB,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,+EAA+E;IAC/E,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,MAAM,EAAE,MAAM,GAAG,SAAS,EAC1B,IAAI,GAAE,qBAA0B,GAC/B,mBAAmB,CAqBrB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,yBAAyB;IACpC,sFAAsF;;IAEtF,sFAAsF;;IAEtF,oFAAoF;;IAEpF,oFAAoF;;CAErF,CAAC"}

package/dist/compact.js

@@ -0,0 +1,130 @@
+import { z } from "zod";
+/**
+ * Default number of leading lines kept when truncating a stream for compact
+ * output. Matches the budget introduced for `server-process` in PR #1020.
+ */
+export const COMPACT_HEAD_LINES = 40;
+/**
+ * Default number of trailing lines kept when truncating a stream for compact
+ * output. Matches the budget introduced for `server-process` in PR #1020.
+ */
+export const COMPACT_TAIL_LINES = 10;
+/**
+ * Default hard byte cap applied to each stream after line trimming.
+ * Matches the budget introduced for `server-process` in PR #1020.
+ */
+export const COMPACT_BYTE_CAP = 8192;
+/**
+ * Truncates a stream (stdout/stderr) to a compact budget: the first
+ * `headLines` lines and the last `tailLines` lines with a
+ * `... (N lines omitted) ...` marker in between, followed by a hard byte cap
+ * that appends `... (truncated)` when exceeded.
+ *
+ * Behaviorally identical to the compact truncation shipped for
+ * `server-process` in PR #1020, extracted so every server can share it
+ * (epic #1022).
+ *
+ * Notes:
+ * - Lines are split on `"\n"`; CRLF input keeps its `"\r"` characters and a
+ *   trailing newline counts as one extra (empty) line, mirroring the
+ *   reference implementation.
+ * - The byte cap is applied to the JavaScript string length (UTF-16 code
+ *   units), matching the original implementation.
+ *
+ * @param text - The raw stream text to truncate.
+ * @param opts - Optional budget overrides (see {@link TruncateStreamOptions}).
+ * @returns The truncated text, whether truncation occurred, and the total
+ *   line count of the original text.
+ */
+export function truncateStream(text, opts = {}) {
+    const headLines = opts.headLines ?? COMPACT_HEAD_LINES;
+    const tailLines = opts.tailLines ?? COMPACT_TAIL_LINES;
+    const byteCap = opts.byteCap ?? COMPACT_BYTE_CAP;
+    const lines = text.split("\n");
+    const totalLines = lines.length;
+    let out = text;
+    let truncated = false;
+    if (totalLines > headLines + tailLines) {
+        const omitted = totalLines - headLines - tailLines;
+        out = [
+            ...lines.slice(0, headLines),
+            `... (${omitted} lines omitted) ...`,
+            ...lines.slice(totalLines - tailLines),
+        ].join("\n");
+        truncated = true;
+    }
+    if (out.length > byteCap) {
+        out = out.slice(0, byteCap) + "\n... (truncated)";
+        truncated = true;
+    }
+    return { text: out, truncated, totalLines };
+}
+/**
+ * Builds the compact stdout/stderr field set used by compact tool results.
+ *
+ * Convenience wrapper around {@link truncateStream} producing the exact
+ * optional-field shape shipped for `server-process` in PR #1020:
+ *
+ * - Empty or `undefined` streams are omitted entirely (no `stdout: ""`).
+ * - `stdoutTruncated`/`stderrTruncated` are set (to `true`) only when the
+ *   corresponding stream was actually truncated — never `false`.
+ * - `stdoutTotalLines`/`stderrTotalLines` are set only when the
+ *   corresponding truncated flag is set.
+ *
+ * Spread the result into a compact result object:
+ * ```ts
+ * const compact = { exitCode, success, ...compactStreamFields(stdout, stderr) };
+ * ```
+ *
+ * @param stdout - Raw stdout text (empty/undefined streams are omitted).
+ * @param stderr - Raw stderr text (empty/undefined streams are omitted).
+ * @param opts - Optional budget overrides (see {@link TruncateStreamOptions}).
+ * @returns An object containing only the fields that apply.
+ */
+export function compactStreamFields(stdout, stderr, opts = {}) {
+    const fields = {};
+    if (stdout) {
+        const t = truncateStream(stdout, opts);
+        fields.stdout = t.text;
+        if (t.truncated) {
+            fields.stdoutTruncated = true;
+            fields.stdoutTotalLines = t.totalLines;
+        }
+    }
+    if (stderr) {
+        const t = truncateStream(stderr, opts);
+        fields.stderr = t.text;
+        if (t.truncated) {
+            fields.stderrTruncated = true;
+            fields.stderrTotalLines = t.totalLines;
+        }
+    }
+    return fields;
+}
+/**
+ * Zod fragment for the compact stream truncation metadata fields.
+ *
+ * Spread into a tool's result schema so `structuredContent` produced with
+ * {@link compactStreamFields} validates:
+ * ```ts
+ * const MyResultSchema = z.object({
+ *   exitCode: z.number(),
+ *   stdout: z.string().optional(),
+ *   stderr: z.string().optional(),
+ *   ...CompactStreamSchemaFields,
+ * });
+ * ```
+ *
+ * Field-compatible with the `server-process` run schema from PR #1020.
+ */
+export const CompactStreamSchemaFields = {
+    /** Whether stdout was truncated to the compact output budget (only set when true). */
+    stdoutTruncated: z.boolean().optional(),
+    /** Whether stderr was truncated to the compact output budget (only set when true). */
+    stderrTruncated: z.boolean().optional(),
+    /** Total stdout lines before compact truncation (only set when stdoutTruncated). */
+    stdoutTotalLines: z.number().optional(),
+    /** Total stderr lines before compact truncation (only set when stderrTruncated). */
+    stderrTotalLines: z.number().optional(),
+};
+//# sourceMappingURL=compact.js.map

package/dist/compact.js.map

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

package/dist/diagnostics.d.ts

@@ -0,0 +1,75 @@
+import { z } from "zod";
+/** Options for {@link surfaceEmptyFailure}. */
+export interface SurfaceEmptyFailureOptions<T extends object> {
+    /**
+     * Predicate deciding whether the parsed data is "empty" — i.e. the parser
+     * found nothing actionable (zero tests, zero diagnostics, zero results).
+     */
+    isEmpty: (data: T) => boolean;
+    /**
+     * Maximum number of characters of raw output to attach as the `error`
+     * detail (the tail of the stream is kept). Default 4096.
+     */
+    maxBytes?: number;
+}
+/** Default maximum error detail length for {@link surfaceEmptyFailure}. */
+export declare const SURFACE_EMPTY_FAILURE_MAX_BYTES = 4096;
+/**
+ * Surfaces a "silent green" failure: the CLI exited non-zero but the parser
+ * produced no results, which would otherwise read as a clean/passing run.
+ *
+ * When `result.exitCode !== 0`, `opts.isEmpty(data)` is true, and no `error`
+ * field is already set on `data`, this returns a copy of `data` with:
+ *
+ * - `error` — the trimmed tail (last `maxBytes` characters) of whichever
+ *   stream has content, preferring stderr when non-empty, else stdout. When
+ *   the detail exceeds `maxBytes` a `… (output truncated)` marker is
+ *   prepended to the kept tail. When both streams are empty a fallback
+ *   message is used so the `error` field is never an empty string.
+ * - `exitCode` — the CLI's exit code.
+ *
+ * Otherwise `data` is returned unchanged (same reference).
+ *
+ * Generalizes `server-test`'s `surfaceLoadFailure` (issues #928/#931) for
+ * every server (epic #1024): a test suite that fails at import/collection
+ * time, a linter that crashes before emitting JSON, etc., all exit non-zero
+ * with nothing parseable — this makes that state visible to agents.
+ *
+ * Layering note: this is NOT a replacement for `classifyError`/`errorOutput`
+ * (see `errors.ts`). Those handle "the command itself failed and the tool
+ * returns an error response". `surfaceEmptyFailure` covers the layer above:
+ * the CLI ran, the tool still returns a structured (non-error) result, but
+ * the output contained nothing parseable — so the result must carry evidence
+ * of the failure instead of looking like a clean pass.
+ *
+ * @param data - The parsed result object (returned as-is when no failure is surfaced).
+ * @param result - The raw CLI outcome (exit code plus captured streams).
+ * @param opts - Emptiness predicate and optional detail size cap.
+ * @returns `data`, possibly augmented with `error` and `exitCode`.
+ */
+export declare function surfaceEmptyFailure<T extends object>(data: T, result: {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}, opts: SurfaceEmptyFailureOptions<T>): T & {
+    error?: string;
+    exitCode?: number;
+};
+/**
+ * Zod fragment for the fields {@link surfaceEmptyFailure} may attach.
+ *
+ * Spread into a tool's result schema so augmented results validate:
+ * ```ts
+ * const MyResultSchema = z.object({
+ *   summary: SummarySchema,
+ *   ...EmptyFailureSchemaFields,
+ * });
+ * ```
+ */
+export declare const EmptyFailureSchemaFields: {
+    /** Raw CLI output surfaced when the run failed but nothing was parseable. */
+    error: z.ZodOptional<z.ZodString>;
+    /** CLI exit code, set alongside `error` when a silent failure was surfaced. */
+    exitCode: z.ZodOptional<z.ZodNumber>;
+};
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,+CAA+C;AAC/C,MAAM,WAAW,0BAA0B,CAAC,CAAC,SAAS,MAAM;IAC1D;;;OAGG;IACH,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,2EAA2E;AAC3E,eAAO,MAAM,+BAA+B,OAAO,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,SAAS,MAAM,EAClD,IAAI,EAAE,CAAC,EACP,MAAM,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,EAC5D,IAAI,EAAE,0BAA0B,CAAC,CAAC,CAAC,GAClC,CAAC,GAAG;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAAE,CAkB3C;AAED;;;;;;;;;;GAUG;AACH,eAAO,MAAM,wBAAwB;IACnC,6EAA6E;;IAE7E,+EAA+E;;CAEhF,CAAC"}

package/dist/diagnostics.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+/** Default maximum error detail length for {@link surfaceEmptyFailure}. */
+export const SURFACE_EMPTY_FAILURE_MAX_BYTES = 4096;
+/**
+ * Surfaces a "silent green" failure: the CLI exited non-zero but the parser
+ * produced no results, which would otherwise read as a clean/passing run.
+ *
+ * When `result.exitCode !== 0`, `opts.isEmpty(data)` is true, and no `error`
+ * field is already set on `data`, this returns a copy of `data` with:
+ *
+ * - `error` — the trimmed tail (last `maxBytes` characters) of whichever
+ *   stream has content, preferring stderr when non-empty, else stdout. When
+ *   the detail exceeds `maxBytes` a `… (output truncated)` marker is
+ *   prepended to the kept tail. When both streams are empty a fallback
+ *   message is used so the `error` field is never an empty string.
+ * - `exitCode` — the CLI's exit code.
+ *
+ * Otherwise `data` is returned unchanged (same reference).
+ *
+ * Generalizes `server-test`'s `surfaceLoadFailure` (issues #928/#931) for
+ * every server (epic #1024): a test suite that fails at import/collection
+ * time, a linter that crashes before emitting JSON, etc., all exit non-zero
+ * with nothing parseable — this makes that state visible to agents.
+ *
+ * Layering note: this is NOT a replacement for `classifyError`/`errorOutput`
+ * (see `errors.ts`). Those handle "the command itself failed and the tool
+ * returns an error response". `surfaceEmptyFailure` covers the layer above:
+ * the CLI ran, the tool still returns a structured (non-error) result, but
+ * the output contained nothing parseable — so the result must carry evidence
+ * of the failure instead of looking like a clean pass.
+ *
+ * @param data - The parsed result object (returned as-is when no failure is surfaced).
+ * @param result - The raw CLI outcome (exit code plus captured streams).
+ * @param opts - Emptiness predicate and optional detail size cap.
+ * @returns `data`, possibly augmented with `error` and `exitCode`.
+ */
+export function surfaceEmptyFailure(data, result, opts) {
+    if (result.exitCode === 0 || !opts.isEmpty(data)) {
+        return data;
+    }
+    if (data.error) {
+        return data;
+    }
+    const maxBytes = opts.maxBytes ?? SURFACE_EMPTY_FAILURE_MAX_BYTES;
+    const detail = (result.stderr.trim() || result.stdout.trim()).trim();
+    const error = detail.length > maxBytes
+        ? `… (output truncated)\n${detail.slice(-maxBytes)}`
+        : detail ||
+            `Command exited with code ${result.exitCode} but produced no parseable output. ` +
+                `This is not a passing run.`;
+    return { ...data, error, exitCode: result.exitCode };
+}
+/**
+ * Zod fragment for the fields {@link surfaceEmptyFailure} may attach.
+ *
+ * Spread into a tool's result schema so augmented results validate:
+ * ```ts
+ * const MyResultSchema = z.object({
+ *   summary: SummarySchema,
+ *   ...EmptyFailureSchemaFields,
+ * });
+ * ```
+ */
+export const EmptyFailureSchemaFields = {
+    /** Raw CLI output surfaced when the run failed but nothing was parseable. */
+    error: z.string().optional(),
+    /** CLI exit code, set alongside `error` when a silent failure was surfaced. */
+    exitCode: z.number().optional(),
+};
+//# sourceMappingURL=diagnostics.js.map

package/dist/diagnostics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBxB,2EAA2E;AAC3E,MAAM,CAAC,MAAM,+BAA+B,GAAG,IAAI,CAAC;AAEpD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,UAAU,mBAAmB,CACjC,IAAO,EACP,MAA4D,EAC5D,IAAmC;IAEnC,IAAI,MAAM,CAAC,QAAQ,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAK,IAA4B,CAAC,KAAK,EAAE,CAAC;QACxC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,+BAA+B,CAAC;IAClE,MAAM,MAAM,GAAG,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACrE,MAAM,KAAK,GACT,MAAM,CAAC,MAAM,GAAG,QAAQ;QACtB,CAAC,CAAC,yBAAyB,MAAM,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,EAAE;QACpD,CAAC,CAAC,MAAM;YACN,4BAA4B,MAAM,CAAC,QAAQ,qCAAqC;gBAC9E,4BAA4B,CAAC;IAErC,OAAO,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,QAAQ,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,MAAM,wBAAwB,GAAG;IACtC,6EAA6E;IAC7E,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IAC5B,+EAA+E;IAC/E,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CAChC,CAAC"}

package/dist/index.d.ts

@@ -6,6 +6,10 @@ export { coerceJsonArray, assertNoFlagInjection, assertSafePassthroughArg, asser
 export { INPUT_LIMITS } from "./limits.js";
 export { compactInput, projectPathInput, repoPathInput, cwdPathInput, fixInput, pathInput, configInput, filePatternsInput, } from "./input-schemas.js";
 export { sanitizeErrorOutput } from "./sanitize.js";
+export { COMPACT_HEAD_LINES, COMPACT_TAIL_LINES, COMPACT_BYTE_CAP, truncateStream, compactStreamFields, CompactStreamSchemaFields, } from "./compact.js";
+export type { TruncateStreamOptions, TruncateStreamResult, CompactStreamFields, } from "./compact.js";
+export { surfaceEmptyFailure, SURFACE_EMPTY_FAILURE_MAX_BYTES, EmptyFailureSchemaFields, } from "./diagnostics.js";
+export type { SurfaceEmptyFailureOptions } from "./diagnostics.js";
 export { shouldRegisterTool, isLazyEnabled, _resetProfileCache } from "./tool-filter.js";
 export { PROFILES, CORE_TOOLS, resolveProfile, isCoreToolForServer } from "./profiles.js";
 export type { ProfileName } from "./profiles.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,GAAG,EACH,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,2BAA2B,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC1F,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,GAAG,EACH,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,EACf,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,WAAW,GACjB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,2BAA2B,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,qBAAqB,EACrB,oBAAoB,EACpB,mBAAmB,GACpB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,mBAAmB,EACnB,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,0BAA0B,EAAE,MAAM,kBAAkB,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAC1F,YAAY,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,qBAAqB,EACrB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,qBAAqB,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/index.js

@@ -6,6 +6,8 @@ export { coerceJsonArray, assertNoFlagInjection, assertSafePassthroughArg, asser
 export { INPUT_LIMITS } from "./limits.js";
 export { compactInput, projectPathInput, repoPathInput, cwdPathInput, fixInput, pathInput, configInput, filePatternsInput, } from "./input-schemas.js";
 export { sanitizeErrorOutput } from "./sanitize.js";
+export { COMPACT_HEAD_LINES, COMPACT_TAIL_LINES, COMPACT_BYTE_CAP, truncateStream, compactStreamFields, CompactStreamSchemaFields, } from "./compact.js";
+export { surfaceEmptyFailure, SURFACE_EMPTY_FAILURE_MAX_BYTES, EmptyFailureSchemaFields, } from "./diagnostics.js";
 export { shouldRegisterTool, isLazyEnabled, _resetProfileCache } from "./tool-filter.js";
 export { PROFILES, CORE_TOOLS, resolveProfile, isCoreToolForServer } from "./profiles.js";
 export { createLazyToolManager, } from "./lazy-tools.js";

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,GAAG,EACH,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GAIhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,2BAA2B,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE1F,OAAO,EACL,qBAAqB,GAGtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,UAAU,EACV,cAAc,EACd,iBAAiB,EACjB,kBAAkB,EAClB,yBAAyB,GAC1B,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,GAAG,EACH,YAAY,EACZ,iBAAiB,EACjB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,eAAe,GAIhB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,2BAA2B,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC1F,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EACL,eAAe,EACf,qBAAqB,EACrB,wBAAwB,EACxB,kBAAkB,EAClB,kBAAkB,EAClB,oBAAoB,GACrB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EACL,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AACpD,OAAO,EACL,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,yBAAyB,GAC1B,MAAM,cAAc,CAAC;AAMtB,OAAO,EACL,mBAAmB,EACnB,+BAA+B,EAC/B,wBAAwB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAE1F,OAAO,EACL,qBAAqB,GAGtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EACL,qBAAqB,EACrB,iBAAiB,EACjB,4BAA4B,GAC7B,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,SAAS,EACT,cAAc,EACd,WAAW,EACX,UAAU,EACV,UAAU,EACV,eAAe,EACf,oBAAoB,GACrB,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAE3C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/testing.d.ts

@@ -0,0 +1,25 @@
+import type { JsonSchemaType } from "@modelcontextprotocol/sdk/validation/types.js";
+/** Result of validating a tool output payload against its registered schema. */
+export interface ToolOutputValidationResult {
+    valid: boolean;
+    /** AJV error message when invalid (mirrors the MCP client's -32602 detail). */
+    errorMessage?: string;
+}
+/**
+ * Converts a Zod outputSchema to JSON Schema exactly like the MCP SDK does
+ * when listing tools (zod v4 branch of `toJsonSchemaCompat`): draft-7 target,
+ * output io — which makes plain `z.object` emit `additionalProperties: false`.
+ */
+export declare function toolOutputJsonSchema(outputSchema: unknown): JsonSchemaType;
+/**
+ * Validates a structuredContent payload against a tool's registered Zod
+ * outputSchema using the SDK's own AJV validator. The payload is JSON
+ * round-tripped first to mirror the wire (drops `undefined`-valued keys).
+ */
+export declare function validateToolOutput(outputSchema: unknown, structuredContent: unknown): ToolOutputValidationResult;
+/**
+ * Assertion form of {@link validateToolOutput}: throws with the AJV error
+ * detail when the payload would be rejected by an MCP client at runtime.
+ */
+export declare function expectToolOutputMatchesSchema(outputSchema: unknown, structuredContent: unknown): void;
+//# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,+CAA+C,CAAC;AAEpF,gFAAgF;AAChF,MAAM,WAAW,0BAA0B;IACzC,KAAK,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,OAAO,GAAG,cAAc,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,YAAY,EAAE,OAAO,EACrB,iBAAiB,EAAE,OAAO,GACzB,0BAA0B,CAM5B;AAED;;;GAGG;AACH,wBAAgB,6BAA6B,CAC3C,YAAY,EAAE,OAAO,EACrB,iBAAiB,EAAE,OAAO,GACzB,IAAI,CAQN"}

package/dist/testing.js

@@ -0,0 +1,56 @@
+/**
+ * Test-only helpers that validate tool output the exact way the MCP SDK does
+ * at runtime.
+ *
+ * Why this exists (#1022 regression class): Zod's `.parse()` silently STRIPS
+ * unknown keys, so `Schema.parse(compactMap(data))` passes even when a compact
+ * mapper emits fields the registered `outputSchema` does not declare. The MCP
+ * SDK, however, converts the Zod outputSchema to JSON Schema (where plain
+ * `z.object` becomes `additionalProperties: false`) and validates
+ * `structuredContent` with AJV on the client side — so undeclared compact-only
+ * fields fail at runtime with `MCP error -32602: data must NOT have
+ * additional properties`, but only when compact mode engages.
+ *
+ * These helpers replicate that pipeline (zod v4 `toJSONSchema` with the SDK's
+ * options + the SDK's own AJV validator) so unit tests catch the mismatch.
+ *
+ * Import from `@paretools/shared/testing` — kept out of the main entry point
+ * so production servers never load AJV.
+ */
+import * as z4mini from "zod/v4-mini";
+import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
+/**
+ * Converts a Zod outputSchema to JSON Schema exactly like the MCP SDK does
+ * when listing tools (zod v4 branch of `toJsonSchemaCompat`): draft-7 target,
+ * output io — which makes plain `z.object` emit `additionalProperties: false`.
+ */
+export function toolOutputJsonSchema(outputSchema) {
+    return z4mini.toJSONSchema(outputSchema, {
+        target: "draft-7",
+        io: "output",
+    });
+}
+/**
+ * Validates a structuredContent payload against a tool's registered Zod
+ * outputSchema using the SDK's own AJV validator. The payload is JSON
+ * round-tripped first to mirror the wire (drops `undefined`-valued keys).
+ */
+export function validateToolOutput(outputSchema, structuredContent) {
+    const jsonSchema = toolOutputJsonSchema(outputSchema);
+    const validate = new AjvJsonSchemaValidator().getValidator(jsonSchema);
+    const wireData = JSON.parse(JSON.stringify(structuredContent));
+    const result = validate(wireData);
+    return result.valid ? { valid: true } : { valid: false, errorMessage: result.errorMessage };
+}
+/**
+ * Assertion form of {@link validateToolOutput}: throws with the AJV error
+ * detail when the payload would be rejected by an MCP client at runtime.
+ */
+export function expectToolOutputMatchesSchema(outputSchema, structuredContent) {
+    const result = validateToolOutput(outputSchema, structuredContent);
+    if (!result.valid) {
+        throw new Error(`structuredContent does not validate against the registered outputSchema ` +
+            `(the MCP client would reject this with -32602): ${result.errorMessage}`);
+    }
+}
+//# sourceMappingURL=testing.js.map

package/dist/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing.js","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,MAAM,MAAM,aAAa,CAAC;AACtC,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAUlF;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAqB;IACxD,OAAO,MAAM,CAAC,YAAY,CAAC,YAAyD,EAAE;QACpF,MAAM,EAAE,SAAS;QACjB,EAAE,EAAE,QAAQ;KACb,CAAmB,CAAC;AACvB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,YAAqB,EACrB,iBAA0B;IAE1B,MAAM,UAAU,GAAG,oBAAoB,CAAC,YAAY,CAAC,CAAC;IACtD,MAAM,QAAQ,GAAG,IAAI,sBAAsB,EAAE,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;IACvE,MAAM,QAAQ,GAAY,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,iBAAiB,CAAC,CAAC,CAAC;IACxE,MAAM,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAClC,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE,CAAC;AAC9F,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,6BAA6B,CAC3C,YAAqB,EACrB,iBAA0B;IAE1B,MAAM,MAAM,GAAG,kBAAkB,CAAC,YAAY,EAAE,iBAAiB,CAAC,CAAC;IACnE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QAClB,MAAM,IAAI,KAAK,CACb,0EAA0E;YACxE,mDAAmD,MAAM,CAAC,YAAY,EAAE,CAC3E,CAAC;IACJ,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paretools/shared",
-  "version": "0.21.1",
+  "version": "0.22.0",
   "description": "Shared utilities for Pare MCP servers",
   "license": "MIT",
   "keywords": [
@@ -23,6 +23,10 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "default": "./dist/testing.js"
     }
   },
   "publishConfig": {
@@ -40,11 +44,11 @@
     "dist"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@modelcontextprotocol/sdk": "^1.30.0",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^26.1.1",
+    "@types/node": "^26.1.2",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "@paretools/tsconfig": "0.0.0"