@mxalbert/context-mode 2.0.0

package/build/truncate.d.ts

@@ -0,0 +1,57 @@
+/**
+ * truncate — Pure string truncation and escaping utilities for context-mode.
+ *
+ * These helpers are used by the core ContentStore (chunking) and
+ * SessionDB (snapshot building). They are extracted here so any
+ * consumer can import them without pulling in the full store or executor.
+ */
+/**
+ * Return a prefix of `str` no longer than `maxChars` UTF-16 code units, with
+ * the cut backed off by one unit if it would split a surrogate pair. Mirrors
+ * the surrogate-safety semantics of the internal `byteSafePrefix`, but uses
+ * a character budget rather than a byte budget.
+ *
+ * Use this instead of bare `str.slice(0, n)` whenever the result is later
+ * JSON-encoded for an RFC 8259-strict consumer (e.g. tool_result payloads
+ * sent back to the host LLM API). `JSON.stringify` will emit a lone high
+ * surrogate as a literal `\uD8xx` escape, which is invalid JSON.
+ *
+ * @param str      - Input string.
+ * @param maxChars - Hard cap in UTF-16 code units.
+ */
+export declare function charSafePrefix(str: string, maxChars: number): string;
+/**
+ * Serialize a value to JSON, then truncate the result to `maxBytes` bytes.
+ * If truncation occurs, the string is cut at a UTF-8-safe boundary and
+ * "... [truncated]" is appended. The result is NOT guaranteed to be valid
+ * JSON after truncation — it is suitable only for display/logging.
+ *
+ * The returned string is always <= `maxBytes` bytes. When `maxBytes` is
+ * smaller than the marker, the marker itself is byte-safely truncated.
+ *
+ * @param value    - Any JSON-serializable value.
+ * @param maxBytes - Maximum byte length of the returned string.
+ * @param indent   - JSON indentation spaces (default 2). Pass 0 for compact.
+ */
+export declare function truncateJSON(value: unknown, maxBytes: number, indent?: number): string;
+/**
+ * Escape a string for safe embedding in an XML or HTML attribute or text node.
+ * Replaces the five XML-reserved characters: `&`, `<`, `>`, `"`, `'`.
+ *
+ * Used by the resume snapshot template builder to embed user content in
+ * `<tool_response>` and `<user_message>` XML tags without breaking the
+ * structured prompt format.
+ */
+export declare function escapeXML(str: string): string;
+/**
+ * Return `str` unchanged if it fits within `maxBytes`, otherwise return a
+ * byte-safe slice with an ellipsis appended. Useful for single-value fields
+ * (e.g., tool response strings) where head+tail splitting is not needed.
+ *
+ * The returned string is always <= `maxBytes` bytes. When `maxBytes` is
+ * smaller than the ellipsis marker, the marker itself is byte-safely truncated.
+ *
+ * @param str      - Input string.
+ * @param maxBytes - Hard byte cap.
+ */
+export declare function capBytes(str: string, maxBytes: number): string;

package/build/truncate.js

