pi-extensions-tool-display 0.1.1 → 0.2.0

package/tool-display-api-consumer.d.ts

@@ -0,0 +1,68 @@
+export type RuntimeToolDefinition = Record<string, unknown>;
+
+export interface ToolDisplayAdapter {
+  kind?: "read" | "edit" | "mcp" | "generic";
+  overrideExistingRenderers?: boolean;
+}
+
+export interface ToolDisplayApi {
+  version: 1;
+  decorateTool<T extends RuntimeToolDefinition>(tool: T, adapter?: ToolDisplayAdapter | Record<string, unknown>): T;
+  registerResultRenderMiddleware(registration: ToolResultRenderMiddlewareRegistration): string;
+  unregisterResultRenderMiddleware(id: string): boolean;
+  hasResultRenderMiddleware(id: string): boolean;
+  isResultRenderPipelineActive(toolName: string): boolean;
+}
+
+export interface ToolResultRenderMiddlewareContext {
+  toolName: string;
+  result: unknown;
+  options: Record<string, unknown>;
+  theme: {
+    fg(color: string, text: string): string;
+    bold(text: string): string;
+  };
+  renderContext?: unknown;
+}
+
+export type ToolResultRenderMiddleware = (
+  context: ToolResultRenderMiddlewareContext,
+  next: () => unknown,
+) => unknown;
+
+export interface ToolResultRenderMiddlewareRegistration {
+  id?: string;
+  toolName: string;
+  middleware: ToolResultRenderMiddleware;
+}
+
+export interface ToolResultRenderMiddlewareOptions {
+  id?: string;
+}
+
+export interface DecorateToolForDisplayOptions {
+  suppressDecorateErrors?: boolean;
+}
+
+export declare function getToolDisplayApi(): ToolDisplayApi | undefined;
+
+export declare function queueToolDisplayDecoration<T extends RuntimeToolDefinition>(
+  tool: T,
+  adapter?: ToolDisplayAdapter | Record<string, unknown>,
+): void;
+
+export declare function decorateToolForDisplay<T extends object>(
+  tool: T,
+  adapter?: ToolDisplayAdapter | Record<string, unknown>,
+  options?: DecorateToolForDisplayOptions,
+): T;
+
+export declare function decorateMcpToolForDisplay<T extends RuntimeToolDefinition>(tool: T): T;
+
+export declare function registerToolResultRenderMiddleware(
+  toolName: string,
+  middleware: ToolResultRenderMiddleware,
+  options?: ToolResultRenderMiddlewareOptions,
+): string;
+
+export declare function unregisterToolResultRenderMiddleware(id: string): boolean;

package/tool-display-api-consumer.js

@@ -0,0 +1,82 @@
+const TOOL_DISPLAY_API_KEY = Symbol.for("pi-tool-display.api.v1");
+const TOOL_DISPLAY_PENDING_DECORATIONS_KEY = Symbol.for("pi-tool-display.pendingDecorations.v1");
+const TOOL_DISPLAY_PENDING_RESULT_MIDDLEWARES_KEY = Symbol.for("pi-tool-display.pendingResultRenderMiddlewares.v1");
+let nextResultMiddlewareId = 0;
+
+export function getToolDisplayApi() {
+  const api = globalThis[TOOL_DISPLAY_API_KEY];
+  if (
+    api?.version !== 1 ||
+    typeof api.decorateTool !== "function"
+  ) {
+    return undefined;
+  }
+
+  return api;
+}
+
+export function queueToolDisplayDecoration(tool, adapter) {
+  const existing = globalThis[TOOL_DISPLAY_PENDING_DECORATIONS_KEY];
+  const queue = Array.isArray(existing) ? existing : [];
+  queue.push({ tool, adapter });
+  globalThis[TOOL_DISPLAY_PENDING_DECORATIONS_KEY] = queue;
+}
+
+export function decorateToolForDisplay(tool, adapter, options = {}) {
+  const api = getToolDisplayApi();
+  if (!api) {
+    queueToolDisplayDecoration(tool, adapter);
+    return tool;
+  }
+
+  try {
+    return api.decorateTool(tool, adapter);
+  } catch (error) {
+    if (options.suppressDecorateErrors) {
+      return tool;
+    }
+
+    throw error;
+  }
+}
+
+export function decorateMcpToolForDisplay(tool) {
+  return decorateToolForDisplay(tool, { kind: "mcp", overrideExistingRenderers: true });
+}
+
+export function registerToolResultRenderMiddleware(toolName, middleware, options = {}) {
+  if (typeof toolName !== "string" || !toolName.trim()) {
+    throw new TypeError("toolName must be a non-empty string");
+  }
+  if (typeof middleware !== "function") {
+    throw new TypeError("middleware must be a function");
+  }
+
+  const id = options.id || `external-result-middleware-${++nextResultMiddlewareId}`;
+  const api = getToolDisplayApi();
+  if (typeof api?.registerResultRenderMiddleware === "function") {
+    return api.registerResultRenderMiddleware({ id, toolName, middleware });
+  }
+
+  const existing = globalThis[TOOL_DISPLAY_PENDING_RESULT_MIDDLEWARES_KEY];
+  const queue = Array.isArray(existing) ? existing : [];
+  const registration = { id, toolName, middleware };
+  const index = queue.findIndex((entry) => entry?.id === id);
+  if (index >= 0) queue[index] = registration;
+  else queue.push(registration);
+  globalThis[TOOL_DISPLAY_PENDING_RESULT_MIDDLEWARES_KEY] = queue;
+  return id;
+}
+
+export function unregisterToolResultRenderMiddleware(id) {
+  const api = getToolDisplayApi();
+  const removedActive = typeof api?.unregisterResultRenderMiddleware === "function"
+    ? api.unregisterResultRenderMiddleware(id)
+    : false;
+  const queue = globalThis[TOOL_DISPLAY_PENDING_RESULT_MIDDLEWARES_KEY];
+  if (!Array.isArray(queue)) return removedActive;
+  const index = queue.findIndex((entry) => entry?.id === id);
+  if (index < 0) return removedActive;
+  queue.splice(index, 1);
+  return true;
+}

package/tsconfig.json

@@ -1,6 +1,7 @@
 {
   "compilerOptions": {
     "target": "ES2022",
+    "lib": ["ES2023"],
     "module": "ESNext",
     "moduleResolution": "Bundler",
     "allowImportingTsExtensions": true,