@matatbread/matbot-plugin-api 0.4.1 → 0.4.3

package/package.json

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

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.
@@ -360,27 +363,91 @@ export interface StorageBackend {
   close?(): Promise<void>;
 }
 
+/**
+ * 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) {