@matatbread/matbot-core 0.2.3 → 0.2.5

package/package.json

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

package/src/index.ts

@@ -25,8 +25,11 @@ export {
   installPrincipalCarrier, currentPrincipal, tryCurrentPrincipal,
   runAs, enterPrincipal, createConstantPrincipalCarrier,
   contextSwitch, onContextQuiesce, flushIfQuiescent,
+  installUsageCarrier, createSerialUsageCarrier, recordUsage, currentUsageSink, withUsageScope,
+  lastActivityAt,
 } from '@matatbread/matbot-plugin-api';
 export * from './session.js';
+export * from './usage.js';
 export * from './hooks.js';
 export * from './runner.js';
 export * from './session-runner.js';

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>();
 
@@ -23,35 +115,29 @@ export class LookupKnowledgeIndex implements KnowledgeIndex {
   }
 
   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/runner.ts

@@ -1,11 +1,13 @@
 import type {
-  Session, MessageContent,
+  Session, MessageContent, Usage,
   PipelineEvent, RunConfig, ProviderAdapter, ProviderConfig,
   Tool, ToolRegistry, ToolContext, Store, FileStore, SystemContextRegistry, Vault, PromptFn, FormField,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
+import { currentUsageSink } from '@matatbread/matbot-plugin-api';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
+import { addUsage } from './usage.js';
 
 export interface RunSessionOpts {
   session:        Session;
@@ -40,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>;
 }
 
@@ -130,6 +132,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
     const pendingCalls: Array<{ id: string; name: string; input: unknown }> = [];
     const assistantParts: MessageContent[] = [];
     let textAcc = '';
+    let turnUsage: Usage | undefined;
 
     // One provider call. The outgoing array (system context + history, with screen's ephemeral
     // blocks appended onto the tail message) is assembled here and handed to `contribute` hooks for
@@ -172,6 +175,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
             pendingCalls.push({ id: ev.id, name: ev.name, input: ev.input });
             break;
           case 'usage':
+            turnUsage = addUsage(turnUsage, ev);
             yield { type: 'usage', inputTokens: ev.inputTokens, outputTokens: ev.outputTokens, traceId,
               ...(ev.costUsd              !== undefined ? { costUsd:              ev.costUsd              } : {}),
               ...(ev.cacheReadTokens     !== undefined ? { cacheReadTokens:     ev.cacheReadTokens     } : {}),
@@ -188,6 +192,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         if (assistantParts.length > 0) {
           session = appendMessage(session, createMessage({
             role: 'assistant', content: assistantParts, traceId, providerName: config.provider,
+            ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
           }));
         }
         await store.set(session.id, session);
@@ -210,6 +215,7 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         content:      assistantParts,
         traceId,
         providerName: config.provider,
+        ...(turnUsage !== undefined ? { usage: turnUsage } : {}),
       });
       session = appendMessage(session, assistantMsg);
     } else {
@@ -257,13 +263,17 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
 
       let result: unknown;
       let isError = false;
+      // Token accounting for completions this tool runs (via singleTurn/complete) accrues into the
+      // ambient turn sink; slice off whatever it appends during *this* call to attribute it here.
+      const usageSink = currentUsageSink();
+      const usageMark = usageSink?.length ?? 0;
       const startedAt = Date.now();
 
       const toolCtx: ToolContext = {
         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  } : {}),
@@ -278,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 } : {}),
@@ -299,7 +309,9 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<PipelineE
         tool, result, isError, durationMs: Date.now() - startedAt,
       });
 
-      toolResults.push({ type: 'tool-result', id: tc.id, result, isError });
+      const callUsage = usageSink ? usageSink.slice(usageMark) : [];
+      toolResults.push({ type: 'tool-result', id: tc.id, result, isError,
+        ...(callUsage.length > 0 ? { usage: callUsage } : {}) });
       yield { type: 'tool:end', callId: tc.id, result, isError, traceId };
     }
 

package/src/session-runner.ts

