@mnemonik/shared 7.41.0 → 7.42.0

package/dist/contextBudget.d.ts

@@ -0,0 +1,47 @@
+export { AMBIENT_ITEM_POINTER_SOURCE } from './ambientPointer.js';
+export type ContextBudgetUnits = 'characters' | 'utf8-bytes';
+export interface ContextBudgetItem {
+    /** Exact text emitted when the item fits in full. */
+    text: string;
+    /** Stable envelope name used by continuation/not-reached pointers. */
+    name: string;
+    /** Memory identity when this item is one pointer-terminated memory precis. */
+    memoryId?: string;
+    /** Memory identities when one rendered envelope represents several memories. */
+    memoryIds?: readonly string[];
+}
+export type ContextBudgetPiece = string | ContextBudgetItem;
+export interface BudgetedContextFit {
+    value: string;
+    fullyDeliveredItems: number;
+    partialItemIndex: number | null;
+    partialUnitsDelivered: number;
+}
+/** Measure rendered context in the host's native budget unit. */
+export declare function measureContext(text: string, units?: ContextBudgetUnits): number;
+/**
+ * Compose ordered items within a fixed budget. Full items are emitted exactly;
+ * the first item that does not fit is packed by whole natural units, and all
+ * later identities share one trailing not-reached pointer.
+ */
+export declare function fitContextItems(items: readonly ContextBudgetItem[], opts: {
+    budget: number;
+    units?: ContextBudgetUnits;
+    reservedSuffix?: readonly ContextBudgetItem[];
+}): BudgetedContextFit;
+/**
+ * Turn one rendered envelope into budget items. Pointer-terminated memories
+ * retain their IDs; an unrecognised shape remains one named envelope. Callers
+ * may provide response metadata IDs for envelopes (such as JIT) whose visible
+ * wire format does not carry trailing memory pointers.
+ */
+export declare function contextItemsFromText(text: string, envelopeName: string, memoryIds?: readonly string[]): ContextBudgetItem[];
+/** Fit one rendered envelope while preserving its exact under-budget bytes. */
+export declare function fitContextText(text: string, envelopeName: string, opts: {
+    budget: number;
+    units?: ContextBudgetUnits;
+    memoryIds?: readonly string[];
+}): string;
+/** Split an ambient body into whole pointer-terminated items. */
+export declare function splitAmbientItems(body: string): string[];
+//# sourceMappingURL=contextBudget.d.ts.map

package/dist/contextBudget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextBudget.d.ts","sourceRoot":"","sources":["../src/contextBudget.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAElE,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,YAAY,CAAC;AAE7D,MAAM,WAAW,iBAAiB;IAChC,qDAAqD;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CAC/B;AAED,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,iBAAiB,CAAC;AAE5D,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAC;IACd,mBAAmB,EAAE,MAAM,CAAC;IAC5B,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,qBAAqB,EAAE,MAAM,CAAC;CAC/B;AAgCD,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,kBAAiC,GAAG,MAAM,CAE7F;AAqDD;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,SAAS,iBAAiB,EAAE,EACnC,IAAI,EAAE;IACJ,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAC3B,cAAc,CAAC,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC/C,GACA,kBAAkB,CAmEpB;AA4BD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,SAAS,GAAE,SAAS,MAAM,EAAO,GAChC,iBAAiB,EAAE,CAMrB;AAED,+EAA+E;AAC/E,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,GAClF,MAAM,CAIR;AAED,iEAAiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAExD"}

package/dist/contextBudget.js

