@remnic/core 9.3.712 → 9.3.714

package/dist/{chunk-I3BT2IDW.js → chunk-SYDHFFAW.js}

@@ -11,19 +11,19 @@ import {
 } from "./chunk-D24OXEPB.js";
 import {
   validateRequest
-} from "./chunk-NUWZFSKC.js";
+} from "./chunk-FVZ2ISIX.js";
 import {
   getOperation
-} from "./chunk-ZVDRL6SK.js";
+} from "./chunk-HHLWSWWF.js";
 import {
   EngramAccessInputError
-} from "./chunk-YVWZW37D.js";
+} from "./chunk-BNOAB5HH.js";
 import {
   projectTagProjectId
 } from "./chunk-SHRRWOVY.js";
 import {
   validateBriefingFormat
-} from "./chunk-35YJ6KCV.js";
+} from "./chunk-JEIROMLX.js";
 import {
   resolvePrincipal
 } from "./chunk-UZYLX7M6.js";
@@ -35,8 +35,1012 @@ import {
 } from "./chunk-JUC24CTX.js";
 
 // src/access-mcp.ts
-import { readFile } from "fs/promises";
+import { readFile as readFile2 } from "fs/promises";
+import { randomUUID as randomUUID2 } from "crypto";
+
+// src/chat/chat-system-prompt.ts
+function buildChatSystemPrompt(opts) {
+  const lines = [
+    "You are Remnic Chat \u2014 a conversational memory inspector and corrector.",
+    "You help the user understand, explore, and fix what Remnic remembers.",
+    "",
+    "## Core rules",
+    "",
+    "1. GROUND EVERY ASSERTION. When you state what Remnic remembers, you MUST",
+    "   cite the memory id or handle, include the source quote, and the date.",
+    "   If no tool result in this turn supports the claim, say",
+    '   "I found nothing" instead of guessing.',
+    "",
+    "2. NO MUTATION WITHOUT CONFIRMATION. You may propose a correction plan",
+    "   (correction_plan), but you must NEVER apply it (correction_apply) until",
+    "   the user explicitly confirms in the conversation.",
+    "",
+    "3. RENDER PLANS AS DIFFS. When you surface a correction plan, render it",
+    "   as the diff preview the plan returns \u2014 before/after, affected memory",
+    "   ids, and the supersession reason.",
+    "",
+    "4. BE HONEST ABOUT LIMITS. If a tool returns no results, say so. If you",
+    "   are unsure, say so. Never fabricate memory content.",
+    "",
+    "5. RESPECT SCOPE. You operate within the caller's namespace and principal.",
+    "   Do not attempt to access memories outside the caller's scope."
+  ];
+  if (opts.correctionAvailable) {
+    lines.push(
+      "",
+      "## Mutation protocol",
+      "",
+      "When the user asks to change or forget memories:",
+      "1. Call correction_plan to generate a diff preview.",
+      "2. Present the diff to the user and ask them to reply 'apply' to confirm.",
+      "3. Only after explicit confirmation, call correction_apply.",
+      "",
+      "For bulk/destructive requests ('forget everything about X'), always go",
+      "through correction_plan first \u2014 there is no direct-delete tool."
+    );
+  } else {
+    lines.push(
+      "",
+      "## Mutation status",
+      "",
+      "Correction (mutation) tools are not yet available in this build.",
+      "You can inspect and search memories but cannot apply corrections.",
+      "When the user asks to change memories, explain that correction tools",
+      "require the Correction Contract (#1580) which is pending."
+    );
+  }
+  return lines.join("\n");
+}
+
+// src/chat/chat-tools.ts
+var MUTATING_TOOLS = /* @__PURE__ */ new Set([
+  "correction_apply",
+  "memory_promote"
+]);
+var MEMORY_SEARCH_SCHEMA = {
+  type: "function",
+  function: {
+    name: "memory_search",
+    description: "Semantic search across stored memories. Returns matching memory paths, scores, and snippets. Use this to find what Remnic remembers about a topic.",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "The search query." },
+        maxResults: { type: "number", description: "Maximum results (default 8)." }
+      },
+      required: ["query"],
+      additionalProperties: false
+    }
+  }
+};
+var MEMORY_GET_SCHEMA = {
+  type: "function",
+  function: {
+    name: "memory_get",
+    description: "Fetch a single memory by its id. Returns the full memory content, category, tags, and source attribution.",
+    parameters: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "The memory id to fetch." }
+      },
+      required: ["memoryId"],
+      additionalProperties: false
+    }
+  }
+};
+var MEMORY_TIMELINE_SCHEMA = {
+  type: "function",
+  function: {
+    name: "memory_timeline",
+    description: "Read the lifecycle timeline of a single memory \u2014 creation, updates, consolidations, and tier transitions.",
+    parameters: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "The memory id." },
+        limit: { type: "number", description: "Maximum rows (default 200)." }
+      },
+      required: ["memoryId"],
+      additionalProperties: false
+    }
+  }
+};
+var RECALL_EXPLAIN_SCHEMA = {
+  type: "function",
+  function: {
+    name: "recall_explain",
+    description: "Explain why Remnic would recall certain memories for a given query. Returns tier scoring and matching details. Use this to answer 'why did you remember this?'",
+    parameters: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Optional query to explain recall for. When omitted, explains the most recent recall." }
+      },
+      required: [],
+      additionalProperties: false
+    }
+  }
+};
+var ENTITY_GET_SCHEMA = {
+  type: "function",
+  function: {
+    name: "entity_get",
+    description: "Fetch the compiled entity record for a named entity (person, project, tool, etc.). Returns traits, timeline, and associated memories.",
+    parameters: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Entity name." }
+      },
+      required: ["name"],
+      additionalProperties: false
+    }
+  }
+};
+var STATS_SCHEMA = {
+  type: "function",
+  function: {
+    name: "stats",
+    description: "Return aggregate memory statistics \u2014 memory count, entity count, profile summary, and open questions. Use this for high-level 'what do you know?' questions.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  }
+};
+var CORRECTION_PLAN_SCHEMA = {
+  type: "function",
+  function: {
+    name: "correction_plan",
+    description: "Generate a correction plan (diff preview) for a requested memory change. This does NOT apply the change \u2014 it previews what would happen. The user must confirm before correction_apply runs.",
+    parameters: {
+      type: "object",
+      properties: {
+        request: {
+          type: "string",
+          description: "Natural-language description of the correction, e.g. 'we finished the MySQL migration in March' or 'forget the outdated database credentials'."
+        }
+      },
+      required: ["request"],
+      additionalProperties: false
+    }
+  }
+};
+var CORRECTION_APPLY_SCHEMA = {
+  type: "function",
+  function: {
+    name: "correction_apply",
+    description: "Apply a previously generated correction plan. The engine intercepts this call and requires explicit user confirmation before it executes.",
+    parameters: {
+      type: "object",
+      properties: {
+        planId: { type: "string", description: "The plan id from correction_plan." }
+      },
+      required: ["planId"],
+      additionalProperties: false
+    }
+  }
+};
+var MEMORY_PROMOTE_SCHEMA = {
+  type: "function",
+  function: {
+    name: "memory_promote",
+    description: "Promote a memory's tier (e.g. from cold to hot). The engine requires user confirmation before executing.",
+    parameters: {
+      type: "object",
+      properties: {
+        memoryId: { type: "string", description: "The memory id to promote." }
+      },
+      required: ["memoryId"],
+      additionalProperties: false
+    }
+  }
+};
+var REVIEW_LIST_SCHEMA = {
+  type: "function",
+  function: {
+    name: "review_list",
+    description: "List items in the contradiction/quality review queue. Returns pairs of potentially conflicting memories awaiting resolution.",
+    parameters: {
+      type: "object",
+      properties: {
+        runId: { type: "string", description: "Optional governance run id." }
+      },
+      additionalProperties: false
+    }
+  }
+};
+var SCOPE_INSPECT_SCHEMA = {
+  type: "function",
+  function: {
+    name: "scope_inspect",
+    description: "Inspect the current scope/namespace resolution \u2014 which namespace the chat session operates in and how it was resolved.",
+    parameters: {
+      type: "object",
+      properties: {},
+      additionalProperties: false
+    }
+  }
+};
+var READONLY_SCHEMAS = [
+  MEMORY_SEARCH_SCHEMA,
+  MEMORY_GET_SCHEMA,
+  MEMORY_TIMELINE_SCHEMA,
+  RECALL_EXPLAIN_SCHEMA,
+  ENTITY_GET_SCHEMA,
+  STATS_SCHEMA,
+  REVIEW_LIST_SCHEMA
+];
+function buildChatToolSchemas(opts) {
+  const tools = [...READONLY_SCHEMAS];
+  if (opts.correctionAvailable) {
+    tools.push(CORRECTION_PLAN_SCHEMA, CORRECTION_APPLY_SCHEMA, MEMORY_PROMOTE_SCHEMA);
+  }
+  if (opts.scopeInspectAvailable) {
+    tools.push(SCOPE_INSPECT_SCHEMA);
+  }
+  return tools;
+}
+
+// src/chat/chat-engine.ts
+var CONFIRMATION_KEYWORDS = /* @__PURE__ */ new Set(["yes", "y", "apply", "confirm"]);
+function isConfirmationMessage(text) {
+  return CONFIRMATION_KEYWORDS.has(text.trim().toLowerCase());
+}
+var ChatEngine = class {
+  llm;
+  executor;
+  maxToolCallsPerTurn;
+  model;
+  correctionAvailable;
+  scopeInspectAvailable;
+  systemPrompt;
+  toolSchemas;
+  allowedToolNames;
+  constructor(opts) {
+    this.llm = opts.llm;
+    this.executor = opts.executor;
+    this.maxToolCallsPerTurn = opts.maxToolCallsPerTurn;
+    this.model = opts.model;
+    this.correctionAvailable = opts.correctionAvailable;
+    this.scopeInspectAvailable = opts.scopeInspectAvailable;
+    this.systemPrompt = buildChatSystemPrompt({
+      correctionAvailable: opts.correctionAvailable
+    });
+    this.toolSchemas = buildChatToolSchemas({
+      correctionAvailable: opts.correctionAvailable,
+      scopeInspectAvailable: opts.scopeInspectAvailable
+    });
+    this.allowedToolNames = new Set(this.toolSchemas.map((t) => t.function.name));
+  }
+  /**
+   * Process a single user message.  The session state is mutated in place
+   * (confirmedPlanIds, pendingPlanId) — the caller persists the transcript.
+   */
+  async processMessage(userMessage, session) {
+    if (isConfirmationMessage(userMessage) && this.correctionAvailable) {
+      if (session.pendingPlanId) {
+        const planId = session.pendingPlanId;
+        session.confirmedPlanIds.add(planId);
+        session.pendingPlanId = void 0;
+        try {
+          const applyResult = await this.executor.correctionApply(planId);
+          session.confirmedPlanIds.delete(planId);
+          return {
+            reply: `Correction applied.
+
+${applyResult}`,
+            chatSessionId: session.id,
+            ...session.pendingPromotionId ? {} : {}
+          };
+        } catch (err) {
+          session.confirmedPlanIds.delete(planId);
+          session.pendingPlanId = planId;
+          const msg = err instanceof Error ? err.message : String(err);
+          return {
+            reply: "[error] Failed to apply the correction. Please try again or re-request the plan.",
+            chatSessionId: session.id,
+            error: msg
+          };
+        }
+      }
+      if (session.pendingPromotionId) {
+        const memoryId = session.pendingPromotionId;
+        session.pendingPromotionId = void 0;
+        try {
+          const promoteResult = await this.executor.memoryPromote(memoryId);
+          return {
+            reply: `Memory promoted.
+
+${promoteResult}`,
+            chatSessionId: session.id
+          };
+        } catch (err) {
+          session.pendingPromotionId = memoryId;
+          const msg = err instanceof Error ? err.message : String(err);
+          return {
+            reply: "[error] Failed to promote the memory. Please try again.",
+            chatSessionId: session.id,
+            error: msg
+          };
+        }
+      }
+    }
+    const recentEntries = session.transcript.slice(-21).filter((e) => e.role !== "system" || e.seq !== 0).filter((e) => !(e.role === "system" && /^[a-z_]+:/.test(e.content))).filter((e, _i, arr) => {
+      if (e.role === "user" && e.content === userMessage) {
+        const lastUser = [...arr].reverse().find((x) => x.role === "user");
+        return e !== lastUser;
+      }
+      return true;
+    });
+    const conversation = [
+      { role: "system", content: this.systemPrompt },
+      ...recentEntries.map((e) => ({
+        role: e.role,
+        content: e.content,
+        ...e.toolCallId ? { toolCallId: e.toolCallId } : {}
+      })),
+      { role: "user", content: userMessage }
+    ];
+    let toolCallCount = 0;
+    const skippedTools = [];
+    let pendingPlan;
+    for (; ; ) {
+      let response;
+      try {
+        response = await this.llm.complete(conversation, {
+          tools: this.toolSchemas,
+          ...this.model ? { model: this.model } : {}
+        });
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+          reply: "[error] The model request failed. Check your model configuration and retry.",
+          chatSessionId: session.id,
+          error: msg
+        };
+      }
+      if (!response) {
+        return {
+          reply: "[error] No LLM model is available. Configure a local or cloud model to use Remnic Chat.",
+          chatSessionId: session.id,
+          error: "no_llm_available"
+        };
+      }
+      if (response.toolCalls.length === 0) {
+        let reply = response.content;
+        if (toolCallCount === 0 && looksLikeMemoryAssertion(reply)) {
+          reply += "\n\n\u26A0\uFE0F The above assertion was not grounded in a tool result this turn. Please verify with memory_search or memory_get.";
+        }
+        return {
+          reply,
+          chatSessionId: session.id,
+          ...pendingPlan ? { pendingPlan } : {},
+          ...skippedTools.length > 0 ? { skippedTools } : {}
+        };
+      }
+      conversation.push({ role: "assistant", content: response.content });
+      for (const tc of response.toolCalls) {
+        if (toolCallCount >= this.maxToolCallsPerTurn) {
+          skippedTools.push(tc.name);
+          continue;
+        }
+        toolCallCount++;
+        if (!this.allowedToolNames.has(tc.name)) {
+          conversation.push({
+            role: "tool",
+            content: JSON.stringify({ error: `Tool '${tc.name}' is not available in this configuration.` }),
+            toolCallId: tc.id
+          });
+          continue;
+        }
+        if (MUTATING_TOOLS.has(tc.name)) {
+          if (tc.name === "correction_apply") {
+            const planId = typeof tc.arguments.planId === "string" ? tc.arguments.planId : "";
+            if (!session.confirmedPlanIds.has(planId)) {
+              try {
+                const plan = await this.executor.correctionPlan(
+                  `retrieve plan ${planId}`
+                );
+                pendingPlan = { planId, preview: plan.preview };
+                session.pendingPlanId = planId;
+                conversation.push({
+                  role: "tool",
+                  content: JSON.stringify({
+                    intercepted: true,
+                    message: "This mutation requires confirmation. The plan preview has been shown to the user."
+                  }),
+                  toolCallId: tc.id
+                });
+                return {
+                  reply: formatPlanPreview(plan.preview),
+                  chatSessionId: session.id,
+                  pendingPlan
+                };
+              } catch {
+                conversation.push({
+                  role: "tool",
+                  content: JSON.stringify({ error: "Plan not found or expired." }),
+                  toolCallId: tc.id
+                });
+                continue;
+              }
+            }
+            session.confirmedPlanIds.delete(planId);
+          }
+        }
+        if (tc.name === "memory_promote" && this.correctionAvailable) {
+          const memoryId = typeof tc.arguments.memoryId === "string" ? tc.arguments.memoryId : "";
+          session.pendingPromotionId = memoryId;
+          conversation.push({
+            role: "tool",
+            content: JSON.stringify({
+              intercepted: true,
+              message: `Memory promotion requires confirmation. Reply 'apply' to promote memory '${memoryId}'.`
+            }),
+            toolCallId: tc.id
+          });
+          return {
+            reply: `I want to promote memory \`${memoryId}\`. Reply **apply** to confirm this promotion, or **cancel** to discard it.`,
+            chatSessionId: session.id
+          };
+        }
+        let result;
+        try {
+          result = await this.executeTool(tc.name, tc.arguments, session);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          result = { content: JSON.stringify({ error: msg }) };
+        }
+        conversation.push({
+          role: "tool",
+          content: result.content,
+          toolCallId: tc.id
+        });
+        if (tc.name === "correction_plan" && this.correctionAvailable) {
+          try {
+            const parsed = JSON.parse(result.content);
+            if (parsed.planId && parsed.preview) {
+              pendingPlan = { planId: parsed.planId, preview: parsed.preview };
+              session.pendingPlanId = parsed.planId;
+            }
+          } catch {
+          }
+        }
+      }
+      if (skippedTools.length > 0) {
+        conversation.push({
+          role: "user",
+          content: `[system] Tool budget exhausted (${this.maxToolCallsPerTurn} calls). ${skippedTools.length} tool(s) were skipped: ${skippedTools.join(", ")}. Please summarize what you found.`
+        });
+        let summaryResponse;
+        try {
+          summaryResponse = await this.llm.complete(conversation, {
+            tools: [],
+            // No more tools — force a text reply.
+            ...this.model ? { model: this.model } : {}
+          });
+        } catch {
+          summaryResponse = null;
+        }
+        const summaryText = summaryResponse?.content ?? "I reached my tool-call budget. Here is what I found so far, but some queries were skipped.";
+        return {
+          reply: summaryText,
+          chatSessionId: session.id,
+          ...pendingPlan ? { pendingPlan } : {},
+          skippedTools
+        };
+      }
+    }
+  }
+  /**
+   * Execute a single tool by name, delegating to the executor.
+   */
+  async executeTool(name, args, _session) {
+    switch (name) {
+      case "memory_search": {
+        const query = typeof args.query === "string" ? args.query : "";
+        const maxResults = typeof args.maxResults === "number" ? args.maxResults : void 0;
+        return { content: await this.executor.memorySearch(query, maxResults) };
+      }
+      case "memory_get": {
+        const memoryId = typeof args.memoryId === "string" ? args.memoryId : "";
+        return { content: await this.executor.memoryGet(memoryId) };
+      }
+      case "memory_timeline": {
+        const memoryId = typeof args.memoryId === "string" ? args.memoryId : "";
+        const limit = typeof args.limit === "number" ? args.limit : void 0;
+        return { content: await this.executor.memoryTimeline(memoryId, limit) };
+      }
+      case "recall_explain": {
+        const query = typeof args.query === "string" ? args.query : "";
+        return { content: await this.executor.recallExplain(query) };
+      }
+      case "entity_get": {
+        const entityName = typeof args.name === "string" ? args.name : "";
+        return { content: await this.executor.entityGet(entityName) };
+      }
+      case "stats": {
+        return { content: await this.executor.stats() };
+      }
+      case "correction_plan": {
+        const request = typeof args.request === "string" ? args.request : "";
+        const plan = await this.executor.correctionPlan(request);
+        return { content: JSON.stringify(plan) };
+      }
+      case "correction_apply": {
+        const planId = typeof args.planId === "string" ? args.planId : "";
+        return { content: await this.executor.correctionApply(planId) };
+      }
+      case "memory_promote": {
+        const memoryId = typeof args.memoryId === "string" ? args.memoryId : "";
+        return { content: await this.executor.memoryPromote(memoryId) };
+      }
+      case "review_list": {
+        const runId = typeof args.runId === "string" ? args.runId : void 0;
+        return { content: await this.executor.reviewList(runId) };
+      }
+      case "scope_inspect": {
+        return { content: await this.executor.scopeInspect() };
+      }
+      default:
+        return { content: JSON.stringify({ error: `Unknown tool: ${name}` }) };
+    }
+  }
+};
+function looksLikeMemoryAssertion(text) {
+  const lower = text.toLowerCase();
+  const assertionPhrases = [
+    "you remember",
+    "i remember",
+    "according to my memory",
+    "your memory",
+    "stored memory",
+    "remnic remembers",
+    "remnic knows"
+  ];
+  const hasAssertion = assertionPhrases.some((p) => lower.includes(p));
+  const hasCitation = lower.includes("[id:") || lower.includes("memory id") || lower.includes("source:");
+  return hasAssertion && !hasCitation;
+}
+function formatPlanPreview(preview) {
+  return [
+    "Here is the correction plan I generated:",
+    "",
+    "```diff",
+    preview,
+    "```",
+    "",
+    "Reply **apply** to confirm and apply this correction.",
+    "Reply **cancel** to discard it."
+  ].join("\n");
+}
+
+// src/chat/chat-llm.ts
+function createProductionChatLlmAdapter(client) {
+  return {
+    async complete(messages, options) {
+      const toolInstruction = formatToolInstruction(options.tools);
+      const mapped = messages.map((m) => {
+        if (m.role === "system") {
+          return { role: m.role, content: m.content + "\n\n" + toolInstruction };
+        }
+        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
+      };
+    }
+  };
+}
+function formatToolInstruction(tools) {
+  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");
+}
+function parseToolCalls(content) {
+  const calls = [];
+  const patterns = [
+    /```json\s*\n([\s\S]*?)\n```/g,
+    /```\s*\n([\s\S]*?)\n```/g
+  ];
+  const candidates = [];
+  for (const pattern of patterns) {
+    let match;
+    while ((match = pattern.exec(content)) !== null) {
+      candidates.push(match[1]);
+    }
+  }
+  for (const line of content.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed.startsWith("{") && trimmed.includes('"tool"')) {
+      candidates.push(trimmed);
+    }
+  }
+  const seen = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (typeof parsed.tool === "string" && parsed.tool.length > 0) {
+        const args = parsed.arguments ?? {};
+        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 {
+    }
+  }
+  return calls;
+}
+function stripToolCallJson(content, toolCalls) {
+  if (toolCalls.length === 0) return content;
+  let result = content;
+  result = result.replace(/```json\s*\n[\s\S]*?\n```/g, "");
+  result = result.replace(/```\s*\n[\s\S]*?\n```/g, "");
+  result = result.split("\n").filter((line) => {
+    const trimmed = line.trim();
+    return !(trimmed.startsWith("{") && trimmed.includes('"tool"'));
+  }).join("\n");
+  return result.trim();
+}
+
+// src/chat/chat-executor.ts
+function createChatExecutor(bindings) {
+  const { service, principal, namespace, sessionKey } = bindings;
+  return {
+    async memorySearch(query, maxResults) {
+      const result = await service.memorySearch({
+        query,
+        ...namespace ? { namespace } : {},
+        ...maxResults !== void 0 ? { maxResults } : {},
+        ...principal ? { principal } : {}
+      });
+      return JSON.stringify(result);
+    },
+    async memoryGet(memoryId) {
+      const result = await service.memoryGet(memoryId, namespace, principal, sessionKey);
+      return JSON.stringify(result);
+    },
+    async memoryTimeline(memoryId, limit) {
+      const result = await service.memoryTimeline(memoryId, namespace, limit ?? 200, principal);
+      return JSON.stringify(result);
+    },
+    async recallExplain(query) {
+      const result = await service.recallExplain({
+        ...sessionKey ? { sessionKey } : {},
+        ...namespace ? { namespace } : {},
+        ...principal ? { authenticatedPrincipal: principal } : {},
+        ...query ? { query } : {}
+      });
+      return JSON.stringify(result);
+    },
+    async entityGet(name) {
+      const result = await service.entityGet(name, namespace);
+      return JSON.stringify(result);
+    },
+    async stats() {
+      const [profile, entities, questions] = await Promise.all([
+        service.memoryProfile(namespace, principal),
+        service.memoryEntitiesList(namespace, principal),
+        service.memoryQuestions(namespace, principal)
+      ]);
+      return JSON.stringify({ profile, entities, questions });
+    },
+    async reviewList(runId) {
+      const result = await service.reviewQueue(runId, namespace, principal);
+      return JSON.stringify(result);
+    },
+    async scopeInspect() {
+      return JSON.stringify({
+        namespace: namespace ?? "default",
+        principal: principal ?? "default",
+        sessionKey: sessionKey ?? void 0
+      });
+    },
+    // ── Correction tools — stubbed until #1580 merges ──────────────────
+    // When the Correction Contract lands, replace these stubs with calls to
+    // the correction module's plan/apply interface.  The engine, CLI, and
+    // MCP tool all consume this interface, so the stub-to-real swap is a
+    // single-file change here.
+    async correctionPlan(request) {
+      return {
+        planId: `stub-${Date.now()}`,
+        preview: `[Correction Contract (#1580) not yet available]
+
+Requested correction: "${request}"
+
+The plan/apply pipeline is pending. Inspection tools are fully functional.`
+      };
+    },
+    async correctionApply(planId) {
+      return JSON.stringify({
+        applied: false,
+        planId,
+        reason: "Correction Contract (#1580) not yet available. No mutation was applied."
+      });
+    },
+    async memoryPromote(memoryId) {
+      try {
+        const serviceWithPromote = service;
+        if (typeof serviceWithPromote.memoryPromote === "function") {
+          const result = await serviceWithPromote.memoryPromote(memoryId, namespace, principal);
+          return JSON.stringify(result);
+        }
+      } catch {
+      }
+      return JSON.stringify({
+        promoted: false,
+        memoryId,
+        reason: "Memory promotion is not available in this build."
+      });
+    }
+  };
+}
+
+// src/chat/chat-session.ts
+import { mkdir, readFile, appendFile, readdir, stat, unlink } from "fs/promises";
+import { join } from "path";
 import { randomUUID } from "crypto";
