agent-orchestrator-mcp-server 0.8.8 → 0.8.9

package/README.md

@@ -31,6 +31,7 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 | `action_session`           | sessions      | write      | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers, change_model, fork, refresh, refresh_all, update_notes, update_title, toggle_favorite, bulk_archive |
 | `manage_enqueued_messages` | sessions      | write      | Manage session message queue: list, get, create, update, delete, reorder, interrupt                                                                                                     |
 | `manage_categories`        | sessions      | write      | Manage dashboard categories that organize sessions: list, create, update, delete, reorder, set_session_category                                                                         |
+| `respond_to_elicitation`   | sessions      | write      | Accept or decline a pending elicitation by its request_id, with optional structured content on accept                                                                                   |
 | `get_notifications`        | notifications | read       | Get/list notifications and badge count                                                                                                                                                  |
 | `send_push_notification`   | notifications | write      | Send a push notification about a session needing human attention                                                                                                                        |
 | `action_notification`      | notifications | write      | Mark read, mark all read, dismiss, dismiss all read notifications                                                                                                                       |
@@ -57,16 +58,16 @@ This server organizes tools into groups that can be selectively enabled or disab
 
 Control which tools are available via the `TOOL_GROUPS` environment variable:
 
-| Group                    | Description                                                                                                          |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
-| `sessions`               | All session tools (read + write): search, get, configs, transcript_archive, start, action, enqueued msgs, categories |
-| `sessions_readonly`      | Session tools (read only): quick_search_sessions, get_session, get_configs, get_transcript_archive                   |
-| `notifications`          | All notification tools (read + write): get, send, mark read, dismiss                                                 |
-| `notifications_readonly` | Notification tools (read only): get_notifications                                                                    |
-| `triggers`               | All trigger tools (read + write): search, create, update, delete, toggle                                             |
-| `triggers_readonly`      | Trigger tools (read only): search_triggers                                                                           |
-| `health`                 | All health tools (read + write): health report, CLI status, maintenance                                              |
-| `health_readonly`        | Health tools (read only): get_system_health                                                                          |
+| Group                    | Description                                                                                                                        |
+| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `sessions`               | All session tools (read + write): search, get, configs, transcript_archive, start, action, enqueued msgs, categories, elicitations |
+| `sessions_readonly`      | Session tools (read only): quick_search_sessions, get_session, get_configs, get_transcript_archive                                 |
+| `notifications`          | All notification tools (read + write): get, send, mark read, dismiss                                                               |
+| `notifications_readonly` | Notification tools (read only): get_notifications                                                                                  |
+| `triggers`               | All trigger tools (read + write): search, create, update, delete, toggle                                                           |
+| `triggers_readonly`      | Trigger tools (read only): search_triggers                                                                                         |
+| `health`                 | All health tools (read + write): health report, CLI status, maintenance                                                            |
+| `health_readonly`        | Health tools (read only): get_system_health                                                                                        |
 
 **Examples:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",

package/shared/orchestrator-client/orchestrator-client.d.ts

@@ -3,7 +3,7 @@
  *
  * A client for interacting with the Agent Orchestrator REST API.
  */
