npm package: @principal-ade/utcp-panel-event
Description: UTCP-compatible tool definitions for panel events - server-safe with no React dependencies
Author: Principal ADE
Latest version: 0.1.0

# @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

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

## Usage

### In an API Route (Server-Side)

```typescript
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

```typescript
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

```typescript
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