@matatbread/matbot-plugin-api 0.4.20 → 0.4.21

package/package.json

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

package/src/contract-arms.ts

@@ -0,0 +1,44 @@
+// The `ToolContracts` arms for tools that carry their contract as a `toolContract` STRING, written out for a
+// file that declares them: the generated dts a body is checked against, the program that types them for
+// validation, a turn's own tools appended to a snippet. One implementation, because each of those must agree
+// on what a string means, and a fourth copy of the namespace rule would drift from the other three.
+//
+// A string may name types that exist nowhere else — a function package's own `interface HubReport`, carried
+// on `toolContractTypes`. Those are declared in a namespace of their own with an alias per tool beside them,
+// so the contract is written exactly as its author wrote it and still resolves, and two packages' `Report`s
+// never meet. Tools carrying identical declarations (one package's exports) share one namespace.
+
+const IDENTIFIER = /^[A-Za-z_$][\w$]*$/;
+
+export interface ContractSource {
+  readonly name:      string;
+  readonly contract:  string;
+  readonly types?:    string | undefined;
+}
+
+export interface ContractArms {
+  /** Top-level declarations to place ahead of the `ToolContracts` augmentation; empty when nothing has types. */
+  readonly preamble:   string;
+  /** Per tool, the type to write as its `ToolContracts` arm: its own string, or the alias that wraps it. */
+  readonly arms:       ReadonlyMap<string, string>;
+  /** Per namespace in the preamble, the tools it serves — what a diagnostic inside it is attributed to. */
+  readonly namespaces: ReadonlyMap<string, readonly string[]>;
+}
+
+export function contractArms(tools: Iterable<ContractSource>): ContractArms {
+  const arms = new Map<string, string>();
+  const groups = new Map<string, { ns: string; members: [alias: string, tool: string, contract: string][] }>();
+  for (const t of tools) {
+    if (t.types === undefined || t.types.trim() === '') { arms.set(t.name, t.contract); continue; }
+    let group = groups.get(t.types);
+    if (group === undefined) { group = { ns: `ToolContractTypes${groups.size + 1}`, members: [] }; groups.set(t.types, group); }
+    const alias = IDENTIFIER.test(t.name) ? t.name : `Tool${group.members.length + 1}`;
+    group.members.push([alias, t.name, t.contract]);
+    arms.set(t.name, `${group.ns}.${alias}`);
+  }
+  const preamble = [...groups].map(([types, g]) =>
+    `declare namespace ${g.ns} {\n${types.split('\n').map(l => `  ${l}`).join('\n')}\n`
+    + g.members.map(([alias, , contract]) => `  export type ${alias} = ${contract};`).join('\n') + '\n}\n').join('');
+  const namespaces = new Map([...groups.values()].map(g => [g.ns, g.members.map(([, tool]) => tool)] as const));
+  return { preamble, arms, namespaces };
+}

package/src/fetch-origin.ts

@@ -0,0 +1,58 @@
+// `fetch`, with every URL a request reaches — the one asked for and each one a redirect leads to — put to
+// `admit` before anything is sent there. A gate on the first URL alone is a gate on nothing: an approved
+// host that answers 302 hands the request, and whatever it carries, to an origin nobody was asked about.
+//
+// So a `follow` request (the default) is followed here, one hop at a time, as the platform would: 303, and
+// 301/302 after a POST, become a bodiless GET; 307/308 resend the body; credentials are dropped on a change
+// of origin; twenty hops at most. What is lost is cosmetic: the final `Response` reports the last hop's URL
+// and `redirected: false`. A `manual` or `error` request is one hop, admitted and handed to `fetch` as is.
+//
+// A browser's `manual` redirect is opaque, with no Location to read, so there it is refused rather than
+// followed blind.
+
+const MAX_REDIRECTS = 20;
+const REDIRECTS = new Set([301, 302, 303, 307, 308]);
+const BODY_HEADERS = ['content-type', 'content-length', 'content-encoding', 'content-language', 'content-location'];
+const CREDENTIAL_HEADERS = ['authorization', 'cookie', 'proxy-authorization'];
+
+export async function originGatedFetch(
+  admit: (url: URL) => Promise<void>,
+  input: RequestInfo | URL,
+  init?: RequestInit,
+  fetchImpl: typeof fetch = fetch,
+): Promise<Response> {
+  const first = new Request(input, init);
+  await admit(new URL(first.url));
+  if (first.redirect !== 'follow') return fetchImpl(first);
+
+  // Read once, up front: a Request body is a stream, and a 307 or 308 sends it again.
+  const payload = first.body === null ? null : await first.clone().arrayBuffer();
+  let current = first;
+  let res = await fetchImpl(first, { redirect: 'manual' });
+  for (let hops = 0; ; hops++) {
+    if (res.type === 'opaqueredirect') {
+      throw new TypeError(`A redirect from ${current.url} was not followed: this platform does not say where it leads. Request the destination directly.`);
+    }
+    const location = res.headers.get('location');
+    if (!REDIRECTS.has(res.status) || location === null) return res;
+    if (hops >= MAX_REDIRECTS) throw new TypeError(`Too many redirects from ${first.url}.`);
+    await res.body?.cancel();
+
+    const next = new URL(location, current.url);
+    const toGet = (res.status === 303 && current.method !== 'HEAD')
+               || ((res.status === 301 || res.status === 302) && current.method === 'POST');
+    const headers = new Headers(current.headers);
+    if (toGet) for (const h of BODY_HEADERS) headers.delete(h);
+    if (next.origin !== new URL(current.url).origin) for (const h of CREDENTIAL_HEADERS) headers.delete(h);
+
+    await admit(next);
+    current = new Request(next, {
+      method:   toGet ? 'GET' : current.method,
+      headers,
+      body:     toGet ? null : payload,
+      signal:   first.signal,
+      redirect: 'manual',
+    });
+    res = await fetchImpl(current);
+  }
+}

