@matatbread/matbot-core 0.4.13 → 0.4.14

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.13",
+  "version": "0.4.14",
   "engines": {
     "node": ">=24.0.0"
   },
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@matatbread/matbot-plugin-api": "^0.4.13"
+    "@matatbread/matbot-plugin-api": "^0.4.14"
   },
   "devDependencies": {
     "typescript": "^6.0.3"

package/src/index.ts

@@ -24,6 +24,15 @@ export { applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE
 // plugin-api dependency to get it.
 export { applyProviderPatch, patchedFields } from '@matatbread/matbot-plugin-api';
 export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind } from '@matatbread/matbot-plugin-api';
+// The canonical `type: 'confirm'` answers. Same reason as the patch policy above: an app implementing a
+// PromptFn (or a test standing one in) has to speak them, and must not hard-code the rendered label.
+export { CONFIRM_YES, CONFIRM_NO } from '@matatbread/matbot-plugin-api';
+// A select option's value vs its label. Frontends render the label and return the value; a caller that
+// branches on the answer compares values, never prose (see FormOption).
+export { optionValue, optionLabel } from '@matatbread/matbot-plugin-api';
+// Binds `ctx.gate` for a hand-assembled ToolContext — anything standing a tool-invocation door up
+// outside the runner (frontend-web's `POST /tools/:name`) needs it, and gets it through core.
+export { bindGate, bindPluginOps } from '@matatbread/matbot-plugin-api';
 // Ambient security principal: the interface is a type (carried by `export type *`); these are the values.
 export { currentPrincipal, tryCurrentPrincipal, runAs, lastActivityAt } from '@matatbread/matbot-plugin-api';
 // Host boot assembly, from plugin-api's `/host` subpath. An embedding app gets these through core and

package/src/registry.ts

@@ -1,6 +1,6 @@
-import type { Tool, ToolRegistry, Hook, PromptFn, FormField, FrontendInfo, ProviderAdapter, ProviderConfig, FailedPlugin } from './types.js';
+import type { Tool, ToolRegistry, Hook, PromptFn, FrontendInfo, ProviderAdapter, ProviderConfig, FailedPlugin } from './types.js';
 import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
-import { scopedNotifier } from '@matatbread/matbot-plugin-api/host';
+import { scopedNotifier, askPermissionGate } from '@matatbread/matbot-plugin-api/host';
 import type {
   MatbotPlugin, MatbotMachine, MatbotRuntime, Mounted,
   ProviderAdapterFactory, StoreFactory,
@@ -26,7 +26,6 @@ const state = {
   systemContextPlugins: new Set<string>(),       // plugins that registered a system-context contributor
   lifecycles:      new Map<string, AbortController>(),  // pluginName → "this plugin is loaded" signal, aborted on unload
   failedPlugins:   [] as FailedPlugin[],         // plugins the loader skipped, keyed by specifier (last failure wins)
-  overwriteAllTools: undefined as boolean | undefined,  // persisted "overwrite on collision, this install" choice, loaded lazily
 };
 
 // Plugin load/unload is announced on the Notifier as a `RegistryChange` with `registry: 'plugins'`, for
@@ -38,22 +37,21 @@ export function announcePluginLoaded(services: MatbotMachine, name: string): voi
   services.Notifier.notify({ kind: RegistryChangeKind, source: 'plugins', registry: 'plugins', name, operation: 'added' });
 }
 
-// Settings namespace + key under which the user's "overwrite all colliding tools" choice
-// is persisted for the installation. The namespace doubles as a Store document id, so it must
-// satisfy the storage id charset (/^[\w-]+$/) — hence underscores, not '@matbot/core'. The
-// dunder marks it reserved (internal), so it won't collide with a real plugin's settings.
-const CORE_SETTINGS_NS    = '__matbot_core__';
-const OVERWRITE_TOOLS_KEY = 'overwriteToolsOnCollision';
-
 /**
- * Decide whether an incoming tool registration may overwrite an existing tool of the
- * same name owned by a different plugin. Returns true to overwrite, false to keep the
- * existing one and drop the incoming registration.
+ * Decide whether an incoming tool registration may overwrite an existing tool of the same name owned
+ * by a different plugin. Returns true to overwrite, false to keep the existing one and drop the
+ * incoming registration.
+ *
+ * Core declares that the decision is needed and nothing else: the installation's `PermissionGate`
+ * decides how acceptance is obtained. Core used to own the whole policy here — a settings key in a
+ * reserved `__matbot_core__` namespace, a cached memo, a per-tool allowlist and two "always" options —
+ * which is an installation policy living in core and keyed in an LLM-writable store, and which an
+ * alternative installation could only defeat rather than replace. Remembering answers is now
+ * `@matatbread/matbot-default-gate`'s, out of its own plugin settings namespace.
  *
- * Resolution order: a persisted "overwrite all (this install)" choice short-circuits to
- * true; otherwise the user is prompted [n / Y / all] with Y (overwrite) as the default.
- * 'all' persists the choice. With no prompt available (non-interactive host) we overwrite —
- * the default — preserving matbot's historical last-registration-wins behaviour.
+ * `fallback: true` is load-bearing: with no gate and no prompt (a boot load), a collision overwrites,
+ * preserving matbot's last-registration-wins behaviour and the deliberate override documented in
+ * docs/PER-USER-PLUGINS.md.
  */
 async function resolveToolCollision(
   services:      MatbotMachine,
@@ -62,34 +60,24 @@ async function resolveToolCollision(
   incomingOwner: string,
   prompt:        PromptFn | undefined,
 ): Promise<boolean> {
-  const coreSettings = makePluginSettings(services.createStore<SettingsDoc>('settings'), CORE_SETTINGS_NS);
-  if (state.overwriteAllTools === undefined) {
-    state.overwriteAllTools = (await coreSettings.get<boolean>(OVERWRITE_TOOLS_KEY)) ?? false;
-  }
-  if (state.overwriteAllTools) return true;
-
   const owner = existingOwner !== undefined ? `"${existingOwner}"` : 'a built-in';
   const label = `Tool \`"${toolName}"\` is already registered by **${owner}**. Overwrite it with the one from **"${incomingOwner}"**?`;
-
-  if (prompt === undefined) {
-    console.warn(`[matbot] ${label} — non-interactive, overwriting (default).`);
-    return true;
-  }
-
-  const field: FormField = {
-    name:    'overwrite',
+  const allowed = await (services.PermissionGate ?? askPermissionGate).decide({
+    gate:     'tools.overwrite',
+    subject:  toolName,
+    // The incoming OWNER rides in the label rather than in a field of its own: a single `subject`
+    // cannot also express "trust everything plugin foo registers", and no policy wants that yet.
     label,
-    type:    'select',
-    options: ['Keep existing', 'Overwrite', 'Always overwrite'],
-    default: 'Overwrite',
-  };
-  const answer = (await prompt(field)).trim().toLowerCase();
-  if (answer.startsWith('a')) {  // "Always overwrite" — persist for the installation
-    state.overwriteAllTools = true;
-    await coreSettings.set(OVERWRITE_TOOLS_KEY, true);
-    return true;
+    fallback: true,
+  }, prompt);
+  // Said out loud when nobody could be asked, as it was before the gate existed: a boot-time overwrite
+  // is the one decision here that proceeds with no human and no record of itself, and "my tool silently
+  // changed hands" is exactly the report this line answers. A policy that overwrites after ASKING
+  // needs no warning — the user just saw the question.
+  if (prompt === undefined) {
+    console.warn(`[matbot] ${label} — non-interactive, ${allowed ? 'overwriting' : 'keeping the existing tool'}.`);
   }
-  return !answer.startsWith('k');  // "Keep existing" → false; "Overwrite"/default → true
+  return allowed;
 }
 
 // ── Version check ─────────────────────────────────────────────────────────────
@@ -352,6 +340,18 @@ export async function setupPlugin(plugin: MatbotPlugin, services: MatbotMachine,
       specifier: plugin.specifier,
       ...(plugin.source !== undefined ? { source: plugin.source } : {}),
     },
+    // Re-declared as a getter because the spread above COPIES: `{ ...services }` evaluates every
+    // getter on the host object exactly once, at plugin-load time. For the other swap-members that is
+    // harmless — the host's getters hand back capture-safe proxies, so a copied reference still follows
+    // the swap — but `PermissionGate` is deliberately NOT proxied (a policy composes by capturing the
+    // gate it displaces; through a proxy that capture resolves to itself, for ever). Copied, a plugin
+    // would hold whatever policy was active when IT loaded: a policy registered later would never be
+    // consulted by anything reading through this machine (frontend-web's `POST /tools/:name` route did
+    // exactly that), and unloading one would leave the copy pointing at the gone impl instead of
+    // reverting to the host's boot default. Reading through to `services` keeps it live per access,
+    // which is what every consumer here wants; a policy plugin's own `previous` capture is unaffected,
+    // being a deliberate read of the concrete gate at that moment.
+    get PermissionGate() { return services.PermissionGate; },
     // Everything this plugin publishes is attributed to it by default — the notification analogue of
     // stamping `pluginName` on its tools. Reads through the host's swap proxy, so a registered
     // distributed Notifier takes effect for a plugin that captured this in setup().

package/src/runner.ts

@@ -2,13 +2,14 @@ import type {
   Session, Message, MessageContent, ModelContent, Usage, UsageSite, ProviderMeta, TruncatedToolResult,
   TurnEvent, RunConfig, ProviderAdapter, ProviderConfig,
   Tool, ToolRegistry, ToolContext, Store, FileStore, MediaStore, SystemContextRegistry, Vault, PromptFn, FormField,
+  PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { ToolPresenter } from '@matatbread/matbot-plugin-api';
 import { recordSpan, recordUsage, withUsageSite } from '@matatbread/matbot-plugin-api/host';
 import { HookRegistry } from './hooks.js';
 import { appendMessage, createMessage } from './session.js';
-import { foldOntoUserTurn, bindPluginOps } from '@matatbread/matbot-plugin-api';
+import { foldOntoUserTurn, bindPluginOps, bindGate } from '@matatbread/matbot-plugin-api';
 import { addUsage } from './usage.js';
 import { MEDIA_RESIDENCY_BYTES, resolveSessionMedia } from './media.js';
 
@@ -114,6 +115,11 @@ export interface RunSessionOpts {
   mediaStore?:    MediaStore;
   /** Supply a prompt implementation to allow tools to ask interactive questions. */
   prompt?:        PromptFn;
+  /** The installation's permission policy, consulted by `ctx.gate` at every privileged tool call site.
+   *  The host passes its live `services.PermissionGate` (a capture-safe proxy, so a policy plugin
+   *  registered mid-session takes effect); absent — a direct `runSession` caller or a test — the
+   *  asking default stands in, which is the same behaviour the host boots with. */
+  permissionGate?: PermissionGate;
   /**
    * Turn-scoped context to inject ephemerally, exactly like a `screen` hook's `ephemeral` (tail-folded
    * onto the freshest non-marker message, never persisted) — merged ahead of whatever `screen` adds.
@@ -585,6 +591,11 @@ export async function* runSession(opts: RunSessionOpts): AsyncIterable<TurnEvent
         provider:     config.provider,
         prompt:       promptFn,
         ...bindPluginOps(opts, promptFn),
+        // `opts.prompt`, deliberately NOT `promptFn`: the stand-in above answers with the field's own
+        // default, so a gate handed it could never tell "no human is reachable" from "a human answered
+        // with the default" — and would get the fallback back one layer too late to reason about.
+        // `ToolContext.prompt` keeps the stand-in exactly as before; only the gate sees the truth.
+        ...bindGate(opts.permissionGate, tc.name, opts.prompt),
         ...(opts.workdir     !== undefined ? { workdir:     opts.workdir     } : {}),
         ...(opts.configPath  !== undefined ? { configPath:  opts.configPath  } : {}),
         ...(opts.files       !== undefined ? { files:       opts.files       } : {}),

package/src/session-runner.ts

@@ -2,7 +2,7 @@ import type {
   Session, Message, MessageContent, Principal, PromptFn, PipelineEvent,
   Store, ToolRegistry, SystemContextRegistry, Vault, FileStore, MediaStore, UserContent, Tool,
   ProviderAdapter, ProviderConfig, SessionRunner, SessionView, OpenOpts, SubmitOpenOpts,
-  SteeringPolicy, SteeringDecision, TurnEntry,
+  SteeringPolicy, SteeringDecision, TurnEntry, PermissionGate,
 } from './types.js';
 import type { MatbotPlugin } from './plugin.js';
 import type { HookRegistry } from './hooks.js';
@@ -33,6 +33,10 @@ export interface SessionRunnerDeps {
   // by-value media is written at the boundary, and where the runner reads it back from. Absent ⇒ an
   // attachment is refused with a reason and a stored `file-ref` degrades to the converters' text note.
   mediaStore?:     () => MediaStore | undefined;
+  // Resolved live (the host boots a default, a plugin may replace it): the installation's permission
+  // policy, consulted by `ctx.gate` at every privileged tool call. Absent ⇒ the asking default, which
+  // is what the host boots with anyway.
+  permissionGate?: () => PermissionGate | undefined;
   hooks?:          HookRegistry;
   systemContext?:  SystemContextRegistry;
   vault?:          Vault;
@@ -363,6 +367,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
         const wire = await deps.toolTypeIndex?.()?.wireContracts();
         const toolPresenter = deps.toolPresenter?.();
         const mediaStore    = deps.mediaStore?.();
+        const permissionGate = deps.permissionGate?.();
         const toolMap = deps.tools !== undefined
           ? new Map<string, Tool>(deps.tools.list().map(t => {
               const wc = wire?.[t.name];
@@ -413,6 +418,7 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
               ...(deps.workdir       !== undefined ? { workdir:       deps.workdir       } : {}),
               ...(deps.files         !== undefined ? { files:         deps.files         } : {}),
               ...(mediaStore         !== undefined ? { mediaStore                        } : {}),
+              ...(permissionGate     !== undefined ? { permissionGate                    } : {}),
               ...(deps.configPath    !== undefined ? { configPath:    deps.configPath    } : {}),
               ...(deps.vault         !== undefined ? { vault:         deps.vault         } : {}),
               ...(head.prompt        !== undefined ? { prompt:        head.prompt        } : {}),

package/src/settings.ts

@@ -39,6 +39,26 @@ let installDefaults: ReadonlyMap<string, Readonly<Record<string, unknown>>> = ne
 /** Host boot assembly: install the read-only defaults. Call before any plugin loads. */
 export function installSettingsDefaults(byPlugin: ReadonlyMap<string, Readonly<Record<string, unknown>>> | undefined): void {
   installDefaults = byPlugin ?? new Map();
+  warnRetiredCoreSettings();
+}
+
+/**
+ * The one retired core setting, named where it was authored. `__matbot_core__.overwriteToolsOnCollision`
+ * moved to the permission policy's own namespace and spelling when core stopped holding a policy, and it
+ * is deliberately NOT migrated — the standing answer is re-offered the next time that collision comes
+ * round. What an adopt-once path would have bought is one keystroke; what this buys is that an install
+ * which authored the key is told, rather than finding a prompt it thought it had answered. The dunder
+ * namespace stays reserved (the host's unmatched-namespace warning skips it), so nothing else says this.
+ */
+function warnRetiredCoreSettings(): void {
+  const core = installDefaults.get('__matbot_core__');
+  if (core === undefined || !('overwriteToolsOnCollision' in core)) return;
+  console.warn(
+    '[matbot] default_settings.__matbot_core__.overwriteToolsOnCollision no longer does anything: the ' +
+    'tool-collision decision is now a permission gate, and standing answers belong to the policy plugin. ' +
+    "Re-author it as default_settings.'@matatbread/matbot-default-gate'.'tools.overwrite' — the same list " +
+    'of tool names, or `true`.',
+  );
 }
 
 /** The plugin names the install supplies defaults for — the host checks these against what loaded. */
@@ -145,5 +165,13 @@ export function makePluginSettings(rawStore: Store<SettingsDoc>, namespace: stri
         return next;
       });
     },
+    async entries(): Promise<Record<string, unknown>> {
+      // The same layering `get` applies, in one pass: the stored document over the install default, so
+      // a stored `null` still reads as the override it is (it is a key `in` the document, and a later
+      // spread wins). One document read — the namespace is one document, and this is the same read a
+      // single `get` already makes.
+      const doc = await getDoc();
+      return { ...installDefaults.get(namespace), ...doc?.data };
+    },
   };
 }