+var CHAT_DIR_NAME = "state/chat";
+function chatSessionDir(memoryDir) {
+  return join(memoryDir, CHAT_DIR_NAME);
+}
+function isSafeChatSessionId(chatSessionId) {
+  return /^[A-Za-z0-9]{8,128}$/.test(chatSessionId.replace(/-/g, ""));
+}
+function chatSessionFile(memoryDir, chatSessionId) {
+  if (!isSafeChatSessionId(chatSessionId)) {
+    throw new Error("Invalid chat session id");
+  }
+  return join(chatSessionDir(memoryDir), `${chatSessionId}.jsonl`);
+}
+async function createChatSession(memoryDir, opts) {
+  const id = randomUUID();
+  const now = (/* @__PURE__ */ new Date()).toISOString();
+  const state = {
+    id,
+    principal: opts.principal,
+    sessionKey: opts.sessionKey,
+    namespace: opts.namespace,
+    transcript: [],
+    confirmedPlanIds: /* @__PURE__ */ new Set(),
+    createdAt: now
+  };
+  await mkdir(chatSessionDir(memoryDir), { recursive: true });
+  await appendFile(
+    chatSessionFile(memoryDir, id),
+    JSON.stringify({
+      seq: 0,
+      ts: now,
+      role: "system",
+      content: `Chat session created. Principal: ${opts.principal ?? "default"}. Namespace: ${opts.namespace ?? "default"}. work_task: Excluded from memory extraction`,
+      // Structured binding fields so loadChatSession doesn't need to regex-parse
+      // prose (robust against dotted principals like alice@example.com).
+      ...opts.principal ? { principal: opts.principal } : {},
+      ...opts.namespace ? { namespace: opts.namespace } : {},
+      ...opts.sessionKey ? { sessionKey: opts.sessionKey } : {}
+    }) + "\n",
+    "utf8"
+  );
+  return state;
+}
+async function loadChatSession(memoryDir, chatSessionId) {
+  let raw;
+  try {
+    raw = await readFile(chatSessionFile(memoryDir, chatSessionId), "utf8");
+  } catch {
+    return null;
+  }
+  const lines = raw.split("\n").filter((l) => l.trim().length > 0);
+  const transcript = [];
+  let principal;
+  let sessionKey;
+  let namespace;
+  let createdAt = "";
+  let pendingPlanId;
+  let pendingPromotionId;
+  for (const line of lines) {
+    try {
+      const entry = JSON.parse(line);
+      transcript.push(entry);
+      if (entry.role === "system" && entry.seq === 0) {
+        const metaPrincipal = typeof entry.principal === "string" ? entry.principal : void 0;
+        const metaNamespace = typeof entry.namespace === "string" ? entry.namespace : void 0;
+        const metaSessionKey = typeof entry.sessionKey === "string" ? entry.sessionKey : void 0;
+        if (metaPrincipal) principal = metaPrincipal;
+        else {
+          const pMatch = entry.content.match(/Principal: (.+?)\.\s/);
+          if (pMatch) principal = pMatch[1]?.trim() === "default" ? void 0 : pMatch[1]?.trim();
+        }
+        if (metaNamespace) namespace = metaNamespace;
+        else {
+          const nsMatch = entry.content.match(/Namespace: (.+?)\.\s/);
+          if (nsMatch) namespace = nsMatch[1]?.trim() === "default" ? void 0 : nsMatch[1]?.trim();
+        }
+        if (metaSessionKey) sessionKey = metaSessionKey;
+        createdAt = entry.ts;
+      }
+      if (entry.role === "system") {
+        const pm = entry.content.match(/^pending_plan:(.+)$/);
+        if (pm) pendingPlanId = pm[1];
+        const pp = entry.content.match(/^pending_promotion:(.+)$/);
+        if (pp) pendingPromotionId = pp[1];
+        const resolved = entry.content.match(/^(plan_applied|plan_cancelled|promotion_applied|promotion_cancelled):/);
+        if (resolved) {
+          if (entry.content.startsWith("plan_")) {
+            pendingPlanId = void 0;
+          }
+          if (entry.content.startsWith("promotion_")) {
+            pendingPromotionId = void 0;
+          }
+        }
+      }
+    } catch {
+    }
+  }
+  return {
+    id: chatSessionId,
+    principal,
+    sessionKey,
+    namespace,
+    transcript,
+    confirmedPlanIds: /* @__PURE__ */ new Set(),
+    ...pendingPlanId ? { pendingPlanId } : {},
+    ...pendingPromotionId ? { pendingPromotionId } : {},
+    createdAt
+  };
+}
+async function appendTranscriptEntry(memoryDir, chatSessionId, entry) {
+  const full = {
+    ...entry,
+    seq: Date.now(),
+    ts: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  await appendFile(
+    chatSessionFile(memoryDir, chatSessionId),
+    JSON.stringify(full) + "\n",
+    "utf8"
+  );
+  return full;
+}
+async function markPendingPlan(memoryDir, chatSessionId, planId) {
+  await appendTranscriptEntry(memoryDir, chatSessionId, {
+    role: "system",
+    content: `pending_plan:${planId}`
+  });
+}
+async function markPendingPromotion(memoryDir, chatSessionId, memoryId) {
+  await appendTranscriptEntry(memoryDir, chatSessionId, {
+    role: "system",
+    content: `pending_promotion:${memoryId}`
+  });
+}
+async function markPlanResolved(memoryDir, chatSessionId, planId) {
+  await appendTranscriptEntry(memoryDir, chatSessionId, {
+    role: "system",
+    content: `plan_applied:${planId}`
+  });
+}
+async function markPromotionResolved(memoryDir, chatSessionId, memoryId) {
+  await appendTranscriptEntry(memoryDir, chatSessionId, {
+    role: "system",
+    content: `promotion_applied:${memoryId}`
+  });
+}
+function sessionBelongsToPrincipal(session, principal) {
+  if (!session.principal) return true;
+  return session.principal === principal;
+}
+
+// src/chat/chat-factory.ts
+function createChatEngine(opts) {
+  const llmClient = opts.fallbackLlm ?? opts.localLlm;
+  if (!llmClient) return null;
+  const adapter = createProductionChatLlmAdapter(llmClient);
+  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
+  });
+}
+async function processChatMessage(opts) {
+  if (!opts.config?.enabled) {
+    throw new Error("chat_disabled");
+  }
+  if (!opts.service.fallbackLlmRef && !opts.service.localLlmRef) {
+    throw new Error("no_llm_available");
+  }
+  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,
+    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
+  });
+  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
+  });
+  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) {
+    await markPlanResolved(opts.memoryDir, session.id, priorPendingPlanId);
+  } else if (priorPendingPromotionId && !session.pendingPromotionId) {
+    await markPromotionResolved(opts.memoryDir, session.id, priorPendingPromotionId);
+  }
+  return result;
+}
+
+// src/access-mcp.ts
 var MCP_PROTOCOL_VERSION = "2024-11-05";
 var LEGACY_MCP_PREFIX = "engram.";
 var CANONICAL_MCP_PREFIX = "remnic.";
