agent-orchestrator-mcp-server 0.2.4 → 0.3.0

package/shared/tools/action-health.js

@@ -0,0 +1,101 @@
+import { z } from 'zod';
+const ACTION_ENUM = [
+    'cleanup_processes',
+    'retry_sessions',
+    'archive_old',
+    'cli_refresh',
+    'cli_clear_cache',
+];
+export const ActionHealthSchema = z.object({
+    action: z.enum(ACTION_ENUM),
+    session_ids: z.array(z.number()).optional(),
+    days: z.number().min(1).max(365).optional(),
+});
+const TOOL_DESCRIPTION = `Perform system health and maintenance actions.
+
+**Actions:**
+- **cleanup_processes**: Terminate orphaned agent processes
+- **retry_sessions**: Retry failed sessions (optionally specify session_ids)
+- **archive_old**: Archive sessions older than N days (requires "days", default 7)
+- **cli_refresh**: Trigger a background refresh of CLI tool installations
+- **cli_clear_cache**: Clear npm/pip caches and reinstall MCP packages
+
+Note: Health actions are rate-limited (30s cooldown between calls).`;
+export function actionHealthTool(_server, clientFactory) {
+    return {
+        name: 'action_health',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: { type: 'string', enum: ACTION_ENUM, description: 'Health action to perform.' },
+                session_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: 'Session IDs to retry. For retry_sessions action.',
+                },
+                days: {
+                    type: 'number',
+                    minimum: 1,
+                    maximum: 365,
+                    description: 'Archive sessions older than this many days. For archive_old action. Default: 7',
+                },
+            },
+            required: ['action'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = ActionHealthSchema.parse(args);
+                const client = clientFactory();
+                const { action } = validated;
+                let result;
+                switch (action) {
+                    case 'cleanup_processes': {
+                        const response = await client.cleanupProcesses();
+                        result = `## Processes Cleaned Up\n\n\`\`\`json\n${JSON.stringify(response, null, 2)}\n\`\`\``;
+                        break;
+                    }
+                    case 'retry_sessions': {
+                        const response = await client.retrySessions(validated.session_ids);
+                        result = `## Sessions Retried\n\n\`\`\`json\n${JSON.stringify(response, null, 2)}\n\`\`\``;
+                        break;
+                    }
+                    case 'archive_old': {
+                        const response = await client.archiveOldSessions(validated.days);
+                        result = `## Old Sessions Archived\n\n\`\`\`json\n${JSON.stringify(response, null, 2)}\n\`\`\``;
+                        break;
+                    }
+                    case 'cli_refresh': {
+                        const response = await client.refreshCli();
+                        result = `## CLI Refresh Queued\n\n- **Message:** ${response.message}`;
+                        break;
+                    }
+                    case 'cli_clear_cache': {
+                        const response = await client.clearCliCache();
+                        result = `## CLI Cache Clear Queued\n\n- **Message:** ${response.message}`;
+                        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 performing health action: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -0,0 +1,46 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const ActionNotificationSchema: z.ZodObject<{
+    action: z.ZodEnum<["mark_read", "mark_all_read", "dismiss", "dismiss_all_read"]>;
+    id: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    action: "mark_read" | "mark_all_read" | "dismiss" | "dismiss_all_read";
+    id?: number | undefined;
+}, {
+    action: "mark_read" | "mark_all_read" | "dismiss" | "dismiss_all_read";
+    id?: number | undefined;
+}>;
+export declare function actionNotificationTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            action: {
+                type: string;
+                enum: readonly ["mark_read", "mark_all_read", "dismiss", "dismiss_all_read"];
+                description: string;
+            };
+            id: {
+                type: string;
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=action-notification.d.ts.map

package/shared/tools/action-notification.js

@@ -0,0 +1,99 @@
+import { z } from 'zod';
+const ACTION_ENUM = ['mark_read', 'mark_all_read', 'dismiss', 'dismiss_all_read'];
+export const ActionNotificationSchema = z.object({
+    action: z.enum(ACTION_ENUM),
+    id: z.number().optional(),
+});
+const TOOL_DESCRIPTION = `Manage notifications in the Agent Orchestrator.
+
+**Actions:**
+- **mark_read**: Mark a specific notification as read (requires "id")
+- **mark_all_read**: Mark all notifications as read
+- **dismiss**: Delete a notification (requires "id", must be read first)
+- **dismiss_all_read**: Delete all read notifications`;
+export function actionNotificationTool(_server, clientFactory) {
+    return {
+        name: 'action_notification',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ACTION_ENUM,
+                    description: 'Action to perform.',
+                },
+                id: {
+                    type: 'number',
+                    description: 'Notification ID. Required for mark_read and dismiss.',
+                },
+            },
+            required: ['action'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = ActionNotificationSchema.parse(args);
+                const client = clientFactory();
+                const { action, id } = validated;
+                let result;
+                switch (action) {
+                    case 'mark_read': {
+                        if (!id) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "id" is required for the "mark_read" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const notification = await client.markNotificationRead(id);
+                        result = `## Notification Marked Read\n\n- **ID:** ${notification.id}\n- **Type:** ${notification.notification_type}`;
+                        break;
+                    }
+                    case 'mark_all_read': {
+                        const response = await client.markAllNotificationsRead();
+                        result = `## All Notifications Marked Read\n\n- **Marked:** ${response.marked_count}\n- **Remaining Pending:** ${response.pending_count}`;
+                        break;
+                    }
+                    case 'dismiss': {
+                        if (!id) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "id" is required for the "dismiss" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        await client.dismissNotification(id);
+                        result = `## Notification Dismissed\n\nNotification ${id} has been deleted.`;
+                        break;
+                    }
+                    case 'dismiss_all_read': {
+                        const response = await client.dismissAllReadNotifications();
+                        result = `## Read Notifications Dismissed\n\n- **Dismissed:** ${response.dismissed_count}\n- **Remaining Pending:** ${response.pending_count}`;
+                        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 notification: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -2,20 +2,29 @@ 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", "change_mcp_servers"]>;
+    session_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+    action: z.ZodEnum<["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "bulk_archive"]>;
     prompt: z.ZodOptional<z.ZodString>;
     mcp_servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    message_index: z.ZodOptional<z.ZodNumber>;
+    session_notes: z.ZodOptional<z.ZodString>;
+    session_ids: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
 }, "strip", z.ZodTypeAny, {
-    session_id: string | number;
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers";
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "fork" | "refresh" | "refresh_all" | "update_notes" | "toggle_favorite" | "bulk_archive";
     mcp_servers?: string[] | undefined;
     prompt?: string | undefined;
+    session_id?: string | number | undefined;
+    message_index?: number | undefined;
+    session_notes?: string | undefined;
+    session_ids?: number[] | undefined;
 }, {
-    session_id: string | number;
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers";
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "fork" | "refresh" | "refresh_all" | "update_notes" | "toggle_favorite" | "bulk_archive";
     mcp_servers?: string[] | undefined;
     prompt?: string | undefined;
+    session_id?: string | number | undefined;
+    message_index?: number | undefined;
+    session_notes?: string | undefined;
+    session_ids?: number[] | undefined;
 }>;
 export declare function actionSessionTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
     name: string;
@@ -27,12 +36,12 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
                 oneOf: {
                     type: string;
                 }[];
-                description: "Session ID (numeric) or slug (string) to perform the action on.";
+                description: "Session ID (numeric) or slug (string). Required for most actions. Not required for \"refresh_all\" and \"bulk_archive\".";
             };
             action: {
                 type: string;
-                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers"];
-                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), \"change_mcp_servers\" (update MCP servers for session)";
+                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "bulk_archive"];
+                description: "Action to perform: \"follow_up\", \"pause\", \"restart\", \"archive\", \"unarchive\", \"change_mcp_servers\", \"fork\", \"refresh\", \"refresh_all\", \"update_notes\", \"toggle_favorite\", \"bulk_archive\"";
             };
             prompt: {
                 type: string;
@@ -45,6 +54,21 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
                 };
                 description: "Required for \"change_mcp_servers\" action. Array of MCP server names to set for the session.";
             };
+            message_index: {
+                type: string;
+                description: "Required for \"fork\" action. The transcript message index to fork from.";
+            };
+            session_notes: {
+                type: string;
+                description: "Required for \"update_notes\" action. The notes text to set on the session.";
+            };
+            session_ids: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: "Required for \"bulk_archive\" action. Array of session IDs to archive.";
+            };
         };
         required: string[];
     };

