@remnic/core 9.3.713 → 9.3.715

package/src/chat/chat-types.ts

@@ -0,0 +1,167 @@
+/**
+ * Shared types for the conversational memory chat engine (issue #1583).
+ *
+ * The chat engine is a deliberately bounded tool-loop agent — NOT a general
+ * assistant.  It exposes a fixed set of read-only and (confirmation-gated)
+ * mutating tools, each a thin adapter over an existing access-service method.
+ */
+
+// ---------------------------------------------------------------------------
+// LLM adapter — production signature (rule 33), stubbable for tests
+// ---------------------------------------------------------------------------
+
+/**
+ * A single chat message in the LLM conversation.
+ */
+export interface ChatLlmMessage {
+  role: "system" | "user" | "assistant" | "tool";
+  content: string;
+  /** Tool-call id when role === "tool" (correlates the result back). */
+  toolCallId?: string;
+}
+
+/**
+ * A tool-call request emitted by the LLM.  The engine parses these from the
+ * LLM response and dispatches them through the tool registry.
+ */
+export interface ChatLlmToolCall {
+  id: string;
+  name: string;
+  arguments: Record<string, unknown>;
+}
+
+/**
+ * Structured LLM response — either a text reply or a set of tool calls.
+ * The adapter (stub or production) is responsible for parsing the raw model
+ * output into this shape.
+ */
+export interface ChatLlmResponse {
+  /** Assistant text reply (empty when only tool calls are present). */
+  content: string;
+  /** Tool calls to execute (empty for a final text reply). */
+  toolCalls: ChatLlmToolCall[];
+}
+
+/**
+ * Production-grade LLM adapter interface.  The stub implementation used in
+ * tests drives scripted sequences; the production implementation wraps the
+ * existing FallbackLlmClient routing chain so local Ollama/vLLM models are
+ * fully supported (gotcha 1).
+ */
+export interface ChatLlmAdapter {
+  /**
+   * Send the conversation so far to the LLM and receive the next response.
+   * Returns `null` when no model is available or the request fails (rule 13).
+   */
+  complete(
+    messages: ChatLlmMessage[],
+    options: {
+      tools: ChatToolSchema[];
+      model?: string;
+      signal?: AbortSignal;
+    },
+  ): Promise<ChatLlmResponse | null>;
+}
+
+// ---------------------------------------------------------------------------
+// Tool schema + execution
+// ---------------------------------------------------------------------------
+
+/**
+ * JSON-Schema description of a chat tool, sent to the LLM so it knows what
+ * tools are available and how to call them.
+ */
+export interface ChatToolSchema {
+  type: "function";
+  function: {
+    name: string;
+    description: string;
+    parameters: Record<string, unknown>;
+  };
+}
+
+/**
+ * Result of executing a chat tool.  Read-only tools return data; mutating
+ * tools go through the confirmation protocol before they reach the executor.
+ */
+export interface ChatToolResult {
+  /** Structured payload returned to the LLM as a tool message. */
+  content: string;
+  /** Whether the tool call was intercepted by the confirmation protocol. */
+  pendingConfirmation?: boolean;
+  /** Plan preview when pendingConfirmation is true. */
+  planPreview?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Chat session — transcript + pending-plan state
+// ---------------------------------------------------------------------------
+
+/**
+ * A single line in the persisted chat transcript (JSONL).
+ */
+export interface ChatTranscriptEntry {
+  /** Monotonic sequence number within the session. */
+  seq: number;
+  /** ISO 8601 timestamp. */
+  ts: string;
+  role: "user" | "assistant" | "tool" | "system";
+  content: string;
+  /** Tool-call id for tool messages. */
+  toolCallId?: string;
+  /** Tool name for tool messages. */
+  toolName?: string;
+}
+
+/**
+ * In-memory session state, backed by the JSONL transcript on disk.
+ */
+export interface ChatSessionState {
+  id: string;
+  /** Caller principal bound at creation (rule 42). */
+  principal?: string;
+  /** Session key for namespace resolution. */
+  sessionKey?: string;
+  /** Namespace override. */
+  namespace?: string;
+  /** Transcript entries loaded from disk. */
+  transcript: ChatTranscriptEntry[];
+  /** Plan ids confirmed by the user for exactly one apply. */
+  confirmedPlanIds: Set<string>;
+  /** The pending plan awaiting confirmation (if any). */
+  pendingPlanId?: string;
+  /** The pending memory-promotion memory id awaiting confirmation (if any). */
+  pendingPromotionId?: string;
+  /** Creation timestamp. */
+  createdAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Engine turn result
+// ---------------------------------------------------------------------------
+
+/**
+ * What the engine returns for a single user message.
+ */
+export interface ChatTurnResult {
+  /** The assistant's text reply (may be partial on budget exhaustion). */
+  reply: string;
+  /** The chat session id (existing or newly created). */
+  chatSessionId: string;
+  /** A pending plan awaiting user confirmation, if surfaced. */
+  pendingPlan?: {
+    planId: string;
+    preview: string;
+  };
+  /** Tool calls that were skipped due to budget exhaustion. */
+  skippedTools?: string[];
+  /** Whether the reply is a tagged error (rule 13). */
+  error?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Chat config — re-exported from types.ts (canonical definition).
+// DEFAULT_CHAT_CONFIG lives in chat-config.ts.
+// ---------------------------------------------------------------------------
+
+export type { ChatConfig } from "../types.js";

package/src/cli.ts

@@ -95,6 +95,7 @@ import { WebDavServer } from "./network/webdav.js";
 import { GraphDashboardServer, type DashboardStatus } from "./dashboard-runtime.js";
 import { EngramAccessService } from "./access-service.js";
 import { EngramAccessHttpServer } from "./access-http.js";
+import { runChatCli } from "./chat/chat-cli.js";
 import {
   buildActionConfidenceInputFromOptions,
   evaluateActionConfidence,
@@ -2807,6 +2808,7 @@ export async function runAccessMcpServeCliCommand(
       architectureCardVisible: service.architectureCardSurfaceVisible,
       codegraphVisible: service.codegraphSurfaceVisible,
       sessionDeltaVisible: service.sessionDeltaSurfaceVisible,
+      chatVisible: service.configRef?.chat?.enabled === true,
       correctionVisible: service.correctionSurfaceVisible,
     });
   await server.runStdio(options.stdin ?? process.stdin, options.stdout ?? process.stdout);
@@ -9336,6 +9338,24 @@ export function registerCli(
             }
           }
         });
