@remnic/core 9.3.713 → 9.3.714

package/src/access-http.ts

@@ -33,6 +33,7 @@ import { getOperation } from "./access-boundary.js";
 // (memory_get / memory_store) as a side effect; the HTTP handlers below
 // dispatch the migrated routes through the registry (issue #1525).
 import "./access-operations.js";
+import { handleChatMessage, handleChatEventsSSE } from "./chat/chat-http.js";
 
 export interface EngramAccessHttpServerOptions {
   service: EngramAccessService;
@@ -320,6 +321,7 @@ export class EngramAccessHttpServer {
       architectureCardVisible: this.service.architectureCardSurfaceVisible,
       codegraphVisible: this.service.codegraphSurfaceVisible,
       sessionDeltaVisible: this.service.sessionDeltaSurfaceVisible,
+      chatVisible: this.service.configRef?.chat?.enabled === true,
       correctionVisible: this.service.correctionSurfaceVisible,
     });
   }
@@ -1561,6 +1563,14 @@ export class EngramAccessHttpServer {
     if (req.method === "GET" && memoryMatch) {
       const memoryId = decodeURIComponent(memoryMatch[1] ?? "");
       const namespace = parsed.searchParams.get("namespace") ?? undefined;
+      // Issue #1582 — thread the transport session key so a `[m:xxxx]` handle in
+      // the path resolves against this session's recall history (codex review).
+      // resolveRequestIdentity reads it from adapter identity / request headers.
+      const sessionKey =
+        this.resolveRequestIdentity(req).sessionKey
+        ?? parsed.searchParams.get("session")
+        ?? parsed.searchParams.get("sessionKey")
+        ?? undefined;
       // Migrated through the access boundary (issue #1525): the registry
       // entry owns memoryId presence/shape validation (rule 51: reject empty
       // ids loudly instead of silently passing "" into the service) and the
@@ -1570,7 +1580,7 @@ export class EngramAccessHttpServer {
         throw new EngramAccessInputError("access-boundary: operation not registered: memory_get");
       }
       const output = (await op.run(
-        { memoryId, namespace: namespace ?? null },
+        { memoryId, namespace: namespace ?? null, sessionKey: sessionKey ?? null },
         { service: this.service, authenticatedPrincipal: this.resolveRequestPrincipal(req) },
       )) as { result: EngramAccessMemoryResponse };
       const response = output.result;
@@ -2048,6 +2058,28 @@ export class EngramAccessHttpServer {
       return;
     }
 
+    // ── Chat endpoints (issue #1583) ────────────────────────────────────────
+    if (req.method === "POST" && pathname === "/engram/v1/chat/message") {
+      void getOperation("chat_message"); // boundary dispatch (issue #1525)
+      const body = await this.readJsonBody(req) as Record<string, unknown>;
+      await handleChatMessage(
+        req, res, body,
+        { service: this.service, config: this.service.configRef?.chat, memoryDir: this.service.memoryDir },
+        this.resolveRequestPrincipal(req),
+      );
+      return;
+    }
+    const chatEventsMatch = /^\/engram\/v1\/chat\/events\/([^/]+)$/.exec(pathname);
+    if (req.method === "GET" && chatEventsMatch) {
+      void getOperation("chat_events"); // boundary dispatch (issue #1525)
+      await handleChatEventsSSE(
+        req, res, chatEventsMatch[1] ?? "",
+        { service: this.service, config: this.service.configRef?.chat, memoryDir: this.service.memoryDir },
+        this.resolveRequestPrincipal(req),
+      );
+      return;
+    }
+
     // ── Peer Registry endpoints (issue #679) ─────────────────────────────────
     // GET /engram/v1/console/state — operator console engine-state snapshot (issue #688 PR 2/3).
     // Read-only; namespace-aware via resolveRequestPrincipal so cross-tenant

package/src/access-mcp.test.ts

@@ -485,6 +485,34 @@ test("MCP session override is injected only into tools that accept sessionKey",
   assert.equal((observeResponse as Record<string, unknown> & { result?: { isError?: boolean } }).result?.isError, false);
 });
 
+test("MCP memory_get advertises sessionKey so the override reaches the resolver (#1582)", async () => {
+  // The engram.memory_get inputSchema must advertise sessionKey, otherwise
+  // toolAcceptsArgument skips the override injection and an MCP caller citing a
+  // [m:xxxx] handle gets "cannot be resolved without a session key" (codex
+  // review). With the field advertised, the transport session key flows through
+  // the registry op into service.memoryGet as the 4th positional arg.
+  let receivedSessionKey: string | undefined;
+  const service = {
+    ...makeMockService(),
+    memoryGet: (_id: string, _ns?: string, _principal?: string, sessionKey?: string) => {
+      receivedSessionKey = sessionKey;
+      return Promise.resolve({ found: false, namespace: "default" });
+    },
+  } as unknown as EngramAccessService;
+  const server = new EngramMcpServer(service);
+
+  const response = await server.handleRequest(
+    makeToolRequest("engram.memory_get", { memoryId: "[m:4f2a]" }),
+    { sessionKeyOverride: "adapter-session" },
+  );
+
+  assert.equal(receivedSessionKey, "adapter-session");
+  assert.equal(
+    (response as Record<string, unknown> & { result?: { isError?: boolean } }).result?.isError,
+    false,
+  );
+});
+
 test("MCP capsule import forwards encrypted archive passphrase", async () => {
   let received: Record<string, unknown> | undefined;
   const service = {

package/src/access-mcp.ts

@@ -34,6 +34,7 @@ import {
   buildChatGptMemoryInspectorResult,
   type RemnicChatGptMemoryInspectorInput,
 } from "./mcp-memory-inspector-app.js";
+import { processChatMessage } from "./chat/chat-factory.js";
 
 type JsonRpcId = string | number | null;
 
@@ -371,6 +372,13 @@ export class EngramMcpServer {
    */
   private readonly correctionVisible: boolean;
 
+  /**
+   * Whether the `memory_chat` tool should appear in `tools/list` (issue
+   * #1583). Gated on `chat.enabled`. When false the tools array is
+   * byte-identical to pre-feature (rule 39).
+   */
+  private readonly chatVisible: boolean;
+
   constructor(
     private readonly service: EngramAccessService,
     options: {
@@ -383,6 +391,7 @@ export class EngramMcpServer {
       codegraphVisible?: boolean;
       sessionDeltaVisible?: boolean;
       correctionVisible?: boolean;
+      chatVisible?: boolean;
     } = {},
   ) {
     this.citationsEnabled = options.citationsEnabled === true;
@@ -394,6 +403,7 @@ export class EngramMcpServer {
     this.sessionDeltaVisible = options.sessionDeltaVisible === true;
     // correction defaults to visible (enabled by default — plan is read-only).
     this.correctionVisible = options.correctionVisible !== false;
+    this.chatVisible = options.chatVisible === true;
     this.authenticatedPrincipal =
       options.principal?.trim() ||
       readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() ||
@@ -1009,6 +1019,11 @@ export class EngramMcpServer {
           properties: {
             memoryId: { type: "string" },
             namespace: { type: "string" },
+            // Issue #1582 — when memoryId is a `[m:xxxx]` handle, sessionKey
+            // scopes resolution to this session's recent recall history.
+            // Advertising it here lets the transport inject its session key
+            // (toolAcceptsArgument) so MCP callers can cite handles (codex review).
+            sessionKey: { type: "string" },
           },
           required: ["memoryId"],
           additionalProperties: false,
@@ -2225,6 +2240,26 @@ export class EngramMcpServer {
       );
       this.tools = [...this.tools, ...planTool, ...applyTool];
     }
+    if (this.chatVisible) {
+      const chatTools = withToolAliases(
+        {
+          name: "engram.memory_chat",
+          description:
+            "Conversational memory inspection and correction (issue #1583). Send a message to chat about what Remnic remembers, inspect memories, or request corrections. Returns {reply, chatSessionId, pendingPlan?}.",
+          inputSchema: {
+            type: "object",
+            properties: {
+              message: { type: "string", description: "The user's message — a question about memories, a correction request, or a confirmation (yes/apply) to proceed with a pending plan." },
+              chatSessionId: { type: "string", description: "Optional existing chat session id to resume. Omit to start a new session." },
+            },
+            required: ["message"],
+            additionalProperties: false,
+          },
+        },
+        this.emitLegacyTools,
+      );
+      this.tools = [...this.tools, ...chatTools];
+    }
   }
 
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */
@@ -2385,7 +2420,13 @@ export class EngramMcpServer {
           argumentsObject = { ...argumentsObject, sessionKey: options.sessionKeyOverride };
         }
         const effectivePrincipal = options?.principalOverride ?? this.authenticatedPrincipal;
-        const result = await this.callTool(name, argumentsObject, effectivePrincipal, options?.sessionId, options?.enforceWriteQuota);
+        // Forward the MCP session scope (namespace/sessionKey overrides) so
+        // tools like memory_chat bind the caller active scope (Thread 17).
+        const mcpScope = {
+          ...(options?.namespaceOverride ? { namespace: options.namespaceOverride } : {}),
+          ...(options?.sessionKeyOverride ? { sessionKey: options.sessionKeyOverride } : {}),
+        };
+        const result = await this.callTool(name, argumentsObject, effectivePrincipal, options?.sessionId, mcpScope, options?.enforceWriteQuota);
         return {
           jsonrpc: "2.0",
           id,
@@ -2573,7 +2614,7 @@ export class EngramMcpServer {
       }));
   }
 
-  private async callTool(name: string, args: Record<string, unknown>, effectivePrincipal?: string, mcpSessionId?: string, enforceWriteQuota?: () => void | Promise<void>): Promise<unknown> {
+  private async callTool(name: string, args: Record<string, unknown>, effectivePrincipal?: string, mcpSessionId?: string, scope?: { namespace?: string; sessionKey?: string }, enforceWriteQuota?: () => void | Promise<void>): Promise<unknown> {
     // Migrated operations dispatch through the access boundary (issue #1525):
     // one registry entry owns schema validation, normalization (rules
     // 17/28/36/48/51), and error mapping for every surface. The switch
@@ -3742,6 +3783,30 @@ export class EngramMcpServer {
           authenticatedPrincipal: effectivePrincipal,
         });
       }
+      case "engram.memory_chat": {
+        const message = typeof args.message === "string" ? args.message : "";
+        if (!message) {
+          throw new EngramAccessInputError("message is required");
+        }
+        const chatSessionId = typeof args.chatSessionId === "string" ? args.chatSessionId : undefined;
+        const chatResult = await processChatMessage({
+          service: this.service,
+          config: this.service.configRef?.chat,
+          memoryDir: this.service.memoryDir,
+          message,
+          ...(chatSessionId ? { chatSessionId } : {}),
+          ...(effectivePrincipal ? { principal: effectivePrincipal } : {}),
+          ...(scope?.namespace ? { namespace: scope.namespace } : {}),
+          ...(scope?.sessionKey ? { sessionKey: scope.sessionKey } : {}),
+        });
+        // Strip internal error details — MCP clients get the tagged reply only,
+        // matching the HTTP handler (cursor security review, Thread 17).
+        if (chatResult && typeof chatResult === "object" && "error" in chatResult) {
+          const { error: _stripped, ...wireResult } = chatResult as unknown as Record<string, unknown>;
+          return wireResult;
+        }
+        return chatResult;
+      }
       default:
         throw new Error(`unknown tool: ${name}`);
     }

package/src/access-operations-batch.ts

@@ -1466,3 +1466,17 @@ defineOperation({
   schema: looseSchema,
   handler: async (_input, _ctx) => ({ result: { stream: "sse" } }),
 });
+
+defineOperation({
+  name: "chat_message",
+  description: "Send a message to Remnic Chat (issue #1583). Endpoint registration only — the handler enforces the chat_disabled gate, message validation, and the confirmation protocol.",
+  schema: looseSchema,
+  handler: async (_input, _ctx) => ({ result: { ok: true } }),
+});
+
+defineOperation({
+  name: "chat_events",
+  description: "Stream chat session transcript events (SSE, issue #1583). Endpoint registration only.",
+  schema: looseSchema,
+  handler: async (_input, _ctx) => ({ result: { stream: "sse" } }),
+});

package/src/access-operations.ts

@@ -58,11 +58,15 @@ import {
  */
 const memoryGetSchema = z.object({
   memoryId: z.string().trim().min(1, "memoryId is required").max(512),
+  // Issue #1582 — when memoryId is a `[m:xxxx]` handle, sessionKey scopes the
+  // resolution to this session's recent recall history.
+  sessionKey: z.string().trim().min(1).max(512).nullable().optional(),
   namespace: z.string().trim().max(256).nullable().optional(),
 });
 
 export interface MemoryGetInput {
   readonly memoryId: string;
+  readonly sessionKey?: string | null;
   readonly namespace?: string | null;
 }
 
@@ -79,6 +83,7 @@ export const memoryGetOperation = defineOperation<MemoryGetInput, MemoryGetOutpu
       input.memoryId,
       input.namespace ?? undefined,
       ctx.authenticatedPrincipal,
+      input.sessionKey ?? undefined,
     );
     return { result };
   },

package/src/access-service.ts

@@ -57,6 +57,7 @@ import {
   type CorrectionPlan,
   type CorrectionRequest,
 } from "./correction/index.js";
+import { isHandleToken } from "./recall-handles.js";
 import { createVersion } from "./page-versioning.js";
 import { WorkStorage } from "./work/storage.js";
 import {
@@ -4491,10 +4492,19 @@ export class EngramAccessService {
     }
   }
 
-  async memoryGet(memoryId: string, namespace?: string, principal?: string): Promise<EngramAccessMemoryResponse> {
+  async memoryGet(
+    memoryId: string,
+    namespace?: string,
+    principal?: string,
+    sessionKey?: string,
+  ): Promise<EngramAccessMemoryResponse> {
+    // Issue #1582 — accept a `[m:xxxx]` handle in place of a memory id; resolve
+    // it against the caller's session via the shared helper (rule 22). A raw id
+    // passes through unchanged, so callers unaware of handles are unaffected.
+    const resolvedId = this.resolveMemoryIdOrHandleInput(memoryId, sessionKey);
     const resolvedNamespace = this.resolveReadableNamespace(namespace, principal);
     const storage = await this.orchestrator.getStorage(resolvedNamespace);
-    const memory = await storage.getMemoryById(memoryId);
+    const memory = await storage.getMemoryById(resolvedId);
     if (!memory) {
       return { found: false, namespace: resolvedNamespace };
     }
@@ -4785,7 +4795,38 @@ export class EngramAccessService {
     return service;
   }
 
+  /**
+   * Issue #1582 — resolve a single memoryId-or-handle reference to a concrete
+   * memory id. Handles resolve against the session's recall history via the
+   * orchestrator's shared helper (rule 22); raw ids pass through unchanged. A
+   * handle that misses or is ambiguous becomes an EngramAccessInputError so the
+   * boundary maps it to a 400 (rule 34/51 — list candidates, never guess).
+   */
+  private resolveMemoryIdOrHandleInput(
+    ref: string,
+    sessionKey: string | undefined,
+  ): string {
+    if (!isHandleToken(ref)) return ref;
+    try {
+      return this.orchestrator.resolveMemoryIdOrHandle(ref, sessionKey);
+    } catch (err) {
+      throw new EngramAccessInputError(
+        err instanceof Error ? err.message : String(err),
+      );
+    }
+  }
+
   async correctionPlan(request: CorrectionRequest): Promise<CorrectionPlan> {
+    // Issue #1582 — resolve any `[m:xxxx]` handle in targetIds to its memory
+    // id against the caller's session BEFORE planning, so the planner only ever
+    // sees concrete ids. One shared resolve path (rule 22); a handle that
+    // misses or collides is an explicit input error, never silent (rule 34/51).
+    if (request.targetIds?.some((id) => isHandleToken(id))) {
+      const targetIds = request.targetIds.map((id) =>
+        this.resolveMemoryIdOrHandleInput(id, request.sessionKey),
+      );
+      return this.correctionService().plan({ ...request, targetIds });
+    }
     return this.correctionService().plan(request);
   }
 

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

@@ -49,7 +49,9 @@ import {
 // alongside the other GET list routes (baseline 80 from #1525 + 1 = 81). Also a
 // catalog-completeness correction: POST /engram/v1/memories (operation memory_store)
 // was always live but omitted from HTTP_ROUTES — it is migrated, so no count change.
-const UNMIGRATED_HANDLER_BASELINE = 81;
+// #1583 remnic chat adds memory_chat — an unmigrated handler dispatched to
+// processChatMessage (carries user input; not a boundary operation) → 81 + 1 = 82.
+const UNMIGRATED_HANDLER_BASELINE = 82;
 
 // Keep the import live — `getOperation` is the call surfaces use at dispatch
 // time; referencing it here pins the registry's lookup contract.
@@ -72,7 +74,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, codegraphVisible: true, sessionDeltaVisible: true });
+  const server = new EngramMcpServer(stub, { emitLegacyTools: true, codingDecisionVisible: true, architectureCardVisible: true, codegraphVisible: true, sessionDeltaVisible: true, chatVisible: 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

@@ -75,6 +75,9 @@ export const MCP_TOOLS: readonly McpToolEntry[] = [
   // Correction Contract (issue #1580) — one plan/apply pipeline.
   { tool: "memory_correct_plan", operation: "memory_correct_plan" },
   { tool: "memory_correct_apply", operation: "memory_correct_apply" },
+  // Conversational memory inspection + correction (issue #1583) — unmigrated
+  // handler dispatched to processChatMessage (not a boundary operation).
+  { tool: "memory_chat", operation: null },
   { tool: "coding_decision", operation: "coding_decision" },
   { tool: "coding_architecture", operation: "coding_architecture" },
   // codegraph parity tools (issue #1554)
@@ -229,6 +232,8 @@ export const HTTP_ROUTES: readonly HttpRouteEntry[] = [
   // streaming lifecycle is owned by the HTTP transport (handleGraphEventsSSE).
   { method: "GET", pathname: "/engram/v1/offline-sync/snapshot-stream", operation: "offline_sync_snapshot_stream" },
   { method: "GET", pathname: "/engram/v1/graph/events", operation: "graph_events" },
+  { method: "POST", pathname: "/engram/v1/chat/message", operation: "chat_message" },
+  { method: "GET", pathname: "/engram/v1/chat/events/:id", operation: "chat_events" },
 ];
 
 /**

package/src/active-memory-bridge.test.ts

@@ -311,3 +311,75 @@ test("getMemoryForActiveMemory ignores explicit namespace overrides when namespa
   assert.equal(result.id, "shared-memory");
   assert.equal(result.text, "shared text");
 });
+
+
+test("getMemoryForActiveMemory resolves a [m:xxxx] handle via the orchestrator resolver (#1582)", async () => {
+  const resolved: string[] = [];
+  const orchestrator = {
+    config: { namespacesEnabled: false },
+    resolveSelfNamespace: () => "readable-session",
+    getStorageForNamespace: async () => ({
+      getMemoryById: async (id: string) =>
+        id === "fact-1" ? ({ content: "text", frontmatter: {} } as never) : null,
+    }),
+    resolveMemoryIdOrHandle: (ref: string) => {
+      resolved.push(ref);
+      return "fact-1";
+    },
+  };
+
+  const result = await getMemoryForActiveMemory(
+    orchestrator as never,
+    "[m:4f2a]",
+    { sessionKey: "session-x" },
+  );
+  assert.deepEqual(resolved, ["[m:4f2a]"]);
+  assert.equal(result.error, undefined);
+  assert.equal(result.id, "fact-1");
+});
+
+test("getMemoryForActiveMemory passes a raw id through unchanged (no resolver call) (#1582)", async () => {
+  const orchestrator = {
+    config: { namespacesEnabled: false },
+    resolveSelfNamespace: () => "readable-session",
+    getStorageForNamespace: async () => ({
+      getMemoryById: async (id: string) =>
+        id === "fact-1" ? ({ content: "text", frontmatter: {} } as never) : null,
+    }),
+    resolveMemoryIdOrHandle: () => {
+      throw new Error("resolver must not be called for a raw id");
+    },
+  };
+
+  const result = await getMemoryForActiveMemory(
+    orchestrator as never,
+    "fact-1",
+    { sessionKey: "session-x" },
+  );
+  assert.equal(result.id, "fact-1");
+});
+
+test("getMemoryForActiveMemory returns not_found when a handle cannot be resolved (#1582, cursor review)", async () => {
+  // A missing session key, unknown handle, or ambiguous handle makes the
+  // orchestrator resolver THROW. The active-memory get path must yield the SAME
+  // not_found contract a bad raw id gets — not propagate the throw and crash an
+  // OpenClaw active-memory caller.
+  const orchestrator = {
+    config: { namespacesEnabled: false },
+    resolveSelfNamespace: () => "readable-session",
+    getStorageForNamespace: async () => ({
+      getMemoryById: async () => null,
+    }),
+    resolveMemoryIdOrHandle: () => {
+      throw new Error("Memory handle [m:dead] cannot be resolved without a session key.");
+    },
+  };
+
+  const result = await getMemoryForActiveMemory(
+    orchestrator as never,
+    "[m:dead]",
+    // No sessionKey → resolver throws "without a session key".
+    {},
+  );
+  assert.equal(result.error, "not_found");
+});

package/src/active-memory-bridge.ts

@@ -1,6 +1,7 @@
 import { canReadNamespace, defaultNamespaceForPrincipal, resolvePrincipal } from "./namespaces/principal.js";
 import type { MemoryFile, PluginConfig } from "./types.js";
 import { collapseWhitespace, truncateCodePointSafe } from "./whitespace.js";
+import { isHandleToken } from "./recall-handles.js";
 
 export interface ActiveMemoryMetadata {
   type?: "fact" | "preference";
@@ -192,6 +193,8 @@ export async function getMemoryForActiveMemory(
     storage?: {
       getMemoryById?: (id: string) => Promise<MemoryFile | null>;
     };
+    /** Issue #1582 — resolves a `[m:xxxx]` handle to a memory id (orchestrator). */
+    resolveMemoryIdOrHandle?: (ref: string, sessionKey?: string) => string;
   },
   id: string,
   options: {
@@ -210,10 +213,26 @@ export async function getMemoryForActiveMemory(
       ? await orchestrator.getStorageForNamespace(namespace)
       : orchestrator.storage;
 
-  const memory = await storage?.getMemoryById?.(id);
+  // Issue #1582 — resolve a `[m:xxxx]` handle to its memory id against the
+  // caller's session before the storage read, so OpenClaw active-memory agents
+  // can cite injected handles through the SAME shared path as memory_get /
+  // correction (cursor review). Raw ids pass through unchanged.
+  //
+  // A handle that misses, collides, or has no session key becomes not_found —
+  // the SAME behavior a bad raw id yields below — instead of throwing, so an
+  // active-memory caller gets a uniform not-found contract (cursor review).
+  let resolvedId = id;
+  if (isHandleToken(id) && typeof orchestrator.resolveMemoryIdOrHandle === "function") {
+    try {
+      resolvedId = orchestrator.resolveMemoryIdOrHandle(id, options.sessionKey);
+    } catch {
+      return { error: "not_found" };
+    }
+  }
+  const memory = await storage?.getMemoryById?.(resolvedId);
   if (!memory) return { error: "not_found" };
   return {
-    id,
+    id: resolvedId,
     text: collapseWhitespace(memory.content),
     metadata: buildActiveMemoryMetadataFromMemory(memory),
   };

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

@@ -0,0 +1,142 @@
+/**
+ * Chat CLI surface tests (issue #1583 PR 2).
+ *
+ * Tests the non-TTY `--once` scripting mode and the no-LLM error path.
+ * Interactive readline mode is exercised via the golden-transcript pattern
+ * in chat-engine.test.ts (the engine loop is identical); here we cover the
+ * CLI's own input/output contract.
+ */
+
+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 type { EngramAccessService } from "../access-service.js";
+import { parseConfig } from "../config.js";
+import { runChatCli } from "./chat-cli.js";
+import { DEFAULT_CHAT_CONFIG } from "./chat-config.js";
+
+/** Capture stdout.write for the duration of `fn`. */
+async function captureStdout(fn: () => Promise<void>): Promise<string> {
+  const chunks: string[] = [];
+  const original = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk: unknown) => {
+    chunks.push(typeof chunk === "string" ? chunk : String(chunk));
+    return true;
+  }) as typeof process.stdout.write;
+  try {
+    await fn();
+  } finally {
+    process.stdout.write = original;
+  }
+  return chunks.join("");
+}
+
+function makeService(overrides: Partial<EngramAccessService> = {}): EngramAccessService {
+  return {
+    fallbackLlmRef: {
+      chatCompletion: async () => ({ content: "Based on memory_search, your database uses PostgreSQL [id: abc]." }),
+    },
+    configRef: parseConfig({ memoryDir: "/tmp/chat-cli-test", chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    memoryDir: "/tmp/chat-cli-test",
+    memoryGet: () => Promise.resolve(null),
+    memoryTimeline: () => Promise.resolve([]),
+    memorySearch: () => Promise.resolve({ results: [{ path: "mem/abc.md", score: 0.9, snippet: "PostgreSQL" }], count: 1 }),
+    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-cli-"));
+  try { return await fn(dir); } finally { await rm(dir, { recursive: true, force: true }); }
+}
+
+test("CLI --once mode: prints the assistant reply and session id", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const out = await captureStdout(() =>
+      runChatCli({
+        service,
+        config: service.configRef!.chat,
+        memoryDir,
+        once: true,
+        input: "what database do I use?",
+      }),
+    );
+    assert.ok(out.includes("PostgreSQL"), `expected reply in stdout, got: ${out}`);
+    assert.ok(out.includes("[session:"), "session id should be printed for --once mode");
+  });
+});
+
+test("CLI --once mode: no input → tagged error", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const out = await captureStdout(() =>
+      runChatCli({
+        service,
+        config: service.configRef!.chat,
+        memoryDir,
+        once: true,
+        input: "   ",
+      }),
+    );
+    assert.ok(out.includes("[error]"), `expected error tag, got: ${out}`);
+  });
+});
+
+test("CLI: no LLM available → tagged error reply", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      fallbackLlmRef: null,
+      localLlmRef: null,
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    const out = await captureStdout(() =>
+      runChatCli({
+        service,
+        config: service.configRef!.chat,
+        memoryDir,
+        once: true,
+        input: "hi",
+      }),
+    );
+    assert.ok(out.includes("[error]"), `expected error tag, got: ${out}`);
+    assert.ok(out.toLowerCase().includes("llm") || out.toLowerCase().includes("model"), "should mention model availability");
+  });
+});
+
+test("CLI: resumes an existing session by id", async () => {
+  await withTempDir(async (memoryDir) => {
+    const service = makeService({
+      memoryDir,
+      configRef: parseConfig({ memoryDir, chat: { ...DEFAULT_CHAT_CONFIG, enabled: true } }),
+    });
+    // First message creates a session.
+    const first = await captureStdout(() =>
+      runChatCli({ service, config: service.configRef!.chat, memoryDir, once: true, input: "hello" }),
+    );
+    const sessionMatch = /\[session: ([^\]]+)\]/.exec(first);
+    assert.ok(sessionMatch, "first run should print a session id");
+    const sessionId = sessionMatch[1]!;
+    // Second message resumes it.
+    const second = await captureStdout(() =>
+      runChatCli({ service, config: service.configRef!.chat, memoryDir, once: true, input: "again", sessionId }),
+    );
+    assert.ok(second.includes("[session:"), "resumed run should also print a session id");
+  });
+});