@matatbread/matbot-plugin-api 0.3.7 → 0.4.0

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

package/src/types/typescript.ts

@@ -0,0 +1,50 @@
+// ── TypeScript ──────────────────────────────────────────────────────────────
+
+/**
+ * Erases TypeScript types from a source string, returning runnable JavaScript. Type-stripping is
+ * foundational — the harness ships raw `.ts` and any code compiled at runtime must have its types
+ * removed before it can execute — so every execution environment provides one, and it lives as a fixed
+ * runtime capability (on {@link MatbotRuntime}) the host supplies per platform, not a swappable service:
+ * node uses its built-in `stripTypeScriptTypes`, the browser bundle uses sucrase. A consumer that
+ * compiles source at runtime (e.g. `tool_function`) calls this instead of importing a platform stripper.
+ *
+ * `strip` may be async: a platform whose stripper loads lazily (the browser fetches sucrase on first use)
+ * returns a promise; a synchronous stripper (node) returns the string directly — callers `await` either.
+ * It is type-erasure, not full transpilation: node's stripper is erasable-only (enums/namespaces throw),
+ * sucrase is more permissive, so authors should keep to erasable TypeScript to stay portable.
+ */
+export interface TypeScriptStripper {
+  strip(source: string): string | Promise<string>;
+}
+
+/**
+ * Optional, node-only developer-experience service: the live `.d.ts` of the types the loaded tools
+ * expose — what `toolResult(invokeTool(…, name, …))`, or a `function-tools` `await tool.name(…)`, resolves
+ * to — derived by compiling each loaded plugin's `declare module '@matatbread/matbot-plugin-api'`
+ * augmentations. The runtime registry can't supply this (result types are erased); only a TypeScript
+ * program reading the source can. Consumers that generate or compose tool-calling code use it so the model
+ * isn't guessing return shapes. Absent where no TypeScript program can run (the browser today) — a consumer
+ * must degrade (guess-and-run) when `services.ToolTypeIndex` is undefined.
+ *
+ * The result is rebuilt lazily and cached, invalidated when the tool set changes. Tools the source scan
+ * can't reach (a `function-tools` function) contribute their types by declaring a `toolContract` string on
+ * their registered {@link Tool} — identical in shape to a `ToolContracts` arm; the index splices it off the
+ * live registry, so no separate registration step is needed.
+ */
+export interface ToolTypeIndex {
+  /** Self-contained type declarations as a `.d.ts` string: the source-derived `ToolContracts` augmentations
+   *  merged with the arms of every other live tool, plus `declare const tool: ToolProxy` — the overloaded
+   *  proxy a generator writes `await tool.x(params)` against. */
+  dts(): Promise<string>;
+  /** Type-check a TypeScript `snippet` against exactly the {@link dts} above — the `tool` proxy ({@link
+   *  ToolProxy}: each multi-action tool an overload set, so `await tool.x(params)` narrows its result by the
+   *  params) is in scope. Returns human-readable diagnostics scoped to the snippet ([] means clean). A
+   *  composer uses it to catch bad tool-call code before running/registering it. */
+  check(snippet: string): Promise<string[]>;
+  /** Per live tool (that has a contract): the `params`/`result` wire text, flattened from the one contract —
+   *  a source tool's `ToolContracts` arms (via the source scan) or a source-less tool's `toolContract` string.
+   *  The single contract is thus also the source of the wire description; the host folds this into the
+   *  outgoing tool descriptions at the turn's dispatch edge. A tool with only a loose `inputSchema` (no
+   *  contract) is absent. */
+  wireContracts(): Promise<Record<string, { params: string; result: string }>>;
+}

package/src/types/vault.ts

@@ -0,0 +1,37 @@
+// ── Vault ─────────────────────────────────────────────────────────────────────
+
+/**
+ * The primitives a vault backend must implement. Resolution, redaction, and the three
+ * low-level store operations the smart `createSecret` policy composes. A backend implements
+ * `Vault` (which is `VaultSpec` plus that policy); plugins are handed a `Vault`.
+ */
+export interface VaultSpec {
+  /** Resolve ${NAME} placeholders by looking up the named value; throws MissingSecretError for any miss. */
+  resolve(ref: string): Promise<string>;
+  scrub(text: string): string;
+  /**
+   * Store `value` under exactly `name`, overwriting. The literal write; no reference/dedup logic.
+   * An empty `value` removes the key instead — there is no such thing as an empty secret, so the
+   * empty string is the removal signal (idempotent: removing an absent name is a no-op).
+   */
+  writeSecret(name: string, value: string): Promise<void>;
+  /** Whether a secret is stored under this exact name. */
+  hasKey(name: string): boolean;
+  /**
+   * The name a value is already stored under, if any. Optional: backends that can't (or won't)
+   * reverse-index omit it, and `createSecret`'s dedup step is skipped.
+   */
+  findByValue?(value: string): string | undefined;
+}
+
+export interface Vault extends VaultSpec {
+  /**
+   * Store a secret coming (often) from a user via the LLM, where we cannot tell a real value
+   * from a key name they typed by mistake. Returns the key name callers MUST reference — not
+   * necessarily the `name` requested:
+   *   - `value` is already a known key name → returns `value` (it was a reference, not a secret)
+   *   - `value` already stored under another name → returns that name (dedup)
+   *   - otherwise → writes under `name` and returns `name`
+   */
+  createSecret(name: string, value: string): Promise<string>;
+}