@vizalice/codegraph 1.5.0

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

@@ -0,0 +1,34 @@
+/**
+ * Server-level instructions emitted in the MCP `initialize` response.
+ *
+ * MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
+ * SDK, …) surface this text in the agent's system prompt automatically,
+ * giving the agent a high-level playbook for the codegraph toolset
+ * before it sees individual tool descriptions.
+ *
+ * Goals when editing this:
+ *   - Lead the agent to codegraph_explore for any structural/flow question
+ *   - Reinforce "explore instead of Read/Grep" for indexed code
+ *   - Anti-patterns (don't re-verify with grep; don't hand-reconstruct flows)
+ *
+ * Keep it tight. The agent reads this every session — long instructions
+ * burn tokens. The DEFAULT MCP surface is `codegraph_explore` ALONE (see
+ * DEFAULT_MCP_TOOLS in tools.ts) — reference only that tool here. The other
+ * tools (node/search/callers/…) stay defined and are re-enablable via
+ * CODEGRAPH_MCP_TOOLS, but they are NOT listed to agents, so don't name them.
+ */
+export declare const SERVER_INSTRUCTIONS = "# Codegraph \u2014 code intelligence over an indexed knowledge graph\n\nCodegraph is a SQLite knowledge graph of every symbol, edge, and file in\nthe workspace \u2014 pre-computed structure you would otherwise re-derive by\nreading files (cached intelligence: thousands of parse/trace decisions you\ndon't pay to re-reason each run). It indexes 30+ languages\n(TypeScript/JavaScript, Python, Go, Rust, Java, C#, C/C++, PHP, Ruby, Swift,\nKotlin, and more) \u2014 don't assume a language here isn't covered. Reads are\nsub-millisecond; the index lags writes by ~1s through the file watcher. Reach for it BEFORE *and* while\nwriting or editing code \u2014 not just for questions: one call returns the\nverbatim source PLUS who calls it and what it affects, so you edit with the\nblast radius in view. More accurate context, in far fewer tokens and\nround-trips than reading files yourself.\n\n## One tool: codegraph_explore \u2014 use it instead of reading files\n\nThere is a single tool, `codegraph_explore`, and it is Read-equivalent. It\ntakes either a natural-language question or a bag of symbol/file names and\nreturns the **verbatim, line-numbered source** of the relevant symbols\ngrouped by file \u2014 the same `<n>\\t<line>` shape `Read` gives you, safe to\n`Edit` from \u2014 PLUS the call path among them (including dynamic-dispatch hops\nlike callbacks, React re-render, and JSX children that grep can't follow) and\na blast-radius summary of what depends on them.\n\nWhether you're answering \"how does X work\" or implementing a change (fixing a\nbug, adding a feature), call `codegraph_explore` before you Read. ONE call\nusually answers the whole question. Codegraph IS the pre-built search index \u2014\nso running your own grep + read loop, or delegating the lookup to a separate\nfile-reading sub-task/agent, repeats work codegraph already did and costs more\nfor the same answer. A direct codegraph answer is typically one to a few\ncalls; a grep/read exploration is dozens.\n\n## How to query\n\n- **Almost any question \u2014 \"how does X work\", architecture, a bug, \"what/where is X\", or surveying an area** \u2192 `codegraph_explore` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.\n- **\"How does X reach/become Y? / the flow / the path from X to Y\"** \u2192 `codegraph_explore`, naming the symbols that span the flow (e.g. `mutateElement renderScene`) \u2014 it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.\n- **Reading or editing a file/symbol you can name** \u2192 put its name or file path in the `codegraph_explore` query \u2014 it returns that current line-numbered source (safe to `Edit` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.\n- **Need more?** Call `codegraph_explore` again with more specific names \u2014 treat the source it returns as already Read.\n\n## Anti-patterns\n\n- **Trust codegraph's results \u2014 don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.\n- **Don't grep or Read first** to find or understand indexed code \u2014 ONE `codegraph_explore` returns the relevant symbols' source together in a single round-trip. Reach for raw `Read`/`Grep` only to confirm a specific detail codegraph didn't cover, or for what codegraph doesn't index (configs, docs).\n- **Don't reconstruct a flow by hand** \u2014 name the endpoints in one `codegraph_explore` and it surfaces the path between them, dynamic-dispatch hops included.\n- **After editing, check the staleness banner.** When a tool response starts with \"\u26A0\uFE0F Some files referenced below were edited since the last index sync\u2026\", the listed files are pending re-index \u2014 Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. A different, rarer banner \u2014 \"\u26A0\uFE0F CodeGraph auto-sync is DISABLED\u2026\" \u2014 means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.\n- **A file flagged \"\u26A0 changed on disk after the last index sync\" drifted from its index** (most common on projects queried via `projectPath`, which have no live watcher). Codegraph never serves a possibly-mis-sliced body from such a file \u2014 it either shows the file's full CURRENT source (trust it as a Read) or omits the source with this flag. When the source was omitted, Read that specific file; line numbers referencing it elsewhere in the response may be shifted until that project's next sync. All unflagged files remain trustworthy.\n\n- **\"Already sent earlier in this conversation\" is a pointer, not a gap.** When a file's section carries that line instead of (or above) its source, an earlier `codegraph_explore` in THIS conversation already returned those exact lines and the file has not changed since \u2014 so the copy already in your context is current and exact. Scroll back to it; don't re-fetch it and don't Read the file. The bytes it freed went into source you have not seen yet, elsewhere in the same response.\n\n## Limitations\n\n- If a tool reports a project isn't indexed (no `.codegraph/`), stop calling codegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision \u2014 mention they can run `codegraph init` if it comes up, but don't run it yourself.\n- Index lags file writes by ~1 second.\n- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.\n- No live correctness validation \u2014 that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.\n";
+/**
+ * Instructions variant sent when the server's own root has NO codegraph index.
+ *
+ * The tools are still exposed (gating tool availability on whether `./` has an
+ * index is the bug behind #964: it breaks monorepos where only sub-projects are
+ * indexed, and a server that started before `codegraph init` never surfaces the
+ * tools afterward). Instead of an "inactive" note, this variant tells the agent
+ * codegraph works **per project**: there's no default project to query, so pass
+ * a `projectPath` to any project that HAS a `.codegraph/`. The full single-
+ * project playbook ({@link SERVER_INSTRUCTIONS}) is sent instead when the root
+ * IS indexed, so the common case stays tight.
+ */
+export declare const SERVER_INSTRUCTIONS_NO_ROOT_INDEX = "# Codegraph \u2014 available (per-project; pass projectPath)\n\nCodegraph is a SQLite knowledge graph of a codebase's symbols, edges, and\nfiles (30+ languages): one `codegraph_explore` call returns the verbatim, line-numbered source\nof the relevant symbols PLUS the call paths between them and a blast-radius\nsummary \u2014 replacing a grep + Read loop with one round-trip.\n\nThis server started somewhere with no `.codegraph/` of its own, so there is no\ndefault project \u2014 but the tools are available and work **per project**:\n\n- To query a project that HAS a `.codegraph/` index (e.g. a service inside a\n  monorepo, or a second repo), pass its path as `projectPath` to\n  `codegraph_explore` (and any other codegraph tool). Codegraph resolves the\n  nearest `.codegraph/` at or above that path and answers from it \u2014 for as many\n  projects as you like in one session.\n- For a project with no `.codegraph/`, use your built-in tools (Read/Grep/Glob)\n  for that project. Indexing is the user's decision \u2014 don't run it yourself, but\n  if it comes up they can run `codegraph init` in a project to enable codegraph\n  there (a new index is picked up live, no restart).\n";
+//# sourceMappingURL=server-instructions.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.d.ts","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,w4LAuD/B,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,iCAAiC,4qCAmB7C,CAAC"}

