@matatbread/matbot-plugin-api 0.4.13 → 0.4.15

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.13",
+  "version": "0.4.15",
   "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,7 +9,7 @@
  */
 
 export type * from './types.js';
-export { CONFIRM_YES, CONFIRM_NO, isTruncatedToolResult } from './types.js';
+export { CONFIRM_YES, CONFIRM_NO, optionValue, optionLabel, isTruncatedToolResult, renderToolCheck, renderToolCheckOmitted, FUNCTION_TIMEOUT } from './types.js';
 
 export * from './base64.js';
 export * from './bytes.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
@@ -44,7 +68,8 @@ export type InvokeToolOptions =
  * calling tool's `ctx` to forward them all (see {@link InvokeToolOptions}); everything else (vault,
  * plugin (un)loading, workdir/configPath/files) is filled from `machine`.
  *
- * Throws synchronously if no tool is registered under `name`. When no `prompt` is supplied the tool
+ * Throws synchronously if no tool is registered under `name`, or if `opts.signal` has already aborted.
+ * When no `prompt` is supplied the tool
  * runs non-interactively: any attempt to prompt rejects, which a tool surfaces as a normal error
  * event. Pair with {@link toolText} to collapse the stream to its result string.
  */
@@ -56,6 +81,9 @@ export function invokeTool<K extends string, const P>(
 ): AsyncIterable<ToolEvent<ToolResultFor<K, P>>> {
   const tool = machine.tools.resolve(name);
   if (tool === null) throw new Error(`Tool "${name}" is not registered`);
+  // A call whose turn was cancelled never starts. Otherwise a composed body looping over `await tool.x()`
+  // goes on calling tools after the abort, each callee deciding for itself whether to honour the signal.
+  if (opts.signal.aborted) throw new Error(`Tool "${name}" was not started: the call was cancelled.`);
 
   const prompt = opts.prompt ?? rejectingPrompt;
   const ctx: ToolContext = {
@@ -65,6 +93,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, FunctionRunner, 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.
@@ -169,6 +191,10 @@ export interface MatbotServices {
    *  `file-ref` degrades to the converters' `[Attached file: x]` note. A text-only deployment is
    *  unaffected either way. See {@link MediaStore}. */
   readonly MediaStore?: MediaStore | undefined;
+  /** Optional bound on how long model-authored code may run without awaiting. The node host registers
+   *  one; absent ⇒ such code runs unbounded, as it must where synchronous code cannot be interrupted.
+   *  See {@link FunctionRunner}. */
+  readonly FunctionRunner?: FunctionRunner | undefined;
 }
 
 /** The assembled machine: registry services wired to the fixed runtime — what `setup()` receives. */

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,109 @@ export interface TypeScriptStripper {
   strip(source: string): string | Promise<string>;
 }
 
+/**
+ * Optional, host-supplied: compiles already-stripped JavaScript into an async function whose SYNCHRONOUS
+ * execution is bounded. Model-authored code (a `tool_function` body) runs on the one event loop every
+ * session, frontend and schedule shares, so a loop that never awaits freezes all of them — and nothing
+ * in-process can stop it, an abort signal included, since stopping needs the loop to yield. Only the
+ * stretches between awaits are bounded: a body waiting on a slow tool call is not doing work.
+ *
+ * Absent ⇒ a consumer compiles with `new AsyncFunction` and runs unbounded, which is all a platform with
+ * no way to interrupt synchronous code (the browser) can do. An embedder may register its own.
+ */
+export interface FunctionRunner {
+  /** Compile `body` as the body of an async function taking `params`. Throws on a syntax error. A call
+   *  stopped at the limit rejects with an error whose `code` is {@link FUNCTION_TIMEOUT}. */
+  compile(params: readonly string[], body: string): (...args: unknown[]) => Promise<unknown>;
+}
+
+/** The `code` on the error a {@link FunctionRunner} rejects with when it stops a run at its limit, so a
+ *  consumer can tell a stopped runaway from an ordinary failure without matching message text. */
+export const FUNCTION_TIMEOUT = 'FUNCTION_TIMEOUT';
+
+/**
+ * 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 +141,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';