@@ -0,0 +1,142 @@
+/**
+ * truncate — Pure string truncation and escaping utilities for context-mode.
+ *
+ * These helpers are used by the core ContentStore (chunking) and
+ * SessionDB (snapshot building). They are extracted here so any
+ * consumer can import them without pulling in the full store or executor.
+ */
+// ─────────────────────────────────────────────────────────
+// Internal: byte-safe prefix
+// ─────────────────────────────────────────────────────────
+/**
+ * Return the longest character-prefix of `str` whose UTF-8 encoding is at
+ * most `maxBytes` bytes. Uses binary search to avoid O(n²) scanning. Returns
+ * "" when `maxBytes` is <= 0 so callers never exceed their budget.
+ *
+ * Guards against splitting a UTF-16 surrogate pair: if the prefix would end
+ * on a lone high surrogate, back off one code unit so the result round-trips
+ * through UTF-8 without producing a U+FFFD replacement character.
+ */
+function byteSafePrefix(str, maxBytes) {
+    if (maxBytes <= 0)
+        return "";
+    if (Buffer.byteLength(str) <= maxBytes)
+        return str;
+    let lo = 0;
+    let hi = str.length;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >> 1;
+        if (Buffer.byteLength(str.slice(0, mid)) <= maxBytes) {
+            lo = mid;
+        }
+        else {
+            hi = mid - 1;
+        }
+    }
+    // If we landed between a high and low surrogate, back off so the prefix
+    // ends on a valid code point boundary.
+    if (lo > 0) {
+        const code = str.charCodeAt(lo - 1);
+        if (code >= 0xd800 && code <= 0xdbff)
+            lo -= 1;
+    }
+    return str.slice(0, lo);
+}
+// ─────────────────────────────────────────────────────────
+// Char-count prefix (UTF-16 surrogate-safe)
+// ─────────────────────────────────────────────────────────
+/**
+ * Return a prefix of `str` no longer than `maxChars` UTF-16 code units, with
+ * the cut backed off by one unit if it would split a surrogate pair. Mirrors
+ * the surrogate-safety semantics of the internal `byteSafePrefix`, but uses
+ * a character budget rather than a byte budget.
+ *
+ * Use this instead of bare `str.slice(0, n)` whenever the result is later
+ * JSON-encoded for an RFC 8259-strict consumer (e.g. tool_result payloads
+ * sent back to the host LLM API). `JSON.stringify` will emit a lone high
+ * surrogate as a literal `\uD8xx` escape, which is invalid JSON.
+ *
+ * @param str      - Input string.
+ * @param maxChars - Hard cap in UTF-16 code units.
+ */
+export function charSafePrefix(str, maxChars) {
+    if (maxChars <= 0)
+        return "";
+    if (str.length <= maxChars)
+        return str;
+    let end = maxChars;
+    const code = str.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        end -= 1;
+    return str.slice(0, end);
+}
+// ─────────────────────────────────────────────────────────
+// JSON truncation
+// ─────────────────────────────────────────────────────────
+/**
+ * Serialize a value to JSON, then truncate the result to `maxBytes` bytes.
+ * If truncation occurs, the string is cut at a UTF-8-safe boundary and
+ * "... [truncated]" is appended. The result is NOT guaranteed to be valid
+ * JSON after truncation — it is suitable only for display/logging.
+ *
+ * The returned string is always <= `maxBytes` bytes. When `maxBytes` is
+ * smaller than the marker, the marker itself is byte-safely truncated.
+ *
+ * @param value    - Any JSON-serializable value.
+ * @param maxBytes - Maximum byte length of the returned string.
+ * @param indent   - JSON indentation spaces (default 2). Pass 0 for compact.
+ */
+export function truncateJSON(value, maxBytes, indent = 2) {
+    const serialized = JSON.stringify(value, null, indent) ?? "null";
+    if (Buffer.byteLength(serialized) <= maxBytes)
+        return serialized;
+    const marker = "... [truncated]";
+    const markerBytes = Buffer.byteLength(marker);
+    // Degenerate budget: can't fit serialized content + marker. Fit as much of
+    // the marker as we can so the return still honors `maxBytes`.
+    if (maxBytes <= markerBytes)
+        return byteSafePrefix(marker, maxBytes);
+    return byteSafePrefix(serialized, maxBytes - markerBytes) + marker;
+}
+// ─────────────────────────────────────────────────────────
+// XML / HTML escaping
+// ─────────────────────────────────────────────────────────
+/**
+ * Escape a string for safe embedding in an XML or HTML attribute or text node.
+ * Replaces the five XML-reserved characters: `&`, `<`, `>`, `"`, `'`.
+ *
+ * Used by the resume snapshot template builder to embed user content in
+ * `<tool_response>` and `<user_message>` XML tags without breaking the
+ * structured prompt format.
+ */
+export function escapeXML(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+// ─────────────────────────────────────────────────────────
+// maxBytes guard
+// ─────────────────────────────────────────────────────────
+/**
+ * Return `str` unchanged if it fits within `maxBytes`, otherwise return a
+ * byte-safe slice with an ellipsis appended. Useful for single-value fields
+ * (e.g., tool response strings) where head+tail splitting is not needed.
+ *
+ * The returned string is always <= `maxBytes` bytes. When `maxBytes` is
+ * smaller than the ellipsis marker, the marker itself is byte-safely truncated.
+ *
+ * @param str      - Input string.
+ * @param maxBytes - Hard byte cap.
+ */
+export function capBytes(str, maxBytes) {
+    if (Buffer.byteLength(str) <= maxBytes)
+        return str;
+    const marker = "...";
+    const markerBytes = Buffer.byteLength(marker);
+    if (maxBytes <= markerBytes)
+        return byteSafePrefix(marker, maxBytes);
+    return byteSafePrefix(str, maxBytes - markerBytes) + marker;
+}

package/build/types.d.ts

@@ -0,0 +1,117 @@
+/**
+ * types — Shared type definitions for context-mode packages.
+ *
+ * Contains interfaces that are genuinely shared between the core (ContentStore,
+ * PolyglotExecutor) and the session domain (SessionDB, event extraction).
+ * Import from "./types.js".
+ */
+/** Tool call representation used during event extraction from Claude messages. */
+export interface ToolCall {
+    toolName: string;
+    toolInput: Record<string, unknown>;
+    toolResponse?: string;
+    isError?: boolean;
+}
+/** User message representation used during event extraction. */
+export interface UserMessage {
+    content: string;
+    timestamp?: string;
+}
+/**
+ * Session event as stored in SessionDB.
+ * Each event captures a discrete unit of session activity (tool use, user
+ * message, assistant response summary, etc.) for later resume-snapshot
+ * reconstruction.
+ */
+export interface SessionEvent {
+    type: string;
+    category: string;
+    data: string;
+    priority: number;
+    data_hash: string;
+    /**
+     * Best-effort project attribution for this event.
+     * Empty string means unattributed/unknown.
+     */
+    project_dir?: string;
+    attribution_source?: string;
+    /** 0..1 confidence score for project attribution. */
+    attribution_confidence?: number;
+}
+/**
+ * Result returned by PolyglotExecutor after running a code snippet.
+ * Shared here so SessionDB can record execution outcomes without importing
+ * the full executor module.
+ */
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    timedOut: boolean;
+    /** Process was detached and continues running in the background. */
+    backgrounded?: boolean;
+}
+/**
+ * Result returned after indexing content into the knowledge base.
+ * Shared so session tooling can record what was indexed without importing
+ * ContentStore.
+ */
+export interface IndexResult {
+    sourceId: number;
+    label: string;
+    totalChunks: number;
+    codeChunks: number;
+}
+/**
+ * A single search result returned from FTS5 BM25-ranked lookup.
+ * Shared for consumers that display or log results outside of ContentStore.
+ */
+export interface SearchResult {
+    title: string;
+    content: string;
+    source: string;
+    rank: number;
+    contentType: "code" | "prose";
+    matchLayer?: "porter" | "trigram" | "fuzzy" | "rrf" | "rrf-fuzzy";
+    highlighted?: string;
+    timestamp?: string;
+    /**
+     * Session-id attribution copied from the `chunks.session_id` column
+     * (legacy unattributed chunks carry an empty string). Used by the
+     * `ctx_search` per-project filter (#737) to scope shared-DB results
+     * to the current project via the 2-step IN-clause strategy.
+     */
+    sessionId?: string;
+}
+/**
+ * Aggregate statistics for a ContentStore instance.
+ */
+export interface StoreStats {
+    sources: number;
+    chunks: number;
+    codeChunks: number;
+}
+/**
+ * Structured representation of a session resume snapshot, suitable for
+ * injecting into a new conversation as context. Generated from stored
+ * SessionEvents by the snapshot builder.
+ */
+export interface ResumeSnapshot {
+    /** ISO-8601 timestamp of when the snapshot was generated. */
+    generatedAt: string;
+    /** Human-readable summary of the session to this point. */
+    summary: string;
+    /** Ordered list of events selected for the snapshot (priority-filtered). */
+    events: SessionEvent[];
+}
+/**
+ * Priority levels for SessionEvent records. Higher numbers are more important
+ * and are retained when the snapshot budget is tight.
+ */
+export declare const EventPriority: {
+    readonly LOW: 1;
+    readonly NORMAL: 2;
+    readonly HIGH: 3;
+    readonly CRITICAL: 4;
+};
+export type EventPriorityLevel = (typeof EventPriority)[keyof typeof EventPriority];

