@matatbread/matbot-plugin-api 0.4.11 → 0.4.13

package/package.json

@@ -4,7 +4,7 @@
     "node",
     "browser"
   ],
-  "version": "0.4.11",
+  "version": "0.4.13",
   "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/index.ts

@@ -16,6 +16,7 @@ export * from './bytes.js';
 export * from './store-query.js';
 export * from './errors.js';
 export * from './vault.js';
+export * from './provider-patch.js';
 export * from './session.js';
 export * from './invoke-tool.js';
 

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/provider-patch.ts

@@ -0,0 +1,33 @@
+import type { ProviderConfig } from './types.js';
+import type { ProviderPatch } from './types/builtin-tools.js';
+
+/**
+ * The `provider update` policy, written once so every implementer of it behaves identically — the same
+ * reasoning as `applyCreateSecret` in `vault.ts`. Two hosts apply this patch (the node `provider` tool
+ * against matbot.yaml, the browser bootstrap against its persisted map) and the *semantics* of a patch
+ * must not be one of the things they differ on: `null` clears a field, absent leaves it alone.
+ *
+ * `parameters` is replaced wholesale rather than merged per key. Its values are forwarded to the
+ * endpoint unmodified and so have no shape to merge against — and `provider list` reports them in full,
+ * 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.
+ */
+export function applyProviderPatch(cur: ProviderConfig, patch: ProviderPatch): 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
+  // stop the compiler checking the one thing worth checking here.
+  if (patch.model      !== undefined) next.model = patch.model;
+  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;  }
+  return next;
+}
+
+/** 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

@@ -174,6 +174,31 @@ export interface ProviderActionResult {
   message: string;
 }
 
+/**
+ * The fields `provider update` can change on an existing profile, and the whole of them.
+ *
+ * `null` clears a field, absent leaves it alone — `undefined` cannot mean "clear", since it is already
+ * what an unsupplied optional looks like. `model` takes no `null`: a profile without one is unrunnable.
+ *
+ * Two fields are deliberately absent. **`credentials`**, because it is the one member of a profile that
+ * `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
+ * 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.
+ *
+ * A named shape rather than an inline arm because the browser's `ProviderAdmin.update` takes the same
+ * patch, and because it is the augmentable half — a host whose profiles carry an extra field adds it
+ * here without touching `ToolContracts`.
+ */
+export interface ProviderPatch {
+  model?:      string;
+  endpoint?:   string | null;
+  parameters?: ModelParameters | null;
+  maxRounds?:  number | null;
+}
+
 /**
  * The `provider` tool's contract. Both implementations declare `provider: ProviderToolContract`.
  *
@@ -181,6 +206,8 @@ export interface ProviderActionResult {
  * supplies its own, while node's executor requires one; `credentialKey`/`credentialEnvVar` name where
  * node's vault should hold the secret, and the browser (which prompts and stores under its own key)
  * ignores them.
+ *
+ * `update` carries no credential of any kind — see {@link ProviderPatch}.
  */
 export type ProviderToolContract =
   | ToolContract<ProviderListResult,   { action: 'list' }>
@@ -195,4 +222,5 @@ export type ProviderToolContract =
       parameters?:       ModelParameters;
       maxRounds?:        number;
     }>
+  | ToolContract<ProviderActionResult, { action: 'update'; name: string } & ProviderPatch>
   | ToolContract<ProviderActionResult, { action: 'remove'; name: string }>;

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