package/shared/tools/action-session.js

@@ -1,9 +1,12 @@
 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), "change_mcp_servers" (update MCP servers for session)',
+    session_id: 'Session ID (numeric) or slug (string). Required for most actions. Not required for "refresh_all" and "bulk_archive".',
+    action: 'Action to perform: "follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "bulk_archive"',
     prompt: 'Required for "follow_up" action. The prompt to send to the agent. Not used for other actions.',
     mcp_servers: 'Required for "change_mcp_servers" action. Array of MCP server names to set for the session.',
+    message_index: 'Required for "fork" action. The transcript message index to fork from.',
+    session_notes: 'Required for "update_notes" action. The notes text to set on the session.',
+    session_ids: 'Required for "bulk_archive" action. Array of session IDs to archive.',
 };
 const ACTION_ENUM = [
     'follow_up',
@@ -12,12 +15,21 @@ const ACTION_ENUM = [
     'archive',
     'unarchive',
     'change_mcp_servers',
+    'fork',
+    'refresh',
+    'refresh_all',
+    'update_notes',
+    'toggle_favorite',
+    'bulk_archive',
 ];
 export const ActionSessionSchema = z.object({
-    session_id: z.union([z.string(), z.number()]).describe(PARAM_DESCRIPTIONS.session_id),
+    session_id: z.union([z.string(), z.number()]).optional().describe(PARAM_DESCRIPTIONS.session_id),
     action: z.enum(ACTION_ENUM).describe(PARAM_DESCRIPTIONS.action),
     prompt: z.string().optional().describe(PARAM_DESCRIPTIONS.prompt),
     mcp_servers: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.mcp_servers),
+    message_index: z.number().optional().describe(PARAM_DESCRIPTIONS.message_index),
+    session_notes: z.string().optional().describe(PARAM_DESCRIPTIONS.session_notes),
+    session_ids: z.array(z.number()).optional().describe(PARAM_DESCRIPTIONS.session_ids),
 });
 const TOOL_DESCRIPTION = `Perform an action on an agent session.
 
@@ -28,19 +40,17 @@ const TOOL_DESCRIPTION = `Perform an action on an agent session.
 - **archive**: Archive a session (marks as completed)
 - **unarchive**: Restore an archived session to "needs_input" status
 - **change_mcp_servers**: Update the MCP servers for a session (requires "mcp_servers" parameter)
