@mxalbert/context-mode 2.0.0

package/build/adapters/qwen-code/usage.js

@@ -0,0 +1,222 @@
+/**
+ * adapters/qwen-code/usage — per-turn token capture from the session JSONL.
+ *
+ * Qwen Code is a Gemini-CLI fork and normalizes EVERY backend (Gemini-native,
+ * OpenAI-compat/DashScope, Anthropic) to the same canonical token shape:
+ * `GenerateContentResponseUsageMetadata` { promptTokenCount, candidatesTokenCount,
+ * cachedContentTokenCount, thoughtsTokenCount, totalTokenCount }
+ * (matrix §1: turn.ts:96,417 + converter.ts:1145-1148). That metadata is
+ * persisted, per API call, into the session record file as a `ChatRecord`
+ * carrying `.usageMetadata` + `.model`
+ * (refs: packages/core/src/services/chatRecordingService.ts:259,261,919 file at
+ * ~/.qwen/tmp/<project_id>/chats/<sessionId>.jsonl — :451 location comment,
+ * :600,628-629 path build).
+ *
+ * CRITICAL (matrix §4): qwen-code's hook payloads carry tool I/O ONLY — token
+ * usage is unreachable through the hook stream (grep of hookEventHandler.ts /
+ * hookSystem.ts / toolHookTriggers.ts for token|usageMetadata|usage → zero
+ * matches). The ONLY live capture path is a tail of the session JSONL. This
+ * module is therefore the JSONL-tail counterpart to claude-code's
+ * `extractTranscriptUsageSince` (src/session/extract.ts) — same cursor-gated,
+ * char-algorithmic, NO-regex parse, same `buildAgentUsageEvent` emission path.
+ *
+ * Per matrix §3 each ChatRecord.usageMetadata is INCREMENTAL per API call
+ * (cumulative session totals are derived downstream via += in
+ * uiTelemetry.ts:237-241), so summing the NEW records since the cursor yields
+ * the exact billed delta with no double-count.
+ *
+ * No native USD — cost_usd is derived from the pricing catalog inside
+ * buildAgentUsageEvent (native_cost_usd omitted). Pure, null-safe, NO regex.
+ */
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { platform } from "node:os";
+import { buildAgentUsageEvent } from "../../session/extract.js";
+/** Floor-and-clamp a token field to a non-negative integer (mirrors omp/usage). */
+function tokenNum(v) {
+    if (typeof v !== "number" || !Number.isFinite(v))
+        return 0;
+    const n = Math.floor(v);
+    return n > 0 ? n : 0;
+}
+/**
+ * Parse ONE qwen `ChatRecord` into the `buildAgentUsageEvent` input shape, or
+ * null when the record carries no usage / sums to zero.
+ *
+ * Mapping → builder shape (AgentUsageCounts):
+ *   promptTokenCount        → input_tokens
+ *   candidatesTokenCount    → output_tokens
+ *   thoughtsTokenCount      → ADDED into output_tokens (Gemini-lineage bills
+ *                             reasoning/thoughts as output — same fold as
+ *                             parseGeminiUsage in src/session/extract.ts)
+ *   cachedContentTokenCount → cache_read_tokens (when present)
+ *   model_id                → ChatRecord.model
+ *
+ * No native cost — native_cost_usd omitted (catalog-derived). NO regex.
+ */
+export function parseQwenUsage(record) {
+    if (!record || typeof record !== "object" || Array.isArray(record))
+        return null;
+    const rec = record;
+    const um = rec.usageMetadata;
+    if (!um || typeof um !== "object")
+        return null;
+    const usage = um;
+    const input = tokenNum(usage.promptTokenCount);
+    const candidates = tokenNum(usage.candidatesTokenCount);
+    const thoughts = tokenNum(usage.thoughtsTokenCount);
+    const cached = tokenNum(usage.cachedContentTokenCount);
+    // Gemini-lineage bills reasoning (thoughts) as output tokens — fold into output.
+    const output = candidates + thoughts;
+    // All token fields zero → not a billable record. buildAgentUsageEvent would
+    // also reject this, but short-circuit keeps the contract explicit.
+    if (input <= 0 && output <= 0 && cached <= 0)
+        return null;
+    const model_id = typeof rec.model === "string" ? rec.model : "";
+    return {
+        model_id,
+        input_tokens: input,
+        output_tokens: output,
+        cache_creation_tokens: 0, // qwen exposes no cache-creation field
+        cache_read_tokens: cached,
+        native_cost_usd: null, // catalog-derived (no native cost on qwen records)
+    };
+}
+/** Stable cursor identity for a ChatRecord: prefer `id`, fall back to `messageId`. */
+function recordId(rec) {
+    if (typeof rec.id === "string" && rec.id.length > 0)
+        return rec.id;
+    if (typeof rec.messageId === "string" && rec.messageId.length > 0)
+        return rec.messageId;
+    return null;
+}
+/**
+ * Cursor-aware tail of the qwen session JSONL. Emits one priced `agent_usage`
+ * event PER distinct model across the records NEW since `cursor`, so re-reading
+ * the (append-only, ever-growing) JSONL each Stop never double-counts.
+ *
+ *   - cursor null/empty            → process ALL records.
+ *   - cursor found                 → process records STRICTLY AFTER it.
+ *   - cursor set but NOT found     → compaction/rotation dropped it: bounded
+ *     fallback processes ONLY THE LAST record (never re-emit full history).
+ *
+ * `cursor` returns the id of the LAST id-bearing record seen (whether or not it
+ * carried usage), so the next call resumes exactly past it. When no record
+ * carries an id, the input cursor is returned unchanged.
+ *
+ * One linear walk, JSON.parse per line, NO regex — mirrors
+ * extractTranscriptUsageSince's structure exactly.
+ */
+export function extractQwenUsageSince(jsonlText, cursor) {
+    const inputCursor = typeof cursor === "string" && cursor.length > 0 ? cursor : null;
+    if (typeof jsonlText !== "string" || jsonlText.length === 0) {
+        return { events: [], cursor: inputCursor };
+    }
+    const rows = [];
+    let start = 0;
+    for (let i = 0; i <= jsonlText.length; i++) {
+        if (i !== jsonlText.length && jsonlText.charCodeAt(i) !== 10 /* \n */)
+            continue;
+        const line = jsonlText.slice(start, i).trim();
+        start = i + 1;
+        if (line.length === 0)
+            continue;
+        let obj;
+        try {
+            const p = JSON.parse(line);
+            if (!p || typeof p !== "object" || Array.isArray(p))
+                continue;
+            obj = p;
+        }
+        catch {
+            continue;
+        }
+        rows.push({ id: recordId(obj), counts: parseQwenUsage(obj) });
+    }
+    if (rows.length === 0)
+        return { events: [], cursor: inputCursor };
+    // Cursor always advances to the last id-bearing record's id (or stays as the
+    // input cursor when no record carries an id).
+    let lastId = inputCursor;
+    for (let i = rows.length - 1; i >= 0; i--) {
+        if (rows[i].id !== null) {
+            lastId = rows[i].id;
+            break;
+        }
+    }
+    // Select the slice to sum.
+    let slice;
+    if (inputCursor === null) {
+        slice = rows; // all records
+    }
+    else {
+        let foundAt = -1;
+        for (let i = 0; i < rows.length; i++) {
+            if (rows[i].id === inputCursor) {
+                foundAt = i;
+                break;
+            }
+        }
+        if (foundAt >= 0) {
+            slice = rows.slice(foundAt + 1); // strictly after the cursor
+        }
+        else {
+            // Compaction/rotation: cursor fell off the front. Bounded fallback — last
+            // record only. Never re-emit the whole history.
+            slice = rows.slice(rows.length - 1);
+        }
+    }
+    // Sum the selected records per model, then emit via the shared builder.
+    const sums = new Map();
+    for (const row of slice) {
+        const c = row.counts;
+        if (!c)
+            continue;
+        const cur = sums.get(c.model_id) ?? { input: 0, output: 0, cacheCreate: 0, cacheRead: 0 };
+        cur.input += c.input_tokens;
+        cur.output += c.output_tokens;
+        cur.cacheCreate += c.cache_creation_tokens;
+        cur.cacheRead += c.cache_read_tokens;
+        sums.set(c.model_id, cur);
+    }
+    const events = [];
+    for (const [model_id, s] of sums) {
+        const ev = buildAgentUsageEvent({
+            model_id,
+            input_tokens: s.input,
+            output_tokens: s.output,
+            cache_creation_tokens: s.cacheCreate,
+            cache_read_tokens: s.cacheRead,
+        });
+        if (ev)
+            events.push(ev);
+    }
+    return { events, cursor: lastId };
+}
+/**
+ * Hash a project root into qwen-code's `<project_id>` directory segment.
+ *
+ * EXACT port of qwen's `getProjectHash`
+ * (refs/platforms/qwen-code/packages/core/src/utils/paths.ts:262 —
+ * `crypto.createHash('sha256').update(normalizedPath).digest('hex')`). On
+ * Windows qwen lowercases the path first (case-insensitive FS); we mirror that
+ * so a hook running on win32 resolves the same tmp dir qwen itself wrote.
+ * Pure, deterministic, NO regex.
+ */
+export function qwenProjectHash(projectRoot) {
+    const normalized = platform() === "win32" ? projectRoot.toLowerCase() : projectRoot;
+    return createHash("sha256").update(normalized).digest("hex");
+}
+/**
+ * Build the canonical session JSONL path qwen-code writes its ChatRecords to:
+ *   <qwenHome>/tmp/<sha256(projectRoot)>/chats/<sessionId>.jsonl
+ * (refs chatRecordingService.ts:451 location + storage.ts:316-320
+ * getProjectTempDir → getGlobalTempDir(<qwenHome>/tmp) + getProjectHash).
+ *
+ * `qwenHome` is normally `<homedir>/.qwen`. Pure path join — does NOT touch the
+ * FS, so it is fully unit-testable; existence probing + the glob fallback live
+ * in the Stop hook (which cannot import this TS at runtime). NO regex.
+ */
+export function qwenChatJsonlPath(qwenHome, projectRoot, sessionId) {
+    return join(qwenHome, "tmp", qwenProjectHash(projectRoot), "chats", `${sessionId}.jsonl`);
+}

