@matatbread/matbot-plugin-api 0.4.11 → 0.4.12

package/package.json

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

package/src/errors.ts

@@ -16,7 +16,7 @@
 
 const BRAND = 'matbot';
 
-export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled' | 'ReadOnly' | 'MediaRejected';
+export type MatbotErrorKind = 'MissingSecret' | 'InvalidSecretName' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled' | 'ReadOnly' | 'MediaRejected';
 
 function isKind(e: unknown, kind: MatbotErrorKind): boolean {
   return typeof e === 'object' && e !== null && (e as Record<string, unknown>)[BRAND] === kind;
@@ -40,6 +40,33 @@ export function isMissingSecretError(e: unknown): e is MissingSecretError {
   return isKind(e, 'MissingSecret');
 }
 
+/**
+ * Thrown by a vault write when the backend cannot store a secret under the requested name — the
+ * name is the caller's, and most callers are an LLM inventing one, so it is regularly unstorable
+ * (a `.env`-backed vault takes environment-variable names; `email:abc:password` is silently
+ * dropped by systemd on the next boot). Refusing at the write is the only point that still knows
+ * which name was asked for.
+ *
+ * `rule` states what IS storable, not what went wrong: it is written for whoever must pick another
+ * name, and the caller that surfaces this — a prompt, a tool error — has no other source for it.
+ * Which names qualify is the backend's own business (`VaultSpec.unstorableKey`), so `rule` comes
+ * from there verbatim.
+ */
+export interface InvalidSecretNameError extends Error {
+  matbot: 'InvalidSecretName';
+  /** The rejected name. `key`, not `name` — `Error.name` is already the error's own type name. */
+  readonly key:  string;
+  readonly rule: string;
+}
+export function invalidSecretNameError(key: string, rule: string): InvalidSecretNameError {
+  const e = new Error(`Vault: cannot store a secret named "${key}" — ${rule}`);
+  e.name = 'InvalidSecretNameError';
+  return Object.assign(e, { matbot: 'InvalidSecretName' as const, key, rule });
+}
+export function isInvalidSecretNameError(e: unknown): e is InvalidSecretNameError {
+  return isKind(e, 'InvalidSecretName');
+}
+
 /**
  * Thrown by the loader when an explicit, single, user-initiated load (the `plugin`/`provider`
  * tools via `services.loadPlugin`) targets a plugin whose `matbotRuntime` excludes this host.

package/src/notify.ts

@@ -54,6 +54,21 @@ export interface NotificationBase {
 export interface ItemChange extends NotificationBase {
   readonly namespace: string;
   readonly id:        string;
+  /**
+   * The **caller's** key for this item, where `id` is derived from it rather than equal to it.
+   *
+   * `id` is the medium's address, and a medium is entitled to shape it: settings namespaces are plugin
+   * package names slugged to satisfy the filesystem store's `/^[\w-]+$/`, and another backend could
+   * legitimately hash or truncate. A consumer routing on identity — "is this MY document?" — otherwise
+   * has to reproduce a transformation it does not own, in a copy that keeps compiling after the rule
+   * changes and simply stops matching. That failure is silent and indistinguishable from "nothing
+   * changed", which is the opposite of what an invalidation is for.
+   *
+   * So the producer states the key it was addressed by, and a consumer compares names. Present only
+   * where the two genuinely differ — `sessions` and `files` address items by the id they were given,
+   * and an absent `key` means exactly that.
+   */
+  readonly key?:      string;
   readonly operation: 'saved' | 'deleted';
   readonly detail?:   unknown;
 }
@@ -221,14 +236,22 @@ export function scopedNotifier(notifier: Notifier, plugin: string): Notifier {
  * partition for visibility filtering). It observes writes made THROUGH it — a second process, or a
  * writer that bypassed this store, is not seen; that is what a backend's own watch, where one exists,
  * is for.
