Skip to content

Soul-driven AI agent with permission-hardened tools, token budgets, and multi-channel access. Runs 24/7 from CLI, Telegram or More.

10.3 KB
Raw Blame
/**
 * The bridge between running plugins and Mercury's tool loop.
 *
 * Runtimes (in-process and out-of-process) publish their tools here; every
 * CapabilityRegistry (the main agent's, sub-agents', and each bot's) reads
 * them on every turn through `getPluginTools()`. Each call is wrapped:
 *   approval → timeout + cancellation → error capture → result size cap,
 * and the outcome is reported to the plugin manager's circuit breaker.
 *
 * Tool names are namespaced as `<plugin-id>__<tool>`. Built-in tools never
 * contain "__", so the name alone identifies a plugin tool.
 */
import { jsonSchema, tool, type Tool } from 'ai';
import { isMcpToolName } from '../capabilities/mcp/naming.js';
import type { PermissionManager } from '../capabilities/permissions.js';
import {
  TOOL_IMAGE_TYPES,
  attachedImagesNote,
  holdImages,
  resetToolImages,
  screenshotRequest,
  setToolImagesAllowed,
  toolImagesAllowed,
  toolOutputWithImages,
  usableImages,
  type ToolImage,
} from '../capabilities/tool-images.js';
import { logger } from '../utils/logger.js';

export interface LiveTool {
  pluginId: string;
  pluginName: string;
  /** Name declared in the manifest (without namespace). */
  name: string;
  description: string;
  inputSchema: Record<string, unknown>;
  readOnly: boolean;
  timeoutMs: number;
  /**
   * Returns screenshots (manifest `screenshots: true`): each call gets
   * `mercury_screenshot: { include, max_width, max_height }` — the size the
   * current model is best served by, or none for a model that can't see
   * images (ADR-043). The plugin shrinks the capture itself, so coordinates
   * stay in the picture the model saw.
   */
  screenshots?: boolean;
  invoke(args: Record<string, unknown>, signal: AbortSignal): Promise<unknown>;
}

export interface PluginCommandHandler {
  pluginId: string;
  pluginName: string;
  name: string;
  description: string;
  run(args: string, io: { reply(text: string): Promise<void>; signal: AbortSignal }): Promise<void>;
}

const MAX_RESULT_CHARS = 100_000;

export const PLUGIN_IMAGE_TYPES = TOOL_IMAGE_TYPES;

export type PluginImage = ToolImage;

const CONTENT = Symbol('mercury.pluginToolContent');

/** A tool result with images for the model, besides its text. */
export interface PluginToolContent {
  [CONTENT]: true;
  text: string;
  images: PluginImage[];
}

export function toolContent(text: string, images: PluginImage[]): PluginToolContent {
  return { [CONTENT]: true, text, images };
}

function isToolContent(v: unknown): v is PluginToolContent {
  return !!v && typeof v === 'object' && (v as Record<symbol, unknown>)[CONTENT] === true;
}

export function setPluginImagesAllowed(allowed: boolean): void {
  setToolImagesAllowed(allowed);
}

/** Capture once when constructing tools for the current provider request. */
export function currentToolImagesAllowed(): boolean { return toolImagesAllowed(); }

const TOOL_NAME_RE = /^([a-z][a-z0-9-]{1,30}[a-z0-9])__([a-z][a-z0-9_]{0,29})$/;

const liveTools = new Map<string, LiveTool>();
const liveCommands = new Map<string, PluginCommandHandler>();

type OutcomeSink = (pluginId: string, outcome: { ok: true } | { ok: false; error: string; timeout: boolean }) => void;
let outcomeSink: OutcomeSink = () => {};

export function setToolOutcomeSink(sink: OutcomeSink): void {
  outcomeSink = sink;
}

export function pluginToolName(pluginId: string, name: string): string {
  return `${pluginId}__${name}`;
}

/** True for any name shaped like a plugin tool, live or not. */
export function isPluginToolName(name: string): boolean {
  // `mcp__<server>__<tool>` has the same shape but is an MCP tool (ADR-029).
  return !isMcpToolName(name) && TOOL_NAME_RE.test(name);
}

/** A bot may use a plugin tool only when its allow list names it, or the whole plugin ("<id>__*"). */
export function pluginToolAllowed(name: string, allow: readonly string[]): boolean {
  const m = TOOL_NAME_RE.exec(name);
  if (!m || isMcpToolName(name)) return false;
  return allow.includes(name) || allow.includes(`${m[1]}__*`);
}

/** The input parameter through which Mercury sizes a plugin's screenshots (ADR-043). */
export const SCREENSHOT_PARAM = 'mercury_screenshot';

/**
 * A plugin tool's input schema as the model sees it, and whether the tool
 * takes screenshots: declared in the manifest (`screenshots: true`) or by a
 * `mercury_screenshot` parameter in its schema. That parameter is Mercury's
 * to fill, so the model never sees it.
 */
export function screenshotContract(schema: Record<string, unknown>, declared?: boolean): { inputSchema: Record<string, unknown>; screenshots: boolean } {
  const props = schema.properties as Record<string, unknown> | undefined;
  const inSchema = !!props && Object.prototype.hasOwnProperty.call(props, SCREENSHOT_PARAM);
  if (!inSchema) return { inputSchema: schema, screenshots: declared === true };
  const { [SCREENSHOT_PARAM]: _hidden, ...rest } = props!;
  const required = Array.isArray(schema.required) ? (schema.required as unknown[]).filter((r) => r !== SCREENSHOT_PARAM) : schema.required;
  return { inputSchema: { ...schema, properties: rest, ...(required !== undefined ? { required } : {}) }, screenshots: true };
}

