@remnic/core 9.3.712 → 9.3.714

package/src/chat/chat-factory.ts

@@ -0,0 +1,161 @@
+/**
+ * Chat engine factory + message processor (issue #1583).
+ *
+ * Wires the LLM adapter, executor, and engine from config + access-service.
+ * Used by all three surfaces (CLI, HTTP, MCP) so they share identical
+ * engine construction and session lifecycle.
+ */
+
+import type { EngramAccessService } from "../access-service.js";
+import type { FallbackLlmClient } from "../fallback-llm.js";
+import type { LocalLlmClient } from "../local-llm.js";
+import type { ChatConfig, ChatTurnResult } from "./chat-types.js";
+import { ChatEngine } from "./chat-engine.js";
+import { createProductionChatLlmAdapter } from "./chat-llm.js";
+import { createChatExecutor } from "./chat-executor.js";
+import {
+  createChatSession,
+  loadChatSession,
+  appendTranscriptEntry,
+  sessionBelongsToPrincipal,
+  markPendingPlan,
+  markPlanResolved,
+  markPendingPromotion,
+  markPromotionResolved,
+} from "./chat-session.js";
+
+export interface ChatEngineFactoryOptions {
+  service: EngramAccessService;
+  config: ChatConfig;
+  fallbackLlm: FallbackLlmClient | null;
+  localLlm: LocalLlmClient | null;
+  principal?: string;
+  namespace?: string;
+  sessionKey?: string;
+}
+
+/**
+ * Create a {@link ChatEngine} from the factory options.  Returns `null` when
+ * no LLM client is available.  The engine uses the fallback LLM chain first
+ * (cloud/gateway), then the local LLM chain — both fully supported (gotcha 1).
+ */
+export function createChatEngine(opts: ChatEngineFactoryOptions): ChatEngine | null {
+  const llmClient = opts.fallbackLlm ?? opts.localLlm;
+  if (!llmClient) return null;
+
+  const adapter = createProductionChatLlmAdapter(llmClient as {
+    chatCompletion(
+      messages: Array<{ role: string; content: string }>,
+      options?: { model?: string; signal?: AbortSignal },
+    ): Promise<{ content: string } | null>;
+  });
+
+  const executor = createChatExecutor({
+    service: opts.service,
+    principal: opts.principal,
+    namespace: opts.namespace,
+    sessionKey: opts.sessionKey,
+  });
+
+  return new ChatEngine({
+    llm: adapter,
+    executor,
+    maxToolCallsPerTurn: opts.config.maxToolCallsPerTurn,
+    ...(opts.config.model ? { model: opts.config.model } : {}),
+    correctionAvailable: false,
+    scopeInspectAvailable: false,
+  });
+}
+
+/**
+ * Process a single chat message end-to-end.  Shared by MCP and HTTP surfaces
+ * so session lifecycle, transcript persistence, and error handling are
+ * identical across transports.
+ *
+ * Throws when chat is disabled or no LLM is available.
+ */
+export async function processChatMessage(opts: {
+  service: EngramAccessService;
+  config: ChatConfig | undefined;
+  memoryDir: string;
+  message: string;
+  chatSessionId?: string;
+  principal?: string;
+  /** Namespace/sessionKey forwarded from the MCP request scope (Thread 17). */
+  namespace?: string;
+  sessionKey?: string;
+}): Promise<ChatTurnResult> {
+  if (!opts.config?.enabled) {
+    throw new Error("chat_disabled");
+  }
+  if (!opts.service.fallbackLlmRef && !opts.service.localLlmRef) {
+    throw new Error("no_llm_available");
+  }
+
+  // Load or create the session FIRST so the engine inherits the session's
+  // namespace/sessionKey scope (rule 42 — every tool call flows with that
+  // identity; the executor must not use a different scope than the session).
+  let session;
+  if (opts.chatSessionId) {
+    session = await loadChatSession(opts.memoryDir, opts.chatSessionId);
+    if (!session) throw new Error("chat_session_not_found");
+    if (!sessionBelongsToPrincipal(session, opts.principal)) {
+      throw new Error("access_denied");
+    }
+  } else {
+    session = await createChatSession(opts.memoryDir, {
+      principal: opts.principal,
+      ...(opts.namespace ? { namespace: opts.namespace } : {}),
+      ...(opts.sessionKey ? { sessionKey: opts.sessionKey } : {}),
+    });
+  }
+
+  const engine = createChatEngine({
+    service: opts.service,
+    config: opts.config as ChatConfig,
+    fallbackLlm: opts.service.fallbackLlmRef,
+    localLlm: opts.service.localLlmRef,
+    principal: opts.principal,
+    ...(session.namespace ? { namespace: session.namespace } : {}),
+    ...(session.sessionKey ? { sessionKey: session.sessionKey } : {}),
+  });
+  if (!engine) {
+    throw new Error("engine_unavailable");
+  }
+
+  await appendTranscriptEntry(opts.memoryDir, session.id, {
+    role: "user",
+    content: opts.message,
+  });
+
+  // Snapshot pending state BEFORE the turn so we only persist a marker when
+  // state actually changed (Thread 15 — a normal turn must not clear an
+  // active pending plan/promotion from an earlier turn).
+  const priorPendingPlanId = session.pendingPlanId;
+  const priorPendingPromotionId = session.pendingPromotionId;
+
+  const result = await engine.processMessage(opts.message, session);
+
+  await appendTranscriptEntry(opts.memoryDir, session.id, {
+    role: "assistant",
+    content: result.reply,
+  });
+
+  // Persist pending-plan/promotion state so a later turn can confirm it
+  // (append-only — loadChatSession scans for the latest unresolved marker).
+  if (result.pendingPlan?.planId) {
+    await markPendingPlan(opts.memoryDir, session.id, result.pendingPlan.planId);
+  } else if (session.pendingPromotionId && !priorPendingPromotionId) {
+    // A promotion just became pending this turn.
+    await markPendingPromotion(opts.memoryDir, session.id, session.pendingPromotionId);
+  } else if (priorPendingPlanId && !session.pendingPlanId) {
+    // A pending plan was consumed (applied) this turn.
+    await markPlanResolved(opts.memoryDir, session.id, priorPendingPlanId);
+  } else if (priorPendingPromotionId && !session.pendingPromotionId) {
+    // A pending promotion was consumed (applied) this turn.
+    await markPromotionResolved(opts.memoryDir, session.id, priorPendingPromotionId);
+  }
+  // else: no pending-state change this turn — do NOT append a marker.
+
+  return result;
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Chat HTTP surface tests (issue #1583 PR 3).
+ *
+ * Contract tests for handleChatMessage (POST /engram/v1/chat/message) and
+ * handleChatEventsSSE (GET /engram/v1/chat/events/:id). Auth/isolation,
+ * chat-disabled gate, input validation, and the happy path are all covered
+ * against in-process mock req/res objects — no port binding.
+ */
+
+import { strict as assert } from "node:assert";
+import { EventEmitter } from "node:events";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import type { EngramAccessService } from "../access-service.js";
+import { parseConfig } from "../config.js";
+import { handleChatMessage, handleChatEventsSSE } from "./chat-http.js";
+import { createChatSession, appendTranscriptEntry, chatSessionFile } from "./chat-session.js";
+import { DEFAULT_CHAT_CONFIG } from "./chat-config.js";
+
+// Minimal mock res capturing writes. All tracking fields live on one
+// object the methods mutate (no spread copy — primitives would freeze at 0).
+interface MockRes {
+  emitter: EventEmitter;
+  status: number;
+  headers: Record<string, string>;
+  body: string;
+  writeHead: (s: number, h?: Record<string, string>) => void;
+  write: (c: string) => void;
+  end: (c?: string) => void;
+}
+function mockRes(): MockRes {
+  const m: MockRes = {
+    emitter: new EventEmitter(),
+    status: 0,
+    headers: {},
+    body: "",
+    writeHead(status: number, headers?: Record<string, string>) { m.status = status; if (headers) m.headers = headers; },
+    write(chunk: string) { m.body += chunk; },
+    end(chunk?: string) { if (chunk) m.body += chunk; m.emitter.emit("done"); },
+  };
+  return m;
+}
+
+function mockReq(): EventEmitter {
+  return new EventEmitter();
+}
+
+function makeService(overrides: Partial<EngramAccessService> = {}): EngramAccessService {
+  return {
+    fallbackLlmRef: { chatCompletion: async () => ({ content: "stub reply" }) },
+    configRef: parseConfig({ memoryDir: "/tmp/chat-http-test", chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    memoryDir: "/tmp/chat-http-test",
+    memoryGet: () => Promise.resolve(null),
+    memoryTimeline: () => Promise.resolve([]),
+    memorySearch: () => Promise.resolve({ results: [], count: 0 }),
+    recallExplain: () => Promise.resolve(null),
+    entityGet: () => Promise.resolve(null),
+    memoryProfile: () => Promise.resolve({}),
+    memoryEntitiesList: () => Promise.resolve({ items: [] }),
+    memoryQuestions: () => Promise.resolve({ items: [] }),
+    reviewQueue: () => Promise.resolve({ items: [] }),
+    ...overrides,
+  } as unknown as EngramAccessService;
+}
+
+async function withTempDir<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), "chat-http-"));
+  try { return await fn(dir); } finally { await rm(dir, { recursive: true, force: true }); }
+}
+
+test("HTTP chat/message: 404 when chat is disabled", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: false } }),
+      memoryDir,
+    });
+    const m = mockRes();
+    await handleChatMessage(mockReq() as never, m as never, { message: "hi" }, { service, config: service.configRef!.chat, memoryDir });
+    assert.equal(m.status, 404);
+    assert.ok(m.body.includes("chat_disabled"));
+  });
+});
+
+test("HTTP chat/message: 400 when message is missing", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({ memoryDir, configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }) });
+    const m = mockRes();
+    await handleChatMessage(mockReq() as never, m as never, {}, { service, config: service.configRef!.chat, memoryDir });
+    assert.equal(m.status, 400);
+    assert.ok(m.body.includes("required"));
+  });
+});
+
+test("HTTP chat/message: 503 when no LLM is available", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      fallbackLlmRef: null,
+      localLlmRef: null,
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const m = mockRes();
+    await handleChatMessage(mockReq() as never, m as never, { message: "hi" }, { service, config: service.configRef!.chat, memoryDir });
+    assert.equal(m.status, 503);
+    assert.ok(m.body.includes("no_llm"));
+  });
+});
+
+test("HTTP chat/message: 200 happy path returns reply + chatSessionId", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const m = mockRes();
+    await handleChatMessage(mockReq() as never, m as never, { message: "hello" }, { service, config: service.configRef!.chat, memoryDir });
+    assert.equal(m.status, 200);
+    const parsed = JSON.parse(m.body) as { reply?: string; chatSessionId?: string };
+    assert.ok(parsed.reply && parsed.reply.length > 0);
+    assert.ok(parsed.chatSessionId);
+  });
+});
+
+test("HTTP chat/message: 403 when resuming a session owned by another principal", async () => {
+  await withTempDir(async (memoryDir) => {
+    const session = await createChatSession(memoryDir, { principal: "alice" });
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const m = mockRes();
+    await handleChatMessage(
+      mockReq() as never, m as never,
+      { message: "hi", chatSessionId: session.id },
+      { service, config: service.configRef!.chat, memoryDir },
+      "bob",
+    );
+    assert.equal(m.status, 403);
+    assert.ok(m.body.includes("access_denied"));
+  });
+});
+
+test("HTTP chat/message: 404 when resuming a non-existent session", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const m = mockRes();
+    await handleChatMessage(
+      mockReq() as never, m as never,
+      { message: "hi", chatSessionId: "does-not-exist" },
+      { service, config: service.configRef!.chat, memoryDir },
+    );
+    assert.equal(m.status, 404);
+    assert.ok(m.body.includes("chat_session_not_found"));
+  });
+});
+
+test("HTTP chat/events SSE: streams transcript entries", async () => {
+  await withTempDir(async (memoryDir) => {
+    const session = await createChatSession(memoryDir, { principal: "alice" });
+    await appendTranscriptEntry(memoryDir, session.id, { role: "user", content: "hello" });
+    await appendTranscriptEntry(memoryDir, session.id, { role: "assistant", content: "world" });
+
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const m = mockRes();
+    const req = mockReq();
+    await handleChatEventsSSE(req as never, m as never, session.id, { service, config: service.configRef!.chat, memoryDir }, "alice");
+    assert.equal(m.status, 200);
+    assert.equal(m.headers["content-type"], "text/event-stream");
+    // The system header + user + assistant = 3 data frames.
+    const frames = m.body.split("\n\n").filter((f) => f.startsWith("data:"));
+    assert.ok(frames.length >= 3, `expected >=3 SSE frames, got ${frames.length}`);
+    // Close the request to stop the heartbeat.
+    req.emit("close");
+  });
+});
+
+test("HTTP chat/events SSE: 403 for a session owned by another principal", async () => {
+  await withTempDir(async (memoryDir) => {
+    const session = await createChatSession(memoryDir, { principal: "alice" });
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const m = mockRes();
+    await handleChatEventsSSE(mockReq() as never, m as never, session.id, { service, config: service.configRef!.chat, memoryDir }, "bob");
+    assert.equal(m.status, 403);
+  });
+});

