@matatbread/matbot-core 0.4.10 → 0.4.12

package/package.json

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

package/src/about.ts

@@ -1,5 +1,5 @@
 import type {
-  Tool, ToolExecutor, ToolContract, ToolResultOf, ToolContext, MatbotMachine, SystemContextPart,
+  Tool, ToolExecutor, ToolContract, NoParams, ToolResultOf, ToolContext, MatbotMachine, SystemContextPart,
 } from '@matatbread/matbot-plugin-api';
 
 declare module '@matatbread/matbot-plugin-api' {
@@ -13,7 +13,7 @@ declare module '@matatbread/matbot-plugin-api' {
       systemPrompt:    string | null;
       /** The same text kept apart and attributed, so a contribution can be traced to its plugin. */
       systemContext:   SystemContextPart[];
-    }, Record<string, never>>;
+    }, NoParams>;
   }
 }
 

package/src/index.ts

@@ -11,13 +11,14 @@ export {
   promptCancelledError, isPromptCancelledError,
   readOnlyError, isReadOnlyError,
   mediaRejectedError, isMediaRejectedError,
+  invalidSecretNameError, isInvalidSecretNameError,
   StoreQueryError,
 } from '@matatbread/matbot-plugin-api';
 export type {
   MissingSecretError, IncompatibleRuntimeError, NotAPluginError, PromptCancelledError, ReadOnlyError,
-  MediaRejectedError, MatbotErrorKind,
+  MediaRejectedError, InvalidSecretNameError, MatbotErrorKind,
 } from '@matatbread/matbot-plugin-api';
-export { applyCreateSecret }  from '@matatbread/matbot-plugin-api';
+export { applyCreateSecret, assertStorableKey, unreferenceableKey, REFERENCEABLE_KEY_RULE } from '@matatbread/matbot-plugin-api';
 export { isTruncatedToolResult, notifyingStore, ItemChangeKind, RegistryChangeKind } 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';

package/src/security/vault.ts

@@ -1,5 +1,5 @@
 import type { Vault } from '@matatbread/matbot-plugin-api';
-import { missingSecretError, applyCreateSecret } from '@matatbread/matbot-plugin-api';
+import { missingSecretError, applyCreateSecret, assertStorableKey, unreferenceableKey } from '@matatbread/matbot-plugin-api';
 
 const REF_RE = /\$\{([^}]+)\}/g;
 