/** Publish a tool; returns its removal. A later registration with the same name replaces it. */
export function publishTool(t: LiveTool): () => void {
  const full = pluginToolName(t.pluginId, t.name);
  liveTools.set(full, t);
  return () => {
    if (liveTools.get(full) === t) liveTools.delete(full);
  };
}

export function publishCommand(c: PluginCommandHandler): () => void {
  liveCommands.set(c.name, c);
  return () => {
    if (liveCommands.get(c.name) === c) liveCommands.delete(c.name);
  };
}

/** Remove everything a plugin published (used when it stops, however it stops). */
export function unpublishPlugin(pluginId: string): void {
  for (const [name, t] of liveTools) if (t.pluginId === pluginId) liveTools.delete(name);
  for (const [name, c] of liveCommands) if (c.pluginId === pluginId) liveCommands.delete(name);
}

export function listLiveTools(): LiveTool[] {
  return [...liveTools.values()];
}

export function getPluginCommand(name: string): PluginCommandHandler | undefined {
  return liveCommands.get(name);
}

export function listPluginCommands(): PluginCommandHandler[] {
  return [...liveCommands.values()];
}

function stringifyResult(value: unknown): string {
  let text: string;
  if (typeof value === 'string') text = value;
  else if (value === undefined || value === null) text = 'Done.';
  else {
    try {
      text = JSON.stringify(value, null, 2);
    } catch {
      text = String(value);
    }
  }
  return text.length > MAX_RESULT_CHARS ? `${text.slice(0, MAX_RESULT_CHARS)}\n[…truncated ${text.length - MAX_RESULT_CHARS} characters]` : text;
}

function describeArgs(args: Record<string, unknown>): string {
  let s: string;
  try {
    s = JSON.stringify(args);
  } catch {
    s = '[unserialisable arguments]';
  }
  return s.length > 400 ? `${s.slice(0, 400)}…` : s;
}

/**
 * Wrap a live tool for the AI SDK. The returned tool never throws: errors,
 * timeouts and denials come back as text the model can act on.
 */
function wrap(t: LiveTool, permissions: PermissionManager): Tool {
  const full = pluginToolName(t.pluginId, t.name);
  return tool<Record<string, unknown>, string>({
    description: `[Plugin: ${t.pluginName}] ${t.description}`,
    inputSchema: jsonSchema<Record<string, unknown>>(t.inputSchema as Parameters<typeof jsonSchema>[0]),
    toModelOutput: ({ toolCallId, output }) =>
      toolOutputWithImages(toolCallId, typeof output === 'string' ? output : stringifyResult(output)),
    execute: async (input, options) => {
      const given = (input && typeof input === 'object' ? input : {}) as Record<string, unknown>;
      // The model never sets this; Mercury does, for the model in use.
      const args = t.screenshots ? { ...given, [SCREENSHOT_PARAM]: screenshotRequest() } : given;
      if (!t.readOnly) {
        const approved = await permissions.approvePluginTool(full, `Run plugin tool ${t.pluginName} → ${t.name} with ${describeArgs(given)}`);
        if (!approved) return `Not run: the plugin tool ${full} was not approved.`;
      }
      const ac = new AbortController();
      const onOuterAbort = () => ac.abort(new Error('cancelled'));
      options?.abortSignal?.addEventListener('abort', onOuterAbort, { once: true });
      let timedOut = false;
      let timer: ReturnType<typeof setTimeout> | undefined;
      const timeout = new Promise<never>((_, reject) => {
        timer = setTimeout(() => {
          timedOut = true;
          ac.abort(new Error('timeout'));
          reject(new Error(`timed out after ${Math.round(t.timeoutMs / 1000)}s`));
        }, t.timeoutMs);
      });
      try {
        const result = await Promise.race([Promise.resolve().then(() => t.invoke(args, ac.signal)), timeout]);
        outcomeSink(t.pluginId, { ok: true });
        if (isToolContent(result)) {
          const images = usableImages(result.images);
          holdImages(options?.toolCallId, images);
          return stringifyResult(`${result.text || 'Done.'}${attachedImagesNote(images.length)}`);
        }
        return stringifyResult(result);
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        if (!options?.abortSignal?.aborted) outcomeSink(t.pluginId, { ok: false, error: message, timeout: timedOut });
        logger.warn({ plugin: t.pluginId, tool: t.name, err: message, timedOut }, 'Plugin tool failed');
        return `Error from plugin tool ${full}: ${message}`;
      } finally {
        if (timer) clearTimeout(timer);
        options?.abortSignal?.removeEventListener('abort', onOuterAbort);
      }
    },
  });
}

/** Live plugin tools as AI SDK tools, wired to this registry's permission manager. */
export function getPluginTools(permissions: PermissionManager, opts: { readOnlyOnly?: boolean } = {}): Record<string, Tool> {
  const out: Record<string, Tool> = {};
  for (const [full, t] of liveTools) {
    if (opts.readOnlyOnly && !t.readOnly) continue;
    try {
      out[full] = wrap(t, permissions);
    } catch (err) {
      logger.warn({ plugin: t.pluginId, tool: t.name, err }, 'Plugin tool has an unusable input schema; skipped');
    }
  }
  return out;
}

/** Test hook. */
export function resetToolBridge(): void {
  resetToolImages();
  liveTools.clear();
  liveCommands.clear();
  outcomeSink = () => {};
}