@matatbread/matbot-plugin-api 0.3.7 → 0.4.0

package/src/types/hooks.ts

@@ -0,0 +1,217 @@
+import type { Message, MessageContent, Session } from './messages.js';
+import type { PromptFn, Tool } from './tools.js';
+
+// ── Pipeline hooks ────────────────────────────────────────────────────────────
+
+export interface RunConfig {
+  provider:   string;
+  sessionId?: string;
+  traceId?:   string;
+}
+
+/**
+ * Hooks are sorted by the *job* they do, not by lifecycle position — the channel name is the
+ * contract. Each channel has a fixed home, cadence, and effect-ceiling (a hook may always do
+ * less: returning nothing makes it a pure observer). The discriminated union on `on` is what
+ * keeps the effects honest — `contribute` hands you a read-only session, `toolcall`/`react` can't
+ * return one at all, so a write that goes nowhere won't type-check.
+ *
+ *   screen      runner, once per turn before the first provider call. The only channel that may
+ *               durably mutate history. Returns any of: a replacement `session` (persisted),
+ *               turn-scoped `ephemeral` context (appended onto the tail of this turn's outgoing
+ *               messages — the freshest input the model reads — never persisted, and placed at the
+ *               tail rather than a system prefix so a "do X now" directive keeps its salience and
+ *               doesn't bust the cached prefix), `durable` context (the persisted, visible twin of
+ *               `ephemeral`: folded onto this turn's user message as `origin: 'robo'` blocks and
+ *               carried live as a `robo-user` event, so it survives into the next turn's history),
+ *               or `abort`. Mix freely. This is where the durable-vs-ephemeral choice for incoming
+ *               user input lives.
+ *   contribute  runner, before *every* provider call. Ephemeral by construction (it re-fires, so a
+ *               durable mutation would accumulate). Returns a transformed copy of `outgoing` — the
+ *               message array about to be sent — and never touches the stored session. Mind prompt
+ *               caching: vary the *tail* (newest turn) freely, but a transform that rewrites the
+ *               cached prefix (system / early history) busts the cache on every call.
+ *   toolcall    runner, before each tool execution. Read-only. Returns `rejectTool` (skip this call,
+ *               feed an error result back so the model self-corrects, without breaking the
+ *               tool_use/tool_result pairing) and/or `abort`.
+ *   toolresult  runner, after each tool execution, before the result is recorded/yielded. Folds the
+ *               result through each hook: return `{ result }` to replace it (hard redaction, truncation),
+ *               or nothing to observe (auditing — the context carries args, result, isError and
+ *               `durationMs`). It owns the LLM-facing + persisted result and the `tool:end` event;
+ *               note it does NOT see the live `tool:stdout/stderr` chunks, which stream before the
+ *               result exists.
+ *   followup    pump, once after a turn commits (post-persist). May `resubmit` a robo follow-up turn
+ *               (head-enqueued, so it runs next as its own real turn; `resubmitDepth` is the chain
+ *               length for the hook's own budget — the runner also hard-caps it), `retractAndRerun`
+ *               (pop the committed turn into a marker and re-run the originating user turn with
+ *               ephemeral context — supersede rather than follow), and/or append durable `markers`
+ *               to the committed session (LLM-invisible annotations — the second durable-write point
+ *               after `screen`, safe because it too fires once per turn).
+ */
+export type HookPoint = 'screen' | 'contribute' | 'toolcall' | 'toolresult' | 'followup';
+
+export interface ScreenContext {
+  session: Session;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** The turn's interactive prompt, when a frontend supplied one (a live user behind this turn).
+   *  A hook that drives an interactive tool (e.g. a trigger invoking `ask_user`) forwards this into
+   *  the tool's context; absent (cron/background/no frontend) the tool gets a rejecting prompt. */
+  prompt?: PromptFn;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+/**
+ * A raced screen verdict the runner folds in WITHOUT gating the turn on it. A `screen` hook that starts
+ * expensive work concurrently (e.g. a triggers classifier judging the user message) returns immediately
+ * and hands back one of these instead of blocking on it. The runner polls `claim()` — synchronously,
+ * never awaiting — at each turn-loop edge (before a provider call, on every stream event, and just
+ * before committing). The first time `claim()` returns blocks (the work has settled WITH a correction),
+ * the runner DISCARDS the uncommitted in-progress response and re-runs the loop with those blocks
+ * tail-folded as ephemeral context — an in-situ redo: no store pop, no retraction marker, cleaner than a
+ * post-commit retract. Because the mid-stream poll runs before each event is emitted, a verdict faster
+ * than time-to-first-token is caught before any token reaches the frontend (the clean path); a slower
+ * one aborts the in-flight provider request, saving the unstreamed remainder. If it never fires before
+ * the turn commits, the turn commits normally and any correction is left to a post-commit `followup`.
+ *
+ * `claim()` MUST be exactly-once: return the correction on the first successful poll and `undefined`
+ * forever after (not settled, no correction, or already claimed). The hook uses that single delivery to
+ * coordinate with its own post-commit path — a claimed verdict is never also delivered by `followup`.
+ */
+export interface DeferredScreen {
+  claim(): DeferredCorrection | undefined;
+}
+/**
+ * A claimed raced-verdict correction. `ephemeral` is tail-folded onto the re-run's outgoing messages
+ * and never persisted (the transient "for this answer only" twin); `durable` is folded onto the turn's
+ * user message — persisted, visible (the hook marks it `origin: 'robo'`), and carried live as a
+ * `robo-user` event — so it updates the conversation rather than informing one answer (a `contextual`
+ * trigger's semantics, preserved even though the verdict now lands mid-turn instead of before it). At
+ * least one is non-empty when returned.
+ */
+export interface DeferredCorrection {
+  ephemeral?: MessageContent[];
+  durable?:   MessageContent[];
+}
+export interface ScreenResult {
+  session?:   Session;
+  /**
+   * A raced verdict the runner folds in without gating on it (see {@link DeferredScreen}). Lets a
+   * screen hook race expensive work — a classifier — against generation: return immediately, hand this
+   * back, and the runner restarts the turn in-situ if the verdict fires before commit. A hook that
+   * would rather gate the turn (block until the verdict) just returns `ephemeral` as usual instead.
+   */
+  deferred?:  DeferredScreen;
+  /** Turn-scoped context appended onto the tail of this turn's outgoing messages (the freshest
+   *  input the model reads), never persisted. At the tail, not a system prefix, so a directive
+   *  keeps its salience and the cached system/history prefix stays stable across turns. */
+  ephemeral?: MessageContent[];
+  /**
+   * The persisted, visible twin of `ephemeral`: context that should outlive this turn rather than
+   * inform it once. The runner folds these blocks onto this turn's user message (so they ride into
+   * the stored history and every subsequent provider call) AND carries them live as a `robo-user`
+   * event, so a live draw and a reload render the same thing. They are LLM-visible (unlike
+   * `markers`) and machine-authored, so a caller marks them `origin: 'robo'` for presentation.
+   * Use when a fired hook produces context that genuinely updates the conversation, not a one-shot
+   * corrective for the turn about to run.
+   */
+  durable?:   MessageContent[];
+  /**
+   * Durable `marker` blocks to append to this turn's session (LLM-invisible). The dispatcher both
+   * appends them to the persisted session AND carries them live on the turn's event stream, so a
+   * live draw and a reload render the same thing. Use instead of hand-appending to `session` when
+   * you just want to annotate (e.g. a fired trigger's silent tool recording what it did).
+   */
+  markers?:   MessageContent[];
+  abort?:     string;
+}
+
+export interface ContributeContext {
+  readonly outgoing: readonly Message[];
+  readonly session:  Session;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+
+export interface ToolCallContext {
+  readonly session:  Session;
+  readonly toolCall: { id: string; name: string; input: unknown };
+  readonly tool:     Tool;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+export interface ToolCallResult {
+  rejectTool?: { message: string };
+  abort?:      string;
+}
+
+export interface ToolResultContext {
+  readonly session:    Session;
+  readonly toolCall:   { id: string; name: string; input: unknown };
+  readonly tool:       Tool;
+  readonly result:     unknown;
+  readonly isError:    boolean;
+  readonly durationMs: number;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+// The toolresult hook returns `{ result }` to replace the tool's result, or nothing to leave it
+// (and just observe) — a trivial single-field return, inlined in the Hook union like `contribute`'s.
+
+export interface FollowupContext {
+  readonly session:       Session;
+  readonly resubmitDepth: number;
+  config:  RunConfig;
+  signal:  AbortSignal;
+  /** The turn's interactive prompt, when a frontend supplied one (a live user behind this turn).
+   *  A hook that drives an interactive tool (e.g. a trigger invoking `ask_user` as a proactive
+   *  follow-up question) forwards this into the tool's context; absent (cron/background/no frontend)
+   *  the tool gets a rejecting prompt. Note this prompt fires *post-commit*, out of band from the
+   *  turn's `done`, and blocks the pump until the human answers. */
+  prompt?: PromptFn;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+export interface FollowupResult {
+  resubmit?: { content: MessageContent[] };
+  /**
+   * Retract-and-rerun: supersede the just-committed turn instead of following it. The pump pops the
+   * committed turn back to (and excluding) the last user message, stashes the popped content in a
+   * durable retraction marker (LLM-elided like every marker, so a frontend can render it
+   * struck-through and a post-mortem can audit it), then re-runs that same user turn with `context`
+   * injected EPHEMERALLY (tail-folded, never persisted) — agent-phase injection time-shifted onto a
+   * committed turn. This is the inverse of `resubmit`, which leaves the response in place and appends
+   * a new robo turn after it. Self-terminating by design: a well-formed trigger fires on a *curable*
+   * defect that the injected context dissolves on the redo, so it won't re-fire; `resubmitDepth` (a
+   * redo carries parent+1) caps an ill-formed one. `resubmit` and `retractAndRerun` are independent
+   * capabilities — a single turn returning both is not expected, but both head-enqueue if it does.
+   *
+   * `context` is folded EPHEMERALLY onto the redo (for-this-answer-only). `durable` is instead folded
+   * onto the re-run's user message — persisted, visible (mark it `origin: 'robo'`), carried live as a
+   * `robo-user` event — so a `contextual`-kind correction updates the conversation durably even when it
+   * lands post-commit. At least one of the two is present.
+   */
+  retractAndRerun?: { context?: MessageContent[]; durable?: MessageContent[] };
+  /**
+   * Durable `marker` blocks to append to the just-committed session (LLM-invisible; for tracing /
+   * cross-references). The second durable-write capability after `screen` — safe here for the same
+   * reason: `followup` fires once per turn, so an append can't accumulate the way a per-call channel
+   * would. The pump persists them AND emits them live (post-commit, like a `queued` event) so a live
+   * draw matches a reload. Use for recording what a post-commit reaction (e.g. a fired trigger's
+   * silent tool) actually did.
+   */
+  markers?: MessageContent[];
+}
+
+export type Hook =
+  | { on: 'screen';     priority?: number; pluginName?: string; handler(ctx: ScreenContext):     ScreenResult | void | Promise<ScreenResult | void> }
+  | { on: 'contribute'; priority?: number; pluginName?: string; handler(ctx: ContributeContext): Message[]    | void | Promise<Message[]    | void> }
+  | { on: 'toolcall';   priority?: number; pluginName?: string; handler(ctx: ToolCallContext):   ToolCallResult | void | Promise<ToolCallResult | void> }
+  | { on: 'toolresult'; priority?: number; pluginName?: string; handler(ctx: ToolResultContext): { result: unknown } | void | Promise<{ result: unknown } | void> }
+  | { on: 'followup';   priority?: number; pluginName?: string; handler(ctx: FollowupContext):   FollowupResult | void | Promise<FollowupResult | void> };

package/src/types/knowledge.ts

@@ -0,0 +1,27 @@
+// ── Knowledge index ───────────────────────────────────────────────────────────
+
+export interface KnowledgeEntry {
+  id:           string;
+  version:      string;
+  entities:     string[];
+  tags:         string[];
+  summary:      string;
+  content:      string;
+  contentHash?: string;
+  source:       { type: string; uuid: string };
+  confidence?:  number;
+  createdAt:    string;
+  updatedAt:    string;
+}
+
+export interface KnowledgeIndex {
+  index(entry: KnowledgeEntry): Promise<void>;
+  /** Remove the entry with this id, if present (idempotent — removing an absent id is a no-op). The
+   *  id is the index's sole primary key (`index` replaces by it), so retraction is by id alone; the
+   *  index never inspects an entry's opaque `source`. The party that indexed an entry owns retracting
+   *  it — e.g. a skill manager retracts a hidden/deleted skill rather than the index policing tenants. */
+  remove(id: string): Promise<void>;
+  search(terms: Array<{ term: string; context?: string }>, signal: AbortSignal): Promise<KnowledgeEntry[]>;
+  /** Enumerate all indexed entries. When present, register('KnowledgeIndex', …) drains these into the incoming backend. */
+  entries?(): Iterable<KnowledgeEntry>;
+}

package/src/types/messages.ts

@@ -0,0 +1,154 @@
+import type { HookPoint } from './hooks.js';
+import type { ISODate, MimeType } from './primitives.js';
+import type { ProviderMeta, Usage, UsageRecord } from './provider.js';
+
+// ── Messages & Session ────────────────────────────────────────────────────────
+
+export type MessageRole = 'user' | 'assistant' | 'tool' | 'system' | 'marker';
+
+export type MessageContent = (
+  // ── prose and reasoning: what the model said ──
+  | { type: 'text';              text: string }
+  | { type: 'thinking';          thinking: string; signature: string }
+  | { type: 'redacted-thinking'; data: string }
+  | { type: 'reasoning';         reasoning: string }
+  | { type: 'refusal';           text: string }
+
+  // ── inline media: bytes plus a mime type. The first three are also `ModelContent` — the arms a tool
+  //    may hand the model to look at (see the `model-content` ToolEvent). `image-url` and `file-ref`
+  //    are references rather than data, and nothing produces them yet; they are reconsidered together
+  //    when durable user-supplied media is built (a `document` / `document-reference` split). ──
+  | { type: 'image';             data: string; mimeType: MimeType }
+  | { type: 'document';          data: string; mimeType: MimeType; name?: string }
+  | { type: 'audio';             data: string; mimeType: MimeType }
+  | { type: 'image-url';         url: string; detail?: 'low' | 'high' | 'auto' }
+  | { type: 'file-ref';          fileId: string; name: string; mimeType: MimeType }
+
+  // ── tool use ──
+  | { type: 'tool-call';         id: string; name: string; input: unknown;
+      /** 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[] }
+
+  // ── frontend-facing: rendered to a person, never sent to the model ──
+  | { type: 'form';              fields: FormField[]; submitLabel?: string }
+  | { type: 'form-response';     values: Record<string, string> }
+  // Durable, opaque annotation — persisted unchanged, elided from every submission. See MarkerData below.
+  | { type: 'marker';            creator: string; data: unknown }
+
+  // ── a provider block this build does not know: preserved verbatim rather than dropped ──
+  | { type: 'unknown-content';   blockType: string; raw: unknown }
+) & {
+  /**
+   * Authorship provenance, for *presentation only* — orthogonal to the message's `role`, which is
+   * the LLM-protocol identity. Absent ⇒ authored per the role (a human for `user`, the model for
+   * `assistant`). `'robo'` ⇒ machine-authored by matbot — a `followup` resubmission, or a hook-
+   * injected fragment inside a human turn. It is still carried to the model as ordinary
+   * role-appropriate content (the model sees a `user` block either way); the flag is OOB metadata
+   * that frontends use to present it agent-side (a robot indicator) rather than as the user's words.
+   */
+  origin?: 'robo';
+};
+
+/**
+ * A marker is opaque, durable annotation carried in the message stream: links, status,
+ * cross-references that are meaningful to a frontend but transparent to the LLM. They are
+ * persisted unchanged, elided from provider submission, and deliberately preserved by
+ * session compaction (removing one can break things — e.g. a pointer back to an ancestor
+ * session). Any code with session access may emit one, normally as its own message.
+ *
+ * `creator` is the emitting plugin's reference; `data` is anything serialisable. For
+ * per-creator type safety, augment `MarkerData` and read/write via `Marker<'your-creator'>`:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface MarkerData { 'split-session': { peerSessionId: string } }
+ *   }
+ *
+ * Unregistered creators fall back to `data: unknown`. The base `MessageContent` member stays
+ * loose (`creator: string`) so the union and its exhaustive switches are unaffected.
+ *
+ * One of matbot's five open-registry augmentation points — same technique at each; see
+ * docs/DEVELOPING.md *Open-registry augmentation* for the shared shape and the rules that follow from it.
+ */
+export interface MarkerData {
+  /** Emitted by the hook dispatcher when a hook handler threw: the hook was skipped (treated as a
+   *  no-op) and this records it once, so a misconfigured/throwing hook degrades visibly instead of
+   *  bricking the turn. `channel` is the hook point, `pluginName` the owning plugin if known. */
+  'matbot-hooks': { channel: HookPoint; pluginName?: string; message: string };
+  /** Emitted by the runner when a provider call was cut short rather than finishing (see the
+   *  `truncated` CompletionEvent). Marker-role so the reader and an audit see it while the model does
+   *  not — the model's own text is already truncated in the transcript; a block telling it so would
+   *  invite it to narrate the cut-off rather than continue past it. */
+  'matbot-truncation': { reason: 'max-tokens' | 'stream-end'; raw?: string };
+}
+
+export type Marker<K extends string = string> = {
+  type:    'marker';
+  creator: K;
+  data:    K extends keyof MarkerData ? MarkerData[K] : unknown;
+};
+
+export interface FormField {
+  name:        string;
+  label:       string;
+  type:        'text' | 'password' | 'select' | 'confirm';
+  options?:    string[];
+  /** select-only: render an "Other…" affordance that lets the user type a free-form answer instead
+   *  of picking an option. The typed value is returned verbatim, on the same channel as a pick —
+   *  callers never learn whether the answer was a preset or free text. Ignored for other types. */
+  allowOther?: boolean;
+  default?:    string;
+  required?:   boolean;
+  /** Presentation hint only (default true): whether the frontend offers a cancel affordance (the
+   *  "give up" path — see `PromptFn`). Set false to render a hard-blocking prompt with no out. The
+   *  runner and server never consult this; a frontend with no cancel UI simply can't fire one. */
+  cancelable?: boolean;
+}
+
+/**
+ * Canonical values a `type: 'confirm'` prompt resolves to. The rendered label and buttons are a
+ * cosmetic, host-specific concern (and may be localised), so consumers MUST branch on these tokens
+ * — never on the displayed string. Compare case-insensitively to tolerate host casing differences.
+ */
+export const CONFIRM_YES = 'yes';
+export const CONFIRM_NO  = 'no';
+
+export interface Message {
+  id:            string;
+  role:          MessageRole;
+  content:       MessageContent[];
+  createdAt:     ISODate;
+  traceId:       string;
+  providerName?: string;
+  /** Token/cost accounting for the provider call that produced this message (assistant turns). The
+   *  billed provider is this message's `providerName`. Accounting only — elided from provider submission. */
+  usage?:        Usage;
+  metadata?:     Record<string, unknown>;
+}
+
+export type SessionStatus = 'active' | 'archived' | 'pinned';
+
+export interface Session {
+  id:                    string;
+  version:               string;
+  // Legacy: persisted sessions may still carry `ownerPrincipalId` / `actorPrincipalId` / `persona`, and
+  // `contexts` (a required-but-never-read `string[]`, dropped at 0.4.0 — system context is contributed by
+  // SystemContextContributor, not carried on the session). Never read — ownership-at-rest is structural
+  // (the storage partition), resolved via the backend, not a field. Left undeclared; old data keeps them
+  // harmlessly as excess properties.
+  title?:                string;
+  status:                SessionStatus;
+  messages:              Message[];
+  parentSessionId?:      string;
+  branchPointMessageId?: string;
+  createdAt:             ISODate;
+  updatedAt:             ISODate;
+}

package/src/types/primitives.ts

@@ -0,0 +1,5 @@
+// ── Primitives ────────────────────────────────────────────────────────────────
+
+export type ISODate = string;
+export type MimeType = string;
+export type JSONSchema = Record<string, unknown>;

package/src/types/principal.ts

@@ -0,0 +1,10 @@
+// ── Principal ───────────────────────────────────────────────────────────────
+
+/** Identity of whatever initiated an operation — a turn, a tool call, a store read/write.
+ *  Established at each entry point and carried ambiently via the `PrincipalCarrier`
+ *  (`currentPrincipal()` / `runAs()`), so any layer can attribute or test the origin without it
+ *  being threaded through every signature. It grants nothing — policy is the service's concern. */
+export interface Principal {
+  id:    string;
+  type:  'user' | 'agent' | 'system';
+}

package/src/types/provider.ts

@@ -0,0 +1,157 @@
+import type { HealthStatus } from './health.js';
+import type { Message } from './messages.js';
+import type { Tool } from './tools.js';
+
+// ── Provider ──────────────────────────────────────────────────────────────────
+
+export interface ModelParameters {
+  temperature?:    number;
+  maxTokens?:      number;
+  topP?:           number;
+  stopSequences?:  string[];
+  [key: string]:   unknown;
+}
+
+export interface ProviderConfig {
+  name:         string;
+  /** Plugin module specifier (npm name or file URL) that provides the adapter for this provider. */
+  module:       string;
+  model:        string;
+  credentials?:  Record<string, string>;
+  endpoint?:    string;
+  parameters?:  ModelParameters;
+  /**
+   * Ceiling on the agentic rounds one turn may take against this provider — a round being one provider
+   * call plus the tool batch it asked for. Reaching it ends the turn (`aborted`, reason `round-limit`)
+   * rather than starting another round. Absent ⇒ unbounded, which is the historical behaviour.
+   *
+   * It lives here, per provider, rather than as one global or a per-call override because that is the
+   * unit spend is actually denominated in: a local model can afford to grind, a frontier model at 100×
+   * the rate cannot, and the same deployment runs both. Not in `parameters` — those are forwarded to
+   * the endpoint unmodified, and this never leaves matbot.
+   */
+  maxRounds?:   number;
+}
+
+/**
+ * Token (and optional cost) counters for one provider call — pure accounting data, never conversation
+ * content. Recorded onto the message stream for cost reckoning but elided from provider submission. The
+ * producing provider is recorded alongside at each storage site (an assistant turn carries it on the
+ * message's `providerName`; a tool-invoked completion pairs it explicitly — see `tool-result`), since a
+ * tool may run a completion against any configured provider, each with its own rates.
+ */
+export interface Usage {
+  inputTokens:          number;
+  outputTokens:         number;
+  costUsd?:             number;
+  cacheReadTokens?:     number;
+  cacheCreationTokens?: number;
+}
+
+/** One provider call's usage, tagged with the provider billed — the unit a tool accrues (a tool may
+ *  run completions against any provider, each with its own rates) and the element persisted on a
+ *  `tool-result`'s `usage` addendum. See the ambient usage carrier (`recordUsage`/`currentUsageSink`). */
+export interface UsageRecord {
+  provider: string;
+  usage:    Usage;
+}
+
+/**
+ * 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
+ * signature", which every historical `functionCall` must carry or the request 400s). The harness never
+ * interprets it: it stores, renders, or elides it. Empty by default — a provider package augments its
+ * OWN slice from its own module (namespaced by provider family, so slices from different providers in a
+ * mixed-provider session never collide), so adding a provider that needs round-trip state touches NO
+ * core code:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface ProviderMeta { google?: { thoughtSignature?: string } }
+ *   }
+ *
+ * A single session interleaves tool-calls from many providers, so this must be an open, additive union
+ * (interface augmentation) — a generic type parameter can bind only one provider per instantiation and
+ * so could not type a heterogeneous transcript.
+ *
+ * One of matbot's five open-registry augmentation points — same technique at each; see
+ * docs/DEVELOPING.md *Open-registry augmentation* for the shared shape and the rules that follow from it.
+ */
+export interface ProviderMeta {}
+
+export type CompletionEvent =
+  | { type: 'text-delta';          delta: string }
+  | { type: 'tool-call';           id: string; name: string; input: unknown;
+      /** Provider-specific round-trip metadata for this call, opaque to the harness — see `ProviderMeta`. */
+      meta?: ProviderMeta;
+      /**
+       * Set when the call's arguments were severed mid-stream and never parsed — nearly always the
+       * response hitting its token limit part-way through a large call. `input` is then `{}` (the wire
+       * requires an object; the real arguments are unrecoverable), and the runner does NOT execute the
+       * call: it pairs it with an error result saying so, exactly as it does a rejected one, and the
+       * model self-corrects on the next round.
+       *
+       * Only adapters that accumulate arguments as a streamed JSON *string* can detect this — the
+       * Anthropic (`input_json_delta`) and OpenAI (`function.arguments` fragments) shapes. Gemini
+       * delivers each `functionCall` complete with `args` already an object, so there is nothing to
+       * sever and the field is never set there.
+       */
+      truncated?: { bytes: number; stopReason?: string } }
+  | { type: 'tool-result';         id: string; result: unknown }
+  | { type: 'thinking';            delta: string }
+  | { type: 'thinking-block';      thinking: string; signature: string }
+  | { type: 'redacted-thinking';   data: string }
+  | { type: 'reasoning-block';     reasoning: string }
+  | { type: 'refusal';             text: string }
+  | { type: 'unknown-block';       blockType: string; raw: unknown }
+  /**
+   * The response was cut short — the model did not choose to stop. `max-tokens` is the provider saying
+   * so outright (`stop_reason: "max_tokens"` / `finish_reason: "length"` / `finishReason: "MAX_TOKENS"`);
+   * `stream-end` is the stream ending with no finish reason at all, e.g. a dropped connection.
+   *
+   * Emitted whether or not a tool call was caught in it, because the far commoner case has no tool call
+   * in it at all: prose stopping mid-sentence, which matbot previously did not surface anywhere. The
+   * runner records it as a durable `matbot-truncation` marker — LLM-invisible, so it informs the reader
+   * and the audit without the model narrating its own cut-off. Acting on it (continuing, re-asking with
+   * a larger budget) is a `followup` hook's business, not the harness's.
+   */
+  | { type: 'truncated';           reason: 'max-tokens' | 'stream-end'; raw?: string }
+  | ({ type: 'usage' } & Usage)
+  | { type: 'done' };
+
+/**
+ * The result the runner records for a tool call whose arguments were truncated (see the `truncated`
+ * field on the `tool-call` event). The call did not run and has no side effect.
+ *
+ * The `truncated` addendum is what makes this distinguishable from an ordinary tool failure, so a
+ * `toolresult` hook can recognise it and fold in advice the harness has no business knowing — which
+ * argument to split, which of *this* tool's parameters offers a cheaper edit. Narrow with
+ * {@link isTruncatedToolResult} rather than duck-typing the shape:
+ *
+ *   services.hooks.register({ on: 'toolresult', handler: ctx => {
+ *     if (!isTruncatedToolResult(ctx.result)) return;
+ *     return { result: { ...ctx.result, error: `${ctx.result.error} For a large edit, pass start_line/end_line instead.` } };
+ *   }});
+ */
+export interface TruncatedToolResult {
+  error:     string;
+  truncated: { tool: string; bytes: number; stopReason?: string };
+}
+
+export function isTruncatedToolResult(result: unknown): result is TruncatedToolResult {
+  if (typeof result !== 'object' || result === null) return false;
+  const t = (result as { truncated?: unknown }).truncated;
+  return typeof t === 'object' && t !== null
+    && typeof (t as { tool?: unknown }).tool  === 'string'
+    && typeof (t as { bytes?: unknown }).bytes === 'number';
+}
+
+export interface ProviderAdapter {
+  readonly name: string;
+  complete(
+    messages: Message[],
+    config:   ProviderConfig,
+    tools:    readonly Tool[],
+    signal:   AbortSignal
+  ): AsyncIterable<CompletionEvent>;
+  health(): Promise<HealthStatus>;
+}

package/src/types/registries.ts

@@ -0,0 +1,84 @@
+import type { Hook } from './hooks.js';
+import type { Session } from './messages.js';
+import type { ProviderConfig } from './provider.js';
+import type { Tool } from './tools.js';
+
+// ── Registries ────────────────────────────────────────────────────────────────
+
+/**
+ * What `services.hooks` is: the *registration* half of hook dispatch, and the whole of what a plugin can
+ * do with it. `MatbotRuntime.hooks` was typed as the `HookRegistry` class, so the plugin contract also
+ * advertised the host's dispatch surface (`runScreen`, `runContribute`, `runToolCall`, `runToolResult`,
+ * `runFollowup`) — none of which a plugin may call, and which the scoped per-plugin facade had to be
+ * `as unknown as`-cast to satisfy. The cast was the tell. Core still holds the class where it dispatches.
+ */
+export interface HookRegistrar {
+  register(hook: Hook): void;
+  removeByPlugin(pluginName: string): void;
+}
+
+/** Tool CRUD is observed on the {@link Notifier}, as a `RegistryChange` with `registry: 'tools'` — this
+ *  registry had its own broadcaster over the same primitive, which is duplication, not layering. One
+ *  notification per tool (removeByPlugin announces a `removed` per matched tool); the registering
+ *  plugin's name rides in `detail`, advisory as ever — resolve the name for anything authoritative. */
+export interface ToolRegistry {
+  /** Registers `tool` and returns — there is nothing to await. The name is free in the overwhelming
+   *  case, and that path completes in the calling tick, so `setup()` can fire-and-forget. When a
+   *  *different* plugin already owns the name the host may resolve it out of band (it can ask the user),
+   *  in which case the tool lands after `setup()` has returned, or not at all if the user keeps the
+   *  incumbent. The host owns that outcome — a failure to resolve keeps the existing tool, and neither
+   *  case can reject into the caller. Registration order across plugins is not a contract; resolve by
+   *  name at call time. */
+  register(tool: Tool): void;
+  remove(name: string): void;
+  resolve(name: string): Tool | null;
+  list(): readonly Tool[];
+  removeByPlugin(pluginName: string): void;
+}
+
+/** What the runner tells a {@link ToolPresenter} about the call it's about to make. */
+export interface PresentContext {
+  /** The session as of this provider call — the persisted user turn plus any assistant/tool turns
+   *  taken so far this turn. A presenter ranks the tool set against this. */
+  session:  Session;
+  /** The provider profile name this turn runs under, so a presenter can tailor to provider
+   *  capabilities (e.g. Anthropic's in-context tool_reference expansion). */
+  provider: string;
+}
+
+/**
+ * Chooses which tools are advertised to the model for a single provider call — a read-only *view* over
+ * the turn's tool snapshot, NOT tool management. Presentation is orthogonal to the {@link ToolRegistry},
+ * which stays the single source of registration, resolution, and type-contracts (its fragile, load-bearing
+ * machinery is never a swap surface). The runner consults the presenter before *every* provider call, so
+ * an impl may present a subset (deferring a large library behind a search tool) and grow it mid-turn as the
+ * model discovers tools. Executor resolution is unaffected — a tool withheld here stays callable by name
+ * through the live registry — so presentation only ever changes what the model is *told about*.
+ *
+ * Optional {@link MatbotServices} member (offer-loosely): absent ⇒ the runner advertises the whole
+ * snapshot, byte-identical to today. `present` may return synchronously or async (a reranker).
+ */
+export interface ToolPresenter {
+  present(tools: readonly Tool[], ctx: PresentContext): readonly Tool[] | Promise<readonly Tool[]>;
+}
+
+/**
+ * The named provider profiles the runtime resolves by name. A `ReadonlyMap` for the many read-only
+ * consumers (`services.providers.get`/`has`/`keys`/…), plus a sanctioned write path so a plugin can
+ * *contribute* profiles live — a storage backend replaying provider definitions it captured in its own
+ * medium, or the built-in `provider` tool — exactly as a plugin contributes tools via {@link ToolRegistry}.
+ * Keyed by `config.name`; `register` upserts.
+ */
+export interface ProviderRegistry extends ReadonlyMap<string, ProviderConfig> {
+  register(config: ProviderConfig): void;
+  /** Explicit delete (the `provider` tool's `remove`) — removes the profile outright. */
+  remove(name: string): boolean;
+  /**
+   * Undo a contribution: restore the boot-baseline profile for `name` if one existed (a plugin-supplied
+   * profile that shadowed a configured one), otherwise delete it. A plugin that registers providers
+   * (e.g. a storage backend replaying them from its medium) calls this for each in its `teardown()`, so
+   * unloading it reverts the provider set to the host's boot condition — the multi-valued analogue of a
+   * swap-member reverting to its captured boot default.
+   */
+  revert(name: string): void;
+}