package/src/hooks.ts

@@ -1,6 +1,7 @@
 import type {
   Hook, HookPoint, HookRegistrar, Message, MessageContent, Session, DeferredScreen, TurnToolSource,
   ScreenContext, ContributeContext, ToolCallContext, ToolCallResult, ToolResultContext, FollowupContext,
+  ValidateContext, ToolInputError,
 } from './types.js';
 import { foldOntoUserTurn, createMessage } from './session.js';
 import { withUsageSite } from './usage-context.js';
@@ -192,6 +193,24 @@ export class HookRegistry implements HookRegistrar {
     return {};
   }
 
+  // validate asks EVERY hook — no short-circuit — so neither the verdict nor the message depends on which
+  // validator happened to load first: refused if any refuses, with every refusal's errors (a field two
+  // validators both reject is said once). `[]` from any is "valid"; `undefined` from all is no opinion.
+  async runValidate(ctx: Omit<ValidateContext, 'removeHook'>): Promise<ToolInputError[] | undefined> {
+    let opinion: ToolInputError[] | undefined;
+    const seen = new Set<string>();
+    for (const hook of this.on('validate')) {
+      const r = await this.invoke(hook, ctx.signal, () => hook.handler({ ...ctx, removeHook: () => this.removeOne('validate', hook) }));
+      if (!r) continue;
+      opinion ??= [];
+      for (const e of r) {
+        const key = `${e.path}\0${e.message}`;
+        if (!seen.has(key)) { seen.add(key); opinion.push(e); }
+      }
+    }
+    return opinion;
+  }
+
   // toolresult folds the tool result through each hook — a transform pipeline (redaction, truncation);
   // a hook that returns nothing just observes (auditing). Returns the final result.
   async runToolResult(ctx: Omit<ToolResultContext, 'removeHook'>): Promise<unknown> {

package/src/index.ts

@@ -17,8 +17,11 @@ export * from './store-query.js';
 export * from './errors.js';
 export * from './vault.js';
 export * from './provider-patch.js';
+export * from './provider-models.js';
 export * from './session.js';
 export * from './invoke-tool.js';
+export * from './fetch-origin.js';
+export * from './contract-arms.js';
 
 // The plugin half of the machine: MatbotPlugin/MatbotServices/MatbotRuntime, the mount-table *consumer*
 // contract, and the API version a plugin declares. Host assembly is in ./host-machine.ts.

package/src/invoke-tool.ts

@@ -58,11 +58,31 @@ export function bindGate(
           && (owner === undefined || tools?.resolve(namespace)?.pluginName !== owner)) {
         throw new Error(`Tool "${name}" cannot ask permission under "${namespace}": a gate namespace must be a tool registered by the same plugin.`);
       }
-      return (gate ?? askPermissionGate).decide({ ...req, gate: `${namespace ?? name}.${req.gate}` }, ask);
+      const qualified = { ...req, gate: `${namespace ?? name}.${req.gate}` };
+      const decision = await (gate ?? askPermissionGate).decide(qualified, ask);
+      if (!decision.allowed && decision.source === 'fallback') reportUnattended(name, qualified.gate, qualified.subject);
+      return decision;
     },
   };
 }
 