-import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse, EnqueuedMessage, EnqueuedMessagesResponse, EnqueuedMessageInterruptResponse, EnqueuedMessageStatus, Category, CategoriesResponse, CreateCategoryRequest, UpdateCategoryRequest, SetSessionCategoryResponse, Trigger, TriggerType, TriggerStatus, TriggersResponse, TriggerResponse, TriggerChannelsResponse, CreateTriggerRequest, UpdateTriggerRequest, Notification, NotificationsResponse, NotificationBadgeResponse, NotificationMarkAllReadResponse, NotificationDismissAllReadResponse, HealthReport, HealthActionResponse, CliStatusResponse, CliActionResponse, ForkSessionResponse, RefreshSessionResponse, RefreshAllSessionsResponse, BulkArchiveResponse, TranscriptResponse, TranscriptArchiveStatusResponse } from '../types.js';
+import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse, EnqueuedMessage, EnqueuedMessagesResponse, EnqueuedMessageInterruptResponse, EnqueuedMessageStatus, Category, CategoriesResponse, CreateCategoryRequest, UpdateCategoryRequest, SetSessionCategoryResponse, Trigger, TriggerType, TriggerStatus, TriggersResponse, TriggerResponse, TriggerChannelsResponse, CreateTriggerRequest, UpdateTriggerRequest, Notification, NotificationsResponse, NotificationBadgeResponse, NotificationMarkAllReadResponse, NotificationDismissAllReadResponse, HealthReport, HealthActionResponse, CliStatusResponse, CliActionResponse, ForkSessionResponse, RefreshSessionResponse, RefreshAllSessionsResponse, BulkArchiveResponse, TranscriptResponse, TranscriptArchiveStatusResponse, ElicitationActionType, ElicitationResponse } from '../types.js';
 /** Raw agent root shape as returned by the Rails API */
 export interface RawAgentRoot {
     name: string;
@@ -148,6 +148,7 @@ export interface IAgentOrchestratorClient {
         url: string;
         apiKey: string;
     };
+    respondToElicitation(requestId: string, actionType: ElicitationActionType, content?: Record<string, unknown>): Promise<ElicitationResponse>;
 }
 /**
  * Implementation of the Agent Orchestrator API client.
@@ -281,5 +282,6 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
         url: string;
         apiKey: string;
     };
+    respondToElicitation(requestId: string, actionType: ElicitationActionType, content?: Record<string, unknown>): Promise<ElicitationResponse>;
 }
 //# sourceMappingURL=orchestrator-client.d.ts.map

package/shared/orchestrator-client/orchestrator-client.integration-mock.d.ts

@@ -5,11 +5,18 @@
  */
 import type { IAgentOrchestratorClient } from './orchestrator-client.js';
 import type { Session, Log, SubagentTranscript, Category } from '../types.js';
