@matatbread/matbot-plugin-api 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"
   },

package/src/index.ts

@@ -4,7 +4,10 @@ export * from './store-query.js';
 export * from './vault.js';
 export * from './errors.js';
 export * from './principal-context.js';
+export * from './usage-context.js';
+export * from './session.js';
 export * from './context-switch.js';
 export * from './hooks.js';
 export * from './plugin.js';
 export * from './broadcast.js';
+export * from './invoke-tool.js';

package/src/invoke-tool.ts

@@ -0,0 +1,100 @@
+import type { MatbotMachine } from './plugin.js';
+import type { ToolContext, ToolEvent, ToolResultOf, PromptFn, FormField } from './types.js';
+
+/**
+ * Inputs to {@link invokeTool} that a one-shot caller can't derive from the machine. A tool
+ * forwarding a call to another tool should pass its own {@link ToolContext} straight through as
+ * `opts` — `session`, `signal`, `prompt` and crucially **`provider`** all propagate, so a callee
+ * that needs an LLM (e.g. `find_fact`, or anything using `singleTurn`) inherits the same model
+ * rather than finding no provider. Only spell out individual fields when starting a call from
+ * scratch or deliberately overriding one; never hand-pick a subset of `ctx` and drop the rest.
+ */
+export type InvokeToolOptions =
+  Pick<ToolContext, 'session' | 'signal'>
+  & Partial<Pick<ToolContext, 'prompt' | 'provider' | 'callId'>>;
+
+/**
+ * Programmatically invoke a tool by name, the same way the harness does — resolve it off the
+ * machine's tool registry, build a `ToolContext` from the machine, and return its event stream.
+ * The host-only bits a one-shot caller can't derive (the session under which the call runs, its
+ * abort signal, and an optional interactive `prompt`/`provider`) come in via `opts` — pass the
+ * calling tool's `ctx` to forward them all (see {@link InvokeToolOptions}); everything else (vault,
+ * plugin (un)loading, workdir/configPath/files) is filled from `machine`.
+ *
+ * Throws synchronously if no tool is registered under `name`. When no `prompt` is supplied the tool
+ * runs non-interactively: any attempt to prompt rejects, which a tool surfaces as a normal error
+ * event. Pair with {@link toolText} to collapse the stream to its result string.
+ */
+export function invokeTool<K extends string>(
+  machine: MatbotMachine,
+  name:    K,
+  params:  unknown,
+  opts:    InvokeToolOptions,
+): AsyncIterable<ToolEvent<ToolResultOf<K>>> {
+  const tool = machine.tools.resolve(name);
+  if (tool === null) throw new Error(`Tool "${name}" is not registered`);
+
+  const prompt = opts.prompt ?? rejectingPrompt;
+  const ctx: ToolContext = {
+    callId:       opts.callId ?? crypto.randomUUID(),
+    session:      opts.session,
+    signal:       opts.signal,
+    vault:        machine.Vault,
+    prompt,
+    loadPlugin:   (specifier, refresh) => machine.loadPlugin(specifier, prompt, refresh),
+    unloadPlugin: (specifier) => machine.unloadPlugin(specifier),
+    ...(opts.provider      !== undefined ? { provider:   opts.provider      } : {}),
+    ...(machine.workdir    !== undefined ? { workdir:    machine.workdir    } : {}),
+    ...(machine.configPath !== undefined ? { configPath: machine.configPath } : {}),
+    ...(machine.files      !== undefined ? { files:      machine.files      } : {}),
+  };
+
+  // The registry is name-keyed and untyped (`ToolExecutor.execute` yields `ToolEvent<unknown>`); the
+  // `ToolResults` mapping is the call-site contract, asserted here so callers read a typed result.
+  return tool.executor.execute(params, ctx) as AsyncIterable<ToolEvent<ToolResultOf<K>>>;
+}
+
+/**
+ * Drain a tool event stream (e.g. {@link invokeTool}'s return) to its raw `result` *value*, typed:
+ * paired with `invokeTool(machine, name, …)` it returns whatever `ToolResults[name]` declares (or
+ * `unknown` for an unregistered tool). This is the structured counterpart to {@link toolText} — use it
+ * for any tool that returns data; use `toolText` when you want the result collapsed to a string.
+ * Stops and throws on the first `error` event, or if the tool finished without yielding a `result`.
+ */
+export async function toolResult<R>(events: AsyncIterable<ToolEvent<R>>): Promise<R> {
+  let value!: R;
+  let hadResult = false;
+  for await (const ev of events) {
+    if      (ev.type === 'result') { value = ev.value; hadResult = true; }
+    else if (ev.type === 'error')  { throw new Error(ev.message); }
+  }
+  if (!hadResult) throw new Error('Tool produced no result');
+  return value;
+}
+
+/**
+ * Drain a tool event stream (e.g. {@link invokeTool}'s return) to its result as text. Stops and
+ * throws on the first `error` event, or if the tool finished without yielding a `result`. The result
+ * value is rendered the way the model would see it: a string verbatim, a `{ content: string }`
+ * (the shape `skill_action` and other prose tools return) by its `content`, anything else as JSON.
+ */
+export async function toolText(events: AsyncIterable<ToolEvent>): Promise<string> {
+  let result: unknown;
+  let hadResult = false;
+  for await (const ev of events) {
+    if      (ev.type === 'result') { result = ev.value; hadResult = true; }
+    else if (ev.type === 'error')  { throw new Error(ev.message); }
+  }
+  if (!hadResult) throw new Error('Tool produced no result');
+
+  if (typeof result === 'string') return result;
+  if (result !== null && typeof result === 'object' && typeof (result as { content?: unknown }).content === 'string') {
+    return (result as { content: string }).content;
+  }
+  return JSON.stringify(result, null, 2);
+}
+
+const rejectingPrompt: PromptFn = (((p: string | FormField): Promise<string> => {
+  const label = typeof p === 'string' ? p : p.label;
+  return Promise.reject(new Error(`Non-interactive context: cannot prompt for "${label}"`));
+}) as PromptFn);

