@m1khal3v/dsh-tool-codegraph 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anton Mikhalev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+<p align="center">
+  <a href="https://www.npmjs.com/package/@m1khal3v/dsh-tool-codegraph"><img alt="npm" src="https://img.shields.io/npm/v/@m1khal3v/dsh-tool-codegraph?style=flat-square&color=4b6fff"></a>
+  <img alt="DeepSeek Harness" src="https://img.shields.io/badge/deepseek--harness-v0.1.1--rc.1-263146?style=flat-square">
+  <a href="LICENSE"><img alt="MIT License" src="https://img.shields.io/badge/license-MIT-263146?style=flat-square"></a>
+  <img alt="Status" src="https://img.shields.io/badge/status-beta-7da1de?style=flat-square">
+</p>
+
+<h1 align="center">dsh-tool-codegraph</h1>
+<p align="center">
+  <b>CodeGraph navigation tools for <a href="https://github.com/deepseek-ai/deepseek-harness">DeepSeek Harness</a>.</b><br>
+  A DSH plugin that wraps the open-source <a href="https://github.com/colbymchenry/codegraph">codegraph</a> CLI
+  (an AST/tree-sitter code index) into ten focused agent tools — status, search,
+  callers/callees, impact, explore, and more.
+</p>
+
+> **This package is a thin wrapper.** All indexing and querying is done by the
+> [codegraph](https://github.com/colbymchenry/codegraph) CLI — install it first
+> and make sure its binary is on `PATH`.
+
+---
+
+## ⚡️ Highlights
+
+- 🧭 **Orientation-first workflow** — usage rules (`status → sync → explore → targeted lookups`) are injected into the agent system prompt automatically.
+- 🧰 **Ten focused tools**, one per operation — no mega-tool with an `action` parameter.
+- ⚡ **O(1) indexed lookups** — light outputs for the main session, heavy explore builds routed to subagents.
+- ⚠️ **Honest about soundness** — callers/callees/impact can miss dynamic-dispatch edges; the prompt tells the model when to fall back to `grep`.
+
+## 🛠 Requirements
+
+- Node `^22.19 || >=24`
+- The [`codegraph`](https://github.com/colbymchenry/codegraph) CLI available on `PATH` (override via the `executable` config key)
+
+## 🚀 Quick Start
+
+### 1. Install the plugin
+
+```sh
+dsh plugin add @m1khal3v/dsh-tool-codegraph
+```
+
+### 2. Check the wrapped CLI
+
+```sh
+codegraph status
+```
+
+If the binary is missing, the tools reply with an install hint and the agent
+falls back to `bash`/`grep`.
+
+## 🧰 Tools
+
+| Tool | Purpose | Output |
+|---|---|---|
+| `codegraph_status` | Index health and statistics | light |
+| `codegraph_sync` | Sync changes since the last index | long |
+| `codegraph_search` | Find a symbol by name | light |
+| `codegraph_explore` | Map an area with verbatim source and call paths | heavy |
+| `codegraph_callers` | Who calls this symbol (unsound) | light |
+| `codegraph_callees` | What this symbol calls | light |
+| `codegraph_impact` | Blast radius of changing a symbol | light |
+| `codegraph_node` | One symbol's details or a file view | light |
+| `codegraph_files` | Project file structure from the index | light |
+| `codegraph_affected` | Find test files affected by changed source files | light |
+
+## ⚙️ Configuration
+
+| Key | Default | Description |
+|---|---|---|
+| `executable` | `codegraph` | Binary name or path of the wrapped CLI |
+| `queryTimeoutMs` | `10000` | Timeout for regular commands |
+| `initTimeoutMs` | `60000` | Timeout for `init` / `sync` |
+
+## 🧑‍💻 Development
+
+```sh
+pnpm install
+pnpm run verify    # typecheck + test
+pnpm run build
+```
+
+## 📄 License
+
+[MIT](LICENSE)
+
+Built on top of [colbymchenry/codegraph](https://github.com/colbymchenry/codegraph).

package/cordis.patch.yml

@@ -0,0 +1,11 @@
+# @m1khal3v/dsh-tool-codegraph — bundle patch layer.
+#
+# Inserts one plugin row that mounts the CodeGraph tool set. Tools shell out to
+# the local `codegraph` CLI (https://github.com/colbymchenry/codegraph) through
+# ctx.shell; override the binary via the `executable` config key if it is not
+# on PATH.
+- insert:
+    - id: tool-codegraph
+      name: '@m1khal3v/dsh-tool-codegraph'
+      config:
+        executable: codegraph

package/lib/index.d.ts

@@ -0,0 +1,119 @@
+/**
+ * CodeGraph navigation tools for DeepSeek Harness agents.
+ *
+ * The plugin registers ten independent agent tools (`codegraph_status`,
+ * `codegraph_sync`, `codegraph_search`, `codegraph_explore`,
+ * `codegraph_callers`, `codegraph_callees`, `codegraph_impact`,
+ * `codegraph_node`, `codegraph_files`, `codegraph_affected`). Every tool
+ * shells out to the local codegraph CLI (https://github.com/colbymchenry/codegraph)
+ * through `ctx.shell` and renders the result as a terminal call card plus
+ * model-facing text.
+ *
+ * A system-prompt section teaches the model the orientation-first workflow:
+ * status first; a missing index is the user's decision (the model tells the
+ * user to run `codegraph init` and keeps working with bash/grep meanwhile);
+ * sync when stale; then lookups; callers/callees/impact are accelerators, not
+ * exhaustive proofs — exhaustive searches fall back to bash/grep.
+ *
+ * Execution follows the canonical-value flow: `execute` returns the structured
+ * `CodegraphResult` validated against `CODEGRAPH_OUTPUT_SCHEMA`, and the
+ * model-facing text is a pure projection of that value (`output.render`), so
+ * every consumer (model, UI, tests) reads the same canonical fact set.
+ *
+ * No background jobs: codegraph runs synchronously under the caller's
+ * AbortSignal; timeouts come from the plugin config.
+ *
+ * @module @m1khal3v/dsh-tool-codegraph
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { TimeoutKind } from './tools.ts';
+/** Cordis plugin name. */
+export declare const name = "tool-codegraph";
+/** Services the plugin needs on its context. */
+export declare const inject: string[];
+/** Plugin config shape (composition entry config). */
+export interface Config {
+    /** Binary name or path of the codegraph CLI. */
+    executable?: string;
+    /** Timeout for regular (light) commands, ms. */
+    queryTimeoutMs?: number;
+    /** Timeout for index-building commands (sync), ms. */
+    initTimeoutMs?: number;
+}
+export declare const Config: z<Config>;
+/** Config with every default applied. */
+export interface ResolvedConfig {
+    executable: string;
+    queryTimeoutMs: number;
+    initTimeoutMs: number;
+}
+/** Resolve the configured timeout for one tool timeout kind. */
+export declare function resolveTimeout(kind: TimeoutKind, config: ResolvedConfig): number;
+/** Expand a leading `~` and make the path absolute and normalized. */
+export declare function canonicalPath(input: string): string;
+/** Canonical value every codegraph tool returns from `execute`. */
+export interface CodegraphResult {
+    /** Constant discriminant of this package's tool outputs. */
+    kind: 'codegraph';
+    /** Full CLI command line that was run, executable included. */
+    command: string;
+    /** Working directory the command ran in; `null` when the session has no cwd. */
+    workdir: string | null;
+    /** Process exit code; `null` when it never exited (signal kill or spawn failure). */
+    exitCode: number | null;
+    /** Model-facing text for the run (output, markers, or an error envelope). */
+    content: string;
+}
+/**
+ * Output contract validated against every successful `execute` value. The
+ * author-facing `required: true` annotations compile into the object's JSON
+ * Schema `required` list, and the nullable fields are `oneOf` unions — a plain
+ * `type: 'string'` would reject the canonical `null` workdir of a session
+ * without a cwd (and `null` exitCode of a signal-killed run).
+ */
+export declare const CODEGRAPH_OUTPUT_SCHEMA: {
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly properties: {
+        readonly kind: {
+            readonly type: "string";
+            readonly const: "codegraph";
+            readonly required: true;
+        };
+        readonly command: {
+            readonly type: "string";
+            readonly required: true;
+        };
+        readonly workdir: {
+            readonly oneOf: readonly [{
+                readonly type: "string";
+            }, {
+                readonly type: "null";
+            }];
+            readonly required: true;
+        };
+        readonly exitCode: {
+            readonly oneOf: readonly [{
+                readonly type: "integer";
+            }, {
+                readonly type: "null";
+            }];
+            readonly required: true;
+        };
+        readonly content: {
+            readonly type: "string";
+            readonly required: true;
+        };
+    };
+};
+/**
+ * Cordis plugin entry: register the codegraph tools and the system-prompt
+ * section. State lives only in this closure; nothing is registered beyond
+ * `ctx.tools` / `ctx.systemPrompt`, and no background jobs are started.
+ * @param ctx - Cordis context carrying the injected services.
+ * @param config - entry config; cordis applies the schemastery defaults of
+ *   {@link Config} before calling `apply`, so the `?? fallback` reads here are
+ *   a defensive normalization for hosts that bypass it, not the primary path.
+ */
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -0,0 +1,392 @@
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region src/render.ts
+/** Placeholder shown when a truncated stream has no recoverable spill file. */
+const SPILL_UNAVAILABLE = "(unavailable)";
+/** Model text for a successful run that produced no stdout at all. */
+const NO_OUTPUT = "(no output)";
+/**
+* Marker appended when the executor truncated a stream and can name the file
+* holding the complete output. `spillPath` is optional in the real
+* `CollectedOutput`: truncation can occur without a safe spill path, so the
+* marker degrades to an explicit placeholder instead of printing "undefined".
+*/
+const truncationMarker = (output) => {
+	if (!output.truncated) return "";
+	return `\n[output truncated; full output: ${output.spillPath ?? SPILL_UNAVAILABLE}]`;
+};
+/**
+* Terminal call card for one codegraph invocation.
+* @param action - CLI subcommand (first argv token), rendered as `codegraph <action>`.
+* @param description - full CLI command line of the invocation.
+* @param cwd - working directory the command runs in; omit when unknown.
+* @returns the pending-state call card shown to the user.
+*/
+function buildCallCard(action, description, cwd) {
+	return {
+		card: "terminal",
+		title: `codegraph ${action}`,
+		description,
+		cwd
+	};
+}
+/** True when the failure looks like a missing codegraph binary. */
+function detectBinaryNotFound(stderrText, exitCode) {
+	if (exitCode === 127) return true;
+	return /not found|missing|no such file/i.test(stderrText);
+}
+/** True when the failure looks like a missing/uninitialized index. */
+function detectIndexMissing(stderrText) {
+	return /not initialized/i.test(stderrText) || /\.codegraph\b/.test(stderrText);
+}
+/**
+* Model-facing text extracted from a finished shell run. A zero exit code
+* surfaces stdout (stderr is deliberately ignored there); anything else —
+* including a signal kill with a null exit code — surfaces stderr plus
+* actionable recovery markers, each on its own leading-newline line.
+* @param result - completed shell run to summarize.
+* @returns the text handed back to the model for this tool call.
+*/
+function extractModelText(result) {
+	if (result.exitCode === 0) return (result.stdout.text.length > 0 ? result.stdout.text : NO_OUTPUT) + truncationMarker(result.stdout);
+	const stderr = result.stderr.text;
+	let text = stderr;
+	if (detectBinaryNotFound(stderr, result.exitCode ?? 0)) text += "\n[Codegraph executable not found. Please install it or rely on bash/grep.]";
+	if (detectIndexMissing(stderr)) text += "\n[Codegraph error: Index missing. Run codegraph_init first.]";
+	return text;
+}
+//#endregion
+//#region src/tools.ts
+/**
+* POSIX single-quote shell escaping: wraps the value in '…' and replaces every
+* interior single quote with '\'' so the value survives shell joining intact.
+*/
+function quoteArg(value) {
+	return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+/** Type-safe factory erasing the concrete param type into CodegraphToolSpec. */
+function defineSpec(spec) {
+	return {
+		name: spec.name,
+		description: spec.description,
+		parameters: spec.parameters,
+		buildArgs: (params) => spec.buildArgs(params),
+		timeout: spec.timeout
+	};
+}
+/** All codegraph tools in registration order. */
+const codegraphToolSpecs = [
+	defineSpec({
+		name: "codegraph_status",
+		description: "Check index health and statistics. Run this once per session to confirm index freshness before querying.",
+		parameters: {},
+		buildArgs: () => ["status"],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_sync",
+		description: "Sync changes since the last index. Run this if the index is stale.",
+		parameters: {},
+		buildArgs: () => ["sync"],
+		timeout: "init"
+	}),
+	defineSpec({
+		name: "codegraph_search",
+		description: "Find a symbol by name across the codebase (Light output).",
+		parameters: { query: {
+			type: "string",
+			required: true,
+			description: "Symbol name to look up."
+		} },
+		buildArgs: ({ query }) => [
+			"query",
+			quoteArg(query),
+			"--json"
+		],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_explore",
+		description: "PRIMARY tool for orienting. Explores an area by returning verbatim source code of relevant symbols and their call paths grouped by file.",
+		parameters: { query: {
+			type: "string",
+			required: true,
+			description: "Area or question to explore."
+		} },
+		buildArgs: ({ query }) => ["explore", quoteArg(query)],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_callers",
+		description: "Find all functions/methods that call a specific symbol. Unsound (may have false negatives). Do not use for exhaustive completeness.",
+		parameters: { symbol: {
+			type: "string",
+			required: true,
+			description: "Symbol name to look up."
+		} },
+		buildArgs: ({ symbol }) => ["callers", quoteArg(symbol)],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_callees",
+		description: "Find all functions/methods that a specific symbol calls.",
+		parameters: { symbol: {
+			type: "string",
+			required: true,
+			description: "Symbol name to look up."
+		} },
+		buildArgs: ({ symbol }) => ["callees", quoteArg(symbol)],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_impact",
+		description: "Analyze what code is affected by changing a symbol. Pre-rank blast radius before editing. depth is optional (default 2).",
+		parameters: {
+			symbol: {
+				type: "string",
+				required: true,
+				description: "Symbol to change."
+			},
+			depth: {
+				type: "number",
+				description: "Blast-radius depth (default 2); flag added only when provided."
+			}
+		},
+		buildArgs: ({ symbol, depth }) => [
+			"impact",
+			quoteArg(symbol),
+			...depth !== void 0 ? ["--depth", String(depth)] : []
+		],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_node",
+		description: "Get one symbol's details (source + caller/callee trail) or read a file with line numbers + dependents. Good for overloaded names.",
+		parameters: { name: {
+			type: "string",
+			required: true,
+			description: "Symbol name or file path."
+		} },
+		buildArgs: ({ name }) => ["node", quoteArg(name)],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_files",
+		description: "Show project file structure from the index.",
+		parameters: {},
+		buildArgs: () => ["files", "--json"],
+		timeout: "query"
+	}),
+	defineSpec({
+		name: "codegraph_affected",
+		description: "Find test files affected by changed source files.",
+		parameters: { files: {
+			type: "array",
+			required: true,
+			items: { type: "string" },
+			description: "Changed source files whose affected tests to find."
+		} },
+		buildArgs: ({ files }) => ["affected", ...files.map(quoteArg)],
+		timeout: "query"
+	})
+];
+//#endregion
+//#region src/index.ts
+/**
+* CodeGraph navigation tools for DeepSeek Harness agents.
+*
+* The plugin registers ten independent agent tools (`codegraph_status`,
+* `codegraph_sync`, `codegraph_search`, `codegraph_explore`,
+* `codegraph_callers`, `codegraph_callees`, `codegraph_impact`,
+* `codegraph_node`, `codegraph_files`, `codegraph_affected`). Every tool
+* shells out to the local codegraph CLI (https://github.com/colbymchenry/codegraph)
+* through `ctx.shell` and renders the result as a terminal call card plus
+* model-facing text.
+*
+* A system-prompt section teaches the model the orientation-first workflow:
+* status first; a missing index is the user's decision (the model tells the
+* user to run `codegraph init` and keeps working with bash/grep meanwhile);
+* sync when stale; then lookups; callers/callees/impact are accelerators, not
+* exhaustive proofs — exhaustive searches fall back to bash/grep.
+*
+* Execution follows the canonical-value flow: `execute` returns the structured
+* `CodegraphResult` validated against `CODEGRAPH_OUTPUT_SCHEMA`, and the
+* model-facing text is a pure projection of that value (`output.render`), so
+* every consumer (model, UI, tests) reads the same canonical fact set.
+*
+* No background jobs: codegraph runs synchronously under the caller's
+* AbortSignal; timeouts come from the plugin config.
+*
+* @module @m1khal3v/dsh-tool-codegraph
+*/
+/** Cordis plugin name. */
+const name = "tool-codegraph";
+/** Services the plugin needs on its context. */
+const inject = [
+	"shell",
+	"tools",
+	"systemPrompt"
+];
+const Config = z.object({
+	executable: z.string().default("codegraph"),
+	queryTimeoutMs: z.number().default(1e4),
+	initTimeoutMs: z.number().default(6e4)
+});
+/** Resolve the configured timeout for one tool timeout kind. */
+function resolveTimeout(kind, config) {
+	return kind === "init" ? config.initTimeoutMs : config.queryTimeoutMs;
+}
+/** Expand a leading `~` and make the path absolute and normalized. */
+function canonicalPath(input) {
+	const home = homedir();
+	const expanded = input === "~" || input.startsWith("~/") ? join(home, input.slice(1).replace(/^\/+/, "")) : input;
+	return resolve(expanded);
+}
+/** System-prompt section text, verbatim contract of the tool catalog workflow. */
+const CODEGRAPH_PROMPT = `CodeGraph Usage Rules:
+- Workflow: ALWAYS check \`codegraph_status\` once per session first. If the index is missing, do NOT build it yourself — indexing is the user's decision: tell the user to run \`codegraph init\`, and continue with bash/grep meanwhile. If stale, run \`codegraph_sync\`.
+- Orientation: Use \`codegraph_explore\` for mapping architecture or "how X works". Use \`codegraph_callers\` / \`codegraph_callees\` / \`codegraph_node\` for targeted lookups.
+- Subagents: For deep exploration, spawn a subagent and explicitly instruct it to use \`codegraph_explore\` — its verbatim source blocks are heavy, so keep them out of the main session.
+- DO NOT trust callers/callees/impact for completeness! They silently drop unresolved method/generic/trait-dispatch edges.
+- For exhaustive searches (e.g., finding ALL callers before a rename or signature change), you MUST use \`bash\` with \`grep\` or \`rg\`. Codegraph is only an accelerator.
+- Overloaded names: Do not query overloaded names with bare callers/callees. Use \`codegraph_node\` on a specific symbol ID or use grep.`;
+/**
+* Output contract validated against every successful `execute` value. The
+* author-facing `required: true` annotations compile into the object's JSON
+* Schema `required` list, and the nullable fields are `oneOf` unions — a plain
+* `type: 'string'` would reject the canonical `null` workdir of a session
+* without a cwd (and `null` exitCode of a signal-killed run).
+*/
+const CODEGRAPH_OUTPUT_SCHEMA = {
+	type: "object",
+	additionalProperties: false,
+	properties: {
+		kind: {
+			type: "string",
+			const: "codegraph",
+			required: true
+		},
+		command: {
+			type: "string",
+			required: true
+		},
+		workdir: {
+			oneOf: [{ type: "string" }, { type: "null" }],
+			required: true
+		},
+		exitCode: {
+			oneOf: [{ type: "integer" }, { type: "null" }],
+			required: true
+		},
+		content: {
+			type: "string",
+			required: true
+		}
+	}
+};
+/**
+* First content block of a completed tool result, when it is plain text.
+* `presentResult` sees only the durable content projection, and codegraph
+* results always render as a single text block; anything else (future block
+* kinds, empty content) degrades to an empty card output.
+*/
+function textOf(result) {
+	const block = result.content[0];
+	return block !== void 0 && block.type === "text" ? block.text : "";
+}
+/**
+* Exit code carried in a tool result's presentation metadata, when present.
+* `ToolResult.meta` is an opaque `JsonValue`, so the shape is narrowed via
+* `in`/`typeof` with one local cast instead of trusting an untyped payload.
+*/
+function metaExitCode(meta) {
+	if (typeof meta !== "object" || meta === null || !("exitCode" in meta)) return void 0;
+	const value = meta.exitCode;
+	return typeof value === "number" ? value : void 0;
+}
+/**
+* Cordis plugin entry: register the codegraph tools and the system-prompt
+* section. State lives only in this closure; nothing is registered beyond
+* `ctx.tools` / `ctx.systemPrompt`, and no background jobs are started.
+* @param ctx - Cordis context carrying the injected services.
+* @param config - entry config; cordis applies the schemastery defaults of
+*   {@link Config} before calling `apply`, so the `?? fallback` reads here are
+*   a defensive normalization for hosts that bypass it, not the primary path.
+*/
+function apply(ctx, config) {
+	const resolved = {
+		executable: config.executable ?? "codegraph",
+		queryTimeoutMs: config.queryTimeoutMs ?? 1e4,
+		initTimeoutMs: config.initTimeoutMs ?? 6e4
+	};
+	/** Run one codegraph CLI command in the agent session's cwd and project it canonically. */
+	const runCodegraph = async (argv, exec, timeout) => {
+		const sessionCwd = exec.agent?.session.header.cwd;
+		const workdir = sessionCwd === void 0 ? void 0 : canonicalPath(sessionCwd);
+		const cmd = [resolved.executable, ...argv].join(" ");
+		const failure = (cause) => ({
+			kind: "codegraph",
+			command: cmd,
+			workdir: workdir ?? null,
+			exitCode: null,
+			content: `[Codegraph error: ${cause}]`
+		});
+		try {
+			const result = await ctx.shell.run(ctx.shell.resolve({
+				command: cmd,
+				workdir,
+				timeoutMs: timeout,
+				signal: exec.signal
+			}));
+			if (result.aborted) return failure("call aborted");
+			return {
+				kind: "codegraph",
+				command: cmd,
+				workdir: workdir ?? null,
+				exitCode: result.exitCode,
+				content: extractModelText(result)
+			};
+		} catch (error) {
+			return failure(error instanceof Error ? error.message : String(error));
+		}
+	};
+	for (const spec of codegraphToolSpecs) ctx.tools.register(defineTool({
+		name: spec.name,
+		description: spec.description,
+		parameters: spec.parameters,
+		output: {
+			schema: CODEGRAPH_OUTPUT_SCHEMA,
+			render: (_args, value) => [{
+				type: "text",
+				text: value.content
+			}],
+			presentationMeta: (_args, value) => ({
+				command: value.command,
+				workdir: value.workdir,
+				exitCode: value.exitCode
+			})
+		},
+		execute: (args, exec) => runCodegraph(spec.buildArgs(args), exec, resolveTimeout(spec.timeout, resolved)),
+		presentCall: (args) => {
+			const argv = spec.buildArgs(args);
+			return buildCallCard(argv[0] ?? "", [resolved.executable, ...argv].join(" "), void 0);
+		},
+		presentResult: (_args, result) => {
+			const exitCode = metaExitCode(result.meta);
+			return {
+				card: "terminal",
+				output: textOf(result),
+				...exitCode !== void 0 ? { exitCode } : {}
+			};
+		}
+	}));
+	ctx.systemPrompt.section({
+		name: "tool:codegraph",
+		order: 110,
+		text: CODEGRAPH_PROMPT
+	});
+}
+//#endregion
+export { CODEGRAPH_OUTPUT_SCHEMA, Config, apply, canonicalPath, inject, name, resolveTimeout };

package/lib/invariant.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Package-owned invariant companion for `@m1khal3v/dsh-tool-codegraph`.
+ * @module @m1khal3v/dsh-tool-codegraph/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-codegraph-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;

package/lib/invariant.js

@@ -0,0 +1,15 @@
+//#region src/invariant.ts
+const PACKAGE_NAME = "@m1khal3v/dsh-tool-codegraph";
+/** Cordis companion plugin name. */
+const name = "tool-codegraph-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/render.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Result rendering for codegraph tool calls: the terminal call card shown to
+ * the user and the model-facing text with actionable markers (missing binary,
+ * missing index, truncated output). Pure functions only.
+ * @module @m1khal3v/dsh-tool-codegraph/render
+ */
+import type { ShellRunResult } from '@deepseek-ai/dsh-shell';
+import type { TerminalCallView, ToolResultView } from '@deepseek-ai/dsh-tools';
+/**
+ * Terminal call card for one codegraph invocation.
+ * @param action - CLI subcommand (first argv token), rendered as `codegraph <action>`.
+ * @param description - full CLI command line of the invocation.
+ * @param cwd - working directory the command runs in; omit when unknown.
+ * @returns the pending-state call card shown to the user.
+ */
+export declare function buildCallCard(action: string, description: string, cwd: string | undefined): TerminalCallView;
+/** True when the failure looks like a missing codegraph binary. */
+export declare function detectBinaryNotFound(stderrText: string, exitCode: number): boolean;
+/** True when the failure looks like a missing/uninitialized index. */
+export declare function detectIndexMissing(stderrText: string): boolean;
+/**
+ * Model-facing text extracted from a finished shell run. A zero exit code
+ * surfaces stdout (stderr is deliberately ignored there); anything else —
+ * including a signal kill with a null exit code — surfaces stderr plus
+ * actionable recovery markers, each on its own leading-newline line.
+ * @param result - completed shell run to summarize.
+ * @returns the text handed back to the model for this tool call.
+ */
+export declare function extractModelText(result: ShellRunResult): string;
+/**
+ * Full tool result for a finished shell run: the completed terminal card
+ * carrying the model text in `output` (the real `ToolResultView` union has no
+ * `text` field) plus the exit code when the process exited.
+ * @param result - completed shell run.
+ * @param command - full CLI command line of the invocation.
+ * @param workdir - working directory the command ran in; the completed view
+ *   cannot carry it, but the pending title is still derived through the call
+ *   card built from it.
+ * @returns the completed terminal card for the invocation.
+ */
+export declare function renderResult(result: ShellRunResult, command: string, workdir: string | undefined): ToolResultView;
+/**
+ * Tool result for a shell call that threw (timeout/abort/spawn failure): the
+ * run produced no exit status, so the completed card carries only the error
+ * text for the model.
+ * @param command - full CLI command line of the invocation.
+ * @param workdir - working directory the command was meant to run in.
+ * @param cause - short reason string, e.g. `call aborted` on an aborted signal.
+ * @returns the completed terminal card with the `[Codegraph error: …]` text.
+ */
+export declare function renderShellFailure(command: string, workdir: string | undefined, cause: string): ToolResultView;

package/lib/tools.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Catalog of the codegraph agent tools: names, model-facing descriptions,
+ * parameter schemas, CLI argv builders and timeout kinds. Pure data — no
+ * context, no shell. The CLI is the open-source codegraph binary
+ * (https://github.com/colbymchenry/codegraph) wrapped by this plugin.
+ * @module @m1khal3v/dsh-tool-codegraph/tools
+ */
+import type { ParameterSchemaSpec } from '@deepseek-ai/dsh-tools';
+/** Which configured timeout a tool uses (see plugin Config). */
+export type TimeoutKind = 'query' | 'init';
+/**
+ * POSIX single-quote shell escaping: wraps the value in '…' and replaces every
+ * interior single quote with '\'' so the value survives shell joining intact.
+ */
+export declare function quoteArg(value: string): string;
+/** Parameter shapes per tool. */
+export interface SearchParams {
+    query: string;
+}
+export interface ExploreParams {
+    query: string;
+}
+export interface CallersParams {
+    symbol: string;
+}
+export interface CalleesParams {
+    symbol: string;
+}
+export interface ImpactParams {
+    symbol: string;
+    depth?: number;
+}
+export interface NodeParams {
+    name: string;
+}
+export interface AffectedParams {
+    files: string[];
+}
+/** Erased per-tool spec stored in the registry. */
+export interface CodegraphToolSpec {
+    /** Registered tool name, e.g. `codegraph_search`. */
+    readonly name: string;
+    /** Model-facing description (English, verbatim from the catalog table). */
+    readonly description: string;
+    /** dsh-tools parameter schema validating the tool input before buildArgs. */
+    readonly parameters: ParameterSchemaSpec;
+    /** Build CLI argv after the executable; dynamic values are quoteArg-ed. */
+    buildArgs(params: unknown): string[];
+    /** Which configured timeout applies to this tool. */
+    readonly timeout: TimeoutKind;
+}
+/** All codegraph tools in registration order. */
+export declare const codegraphToolSpecs: readonly CodegraphToolSpec[];

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@m1khal3v/dsh-tool-codegraph",
+  "version": "0.0.1",
+  "description": "CodeGraph integration for DeepSeek Harness",
+  "license": "MIT",
+  "author": "m1khal3v",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/m1khal3v/dsh-tool-codegraph.git"
+  },
+  "bugs": {
+    "url": "https://github.com/m1khal3v/dsh-tool-codegraph/issues"
+  },
+  "homepage": "https://github.com/m1khal3v/dsh-tool-codegraph#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./cordis.patch.yml": "./cordis.patch.yml",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/**/*.js",
+    "lib/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": "^22.19 || >=24"
+  },
+  "scripts": {
+    "build": "tsdown && tsc -p tsconfig.types.json",
+    "prepublishOnly": "pnpm run build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "pnpm run typecheck && pnpm run test"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "keywords": [
+    "dsh",
+    "deepseek-harness",
+    "cordis",
+    "codegraph",
+    "tree-sitter",
+    "code-navigation",
+    "tools"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-agent": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-shell": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.1.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@types/node": "^22.0.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.9.0",
+    "vitest": "^2.1.9"
+  }
+}