@remnic/core 9.3.712 → 9.3.714

package/src/chat/chat-llm.ts

@@ -0,0 +1,229 @@
+/**
+ * LLM adapter for the chat engine (issue #1583).
+ *
+ * The adapter exposes the production {@link ChatLlmAdapter} interface so the
+ * engine is decoupled from the routing chain.  Two implementations:
+ *
+ * - {@link createProductionChatLlmAdapter}: wraps the existing
+ *   FallbackLlmClient / LocalLlmClient routing chain so local Ollama/vLLM
+ *   models are fully supported (gotcha 1).  Memory chat must not require
+ *   cloud.
+ *
+ * - {@link StubChatLlmAdapter}: test-only adapter that drives scripted
+ *   tool-call sequences.  PR 1 tests use this to verify the engine loop,
+ *   confirmation protocol, budget exhaustion, and citation guard without
+ *   real LLM calls.
+ */
+
+import type { ChatLlmAdapter, ChatLlmMessage, ChatLlmResponse, ChatLlmToolCall, ChatToolSchema } from "./chat-types.js";
+
+// ---------------------------------------------------------------------------
+// Minimal LLM-client interface (duck-typed from FallbackLlmClient and
+// LocalLlmClient — both expose chatCompletion returning {content}|null).
+// ---------------------------------------------------------------------------
+
+interface LlmLikeClient {
+  chatCompletion(
+    messages: Array<{ role: string; content: string }>,
+    options?: { model?: string; signal?: AbortSignal; [k: string]: unknown },
+  ): Promise<{ content: string; modelUsed?: string } | null>;
+}
+
+/**
+ * Create a production LLM adapter from an existing routing-chain client
+ * (FallbackLlmClient or LocalLlmClient).
+ *
+ * The adapter maps the chat engine's message format to the client's
+ * chatCompletion signature, injects the tool schema as a system-level
+ * instruction (OpenAI function-calling compat), and parses tool-call requests
+ * from the model's response.
+ */
+export function createProductionChatLlmAdapter(
+  client: LlmLikeClient,
+): ChatLlmAdapter {
+  return {
+    async complete(
+      messages: ChatLlmMessage[],
+      options: { tools: ChatToolSchema[]; model?: string; signal?: AbortSignal },
+    ): Promise<ChatLlmResponse | null> {
+      // Build the tool-calling instruction appended to the system message.
+      const toolInstruction = formatToolInstruction(options.tools);
+      const mapped = messages.map((m) => {
+        if (m.role === "system") {
+          return { role: m.role, content: m.content + "\n\n" + toolInstruction };
+        }
+        // Normalize tool results to a provider-safe role. The underlying
+        // chat-completion clients do not implement native tool-call envelopes,
+        // so a bare role:"tool" (without tool_call_id) is rejected by
+        // OpenAI/Anthropic/Ollama endpoints. Surface the result as a user
+        // message so the follow-up LLM turn always succeeds (P1).
+        if (m.role === "tool") {
+          const tag = m.toolCallId ? `[tool:${m.toolCallId}]` : "[tool]";
+          return { role: "user", content: `${tag} ${m.content}` };
+        }
+        return { role: m.role, content: m.content };
+      });
+      const result = await client.chatCompletion(mapped, {
+        ...(options.model ? { model: options.model } : {}),
+        ...(options.signal ? { signal: options.signal } : {}),
+      });
+      if (!result) return null;
+      const toolCalls = parseToolCalls(result.content);
+      return {
+        content: stripToolCallJson(result.content, toolCalls),
+        toolCalls,
+      };
+    },
+  };
+}
+
+/**
+ * Format the available tools as a function-calling instruction for the LLM.
+ * Models that support native function-calling can ignore this; models that
+ * don't (most local models) use it to emit structured tool calls.
+ */
+function formatToolInstruction(tools: ChatToolSchema[]): string {
+  if (tools.length === 0) return "";
+  const lines = [
+    "## Available tools",
+    "",
+    "You may call the following tools by emitting a JSON block on its own line:",
+    "```json",
+    '{"tool": "<name>", "arguments": { ... }}',
+    "```",
+    "",
+    "Call one tool at a time. After receiving the tool result, continue your",
+    "reasoning or emit another tool call. When you have a final answer, reply",
+    "with text only (no tool-call JSON).",
+    "",
+    "Tools:",
+  ];
+  for (const t of tools) {
+    const params = JSON.stringify(t.function.parameters);
+    lines.push(`- ${t.function.name}: ${t.function.description}`);
+    lines.push(`  Parameters: ${params}`);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Parse a tool-call JSON block from the model's response content.
+ * Tolerates leading/trailing text and code fences.
+ */
+export function parseToolCalls(content: string): ChatLlmToolCall[] {
+  const calls: ChatLlmToolCall[] = [];
+  // Match ```json ... ``` blocks and bare JSON objects with "tool" key.
+  const patterns = [
+    /```json\s*\n([\s\S]*?)\n```/g,
+    /```\s*\n([\s\S]*?)\n```/g,
+  ];
+  const candidates: string[] = [];
+  for (const pattern of patterns) {
+    let match: RegExpExecArray | null;
+    while ((match = pattern.exec(content)) !== null) {
+      candidates.push(match[1]);
+    }
+  }
+  // Also try bare JSON lines.
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("{") && trimmed.includes('"tool"')) {
+      candidates.push(trimmed);
+    }
+  }
+  const seen = new Set<string>();
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate) as { tool?: string; arguments?: Record<string, unknown> };
+      if (typeof parsed.tool === "string" && parsed.tool.length > 0) {
+        const args = parsed.arguments ?? {};
+        // De-duplicate: a fenced block and its inner bare line can both match.
+        const key = parsed.tool + ":" + JSON.stringify(args);
+        if (seen.has(key)) continue;
+        seen.add(key);
+        calls.push({
+          id: `call_${calls.length + 1}`,
+          name: parsed.tool,
+          arguments: args,
+        });
+      }
+    } catch {
+      // Not valid JSON — skip.
+    }
+  }
+  return calls;
+}
+
+/**
+ * Remove tool-call JSON blocks from the content, leaving only prose.
+ */
+function stripToolCallJson(content: string, toolCalls: ChatLlmToolCall[]): string {
+  if (toolCalls.length === 0) return content;
+  let result = content;
+  // Remove fenced blocks.
+  result = result.replace(/```json\s*\n[\s\S]*?\n```/g, "");
+  result = result.replace(/```\s*\n[\s\S]*?\n```/g, "");
+  // Remove bare JSON tool-call lines.
+  result = result
+    .split("\n")
+    .filter((line) => {
+      const trimmed = line.trim();
+      return !(trimmed.startsWith("{") && trimmed.includes('"tool"'));
+    })
+    .join("\n");
+  return result.trim();
+}
+
+// ---------------------------------------------------------------------------
+// Stub adapter — for tests (rule 33: production signature, scripted behaviour)
+// ---------------------------------------------------------------------------
+
+/**
+ * A scripted step in the stub adapter.  Each step is consumed in order for
+ * each LLM call; the last step repeats if the engine loops beyond the
+ * script length.
+ */
+export interface StubLlmStep {
+  content?: string;
+  toolCalls?: Array<{ name: string; arguments: Record<string, unknown> }>;
+}
+
+export class StubChatLlmAdapter implements ChatLlmAdapter {
+  private steps: StubLlmStep[];
+  private callIndex = 0;
+
+  constructor(steps: StubLlmStep[]) {
+    this.steps = steps;
+  }
+
+  async complete(
+    _messages: ChatLlmMessage[],
+    _options: { tools: ChatToolSchema[]; model?: string; signal?: AbortSignal },
+  ): Promise<ChatLlmResponse | null> {
+    const step = this.steps[Math.min(this.callIndex, this.steps.length - 1)];
+    this.callIndex++;
+    const toolCalls: ChatLlmToolCall[] = (step.toolCalls ?? []).map((tc, i) => ({
+      id: `call_${i + 1}`,
+      name: tc.name,
+      arguments: tc.arguments,
+    }));
+    return {
+      content: step.content ?? "",
+      toolCalls,
+    };
+  }
+
+  /** Reset the call index (for test reuse). */
+  reset(): void {
+    this.callIndex = 0;
+  }
+}
+
+/**
+ * A stub adapter that always returns null (simulates LLM outage, rule 13).
+ */
+export class NullChatLlmAdapter implements ChatLlmAdapter {
+  async complete(): Promise<null> {
+    return null;
+  }
+}