+/** Minimal elicitation record used to simulate the respond endpoint. */
+export interface MockElicitation {
+    request_id: string;
+    status: 'pending' | 'accept' | 'decline';
+    content?: Record<string, unknown> | null;
+}
 interface MockData {
     sessions?: Session[];
     logs?: Log[];
     subagentTranscripts?: SubagentTranscript[];
     categories?: Category[];
+    elicitations?: MockElicitation[];
 }
 /**
  * Creates a mock Agent Orchestrator client for integration testing.

package/shared/orchestrator-client/orchestrator-client.integration-mock.js

@@ -76,6 +76,7 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 updated_at: '2025-01-15T14:00:00Z',
             },
         ],
+        elicitations: initialMockData?.elicitations || [],
     };
     let sessionIdCounter = mockData.sessions?.length || 1;
     let logIdCounter = mockData.logs?.length || 1;
@@ -912,5 +913,22 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 apiKey: 'test-api-key',
             };
         },
+        // Elicitations
+        async respondToElicitation(requestId, actionType, content) {
+            const elicitation = mockData.elicitations?.find((e) => e.request_id === requestId);
+            if (!elicitation) {
+                throw new Error(`API Error (404): Elicitation not found for request_id: ${requestId}`);
+            }
+            if (elicitation.status !== 'pending') {
+                throw new Error(`API Error (422): Elicitation ${requestId} is not pending (status: ${elicitation.status})`);
+            }
+            elicitation.status = actionType;
+            elicitation.content = actionType === 'accept' ? (content ?? null) : null;
+            return {
+                action: actionType,
+                content: elicitation.content,
+                _meta: { 'com.pulsemcp/request-id': requestId },
+            };
+        },
     };
 }

package/shared/orchestrator-client/orchestrator-client.js

@@ -461,4 +461,14 @@ export class AgentOrchestratorClient {
             apiKey: this.apiKey,
         };
     }
+    // Elicitations
+    async respondToElicitation(requestId, actionType, content) {
+        const body = {
+            action_type: actionType,
+        };
+        if (content !== undefined) {
+            body.content = content;
+        }
+        return this.request('PATCH', `/elicitations/${encodeURIComponent(requestId)}/respond`, body);
+    }
 }

package/shared/tools/respond-to-elicitation.d.ts

@@ -0,0 +1,53 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const RespondToElicitationSchema: z.ZodObject<{
+    request_id: z.ZodString;
+    action_type: z.ZodEnum<["accept", "decline"]>;
+    content: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    request_id: string;
+    action_type: "accept" | "decline";
+    content?: Record<string, unknown> | undefined;
+}, {
+    request_id: string;
+    action_type: "accept" | "decline";
+    content?: Record<string, unknown> | undefined;
+}>;
+export declare function respondToElicitationTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            request_id: {
+                type: string;
+                description: "The elicitation `request_id` — the public identifier the MCP server assigned when it created the elicitation (the `com.pulsemcp/request-id` value, surfaced in the poll URL). This is NOT the database primary key.";
+            };
+            action_type: {
+                type: string;
+                enum: string[];
+                description: "How to resolve the elicitation. \"accept\" approves the request and lets the paused MCP flow continue (optionally with structured `content`); \"decline\" rejects it and unblocks the flow with a declined outcome.";
+            };
+            content: {
+                type: string;
+                description: "Optional structured JSON object supplied with an \"accept\" response (e.g. the form fields the elicitation requested). Ignored for \"decline\". Must be a JSON object, not a scalar or array.";
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+//# sourceMappingURL=respond-to-elicitation.d.ts.map

package/shared/tools/respond-to-elicitation.js

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+const PARAM_DESCRIPTIONS = {
+    request_id: 'The elicitation `request_id` — the public identifier the MCP server assigned when it created the elicitation (the `com.pulsemcp/request-id` value, surfaced in the poll URL). This is NOT the database primary key.',
+    action_type: 'How to resolve the elicitation. "accept" approves the request and lets the paused MCP flow continue (optionally with structured `content`); "decline" rejects it and unblocks the flow with a declined outcome.',
+    content: 'Optional structured JSON object supplied with an "accept" response (e.g. the form fields the elicitation requested). Ignored for "decline". Must be a JSON object, not a scalar or array.',
+};
+export const RespondToElicitationSchema = z.object({
+    request_id: z.string().min(1).describe(PARAM_DESCRIPTIONS.request_id),
+    action_type: z.enum(['accept', 'decline']).describe(PARAM_DESCRIPTIONS.action_type),
+    content: z.record(z.unknown()).optional().describe(PARAM_DESCRIPTIONS.content),
+});
+const TOOL_DESCRIPTION = `Respond to a pending Agent Orchestrator elicitation request — programmatically accept or decline it so the paused MCP flow that is waiting on it can continue.
+
+**Context:** When an MCP server needs human approval (e.g. a write-class action), it creates an *elicitation* and blocks, polling Agent Orchestrator until someone responds. Normally a human clicks "accept" / "decline" in the AO web UI. This tool exposes that same resolution over the API, so an agent or automated test can unblock the flow without a human in the loop.
+
+**What it does:**
+- Looks up the elicitation by its public \`request_id\` (the \`com.pulsemcp/request-id\` identifier, not the DB primary key).
+- Records an \`accept\` (optionally with a structured \`content\` payload) or \`decline\`.
+- Returns the elicitation's resulting poll-response so you can confirm the outcome.
+
+**Example response:**
+\`\`\`
+## Elicitation Accepted
+
+- **Request ID:** req-abc123
+- **Action:** accept
+- **Content:** { "approved": true }
+\`\`\`
+
+**Enum — action_type:**
+- **accept** — Approve the request; the waiting MCP flow proceeds. Pass optional \`content\` to supply the structured data the elicitation asked for.
+- **decline** — Reject the request; the waiting MCP flow unblocks with a declined outcome. \`content\` is ignored.
+
+**Use cases:**
+- Closed-loop testing of an MCP server's elicitation-gated behavior without a human clicking in the UI.
+- Automating approval of a known, expected elicitation as part of a larger orchestrated task.
+
+**Errors:**
+- Unknown \`request_id\` → 404 (elicitation not found).
+- Elicitation already resolved / not pending, or an invalid \`action_type\` → 422.`;
+export function respondToElicitationTool(_server, clientFactory) {
+    return {
+        name: 'respond_to_elicitation',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                request_id: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.request_id,
+                },
+                action_type: {
+                    type: 'string',
+                    enum: ['accept', 'decline'],
+                    description: PARAM_DESCRIPTIONS.action_type,
+                },
+                content: {
+                    type: 'object',
+                    description: PARAM_DESCRIPTIONS.content,
+                },
+            },
+            required: ['request_id', 'action_type'],
+        },
+        handler: async (args) => {
+            try {
+                const { request_id, action_type, content } = RespondToElicitationSchema.parse(args);
+                const client = clientFactory();
+                const response = await client.respondToElicitation(request_id, action_type, content);
+                const lines = [
+                    `## Elicitation ${action_type === 'accept' ? 'Accepted' : 'Declined'}`,
+                    '',
+                    `- **Request ID:** ${request_id}`,
+                    `- **Action:** ${response.action}`,
+                ];
+                if (response.content != null) {
+                    lines.push(`- **Content:** ${JSON.stringify(response.content)}`);
+                }
+                return {
+                    content: [{ type: 'text', text: lines.join('\n') }],
+                };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error responding to elicitation: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.js

@@ -1,5 +1,5 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-// 17 tools across 4 domains + 1 composite group
+// 18 tools across 4 domains + 1 composite group
 import { quickSearchSessionsTool } from './tools/search-sessions.js';
 import { startSessionTool } from './tools/start-session.js';
 import { getSessionTool } from './tools/get-session.js';
@@ -17,6 +17,7 @@ import { wakeMeUpWhenSessionChangesStateTool } from './tools/wake-me-up-when-ses
 import { getSystemHealthTool } from './tools/get-system-health.js';
 import { actionHealthTool } from './tools/action-health.js';
 import { getTranscriptArchiveTool } from './tools/get-transcript-archive.js';
+import { respondToElicitationTool } from './tools/respond-to-elicitation.js';
 /**
  * All valid tool groups (domain groups, their _readonly variants, and composite groups)
  */
