agent-orchestrator-mcp-server 0.2.4 → 0.3.0

package/shared/tools/search-triggers.js

@@ -0,0 +1,145 @@
+import { z } from 'zod';
+export const SearchTriggersSchema = z.object({
+    id: z.number().optional(),
+    trigger_type: z.enum(['slack', 'schedule']).optional(),
+    status: z.enum(['enabled', 'disabled']).optional(),
+    include_channels: z.boolean().optional(),
+    page: z.number().min(1).optional(),
+    per_page: z.number().min(1).max(100).optional(),
+});
+const TOOL_DESCRIPTION = `Search and list automation triggers.
+
+**Modes:**
+- **Get by ID**: Provide an id to get trigger details with recent sessions
+- **List**: List triggers with optional filters (trigger_type, status, pagination)
+- **Include channels**: Set include_channels=true to also list available Slack channels (useful when creating Slack triggers)
+
+**Use cases:**
+- View configured automations (scheduled tasks, Slack integrations)
+- Check trigger status and execution history
+- Discover available Slack channels for new triggers`;
+export function searchTriggersTool(_server, clientFactory) {
+    return {
+        name: 'search_triggers',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    type: 'number',
+                    description: 'Get a specific trigger by ID. Returns trigger details with recent sessions.',
+                },
+                trigger_type: {
+                    type: 'string',
+                    enum: ['slack', 'schedule'],
+                    description: 'Filter by trigger type.',
+                },
+                status: {
+                    type: 'string',
+                    enum: ['enabled', 'disabled'],
+                    description: 'Filter by status.',
+                },
+                include_channels: {
+                    type: 'boolean',
+                    description: 'Include available Slack channels. Default: false',
+                },
+                page: { type: 'number', minimum: 1, description: 'Page number. Default: 1' },
+                per_page: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 100,
+                    description: 'Results per page. Default: 25',
+                },
+            },
+            required: [],
+        },
+        handler: async (args) => {
+            try {
+                const validated = SearchTriggersSchema.parse(args);
+                const client = clientFactory();
+                if (validated.id) {
+                    const response = await client.getTrigger(validated.id);
+                    const t = response.trigger;
+                    const lines = [
+                        `## Trigger: ${t.name}`,
+                        '',
+                        `- **ID:** ${t.id}`,
+                        `- **Type:** ${t.trigger_type}`,
+                        `- **Status:** ${t.status}`,
+                        `- **Agent Root:** ${t.agent_root_name}`,
+                        `- **Reuse Session:** ${t.reuse_session ? 'Yes' : 'No'}`,
+                        `- **MCP Servers:** ${t.mcp_servers.length > 0 ? t.mcp_servers.join(', ') : '(none)'}`,
+                    ];
+                    if (t.stop_condition)
+                        lines.push(`- **Stop Condition:** ${t.stop_condition}`);
+                    if (t.schedule_description)
+                        lines.push(`- **Schedule:** ${t.schedule_description}`);
+                    lines.push(`- **Sessions Created:** ${t.sessions_created_count}`);
+                    if (t.last_triggered_at)
+                        lines.push(`- **Last Triggered:** ${t.last_triggered_at}`);
+                    lines.push('', '### Prompt Template', '```', t.prompt_template, '```');
+                    if (t.configuration && Object.keys(t.configuration).length > 0) {
+                        lines.push('', '### Configuration', '```json', JSON.stringify(t.configuration, null, 2), '```');
+                    }
+                    if (response.recent_sessions && response.recent_sessions.length > 0) {
+                        lines.push('', '### Recent Sessions');
+                        response.recent_sessions.forEach((s) => {
+                            lines.push(`- **#${s.id}** ${s.title} (${s.status})`);
+                        });
+                    }
+                    return { content: [{ type: 'text', text: lines.join('\n') }] };
+                }
+                // List triggers
+                const response = await client.listTriggers({
+                    trigger_type: validated.trigger_type,
+                    status: validated.status,
+                    page: validated.page,
+                    per_page: validated.per_page,
+                });
+                const lines = [];
+                if (response.triggers.length === 0) {
+                    lines.push('## Triggers\n\nNo triggers found.');
+                }
+                else {
+                    lines.push(`## Triggers (${response.pagination.total_count} total, page ${response.pagination.page} of ${response.pagination.total_pages})`, '');
+                    response.triggers.forEach((t) => {
+                        lines.push(`### ${t.name} (ID: ${t.id})`);
+                        lines.push(`- **Type:** ${t.trigger_type} | **Status:** ${t.status} | **Sessions:** ${t.sessions_created_count}`);
+                        if (t.schedule_description)
+                            lines.push(`- **Schedule:** ${t.schedule_description}`);
+                        lines.push('');
+                    });
+                }
+                if (validated.include_channels) {
+                    try {
+                        const channels = await client.getTriggerChannels();
+                        lines.push('', '## Available Slack Channels', '');
+                        if (channels.channels.length === 0) {
+                            lines.push('No Slack channels available.');
+                        }
+                        else {
+                            channels.channels.forEach((ch) => {
+                                lines.push(`- **#${ch.name}** (${ch.id}) - ${ch.num_members} members${ch.is_private ? ' [private]' : ''}`);
+                            });
+                        }
+                    }
+                    catch (error) {
+                        lines.push('', `*Could not fetch Slack channels: ${error instanceof Error ? error.message : 'Unknown error'}*`);
+                    }
+                }
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error searching triggers: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -1,15 +1,13 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ClientFactory } from './server.js';
 /**
- * Available tool groups for agent-orchestrator:
- * - 'readonly': Read-only operations (search_sessions, get_session)
- * - 'write': Write operations (start_session, action_session)
- * - 'admin': Administrative operations (reserved for future use)
+ * Available tool groups for agent-orchestrator.
+ * Each domain has a base group (full access) and a _readonly variant (read-only).
  */
-export type ToolGroup = 'readonly' | 'write' | 'admin';
+export type ToolGroup = 'sessions' | 'sessions_readonly' | 'notifications' | 'notifications_readonly' | 'triggers' | 'triggers_readonly' | 'health' | 'health_readonly';
 /**
- * Parse enabled tool groups from environment variable.
- * @param enabledGroupsParam - Comma-separated list of groups (e.g., "readonly,write")
+ * Parse enabled tool groups from environment variable or parameter.
+ * @param enabledGroupsParam - Comma-separated list of groups (e.g., "sessions,notifications")
  * @returns Array of enabled tool groups
  */
 export declare function parseEnabledToolGroups(enabledGroupsParam?: string): ToolGroup[];
@@ -21,9 +19,9 @@ export declare function parseEnabledToolGroups(enabledGroupsParam?: string): Too
  * a factory pattern that accepts the server and clientFactory as parameters.
  *
  * @param clientFactory - Factory function that creates client instances
- * @param enabledGroups - Optional array of enabled tool groups (defaults to all)
+ * @param enabledGroups - Optional string of enabled tool groups (defaults to all)
  * @returns Function that registers all tools with a server
  */
-export declare function createRegisterTools(clientFactory: ClientFactory, enabledGroups?: ToolGroup[]): (server: Server) => void;
+export declare function createRegisterTools(clientFactory: ClientFactory, enabledGroups?: string): (server: Server) => void;
 export declare function registerTools(server: Server): void;
 //# sourceMappingURL=tools.d.ts.map

package/shared/tools.js

@@ -1,51 +1,122 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-// Simplified tool surface - 6 tools
-import { searchSessionsTool } from './tools/search-sessions.js';
+// 13 tools across 4 domains
+import { quickSearchSessionsTool } from './tools/search-sessions.js';
 import { startSessionTool } from './tools/start-session.js';
 import { getSessionTool } from './tools/get-session.js';
 import { actionSessionTool } from './tools/action-session.js';
 import { getConfigsTool } from './tools/get-configs.js';
+import { manageEnqueuedMessagesTool } from './tools/manage-enqueued-messages.js';
 import { sendPushNotificationTool } from './tools/send-push-notification.js';
-const ALL_TOOL_GROUPS = ['readonly', 'write', 'admin'];
+import { getNotificationsTool } from './tools/get-notifications.js';
+import { actionNotificationTool } from './tools/action-notification.js';
+import { searchTriggersTool } from './tools/search-triggers.js';
+import { actionTriggerTool } from './tools/action-trigger.js';
+import { getSystemHealthTool } from './tools/get-system-health.js';
+import { actionHealthTool } from './tools/action-health.js';
+import { getTranscriptArchiveTool } from './tools/get-transcript-archive.js';
 /**
- * Parse enabled tool groups from environment variable.
- * @param enabledGroupsParam - Comma-separated list of groups (e.g., "readonly,write")
+ * All valid tool groups (base groups and their _readonly variants)
+ */
+const VALID_TOOL_GROUPS = [
+    'sessions',
+    'sessions_readonly',
+    'notifications',
+    'notifications_readonly',
+    'triggers',
+    'triggers_readonly',
+    'health',
+    'health_readonly',
+];
+/**
+ * Base groups (without _readonly suffix) - used for default "all groups" behavior
+ */
+const BASE_TOOL_GROUPS = ['sessions', 'notifications', 'triggers', 'health'];
+/**
+ * Parse enabled tool groups from environment variable or parameter.
+ * @param enabledGroupsParam - Comma-separated list of groups (e.g., "sessions,notifications")
  * @returns Array of enabled tool groups
  */
 export function parseEnabledToolGroups(enabledGroupsParam) {
-    if (!enabledGroupsParam) {
-        return ALL_TOOL_GROUPS; // All groups enabled by default
+    const groupsStr = enabledGroupsParam || process.env.TOOL_GROUPS || '';
+    if (!groupsStr) {
+        // Default: all base groups enabled (full read+write access)
+        return [...BASE_TOOL_GROUPS];
     }
-    const requestedGroups = enabledGroupsParam.split(',').map((g) => g.trim().toLowerCase());
-    const validGroups = requestedGroups.filter((g) => ALL_TOOL_GROUPS.includes(g));
-    if (validGroups.length === 0) {
-        console.error(`Warning: No valid tool groups found in "${enabledGroupsParam}". Valid groups: ${ALL_TOOL_GROUPS.join(', ')}`);
-        return ALL_TOOL_GROUPS;
+    const groups = groupsStr.split(',').map((g) => g.trim());
+    const validGroups = [];
+    for (const group of groups) {
+        if (VALID_TOOL_GROUPS.includes(group) &&
+            !validGroups.includes(group)) {
+            validGroups.push(group);
+        }
+        else if (!VALID_TOOL_GROUPS.includes(group)) {
+            console.warn(`Unknown tool group: ${group}`);
+        }
     }
     return validGroups;
 }
 /**
  * All available tools with their group assignments.
- * Tools can belong to multiple groups.
  *
- * Simplified tool surface:
- * - search_sessions: Search/list/get sessions by ID
- * - start_session: Create a new session
- * - get_session: Get detailed session info with optional logs/transcripts
- * - action_session: Perform actions (follow_up, pause, restart, archive, unarchive)
- * - get_configs: Fetch all static configuration (MCP servers, agent roots, stop conditions)
- * - send_push_notification: Send a push notification about a session needing attention
+ * 14 tools across 4 domains:
+ * - quick_search_sessions: Quick title-based search/list/get sessions by ID (sessions, read)
+ * - get_session: Get detailed session info with optional logs/transcripts (sessions, read)
+ * - get_configs: Fetch all static configuration (sessions, read)
+ * - get_transcript_archive: Get transcript archive download URL and metadata (sessions, read)
+ * - start_session: Create a new session (sessions, write)
+ * - action_session: Perform session actions (sessions, write)
+ * - manage_enqueued_messages: Manage session message queue (sessions, write)
+ * - get_notifications: Get/list notifications and badge count (notifications, read)
+ * - send_push_notification: Send a push notification (notifications, write)
+ * - action_notification: Mark read, dismiss notifications (notifications, write)
+ * - search_triggers: Search/list automation triggers (triggers, read)
+ * - action_trigger: Create, update, delete, toggle triggers (triggers, write)
+ * - get_system_health: Get system health report and CLI status (health, read)
+ * - action_health: System maintenance actions (health, write)
  */
 const ALL_TOOLS = [
-    // Read operations
-    { factory: searchSessionsTool, groups: ['readonly', 'write', 'admin'] },
-    { factory: getSessionTool, groups: ['readonly', 'write', 'admin'] },
-    { factory: getConfigsTool, groups: ['readonly', 'write', 'admin'] },
-    // Write operations
-    { factory: startSessionTool, groups: ['write', 'admin'] },
-    { factory: actionSessionTool, groups: ['write', 'admin'] },
-    { factory: sendPushNotificationTool, groups: ['write', 'admin'] },
+    // Session tools - read operations
+    { factory: quickSearchSessionsTool, group: 'sessions', isWriteOperation: false },
+    { factory: getSessionTool, group: 'sessions', isWriteOperation: false },
+    { factory: getConfigsTool, group: 'sessions', isWriteOperation: false },
+    { factory: getTranscriptArchiveTool, group: 'sessions', isWriteOperation: false },
+    // Session tools - write operations
+    { factory: startSessionTool, group: 'sessions', isWriteOperation: true },
+    { factory: actionSessionTool, group: 'sessions', isWriteOperation: true },
+    { factory: manageEnqueuedMessagesTool, group: 'sessions', isWriteOperation: true },
+    // Notification tools - read operations
+    { factory: getNotificationsTool, group: 'notifications', isWriteOperation: false },
+    // Notification tools - write operations
+    { factory: sendPushNotificationTool, group: 'notifications', isWriteOperation: true },
+    { factory: actionNotificationTool, group: 'notifications', isWriteOperation: true },
+    // Trigger tools - read operations
+    { factory: searchTriggersTool, group: 'triggers', isWriteOperation: false },
+    // Trigger tools - write operations
+    { factory: actionTriggerTool, group: 'triggers', isWriteOperation: true },
+    // Health tools - read operations
+    { factory: getSystemHealthTool, group: 'health', isWriteOperation: false },
+    // Health tools - write operations
+    { factory: actionHealthTool, group: 'health', isWriteOperation: true },
 ];
+/**
+ * Check if a tool should be included based on enabled groups.
+ * @param toolDef - The tool definition to check
+ * @param enabledGroups - Array of enabled tool groups
+ * @returns true if the tool should be included
+ */
+function shouldIncludeTool(toolDef, enabledGroups) {
+    const baseGroup = toolDef.group;
+    const readonlyGroup = `${baseGroup}_readonly`;
+    // Check if the base group (full access) is enabled
+    if (enabledGroups.includes(baseGroup)) {
+        return true;
+    }
+    // Check if the readonly group is enabled (only include read operations)
+    if (enabledGroups.includes(readonlyGroup) && !toolDef.isWriteOperation) {
+        return true;
+    }
+    return false;
+}
 /**
  * Creates a function to register all tools with the server.
  * This pattern uses individual tool files for better modularity and testability.
@@ -54,14 +125,16 @@ const ALL_TOOLS = [
  * a factory pattern that accepts the server and clientFactory as parameters.
  *
  * @param clientFactory - Factory function that creates client instances
- * @param enabledGroups - Optional array of enabled tool groups (defaults to all)
+ * @param enabledGroups - Optional string of enabled tool groups (defaults to all)
  * @returns Function that registers all tools with a server
  */
 export function createRegisterTools(clientFactory, enabledGroups) {
-    const groups = enabledGroups || parseEnabledToolGroups(process.env.ENABLED_TOOLGROUPS);
     return (server) => {
-        // Filter tools by enabled groups and create instances
-        const tools = ALL_TOOLS.filter((def) => def.groups.some((g) => groups.includes(g))).map((def) => def.factory(server, clientFactory));
+        const enabledToolGroups = parseEnabledToolGroups(enabledGroups);
+        // Filter tools based on enabled groups
+        const enabledTools = ALL_TOOLS.filter((toolDef) => shouldIncludeTool(toolDef, enabledToolGroups));
+        // Create tool instances
+        const tools = enabledTools.map((toolDef) => toolDef.factory(server, clientFactory));
         // List available tools
         server.setRequestHandler(ListToolsRequestSchema, async () => {
             return {

package/shared/types.d.ts

@@ -68,7 +68,6 @@ export interface SessionsResponse {
 }
 export interface SearchSessionsResponse {
     query: string;
-    search_contents: boolean;
     sessions: Session[];
     pagination: Pagination;
 }
@@ -186,4 +185,166 @@ export interface UpdateSubagentTranscriptRequest {
     total_tokens?: number;
     tool_use_count?: number;
 }
+export type EnqueuedMessageStatus = 'pending' | 'processing' | 'sent';
+export interface EnqueuedMessage {
+    id: number;
+    session_id: number;
+    content: string;
+    stop_condition: string | null;
+    position: number;
+    status: EnqueuedMessageStatus;
+    created_at: string;
+    updated_at: string;
+}
+export interface EnqueuedMessagesResponse {
+    enqueued_messages: EnqueuedMessage[];
+    pagination: Pagination;
+}
+export interface EnqueuedMessageResponse {
+    enqueued_message: EnqueuedMessage;
+}
+export interface EnqueuedMessageInterruptResponse {
+    session: Session;
+    message: string;
+}
+export type TriggerType = 'slack' | 'schedule';
+export type TriggerStatus = 'enabled' | 'disabled';
+export interface Trigger {
+    id: number;
+    name: string;
+    trigger_type: TriggerType;
+    status: TriggerStatus;
+    agent_root_name: string;
+    prompt_template: string;
+    stop_condition: string | null;
+    reuse_session: boolean;
+    mcp_servers: string[];
+    configuration: Record<string, unknown>;
+    schedule_description: string | null;
+    last_session_id: number | null;
+    last_triggered_at: string | null;
+    last_polled_at: string | null;
+    sessions_created_count: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface TriggersResponse {
+    triggers: Trigger[];
+    pagination: Pagination;
+}
+export interface TriggerResponse {
+    trigger: Trigger;
+    recent_sessions?: Session[];
+}
+export interface TriggerChannelsResponse {
+    channels: Array<{
+        id: string;
+        name: string;
+        is_private: boolean;
+        num_members: number;
+    }>;
+}
+export interface CreateTriggerRequest {
+    name: string;
+    trigger_type: TriggerType;
+    agent_root_name: string;
+    prompt_template: string;
+    status?: TriggerStatus;
+    stop_condition?: string;
+    reuse_session?: boolean;
+    mcp_servers?: string[];
+    configuration?: Record<string, unknown>;
+}
+export interface UpdateTriggerRequest {
+    name?: string;
+    trigger_type?: TriggerType;
+    agent_root_name?: string;
+    prompt_template?: string;
+    status?: TriggerStatus;
+    stop_condition?: string;
+    reuse_session?: boolean;
+    mcp_servers?: string[];
+    configuration?: Record<string, unknown>;
+}
+export interface Notification {
+    id: number;
+    session_id: number;
+    notification_type: string;
+    read: boolean;
+    stale: boolean;
+    created_at: string;
+    updated_at: string;
+    session?: {
+        id: number;
+        slug: string | null;
+        title: string;
+        status: string;
+    };
+}
+export interface NotificationsResponse {
+    notifications: Notification[];
+    pagination: Pagination;
+}
+export interface NotificationResponse {
+    notification: Notification;
+}
+export interface NotificationBadgeResponse {
+    pending_count: number;
+}
+export interface NotificationMarkAllReadResponse {
+    marked_count: number;
+    pending_count: number;
+}
+export interface NotificationDismissAllReadResponse {
+    dismissed_count: number;
+    pending_count: number;
+}
+export interface HealthReport {
+    health_report: Record<string, unknown>;
+    timestamp: string;
+    rails_env: string;
+    ruby_version: string;
+}
+export interface HealthActionResponse {
+    [key: string]: unknown;
+}
+export interface CliStatusResponse {
+    cli_status: Record<string, unknown>;
+    unauthenticated_count: number;
+}
+export interface CliActionResponse {
+    queued: boolean;
+    message: string;
+    [key: string]: unknown;
+}
+export interface ForkSessionResponse {
+    session: Session;
+    message: string;
+}
+export interface RefreshSessionResponse {
+    session: Session;
+    message: string;
+}
+export interface RefreshAllSessionsResponse {
+    message: string;
+    refreshed: number;
+    restarted: number;
+    continued: number;
+    errors: number;
+}
+export interface BulkArchiveResponse {
+    archived_count: number;
+    errors: Array<{
+        id: number;
+        error: string;
+    }>;
+}
+export interface TranscriptResponse {
+    transcript_text: string;
+}
+export interface TranscriptArchiveStatusResponse {
+    generated_at: string;
+    session_count: number;
+    file_size_bytes: number;
+}
 //# sourceMappingURL=types.d.ts.map