@matatbread/matbot-plugin-api 0.4.12 → 0.4.14

package/package.json

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

package/src/host.ts

@@ -33,6 +33,11 @@ export * from './usage-context.js';
 // The machine half of a context switch: quiescent-edge flushers and the deferred-swap application point.
 export * from './context-switch.js';
 
+// The boot `PermissionGate` a host installs as the base of the swap-member: ask through whatever
+// channel is in scope, else answer the request's own `fallback`. A plugin supplying a *policy* is the
+// author-facing half and needs only the `PermissionGate` type, which the root exports.
+export { askPermissionGate } from './permission-gate.js';
+
 // Hook dispatch implementation. Plugins register hooks through `services.hooks`; only the host constructs
 // the registry that backs it.
 export { HookRegistry } from './hooks.js';

package/src/index.ts

@@ -9,13 +9,14 @@
  */
 
 export type * from './types.js';
-export { CONFIRM_YES, CONFIRM_NO, isTruncatedToolResult } from './types.js';
+export { CONFIRM_YES, CONFIRM_NO, optionValue, optionLabel, isTruncatedToolResult, renderToolCheck, renderToolCheckOmitted } from './types.js';
 
 export * from './base64.js';
 export * from './bytes.js';
 export * from './store-query.js';
 export * from './errors.js';
 export * from './vault.js';
+export * from './provider-patch.js';
 export * from './session.js';
 export * from './invoke-tool.js';
 

package/src/invoke-tool.ts

@@ -1,5 +1,6 @@
 import type { MatbotMachine, MatbotPlugin } from './plugin.js';
-import type { ToolContext, ToolEvent, ToolResultFor, ToolProxy, PromptFn, FormField } from './types.js';
+import type { ToolContext, ToolEvent, ToolResultFor, ToolProxy, PromptFn, FormField, PermissionGate } from './types.js';
+import { askPermissionGate } from './permission-gate.js';
 
 /** The host's plugin hot-load ops, as both the runner and {@link invokeTool} hold them. */
 export interface PluginOps {
@@ -24,6 +25,29 @@ export function bindPluginOps(host: PluginOps, prompt: PromptFn): Pick<ToolConte
   };
 }
 
+/**
+ * Bind {@link ToolContext.gate} for a tool call, qualifying the suffix the tool supplies with the name
+ * it is registered under: `ctx.gate({ gate: 'add', … })` from the `plugin` tool asks `plugin.add`.
+ * Qualifying by TOOL name rather than package is what makes one policy cover both runtimes' versions
+ * of a tool (node's `tool-plugin` and the browser's `plugin-tool` both register `plugin`), and what
+ * stops a plugin addressing a gate it does not own — tool-name collision on `register` is already
+ * resolved, so the name is not something a second plugin can quietly claim.
+ *
+ * `ask` is the RAW per-turn prompt, never a stand-in that answers with a field's default: `undefined`
+ * is how "no human is reachable" reaches the policy, and a substitute would make that undecidable.
+ * `gate` is the registered `PermissionGate`; it is a non-optional service, but a hand-assembled
+ * machine (a test, a minimal embedder) may still have none, so the asking default stands in.
+ */
+export function bindGate(
+  gate:     PermissionGate | undefined,
+  toolName: string,
+  ask:      PromptFn | undefined,
+): Pick<ToolContext, 'gate'> {
+  return {
+    gate: req => (gate ?? askPermissionGate).decide({ ...req, gate: `${toolName}.${req.gate}` }, ask),
+  };
+}
+
 /**
  * Inputs to {@link invokeTool} that a one-shot caller can't derive from the machine. A tool
  * forwarding a call to another tool should pass its own {@link ToolContext} straight through as
@@ -65,6 +89,10 @@ export function invokeTool<K extends string, const P>(
     vault:        machine.Vault,
     prompt,
     ...bindPluginOps(machine, prompt),
+    // The raw `opts.prompt`, not the rejecting stand-in above: a gate must be able to tell "nobody is
+    // here" from "a human answered", and `POST /tools/:name` reaching a privileged tool is exactly the
+    // non-interactive case the request's `fallback` exists to answer.
+    ...bindGate(machine.PermissionGate, name, opts.prompt),
     ...(opts.provider      !== undefined ? { provider:   opts.provider      } : {}),
     ...(machine.workdir    !== undefined ? { workdir:    machine.workdir    } : {}),
     ...(machine.configPath !== undefined ? { configPath: machine.configPath } : {}),

package/src/permission-gate.ts

@@ -0,0 +1,24 @@
+import { CONFIRM_NO, CONFIRM_YES } from './types/messages.js';
+import type { FormField } from './types/messages.js';
+import type { PermissionGate } from './types/permission.js';
+
+/**
+ * The bare asking `PermissionGate`: ask through the channel in scope, and answer `req.fallback` when
+ * there is no channel at all. Nothing stored — no memory, no allowlist, no settings key.
+ *
+ * The floor under a hand-assembled machine (a test, a minimal embedder) and the fallback `bindGate`
+ * uses when a machine carries no policy at all. matbot's own hosts boot something slightly richer:
+ * `@matatbread/matbot-default-gate`'s policy, which is this behaviour plus remembered standing
+ * answers, seeded by the host rather than loaded as a plugin — so a minimal install still has both a
+ * policy and the `gate_action` tool. Whatever a host seeds is what `unregister` reverts to.
+ *
+ * A structured `confirm` field, so rich frontends render real buttons and the affirmative is the
+ * canonical `CONFIRM_YES` token rather than a parse of a rendered (and possibly localised) label.
+ */
+export const askPermissionGate: PermissionGate = {
+  async decide(req, ask) {
+    if (ask === undefined) return req.fallback;
+    const field: FormField = { name: 'confirm', label: req.label, type: 'confirm', default: CONFIRM_NO };
+    return (await ask(field)).trim().toLowerCase() === CONFIRM_YES;
+  },
+};