@@ -6,7 +6,7 @@ import type {
 import type { MatbotPlugin } from './plugin.js';
 import type { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
-import { contextSwitch } from '@matatbread/matbot-plugin-api';
+import { contextSwitch, withUsageScope } from '@matatbread/matbot-plugin-api';
 import { runSession } from './runner.js';
 
 export interface SessionRunnerDeps {
@@ -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>;
 }
 
@@ -219,7 +219,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // the callback: an async iterator returned out of the scope would lose it before it pulls.
           // contextSwitch (not bare runAs): a turn is the transactional unit, so a StorageBackend swap
           // deferred during it lands at this scope's quiescent edge — never mid-CAS.
-          await contextSwitch(head.principal, async () => {
+          await contextSwitch(head.principal, () => withUsageScope(async () => {
             for await (const ev of runSession({
               session,
               config:         { provider: head.provider, traceId: head.traceId },
@@ -242,7 +242,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
             })) {
               emit(s, ev);
             }
-          });
+          }));
 
           // followup — post-commit, in the queue owner. A hook reads the just-committed turn and may
           // head-enqueue a robo follow-up (its own real turn, running next). Skipped on abort; runs

package/src/session.ts

@@ -1,4 +1,4 @@
-import type { Session, Message, MessageContent, MessageRole, Principal } from './types.js';
+import type { Session, Message, MessageContent, MessageRole, Principal, Usage } from './types.js';
 
 export interface CreateSessionOpts {
   ownerPrincipal:        Principal;
@@ -32,10 +32,12 @@ export function createSession(opts: CreateSessionOpts): Session {
 }
 
 export function appendMessage(session: Session, message: Message): Session {
+  // updatedAt tracks conversational activity: the new last message's timestamp (the lastActivityAt
+  // invariant), not a fresh `now()` — so it stays consistent with structural edits that preserve the tail.
   return {
     ...session,
     messages:  [...session.messages, message],
-    updatedAt: new Date().toISOString(),
+    updatedAt: message.createdAt,
     version:   crypto.randomUUID(),
   };
 }
@@ -45,6 +47,7 @@ export function createMessage(opts: {
   content:        MessageContent[];
   traceId:        string;
   providerName?:  string;
+  usage?:         Usage;
   metadata?:      Record<string, unknown>;
 }): Message {
   return {
@@ -54,6 +57,7 @@ export function createMessage(opts: {
     createdAt: new Date().toISOString(),
     traceId:   opts.traceId,
     ...(opts.providerName !== undefined ? { providerName: opts.providerName } : {}),
+    ...(opts.usage        !== undefined ? { usage:        opts.usage        } : {}),
     ...(opts.metadata     !== undefined ? { metadata:     opts.metadata     } : {}),
   };
 }

package/src/single-turn.ts

@@ -33,7 +33,9 @@ export function createSingleTurnTool(services: MatbotMachine): Tool {
         signal: ctx.signal,
         ...(typeof args.system === 'string' ? { system: args.system } : {}),
       });
-      yield { type: 'result', value: { text: res.text, usage: res.usage } };
+      // Usage is accounting, not conversation: it is captured ambiently (the host's complete() reports
+      // it into the turn's usage sink, attributed to this tool call) — the model gets only the text.
+      yield { type: 'result', value: { text: res.text } };
     },
   };
 
@@ -42,13 +44,13 @@ export function createSingleTurnTool(services: MatbotMachine): Tool {
     description:
       'Run a single-turn completion against a configured provider and return its reply. This is a ' +
       'one-shot call — not your own response: you send one `prompt` (and optional `system`), and get ' +
-      'back its text and token usage. Use it to consult a different model — e.g. a second, ' +
+      'back its text. Use it to consult a different model — e.g. a second, ' +
       'different-lineage model critiquing your draft, or any generation that should run on a specific ' +
       'provider. `provider` is OPTIONAL: omit it to run on the current conversation\'s model, or name ' +
       'a configured provider to switch models (list or add providers with the provider tool).\n\n' +
       'Parameters (TypeScript):\n' +
       '```ts\n' +
-      '{ provider?: string; prompt: string; system?: string }  // -> { text, usage: { inputTokens, outputTokens } }\n' +
+      '{ provider?: string; prompt: string; system?: string }  // -> { text }\n' +
       '```',
     inputSchema: {
       type:       'object',

package/src/usage.ts

@@ -0,0 +1,36 @@
+import type { Message, Usage } from './types.js';
+
+/** Fold one usage tally into a running total; optional fields are summed only when either side has them. */
+export function addUsage(acc: Usage | undefined, next: Usage): Usage {
+  const a = acc ?? { inputTokens: 0, outputTokens: 0 };
+  const add = (x: number | undefined, y: number | undefined): number | undefined =>
+    x === undefined && y === undefined ? undefined : (x ?? 0) + (y ?? 0);
+  return {
+    inputTokens:  a.inputTokens  + next.inputTokens,
+    outputTokens: a.outputTokens + next.outputTokens,
+    ...(((c) => c !== undefined ? { costUsd:             c } : {}))(add(a.costUsd,             next.costUsd)),
+    ...(((c) => c !== undefined ? { cacheReadTokens:     c } : {}))(add(a.cacheReadTokens,     next.cacheReadTokens)),
+    ...(((c) => c !== undefined ? { cacheCreationTokens: c } : {}))(add(a.cacheCreationTokens, next.cacheCreationTokens)),
+  };
+}
+
+/**
+ * Aggregate the token accounting recorded on a set of messages, keyed by the provider billed: an
+ * assistant turn's own `Message.usage` (billed to its `providerName`) plus every `tool-result` block's
+ * `usage` records (each provider-tagged — a tool may run completions against several). Pass a single
+ * turn's messages (filtered by `traceId`) for a per-turn breakdown, or a whole session for its total.
+ */
+export function usageByProvider(messages: Iterable<Message>): Map<string, Usage> {
+  const out = new Map<string, Usage>();
+  for (const m of messages) {
+    if (m.usage !== undefined && m.providerName !== undefined) {
+      out.set(m.providerName, addUsage(out.get(m.providerName), m.usage));
+    }
+    for (const c of m.content) {
+      if (c.type === 'tool-result' && c.usage !== undefined) {
+        for (const r of c.usage) out.set(r.provider, addUsage(out.get(r.provider), r.usage));
+      }
+    }
+  }
+  return out;
+}