package/src/plugin.ts

@@ -1,7 +1,7 @@
 import type {
   FileStore, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, Tool, ToolRegistry, FrontendInfo,
-  Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner,
+  Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage,
 } from './types.js';
 import type { HookRegistry } from './hooks.js';
 
@@ -19,7 +19,7 @@ export interface CompletionRequest {
 
 export interface CompletionResponse {
   text:  string;
-  usage: { inputTokens: number; outputTokens: number };
+  usage: Usage;
 }
 
 export interface SingleTurnRequest {
@@ -116,8 +116,11 @@ export interface MatbotRuntime {
    * Hot-load a plugin by specifier into the running process. Returns the loaded plugin.
    * `prompt`, when supplied, resolves tool-name collisions interactively during the new
    * plugin's setup(); the runner injects the triggering session's prompt automatically.
+   * `refresh` (default false) forces a remote (github/http) plugin's `.plugins/` cache subtree
+   * to be evicted and re-downloaded — a reload of changed upstream source. Cache-first otherwise:
+   * a programmatic loader gets the cached copy and stays offline-tolerant.
    */
-  loadPlugin(specifier: string, prompt?: PromptFn): Promise<MatbotPlugin>;
+  loadPlugin(specifier: string, prompt?: PromptFn, refresh?: boolean): Promise<MatbotPlugin>;
 
   /**
    * Hot-unload a plugin by specifier, removing its tools, hooks, and system context contributions.

package/src/session.ts

@@ -0,0 +1,17 @@
+import type { Session } from './types.js';
+
+/**
+ * A session's `updatedAt` invariant: the timestamp of its last message, or its own `createdAt` when it
+ * has none. `updatedAt` tracks *conversational activity*, not structural or metadata edits — so a
+ * compaction, cut, split, fork, rename, or archive leaves it (and thus the session's place in a
+ * recency-sorted list) untouched, since none of them change which message is last. Kept as a
+ * materialised field, not a getter: `Session` round-trips as plain JSON through every storage backend
+ * and is sorted on `updatedAt` as a stored column, neither of which survives a live accessor.
+ *
+ * Apply it to the final session object at every write — `{ ...session, updatedAt: lastActivityAt(session) }`
+ * — rather than stamping a fresh `now()`.
+ */
+export function lastActivityAt(session: Session): string {
+  const last = session.messages[session.messages.length - 1];
+  return last ? last.createdAt : session.createdAt;
+}

package/src/store-query.ts

@@ -38,7 +38,7 @@ export interface StoreQuery {
   where?:  Filter;
   sort?:   SortSpec[];
   limit?:  number;
-  cursor?: string;
+  cursor?: string | undefined;
 }
 
 export interface QueryResult<T> {

package/src/types.ts

@@ -39,6 +39,29 @@ export interface ProviderConfig {
   fallback?:    string;
 }
 
+/**
+ * Token (and optional cost) counters for one provider call — pure accounting data, never conversation
+ * content. Recorded onto the message stream for cost reckoning but elided from provider submission. The
+ * producing provider is recorded alongside at each storage site (an assistant turn carries it on the
+ * message's `providerName`; a tool-invoked completion pairs it explicitly — see `tool-result`), since a
+ * tool may run a completion against any configured provider, each with its own rates.
+ */
+export interface Usage {
+  inputTokens:          number;
+  outputTokens:         number;
+  costUsd?:             number;
+  cacheReadTokens?:     number;
+  cacheCreationTokens?: number;
+}
+
+/** One provider call's usage, tagged with the provider billed — the unit a tool accrues (a tool may
+ *  run completions against any provider, each with its own rates) and the element persisted on a
+ *  `tool-result`'s `usage` addendum. See the ambient usage carrier (`recordUsage`/`currentUsageSink`). */
+export interface UsageRecord {
+  provider: string;
+  usage:    Usage;
+}
+
 export type CompletionEvent =
   | { type: 'text-delta';          delta: string }
   | { type: 'tool-call';           id: string; name: string; input: unknown }
@@ -49,7 +72,7 @@ export type CompletionEvent =
   | { type: 'reasoning-block';     reasoning: string }
   | { type: 'refusal';             text: string }
   | { type: 'unknown-block';       blockType: string; raw: unknown }
-  | { type: 'usage';               inputTokens: number; outputTokens: number; costUsd?: number; cacheReadTokens?: number; cacheCreationTokens?: number }
+  | ({ type: 'usage' } & Usage)
   | { type: 'done' };
 
 export interface ProviderAdapter {
@@ -77,7 +100,14 @@ export type MessageContent = (
   | { type: 'document';          data: string; mimeType: MimeType; name?: string }
   | { type: 'audio';             data: string; mimeType: MimeType }
   | { type: 'tool-call';         id: string; name: string; input: unknown }
-  | { type: 'tool-result';       id: string; result: unknown; isError?: boolean }
+  | { type: 'tool-result';       id: string; result: unknown; isError?: boolean;
+      /**
+       * Accounting addendum: completions the tool itself ran (e.g. `single_turn`, `dream_time`'s ranker/
+       * merger), captured ambiently via the usage carrier and recorded for cost reckoning. Elided from
+       * provider submission — adapters serialise only `id`/`result`/`isError`. One entry per provider
+       * call, each tagged with the provider billed; never summed at write time, as rates differ.
+       */
+      usage?: UsageRecord[] }
   | { type: 'refusal';           text: string }
   | { type: 'file-ref';          fileId: string; name: string; mimeType: MimeType }
   | { type: 'form';              fields: FormField[]; submitLabel?: string }
@@ -158,6 +188,9 @@ export interface Message {
   createdAt:     ISODate;
   traceId:       string;
   providerName?: string;
+  /** Token/cost accounting for the provider call that produced this message (assistant turns). The
+   *  billed provider is this message's `providerName`. Accounting only — elided from provider submission. */
+  usage?:        Usage;
   metadata?:     Record<string, unknown>;
 }
 
@@ -405,11 +438,11 @@ export interface KnowledgeIndex {
 
 // ── Tools ─────────────────────────────────────────────────────────────────────
 
-export type ToolEvent =
+export type ToolEvent<Result = unknown> =
   | { type: 'stdout';   chunk: string }
   | { type: 'stderr';   chunk: string }
   | { type: 'progress'; pct: number; message?: string }
-  | { type: 'result';   value: unknown }
+  | { type: 'result';   value: Result }
   | { type: 'file';     handle: FileHandle }
   // A durable, LLM-invisible annotation the tool emits as it runs (a link, a status, a trace of a
   // side-effect). Persisted as a `marker`-role message; elided from provider submission like any
@@ -418,6 +451,26 @@ export type ToolEvent =
   | { type: 'marker';   creator: string; data: unknown }
   | { type: 'error';    message: string; code?: number; stdout?: string; stderr?: string };
 
+/**
+ * Per-tool result-type registry: maps a tool's `name` to the type of the `value` it yields in its
+ * `result` event. Augment it exactly like {@link MarkerData} / `MatbotServices`, so a caller gets the
+ * concrete result type back from {@link invokeTool} + `toolResult` instead of `unknown`:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface ToolResults { find_fact: string[] | null }
+ *   }
+ *
+ * The tool name is the discriminator: `invokeTool(machine, 'find_fact', …)` is typed
+ * `AsyncIterable<ToolEvent<string[] | null>>`, so `toolResult(…)` resolves to `string[] | null`. A
+ * name with no registered entry resolves to `unknown` (the caller must narrow). This is a pure
+ * type-level construct — no runtime validation; it pins, at the call site, the contract a tool's
+ * executor already produces. Keep the entry in sync with what the executor actually yields.
+ */
+export interface ToolResults {}
+
+/** The `result` value a tool named `K` yields, or `unknown` when `K` isn't registered in {@link ToolResults}. */
+export type ToolResultOf<K extends string> = K extends keyof ToolResults ? ToolResults[K] : unknown;
+
 /**
  * Ask the user a question and resolve with their answer. The host supplies the
  * implementation — readline in the CLI, an SSE round-trip in the web frontend. This is
@@ -455,8 +508,10 @@ export interface ToolContext {
   files?:      FileStore;
   /** Prompt the user for input. The host provides a readline or form implementation. */
   prompt:      PromptFn;
-  /** Hot-load a plugin by specifier without restarting the process. Returns the loaded plugin. */
-  loadPlugin(specifier: string): Promise<MatbotPlugin>;
+  /** Hot-load a plugin by specifier without restarting the process. Returns the loaded plugin.
+   *  `refresh` (default false) forces a remote (github/http) plugin to be re-downloaded rather than
+   *  re-loaded from its `.plugins/` cache — pass true to pick up changed upstream source. */
+  loadPlugin(specifier: string, refresh?: boolean): Promise<MatbotPlugin>;
   /**
    * Hot-unload a plugin by specifier, removing its tools, hooks, and system context contributions.
    * Resolves `true` if a plugin was actually resident and unloaded, `false` if there was nothing
@@ -616,9 +671,10 @@ export type PipelineEvent =
   | { type: 'tool:start';     callId: string; name: string; input: unknown; traceId: string }
   | { type: 'tool:stdout';    callId: string; chunk: string;  traceId: string }
   | { type: 'tool:stderr';    callId: string; chunk: string;  traceId: string }
+  | { type: 'tool:progress';  callId: string; pct: number; message?: string; traceId: string }
   | { type: 'tool:end';       callId: string; result: unknown; isError: boolean; traceId: string }
   | { type: 'file';           handle: FileHandle;     traceId: string }
-  | { type: 'usage';          inputTokens: number; outputTokens: number; costUsd?: number; cacheReadTokens?: number; cacheCreationTokens?: number; traceId: string }
+  | ({ type: 'usage';         traceId: string } & Usage)
   | { type: 'done';           session: Session;       traceId: string }
   | { type: 'aborted';        reason: string; session: Session; traceId: string }
   | { type: 'cancelled';      sessionId: string;      traceId: string }

package/src/usage-context.ts

@@ -0,0 +1,82 @@
+import type { Usage, UsageRecord } from './types.js';
+
+/**
+ * Ambient carrier for token accounting — the channel by which a completion run *inside a tool* (via
+ * `MatbotRuntime.complete`/`singleTurn`) reports its usage back to the runner without that bookkeeping
+ * being threaded through every tool, ranker, or merger signature. It mirrors the {@link PrincipalCarrier}:
+ * a sink is established for an async extent, and code deep within (the host's `complete()`) appends to
+ * whatever sink is in force via {@link recordUsage}.
+ *
+ * Why ambient. A tool reaches an LLM only through the core completion services — it cannot call a
+ * provider directly. Recording at that one choke point therefore captures *every* tool's spend (a
+ * `single_turn`, an `ask_inner_voice`, each of `dream_time`'s per-fact ranker/merger calls) with zero
+ * per-tool code. The runner opens one sink per turn ({@link withUsageScope}) and slices it per tool
+ * call, attributing each completion to the call that triggered it.
+ *
+ * The host installs one platform implementation at boot:
+ *   - node (concurrent turns): an `AsyncLocalStorage`-backed carrier, so overlapping turns keep
+ *     separate sinks (see the node app's `createAlsUsageCarrier`).
+ *   - browser / single-turn realms: {@link createSerialUsageCarrier} — a set-and-restore global,
+ *     correct while turns do not truly overlap (the same realm the constant principal carrier assumes).
+ *
+ * Capture is best-effort accounting: with no carrier installed (e.g. tests), {@link recordUsage} and
+ * {@link currentUsageSink} are no-ops and usage simply isn't recorded — never an error.
+ */
+export interface UsageCarrier {
+  /** Establish a fresh `sink` for the dynamic extent of `fn`. Consume any async iterable *inside* `fn`. */
+  run<T>(sink: UsageRecord[], fn: () => T): T;
+  /** The sink in force for the current async flow, or `undefined` outside any scope. */
+  tryCurrent(): UsageRecord[] | undefined;
+}
+
+const CARRIER_KEY = Symbol.for('@matatbread/matbot-plugin-api#usageCarrier');
+type CarrierGlobal = { [CARRIER_KEY]?: UsageCarrier };
+
+/** Install the host's platform carrier. Called once at boot. */
+export function installUsageCarrier(impl: UsageCarrier): void {
+  (globalThis as CarrierGlobal)[CARRIER_KEY] = impl;
+}
+
+/** The usage sink in force, or `undefined` when no carrier is installed or no scope is established. */
+export function currentUsageSink(): UsageRecord[] | undefined {
+  return (globalThis as CarrierGlobal)[CARRIER_KEY]?.tryCurrent();
+}
+
+/** Append one provider call's usage to the sink in force. No-op outside any scope (best-effort accounting). */
+export function recordUsage(provider: string, usage: Usage): void {
+  currentUsageSink()?.push({ provider, usage });
+}
+
+/** Run `fn` with a fresh, empty usage sink established for its async extent. Passthrough when no carrier. */
+export function withUsageScope<T>(fn: () => T): T {
+  const carrier = (globalThis as CarrierGlobal)[CARRIER_KEY];
+  if (carrier === undefined) return fn();
+  return carrier.run([], fn);
+}
+
+/**
+ * A carrier for realms with no async-context isolation (the browser, tests): a single module-global
+ * sink, set on `run` and restored once `fn` settles. Correct as long as scopes do not truly overlap —
+ * the same single-turn assumption the constant principal carrier makes.
+ */
+export function createSerialUsageCarrier(): UsageCarrier {
+  let current: UsageRecord[] | undefined;
+  return {
+    run(sink, fn) {
+      const prev = current;
+      current = sink;
+      try {
+        const r = fn();
+        if (r instanceof Promise) {
+          return r.finally(() => { current = prev; }) as unknown as ReturnType<typeof fn>;
+        }
+        current = prev;
+        return r;
+      } catch (e) {
+        current = prev;
+        throw e;
+      }
+    },
+    tryCurrent: () => current,
+  };
+}