@shrkcrft/mcp-server 0.1.0-alpha.2 → 0.1.0-alpha.20

package/dist/index.d.ts

@@ -5,4 +5,8 @@ export { ALL_TOOLS } from './tools/index.js';
 export type { IToolDefinition, IToolResponse, IToolContext, IMcpGateDecision, McpGateResolver, } from './server/tool-definition.js';
 export { MCP_PROTOCOL_VERSION, MCP_SERVER_NAME, MCP_SERVER_VERSION, } from './server/mcp-server-config.js';
 export { buildResourceList, readResource, parseResourceUri, knowledgeUri, templateUri, docUri, OVERVIEW_URI, AGENT_INSTRUCTIONS_URI, URI_SCHEME, } from './resources/index.js';
+export { getRelevantContextTool } from './tools/get-relevant-context.tool.js';
+export { getTaskPacketTool } from './tools/get-task-packet.tool.js';
+export { prepareAgentTaskTool } from './tools/r33-agent-task-prep.tool.js';
+export { COMMAND_CATALOG_EXPORT } from './tools/command-catalog.tool.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,GACnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAK7C,YAAY,EACV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,MAAM,EACN,YAAY,EACZ,sBAAsB,EACtB,UAAU,GACX,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,sBAAsB,EACtB,iBAAiB,EACjB,KAAK,qBAAqB,EAC1B,KAAK,6BAA6B,GACnC,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AACpF,OAAO,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAC;AACxE,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAK7C,YAAY,EACV,eAAe,EACf,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,eAAe,GAChB,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,kBAAkB,GACnB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,iBAAiB,EACjB,YAAY,EACZ,gBAAgB,EAChB,YAAY,EACZ,WAAW,EACX,MAAM,EACN,YAAY,EACZ,sBAAsB,EACtB,UAAU,GACX,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EAAE,sBAAsB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAC3E,OAAO,EAAE,sBAAsB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -4,3 +4,7 @@ export { startSharkcraftWatcher } from "./server/sharkcraft-watcher.js";
 export { ALL_TOOLS } from "./tools/index.js";
 export { MCP_PROTOCOL_VERSION, MCP_SERVER_NAME, MCP_SERVER_VERSION, } from "./server/mcp-server-config.js";
 export { buildResourceList, readResource, parseResourceUri, knowledgeUri, templateUri, docUri, OVERVIEW_URI, AGENT_INSTRUCTIONS_URI, URI_SCHEME, } from "./resources/index.js";
+export { getRelevantContextTool } from "./tools/get-relevant-context.tool.js";
+export { getTaskPacketTool } from "./tools/get-task-packet.tool.js";
+export { prepareAgentTaskTool } from "./tools/r33-agent-task-prep.tool.js";
+export { COMMAND_CATALOG_EXPORT } from "./tools/command-catalog.tool.js";

package/dist/server/columnar-format.d.ts

@@ -0,0 +1,34 @@
+/**
+ * One-line explainer shipped alongside a columnar payload so an agent can decode
+ * it. Kept terse on purpose: this string is paid once per columnar response, so
+ * a shorter legend is a real per-response token saving — and a smaller fixed
+ * cost means the net-loss guard keeps `table` form on more (smaller) payloads.
+ */
+export declare const COLUMNAR_LEGEND = "_table: rows[i] are values in cols order; absent=[row,col] keys to skip when rebuilding objects. If _table.dict[col] exists, that column\u2019s cells are integer indices into dict[col].";
+/** Shared `format` input fragment for list tools that support columnar output. */
+export declare const FORMAT_INPUT_PROPERTY: {
+    format: {
+        type: "string";
+        enum: readonly ["json", "table"];
+        description: string;
+    };
+};
+/** Whether a tool should emit columnar for this request. */
+export declare function wantsTable(input: Record<string, unknown>): boolean;
+/**
+ * Shape a list tool's homogeneous rows for output. `format:"table"` returns a
+ * columnar envelope (`{ format, legend, items }`) — still valid JSON but with
+ * the schema hoisted out of every row. Any other value returns the bare array
+ * unchanged (back-compat). If the rows don't qualify for compaction, the bare
+ * array is returned so callers always get valid data.
+ */
+export declare function formatRows(rows: ReadonlyArray<Record<string, unknown>>, input: Record<string, unknown>): unknown;
+/**
+ * Columnar-compact the top-level array fields of a result OBJECT (e.g. a graph
+ * query's `{ directDependents: [...], transitiveDependents: [...] }`) when the
+ * caller asked for `format:"table"`. Each compactable array becomes a columnar
+ * envelope; scalars, small arrays, and heterogeneous arrays are left as-is.
+ * Returns the original object unchanged when nothing compacted (back-compat).
+ */
+export declare function formatObjectArrays(data: unknown, input: Record<string, unknown>): unknown;
+//# sourceMappingURL=columnar-format.d.ts.map

