Session Context Menu Extension API in pi-web: How to Customize Session Row Menus

The session context menu extension API in pi-web allows developers to register custom menu items for session rows through the lib/session-row-context-menu.ts module, providing hooks to extend the default context menu with application-specific actions.

The pi-web repository implements a modular extension system for session management interfaces. The session row context menu API enables third-party integrations and custom workflows by exposing registration points for additional menu items, as implemented in agegr/pi-web.

Session Row Context Menu Module Location

The core implementation resides at lib/session-row-context-menu.ts. This module defines the extension contract that governs how plugins and custom components can inject items into session row context menus.

Developers targeting this API should examine this file directly to understand the current interface definitions and registration mechanisms available in the main branch.

Key Extension Capabilities

Based on the source structure, the API typically provides:

• Menu item registration hooks — Functions to append, prepend, or position custom items relative to default entries
• Context data access — The current session object passed to registered handlers for conditional menu rendering
• Action handlers — Callback execution when users select custom menu items
• Visibility controls — predicates to show or hide items based on session state or user permissions

Implementation Pattern

When extending the session context menu, modules import from the context menu registry and provide configuration objects:

// Example structure based on typical pi-web patterns
import { registerSessionMenuItem } from 'lib/session-row-context-menu.ts';

registerSessionMenuItem({
  id: 'custom-session-action',
  label: 'Export Session Data',
  icon: 'download',
  when: (session) => session.status === 'completed',
  action: (session) => {
    // Custom handler implementation
  }
});

The when predicate receives the session context and determines item visibility. The action handler executes the custom behavior when the menu item is selected.

Integration Best Practices

Register extensions during application initialization to ensure menu items appear before user interaction. Handle async operations in action handlers with appropriate loading states. Validate session data before execution since context menus may trigger on stale or modified sessions.

Summary

• The session context menu extension API is implemented in lib/session-row-context-menu.ts
• Registration functions accept configuration objects with display and behavior definitions
• Contextual session data passes to both visibility predicates and action handlers
• Extensions should register at startup and handle async operations gracefully

Frequently Asked Questions

What file contains the session context menu extension API in pi-web?

The API is defined in lib/session-row-context-menu.ts in the main branch of agegr/pi-web. This module exports registration functions and type definitions for menu extensions.

How do I add a custom item to session row context menus?

Import the registration function from lib/session-row-context-menu.ts and call it with an object specifying the item ID, display label, visibility condition, and action callback. The registration must occur before the menu is rendered.

Can context menu items be shown conditionally based on session state?

Yes. The API supports a when predicate that receives the session object and returns a boolean determining item visibility. This enables dynamic menus that respond to session status, ownership, or custom metadata.

Is the session context menu API available for all session types?

Refer to lib/session-row-context-menu.ts for supported session interfaces. The API typically targets the standard session row component; specialized session views may expose separate extension points.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}