agent-working-memory 0.8.6 → 0.8.7

package/src/core/lite-compress.ts

@@ -0,0 +1,129 @@
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Lite output compressor — token-efficient encoding of STRUCTURED tool output.
+ *
+ * Why this exists: agents burn tokens re-reading large structured tool results
+ * (JSON arrays, query rows, log dumps). Encoding them as TOON (Token-Oriented
+ * Object Notation — a compact, schema-aware tabular form of JSON) cuts ~50-65%
+ * of the tokens on uniform arrays at ZERO comprehension cost. An A/B test on
+ * claude-sonnet-4-6 and claude-haiku-4-5 found identical retrieval accuracy
+ * reading TOON vs JSON (95.8%/83.3% on both encodings, identical misses).
+ *
+ * This is OUTPUT-ONLY. It never touches stored memory content or the write
+ * path. It is intentionally narrow and safe:
+ *   - Structured data (parseable JSON object/array)  -> TOON, IF it round-trips
+ *   - Prose / non-JSON                               -> passthrough untouched
+ *   - TOON that would lose fidelity or barely save   -> plain JSON fallback
+ *
+ * Safety: TOON (like CSV/YAML) can type-coerce ambiguous bare scalars
+ * (the string "123" can decode back as the number 123). So every encode is
+ * SELF-VERIFIED (encode -> decode -> deep-equal) and we only emit TOON when it
+ * reproduces the input exactly. Originals are stashed so the agent can retrieve
+ * the verbatim source via a CCR-lite handle if it ever needs it.
+ *
+ * No ML, no network, no I/O — a pure in-process structural transform.
+ */
+import { encode, decode } from '@toon-format/toon';
+
+export interface CompressResult {
+  /** The text to put in the model's context. */
+  text: string;
+  /** 'toon' when compressed, 'json'/'passthrough' when not. */
+  format: 'toon' | 'json' | 'passthrough';
+  /** Retrieval handle for the verbatim original, or null when unchanged. */
+  ref: string | null;
+  charsBefore: number;
+  charsAfter: number;
+  /** Approx fraction of characters saved (0..1); a rough proxy for token savings. */
+  ratio: number;
+}
+
+export interface CompressOptions {
+  /** Don't bother emitting TOON unless it saves at least this many chars. Default 40. */
+  minSavingChars?: number;
+}
+
+// ── CCR-lite: stash verbatim originals, hand back a retrieval id ────────────
+// Bounded FIFO so a long-lived MCP process can't leak memory.
+const MAX_STORE = 512;
+const _store = new Map<string, string>();
+let _seq = 0;
+
+function stash(original: string): string {
+  const id = `awm_orig_${++_seq}`;
+  _store.set(id, original);
+  if (_store.size > MAX_STORE) {
+    const oldest = _store.keys().next().value;
+    if (oldest !== undefined) _store.delete(oldest);
+  }
+  return id;
+}
+
+/** Retrieve the verbatim original for a CCR-lite ref, or undefined if evicted. */
+export function retrieveOriginal(ref: string): string | undefined {
+  return _store.get(ref);
+}
+
+/** True if TOON encode->decode reproduces `obj` exactly (no scalar coercion drift). */
+function roundTrips(obj: unknown, toon: string): boolean {
+  try {
+    return JSON.stringify(decode(toon)) === JSON.stringify(obj);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Compress a structured tool output for model consumption.
+ *
+ * @param value Either a JS object/array, or a string (JSON is parsed; anything
+ *              that isn't valid JSON is treated as prose and passed through).
+ */
+export function liteCompress(value: unknown, options: CompressOptions = {}): CompressResult {
+  const minSaving = options.minSavingChars ?? 40;
+
+  let obj: unknown;
+  let jsonText: string;
+
+  if (typeof value === 'string') {
+    try {
+      obj = JSON.parse(value);
+    } catch {
+      // Not JSON — prose. Leave it alone; that's granularity:compact's job.
+      return { text: value, format: 'passthrough', ref: null,
+               charsBefore: value.length, charsAfter: value.length, ratio: 0 };
+    }
+    jsonText = value;
+  } else {
+    obj = value;
+    jsonText = JSON.stringify(obj, null, 2);
+  }
+
+  // Only structured shapes benefit; a bare scalar gains nothing.
+  if (obj === null || typeof obj !== 'object') {
+    return { text: jsonText, format: 'json', ref: null,
+             charsBefore: jsonText.length, charsAfter: jsonText.length, ratio: 0 };
+  }
+
+  let toon: string;
+  try {
+    toon = encode(obj);
+  } catch {
+    return { text: jsonText, format: 'json', ref: null,
+             charsBefore: jsonText.length, charsAfter: jsonText.length, ratio: 0 };
+  }
+
+  const before = jsonText.length;
+  const after = toon.length;
+
+  // Reject if it doesn't round-trip exactly, or the saving isn't worth it.
+  if (!roundTrips(obj, toon) || before - after < minSaving) {
+    return { text: jsonText, format: 'json', ref: null,
+             charsBefore: before, charsAfter: before, ratio: 0 };
+  }
+
+  const ref = stash(jsonText);
+  return { text: toon, format: 'toon', ref,
+           charsBefore: before, charsAfter: after, ratio: 1 - after / before };
+}

package/src/core/logger.ts

@@ -1,36 +1,36 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Simple file logger for AWM activity.
- *
- * Appends one line per event to data/awm.log (next to memory.db).
- * Format: ISO timestamp | agent | event | detail
- *
- * Designed for dev pilot observability — know at a glance what's happening.
- */
-
-import { appendFileSync, mkdirSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-
-let logPath: string | null = null;
-
-export function initLogger(dbPath: string): void {
-  const dir = dirname(resolve(dbPath));
-  mkdirSync(dir, { recursive: true });
-  logPath = resolve(dir, 'awm.log');
-}
-
-export function log(agentId: string, event: string, detail: string): void {
-  if (!logPath) return;
-  const ts = new Date().toISOString();
-  const line = `${ts} | ${agentId} | ${event} | ${detail}\n`;
-  try {
-    appendFileSync(logPath, line);
-  } catch {
-    // Logging should never crash the server
-  }
-}
-
-export function getLogPath(): string | null {
-  return logPath;
-}
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Simple file logger for AWM activity.
+ *
+ * Appends one line per event to data/awm.log (next to memory.db).
+ * Format: ISO timestamp | agent | event | detail
+ *
+ * Designed for dev pilot observability — know at a glance what's happening.
+ */
+
+import { appendFileSync, mkdirSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+
+let logPath: string | null = null;
+
+export function initLogger(dbPath: string): void {
+  const dir = dirname(resolve(dbPath));
+  mkdirSync(dir, { recursive: true });
+  logPath = resolve(dir, 'awm.log');
+}
+
+export function log(agentId: string, event: string, detail: string): void {
+  if (!logPath) return;
+  const ts = new Date().toISOString();
+  const line = `${ts} | ${agentId} | ${event} | ${detail}\n`;
+  try {
+    appendFileSync(logPath, line);
+  } catch {
+    // Logging should never crash the server
+  }
+}
+
+export function getLogPath(): string | null {
+  return logPath;
+}

package/src/core/ml-worker-entry.ts

@@ -1,194 +1,194 @@
-// Copyright 2026 Robert Winter / Complete Ideas
-// SPDX-License-Identifier: Apache-2.0
-/**
- * ML worker entry — runs INSIDE a worker_thread.
- *
- * Loaded once per worker, sets up the model for the assigned role
- * (embed | rerank | expand), then handles request messages from the
- * main thread via the parentPort.
- *
- * Protocol:
- *   Main thread → worker:  { id, op, args }    (op matches the worker's role)
- *   Worker → main thread:  { id, ok: true, result } or { id, ok: false, error }
- *   Worker → main thread:  { ready: true }     (one-time signal after model load)
- *   Main thread → worker:  { shutdown: true }  (drain queue, then terminate)
- *
- * The worker stays loaded — the model lives in memory for the worker's lifetime.
- */
-
-import { parentPort, workerData } from 'node:worker_threads';
-
-if (!parentPort) {
-  throw new Error('ml-worker-entry: must be loaded as a worker_thread');
-}
-
-type WorkerRole = 'embed' | 'rerank' | 'expand';
-const role: WorkerRole = workerData?.role;
-if (role !== 'embed' && role !== 'rerank' && role !== 'expand') {
-  throw new Error(`ml-worker-entry: invalid role '${role}'`);
-}
-
-// --- Lazy model loaders (each worker loads only its own model) ---
-
-let embedderPipeline: any = null;
-let rerankerTokenizer: any = null;
-let rerankerModel: any = null;
-let expanderPipeline: any = null;
-
-// Inside worker_threads we must use the WASM ONNX backend, not the native one.
-// onnxruntime-node's native bindings store V8 handles that get invalidated when
-// crossing isolate boundaries — calling from a worker crashes with
-// `v8::HandleScope::CreateHandle()` failures. The WASM backend is V8-safe.
-const WORKER_DEVICE = 'wasm' as const;
-
-async function loadEmbedder(): Promise<void> {
-  const { pipeline } = await import('@huggingface/transformers');
-  const modelId = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
-  embedderPipeline = await pipeline('feature-extraction', modelId, { dtype: 'fp32', device: WORKER_DEVICE });
-}
-
-async function loadReranker(): Promise<void> {
-  const { AutoTokenizer, AutoModelForSequenceClassification } = await import('@huggingface/transformers');
-  const modelId = process.env.AWM_RERANKER_MODEL || 'Xenova/ms-marco-MiniLM-L-6-v2';
-  rerankerTokenizer = await AutoTokenizer.from_pretrained(modelId);
-  rerankerModel = await AutoModelForSequenceClassification.from_pretrained(modelId, { dtype: 'fp32', device: WORKER_DEVICE });
-}
-
-async function loadExpander(): Promise<void> {
-  const { pipeline } = await import('@huggingface/transformers');
-  expanderPipeline = await pipeline('text2text-generation', 'Xenova/flan-t5-small', { dtype: 'fp32', device: WORKER_DEVICE });
-}
-
-// --- Per-role inference handlers ---
-
-function sigmoid(x: number): number {
-  return 1 / (1 + Math.exp(-x));
-}
-
-async function handleEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]> {
-  if (!embedderPipeline) throw new Error('embedder not loaded');
-  const { texts, pooling, dimensions } = args;
-  if (texts.length === 0) return [];
-  const result = await embedderPipeline(texts, { pooling, normalize: true });
-  const data = result.data as Float32Array;
-  const vectors: number[][] = [];
-  for (let i = 0; i < texts.length; i++) {
-    vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
-  }
-  return vectors;
-}
-
-interface RerankResult { index: number; score: number; }
-
-async function handleRerank(args: { query: string; passages: string[] }): Promise<RerankResult[]> {
-  if (!rerankerTokenizer || !rerankerModel) throw new Error('reranker not loaded');
-  const { query, passages } = args;
-  if (passages.length === 0) return [];
-
-  // Batch path
-  try {
-    const queries = passages.map(() => query);
-    const inputs = rerankerTokenizer(queries, {
-      text_pair: passages,
-      padding: true,
-      truncation: true,
-      return_tensors: 'pt',
-    });
-    const output = await rerankerModel(inputs);
-    const logits = output.logits ?? output.last_hidden_state;
-    const data = logits.data as Float32Array | number[];
-    const results: RerankResult[] = [];
-    for (let i = 0; i < passages.length; i++) {
-      const rawLogit = Number(data[i] ?? 0);
-      results.push({ index: i, score: sigmoid(rawLogit) });
-    }
-    results.sort((a, b) => b.score - a.score);
-    return results;
-  } catch {
-    // Per-passage fallback
-    const results: RerankResult[] = [];
-    for (let i = 0; i < passages.length; i++) {
-      try {
-        const inputs = rerankerTokenizer(query, {
-          text_pair: passages[i],
-          padding: true,
-          truncation: true,
-          return_tensors: 'pt',
-        });
-        const output = await rerankerModel(inputs);
-        const logits = output.logits ?? output.last_hidden_state;
-        const rawLogit = logits.data[0] as number;
-        results.push({ index: i, score: sigmoid(rawLogit) });
-      } catch {
-        results.push({ index: i, score: 0 });
-      }
-    }
-    results.sort((a, b) => b.score - a.score);
-    return results;
-  }
-}
-
-async function handleExpand(args: { prompt: string; maxNewTokens: number; noRepeatNgramSize: number }): Promise<string> {
-  if (!expanderPipeline) throw new Error('expander not loaded');
-  const result = await expanderPipeline(args.prompt, {
-    max_new_tokens: args.maxNewTokens,
-    no_repeat_ngram_size: args.noRepeatNgramSize,
-  });
-  const text = Array.isArray(result) ? (result[0] as any)?.generated_text ?? '' : '';
-  return String(text).trim();
-}
-
-// --- Main loop ---
-
-let shuttingDown = false;
-const inflight = new Set<Promise<void>>();
-
-async function loadModel(): Promise<void> {
-  switch (role) {
-    case 'embed': await loadEmbedder(); break;
-    case 'rerank': await loadReranker(); break;
-    case 'expand': await loadExpander(); break;
-  }
-}
-
-async function handleMessage(msg: { id: number; op: WorkerRole; args: any }): Promise<void> {
-  try {
-    let result: unknown;
-    switch (msg.op) {
-      case 'embed':  result = await handleEmbed(msg.args); break;
-      case 'rerank': result = await handleRerank(msg.args); break;
-      case 'expand': result = await handleExpand(msg.args); break;
-    }
-    parentPort!.postMessage({ id: msg.id, ok: true, result });
-  } catch (err) {
-    parentPort!.postMessage({ id: msg.id, ok: false, error: String((err as Error)?.message ?? err) });
-  }
-}
-
-(async () => {
-  try {
-    await loadModel();
-    parentPort!.postMessage({ ready: true, role });
-  } catch (err) {
-    parentPort!.postMessage({ ready: false, role, error: String((err as Error)?.message ?? err) });
-    process.exit(1);
-  }
-})();
-
-parentPort.on('message', (msg: any) => {
-  if (msg?.shutdown) {
-    shuttingDown = true;
-    // Wait for in-flight work, then exit
-    void Promise.allSettled([...inflight]).then(() => {
-      parentPort!.postMessage({ shutdown: 'done' });
-      process.exit(0);
-    });
-    return;
-  }
-  if (shuttingDown) return;
-  if (typeof msg?.id !== 'number' || typeof msg?.op !== 'string') return;
-
-  const promise = handleMessage(msg);
-  inflight.add(promise);
-  void promise.finally(() => inflight.delete(promise));
-});
+// Copyright 2026 Robert Winter / Complete Ideas
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * ML worker entry — runs INSIDE a worker_thread.
+ *
+ * Loaded once per worker, sets up the model for the assigned role
+ * (embed | rerank | expand), then handles request messages from the
+ * main thread via the parentPort.
+ *
+ * Protocol:
+ *   Main thread → worker:  { id, op, args }    (op matches the worker's role)
+ *   Worker → main thread:  { id, ok: true, result } or { id, ok: false, error }
+ *   Worker → main thread:  { ready: true }     (one-time signal after model load)
+ *   Main thread → worker:  { shutdown: true }  (drain queue, then terminate)
+ *
+ * The worker stays loaded — the model lives in memory for the worker's lifetime.
+ */
+
+import { parentPort, workerData } from 'node:worker_threads';
+
+if (!parentPort) {
+  throw new Error('ml-worker-entry: must be loaded as a worker_thread');
+}
+
+type WorkerRole = 'embed' | 'rerank' | 'expand';
+const role: WorkerRole = workerData?.role;
+if (role !== 'embed' && role !== 'rerank' && role !== 'expand') {
+  throw new Error(`ml-worker-entry: invalid role '${role}'`);
+}
+
+// --- Lazy model loaders (each worker loads only its own model) ---
+
+let embedderPipeline: any = null;
+let rerankerTokenizer: any = null;
+let rerankerModel: any = null;
+let expanderPipeline: any = null;
+
+// Inside worker_threads we must use the WASM ONNX backend, not the native one.
+// onnxruntime-node's native bindings store V8 handles that get invalidated when
+// crossing isolate boundaries — calling from a worker crashes with
+// `v8::HandleScope::CreateHandle()` failures. The WASM backend is V8-safe.
+const WORKER_DEVICE = 'wasm' as const;
+
+async function loadEmbedder(): Promise<void> {
+  const { pipeline } = await import('@huggingface/transformers');
+  const modelId = process.env.AWM_EMBED_MODEL ?? 'Xenova/bge-small-en-v1.5';
+  embedderPipeline = await pipeline('feature-extraction', modelId, { dtype: 'fp32', device: WORKER_DEVICE });
+}
+
+async function loadReranker(): Promise<void> {
+  const { AutoTokenizer, AutoModelForSequenceClassification } = await import('@huggingface/transformers');
+  const modelId = process.env.AWM_RERANKER_MODEL || 'Xenova/ms-marco-MiniLM-L-6-v2';
+  rerankerTokenizer = await AutoTokenizer.from_pretrained(modelId);
+  rerankerModel = await AutoModelForSequenceClassification.from_pretrained(modelId, { dtype: 'fp32', device: WORKER_DEVICE });
+}
+
+async function loadExpander(): Promise<void> {
+  const { pipeline } = await import('@huggingface/transformers');
+  expanderPipeline = await pipeline('text2text-generation', 'Xenova/flan-t5-small', { dtype: 'fp32', device: WORKER_DEVICE });
+}
+
+// --- Per-role inference handlers ---
+
+function sigmoid(x: number): number {
+  return 1 / (1 + Math.exp(-x));
+}
+
+async function handleEmbed(args: { texts: string[]; pooling: 'cls' | 'mean'; dimensions: number }): Promise<number[][]> {
+  if (!embedderPipeline) throw new Error('embedder not loaded');
+  const { texts, pooling, dimensions } = args;
+  if (texts.length === 0) return [];
+  const result = await embedderPipeline(texts, { pooling, normalize: true });
+  const data = result.data as Float32Array;
+  const vectors: number[][] = [];
+  for (let i = 0; i < texts.length; i++) {
+    vectors.push(Array.from(data.slice(i * dimensions, (i + 1) * dimensions)));
+  }
+  return vectors;
+}
+
+interface RerankResult { index: number; score: number; }
+
+async function handleRerank(args: { query: string; passages: string[] }): Promise<RerankResult[]> {
+  if (!rerankerTokenizer || !rerankerModel) throw new Error('reranker not loaded');
+  const { query, passages } = args;
+  if (passages.length === 0) return [];
+
+  // Batch path
+  try {
+    const queries = passages.map(() => query);
+    const inputs = rerankerTokenizer(queries, {
+      text_pair: passages,
+      padding: true,
+      truncation: true,
+      return_tensors: 'pt',
+    });
+    const output = await rerankerModel(inputs);
+    const logits = output.logits ?? output.last_hidden_state;
+    const data = logits.data as Float32Array | number[];
+    const results: RerankResult[] = [];
+    for (let i = 0; i < passages.length; i++) {
+      const rawLogit = Number(data[i] ?? 0);
+      results.push({ index: i, score: sigmoid(rawLogit) });
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  } catch {
+    // Per-passage fallback
+    const results: RerankResult[] = [];
+    for (let i = 0; i < passages.length; i++) {
+      try {
+        const inputs = rerankerTokenizer(query, {
+          text_pair: passages[i],
+          padding: true,
+          truncation: true,
+          return_tensors: 'pt',
+        });
+        const output = await rerankerModel(inputs);
+        const logits = output.logits ?? output.last_hidden_state;
+        const rawLogit = logits.data[0] as number;
+        results.push({ index: i, score: sigmoid(rawLogit) });
+      } catch {
+        results.push({ index: i, score: 0 });
+      }
+    }
+    results.sort((a, b) => b.score - a.score);
+    return results;
+  }
+}
+
+async function handleExpand(args: { prompt: string; maxNewTokens: number; noRepeatNgramSize: number }): Promise<string> {
+  if (!expanderPipeline) throw new Error('expander not loaded');
+  const result = await expanderPipeline(args.prompt, {
+    max_new_tokens: args.maxNewTokens,
+    no_repeat_ngram_size: args.noRepeatNgramSize,
+  });
+  const text = Array.isArray(result) ? (result[0] as any)?.generated_text ?? '' : '';
+  return String(text).trim();
+}
+
+// --- Main loop ---
+
+let shuttingDown = false;
+const inflight = new Set<Promise<void>>();
+
+async function loadModel(): Promise<void> {
+  switch (role) {
+    case 'embed': await loadEmbedder(); break;
+    case 'rerank': await loadReranker(); break;
+    case 'expand': await loadExpander(); break;
+  }
+}
+
+async function handleMessage(msg: { id: number; op: WorkerRole; args: any }): Promise<void> {
+  try {
+    let result: unknown;
+    switch (msg.op) {
+      case 'embed':  result = await handleEmbed(msg.args); break;
+      case 'rerank': result = await handleRerank(msg.args); break;
+      case 'expand': result = await handleExpand(msg.args); break;
+    }
+    parentPort!.postMessage({ id: msg.id, ok: true, result });
+  } catch (err) {
+    parentPort!.postMessage({ id: msg.id, ok: false, error: String((err as Error)?.message ?? err) });
+  }
+}
+
+(async () => {
+  try {
+    await loadModel();
+    parentPort!.postMessage({ ready: true, role });
+  } catch (err) {
+    parentPort!.postMessage({ ready: false, role, error: String((err as Error)?.message ?? err) });
+    process.exit(1);
+  }
+})();
+
+parentPort.on('message', (msg: any) => {
+  if (msg?.shutdown) {
+    shuttingDown = true;
+    // Wait for in-flight work, then exit
+    void Promise.allSettled([...inflight]).then(() => {
+      parentPort!.postMessage({ shutdown: 'done' });
+      process.exit(0);
+    });
+    return;
+  }
+  if (shuttingDown) return;
+  if (typeof msg?.id !== 'number' || typeof msg?.op !== 'string') return;
+
+  const promise = handleMessage(msg);
+  inflight.add(promise);
+  void promise.finally(() => inflight.delete(promise));
+});