@remnic/core 1.1.30 → 9.3.515

package/dist/{chunk-IQT3XTKW.js → chunk-D24OXEPB.js}

@@ -39,15 +39,18 @@ function parseEntryLine(line) {
   if (!pathRaw || !startRaw || !endRaw) return null;
   const lineStart = parseInt(startRaw, 10);
   const lineEnd = parseInt(endRaw, 10);
-  if (!Number.isFinite(lineStart) || !Number.isFinite(lineEnd)) return null;
-  if (lineStart < 0 || lineEnd < 0) return null;
+  const entryPath = pathRaw.trim();
+  if (!entryPath || !isValidCitationRange(lineStart, lineEnd)) return null;
   return {
-    path: pathRaw.trim(),
+    path: entryPath,
     lineStart,
     lineEnd,
     note: noteRaw ?? ""
   };
 }
+function isValidCitationRange(lineStart, lineEnd) {
+  return Number.isInteger(lineStart) && Number.isInteger(lineEnd) && lineStart >= 1 && lineEnd >= lineStart;
+}
 function parseIds(block, openTag, closeTag) {
   const start = block.indexOf(openTag);
   if (start < 0) return null;
@@ -83,11 +86,14 @@ function formatOaiMemCitation(block) {
   ].join("\n");
 }
 function buildCitationGuidance(citations) {
-  if (citations.length === 0) return "";
-  const entryExamples = citations.map(
+  const validCitations = citations.filter(
+    (citation) => citation.path.trim().length > 0 && isValidCitationRange(citation.lineStart, citation.lineEnd)
+  );
+  if (validCitations.length === 0) return "";
+  const entryExamples = validCitations.map(
     (c) => `${c.path}:${c.lineStart}-${c.lineEnd}|note=[${sanitizeNoteForCitation(c.noteDefault)}]`
   );
-  const rolloutExamples = citations.filter((c) => c.rolloutId != null).map((c) => c.rolloutId);
+  const rolloutExamples = validCitations.filter((c) => c.rolloutId != null).map((c) => c.rolloutId);
   const seenRollouts = /* @__PURE__ */ new Set();
   const uniqueRollouts = [];
   for (const id of rolloutExamples) {
@@ -118,4 +124,4 @@ export {
   formatOaiMemCitation,
   buildCitationGuidance
 };
-//# sourceMappingURL=chunk-IQT3XTKW.js.map
+//# sourceMappingURL=chunk-D24OXEPB.js.map

package/dist/chunk-D24OXEPB.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/citations.ts"],"sourcesContent":["/**\n * OAI-mem-citation parser and formatter (issue #379).\n *\n * Mirrors the citation block format used by Codex's `citations.rs` so that\n * Remnic recall responses produce compatible citation blocks. The model\n * appends these blocks to its final reply, and downstream hooks parse them\n * to increment memory usage tracking.\n *\n * Block format:\n *\n *   <oai-mem-citation>\n *   <citation_entries>\n *   path/to/file.md:1-5|note=[short explanation]\n *   </citation_entries>\n *   <rollout_ids>\n *   rollout-abc123\n *   </rollout_ids>\n *   </oai-mem-citation>\n */\n\n/** A single citation entry referencing a memory file and line range. */\nexport interface CitationEntry {\n  path: string;\n  lineStart: number;\n  lineEnd: number;\n  note: string;\n}\n\n/** Parsed citation block containing entries and rollout/thread IDs. */\nexport interface CitationBlock {\n  entries: CitationEntry[];\n  rolloutIds: string[];\n}\n\n/** Metadata attached to a recall result for citation guidance. */\nexport interface CitationMetadata {\n  memoryId: string;\n  path: string;\n  lineStart: number;\n  lineEnd: number;\n  rolloutId?: string;\n  noteDefault: string;\n}\n\n// ---------------------------------------------------------------------------\n// Parser\n// ---------------------------------------------------------------------------\n\nconst OPEN_TAG = \"<oai-mem-citation>\";\nconst CLOSE_TAG = \"</oai-mem-citation>\";\nconst ENTRIES_OPEN = \"<citation_entries>\";\nconst ENTRIES_CLOSE = \"</citation_entries>\";\nconst ROLLOUT_OPEN = \"<rollout_ids>\";\nconst ROLLOUT_CLOSE = \"</rollout_ids>\";\n/** Legacy alias accepted during parsing (Codex historically used thread_ids). */\nconst THREAD_OPEN = \"<thread_ids>\";\nconst THREAD_CLOSE = \"</thread_ids>\";\n\n/**\n * Parse an `<oai-mem-citation>` block from arbitrary text.\n *\n * Returns `null` when no valid block is found. Malformed entry lines are\n * silently skipped; only valid lines contribute to the result. Rollout IDs\n * are deduped while preserving insertion order.\n */\nexport function parseOaiMemCitation(text: string): CitationBlock | null {\n  const openIdx = text.indexOf(OPEN_TAG);\n  if (openIdx < 0) return null;\n  const closeIdx = text.indexOf(CLOSE_TAG, openIdx + OPEN_TAG.length);\n  if (closeIdx < 0) return null;\n\n  const inner = text.slice(openIdx + OPEN_TAG.length, closeIdx);\n\n  const entries = parseEntries(inner);\n  const rolloutIds = parseIds(inner, ROLLOUT_OPEN, ROLLOUT_CLOSE)\n    ?? parseIds(inner, THREAD_OPEN, THREAD_CLOSE)\n    ?? [];\n\n  if (entries.length === 0 && rolloutIds.length === 0) return null;\n\n  return { entries, rolloutIds };\n}\n\nfunction parseEntries(block: string): CitationEntry[] {\n  const start = block.indexOf(ENTRIES_OPEN);\n  if (start < 0) return [];\n  const end = block.indexOf(ENTRIES_CLOSE, start + ENTRIES_OPEN.length);\n  if (end < 0) return [];\n\n  const raw = block.slice(start + ENTRIES_OPEN.length, end);\n  const lines = raw.split(\"\\n\").map((l) => l.trim()).filter((l) => l.length > 0);\n  const results: CitationEntry[] = [];\n  for (const line of lines) {\n    const parsed = parseEntryLine(line);\n    if (parsed) results.push(parsed);\n  }\n  return results;\n}\n\n/**\n * Parse a single citation entry line:\n *   `<path>:<line_start>-<line_end>|note=[<note>]`\n *\n * Splits on the LAST `:` before the range pattern, not the first, because\n * file paths can contain colons on some systems (e.g., Windows drive letters\n * like `C:\\` or macOS resource forks).\n */\nfunction parseEntryLine(line: string): CitationEntry | null {\n  // Match the range+note suffix anchored at the end, allowing the path prefix\n  // to contain colons. The (.+) is greedy so it consumes everything up to the\n  // LAST `:` before the `\\d+-\\d+|note=[...]` suffix.\n  const match = line.match(/^(.+):(\\d+)-(\\d+)\\|note=\\[(.*)?\\]$/);\n  if (!match) return null;\n  const [, pathRaw, startRaw, endRaw, noteRaw] = match;\n  if (!pathRaw || !startRaw || !endRaw) return null;\n  const lineStart = parseInt(startRaw, 10);\n  const lineEnd = parseInt(endRaw, 10);\n  const entryPath = pathRaw.trim();\n  if (!entryPath || !isValidCitationRange(lineStart, lineEnd)) return null;\n  return {\n    path: entryPath,\n    lineStart,\n    lineEnd,\n    note: noteRaw ?? \"\",\n  };\n}\n\nfunction isValidCitationRange(lineStart: number, lineEnd: number): boolean {\n  return (\n    Number.isInteger(lineStart) &&\n    Number.isInteger(lineEnd) &&\n    lineStart >= 1 &&\n    lineEnd >= lineStart\n  );\n}\n\nfunction parseIds(block: string, openTag: string, closeTag: string): string[] | null {\n  const start = block.indexOf(openTag);\n  if (start < 0) return null;\n  const end = block.indexOf(closeTag, start + openTag.length);\n  if (end < 0) return null;\n\n  const raw = block.slice(start + openTag.length, end);\n  const lines = raw.split(\"\\n\").map((l) => l.trim()).filter((l) => l.length > 0);\n\n  // Deduplicate preserving insertion order.\n  const seen = new Set<string>();\n  const unique: string[] = [];\n  for (const id of lines) {\n    if (!seen.has(id)) {\n      seen.add(id);\n      unique.push(id);\n    }\n  }\n  return unique.length > 0 ? unique : null;\n}\n\n// ---------------------------------------------------------------------------\n// Sanitizer\n// ---------------------------------------------------------------------------\n\n/**\n * Replace newline characters (\\n, \\r) with spaces so that note values can be\n * safely embedded in a single citation entry line without corrupting the\n * line-based parser (`parseEntryLine` splits on `\\n`).\n */\nexport function sanitizeNoteForCitation(note: string): string {\n  return note.replace(/[\\r\\n]+/g, \" \").trim();\n}\n\n// ---------------------------------------------------------------------------\n// Formatter\n// ---------------------------------------------------------------------------\n\n/**\n * Format a `CitationBlock` into the canonical `<oai-mem-citation>` XML block.\n */\nexport function formatOaiMemCitation(block: CitationBlock): string {\n  const entryLines = block.entries\n    .map((e) => `${e.path}:${e.lineStart}-${e.lineEnd}|note=[${sanitizeNoteForCitation(e.note)}]`)\n    .join(\"\\n\");\n  const idLines = block.rolloutIds.join(\"\\n\");\n\n  return [\n    OPEN_TAG,\n    ENTRIES_OPEN,\n    entryLines,\n    ENTRIES_CLOSE,\n    ROLLOUT_OPEN,\n    idLines,\n    ROLLOUT_CLOSE,\n    CLOSE_TAG,\n  ].join(\"\\n\");\n}\n\n// ---------------------------------------------------------------------------\n// Guidance builder\n// ---------------------------------------------------------------------------\n\n/**\n * Build the citation guidance text appended to recall responses so that the\n * model knows how to emit a citation block in its reply.\n *\n * Returns an empty string when `citations` is empty (no guidance needed).\n */\nexport function buildCitationGuidance(citations: CitationMetadata[]): string {\n  const validCitations = citations.filter((citation) =>\n    citation.path.trim().length > 0 &&\n    isValidCitationRange(citation.lineStart, citation.lineEnd)\n  );\n  if (validCitations.length === 0) return \"\";\n\n  const entryExamples = validCitations.map((c) =>\n    `${c.path}:${c.lineStart}-${c.lineEnd}|note=[${sanitizeNoteForCitation(c.noteDefault)}]`,\n  );\n  const rolloutExamples = validCitations\n    .filter((c) => c.rolloutId != null)\n    .map((c) => c.rolloutId!);\n\n  // Dedupe rollout IDs preserving order.\n  const seenRollouts = new Set<string>();\n  const uniqueRollouts: string[] = [];\n  for (const id of rolloutExamples) {\n    if (!seenRollouts.has(id)) {\n      seenRollouts.add(id);\n      uniqueRollouts.push(id);\n    }\n  }\n\n  const lines = [\n    \"\",\n    \"[Remnic citation guidance]\",\n    \"If you used any of the memories above, append the following to the END of your final reply:\",\n    OPEN_TAG,\n    ENTRIES_OPEN,\n    ...entryExamples,\n    ENTRIES_CLOSE,\n    ROLLOUT_OPEN,\n    ...uniqueRollouts,\n    ROLLOUT_CLOSE,\n    CLOSE_TAG,\n  ];\n\n  return lines.join(\"\\n\");\n}\n"],"mappings":"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","names":[]}