package/src/plugin.ts

@@ -2,7 +2,7 @@ import type {
   FileStore, MediaStore, Principal, Vault, Message, ModelParameters,
   ProviderAdapter, ProviderConfig, ProviderRegistry, Tool, ToolRegistry, FrontendInfo,
   Store, Session, SystemContextRegistry, KnowledgeIndex, PromptFn, SessionRunner, Usage, HookRegistrar,
-  TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy, UserContent,
+  TypeScriptStripper, ToolTypeIndex, ToolPresenter, SteeringPolicy, UserContent, PermissionGate,
 } from './types.js';
 import type { Notifications, Notifier } from './notify.js';
 
@@ -71,6 +71,21 @@ export interface PluginSettings {
   get<T>(key: string): Promise<T | undefined>;
   set<T>(key: string, value: T): Promise<void>;
   delete(key: string): Promise<void>;
+  /**
+   * Everything in force for this plugin, as one map — layered exactly as {@link get} is: a stored key
+   * wins, else the install's configured default. The only way to answer "what is set?", which a plugin
+   * holding per-key state (a policy's standing answers, a per-item override) otherwise has to answer by
+   * maintaining a second copy of its own keyspace — a duplicate that cannot see a configured default,
+   * drifts when a write and its index-write are interrupted, and reports what was *ever* written
+   * rather than what is set.
+   *
+   * A map rather than key/value tuples, and whole rather than a `keys()`: a settings namespace IS one
+   * document, so the medium hands over the values with the names, and `keys()` + N × `get` would be
+   * N+1 reads of the document this returns in one. Cost is therefore exactly one `get`.
+   *
+   * Scoped like every other method — a plugin enumerates its own namespace and cannot name another's.
+   */
+  entries(): Promise<Record<string, unknown>>;
 }
 
 // ── Plugin identity ─────────────────────────────────────────────────────────────