package/src/chat/chat-http.ts

@@ -0,0 +1,222 @@
+/**
+ * Chat HTTP handler (issue #1583 PR 3).
+ *
+ * Implements the HTTP backend for the admin console Chat pane:
+ * - POST /engram/v1/chat/message — send a message, get a reply
+ * - GET  /engram/v1/chat/events/:chatSessionId — SSE stream for replies
+ *
+ * Auth: same Bearer token as every other admin endpoint (loopback bearer).
+ * Per-session isolation: every request verifies the session's principal
+ * matches the caller (rule 42/47).
+ *
+ * This module is imported by access-http.ts with thin route registration —
+ * the god-file ratchet (#1520) tracks access-http.ts LOC.
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { EngramAccessService } from "../access-service.js";
+import type { ChatConfig } from "./chat-types.js";
+import type { ChatTurnResult } from "./chat-types.js";
+import { ChatEngine } from "./chat-engine.js";
+import { isConfirmationMessage } from "./chat-engine.js";
+import { createProductionChatLlmAdapter } from "./chat-llm.js";
+import { createChatExecutor } from "./chat-executor.js";
+import {
+  createChatSession,
+  loadChatSession,
+  appendTranscriptEntry,
+  sessionBelongsToPrincipal,
+  markPendingPlan,
+  markPlanResolved,
+  markPendingPromotion,
+  markPromotionResolved,
+} from "./chat-session.js";
+
+export interface ChatHttpHandlerOptions {
+  service: EngramAccessService;
+  config: ChatConfig | undefined;
+  memoryDir: string;
+}
+
+/**
+ * Handle POST /engram/v1/chat/message.
+ *
+ * Body: `{ message: string, chatSessionId?: string }`
+ * Response: `{ reply: string, chatSessionId: string, pendingPlan?: {...} }`
+ */
+export async function handleChatMessage(
+  req: IncomingMessage,
+  res: ServerResponse,
+  body: Record<string, unknown>,
+  opts: ChatHttpHandlerOptions,
+  principal?: string,
+): Promise<void> {
+  if (!opts.config?.enabled) {
+    respondJson(res, 404, { error: "chat_disabled", code: "chat_disabled" });
+    return;
+  }
+
+  const message = typeof body.message === "string" ? body.message : "";
+  if (!message) {
+    respondJson(res, 400, { error: "message is required", code: "input_error" });
+    return;
+  }
+
+  const llm = opts.service.fallbackLlmRef ?? opts.service.localLlmRef;
+  if (!llm) {
+    respondJson(res, 503, {
+      error: "No LLM model is available. Configure a local or cloud model.",
+      code: "no_llm",
+    });
+    return;
+  }
+
+  const adapter = createProductionChatLlmAdapter(llm as {
+    chatCompletion(
+      messages: Array<{ role: string; content: string }>,
+      options?: { model?: string; signal?: AbortSignal },
+    ): Promise<{ content: string } | null>;
+  });
+
+  // Load or create session.
+  const requestedSessionId = typeof body.chatSessionId === "string" ? body.chatSessionId : undefined;
+  let session;
+  if (requestedSessionId) {
+    session = await loadChatSession(opts.memoryDir, requestedSessionId);
+    if (!session) {
+      respondJson(res, 404, { error: "chat_session_not_found", code: "chat_session_not_found" });
+      return;
+    }
+    if (!sessionBelongsToPrincipal(session, principal)) {
+      respondJson(res, 403, { error: "access_denied", code: "access_denied" });
+      return;
+    }
+  } else {
+    session = await createChatSession(opts.memoryDir, { principal });
+  }
+
+  const executor = createChatExecutor({
+    service: opts.service,
+    principal,
+    ...(session.namespace ? { namespace: session.namespace } : {}),
+    ...(session.sessionKey ? { sessionKey: session.sessionKey } : {}),
+  });
+
+  const engine = new ChatEngine({
+    llm: adapter,
+    executor,
+    maxToolCallsPerTurn: opts.config.maxToolCallsPerTurn,
+    ...(opts.config.model ? { model: opts.config.model } : {}),
+    correctionAvailable: false,
+    scopeInspectAvailable: false,
+  });
+
+  await appendTranscriptEntry(opts.memoryDir, session.id, {
+    role: "user",
+    content: message,
+  });
+
+  // Snapshot pending state BEFORE the turn so we only persist a marker when
+  // state actually changed (Thread 15 — a normal turn must not clear an
+  // active pending plan/promotion from an earlier turn).
+  const priorPendingPlanId = session.pendingPlanId;
+  const priorPendingPromotionId = session.pendingPromotionId;
+
+  const result: ChatTurnResult = await engine.processMessage(message, session);
+
+  await appendTranscriptEntry(opts.memoryDir, session.id, {
+    role: "assistant",
+    content: result.reply,
+  });
+
+  // Persist pending-plan/promotion state (append-only markers). Only append
+  // when state actually changed.
+  if (result.pendingPlan?.planId) {
+    await markPendingPlan(opts.memoryDir, session.id, result.pendingPlan.planId);
+  } else if (session.pendingPromotionId && !priorPendingPromotionId) {
+    await markPendingPromotion(opts.memoryDir, session.id, session.pendingPromotionId);
+  } else if (priorPendingPlanId && !session.pendingPlanId && !result.error) {
+    await markPlanResolved(opts.memoryDir, session.id, priorPendingPlanId);
+  } else if (priorPendingPromotionId && !session.pendingPromotionId && !result.error) {
+    await markPromotionResolved(opts.memoryDir, session.id, priorPendingPromotionId);
+  }
+
+  // Strip internal error details from the wire response (CodeQL — no stack
+  // traces or internal messages leak to the client; keep only the tagged reply).
+  const wireResult = result.error
+    ? { reply: result.reply, chatSessionId: result.chatSessionId, ...(result.pendingPlan ? { pendingPlan: result.pendingPlan } : {}) }
+    : result;
+  respondJson(res, 200, wireResult);
+}
+
+/**
+ * Handle GET /engram/v1/chat/events/:chatSessionId.
+ *
+ * SSE stream.  Sends a heartbeat every 25s so proxies don't time out.
+ * Currently streams the session transcript as an initial burst, then keeps
+ * the connection open for future updates.
+ */
+export async function handleChatEventsSSE(
+  req: IncomingMessage,
+  res: ServerResponse,
+  chatSessionId: string,
+  opts: ChatHttpHandlerOptions,
+  principal?: string,
+): Promise<void> {
+  if (!opts.config?.enabled) {
+    respondJson(res, 404, { error: "chat_disabled", code: "chat_disabled" });
+    return;
+  }
+
+  const session = await loadChatSession(opts.memoryDir, chatSessionId);
+  if (!session) {
+    respondJson(res, 404, { error: "chat_session_not_found", code: "chat_session_not_found" });
+    return;
+  }
+  if (!sessionBelongsToPrincipal(session, principal)) {
+    respondJson(res, 403, { error: "access_denied", code: "access_denied" });
+    return;
+  }
+
+  // SSE headers.
+  res.writeHead(200, {
+    "content-type": "text/event-stream",
+    "cache-control": "no-cache",
+    connection: "keep-alive",
+  });
+
+  // Send the transcript as an initial burst.
+  for (const entry of session.transcript) {
+    res.write(`data: ${JSON.stringify(entry)}\n\n`);
+  }
+
+  // Heartbeat. Unref'd so a lingering connection never blocks process
+  // exit (rule 47 — no shared mutable objects keep the loop alive).
+  const heartbeat = setInterval(() => {
+    try {
+      res.write(`data: ${JSON.stringify({ type: "heartbeat" })}\n\n`);
+    } catch {
+      // Connection closed — clearInterval below.
+    }
+  }, 25_000);
+  heartbeat.unref();
+
+  req.on("close", () => {
+    clearInterval(heartbeat);
+    try { res.end(); } catch { /* already ended */ }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function respondJson(res: ServerResponse, status: number, body: unknown): void {
+  const json = JSON.stringify(body);
+  res.writeHead(status, {
+    "content-type": "application/json; charset=utf-8",
+    "content-length": Buffer.byteLength(json, "utf8"),
+  });
+  res.end(json);
+}