agent-orchestrator-mcp-server 0.1.0

package/shared/tools/action-session.d.ts

@@ -0,0 +1,55 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const ActionSessionSchema: z.ZodObject<{
+    session_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    action: z.ZodEnum<["follow_up", "pause", "restart", "archive", "unarchive"]>;
+    prompt: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    session_id: string | number;
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive";
+    prompt?: string | undefined;
+}, {
+    session_id: string | number;
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive";
+    prompt?: string | undefined;
+}>;
+export declare function actionSessionTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            session_id: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: "Session ID (numeric) or slug (string) to perform the action on.";
+            };
+            action: {
+                type: string;
+                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive"];
+                description: "Action to perform: \"follow_up\" (send prompt to paused session), \"pause\" (pause running session), \"restart\" (restart paused/failed session), \"archive\" (archive session), \"unarchive\" (restore archived session)";
+            };
+            prompt: {
+                type: string;
+                description: "Required for \"follow_up\" action. The prompt to send to the agent. Not used for other actions.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=action-session.d.ts.map

package/shared/tools/action-session.js

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    session_id: 'Session ID (numeric) or slug (string) to perform the action on.',
+    action: 'Action to perform: "follow_up" (send prompt to paused session), "pause" (pause running session), "restart" (restart paused/failed session), "archive" (archive session), "unarchive" (restore archived session)',
+    prompt: 'Required for "follow_up" action. The prompt to send to the agent. Not used for other actions.',
+};
+const ACTION_ENUM = ['follow_up', 'pause', 'restart', 'archive', 'unarchive'];
+export const ActionSessionSchema = z.object({
+    session_id: z.union([z.string(), z.number()]).describe(PARAM_DESCRIPTIONS.session_id),
+    action: z.enum(ACTION_ENUM).describe(PARAM_DESCRIPTIONS.action),
+    prompt: z.string().optional().describe(PARAM_DESCRIPTIONS.prompt),
+});
+const TOOL_DESCRIPTION = `Perform an action on an agent session.
+
+**Actions:**
+- **follow_up**: Send a follow-up prompt to a paused session (requires "prompt" parameter)
+- **pause**: Pause a running session, transitioning it to "needs_input" status
+- **restart**: Restart a paused or failed session without providing new input
+- **archive**: Archive a session (marks as completed)
+- **unarchive**: Restore an archived session to "needs_input" status
+
+**Status requirements:**
+- follow_up: Session must be "needs_input"
+- pause: Session must be "running"
+- restart: Session must be "needs_input" or "failed"
+- archive: Session can be in any status except "archived"
+- unarchive: Session must be "archived"
+
+**Use cases:**
+- Provide additional instructions to an agent
+- Control session lifecycle (pause, restart)
+- Organize sessions (archive, unarchive)`;
+export function actionSessionTool(_server, clientFactory) {
+    return {
+        name: 'action_session',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }],
+                    description: PARAM_DESCRIPTIONS.session_id,
+                },
+                action: {
+                    type: 'string',
+                    enum: ACTION_ENUM,
+                    description: PARAM_DESCRIPTIONS.action,
+                },
+                prompt: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.prompt,
+                },
+            },
+            required: ['session_id', 'action'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = ActionSessionSchema.parse(args);
+                const client = clientFactory();
+                const { session_id, action, prompt } = validatedArgs;
+                // Validate that prompt is provided for follow_up action
+                if (action === 'follow_up' && !prompt) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "prompt" parameter is required for the "follow_up" action.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                let result;
+                switch (action) {
+                    case 'follow_up': {
+                        const response = await client.followUp(session_id, prompt);
+                        const lines = [
+                            `## Follow-up Sent`,
+                            '',
+                            `- **Session ID:** ${response.session.id}`,
+                            `- **Title:** ${response.session.title}`,
+                            `- **New Status:** ${response.session.status}`,
+                        ];
+                        if (response.message) {
+                            lines.push(`- **Message:** ${response.message}`);
+                        }
+                        if (response.session.running_job_id) {
+                            lines.push(`- **Job ID:** ${response.session.running_job_id}`);
+                        }
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'pause': {
+                        const response = await client.pauseSession(session_id);
+                        const lines = [
+                            `## Session Paused`,
+                            '',
+                            `- **Session ID:** ${response.session.id}`,
+                            `- **Title:** ${response.session.title}`,
+                            `- **New Status:** ${response.session.status}`,
+                        ];
+                        if (response.message) {
+                            lines.push(`- **Message:** ${response.message}`);
+                        }
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'restart': {
+                        const response = await client.restartSession(session_id);
+                        const lines = [
+                            `## Session Restarted`,
+                            '',
+                            `- **Session ID:** ${response.session.id}`,
+                            `- **Title:** ${response.session.title}`,
+                            `- **New Status:** ${response.session.status}`,
+                        ];
+                        if (response.message) {
+                            lines.push(`- **Message:** ${response.message}`);
+                        }
+                        if (response.session.running_job_id) {
+                            lines.push(`- **Job ID:** ${response.session.running_job_id}`);
+                        }
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'archive': {
+                        const session = await client.archiveSession(session_id);
+                        const lines = [
+                            `## Session Archived`,
+                            '',
+                            `- **Session ID:** ${session.id}`,
+                            `- **Title:** ${session.title}`,
+                            `- **New Status:** ${session.status}`,
+                            `- **Archived At:** ${session.archived_at}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'unarchive': {
+                        const session = await client.unarchiveSession(session_id);
+                        const lines = [
+                            `## Session Unarchived`,
+                            '',
+                            `- **Session ID:** ${session.id}`,
+                            `- **Title:** ${session.title}`,
+                            `- **New Status:** ${session.status}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
+                    default: {
+                        // This should never happen due to Zod validation
+                        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 performing action: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/get-session.d.ts

@@ -0,0 +1,95 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const GetSessionSchema: z.ZodObject<{
+    id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    include_transcript: z.ZodOptional<z.ZodBoolean>;
+    include_logs: z.ZodOptional<z.ZodBoolean>;
+    logs_page: z.ZodOptional<z.ZodNumber>;
+    logs_per_page: z.ZodOptional<z.ZodNumber>;
+    include_subagent_transcripts: z.ZodOptional<z.ZodBoolean>;
+    transcripts_page: z.ZodOptional<z.ZodNumber>;
+    transcripts_per_page: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    id: string | number;
+    include_transcript?: boolean | undefined;
+    include_logs?: boolean | undefined;
+    logs_page?: number | undefined;
+    logs_per_page?: number | undefined;
+    include_subagent_transcripts?: boolean | undefined;
+    transcripts_page?: number | undefined;
+    transcripts_per_page?: number | undefined;
+}, {
+    id: string | number;
+    include_transcript?: boolean | undefined;
+    include_logs?: boolean | undefined;
+    logs_page?: number | undefined;
+    logs_per_page?: number | undefined;
+    include_subagent_transcripts?: boolean | undefined;
+    transcripts_page?: number | undefined;
+    transcripts_per_page?: number | undefined;
+}>;
+export declare function getSessionTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            id: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: "Session ID (numeric) or slug (string). Examples: \"1\", \"fix-auth-bug-20250115\"";
+            };
+            include_transcript: {
+                type: string;
+                description: "Include the full transcript of the session. Default: false. Set to true for complete conversation history.";
+            };
+            include_logs: {
+                type: string;
+                description: "Include logs for the session. Default: false. Use logs_page and logs_per_page for pagination.";
+            };
+            logs_page: {
+                type: string;
+                minimum: number;
+                description: "Page number for logs pagination. Default: 1";
+            };
+            logs_per_page: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: "Number of logs per page (1-100). Default: 25";
+            };
+            include_subagent_transcripts: {
+                type: string;
+                description: "Include subagent transcripts for the session. Default: false. Use transcripts_page and transcripts_per_page for pagination.";
+            };
+            transcripts_page: {
+                type: string;
+                minimum: number;
+                description: "Page number for subagent transcripts pagination. Default: 1";
+            };
+            transcripts_per_page: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                description: "Number of subagent transcripts per page (1-100). Default: 25";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=get-session.d.ts.map

package/shared/tools/get-session.js

@@ -0,0 +1,271 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    id: 'Session ID (numeric) or slug (string). Examples: "1", "fix-auth-bug-20250115"',
+    include_transcript: 'Include the full transcript of the session. Default: false. Set to true for complete conversation history.',
+    include_logs: 'Include logs for the session. Default: false. Use logs_page and logs_per_page for pagination.',
+    logs_page: 'Page number for logs pagination. Default: 1',
+    logs_per_page: 'Number of logs per page (1-100). Default: 25',
+    include_subagent_transcripts: 'Include subagent transcripts for the session. Default: false. Use transcripts_page and transcripts_per_page for pagination.',
+    transcripts_page: 'Page number for subagent transcripts pagination. Default: 1',
+    transcripts_per_page: 'Number of subagent transcripts per page (1-100). Default: 25',
+};
+export const GetSessionSchema = z.object({
+    id: z.union([z.string(), z.number()]).describe(PARAM_DESCRIPTIONS.id),
+    include_transcript: z.boolean().optional().describe(PARAM_DESCRIPTIONS.include_transcript),
+    include_logs: z.boolean().optional().describe(PARAM_DESCRIPTIONS.include_logs),
+    logs_page: z.number().min(1).optional().describe(PARAM_DESCRIPTIONS.logs_page),
+    logs_per_page: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.logs_per_page),
+    include_subagent_transcripts: z
+        .boolean()
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.include_subagent_transcripts),
+    transcripts_page: z.number().min(1).optional().describe(PARAM_DESCRIPTIONS.transcripts_page),
+    transcripts_per_page: z
+        .number()
+        .min(1)
+        .max(100)
+        .optional()
+        .describe(PARAM_DESCRIPTIONS.transcripts_per_page),
+});
+const TOOL_DESCRIPTION = `Get detailed information about a specific agent session.
+
+**Returns:** Complete session details including status, configuration, metadata, and optionally:
+- Full session transcript
+- Session logs (paginated)
+- Subagent transcripts (paginated)
+
+**Use cases:**
+- View detailed session information
+- Check session status and progress
+- Retrieve session transcript for review
+- Review logs for debugging
+- Inspect subagent transcripts`;
+function formatSessionDetails(session, includeTranscript) {
+    const lines = [
+        `## Session: ${session.title}`,
+        '',
+        '### Basic Information',
+        `- **ID:** ${session.id}`,
+        `- **Status:** ${session.status}`,
+        `- **Agent Type:** ${session.agent_type}`,
+    ];
+    if (session.slug)
+        lines.push(`- **Slug:** ${session.slug}`);
+    lines.push('');
+    lines.push('### Git Configuration');
+    if (session.git_root)
+        lines.push(`- **Repository:** ${session.git_root}`);
+    if (session.branch)
+        lines.push(`- **Branch:** ${session.branch}`);
+    if (session.subdirectory)
+        lines.push(`- **Subdirectory:** ${session.subdirectory}`);
+    lines.push('');
+    lines.push('### Execution');
+    lines.push(`- **Execution Provider:** ${session.execution_provider}`);
+    if (session.stop_condition)
+        lines.push(`- **Stop Condition:** ${session.stop_condition}`);
+    if (session.mcp_servers && session.mcp_servers.length > 0) {
+        lines.push(`- **MCP Servers:** ${session.mcp_servers.join(', ')}`);
+    }
+    if (session.prompt) {
+        lines.push('');
+        lines.push('### Current Prompt');
+        lines.push('```');
+        lines.push(session.prompt);
+        lines.push('```');
+    }
+    lines.push('');
+    lines.push('### Job Information');
+    if (session.session_id)
+        lines.push(`- **Claude Session ID:** ${session.session_id}`);
+    if (session.job_id)
+        lines.push(`- **Initial Job ID:** ${session.job_id}`);
+    if (session.running_job_id)
+        lines.push(`- **Running Job ID:** ${session.running_job_id}`);
+    if (Object.keys(session.metadata).length > 0) {
+        lines.push('');
+        lines.push('### System Metadata');
+        lines.push('```json');
+        lines.push(JSON.stringify(session.metadata, null, 2));
+        lines.push('```');
+    }
+    if (Object.keys(session.custom_metadata).length > 0) {
+        lines.push('');
+        lines.push('### Custom Metadata');
+        lines.push('```json');
+        lines.push(JSON.stringify(session.custom_metadata, null, 2));
+        lines.push('```');
+    }
+    lines.push('');
+    lines.push('### Timestamps');
+    lines.push(`- **Created:** ${session.created_at}`);
+    lines.push(`- **Updated:** ${session.updated_at}`);
+    if (session.archived_at)
+        lines.push(`- **Archived:** ${session.archived_at}`);
+    if (includeTranscript && session.transcript) {
+        lines.push('');
+        lines.push('### Transcript');
+        lines.push('```');
+        lines.push(session.transcript);
+        lines.push('```');
+    }
+    return lines.join('\n');
+}
+function formatLogs(logs, pagination) {
+    const lines = [
+        '',
+        '---',
+        `### Logs (${pagination.total_count} total, page ${pagination.page} of ${pagination.total_pages})`,
+        '',
+    ];
+    if (logs.length === 0) {
+        lines.push('No logs found.');
+    }
+    else {
+        logs.forEach((log) => {
+            const levelIcons = {
+                debug: '🔍',
+                info: 'ℹ️',
+                warning: '⚠️',
+                error: '❌',
+                verbose: '📝',
+            };
+            const icon = levelIcons[log.level] || '📝';
+            lines.push(`${icon} **[${log.level.toUpperCase()}]** ${log.created_at}`);
+            lines.push(`   ${log.content}`);
+            lines.push('');
+        });
+    }
+    if (pagination.page < pagination.total_pages) {
+        lines.push(`*More logs available. Use logs_page=${pagination.page + 1} to see the next page.*`);
+    }
+    return lines.join('\n');
+}
+function formatSubagentTranscripts(transcripts, pagination) {
+    const lines = [
+        '',
+        '---',
+        `### Subagent Transcripts (${pagination.total_count} total, page ${pagination.page} of ${pagination.total_pages})`,
+        '',
+    ];
+    if (transcripts.length === 0) {
+        lines.push('No subagent transcripts found.');
+    }
+    else {
+        transcripts.forEach((transcript) => {
+            const statusIcons = {
+                running: '🔄',
+                completed: '✅',
+                failed: '❌',
+            };
+            const icon = transcript.status ? statusIcons[transcript.status] || '📝' : '📝';
+            const label = transcript.display_label || transcript.agent_id;
+            const statusText = transcript.status || 'unknown';
+            lines.push(`${icon} **${label}** (${statusText})`);
+            if (transcript.description)
+                lines.push(`   ${transcript.description}`);
+            if (transcript.subagent_type)
+                lines.push(`   Type: ${transcript.subagent_type}`);
+            lines.push(`   Created: ${transcript.created_at}`);
+            lines.push('');
+        });
+    }
+    if (pagination.page < pagination.total_pages) {
+        lines.push(`*More transcripts available. Use transcripts_page=${pagination.page + 1} to see the next page.*`);
+    }
+    return lines.join('\n');
+}
+export function getSessionTool(_server, clientFactory) {
+    return {
+        name: 'get_session',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                id: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }],
+                    description: PARAM_DESCRIPTIONS.id,
+                },
+                include_transcript: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.include_transcript,
+                },
+                include_logs: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.include_logs,
+                },
+                logs_page: {
+                    type: 'number',
+                    minimum: 1,
+                    description: PARAM_DESCRIPTIONS.logs_page,
+                },
+                logs_per_page: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 100,
+                    description: PARAM_DESCRIPTIONS.logs_per_page,
+                },
+                include_subagent_transcripts: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.include_subagent_transcripts,
+                },
+                transcripts_page: {
+                    type: 'number',
+                    minimum: 1,
+                    description: PARAM_DESCRIPTIONS.transcripts_page,
+                },
+                transcripts_per_page: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 100,
+                    description: PARAM_DESCRIPTIONS.transcripts_per_page,
+                },
+            },
+            required: ['id'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = GetSessionSchema.parse(args);
+                const client = clientFactory();
+                // Get session details
+                const session = await client.getSession(validatedArgs.id, validatedArgs.include_transcript);
+                let output = formatSessionDetails(session, validatedArgs.include_transcript || false);
+                // Get logs if requested
+                if (validatedArgs.include_logs) {
+                    const logsResponse = await client.listLogs(session.id, {
+                        page: validatedArgs.logs_page,
+                        per_page: validatedArgs.logs_per_page,
+                    });
+                    output += formatLogs(logsResponse.logs, logsResponse.pagination);
+                }
+                // Get subagent transcripts if requested
+                if (validatedArgs.include_subagent_transcripts) {
+                    const transcriptsResponse = await client.listSubagentTranscripts(session.id, {
+                        page: validatedArgs.transcripts_page,
+                        per_page: validatedArgs.transcripts_per_page,
+                    });
+                    output += formatSubagentTranscripts(transcriptsResponse.subagent_transcripts, transcriptsResponse.pagination);
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: output,
+                        },
+                    ],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error getting session: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}