+// When nobody can be asked (a background job, a trigger, `POST /tools/:name`), a gate refuses, and the model
+// is told so. Nobody else would be: the operation simply did not happen, in a process nobody is watching. So
+// it is logged, naming what a standing answer would have to say to allow it. At error level, because a
+// background job's process keeps only errors (its output is its result); and at most once an hour per gate
+// and subject, because a dashboard polling a gated tool would otherwise log every poll.
+const UNATTENDED_REPORT_MS = 60 * 60 * 1000;
+const unattendedReported = new Map<string, number>();
+function reportUnattended(tool: string, gate: string, subject: string): void {
+  const key = `${gate}\0${subject}`;
+  const now = Date.now();
+  if (now - (unattendedReported.get(key) ?? -Infinity) < UNATTENDED_REPORT_MS) return;
+  unattendedReported.set(key, now);
+  console.error(`[gate] Refused ${gate} for "${subject}" (tool ${tool}): nobody was there to ask. ` +
+                `To allow it unattended, give a standing answer for that gate and subject (e.g. answer "Always" ` +
+                `when it is next asked in the UI, or configure the permission policy).`);
+}
+
 /**
  * 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

package/src/provider-models.ts

@@ -0,0 +1,106 @@
+import type { ProviderAdapter, ProviderConfig } from './types.js';
+import type { Vault } from './types/vault.js';
+
+export const MODEL_LIST_TIMEOUT_MS = 8_000;
+
+export type ModelCheck =
+  | { kind: 'listed' }
+  | { kind: 'unlisted'; count: number; closest: string[] }
+  /** Nothing could be compared: no `models`, a missing key, a refusal, a timeout, an empty list. */
+  | { kind: 'unchecked'; reason: string };
+
+/**
+ * Whether `model` is one the endpoint lists. Not exact equality, because an endpoint accepts more names
+ * than it lists: Anthropic an undated alias of a dated id (`claude-sonnet-4-5` for
+ * `claude-sonnet-4-5-20250929`) and a `-latest` one, Ollama a bare name for its `:latest` tag. Gemini's
+ * lists say `models/<id>`, which either spelling of the model matches.
+ */
+export function modelListed(model: string, ids: readonly string[]): boolean {
+  const m = model.replace(/^models\//, '');
+  return ids.some(raw => {
+    const id = raw.replace(/^models\//, '');
+    return id === m || id === `${m}:latest`
+      || (id.startsWith(`${m}-`) && /^\d{8}$/.test(id.slice(m.length + 1)))
+      || (m.endsWith('-latest') && id.startsWith(m.slice(0, -'latest'.length)));
+  });
+}
+
+function editDistance(a: string, b: string): number {
+  let prev = Array.from({ length: b.length + 1 }, (_, j) => j);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j]! + 1, row[j - 1]! + 1, prev[j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = row;
+  }
+  return prev[b.length]!;
+}
+
+/**
+ * The ids nearest `id`, best first. Shared name segments (family, size, quantisation) find a model's
+ * siblings from a partial name (`qwen3-4b`, `sonnet-4-6`); a spelling within two edits of an id comes
+ * ahead of them all, being what a typo looks like.
+ */
+export function closestIds(id: string, ids: readonly string[], n = 5): string[] {
+  const parts = (s: string): string[] => s.toLowerCase().split(/[-_.:/\s]+/).filter(Boolean);
+  const want = parts(id);
+  return ids
+    .map(candidate => {
+      const have  = parts(candidate);
+      const score = want.filter(w => have.some(h => h === w)).length * 2
+        + want.filter(w => have.some(h => h !== w && (h.includes(w) || w.includes(h)))).length;
+      return { id: candidate, score, dist: editDistance(id.toLowerCase(), candidate.toLowerCase()) };
+    })
+    .filter(x => x.score > 0 || x.dist <= 2)
+    .sort((a, b) => Number(a.dist > 2) - Number(b.dist > 2) || b.score - a.score || a.dist - b.dist || a.id.localeCompare(b.id))
+    .slice(0, n)
+    .map(x => x.id);
+}
+
+/**
+ * Asks the endpoint which models it serves and compares `config.model` against them, so a typo is caught
+ * where it is made rather than as a 404 on the next turn. Listing SENDS the profile's credential, so a
+ * caller asks only once that credential may go to `config.endpoint` — the same exposure the profile's
+ * own first turn has.
+ *
+ * Never throws, and `unchecked` is not a failure: most endpoints that cannot list (a gateway, a key not
+ * yet stored, a server with no `/models`) still serve the model fine.
+ */
+export async function checkProviderModel(
+  adapter:   Pick<ProviderAdapter, 'models'>,
+  config:    ProviderConfig,
+  vault:     Pick<Vault, 'resolve'>,
+  timeoutMs: number = MODEL_LIST_TIMEOUT_MS,
+): Promise<ModelCheck> {
+  if (adapter.models === undefined) return { kind: 'unchecked', reason: 'the adapter cannot list its models' };
+  let resolved: ProviderConfig;
+  try {
+    const credentials: Record<string, string> = {};
+    for (const [k, v] of Object.entries(config.credentials ?? {})) credentials[k] = await vault.resolve(v);
+    resolved = {
+      ...config,
+      ...(config.credentials !== undefined ? { credentials } : {}),
+      ...(config.endpoint    !== undefined ? { endpoint: await vault.resolve(config.endpoint) } : {}),
+    };
+  } catch (e) {
+    return { kind: 'unchecked', reason: e instanceof Error ? e.message : String(e) };
+  }
+
+  const signal = AbortSignal.timeout(timeoutMs);
+  let ids: readonly string[];
+  try {
+    // Raced as well as signalled: an adapter may ignore the signal, and a hung list must not hold up the tool.
+    ids = await Promise.race([
+      adapter.models(resolved, signal),
+      new Promise<never>((_, reject) => signal.addEventListener('abort', () => reject(new Error(`no answer within ${timeoutMs / 1000}s`)), { once: true })),
+    ]);
+  } catch (e) {
+    // An endpoint's error body is often pretty-printed JSON; the reason is shown on one line.
+    const why = (e instanceof Error ? e.message : String(e)).replace(/\s+/g, ' ');
+    return { kind: 'unchecked', reason: why.length > 200 ? `${why.slice(0, 200)}…` : why };
+  }
+  if (ids.length === 0) return { kind: 'unchecked', reason: 'the endpoint listed no models' };
+  if (modelListed(config.model, ids)) return { kind: 'listed' };
+  return { kind: 'unlisted', count: ids.length, closest: closestIds(config.model, ids) };
+}

package/src/provider-patch.ts

@@ -1,5 +1,11 @@
 import type { ProviderConfig } from './types.js';
 import type { ProviderPatch } from './types/builtin-tools.js';
+import type { VaultSpec } from './types/vault.js';
+
+/** The vault key a profile's own credential is stored under by default: `MATBOT_API_KEY_<PROFILE>`. */
+export function credentialKeyName(profile: string): string {
+  return `MATBOT_API_KEY_${profile.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+}
 
 /**
  * The `provider update` policy, written once so every implementer of it behaves identically — the same
@@ -12,10 +18,16 @@ import type { ProviderPatch } from './types/builtin-tools.js';
  * 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.
+ * `credentials` and `module` are absent from `ProviderPatch`; see that type for why neither belongs in an
+ * update. `module` rides through untouched. `credentials` does too — unless the endpoint now names another
+ * ORIGIN (scheme, host and port; clearing it back to the adapter's default counts), because the credential
+ * is sent wherever the endpoint points: an endpoint change was a way to post the key to any host at all,
+ * with the update's own prompt never mentioning it. So the profile is pointed at fresh vault keys instead,
+ * none of which exists yet, and whoever means it to have a credential there supplies one out of band
+ * (`plugin store-key`). The old keys stay in the vault, since another profile may share them.
+ * {@link movedCredentialKeys} names the new ones.
  */
-export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch): ProviderConfig {
+export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch, vault: Pick<VaultSpec, 'hasKey'>): 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
@@ -24,9 +36,34 @@ export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch): P
   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;  }
+  if (cur.credentials !== undefined && originOf(cur.endpoint) !== originOf(next.endpoint)) {
+    const base = credentialKeyName(cur.name);
+    const taken = new Set<string>();
+    const fresh: Record<string, string> = {};
+    for (const field of Object.keys(cur.credentials)) {
+      const stem = field === 'apiKey' ? base : `${base}_${field.toUpperCase().replace(/[^A-Z0-9]/g, '_')}`;
+      let key = stem;
+      for (let n = 2; vault.hasKey(key) || taken.has(key); n++) key = `${stem}_${n}`;
+      taken.add(key);
+      fresh[field] = `\${${key}}`;
+    }
+    next.credentials = fresh;
+  }
   return next;
 }
 
+/** The vault keys a patched profile now reads its credential from, where {@link applyProviderPatch} took
+ *  it off because the endpoint moved origin; empty when it did not. */
+export function movedCredentialKeys(cur: ProviderConfig, next: ProviderConfig): readonly string[] {
+  if (cur.credentials === next.credentials || next.credentials === undefined) return [];
+  return Object.values(next.credentials).map(v => v.slice(2, -1));
+}
+
+// An endpoint that is not a URL is compared as written: nothing can say it is the same place.
+function originOf(endpoint: string | undefined): string | undefined {
+  return endpoint !== undefined && URL.canParse(endpoint) ? new URL(endpoint).origin : endpoint;
+}
+
 /** 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

@@ -184,7 +184,8 @@ export interface ProviderActionResult {
  * `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
+ * `plugin store-key`'s, which addresses the vault name directly. (An `endpoint` moved to another origin does
+ * change them, by policy — see `applyProviderPatch`.) 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.
  *

package/src/types/hooks.ts

@@ -48,8 +48,12 @@ export interface RunConfig {
  *               ephemeral context — supersede rather than follow), and/or append durable `markers`
  *               to the committed session (LLM-invisible annotations — the second durable-write point
  *               after `screen`, safe because it too fires once per turn).
+ *   validate    the EXECUTOR, before every call through every door — the runner, `POST /tools/:name`,
+ *               `invokeTool` — and `tools.validate`. Not a runner channel, so it carries no session.
+ *               Every hook runs; the call is refused if ANY returns errors. `undefined` is no opinion,
+ *               never "valid". See {@link ValidateContext}.
  */
-export type HookPoint = 'screen' | 'contribute' | 'toolcall' | 'toolresult' | 'followup';
+export type HookPoint = 'screen' | 'contribute' | 'toolcall' | 'toolresult' | 'followup' | 'validate';
 
 export interface ScreenContext {
   session: Session;
@@ -181,6 +185,41 @@ export interface ToolResultContext {
   /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
   removeHook(): void;
 }
+/**
+ * One rejected field. `path` is dotted, as a caller would WRITE the access (`.items[0].name`) rather
+ * than as JSON Pointer — the reader is either a model repairing its own call or a developer looking at
+ * a 422, and both write dots. `.` alone is the whole value.
+ *
+ * `value` is what was actually supplied there, and is what makes the difference between a message a
+ * model can act on and one it has to guess at. Optional because a validator may not have it, and
+ * `undefined` specifically means ABSENT: JSON carries no undefined, so there is nothing to show for a
+ * missing property beyond saying it is missing.
+ */
+export interface ToolInputError {
+  path:   string;
+  message: string;
+  value?: unknown;
+}
+
+/**
+ * A tool call about to execute, for a validator to judge — `json-validation` against the tool's
+ * `inputSchema`, `ts-validation` against its `ToolContract` params type. A hook rather than a service
+ * so several co-exist with no reference to each other: each is consulted, a call is refused if any
+ * refuses it, and unloading one removes only its own opinion. It was a single-valued service key, which
+ * forced the second validator to capture the first and delegate to it — so the pair depended on load
+ * order, and on each other.
+ *
+ * Return errors to refuse, `[]` to say the input is valid, or nothing for NO OPINION (no contract for
+ * this tool, or one that cannot be honestly validated). A throw is no opinion too, logged.
+ */
+export interface ValidateContext {
+  readonly tool:       string;
+  readonly parameters: unknown;
+  signal:  AbortSignal;
+  /** Unregister the hook currently running. For one-shot hooks that should fire at most once. */
+  removeHook(): void;
+}
+
 // The toolresult hook returns `{ result }` to replace the tool's result, or nothing to leave it
 // (and just observe) — a trivial single-field return, inlined in the Hook union like `contribute`'s.
 
@@ -235,4 +274,5 @@ export type Hook =
   | { on: 'contribute'; priority?: number; pluginName?: string; handler(ctx: ContributeContext): Message[]    | void | Promise<Message[]    | void> }
   | { on: 'toolcall';   priority?: number; pluginName?: string; handler(ctx: ToolCallContext):   ToolCallResult | void | Promise<ToolCallResult | void> }
   | { on: 'toolresult'; priority?: number; pluginName?: string; handler(ctx: ToolResultContext): { result: unknown } | void | Promise<{ result: unknown } | void> }
-  | { on: 'followup';   priority?: number; pluginName?: string; handler(ctx: FollowupContext):   FollowupResult | void | Promise<FollowupResult | void> };
+  | { on: 'followup';   priority?: number; pluginName?: string; handler(ctx: FollowupContext):   FollowupResult | void | Promise<FollowupResult | void> }
+  | { on: 'validate';   priority?: number; pluginName?: string; handler(ctx: ValidateContext):   ToolInputError[] | undefined | void | Promise<ToolInputError[] | undefined | void> };

package/src/types/permission.ts

@@ -120,7 +120,7 @@ export function refusalMessage(decision: PermissionDecision, act?: string): stri
  * 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.
+ * delegates to it, so a pair composes in either load order.
  */
 export interface PermissionGate {
   decide(req: PermissionRequest, ask: PromptFn | undefined): Promise<PermissionDecision>;

package/src/types/provider.ts

@@ -264,4 +264,11 @@ export interface ProviderAdapter {
     signal:   AbortSignal
   ): AsyncIterable<CompletionEvent>;
   health(): Promise<HealthStatus>;
+  /**
+   * The model ids this adapter can run under `config`, for a person choosing one (the setup wizards) and
+   * for `checkProviderModel`, which catches a mistyped one. Absent where the adapter cannot enumerate
+   * them, and a rejection means the same: the caller asks for a model name instead, or accepts it
+   * unchecked. `config` carries resolved credentials, which a remote list is sent with.
+   */
+  models?(config: ProviderConfig, signal?: AbortSignal): Promise<string[]>;
 }

package/src/types/registries.ts

@@ -1,4 +1,4 @@
-import type { Hook } from './hooks.js';
+import type { Hook, ToolInputError } from './hooks.js';
 import type { Session } from './messages.js';
 import type { ProviderConfig } from './provider.js';
 import type { Tool } from './tools.js';
@@ -34,6 +34,11 @@ export interface ToolRegistry {
   resolve(name: string): Tool | null;
   list(): readonly Tool[];
   removeByPlugin(pluginName: string): void;
+  /** Judge `parameters` for the tool `name` exactly as its executor will before running it: every
+   *  `validate` hook. Errors refuse, `[]` is valid, `undefined` means nothing had an opinion. For a
+   *  caller that stores a call to make later (a trigger's `invoke`), so it can be refused while its
+   *  author is present. Optional: a registry stood up by hand need not validate. */
+  validate?(name: string, parameters: unknown): Promise<ToolInputError[] | undefined>;
 }
 
 /** What the runner tells a {@link ToolPresenter} about the call it's about to make. */

package/src/types/tools.ts

@@ -314,6 +314,12 @@ export interface Tool<R = unknown> {
    *  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;
+  /** Declarations (`interface`, `type`) that {@link toolContract} names and that exist nowhere else — a
+   *  function package's own types, which its exports' contracts refer to by name. In scope for this tool's
+   *  contract only: a consumer declares them in a namespace of their own beside the contract
+   *  (`contractArms`), so two tools' types of one name never meet. Absent ⇒ the contract names only
+   *  plugin-api types and TypeScript's own. */
+  toolContractTypes?: string;
   executor:     ToolExecutor<R>;
   pluginName?:  string;
 }

package/src/types/typescript.ts

@@ -79,6 +79,12 @@ export interface FunctionCall {
   /** What {@link FunctionRunner.settings} returned at the start of this invocation. Absent ⇒ the runner
    *  applies its own defaults, as it must for a value it did not produce. */
   readonly settings?: FunctionRunSettings;
+  /** What a body's own `fetch` and `WebSocket` should be: the consumer's, which put each origin they reach
+   *  to a {@link PermissionGate}, as `importModule` puts each module. A runner binds them in place of the
+   *  globals; absent, or a runner that does not, leaves the body the platform's. Their types are the
+   *  platform's own, so nothing a body is checked against changes. */
+  readonly fetch?: typeof fetch;
+  readonly WebSocket?: typeof WebSocket;
 }
 
 export interface FunctionRunner {
@@ -139,7 +145,7 @@ export interface FunctionRunner {
   canonicalImport?(spec: string): string;
   /**
    * Identifiers a body does NOT have — anything this runner withholds, shadows or never binds (node's
-   * withholds `process`, `globalThis`, `Buffer`, `eval` and `Function`, and names the phantom
+   * withholds `process`, `globalThis`, `global`, `eval` and `Function`, and names the phantom
    * `require`/`module`/`__dirname` too, which never existed in a bare function expression but whose node
    * types would otherwise make one typecheck and then fail at the first call).
    *