package/dist/server/columnar-format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columnar-format.d.ts","sourceRoot":"","sources":["../../src/server/columnar-format.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,8LAC4J,CAAC;AAEzL,kFAAkF;AAClF,eAAO,MAAM,qBAAqB;;;;;;CAOjC,CAAC;AAiBF,4DAA4D;AAC5D,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAIlE;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CACxB,IAAI,EAAE,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAC5C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC7B,OAAO,CAQT;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CA0BzF"}

package/dist/server/columnar-format.js

@@ -0,0 +1,95 @@
+import { compactArrayToColumnar, estimateTokens, EContentType } from '@shrkcrft/compress';
+/** Token cost of a value as minified JSON — the shape the wire serializes. */
+function jsonTokens(value) {
+    return estimateTokens(JSON.stringify(value) ?? 'null', EContentType.Json);
+}
+/**
+ * One-line explainer shipped alongside a columnar payload so an agent can decode
+ * it. Kept terse on purpose: this string is paid once per columnar response, so
+ * a shorter legend is a real per-response token saving — and a smaller fixed
+ * cost means the net-loss guard keeps `table` form on more (smaller) payloads.
+ */
+export const COLUMNAR_LEGEND = '_table: rows[i] are values in cols order; absent=[row,col] keys to skip when rebuilding objects. If _table.dict[col] exists, that column’s cells are integer indices into dict[col].';
+/** Shared `format` input fragment for list tools that support columnar output. */
+export const FORMAT_INPUT_PROPERTY = {
+    format: {
+        type: 'string',
+        enum: ['json', 'table'],
+        description: 'json: explicit object array. table: token-efficient columnar encoding (still valid JSON, schema hoisted, keys deduped) — recommended for large lists. Default is table; set SHRK_MCP_TABLE=0 on the server (or pass format:"json") for the explicit array.',
+    },
+};
+/** Deployment toggle: whether columnar `table` is the default wire shape.
+ *  Default ON — every columnar-capable tool emits `table` so agents get the
+ *  token savings without asking. Set `SHRK_MCP_TABLE=0` (or `false`/`no`/`off`)
+ *  to opt out fleet-wide and restore the explicit-array shape for clients that
+ *  need it. `format:"json"` always forces the explicit array per call,
+ *  `format:"table"` always forces columnar — both override this default.
+ *
+ *  Compaction itself is conservative: `compactArrayToColumnar` returns null for
+ *  small / heterogeneous arrays, so default-on only reshapes payloads where the
+ *  columnar form is an actual win; everything else stays a bare array. */
+function tableIsDefault() {
+    const v = (process.env.SHRK_MCP_TABLE ?? '').toLowerCase();
+    return v !== '0' && v !== 'false' && v !== 'no' && v !== 'off';
+}
+/** Whether a tool should emit columnar for this request. */
+export function wantsTable(input) {
+    if (input.format === 'table')
+        return true;
+    if (input.format === 'json')
+        return false;
+    return tableIsDefault();
+}
+/**
+ * Shape a list tool's homogeneous rows for output. `format:"table"` returns a
+ * columnar envelope (`{ format, legend, items }`) — still valid JSON but with
+ * the schema hoisted out of every row. Any other value returns the bare array
+ * unchanged (back-compat). If the rows don't qualify for compaction, the bare
+ * array is returned so callers always get valid data.
+ */
+export function formatRows(rows, input) {
+    if (!wantsTable(input))
+        return rows;
+    const columnar = compactArrayToColumnar(rows);
+    if (!columnar)
+        return rows;
+    const candidate = { format: 'table', legend: COLUMNAR_LEGEND, items: columnar };
+    // Net-loss guard: the legend + envelope can exceed the bare array on a small
+    // list. Ship whichever is smaller so `format:"table"` never inflates a payload.
+    return jsonTokens(candidate) < jsonTokens(rows) ? candidate : rows;
+}
+/**
+ * Columnar-compact the top-level array fields of a result OBJECT (e.g. a graph
+ * query's `{ directDependents: [...], transitiveDependents: [...] }`) when the
+ * caller asked for `format:"table"`. Each compactable array becomes a columnar
+ * envelope; scalars, small arrays, and heterogeneous arrays are left as-is.
+ * Returns the original object unchanged when nothing compacted (back-compat).
+ */
+export function formatObjectArrays(data, input) {
+    if (!wantsTable(input) || data === null || typeof data !== 'object' || Array.isArray(data)) {
+        return data;
+    }
+    const src = data;
+    const out = {};
+    let compacted = false;
+    for (const [key, value] of Object.entries(src)) {
+        if (Array.isArray(value)) {
+            const table = compactArrayToColumnar(value);
+            // Per-array net-loss guard: only hoist an array whose columnar form is
+            // actually smaller — a tiny array loses to its own hoisted schema header.
+            if (table && jsonTokens(table) < jsonTokens(value)) {
+                out[key] = table;
+                compacted = true;
+                continue;
+            }
+        }
+        out[key] = value;
+    }
+    if (!compacted)
+        return data;
+    const candidate = { _format: 'table', _legend: COLUMNAR_LEGEND, ...out };
+    // Overall net-loss guard: the shared legend must not push the whole payload
+    // above the bare object — table mode never inflates (the "never a negative
+    // saving" promise the dashboard makes).
+    return jsonTokens(candidate) < jsonTokens(data) ? candidate : data;
+}

