agent-orchestrator-mcp-server 0.2.4 → 0.3.0

package/shared/tools/get-transcript-archive.d.ts

@@ -0,0 +1,27 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const GetTranscriptArchiveSchema: z.ZodObject<{}, "strip", z.ZodTypeAny, {}, {}>;
+export declare function getTranscriptArchiveTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {};
+        required: never[];
+    };
+    handler: (_args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-transcript-archive.d.ts.map

package/shared/tools/get-transcript-archive.js

@@ -0,0 +1,64 @@
+import { z } from 'zod';
+export const GetTranscriptArchiveSchema = z.object({});
+const TOOL_DESCRIPTION = `Get the download URL and curl command for the transcript archive zip file.
+
+Returns the download URL, a ready-to-use curl command, and archive metadata (generation time, session count, file size). The archive is built incrementally every 10 minutes and contains all session transcripts.
+
+**Use cases:**
+- Download all session transcripts as a zip archive for backup or analysis
+- Get archive metadata to check when it was last generated and how many sessions it contains`;
+export function getTranscriptArchiveTool(_server, clientFactory) {
+    return {
+        name: 'get_transcript_archive',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        handler: async (_args) => {
+            try {
+                const client = clientFactory();
+                const status = await client.getTranscriptArchiveStatus();
+                const downloadInfo = client.getTranscriptArchiveDownloadUrl();
+                const lines = [
+                    '## Transcript Archive',
+                    '',
+                    `- **Generated At:** ${status.generated_at}`,
+                    `- **Session Count:** ${status.session_count}`,
+                    `- **File Size:** ${formatFileSize(status.file_size_bytes)}`,
+                    '',
+                    '### Download',
+                    '',
+                    `**URL:** \`${downloadInfo.url}\``,
+                    '',
+                    'To download, run:',
+                    '```bash',
+                    `curl -o /path/to/transcript-archive.zip -H "X-API-Key: ${downloadInfo.apiKey}" "${downloadInfo.url}"`,
+                    '```',
+                ];
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error getting transcript archive: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}
+function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes} B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)} KB`;
+    if (bytes < 1024 * 1024 * 1024)
+        return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+    return `${(bytes / (1024 * 1024 * 1024)).toFixed(1)} GB`;
+}

package/shared/tools/manage-enqueued-messages.d.ts

@@ -0,0 +1,94 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const ManageEnqueuedMessagesSchema: z.ZodObject<{
+    session_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    action: z.ZodEnum<["list", "get", "create", "update", "delete", "reorder", "interrupt"]>;
+    message_id: z.ZodOptional<z.ZodNumber>;
+    content: z.ZodOptional<z.ZodString>;
+    stop_condition: z.ZodOptional<z.ZodString>;
+    position: z.ZodOptional<z.ZodNumber>;
+    page: z.ZodOptional<z.ZodNumber>;
+    per_page: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    session_id: string | number;
+    action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt";
+    per_page?: number | undefined;
+    page?: number | undefined;
+    content?: string | undefined;
+    stop_condition?: string | undefined;
+    message_id?: number | undefined;
+    position?: number | undefined;
+}, {
+    session_id: string | number;
+    action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt";
+    per_page?: number | undefined;
+    page?: number | undefined;
+    content?: string | undefined;
+    stop_condition?: string | undefined;
+    message_id?: number | undefined;
+    position?: number | undefined;
+}>;
+export declare function manageEnqueuedMessagesTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            session_id: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: string;
+            };
+            action: {
+                type: string;
+                enum: readonly ["list", "get", "create", "update", "delete", "reorder", "interrupt"];
+                description: string;
+            };
+            message_id: {
+                type: string;
+                description: string;
+            };
+            content: {
+                type: string;
+                description: string;
+            };
+            stop_condition: {
+                type: string;
+                description: string;
+            };
+            position: {
+                type: string;
+                minimum: number;
+                description: string;
+            };
+            page: {
+                type: string;
+                minimum: number;
+                description: string;
+            };
+            per_page: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=manage-enqueued-messages.d.ts.map

package/shared/tools/manage-enqueued-messages.js

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+const ACTION_ENUM = ['list', 'get', 'create', 'update', 'delete', 'reorder', 'interrupt'];
+export const ManageEnqueuedMessagesSchema = z.object({
+    session_id: z.union([z.string(), z.number()]),
+    action: z.enum(ACTION_ENUM),
+    message_id: z.number().optional(),
+    content: z.string().optional(),
+    stop_condition: z.string().optional(),
+    position: z.number().min(1).optional(),
+    page: z.number().min(1).optional(),
+    per_page: z.number().min(1).max(100).optional(),
+});
+const TOOL_DESCRIPTION = `Manage the enqueued message queue for an agent session.
+
+**Actions:**
+- **list**: List all enqueued messages for a session (supports pagination)
+- **get**: Get a specific enqueued message by ID
+- **create**: Add a new message to the queue (requires "content")
+- **update**: Update an existing message (requires "message_id")
+- **delete**: Remove a message from the queue (requires "message_id")
+- **reorder**: Change a message's position in the queue (requires "message_id" and "position")
+- **interrupt**: Pause the session and send this message immediately (requires "message_id")
+
+Enqueued messages are follow-up prompts queued to be sent to the agent in order.`;
+export function manageEnqueuedMessagesTool(_server, clientFactory) {
+    return {
+        name: 'manage_enqueued_messages',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }],
+                    description: 'Session ID (numeric) or slug (string).',
+                },
+                action: {
+                    type: 'string',
+                    enum: ACTION_ENUM,
+                    description: 'Action to perform on enqueued messages.',
+                },
+                message_id: {
+                    type: 'number',
+                    description: 'Message ID. Required for get, update, delete, reorder, and interrupt.',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Message content. Required for create. Optional for update.',
+                },
+                stop_condition: {
+                    type: 'string',
+                    description: 'Stop condition for this message. Optional for create and update.',
+                },
+                position: {
+                    type: 'number',
+                    minimum: 1,
+                    description: 'New position in queue. Required for reorder.',
+                },
+                page: { type: 'number', minimum: 1, description: 'Page number for list. Default: 1' },
+                per_page: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 100,
+                    description: 'Results per page for list. Default: 25',
+                },
+            },
+            required: ['session_id', 'action'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = ManageEnqueuedMessagesSchema.parse(args);
+                const client = clientFactory();
+                const { session_id, action, message_id, content, stop_condition, position, page, per_page, } = validated;
+                let result;
+                switch (action) {
+                    case 'list': {
+                        const response = await client.listEnqueuedMessages(session_id, { page, per_page });
+                        if (response.enqueued_messages.length === 0) {
+                            result = '## Enqueued Messages\n\nNo enqueued messages found.';
+                        }
+                        else {
+                            const lines = [
+                                `## Enqueued Messages (${response.pagination.total_count} total, page ${response.pagination.page} of ${response.pagination.total_pages})`,
+                                '',
+                            ];
+                            response.enqueued_messages.forEach((msg) => {
+                                lines.push(`### Position ${msg.position} (ID: ${msg.id})`);
+                                lines.push(`- **Status:** ${msg.status}`);
+                                lines.push(`- **Content:** ${msg.content.substring(0, 200)}${msg.content.length > 200 ? '...' : ''}`);
+                                if (msg.stop_condition)
+                                    lines.push(`- **Stop Condition:** ${msg.stop_condition}`);
+                                lines.push('');
+                            });
+                            result = lines.join('\n');
+                        }
+                        break;
+                    }
+                    case 'get': {
+                        if (!message_id) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "message_id" is required for the "get" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const msg = await client.getEnqueuedMessage(session_id, message_id);
+                        result = [
+                            `## Enqueued Message #${msg.id}`,
+                            '',
+                            `- **Session ID:** ${msg.session_id}`,
+                            `- **Position:** ${msg.position}`,
+                            `- **Status:** ${msg.status}`,
+                            `- **Content:** ${msg.content}`,
+                            msg.stop_condition ? `- **Stop Condition:** ${msg.stop_condition}` : '',
+                            `- **Created:** ${msg.created_at}`,
+                        ]
+                            .filter(Boolean)
+                            .join('\n');
+                        break;
+                    }
+                    case 'create': {
+                        if (!content) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "content" is required for the "create" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const msg = await client.createEnqueuedMessage(session_id, {
+                            content,
+                            stop_condition: stop_condition || undefined,
+                        });
+                        result = [
+                            '## Message Enqueued',
+                            '',
+                            `- **ID:** ${msg.id}`,
+                            `- **Position:** ${msg.position}`,
+                            `- **Status:** ${msg.status}`,
+                            `- **Content:** ${msg.content.substring(0, 200)}${msg.content.length > 200 ? '...' : ''}`,
+                        ].join('\n');
+                        break;
+                    }
+                    case 'update': {
+                        if (!message_id) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "message_id" is required for the "update" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const msg = await client.updateEnqueuedMessage(session_id, message_id, {
+                            content: content || undefined,
+                            stop_condition: stop_condition || undefined,
+                        });
+                        result = [
+                            '## Message Updated',
+                            '',
+                            `- **ID:** ${msg.id}`,
+                            `- **Position:** ${msg.position}`,
+                            `- **Content:** ${msg.content.substring(0, 200)}${msg.content.length > 200 ? '...' : ''}`,
+                        ].join('\n');
+                        break;
+                    }
+                    case 'delete': {
+                        if (!message_id) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "message_id" is required for the "delete" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        await client.deleteEnqueuedMessage(session_id, message_id);
+                        result = `## Message Deleted\n\nEnqueued message ${message_id} has been removed from the queue.`;
+                        break;
+                    }
+                    case 'reorder': {
+                        if (!message_id) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "message_id" is required for the "reorder" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        if (!position) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "position" is required for the "reorder" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const msg = await client.reorderEnqueuedMessage(session_id, message_id, position);
+                        result = [
+                            '## Message Reordered',
+                            '',
+                            `- **ID:** ${msg.id}`,
+                            `- **New Position:** ${msg.position}`,
+                        ].join('\n');
+                        break;
+                    }
+                    case 'interrupt': {
+                        if (!message_id) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "message_id" is required for the "interrupt" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const response = await client.interruptEnqueuedMessage(session_id, message_id);
+                        result = [
+                            '## Message Sent as Interrupt',
+                            '',
+                            `- **Session ID:** ${response.session.id}`,
+                            `- **Session Status:** ${response.session.status}`,
+                            `- **Message:** ${response.message}`,
+                        ].join('\n');
+                        break;
+                    }
+                    default: {
+                        const _exhaustiveCheck = action;
+                        return {
+                            content: [{ type: 'text', text: `Error: Unknown action "${_exhaustiveCheck}"` }],
+                            isError: true,
+                        };
+                    }
+                }
+                return { content: [{ type: 'text', text: result }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error managing enqueued messages: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/search-sessions.d.ts

@@ -1,10 +1,9 @@
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
 import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
-export declare const SearchSessionsSchema: z.ZodObject<{
+export declare const QuickSearchSessionsSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodNumber>;
     query: z.ZodOptional<z.ZodString>;
-    search_contents: z.ZodOptional<z.ZodBoolean>;
     status: z.ZodOptional<z.ZodEnum<["waiting", "running", "needs_input", "failed", "archived"]>>;
     agent_type: z.ZodOptional<z.ZodString>;
     show_archived: z.ZodOptional<z.ZodBoolean>;
@@ -16,7 +15,6 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }, {
@@ -25,11 +23,10 @@ export declare const SearchSessionsSchema: z.ZodObject<{
     agent_type?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
-    search_contents?: boolean | undefined;
     id?: number | undefined;
     query?: string | undefined;
 }>;
-export declare function searchSessionsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+export declare function quickSearchSessionsTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
     name: string;
     description: string;
     inputSchema: {
@@ -42,11 +39,7 @@ export declare function searchSessionsTool(_server: Server, clientFactory: () =>
             query: {
                 type: string;
                 maxLength: number;
-                description: "Search query to find sessions. Searches across title, metadata, and custom_metadata. Leave empty to list all sessions.";
-            };
-            search_contents: {
-                type: string;
-                description: "Also search within transcript contents. May be slow for sessions with large transcripts. Default: false";
+                description: "Search query to find sessions. Matches against session title only — this is a simple title search, not a full-text or semantic search. Leave empty to list all sessions.";
             };
             status: {
                 type: string;

package/shared/tools/search-sessions.js

@@ -1,18 +1,16 @@
 import { z } from 'zod';
 const PARAM_DESCRIPTIONS = {
     id: 'Get a specific session by ID. When provided, other filters are ignored.',
-    query: 'Search query to find sessions. Searches across title, metadata, and custom_metadata. Leave empty to list all sessions.',
-    search_contents: 'Also search within transcript contents. May be slow for sessions with large transcripts. Default: false',
+    query: 'Search query to find sessions. Matches against session title only — this is a simple title search, not a full-text or semantic search. Leave empty to list all sessions.',
     status: 'Filter results by status. Options: "waiting", "running", "needs_input", "failed", "archived"',
     agent_type: 'Filter results by agent type.',
     show_archived: 'Include archived sessions in results. Default: false',
     page: 'Page number for pagination. Default: 1',
     per_page: 'Number of results per page (1-100). Default: 25',
 };
-export const SearchSessionsSchema = z.object({
+export const QuickSearchSessionsSchema = z.object({
     id: z.number().optional().describe(PARAM_DESCRIPTIONS.id),
     query: z.string().max(1000).optional().describe(PARAM_DESCRIPTIONS.query),
-    search_contents: z.boolean().optional().describe(PARAM_DESCRIPTIONS.search_contents),
     status: z
         .enum(['waiting', 'running', 'needs_input', 'failed', 'archived'])
         .optional()
@@ -22,11 +20,13 @@ export const SearchSessionsSchema = z.object({
     page: z.number().min(1).optional().describe(PARAM_DESCRIPTIONS.page),
     per_page: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.per_page),
 });
-const TOOL_DESCRIPTION = `Search for agent sessions in the Agent Orchestrator.
+const TOOL_DESCRIPTION = `Quick title-based search for agent sessions in the Agent Orchestrator.
+
+**Important:** This tool only searches session titles. It is NOT a full-text or semantic search across session contents/transcripts. Use this when you roughly know the session title you're looking for.
 
 **Use cases:**
 - Find a specific session by ID (set id parameter)
-- Search sessions by keyword in title/prompt (set query parameter)
+- Search sessions by title keyword (set query parameter)
 - List all sessions with optional status filter
 - Monitor sessions requiring attention (status: "needs_input")
 
@@ -66,9 +66,9 @@ function formatSession(session) {
     lines.push(`- **Updated:** ${session.updated_at}`);
     return lines.join('\n');
 }
-export function searchSessionsTool(_server, clientFactory) {
+export function quickSearchSessionsTool(_server, clientFactory) {
     return {
-        name: 'search_sessions',
+        name: 'quick_search_sessions',
         description: TOOL_DESCRIPTION,
         inputSchema: {
             type: 'object',
@@ -82,10 +82,6 @@ export function searchSessionsTool(_server, clientFactory) {
                     maxLength: 1000,
                     description: PARAM_DESCRIPTIONS.query,
                 },
-                search_contents: {
-                    type: 'boolean',
-                    description: PARAM_DESCRIPTIONS.search_contents,
-                },
                 status: {
                     type: 'string',
                     enum: ['waiting', 'running', 'needs_input', 'failed', 'archived'],
@@ -115,7 +111,7 @@ export function searchSessionsTool(_server, clientFactory) {
         },
         handler: async (args) => {
             try {
-                const validatedArgs = SearchSessionsSchema.parse(args);
+                const validatedArgs = QuickSearchSessionsSchema.parse(args);
                 const client = clientFactory();
                 // If ID is provided, get that specific session
                 if (validatedArgs.id !== undefined) {
@@ -133,9 +129,8 @@ export function searchSessionsTool(_server, clientFactory) {
                 let sessions;
                 let pagination;
                 if (validatedArgs.query) {
-                    // Use search endpoint
+                    // Use search endpoint (title-only search, no content search)
                     const response = await client.searchSessions(validatedArgs.query, {
-                        search_contents: validatedArgs.search_contents,
                         status: validatedArgs.status,
                         agent_type: validatedArgs.agent_type,
                         show_archived: validatedArgs.show_archived,

package/shared/tools/search-triggers.d.ts

@@ -0,0 +1,78 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const SearchTriggersSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodNumber>;
+    trigger_type: z.ZodOptional<z.ZodEnum<["slack", "schedule"]>>;
+    status: z.ZodOptional<z.ZodEnum<["enabled", "disabled"]>>;
+    include_channels: z.ZodOptional<z.ZodBoolean>;
+    page: z.ZodOptional<z.ZodNumber>;
+    per_page: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    per_page?: number | undefined;
+    status?: "enabled" | "disabled" | undefined;
+    page?: number | undefined;
+    trigger_type?: "slack" | "schedule" | undefined;
+    id?: number | undefined;
+    include_channels?: boolean | undefined;
+}, {
+    per_page?: number | undefined;
+    status?: "enabled" | "disabled" | undefined;
+    page?: number | undefined;
+    trigger_type?: "slack" | "schedule" | undefined;
+    id?: number | undefined;
+    include_channels?: boolean | undefined;
+}>;
+export declare function searchTriggersTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                type: string;
+                description: string;
+            };
+            trigger_type: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            status: {
+                type: string;
+                enum: string[];
+                description: string;
+            };
+            include_channels: {
+                type: string;
+                description: string;
+            };
+            page: {
+                type: string;
+                minimum: number;
+                description: string;
+            };
+            per_page: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: string;
+            };
+        };
+        required: never[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=search-triggers.d.ts.map