agent-orchestrator-mcp-server 0.6.8 → 0.7.3

package/build/index.js

@@ -31,7 +31,7 @@ function validateEnvironment() {
     const optional = [
         {
             name: 'TOOL_GROUPS',
-            description: 'Comma-separated list of tool groups to enable (sessions,sessions_readonly,notifications,notifications_readonly,triggers,triggers_readonly,health,health_readonly)',
+            description: 'Comma-separated list of tool groups to enable (sessions,sessions_readonly,notifications,notifications_readonly,triggers,triggers_readonly,health,health_readonly,self_session)',
             defaultValue: 'all groups enabled',
         },
         {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.6.8",
+  "version": "0.7.3",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",
@@ -29,7 +29,7 @@
     "stage-publish": "npm version"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.19.1",
+    "@modelcontextprotocol/sdk": "^1.26.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {

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

@@ -50,8 +50,12 @@ export interface IAgentOrchestratorClient {
     deleteSession(id: string | number): Promise<void>;
     archiveSession(id: string | number): Promise<Session>;
     unarchiveSession(id: string | number): Promise<Session>;
-    followUp(id: string | number, prompt: string): Promise<SessionActionResponse>;
+    followUp(id: string | number, prompt: string, options?: {
+        force_immediate?: boolean;
+        stop_condition?: string;
+    }): Promise<SessionActionResponse>;
     pauseSession(id: string | number): Promise<SessionActionResponse>;
+    sleepSession(id: string | number): Promise<Session>;
     restartSession(id: string | number): Promise<SessionActionResponse>;
     changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
     changeModel(id: string | number, model: string): Promise<Session>;
@@ -173,8 +177,12 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     deleteSession(id: string | number): Promise<void>;
     archiveSession(id: string | number): Promise<Session>;
     unarchiveSession(id: string | number): Promise<Session>;
-    followUp(id: string | number, prompt: string): Promise<SessionActionResponse>;
+    followUp(id: string | number, prompt: string, options?: {
+        force_immediate?: boolean;
+        stop_condition?: string;
+    }): Promise<SessionActionResponse>;
     pauseSession(id: string | number): Promise<SessionActionResponse>;
+    sleepSession(id: string | number): Promise<Session>;
     restartSession(id: string | number): Promise<SessionActionResponse>;
     changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
     changeModel(id: string | number, model: string): Promise<Session>;

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

@@ -204,19 +204,27 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             session.updated_at = new Date().toISOString();
             return session;
         },
-        async followUp(id, prompt) {
+        async followUp(id, prompt, options) {
             const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
             if (!session) {
                 throw new Error(`API Error (404): Session not found`);
             }
-            if (session.status !== 'needs_input') {
+            if (options?.force_immediate) {
+                if (session.status === 'failed' || session.status === 'archived') {
+                    throw new Error(`API Error (422): Session cannot receive follow-up in ${session.status} status`);
+                }
+            }
+            else if (session.status !== 'needs_input') {
                 throw new Error(`API Error (422): Session is not in needs_input status`);
             }
             session.prompt = prompt;
             session.status = 'running';
             session.running_job_id = `job_${Date.now()}`;
             session.updated_at = new Date().toISOString();
-            return { session, message: 'Follow-up prompt sent' };
+            const message = options?.force_immediate
+                ? 'Follow-up prompt sent immediately'
+                : 'Follow-up prompt sent';
+            return { session, message };
         },
         async pauseSession(id) {
             const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
@@ -228,6 +236,18 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             session.updated_at = new Date().toISOString();
             return { session, message: 'Session paused' };
         },
+        async sleepSession(id) {
+            const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            if (session.status !== 'needs_input') {
+                throw new Error(`API Error (422): Session must be in needs_input state to sleep`);
+            }
+            session.status = 'waiting';
+            session.updated_at = new Date().toISOString();
+            return session;
+        },
         async restartSession(id) {
             const session = mockData.sessions?.find((s) => s.id === Number(id) || s.slug === String(id));
             if (!session) {

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

@@ -204,12 +204,20 @@ export class AgentOrchestratorClient {
         const response = await this.request('POST', `/sessions/${id}/unarchive`);
         return response.session;
     }
-    async followUp(id, prompt) {
-        return this.request('POST', `/sessions/${id}/follow_up`, { prompt });
+    async followUp(id, prompt, options) {
+        return this.request('POST', `/sessions/${id}/follow_up`, {
+            prompt,
+            ...(options?.force_immediate && { force_immediate: true }),
+            ...(options?.stop_condition && { stop_condition: options.stop_condition }),
+        });
     }
     async pauseSession(id) {
         return this.request('POST', `/sessions/${id}/pause`);
     }
+    async sleepSession(id) {
+        const response = await this.request('POST', `/sessions/${id}/sleep`);
+        return response.session;
+    }
     async restartSession(id) {
         return this.request('POST', `/sessions/${id}/restart`);
     }

package/shared/resources.js

@@ -74,6 +74,7 @@ export function createRegisterResources(clientFactory) {
                         triggers_readonly: 'Trigger tools (read only): search_triggers',
                         health: 'All health tools (read + write): health report, CLI status, maintenance actions',
                         health_readonly: 'Health tools (read only): get_system_health',
+                        self_session: 'Self-management tools for auto-injected servers: get_session, get_configs (read), action_session (filtered: update_notes, update_title, archive), send_push_notification',
                     },
                 };
                 return {

package/shared/server.d.ts

@@ -13,6 +13,9 @@ export declare function createMCPServer(options: CreateMCPServerOptions): {
             _meta?: {
                 [x: string]: unknown;
                 progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
             } | undefined;
         } | undefined;
     }, {
@@ -21,12 +24,20 @@ export declare function createMCPServer(options: CreateMCPServerOptions): {
             [x: string]: unknown;
             _meta?: {
                 [x: string]: unknown;
+                progressToken?: string | number | undefined;
+                "io.modelcontextprotocol/related-task"?: {
+                    taskId: string;
+                } | undefined;
             } | undefined;
         } | undefined;
     }, {
         [x: string]: unknown;
         _meta?: {
             [x: string]: unknown;
+            progressToken?: string | number | undefined;
+            "io.modelcontextprotocol/related-task"?: {
+                taskId: string;
+            } | undefined;
         } | undefined;
     }>;
     registerHandlers: (server: Server, clientFactory?: ClientFactory) => Promise<void>;

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

@@ -5,6 +5,7 @@ export declare const ActionSessionSchema: z.ZodObject<{
     session_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
     action: z.ZodEnum<["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"]>;
     prompt: z.ZodOptional<z.ZodString>;
+    force_immediate: z.ZodOptional<z.ZodBoolean>;
     mcp_servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     model: z.ZodOptional<z.ZodString>;
     message_index: z.ZodOptional<z.ZodNumber>;
@@ -17,6 +18,7 @@ export declare const ActionSessionSchema: z.ZodObject<{
     title?: string | undefined;
     mcp_servers?: string[] | undefined;
     session_id?: string | number | undefined;
+    force_immediate?: boolean | undefined;
     model?: string | undefined;
     message_index?: number | undefined;
     session_notes?: string | undefined;
@@ -27,6 +29,7 @@ export declare const ActionSessionSchema: z.ZodObject<{
     title?: string | undefined;
     mcp_servers?: string[] | undefined;
     session_id?: string | number | undefined;
+    force_immediate?: boolean | undefined;
     model?: string | undefined;
     message_index?: number | undefined;
     session_notes?: string | undefined;
@@ -53,6 +56,10 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
                 type: string;
                 description: "Required for \"follow_up\" action. The prompt to send to the agent. Not used for other actions.";
             };
+            force_immediate: {
+                type: string;
+                description: "Optional for \"follow_up\" action. When true, interrupts a running session to deliver the prompt immediately instead of queuing it. Not used for other actions.";
+            };
             mcp_servers: {
                 type: string;
                 items: {
@@ -100,4 +107,62 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
         isError?: undefined;
     }>;
 };
+export declare const SelfSessionActionSessionSchema: z.ZodObject<{
+    session_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    action: z.ZodEnum<["update_notes", "update_title", "archive"]>;
+    session_notes: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    session_id: string | number;
+    action: "archive" | "update_notes" | "update_title";
+    title?: string | undefined;
+    session_notes?: string | undefined;
+}, {
+    session_id: string | number;
+    action: "archive" | "update_notes" | "update_title";
+    title?: string | undefined;
+    session_notes?: string | undefined;
+}>;
+export declare function selfSessionActionSessionTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            session_id: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: "Session ID (numeric) or slug (string). Required for most actions. Not required for \"refresh_all\" and \"bulk_archive\".";
+            };
+            action: {
+                type: string;
+                enum: readonly ["update_notes", "update_title", "archive"];
+                description: string;
+            };
+            session_notes: {
+                type: string;
+                description: "Required for \"update_notes\" action. The notes text to set on the session.";
+            };
+            title: {
+                type: string;
+                description: "Required for \"update_title\" action. The new title for the session.";
+            };
+        };
+        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

@@ -4,6 +4,7 @@ const PARAM_DESCRIPTIONS = {
     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", "change_model", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"',
     prompt: 'Required for "follow_up" action. The prompt to send to the agent. Not used for other actions.',
+    force_immediate: 'Optional for "follow_up" action. When true, interrupts a running session to deliver the prompt immediately instead of queuing it. Not used for other actions.',
     mcp_servers: 'Required for "change_mcp_servers" action. Array of MCP server names to set for the session.',
     model: 'Required for "change_model" action. The model identifier to use (e.g., "opus", "sonnet").',
     message_index: 'Required for "fork" action. The transcript message index to fork from.',
@@ -31,6 +32,7 @@ export const ActionSessionSchema = z.object({
     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),
+    force_immediate: z.boolean().optional().describe(PARAM_DESCRIPTIONS.force_immediate),
     mcp_servers: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.mcp_servers),
     model: z.string().optional().describe(PARAM_DESCRIPTIONS.model),
     message_index: z.number().optional().describe(PARAM_DESCRIPTIONS.message_index),
@@ -41,7 +43,7 @@ export const ActionSessionSchema = z.object({
 const TOOL_DESCRIPTION = `Perform an action on an agent session.
 
 **Actions:**
-- **follow_up**: Send a follow-up prompt to an idle session (requires "prompt" parameter)
+- **follow_up**: Send a follow-up prompt to a session (requires "prompt"; optional "force_immediate" to interrupt a running session). Without "force_immediate", uses smart routing: sends immediately if idle, auto-queues if running. Alternative: use manage_enqueued_messages "send_now" for one-step immediate delivery with stop_condition support.
 - **pause**: Pause a running session, transitioning it to idle "needs_input" status
 - **restart**: Restart an idle or failed session without providing new input
 - **archive**: Archive a session (marks as completed)
@@ -82,6 +84,10 @@ export function actionSessionTool(_server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.prompt,
                 },
+                force_immediate: {
+                    type: 'boolean',
+                    description: PARAM_DESCRIPTIONS.force_immediate,
+                },
                 mcp_servers: {
                     type: 'array',
                     items: { type: 'string' },
@@ -115,7 +121,7 @@ export function actionSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = ActionSessionSchema.parse(args);
                 const client = clientFactory();
-                const { session_id, action, prompt, mcp_servers, model, message_index, session_notes, session_ids, title, } = validatedArgs;
+                const { session_id, action, prompt, force_immediate, mcp_servers, model, message_index, session_notes, session_ids, title, } = validatedArgs;
                 // Actions that require session_id
                 const requiresSessionId = [
                     'follow_up',
@@ -241,9 +247,13 @@ export function actionSessionTool(_server, clientFactory) {
                 let result;
                 switch (action) {
                     case 'follow_up': {
-                        const response = await client.followUp(session_id, prompt);
+                        const response = await client.followUp(session_id, prompt, {
+                            force_immediate,
+                        });
+                        const immediate = response.message?.toLowerCase().includes('immediately');
+                        const heading = immediate ? 'Follow-up Sent Immediately' : 'Follow-up Sent';
                         const lines = [
-                            `## Follow-up Sent`,
+                            `## ${heading}`,
                             '',
                             `- **Session ID:** ${response.session.id}`,
                             `- **Title:** ${response.session.title}`,
@@ -393,7 +403,9 @@ export function actionSessionTool(_server, clientFactory) {
                         break;
                     }
                     case 'update_title': {
-                        const session = await client.updateSession(session_id, { title: title });
+                        const session = await client.updateSession(session_id, {
+                            title: title,
+                        });
                         const lines = [
                             `## Session Title Updated`,
                             '',
@@ -463,3 +475,155 @@ export function actionSessionTool(_server, clientFactory) {
         },
     };
 }
+// =============================================================================
+// SELF-SESSION VARIANT
+// =============================================================================
+// Restricted version of action_session for the self_session composite group.
+// Only allows self-management actions: update_notes, update_title, archive.
+// =============================================================================
+const SELF_SESSION_ACTION_ENUM = ['update_notes', 'update_title', 'archive'];
+export const SelfSessionActionSessionSchema = z.object({
+    session_id: z.union([z.string(), z.number()]).describe(PARAM_DESCRIPTIONS.session_id),
+    action: z
+        .enum(SELF_SESSION_ACTION_ENUM)
+        .describe('Action to perform: "update_notes", "update_title", "archive"'),
+    session_notes: z.string().optional().describe(PARAM_DESCRIPTIONS.session_notes),
+    title: z.string().optional().describe(PARAM_DESCRIPTIONS.title),
+});
+const SELF_SESSION_TOOL_DESCRIPTION = `Perform a self-management action on a session.
+
+**Actions (limited to self-management):**
+- **update_notes**: Update the notes on a session (requires "session_notes")
+- **update_title**: Update the title of a session (requires "title")
+- **archive**: Archive a session (marks as completed)
+
+**Use cases:**
+- Update session notes to record progress or context
+- Set a meaningful session title
+- Archive the session when work is complete`;
+export function selfSessionActionSessionTool(_server, clientFactory) {
+    return {
+        name: 'action_session',
+        description: SELF_SESSION_TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }],
+                    description: PARAM_DESCRIPTIONS.session_id,
+                },
+                action: {
+                    type: 'string',
+                    enum: SELF_SESSION_ACTION_ENUM,
+                    description: 'Action to perform: "update_notes", "update_title", "archive"',
+                },
+                session_notes: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.session_notes,
+                },
+                title: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.title,
+                },
+            },
+            required: ['session_id', 'action'],
+        },
+        handler: async (args) => {
+            try {
+                const validatedArgs = SelfSessionActionSessionSchema.parse(args);
+                const client = clientFactory();
+                const { session_id, action, session_notes, title } = validatedArgs;
+                // 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 update_title requires title
+                if (action === 'update_title' && !title) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "title" parameter is required for the "update_title" action.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                let result;
+                switch (action) {
+                    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 '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 'update_title': {
+                        const session = await client.updateSession(session_id, {
+                            title: title,
+                        });
+                        const lines = [
+                            `## Session Title Updated`,
+                            '',
+                            `- **Session ID:** ${session.id}`,
+                            `- **Title:** ${session.title}`,
+                        ];
+                        result = lines.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 performing action: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

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

@@ -19,8 +19,8 @@ export declare const ActionTriggerSchema: z.ZodObject<{
     stop_condition?: string | undefined;
     mcp_servers?: string[] | undefined;
     trigger_type?: "slack" | "schedule" | undefined;
-    name?: string | undefined;
     id?: number | undefined;
+    name?: string | undefined;
     agent_root_name?: string | undefined;
     prompt_template?: string | undefined;
     reuse_session?: boolean | undefined;
@@ -31,8 +31,8 @@ export declare const ActionTriggerSchema: z.ZodObject<{
     stop_condition?: string | undefined;
     mcp_servers?: string[] | undefined;
     trigger_type?: "slack" | "schedule" | undefined;
-    name?: string | undefined;
     id?: number | undefined;
+    name?: string | undefined;
     agent_root_name?: string | undefined;
     prompt_template?: string | undefined;
     reuse_session?: boolean | undefined;

package/shared/tools/action-trigger.js

@@ -24,7 +24,11 @@ const TOOL_DESCRIPTION = `Create, update, delete, or toggle automation triggers.
 
 **Trigger types:**
 - **slack**: Triggered by Slack events (requires configuration with channel_id)
-- **schedule**: Triggered on a schedule (requires configuration with interval, unit, etc.)
+- **schedule**: Triggered on a recurring or one-time schedule
+
+**Schedule configuration:**
+- **Recurring**: \`{"interval": 2, "unit": "hours", "timezone": "UTC"}\` — fires every N units
+- **One-time**: \`{"scheduled_at": "2026-04-15T14:30:00", "timezone": "America/New_York"}\` — fires once at the specified datetime (ISO 8601), then auto-disables
 
 Use search_triggers first to see available triggers and Slack channels.`;
 export function actionTriggerTool(_server, clientFactory) {

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

@@ -3,7 +3,7 @@ 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"]>;
+    action: z.ZodEnum<["list", "get", "create", "update", "delete", "reorder", "interrupt", "send_now"]>;
     message_id: z.ZodOptional<z.ZodNumber>;
     content: z.ZodOptional<z.ZodString>;
     stop_condition: z.ZodOptional<z.ZodString>;
@@ -12,7 +12,7 @@ export declare const ManageEnqueuedMessagesSchema: z.ZodObject<{
     per_page: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     session_id: string | number;
-    action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt";
+    action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt" | "send_now";
     per_page?: number | undefined;
     page?: number | undefined;
     stop_condition?: string | undefined;
@@ -21,7 +21,7 @@ export declare const ManageEnqueuedMessagesSchema: z.ZodObject<{
     position?: number | undefined;
 }, {
     session_id: string | number;
-    action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt";
+    action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt" | "send_now";
     per_page?: number | undefined;
     page?: number | undefined;
     stop_condition?: string | undefined;
@@ -43,7 +43,7 @@ export declare function manageEnqueuedMessagesTool(_server: Server, clientFactor
             };
             action: {
                 type: string;
-                enum: readonly ["list", "get", "create", "update", "delete", "reorder", "interrupt"];
+                enum: readonly ["list", "get", "create", "update", "delete", "reorder", "interrupt", "send_now"];
                 description: string;
             };
             message_id: {

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

@@ -1,5 +1,14 @@
 import { z } from 'zod';
-const ACTION_ENUM = ['list', 'get', 'create', 'update', 'delete', 'reorder', 'interrupt'];
+const ACTION_ENUM = [
+    'list',
+    'get',
+    'create',
+    'update',
+    'delete',
+    'reorder',
+    'interrupt',
+    'send_now',
+];
 export const ManageEnqueuedMessagesSchema = z.object({
     session_id: z.union([z.string(), z.number()]),
     action: z.enum(ACTION_ENUM),
@@ -10,18 +19,23 @@ export const ManageEnqueuedMessagesSchema = z.object({
     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.
+const TOOL_DESCRIPTION = `Queue messages for later delivery or send messages immediately to 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")
+**Quick guide — two ways to send a message:**
+- **send_now**: Interrupt the session and deliver a message immediately, even if the session is running. One step — just provide "content".
+- **create**: Add a message to the queue for delivery when the session finishes its current work. Does NOT send immediately.
+
+Use "send_now" when you need the agent to act on something urgently. Use "create" when the message can wait until the session is idle.
+
+**All actions:**
+- **send_now**: Interrupt the session and deliver a message immediately (requires "content"). The session is paused, the message is sent, and the session resumes with this message. Works regardless of session state.
+- **create**: Add a new message to the end of the queue for later delivery (requires "content"). The message waits until the session becomes idle.
+- **list**: List all enqueued messages for a session (supports pagination with "page" and "per_page")
+- **get**: Get a specific enqueued message by ID (requires "message_id")
+- **update**: Update an existing queued message's content or stop condition (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.`;
+- **interrupt**: Pause the session and send an existing queued message immediately (requires "message_id"). Prefer "send_now" for new messages — "interrupt" is for promoting an already-queued message.`;
 export function manageEnqueuedMessagesTool(_server, clientFactory) {
     return {
         name: 'manage_enqueued_messages',
@@ -36,7 +50,7 @@ export function manageEnqueuedMessagesTool(_server, clientFactory) {
                 action: {
                     type: 'string',
                     enum: ACTION_ENUM,
-                    description: 'Action to perform on enqueued messages.',
+                    description: 'Action to perform. Use "send_now" to interrupt and deliver immediately. Use "create" to queue for later.',
                 },
                 message_id: {
                     type: 'number',
@@ -44,11 +58,11 @@ export function manageEnqueuedMessagesTool(_server, clientFactory) {
                 },
                 content: {
                     type: 'string',
-                    description: 'Message content. Required for create. Optional for update.',
+                    description: 'Message content. Required for create and send_now. Optional for update.',
                 },
                 stop_condition: {
                     type: 'string',
-                    description: 'Stop condition for this message. Optional for create and update.',
+                    description: 'Stop condition for this message. Optional for create, send_now, and update.',
                 },
                 position: {
                     type: 'number',
@@ -132,7 +146,9 @@ export function manageEnqueuedMessagesTool(_server, clientFactory) {
                             stop_condition: stop_condition || undefined,
                         });
                         result = [
-                            '## Message Enqueued',
+                            '## Message Queued',
+                            '',
+                            `Message added to queue — it will be delivered when the session becomes idle.`,
                             '',
                             `- **ID:** ${msg.id}`,
                             `- **Position:** ${msg.position}`,
@@ -233,6 +249,33 @@ export function manageEnqueuedMessagesTool(_server, clientFactory) {
                         ].join('\n');
                         break;
                     }
+                    case 'send_now': {
+                        if (!content) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "content" is required for the "send_now" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const response = await client.followUp(session_id, content, {
+                            force_immediate: true,
+                            stop_condition: stop_condition || undefined,
+                        });
+                        result = [
+                            '## Message Sent Immediately',
+                            '',
+                            `The session was interrupted and the message was delivered.`,
+                            '',
+                            `- **Session ID:** ${response.session.id}`,
+                            `- **Session Status:** ${response.session.status}`,
+                            `- **Result:** ${response.message}`,
+                        ].join('\n');
+                        break;
+                    }
                     default: {
                         const _exhaustiveCheck = action;
                         return {

package/shared/tools/wake-me-up-later.d.ts

@@ -0,0 +1,61 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const WakeMeUpLaterSchema: z.ZodObject<{
+    session_id: z.ZodUnion<[z.ZodString, z.ZodNumber]>;
+    wake_at: z.ZodString;
+    timezone: z.ZodOptional<z.ZodString>;
+    prompt: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    prompt: string;
+    session_id: string | number;
+    wake_at: string;
+    timezone?: string | undefined;
+}, {
+    prompt: string;
+    session_id: string | number;
+    wake_at: string;
+    timezone?: string | undefined;
+}>;
+export declare function wakeMeUpLaterTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            session_id: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: string;
+            };
+            wake_at: {
+                type: string;
+                description: string;
+            };
+            timezone: {
+                type: string;
+                description: string;
+            };
+            prompt: {
+                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=wake-me-up-later.d.ts.map

package/shared/tools/wake-me-up-later.js

@@ -0,0 +1,148 @@
+import { z } from 'zod';
+import { parseAllowedAgentRoots } from '../allowed-agent-roots.js';
+export const WakeMeUpLaterSchema = z.object({
+    session_id: z.union([z.string(), z.number()]),
+    wake_at: z.string(),
+    timezone: z.string().optional(),
+    prompt: z.string(),
+});
+function buildToolDescription() {
+    const now = new Date();
+    const utcNow = now.toISOString().replace(/\.\d{3}Z$/, 'Z');
+    return `Schedule this session to be woken up at a specific time. The session will be put to sleep (waiting status) and a one-time trigger will fire at the specified time to resume it with the given prompt. If the session is manually resumed before the scheduled time, the trigger will be silently dropped.
+
+**Current server time:** ${utcNow} (UTC). Use this as your reference point when calculating wake-up times.
+
+**Timezone handling:**
+- The \`wake_at\` parameter is interpreted in the timezone specified by \`timezone\` (default: "UTC").
+- To schedule "30 minutes from now": take the current UTC time above, add 30 minutes, and pass that as \`wake_at\` with timezone "UTC" (or omit timezone).
+- To schedule at a wall-clock time in a specific timezone (e.g., "9am Eastern"): pass \`wake_at\` as "2026-04-15T09:00:00" with timezone "America/New_York". The server converts to UTC internally.
+- Use IANA timezone names (e.g., "America/New_York", "Europe/London", "Asia/Tokyo"). Do NOT pass UTC offsets like "+05:00" in the timezone parameter.
+- If you omit timezone, wake_at is treated as UTC.
+
+**Parameters:**
+- **session_id**: The session to wake up (must be in needs_input state)
+- **wake_at**: ISO 8601 datetime without offset for when to wake up (e.g., "2026-04-15T14:30:00")
+- **timezone**: IANA timezone for interpreting wake_at (default: "UTC", e.g., "America/New_York")
+- **prompt**: The prompt to send when waking up the session
+
+**What happens:**
+1. Validates the session is in needs_input state
+2. Puts the session to sleep (waiting status)
+3. Creates a one-time schedule trigger that fires at the specified time
+4. The trigger resumes the session with the provided prompt`;
+}
+export function wakeMeUpLaterTool(_server, clientFactory) {
+    return {
+        name: 'wake_me_up_later',
+        description: buildToolDescription(),
+        inputSchema: {
+            type: 'object',
+            properties: {
+                session_id: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }],
+                    description: 'Session ID (numeric) or slug (string). Must be in needs_input state.',
+                },
+                wake_at: {
+                    type: 'string',
+                    description: 'ISO 8601 datetime for when to wake up (e.g., "2026-04-15T14:30:00").',
+                },
+                timezone: {
+                    type: 'string',
+                    description: 'Timezone for the wake_at datetime. Default: "UTC".',
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'The prompt to send when waking up the session.',
+                },
+            },
+            required: ['session_id', 'wake_at', 'prompt'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = WakeMeUpLaterSchema.parse(args);
+                const client = clientFactory();
+                const { session_id, wake_at, prompt } = validated;
+                const timezone = validated.timezone || 'UTC';
+                if (parseAllowedAgentRoots() !== null) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: wake_me_up_later is not allowed when ALLOWED_AGENT_ROOTS is set. Triggers cannot be created because sessions are restricted to specific preconfigured agent roots.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const session = await client.getSession(session_id);
+                if (session.status !== 'needs_input') {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: Session must be in "needs_input" state to sleep (current: "${session.status}"). Only idle sessions can be scheduled for a delayed wake-up.`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                const sleepingSession = await client.sleepSession(session_id);
+                let trigger;
+                try {
+                    trigger = await client.createTrigger({
+                        name: `Wake session #${sleepingSession.id} at ${wake_at}`,
+                        trigger_type: 'schedule',
+                        agent_root_name: session.agent_type,
+                        prompt_template: prompt,
+                        reuse_session: true,
+                        configuration: {
+                            scheduled_at: wake_at,
+                            timezone,
+                        },
+                    });
+                }
+                catch (triggerError) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: `Error: Session ${sleepingSession.id} was put to sleep (waiting status) but trigger creation failed: ${triggerError instanceof Error ? triggerError.message : 'Unknown error'}. The session is now in "waiting" state and needs manual intervention (use action_session with "restart" or "follow_up" to recover).`,
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
+                await client.updateSession(session_id, {
+                    custom_metadata: {
+                        ...session.custom_metadata,
+                        wake_trigger_id: trigger.id,
+                    },
+                });
+                const lines = [
+                    '## Session Scheduled for Wake-Up',
+                    '',
+                    `- **Session ID:** ${sleepingSession.id}`,
+                    `- **Session Status:** ${sleepingSession.status}`,
+                    `- **Wake At:** ${wake_at} (${timezone})`,
+                    `- **Trigger ID:** ${trigger.id}`,
+                    `- **Trigger Name:** ${trigger.name}`,
+                    '',
+                    'The session is now sleeping. It will be automatically resumed at the scheduled time with the provided prompt.',
+                ];
+                return { content: [{ type: 'text', text: lines.join('\n') }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error scheduling wake-up: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools.d.ts

@@ -2,9 +2,10 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { ClientFactory } from './server.js';
 /**
  * Available tool groups for agent-orchestrator.
- * Each domain has a base group (full access) and a _readonly variant (read-only).
+ * - Domain groups: each domain has a base group (full access) and a _readonly variant (read-only)
+ * - Composite groups: curated cross-domain tool sets (e.g., self_session)
  */
-export type ToolGroup = 'sessions' | 'sessions_readonly' | 'notifications' | 'notifications_readonly' | 'triggers' | 'triggers_readonly' | 'health' | 'health_readonly';
+export type ToolGroup = 'sessions' | 'sessions_readonly' | 'notifications' | 'notifications_readonly' | 'triggers' | 'triggers_readonly' | 'health' | 'health_readonly' | 'self_session';
 /**
  * Parse enabled tool groups from environment variable or parameter.
  * @param enabledGroupsParam - Comma-separated list of groups (e.g., "sessions,notifications")

package/shared/tools.js

@@ -1,9 +1,9 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-// 13 tools across 4 domains
+// 15 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';
-import { actionSessionTool } from './tools/action-session.js';
+import { actionSessionTool, selfSessionActionSessionTool } from './tools/action-session.js';
 import { getConfigsTool } from './tools/get-configs.js';
 import { manageEnqueuedMessagesTool } from './tools/manage-enqueued-messages.js';
 import { sendPushNotificationTool } from './tools/send-push-notification.js';
@@ -11,11 +11,12 @@ import { getNotificationsTool } from './tools/get-notifications.js';
 import { actionNotificationTool } from './tools/action-notification.js';
 import { searchTriggersTool } from './tools/search-triggers.js';
 import { actionTriggerTool } from './tools/action-trigger.js';
+import { wakeMeUpLaterTool } from './tools/wake-me-up-later.js';
 import { getSystemHealthTool } from './tools/get-system-health.js';
 import { actionHealthTool } from './tools/action-health.js';
 import { getTranscriptArchiveTool } from './tools/get-transcript-archive.js';
 /**
- * All valid tool groups (base groups and their _readonly variants)
+ * All valid tool groups (domain groups, their _readonly variants, and composite groups)
  */
 const VALID_TOOL_GROUPS = [
     'sessions',
@@ -26,6 +27,7 @@ const VALID_TOOL_GROUPS = [
     'triggers_readonly',
     'health',
     'health_readonly',
+    'self_session',
 ];
 /**
  * Base groups (without _readonly suffix) - used for default "all groups" behavior
@@ -58,41 +60,91 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
 /**
  * All available tools with their group assignments.
  *
- * 14 tools across 4 domains:
+ * 15 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)
- * - get_configs: Fetch all static configuration (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)
  * - get_transcript_archive: Get transcript archive download URL and metadata (sessions, read)
  * - start_session: Create a new session (sessions, write)
- * - action_session: Perform session actions (sessions, write)
+ * - 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)
  * - get_notifications: Get/list notifications and badge count (notifications, read)
- * - send_push_notification: Send a push notification (notifications, write)
+ * - send_push_notification: Send a push notification (notifications, write; self_session)
  * - action_notification: Mark read, dismiss notifications (notifications, write)
  * - search_triggers: Search/list automation triggers (triggers, read)
  * - action_trigger: Create, update, delete, toggle triggers (triggers, write)
+ * - wake_me_up_later: Schedule a session to be woken up at a specific time (triggers, write; self_session)
  * - get_system_health: Get system health report and CLI status (health, read)
  * - action_health: System maintenance actions (health, write)
  */
 const ALL_TOOLS = [
     // Session tools - read operations
-    { factory: quickSearchSessionsTool, group: 'sessions', isWriteOperation: false },
-    { factory: getSessionTool, group: 'sessions', isWriteOperation: false },
-    { factory: getConfigsTool, group: 'sessions', isWriteOperation: false },
-    { factory: getTranscriptArchiveTool, group: 'sessions', isWriteOperation: false },
+    {
+        factory: quickSearchSessionsTool,
+        group: 'sessions',
+        isWriteOperation: false,
+    },
+    {
+        factory: getSessionTool,
+        group: 'sessions',
+        isWriteOperation: false,
+        compositeGroups: ['self_session'],
+    },
+    {
+        factory: getConfigsTool,
+        group: 'sessions',
+        isWriteOperation: false,
+        compositeGroups: ['self_session'],
+    },
+    {
+        factory: getTranscriptArchiveTool,
+        group: 'sessions',
+        isWriteOperation: false,
+    },
     // Session tools - write operations
     { factory: startSessionTool, group: 'sessions', isWriteOperation: true },
-    { factory: actionSessionTool, group: 'sessions', isWriteOperation: true },
-    { factory: manageEnqueuedMessagesTool, group: 'sessions', isWriteOperation: true },
+    {
+        factory: actionSessionTool,
+        group: 'sessions',
+        isWriteOperation: true,
+        compositeGroups: ['self_session'],
+        compositeGroupFactoryOverrides: {
+            self_session: selfSessionActionSessionTool,
+        },
+    },
+    {
+        factory: manageEnqueuedMessagesTool,
+        group: 'sessions',
+        isWriteOperation: true,
+    },
     // Notification tools - read operations
-    { factory: getNotificationsTool, group: 'notifications', isWriteOperation: false },
+    {
+        factory: getNotificationsTool,
+        group: 'notifications',
+        isWriteOperation: false,
+    },
     // Notification tools - write operations
-    { factory: sendPushNotificationTool, group: 'notifications', isWriteOperation: true },
-    { factory: actionNotificationTool, group: 'notifications', isWriteOperation: true },
+    {
+        factory: sendPushNotificationTool,
+        group: 'notifications',
+        isWriteOperation: true,
+        compositeGroups: ['self_session'],
+    },
+    {
+        factory: actionNotificationTool,
+        group: 'notifications',
+        isWriteOperation: true,
+    },
     // Trigger tools - read operations
     { factory: searchTriggersTool, group: 'triggers', isWriteOperation: false },
     // Trigger tools - write operations
     { factory: actionTriggerTool, group: 'triggers', isWriteOperation: true },
+    {
+        factory: wakeMeUpLaterTool,
+        group: 'triggers',
+        isWriteOperation: true,
+        compositeGroups: ['self_session'],
+    },
     // Health tools - read operations
     { factory: getSystemHealthTool, group: 'health', isWriteOperation: false },
     // Health tools - write operations
@@ -115,8 +167,48 @@ function shouldIncludeTool(toolDef, enabledGroups) {
     if (enabledGroups.includes(readonlyGroup) && !toolDef.isWriteOperation) {
         return true;
     }
+    // Check if any composite group that includes this tool is enabled
+    if (toolDef.compositeGroups) {
+        for (const compositeGroup of toolDef.compositeGroups) {
+            if (enabledGroups.includes(compositeGroup)) {
+                return true;
+            }
+        }
+    }
     return false;
 }
+/**
+ * Determine which factory to use for a tool based on enabled groups.
+ * Domain groups (base/readonly) use the default factory. Composite groups
+ * may have factory overrides (e.g., restricted action_session for self_session).
+ * Domain base group takes precedence over composite group overrides.
+ *
+ * Priority: base group > readonly group > composite group override > default factory.
+ * A write operation with only the readonly group enabled is NOT covered by the
+ * domain group — it falls through to composite group override logic.
+ */
+function getToolFactory(toolDef, enabledGroups) {
+    const baseGroup = toolDef.group;
+    const readonlyGroup = `${baseGroup}_readonly`;
+    // If included via base group (full access), always use the default factory
+    if (enabledGroups.includes(baseGroup)) {
+        return toolDef.factory;
+    }
+    // If included via readonly group AND this is a read operation, use the default factory
+    if (enabledGroups.includes(readonlyGroup) && !toolDef.isWriteOperation) {
+        return toolDef.factory;
+    }
+    // Otherwise, the tool is included via a composite group — check for factory overrides
+    if (toolDef.compositeGroupFactoryOverrides && toolDef.compositeGroups) {
+        for (const compositeGroup of toolDef.compositeGroups) {
+            if (enabledGroups.includes(compositeGroup) &&
+                toolDef.compositeGroupFactoryOverrides[compositeGroup]) {
+                return toolDef.compositeGroupFactoryOverrides[compositeGroup];
+            }
+        }
+    }
+    return toolDef.factory;
+}
 /**
  * Creates a function to register all tools with the server.
  * This pattern uses individual tool files for better modularity and testability.
@@ -133,8 +225,11 @@ export function createRegisterTools(clientFactory, enabledGroups) {
         const enabledToolGroups = parseEnabledToolGroups(enabledGroups);
         // Filter tools based on enabled groups
         const enabledTools = ALL_TOOLS.filter((toolDef) => shouldIncludeTool(toolDef, enabledToolGroups));
-        // Create tool instances
-        const tools = enabledTools.map((toolDef) => toolDef.factory(server, clientFactory));
+        // Create tool instances (using factory overrides for composite groups when applicable)
+        const tools = enabledTools.map((toolDef) => {
+            const factory = getToolFactory(toolDef, enabledToolGroups);
+            return factory(server, clientFactory);
+        });
         // List available tools
         server.setRequestHandler(ListToolsRequestSchema, async () => {
             return {