@@ -81,7 +1085,7 @@ var MCP_MIGRATED_OPERATIONS = {
 function resolveChatGptInspectorRecallSessionKey(explicitSessionKey, authenticatedPrincipal) {
   if (explicitSessionKey) return explicitSessionKey;
   if (!authenticatedPrincipal) return void 0;
-  return `remnic:chatgpt-memory-inspector:${randomUUID()}`;
+  return `remnic:chatgpt-memory-inspector:${randomUUID2()}`;
 }
 var STRICT_MCP_SCHEMA_KEYS = {
   daySummary: [
@@ -202,7 +1206,7 @@ async function getMcpServerVersion() {
   if (envVersion) return envVersion;
   try {
     const pkgPath = new URL("../package.json", import.meta.url);
-    const raw = await readFile(pkgPath, "utf-8");
+    const raw = await readFile2(pkgPath, "utf-8");
     const parsed = JSON.parse(raw);
     return parsed.version?.trim() || "unknown";
   } catch {
@@ -220,6 +1224,7 @@ var EngramMcpServer = class {
     this.codegraphVisible = options.codegraphVisible === true;
     this.sessionDeltaVisible = options.sessionDeltaVisible === true;
     this.correctionVisible = options.correctionVisible !== false;
+    this.chatVisible = options.chatVisible === true;
     this.authenticatedPrincipal = options.principal?.trim() || readEnvVar("OPENCLAW_ENGRAM_ACCESS_PRINCIPAL")?.trim() || void 0;
     this.resources = [
       {
@@ -806,7 +1811,12 @@ var EngramMcpServer = class {
           type: "object",
           properties: {
             memoryId: { type: "string" },
-            namespace: { 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
@@ -960,6 +1970,10 @@ var EngramMcpServer = class {
               },
               description: "Conversation messages to observe"
             },
+            idempotencyKey: {
+              type: "string",
+              description: "Optional idempotency key (issue #1649). Deduplicates a retried observe POST server-side so the batch is ingested once even when the HTTP response is lost. Reusing the key with a different payload is rejected."
+            },
             namespace: { type: "string" },
             skipExtraction: { type: "boolean" },
             cwd: { type: "string", description: "Working directory for auto git-context resolution." },
@@ -1988,6 +3002,25 @@ var EngramMcpServer = class {
       );
       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 \u2014 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];
+    }
   }
   service;
   buffer = Buffer.alloc(0);
@@ -2049,6 +3082,12 @@ var EngramMcpServer = class {
    * byte-identical to pre-feature.
    */
   correctionVisible;
+  /**
+   * 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).
+   */
+  chatVisible;
   /** Get clientInfo for a specific MCP session. Returns undefined for non-MCP requests. */
   getClientInfo(sessionId) {
     if (sessionId) {
@@ -2072,7 +3111,7 @@ var EngramMcpServer = class {
     if (method === "initialize") {
       const params = request.params ?? {};
       const rawClientInfo = params.clientInfo;
-      const newSessionId = randomUUID();
+      const newSessionId = randomUUID2();
       if (rawClientInfo && typeof rawClientInfo.name === "string") {
         const info = { name: rawClientInfo.name, version: rawClientInfo.version };
         this.clientInfoBySession.set(newSessionId, info);
@@ -2186,7 +3225,11 @@ var EngramMcpServer = class {
           argumentsObject = { ...argumentsObject, sessionKey: options.sessionKeyOverride };
         }
         const effectivePrincipal = options?.principalOverride ?? this.authenticatedPrincipal;
-        const result = await this.callTool(name, argumentsObject, effectivePrincipal, options?.sessionId);
+        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,
@@ -2351,7 +3394,7 @@ ${body}`;
       noteDefault: r.preview?.slice(0, 60) || r.id
     }));
   }
-  async callTool(name, args, effectivePrincipal, mcpSessionId) {
+  async callTool(name, args, effectivePrincipal, mcpSessionId, scope, enforceWriteQuota) {
     const migrated = MCP_MIGRATED_OPERATIONS[toLegacyToolName(name)];
     if (migrated) {
       const op = getOperation(migrated);
@@ -2596,7 +3639,7 @@ ${body}`;
         }
         let currentContextScopes;
         if (args.currentContextScopes !== void 0 && args.currentContextScopes !== null) {
-          if (!Array.isArray(args.currentContextScopes) || !args.currentContextScopes.every((scope) => typeof scope === "string")) {
+          if (!Array.isArray(args.currentContextScopes) || !args.currentContextScopes.every((scope2) => typeof scope2 === "string")) {
             throw new EngramAccessInputError(
               "currentContextScopes must be an array of strings"
             );
@@ -2773,21 +3816,27 @@ ${body}`;
         );
       case "engram.observe": {
         const body = parseMcpRequest("observe", args);
-        return this.service.observe({
-          sessionKey: body.sessionKey,
-          messages: body.messages.map((message) => ({
-            role: message.role,
-            content: message.content,
-            parts: message.parts ?? void 0,
-            rawContent: message.rawContent ?? void 0,
-            sourceFormat: message.sourceFormat ?? void 0
-          })),
-          namespace: body.namespace,
-          authenticatedPrincipal: effectivePrincipal,
-          skipExtraction: body.skipExtraction === true,
-          cwd: body.cwd,
-          projectTag: body.projectTag
-        });
+        return this.service.observe(
+          {
+            sessionKey: body.sessionKey,
+            messages: body.messages.map((message) => ({
+              role: message.role,
+              content: message.content,
+              parts: message.parts ?? void 0,
+              rawContent: message.rawContent ?? void 0,
+              sourceFormat: message.sourceFormat ?? void 0
+            })),
+            skipExtraction: body.skipExtraction === true,
+            idempotencyKey: body.idempotencyKey,
+            namespace: body.namespace,
+            authenticatedPrincipal: effectivePrincipal,
+            cwd: body.cwd,
+            projectTag: body.projectTag
+          },
+          // Forward the transport's write-quota enforcer into observe's
+          // idempotency lock so a replay is never 429'd (issue #1649).
+          enforceWriteQuota ? { enforceWriteQuota } : void 0
+        );
       }
       case "engram.lcm_search":
         return this.service.lcmSearch({
@@ -3350,6 +4399,28 @@ ${body}`;
           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 : void 0;
+        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 } : {}
+        });
+        if (chatResult && typeof chatResult === "object" && "error" in chatResult) {
+          const { error: _stripped, ...wireResult } = chatResult;
+          return wireResult;
+        }
+        return chatResult;
+      }
       default:
         throw new Error(`unknown tool: ${name}`);
     }
@@ -3357,6 +4428,17 @@ ${body}`;
 };
 
 export {
+  ChatEngine,
+  createProductionChatLlmAdapter,
+  createChatExecutor,
+  createChatSession,
+  loadChatSession,
+  appendTranscriptEntry,
+  markPendingPlan,
+  markPendingPromotion,
+  markPlanResolved,
+  markPromotionResolved,
+  sessionBelongsToPrincipal,
   EngramMcpServer
 };
-//# sourceMappingURL=chunk-I3BT2IDW.js.map
+//# sourceMappingURL=chunk-SYDHFFAW.js.map