package/build/adapters/types.d.ts

@@ -0,0 +1,360 @@
+/**
+ * adapters/types — Platform adapter interface for multi-platform hook support.
+ *
+ * Defines the contract that each platform adapter must implement.
+ * Three paradigms exist across supported platforms:
+ *   A) JSON stdin/stdout — Claude Code, Gemini/Qwen family CLIs, Copilot/Codex/Kimi,
+ *      Cursor, Kiro, Antigravity CLI (`agy`)
+ *   B) TS Plugin Functions — OpenCode, KiloCode, OpenClaw
+ *   C) MCP-only (no hooks) — Antigravity IDE, Zed, Pi/OMP MCP-only paths
+ *
+ * The MCP server layer is 100% portable and needs no adapter.
+ * Only the hook layer requires platform-specific adapters.
+ */
+export type HookParadigm = "json-stdio" | "ts-plugin" | "mcp-only";
+export interface PlatformCapabilities {
+    /** Platform supports PreToolUse / BeforeTool / tool.execute.before hooks. */
+    preToolUse: boolean;
+    /** Platform supports PostToolUse / AfterTool / tool.execute.after hooks. */
+    postToolUse: boolean;
+    /** Platform supports PreCompact / PreCompress / session.compacting hooks. */
+    preCompact: boolean;
+    /** Platform supports SessionStart / session.created hooks. */
+    sessionStart: boolean;
+    /** Platform allows modifying tool input arguments via hooks. */
+    canModifyArgs: boolean;
+    /** Platform allows modifying tool output via PostToolUse hooks. */
+    canModifyOutput: boolean;
+    /** Platform allows injecting context during session start or compaction. */
+    canInjectSessionContext: boolean;
+}
+/** Normalized PreToolUse event — platform-agnostic representation. */
+export interface PreToolUseEvent {
+    /** Tool name being invoked (e.g., "Bash", "Read", "WebFetch"). */
+    toolName: string;
+    /** Tool input arguments as key-value pairs. */
+    toolInput: Record<string, unknown>;
+    /** Session ID extracted by the adapter. */
+    sessionId: string;
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input (for passthrough if needed). */
+    raw: unknown;
+}
+/** Normalized PostToolUse event — platform-agnostic representation. */
+export interface PostToolUseEvent {
+    /** Tool name that was invoked. */
+    toolName: string;
+    /** Tool input arguments. */
+    toolInput: Record<string, unknown>;
+    /** Tool output/response (if available). */
+    toolOutput?: string;
+    /** Whether the tool call resulted in an error. */
+    isError?: boolean;
+    /** Session ID extracted by the adapter. */
+    sessionId: string;
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input. */
+    raw: unknown;
+}
+/** Normalized PreCompact event. */
+export interface PreCompactEvent {
+    /** Session ID. */
+    sessionId: string;
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input. */
+    raw: unknown;
+}
+/** Normalized SessionStart event. */
+export interface SessionStartEvent {
+    /** Session ID. */
+    sessionId: string;
+    /** Lifecycle source: fresh start, compaction, resume, or clear. */
+    source: "startup" | "compact" | "resume" | "clear";
+    /** Project directory (if available). */
+    projectDir?: string;
+    /** Raw platform-specific input. */
+    raw: unknown;
+}
+/** Response from PreToolUse hook — can block, modify, inject context, or pass through. */
+export interface PreToolUseResponse {
+    /**
+     * "allow"   = pass through (no action)
+     * "deny"    = block tool execution
+     * "modify"  = change input args
+     * "context" = inject additional context (soft guidance)
+     * "ask"     = prompt user for confirmation (security policy match)
+     */
+    decision: "allow" | "deny" | "modify" | "context" | "ask";
+    /** Reason for denial (shown to the model). */
+    reason?: string;
+    /** Modified tool input (only when decision = "modify"). */
+    updatedInput?: Record<string, unknown>;
+    /** Additional context to inject (only when decision = "context"). */
+    additionalContext?: string;
+}
+/** Response from PostToolUse hook — can inject context or modify output. */
+export interface PostToolUseResponse {
+    /** Additional context to inject after tool output. */
+    additionalContext?: string;
+    /** Modified tool output (if platform supports it). */
+    updatedOutput?: string;
+}
+/** Response from PreCompact hook — injects context before compaction. */
+export interface PreCompactResponse {
+    /** Context to preserve across compaction. */
+    context?: string;
+}
+/** Response from SessionStart hook — injects context at session start. */
+export interface SessionStartResponse {
+    /** Context to inject at session start. */
+    context?: string;
+}
+/** A single hook entry in platform configuration. */
+export interface HookEntry {
+    /** Tool matcher pattern (empty = match all). */
+    matcher: string;
+    /** Hook commands/handlers to execute. */
+    hooks: Array<{
+        type: string;
+        command: string;
+    }>;
+}
+/** Hook registration map — maps hook types to their entries. */
+export type HookRegistration = Record<string, HookEntry[]>;
+/**
+ * HookAdapter — contract for platform-specific hook implementations.
+ *
+ * Each supported platform (Claude Code, Gemini CLI, OpenCode, etc.)
+ * provides an adapter that normalizes its hook I/O into a common format.
+ */
+export interface HookAdapter {
+    /** Human-readable platform name (e.g., "Claude Code", "Gemini CLI"). */
+    readonly name: string;
+    /** Hook I/O paradigm used by this platform. */
+    readonly paradigm: HookParadigm;
+    /** What this platform supports. */
+    readonly capabilities: PlatformCapabilities;
+    /** Parse raw PreToolUse input into normalized form. */
+    parsePreToolUseInput(raw: unknown): PreToolUseEvent;
+    /** Parse raw PostToolUse input into normalized form. */
+    parsePostToolUseInput(raw: unknown): PostToolUseEvent;
+    /** Parse raw PreCompact input (optional — not all platforms support it). */
+    parsePreCompactInput?(raw: unknown): PreCompactEvent;
+    /** Parse raw SessionStart input (optional — not all platforms support it). */
+    parseSessionStartInput?(raw: unknown): SessionStartEvent;
+    /** Format a PreToolUse response into platform-specific output. */
+    formatPreToolUseResponse(response: PreToolUseResponse): unknown;
+    /** Format a PostToolUse response into platform-specific output. */
+    formatPostToolUseResponse(response: PostToolUseResponse): unknown;
+    /** Format a PreCompact response into platform-specific output. */
+    formatPreCompactResponse?(response: PreCompactResponse): unknown;
+    /** Format a SessionStart response into platform-specific output. */
+    formatSessionStartResponse?(response: SessionStartResponse): unknown;
+    /** Path to the platform's settings file (e.g., ~/.claude/settings.json). */
+    getSettingsPath(): string;
+    /**
+     * Directory where session data is stored.
+     *
+     * NOTE — C2 narrowing (2026-05): this is the ONLY storage-path concern an
+     * adapter exposes. Per-project DB paths are derived by callers via
+     * `resolveSessionDbPath({ projectDir, sessionsDir: adapter.getSessionDir() })`
+     * (see `src/session/db.ts`). Per-project events.md paths follow the same
+     * `<sessionDir>/<hash><suffix>-events.md` shape and are computed inline at
+     * the small number of call sites that need them (server.ts, hooks).
+     */
+    getSessionDir(): string;
+    /**
+     * Platform config directory.
+     *
+     * Contract: ALWAYS returns an absolute path. Never returns a relative
+     * segment, never returns an empty string. This eliminates the leaky-seam
+     * where callers could not tell whether the return needed further resolution.
+     *
+     * Resolution rules:
+     *   - Home-rooted platforms (claude-code, codex, qwen, gemini, antigravity,
+     *     zed, opencode, …) return paths under `homedir()` / XDG / APPDATA.
+     *   - Project-scoped platforms (cursor → `.cursor`, vscode-copilot &
+     *     jetbrains-copilot → `.github`, kiro → `.kiro`, openclaw → project root)
+     *     resolve their segment against the supplied `projectDir`. When
+     *     `projectDir` is omitted, `process.cwd()` is used as the fallback.
+     *
+     * @param projectDir Optional project root used to resolve project-scoped
+     *                   adapters. Ignored by home-rooted adapters.
+     */
+    getConfigDir(projectDir?: string): string;
+    /**
+     * Names of platform-native instruction/rule files that act as the
+     * project's "user CLAUDE.md equivalent" (e.g., ["CLAUDE.md"],
+     * ["AGENTS.md"], ["GEMINI.md"]). Auto-memory scans for these in the
+     * project root and config dir, and rule-detection emits "rule" events
+     * when they are read.
+     */
+    getInstructionFiles(): string[];
+    /**
+     * Directory where persistent per-user memory is stored
+     * (e.g., ~/.claude/memory, ~/.codex/memories). Auto-memory scans
+     * *.md files in this directory.
+     *
+     * When `projectDir` is supplied, the path MUST be project-scoped (issue
+     * #663) so two projects running in parallel cannot read each other's
+     * memory. Adapters scope via `hashProjectDirCanonical(projectDir)`.
+     * Callers that pre-date this contract may omit `projectDir`; in that
+     * case the unscoped legacy path is returned.
+     */
+    getMemoryDir(projectDir?: string): string;
+    /** Generate hook registration config for this platform. */
+    generateHookConfig(pluginRoot: string): HookRegistration;
+    /** Read current platform settings. */
+    readSettings(): Record<string, unknown> | null;
+    /** Write platform settings. */
+    writeSettings(settings: Record<string, unknown>): void;
+    /** Validate that hooks are properly configured for this platform. */
+    validateHooks(pluginRoot: string): DiagnosticResult[];
+    /**
+     * Adapter-defined per-platform health checks (Algo-D1).
+     *
+     * OPTIONAL. Adapters that don't override return nothing — they don't
+     * have this class of check today. claude-code overrides with hook-script
+     * existence checks that join `pluginRoot + scriptName` directly via
+     * `existsSync`, so doctor never round-trips through a regex on a hook
+     * command (the #548 root cause).
+     *
+     * Adapter #16 with hook scripts inherits the contract by overriding;
+     * adapter #17 without hook scripts simply doesn't override. The doctor
+     * iterates `adapter.getHealthChecks?.(pluginRoot) ?? []` and renders
+     * each — no per-adapter wiring in the doctor body.
+     */
+    getHealthChecks?(pluginRoot: string): readonly HealthCheck[];
+    /** Check if the plugin is registered/enabled on this platform. */
+    checkPluginRegistration(): DiagnosticResult;
+    /**
+     * Get the installed version from this platform's registry/marketplace, or
+     * "standalone" when no platform-owned plugin version exists.
+     */
+    getInstalledVersion(): string;
+    /** Configure all hooks for this platform. Returns change descriptions. */
+    configureAllHooks(pluginRoot: string): string[];
+    /** Backup platform settings before modification. Returns backup path or null. */
+    backupSettings(): string | null;
+    /** Set executable permissions on hook scripts. Returns paths that were set. */
+    setHookPermissions(pluginRoot: string): string[];
+    /** Update platform's plugin registry to point to given path and version. */
+    updatePluginRegistry(pluginRoot: string, version: string): void;
+}
+/** Result from a platform-specific diagnostic check. */
+export interface DiagnosticResult {
+    /** What was checked. */
+    check: string;
+    /** Pass, fail, or warning. */
+    status: "pass" | "fail" | "warn";
+    /** Human-readable message. */
+    message: string;
+    /** Suggested fix command (if applicable). */
+    fix?: string;
+}
+/**
+ * Adapter-defined health check (Algo-D1).
+ *
+ * Lighter-weight than `DiagnosticResult`: adapters declare a name and a
+ * synchronous `check()` thunk. The doctor renders the result. The
+ * thunk-style intentionally avoids forcing adapters into async — the
+ * existsSync probe used by claude-code is sync and the doctor invokes it
+ * directly without an `await`. Adapters needing async work return a
+ * pre-resolved status (the check ran at thunk-creation time) or extend
+ * `validateHooks()` instead.
+ */
+export interface HealthCheck {
+    /** Human-readable check title (e.g. "Hook script exists: pretooluse.mjs"). */
+    readonly name: string;
+    /** Synchronous check thunk. Returns OK or FAIL with optional detail. */
+    check(): {
+        status: "OK" | "FAIL";
+        detail?: string;
+    };
+}
+/**
+ * Build a cross-platform `node <script>` command string.
+ *
+ * Fixes two Windows bugs:
+ *   #369 — Bare `node` fails on Windows Git Bash (MSYS) because PATH
+ *          resolution is unreliable. Uses `process.execPath` instead.
+ *   #372 — MSYS rewrites absolute paths on non-C: drives (e.g.
+ *          `C:\Users\...` → `D:\c\Users\...`). Forward slashes +
+ *          double-quoting prevents the translation.
+ *
+ * Safe on macOS/Linux — quoting and forward slashes are no-ops there.
+ */
+export declare function buildNodeCommand(scriptPath: string, opts?: {
+    platform?: string;
+    jsRuntime?: string;
+}): string;
+/**
+ * Build a cross-platform hook spawn command using the resolved JS runtime
+ * (issue #738). Identical wire-format to {@link buildNodeCommand} — two
+ * double-quoted, forward-slashed tokens separated by whitespace — so it
+ * round-trips through {@link parseNodeCommand} unchanged.
+ *
+ * The only difference is the runtime path: when a Bun ≥1.0 install is
+ * detected at process start, that path is used in place of `process.execPath`.
+ * Hooks run end-to-end in pure JS (no native modules) so swapping the
+ * runtime is a no-op for output but cuts ~40-60ms of Node cold-start per
+ * tool call.
+ *
+ * Why a SEPARATE helper instead of repurposing {@link buildNodeCommand}:
+ *   `buildNodeCommand` is also called by openclaw plugin (doctor / upgrade
+ *   command suggestions in `src/adapters/openclaw/plugin.ts`). Those CLI
+ *   targets MUST stay on Node because they load better-sqlite3, which has
+ *   no Bun-compatible prebuild yet (#543). Keeping the two helpers separate
+ *   makes the audit trivial: anything emitting a hook spawn command uses
+ *   `buildHookRuntimeCommand`; anything emitting a user-visible CLI command
+ *   stays on `buildNodeCommand`.
+ *
+ * `opts.platform` is forwarded to {@link isInProcessPluginPlatform} so the
+ * existing opencode/kilo in-process JS-runtime substitution still works
+ * (those platforms inject their own runtime via `opts.jsRuntime`).
+ */
+export declare function buildHookRuntimeCommand(scriptPath: string, opts?: {
+    platform?: string;
+    jsRuntime?: string;
+}): string;
+/**
+ * Strict inverse of `buildNodeCommand`.
+ *
+ * Returns `{ nodePath, scriptPath }` ONLY when `cmd` could have been
+ * produced by `buildNodeCommand` — i.e. exactly two double-quoted args
+ * separated by whitespace. Anything else (bare `node …`, single quotes,
+ * unquoted ambiguous input, CLI dispatcher entries) returns `null`.
+ *
+ * Why strict: the legacy `\S+\.mjs` fallback in
+ * `src/util/hook-config.ts:24` and the two-step regex in
+ * `src/adapters/claude-code/hooks.ts:178` silently grabbed the path tail
+ * after the last whitespace whenever the host wire-format dropped quotes,
+ * producing the #548 doubled-path FAIL when `pluginRoot` contained
+ * spaces (e.g. `C:\Users\High Ground Services\…`). A canonical inverse
+ * lets every emit (`buildNodeCommand`) round-trip through every parse
+ * (`parseNodeCommand`) without inventing fallbacks. Adapter #16 inherits
+ * the contract by importing one module.
+ */
+export declare function parseNodeCommand(cmd: string): {
+    nodePath: string;
+    scriptPath: string;
+} | null;
+/** Known JS runtime binary names (base filename without extension). */
+export declare const JS_RUNTIMES: ReadonlySet<string>;
+/** Platforms where context-mode runs as an in-process TS plugin (not MCP stdio). */
+export declare const IN_PROCESS_PLUGIN_PLATFORMS: ReadonlySet<string>;
+export declare function isInProcessPluginPlatform(p: string | undefined): boolean;
+/** Supported platform identifiers. */
+export type PlatformId = "claude-code" | "gemini-cli" | "opencode" | "kilo" | "openclaw" | "codex" | "vscode-copilot" | "jetbrains-copilot" | "copilot-cli" | "cursor" | "antigravity" | "antigravity-cli" | "kiro" | "pi" | "omp" | "kimi" | "zed" | "qwen-code" | "unknown";
+/** Detection signal used to identify which platform is running. */
+export interface DetectionSignal {
+    /** Platform identifier. */
+    platform: PlatformId;
+    /** Confidence: env var match > config dir match > fallback. */
+    confidence: "high" | "medium" | "low";
+    /** How it was detected. */
+    reason: string;
+}