@matatbread/matbot-plugin-api 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"
   },

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/principal-context.ts

@@ -23,8 +23,9 @@ export interface PrincipalCarrier {
   /**
    * Establish `principal` for the dynamic extent of `fn` and return whatever `fn` returns. On node
    * this is per-async-flow (concurrent turns stay isolated); nesting cleanly shadows-and-restores,
-   * which is how in-flow delegation works. Consume any async iterable *inside* `fn` — returning an
-   * unconsumed iterator drops the scope before it is pulled.
+   * which is how in-flow delegation works. An implementation establishes the scope and nothing more:
+   * deferred work returned out of it (an unpulled iterator, a promise of one) is {@link runAs}'s to
+   * re-establish, and doing it here as well would only nest the same identity twice.
    */
   run<T>(principal: Principal, fn: () => T): T;
   /**
@@ -71,7 +72,75 @@ export function tryCurrentPrincipal(): Principal | undefined {
 
 /** Run `fn` with `principal` established as the ambient identity for its async extent. */
 export function runAs<T>(principal: Principal, fn: () => T): T {
-  return need().run(principal, fn);
+  const carrier = need();
+  return carrier.run(principal, () => rescope(carrier, principal, fn()));
+}
+
+// A generator's body does not begin until the first pull, so an iterator returned out of the scope carries
+// its whole extent with it: `fn` established the identity for the *construction*, and the work then runs in
+// whatever flow happens to pull it. The tool ABI returns exactly that shape (`executor.execute()`), so the
+// natural thing to write at a tool seam was the broken thing — silently, since a host that entered a boot
+// principal reads a plausible one rather than throwing. Re-establishing per pull rather than requiring the
+// caller to consume inside `fn`: the principal is a re-entrant label that grants nothing, and nesting
+// already shadows-and-restores, so re-entering costs nothing semantically — which is also what makes nesting
+// unremarkable: `runAs(A, () => runAs(B, () => gen()))` stacks two wrappers and every pull resolves to B,
+// the same answer plain nesting gives with no iterator in sight. Deliberately NOT extended to
+// `machineBusy` or `withUsageScope`, whose shape is identical but whose hold and roll-up settle when `fn`
+// does — a resource with a settle edge cannot be re-entered per pull, only an identity can.
+function rescope<T>(carrier: PrincipalCarrier, principal: Principal, value: T): T {
+  if (isAsyncIterator(value)) return scopedIterator(carrier, principal, value) as T;
+  // `async () => execute(...)` defers the identical body behind one await. This DERIVES a promise rather
+  // than intercepting one, which is why a single `then` covers it: `catch`/`finally` on what the caller
+  // receives are downstream of the rescope, and a rejection is a value rather than a deferred body, so an
+  // `onRejected` would have nothing to re-establish and would cost the rejection's identity. Native only —
+  // `PromiseLike.then` need not return a promise, so adopting a thenable would replace an object the caller
+  // may use for more than awaiting (a chainable query builder), and `async` produces the native one anyway.
+  if (value instanceof Promise) return value.then(inner => rescope(carrier, principal, inner)) as T;
+  return value;
+}
+
+// Iterator-shaped, not merely async-iterable. A ReadableStream is `for await`-able too, and CAN be proxied
+// (measured: `instanceof`, `pipeTo` and a platform `new Response(stream)` all survive one) — but only two of
+// its pull paths could then be re-entered, `[Symbol.asyncIterator]` and `getReader().read()`, while
+// `pipeTo`/`pipeThrough`/`tee` pull from platform internals no wrapper reaches. A conditional guarantee is
+// worse than none in an identity primitive: a host testing with `for await` and shipping `pipeTo` would
+// regress silently. Its eager half is safe either way — `start()` runs at construction, inside the scope —
+// so what is uncovered is a lazy `pull()` that reads the principal, which no in-repo streamer is: every one
+// is an async generator, and `FileHandle.stream()` is `AsyncIterable` by contract. Carrying `next` is then
+// taken to mean the value IS the iterator — what a caller holding `execute()`'s result has — rather than a
+// factory for fresh ones, a thing it cannot also be.
+function isAsyncIterator(value: unknown): value is AsyncIterator<unknown> & AsyncIterable<unknown> {
+  return typeof value === 'object' && value !== null
+    && typeof (value as AsyncIterable<unknown>)[Symbol.asyncIterator] === 'function'
+    && typeof (value as AsyncIterator<unknown>).next === 'function';
+}
+
+function scopedIterator<T>(
+  carrier:   PrincipalCarrier,
+  principal: Principal,
+  source:    AsyncIterator<T> & AsyncIterable<T>,
+): AsyncIterableIterator<T> {
+  const inScope = <R>(f: () => R): R => carrier.run(principal, f);
+  // A Proxy rather than a fresh object literal: the value crossing back out must still BE what it was —
+  // a custom iterator's own methods, its prototype, `instanceof` — so only the pull points are replaced.
+  // Anything else is forwarded bound to the target, which a class-based iterator holding internal state
+  // (or an object with internal slots) requires.
+  const pulls: Record<PropertyKey, unknown> = {
+    [Symbol.asyncIterator]: () => proxy,
+    next:   (...args: [] | [undefined]) => inScope(() => source.next(...args)),
+    ...(source.return !== undefined ? { return: (value?: unknown) => inScope(() => source.return!(value)) } : {}),
+    ...(source.throw  !== undefined ? { throw:  (error?: unknown) => inScope(() => source.throw!(error))  } : {}),
+  };
+  const proxy = new Proxy(source, {
+    // `hasOwn`, not `in`: the latter reaches Object.prototype, which would serve `toString`/`constructor`
+    // off the lookup object instead of the iterator being wrapped.
+    get(target, prop) {
+      if (Object.hasOwn(pulls, prop)) return pulls[prop];
+      const value = Reflect.get(target, prop, target);
+      return typeof value === 'function' ? value.bind(target) : value;
+    },
+  }) as AsyncIterableIterator<T>;
+  return proxy;
 }
 
 /** Imperatively establish `principal` for the current flow (entry points only). */

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