@mxalbert/context-mode 2.0.0

package/build/server.d.ts

@@ -0,0 +1,240 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type SpawnSyncOptions, type SpawnSyncReturns } from "node:child_process";
+import { ContentStore } from "./store.js";
+import { type PlatformId } from "./adapters/types.js";
+export declare const server: McpServer;
+export interface RegisteredCtxTool {
+    name: string;
+    config: Record<string, unknown>;
+    handler: (args: Record<string, unknown>) => Promise<unknown> | unknown;
+}
+export declare const REGISTERED_CTX_TOOLS: RegisteredCtxTool[];
+export declare function shouldSuppressMcpToolsForNativePluginHost(opts?: {
+    embedded?: string;
+    platform?: PlatformId;
+    settings?: Record<string, unknown> | null;
+}): boolean;
+export declare function emitSuppressionDiagnostic(opts?: {
+    platform?: string;
+    write?: (chunk: string) => void;
+}): void;
+/** Test-only: reset the one-shot emission flag so suites can re-exercise. */
+export declare function __resetSuppressionDiagnosticForTests(): void;
+/**
+ * Issue #637 — register an explicit empty `tools/list` handler on the McpServer.
+ *
+ * Background: when `suppressMcpToolsForNativePluginHost` is true, every
+ * `server.registerTool()` call is short-circuited (returns `undefined` above).
+ * The MCP SDK only installs the SDK-default `tools/list` handler when at least
+ * one `registerTool()` reaches `setToolRequestHandlers()` internally
+ * (mcp.js:56-67). Suppressing every registration leaves `tools/list`
+ * unregistered, and the framework's RPC layer answers it with
+ * `-32601 "Method not found"`.
+ *
+ * The reporter of #637 (SquirrelRat) inspected the suppressed child via
+ * `tools/list` and read the JSON-RPC error as "the plugin never registers any
+ * ctx_* tools" — when in fact the plugin DOES register all 11 tools natively
+ * (verified at `src/adapters/opencode/plugin.ts:469` and
+ * `tests/opencode-plugin.test.ts:88`). The misleading -32601 is the seed of
+ * the #637 perception.
+ *
+ * This helper installs an explicit handler that returns `{tools: []}` — a
+ * spec-compliant empty list. Paired with the existing #623 stderr diagnostic,
+ * an operator now sees:
+ *   - wire response: `{tools: []}` (matches expectation, no JSON-RPC error)
+ *   - stderr: `[context-mode] ctx_* tools/list intentionally empty… (#623)`
+ *
+ * Idempotent: throws inside SDK if called twice on the same server because
+ * `assertCanSetRequestHandler` (mcp.js:60) rejects duplicate registrations;
+ * we therefore install the SDK's default tool handlers FIRST (via a no-op
+ * registerTool of a fake tool, immediately removed) only if needed. To keep
+ * the public surface minimal, we just call `server.server.setRequestHandler`
+ * directly — that is the same low-level call used for prompts/resources at
+ * server.ts:259-261 and avoids the SDK guard entirely.
+ *
+ * Exported for test (#637 in-memory regression guard).
+ */
+export declare function registerEmptyToolsListHandler(target?: McpServer): void;
+type ToolContextOverride = {
+    projectDir: string;
+    sessionId?: string;
+};
+export declare function withProjectDirOverride<T>(projectDir: string | ToolContextOverride, fn: () => Promise<T>): Promise<T>;
+export declare function sanitizeSchemaForStrictClients(node: unknown): unknown;
+export declare function installStrictClientSchemaCompat(target?: McpServer): void;
+/**
+ * Build the FK-attribution object passed to every ContentStore.index*() call
+ * in this process. CLAUDE_SESSION_ID is the only MCP-side handle we have on
+ * the current session — eventId stays undefined because MCP tool invocations
+ * are not paired with PostToolUse event rows at index time (the hook fires
+ * AFTER the tool returns). Empty-string fallback inside #insertChunks keeps
+ * legacy unattributed rows readable.
+ */
+export declare function currentAttribution(): {
+    sessionId?: string;
+} | undefined;
+/** v1.0.134 SLICE A: opts injection for testability. Production callers pass nothing. */
+export declare function resolveSessionIdFromSessionDB(opts?: {
+    projectDir?: string;
+    sessionsDir?: string;
+    bypassCache?: boolean;
+}): string | undefined;
+/**
+ * Project directory detection across supported platforms.
+ *
+ * Priority:
+ *   1. Platform-specific env var (set by host IDE before MCP server spawn)
+ *   2. CONTEXT_MODE_PROJECT_DIR (set by start.mjs for ALL platforms — universal)
+ *   3. process.cwd() (last resort)
+ *
+ * CONTEXT_MODE_PROJECT_DIR guarantees correct projectDir even for platforms
+ * that don't set their own env var (Cursor, OpenClaw, Codex, Kiro, Zed).
+ */
+export declare function getProjectDir(): string;
+/**
+ * Parse FTS5 highlight markers to find match positions in the
+ * original (marker-free) text. Returns character offsets into the
+ * stripped content where each matched token begins.
+ */
+export declare function positionsFromHighlight(highlighted: string): number[];
+export declare function extractSnippet(content: string, query: string, maxLen?: number, highlighted?: string): string;
+export type BatchQueryScope = "batch" | "global";
+export declare function formatBatchQueryResults(store: ContentStore, queries: string[], source: string, maxOutput?: number, scope?: BatchQueryScope): string[];
+export interface BatchCommand {
+    label: string;
+    command: string;
+}
+export interface BatchRunResult {
+    outputs: string[];
+    timedOut: boolean;
+}
+export interface BatchRunOptions {
+    /**
+     * Total budget (concurrency=1, shared) or per-command (concurrency>1).
+     * When `undefined`, no server-side timer fires — the MCP host's RPC
+     * timeout governs (Issue #406).
+     */
+    timeout: number | undefined;
+    concurrency: number;
+    nodeOptsPrefix: string;
+    cwd?: string;
+    onFsBytes?: (bytes: number) => void;
+}
+interface BatchExecutor {
+    execute(input: {
+        language: "shell";
+        code: string;
+        timeout: number | undefined;
+        cwd?: string;
+    }): Promise<{
+        stdout: string;
+        timedOut?: boolean;
+    }>;
+}
+export declare function buildBatchNodeOptionsPrefix(shellPath: string, preloadPath: string): string;
+/**
+ * Default execution timeout (ms) applied ONLY under Antigravity CLI (`agy`).
+ * agy does not enforce an MCP RPC timeout, so a ctx_execute with a runaway or
+ * blocking script hangs forever — the host never kills it and the user must
+ * interrupt. Every other host enforces its own RPC timeout, so we keep the
+ * no-server-timer behavior there (Issue #406 — long builds need an unbounded
+ * run). A caller can still pass an explicit `timeout` to override on any host.
+ */
+export declare const AGY_DEFAULT_EXEC_TIMEOUT_MS = 120000;
+export declare function resolveExecTimeout(timeout: number | undefined): number | undefined;
+/**
+ * Execute batch commands. concurrency=1 preserves the legacy serial path
+ * (shared timeout budget + cascading skip-on-timeout). concurrency>1 runs
+ * commands concurrently with at most N in flight; each command receives the
+ * full timeout, output is collated by input index, and per-command timeouts
+ * record `(timed out)` blocks without skipping siblings.
+ */
+export declare function runBatchCommands(commands: BatchCommand[], opts: BatchRunOptions, executor: BatchExecutor): Promise<BatchRunResult>;
+export declare function buildFetchCode(url: string, outputPath: string): string;
+export type ExtractionVerdict = {
+    kind: "ok";
+} | {
+    kind: "shell";
+    textBytes: number;
+    sourceBytes: number;
+    yieldPct: string;
+};
+/**
+ * Decide whether a non-empty extraction is actually a document or a
+ * JavaScript-rendered shell.
+ *
+ * WHY THIS EXISTS. The old guard was `markdown.length === 0`. A canvas app or
+ * SPA serves a few KB of bootstrap HTML whose entire text content is its
+ * <title>; Turndown faithfully renders that to ~20 bytes. Twenty bytes is not
+ * zero, so the fetch was reported as a success and the shell was indexed as if
+ * it were the page. The caller had no way to tell that apart from a genuinely
+ * short document.
+ *
+ * Measured on this exact code path (2026-08, bytes in -> markdown bytes out):
+ *   excalidraw.com            6,862 ->     21   (0.31% yield)  <- shell
+ *   app.diagrams.net          2,759 ->    476   (17.3% yield)   real prose
+ *   nextjs.org              316,151 -> 13,587   (4.30% yield)   real prose
+ *   developers.cloudflare.com 178,627 -> 8,389  (4.70% yield)   real prose
+ *
+ * Neither signal works alone. A ratio alone condemns a small valid page
+ * (`<p>Hello</p>` is 5 bytes of text from 40 of markup and is perfectly fine).
+ * A floor alone condemns a genuinely short document. Requiring BOTH — almost
+ * no text came out AND almost none of what came in survived — isolates the
+ * shell case and leaves every measured real page above untouched.
+ *
+ * Arithmetic only: no pattern matching, no markup sniffing, no word lists.
+ *
+ * The two thresholds live INSIDE the body on purpose. This function is
+ * injected verbatim into the fetch subprocess (see buildFetchCode) so the
+ * subprocess decides "is this a shell?" with the same arithmetic the parent
+ * uses — one definition, two callers. A `const` at module scope would not
+ * survive `.toString()` and the subprocess would throw a ReferenceError.
+ *
+ * @param textBytes   length of the converted text, already trimmed
+ * @param sourceBytes bytes received off the wire pre-conversion; a
+ *                    non-positive value means the subprocess did not report it
+ *                    (older bundle), and with no evidence we never accuse.
+ */
+export declare function classifyExtraction(textBytes: number, sourceBytes: number): ExtractionVerdict;
+/**
+ * Classify an IP address.
+ *   - "block":    always blocked (link-local/IMDS/multicast/reserved/malformed)
+ *   - "private":  loopback or RFC1918 — allowed by default, blocked in strict mode
+ *   - "public":   safe to fetch
+ *
+ * Exported (via the function name) so SSRF tests can exercise the matcher directly.
+ */
+export declare function classifyIp(rawIp: string): "block" | "private" | "public";
+/**
+ * The rung-2 urls the subprocess requested. An unparseable or absent line
+ * yields an empty list, which the refusal reads as "not reported" — it never
+ * claims urls were tried when there is no evidence that they were.
+ */
+export declare function parseLadderTried(raw: string): string[];
+/**
+ * How the ladder's rung ids read in a report. The point of a ladder is that a
+ * reader can see WHICH step paid for this page, so every fetch says so.
+ */
+export declare function describeRung(rung: string): string;
+export type SpawnSyncFn = (cmd: string, args: readonly string[], opts?: SpawnSyncOptions) => SpawnSyncReturns<string | Buffer>;
+export type BrowserOpenResult = {
+    ok: true;
+    method: string;
+} | {
+    ok: false;
+    method: "none";
+    reason: string;
+};
+export type KillResult = {
+    killedPids: string[];
+    attemptedPids: string[];
+    errors: string[];
+};
+export declare function browserOpenArgv(url: string, platform: NodeJS.Platform): readonly {
+    cmd: string;
+    args: readonly string[];
+}[];
+export declare function openBrowserSync(url: string, platform?: NodeJS.Platform, runner?: SpawnSyncFn): BrowserOpenResult;
+export declare function killProcessOnPort(port: number, platform?: NodeJS.Platform, runner?: SpawnSyncFn): KillResult;
+export {};