@remnic/core 9.3.693 → 9.3.695

package/src/access-operations.ts

@@ -29,6 +29,11 @@ import {
   type ArchitectureSurfaceRequest,
   type ArchitectureSurfaceResponse,
 } from "./coding/architecture-surfaces.js";
+import {
+  type CodegraphSurfaceRequest,
+  type CodegraphSurfaceResponse,
+  isCodegraphToolName,
+} from "./coding/codegraph-surfaces.js";
 import {
   DELTA_SUBCOMMANDS,
   type DeltaSurfaceRequest,
@@ -255,6 +260,50 @@ export const codingArchitectureOperation = defineOperation<
   },
 });
 
+const codegraphSurfaceSchema = z.preprocess(
+  (data) => {
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+      const obj = data as Record<string, unknown>;
+      const cleaned: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(obj)) {
+        if (value !== null) cleaned[key] = value;
+      }
+      return cleaned;
+    }
+    return data;
+  },
+  z.object({
+    tool: z.string().refine(isCodegraphToolName, {
+      message: "tool must be one of the codegraph tool names",
+    }),
+    sessionKey: z.string().max(512).optional(),
+    principal: z.string().max(256).optional(),
+    project: z.string().max(256).optional(),
+    query: z.string().max(2048).optional(),
+    limit: z.number().int().positive().max(200).optional(),
+    start: z.string().max(512).optional(),
+    direction: z.string().max(64).optional(),
+    depth: z.number().int().positive().max(10).optional(),
+    qualifiedName: z.string().max(1024).optional(),
+    path: z.string().max(2048).optional(),
+    structuredQuery: z.record(z.string(), z.unknown()).optional(),
+    head: z.string().max(256).optional(),
+    repoRoot: z.string().max(2048).optional(),
+    mode: z.string().max(64).optional(),
+    confirm: z.boolean().optional(),
+    subcommand: z.string().max(64).optional(),
+    id: z.string().max(512).optional(),
+    title: z.string().max(512).optional(),
+    status: z.string().max(64).optional(),
+    context: z.string().max(8192).optional(),
+    decision: z.string().max(8192).optional(),
+    consequences: z.string().max(8192).optional(),
+    entityRefs: z.array(z.string().max(256)).optional(),
+    supersedesId: z.string().max(512).optional(),
+    traces: z.array(z.unknown()).optional(),
+  }),
+) as z.ZodType<CodegraphSurfaceRequest>;
+
 // ---------------------------------------------------------------------------
 // coding_delta — session-delta surface (issue #1548 Track A PR 4)
 // ---------------------------------------------------------------------------
@@ -304,11 +353,221 @@ export const codingDeltaOperation = defineOperation<
  * the boundary owns today. The fitness test treats this set as the migrated
  * set; everything else on a surface is unmigrated and counted by the ratchet.
  */
+export const codegraphIndexOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_index",
+  description:
+    "Codegraph parity tool (issue #1554): index. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphListProjectsOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_list_projects",
+  description:
+    "Codegraph parity tool (issue #1554): list_projects. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphDeleteProjectOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_delete_project",
+  description:
+    "Codegraph parity tool (issue #1554): delete_project. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphIndexStatusOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_index_status",
+  description:
+    "Codegraph parity tool (issue #1554): index_status. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphSearchGraphOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_search_graph",
+  description:
+    "Codegraph parity tool (issue #1554): search_graph. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphTracePathOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_trace_path",
+  description:
+    "Codegraph parity tool (issue #1554): trace_path. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphDetectChangesOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_detect_changes",
+  description:
+    "Codegraph parity tool (issue #1554): detect_changes. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphQueryGraphOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_query_graph",
+  description:
+    "Codegraph parity tool (issue #1554): query_graph. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphGetSchemaOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_get_schema",
+  description:
+    "Codegraph parity tool (issue #1554): get_schema. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphGetSnippetOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_get_snippet",
+  description:
+    "Codegraph parity tool (issue #1554): get_snippet. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphGetArchitectureOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_get_architecture",
+  description:
+    "Codegraph parity tool (issue #1554): get_architecture. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphSearchCodeOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_search_code",
+  description:
+    "Codegraph parity tool (issue #1554): search_code. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphManageAdrOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_manage_adr",
+  description:
+    "Codegraph parity tool (issue #1554): manage_adr. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
+export const codegraphIngestTracesOperation = defineOperation<
+  CodegraphSurfaceRequest,
+  { result: CodegraphSurfaceResponse }
+>({
+  name: "codegraph_ingest_traces",
+  description:
+    "Codegraph parity tool (issue #1554): ingest_traces. Delegates to the shared codegraph surface handler.",
+  schema: codegraphSurfaceSchema,
+  handler: async (input, ctx) => {
+    const result = await ctx.service.codegraphTool(input, ctx.authenticatedPrincipal);
+    return { result };
+  },
+});
+
 export const REGISTERED_OPERATIONS = [
   memoryGetOperation.spec.name,
   memorySearchOperation.spec.name,
   memoryStoreOperation.spec.name,
   codingDecisionOperation.spec.name,
   codingArchitectureOperation.spec.name,
+  codegraphIndexOperation.spec.name,
+  codegraphListProjectsOperation.spec.name,
+  codegraphDeleteProjectOperation.spec.name,
+  codegraphIndexStatusOperation.spec.name,
+  codegraphSearchGraphOperation.spec.name,
+  codegraphTracePathOperation.spec.name,
+  codegraphDetectChangesOperation.spec.name,
+  codegraphQueryGraphOperation.spec.name,
+  codegraphGetSchemaOperation.spec.name,
+  codegraphGetSnippetOperation.spec.name,
+  codegraphGetArchitectureOperation.spec.name,
+  codegraphSearchCodeOperation.spec.name,
+  codegraphManageAdrOperation.spec.name,
+  codegraphIngestTracesOperation.spec.name,
   codingDeltaOperation.spec.name,
 ] as const;