package/dist/mcp/server-instructions.js

@@ -0,0 +1,111 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = exports.SERVER_INSTRUCTIONS = void 0;
+/**
+ * Server-level instructions emitted in the MCP `initialize` response.
+ *
+ * MCP clients (Claude Code, Cursor, opencode, LangChain, OpenAI Agent
+ * SDK, …) surface this text in the agent's system prompt automatically,
+ * giving the agent a high-level playbook for the codegraph toolset
+ * before it sees individual tool descriptions.
+ *
+ * Goals when editing this:
+ *   - Lead the agent to codegraph_explore for any structural/flow question
+ *   - Reinforce "explore instead of Read/Grep" for indexed code
+ *   - Anti-patterns (don't re-verify with grep; don't hand-reconstruct flows)
+ *
+ * Keep it tight. The agent reads this every session — long instructions
+ * burn tokens. The DEFAULT MCP surface is `codegraph_explore` ALONE (see
+ * DEFAULT_MCP_TOOLS in tools.ts) — reference only that tool here. The other
+ * tools (node/search/callers/…) stay defined and are re-enablable via
+ * CODEGRAPH_MCP_TOOLS, but they are NOT listed to agents, so don't name them.
+ */
+exports.SERVER_INSTRUCTIONS = `# Codegraph — code intelligence over an indexed knowledge graph
+
+Codegraph is a SQLite knowledge graph of every symbol, edge, and file in
+the workspace — pre-computed structure you would otherwise re-derive by
+reading files (cached intelligence: thousands of parse/trace decisions you
+don't pay to re-reason each run). It indexes 30+ languages
+(TypeScript/JavaScript, Python, Go, Rust, Java, C#, C/C++, PHP, Ruby, Swift,
+Kotlin, and more) — don't assume a language here isn't covered. Reads are
+sub-millisecond; the index lags writes by ~1s through the file watcher. Reach for it BEFORE *and* while
+writing or editing code — not just for questions: one call returns the
+verbatim source PLUS who calls it and what it affects, so you edit with the
+blast radius in view. More accurate context, in far fewer tokens and
+round-trips than reading files yourself.
+
+## One tool: codegraph_explore — use it instead of reading files
+
+There is a single tool, \`codegraph_explore\`, and it is Read-equivalent. It
+takes either a natural-language question or a bag of symbol/file names and
+returns the **verbatim, line-numbered source** of the relevant symbols
+grouped by file — the same \`<n>\\t<line>\` shape \`Read\` gives you, safe to
+\`Edit\` from — PLUS the call path among them (including dynamic-dispatch hops
+like callbacks, React re-render, and JSX children that grep can't follow) and
+a blast-radius summary of what depends on them.
+
+Whether you're answering "how does X work" or implementing a change (fixing a
+bug, adding a feature), call \`codegraph_explore\` before you Read. ONE call
+usually answers the whole question. Codegraph IS the pre-built search index —
+so running your own grep + read loop, or delegating the lookup to a separate
+file-reading sub-task/agent, repeats work codegraph already did and costs more
+for the same answer. A direct codegraph answer is typically one to a few
+calls; a grep/read exploration is dozens.
+
+## How to query
+
+- **Almost any question — "how does X work", architecture, a bug, "what/where is X", or surveying an area** → \`codegraph_explore\` with a natural-language question or the relevant names. ONE capped call returns the verbatim source grouped by file; most often the ONLY call you need.
+- **"How does X reach/become Y? / the flow / the path from X to Y"** → \`codegraph_explore\`, naming the symbols that span the flow (e.g. \`mutateElement renderScene\`) — it surfaces the call path among them, riding dynamic-dispatch hops, and returns their source.
+- **Reading or editing a file/symbol you can name** → put its name or file path in the \`codegraph_explore\` query — it returns that current line-numbered source (safe to \`Edit\` from) with the call path and blast radius attached, so you don't Read it separately. For an overloaded name it returns every matching definition's body in one call.
+- **Need more?** Call \`codegraph_explore\` again with more specific names — treat the source it returns as already Read.
+
+## Anti-patterns
+
+- **Trust codegraph's results — don't re-verify them with grep.** They come from a full AST parse; re-checking with grep is slower, less accurate, and wastes context.
+- **Don't grep or Read first** to find or understand indexed code — ONE \`codegraph_explore\` returns the relevant symbols' source together in a single round-trip. Reach for raw \`Read\`/\`Grep\` only to confirm a specific detail codegraph didn't cover, or for what codegraph doesn't index (configs, docs).
+- **Don't reconstruct a flow by hand** — name the endpoints in one \`codegraph_explore\` and it surfaces the path between them, dynamic-dispatch hops included.
+- **After editing, check the staleness banner.** When a tool response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Every file NOT in that banner is fresh, so still trust codegraph. A different, rarer banner — "⚠️ CodeGraph auto-sync is DISABLED…" — means live watching stopped entirely (the whole index is frozen, not just a few files); until it's resolved, Read files directly to confirm anything that may have changed.
+- **A file flagged "⚠ changed on disk after the last index sync" drifted from its index** (most common on projects queried via \`projectPath\`, which have no live watcher). Codegraph never serves a possibly-mis-sliced body from such a file — it either shows the file's full CURRENT source (trust it as a Read) or omits the source with this flag. When the source was omitted, Read that specific file; line numbers referencing it elsewhere in the response may be shifted until that project's next sync. All unflagged files remain trustworthy.
+
+- **"Already sent earlier in this conversation" is a pointer, not a gap.** When a file's section carries that line instead of (or above) its source, an earlier \`codegraph_explore\` in THIS conversation already returned those exact lines and the file has not changed since — so the copy already in your context is current and exact. Scroll back to it; don't re-fetch it and don't Read the file. The bytes it freed went into source you have not seen yet, elsewhere in the same response.
+
+## Limitations
+
+- If a tool reports a project isn't indexed (no \`.codegraph/\`), stop calling codegraph tools for that project for the rest of the session and use your built-in tools there instead. Indexing is the user's decision — mention they can run \`codegraph init\` if it comes up, but don't run it yourself.
+- Index lags file writes by ~1 second.
+- Cross-file resolution is best-effort name matching; ambiguous calls may return multiple candidates.
+- No live correctness validation — that's still the TypeScript compiler / test suite / linter's job. Codegraph supplements those with structural context they don't have.
+`;
+/**
+ * Instructions variant sent when the server's own root has NO codegraph index.
+ *
+ * The tools are still exposed (gating tool availability on whether `./` has an
+ * index is the bug behind #964: it breaks monorepos where only sub-projects are
+ * indexed, and a server that started before `codegraph init` never surfaces the
+ * tools afterward). Instead of an "inactive" note, this variant tells the agent
+ * codegraph works **per project**: there's no default project to query, so pass
+ * a `projectPath` to any project that HAS a `.codegraph/`. The full single-
+ * project playbook ({@link SERVER_INSTRUCTIONS}) is sent instead when the root
+ * IS indexed, so the common case stays tight.
+ */
+exports.SERVER_INSTRUCTIONS_NO_ROOT_INDEX = `# Codegraph — available (per-project; pass projectPath)
+
+Codegraph is a SQLite knowledge graph of a codebase's symbols, edges, and
+files (30+ languages): one \`codegraph_explore\` call returns the verbatim, line-numbered source
+of the relevant symbols PLUS the call paths between them and a blast-radius
+summary — replacing a grep + Read loop with one round-trip.
+
+This server started somewhere with no \`.codegraph/\` of its own, so there is no
+default project — but the tools are available and work **per project**:
+
+- To query a project that HAS a \`.codegraph/\` index (e.g. a service inside a
+  monorepo, or a second repo), pass its path as \`projectPath\` to
+  \`codegraph_explore\` (and any other codegraph tool). Codegraph resolves the
+  nearest \`.codegraph/\` at or above that path and answers from it — for as many
+  projects as you like in one session.
+- For a project with no \`.codegraph/\`, use your built-in tools (Read/Grep/Glob)
+  for that project. Indexing is the user's decision — don't run it yourself, but
+  if it comes up they can run \`codegraph init\` in a project to enable codegraph
+  there (a new index is picked up live, no restart).
+`;
+//# sourceMappingURL=server-instructions.js.map