@@ -125,7 +140,7 @@ export interface PluginSelf {
  * The registry bucket: the swappable, registerable services, keyed by interface name. This is the
  * `keyof` domain of {@link MatbotRuntime.register}/`get`, and the surface third-party plugins augment
  * (`declare module '@matatbread/matbot-plugin-api' { interface MatbotServices { Foo?: Foo } }`). The
- * four swap-members (`StorageBackend`, `KnowledgeIndex`, `Vault`, `Notifier`) carry a host boot default
+ * five swap-members (`StorageBackend`, `KnowledgeIndex`, `Vault`, `Notifier`, `PermissionGate`) carry a host boot default
  * and revert to it when unregistered; an augmented service is optional and simply drops. Read each as
  * a member (`services.KnowledgeIndex`); swap with register().
  */
@@ -139,6 +154,13 @@ export interface MatbotServices {
    *  reference held across a swap keeps resolving to the live backend. Always present (boot default). */
   readonly Vault: Vault;
   readonly KnowledgeIndex: KnowledgeIndex;
+  /** The installation's permission policy — consulted by every privileged call site (`ctx.gate`, and
+   *  core's own tool-collision decision) and also the `register('PermissionGate', impl)` swap key.
+   *  NOT optional: absence is not a sensible state, since the behaviour has to exist. The host boots a
+   *  default that asks the user (or answers `req.fallback` when nobody is reachable), and unregistering
+   *  a policy plugin reverts to it — "unload the policy ⇒ back to asking", for free. See
+   *  {@link PermissionGate}. */
+  readonly PermissionGate: PermissionGate;
   /** The notification bus — every "something changed" fact, one fan-out. Also the `register('Notifier',
    *  impl)` swap key: the host boots an in-process broadcaster, a plugin may swap in a distributed one
    *  (and unloading it reverts to the boot default). Capture-safe behind a proxy. Always present.

package/src/provider-patch.ts

@@ -0,0 +1,33 @@
+import type { ProviderConfig } from './types.js';
+import type { ProviderPatch } from './types/builtin-tools.js';
+
+/**
+ * The `provider update` policy, written once so every implementer of it behaves identically — the same
+ * reasoning as `applyCreateSecret` in `vault.ts`. Two hosts apply this patch (the node `provider` tool
+ * against matbot.yaml, the browser bootstrap against its persisted map) and the *semantics* of a patch
+ * must not be one of the things they differ on: `null` clears a field, absent leaves it alone.
+ *
+ * `parameters` is replaced wholesale rather than merged per key. Its values are forwarded to the
+ * endpoint unmodified and so have no shape to merge against — and `provider list` reports them in full,
+ * which is what makes a read-modify-write something a caller can actually carry out. (Contrast
+ * `default_settings`, which merges per key: there the keys are matbot's own.)
+ *
+ * `credentials` and `module` are absent from `ProviderPatch` and therefore ride through untouched; see
+ * that type for why neither belongs in an update.
+ */
+export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch): ProviderConfig {
+  const next: ProviderConfig = { ...cur };
+  // Spelled out per field rather than looped: `exactOptionalPropertyTypes` makes "assign, or delete if
+  // null" a different statement for each type, and a loop only reaches them through a cast that would
+  // stop the compiler checking the one thing worth checking here.
+  if (patch.model      !== undefined) next.model = patch.model;
+  if (patch.endpoint   !== undefined) { if (patch.endpoint   === null) delete next.endpoint;   else next.endpoint   = patch.endpoint;   }
+  if (patch.parameters !== undefined) { if (patch.parameters === null) delete next.parameters; else next.parameters = patch.parameters; }
+  if (patch.maxRounds  !== undefined) { if (patch.maxRounds  === null) delete next.maxRounds;  else next.maxRounds  = patch.maxRounds;  }
+  return next;
+}
+
+/** The fields a patch actually changes, in a stable order — for a confirmation prompt or a result message. */
+export function patchedFields(patch: ProviderPatch): readonly ('model' | 'endpoint' | 'parameters' | 'maxRounds')[] {
+  return (['model', 'endpoint', 'parameters', 'maxRounds'] as const).filter(f => patch[f] !== undefined);
+}

package/src/types/builtin-tools.ts

@@ -174,6 +174,31 @@ export interface ProviderActionResult {
   message: string;
 }
 
+/**
+ * The fields `provider update` can change on an existing profile, and the whole of them.
+ *
+ * `null` clears a field, absent leaves it alone — `undefined` cannot mean "clear", since it is already
+ * what an unsupplied optional looks like. `model` takes no `null`: a profile without one is unrunnable.
+ *
+ * Two fields are deliberately absent. **`credentials`**, because it is the one member of a profile that
+ * `provider list` does not report back (it projects to `hasCredentials`, and a secret must not ride the
+ * transcript) — so a caller cannot read-modify-write it, and an `update` that accepted it would have to
+ * guess between rewriting a `${NAME}` reference and replacing a literal. Credentials are
+ * `plugin store-key`'s, which addresses the vault name directly. And **`module`**, because changing the
+ * adapter re-opens every resolution question `add` answers (is it loaded, does it resolve by package
+ * name, is it even a provider adapter); `remove` + `add` is the honest route for that.
+ *
+ * A named shape rather than an inline arm because the browser's `ProviderAdmin.update` takes the same
+ * patch, and because it is the augmentable half — a host whose profiles carry an extra field adds it
+ * here without touching `ToolContracts`.
+ */
+export interface ProviderPatch {
+  model?:      string;
+  endpoint?:   string | null;
+  parameters?: ModelParameters | null;
+  maxRounds?:  number | null;
+}
+
 /**
  * The `provider` tool's contract. Both implementations declare `provider: ProviderToolContract`.
  *
@@ -181,6 +206,8 @@ export interface ProviderActionResult {
  * supplies its own, while node's executor requires one; `credentialKey`/`credentialEnvVar` name where
  * node's vault should hold the secret, and the browser (which prompts and stores under its own key)
  * ignores them.
+ *
+ * `update` carries no credential of any kind — see {@link ProviderPatch}.
  */
 export type ProviderToolContract =
   | ToolContract<ProviderListResult,   { action: 'list' }>
@@ -195,4 +222,5 @@ export type ProviderToolContract =
       parameters?:       ModelParameters;
       maxRounds?:        number;
     }>
