@ixo/oracle-runtime-workers 0.25.0 → 0.27.0

package/src/memory/user-context-invalidation.ts

@@ -2,8 +2,8 @@
  * Drops a room's prefetched user context (`UserContextFetcher.invalidate`)
  * after a tool call that changed the user's memory succeeded, so the next
  * session in the room gathers again instead of reading the pre-write answer
- * for the rest of the cache TTL. It never changes the current thread: a
- * thread keeps the context it got on first contact.
+ * for the rest of the cache TTL. Channel turns adopt the refreshed context
+ * on a later turn; other clients keep their first-contact context.
  *
  * Applied as a tool middleware to the main agent and every sub-agent; a
  * failed call (thrown, or an error `ToolMessage`) leaves the cache alone.
@@ -19,6 +19,10 @@ import {
   MEMORY_DELETE_EDGE_MCP_NAME,
   MEMORY_DELETE_EPISODE_MCP_NAME,
 } from '../plugins/memory/memory-tools';
+import {
+  ADD_ORACLE_DOCUMENT_TOOL_NAME,
+  DELETE_ORACLE_DOCUMENT_TOOL_NAME,
+} from '../plugins/memory/oracle-document-tools';
 
 /** The memory engine tools that write or delete what the prefetch reads. */
 export const MEMORY_WRITE_TOOL_NAMES: readonly string[] = [
@@ -27,6 +31,8 @@ export const MEMORY_WRITE_TOOL_NAMES: readonly string[] = [
   MEMORY_DELETE_EPISODE_MCP_NAME,
   MEMORY_DELETE_EDGE_MCP_NAME,
   MEMORY_CLEAR_MCP_NAME,
+  ADD_ORACLE_DOCUMENT_TOOL_NAME,
+  DELETE_ORACLE_DOCUMENT_TOOL_NAME,
 ];
 
 export interface UserContextInvalidationOptions {

package/src/plugins/action-proposals/evidence.ts

@@ -1,8 +1,5 @@
 import type { BaseMessage } from '@langchain/core/messages';
-import {
-  stripTurnTimeNote,
-  TURN_TIME_NOTE_KWARG,
-} from '../../core/turn-time-note';
+import { userContent } from '../../channels/replies';
 import { contentToText } from '../../do/transcript';
 
 /** How many of the user's own messages count as evidence, and how much of each. */
@@ -18,8 +15,10 @@ export const NEGATION =
 
 /**
  * The user's own words from the last few turns. The runtime's time note
- * (`Current time: … 14:05 …`) rides on every message the user sent; it is
- * stripped here so its digits can never stand in for an amount.
+ * (`Current time: … 14:05 …`) rides on every message the user sent, and a
+ * WhatsApp reply carries the quoted message; both are stripped here so
+ * neither the note's digits nor an address or amount the user merely quoted
+ * can stand in for what they typed.
  */
 export function userEvidence(messages: readonly BaseMessage[]): string[] {
   return messages
@@ -27,9 +26,9 @@ export function userEvidence(messages: readonly BaseMessage[]): string[] {
     .slice(-EVIDENCE_MESSAGES)
     .map((m) =>
       contentToText(
-        stripTurnTimeNote(
+        userContent(
           m.content,
-          m.additional_kwargs?.[TURN_TIME_NOTE_KWARG],
+          m.additional_kwargs as Record<string, unknown> | undefined,
         ),
       ).slice(0, EVIDENCE_MESSAGE_CHARS),
     );

package/src/plugins/memory/document-chunker.ts

@@ -0,0 +1,313 @@
+/**
+ * Splits extracted document text into chunks the Memory Engine accepts: every
+ * chunk is at most `maxChunkBytes` UTF-8 bytes, cut at the largest natural
+ * boundary that fits (paragraph, line, sentence) and only then mid-text, never
+ * inside a UTF-8 sequence or surrogate pair.
+ */
+
+export interface ChunkerOptions {
+  /** Upper bound of one chunk in UTF-8 bytes (default 12 000). */
+  maxChunkBytes: number;
+  /** Most chunks to return (default 64). */
+  maxChunks: number;
+}
+
+export interface DocumentChunk {
+  /** Zero-based position in the document. */
+  index: number;
+  /** `p. 3`, `p. 3–5` when the text carries page markers, else `part 2 of 7`. */
+  label: string;
+  content: string;
+}
+
+export interface ChunkedDocument {
+  chunks: DocumentChunk[];
+  /** More chunks were needed than `maxChunks`; only the first ones are returned. */
+  truncated: boolean;
+  /** UTF-8 size of the normalised text. */
+  totalBytes: number;
+}
+
+export const DEFAULT_CHUNK_BYTES = 12_000;
+export const DEFAULT_MAX_CHUNKS = 64;
+
+const MIN_CHUNK_BYTES = 4;
+/** A whole line that only names a page: `--- page 3 ---`, `Page 3`, `p. 3`, `Page 3 of 10`. */
+const PAGE_MARKER =
+  /^\s*(?:---\s*page\s+(\d+)\s*---|(?:page|p\.)\s*(\d+)(?:\s*(?:of|\/)\s*\d+)?)\s*$/i;
+
+/** UTF-8 length of a string, counting a lone surrogate as U+FFFD (3 bytes). */
+export function utf8ByteLength(text: string): number {
+  let bytes = 0;
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.charCodeAt(i);
+    if (code < 0x80) bytes += 1;
+    else if (code < 0x800) bytes += 2;
+    else if (code >= 0xd800 && code <= 0xdbff) {
+      const next = text.charCodeAt(i + 1);
+      if (next >= 0xdc00 && next <= 0xdfff) {
+        bytes += 4;
+        i += 1;
+      } else bytes += 3;
+    } else bytes += 3;
+  }
+  return bytes;
+}
+
+interface Paragraph {
+  text: string;
+  page: number | undefined;
+}
+
+interface Unit {
+  text: string;
+  /** What joins this unit to the previous one inside a chunk. */
+  sep: string;
+  page: number | undefined;
+}
+
+/** Drops trailing spaces and tabs in one backwards pass (no regex backtracking; a form feed stays). */
+function trimLineEnd(line: string): string {
+  let end = line.length;
+  while (end > 0 && (line[end - 1] === ' ' || line[end - 1] === '\t')) end -= 1;
+  return end === line.length ? line : line.slice(0, end);
+}
+
+function normalise(text: string): string {
+  return text
+    .replace(/\r\n?/g, '\n')
+    .split('\n')
+    .map(trimLineEnd)
+    .join('\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trim();
+}
+
+function isMarkerOnly(text: string): boolean {
+  return !text.includes('\n') && PAGE_MARKER.test(text);
+}
+
+function groupText(group: readonly Unit[]): string {
+  return group.reduce(
+    (acc, u, i) => (i === 0 ? u.text : acc + u.sep + u.text),
+    '',
+  );
+}
+
+/**
+ * A group that only names pages (`--- page 4 ---`) says nothing: it joins the
+ * start of the next group, else the end of the previous one, if it fits, and
+ * is dropped otherwise (the page of every unit is already known).
+ */
+function absorbMarkerGroups(groups: Unit[][], maxBytes: number): Unit[][] {
+  const out: Unit[][] = [];
+  let carry: Unit[] = [];
+  for (const group of groups) {
+    if (group.every((u) => isMarkerOnly(u.text))) {
+      carry = [...carry, ...group];
+      continue;
+    }
+    if (
+      carry.length > 0 &&
+      utf8ByteLength(groupText([...carry, ...group])) <= maxBytes
+    ) {
+      out.push([...carry, ...group]);
+    } else {
+      const last = out[out.length - 1];
+      if (
+        carry.length > 0 &&
+        last &&
+        utf8ByteLength(groupText([...last, ...carry])) <= maxBytes
+      ) {
+        last.push(...carry);
+      }
+      out.push(group);
+    }
+    carry = [];
+  }
+  const last = out[out.length - 1];
+  if (
+    carry.length > 0 &&
+    last &&
+    utf8ByteLength(groupText([...last, ...carry])) <= maxBytes
+  ) {
+    last.push(...carry);
+  }
+  return out;
+}
+
+/** Paragraphs in order, each tagged with the page it starts on (if paged). */
+function splitParagraphs(text: string): {
+  paragraphs: Paragraph[];
+  paged: boolean;
+} {
+  const lines = text.replace(/\f/g, '\n\f\n').split('\n');
+  const paged =
+    text.includes('\f') || lines.some((line) => PAGE_MARKER.test(line));
+  const paragraphs: Paragraph[] = [];
+  let page: number | undefined = paged ? 1 : undefined;
+  let current: string[] = [];
+  let currentPage = page;
+
+  const flush = (): void => {
+    const joined = current.join('\n').trim();
+    if (joined) paragraphs.push({ text: joined, page: currentPage });
+    current = [];
+  };
+
+  for (const line of lines) {
+    if (line === '\f') {
+      flush();
+      page = (page ?? 1) + 1;
+      continue;
+    }
+    if (line.trim() === '') {
+      flush();
+      continue;
+    }
+    const marker = PAGE_MARKER.exec(line);
+    if (marker) {
+      flush();
+      page = Number(marker[1] ?? marker[2]);
+    }
+    if (current.length === 0) currentPage = page;
+    current.push(line);
+  }
+  flush();
+  return { paragraphs, paged };
+}
+
+interface Level {
+  sep: string;
+  split: (text: string) => string[];
+}
+
+/** Boundaries tried in order when a piece is still too large. */
+const LEVELS: readonly Level[] = [
+  {
+    sep: '\n',
+    split: (t) =>
+      t
+        .split('\n')
+        .map((l) => l.trim())
+        .filter(Boolean),
+  },
+  {
+    sep: ' ',
+    split: (t) =>
+      t
+        .split(/(?<=[.!?。！？])\s+/u)
+        .map((s) => s.trim())
+        .filter(Boolean),
+  },
+];
+
+function hardSplit(text: string, maxBytes: number): string[] {
+  const pieces: string[] = [];
+  let start = 0;
+  let bytes = 0;
+  let i = 0;
+  while (i < text.length) {
+    const code = text.codePointAt(i) ?? 0;
+    const width = code > 0xffff ? 2 : 1;
+    const size = utf8ByteLength(text.slice(i, i + width));
+    if (bytes + size > maxBytes) {
+      pieces.push(text.slice(start, i));
+      start = i;
+      bytes = 0;
+    }
+    bytes += size;
+    i += width;
+  }
+  if (start < text.length) pieces.push(text.slice(start));
+  return pieces;
+}
+
+function fit(
+  text: string,
+  sep: string,
+  levels: readonly Level[],
+  maxBytes: number,
+  page: number | undefined,
+): Unit[] {
+  if (utf8ByteLength(text) <= maxBytes) return [{ text, sep, page }];
+  const [level, ...rest] = levels;
+  if (!level) {
+    return hardSplit(text, maxBytes).map((piece, i) => ({
+      text: piece,
+      sep: i === 0 ? sep : '',
+      page,
+    }));
+  }
+  const parts = level.split(text);
+  if (parts.length <= 1) return fit(text, sep, rest, maxBytes, page);
+  return parts.flatMap((part, i) =>
+    fit(part, i === 0 ? sep : level.sep, rest, maxBytes, page),
+  );
+}
+
+function pageLabel(first: number, last: number): string {
+  return first === last ? `p. ${first}` : `p. ${first}–${last}`;
+}
+
+export function chunkDocument(
+  text: string,
+  opts: Partial<ChunkerOptions> = {},
+): ChunkedDocument {
+  const maxChunkBytes = opts.maxChunkBytes ?? DEFAULT_CHUNK_BYTES;
+  const maxChunks = opts.maxChunks ?? DEFAULT_MAX_CHUNKS;
+  if (!Number.isInteger(maxChunkBytes) || maxChunkBytes < MIN_CHUNK_BYTES) {
+    throw new RangeError(
+      `maxChunkBytes must be an integer >= ${MIN_CHUNK_BYTES}`,
+    );
+  }
+  if (!Number.isInteger(maxChunks) || maxChunks < 1) {
+    throw new RangeError('maxChunks must be a positive integer');
+  }
+
+  const normalised = normalise(text);
+  if (!normalised) return { chunks: [], truncated: false, totalBytes: 0 };
+
+  const { paragraphs, paged } = splitParagraphs(normalised);
+  const units = paragraphs
+    .flatMap((p) => fit(p.text, '\n\n', LEVELS, maxChunkBytes, p.page))
+    .filter((u) => u.text.trim() !== '');
+
+  const groups: Unit[][] = [];
+  let group: Unit[] = [];
+  let groupBytes = 0;
+  for (const unit of units) {
+    const unitBytes = utf8ByteLength(unit.text);
+    // Separators are ASCII, so their length is their byte length.
+    const joined = groupBytes + unit.sep.length + unitBytes;
+    if (group.length > 0 && joined <= maxChunkBytes) {
+      group.push(unit);
+      groupBytes = joined;
+    } else {
+      if (group.length > 0) groups.push(group);
+      group = [unit];
+      groupBytes = unitBytes;
+    }
+  }
+  if (group.length > 0) groups.push(group);
+
+  const kept = absorbMarkerGroups(groups, maxChunkBytes);
+  const total = kept.length;
+  const chunks = kept.slice(0, maxChunks).map((members, index) => {
+    const body = groupText(members);
+    const pages = members
+      .map((u) => u.page)
+      .filter((p): p is number => p !== undefined);
+    const label =
+      paged && pages.length > 0
+        ? pageLabel(Math.min(...pages), Math.max(...pages))
+        : `part ${index + 1} of ${total}`;
+    return { index, label, content: body };
+  });
+
+  return {
+    chunks,
+    truncated: total > maxChunks,
+    totalBytes: utf8ByteLength(normalised),
+  };
+}

package/src/plugins/memory/document-source.ts

@@ -0,0 +1,229 @@
+/**
+ * Where the memory plugin's document tools get a document's text from: a chat
+ * attachment of the session (through the host's `AttachmentViewSurface`) or a
+ * file in the user's VFS. Both lanes return the document's own words — plain
+ * text decoded locally, a PDF's text layer parsed locally, anything else (a
+ * scan, an image, an Office file) transcribed by the helper model — never a
+ * stub or a `[Content of …]` wrapper.
+ *
+ * Every error thrown here carries a message meant for the person (the tools
+ * relay it as is).
+ */
+import { capText } from '../../attachments/extract';
+import { extractPdfText } from '../../attachments/pdf-text';
+import type { RuntimeContext } from '../../plugin-api/types';
+import type { VfsClient, VfsContentBytes } from '../vfs/vfs-client';
+import { mapVfsError, VfsAuthError, VfsHttpError } from '../vfs/vfs-errors';
+import {
+  isTextMime,
+  MAX_VISION_BYTES,
+  renderBinaryForIngestion,
+} from '../vfs/vfs-content';
+import { buildClient } from '../vfs/vfs-tools';
+import { resolveVfsConfig, type VfsConfig } from '../vfs/vfs.plugin';
+
+export type DocumentSource = { attachment_ref: string } | { vfs_path: string };
+
+export interface LoadedDocument {
+  text: string;
+  filename: string;
+  mimetype: string;
+  /** Size of the original file in bytes (of the text when the host did not report it). */
+  bytes: number;
+  method: 'text' | 'pdf' | 'model';
+  /** Page count, set when the text came from a PDF's text layer. */
+  pages?: number;
+  /** True when the text was cut at `maxChars`. */
+  truncated: boolean;
+}
+
+export interface DocumentSourceDeps {
+  /** Longest text returned (characters); more is cut and reported as `truncated`. */
+  maxChars: number;
+  /** Injected transport for the VFS client (tests). */
+  fetchImpl?: typeof fetch;
+  /** Retry backoff forwarded to the VFS client (tests pass `0`). */
+  retryDelayMs?: number;
+}
+
+const PDF_MIME = 'application/pdf';
+
+const LIBRARY_DISABLED = 'Library files are not enabled on this oracle.';
+
+function basename(path: string): string {
+  const i = path.lastIndexOf('/');
+  return i >= 0 ? path.slice(i + 1) : path;
+}
+
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function requireText(loaded: LoadedDocument): LoadedDocument {
+  if (loaded.text.trim().length === 0) {
+    throw new Error(
+      `No text could be extracted from "${loaded.filename}" (${loaded.mimetype}).`,
+    );
+  }
+  return loaded;
+}
+
+export async function loadDocumentText(
+  ctx: RuntimeContext,
+  source: DocumentSource,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  return requireText(
+    'attachment_ref' in source
+      ? await loadAttachment(ctx, source.attachment_ref, deps)
+      : await loadVfsFile(ctx, source.vfs_path, deps),
+  );
+}
+
+async function loadAttachment(
+  ctx: RuntimeContext,
+  ref: string,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  if (!ctx.attachments) {
+    throw new Error(
+      'Chat attachments cannot be read from this session; use a file from the Library (vfs_path) instead.',
+    );
+  }
+  let extracted: Awaited<ReturnType<typeof ctx.attachments.extractText>>;
+  try {
+    extracted = await ctx.attachments.extractText(ref, {
+      maxChars: deps.maxChars,
+    });
+  } catch (error) {
+    throw new Error(`Could not read attachment ${ref}: ${describe(error)}`);
+  }
+  if (!extracted) {
+    throw new Error(
+      `No attachment ${ref} in this conversation; ask the person to attach the file again.`,
+    );
+  }
+  return extracted;
+}
+
+async function loadVfsFile(
+  ctx: RuntimeContext,
+  path: string,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  // Library files are the Files plugin's: an oracle that does not run it
+  // does not expose them through the memory tools either.
+  if (!ctx.availablePlugins.has('vfs')) throw new Error(LIBRARY_DISABLED);
+  if (!ctx.ucan.hasSigningKey()) {
+    throw new Error(
+      'The Library (files) is not available: this oracle has no UCAN signing key.',
+    );
+  }
+  let cfg: VfsConfig;
+  try {
+    cfg = resolveVfsConfig(ctx.config);
+  } catch {
+    throw new Error(LIBRARY_DISABLED);
+  }
+  const client = buildClient(ctx, {
+    cfg,
+    fetchImpl: deps.fetchImpl,
+    retryDelayMs: deps.retryDelayMs,
+  });
+  const oracleDid = oracleDidOf(ctx);
+  try {
+    return await readVfsFile(ctx, client, path, deps);
+  } catch (error) {
+    // Errors of the VFS family become the same sentences `vfs_read` gives;
+    // anything else already carries its own message.
+    if (error instanceof VfsAuthError || error instanceof VfsHttpError) {
+      throw new Error(mapVfsError(error, { path, oracleDid }));
+    }
+    throw error;
+  }
+}
+
+function oracleDidOf(ctx: RuntimeContext): string | undefined {
+  const did = (ctx.config as { ORACLE_DID?: unknown } | undefined)?.ORACLE_DID;
+  return typeof did === 'string' && did.length > 0 ? did : undefined;
+}
+
+async function readVfsFile(
+  ctx: RuntimeContext,
+  client: VfsClient,
+  path: string,
+  deps: DocumentSourceDeps,
+): Promise<LoadedDocument> {
+  const stat = await client.statByPath(path);
+  if (!stat) throw new Error(`No file at ${path} in your files.`);
+  const mimetype = stat.mimeType || 'application/octet-stream';
+  const filename = stat.name || basename(stat.path) || stat.id;
+  if (stat.size > MAX_VISION_BYTES) {
+    throw new Error(
+      `"${filename}" is ${stat.size} bytes, over the ${MAX_VISION_BYTES} byte limit for documents.`,
+    );
+  }
+
+  if (isTextMime(mimetype)) {
+    const { bytes } = await client.contentBytes(stat.id, MAX_VISION_BYTES);
+    // At most 3 UTF-8 bytes per UTF-16 unit: decoding past this adds nothing.
+    const head = new Uint8Array(bytes).subarray(0, deps.maxChars * 3 + 4);
+    const capped = capText(new TextDecoder().decode(head), deps.maxChars);
+    return {
+      ...capped,
+      filename,
+      mimetype,
+      bytes: bytes.byteLength,
+      method: 'text',
+    };
+  }
+
+  // Only a PDF is downloaded here (to try its text layer); any other type
+  // is downloaded by the render step itself, after its own type/size checks.
+  let downloaded: VfsContentBytes | undefined;
+  if (mimetype === PDF_MIME) {
+    downloaded = await client.contentBytes(stat.id, MAX_VISION_BYTES);
+    try {
+      const pdf = await extractPdfText(new Uint8Array(downloaded.bytes), {
+        maxChars: deps.maxChars,
+        signal: ctx.abortSignal,
+      });
+      if (pdf.kind === 'text') {
+        return {
+          text: pdf.text,
+          truncated: pdf.truncated,
+          filename,
+          mimetype,
+          bytes: downloaded.bytes.byteLength,
+          method: 'pdf',
+          pages: pdf.pages,
+        };
+      }
+      ctx.logger.log(
+        `[memory] document "${filename}": no text layer (${pdf.pages} page(s)), using the helper model`,
+      );
+    } catch (error) {
+      if (ctx.abortSignal.aborted) throw error;
+      ctx.logger.warn(
+        `[memory] document "${filename}": local PDF parse failed (${describe(error)}), using the helper model`,
+      );
+    }
+  }
+
+  // The bytes are already in hand: the render step does not download again.
+  const rendered = await renderBinaryForIngestion(
+    client,
+    ctx,
+    stat,
+    downloaded,
+  );
+  const capped = capText(rendered.text, deps.maxChars);
+  return {
+    text: capped.text,
+    truncated: capped.truncated || rendered.truncated,
+    filename,
+    mimetype,
+    bytes: stat.size,
+    method: 'model',
+  };
+}