-
-**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"
-- change_mcp_servers: Session can be in any status except "archived"
+- **fork**: Fork a session from a specific transcript message (requires "message_index")
+- **refresh**: Refresh a single session's status from the execution provider
+- **refresh_all**: Refresh all active sessions (no session_id needed)
+- **update_notes**: Update the notes on a session (requires "session_notes")
+- **toggle_favorite**: Toggle favorite status on a session
+- **bulk_archive**: Archive multiple sessions at once (requires "session_ids", no session_id needed)
 
 **Use cases:**
 - Provide additional instructions to an agent
-- Control session lifecycle (pause, restart)
-- Organize sessions (archive, unarchive)
+- Control session lifecycle (pause, restart, fork, refresh)
+- Organize sessions (archive, unarchive, bulk_archive, toggle_favorite, update_notes)
 - Reconfigure session MCP server access`;
 export function actionSessionTool(_server, clientFactory) {
     return {
@@ -67,14 +77,51 @@ export function actionSessionTool(_server, clientFactory) {
                     items: { type: 'string' },
                     description: PARAM_DESCRIPTIONS.mcp_servers,
                 },
+                message_index: {
+                    type: 'number',
+                    description: PARAM_DESCRIPTIONS.message_index,
+                },
+                session_notes: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.session_notes,
+                },
+                session_ids: {
+                    type: 'array',
+                    items: { type: 'number' },
+                    description: PARAM_DESCRIPTIONS.session_ids,
+                },
             },
-            required: ['session_id', 'action'],
+            required: ['action'],
         },
         handler: async (args) => {
             try {
                 const validatedArgs = ActionSessionSchema.parse(args);
                 const client = clientFactory();
-                const { session_id, action, prompt, mcp_servers } = validatedArgs;
+                const { session_id, action, prompt, mcp_servers, message_index, session_notes, session_ids, } = validatedArgs;
+                // Actions that require session_id
+                const requiresSessionId = [
+                    'follow_up',
+                    'pause',
+                    'restart',
+                    'archive',
+                    'unarchive',
+                    'change_mcp_servers',
+                    'fork',
+                    'refresh',
+                    'update_notes',
+                    'toggle_favorite',
+                ];
+                if (requiresSessionId.includes(action) && !session_id) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: The "session_id" parameter is required for the "${action}" action.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 // Validate that prompt is provided for follow_up action
                 if (action === 'follow_up' && !prompt) {
                     return {
@@ -99,6 +146,42 @@ export function actionSessionTool(_server, clientFactory) {
                         isError: true,
                     };
                 }
+                // Validate fork requires message_index
+                if (action === 'fork' && message_index === undefined) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "message_index" parameter is required for the "fork" action.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Validate update_notes requires session_notes
+                if (action === 'update_notes' && session_notes === undefined) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "session_notes" parameter is required for the "update_notes" action.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                // Validate bulk_archive requires session_ids
+                if (action === 'bulk_archive' && (!session_ids || session_ids.length === 0)) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "session_ids" parameter is required for the "bulk_archive" action.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 let result;
                 switch (action) {
                     case 'follow_up': {
@@ -189,6 +272,85 @@ export function actionSessionTool(_server, clientFactory) {
                         result = lines.join('\n');
                         break;
                     }
+                    case 'fork': {
+                        const response = await client.forkSession(session_id, message_index);
+                        const lines = [
+                            `## Session Forked`,
+                            '',
+                            `- **New Session ID:** ${response.session.id}`,
+                            `- **Title:** ${response.session.title}`,
+                            `- **Status:** ${response.session.status}`,
+                            `- **Message:** ${response.message}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'refresh': {
+                        const response = await client.refreshSession(session_id);
+                        const lines = [
+                            `## Session Refreshed`,
+                            '',
+                            `- **Session ID:** ${response.session.id}`,
+                            `- **Title:** ${response.session.title}`,
+                            `- **Status:** ${response.session.status}`,
+                            `- **Message:** ${response.message}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'refresh_all': {
+                        const response = await client.refreshAllSessions();
+                        const lines = [
+                            `## All Sessions Refreshed`,
+                            '',
+                            `- **Message:** ${response.message}`,
+                            `- **Refreshed:** ${response.refreshed}`,
+                            `- **Restarted:** ${response.restarted}`,
+                            `- **Continued:** ${response.continued}`,
+                            `- **Errors:** ${response.errors}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'update_notes': {
+                        const session = await client.updateSessionNotes(session_id, session_notes);
+                        const lines = [
+                            `## Session Notes Updated`,
+                            '',
+                            `- **Session ID:** ${session.id}`,
+                            `- **Title:** ${session.title}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'toggle_favorite': {
+                        const session = await client.toggleFavorite(session_id);
+                        const lines = [
+                            `## Favorite Toggled`,
+                            '',
+                            `- **Session ID:** ${session.id}`,
+                            `- **Title:** ${session.title}`,
+                            `- **Favorited:** ${session.favorited ? 'Yes' : 'No'}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
+                    case 'bulk_archive': {
+                        const response = await client.bulkArchiveSessions(session_ids);
+                        const lines = [
+                            `## Bulk Archive Complete`,
+                            '',
+                            `- **Archived:** ${response.archived_count}`,
+                        ];
+                        if (response.errors.length > 0) {
+                            lines.push(`- **Errors:** ${response.errors.length}`);
+                            response.errors.forEach((err) => {
+                                lines.push(`  - Session ${err.id}: ${err.error}`);
+                            });
+                        }
+                        result = lines.join('\n');
+                        break;
+                    }
                     default: {
                         // This should never happen due to Zod validation
                         const _exhaustiveCheck = action;