package/src/chat/chat-mcp.test.ts

@@ -0,0 +1,135 @@
+/**
+ * Chat MCP surface tests (issue #1583 PR 4).
+ *
+ * Verifies the tools/list parity gate (chat.enabled → memory_chat visible,
+ * byte-identical when off — rule 39) and the memory_chat tool dispatch.
+ */
+
+import { strict as assert } from "node:assert";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import { EngramMcpServer } from "../access-mcp.js";
+import type { EngramAccessService } from "../access-service.js";
+import { parseConfig } from "../config.js";
+import { DEFAULT_CHAT_CONFIG } from "./chat-config.js";
+
+function makeBaseService(overrides: Record<string, unknown> = {}): EngramAccessService {
+  return {
+    briefingEnabled: false,
+    briefing: () => Promise.resolve({ markdown: "", json: {}, sections: {}, window: {} }),
+    recall: () => Promise.resolve({ context: "" }),
+    recallExplain: () => Promise.resolve(null),
+    store: () => Promise.resolve({ id: "x", stored: true }),
+    memoryStore: () => Promise.resolve({ schemaVersion: 1, operation: "memory_store", namespace: "default", dryRun: true, accepted: true, queued: false, status: "validated" }),
+    memoryGet: () => Promise.resolve(null),
+    memoryTimeline: () => Promise.resolve([]),
+    entityGet: () => Promise.resolve(null),
+    reviewQueueList: () => Promise.resolve({ items: [] }),
+    observe: () => Promise.resolve({ ok: true }),
+    ...overrides,
+  } as unknown as EngramAccessService;
+}
+
+function makeListRequest(): Record<string, unknown> {
+  return { jsonrpc: "2.0", id: 1, method: "tools/list", params: {} };
+}
+
+function makeCallRequest(name: string, args: Record<string, unknown>): Record<string, unknown> {
+  return { jsonrpc: "2.0", id: 2, method: "tools/call", params: { name, arguments: args } };
+}
+
+test("MCP tools/list: memory_chat absent when chatVisible is false (byte-identical, rule 39)", async () => {
+  const service = makeBaseService();
+  const server = new EngramMcpServer(service, { chatVisible: false });
+  const response = await server.handleRequest(makeListRequest());
+  const tools = (response as { result?: { tools?: { name: string }[] } }).result?.tools ?? [];
+  const names = tools.map((t) => t.name);
+  assert.ok(!names.includes("engram.memory_chat"), "memory_chat must NOT appear when chat is disabled");
+});
+
+test("MCP tools/list: memory_chat present when chatVisible is true", async () => {
+  const service = makeBaseService();
+  const server = new EngramMcpServer(service, { chatVisible: true });
+  const response = await server.handleRequest(makeListRequest());
+  const tools = (response as { result?: { tools?: { name: string }[] } }).result?.tools ?? [];
+  const names = tools.map((t) => t.name);
+  assert.ok(names.includes("engram.memory_chat"), "memory_chat must appear when chat is enabled");
+});
+
+test("MCP memory_chat: dispatches to processChatMessage and returns a reply", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-"));
+  const llm = {
+    chatCompletion: async () => ({ content: "Your database uses PostgreSQL [id: abc]." }),
+  };
+  const service = makeBaseService({
+    fallbackLlmRef: llm,
+    memoryDir,
+    configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+  });
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  const response = await server.handleRequest(
+    makeCallRequest("engram.memory_chat", { message: "what database?" }),
+  );
+  const result = (response as { result?: { content?: { text?: string }[]; isError?: boolean } }).result;
+  assert.equal(result?.isError, false);
+  const text = result?.content?.[0]?.text ?? "";
+  const parsed = JSON.parse(text) as { reply?: string; chatSessionId?: string };
+  assert.ok(parsed.reply && parsed.reply.length > 0, "reply text must be present");
+  assert.ok(parsed.chatSessionId, "chatSessionId must be returned");
+  await rm(memoryDir, { recursive: true, force: true });
+});
+
+test("MCP memory_chat: rejects empty message with input error", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-err-"));
+  const service = makeBaseService({
+    fallbackLlmRef: { chatCompletion: async () => ({ content: "x" }) },
+    memoryDir,
+    configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+  });
+  const server = new EngramMcpServer(service, { chatVisible: true });
+
+  const response = await server.handleRequest(
+    makeCallRequest("engram.memory_chat", { message: "" }),
+  );
+  const result = (response as { result?: { isError?: boolean; content?: { text?: string }[] } }).result;
+  assert.equal(result?.isError, true, "empty message must surface an input error");
+  await rm(memoryDir, { recursive: true, force: true });
+});
+
+test("MCP memory_chat: strips internal error from structuredContent (Thread 17)", async () => {
+  const memoryDir = await mkdtemp(join(tmpdir(), "chat-mcp-leak-"));
+  // LLM returns null → engine tags the result with error: "no_llm_available".
+  const llm = {
+    chatCompletion: async () => null,
+  };
+  const service = makeBaseService({
+    fallbackLlmRef: llm,
+    memoryDir,
+    configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+  });
+  const server = new EngramMcpServer(service, { chatVisible: true, principal: "alice" });
+
+  const response = await server.handleRequest(
+    makeCallRequest("engram.memory_chat", { message: "what database?" }),
+  );
+  const result = (response as {
+    result?: {
+      content?: { text?: string }[];
+      structuredContent?: Record<string, unknown>;
+      isError?: boolean;
+    };
+  }).result;
+  assert.equal(result?.isError, false, "should not be a JSON-RPC error");
+  // The text content and structuredContent must NOT expose the raw error field.
+  const sc = result?.structuredContent ?? {};
+  assert.ok(!("error" in sc), "structuredContent must not leak the error field");
+  const text = result?.content?.[0]?.text ?? "";
+  const parsed = JSON.parse(text) as Record<string, unknown>;
+  assert.ok(!("error" in parsed), "text content must not leak the error field");
+  assert.ok(typeof parsed.reply === "string", "reply must be present");
+  await rm(memoryDir, { recursive: true, force: true });
+});