@matatbread/matbot-core 0.1.0

package/src/single-turn.ts

@@ -0,0 +1,64 @@
+import type { Tool, ToolExecutor, ToolContext, ToolEvent, MatbotMachine } from '@matatbread/matbot-plugin-api';
+
+/**
+ * Exposes {@link MatbotMachine.singleTurn} to the model: a one-shot completion against a configured
+ * provider, returning its reply. The intended use is consulting another model (e.g. a different-lineage
+ * critic of the current draft, or any generation that should run on a specific provider) with a
+ * well-defined interface, rather than the model improvising a bash/curl call.
+ *
+ * `provider` is optional: omitted, the call runs on the current turn's provider ({@link ToolContext.provider}).
+ * This is the general case — name a provider to switch models, or leave it off to relay through the
+ * model already in use. It lives in core (not in any plugin) because it is the model-facing surface of
+ * 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> {
+      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;
+      if (!provider) {
+        yield { type: 'error', message: 'single_turn needs a "provider" — none was given and there is no current turn provider to fall back to.' };
+        return;
+      }
+      if (!services.providers.has(provider)) {
+        const known = [...services.providers.keys()].join(', ') || '(none configured)';
+        yield { type: 'error', message: `Unknown provider "${provider}". Configured providers: ${known}.` };
+        return;
+      }
+      const res = await services.singleTurn({
+        provider,
+        prompt: args.prompt,
+        signal: ctx.signal,
+        ...(typeof args.system === 'string' ? { system: args.system } : {}),
+      });
+      yield { type: 'result', value: { text: res.text, usage: res.usage } };
+    },
+  };
+
+  return {
+    name: 'single_turn',
+    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, ' +
+      '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' +
+      '```',
+    inputSchema: {
+      type:       'object',
+      required:   ['prompt'],
+      properties: {
+        provider: { type: 'string', description: 'Name of a configured provider to run the completion against. Optional — defaults to the current turn\'s provider.' },
+        prompt:   { type: 'string', description: 'The user message to send to that provider.' },
+        system:   { type: 'string', description: 'Optional system prompt for the call.' },
+      },
+    },
+    executor,
+  };
+}

package/src/storage-base/index.ts

@@ -0,0 +1 @@
+export * from './query/index.js';

package/src/storage-base/query/access.ts

@@ -0,0 +1,16 @@
+import type { FieldPath } from '@matatbread/matbot-plugin-api';
+
+export function pathSegments(field: FieldPath): string[] {
+  return Array.isArray(field) ? field : [field];
+}
+
+// Null-safe traversal (the grammar's implicit `?.`): any absent or non-object segment
+// short-circuits to undefined and never throws. A present `null` is returned as-is.
+export function getField(row: unknown, segments: string[]): unknown {
+  let cur: unknown = row;
+  for (const seg of segments) {
+    if (cur === null || typeof cur !== 'object') return undefined;
+    cur = (cur as Record<string, unknown>)[seg];
+  }
+  return cur;
+}

package/src/storage-base/query/compile.ts

@@ -0,0 +1,42 @@
+import type { Filter, Orderable } from '@matatbread/matbot-plugin-api';
+import { getField, pathSegments } from './access.js';
+
+type Predicate = (row: unknown) => boolean;
+
+// null and absent collapse to a single "missing" state — no comparison ever matches a missing
+// value (so `neq` excludes missing rows too). Only `exists` observes missing-ness.
+function resolve(row: unknown, seg: string[]): unknown {
+  const v = getField(row, seg);
+  return v === null ? undefined : v;
+}
+
+// Ordering is defined only within a type (numeric for numbers, codepoint for strings). A
+// cross-type comparison yields undefined → the predicate is false (type-mismatch no-match).
+function order(a: unknown, b: Orderable): number | undefined {
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  if (typeof a === 'string' && typeof b === 'string') return a < b ? -1 : a > b ? 1 : 0;
+  return undefined;
+}
+
+// Compile the AST to a composed closure — the same one-pass "compile to native" the SQL/ES
+// backends do, with JS closures as the target. No `eval`/`new Function`: CSP-safe, and operands
+// are captured as data so there is no injection surface.
+export function compileFilter(f: Filter): Predicate {
+  switch (f.op) {
+    case 'and': { const ps = f.clauses.map(compileFilter); return r => ps.every(p => p(r)); }
+    case 'or':  { const ps = f.clauses.map(compileFilter); return r => ps.some(p => p(r)); }
+    case 'not': { const p = compileFilter(f.clause); return r => !p(r); }
+
+    case 'eq':  { const seg = pathSegments(f.field), v = f.value; return r => resolve(r, seg) === v; }
+    case 'neq': { const seg = pathSegments(f.field), v = f.value; return r => { const x = resolve(r, seg); return x !== undefined && x !== v; }; }
+    case 'lt':  { const seg = pathSegments(f.field), v = f.value; return r => { const c = order(resolve(r, seg), v); return c !== undefined && c < 0; }; }
+    case 'lte': { const seg = pathSegments(f.field), v = f.value; return r => { const c = order(resolve(r, seg), v); return c !== undefined && c <= 0; }; }
+    case 'gt':  { const seg = pathSegments(f.field), v = f.value; return r => { const c = order(resolve(r, seg), v); return c !== undefined && c > 0; }; }
+    case 'gte': { const seg = pathSegments(f.field), v = f.value; return r => { const c = order(resolve(r, seg), v); return c !== undefined && c >= 0; }; }
+    case 'in':  { const seg = pathSegments(f.field), vs = f.value as unknown[]; return r => { const x = resolve(r, seg); return x !== undefined && vs.includes(x); }; }
+    case 'nin': { const seg = pathSegments(f.field), vs = f.value as unknown[]; return r => { const x = resolve(r, seg); return x !== undefined && !vs.includes(x); }; }
+    case 'exists':         { const seg = pathSegments(f.field), want = f.value; return r => (resolve(r, seg) !== undefined) === want; }
+    case 'stringContains': { const seg = pathSegments(f.field), v = f.value; return r => { const x = resolve(r, seg); return typeof x === 'string' && x.includes(v); }; }
+    case 'arrayContains':  { const seg = pathSegments(f.field), v = f.value; return r => { const x = getField(r, seg); return Array.isArray(x) && (x as unknown[]).includes(v); }; }
+  }
+}

package/src/storage-base/query/execute.ts

@@ -0,0 +1,49 @@
+import type { StoreQuery, QueryResult } from '@matatbread/matbot-plugin-api';
+import { validateQuery } from './validate.js';
+import { compileFilter } from './compile.js';
+import { applySort } from './sort.js';
+import { encodeCursor, decodeCursor, type PageState } from './paginate.js';
+
+function toQuery(p: PageState): StoreQuery {
+  return {
+    ...(p.where !== undefined ? { where: p.where } : {}),
+    ...(p.sort  !== undefined ? { sort:  p.sort  } : {}),
+    ...(p.limit !== undefined ? { limit: p.limit } : {}),
+  };
+}
+
+// Reference in-memory execution: validate → filter → totally-order → paginate. Backends that load
+// all documents into memory (filesystem, IndexedDB, sqlite-as-blob) delegate here; a pushdown
+// backend would instead compile the same StoreQuery to its native query language.
+//
+// A cursor is self-contained: it carries the query, sort, page size, and position, so a caller can
+// page by sending only the cursor back. When a cursor is present it fully determines the page —
+// any where/sort/limit passed alongside it are ignored — which is what makes consecutive pages a
+// disjoint cover (page N re-applies the same sort as page 1, so the total order never shifts). A
+// cursor is untrusted input, so its decoded query is validated exactly like a fresh one.
+export function executeQuery<T extends { id: string; version: string }>(docs: T[], q: StoreQuery): QueryResult<T> {
+  const page: PageState = q.cursor !== undefined
+    ? decodeCursor(q.cursor)
+    : {
+        offset: 0,
+        ...(q.where !== undefined ? { where: q.where } : {}),
+        ...(q.sort  !== undefined ? { sort:  q.sort  } : {}),
+        ...(q.limit !== undefined ? { limit: q.limit } : {}),
+      };
+
+  validateQuery(toQuery(page));
+
+  const predicate = page.where !== undefined ? compileFilter(page.where) : () => true;
+  const ordered   = applySort(docs.filter(predicate), page.sort);
+
+  const total = ordered.length;
+  const end   = page.limit !== undefined ? page.offset + page.limit : ordered.length;
+  const slice = ordered.slice(page.offset, end);
+  const next  = page.offset + slice.length;
+
+  return {
+    items: slice,
+    total,
+    ...(next < total ? { cursor: encodeCursor({ ...page, offset: next }) } : {}),
+  };
+}

package/src/storage-base/query/index.ts

@@ -0,0 +1,6 @@
+export { getField, pathSegments } from './access.js';
+export { compileFilter }           from './compile.js';
+export { validateQuery }           from './validate.js';
+export { applySort }               from './sort.js';
+export { encodeCursor, decodeCursor, type PageState } from './paginate.js';
+export { executeQuery }            from './execute.js';

package/src/storage-base/query/paginate.ts

@@ -0,0 +1,26 @@
+import type { Filter, SortSpec } from '@matatbread/matbot-plugin-api';
+import { StoreQueryError } from '@matatbread/matbot-plugin-api';
+
+// Everything needed to reproduce the next page deterministically: the query, its sort, the page
+// size, and the position. The cursor is opaque and self-contained — a caller pages by sending only
+// a previous result's cursor back. The in-memory reference backend carries the literal query and an
+// offset; a pushdown backend would carry its own keyset under the same opaque contract.
+export interface PageState {
+  where?:  Filter;
+  sort?:   SortSpec[];
+  limit?:  number;
+  offset:  number;
+}
+
+export function encodeCursor(state: PageState): string {
+  return JSON.stringify(state);
+}
+
+export function decodeCursor(cursor: string): PageState {
+  let parsed: unknown;
+  try { parsed = JSON.parse(cursor); } catch { parsed = undefined; }
+  const offset = (parsed as { offset?: unknown } | undefined)?.offset;
+  if (parsed === null || typeof parsed !== 'object' || typeof offset !== 'number' || !Number.isInteger(offset) || offset < 0)
+    throw new StoreQueryError('unreadable cursor — pass back a cursor from a previous result verbatim', '/cursor', 'MALFORMED');
+  return parsed as PageState;
+}

package/src/storage-base/query/sort.ts

@@ -0,0 +1,29 @@
+import type { SortSpec } from '@matatbread/matbot-plugin-api';
+import { getField, pathSegments } from './access.js';
+
+// Compares two resolved field values. Missing (undefined/null) sorts last; numbers compare
+// numerically, everything else by string codepoint order.
+function compareValues(a: unknown, b: unknown): number {
+  if (a === b) return 0;
+  const am = a === undefined || a === null;
+  const bm = b === undefined || b === null;
+  if (am || bm) return am ? (bm ? 0 : 1) : -1;
+  if (typeof a === 'number' && typeof b === 'number') return a - b;
+  const as = String(a), bs = String(b);
+  return as < bs ? -1 : as > bs ? 1 : 0;
+}
+
+// Sorts by the requested specs, then appends `id` as a final tiebreaker so the order is always
+// total — without which an opaque cursor over the result could not point at a stable boundary.
+export function applySort<T extends { id: string }>(docs: T[], sort: SortSpec[] | undefined): T[] {
+  const compiled = [...(sort ?? []), { field: 'id', dir: 'asc' as const }]
+    .map(s => ({ seg: pathSegments(s.field), sign: s.dir === 'desc' ? -1 : 1 }));
+
+  return [...docs].sort((a, b) => {
+    for (const { seg, sign } of compiled) {
+      const c = compareValues(getField(a, seg), getField(b, seg));
+      if (c !== 0) return c * sign;
+    }
+    return 0;
+  });
+}

package/src/storage-base/query/validate.ts

@@ -0,0 +1,113 @@
+import type { StoreQuery, Filter } from '@matatbread/matbot-plugin-api';
+import { StoreQueryError } from '@matatbread/matbot-plugin-api';
+
+// Validate the query at the boundary, before any backend touches data, and throw a located,
+// detailed StoreQueryError so an LLM author can fix the offending clause and retry. Input is
+// treated as untrusted (LLM/JSON-sourced) — the static types are only a convenience for callers.
+
+function isComparable(v: unknown): boolean {
+  return typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
+}
+
+function requireComparable(v: unknown, ptr: string, op: string): void {
+  if (v === null)
+    throw new StoreQueryError(`'${op}' cannot compare to null — use { op: 'exists', value: false } to match absent-or-null`, ptr, 'NULL_OPERAND');
+  if (!isComparable(v))
+    throw new StoreQueryError(`'${op}' requires a string|number|boolean value`, ptr, 'OPERAND_TYPE');
+}
+
+function requireOrderable(v: unknown, ptr: string, op: string): void {
+  if (v === null)
+    throw new StoreQueryError(`'${op}' cannot compare to null — use { op: 'exists', value: false }`, ptr, 'NULL_OPERAND');
+  if (typeof v !== 'string' && typeof v !== 'number')
+    throw new StoreQueryError(`'${op}' requires a string|number value`, ptr, 'OPERAND_TYPE');
+}
+
+function validateField(field: unknown, ptr: string): void {
+  if (typeof field === 'string') {
+    if (field.length === 0) throw new StoreQueryError('field path is empty', ptr, 'EMPTY_FIELD');
+    return;
+  }
+  if (Array.isArray(field)) {
+    if (field.length === 0) throw new StoreQueryError('field path has no segments', ptr, 'EMPTY_FIELD');
+    field.forEach((s, i) => {
+      if (typeof s !== 'string' || s.length === 0)
+        throw new StoreQueryError('field path segment must be a non-empty string', `${ptr}/${i}`, 'EMPTY_FIELD');
+    });
+    return;
+  }
+  throw new StoreQueryError('field must be a string or array of strings', ptr, 'MALFORMED');
+}
+
+function validateFilter(f: Filter, ptr: string): void {
+  if (f === null || typeof f !== 'object' || typeof (f as { op?: unknown }).op !== 'string')
+    throw new StoreQueryError('filter node must be an object with an `op`', ptr, 'MALFORMED');
+
+  switch (f.op) {
+    case 'and':
+    case 'or':
+      if (!Array.isArray(f.clauses) || f.clauses.length === 0)
+        throw new StoreQueryError(`'${f.op}' requires a non-empty clauses array`, `${ptr}/clauses`, 'EMPTY_CLAUSES');
+      f.clauses.forEach((c, i) => validateFilter(c, `${ptr}/clauses/${i}`));
+      return;
+    case 'not':
+      if (f.clause === undefined)
+        throw new StoreQueryError(`'not' requires a clause`, `${ptr}/clause`, 'MALFORMED');
+      validateFilter(f.clause, `${ptr}/clause`);
+      return;
+    case 'eq':
+    case 'neq':
+      validateField(f.field, `${ptr}/field`);
+      requireComparable(f.value, `${ptr}/value`, f.op);
+      return;
+    case 'lt':
+    case 'lte':
+    case 'gt':
+    case 'gte':
+      validateField(f.field, `${ptr}/field`);
+      requireOrderable(f.value, `${ptr}/value`, f.op);
+      return;
+    case 'in':
+    case 'nin':
+      validateField(f.field, `${ptr}/field`);
+      if (!Array.isArray(f.value))
+        throw new StoreQueryError(`'${f.op}' requires an array value`, `${ptr}/value`, 'OPERAND_TYPE');
+      f.value.forEach((el, i) => requireComparable(el, `${ptr}/value/${i}`, f.op));
+      return;
+    case 'exists':
+      validateField(f.field, `${ptr}/field`);
+      if (typeof f.value !== 'boolean')
+        throw new StoreQueryError(`'exists' requires a boolean value`, `${ptr}/value`, 'OPERAND_TYPE');
+      return;
+    case 'stringContains':
+      validateField(f.field, `${ptr}/field`);
+      if (typeof f.value !== 'string')
+        throw new StoreQueryError(`'stringContains' requires a string value`, `${ptr}/value`, 'OPERAND_TYPE');
+      return;
+    case 'arrayContains':
+      validateField(f.field, `${ptr}/field`);
+      requireComparable(f.value, `${ptr}/value`, f.op);
+      return;
+    default:
+      throw new StoreQueryError(`unknown op '${String((f as { op: unknown }).op)}'`, `${ptr}/op`, 'UNKNOWN_OP');
+  }
+}
+
+export function validateQuery(q: StoreQuery): void {
+  if (q.where !== undefined) validateFilter(q.where, '/where');
+
+  if (q.sort !== undefined) {
+    if (!Array.isArray(q.sort))
+      throw new StoreQueryError('`sort` must be an array', '/sort', 'MALFORMED');
+    q.sort.forEach((s, i) => {
+      if (s === null || typeof s !== 'object')
+        throw new StoreQueryError('sort spec must be an object', `/sort/${i}`, 'MALFORMED');
+      validateField(s.field, `/sort/${i}/field`);
+      if (s.dir !== 'asc' && s.dir !== 'desc')
+        throw new StoreQueryError(`sort dir must be 'asc' or 'desc'`, `/sort/${i}/dir`, 'MALFORMED');
+    });
+  }
+
+  if (q.limit !== undefined && (typeof q.limit !== 'number' || !Number.isInteger(q.limit) || q.limit < 0))
+    throw new StoreQueryError('`limit` must be a non-negative integer', '/limit', 'MALFORMED');
+}

package/src/system-context.ts

@@ -0,0 +1,26 @@
+import type { Session, SystemContextContributor, SystemContextRegistry } from './types.js';
+
+interface TaggedContributor {
+  fn:          SystemContextContributor;
+  pluginName?: string;
+}
+
+export class SystemContextRegistryImpl implements SystemContextRegistry {
+  private readonly _contributors: TaggedContributor[] = [];
+
+  register(contributor: SystemContextContributor, pluginName?: string): void {
+    this._contributors.push({ fn: contributor, ...(pluginName !== undefined ? { pluginName } : {}) });
+  }
+
+  removeByPlugin(pluginName: string): void {
+    for (let i = this._contributors.length - 1; i >= 0; i--) {
+      if (this._contributors[i]?.pluginName === pluginName) this._contributors.splice(i, 1);
+    }
+  }
+
+  async build(ctx: { session: Session; signal: AbortSignal }): Promise<string | null> {
+    const parts = (await Promise.all(this._contributors.map(c => c.fn(ctx))))
+      .filter((s): s is string => typeof s === 'string' && s.length > 0);
+    return parts.length > 0 ? parts.join('\n\n') : null;
+  }
+}

package/src/tool-registry.ts

@@ -0,0 +1,38 @@
+import type { Tool, ToolRegistry, ToolRegistryEvent } from './types.js';
+import { createBroadcaster } from '@matatbread/matbot-plugin-api';
+
+export class ToolRegistryImpl implements ToolRegistry {
+  private readonly tools = new Map<string, Tool>();
+  private readonly events = createBroadcaster<ToolRegistryEvent>();
+
+  constructor(initial?: Iterable<Tool>) {
+    if (initial !== undefined) for (const tool of initial) this.tools.set(tool.name, tool);
+  }
+
+  register(tool: Tool): void {
+    this.tools.set(tool.name, tool);
+    this.events.emit({ type: 'registered', name: tool.name, ...(tool.pluginName !== undefined ? { pluginName: tool.pluginName } : {}) });
+  }
+
+  remove(name: string): void {
+    if (this.tools.delete(name)) this.events.emit({ type: 'removed', name });
+  }
+
+  removeByPlugin(pluginName: string): void {
+    for (const [name, tool] of this.tools) {
+      if (tool.pluginName === pluginName && this.tools.delete(name)) this.events.emit({ type: 'removed', name });
+    }
+  }
+
+  resolve(name: string): Tool | null {
+    return this.tools.get(name) ?? null;
+  }
+
+  list(): Tool[] {
+    return [...this.tools.values()];
+  }
+
+  watch(signal?: AbortSignal): AsyncIterable<ToolRegistryEvent> {
+    return this.events.subscribe(signal);
+  }
+}

package/src/types.ts

@@ -0,0 +1,13 @@
+export type * from '@matatbread/matbot-plugin-api';
+
+// ── Internal types (not part of the plugin API) ───────────────────────────────
+
+import type {
+  ProviderAdapter,
+} from '@matatbread/matbot-plugin-api';
+
+export interface ProviderRegistry {
+  register(adapter: ProviderAdapter): void;
+  resolve(name: string): ProviderAdapter;
+}
+