package/build/types.js

@@ -0,0 +1,20 @@
+/**
+ * types — Shared type definitions for context-mode packages.
+ *
+ * Contains interfaces that are genuinely shared between the core (ContentStore,
+ * PolyglotExecutor) and the session domain (SessionDB, event extraction).
+ * Import from "./types.js".
+ */
+// ─────────────────────────────────────────────────────────
+// Priority constants
+// ─────────────────────────────────────────────────────────
+/**
+ * Priority levels for SessionEvent records. Higher numbers are more important
+ * and are retained when the snapshot budget is tight.
+ */
+export const EventPriority = {
+    LOW: 1,
+    NORMAL: 2,
+    HIGH: 3,
+    CRITICAL: 4,
+};

package/build/util/claude-config.d.ts

@@ -0,0 +1,32 @@
+export declare function resolveClaudeConfigDir(env?: NodeJS.ProcessEnv): string;
+/** Resolve the global settings.json path, honoring CLAUDE_CONFIG_DIR. */
+export declare function resolveClaudeGlobalSettingsPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Issue #451 round-3: cross-adapter deny-policy parity.
+ *
+ * `resolveClaudeGlobalSettingsPath` hardcodes the `.claude` segment, so
+ * non-Claude adapters (cursor, codex, qwen-code, gemini-cli, jetbrains-copilot,
+ * vscode-copilot, etc.) never had their global settings consulted by the
+ * security policy reader. This helper returns the union of:
+ *
+ *   1. The currently-detected adapter's home-rooted settings.json (when the
+ *      adapter is non-claude — claude is already covered by entry 2).
+ *   2. The claude global settings.json (always — defense in depth).
+ *
+ * Static import of `../adapters/detect.js` is safe — detect.ts only imports
+ * `node:` builtins, `./types.js` (type-only), and `./client-map.js` (pure
+ * data). It does NOT import claude-config back, so no cycle.
+ *
+ * History: this used `createRequire(import.meta.url).resolve(...)` to lazy-
+ * load detect at call time. That pattern requires `require(esm)`, which is
+ * flag-gated on Node 22.x before 22.12 (`--experimental-require-module`).
+ * CI run 25877550371 on Node 22.5 silently failed every detect.* call —
+ * the catch block ate the error and every cross-adapter deny-policy test
+ * returned an empty policy list. Static import sidesteps the require(esm)
+ * gate entirely, so the same code works on every supported Node version
+ * (20.x, 22.5, 22.12+, 24+) without needing the experimental flag.
+ *
+ * The returned array is deduplicated and order-stable: adapter-specific path
+ * first (most specific), claude global second (fallback).
+ */
+export declare function resolveAdapterGlobalSettingsPaths(env?: NodeJS.ProcessEnv): string[];