+      // ── Chat — conversational memory inspection + correction (#1583) ────
+      cmd
+        .command("chat")
+        .description("Conversational memory inspection and correction (issue #1583)")
+        .option("--session <id>", "Resume an existing chat session")
+        .option("--once", "Process a single message from stdin and exit (non-TTY/scripting)")
+        .option("--principal <principal>", "Trusted principal (defaults to config/env)")
+        .action(async (...args: unknown[]) => {
+          const options = (args[0] ?? {}) as Record<string, unknown>;
+          await runChatCli({
+            service: new EngramAccessService(orchestrator),
+            config: orchestrator.config?.chat,
+            memoryDir: orchestrator.config.memoryDir,
+            principal: resolveAccessPrincipalOverride(options.principal, orchestrator.config.agentAccessHttp.principal),
+            ...(typeof options.session === "string" ? { sessionId: options.session } : {}),
+            ...(options.once === true ? { once: true } : {}),
+          });
+        });
     },
     { commands: ["engram"] },
   );

package/src/config.ts

@@ -47,6 +47,7 @@ import {
 import { parseWearablesConfig } from "./wearables/config.js";
 import { parseProvenanceConfig } from "./provenance.js";
 import { parseCodingKnowledgeConfig } from "./coding/coding-knowledge-config.js";
+import { parseChatConfig } from "./chat/chat-config.js";
 const DEFAULT_MEMORY_DIR = path.join(
   resolveHomeDir(),
   ".openclaw",
@@ -2507,6 +2508,7 @@ export function parseConfig(
     slotBehavior,
     codexCompat,
     codingKnowledge: parseCodingKnowledgeConfig(cfg.codingKnowledge),
+    chat: parseChatConfig(cfg.chat),
      // Hourly summaries
     hourlySummariesEnabled: cfg.hourlySummariesEnabled !== false, // default: true
     daySummaryEnabled: cfg.daySummaryEnabled !== false, // default: true
@@ -3246,6 +3248,13 @@ export function parseConfig(
     // Issue #564 PR 3: off by default; enable explicitly after bench validation.
     recallReasoningTraceBoostEnabled:
       coerceBool(cfg.recallReasoningTraceBoostEnabled) ?? false,
+    // Issue #1582: off by default — handles are byte-additive at injection time.
+    recallMemoryHandles: coerceBool(cfg.recallMemoryHandles) ?? false,
+    recallHandleSnapshotDepth:
+      typeof cfg.recallHandleSnapshotDepth === "number" &&
+      Number.isFinite(cfg.recallHandleSnapshotDepth)
+        ? Math.max(1, Math.min(50, Math.floor(cfg.recallHandleSnapshotDepth)))
+        : 5,
     qmdRecallCacheTtlMs:
       typeof cfg.qmdRecallCacheTtlMs === "number" ? Math.max(0, Math.floor(cfg.qmdRecallCacheTtlMs)) : 60_000,
     qmdRecallCacheStaleTtlMs:

package/src/faithfulness-graph-guard.test.ts

@@ -25,6 +25,7 @@ import { Orchestrator } from "./orchestrator.js";
 import { readEdges } from "./graph.js";
 import type { ExtractionResult, PluginConfig } from "./types.js";
 import type { LocalLlmClient } from "./local-llm.js";
+import type { BufferTurn, ConversationThread } from "./types.js";
 
 /**
  * Stub local LLM whose `chatCompletion` only answers faithfulness-gate calls
@@ -42,15 +43,20 @@ function faithfulnessStubLocalLlm(
     ) => {
       if (options.operation !== "extraction-faithfulness") return null;
       const userMsg = messages.find((m) => m.role === "user");
-      // The prompt emits `FACT: "<text>"` — fact text never contains a raw
-      // double-quote, so capture up to the closing quote.
-      const match = userMsg?.content.match(/FACT: "([^"]*)"/);
-      const factContent = match ? (match[1] ?? "") : "";
-      const verdict = verdictForFactContent(factContent);
+      // The batch prompt emits one `FACT: "<text>"` line per fact, each
+      // followed by `Respond with the JSON array entry for index <i>`. The
+      // gate maps verdicts back to facts by that index, so return one entry
+      // per fact in prompt order. (Single-fact callers still get one entry.)
+      const factMatches = [...(userMsg?.content ?? "").matchAll(/FACT: "([^"]*)"/g)];
+      const entries = factMatches.map((m, i) => ({
+        index: i,
+        verdict: verdictForFactContent(m[1] ?? ""),
+        rationale: "stub verdict",
+      }));
       return {
-        content: JSON.stringify([
-          { index: 0, verdict, rationale: "stub verdict" },
-        ]),
+        content: JSON.stringify(
+          entries.length > 0 ? entries : [{ index: 0, verdict: "entailed" as const, rationale: "stub" }],
+        ),
       };
     },
   } as unknown as LocalLlmClient;
@@ -250,3 +256,203 @@ test("pending_review fact gets no graph edge; an active fact with the same entit
     await rm(memoryDir, { recursive: true, force: true });
   }
 });
+
+
+/**
+ * Thread-enabled harness for issue #1635: time + causal graph ON (so
+ * thread-predecessor edges are built), faithfulness gate in enforce mode.
+ * Entity graph is left OFF to isolate the thread-episode predecessor
+ * mechanism (entity-sibling edges are a separate, out-of-scope path).
+ */
+async function makeThreadHarness(): Promise<OrchHarness> {
+  const memoryDir = await mkdtemp(
+    path.join(os.tmpdir(), "remnic-faithfulness-thread-"),
+  );
+  const config: PluginConfig = parseConfig({
+    openaiApiKey: "sk-test",
+    memoryDir,
+    workspaceDir: path.join(memoryDir, "workspace"),
+    multiGraphMemoryEnabled: true,
+    entityGraphEnabled: false,
+    timeGraphEnabled: true,
+    causalGraphEnabled: true,
+    extractionFaithfulnessGate: "enforce",
+    extractionFaithfulnessContextChars: 400,
+    extractionFaithfulnessTimeoutMs: 2000,
+    extractionJudgeEnabled: false,
+    temporalSupersessionEnabled: false,
+    contradictionDetectionEnabled: false,
+    chunkingEnabled: false,
+    embeddingFallbackEnabled: false,
+    qmdEnabled: false,
+    extractionMinChars: 0,
+    extractionMinImportanceLevel: "trivial",
+    inlineSourceAttributionEnabled: false,
+  });
+  const orchestrator = new Orchestrator(config);
+  return { orchestrator, memoryDir };
+}
+
+/** ExtractionResult with two facts (order preserved by the persist loop). */
+function twoFactResult(
+  contentA: string,
+  entityRefA: string,
+  contentB: string,
+  entityRefB: string,
+): ExtractionResult {
+  return {
+    facts: [
+      { content: contentA, category: "fact", tags: [], confidence: 0.9, entityRef: entityRefA },
+      { content: contentB, category: "fact", tags: [], confidence: 0.9, entityRef: entityRefB },
+    ],
+    entities: [],
+    relationships: [],
+    questions: [],
+    profileUpdates: [],
+  } as unknown as ExtractionResult;
+}
+
+interface StorageLike {
+  ensureDirectories: () => Promise<void>;
+  dir: string;
+  readAllMemories: () => Promise<
+    Array<{ path: string; frontmatter: { id: string; status?: string } }>
+  >;
+}
+
+interface PersistExtractionSig {
+  (
+    r: ExtractionResult,
+    s: unknown,
+    t: string | null,
+    ctx: unknown,
+    bn: unknown,
+    plan: unknown,
+    src: string,
+  ): Promise<string[]>;
+}
+
+test("pending_review id must NOT enter persisted thread episodes across a cross-flush (#1635)", async () => {
+  const { orchestrator, memoryDir } = await makeThreadHarness();
+  try {
+    // fact content containing "closed permanently" → unsupported → pending_review.
+    (orchestrator as unknown as { localLlm: LocalLlmClient }).localLlm =
+      faithfulnessStubLocalLlm((c) =>
+        c.includes("closed permanently") ? "unsupported" : "entailed",
+      );
+
+    const getStorage = orchestrator as unknown as {
+      getStorage: (ns: string) => Promise<StorageLike>;
+    };
+    const storage = await getStorage.getStorage("default");
+    await storage.ensureDirectories();
+
+    // Establish a real thread (mirrors runExtraction's processTurn step) so
+    // appendEpisodeIds has a thread file to write episode ids into.
+    const threading = orchestrator as unknown as {
+      threading: {
+        processTurn: (turn: BufferTurn, ids: string[]) => Promise<string>;
+        loadThread: (id: string) => Promise<ConversationThread | null>;
+      };
+    };
+    const seedTurn: BufferTurn = {
+      role: "user",
+      content: "Tell me about the widget factory.",
+      timestamp: "2026-07-06T10:00:00.000Z",
+      sessionKey: "agent:test:main",
+    };
+    const threadId = await threading.threading.processTurn(seedTurn, []);
+    assert.ok(threadId, "thread established via processTurn");
+
+    const persist = orchestrator as unknown as {
+      persistExtraction: PersistExtractionSig;
+      appendPersistedThreadEpisodes: (
+        threadId: string,
+        persistedIds: string[],
+      ) => Promise<void>;
+    };
+
+    const sourceText =
+      "The widget factory reopened this quarter after being closed permanently last year.";
+
+    // --- Flush 1: an active fact + a pending_review fact, same thread ---
+    const flush1 = await persist.persistExtraction(
+      twoFactResult(
+        "The widget factory reopened this quarter.", "wf-active",
+        "The widget factory closed permanently last year.", "wf-pending",
+      ),
+      storage,
+      threadId,
+      { sessionKey: "agent:test:main", principal: "test" },
+      undefined,
+      null,
+      sourceText,
+    );
+    const [activeId1, pendingId] = flush1;
+    assert.ok(activeId1, "flush1 active fact persisted");
+    assert.ok(pendingId, "flush1 pending_review fact persisted");
+
+    // runExtraction's append step (the real helper; filters pending_review).
+    await persist.appendPersistedThreadEpisodes(threadId, flush1);
+
+    // PART (a): the thread FILE must hold the active id but NOT the pending id.
+    const threadAfter1 = await threading.threading.loadThread(threadId);
+    assert.ok(threadAfter1, "thread file readable after flush 1");
+    assert.ok(
+      threadAfter1!.episodeIds.includes(activeId1),
+      "active fact id is in persisted thread episodes",
+    );
+    assert.ok(
+      !threadAfter1!.episodeIds.includes(pendingId),
+      "pending_review id must NOT enter persisted thread episodes (#1635)",
+    );
+
+    // The pending fact IS durable (with status pending_review) — proves the
+    // gate routed it correctly; the guard is about its absence from the thread.
+    const memsAfter1 = await storage.readAllMemories();
+    const pendingMem = memsAfter1.find((m) => m.frontmatter.id === pendingId);
+    assert.ok(pendingMem, "pending_review fact is durable");
+    assert.equal(
+      pendingMem!.frontmatter.status,
+      "pending_review",
+      "unsupported fact is pending_review under enforce",
+    );
+
+    // --- Flush 2: an active fact in the SAME thread ---
+    const flush2 = await persist.persistExtraction(
+      factResult("The widget factory hired ten new engineers.", "wf-active"),
+      storage,
+      threadId,
+      { sessionKey: "agent:test:main", principal: "test" },
+      undefined,
+      null,
+      sourceText,
+    );
+    const activeId2 = flush2[0];
+    assert.ok(activeId2, "flush2 active fact persisted");
+    await persist.appendPersistedThreadEpisodes(threadId, flush2);
+
+    // PART (a)+(b): no predecessor edge may reference the pending fact. Under
+    // the bug, flush 1 would have appended pendingId to the thread file, flush
+    // 2's loadThread would re-seed it into threadEpisodeIdsForGraph, and the
+    // active fact2 would build a time/causal predecessor edge to it.
+    const pendingPath = path.relative(memoryDir, pendingMem!.path);
+    for (const gtype of ["time", "causal"] as const) {
+      const edges = await readEdges(memoryDir, gtype);
+      assert.ok(
+        !edges.some((e) => e.from === pendingPath || e.to === pendingPath),
+        `no ${gtype} edge references the pending_review fact path (${pendingPath}); got ${edges.length} edges`,
+      );
+    }
+
+    // Control: the graph + threading are wired — the active fact2 builds a
+    // time predecessor edge to the active fact1 (which IS in the thread file).
+    const timeEdges = await readEdges(memoryDir, "time");
+    assert.ok(
+      timeEdges.length > 0,
+      "active fact2 builds a time predecessor edge (control: graph+threading wired)",
+    );
+  } finally {
+    await rm(memoryDir, { recursive: true, force: true });
+  }
+});