@principal-ade/utcp-panel-event

UTCP-compatible tool definitions for panel event-based actions. This package is server-safe and has no React dependencies.

Features

• Layout Tools: Pre-built tools for common panel operations (toggle, collapse, expand, switch, focus, reset)
• AI Provider Converters: Convert tools to Gemini, OpenAI, and Anthropic formats
• System Prompt Generator: Generate AI system prompts describing available tools
• Server-Safe: Can be imported in Next.js API routes, Node.js scripts, etc.
• Zero Dependencies: No runtime dependencies, just TypeScript types

Installation

npm install @principal-ade/utcp-panel-event
# or
bun add @principal-ade/utcp-panel-event

Usage

In an API Route (Server-Side)

import {
  layoutTools,
  toolsToGeminiFormat,
  generateToolsSystemPrompt,
} from '@principal-ade/utcp-panel-event';

// Convert to Gemini format
const geminiTools = toolsToGeminiFormat(layoutTools);

// Generate system prompt
const systemPrompt = generateToolsSystemPrompt(layoutTools);

Available Layout Tools

| Tool | Event | Description | |------|-------|-------------| | toggle_panel | panel:toggle | Toggle left/right panel visibility | | collapse_all_panels | panel:collapse-all | Collapse all panels | | expand_all_panels | panel:expand-all | Expand all panels | | switch_panel | panel:switch | Switch content in a panel slot | | focus_panel | panel:focus | Set focus to a panel slot | | reset_layout | panel:reset-layout | Reset to default layout |

AI Provider Formats

import {
  toolsToGeminiFormat,
  toolsToOpenAIFormat,
  toolsToAnthropicFormat,
} from '@principal-ade/utcp-panel-event';

// Google Gemini
const geminiTools = toolsToGeminiFormat(layoutTools);

// OpenAI
const openaiTools = toolsToOpenAIFormat(layoutTools);

// Anthropic Claude
const anthropicTools = toolsToAnthropicFormat(layoutTools);

Creating Custom Tools

import type { PanelTool, PanelEventCallTemplate } from '@principal-ade/utcp-panel-event';

const myTool: PanelTool = {
  name: 'open_file',
  description: 'Open a file in the viewer',
  inputs: {
    type: 'object',
    properties: {
      path: { type: 'string', description: 'File path to open' },
    },
    required: ['path'],
  },
  outputs: {
    type: 'object',
    properties: {
      success: { type: 'boolean' },
    },
  },
  tags: ['file', 'navigation'],
  tool_call_template: {
    call_template_type: 'panel_event',
    event_type: 'file:open',
  },
};

Architecture

This package provides the tool definitions and format converters. The actual event emission happens in your application code when handling tool invocations:

┌─────────────────────────┐     ┌─────────────────────────┐
│    AI Provider          │     │   Your Application      │
│  (Gemini/OpenAI/etc)    │────▶│   (handles tool calls)  │
└─────────────────────────┘     └───────────┬─────────────┘
                                            │
                                            ▼
                                ┌─────────────────────────┐
                                │   Event Emitter         │
                                │  (panel-framework-core) │
                                └───────────┬─────────────┘
                                            │
                                            ▼
                                ┌─────────────────────────┐
                                │   Panel Components      │
                                │  (listen for events)    │
                                └─────────────────────────┘

License

MIT