@matatbread/matbot-plugin-api 0.2.2 → 0.2.4

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.2.2",
+  "version": "0.2.4",
   "engines": {
     "node": ">=24.0.0"
   },

package/src/index.ts

@@ -4,6 +4,8 @@ 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';

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 {

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>;
 }
 
@@ -618,7 +651,7 @@ export type PipelineEvent =
   | { type: 'tool:stderr';    callId: string; chunk: 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,
+  };
+}