package/build/util/claude-config.js

@@ -0,0 +1,84 @@
+/**
+ * Claude Code config directory resolver — single source of truth.
+ *
+ * Issue #460 follow-up: every Claude-aware reader (adapters, security policy
+ * loader, hook helpers) MUST agree on where global settings live. Hardcoding
+ * `~/.claude` in any one reader silently breaks `CLAUDE_CONFIG_DIR` for that
+ * code path, producing policy drift that is invisible until a user sets the
+ * env var and watches their settings get ignored.
+ *
+ * Mirrors the contract of `hooks/session-helpers.mjs::resolveConfigDir` and
+ * `ClaudeCodeAdapter.getConfigDir`:
+ *   - env unset, empty string, or whitespace-only → ~/.claude
+ *   - env starts with `~`, `~/`, or `~\` → expanded against homedir()
+ *   - otherwise → resolved to absolute (relative paths anchor to cwd)
+ *
+ * Whitespace guard: shells that quote-pad the env value (`CLAUDE_CONFIG_DIR=" "`)
+ * would otherwise resolve to `cwd/<spaces>` — silently writing settings into
+ * the project tree. Trim before the truthy check so quote-padding falls back
+ * to `~/.claude` like a sane default.
+ *
+ * Cross-platform note: tilde regex strips a single leading `/` OR `\` so
+ * `~\Users\foo` works on Windows. `path.resolve` handles drive-letter joining.
+ */
+import { resolve } from "node:path";
+import { homedir } from "node:os";
+import { detectPlatform, getSessionDirSegments } from "../adapters/detect.js";
+export function resolveClaudeConfigDir(env = process.env) {
+    const envVal = env.CLAUDE_CONFIG_DIR;
+    if (envVal && envVal.trim() !== "") {
+        if (envVal.startsWith("~")) {
+            return resolve(homedir(), envVal.replace(/^~[/\\]?/, ""));
+        }
+        return resolve(envVal);
+    }
+    return resolve(homedir(), ".claude");
+}
+/** Resolve the global settings.json path, honoring CLAUDE_CONFIG_DIR. */
+export function resolveClaudeGlobalSettingsPath(env = process.env) {
+    return resolve(resolveClaudeConfigDir(env), "settings.json");
+}
+/**
+ * Issue #451 round-3: cross-adapter deny-policy parity.
+ *
+ * `resolveClaudeGlobalSettingsPath` hardcodes the `.claude` segment, so
+ * non-Claude adapters (cursor, codex, qwen-code, gemini-cli, jetbrains-copilot,
+ * vscode-copilot, etc.) never had their global settings consulted by the
+ * security policy reader. This helper returns the union of:
+ *
+ *   1. The currently-detected adapter's home-rooted settings.json (when the
+ *      adapter is non-claude — claude is already covered by entry 2).
+ *   2. The claude global settings.json (always — defense in depth).
+ *
+ * Static import of `../adapters/detect.js` is safe — detect.ts only imports
+ * `node:` builtins, `./types.js` (type-only), and `./client-map.js` (pure
+ * data). It does NOT import claude-config back, so no cycle.
+ *
+ * History: this used `createRequire(import.meta.url).resolve(...)` to lazy-
+ * load detect at call time. That pattern requires `require(esm)`, which is
+ * flag-gated on Node 22.x before 22.12 (`--experimental-require-module`).
+ * CI run 25877550371 on Node 22.5 silently failed every detect.* call —
+ * the catch block ate the error and every cross-adapter deny-policy test
+ * returned an empty policy list. Static import sidesteps the require(esm)
+ * gate entirely, so the same code works on every supported Node version
+ * (20.x, 22.5, 22.12+, 24+) without needing the experimental flag.
+ *
+ * The returned array is deduplicated and order-stable: adapter-specific path
+ * first (most specific), claude global second (fallback).
+ */
+export function resolveAdapterGlobalSettingsPaths(env = process.env) {
+    const paths = [];
+    const detected = detectPlatform();
+    if (detected.platform !== "claude-code") {
+        const segments = getSessionDirSegments(detected.platform);
+        if (segments && segments.length > 0) {
+            paths.push(resolve(homedir(), ...segments, "settings.json"));
+        }
+    }
+    // Always include claude global as fallback (defense in depth).
+    const claudePath = resolveClaudeGlobalSettingsPath(env);
+    if (!paths.includes(claudePath)) {
+        paths.push(claudePath);
+    }
+    return paths;
+}