package/dist/server/create-mcp-server.d.ts

@@ -1,5 +1,6 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { type ISharkcraftInspection } from '@shrkcrft/inspector';
+import { type ICcrStore } from '@shrkcrft/compress';
 import { type IMcpServerConfig } from './mcp-server-config.js';
 import type { IToolDefinition, McpGateResolver } from './tool-definition.js';
 export interface StartMcpServerOptions {
@@ -40,6 +41,8 @@ interface ServerState {
     toolsByName: Map<string, IToolDefinition>;
     /** Optional tier-gate resolver. */
     gateResolver?: McpGateResolver;
+    /** In-memory CCR store shared across this server's tool calls. */
+    ccrStore: ICcrStore;
 }
 /**
  * Resolve which directory the MCP server should treat as the target project.

package/dist/server/create-mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-mcp-server.d.ts","sourceRoot":"","sources":["../../src/server/create-mcp-server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAK9B,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACrE,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACzC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,mCAAmC;IACnC,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAIR;AAqBD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,6BAA6B,GAAG;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;CACpB,CAqHA;AAED,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAmEvF"}
+{"version":3,"file":"create-mcp-server.d.ts","sourceRoot":"","sources":["../../src/server/create-mcp-server.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,2CAA2C,CAAC;AAQnE,OAAO,EAAqB,KAAK,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACpF,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEtE,OAAO,EAGL,KAAK,gBAAgB,EACtB,MAAM,wBAAwB,CAAC;AAChC,OAAO,KAAK,EACV,eAAe,EAEf,eAAe,EAChB,MAAM,sBAAsB,CAAC;AAM9B,MAAM,WAAW,qBAAqB;IACpC,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAC7B,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;;OAKG;IACH,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,MAAM,WAAW,6BAA8B,SAAQ,gBAAgB;IACrE,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,YAAY,CAAC,EAAE,eAAe,CAAC;CAChC;AAED,UAAU,WAAW;IACnB,MAAM,EAAE,gBAAgB,CAAC;IACzB,UAAU,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACzC,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IAC1C,mCAAmC;IACnC,YAAY,CAAC,EAAE,eAAe,CAAC;IAC/B,kEAAkE;IAClE,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,iBAAiB,EAAE,MAAM,GAAG,SAAS,EACrC,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GACpD,MAAM,CAIR;AAqBD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,6BAA6B,GAAG;IAC7E,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,WAAW,CAAC;CACpB,CAiIA;AAED,wBAAsB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,IAAI,CAAC,CAmEvF"}

package/dist/server/create-mcp-server.js

@@ -3,8 +3,11 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
 import { inspectSharkcraft } from '@shrkcrft/inspector';
+import { InMemoryCcrStore } from '@shrkcrft/compress';
+import { serializeToolData } from "./serialize-tool-data.js";
 import { MCP_SERVER_NAME, MCP_SERVER_VERSION, } from "./mcp-server-config.js";
 import { ALL_TOOLS } from "../tools/index.js";
+import { PRIMARY_MCP_TOOLS, shouldAdvertiseFullToolset } from "../tools/primary-tools.js";
 import { validateToolInput } from "./tool-input-validators.js";
 import { buildResourceList, readResource } from "../resources/index.js";
 /**
@@ -26,7 +29,7 @@ function toolResponseToCallResult(response) {
     if (response.text)
         content.push({ type: 'text', text: response.text });
     if (response.data !== undefined) {
-        content.push({ type: 'text', text: JSON.stringify(response.data, null, 2) });
+        content.push({ type: 'text', text: serializeToolData(response.data) });
     }
     if (content.length === 0)
         content.push({ type: 'text', text: '(empty)' });
@@ -44,6 +47,7 @@ export function createSharkcraftServer(config) {
         config: effectiveConfig,
         inspection: null,
         toolsByName: new Map(ALL_TOOLS.map((t) => [t.name, t])),
+        ccrStore: new InMemoryCcrStore(),
         ...(config.gateResolver ? { gateResolver: config.gateResolver } : {}),
     };
     const server = new Server({ name: effectiveConfig.name, version: effectiveConfig.version }, {
@@ -52,13 +56,24 @@ export function createSharkcraftServer(config) {
             resources: { listChanged: true },
         },
     });
-    server.setRequestHandler(ListToolsRequestSchema, async () => ({
-        tools: ALL_TOOLS.map((t) => ({
-            name: t.name,
-            description: t.description,
-            inputSchema: t.inputSchema,
-        })),
-    }));
+    server.setRequestHandler(ListToolsRequestSchema, async () => {
+        // Default `tools/list` advertises only the ~30 primary tools to
+        // keep the agent's tool-selection surface focused. The other ~200
+        // tools stay CALLABLE via `tools/call` for agents that already
+        // know the name (e.g. via `shrk export claude-skill` referencing
+        // them). Set SHRK_MCP_FULL_TOOLS=1 to advertise everything.
+        const advertiseFull = shouldAdvertiseFullToolset();
+        const advertised = advertiseFull
+            ? ALL_TOOLS
+            : ALL_TOOLS.filter((t) => PRIMARY_MCP_TOOLS.has(t.name));
+        return {
+            tools: advertised.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+            })),
+        };
+    });
     server.setRequestHandler(CallToolRequestSchema, async (request) => {
         const name = request.params.name;
         const args = (request.params.arguments ?? {});
@@ -112,7 +127,7 @@ export function createSharkcraftServer(config) {
         }
         try {
             const inspection = await loadInspection(state);
-            const response = await tool.handler(validation.data, { inspection, cwd: state.config.cwd });
+            const response = await tool.handler(validation.data, { inspection, cwd: state.config.cwd, allTools: ALL_TOOLS, ccrStore: state.ccrStore });
             return toolResponseToCallResult(response);
         }
         catch (e) {

package/dist/server/fit-array-to-budget.d.ts

@@ -0,0 +1,24 @@
+import { type ICcrStore } from '@shrkcrft/compress';
+export interface IFittedArray {
+    /** The array shaped for output: lossless columnar, or a lossy sample. */
+    value: unknown;
+    /** Set when a lossy sample was taken — the CCR key for the cached original. */
+    ccrKey?: string;
+}
+/**
+ * Fit a homogeneous object array to an optional token budget (P5.2).
+ *
+ *  - No budget (or under budget): the lossless columnar form.
+ *  - Over budget: the SmartCrusher row-sample (representative rows kept, the
+ *    rest dropped) with the FULL original cached in `store` — the agent can
+ *    `retrieve_original` with the returned `ccrKey`.
+ *
+ * `compressJson({ maxTokens })` owns the lossless-vs-lossy DECISION, but its
+ * sampler keep-count is not derived from the budget, so a single sample can
+ * still exceed `maxTokens`. We therefore binary-search the row cap so the
+ * emitted payload actually fits the budget (down to a 1-row floor — a single
+ * row's columnar envelope may still exceed a very small budget, which is the
+ * best achievable while keeping any data).
+ */
+export declare function fitArrayToBudget(array: readonly unknown[], maxTokens: number | undefined, store?: ICcrStore): IFittedArray;
+//# sourceMappingURL=fit-array-to-budget.d.ts.map

