@matatbread/matbot-core 0.2.4 → 0.2.6

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.2.4",
+  "version": "0.2.6",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.2.4"
+    "@matatbread/matbot-plugin-api": "^0.2.6"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/knowledge/lookup-knowledge-index.ts

@@ -1,9 +1,101 @@
 import type { KnowledgeIndex, KnowledgeEntry } from '@matatbread/matbot-plugin-api';
 
-// In-memory KnowledgeIndex for development and environments without a BGE reranker.
-// Entries are held in a Set; search scores each doc by raw term-occurrence count, sorts
-// descending, then returns the top docs whose cumulative score covers 50% of the total —
-// surfacing clear winners quickly without drowning results in long-tail noise.
+// In-memory KnowledgeIndex for development and environments without a persistent/reranking
+// backend. Entries are held in a Set; search scores each entry across its curated metadata
+// (entities, tags, summary) as well as its content, then returns the clear winners.
+//
+// Scoring rationale — the metadata is the signal, the body is the tie-breaker. A curated entity
+// match is the strongest evidence an entry is *about* a term; a heading is next; the summary is a
+// tight, deliberately-written description; raw body text is the weakest (it is incidental and
+// length-biased — a long document mentions everything). Body occurrences are therefore saturated
+// (tf/(tf+k)), so a wordy entry can't win on sheer volume of passing mentions over a short entry
+// whose curated entities name the term outright. This deliberately does NOT weight by
+// procedural/informational class: that is not a relevance signal (a how-to about X is a fair match
+// for X) — it lives on the entry as metadata for other consumers, not here.
+const WEIGHT = {
+  entityExact: 10,  // the term IS a curated entity — strongest evidence
+  entityFuzzy:  4,  // the term is only a substring of an entity ("matt" in "plant matter") — weaker
+  tag:          4,
+  summary:      3,  // per occurrence, capped (the summary is short, so this is naturally bounded)
+  headingH1:    8,
+  headingH2:    5,
+  headingH3:    3,
+  body:         2,  // multiplied by a 0–1 saturation factor, so this is the per-term ceiling
+} as const;
+
+// Body term-frequency saturation: contribution = WEIGHT.body * tf/(tf + BODY_K). Diminishing
+// returns past a couple of mentions keep long documents from dominating on raw count.
+const BODY_K = 3;
+
+// Returned window: the clear winners by cumulative-score coverage, but always offer at least MIN
+// alternatives (when they exist) so a consumer can re-rank/filter, and never more than MAX.
+const COVERAGE = 0.5;
+const MIN_RESULTS = 3;
+const MAX_RESULTS = 10;
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Whole-word occurrence count, for free text (content, summary). Word-boundary matching avoids the
+// substring trap — "matt" must not match "matter", "owl" must not match "fowl" — that plain
+// indexOf() falls into. A multi-word term ("inner voice") is matched as a phrase.
+function countWordMatches(haystack: string, term: string): number {
+  const m = haystack.match(new RegExp(`\\b${escapeRegExp(term)}\\b`, 'g'));
+  return m ? m.length : 0;
+}
+
+// Looser, substring-in-either-direction match for CURATED fields (entities, tags), where fuzziness
+// is wanted: "matt" should match the entity "Matthew Woolf", "volvo" the entity "my volvo". Guarded
+// so the contained string is at least 3 chars, keeping "us" out of "user"/"bus".
+function fuzzyMatch(a: string, b: string): boolean {
+  if (a === b) return true;
+  if (b.length >= 3 && a.includes(b)) return true;
+  if (a.length >= 3 && b.includes(a)) return true;
+  return false;
+}
+
+function headingWeight(level: number): number {
+  if (level === 1) return WEIGHT.headingH1;
+  if (level === 2) return WEIGHT.headingH2;
+  return WEIGHT.headingH3;
+}
+
+function scoreContent(content: string, term: string): number {
+  let headingScore = 0;
+  let bodyTf = 0;
+  for (const line of content.split('\n')) {
+    const m = /^(#{1,3})(?!#)\s+(.+)/.exec(line);
+    if (m) {
+      if (countWordMatches(m[2]!.toLowerCase(), term) > 0) headingScore += headingWeight(m[1]!.length);
+    } else {
+      bodyTf += countWordMatches(line.toLowerCase(), term);
+    }
+  }
+  const bodyScore = bodyTf > 0 ? WEIGHT.body * (bodyTf / (bodyTf + BODY_K)) : 0;
+  return headingScore + bodyScore;
+}
+
+function scoreEntry(entry: KnowledgeEntry, terms: Array<{ term: string }>): number {
+  const entities = entry.entities.map(e => e.toLowerCase());
+  const tags     = entry.tags.map(t => t.toLowerCase());
+  const summary  = entry.summary.toLowerCase();
+  let score = 0;
+  for (const { term } of terms) {
+    const t = term.toLowerCase().trim();
+    if (t.length < 2) continue;
+    // Best single entity match for this term: exact beats fuzzy-substring, and we don't stack
+    // multiple entity hits for one term (one entity naming the term is the signal, not how many).
+    if (entities.includes(t)) score += WEIGHT.entityExact;
+    else if (entities.some(e => fuzzyMatch(e, t))) score += WEIGHT.entityFuzzy;
+    if (tags.some(g => fuzzyMatch(g, t))) score += WEIGHT.tag;
+    const sf = countWordMatches(summary, t);
+    if (sf > 0) score += WEIGHT.summary * Math.min(sf, 2);
+    score += scoreContent(entry.content, t);
+  }
+  return score;
+}
+
 export class LookupKnowledgeIndex implements KnowledgeIndex {
   readonly docs = new Set<KnowledgeEntry>();
 
@@ -22,36 +114,39 @@ export class LookupKnowledgeIndex implements KnowledgeIndex {
     this.docs.add(entry);
   }
 
+  async remove(id: string): Promise<void> {
+    for (const existing of this.docs) {
+      if (existing.id === id) {
+        this.docs.delete(existing);
+        return;
+      }
+    }
+  }
+
   async search(
-    terms:  Array<{ term: string; context?: string }>,
+    terms:   Array<{ term: string; context?: string }>,
     _signal: AbortSignal,
   ): Promise<KnowledgeEntry[]> {
-    const results: Array<{ entry: KnowledgeEntry; score: number }> = [];
+    if (terms.length === 0) return [];
 
+    const scored: Array<{ entry: KnowledgeEntry; score: number }> = [];
     for (const entry of this.docs) {
-      const text = entry.content.toLowerCase();
-      let score = 0;
-      for (const { term } of terms) {
-        const t = term.toLowerCase();
-        let pos = 0;
-        while ((pos = text.indexOf(t, pos)) !== -1) {
-          score++;
-          pos += t.length;
-        }
-      }
-      if (score > 0) results.push({ entry, score });
+      const score = scoreEntry(entry, terms);
+      if (score > 0) scored.push({ entry, score });
     }
+    scored.sort((a, b) => b.score - a.score);
 
-    results.sort((a, b) => b.score - a.score);
+    const total = scored.reduce((sum, r) => sum + r.score, 0);
+    if (total <= 0) return [];
 
-    const total     = results.reduce((sum, r) => sum + r.score, 0);
-    const threshold = total * 0.5;
-    let   cumulative = 0;
+    const target = total * COVERAGE;
     const top: KnowledgeEntry[] = [];
-    for (const { entry, score } of results) {
+    let cumulative = 0;
+    for (const { entry, score } of scored) {
       top.push(entry);
       cumulative += score;
-      if (cumulative >= threshold) break;
+      if (top.length >= MAX_RESULTS) break;
+      if (top.length >= MIN_RESULTS && cumulative >= target) break;
     }
     return top;
   }

package/src/loader.ts

@@ -118,7 +118,7 @@ export async function loadPlugins(
     ),
   );
 
-  const toLoad: { spec: string; importSpec: string; name?: string; runtimes?: readonly Runtime[] }[] = [];
+  const toLoad: { spec: string; importSpec: string; resolvedUrl: string; name?: string; runtimes?: readonly Runtime[] }[] = [];
   for (let i = 0; i < reqs.length; i++) {
     const { spec, importSpec, name } = reqs[i]!;
     const runtimes = declared[i];
@@ -132,6 +132,10 @@ export async function loadPlugins(
     toLoad.push({
       spec,
       importSpec: freshImportSpec(spec, importSpec, bustCache),
+      // The resolved location WITHOUT the reload cache-bust stamp — a stable `file:`/bare URL a
+      // consumer can map back to source (e.g. skills_compiler building a types program over the
+      // live plugin set). Falls back to the bare spec when the host pre-resolved nothing.
+      resolvedUrl: importSpec ?? spec,
       ...(name     !== undefined ? { name }     : {}),
       ...(runtimes !== undefined ? { runtimes } : {}),
     });
@@ -211,7 +215,8 @@ export async function loadPlugins(
     const plugin: MatbotPlugin = {
       ...spec_obj,
       name,
-      specifier: spec,
+      specifier:   spec,
+      resolvedUrl: toLoad[i]!.resolvedUrl,
       ...(source   !== undefined ? { source }                 : {}),
       ...(runtimes !== undefined ? { matbotRuntime: runtimes } : {}),
     };

package/src/runner.ts

@@ -42,7 +42,7 @@ export interface RunSessionOpts {
    * re-run of the originating user turn. Empty/absent for an ordinary turn.
    */
   injectedEphemeral?: MessageContent[];
-  loadPlugin:     (specifier: string, prompt?: PromptFn) => Promise<MatbotPlugin>;
+  loadPlugin:     (specifier: string, prompt?: PromptFn, refresh?: boolean) => Promise<MatbotPlugin>;
   unloadPlugin:   (specifier: string) => Promise<boolean>;
 }
 
@@ -273,7 +273,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         callId: tc.id, session, signal, vault,
         provider:     config.provider,
         prompt:       promptFn,
-        loadPlugin:   (specifier: string) => opts.loadPlugin(specifier, promptFn),
+        loadPlugin:   (specifier: string, refresh?: boolean) => opts.loadPlugin(specifier, promptFn, refresh),
         unloadPlugin: opts.unloadPlugin,
         ...(opts.workdir     !== undefined ? { workdir:     opts.workdir     } : {}),
         ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
@@ -288,7 +288,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
             case 'file':     yield { type: 'file', handle: toolEv.handle, traceId }; break;
             case 'result':   result = toolEv.value; break;
             case 'marker':   toolMarkers.push({ type: 'marker', creator: toolEv.creator, data: toolEv.data }); break;
-            case 'progress': break;
+            case 'progress': yield { type: 'tool:progress', callId: tc.id, pct: toolEv.pct, ...(toolEv.message !== undefined ? { message: toolEv.message } : {}), traceId }; break;
             case 'error':    result = {
               error: toolEv.message,
               ...(toolEv.stdout !== undefined ? { stdout: toolEv.stdout } : {}),

package/src/session-runner.ts

@@ -19,7 +19,7 @@ export interface SessionRunnerDeps {
   files?:          FileStore;
   workdir?:        string;
   configPath?:     string;
-  loadPlugin:      (specifier: string, prompt?: PromptFn) => Promise<MatbotPlugin>;
+  loadPlugin:      (specifier: string, prompt?: PromptFn, refresh?: boolean) => Promise<MatbotPlugin>;
   unloadPlugin:    (specifier: string) => Promise<boolean>;
 }
 

package/src/single-turn.ts

@@ -1,4 +1,10 @@
-import type { Tool, ToolExecutor, ToolContext, ToolEvent, MatbotMachine } from '@matatbread/matbot-plugin-api';
+import type { Tool, ToolExecutor, ToolResultOf, ToolContext, MatbotMachine } from '@matatbread/matbot-plugin-api';
+
+declare module '@matatbread/matbot-plugin-api' {
+  interface ToolResults {
+    single_turn: { text: string };  // the consulted provider's reply text
+  }
+}
 
 /**
  * Exposes {@link MatbotMachine.singleTurn} to the model: a one-shot completion against a configured
@@ -12,9 +18,9 @@ import type { Tool, ToolExecutor, ToolContext, ToolEvent, MatbotMachine } from '
  * a core service (`singleTurn`); core is also the one cross-runtime home both the node app and the
  * browser bundle register it from — the tool-plugin barrel (where `plugin`/`provider` live) is node-only.
  */
-export function createSingleTurnTool(services: MatbotMachine): Tool {
-  const executor: ToolExecutor = {
-    async *execute(input: unknown, ctx: ToolContext): AsyncIterable<ToolEvent> {
+export function createSingleTurnTool(services: MatbotMachine): Tool<ToolResultOf<'single_turn'>> {
+  const executor: ToolExecutor<ToolResultOf<'single_turn'>> = {
+    async *execute(input: unknown, ctx: ToolContext) {
       const args = input as { provider?: string; prompt?: string; system?: string };
       if (typeof args.prompt !== 'string') { yield { type: 'error', message: 'single_turn requires a string "prompt".' }; return; }
       const provider = args.provider ?? ctx.provider;