@@ -62,7 +63,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
 /**
  * All available tools with their group assignments.
  *
- * 17 tools across 4 domains + 1 composite group:
+ * 18 tools across 4 domains + 1 composite group:
  * - 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; self_session)
  * - get_configs: Fetch all static configuration (sessions, read; self_session)
@@ -71,6 +72,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  * - action_session: Perform session actions (sessions, write; self_session: filtered to update_notes, update_title, archive)
  * - manage_enqueued_messages: Manage session message queue (sessions, write)
  * - manage_categories: Manage dashboard categories and session assignment (sessions, write)
+ * - respond_to_elicitation: Accept or decline a pending elicitation by request_id (sessions, write)
  * - get_notifications: Get/list notifications and badge count (notifications, read)
  * - send_push_notification: Send a push notification (notifications, write; self_session)
  * - action_notification: Mark read, dismiss notifications (notifications, write)
@@ -126,6 +128,11 @@ const ALL_TOOLS = [
         group: 'sessions',
         isWriteOperation: true,
     },
+    {
+        factory: respondToElicitationTool,
+        group: 'sessions',
+        isWriteOperation: true,
+    },
     // Notification tools - read operations
     {
         factory: getNotificationsTool,

package/shared/types.d.ts

@@ -402,6 +402,21 @@ export interface BulkArchiveResponse {
 export interface TranscriptResponse {
     transcript_text: string;
 }
+/** Action taken when responding to a pending elicitation. */
+export type ElicitationActionType = 'accept' | 'decline';
+/**
+ * Poll-response shape returned by the elicitation endpoints.
+ *
+ * `action` is `"pending"` while the elicitation is still open, or the resolved
+ * status (e.g. `"accept"` / `"decline"`) once a response has been recorded.
+ * `content` carries the structured payload supplied with an accepted response
+ * (null when pending or when no content was provided).
+ */
+export interface ElicitationResponse {
+    action: string;
+    content: Record<string, unknown> | null;
+    _meta?: Record<string, unknown>;
+}
 export interface TranscriptArchiveStatusResponse {
     generated_at: string;
     session_count: number;