package/build/util/hook-config.d.ts

@@ -0,0 +1,27 @@
+import { type HookAdapter } from "../adapters/types.js";
+export declare function getCommandsFromHookEntry(entry: unknown): string[];
+/**
+ * Extract the hook script path from a hook command string.
+ *
+ * Post Algo-D2 this is a thin wrapper around `parseNodeCommand` with a
+ * single legacy fallback retained for stale-entry cleanup
+ * (`configureAllHooks` walks pre-v1.0.124 settings.json shapes that
+ * predate `buildNodeCommand`). The legacy branches are deliberately
+ * narrow:
+ *
+ *   1) Canonical: `"<nodePath>" "<scriptPath>.mjs"` — `parseNodeCommand`
+ *      handles this; round-trips with `buildNodeCommand`.
+ *   2) Legacy quoted: `node "<scriptPath>.mjs"` — emitted by claude-code
+ *      pre-D3. The script segment is fully quoted, no whitespace
+ *      ambiguity.
+ *   3) Legacy unquoted: `node <scriptPath>.mjs` — only when the entire
+ *      command is whitespace-safe (exactly two whitespace-separated
+ *      tokens). The #548 wire shape — `node C:/Users/High Ground …` —
+ *      contains internal whitespace so this branch refuses it. Returns
+ *      `null` instead of grabbing the tail after the last whitespace.
+ *
+ * Anything else returns `null`, letting the doctor (Algo-D1) fall
+ * through to direct `existsSync` instead of trusting the regex.
+ */
+export declare function extractHookScriptPath(command: string): string | null;
+export declare function getHookScriptPaths(adapter: HookAdapter, pluginRoot: string): string[];

