@matatbread/matbot-plugin-api 0.3.8 → 0.4.0

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;
+}

package/src/types/session-runner.ts

@@ -0,0 +1,69 @@
+import type { PipelineEvent } from './events.js';
+import type { MessageContent, Session } from './messages.js';
+import type { Principal } from './principal.js';
+import type { SteeringMode } from './steering.js';
+import type { PromptFn } from './tools.js';
+
+// ── Session runner ──────────────────────────────────────────────────────────────
+
+/**
+ * A view onto a session returned by `SessionRunner.open`. `session` is the authoritative
+ * server-side state — committed messages plus an overlay of any queued-but-not-yet-run
+ * submissions (each carrying `metadata.pending: true`). `events` is a lazy, per-session live
+ * tap: accessing it subscribes to the turn event stream from now (replaying the in-flight
+ * turn, if any); never touching it costs nothing.
+ */
+export interface SessionView {
+  session:        Session;
+  /** Submissions waiting behind the current turn (does not count the running turn). */
+  queued:         number;
+  /** Correlation id of the submission this call enqueued — present only when content was supplied. */
+  traceId?:       string;
+  readonly events: AsyncIterable<PipelineEvent>;
+}
+
+/** Observe a session without submitting anything. */
+export interface OpenOpts {
+  sessionId: string;
+  signal:    AbortSignal;
+  /** Optional caller-supplied correlation id; one is generated when absent. */
+  traceId?:  string;
+}
+
+/** Observe a session AND enqueue a submission. The compiler enforces provider/principal here;
+ *  a remote frontend deserializing a request body must still validate the wire input itself. */
+export interface SubmitOpenOpts extends OpenOpts {
+  content:      MessageContent[];
+  provider:     string;
+  principal:    Principal;
+  /** When true, this submission may be merged with others drained in the same batch. Default false
+   *  (queue mode: one turn per submission). */
+  concatQueue?: boolean;
+  /** Disposition for a submission arriving while a turn is running (see {@link SteeringPolicy}):
+   *  'queue' waits for the turn boundary (default), 'interrupt' stops the running turn — keeping its
+   *  committed partial work — and runs this next, 'auto' defers to the registered SteeringPolicy (else
+   *  the host default). Meaningless when nothing is running (degrades to a plain enqueue). */
+  mode?:        SteeringMode;
+  /** Interactive prompt implementation for this submission's turn. The frontend owns delivery —
+   *  it must target the frontend's per-session client connections, not a single request. */
+  prompt?:      PromptFn;
+}
+
+/**
+ * Serialises turns per session. A submission never executes concurrently with another for the
+ * same session; the in-memory queue (lost on process restart, by design) absorbs anything that
+ * arrives mid-turn. The server is the source of truth: a frontend renders whatever `open()`
+ * returns and treats the live `events` stream purely as an optimisation.
+ */
+export interface SessionRunner {
+  open(opts: OpenOpts | SubmitOpenOpts): Promise<SessionView>;
+  /** Abort the running turn (if any) and drop all queued submissions, emitting `cancelled` for each. */
+  abort(sessionId: string): void;
+  /** Abandon the running turn (if any) WITHOUT touching the queue — `pump` advances to the next
+   *  queued submission, or idles. The "give up on this turn" path (a prompt cancel); contrast
+   *  `abort`, which also clears the queue. A no-op if nothing is running. */
+  cancelTurn(sessionId: string): void;
+  /** Snapshot of a session's live state: whether a turn is running and how many submissions wait
+   *  behind it. `busy` is `running || queued > 0`. */
+  status(sessionId: string): { busy: boolean; running: boolean; queued: number };
+}

package/src/types/steering.ts