@@ -37,8 +37,16 @@ export class VaultImpl implements Vault {
   }
 
   async writeSecret(name: string, value: string): Promise<void> {
-    if (value === '') this.store.delete(name);
-    else this.store.set(name, value);
+    if (value === '') { this.store.delete(name); return; }
+    // `this`, not the base policy directly, so a subclass narrowing the rule (EnvFileVault) is
+    // enforced through the inherited write rather than having to re-implement it.
+    assertStorableKey(this, name);
+    this.store.set(name, value);
+  }
+
+  /** A plain map stores anything that can be referenced; subclasses narrowing this call `super`. */
+  unstorableKey(name: string): string | undefined {
+    return unreferenceableKey(name);
   }
 
   hasKey(name: string): boolean {

package/src/session-runner.ts

@@ -376,8 +376,8 @@ export function createSessionRunner(deps: SessionRunnerDeps): SessionRunner {
           // Establish the submitter's principal for the whole turn here, not inside runSession:
           // pump runs detached (`void pump`), so this scope — not the request that enqueued — is the
           // turn's async root. Everything downstream (hooks, tools, and any Store/FileStore/Vault
-          // access they trigger) reads it via currentPrincipal(). The consumption MUST happen inside
-          // the callback: an async iterator returned out of the scope would lose it before it pulls.
+          // access they trigger) reads it via currentPrincipal(). The consumption is inside the callback
+          // because the pump owns it, not because it must be: runAs rescopes a returned iterator itself.
           // runAs, not a context switch of its own: the pump holds the machine across the whole queue
           // (see above), so a turn declares only its owner. Each item carries its own submitter.
           // The terminal event this turn ended on. `followup` is post-COMMIT, and only `done` is a

package/src/settings.ts

@@ -1,4 +1,5 @@
-import type { PluginSettings, Store } from '@matatbread/matbot-plugin-api';
+import type { Notifier, PluginSettings, Store } from '@matatbread/matbot-plugin-api';
+import { notifyingStore } from '@matatbread/matbot-plugin-api';
 
 export interface SettingsDoc {
   id:      string;
@@ -45,6 +46,38 @@ export function settingsDefaultNamespaces(): readonly string[] {
   return [...installDefaults.keys()];
 }
 
+/** The routing namespace settings changes are announced under — the store namespace they live in. A
+ *  consumer filters `kind === ItemChangeKind && namespace === SETTINGS_NAMESPACE && id === slug(mine)`. */
+export const SETTINGS_NAMESPACE = 'settings';
+
+/**
+ * The bus settings writes announce on, installed by the host at boot alongside {@link installSettingsDefaults}.
+ *
+ * Module state consulted inside {@link makePluginSettings} for the same reason the defaults are, and it
+ * is the same call site that proves it: `plugins/browser` builds its own settings facade over a concrete
+ * backend, and a notifier passed as a parameter is one that facade silently omits — the symptom being a
+ * setting that quietly stops being observable, which nothing distinguishes from one that never changed.
+ *
+ * Hosts pass their capture-safe `Notifier` proxy, so a later `register('Notifier', …)` swap carries
+ * settings traffic with everything else. Absent (a test, an embedder that installed nothing) a write
+ * publishes nothing — settings still work, they are just unobservable.
+ */
+let settingsNotifier: Notifier | undefined;
+
+/** Host boot assembly: announce settings writes on this bus. Call before any plugin loads. */
+export function installSettingsNotifier(notifier: Notifier | undefined): void {
+  settingsNotifier = notifier;
+}
+
+/** Read per publish, not captured at facade construction — a facade built before the host installs the
+ *  bus (core's own reserved-namespace settings, a test) would otherwise be permanently silent. Only
+ *  `notify` is ever reached: `notifyingStore` publishes and never subscribes. */
+const lateBoundNotifier: Notifier = {
+  notify:    n => settingsNotifier?.notify(n),
+  subscribe: async function *(signal, filter) { yield* settingsNotifier?.subscribe(signal, filter) ?? []; },
+  consume:   (handler, signal, filter) => settingsNotifier?.consume(handler, signal, filter),
+};
+
 /**
  * Build a PluginSettings facade over the shared settings store, scoped to one document id.
  *
@@ -60,8 +93,19 @@ export function settingsDefaultNamespaces(): readonly string[] {
  * key's default. Seeding on write would make a later config edit work or not work depending on
  * unrelated write history, which is unexplainable to whoever edits the yaml.
  */
-export function makePluginSettings(store: Store<SettingsDoc>, namespace: string): PluginSettings {
+export function makePluginSettings(rawStore: Store<SettingsDoc>, namespace: string): PluginSettings {
   const id = slugSettingsNamespace(namespace);
+  // Wrapped here, not at the call sites, for the reason installDefaults is consulted here: the writers
+  // are `set` and `delete` below and nowhere else, so one wrapper covers every plugin's settings and
+  // cannot be forgotten by a host building its own facade.
+  //
+  // The announcement carries the UNSLUGGED namespace as `key`, because `id` is the slug — a shape the
+  // filesystem store's id rule imposed, which another backend could impose differently. A consumer
+  // asking "are these my settings?" compares `key` against its own `services.self.name` and never
+  // reproduces `slugSettingsNamespace`, which would keep compiling after that rule changed and simply
+  // stop matching. It also carries the ambient principal, an override being per-principal: a change to
+  // someone else's settings is not a change to yours.
+  const store = notifyingStore(rawStore, lateBoundNotifier, SETTINGS_NAMESPACE, 'settings', () => namespace);
 
   const getDoc = async (): Promise<SettingsDoc | null> => {
     const raw = await store.get(id);

package/src/tool-registry.ts

@@ -1,5 +1,123 @@
 import { RegistryChangeKind } from '@matatbread/matbot-plugin-api';
-import type { Tool, ToolRegistry, Notifier } from './types.js';
+import type { Tool, ToolRegistry, Notifier, ToolContext, ToolEvent } from './types.js';
+
+/**
+ * Structural contract for a registered input validator — duck-typed, never imported, exactly as
+ * `ProfileDirectory` is: core must not depend on whichever plugin implements it (today
+ * `@matatbread/matbot-tool-types`, from a tool's `ToolContract` params type), and the shape is the
+ * whole agreement. `undefined` means NO OPINION — no contract for this tool, or one that cannot be
+ * honestly validated — and is never read as "valid".
+ */
+export interface ToolInputValidator {
+  validateToolCall(tool: string, parameters: unknown): Promise<ToolInputError[] | undefined>;
+}
+
+/**
+ * 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;
+}
+
+/** Cap on the rendered value. Long enough to identify what was sent, short enough that a base64
+ *  attachment or a large document cannot turn one rejected field into the bulk of a turn's context. */
+const VALUE_CHARS = 160;
+
+/**
+ * `.x: expected string, actual value \`{"x":8}\``
+ *
+ * The value is wrapped in its own field name, so what is shown is a fragment the caller can compare
+ * against what it sent rather than a bare literal it has to locate. An array element or the root has no
+ * name to wrap it in, so those render the value alone — the path already says which one it was.
+ */
+function formatError(e: ToolInputError): string {
+  if (e.value === undefined) return `${e.path}: ${e.message}`;
+  const named = /\.([A-Za-z_$][\w$]*)$/.exec(e.path);
+  let shown: string;
+  try {
+    // Validation now runs on internal calls too, so this is not always JSON.parse output: a caller can
+    // reach here with a bigint or a cycle, and a throw while REPORTING an error would replace the
+    // diagnosis with a stack trace.
+    shown = JSON.stringify(named ? { [named[1]!]: e.value } : e.value) ?? String(e.value);
+  } catch {
+    return `${e.path}: ${e.message}`;
+  }
+  if (shown.length > VALUE_CHARS) shown = `${shown.slice(0, VALUE_CHARS)}…`;
+  return `${e.path}: ${e.message}, actual value \`${shown}\``;
+}
+
+/**
+ * Declared HERE, by the consumer, rather than by any of the plugins that implement it — `json-validation`
+ * (against `inputSchema`) and `ts-validation` (against the `ToolContract` type) both register this key,
+ * and two plugins declaring one key must declare it identically or the merge is a TS2717 in a file
+ * neither owns. Core reads it, so core names it.
+ *
+ * Exactly one is active, since the registry holds one value per key. A validator that loads over another
+ * should capture the one it displaces and delegate to it when it has no opinion of its own — which is
+ * how the typed and schema validators compose rather than shadow each other.
+ */
+declare module '@matatbread/matbot-plugin-api' {
+  interface MatbotServices {
+    ToolCallValidator?: ToolInputValidator;
+  }
+}
+
+/**
+ * The `code` on the `error` event a rejected call yields. 422 rather than 400 because the body parsed
+ * fine and its *shape* is wrong, and — the reason a number is safe here at all — a process exit code
+ * cannot exceed 255, so this can never be mistaken for one (`bash` puts its exit status in the same
+ * field). A transport may map a 4xx code onto its own status; nothing is obliged to.
+ */
+export const TOOL_INPUT_INVALID = 422;
+
+/**
+ * Validation belongs at the executor, not in a `toolcall` hook, because the hook is a RUNNER channel:
+ * it guards the model's path and nothing else. `POST /tools/:name` and `invokeTool` both call
+ * `tool.executor.execute` directly and fire no hooks, so a hook leaves two doors open and invites the
+ * per-door duplication that then drifts. Wrapping here is the one place every door already passes
+ * through.
+ *
+ * Wrapped at REGISTRATION rather than at `resolve`, so there is exactly one wrapper per tool and
+ * `resolve(x) === resolve(x)` still holds.
+ *
+ * The validator is looked up per CALL, not captured: it may be registered long after the tools are
+ * (plugin order), and it may be unloaded. No validator ⇒ the call passes straight through, so core
+ * mandates no validation — it only honours one that is registered. The cost when a validator IS
+ * present is one generator frame plus a structural check (measured in the tens of nanoseconds against
+ * tool work measured in milliseconds); the deliberate trade is that an INTERNAL call is validated too,
+ * though a statically-typed call site should already be sound. That is not pure waste: `invokeTool`
+ * with a dynamic name, a trigger's `invoke.params` (typed `object`) and a compiled skill's payload are
+ * all internal callers whose input no compiler has checked.
+ */
+function validatingTool(tool: Tool, lookup: () => ToolInputValidator | undefined): Tool {
+  const inner = tool.executor;
+  return {
+    ...tool,
+    executor: {
+      execute(input: unknown, ctx: ToolContext): AsyncIterable<ToolEvent> {
+        return (async function* () {
+          const errs = await lookup()?.validateToolCall(tool.name, input);
+          if (errs !== undefined && errs.length > 0) {
+            const detail = errs.map(formatError).join('; ');
+            yield { type: 'error', message: `Invalid input for tool "${tool.name}": ${detail}`, code: TOOL_INPUT_INVALID };
+            return;
+          }
+          // `yield*` delegates `return`/`throw` as well as values, so an abort still reaches the tool.
+          yield* inner.execute(input, ctx);
+        })();
+      },
+    },
+  };
+}
 
 export class ToolRegistryImpl implements ToolRegistry {
   private readonly tools = new Map<string, Tool>();
@@ -7,12 +125,20 @@ export class ToolRegistryImpl implements ToolRegistry {
   // proxy, not a resolved impl, so a later register('Notifier', …) takes effect here too. Optional: a
   // registry built without one (tests) simply announces nothing.
   private readonly notifier: Notifier | undefined;
+  // Host-injected, late-bound: a validator is typically registered by a plugin long after the builtin
+  // tools are seeded, so this is read per call rather than resolved here.
+  private readonly validator: (() => ToolInputValidator | undefined) | undefined;
 
-  constructor(initial?: Iterable<Tool>, notifier?: Notifier) {
-    if (initial !== undefined) for (const tool of initial) this.tools.set(tool.name, tool);
+  constructor(initial?: Iterable<Tool>, notifier?: Notifier, validator?: () => ToolInputValidator | undefined) {
+    this.validator = validator;
+    if (initial !== undefined) for (const tool of initial) this.tools.set(tool.name, this.guard(tool));
     this.notifier = notifier;
   }
 
+  private guard(tool: Tool): Tool {
+    return this.validator === undefined ? tool : validatingTool(tool, this.validator);
+  }
+
   private announce(name: string, operation: 'added' | 'removed', pluginName?: string): void {
     this.notifier?.notify({
       kind: RegistryChangeKind, source: 'tools', registry: 'tools', name, operation,
@@ -21,7 +147,7 @@ export class ToolRegistryImpl implements ToolRegistry {
   }
 
   register(tool: Tool): void {
-    this.tools.set(tool.name, tool);
+    this.tools.set(tool.name, this.guard(tool));
     this.announce(tool.name, 'added', tool.pluginName);
   }