package/src/access-service.ts

@@ -1,6 +1,7 @@
 import { stat } from "node:fs/promises";
 import * as nodeFs from "node:fs/promises";
 import { constants as fsConstants } from "node:fs";
+import { readdirSync, unlinkSync } from "node:fs";
 import { createHash } from "node:crypto";
 import { ZodError } from "zod";
 import { AccessIdempotencyStore, hashAccessIdempotencyPayload } from "./access-idempotency.js";
@@ -28,6 +29,19 @@ import {
   ARCHITECTURE_CARD_TAG,
 } from "./coding/architecture-surfaces.js";
 import { buildArchitectureCard, createArchitectureCardSummariser } from "./coding/architecture-card.js";
+import {
+  handleCodegraphTool,
+  type CodegraphSurfaceContext,
+  type CodegraphSurfaceRequest,
+  type CodegraphSurfaceResponse,
+} from "./coding/codegraph-surfaces.js";
+import {
+  codegraphSurfaceVisible,
+  getCodegraphStore,
+  makeCodegraphRuntimeDelegates,
+  resolveCodegraphProjectId,
+  type CodegraphStore,
+} from "./coding/codegraph-runtime.js";
 import {
   handleCodingDelta,
   type DeltaSurfaceRequest,
@@ -4463,6 +4477,65 @@ export class EngramAccessService {
     };
   }
 
