@matatbread/matbot-plugin-api 0.2.0 → 0.2.1

package/package.json

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

package/src/context-switch.ts

@@ -1,5 +1,6 @@
 import type { Principal } from './types.js';
 import { runAs } from './principal-context.js';
+import { globalSlot } from './global-state.js';
 
 /**
  * A context switch is the machine analogue of an OS one: it pages in any pending machine state and
@@ -19,9 +20,19 @@ import { runAs } from './principal-context.js';
  * baseline and is never counted.
  */
 
-const quiescers = new Set<() => void>();
-let depth = 0;
-let flushing = false;
+// State-shaped and reachable from a plugin (a storage plugin registering a deferred-swap flusher, or
+// switching context), so it lives in the global slot: a duplicated plugin-api copy shares one set of
+// quiescers and one depth count rather than splitting them. See ./global-state.ts.
+interface ContextSwitchState {
+  quiescers: Set<() => void>;
+  depth:     number;
+  flushing:  boolean;
+}
+const cs = globalSlot<ContextSwitchState>('context-switch', () => ({
+  quiescers: new Set<() => void>(),
+  depth:     0,
+  flushing:  false,
+}));
 
 /**
  * Register a machine-update flush, run at every quiescent edge (no context active). Flushers MUST be
@@ -30,8 +41,8 @@ let flushing = false;
  * into the operation that triggered the edge.
  */
 export function onContextQuiesce(flush: () => void): () => void {
-  quiescers.add(flush);
-  return () => { quiescers.delete(flush); };
+  cs.quiescers.add(flush);
+  return () => { cs.quiescers.delete(flush); };
 }
 
 /**
@@ -41,15 +52,15 @@ export function onContextQuiesce(flush: () => void): () => void {
  * it applies immediately, so an idle-time swap doesn't wait for the next request to take effect.
  */
 export function flushIfQuiescent(): void {
-  if (depth !== 0 || flushing) return;
-  flushing = true;
+  if (cs.depth !== 0 || cs.flushing) return;
+  cs.flushing = true;
   try {
-    for (const q of quiescers) {
+    for (const q of cs.quiescers) {
       try { q(); }
       catch (e) { console.error('[matbot] context-quiesce flush threw:', e instanceof Error ? e.message : e); }
     }
   } finally {
-    flushing = false;
+    cs.flushing = false;
   }
 }
 
@@ -60,8 +71,8 @@ export function flushIfQuiescent(): void {
  */
 export function contextSwitch<T>(principal: Principal, fn: () => T): T {
   flushIfQuiescent();
-  depth++;
-  const settle = (): void => { depth--; flushIfQuiescent(); };
+  cs.depth++;
+  const settle = (): void => { cs.depth--; flushIfQuiescent(); };
   let result: T;
   try {
     result = runAs(principal, fn);

package/src/errors.ts

@@ -1,16 +1,43 @@
+/**
+ * matbot's typed errors are **duck-typed, not class-based**: each is a plain `Error` carrying a
+ * `matbot` brand string (the discriminant) plus its data fields. Callers test the brand through the
+ * exported `isX` guards — never `instanceof`.
+ *
+ * Why not classes: plugin-api can be physically duplicated in a skewed install (two copies at
+ * different versions). A class is a per-copy object, so `instanceof MissingSecretError` returns
+ * `false` when the host throws from one copy and a plugin tests with another — silently breaking
+ * error handling across the boundary. A brand string is identity-independent, so the guard holds no
+ * matter how many copies are loaded. See docs/duplicate-singletons.md.
+ *
+ * The interfaces are kept named `XError` so existing `import type { XError }` annotations and field
+ * access (`e.missingKeys`) survive; only construction (`new XError()` → `xError()`) and detection
+ * (`instanceof XError` → `isXError()`) change.
+ */
+
+const BRAND = 'matbot';
+
+export type MatbotErrorKind = 'MissingSecret' | 'IncompatibleRuntime' | 'NotAPlugin' | 'PromptCancelled';
+
+function isKind(e: unknown, kind: MatbotErrorKind): boolean {
+  return typeof e === 'object' && e !== null && (e as Record<string, unknown>)[BRAND] === kind;
+}
+
 /**
  * Thrown by Vault.resolve() when one or more ${NAME} placeholders cannot be resolved.
  * `missingKeys` carries the unresolved key names (e.g. `ANTHROPIC_API_KEY`) so callers
  * can prompt for and store them.
  */
-export class MissingSecretError extends Error {
+export interface MissingSecretError extends Error {
+  matbot: 'MissingSecret';
   readonly missingKeys: readonly string[];
-
-  constructor(missingKeys: readonly string[]) {
-    super(`Vault: secret(s) not found: ${missingKeys.join(', ')}`);
-    this.name        = 'MissingSecretError';
-    this.missingKeys = missingKeys;
-  }
+}
+export function missingSecretError(missingKeys: readonly string[]): MissingSecretError {
+  const e = new Error(`Vault: secret(s) not found: ${missingKeys.join(', ')}`);
+  e.name = 'MissingSecretError';
+  return Object.assign(e, { matbot: 'MissingSecret' as const, missingKeys });
+}
+export function isMissingSecretError(e: unknown): e is MissingSecretError {
+  return isKind(e, 'MissingSecret');
 }
 
 /**
@@ -20,18 +47,19 @@ export class MissingSecretError extends Error {
  * fix — this is permanent for the host, so the `add` flow catches it specifically and rolls the
  * specifier back out of matbot.yaml rather than persisting a plugin that can never activate here.
  */
-export class IncompatibleRuntimeError extends Error {
-  readonly specifier:    string;
-  readonly declared:     readonly string[];
-  readonly hostRuntime:  string;
-
-  constructor(specifier: string, declared: readonly string[], hostRuntime: string) {
-    super(`Cannot load plugin "${specifier}": declares matbotRuntime [${declared.join(', ')}], host runtime is "${hostRuntime}".`);
-    this.name        = 'IncompatibleRuntimeError';
-    this.specifier   = specifier;
-    this.declared    = declared;
-    this.hostRuntime = hostRuntime;
-  }
+export interface IncompatibleRuntimeError extends Error {
+  matbot: 'IncompatibleRuntime';
+  readonly specifier:   string;
+  readonly declared:    readonly string[];
+  readonly hostRuntime: string;
+}
+export function incompatibleRuntimeError(specifier: string, declared: readonly string[], hostRuntime: string): IncompatibleRuntimeError {
+  const e = new Error(`Cannot load plugin "${specifier}": declares matbotRuntime [${declared.join(', ')}], host runtime is "${hostRuntime}".`);
+  e.name = 'IncompatibleRuntimeError';
+  return Object.assign(e, { matbot: 'IncompatibleRuntime' as const, specifier, declared, hostRuntime });
+}
+export function isIncompatibleRuntimeError(e: unknown): e is IncompatibleRuntimeError {
+  return isKind(e, 'IncompatibleRuntime');
 }
 
 /**
@@ -44,16 +72,18 @@ export class IncompatibleRuntimeError extends Error {
  * surfacing this to an LLM should prefer a terminal "not a plugin" message over echoing `reason`,
  * which is phrased as a code-fix instruction the model may try to act on.
  */
-export class NotAPluginError extends Error {
+export interface NotAPluginError extends Error {
+  matbot: 'NotAPlugin';
   readonly specifier: string;
   readonly reason:    string;
-
-  constructor(specifier: string, reason: string) {
-    super(reason);
-    this.name      = 'NotAPluginError';
-    this.specifier = specifier;
-    this.reason    = reason;
-  }
+}
+export function notAPluginError(specifier: string, reason: string): NotAPluginError {
+  const e = new Error(reason);
+  e.name = 'NotAPluginError';
+  return Object.assign(e, { matbot: 'NotAPlugin' as const, specifier, reason });
+}
+export function isNotAPluginError(e: unknown): e is NotAPluginError {
+  return isKind(e, 'NotAPlugin');
 }
 
 /**
@@ -61,9 +91,14 @@ export class NotAPluginError extends Error {
  * decline. Callers awaiting `ctx.prompt()` need not branch on it: the surrounding try/catch turns
  * it into a tool error that closes the tool call, while the host separately abandons the turn.
  */
-export class PromptCancelledError extends Error {
-  constructor(message = 'User cancelled — cannot proceed.') {
-    super(message);
-    this.name = 'PromptCancelledError';
-  }
+export interface PromptCancelledError extends Error {
+  matbot: 'PromptCancelled';
+}
+export function promptCancelledError(message = 'User cancelled — cannot proceed.'): PromptCancelledError {
+  const e = new Error(message);
+  e.name = 'PromptCancelledError';
+  return Object.assign(e, { matbot: 'PromptCancelled' as const });
+}
+export function isPromptCancelledError(e: unknown): e is PromptCancelledError {
+  return isKind(e, 'PromptCancelled');
 }

package/src/global-state.ts

@@ -0,0 +1,39 @@
+/**
+ * Process-global home for matbot's **state-shaped** singletons.
+ *
+ * A skewed install can load two physical copies of plugin-api (a plugin bundling its own copy at a
+ * version that doesn't dedupe with the host's). Module-level state then splits: the host mutates one
+ * copy's state, a plugin reads the other's, and the two never agree. Anchoring that state on
+ * `globalThis` under one well-known key collapses every copy onto a single shared object, so
+ * duplication becomes *benign* rather than corrupting.
+ *
+ * This handles state — Sets, Maps, counters-in-a-container. It deliberately does NOT cover
+ * identity-shaped things (class `instanceof`): a class object is per-copy and can't be shared this
+ * way, which is why plugin-api's typed errors are brand-based instead (see ./errors.ts). And the
+ * principal carrier predates this module and stays on its own established `Symbol.for` key for
+ * backward compatibility with already-published copies — moving it would re-split it in mixed
+ * version trees, the exact bug it fixes. See docs/duplicate-singletons.md.
+ *
+ * Keyed by a registered `Symbol.for` so the lookup is identical across every module copy and
+ * resistant to accidental string-key clashes on `globalThis`.
+ */
+
+const KEY = Symbol.for('@matatbread/matbot.globalState');
+
+type GlobalState = Record<string, unknown>;
+
+function bag(): GlobalState {
+  const g = globalThis as { [KEY]?: GlobalState };
+  return (g[KEY] ??= {});
+}
+
+/**
+ * Return the shared slot named `name`, creating it from `init` on first access. Every copy of every
+ * module that asks for the same `name` gets the same object back, so the state is singular however
+ * many physical copies are loaded. `init` must produce a *container* (object/Map/Set) — primitives
+ * can't be shared by reference, so counters live as fields inside a container.
+ */
+export function globalSlot<T extends object>(name: string, init: () => T): T {
+  const b = bag();
+  return (b[name] ??= init()) as T;
+}