@@ -0,0 +1,193 @@
+import { AMBIENT_ITEM_POINTER_SOURCE } from './ambientPointer.js';
+export { AMBIENT_ITEM_POINTER_SOURCE } from './ambientPointer.js';
+const JOINER = '\n\n';
+const CONTINUATION_PREFIX = '… continues: ';
+const NOT_REACHED_PREFIX = '… not reached: ';
+function itemMemoryIds(item) {
+    if (item.memoryIds && item.memoryIds.length > 0)
+        return item.memoryIds;
+    return item.memoryId ? [item.memoryId] : [];
+}
+function identity(item) {
+    const memoryIds = itemMemoryIds(item);
+    if (memoryIds.length > 0)
+        return memoryIds.map((id) => `memory_get ${id}`).join(', ');
+    return item.name.replace(/\s+/g, ' ').trim();
+}
+function continuationPointer(item) {
+    return `${CONTINUATION_PREFIX}${identity(item)}`;
+}
+function notReachedPointer(items) {
+    if (items.length === 0)
+        return null;
+    return `${NOT_REACHED_PREFIX}${items.map(identity).join(', ')}`;
+}
+function joinSections(sections) {
+    return sections
+        .filter((section) => section !== null && section.length > 0)
+        .join(JOINER);
+}
+/** Measure rendered context in the host's native budget unit. */
+export function measureContext(text, units = 'characters') {
+    return units === 'utf8-bytes' ? Buffer.byteLength(text, 'utf8') : text.length;
+}
+function withoutTerminalMemoryPointer(item) {
+    if (!item.memoryId)
+        return item.text;
+    const terminalPointer = new RegExp(`\\s*${AMBIENT_ITEM_POINTER_SOURCE}\\s*$`);
+    return item.text.replace(terminalPointer, '').trimEnd();
+}
+/**
+ * Prefer bullet lines whenever the item contains them. Text ahead of the first
+ * bullet is framing and travels with the first admitted fact. Otherwise each
+ * sentence (including a final sentence ending at end-of-item) is one unit.
+ */
+function naturalUnits(item) {
+    const text = withoutTerminalMemoryPointer(item);
+    const bulletStarts = [];
+    const bulletPattern = /(^|\n)(?=[ \t]*(?:•|[-*])[ \t]+)/g;
+    let bulletMatch;
+    while ((bulletMatch = bulletPattern.exec(text)) !== null) {
+        bulletStarts.push(bulletMatch.index + (bulletMatch[1] ?? '').length);
+        if (bulletPattern.lastIndex === bulletMatch.index)
+            bulletPattern.lastIndex += 1;
+    }
+    if (bulletStarts.length > 0) {
+        return {
+            prefix: text.slice(0, bulletStarts[0]),
+            units: bulletStarts.map((start, index) => text.slice(start, bulletStarts[index + 1])),
+        };
+    }
+    const units = [];
+    const sentenceEnd = /[.!?](?:["')\]]*)?(?=\s|$)/g;
+    let cursor = 0;
+    let sentenceMatch;
+    while ((sentenceMatch = sentenceEnd.exec(text)) !== null) {
+        const end = sentenceMatch.index + sentenceMatch[0].length;
+        units.push(text.slice(cursor, end));
+        cursor = end;
+    }
+    if (cursor < text.length)
+        units.push(text.slice(cursor));
+    return { prefix: '', units: units.filter((unit) => unit.trim().length > 0) };
+}
+function partialText(item, plan, count) {
+    const content = `${plan.prefix}${plan.units.slice(0, count).join('')}`.trimEnd();
+    return `${content}\n${continuationPointer(item)}`;
+}
+/**
+ * Compose ordered items within a fixed budget. Full items are emitted exactly;
+ * the first item that does not fit is packed by whole natural units, and all
+ * later identities share one trailing not-reached pointer.
+ */
+export function fitContextItems(items, opts) {
+    const units = opts.units ?? 'characters';
+    const suffix = opts.reservedSuffix ?? [];
+    const fullValue = [...items, ...suffix].map((item) => item.text).join(JOINER);
+    if (measureContext(fullValue, units) <= opts.budget) {
+        return {
+            value: fullValue,
+            fullyDeliveredItems: items.length,
+            partialItemIndex: null,
+            partialUnitsDelivered: 0,
+        };
+    }
+    const accepted = [];
+    for (let index = 0; index < items.length; index += 1) {
+        const item = items[index];
+        if (item === undefined)
+            continue;
+        const later = items.slice(index + 1);
+        const withFullItem = joinSections([
+            ...accepted,
+            item.text,
+            ...suffix.map((entry) => entry.text),
+            notReachedPointer(later),
+        ]);
+        if (measureContext(withFullItem, units) <= opts.budget) {
+            accepted.push(item.text);
+            continue;
+        }
+        const plan = naturalUnits(item);
+        let partialUnitsDelivered = 0;
+        for (let count = 1; count <= plan.units.length; count += 1) {
+            const candidate = joinSections([
+                ...accepted,
+                partialText(item, plan, count),
+                ...suffix.map((entry) => entry.text),
+                notReachedPointer(later),
+            ]);
+            if (measureContext(candidate, units) > opts.budget)
+                break;
+            partialUnitsDelivered = count;
+        }
+        // A one-fact excerpt reads as though it were the whole memory. Require two
+        // complete units before admitting a partial item; otherwise name it only.
+        const meaningfulMinimum = Math.min(2, plan.units.length);
+        const partialAccepted = partialUnitsDelivered >= meaningfulMinimum && partialUnitsDelivered > 0;
+        const partial = partialAccepted ? partialText(item, plan, partialUnitsDelivered) : null;
+        const unreached = partialAccepted ? later : items.slice(index);
+        return {
+            value: joinSections([
+                ...accepted,
+                partial,
+                ...suffix.map((entry) => entry.text),
+                notReachedPointer(unreached),
+            ]),
+            fullyDeliveredItems: index,
+            partialItemIndex: partialAccepted ? index : null,
+            partialUnitsDelivered: partialAccepted ? partialUnitsDelivered : 0,
+        };
+    }
+    return {
+        value: joinSections([...accepted, ...suffix.map((entry) => entry.text)]),
+        fullyDeliveredItems: items.length,
+        partialItemIndex: null,
+        partialUnitsDelivered: 0,
+    };
+}
+function parsePointerItems(body, envelopeName) {
+    const regex = new RegExp(AMBIENT_ITEM_POINTER_SOURCE, 'g');
+    const memories = [];
+    let cursor = 0;
+    let match;
+    while ((match = regex.exec(body)) !== null) {
+        const end = match.index + match[0].length;
+        const text = body.slice(cursor, end).trim();
+        const memoryId = match[1];
+        if (text.length > 0 && memoryId !== undefined) {
+            memories.push({ text, name: envelopeName, memoryId });
+        }
+        cursor = end;
+    }
+    const trailerText = body.slice(cursor).trim();
+    return {
+        memories,
+        trailer: trailerText ? { text: trailerText, name: `${envelopeName} trailer` } : null,
+    };
+}
+/**
+ * Turn one rendered envelope into budget items. Pointer-terminated memories
+ * retain their IDs; an unrecognised shape remains one named envelope. Callers
+ * may provide response metadata IDs for envelopes (such as JIT) whose visible
+ * wire format does not carry trailing memory pointers.
+ */
+export function contextItemsFromText(text, envelopeName, memoryIds = []) {
+    const parsed = parsePointerItems(text, envelopeName);
+    if (parsed.memories.length === 0) {
+        return [{ text, name: envelopeName, ...(memoryIds.length > 0 ? { memoryIds } : {}) }];
+    }
+    return [...parsed.memories, ...(parsed.trailer ? [parsed.trailer] : [])];
+}
+/** Fit one rendered envelope while preserving its exact under-budget bytes. */
+export function fitContextText(text, envelopeName, opts) {
+    const units = opts.units ?? 'characters';
+    if (measureContext(text, units) <= opts.budget)
+        return text;
+    return fitContextItems(contextItemsFromText(text, envelopeName, opts.memoryIds), opts).value;
+}
+/** Split an ambient body into whole pointer-terminated items. */
+export function splitAmbientItems(body) {
+    return parsePointerItems(body, 'ambient recall').memories.map((item) => item.text);
+}
+//# sourceMappingURL=contextBudget.js.map

package/dist/contextBudget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contextBudget.js","sourceRoot":"","sources":["../src/contextBudget.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemonik/shared",
-  "version": "7.41.0",
+  "version": "7.42.0",
   "description": "Shared constants and utilities for Mnemonik packages",
   "repository": {
     "type": "git",
@@ -26,6 +26,10 @@
     "./ambient-pointer": {
       "import": "./dist/ambientPointer.js",
       "types": "./dist/ambientPointer.d.ts"
+    },
+    "./context-budget": {
+      "import": "./dist/contextBudget.js",
+      "types": "./dist/contextBudget.d.ts"
     }
   },
   "scripts": {

package/src/contextBudget.ts

@@ -0,0 +1,252 @@
+import { AMBIENT_ITEM_POINTER_SOURCE } from './ambientPointer.js';
+
+export { AMBIENT_ITEM_POINTER_SOURCE } from './ambientPointer.js';
+
+export type ContextBudgetUnits = 'characters' | 'utf8-bytes';
+
+export interface ContextBudgetItem {
+  /** Exact text emitted when the item fits in full. */
+  text: string;
+  /** Stable envelope name used by continuation/not-reached pointers. */
+  name: string;
+  /** Memory identity when this item is one pointer-terminated memory precis. */
+  memoryId?: string;
+  /** Memory identities when one rendered envelope represents several memories. */
+  memoryIds?: readonly string[];
+}
+
+export type ContextBudgetPiece = string | ContextBudgetItem;
+
+export interface BudgetedContextFit {
+  value: string;
+  fullyDeliveredItems: number;
+  partialItemIndex: number | null;
+  partialUnitsDelivered: number;
+}
+
+const JOINER = '\n\n';
+const CONTINUATION_PREFIX = '… continues: ';
+const NOT_REACHED_PREFIX = '… not reached: ';
+
+function itemMemoryIds(item: ContextBudgetItem): readonly string[] {
+  if (item.memoryIds && item.memoryIds.length > 0) return item.memoryIds;
+  return item.memoryId ? [item.memoryId] : [];
+}
+
+function identity(item: ContextBudgetItem): string {
+  const memoryIds = itemMemoryIds(item);
+  if (memoryIds.length > 0) return memoryIds.map((id) => `memory_get ${id}`).join(', ');
+  return item.name.replace(/\s+/g, ' ').trim();
+}
+
+function continuationPointer(item: ContextBudgetItem): string {
+  return `${CONTINUATION_PREFIX}${identity(item)}`;
+}
+
+function notReachedPointer(items: readonly ContextBudgetItem[]): string | null {
+  if (items.length === 0) return null;
+  return `${NOT_REACHED_PREFIX}${items.map(identity).join(', ')}`;
+}
+
+function joinSections(sections: readonly (string | null)[]): string {
+  return sections
+    .filter((section): section is string => section !== null && section.length > 0)
+    .join(JOINER);
+}
+
+/** Measure rendered context in the host's native budget unit. */
+export function measureContext(text: string, units: ContextBudgetUnits = 'characters'): number {
+  return units === 'utf8-bytes' ? Buffer.byteLength(text, 'utf8') : text.length;
+}
+
+interface NaturalUnits {
+  prefix: string;
+  units: string[];
+}
+
+function withoutTerminalMemoryPointer(item: ContextBudgetItem): string {
+  if (!item.memoryId) return item.text;
+  const terminalPointer = new RegExp(`\\s*${AMBIENT_ITEM_POINTER_SOURCE}\\s*$`);
+  return item.text.replace(terminalPointer, '').trimEnd();
+}
+
+/**
+ * Prefer bullet lines whenever the item contains them. Text ahead of the first
+ * bullet is framing and travels with the first admitted fact. Otherwise each
+ * sentence (including a final sentence ending at end-of-item) is one unit.
+ */
+function naturalUnits(item: ContextBudgetItem): NaturalUnits {
+  const text = withoutTerminalMemoryPointer(item);
+  const bulletStarts: number[] = [];
+  const bulletPattern = /(^|\n)(?=[ \t]*(?:•|[-*])[ \t]+)/g;
+  let bulletMatch: RegExpExecArray | null;
+  while ((bulletMatch = bulletPattern.exec(text)) !== null) {
+    bulletStarts.push(bulletMatch.index + (bulletMatch[1] ?? '').length);
+    if (bulletPattern.lastIndex === bulletMatch.index) bulletPattern.lastIndex += 1;
+  }
+
+  if (bulletStarts.length > 0) {
+    return {
+      prefix: text.slice(0, bulletStarts[0]),
+      units: bulletStarts.map((start, index) => text.slice(start, bulletStarts[index + 1])),
+    };
+  }
+
+  const units: string[] = [];
+  const sentenceEnd = /[.!?](?:["')\]]*)?(?=\s|$)/g;
+  let cursor = 0;
+  let sentenceMatch: RegExpExecArray | null;
+  while ((sentenceMatch = sentenceEnd.exec(text)) !== null) {
+    const end = sentenceMatch.index + sentenceMatch[0].length;
+    units.push(text.slice(cursor, end));
+    cursor = end;
+  }
+  if (cursor < text.length) units.push(text.slice(cursor));
+  return { prefix: '', units: units.filter((unit) => unit.trim().length > 0) };
+}
+
+function partialText(item: ContextBudgetItem, plan: NaturalUnits, count: number): string {
+  const content = `${plan.prefix}${plan.units.slice(0, count).join('')}`.trimEnd();
+  return `${content}\n${continuationPointer(item)}`;
+}
+
+/**
+ * Compose ordered items within a fixed budget. Full items are emitted exactly;
+ * the first item that does not fit is packed by whole natural units, and all
+ * later identities share one trailing not-reached pointer.
+ */
+export function fitContextItems(
+  items: readonly ContextBudgetItem[],
+  opts: {
+    budget: number;
+    units?: ContextBudgetUnits;
+    reservedSuffix?: readonly ContextBudgetItem[];
+  }
+): BudgetedContextFit {
+  const units = opts.units ?? 'characters';
+  const suffix = opts.reservedSuffix ?? [];
+  const fullValue = [...items, ...suffix].map((item) => item.text).join(JOINER);
+  if (measureContext(fullValue, units) <= opts.budget) {
+    return {
+      value: fullValue,
+      fullyDeliveredItems: items.length,
+      partialItemIndex: null,
+      partialUnitsDelivered: 0,
+    };
+  }
+
+  const accepted: string[] = [];
+  for (let index = 0; index < items.length; index += 1) {
+    const item = items[index];
+    if (item === undefined) continue;
+    const later = items.slice(index + 1);
+    const withFullItem = joinSections([
+      ...accepted,
+      item.text,
+      ...suffix.map((entry) => entry.text),
+      notReachedPointer(later),
+    ]);
+    if (measureContext(withFullItem, units) <= opts.budget) {
+      accepted.push(item.text);
+      continue;
+    }
+
+    const plan = naturalUnits(item);
+    let partialUnitsDelivered = 0;
+    for (let count = 1; count <= plan.units.length; count += 1) {
+      const candidate = joinSections([
+        ...accepted,
+        partialText(item, plan, count),
+        ...suffix.map((entry) => entry.text),
+        notReachedPointer(later),
+      ]);
+      if (measureContext(candidate, units) > opts.budget) break;
+      partialUnitsDelivered = count;
+    }
+
+    // A one-fact excerpt reads as though it were the whole memory. Require two
+    // complete units before admitting a partial item; otherwise name it only.
+    const meaningfulMinimum = Math.min(2, plan.units.length);
+    const partialAccepted = partialUnitsDelivered >= meaningfulMinimum && partialUnitsDelivered > 0;
+    const partial = partialAccepted ? partialText(item, plan, partialUnitsDelivered) : null;
+    const unreached = partialAccepted ? later : items.slice(index);
+    return {
+      value: joinSections([
+        ...accepted,
+        partial,
+        ...suffix.map((entry) => entry.text),
+        notReachedPointer(unreached),
+      ]),
+      fullyDeliveredItems: index,
+      partialItemIndex: partialAccepted ? index : null,
+      partialUnitsDelivered: partialAccepted ? partialUnitsDelivered : 0,
+    };
+  }
+
+  return {
+    value: joinSections([...accepted, ...suffix.map((entry) => entry.text)]),
+    fullyDeliveredItems: items.length,
+    partialItemIndex: null,
+    partialUnitsDelivered: 0,
+  };
+}
+
+interface ParsedPointerItems {
+  memories: ContextBudgetItem[];
+  trailer: ContextBudgetItem | null;
+}
+
+function parsePointerItems(body: string, envelopeName: string): ParsedPointerItems {
+  const regex = new RegExp(AMBIENT_ITEM_POINTER_SOURCE, 'g');
+  const memories: ContextBudgetItem[] = [];
+  let cursor = 0;
+  let match: RegExpExecArray | null;
+  while ((match = regex.exec(body)) !== null) {
+    const end = match.index + match[0].length;
+    const text = body.slice(cursor, end).trim();
+    const memoryId = match[1];
+    if (text.length > 0 && memoryId !== undefined) {
+      memories.push({ text, name: envelopeName, memoryId });
+    }
+    cursor = end;
+  }
+  const trailerText = body.slice(cursor).trim();
+  return {
+    memories,
+    trailer: trailerText ? { text: trailerText, name: `${envelopeName} trailer` } : null,
+  };
+}
+
+/**
+ * Turn one rendered envelope into budget items. Pointer-terminated memories
+ * retain their IDs; an unrecognised shape remains one named envelope. Callers
+ * may provide response metadata IDs for envelopes (such as JIT) whose visible
+ * wire format does not carry trailing memory pointers.
+ */
+export function contextItemsFromText(
+  text: string,
+  envelopeName: string,
+  memoryIds: readonly string[] = []
+): ContextBudgetItem[] {
+  const parsed = parsePointerItems(text, envelopeName);
+  if (parsed.memories.length === 0) {
+    return [{ text, name: envelopeName, ...(memoryIds.length > 0 ? { memoryIds } : {}) }];
+  }
+  return [...parsed.memories, ...(parsed.trailer ? [parsed.trailer] : [])];
+}
+
+/** Fit one rendered envelope while preserving its exact under-budget bytes. */
+export function fitContextText(
+  text: string,
+  envelopeName: string,
+  opts: { budget: number; units?: ContextBudgetUnits; memoryIds?: readonly string[] }
+): string {
+  const units = opts.units ?? 'characters';
+  if (measureContext(text, units) <= opts.budget) return text;
+  return fitContextItems(contextItemsFromText(text, envelopeName, opts.memoryIds), opts).value;
+}
+
+/** Split an ambient body into whole pointer-terminated items. */
+export function splitAmbientItems(body: string): string[] {
+  return parsePointerItems(body, 'ambient recall').memories.map((item) => item.text);
+}