package/dist/server/fit-array-to-budget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fit-array-to-budget.d.ts","sourceRoot":"","sources":["../../src/server/fit-array-to-budget.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,oBAAoB,CAAC;AAE5B,MAAM,WAAW,YAAY;IAC3B,yEAAyE;IACzE,KAAK,EAAE,OAAO,CAAC;IACf,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,OAAO,EAAE,EACzB,SAAS,EAAE,MAAM,GAAG,SAAS,EAC7B,KAAK,CAAC,EAAE,SAAS,GAChB,YAAY,CA2Cd"}

package/dist/server/fit-array-to-budget.js

@@ -0,0 +1,60 @@
+import { compactArrayToColumnar, compressJson, estimateTokens, EContentType, } from '@shrkcrft/compress';
+/**
+ * Fit a homogeneous object array to an optional token budget (P5.2).
+ *
+ *  - No budget (or under budget): the lossless columnar form.
+ *  - Over budget: the SmartCrusher row-sample (representative rows kept, the
+ *    rest dropped) with the FULL original cached in `store` — the agent can
+ *    `retrieve_original` with the returned `ccrKey`.
+ *
+ * `compressJson({ maxTokens })` owns the lossless-vs-lossy DECISION, but its
+ * sampler keep-count is not derived from the budget, so a single sample can
+ * still exceed `maxTokens`. We therefore binary-search the row cap so the
+ * emitted payload actually fits the budget (down to a 1-row floor — a single
+ * row's columnar envelope may still exceed a very small budget, which is the
+ * best achievable while keeping any data).
+ */
+export function fitArrayToBudget(array, maxTokens, store) {
+    const columnar = compactArrayToColumnar(array) ?? array;
+    if (!maxTokens || maxTokens <= 0)
+        return { value: columnar };
+    const json = JSON.stringify(array);
+    const run = (maxItems) => {
+        const r = compressJson(json, {
+            maxTokens,
+            ...(maxItems !== undefined ? { maxItems } : {}),
+            ...(store ? { store } : {}),
+        });
+        // A CCR key is set only on the lossy sample path; under budget the result
+        // is the lossless form, so the caller falls back to the columnar value.
+        if (!r.ccrKey)
+            return null;
+        const firstLine = r.compressed.split('\n')[0] ?? 'null';
+        return { value: JSON.parse(firstLine), ccrKey: r.ccrKey };
+    };
+    const fits = (fitted) => estimateTokens(JSON.stringify(fitted.value), EContentType.JsonArray) <= maxTokens;
+    // Default sample (no cap). Null → under budget, emit the lossless form.
+    const initial = run();
+    if (!initial)
+        return { value: columnar };
+    if (fits(initial))
+        return initial;
+    // Largest row cap whose sampled payload still fits the budget.
+    let lo = 1;
+    let hi = array.length;
+    let best = null;
+    while (lo <= hi) {
+        const mid = Math.floor((lo + hi) / 2);
+        const candidate = run(mid);
+        if (candidate && fits(candidate)) {
+            best = candidate;
+            lo = mid + 1;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    // Even one row over budget → keep the smallest sample (best effort, still
+    // recoverable via ccrKey) rather than the much larger default sample.
+    return best ?? run(1) ?? initial;
+}

package/dist/server/serialize-tool-data.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Serialize a tool's structured `data` into the text the MCP wire carries.
+ *
+ * The default is **minified** JSON: still valid JSON (identical shape, so
+ * JSON-parsing clients are unaffected), but without the pretty-print
+ * indentation that every `JSON.stringify(data, null, 2)` paid for. Across
+ * ~200 tools that indentation is pure token overhead an agent reads and pays
+ * for. Set `SHRK_MCP_PRETTY=1` to restore indented output for debugging.
+ *
+ * This transform is lossless and structure-preserving by design. Lossy /
+ * shape-changing compaction (columnar tables, CCR offload) is opt-in per
+ * tool, never applied blindly here.
+ */
+export declare function serializeToolData(data: unknown): string;
+//# sourceMappingURL=serialize-tool-data.d.ts.map

package/dist/server/serialize-tool-data.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize-tool-data.d.ts","sourceRoot":"","sources":["../../src/server/serialize-tool-data.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAGvD"}

package/dist/server/serialize-tool-data.js

@@ -0,0 +1,22 @@
+/**
+ * Serialize a tool's structured `data` into the text the MCP wire carries.
+ *
+ * The default is **minified** JSON: still valid JSON (identical shape, so
+ * JSON-parsing clients are unaffected), but without the pretty-print
+ * indentation that every `JSON.stringify(data, null, 2)` paid for. Across
+ * ~200 tools that indentation is pure token overhead an agent reads and pays
+ * for. Set `SHRK_MCP_PRETTY=1` to restore indented output for debugging.
+ *
+ * This transform is lossless and structure-preserving by design. Lossy /
+ * shape-changing compaction (columnar tables, CCR offload) is opt-in per
+ * tool, never applied blindly here.
+ */
+export function serializeToolData(data) {
+    if (wantsPretty())
+        return JSON.stringify(data, null, 2) ?? 'null';
+    return JSON.stringify(data) ?? 'null';
+}
+function wantsPretty() {
+    const v = process.env.SHRK_MCP_PRETTY;
+    return v === '1' || v === 'true' || v === 'yes';
+}

package/dist/server/tool-definition.d.ts

@@ -1,4 +1,5 @@
 import type { ISharkcraftInspection } from '@shrkcrft/inspector';
+import type { ICcrStore } from '@shrkcrft/compress';
 export interface IToolJsonSchema {
     type: 'object';
     properties?: Record<string, unknown>;
@@ -8,6 +9,20 @@ export interface IToolJsonSchema {
 export interface IToolContext {
     inspection: ISharkcraftInspection;
     cwd: string;
+    /**
+     * The full list of tools registered in the server. Tools that need
+     * to self-reflect (e.g. `get_safety_audit`) use this instead of
+     * importing `ALL_TOOLS` from the tool-registry to avoid import cycles.
+     */
+    allTools?: readonly IToolDefinition[];
+    /**
+     * Per-server in-memory Compress-Cache-Retrieve store. The
+     * `compress_context` tool caches originals here and `retrieve_original`
+     * reads them back. In-memory only — the MCP server never writes to disk,
+     * honouring the read-only contract. Absent in unit tests that construct a
+     * bare context.
+     */
+    ccrStore?: ICcrStore;
 }
 export interface IToolDefinition {
     name: string;

package/dist/server/tool-definition.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-definition.d.ts","sourceRoot":"","sources":["../../src/server/tool-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AAEjE,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,qBAAqB,CAAC;IAClC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,eAAe,CAAC;IAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;IAC3G;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,eAAe,KAAK,gBAAgB,GAAG,IAAI,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB"}
+{"version":3,"file":"tool-definition.d.ts","sourceRoot":"","sources":["../../src/server/tool-definition.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC;AACjE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACrC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,MAAM,WAAW,YAAY;IAC3B,UAAU,EAAE,qBAAqB,CAAC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACtC;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,eAAe,CAAC;IAC7B,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,EAAE,YAAY,KAAK,OAAO,CAAC,aAAa,CAAC,GAAG,aAAa,CAAC;IAC3G;;;;;;;;;OASG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,eAAe,KAAK,gBAAgB,GAAG,IAAI,CAAC;AAEjF,MAAM,WAAW,UAAU;IACzB,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,2BAA2B;IAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,2EAA2E;IAC3E,KAAK,CAAC,EAAE,UAAU,CAAC;CACpB"}

package/dist/server/tool-input-validators.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-input-validators.d.ts","sourceRoot":"","sources":["../../src/server/tool-input-validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAwFxB,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAgBpE,CAAC;AAEH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAkB9E"}
+{"version":3,"file":"tool-input-validators.d.ts","sourceRoot":"","sources":["../../src/server/tool-input-validators.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmIxB,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAsBpE,CAAC;AAEH,MAAM,WAAW,sBAAsB;IACrC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC7C;AAED,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,MAAM,EAChB,KAAK,EAAE,OAAO,GACb;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,OAAO,EAAE,sBAAsB,CAAA;CAAE,CAkB9E"}

package/dist/server/tool-input-validators.js

@@ -38,6 +38,7 @@ const getRelevantContextSchema = z
     includeRules: z.boolean().optional(),
     includePaths: z.boolean().optional(),
     includeDocs: z.boolean().optional(),
+    compact: z.boolean().optional(),
 })
     .strict();
 const getRelevantRulesSchema = z
@@ -75,6 +76,42 @@ const getPipelineContextSchema = z
     scope: z.array(z.string()).optional(),
 })
     .strict();
+const compressContextSchema = z
+    .object({
+    content: z.string().min(1, 'content is required'),
+    contentType: z.string().optional(),
+    query: z.string().optional(),
+    maxItems: z.number().int().min(1).optional(),
+    // Arms the lossy SmartCrusher row-sampler for oversized homogeneous arrays.
+    // Must mirror the tool's inputSchema, or the strict validator rejects the
+    // call on the real MCP wire before the handler ever runs.
+    maxTokens: z.number().int().min(1).optional(),
+})
+    .strict();
+const retrieveOriginalSchema = z.object({ key: z.string().min(1, 'key is required') }).strict();
+const alignCacheSchema = z
+    .object({ content: z.string().min(1, 'content is required'), map: z.unknown().optional() })
+    .strict();
+const restoreCacheSchema = z
+    .object({ content: z.string(), map: z.unknown() })
+    .strict();
+const getKnowledgeGraphSchema = z
+    .object({
+    format: z.enum(['json', 'table']).optional(),
+    // Mirrors the tool's inputSchema (P5.2). Must stay in lockstep, or the
+    // schema-parity guard (schema-parity.test.ts) turns red.
+    maxTokens: z.number().int().min(1).optional(),
+})
+    .strict();
+// deps_audit advertises package/format/maxTokens; validate them on the wire so
+// the new lossy `maxTokens` budget can't be armed with a bad value (P5.2/P1.3).
+const depsAuditSchema = z
+    .object({
+    package: z.string().optional(),
+    format: z.enum(['json', 'table']).optional(),
+    maxTokens: z.number().int().min(1).optional(),
+})
+    .strict();
 export const TOOL_INPUT_SCHEMAS = Object.freeze({
     create_generation_plan: createGenerationPlanSchema,
     render_template_preview: renderTemplatePreviewSchema,
@@ -91,6 +128,12 @@ export const TOOL_INPUT_SCHEMAS = Object.freeze({
     get_pipeline_context: getPipelineContextSchema,
     get_pack: getPackSchema,
     create_pipeline_plan: createPipelinePlanSchema,
+    compress_context: compressContextSchema,
+    retrieve_original: retrieveOriginalSchema,
+    align_cache: alignCacheSchema,
+    restore_cache: restoreCacheSchema,
+    get_knowledge_graph: getKnowledgeGraphSchema,
+    deps_audit: depsAuditSchema,
 });
 export function validateToolInput(toolName, input) {
     const schema = TOOL_INPUT_SCHEMAS[toolName];

package/dist/tools/agent-brief.tool.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-brief.tool.d.ts","sourceRoot":"","sources":["../../src/tools/agent-brief.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE,eAAO,MAAM,oBAAoB,EAAE,eA2ClC,CAAC"}
+{"version":3,"file":"agent-brief.tool.d.ts","sourceRoot":"","sources":["../../src/tools/agent-brief.tool.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAIpE,eAAO,MAAM,oBAAoB,EAAE,eA+DlC,CAAC"}

package/dist/tools/agent-brief.tool.js

@@ -1,4 +1,5 @@
 import { buildAgentBrief, BriefMode } from '@shrkcrft/inspector';
+import { compressMarkdown } from '@shrkcrft/compress';
 const VALID_MODES = new Set(Object.values(BriefMode));
 export const createAgentBriefTool = {
     name: 'create_agent_brief',
@@ -14,6 +15,10 @@ export const createAgentBriefTool = {
             maxTokens: { type: 'number' },
             chunked: { type: 'boolean' },
             sectionBudgets: { type: 'object' },
+            compact: {
+                type: 'boolean',
+                description: 'Run the brief markdown through the deterministic markdown compressor (headers/leads/structure kept, prose thinned). Reversible — the original is cached and a `<<ccr:KEY>>` marker emitted (retrieve_original to recover).',
+            },
         },
         additionalProperties: false,
     },
@@ -39,6 +44,21 @@ export const createAgentBriefTool = {
             ...(chunked ? { chunked: true } : {}),
             ...(sectionBudgets ? { sectionBudgets } : {}),
         });
+        if (input['compact'] === true) {
+            const c = compressMarkdown(brief.markdown, ctx.ccrStore ? { store: ctx.ccrStore } : {});
+            return {
+                data: {
+                    ...brief,
+                    markdown: c.compressed,
+                    compaction: {
+                        strategy: c.strategy,
+                        tokensBefore: c.savings.before,
+                        tokensAfter: c.savings.after,
+                        ccrKey: c.ccrKey ?? null,
+                    },
+                },
+            };
+        }
         return { data: brief };
     },
 };

package/dist/tools/align-cache.tool.d.ts

@@ -0,0 +1,11 @@
+import type { IToolDefinition } from '../server/tool-definition.js';
+/**
+ * Active cache-aligner: replace volatile tokens with stable placeholders so a
+ * provider KV-cache prefix stays steady across turns. Returns the map in the
+ * payload (never writes disk) so the host carries it forward — honouring
+ * MCP-never-writes. Reversible via `restore_cache`.
+ */
+export declare const alignCacheTool: IToolDefinition;
+/** The restore half of {@link alignCacheTool}. Read-only. */
+export declare const restoreCacheTool: IToolDefinition;
+//# sourceMappingURL=align-cache.tool.d.ts.map

package/dist/tools/align-cache.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align-cache.tool.d.ts","sourceRoot":"","sources":["../../src/tools/align-cache.tool.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AASpE;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,eAkC5B,CAAC;AAEF,6DAA6D;AAC7D,eAAO,MAAM,gBAAgB,EAAE,eA0B9B,CAAC"}

package/dist/tools/align-cache.tool.js

@@ -0,0 +1,76 @@
+import { alignVolatileTokens, restoreVolatileTokens } from '@shrkcrft/compress';
+function asAlignmentMap(value) {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const m = value;
+    if (m.version !== 1 || !Array.isArray(m.bindings))
+        return undefined;
+    return value;
+}
+/**
+ * Active cache-aligner: replace volatile tokens with stable placeholders so a
+ * provider KV-cache prefix stays steady across turns. Returns the map in the
+ * payload (never writes disk) so the host carries it forward — honouring
+ * MCP-never-writes. Reversible via `restore_cache`.
+ */
+export const alignCacheTool = {
+    name: 'align_cache',
+    description: 'Replace volatile tokens (UUIDs, JWTs, ISO timestamps, hashes, epochs) in a blob with stable `«vk:…»` placeholders so a provider KV-cache prefix stays stable across turns — same information, fewer cache-busting tokens. Returns the aligned text plus a map; pass the map back in next turn (and to `restore_cache`) so placeholders stay stable. Deterministic, reversible, no model. Read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            content: { type: 'string', description: 'The text to align.' },
+            map: { type: 'object', description: 'A prior alignment map to carry forward (optional).' },
+        },
+        required: ['content'],
+        additionalProperties: false,
+    },
+    handler(input) {
+        const content = typeof input.content === 'string' ? input.content : '';
+        if (content.length === 0) {
+            return {
+                isError: true,
+                text: 'align_cache requires a non-empty "content" string.',
+                error: { code: 'invalid-input', message: 'content is required' },
+            };
+        }
+        const prior = asAlignmentMap(input.map);
+        const result = alignVolatileTokens(content, prior);
+        return {
+            data: {
+                aligned: result.aligned,
+                map: result.map,
+                replaced: result.replaced,
+                restoreWith: 'restore_cache { "content": "<aligned>", "map": <map> }',
+            },
+            text: result.aligned,
+        };
+    },
+};
+/** The restore half of {@link alignCacheTool}. Read-only. */
+export const restoreCacheTool = {
+    name: 'restore_cache',
+    description: 'Reverse `align_cache`: restore the original volatile tokens in an aligned blob using its map. Lossless. Read-only.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            content: { type: 'string', description: 'Aligned text containing `«vk:…»` placeholders.' },
+            map: { type: 'object', description: 'The alignment map returned by `align_cache`.' },
+        },
+        required: ['content', 'map'],
+        additionalProperties: false,
+    },
+    handler(input) {
+        const content = typeof input.content === 'string' ? input.content : '';
+        const map = asAlignmentMap(input.map);
+        if (!map) {
+            return {
+                isError: true,
+                text: 'restore_cache requires the `map` returned by align_cache.',
+                error: { code: 'invalid-input', message: 'a valid alignment map is required' },
+            };
+        }
+        const restored = restoreVolatileTokens(content, map);
+        return { data: { restored }, text: restored };
+    },
+};

package/dist/tools/all-tools.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAmTpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EA6P9C,CAAC"}
+{"version":3,"file":"all-tools.d.ts","sourceRoot":"","sources":["../../src/tools/all-tools.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAkVpE,eAAO,MAAM,SAAS,EAAE,SAAS,eAAe,EA4R9C,CAAC"}