package/build/util/hook-config.js

@@ -0,0 +1,76 @@
+import { parseNodeCommand } from "../adapters/types.js";
+export function getCommandsFromHookEntry(entry) {
+    const commands = [];
+    if (entry && typeof entry === "object") {
+        const command = entry.command;
+        if (typeof command === "string")
+            commands.push(command);
+        const hooks = entry.hooks;
+        if (Array.isArray(hooks)) {
+            for (const hook of hooks) {
+                if (hook && typeof hook === "object") {
+                    const nestedCommand = hook.command;
+                    if (typeof nestedCommand === "string")
+                        commands.push(nestedCommand);
+                }
+            }
+        }
+    }
+    return commands;
+}
+/**
+ * Extract the hook script path from a hook command string.
+ *
+ * Post Algo-D2 this is a thin wrapper around `parseNodeCommand` with a
+ * single legacy fallback retained for stale-entry cleanup
+ * (`configureAllHooks` walks pre-v1.0.124 settings.json shapes that
+ * predate `buildNodeCommand`). The legacy branches are deliberately
+ * narrow:
+ *
+ *   1) Canonical: `"<nodePath>" "<scriptPath>.mjs"` — `parseNodeCommand`
+ *      handles this; round-trips with `buildNodeCommand`.
+ *   2) Legacy quoted: `node "<scriptPath>.mjs"` — emitted by claude-code
+ *      pre-D3. The script segment is fully quoted, no whitespace
+ *      ambiguity.
+ *   3) Legacy unquoted: `node <scriptPath>.mjs` — only when the entire
+ *      command is whitespace-safe (exactly two whitespace-separated
+ *      tokens). The #548 wire shape — `node C:/Users/High Ground …` —
+ *      contains internal whitespace so this branch refuses it. Returns
+ *      `null` instead of grabbing the tail after the last whitespace.
+ *
+ * Anything else returns `null`, letting the doctor (Algo-D1) fall
+ * through to direct `existsSync` instead of trusting the regex.
+ */
+export function extractHookScriptPath(command) {
+    const parsed = parseNodeCommand(command);
+    if (parsed) {
+        return parsed.scriptPath.endsWith(".mjs") ? parsed.scriptPath : null;
+    }
+    // Legacy quoted: `node "/path/with spaces/x.mjs"` (pre-D3 claude-code emit).
+    const legacyQuoted = command.match(/^\s*node\s+"([^"]+\.mjs)"\s*$/);
+    if (legacyQuoted)
+        return legacyQuoted[1];
+    // Legacy unquoted: `node /path/x.mjs` — refuses internal whitespace
+    // by anchoring both tokens. The #548 ambiguous shape has 3+ tokens
+    // (spaces in the path) and falls through to `null`.
+    const legacyBare = command.match(/^\s*node\s+(\S+\.mjs)\s*$/);
+    if (legacyBare)
+        return legacyBare[1];
+    return null;
+}
+export function getHookScriptPaths(adapter, pluginRoot) {
+    const paths = new Set();
+    const hookConfig = adapter.generateHookConfig(pluginRoot);
+    for (const entries of Object.values(hookConfig)) {
+        if (!Array.isArray(entries))
+            continue;
+        for (const entry of entries) {
+            for (const command of getCommandsFromHookEntry(entry)) {
+                const scriptPath = extractHookScriptPath(command);
+                if (scriptPath)
+                    paths.add(scriptPath);
+            }
+        }
+    }
+    return [...paths];
+}