package/dist/mcp/server-instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server-instructions.js","sourceRoot":"","sources":["../../src/mcp/server-instructions.ts"],"names":[],"mappings":";;;AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACU,QAAA,mBAAmB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDlC,CAAC;AAEF;;;;;;;;;;;GAWG;AACU,QAAA,iCAAiC,GAAG;;;;;;;;;;;;;;;;;;;CAmBhD,CAAC"}

package/dist/mcp/session.d.ts

@@ -0,0 +1,109 @@
+/**
+ * MCP per-connection session — speaks the JSON-RPC protocol (initialize,
+ * tools/list, tools/call) over a single {@link JsonRpcTransport}. It owns
+ * per-client state only (which protocol version the client asked for, whether
+ * it advertised `roots`, the one-shot roots/list latch); the heavyweight
+ * resources (CodeGraph, watcher, ToolHandler) live in the shared
+ * {@link MCPEngine} so daemon mode can collapse N inotify sets / DB handles
+ * to one.
+ *
+ * The state-machine itself mirrors what `MCPServer` used to do inline before
+ * issue #411 split it out — the same regression tests in
+ * `__tests__/mcp-initialize.test.ts` still drive this code path.
+ */
+import { JsonRpcTransport } from './transport';
+import { MCPEngine } from './engine';
+import { ExploreSessionState } from './explore-session-state';
+/**
+ * MCP Server Info — kept on the session because some clients log it. The
+ * version tracks the real package version (was a hard-coded '0.1.0').
+ */
+export declare const SERVER_INFO: {
+    name: string;
+    version: string;
+};
+/**
+ * Instructions for the `initialize` response, with the update-availability
+ * notice appended when one is known (#1243). Exported so the proxy's local
+ * handshake sends the IDENTICAL payload — same convention as SERVER_INFO.
+ * `getUpdateNotice` is a memoized synchronous cache read, so the #172
+ * respond-fast contract holds; when no notice exists the instructions are
+ * byte-identical to the bare constants.
+ *
+ * Test-authoring note: on a machine whose real `~/.codegraph` cache knows a
+ * newer release, spawned servers append the notice — a test asserting exact
+ * instructions equality must set `CODEGRAPH_NO_UPDATE_CHECK=1` in the spawn
+ * env or it will fail only in the weeks after a release ships.
+ */
+export declare function initializeInstructions(base: string, notice?: string | null): string;
+/** MCP Protocol Version (latest the server claims). */
+export declare const PROTOCOL_VERSION = "2024-11-05";
+export interface MCPSessionOptions {
+    /**
+     * Explicit project path from the `--path` CLI flag. When set, the session
+     * will not bother asking the client for `roots/list` — we already know
+     * where the project lives.
+     */
+    explicitProjectPath?: string | null;
+}
+/**
+ * One MCP client's view of the server. Created fresh per stdio launch
+ * (direct mode) or per socket connection (daemon mode).
+ */
+export declare class MCPSession {
+    private transport;
+    private engine;
+    private clientSupportsRoots;
+    /** From the initialize handshake — attributes usage rollups to the agent host. */
+    private clientInfo;
+    private rootsAttempted;
+    private resolvePromise;
+    private explicitProjectPath;
+    /**
+     * What `codegraph_explore` has already returned to THIS client, per project
+     * (CG-17). Owned by the session, not the engine: the daemon shares one engine
+     * (and one ToolHandler, and a pool of worker threads) across every connected
+     * client, so state kept over there would blend two agents' histories and let
+     * one session's calls suppress source the other has never seen. It dies with
+     * the session — a reconnecting client starts clean.
+     */
+    private readonly exploreSession;
+    constructor(transport: JsonRpcTransport, engine: MCPEngine, opts?: MCPSessionOptions);
+    /**
+     * Start handling messages from the transport. Returns immediately — the
+     * session lives for as long as the transport is open.
+     */
+    start(): void;
+    /**
+     * Tear down the session. Does NOT touch the engine (the engine may serve
+     * other sessions) or call `process.exit` (the daemon decides when to exit).
+     */
+    stop(): void;
+    /** Underlying transport — exposed for daemon-side close hooks. */
+    getTransport(): JsonRpcTransport;
+    /**
+     * This session's explore call history (CG-17). Exposed so tests can assert
+     * that two sessions on one daemon keep separate state; nothing in the server
+     * reaches for another session's copy.
+     */
+    getExploreSessionState(): ExploreSessionState;
+    private handleMessage;
+    private handleInitialize;
+    private handleToolsList;
+    private handleToolsCall;
+    /**
+     * Lazy default-project resolution. Three layers:
+     *   1. await the in-flight init kicked off from `handleInitialize` (if any);
+     *   2. if still uninitialized and we never asked the client for its roots,
+     *      do so now (one-shot); fall back to cwd if the client lacks roots;
+     *   3. last-resort: re-walk from the best candidate — picks up projects
+     *      that were `codegraph init`'d *after* the server started.
+     */
+    private retryInitIfNeeded;
+    /**
+     * Ask the client for its workspace root via `roots/list` and open the
+     * first one. Falls back to `process.cwd()` on timeout or empty answer.
+     */
+    private initFromRoots;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/mcp/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/mcp/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,EAAuC,gBAAgB,EAAc,MAAM,aAAa,CAAC;AAChG,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAOrC,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D;;;GAGG;AAGH,eAAO,MAAM,WAAW;;;CAGvB,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,GAAG,IAAwB,GAAG,MAAM,CAMtG;AAED,uDAAuD;AACvD,eAAO,MAAM,gBAAgB,eAAe,CAAC;AAmC7C,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC;AAED;;;GAGG;AACH,qBAAa,UAAU;IAkBnB,OAAO,CAAC,SAAS;IACjB,OAAO,CAAC,MAAM;IAlBhB,OAAO,CAAC,mBAAmB,CAAS;IACpC,kFAAkF;IAClF,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,cAAc,CAA8B;IACpD,OAAO,CAAC,mBAAmB,CAAgB;IAC3C;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA6B;gBAGlD,SAAS,EAAE,gBAAgB,EAC3B,MAAM,EAAE,SAAS,EACzB,IAAI,GAAE,iBAAsB;IAK9B;;;OAGG;IACH,KAAK,IAAI,IAAI;IAIb;;;OAGG;IACH,IAAI,IAAI,IAAI;IAIZ,kEAAkE;IAClE,YAAY,IAAI,gBAAgB;IAIhC;;;;OAIG;IACH,sBAAsB,IAAI,mBAAmB;YAI/B,aAAa;YA0Cb,gBAAgB;YA0DhB,eAAe;YAkBf,eAAe;IAoC7B;;;;;;;OAOG;YACW,iBAAiB;IAyB/B;;;OAGG;YACW,aAAa;CAgB5B"}

package/dist/mcp/session.js

@@ -0,0 +1,375 @@
+"use strict";
+/**
+ * MCP per-connection session — speaks the JSON-RPC protocol (initialize,
+ * tools/list, tools/call) over a single {@link JsonRpcTransport}. It owns
+ * per-client state only (which protocol version the client asked for, whether
+ * it advertised `roots`, the one-shot roots/list latch); the heavyweight
+ * resources (CodeGraph, watcher, ToolHandler) live in the shared
+ * {@link MCPEngine} so daemon mode can collapse N inotify sets / DB handles
+ * to one.
+ *
+ * The state-machine itself mirrors what `MCPServer` used to do inline before
+ * issue #411 split it out — the same regression tests in
+ * `__tests__/mcp-initialize.test.ts` still drive this code path.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MCPSession = exports.PROTOCOL_VERSION = exports.SERVER_INFO = void 0;
+exports.initializeInstructions = initializeInstructions;
+const path = __importStar(require("path"));
+const transport_1 = require("./transport");
+const tools_1 = require("./tools");
+const server_instructions_1 = require("./server-instructions");
+const version_1 = require("./version");
+const directory_1 = require("../directory");
+const telemetry_1 = require("../telemetry");
+const update_check_1 = require("../upgrade/update-check");
+const explore_session_state_1 = require("./explore-session-state");
+/**
+ * MCP Server Info — kept on the session because some clients log it. The
+ * version tracks the real package version (was a hard-coded '0.1.0').
+ */
+// Exported so the proxy can answer `initialize` locally with the IDENTICAL
+// payload the daemon would send — no drift between the two handshake paths.
+exports.SERVER_INFO = {
+    name: 'codegraph',
+    version: version_1.CodeGraphPackageVersion,
+};
+/**
+ * Instructions for the `initialize` response, with the update-availability
+ * notice appended when one is known (#1243). Exported so the proxy's local
+ * handshake sends the IDENTICAL payload — same convention as SERVER_INFO.
+ * `getUpdateNotice` is a memoized synchronous cache read, so the #172
+ * respond-fast contract holds; when no notice exists the instructions are
+ * byte-identical to the bare constants.
+ *
+ * Test-authoring note: on a machine whose real `~/.codegraph` cache knows a
+ * newer release, spawned servers append the notice — a test asserting exact
+ * instructions equality must set `CODEGRAPH_NO_UPDATE_CHECK=1` in the spawn
+ * env or it will fail only in the weeks after a release ships.
+ */
+function initializeInstructions(base, notice = (0, update_check_1.getUpdateNotice)()) {
+    if (!notice)
+        return base;
+    return (`${base}\n\n---\n${notice} This server keeps running the old version until ` +
+        `the user upgrades — mention it when convenient; do not run the upgrade yourself.`);
+}
+/** MCP Protocol Version (latest the server claims). */
+exports.PROTOCOL_VERSION = '2024-11-05';
+/**
+ * How long to wait for the client's `roots/list` response before giving up
+ * and falling back to the process cwd.
+ */
+const ROOTS_LIST_TIMEOUT_MS = 5000;
+/**
+ * Convert a file:// URI to a filesystem path. Handles URL encoding and
+ * Windows drive letter paths.
+ */
+function fileUriToPath(uri) {
+    try {
+        const url = new URL(uri);
+        let filePath = decodeURIComponent(url.pathname);
+        if (process.platform === 'win32' && /^\/[a-zA-Z]:/.test(filePath)) {
+            filePath = filePath.slice(1);
+        }
+        return path.resolve(filePath);
+    }
+    catch {
+        return uri.replace(/^file:\/\/\/?/, '');
+    }
+}
+/** First usable filesystem path from a `roots/list` result, or null. */
+function firstRootPath(result) {
+    if (!result || typeof result !== 'object')
+        return null;
+    const roots = result.roots;
+    if (!Array.isArray(roots) || roots.length === 0)
+        return null;
+    const first = roots[0];
+    if (typeof first?.uri !== 'string')
+        return null;
+    return fileUriToPath(first.uri);
+}
+/**
+ * One MCP client's view of the server. Created fresh per stdio launch
+ * (direct mode) or per socket connection (daemon mode).
+ */
+class MCPSession {
+    transport;
+    engine;
+    clientSupportsRoots = false;
+    /** From the initialize handshake — attributes usage rollups to the agent host. */
+    clientInfo;
+    rootsAttempted = false;
+    resolvePromise = null;
+    explicitProjectPath;
+    /**
+     * What `codegraph_explore` has already returned to THIS client, per project
+     * (CG-17). Owned by the session, not the engine: the daemon shares one engine
+     * (and one ToolHandler, and a pool of worker threads) across every connected
+     * client, so state kept over there would blend two agents' histories and let
+     * one session's calls suppress source the other has never seen. It dies with
+     * the session — a reconnecting client starts clean.
+     */
+    exploreSession = new explore_session_state_1.ExploreSessionState();
+    constructor(transport, engine, opts = {}) {
+        this.transport = transport;
+        this.engine = engine;
+        this.explicitProjectPath = opts.explicitProjectPath ?? null;
+    }
+    /**
+     * Start handling messages from the transport. Returns immediately — the
+     * session lives for as long as the transport is open.
+     */
+    start() {
+        this.transport.start(this.handleMessage.bind(this));
+    }
+    /**
+     * Tear down the session. Does NOT touch the engine (the engine may serve
+     * other sessions) or call `process.exit` (the daemon decides when to exit).
+     */
+    stop() {
+        this.transport.stop();
+    }
+    /** Underlying transport — exposed for daemon-side close hooks. */
+    getTransport() {
+        return this.transport;
+    }
+    /**
+     * This session's explore call history (CG-17). Exposed so tests can assert
+     * that two sessions on one daemon keep separate state; nothing in the server
+     * reaches for another session's copy.
+     */
+    getExploreSessionState() {
+        return this.exploreSession;
+    }
+    async handleMessage(message) {
+        const isRequest = 'id' in message;
+        switch (message.method) {
+            case 'initialize':
+                if (isRequest)
+                    await this.handleInitialize(message);
+                break;
+            case 'initialized':
+                // Notification that client has finished initialization — no action needed.
+                break;
+            case 'tools/list':
+                if (isRequest)
+                    await this.handleToolsList(message);
+                break;
+            case 'tools/call':
+                if (isRequest)
+                    await this.handleToolsCall(message);
+                break;
+            case 'ping':
+                if (isRequest)
+                    this.transport.sendResult(message.id, {});
+                break;
+            case 'resources/list':
+                // We expose no MCP resources, but some clients (opencode, Codex) probe
+                // for them on connect; reply with an empty list instead of a
+                // MethodNotFound error that surfaces as a scary `-32601` log line. (#621)
+                if (isRequest)
+                    this.transport.sendResult(message.id, { resources: [] });
+                break;
+            case 'resources/templates/list':
+                if (isRequest)
+                    this.transport.sendResult(message.id, { resourceTemplates: [] });
+                break;
+            case 'prompts/list':
+                // Likewise — no prompts exposed, but answer the probe cleanly. (#621)
+                if (isRequest)
+                    this.transport.sendResult(message.id, { prompts: [] });
+                break;
+            default:
+                if (isRequest) {
+                    this.transport.sendError(message.id, transport_1.ErrorCodes.MethodNotFound, `Method not found: ${message.method}`);
+                }
+        }
+    }
+    async handleInitialize(request) {
+        const params = request.params;
+        this.clientSupportsRoots = !!params?.capabilities?.roots;
+        if (params?.clientInfo) {
+            this.clientInfo = {
+                name: typeof params.clientInfo.name === 'string' ? params.clientInfo.name : undefined,
+                version: typeof params.clientInfo.version === 'string' ? params.clientInfo.version : undefined,
+            };
+        }
+        // Explicit project signal, strongest first: client-provided rootUri /
+        // workspaceFolders (LSP-style), else the --path the server was launched
+        // with. cwd is NOT used here — we defer it so a roots/list answer can
+        // win over it. See issue #196.
+        let explicitPath = null;
+        if (params?.rootUri) {
+            explicitPath = fileUriToPath(params.rootUri);
+        }
+        else if (params?.workspaceFolders?.[0]?.uri) {
+            explicitPath = fileUriToPath(params.workspaceFolders[0].uri);
+        }
+        else if (this.explicitProjectPath) {
+            explicitPath = this.explicitProjectPath;
+        }
+        // Pick the instructions variant by the root's index state — a cheap
+        // synchronous walk-up (existsSync loop only, no DB open, so the #172
+        // respond-fast contract holds). When the root IS indexed, send the full
+        // single-project playbook. When it ISN'T, send the per-project variant
+        // (tools are still exposed — see handleToolsList): it tells the agent there
+        // is no default project and to pass `projectPath` to any project that has a
+        // `.codegraph/`. Gating tool AVAILABILITY on whether `./` is indexed was the
+        // #964 bug — it broke monorepos (only sub-projects indexed) and never
+        // surfaced the tools after a mid-session `codegraph init`. When no explicit
+        // path is known yet (roots/list dance pending), cwd is the best predictor of
+        // where the default project will resolve.
+        const indexed = (0, directory_1.findNearestCodeGraphRoot)(explicitPath ?? process.cwd()) !== null;
+        // Respond to the handshake BEFORE doing any heavy init — see issue #172.
+        this.transport.sendResult(request.id, {
+            protocolVersion: exports.PROTOCOL_VERSION,
+            capabilities: { tools: {} },
+            serverInfo: exports.SERVER_INFO,
+            instructions: initializeInstructions(indexed ? server_instructions_1.SERVER_INSTRUCTIONS : server_instructions_1.SERVER_INSTRUCTIONS_NO_ROOT_INDEX),
+        });
+        if (explicitPath) {
+            // Kick off engine init in the background. If another session in the
+            // same daemon already opened the project, `ensureInitialized` is a
+            // ~free no-op — N concurrent clients pay exactly one open.
+            this.resolvePromise = this.engine.ensureInitialized(explicitPath);
+        }
+    }
+    async handleToolsList(request) {
+        await this.retryInitIfNeeded();
+        // Always expose the tools — even when the server root has no index. Gating
+        // availability on whether `./` is indexed (the old behavior) breaks the
+        // monorepo case where only sub-projects carry a `.codegraph/` (the agent
+        // saw zero tools and couldn't even reach an indexed sub-project by
+        // `projectPath`), and it hides the tools from a session that started before
+        // the user ran `codegraph init` (most hosts request the list once, so the
+        // freshly-built index never surfaces). #964. The not-indexed case is still
+        // safe: a call against an un-indexed path returns SUCCESS-shaped guidance
+        // ("pass projectPath / run codegraph init"), never `isError`, so it can't
+        // teach the agent to abandon codegraph. `getTools()` returns the default
+        // surface even before a project is open.
+        this.transport.sendResult(request.id, {
+            tools: this.engine.getToolHandler().getTools(),
+        });
+    }
+    async handleToolsCall(request) {
+        const params = request.params;
+        if (!params || !params.name) {
+            this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, 'Missing tool name');
+            return;
+        }
+        const toolName = params.name;
+        const toolArgs = params.arguments || {};
+        const tool = tools_1.tools.find((t) => t.name === toolName);
+        if (!tool) {
+            this.transport.sendError(request.id, transport_1.ErrorCodes.InvalidParams, `Unknown tool: ${toolName}`);
+            return;
+        }
+        if (process.env.CODEGRAPH_MCP_DEBUG)
+            process.stderr.write(`[mcp-debug] toolsCall ${toolName} id=${String(request.id)} pre-init\n`);
+        await this.retryInitIfNeeded();
+        if (process.env.CODEGRAPH_MCP_DEBUG)
+            process.stderr.write(`[mcp-debug] toolsCall ${toolName} id=${String(request.id)} dispatch\n`);
+        const result = await this.engine.getToolHandler().execute(toolName, toolArgs, this.exploreSession);
+        if (process.env.CODEGRAPH_MCP_DEBUG)
+            process.stderr.write(`[mcp-debug] toolsCall ${toolName} id=${String(request.id)} done\n`);
+        this.transport.sendResult(request.id, result);
+        // After the reply is on the wire — telemetry must never delay a tool
+        // response (in-memory increment only; see src/telemetry).
+        (0, telemetry_1.getTelemetry)().recordUsage('mcp_tool', toolName, !result.isError, this.clientInfo);
+    }
+    /**
+     * Lazy default-project resolution. Three layers:
+     *   1. await the in-flight init kicked off from `handleInitialize` (if any);
+     *   2. if still uninitialized and we never asked the client for its roots,
+     *      do so now (one-shot); fall back to cwd if the client lacks roots;
+     *   3. last-resort: re-walk from the best candidate — picks up projects
+     *      that were `codegraph init`'d *after* the server started.
+     */
+    async retryInitIfNeeded() {
+        if (this.resolvePromise) {
+            try {
+                await this.resolvePromise;
+            }
+            catch { /* fall through to retry */ }
+            this.resolvePromise = null;
+        }
+        if (this.engine.hasDefaultCodeGraph())
+            return;
+        const hint = this.explicitProjectPath ?? this.engine.getProjectPath();
+        if (!hint && !this.rootsAttempted) {
+            this.rootsAttempted = true;
+            this.resolvePromise = this.clientSupportsRoots
+                ? this.initFromRoots()
+                : this.engine.ensureInitialized(process.cwd());
+            try {
+                await this.resolvePromise;
+            }
+            catch { /* fall through */ }
+            this.resolvePromise = null;
+            if (this.engine.hasDefaultCodeGraph())
+                return;
+        }
+        // Last resort: walk from the best candidate (sync open). Picks up
+        // projects that appeared after the server started.
+        const candidate = hint ?? process.cwd();
+        this.engine.retryInitializeSync(candidate);
+    }
+    /**
+     * Ask the client for its workspace root via `roots/list` and open the
+     * first one. Falls back to `process.cwd()` on timeout or empty answer.
+     */
+    async initFromRoots() {
+        let target = process.cwd();
+        try {
+            const result = await this.transport.request('roots/list', undefined, ROOTS_LIST_TIMEOUT_MS);
+            const rootPath = firstRootPath(result);
+            if (rootPath) {
+                target = rootPath;
+            }
+            else {
+                process.stderr.write('[CodeGraph MCP] Client returned no workspace roots; falling back to process cwd.\n');
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            process.stderr.write(`[CodeGraph MCP] roots/list request failed (${msg}); falling back to process cwd.\n`);
+        }
+        await this.engine.ensureInitialized(target);
+    }
+}
+exports.MCPSession = MCPSession;
+//# sourceMappingURL=session.js.map