@@ -0,0 +1,33 @@
+import type { MessageContent, Session } from './messages.js';
+
+// ── Steering ────────────────────────────────────────────────────────────────────
+
+/** Disposition of a submission that arrives while a turn is running. `interrupt` stops the running
+ *  turn (its committed partial work is preserved) and runs the new message next; `queue` waits for the
+ *  turn boundary. */
+export type SteeringDecision = 'queue' | 'interrupt';
+/** The wire-level request (see `SubmitOpenOpts.mode`). `auto` defers the decision to the registered
+ *  {@link SteeringPolicy} (else the host default). */
+export type SteeringMode = SteeringDecision | 'auto';
+
+/**
+ * How the runner disposes of a mid-turn submission under `mode: 'auto'`, and how an interrupt's
+ * continuation is nudged. An optional, registerable service ({@link MatbotServices}); absent ⇒ the
+ * runner uses its own defaults. Both members are optional so a plugin may override one, the other, or
+ * both. `classify` is deliberately NOT assumed to be an LLM — a regex or a semantic classifier is a
+ * first-class implementation (return synchronously); an LLM `singleTurn` returns a promise.
+ */
+export interface SteeringPolicy {
+  /**
+   * Consulted only for `mode: 'auto'` while a turn is running. `session` is the COMMITTED session
+   * (history up to the running turn's start — the in-flight partial is not reachable at submit time);
+   * `steer` is the incoming submission. Return synchronously (regex) or async (semantic / singleTurn).
+   * Absent ⇒ the host default disposition.
+   */
+  classify?(ctx: { session: Session; steer: MessageContent[] }): SteeringDecision | Promise<SteeringDecision>;
+  /**
+   * The ephemeral "keep going, noting the above" context folded onto an interrupt's continuation turn
+   * (never persisted). Absent ⇒ the host default nudge.
+   */
+  nudge?(ctx: { session: Session; steer: MessageContent[] }): MessageContent[];
+}

package/src/types/storage.ts

@@ -0,0 +1,16 @@
+import type { QueryResult, StoreQuery } from '../store-query.js';
+
+// ── Storage ───────────────────────────────────────────────────────────────────
+// The query grammar (Filter AST, StoreQuery, QueryResult, StoreQueryError) lives in ./store-query.
+
+export type CASResult<T> =
+  | { ok: true;  doc: T }
+  | { ok: false; current: T | null };
+
+export interface Store<T extends { id: string; version: string }> {
+  get(id: string): Promise<T | null>;
+  set(id: string, value: T): Promise<void>;
+  cas(id: string, expected: string, next: T): Promise<CASResult<T>>;
+  delete(id: string, expectedVersion?: string): Promise<boolean>;
+  query(q: StoreQuery): Promise<QueryResult<T>>;
+}

package/src/types/system-context.ts

@@ -0,0 +1,15 @@
+import type { Session } from './messages.js';
+
+// ── System context ────────────────────────────────────────────────────────────
+
+export type SystemContextContributor = (ctx: {
+  session:   Session;
+  signal:    AbortSignal;
+}) => string | null | Promise<string | null>;
+
+export interface SystemContextRegistry {
+  register(contributor: SystemContextContributor, pluginName?: string): void;
+  removeByPlugin(pluginName: string): void;
+  /** Calls all contributors and joins non-null, non-empty results with double newlines. */
+  build(ctx: { session: Session; signal: AbortSignal }): Promise<string | null>;
+}

package/src/types/tools.ts

