@matatbread/matbot-plugin-api 0.4.1 → 0.4.4

package/package.json

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

package/src/context-switch.ts

@@ -5,80 +5,218 @@ import { globalSlot } from './global-state.js';
 /**
  * A context switch is the machine analogue of an OS one: it pages in any pending machine state and
  * sets the owner. {@link runAs} is the bare "set the owner" instruction (the principal carrier);
- * {@link contextSwitch} is the scheduler operation layered on top — it also lands any machine
- * mutation that was deferred while the machine was busy.
+ * {@link machineBusy} is the other half — "hold the machine, I am mid-operation" — and
+ * {@link contextSwitch} is the two together, for an operation that is both.
  *
  * Why deferral exists: a service like the `StorageBackend` is the system of record, and swapping it
  * under a running operation would split a compare-and-swap (or a turn) across two backends. So a
- * swap is queued and applied only at the *quiescent edge* — the instant no context is active — which
- * is exactly a context-switch boundary. The principal carrier stays a pure identity primitive; this
- * module owns the machine-update half, so the two concerns share call sites without sharing code.
+ * swap is queued and applied only at the *quiescent edge* — the instant nothing holds the machine.
+ * The principal carrier stays a pure identity primitive; this module owns the machine half.
  *
- * The host registers what to flush ({@link onContextQuiesce}); the three entry points (a web
- * request, a telegram message, a turn) switch context through {@link contextSwitch} instead of
- * calling {@link runAs} directly. The boot principal (an `enter`, not a `run`) is the depth-0
- * baseline and is never counted.
+ * **What counts as busy is the operation, not the turn.** The two are not the same thing, and
+ * assuming they were is what made this edge wrong: a turn commits its session document, and *then*
+ * its pump reads that document back, appends followup markers, rewrites it for a retract, and starts
+ * the next queued turn — all of it store work outside the turn, and all of it quiescent under a
+ * per-turn hold. A mutation landing in that window splits exactly what the deferral exists to keep
+ * whole. So the pump holds the machine for its whole queue and switches principal per item, which is
+ * also where accounting already flushes: "the end of a turn" is not a moment anything can be totalled
+ * or swapped at, and the queue draining is.
+ *
+ * The host registers what to flush ({@link onContextQuiesce}). Entry points that receive work but do
+ * not perform it — a web request holding an SSE stream open, a telegram message — use {@link runAs}
+ * and are deliberately NOT busy: their scope spans a long-lived stream, and counting it would mean
+ * the machine never reaches an edge at all. The boot principal (an `enter`, not a `run`) is likewise
+ * never counted.
  */
 
 // State-shaped and reachable from a plugin (a storage plugin registering a deferred-swap flusher, or
-// switching context), so it lives in the global slot: a duplicated plugin-api copy shares one set of
-// quiescers and one depth count rather than splitting them. See ./global-state.ts.
+// holding the machine), so it lives in the global slot: a duplicated plugin-api copy shares one set
+// of quiescers and one hold count rather than splitting them. See ./global-state.ts.
+//
+// `depth` keeps its name across the change of meaning — it counts machine holds now, of which a
+// principal-bearing context switch is one — because the slot is shared by every loaded copy of this
+// module, including published older ones. Both spellings of "busy" increment the same field, so a
+// skewed install still agrees on when the machine is idle; a renamed field would have left an old
+// copy marking a turn busy on `depth` while a new copy read `busy` and called the machine quiet.
 interface ContextSwitchState {
-  quiescers: Set<() => void>;
+  quiescers: Set<Quiescer>;
   depth:     number;
   flushing:  boolean;
+  /** The flush currently settling, when a flusher went async. Held so a second caller joins the one
+   *  in flight rather than starting a second, and so {@link quiesced} has something to wait on. */
+  inflight?: Promise<void> | undefined;
 }
 const cs = globalSlot<ContextSwitchState>('context-switch', () => ({
-  quiescers: new Set<() => void>(),
+  quiescers: new Set<Quiescer>(),
   depth:     0,
   flushing:  false,
 }));
 
 /**
- * Register a machine-update flush, run at every quiescent edge (no context active). Flushers MUST be
- * idempotent: a no-op when nothing is pending, since the edge is reached after every operation.
- * Returns an unregister fn. A throwing flusher is isolated — one must not block the others or escape
- * into the operation that triggered the edge.
+ * A machine-update flush. Returning a promise makes the edge *wait*: the deferred work is no longer
+ * merely started at the edge but finished before the machine is handed to whoever asked to be
+ * quiesced first (see {@link quiesced}). That matters for work that reads and rewrites a document the
+ * next operation is about to read — a store edge deferred out of a turn lands in the window before
+ * the next turn takes its copy, or not at all.
  */