package/build/util/jsonc.d.ts

@@ -0,0 +1,14 @@
+/**
+ * util/jsonc — string-aware JSONC comment + trailing-comma stripping and a
+ * tolerant parse. Several agent CLIs ship config files as JSONC (VS Code
+ * `mcp.json`, Zed `settings.json`), so a strict `JSON.parse` false-fails on a
+ * perfectly valid commented file. Use `parseJsonc` whenever reading a
+ * platform config we did not write ourselves.
+ */
+/** Strip `//` line + `/* *​/` block comments and trailing commas, string-aware. */
+export declare function stripJsonComments(str: string): string;
+/**
+ * Parse JSON or JSONC. Tries strict `JSON.parse` first (fast, exact), then a
+ * comment/trailing-comma-stripped parse. Returns `undefined` when both fail.
+ */
+export declare function parseJsonc<T = unknown>(raw: string): T | undefined;

package/build/util/jsonc.js

@@ -0,0 +1,104 @@
+/**
+ * util/jsonc — string-aware JSONC comment + trailing-comma stripping and a
+ * tolerant parse. Several agent CLIs ship config files as JSONC (VS Code
+ * `mcp.json`, Zed `settings.json`), so a strict `JSON.parse` false-fails on a
+ * perfectly valid commented file. Use `parseJsonc` whenever reading a
+ * platform config we did not write ourselves.
+ */
+/** Strip `//` line + `/* *​/` block comments and trailing commas, string-aware. */
+export function stripJsonComments(str) {
+    let out = "";
+    let inString = false;
+    let escaped = false;
+    let inBlockComment = false;
+    for (let i = 0; i < str.length; i++) {
+        const c = str[i];
+        const next = str[i + 1];
+        if (inBlockComment) {
+            if (c === "*" && next === "/") {
+                inBlockComment = false;
+                i++;
+            }
+            continue;
+        }
+        if (escaped) {
+            out += c;
+            escaped = false;
+            continue;
+        }
+        if (c === "\\") {
+            out += c;
+            escaped = inString;
+            continue;
+        }
+        if (c === '"') {
+            inString = !inString;
+            out += c;
+            continue;
+        }
+        if (!inString && c === "/" && next === "/") {
+            while (i < str.length && str[i] !== "\n")
+                i++;
+            if (i < str.length)
+                out += "\n";
+            continue;
+        }
+        if (!inString && c === "/" && next === "*") {
+            inBlockComment = true;
+            i++;
+            continue;
+        }
+        out += c;
+    }
+    // Trailing-comma removal, string-aware. The scan above already removed
+    // comments, so this second pass over `out` only needs to track string state:
+    // a comma is "trailing" when the next significant char is `}` or `]`. Doing
+    // it here — instead of a post-hoc trailing-comma regex over the whole string —
+    // preserves commas inside string literals (e.g. "[1, ]"), which that regex
+    // silently corrupted to "[1 ]". See #787 review.
+    let result = "";
+    let inStr = false;
+    let esc = false;
+    for (let i = 0; i < out.length; i++) {
+        const c = out[i];
+        if (esc) {
+            result += c;
+            esc = false;
+            continue;
+        }
+        if (c === "\\") {
+            result += c;
+            esc = inStr;
+            continue;
+        }
+        if (c === '"') {
+            inStr = !inStr;
+            result += c;
+            continue;
+        }
+        if (!inStr && c === ",") {
+            let j = i + 1;
+            while (j < out.length && (out[j] === " " || out[j] === "\t" || out[j] === "\r" || out[j] === "\n"))
+                j++;
+            if (out[j] === "}" || out[j] === "]")
+                continue;
+        }
+        result += c;
+    }
+    return result;
+}
+/**
+ * Parse JSON or JSONC. Tries strict `JSON.parse` first (fast, exact), then a
+ * comment/trailing-comma-stripped parse. Returns `undefined` when both fail.
+ */
+export function parseJsonc(raw) {
+    for (const candidate of [raw, stripJsonComments(raw)]) {
+        try {
+            return JSON.parse(candidate);
+        }
+        catch {
+            /* try next */
+        }
+    }
+    return undefined;
+}