@remnic/core 9.3.712 → 9.3.714

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/orchestrator.ts

@@ -126,6 +126,7 @@ import { RelevanceStore } from "./relevance.js";
 import { NegativeExampleStore } from "./negative.js";
 import {
   LastRecallStore,
+  RecallHandleHistoryStore,
   type LastRecallBudgetSummary,
   TierMigrationStatusStore,
   clampGraphRecallExpandedEntries,
@@ -134,6 +135,14 @@ import {
   type TierMigrationCycleSummary,
   type TierMigrationStatusSnapshot,
 } from "./recall-state.js";
+import {
+  buildHandleIndexForResults,
+  MEMORY_ID_PATTERN,
+  parseIdOrHandle,
+  resolveHandle,
+  stripHandles,
+  type RecallSnapshotIds,
+} from "./recall-handles.js";
 import {
   buildXraySnapshot,
   type RecallFilterTrace,
@@ -1872,6 +1881,7 @@ export class Orchestrator {
   readonly relevance: RelevanceStore;
   readonly negatives: NegativeExampleStore;
   readonly lastRecall: LastRecallStore;
+  readonly handleHistory: RecallHandleHistoryStore;
   readonly tierMigrationStatus: TierMigrationStatusStore;
   /**
    * In-memory X-ray snapshot from the most recent `recall()` call that
@@ -2797,6 +2807,9 @@ export class Orchestrator {
     this.relevance = new RelevanceStore(config.memoryDir);
     this.negatives = new NegativeExampleStore(config.memoryDir);
     this.lastRecall = new LastRecallStore(config.memoryDir);
+    this.handleHistory = new RecallHandleHistoryStore(config.memoryDir, {
+      maxDepth: config.recallHandleSnapshotDepth,
+    });
     this.tierMigrationStatus = new TierMigrationStatusStore(config.memoryDir);
     this.sessionObserver = new SessionObserverState({
       memoryDir: config.memoryDir,
@@ -3241,6 +3254,7 @@ export class Orchestrator {
       await this.relevance.load();
       await this.negatives.load();
       await this.lastRecall.load();
+      await this.handleHistory.load();
       await this.tierMigrationStatus.load();
       await this.sessionObserver.load();
       this.runtimePolicyValues = await this.policyRuntime.loadRuntimeValues();
@@ -11299,7 +11313,7 @@ export class Orchestrator {
         this.appendRecallSection(
           sectionBuckets,
           "workspace-context",
-          this.formatQmdResults("Workspace Context", globalResults),
+          this.formatQmdResults("Workspace Context", globalResults, sessionKey),
         );
       }
 
@@ -12073,6 +12087,22 @@ export class Orchestrator {
             backendDegradations.length > 0 ? backendDegradations : undefined,
         })
         .catch((err) => log.debug(`last recall record failed: ${err}`));
+      // Issue #1582 — record the admitted memory-id set for handle resolution.
+      // Only when handles are enabled: if injection is off, no handle is ever
+      // rendered, so there is nothing to resolve and we skip the write.
+      if (this.config.recallMemoryHandles && recalledMemoryIds.length > 0) {
+        // Only handle-eligible ids aid resolution; filter out non-memory .md
+        // basenames (entity reconstructions) so the resolver never records a
+        // citation target that cannot be loaded.
+        const handleEligibleIds = recalledMemoryIds.filter((id) =>
+          MEMORY_ID_PATTERN.test(id),
+        );
+        if (handleEligibleIds.length > 0) {
+          this.handleHistory
+            .record(sessionKey, handleEligibleIds)
+            .catch((err) => log.debug(`handle history record failed: ${err}`));
+        }
+      }
     }
     if (sessionKey) {
       this.queueEvalShadowRecall({
@@ -12165,9 +12195,17 @@ export class Orchestrator {
           ? sessionKey
           : "default";
     const captureTimestamp = new Date().toISOString();
+    // Issue #1582 hygiene §2 — strip any echoed `[m:xxxx]` handle before the
+    // turn enters the extraction buffer so handles never become memory content
+    // or get QMD-indexed (rule 23). Gated on the feature flag: when handles are
+    // off none are ever injected, so there is nothing to strip and the buffer
+    // stays byte-identical to the pre-#1582 path.
+    const bufferedContent = this.config.recallMemoryHandles
+      ? stripHandles(content)
+      : content;
     const turn: BufferTurn = {
       role,
-      content,
+      content: bufferedContent,
       timestamp: captureTimestamp,
       // #1578: anchor live-capture turns to wall-clock when bi-temporal is on;
       // replay/import turns carry sourceValidAt explicitly (codex P1).
@@ -17455,13 +17493,28 @@ export class Orchestrator {
     }
   }
 
-  private formatQmdResults(title: string, results: QmdSearchResult[]): string {
+  private formatQmdResults(
+    title: string,
+    results: QmdSearchResult[],
+    sessionKey?: string,
+  ): string {
+    // Issue #1582 — handles are only rendered when a session key is available:
+    // resolution requires the handle history to have been recorded for this
+    // session, which only happens when sessionKey is present. Rendering handles
+    // without recording would show tokens a user can never resolve (cursor
+    // review). The rendering logic itself lives in the pure handles module.
+    const handleByIndex = buildHandleIndexForResults(
+      results,
+      this.config.recallMemoryHandles === true && sessionKey != null,
+    );
     const lines = results.map((r, i) => {
       const snippet = r.snippet
         ? r.snippet.slice(0, 500).replace(/\n/g, " ")
         : "(no preview)";
       const source = typeof r.line === "number" ? `${r.path}:${r.line}` : r.path;
-      return `[${i + 1}] ${source} (score: ${r.score.toFixed(3)})\n${snippet}`;
+      const head = `[${i + 1}] ${source} (score: ${r.score.toFixed(3)})\n${snippet}`;
+      const handle = handleByIndex.get(i);
+      return handle ? `${head.replace(/\s+$/, "")} ${handle}` : head;
     });
     return `## ${title}\n\n${lines.join("\n\n")}`;
   }
@@ -17826,7 +17879,7 @@ export class Orchestrator {
     this.appendRecallSection(
       options.sectionBuckets,
       sectionId,
-      this.formatQmdResults(options.title, options.results),
+      this.formatQmdResults(options.title, options.results, options.sessionKey),
     );
   }
 
@@ -19661,6 +19714,54 @@ export class Orchestrator {
     return this.lastRecall.get(sessionKey);
   }
 
+  /**
+   * Issue #1582 — resolve a memory handle (`[m:4f2a]` / bare hex) to its memory
+   * id against THIS session's recent recall history. Returns the id on a unique
+   * hit, `null` on a miss, and throws on ambiguity (callers must disambiguate —
+   * rule 34/51). Resolution is per-session and snapshot-scoped; there is no
+   * global handle→id map (rule 42).
+   */
+  resolveMemoryHandle(handle: string, sessionKey: string): string | null {
+    if (!sessionKey) return null;
+    const depth = this.config.recallHandleSnapshotDepth;
+    const snapshots: RecallSnapshotIds[] = this.handleHistory
+      .recent(sessionKey, depth)
+      .map((ids) => ({ memoryIds: ids }));
+    const result = resolveHandle(handle, snapshots, depth);
+    if (result.ok) return result.memoryId;
+    if (result.reason === "ambiguous") {
+      throw new Error(
+        `Memory handle ${handle} is ambiguous in session ${sessionKey}: ` +
+          `${result.candidates.join(", ")}. Cite a unique memory id instead.`,
+      );
+    }
+    return null;
+  }
+
+  /**
+   * Issue #1582 — resolve a caller reference that may be EITHER a memory id or
+   * a handle to a concrete memory id. Handles resolve against the session's
+   * recall history; raw ids pass through unchanged. The single shared helper
+   * every surface (memory_get / feedback / outcome / correction targetIds)
+   * calls so handle resolution has one path (rule 22).
+   */
+  resolveMemoryIdOrHandle(ref: string, sessionKey?: string): string {
+    const parsed = parseIdOrHandle(ref);
+    if (!parsed.isHandle) return parsed.value;
+    if (!sessionKey) {
+      throw new Error(
+        `Memory handle ${ref} cannot be resolved without a session key.`,
+      );
+    }
+    const resolved = this.resolveMemoryHandle(parsed.value, sessionKey);
+    if (resolved === null) {
+      throw new Error(
+        `Memory handle ${ref} was not found in the recent recall history for session ${sessionKey}.`,
+      );
+    }
+    return resolved;
+  }
+
   /**
    * Check if a new memory contradicts an existing one.
    * Uses QMD to find similar memories, then LLM to verify contradiction.