+ *
+ * `keyOf` supplies {@link ItemChange.key} for a namespace whose document ids are DERIVED from the
+ * caller's key (settings: a plugin name slugged to a legal id) — a function of the id rather than a
+ * constant, because this wraps a whole store and a per-document answer is the only honest shape.
+ * Omit it where the id IS the key, which is every other namespace today.
  */
 export function notifyingStore<T extends { id: string; version: string }>(
   store: Store<T>, notifier: Notifier, namespace: string, source: string,
+  keyOf?: (id: string) => string | undefined,
 ): Store<T> {
   const announce = (operation: 'saved' | 'deleted', id: string): void => {
     const principal = tryCurrentPrincipal();
+    const key       = keyOf?.(id);
     notifier.notify({
       kind: ItemChangeKind, source, operation, namespace, id,
+      ...(key !== undefined ? { key } : {}),
       ...(principal !== undefined ? { principal } : {}),
     });
   };

package/src/types/tools.ts

@@ -105,6 +105,17 @@ export interface ToolContract<Result, Args = unknown> {
   readonly [ARGS]:   Args;
 }
 
+/**
+ * The params of a tool that takes none — an object with no properties.
+ *
+ * Spelled out because both obvious alternatives are wrong. **`{}` is not the empty object type**: in
+ * TypeScript it means "any non-nullish value", so `ToolContract<R, {}>` accepts `'hello'` and `42` and
+ * describes nothing. And **omitting `Args` is looser still**: it defaults to `unknown`, which a
+ * validator can only pass, so a caller sending `null` — or anything at all — is accepted. Both read as
+ * "no parameters" and neither says it.
+ */
+export type NoParams = Record<string, never>;
+
 type ToolResultArmed<E>           = E extends ToolContract<unknown, unknown> ? true : false;
 type ToolResultUnion<E>           = E extends ToolContract<infer R, unknown> ? R : never;
 type ToolResultMatched<E, P>      = E extends ToolContract<infer R, infer A> ? (P extends A ? R : never) : never;

package/src/types/vault.ts

@@ -22,6 +22,18 @@ export interface VaultSpec {
    * reverse-index omit it, and `createSecret`'s dedup step is skipped.
    */
   findByValue?(value: string): string | undefined;
+  /**
+   * Why this backend cannot store a secret under `name` — `undefined` when it can. What is storable
+   * is the *backend's* business: an in-memory map takes anything referenceable, a `.env`-backed one
+   * takes environment-variable names, a header-based one may exclude `:`.
+   *
+   * The returned string is the RULE, phrased for whoever must now choose another name (often an LLM
+   * that invented the rejected one), not a restatement of the failure — it is the only place that
+   * knowledge exists, and it is what rides on the thrown {@link InvalidSecretNameError}. Enforced by
+   * `assertStorableKey`, which every backend's `writeSecret` calls before storing; a backend omitting
+   * this method accepts any name.
+   */
+  unstorableKey?(name: string): string | undefined;
 }
 
 export interface Vault extends VaultSpec {

package/src/vault.ts

@@ -1,4 +1,34 @@
 import type { VaultSpec } from './types.js';
+import { invalidSecretNameError } from './errors.js';
+
+/**
+ * The rule every vault shares, whatever else it adds: a secret is only reachable through a
+ * `${NAME}` placeholder, so a name carrying whitespace, `$`, `{` or `}` — or no characters at all —
+ * can be written and never read back. Backends narrow this (see `EnvFileVault`); none widen it.
+ */
+export const REFERENCEABLE_KEY_RULE =
+  'a secret name must be non-empty and contain no whitespace, `$`, `{` or `}`, so that it can be referenced as ${NAME}';
+
+/** The shared base policy, for a backend whose `unstorableKey` adds nothing of its own. */
+export function unreferenceableKey(name: string): string | undefined {
+  return /^[^\s${}]+$/.test(name) ? undefined : REFERENCEABLE_KEY_RULE;
+}
+
+/**
+ * Refuse a name the backend cannot store, rather than writing something that silently disappears —
+ * the `.env` line systemd discards, the header a proxy strips. Called by every backend's
+ * `writeSecret` before it stores, which is the one point that still knows the requested name:
+ * `createSecret` may canonicalise it away, and by the time a reader misses the secret there is
+ * nothing left to blame.
+ *
+ * Removal (`writeSecret(name, '')`) deliberately does not go through here — a name that became
+ * unstorable, or arrived from an environment snapshot that never passed the policy, must still be
+ * deletable.
+ */
+export function assertStorableKey(spec: VaultSpec, name: string): void {
+  const rule = spec.unstorableKey?.(name);
+  if (rule !== undefined) throw invalidSecretNameError(name, rule);
+}
 
 /**
  * The `createSecret` policy, written once over the spec primitives so every backend behaves