@@ -0,0 +1,262 @@
+import type { FileHandle, FileStore } from './files.js';
+import type { FormField, MessageContent, Session } from './messages.js';
+import type { MatbotPlugin } from '../plugin.js';
+import type { JSONSchema } from './primitives.js';
+import type { Vault } from './vault.js';
+
+// ── Tools ─────────────────────────────────────────────────────────────────────
+
+/**
+ * Media a tool hands to the model to *look at*, as opposed to the JSON it reads as a `result`. The
+ * inline arms of {@link MessageContent} — bytes plus a mime type, carrying their own meaning with no
+ * dependency on anything that could resolve a reference. Where the tool got the bytes (a `FileStore`,
+ * an HTTP fetch, a chart rendered in memory) is entirely the tool's business; the harness never asks.
+ */
+export type ModelContent = Extract<MessageContent, { type: 'image' | 'document' | 'audio' }>;
+
+export type ToolEvent<Result = unknown> =
+  | { type: 'stdout';   chunk: string }
+  | { type: 'stderr';   chunk: string }
+  | { type: 'progress'; pct: number; message?: string }
+  | { type: 'result';   value: Result }
+  | { type: 'file';     handle: FileHandle }
+  // Media for the model's eyes, pinned to this tool call's result and carried on the wire for the
+  // REST OF THIS TURN only — never persisted. Independent of `result`: the durable record of what the
+  // tool did is its `result`, and a transcript that re-reads clean is the point. A later turn that
+  // needs the bytes again calls the tool again, which is the same pull the model already performed.
+  //
+  // Rest-of-turn rather than next-call-only because withdrawing content the model has already seen
+  // mid-history breaks the prompt cache from that point and leaves it referring to something no longer
+  // there. The corollary is cost: a large document is re-sent on every subsequent round of the turn,
+  // so a tool should hand over the smallest thing that answers the question (a page range, a thumbnail)
+  // and `maxRounds` is the ceiling on how often it is paid for.
+  | { type: 'model-content'; content: ModelContent[] }
+  // A durable, LLM-invisible annotation the tool emits as it runs (a link, a status, a trace of a
+  // side-effect). Persisted as a `marker`-role message; elided from provider submission like any
+  // marker. Independent of `result` — a tool may emit markers and no result (a silent side-effect,
+  // e.g. a trigger-fired tool), a result and no markers, or both.
+  | { type: 'marker';   creator: string; data: unknown }
+  | { type: 'error';    message: string; code?: number; stdout?: string; stderr?: string };
+
+/**
+ * Per-tool call-contract registry: maps a tool's `name` to a {@link ToolContract} arm (or a union of
+ * them) pairing the `value` it yields in its `result` event with the params that produce it. Augment it
+ * exactly like {@link MarkerData} / `MatbotServices`, so a caller gets the concrete result type back
+ * from {@link invokeTool} + `toolResult` instead of `unknown`:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface ToolContracts {
+ *       find_fact: ToolContract<string[] | null, { question: string; terms: { term: string }[] }>;
+ *     }
+ *   }
+ *
+ * The tool name is the discriminator: `invokeTool(machine, 'find_fact', …)` is typed
+ * `AsyncIterable<ToolEvent<string[] | null>>`, so `toolResult(…)` resolves to `string[] | null`. A
+ * name with no registered entry resolves to `unknown` (the caller must narrow). This is a pure
+ * type-level construct — no runtime validation; it pins, at the call site, the contract a tool's
+ * executor already produces. Keep the entry in sync with what the executor actually yields.
+ *
+ * Even a single-action tool declares an **arm**, never a bare `name: Result`. The bare form still
+ * type-checks — `ToolResultOf`/`ToolResultFor` keep a plain-entry path so an unregistered or foreign
+ * tool stays loose — but it carries no params, so {@link ToolProxy} derives no call signature from it
+ * and `await tool.find_fact(…)` is uncallable.
+ *
+ * **Multi-action tools** are a weird form of overloaded function: the same tool returns different
+ * shapes depending on its params. Register such a tool as a union of {@link ToolContract} *arms*, each
+ * pairing a result with the discriminating params *pattern* that selects it — `invokeTool` matches the
+ * call's literal params against the patterns and narrows the result to the matching arm:
+ *
+ *   declare module '@matatbread/matbot-plugin-api' {
+ *     interface ToolContracts {
+ *       session_action:
+ *         | ToolContract<Session,                       { action: 'get' }>
+ *         | ToolContract<{ id: string; title: string }, { action: 'rename' }>;
+ *     }
+ *   }
+ *   // invokeTool(machine, 'session_action', { action: 'get', sessionId }) → result is Session
+ *
+ * The pattern is *any* discriminating field(s), not just `action` (a tool keying on `interval`'s
+ * presence registers `ToolContract<…, { interval: string }>`). It is a *pattern*, not the full input:
+ * key only on the discriminant so a call carrying just that field still matches. When no arm's pattern
+ * matches (a non-literal discriminant, or an absence-discriminant the positive patterns can't express),
+ * the result falls back to the union of every arm — always sound, just less narrow.
+ *
+ * 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 ToolContracts {}
+
+// Phantom carriers for ToolContract's two parameters. `unique symbol` keys rather than `__result`/`__args`
+// so the type is *uninhabitable*: a plugin author cannot name these keys, so no value of ToolContract can
+// be written down by accident (or on purpose, to smuggle a shape past the checker) — where the previous
+// `__`-prefixed properties were merely conventionally-private and constructible with a couple of casts.
+// A cast is the one hole through which a hallucinated result shape survives to runtime, which is why the
+// generated-code checker closes it deterministically; this closes the same hole in the type itself.
+declare const RESULT: unique symbol;
+declare const ARGS:   unique symbol;
+
+/**
+ * One overload arm of a multi-action tool registered in {@link ToolContracts}: the `Result` it yields
+ * for a call whose params match the discriminating pattern `Args`. `Args` defaults to `unknown` (an
+ * arm that matches any params). Purely type-level — the fields below are phantom and uninstantiable.
+ */
+export interface ToolContract<Result, Args = unknown> {
+  readonly [RESULT]: Result;
+  readonly [ARGS]:   Args;
+}
+
+type ToolResultArmed<E>           = E extends ToolContract<unknown, unknown> ? true : false;
+type ToolResultUnion<E>           = E extends ToolContract<infer R, unknown> ? R : never;
+type ToolResultMatched<E, P>      = E extends ToolContract<infer R, infer A> ? (P extends A ? R : never) : never;
+
+/** The full set of `result` values a tool named `K` may yield — the union over all its arms (for an
+ *  arm-based entry), the entry itself (for a plain entry), or `unknown` when `K` is unregistered. This
+ *  is what an executor binds against (`ToolExecutor<ToolResultOf<'my_tool'>>`): it must cover every arm. */
+export type ToolResultOf<K extends string> =
+  K extends keyof ToolContracts
+    ? ToolResultArmed<ToolContracts[K]> extends true ? ToolResultUnion<ToolContracts[K]> : ToolContracts[K]
+    : unknown;
+
+/** The `result` a call to tool `K` with params `P` yields: for an arm-based entry, the arm whose
+ *  pattern `P` matches (or the full union when none match — always sound); otherwise {@link ToolResultOf}. */
+export type ToolResultFor<K extends string, P> =
+  K extends keyof ToolContracts
+    ? ToolResultArmed<ToolContracts[K]> extends true
+      ? ([ToolResultMatched<ToolContracts[K], P>] extends [never]
+          ? ToolResultUnion<ToolContracts[K]>
+          : ToolResultMatched<ToolContracts[K], P>)
+      : ToolContracts[K]
+    : unknown;
+
+// Distribute a union to its intersection: `A | B` → `A & B`. An intersection of function types is an
+// overload set, so this turns a union of per-arm call signatures into an overloaded function.
+type UnionToIntersection<U> =
+  (U extends unknown ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+
+// One `ToolContracts` arm → its call signature. A fully-untyped arm (`ToolContract<unknown, unknown>`, the
+// fallback for a foreign/MCP tool carrying only a JSON-Schema `inputSchema`) keeps a loose, optional-param
+// signature so it stays callable; a typed arm requires its declared params.
+type ArmCallSig<E> =
+  E extends ToolContract<infer R, infer P>
+    ? (unknown extends P ? (params?: unknown) => Promise<R> : (params: P) => Promise<R>)
+    : never;
+
+// The union of a tool's arm params — the parameter type of the trailing catch-all signature below.
+type ArmArgsUnion<E> = E extends ToolContract<unknown, infer A> ? A : never;
+
+/**
+ * The type of the injected `tool` proxy that `function-tools` and compiled skills call
+ * (`await tool.name(params)`). Each key is derived from its {@link ToolContracts} entry: a multi-arm
+ * (multi-action) entry becomes an **overload set** — one `(params) => Promise<result>` signature per arm —
+ * so `await tool.name(params)` narrows its result by the params passed, exactly the contract a code
+ * generator needs to write a correct call first time. A single-arm entry is one signature. This is what the
+ * generated `dts()` declares `tool` as; it is *derived* — never hand-authored — from the same `ToolContracts`
+ * augmentation that types authors' `invokeTool`/`toolResult` calls, so the human editor and the LLM see one
+ * source of truth.
+ *
+ * The trailing catch-all signature (params union → result union) exists for soundness at the *meta-type*
+ * level, not for call sites: overload resolution is first-match, so a well-formed call still hits its
+ * specific arm and narrows precisely, and a malformed call matches nothing and still errors. What it
+ * changes: `ReturnType<typeof tool.x>` — which on a bare overload set resolves to an arbitrary (last) arm,
+ * a real-world codegen trap — now degrades to the sound full union; and a params value typed as a union of
+ * arms (dynamic multi-action dispatch) becomes callable, returning the result union.
+ */
+export type ToolProxy = { [K in keyof ToolContracts]:
+    UnionToIntersection<ArmCallSig<ToolContracts[K]>>
+  & ((params: ArmArgsUnion<ToolContracts[K]>) => Promise<ToolResultUnion<ToolContracts[K]>>) };
+
+/**
+ * Ask the user a question and resolve with their answer. The host supplies the
+ * implementation — readline in the CLI, an SSE round-trip in the web frontend. This is
+ * matbot's single mechanism for eliciting user input at runtime; it is injected both into
+ * tool execution (`ToolContext.prompt`) and into plugin loading (collision resolution in setup).
+ *
+ * Two call forms:
+ *   - `(question, defaultValue?)` — free text; resolves to the typed string (or the default).
+ *   - `(field: FormField)` — a single structured field (`select`/`confirm`/`password`/`text`),
+ *     letting rich frontends render real controls (buttons, masked input). Frontends that can't
+ *     render it fall back to `field.label` as plain text. Resolves to the chosen/typed value.
+ *
+ * Cancellation is the "we can't proceed — give up" path (distinct from a graceful "decline", which
+ * is simply one of the offered `options`). The host rejects the promise with `PromptCancelledError`
+ * and abandons the current turn, returning to idle; a caller's surrounding try/catch turns the
+ * rejection into a tool error that closes the tool call cleanly.
+ *     This reuses `FormField` rather than a parallel type; it is a one-shot request/response and
+ *     deliberately does NOT engage the session-bound `form`/`form-response` flow.
+ */
+export interface PromptFn {
+  (question: string, defaultValue?: string): Promise<string>;
+  (field: FormField): Promise<string>;
+}
+
+export interface ToolContext {
+  callId:      string;
+  session:     Session;
+  signal:      AbortSignal;
+  vault:       Vault;
+  /** The provider key driving the current turn (`RunConfig.provider`). A tool that spawns further
+   *  work should default to this so the child inherits the same model rather than the config default. */
+  provider?:   string;
+  workdir?:    string;
+  configPath?: string;
+  files?:      FileStore;
+  /** Prompt the user for input. The host provides a readline or form implementation. */
+  prompt:      PromptFn;
+  /** Hot-load a plugin by specifier without restarting the process. Returns the loaded plugin.
+   *  `refresh` (default false) forces a remote (github/http) plugin to be re-downloaded rather than
+   *  re-loaded from its `.plugins/` cache — pass true to pick up changed upstream source. */
+  loadPlugin(specifier: string, refresh?: boolean): Promise<MatbotPlugin>;
+  /**
+   * Hot-unload a plugin by specifier, removing its tools, hooks, and system context contributions.
+   * Resolves `true` if a plugin was actually resident and unloaded, `false` if there was nothing
+   * to unload. A failed `teardown()` (e.g. timeout) still throws — the plugin was resident in that case.
+   */
+  unloadPlugin(specifier: string): Promise<boolean>;
+}
+
+/**
+ * The read-only facts about the call a composed function is running under, injected into a
+ * `tool_function` body as the ambient `context` binding beside `tool`/`toolInContext`. Deliberately
+ * narrower than {@link ToolContext}: the identity of the call, not its capabilities — `vault`,
+ * `files`, `prompt` and plugin (un)loading stay off a surface authored by a model and reachable only
+ * through the tool contracts. A tool with real source takes `ToolContext` and needs none of this.
+ *
+ * Not `ToolCallContext` — that name belongs to the `toolcall` hook's context; this is the composed
+ * caller's own view, not a hook's view of a call about to run.
+ */
+export interface ComposedCallContext {
+  readonly callId:    string;
+  readonly sessionId: string;
+  /** The provider key driving the turn — the same one nested `tool.x(…)` calls inherit. */
+  readonly provider?: string;
+  readonly workdir?:  string;
+  readonly signal:    AbortSignal;
+}
+
+/**
+ * A tool's runtime. `R` is the type of the `value` carried by its `result` event — declared once,
+ * at the source, so the executor's yields and the tool's {@link ToolContracts} registry entry can't
+ * silently drift. The `unknown` default keeps untyped executors compiling untouched, and covariance
+ * means a narrower `ToolExecutor<X>` still satisfies `ToolExecutor` (i.e. `ToolExecutor<unknown>`),
+ * so the heterogeneous registry boundary (`Tool[]`) accepts any executor. Bind `R` to the registry
+ * entry with `ToolExecutor<ToolResultOf<'my_tool'>>` so the single augmentation is the source of truth.
+ */
+export interface ToolExecutor<R = unknown> {
+  execute(input: unknown, ctx: ToolContext): AsyncIterable<ToolEvent<R>>;
+}
+
+export interface Tool<R = unknown> {
+  name:         string;
+  description:  string;
+  inputSchema:  JSONSchema;
+  /** The call contract as TypeScript source — a {@link ToolContract}`<Result, Params>` (or a union of arms
+   *  for a multi-action tool), *identical in shape* to what a `ToolContracts` augmentation declares. Only a
+   *  tool with **no scannable source** carries this — a `function-tools` function (whose signature supplies
+   *  both halves), and any similarly runtime-defined tool: the host splices it verbatim into the generated
+   *  dts's `ToolContracts`, and derives the wire `params`/`result` text from it. A tool WITH source declares
+   *  its contract as a `ToolContracts` augmentation instead and omits this. Foreign tools (e.g. MCP proxies)
+   *  that have neither fall back to the loose `inputSchema`. */
+  toolContract?: string;
+  executor:     ToolExecutor<R>;
+  pluginName?:  string;
+}