+  /**
+   * Codegraph parity tool delegate (issue #1554). All three surfaces (MCP,
+   * HTTP, CLI) arrive here via the codegraph_* boundary operations. The
+   * handler lives in coding/codegraph-surfaces.ts; this method just wires
+   * the context. Memory dir + principal + coding-context lookup come from
+   * the orchestrator/access-service fabric -- no handler-side state.
+   */
+  async codegraphTool(
+    request: CodegraphSurfaceRequest,
+    authenticatedPrincipal?: string,
+  ): Promise<CodegraphSurfaceResponse> {
+    const principal = authenticatedPrincipal ?? "default";
+    const memoryDir = this.orchestrator.config.memoryDir;
+    const ctx: CodegraphSurfaceContext = {
+      config: this.orchestrator.config,
+      memoryDir,
+      principal,
+      getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk),
+      // Project resolution chokepoint lives in codegraph-runtime.ts so every
+      // store-backed tool derives the same id and the tagged error flows back
+      // as a structured response (issue #1554 threads 7/9/11). Thin wiring.
+      resolveStore: async (req) => {
+        const projectId = resolveCodegraphProjectId({
+          request: req,
+          getCodingContext: (sk) => this.orchestrator.getCodingContextForSession(sk),
+        });
+        return getCodegraphStore({
+          config: this.orchestrator.config,
+          memoryDir,
+          principal,
+          projectId,
+          repoRoot: req.repoRoot,
+        }) as Promise<CodegraphStore>;
+      },
+      listDirs: (dir) => {
+        try {
+          return readdirSync(dir) as readonly string[];
+        } catch {
+          return [];
+        }
+      },
+      removeFile: (filePath) => unlinkSync(filePath), // propagate failures → deleteCodegraphProject classifies (thread 7)
+      throwInputError: (msg) => {
+        throw new EngramAccessInputError(msg);
+      },
+      delegateDecisionRecord: async (decisionRequest) => {
+        return this.codingDecision(decisionRequest, authenticatedPrincipal);
+      },
+      buildArchitectureCard: async (repoRoot) => {
+        return buildArchitectureCard(repoRoot, {
+          llmSummary: this.orchestrator.config.codingKnowledge?.architectureCardLlmSummary === true,
+          summariser: createArchitectureCardSummariser(this.fallbackLlmRef ?? this.localLlmRef),
+        });
+      },
+      ...makeCodegraphRuntimeDelegates(),
+    };
+    return handleCodegraphTool(request, ctx);
+  }
+
   /** Whether the coding_decision tool should appear in tools/list (rule 39). */
   get decisionRecordSurfaceVisible(): boolean {
     return this.orchestrator.config.codingKnowledge?.enabled === true
@@ -4507,6 +4580,15 @@ export class EngramAccessService {
     return this.orchestrator.config.codingKnowledge?.enabled === true
       && this.orchestrator.config.codingKnowledge?.architectureCard === true;
   }
+
+  /**
+   * Whether the 14 codegraph parity tools should appear in tools/list
+   * (rule 39). Config-only -- runtime availability is checked at call time.
+   * When false the tools array is byte-identical to pre-feature.
+   */
+  get codegraphSurfaceVisible(): boolean {
+    return codegraphSurfaceVisible(this.orchestrator.config);
+  }
   /**
    * Thin delegate — handler logic in coding/architecture-surfaces.ts (#1548 PR3).
    * All three surfaces (MCP/HTTP/CLI) arrive here via the boundary operation.

package/src/access-surface-catalog.test.ts

@@ -67,7 +67,7 @@ function shortToolName(advertised: string): string {
 /** Spin up a server with emitLegacyTools=true and read the deduped short names. */
 async function liveMcpToolShortNames(): Promise<ReadonlySet<string>> {
   const stub = { briefingEnabled: true } as unknown as EngramAccessService;
-  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: true, sessionDeltaVisible: true });
+  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: true, codegraphVisible: true, sessionDeltaVisible: true });
   const response = await server.handleRequest({ jsonrpc: "2.0", id: 1, method: "tools/list" });
   const result = (response as { result?: { tools?: Array<{ name: string }> } }).result;
   const names = new Set<string>();

package/src/access-surface-catalog.ts

@@ -74,6 +74,21 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   { tool: "memory_store", operation: "memory_store" },
   { tool: "coding_decision", operation: "coding_decision" },
   { tool: "coding_architecture", operation: "coding_architecture" },
+  // codegraph parity tools (issue #1554)
+  { tool: "codegraph_index", operation: "codegraph_index" },
+  { tool: "codegraph_list_projects", operation: "codegraph_list_projects" },
+  { tool: "codegraph_delete_project", operation: "codegraph_delete_project" },
+  { tool: "codegraph_index_status", operation: "codegraph_index_status" },
+  { tool: "codegraph_search_graph", operation: "codegraph_search_graph" },
+  { tool: "codegraph_trace_path", operation: "codegraph_trace_path" },
+  { tool: "codegraph_detect_changes", operation: "codegraph_detect_changes" },
+  { tool: "codegraph_query_graph", operation: "codegraph_query_graph" },
+  { tool: "codegraph_get_schema", operation: "codegraph_get_schema" },
+  { tool: "codegraph_get_snippet", operation: "codegraph_get_snippet" },
+  { tool: "codegraph_get_architecture", operation: "codegraph_get_architecture" },
+  { tool: "codegraph_search_code", operation: "codegraph_search_code" },
+  { tool: "codegraph_manage_adr", operation: "codegraph_manage_adr" },
+  { tool: "codegraph_ingest_traces", operation: "codegraph_ingest_traces" },
   { tool: "coding_delta", operation: "coding_delta" },
   { tool: "suggestion_submit", operation: null },
   { tool: "entity_get", operation: null },

package/src/cli.ts

@@ -2803,6 +2803,7 @@ export async function runAccessMcpServeCliCommand(
       emitLegacyTools: options.emitLegacyTools,
       codingDecisionVisible: service.decisionRecordSurfaceVisible,
       architectureCardVisible: service.architectureCardSurfaceVisible,
+      codegraphVisible: service.codegraphSurfaceVisible,
       sessionDeltaVisible: service.sessionDeltaSurfaceVisible,
     });
   await server.runStdio(options.stdin ?? process.stdin, options.stdout ?? process.stdout);

package/src/coding/architecture-surfaces.test.ts

@@ -53,6 +53,8 @@ const DEFAULT_CONFIG: CodingKnowledgeConfig = {
   architectureCardLlmSummary: false,
   structuralProvider: "none",
   structuralProviderCommand: "",
+  codegraphTools: false,
+  codegraphDbDir: "",
 };
 
 const CODING_CONTEXT: CodingContext = {