@wrongstack/core 0.313.0 → 0.316.1

package/dist/chunk-TCCHINEF.js

@@ -0,0 +1,655 @@
+import {
+  applyToolDescriptionModeToTool,
+  normalizeToolDescriptionMode
+} from "./chunk-WQTOVMGV.js";
+import {
+  estimateToolDefTokens
+} from "./chunk-HMLIGAU7.js";
+import {
+  ERROR_CODES,
+  WrongStackError
+} from "./chunk-25LSLC3G.js";
+import {
+  toErrorMessage
+} from "./chunk-TBRL2RCC.js";
+
+// src/registry/provider-registry.ts
+var ProviderRegistry = class {
+  factories = /* @__PURE__ */ new Map();
+  /**
+   * Register a provider factory. If a factory with the same type already
+   * exists, it is replaced. Use this for both initial registration and
+   * runtime overrides (e.g. from plugins or CLI flags).
+   */
+  register(f) {
+    this.factories.set(f.type, f);
+  }
+  /**
+   * Bulk-register multiple provider factories at once.
+   */
+  registerAll(factories) {
+    for (const f of factories) this.register(f);
+  }
+  /**
+   * Override an existing factory. Throws if no factory is registered
+   * for the given type. Use this to safely replace a provider at runtime
+   * (e.g. in tests or when a plugin provides a custom implementation).
+   */
+  override(type, f) {
+    if (!this.factories.has(type)) {
+      throw new Error(`Provider type "${type}" not registered; cannot override`);
+    }
+    this.factories.set(type, f);
+  }
+  has(type) {
+    return this.factories.has(type);
+  }
+  /**
+   * Unregister a provider factory by type. Returns true if a factory was
+   * removed, false if none was registered for that type.
+   */
+  unregister(type) {
+    return this.factories.delete(type);
+  }
+  create(cfg, factoryType = cfg.type) {
+    const f = this.factories.get(factoryType);
+    if (!f) {
+      throw new Error(
+        `Provider type "${factoryType}" not registered. Available: ${Array.from(this.factories.keys()).join(", ")}`
+      );
+    }
+    return f.create(cfg);
+  }
+  list() {
+    return Array.from(this.factories.keys());
+  }
+};
+
+// src/registry/slash-command-registry.ts
+var SlashCommandRegistry = class {
+  cmds = /* @__PURE__ */ new Map();
+  /**
+   * Register a command.
+   *
+   * Trust tiers, by `owner` and `opts.official`:
+   *
+   *  - **Built-ins** (`owner === 'core'`) and **official plugins**
+   *    (`opts.official === true`, set by the host only for first-party plugins
+   *    loaded from the built-in factory list) claim the **bare** command name
+   *    (`/prompts`). They may override one another — last write wins — so an
+   *    official plugin can replace a built-in. Official plugins are *also*
+   *    reachable under their `owner:name` namespace.
+   *  - **External plugins** (any other `owner`) are isolated under the
+   *    `owner:name` namespace: invocable only as `/owner:cmd`, never by bare
+   *    name, and unable to shadow or override a built-in or official command.
+   *
+   * Officiality is supplied by the host based on the plugin's load source, not
+   * self-declared by the plugin — an external plugin cannot name itself into
+   * the official tier.
+   */
+  register(cmd, owner = "core", opts) {
+    const isPlugin = owner !== "core";
+    const official = !isPlugin || opts?.official === true;
+    if (official) {
+      const existing = this.cmds.get(cmd.name);
+      if (existing) {
+        const existingIsOfficialPlugin = existing.official && existing.owner !== "core";
+        if (!isPlugin && existingIsOfficialPlugin) {
+          return;
+        }
+        if (!isPlugin && existing.owner === "core") return;
+      }
+      this.cmds.set(cmd.name, { cmd, owner, official });
+      for (const a of cmd.aliases ?? []) {
+        this.cmds.set(a, { cmd, owner, official });
+      }
+    }
+    if (isPlugin) {
+      this.cmds.set(`${owner}:${cmd.name}`, { cmd, owner, official });
+      for (const a of cmd.aliases ?? []) {
+        this.cmds.set(`${owner}:${a}`, { cmd, owner, official });
+      }
+    }
+  }
+  unregister(name) {
+    const entry = this.cmds.get(name);
+    if (!entry) return false;
+    for (const [key, e] of this.cmds.entries()) {
+      if (e.cmd === entry.cmd) this.cmds.delete(key);
+    }
+    return true;
+  }
+  /**
+   * Bulk-register multiple slash commands at once.
+   */
+  registerAll(cmds, owner = "core") {
+    for (const cmd of cmds) this.register(cmd, owner);
+  }
+  get(name) {
+    return this.cmds.get(name)?.cmd;
+  }
+  ownerOf(name) {
+    return this.cmds.get(name)?.owner;
+  }
+  list() {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const { cmd } of this.cmds.values()) {
+      if (!seen.has(cmd)) {
+        seen.add(cmd);
+        out.push(cmd);
+      }
+    }
+    return out;
+  }
+  listWithOwner() {
+    const seen = /* @__PURE__ */ new Set();
+    const out = [];
+    for (const [fullName, { cmd, owner }] of this.cmds.entries()) {
+      if (!seen.has(cmd)) {
+        seen.add(cmd);
+        out.push({ cmd, owner, fullName });
+      }
+    }
+    return out;
+  }
+  /**
+   * Parse a slash command line. Accepts both:
+   *   `/cmd args`          → builtin command (owner=core)
+   *   `/pluginName:cmd args` → plugin command
+   * The command name is split at the first `:` if the prefix matches a known owner.
+   */
+  async dispatch(line, ctx) {
+    if (!line.startsWith("/")) return null;
+    const trimmed = line.slice(1);
+    const spaceIdx = trimmed.indexOf(" ");
+    const firstColonIdx = trimmed.indexOf(":");
+    let name;
+    let args;
+    if (firstColonIdx !== -1 && (spaceIdx === -1 || firstColonIdx < spaceIdx)) {
+      const prefix = trimmed.slice(0, firstColonIdx);
+      name = trimmed.slice(0, spaceIdx === -1 ? void 0 : spaceIdx);
+      args = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1);
+      const entry2 = this.cmds.get(name);
+      if (!entry2 || entry2.owner !== prefix) {
+        name = trimmed.slice(0, spaceIdx === -1 ? void 0 : spaceIdx);
+        args = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1);
+      }
+    } else {
+      name = trimmed.slice(0, spaceIdx === -1 ? void 0 : spaceIdx);
+      args = spaceIdx === -1 ? "" : trimmed.slice(spaceIdx + 1);
+    }
+    const entry = this.cmds.get(name);
+    if (!entry) {
+      return { message: `Unknown command "/${name}". Type /help for a list.` };
+    }
+    try {
+      const res = await entry.cmd.run(args, ctx);
+      return res ?? {};
+    } catch (err) {
+      const msg = toErrorMessage(err);
+      return { message: `Command "/${name}" failed: ${msg}` };
+    }
+  }
+};
+
+// src/registry/tool-registry.ts
+var ToolRegistry = class _ToolRegistry {
+  tools = /* @__PURE__ */ new Map();
+  descriptionModes = /* @__PURE__ */ new Map();
+  /**
+   * Disabled tool names plus the audit-trail metadata explaining WHY each
+   * one was disabled. `user` is the historical default (manual
+   * `/tool disable`); `auto-thinned` is the new path the auto-thinning
+   * pipeline writes so `/tool autothin undo` can restore the right subset.
+   * The underlying tool data stays in `_tools` so re-enable is constant-time.
+   */
+  _disabled = /* @__PURE__ */ new Map();
+  /**
+   * Optional EventBus used by `thinUnderused()` to emit `tool.thinned`.
+   * Set via `setEventBus()` at boot — optional so the registry stays
+   * usable in pure unit tests and in code paths that never run the
+   * auto-thinning pipeline.
+   */
+  _events;
+  /** Monotonic version bumped on every registry mutation. */
+  _version = 0;
+  /** Cached `list()` result, frozen after build. Invalidated on _version change. */
+  _listSnapshot;
+  _listSnapshotVersion = -1;
+  /**
+   * Optional direct provider surface. `undefined` preserves the legacy
+   * behaviour (every enabled catalog tool is direct); when set, `list()` still
+   * exposes the complete executable catalog while `listForProvider()` returns
+   * only these names. This keeps lazy tools discoverable by tool_search/tool_use.
+   */
+  _providerToolNames;
+  _providerListSnapshot;
+  _providerListSnapshotVersion = -1;
+  /** Pre-compute tool definition token estimate once at registration time. */
+  _stampDefTokens(tool) {
+    if (tool._estDefTokens === void 0) {
+      tool._estDefTokens = estimateToolDefTokens(tool);
+    }
+  }
+  /** Apply the description mode transform and stamp token estimates. */
+  _prepareForStorage(tool) {
+    const mode = this.descriptionModes.get(tool.name) ?? "extend";
+    return applyToolDescriptionModeToTool(tool, mode);
+  }
+  register(tool, owner = "core") {
+    if (this.tools.has(tool.name)) {
+      throw new WrongStackError({
+        message: `Tool "${tool.name}" already registered`,
+        code: ERROR_CODES.REGISTRY_DUPLICATE,
+        subsystem: "container",
+        context: { tool: tool.name }
+      });
+    }
+    if (!tool.inputSchema || typeof tool.inputSchema !== "object") {
+      throw new WrongStackError({
+        message: `Tool "${tool.name}" has an invalid or missing inputSchema`,
+        code: ERROR_CODES.REGISTRY_INVALID,
+        subsystem: "container",
+        context: { tool: tool.name }
+      });
+    }
+    const stored = this._prepareForStorage(tool);
+    this._stampDefTokens(stored);
+    this.tools.set(tool.name, { tool: stored, owner });
+    this._version++;
+  }
+  /**
+   * Attempt to register a tool. Returns true if successful, false if a tool
+   * with the same name is already registered. Useful in multi-agent or plugin
+   * scenarios where duplicate registration may be intentional.
+   */
+  tryRegister(tool, owner = "core") {
+    if (this.tools.has(tool.name)) return false;
+    if (!tool.inputSchema || typeof tool.inputSchema !== "object") {
+      return false;
+    }
+    const stored = this._prepareForStorage(tool);
+    this._stampDefTokens(stored);
+    this.tools.set(tool.name, { tool: stored, owner });
+    this._version++;
+    return true;
+  }
+  /**
+   * Bulk-register multiple tools at once. Each tool that conflicts with an
+   * existing registration is silently skipped — use `registerAllOrThrow`
+   * if you want it to throw on conflicts.
+   */
+  registerAll(tools, owner = "core") {
+    for (const tool of tools) this.tryRegister(tool, owner);
+  }
+  /**
+   * Bulk-register and throw on the first conflict. Use when you need
+   * strict registration (e.g. at boot time).
+   */
+  registerAllOrThrow(tools, owner = "core") {
+    for (const tool of tools) this.register(tool, owner);
+  }
+  /**
+   * Register a tool as a default. If the tool name is already registered,
+   * this is a no-op — the existing registration (from core or another
+   * plugin) takes precedence. Use `override` to intentionally replace.
+   */
+  registerDefault(tool, owner = "core") {
+    if (this.tools.has(tool.name)) return;
+    const stored = this._prepareForStorage(tool);
+    this._stampDefTokens(stored);
+    this.tools.set(tool.name, { tool: stored, owner });
+    this._version++;
+  }
+  unregister(name) {
+    const deleted = this.tools.delete(name);
+    if (deleted) this._version++;
+    return deleted;
+  }
+  /**
+   * Override an existing tool. Throws if the tool is not already registered.
+   * Plugins use this to replace built-in tools with custom implementations.
+   */
+  override(name, tool, owner = "core") {
+    if (!this.tools.has(name)) {
+      throw new WrongStackError({
+        message: `Tool "${name}" not registered; cannot override`,
+        code: ERROR_CODES.REGISTRY_NOT_FOUND,
+        subsystem: "container",
+        context: { tool: name }
+      });
+    }
+    const stored = this._prepareForStorage(tool);
+    this._stampDefTokens(stored);
+    this.tools.set(name, { tool: stored, owner });
+    this._version++;
+  }
+  /**
+   * Wrap (decorate) an existing tool. The wrapper receives the current
+   * tool and must return a new tool — typically the same tool with a
+   * wrapped `execute` or `executeStream`. Throws if the tool is not
+   * registered.
+   *
+   * Multiple wraps stack: each wrapper gets the output of the previous.
+   *
+   * @example
+   * registry.wrap('bash', (t) => ({ ...t, permission: 'confirm' }));
+   */
+  wrap(name, wrapper, owner = "core") {
+    const entry = this.tools.get(name);
+    if (!entry) {
+      throw new WrongStackError({
+        message: `Tool "${name}" not registered; cannot wrap`,
+        code: ERROR_CODES.REGISTRY_NOT_FOUND,
+        subsystem: "container",
+        context: { tool: name }
+      });
+    }
+    const current = applyToolDescriptionModeToTool(entry.tool, "extend");
+    const wrapped = this._prepareForStorage(wrapper(current));
+    wrapped._estDefTokens = void 0;
+    this._stampDefTokens(wrapped);
+    this.tools.set(name, { tool: wrapped, owner: `${entry.owner}+${owner}` });
+    this._version++;
+  }
+  setDescriptionMode(name, mode) {
+    const normalized = normalizeToolDescriptionMode(mode);
+    if (!normalized) return false;
+    const entry = this.tools.get(name);
+    if (!entry) return false;
+    if (normalized === "extend") {
+      this.descriptionModes.delete(name);
+    } else {
+      this.descriptionModes.set(name, normalized);
+    }
+    const stored = applyToolDescriptionModeToTool(entry.tool, normalized);
+    stored._estDefTokens = void 0;
+    this._stampDefTokens(stored);
+    this.tools.set(name, { ...entry, tool: stored });
+    this._version++;
+    return true;
+  }
+  getDescriptionMode(name) {
+    return this.descriptionModes.get(name) ?? "extend";
+  }
+  applyDescriptionModes(modes = {}) {
+    const missing = [];
+    let applied = 0;
+    for (const [name, rawMode] of Object.entries(modes)) {
+      const mode = normalizeToolDescriptionMode(rawMode);
+      if (!mode) continue;
+      if (this.tools.has(name)) {
+        if (this.setDescriptionMode(name, mode)) applied++;
+      } else {
+        if (mode === "simple") this.descriptionModes.set(name, mode);
+        else this.descriptionModes.delete(name);
+        missing.push(name);
+      }
+    }
+    return { applied, missing };
+  }
+  get(name) {
+    if (this._disabled.has(name)) return void 0;
+    return this.tools.get(name)?.tool;
+  }
+  ownerOf(name) {
+    return this.tools.get(name)?.owner;
+  }
+  // ── Disable / enable ────────────────────────────────────────────
+  /** Attach the EventBus so `thinUnderused()` can emit `tool.thinned`.
+   *  Idempotent; safe to call multiple times at boot. */
+  setEventBus(events) {
+    this._events = events;
+  }
+  /**
+   * Disable a tool by name. The tool is removed from all public accessors
+   * (list(), get(), listByCategory(), listWithOwner()) so it does NOT
+   * appear in the system prompt or provider request. The underlying
+   * registration is preserved in memory — use `enable()` to restore it.
+   *
+   * `reason` defaults to `'user'` for backward compatibility — every
+   * historical caller (CLI `/tool disable`, WebUI, subagent filter)
+   * writes a user-authored disable. The auto-thinning pipeline always
+   * passes `'auto-thinned'`.
+   *
+   * @returns `true` if the tool was found and disabled; `false` if the
+   *          tool is not registered or is already disabled.
+   */
+  disable(name, reason = "user", meta) {
+    if (!this.tools.has(name) || this._disabled.has(name)) return false;
+    this._disabled.set(name, {
+      reason,
+      at: Date.now(),
+      ...meta?.caller ? { caller: meta.caller } : {}
+    });
+    this._version++;
+    return true;
+  }
+  /**
+   * Re-enable a previously disabled tool. The tool reappears in all
+   * public accessors and will be included in the next system prompt /
+   * provider request.
+   *
+   * @returns `true` if the tool was disabled and is now re-enabled;
+   *          `false` if the tool was not disabled.
+   */
+  enable(name) {
+    if (!this._disabled.has(name)) return false;
+    this._disabled.delete(name);
+    this._version++;
+    return true;
+  }
+  /**
+   * Re-enable ALL currently disabled tools at once. Returns the number
+   * of tools that were re-enabled.
+   */
+  enableAll() {
+    const count = this._disabled.size;
+    if (count === 0) return 0;
+    this._disabled.clear();
+    this._version++;
+    return count;
+  }
+  /**
+   * Re-enable only the tools that were disabled by the auto-thinning
+   * pipeline (`reason === 'auto-thinned'` in `disabledToolMeta`). Manual
+   * user disables are preserved. Returns the names that were re-enabled.
+   */
+  enableAutoThinned() {
+    const restored = [];
+    for (const [name, meta] of this._disabled) {
+      if (meta.reason === "auto-thinned") {
+        this._disabled.delete(name);
+        restored.push(name);
+      }
+    }
+    if (restored.length > 0) this._version++;
+    return restored;
+  }
+  /**
+   * Check whether a tool is currently disabled.
+   */
+  isDisabled(name) {
+    return this._disabled.has(name);
+  }
+  /** Return the audit-trail metadata for a disabled tool, if any. */
+  disabledMeta(name) {
+    return this._disabled.get(name);
+  }
+  /**
+   * Apply a list of tool names to disable. Tools not in the registry
+   * are silently ignored so config can reference future tools without
+   * error. Returns the number of tools actually disabled. Always
+   * tagged `reason: 'user'` — the auto-thinning pipeline uses
+   * `thinUnderused()` instead.
+   */
+  applyDisabled(names) {
+    let count = 0;
+    for (const name of names) {
+      if (this.disable(name, "user")) count++;
+    }
+    return count;
+  }
+  /**
+   * Apply the audit-trail metadata for a previously-disabled tool.
+   * Used at boot to restore `disabledToolMeta` (so the auto-thinned
+   * decision survives a restart). Does NOT mutate the disabled set
+   * itself — pair with `applyDisabled()` on the same names.
+   */
+  applyDisabledMeta(meta) {
+    let count = 0;
+    const at = Date.now();
+    for (const [name, entry] of Object.entries(meta)) {
+      if (!this._disabled.has(name)) continue;
+      this._disabled.set(name, { ...entry, at: entry.at ?? at });
+      count++;
+    }
+    if (count > 0) this._version++;
+    return count;
+  }
+  /**
+   * Disable every name in `candidates` that is currently registered and
+   * not already disabled, tagged with `reason: 'auto-thinned'`. Emits
+   * a `tool.thinned` event with the names that actually flipped.
+   *
+   * @returns `{ thinned, skipped }` so the caller can persist the
+   *  decision to `disabledToolMeta` and report what was changed.
+   */
+  thinUnderused(candidates, caller) {
+    const thinned = [];
+    const skipped = [];
+    const at = Date.now();
+    for (const name of candidates) {
+      if (!this.tools.has(name)) {
+        skipped.push(name);
+        continue;
+      }
+      if (this._disabled.has(name)) {
+        skipped.push(name);
+        continue;
+      }
+      this._disabled.set(name, { reason: "auto-thinned", at, caller });
+      thinned.push(name);
+    }
+    if (thinned.length > 0) {
+      this._version++;
+      this._events?.emit("tool.thinned", { names: thinned, reason: caller, at });
+    }
+    return { thinned, skipped };
+  }
+  /**
+   * Return the list of all disabled tool entries (tool + owner + reason).
+   * Useful for the /tools slash command to show disabled tools alongside
+   * enabled ones, and for `/tool autothin status` to count the auto-thinned subset.
+   */
+  listDisabled() {
+    const out = [];
+    for (const [name, meta] of this._disabled) {
+      const entry = this.tools.get(name);
+      if (!entry) continue;
+      out.push({ tool: entry.tool, owner: entry.owner, meta });
+    }
+    return out;
+  }
+  list() {
+    if (this._listSnapshot && this._version === this._listSnapshotVersion) {
+      return this._listSnapshot;
+    }
+    const arr = Array.from(this.tools.entries()).filter(([name]) => !this._disabled.has(name)).map(([, entry]) => entry.tool);
+    this._listSnapshot = arr;
+    this._listSnapshotVersion = this._version;
+    return arr;
+  }
+  /** Replace the direct provider surface. Pass `undefined` to expose the catalog. */
+  setProviderToolNames(names) {
+    this._providerToolNames = names ? new Set(names) : void 0;
+    this._version++;
+  }
+  /** Add registered or future tool names to the direct provider surface. */
+  exposeToProvider(names) {
+    if (!this._providerToolNames) return;
+    for (const name of typeof names === "string" ? [names] : names) {
+      this._providerToolNames.add(name);
+    }
+    this._version++;
+  }
+  /** Tools serialized into provider requests and described by the system prompt. */
+  listForProvider() {
+    if (!this._providerToolNames) return this.list();
+    if (this._providerListSnapshot && this._version === this._providerListSnapshotVersion) {
+      return this._providerListSnapshot;
+    }
+    const arr = Array.from(this.tools.entries()).filter(([name]) => !this._disabled.has(name) && this._providerToolNames?.has(name) === true).map(([, entry]) => entry.tool);
+    this._providerListSnapshot = arr;
+    this._providerListSnapshotVersion = this._version;
+    return arr;
+  }
+  /**
+   * Whether an enabled catalog tool is part of the direct provider surface.
+   *
+   * This is intentionally different from `get()`/`list()`: a tool can remain
+   * executable through a lazy gateway while its schema is omitted from the
+   * next provider request. Disabled and unknown tools always return false.
+   */
+  isExposedToProvider(name) {
+    if (this._disabled.has(name) || !this.tools.has(name)) return false;
+    return this._providerToolNames?.has(name) ?? true;
+  }
+  /**
+   * Group tools by their `category` field. Tools without a category
+   * are placed under the key `""` (empty string). Returns a Map of
+   * category → tools, sorted by registration order within each category.
+   */
+  listByCategory() {
+    const map = /* @__PURE__ */ new Map();
+    for (const [name, { tool }] of this.tools) {
+      if (this._disabled.has(name)) continue;
+      const cat = tool.category ?? "";
+      let group = map.get(cat);
+      if (!group) {
+        group = [];
+        map.set(cat, group);
+      }
+      group.push(tool);
+    }
+    return map;
+  }
+  listWithOwner() {
+    return Array.from(this.tools.entries()).filter(([name]) => !this._disabled.has(name)).map(([, entry]) => entry);
+  }
+  clear() {
+    this.tools.clear();
+    this.descriptionModes.clear();
+    this._disabled.clear();
+    this._providerToolNames = void 0;
+    this._version++;
+  }
+  /**
+   * Return a new ToolRegistry with the same registered tools and owners.
+   * Useful for creating filtered copies in multi-agent scenarios.
+   */
+  clone() {
+    const copy = new _ToolRegistry();
+    copy.descriptionModes.clear();
+    for (const [name, mode] of this.descriptionModes) {
+      copy.descriptionModes.set(name, mode);
+    }
+    for (const [name, { tool, owner }] of this.tools) {
+      copy.tools.set(name, { tool, owner });
+    }
+    for (const [name, meta] of this._disabled) {
+      copy._disabled.set(name, { ...meta });
+    }
+    copy._providerToolNames = this._providerToolNames ? new Set(this._providerToolNames) : void 0;
+    copy._version = this._version;
+    return copy;
+  }
+};
+
+export {
+  ProviderRegistry,
+  SlashCommandRegistry,
+  ToolRegistry
+};
+//# sourceMappingURL=chunk-TCCHINEF.js.map