+  | ToolContract<ProviderActionResult, { action: 'update'; name: string } & ProviderPatch>
   | ToolContract<ProviderActionResult, { action: 'remove'; name: string }>;

package/src/types/messages.ts

@@ -95,15 +95,44 @@ export type Marker<K extends string = string> = {
   data:    K extends keyof MarkerData ? MarkerData[K] : unknown;
 };
 
+/**
+ * One choice in a `select`. A bare string is the ordinary form and means "the value IS the label";
+ * the pair form separates what the user *reads* from what the caller gets *back*.
+ *
+ * That separation exists because a rendered label is a cosmetic, host-specific, potentially localised
+ * string, and using it as an identity is a footgun with a proven bite: the permission gate offered
+ * *Allow* and *Always allow "…"*, and matching an answer against prose read the first as the second —
+ * granting standing permission nobody gave. `confirm` already avoided this with {@link CONFIRM_YES} /
+ * {@link CONFIRM_NO}, which are tokens rather than labels; this is the same medicine for `select`.
+ *
+ * A caller that BRANCHES on the answer should use the pair form and compare values. A caller whose
+ * options are themselves the answer — `ask_user`, where the options are the user's own words and
+ * `allowOther` free text arrives on the same channel — keeps bare strings, which is why the string
+ * form is not deprecated.
+ *
+ * Frontends: render {@link optionLabel}, return {@link optionValue}. `default` is matched against the
+ * VALUE, so a default survives a reworded label.
+ */
+export type FormOption = string | { value: string; label: string };
+
+/** The token a picked option resolves to — what a caller branches on. */
+export const optionValue = (option: FormOption): string => typeof option === 'string' ? option : option.value;
+
+/** What the user reads. Never compared against — see {@link FormOption}. */
+export const optionLabel = (option: FormOption): string => typeof option === 'string' ? option : option.label;
+
 export interface FormField {
   name:        string;
   label:       string;
   type:        'text' | 'password' | 'select' | 'confirm';
-  options?:    string[];
+  /** select-only: the choices. See {@link FormOption} — a bare string means value === label. */
+  options?:    FormOption[];
   /** 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. */
+   *  callers never learn whether the answer was a preset or free text (which is why a picked option
+   *  resolves to a string, never an index). Ignored for other types. */
   allowOther?: boolean;
+  /** select: matched against an option's VALUE, not its label. */
   default?:    string;
   required?:   boolean;
   /** Presentation hint only (default true): whether the frontend offers a cancel affordance (the

package/src/types/permission.ts

@@ -0,0 +1,46 @@
+import type { PromptFn } from './tools.js';
+
+/**
+ * A privileged operation asking to proceed. Boolean by construction: every gate in the system is
+ * allow-or-not, because the *value*-returning prompts (a secret, an API key, `ask_user`) never reach
+ * a gate at all — they stay on `ctx.prompt`. Authorization and elicitation are different channels,
+ * which is what keeps this shape from growing a routing layer.
+ */
+export interface PermissionRequest {
+  /** Qualified gate id — a small, documented vocabulary (`plugin.add`, `tools.overwrite`). A tool
+   *  supplies the SUFFIX only (`'add'`); {@link ToolContext.gate} qualifies it with the tool's
+   *  registered name, so a plugin cannot address a gate it does not own, and tool-name collision on
+   *  `register` closes the impersonation route. The host reserves `tools.*` for core's own gates.
+   *  Open at runtime: a plugin this build never compiled against contributes ids, so a policy must
+   *  treat an id it does not recognise as "ask", never as "allow". */
+  gate:     string;
+  /** What the operation acts on: a tool name, a plugin specifier, a provider profile, an MCP server.
+   *  The identifier a policy keys its memory or its delegation on — never folded into `gate`, which
+   *  would make the vocabulary unbounded and "unknown gate ⇒ ask" unwritable. It is the identifier
+   *  the call site *has*, not a canonical identity: at `plugin.add` the plugin is not loaded, so the
+   *  subject is the specifier **as typed**, and a remembered allow for `@x/foo` will not match
+   *  `https://…/foo.ts` (different trust root, different decision). */
+  subject:  string;
+  /** Host- or tool-authored prose naming the specific act. The gate renders it; it never rewrites it. */
+  label:    string;
+  /** What this site does when nothing can be asked and nothing decides — today's non-interactive
+   *  behaviour, stated once per site instead of implied at each. */
+  fallback: boolean;
+}
+
+/**
+ * Decides whether a privileged operation may proceed. A swap-member of `MatbotServices`: the host
+ * installs a boot default (ask if a channel exists, else `req.fallback`), a plugin may replace it,
+ * and `unregister` reverts to the host's — so unloading a policy plugin means "back to asking" with
+ * no revert rule of its own.
+ *
+ * `ask` is the channel in scope for THIS call — the turn's `PromptFn`, or core's registration-path
+ * one — passed per call rather than held, because it is per-turn and frontend-owned. `undefined`
+ * means **no human is reachable**; a policy that wants to behave differently then simply checks it.
+ *
+ * A gate that wants "my rules, else the previous behaviour" captures the gate it displaces and
+ * delegates to it (the `ToolCallValidator` idiom), so a pair composes in either load order.
+ */
+export interface PermissionGate {
+  decide(req: PermissionRequest, ask: PromptFn | undefined): Promise<boolean>;
+}

package/src/types/tools.ts

@@ -2,6 +2,7 @@ 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 { PermissionRequest } from './permission.js';
 import type { Vault } from './vault.js';
 
 // ── Tools ─────────────────────────────────────────────────────────────────────
@@ -213,6 +214,17 @@ export interface ToolContext {
   files?:      FileStore;
   /** Prompt the user for input. The host provides a readline or form implementation. */
   prompt:      PromptFn;
+  /**
+   * Ask permission for a privileged operation — install a plugin, remove a provider profile, add an
+   * MCP server. Resolves `true` to proceed. The call site declares *that* acceptance is needed; the
+   * registered {@link PermissionGate} decides *how* it is obtained (the default asks the user).
+   *
+   * `gate` is the SUFFIX (`'add'`): the host qualifies it with this tool's registered name, so one
+   * policy covers both runtimes' implementations of a tool (node's `plugin` and the browser's) and a
+   * plugin cannot address a gate it does not own. `fallback` is what happens when no human is
+   * reachable and no policy decides.
+   */
+  gate(req: PermissionRequest): Promise<boolean>;
   /** 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. */

package/src/types/typescript.ts

@@ -17,6 +17,89 @@ export interface TypeScriptStripper {
   strip(source: string): string | Promise<string>;
 }
 
+/**
+ * One finding from {@link ToolTypeIndex.check} — the record, not a rendering of it.
+ *
+ * `rendered` travels WITH the record rather than being left for the consumer to rebuild: the annotated
+ * form (caret-anchored frame, related locations, a directed hint) is the thing a model repairs from,
+ * and the renderer lives behind the service. So a consumer displays `rendered` and counts, groups or
+ * routes on the fields — instead of regexing `line \d+ TS\d+` back out of prose, which is what the
+ * flattened `string[]` made every consumer do.
+ */
+export interface ToolCheckDiagnostic {
+  /** The rule's one name, in every renderer: `TS2339`, or `CAST-GATE` for a structural cast-gate finding. */
+  label:    string;
+  /** The numeric code. Cast-gate findings use a private 9000x range — read {@link syn}, not the number. */
+  code:     number;
+  message:  string;
+  file?:    string;
+  line?:    number;
+  col?:     number;
+  /** Caret-anchored source frame. */
+  frame?:   string;
+  related?: string[];
+  hint?:    string;
+  /** A structural cast-gate finding (a rule of this harness) rather than a `tsc` error. */
+  syn?:     true;
+  /** The annotated block for display: message, frame, related locations and hint. */
+  rendered: string;
+}
+
+/**
+ * The outcome of a {@link ToolTypeIndex.check}. `ok` is `total === 0`.
+ *
+ * Detail is capped, because a cascade of errors must not become the bulk of a turn's context — but the
+ * cap is expressed as data, not smuggled in as a prose element of the findings array. It was appended as
+ * one: `diagnostics.length` then counted a summary line as a finding, and any per-code breakdown derived
+ * by iterating the array was wrong wherever an overflow had occurred.
+ */
+export interface ToolCheckReport {
+  ok:           boolean;
+  /**
+   * Whether a check actually RAN. It qualifies `ok`: `ok: true` with `checked: false` means nothing was
+   * examined, not that the source is sound — an index that cannot type-check (the browser, which has no
+   * TypeScript program) reports exactly that.
+   *
+   * Required, not optional, because the alternative is the failure this whole path is built to avoid: a
+   * checker that reports success while checking nothing is indistinguishable from one that works, and a
+   * caller recording "verified" off the back of it records something false.
+   */
+  checked:      boolean;
+  /** Every finding, including those not detailed below — the number to report. */
+  total:        number;
+  /** The detailed findings, capped. */
+  diagnostics:  ToolCheckDiagnostic[];
+  /** Present only when the cap hid some, tallied by the same `label` the detailed ones carry. */
+  omitted?:     { count: number; byLabel: Record<string, number> };
+}
+
+/**
+ * A {@link ToolCheckReport} as the text an author — usually a model repairing its own code — reads:
+ * each finding's annotated block, then the overflow summary as a TRAILING LINE.
+ *
+ * Here rather than in the checker because two packages render one report: the node checker that
+ * produces it, and any consumer that must put it in front of whoever wrote the code. The overflow line
+ * is the reason it is worth sharing at all — appending it to the findings ARRAY instead is exactly the
+ * bug this shape exists to prevent, and one renderer is one place for that to stay true.
+ */
+export function renderToolCheck(report: ToolCheckReport): string {
+  const parts = report.diagnostics.map(d => d.rendered);
+  if (report.omitted !== undefined) parts.push(renderToolCheckOmitted(report.omitted));
+  return parts.join('\n');
+}
+
+/** The overflow summary alone — one line, for a consumer laying the findings out itself. Separate so it
+ *  can be had without rendering every finding in order to keep the last line of the result. */
+export function renderToolCheckOmitted(omitted: NonNullable<ToolCheckReport['omitted']>): string {
+  const tally = Object.entries(omitted.byLabel).map(([l, n]) => `${l}×${n}`).join(', ');
+  // The cascade advice is about tsc's own errors: a cast-gate finding is a structural rule fired at one
+  // site, cascades from nothing, and inviting a reader to expect it to vanish with the first fix is what
+  // would get it ignored.
+  const cascade = Object.keys(omitted.byLabel).some(l => l.startsWith('TS'))
+    ? ' — likely cascading from the errors above.' : '';
+  return `…plus ${omitted.count} more: ${tally}${cascade}`;
+}
+
 /**
  * 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
@@ -38,9 +121,9 @@ export interface ToolTypeIndex {
   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
+   *  params) is in scope. Returns a {@link ToolCheckReport} whose positions are snippet-relative. A
    *  composer uses it to catch bad tool-call code before running/registering it. */
-  check(snippet: string): Promise<string[]>;
+  check(snippet: string): Promise<ToolCheckReport>;
   /** 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

package/src/types.ts

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