-export function onContextQuiesce(flush: () => void): () => void {
+export type Quiescer = () => void | Promise<void>;
+
+/**
+ * Register a machine-update flush, run at every quiescent edge (nothing holding the machine).
+ * Flushers MUST be idempotent: a no-op when nothing is pending, since the edge is reached after every
+ * operation. Returns an unregister fn.
+ *
+ * What the edge guarantees a flusher:
+ *
+ * - Flushers are **invoked in registration order**, in one synchronous sweep; one that goes async is
+ *   started in that order and then left to settle alongside the rest.
+ * - **The synchronous prefix lands within the call.** As long as flushers are synchronous nothing
+ *   yields at all, which is what lets the host stage a mutation and land it with a bare
+ *   `flushIfQuiescent()` — in effect before the call returns.
+ * - **No second sweep begins until the current one has completely settled**, and a mutation staged
+ *   meanwhile is turned away rather than applied.
+ * - A throwing flusher is isolated, and so is a rejecting one — neither may deny the others their
+ *   completion, nor escape into the operation whose release happened to reach the edge.
+ *
+ * **It does not give exclusivity, and could not.** A synchronous flusher has it for free — the runtime
+ * is single-threaded — and that is the argument for keeping a flusher synchronous whenever the work
+ * allows. The moment one awaits, the window is open: `depth` is 0 while a flush settles, so an HTTP
+ * endpoint can accept a request and run a tool call to completion inside a single `await`, and only an
+ * operation that asked to be {@link quiesced} first (the pump) is held back. Flushers may therefore
+ * overlap each other too, and sequencing them would buy nothing — it would remove one source of
+ * concurrent mutation while leaving every other in place, at the price of every flusher waiting on the
+ * slowest.
+ *
+ * So contention over a service is the *service's* to resolve, not the sweep's: a `Store` answers it
+ * with compare-and-swap, and a subsystem with a stronger requirement owns a stronger answer. The
+ * sweep's job is to make contention rare, not to pretend the machine stops.
+ *
+ * **Known gap, not caused here.** Compare-and-swap answers "did this document change?", not "did the
+ * medium change?" — a read from one `StorageBackend` and a write to another compares a version from
+ * the first against the second, and a session migrates with nothing in a position to notice. Staging
+ * a swap rather than applying it while a flush settles narrows that window, but it is a mitigation
+ * in the wrong place: an HTTP tool call has always been able to straddle a swap the same way, so the
+ * exposure predates asynchronous flushers and is merely easier to reach with them. The fix belongs
+ * where the consequence lands — a `cas` that checks the backend it is writing to is the one it read
+ * from, and fails when it is not.
+ *
+ * The keys that repoint *immediately* — `Vault`, `KnowledgeIndex`, `Notifier`, anything a plugin
+ * registers — carry no protection here or anywhere: they change under a running turn too, by the
+ * design decision that only the system of record is worth deferring. A flusher that depends on one
+ * should resolve it once rather than either side of an await, exactly as a turn should.
+ */
+export function onContextQuiesce(flush: Quiescer): () => void {
   cs.quiescers.add(flush);
   return () => { cs.quiescers.delete(flush); };
 }
 
 /**
- * Run the registered flushers iff no context is currently active — the quiescent edge. Called by
- * {@link contextSwitch} at both edges, and by the host right after it *queues* a deferred mutation:
- * queued while busy (depth > 0) this no-ops and the exit edge lands it; queued while idle (depth 0)
+ * Run the registered flushers iff nothing holds the machine — the quiescent edge. Called by
+ * {@link machineBusy} at both edges, and by the host right after it *queues* a deferred mutation:
+ * queued while busy (depth > 0) this no-ops and the release edge lands it; queued while idle (depth 0)
  * it applies immediately, so an idle-time swap doesn't wait for the next request to take effect.
+ *
+ * Returns the settling promise when some flusher went async, and `undefined` when the edge is already
+ * complete — the caller decides whether it can afford to wait ({@link quiesced} does; a synchronous
+ * caller cannot). Re-entering while one is settling joins it rather than starting a second: `flushing`
+ * stays raised for the whole asynchronous extent, not just the synchronous sweep.
  */
-export function flushIfQuiescent(): void {
-  if (cs.depth !== 0 || cs.flushing) return;
+export function flushIfQuiescent(): Promise<void> | undefined {
+  if (cs.depth !== 0 || cs.flushing) return cs.inflight;
   cs.flushing = true;
-  try {
-    for (const q of cs.quiescers) {
-      try { q(); }
-      catch (e) { console.error('[matbot] context-quiesce flush threw:', e instanceof Error ? e.message : e); }
-    }
-  } finally {
+
+  // Snapshot: a one-shot flusher unregisters itself as it fires, and a flusher may register another.
+  // Iterating a copy makes both safe and settles what a mid-sweep registration means — it was not
+  // registered when this edge began, so it runs at the next one.
+  const settling = [...cs.quiescers]
+    .map(q => {
+      // A synchronous throw is the flusher's own business, never that of the operation whose release
+      // happened to reach the edge. A rejection is handled below, by allSettled.
+      try { return q() ?? undefined; }
+      catch (e) { console.error('[matbot] context-quiesce flush threw:', e instanceof Error ? e.message : e); return undefined; }
+    })
+    .filter((p): p is Promise<void> => p !== undefined);
+
+  if (settling.length === 0) {
+    // Every flusher was synchronous, so the edge is complete on return — which is what lets the host
+    // stage a mutation and land it with a bare `flushIfQuiescent()`, in effect before the call returns.
     cs.flushing = false;
+    cs.inflight = undefined;
+    return undefined;
   }
+
+  // allSettled, not all: one flusher's rejection must not deny the others their completion, and the
+  // aggregate must never reject — the release below depends on it, and there is nobody to catch it.
+  const all = Promise.allSettled(settling).then(results => {
+    for (const r of results) {
+      if (r.status === 'rejected') console.error('[matbot] context-quiesce flush rejected:', r.reason instanceof Error ? r.reason.message : r.reason);
+    }
+    cs.flushing = false;
+    cs.inflight = undefined;
+  });
+  cs.inflight = all;
+  return all;
 }
 
 /**
- * Switch into the machine as `principal`: land any pending machine mutation (only safe while idle),
- * then run `fn` under the principal. Mirrors {@link runAs}'s sync/async return — when `fn` is async,
- * the context stays open until its promise settles, so the depth count tracks the real operation.
+ * Wait until the edge is not merely reached but *complete*: reach it, and let any deferred work it
+ * starts (or finds already settling) finish. An operation that must not overlap deferred work — a turn
+ * about to take its copy of a session that a previous turn's deferred edit is rewriting — awaits this
+ * before holding the machine.
+ *
+ * **One pass, deliberately not a loop.** An `async` flusher returns a promise whether or not it had
+ * anything to do — "nothing pending" is unobservable from out here, since an immediately-resolved
+ * promise and a real unit of work are the same object to us. A loop that waited for a pass to produce
+ * no promise would therefore never terminate against an idempotent async flusher, and neither would a
+ * re-run scheduled after each settle: each pass would manufacture the evidence for the next. So work
+ * staged *during* a flush lands at the following edge — the next `machineBusy` release, or the next
+ * caller through here — which is all the mount contract has ever promised: eventual and ordered,
+ * never timed.
  */
-export function contextSwitch<T>(principal: Principal, fn: () => T): T {
+export async function quiesced(): Promise<void> {
+  await flushIfQuiescent();
+}
+
+/**
+ * Hold the machine for the extent of `fn`: land any pending mutation first (only safe while idle),
+ * then keep the machine off-limits to further ones until `fn` is done. Mirrors {@link runAs}'s
+ * sync/async return — when `fn` is async the hold stays up until its promise settles, so the count
+ * tracks the real operation rather than the synchronous call.
+ *
+ * The hold is released on **every** exit — a synchronous throw, a rejected promise, a bare `return`
+ * from anywhere inside — because the release is bound to the call, not written at the exits. That is
+ * the whole reason this is a wrapper and not a `begin()`/`end()` pair: a caller with a dozen early
+ * returns (the pump has several per queue item) cannot leave the counter stuck, and a stuck counter
+ * is unrecoverable — every later flush would silently no-op forever, and the symptom would be a
+ * deferred mutation that simply never happens.
+ */
+export function machineBusy<T>(fn: () => T): T {
   flushIfQuiescent();
   cs.depth++;
-  const settle = (): void => { cs.depth--; flushIfQuiescent(); };
+  let settled = false;
+  const settle = (): void => {
+    if (settled) return;   // the sync-throw path settles before rethrowing; never settle twice
+    settled = true;
+    cs.depth--;
+    flushIfQuiescent();
+  };
   let result: T;
   try {
-    result = runAs(principal, fn);
+    result = fn();
   } catch (e) {
     settle();
     throw e;
   }
   return result instanceof Promise ? (result.finally(settle) as T) : (settle(), result);
 }
+
+/**
+ * Switch into the machine as `principal`: hold it for the extent of `fn` ({@link machineBusy}) and
+ * run `fn` under the principal ({@link runAs}). The composition, for an operation that both owns the
+ * machine and has an owner — a single-turn request standing on its own. An operation that decomposes
+ * into differently-owned units (the pump: one queue, a principal per item) holds the machine once
+ * around the whole of it and calls `runAs` per unit instead.
+ */
+export function contextSwitch<T>(principal: Principal, fn: () => T): T {
+  return machineBusy(() => runAs(principal, fn));
+}

package/src/hooks.ts

@@ -3,6 +3,7 @@ import type {
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
 } from './types.js';
 import { foldOntoUserTurn } from './session.js';
+import { withUsageSite } from './usage-context.js';
 
 const HOOK_ERROR_CREATOR = 'matbot-hooks';
 
@@ -43,9 +44,18 @@ export class HookRegistry implements HookRegistrar {
 
   // Run one handler, isolating a throw: log it, record it for a one-time marker, and return undefined
   // — which every run* method already treats as "no contribution from this hook".
+  //
+  // Also the accounting push site for the `hook` call site: a handler that runs a completion (a trigger
+  // classifier, a router) records against the channel and plugin that owns it. Established here rather
+  // than per-channel because it is the one place every handler invocation passes through — and because
+  // the site must be in force when the handler *starts*, so work it kicks off detached stays attributed
+  // to it however late it settles.
   private async invoke<R>(hook: Hook, run: () => R | Promise<R>): Promise<R | undefined> {
     try {
-      return await run();
+      return await withUsageSite(
+        { kind: 'hook', channel: hook.on, ...(hook.pluginName !== undefined ? { plugin: hook.pluginName } : {}) },
+        run,
+      );
     } catch (err) {
       const message = err instanceof Error ? err.message : String(err);
       const owner = hook.pluginName !== undefined ? ` from "${hook.pluginName}"` : '';

package/src/plugin.ts

@@ -4,7 +4,7 @@ import type {
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage, HookRegistrar,
   TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy,
 } from './types.js';
-import type { Notifier } from './notify.js';
+import type { Notifications, Notifier } from './notify.js';
 
 /**
  * The plugin API contract version: this package's `major.minor`, and nothing else. It sat at `'0.1'`
@@ -150,6 +150,9 @@ export interface MatbotServices {
    *  registered by a partitioning storage backend. Absent ⇒ frontends use the plain `fileStore.watch()`.
    *  See {@link WatchVisibility}. */
   readonly WatchVisibility?: WatchVisibility | undefined;
+  /** Optional file-partition addressing, registered by the same partitioning storage backend as
+   *  {@link WatchVisibility}. Absent ⇒ one undivided file area. See {@link FilePartition}. */
+  readonly FilePartition?: FilePartition | undefined;
   /** Optional steering policy: decides how a mid-turn submission under `mode: 'auto'` is disposed
    *  (queue vs interrupt) and supplies the nudge folded onto an interrupt's continuation. Absent ⇒ the
    *  runner uses its own defaults. A plain registered service, consumed by the runner as a member.
@@ -358,29 +361,114 @@ export interface StorageBackend {
   createStore<T extends { id: string; version: string }>(namespace: string): Store<T>;
   readonly fileStore: FileStore;
   close?(): Promise<void>;
+  /**
+   * The namespaces this backend currently holds documents for — the `createStore` arguments that
+   * would reach real data. `createStore` is addressed BY name, so without this a caller can only read
+   * a namespace it already knows about; enumerating is what makes a backend traversable (copying one
+   * backend into another, auditing what is stored, reporting on a `.data` directory).
+   *
+   * **Optional because absence is a type.** A backend addressing a medium with no listing operation
+   * cannot answer, and must not guess: a caller that needs a complete list degrades to being told the
+   * namespaces explicitly rather than silently working from a partial one. Do not implement this by
+   * returning "the namespaces `createStore` happened to be called with this session" — that is a lower
+   * bound masquerading as an answer, and a traversal built on it silently skips whatever no plugin
+   * touched. If the medium cannot be listed, leave it off, or throw with a reason.
+   *
+   * Excludes the file store: files are a separate axis with their own enumeration
+   * ({@link FileStore.list}), not a namespace among the document stores.
+   *
+   * A namespace holding no documents may be omitted — "empty" and "absent" are not usefully different
+   * to a caller that is about to read it. Implementations return the list sorted, so a diff of two
+   * backends is stable.
+   */
+  namespaces?(): Promise<string[]>;
+}
+
+/**
+ * What a {@link WatchVisibility} predicate decides on. A named object rather than positional parameters
+ * because `kind`/`namespace`/`id` are three adjacent strings around two `Principal`s — an ordering an
+ * implementation could get wrong silently.
+ *
+ * Populated by whoever consults the predicate; a frontend firehose fills it from the notification it is
+ * about to fan out.
+ */
+export interface VisibilityQuery {
+  /** The principal asking — the owner of the connection this fan-out would reach. */
+  viewer:     Principal;
+  /** The notification's `kind`. Present so an implementation can apply a policy PER KIND: some kinds are
+   *  global, some are checked against the recipient (`viewer`), some against the sender (`origin`). Typed
+   *  as the registry key for narrowing, but **open at runtime** like every `kind` — a plugin outside this
+   *  build, or a bridged remote, can supply one, so `default` your switch and never assume exhaustiveness. */
+  kind:       keyof Notifications;
+  /** Routing namespace of the changed item — the axis a profile isolates. Absent when the kind addresses
+   *  no item (a `RegistryChange`, or a plugin kind carrying a measurement or an external event). */
+  namespace?: string;
+  /** Store id of the changed item; drives the shared-in check. Absent with `namespace`. */
+  id?:        string;
+  /** Whose data the fact is about — `NotificationBase.principal`, the ownership axis, NOT attribution.
+   *  Absent ⇒ a global fact. */
+  origin?:    Principal;
 }
 
 /**
  * The per-connection visibility layer, registered by a storage backend that partitions per principal (the
  * profiles backend). Consumed by a frontend firehose to decide, per SSE connection, whether a given
  * notification is visible to that connection's principal. Absent ⇒ no partitioning, and every connection
- * sees everything. Generic across kinds: it answers on (`namespace`, `id`, `origin`), so files, skills and
- * stores all route through the one predicate.
+ * sees everything.
+ *
+ * **The predicate is consulted for EVERY kind, and decides for itself which it filters.** It used to be
+ * reached only for an `ItemChange` carrying a principal, because the caller gated on that — which left
+ * every plugin-defined kind fanned out unfiltered with no hook capable of stopping it, and made `kind` a
+ * constant not worth passing. Moving that judgement here is the point: routing a partitioned namespace and
+ * addressing a notification to a recipient are two different policies, and only the implementation knows
+ * which of its kinds want which. An implementation that has nothing to say about a kind returns `true`.
  */
 export interface WatchVisibility {
   /**
    * The per-connection visibility predicate for ANY partitioned event stream (files, skills, …): would a
-   * connection owned by `viewer` see the change to (`namespace`, `id`) produced by `origin`? True iff the
-   * viewer routes that namespace to the same partition as `origin` — `route(viewer, namespace) ===
-   * route(origin, namespace)` — OR the item is shared INTO the viewer's partition (the owner edits a
-   * shared-in item: origin=owner ≠ the viewer's route, yet the viewer holds a live link to it). This yields
-   * the intended behavior uniformly: global/base events for namespaces the viewer has NOT isolated,
-   * own-partition events for those it has, plus live updates to items shared in from another partition.
-   * `origin` may be a partition principal (files, tagged by the merge) or the acting principal (skills,
-   * stamped at write) — routing both sides makes either correct. `undefined` origin ⇒ base. `id` is the
-   * store id of the changed item; it drives the shared-in check.
+   * connection owned by `q.viewer` see this change? For a partitioning backend, true iff the viewer routes
+   * `q.namespace` to the same partition as `q.origin` — `route(viewer, ns) === route(origin, ns)` — OR the
+   * item is shared INTO the viewer's partition (the owner edits a shared-in item: origin=owner ≠ the
+   * viewer's route, yet the viewer holds a live link to it). That yields the intended behavior uniformly:
+   * global/base events for namespaces the viewer has NOT isolated, own-partition events for those it has,
+   * plus live updates to items shared in from another partition. `q.origin` may be a partition principal
+   * (files, tagged by the merge) or the acting principal (skills, stamped at write) — routing both sides
+   * makes either correct.
+   *
+   * Fail OPEN on anything you do not recognise: a kind you have no policy for, or a query with no
+   * `namespace`/`origin` to route on. A predicate that guesses `false` silently drops another party's
+   * events; one that returns `true` leaves them exactly as unfiltered as they were before it registered.
    */
-  visible(viewer: Principal, namespace: string, id: string, origin: Principal | undefined): boolean;
+  visible(q: VisibilityQuery): boolean;
+}
+
+/**
+ * Addressing for the file area, registered by a storage backend that partitions it per principal (the
+ * profiles backend). It exists so a caller that must name a file area OUT OF BAND — in a URL a plain
+ * browser GET will replay, with no ambient principal and no header to carry one — can do so without
+ * reimplementing the backend's routing.
+ *
+ * **The token is a partition, never a principal.** The two are not interchangeable: one principal may
+ * hold several profiles, and a profile may alias a namespace onto a third profile's partition, so the
+ * partition serving a principal's files is not derivable from the principal id. Minting the token from
+ * the identity in force — the bug this replaces — attached an addressable partition to files that were
+ * in the shared base area, and would have pointed at an empty partition the moment one was created
+ * under that name.
+ *
+ * `current` and `enter` are one round trip and must stay each other's inverse: whatever `current`
+ * returns, `enter` puts a reader back into the area those bytes were written to. Both live here rather
+ * than on the consumer because only the backend knows how a token resolves — a frontend that
+ * synthesised a principal from the token would be guessing at the routing again, one layer up.
+ */
+export interface FilePartition {
+  /** The partition the CURRENT principal's file area resolves to, as an opaque token — or `undefined`
+   *  for the shared base area, which needs no addressing (a bare path already reaches it). Never
+   *  interpret the token: it is the backend's, and only `enter` gives it meaning. */
+  current(): string | undefined;
+  /** Run `fn` reading the file area named by `token` — the inverse of `current`. An unknown token
+   *  resolves to whatever that backend serves for one; it is an address, not a capability, so it grants
+   *  no access the caller's own gating (a file's `allowed` flag) does not already permit. */
+  enter<T>(token: string, fn: () => Promise<T>): Promise<T>;
 }
 
 // ── Plugin interface ──────────────────────────────────────────────────────────

package/src/store-query.ts

@@ -37,6 +37,12 @@ export interface SortSpec {
 export interface StoreQuery {
   where?:  Filter;
   sort?:   SortSpec[];
+  /**
+   * Page size. `0` is the count form — the filter runs and `total` answers, but no document is
+   * materialised and no cursor is issued. It is a page size of zero rather than a `count` flag
+   * because that is already what the word means, in the grammar and in a pushdown backend's native
+   * query alike: fetch no rows, report how many there were.
+   */
   limit?:  number;
   cursor?: string | undefined;
   /**

package/src/types/builtin-tools.ts

@@ -0,0 +1,175 @@
+import type { PluginSource, Runtime } from '../plugin.js';
+import type { ModelParameters } from './provider.js';
+import type { ToolContract } from './tools.js';
+
+/*
+ * Call contracts for the two builtin admin tools that have BOTH a node and a browser implementation —
+ * `plugin` (@matatbread/matbot-tool-plugin, @matatbread/matbot-browser) and `provider` (likewise).
+ *
+ * They live here, rather than beside either implementation, for two reasons.
+ *
+ * ONE DECLARATION, NOT TWO IDENTICAL ONES. A `ToolContracts` key is registered by declaration merging,
+ * which requires every declaration of it to have the same type. Two implementations of one tool name
+ * therefore cannot each describe themselves: the moment their shapes differ it is a TS2717, and since
+ * the dts scan reads the checker rather than the Program's diagnostics, that error was invisible — one
+ * declaration won on file order and its shape was emitted as the contract for whichever implementation
+ * was actually loaded. Both tools now name the alias below, so the two declarations are the same
+ * symbol and cannot drift; `buildMatbotToolsDts` reports it loudly if any pair ever does again.
+ *
+ * NAMED SHAPES ARE AUGMENTABLE. These were inline object literals, which closed the one extension point
+ * the rest of the API leans on: a host that overrides a builtin tool and returns a superset had no way
+ * to say so (declaring its own arm is TS2717; declaring nothing inherits a shape it does not return).
+ * Naming them applies the open-registry technique in DEVELOPING.md one level down — a host augments the
+ * shape and never touches `ToolContracts`:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface LoadedPluginSummary { managedBy?: 'personal' | 'shipped' }
+ *   }
+ *
+ * Where the two runtimes genuinely differ, the shared shape carries the superset and the divergent
+ * member is optional — absence is the honest encoding of "this runtime has nothing to report". Each
+ * implementation's `inputSchema` is unchanged and still the enforcement point, per the multi-action
+ * tool rule: loose schema, executor enforces.
+ */
+
+/** A tool as reported by `plugin`'s `list`/`builtinTools` — the name and blurb, not the schema. */
+export interface ToolSummary {
+  name:        string;
+  description: string;
+}
+
+/**
+ * A plugin the loader could not bring up — an incompatible runtime, an import that rejected, a module
+ * that is not plugin-shaped, or a `setup()` throw. Recorded rather than discarded so the failure is
+ * *graceful but not silent*: `plugin list` and the web plugins panel show which configured plugins
+ * failed and why, instead of the failure vanishing into a boot-time console line. `error` is
+ * pre-stringified (sidesteps the `unknown` catch-var); `name` is present only when it was known before
+ * the failure.
+ */
+export interface FailedPlugin {
+  specifier: string;
+  name?:     string;
+  error:     string;
+}
+
+/** One entry in `plugin list`'s `loaded`. */
+export interface LoadedPluginSummary {
+  name:       string;
+  apiVersion: string;
+  /** package.json `version`, read by the resolver at load. Absent ⇒ unreadable (no package.json, or a
+   *  remote whose version isn't baked). */
+  version?:   string;
+  /** The stable URL the loader imported, minus any reload cache-bust stamp. Absent on a host that
+   *  constructed the plugin by hand, and on runtimes with no meaningful URL to report. */
+  resolvedUrl?: string;
+  /** Every channel the plugin contributes through (`tools`, `hooks`, `storage`, registered service
+   *  keys, …) — reflected from the registries, not declared. */
+  types:      string[];
+  tools:      ToolSummary[];
+  specifier:  string;
+  description?: string;
+  matbotRuntime?: readonly Runtime[];
+}
+
+export interface PluginListResult {
+  loaded:        LoadedPluginSummary[];
+  configured:    string[];
+  failed?:       FailedPlugin[] | undefined;
+  /** Tools registered by the host rather than by any plugin. */
+  builtinTools?: ToolSummary[] | undefined;
+}
+
+/** One installable plugin found by `plugin discover_local`. */
+export interface DiscoveredPlugin {
+  specifier:    string;
+  name:         string;
+  description:  string;
+  version?:     string;
+  /** `type` categorises the origin; `uri` is the concrete location as a scheme-qualified URI — `file://…`
+   *  on disk, the `https://…` it was fetched from for a cached remote. Optional because it is the one
+   *  member with no browser analogue: a baked-but-idle plugin was inlined into the artifact and has no
+   *  location to name. Absent ⇒ nothing to resolve it back to, not "unknown origin". */
+  source?:      { type: PluginSource; uri: string };
+  matbotRuntime?: readonly Runtime[];
+  /** Which config section already references this specifier, or `null` if none does. */
+  configuredVia: 'plugins' | 'providers' | null;
+}
+
+/** Result of the mutating `plugin` actions. `installationMessage` is the loaded plugin's own greeting. */
+export interface PluginActionResult {
+  message:              string;
+  installationMessage?: string;
+}
+
+/**
+ * The `plugin` tool's contract. Both implementations declare `plugin: PluginToolContract`.
+ *
+ * `reload`'s `refresh` is node-only in effect (it re-downloads a remote plugin's upstream source);
+ * the browser resolves every specifier through its import map and ignores the flag.
+ */
+export type PluginToolContract =
+  | ToolContract<PluginListResult,    { action: 'list' }>
+  | ToolContract<DiscoveredPlugin[],  { action: 'discover_local' }>
+  | ToolContract<PluginActionResult,  { action: 'add';       specifier: string }>
+  | ToolContract<PluginActionResult,  { action: 'remove';    specifier: string }>
+  | ToolContract<PluginActionResult,  { action: 'reload';    specifier: string; refresh?: boolean }>
+  | ToolContract<PluginActionResult,  { action: 'store-key'; key: string }>;
+
+/** One configured provider profile as reported by `provider list`. */
+export interface ProviderSummary {
+  name:           string;
+  /** The adapter's module specifier — the `module:` key in matbot.yaml. */
+  module:         string;
+  model:          string;
+  /** Whether a credential is on file. Never the credential itself. */
+  hasCredentials: boolean;
+  endpoint?:      string;
+  parameters?:    ModelParameters;
+  maxRounds?:     number;
+}
+
+/** An adapter a `provider add` could name, offered by runtimes that can enumerate them. */
+export interface AvailableProvider {
+  label:          string;
+  module:         string;
+  endpointHint?:  string;
+  modelHint?:     string;
+  /** Needs no endpoint/model/API key (e.g. a self-contained local adapter): the browser wizard hides
+   *  those fields and submits just a name, using `modelHint` as the model. */
+  selfContained?: boolean;
+}
+
+export interface ProviderListResult {
+  providers: ProviderSummary[];
+  /** The adapters this runtime can offer. Present in the browser, where the set was baked into the
+   *  artifact and is therefore knowable; absent on node, which discovers adapters through
+   *  `plugin discover_local` instead of enumerating them here. */
+  adapters?: AvailableProvider[];
+}
+
+export interface ProviderActionResult {
+  message: string;
+}
+
+/**
+ * The `provider` tool's contract. Both implementations declare `provider: ProviderToolContract`.
+ *
+ * `add` is the superset of the two: `model` is optional because a self-contained browser adapter
+ * supplies its own, while node's executor requires one; `credentialKey`/`credentialEnvVar` name where
+ * node's vault should hold the secret, and the browser (which prompts and stores under its own key)
+ * ignores them.
+ */
+export type ProviderToolContract =
+  | ToolContract<ProviderListResult,   { action: 'list' }>
+  | ToolContract<ProviderActionResult, {
+      action:            'add';
+      name:              string;
+      module:            string;
+      model?:            string;
+      endpoint?:         string;
+      credentialKey?:    string;
+      credentialEnvVar?: string;
+      parameters?:       ModelParameters;
+      maxRounds?:        number;
+    }>
+  | ToolContract<ProviderActionResult, { action: 'remove'; name: string }>;

package/src/types/events.ts

@@ -23,7 +23,10 @@ export type TurnEvent =
   | { 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 }
+  // `durationMs` is the runner's own bracket around the executor — the same number persisted as the
+  // call's `span` entry, carried live so a frontend can draw it without waiting for the idle flush.
+  // Absent for a call that never ran (a rejected or severed one), which is not the same as 0ms.
+  | { type: 'tool:end';       callId: string; result: unknown; isError: boolean; durationMs?: number; traceId: string }
 
   // ── live delivery of state that is ALREADY persisted; never the source of truth ──
   | { type: 'file';           handle: FileHandle;     traceId: string }

package/src/types/messages.ts

@@ -1,6 +1,6 @@
 import type { HookPoint } from './hooks.js';
 import type { ISODate, MimeType } from './primitives.js';
-import type { ProviderMeta, Usage, UsageRecord } from './provider.js';
+import type { ProviderMeta, TurnEntry, UsageRecord } from './provider.js';
 
 // ── Messages & Session ────────────────────────────────────────────────────────
 
@@ -29,14 +29,11 @@ export type MessageContent = (
       /** Provider-specific round-trip metadata, persisted and re-sent verbatim on replay — see
        *  `ProviderMeta` and the `tool-call` `CompletionEvent`. */
       meta?: ProviderMeta }
-  | { 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[] }
+  // A tool's own completions (`single_turn`, `dream_time`'s ranker/merger) are no longer recorded here:
+  // they are entries on the turn head, tagged `site: { kind: 'tool', callId }`. A tool message is popped
+  // wholesale by a retract-and-rerun, which took its accounting out of reach of any reduction over
+  // `session.messages` — see `Message.usage`.
+  | { type: 'tool-result';       id: string; result: unknown; isError?: boolean }
 
   // ── frontend-facing: rendered to a person, never sent to the model ──
   | { type: 'form';              fields: FormField[]; submitLabel?: string }
@@ -128,9 +125,20 @@ 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;
+  /**
+   * The turn's activity log, anchored here — every provider call it caused, whatever ran it (a round, a
+   * tool, a hook), plus every bracket matbot held open that was not a call of its own (a tool span).
+   * Each entry is self-describing via its `site` and causal `traceId`. Bookkeeping only: elided from
+   * provider submission, and a `flatMap` away from any total or waterfall a consumer wants.
+   *
+   * Anchored on the turn's **head** (its user message) rather than on the message whose call produced
+   * it, because that is the one message a retract-and-rerun keeps: the pop stashes assistant and tool
+   * messages inside a retraction marker, where no reduction over `session.messages` will ever find them
+   * again, so a retried turn would silently under-report by the attempt it discarded. Locality is not
+   * lost — `site` already names the round or tool call, and physical adjacency carried nothing the
+   * coordinate does not. See docs/ACCOUNTING-RATIONALE.md.
+   */
+  activity?:     TurnEntry[];
   metadata?:     Record<string, unknown>;
 }
 

package/src/types/provider.ts

@@ -1,5 +1,7 @@
 import type { HealthStatus } from './health.js';
+import type { HookPoint } from './hooks.js';
 import type { Message } from './messages.js';
+import type { ISODate } from './primitives.js';
 import type { Tool } from './tools.js';
 
 // ── Provider ──────────────────────────────────────────────────────────────────
@@ -43,19 +45,119 @@ export interface ProviderConfig {
 export interface Usage {
   inputTokens:          number;
   outputTokens:         number;
-  costUsd?:             number;
   cacheReadTokens?:     number;
   cacheCreationTokens?: number;
+  /**
+   * What the endpoint actually reported, under its own field names, verbatim — the adapter's `usage`
+   * object passed through rather than interpreted. Present only for fields the endpoint sent: an
+   * explicit `0` and an absent key are different facts, and collapsing them is not the adapter's call
+   * to make (a host that strips a capability and a call with genuinely no cache activity look identical
+   * once you do).
+   *
+   * The normalised counters above are still the comparable ones — every protocol has input and output
+   * tokens unambiguously, and something must be common or a turn spanning three providers cannot be
+   * totalled at all. This is what makes that normalisation non-destructive: `inputTokens` may be a real
+   * interpretation (openai-compat reports it net of cache hits, so it means what anthropic's
+   * `input_tokens` means), and keeping the components alongside means a consumer can check it, reverse
+   * it, or reconcile against a vendor's own dashboard.
+   *
+   * Not all values are counters — `service_tier` is a string that prices the call, `latency_checkpoint`
+   * a nested object — so this is deliberately not a `Record<string, number>`. Aggregation sums numeric
+   * values key-wise and leaves the rest alone; and only ever within one provider, since the same key
+   * means different things under different protocols (`prompt_tokens` includes cache hits,
+   * `input_tokens` does not). See docs/ACCOUNTING-RATIONALE.md.
+   */
+  reported?:            Record<string, unknown>;
 }
 
+/**
+ * Where in matbot's own control flow a completion happened — the one accounting fact no adapter and no
+ * plugin can recover after the fact, and therefore the one matbot must record. Everything derived from
+ * it (what a tool costs, what a user costs, what a "task" costs) is a *grouping* of these coordinates
+ * plus a rate table: policy, and a plugin's to own. See docs/ACCOUNTING-RATIONALE.md.
+ *
+ * Closed by construction: inside a turn there are exactly three places a completion can originate.
+ * Outside a turn there is no scope at all, and accounting is the documented no-op.
+ */
+export type UsageSite =
+  /** The runner's own provider call for one agentic round (1-based, as counted against `maxRounds`). */
+  | { kind: 'round'; round: number }
+  /** A completion run by a tool executor — `single_turn`, a ranker, a merger. */
+  | { kind: 'tool';  callId: string; tool: string }
+  /** A completion run by a hook handler — a trigger classifier, a router, an auto-compaction. */
+  | { kind: 'hook';  channel: HookPoint; plugin?: string };
+
 /** 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;
+  /**
+   * The call site in force when this was recorded, stamped by the producer rather than inferred by the
+   * consumer. Absent only when a completion ran with no site established (a plugin reaching `complete`
+   * outside any turn).
+   *
+   * Attribution is *declared*, not derived from timing, and that is the whole point: the triggers
+   * classifier is kicked off detached inside a `screen` hook and resolves at an arbitrary later moment,
+   * so any scheme that infers ownership from when a record lands (as slicing the sink by index did)
+   * credits it to whichever tool happened to be running. Capturing the site where the work *starts*
+   * makes that race unrepresentable.
+   */
+  site?:    UsageSite;
+  /** When the provider call started, and how long matbot's own scope around it was open. The *bracket*,
+   *  not the endpoint's view: server-side latency, when an endpoint reports it, arrives in
+   *  `usage.reported` like any other provider-named field. Neither substitutes for the other. */
+  startedAt?:  ISODate;
+  durationMs?: number;
+  /**
+   * The turn that *caused* this call, which is not the same question as where the record ends up.
+   * Two ordinary behaviours separate the two: a completion can be recorded after its turn commits (a
+   * detached trigger classifier, a `followup` hook), and a retract-and-rerun moves messages around
+   * underneath it. Carrying the cause on the entry makes an entry self-describing, so grouping by turn
+   * is a *query* rather than something inferred from adjacency — and so are grouping by tool, by user
+   * and by session. See docs/ACCOUNTING-RATIONALE.md.
+   */
+  traceId?: string;
+  /**
+   * The originating human turn, carried down a resubmission chain (a human submit is its own root). Not
+   * redundant with `traceId`: a retract-and-rerun re-runs an *existing* user turn under a fresh traceId
+   * and introduces no user message of its own, so its entries have no head of their own to sit on. The
+   * root is what gives them one — and it is the honest answer anyway, since the retry's cost belongs to
+   * the turn being retried.
+   */
+  rootTraceId?: string;
 }
 
+/**
+ * A bracket matbot held open that was not itself a provider call — today, a tool call. Only matbot can
+ * measure one: it is the interval between handing control to an executor and getting it back, which no
+ * adapter and no plugin can see from where it sits.
+ *
+ * Separate from `UsageRecord` because most tool calls spend no tokens at all — `bash`, `http`,
+ * `workspace` — so hanging duration off an accounting record would record it for exactly the tools that
+ * happen to call an LLM and lose it for the rest, which is backwards. A tool call that *does* run
+ * completions produces both: this span, and one `UsageRecord` per call it made, sharing its `site`.
+ */
+export interface SpanRecord {
+  site:         UsageSite;
+  traceId?:     string;
+  /** See `UsageRecord.rootTraceId` — a span needs the same anchor for the same reason. */
+  rootTraceId?: string;
+  startedAt:    ISODate;
+  durationMs:   number;
+}
+
+/**
+ * One thing that happened during a turn, at a place only matbot can name — the element of the turn's
+ * activity log. A discriminated union rather than one loose shape with everything optional: a span has
+ * no provider and no tokens, and pretending otherwise would mean writing zeros that a consumer cannot
+ * tell from measured ones.
+ */
+export type TurnEntry =
+  | ({ kind: 'call' } & UsageRecord)
+  | ({ kind: 'span' } & SpanRecord);
+
 /**
  * Opaque, provider-specific round-trip metadata attached to a tool-call — captured from a completion,
  * persisted, and re-sent verbatim when the call is replayed in history (e.g. a Gemini 3 "thought

package/src/types.ts

@@ -17,6 +17,7 @@ export * from './types/storage.js';
 export * from './types/knowledge.js';
 export * from './types/typescript.js';
 export * from './types/tools.js';
+export * from './types/builtin-tools.js';
 export * from './types/files.js';
 export * from './types/frontend.js';
 export * from './types/vault.js';

package/src/usage-context.ts

@@ -1,17 +1,37 @@
-import type { Usage, UsageRecord } from './types.js';
+import type { ISODate, TurnEntry, Usage, UsageSite } from './types.js';
+
+/**
+ * The accounting bag for one turn (or one sub-turn): the entries recorded within it, the call site in
+ * force, and the parent it rolls up into. One object, carried ambiently, accumulating a *log* rather
+ * than a fold — per-provider totals are a derived view (`usageByProvider`), and folding at write time
+ * would bake in one grouping and destroy the others. See docs/ACCOUNTING-RATIONALE.md.
+ */
+export interface UsageScope {
+  entries:  TurnEntry[];
+  site?:    UsageSite;
+  /** The turn this scope accounts for, and the human turn that ultimately caused it; both stamped
+   *  onto every entry recorded within it. */
+  traceId?:     string;
+  rootTraceId?: string;
+  parent?:  UsageScope;
+}
 
 /**
  * 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}.
+ * a scope is established for an async extent, and code deep within (the host's `complete()`) appends to
+ * whatever scope 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.
+ * per-tool code. The runner opens one scope per turn ({@link withUsageScope}) and labels the work
+ * within it ({@link withUsageSite}), so each record carries the call site that produced it.
+ *
+ * The same ambience is what makes attribution correct rather than approximate: a carrier captures at
+ * continuation creation, so a completion kicked off inside a `screen` hook and awaited long afterwards
+ * still reports the site it *started* from, not whatever was running when it happened to resolve.
  *
  * The host installs one platform implementation at boot:
  *   - node (concurrent turns): an `AsyncLocalStorage`-backed carrier, so overlapping turns keep
@@ -23,10 +43,10 @@ import type { Usage, UsageRecord } from './types.js';
  * {@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;
+  /** Establish `scope` for the dynamic extent of `fn`. Consume any async iterable *inside* `fn`. */
+  run<T>(scope: UsageScope, fn: () => T): T;
+  /** The scope in force for the current async flow, or `undefined` outside any scope. */
+  tryCurrent(): UsageScope | undefined;
 }
 
 const CARRIER_KEY = Symbol.for('@matatbread/matbot-plugin-api#usageCarrier');
@@ -37,21 +57,95 @@ 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 {
+/** The usage scope in force, or `undefined` when no carrier is installed or none is established. */
+export function currentUsageScope(): UsageScope | 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 });
+/** The entries of the scope in force. `undefined` outside any scope. */
+export function currentUsageSink(): TurnEntry[] | undefined {
+  return currentUsageScope()?.entries;
+}
+
+/** The call site in force, or `undefined` when none has been established. */
+export function currentUsageSite(): UsageSite | undefined {
+  return currentUsageScope()?.site;
+}
+
+/**
+ * Append one provider call's usage to the scope in force, stamped with the call site in force. No-op
+ * outside any scope (best-effort accounting).
+ */
+export function recordUsage(provider: string, usage: Usage, span?: { startedAt: ISODate; durationMs: number }): void {
+  const scope = currentUsageScope();
+  if (scope === undefined) return;
+  scope.entries.push({
+    kind: 'call', provider, usage,
+    ...(scope.site        !== undefined ? { site:        scope.site        } : {}),
+    ...(scope.traceId     !== undefined ? { traceId:     scope.traceId     } : {}),
+    ...(scope.rootTraceId !== undefined ? { rootTraceId: scope.rootTraceId } : {}),
+    ...(span              !== undefined ? span : {}),
+  });
+}
+
+/**
+ * Record a bracket matbot held open that was not a provider call — a tool call. Takes the site
+ * explicitly rather than reading the ambient one, because the caller records this *after* the scope it
+ * measured has closed.
+ */
+export function recordSpan(site: UsageSite, startedAt: ISODate, durationMs: number): void {
+  const scope = currentUsageScope();
+  if (scope === undefined) return;
+  scope.entries.push({
+    kind: 'span', site, startedAt, durationMs,
+    ...(scope.traceId     !== undefined ? { traceId:     scope.traceId     } : {}),
+    ...(scope.rootTraceId !== undefined ? { rootTraceId: scope.rootTraceId } : {}),
+  });
+}
+
+/**
+ * Run `fn` with a fresh usage scope established for its async extent, handing the scope to `fn` so the
+ * caller can read what accrued. Passthrough (no scope) when no carrier is installed.
+ *
+ * Scopes **nest**: opened inside another, the child accumulates its own entries and rolls them up into
+ * the parent when `fn` settles — so a sub-turn can be asked what it cost without its spend vanishing
+ * from the turn containing it. Roll-up happens on rejection too: the tokens were spent either way.
+ */
+export function withUsageScope<T>(
+  fn:  (scope: UsageScope) => T,
+  ids?: { traceId?: string; rootTraceId?: string },
+): T {
+  const carrier = (globalThis as CarrierGlobal)[CARRIER_KEY];
+  if (carrier === undefined) return fn({ entries: [], ...ids });
+  const parent = carrier.tryCurrent();
+  const trace  = ids?.traceId     ?? parent?.traceId;
+  const root   = ids?.rootTraceId ?? parent?.rootTraceId;
+  const scope: UsageScope = {
+    entries: [],
+    ...(trace  !== undefined ? { traceId:     trace } : {}),
+    ...(root   !== undefined ? { rootTraceId: root  } : {}),
+    ...(parent !== undefined ? { parent } : {}),
+  };
+  const rollUp = (): void => { if (parent !== undefined) parent.entries.push(...scope.entries); };
+  return carrier.run(scope, () => {
+    const r = fn(scope);
+    if (r instanceof Promise) return r.finally(rollUp) as unknown as T;
+    rollUp();
+    return r;
+  });
 }
 
-/** Run `fn` with a fresh, empty usage sink established for its async extent. Passthrough when no carrier. */
-export function withUsageScope<T>(fn: () => T): T {
+/**
+ * Run `fn` with `site` established as the call site, sharing the enclosing scope's entries — a *label*,
+ * not a new bag. Pushed by the runner around its own provider call and around each tool executor, and
+ * by the hook registry around each handler: the three places a completion can originate. Passthrough
+ * when no carrier or no enclosing scope, so a site never conjures a bag that would be dropped.
+ */
+export function withUsageSite<T>(site: UsageSite, fn: () => T): T {
   const carrier = (globalThis as CarrierGlobal)[CARRIER_KEY];
-  if (carrier === undefined) return fn();
-  return carrier.run([], fn);
+  const parent  = carrier?.tryCurrent();
+  if (carrier === undefined || parent === undefined) return fn();
+  return carrier.run({ ...parent, site }, fn);
 }
 
 /**
@@ -60,11 +154,11 @@ export function withUsageScope<T>(fn: () => T): T {
  * the same single-turn assumption the constant principal carrier makes.
  */
 export function createSerialUsageCarrier(): UsageCarrier {
-  let current: UsageRecord[] | undefined;
+  let current: UsageScope | undefined;
   return {
-    run(sink, fn) {
+    run(scope, fn) {
       const prev = current;
-      current = sink;
+      current = scope;
       try {
         const r = fn();
         if (r instanceof Promise) {