agent-orchestrator-mcp-server 0.7.3 → 0.7.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.7.3",
+  "version": "0.7.9",
   "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.26.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "zod": "^3.24.1"
   },
   "devDependencies": {

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

@@ -241,8 +241,8 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             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`);
+            if (session.status !== 'needs_input' && session.status !== 'running') {
+                throw new Error(`API Error (422): Session must be in needs_input or running state to sleep (current: ${session.status})`);
             }
             session.status = 'waiting';
             session.updated_at = new Date().toISOString();
@@ -633,7 +633,7 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             return {
                 id: 1,
                 name: data.name,
-                trigger_type: data.trigger_type,
+                trigger_type: data.trigger_type || 'schedule',
                 status: data.status || 'enabled',
                 agent_root_name: data.agent_root_name,
                 prompt_template: data.prompt_template,
@@ -642,7 +642,7 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 mcp_servers: data.mcp_servers || [],
                 configuration: data.configuration || {},
                 schedule_description: null,
-                last_session_id: null,
+                last_session_id: data.last_session_id ?? null,
                 last_triggered_at: null,
                 last_polled_at: null,
                 sessions_created_count: 0,

package/shared/tools/action-session.js

@@ -500,7 +500,12 @@ const SELF_SESSION_TOOL_DESCRIPTION = `Perform a self-management action on a ses
 **Use cases:**
 - Update session notes to record progress or context
 - Set a meaningful session title
-- Archive the session when work is complete`;
+- Archive the session when work is complete
+
+**Archive guidelines:**
+- Only self-archive when explicitly instructed to (e.g., a stop condition says "archive yourself")
+- Subagents that report results back to a parent agent via a tool call may self-archive, since no human needs to read the session output directly
+- Do NOT self-archive if a human user needs to read your output. Sessions in \`needs_input\` appear on the user's homepage — archiving removes them before the user can see your work. If your work product is a message the user should read, let the session stay in \`needs_input\``;
 export function selfSessionActionSessionTool(_server, clientFactory) {
     return {
         name: 'action_session',

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

@@ -11,6 +11,13 @@ function buildToolDescription() {
     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.
 
+**IMPORTANT — Use this tool instead of workarounds.** When this tool is available, it is the correct way to schedule a delayed wake-up in an Agent Orchestrator context. Do NOT use these alternatives:
+- **Bash \`sleep\`**: Blocks the process and wastes compute resources for the entire sleep duration. The session remains "running" and cannot be reclaimed.
+- **Claude Code \`ScheduleWakeup\` tool**: Does not integrate with AO's session lifecycle — it won't transition the session to sleeping/waiting state or create an AO trigger, so AO cannot track or manage the wake-up.
+- **Claude Code \`Monitor\` tool**: Same problem — it operates outside AO's session state management.
+
+This tool creates a one-time AO wake-up trigger bound to the target session. The AO API atomically transitions the session to sleeping (waiting) state as part of creating the trigger, so AO can reclaim resources and the trigger is guaranteed to resume the correct session at the specified time.
+
 **Current server time:** ${utcNow} (UTC). Use this as your reference point when calculating wake-up times.
 
 **Timezone handling:**
@@ -21,16 +28,15 @@ function buildToolDescription() {
 - If you omit timezone, wake_at is treated as UTC.
 
 **Parameters:**
-- **session_id**: The session to wake up (must be in needs_input state)
+- **session_id**: The session to wake up. Works from either \`needs_input\` or \`running\` state — if you call this tool from within your own currently-running session, the sleep transition is recorded and takes effect after the current turn ends.
 - **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`;
+1. Creates a one-time schedule trigger bound to this session that fires at the specified time.
+2. As a side effect of creating the trigger, the AO API transitions the session to sleeping (waiting) status — immediately if currently \`needs_input\`, or after the current turn ends if currently \`running\`.
+3. At the scheduled time, the trigger resumes the session with the provided prompt.`;
 }
 export function wakeMeUpLaterTool(_server, clientFactory) {
     return {
@@ -41,7 +47,7 @@ export function wakeMeUpLaterTool(_server, clientFactory) {
             properties: {
                 session_id: {
                     oneOf: [{ type: 'string' }, { type: 'number' }],
-                    description: 'Session ID (numeric) or slug (string). Must be in needs_input state.',
+                    description: 'Session ID (numeric) or slug (string). Accepts sessions in needs_input or running state — from a running session, the sleep takes effect after the current turn ends.',
                 },
                 wake_at: {
                     type: 'string',
@@ -76,30 +82,49 @@ export function wakeMeUpLaterTool(_server, clientFactory) {
                     };
                 }
                 const session = await client.getSession(session_id);
-                if (session.status !== 'needs_input') {
+                // Reject states the Rails API can't auto-sleep from. `needs_input` →
+                // immediate sleep; `running` → deferred sleep via pending_sleep metadata;
+                // `waiting` → already dormant, trigger fires normally. Anything else
+                // (failed, archived) would silently no-op the auto-sleep and leave the
+                // caller with a trigger targeting a session that can't be woken.
+                const WAKEABLE_STATUSES = ['needs_input', 'running', 'waiting'];
+                if (!WAKEABLE_STATUSES.includes(session.status)) {
                     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.`,
+                                text: `Error: Session ${session.id} is in "${session.status}" state and cannot be scheduled for wake-up. Only sessions in ${WAKEABLE_STATUSES.join(', ')} can be woken up.`,
                             },
                         ],
                         isError: true,
                     };
                 }
-                const sleepingSession = await client.sleepSession(session_id);
+                // The Rails Trigger model requires agent_root_name, but for per-session
+                // wake-up triggers (reuse_session + last_session_id + one-time schedule)
+                // the value is never used to spawn a session — the target session is
+                // always reused. Prefer the canonical metadata value. The agent_type
+                // fallback is a best-effort for pre-migration sessions without an
+                // agent_root_key; if agent_type isn't a registered agent root, the
+                // createTrigger call will fail loudly with a 422 rather than proceed
+                // with a bad value — which is what we want.
+                const agentRootName = session.metadata?.agent_root_key || session.agent_type;
                 let trigger;
                 try {
                     trigger = await client.createTrigger({
-                        name: `Wake session #${sleepingSession.id} at ${wake_at}`,
-                        trigger_type: 'schedule',
-                        agent_root_name: session.agent_type,
+                        name: `Wake session #${session.id} at ${wake_at}`,
+                        agent_root_name: agentRootName,
                         prompt_template: prompt,
                         reuse_session: true,
-                        configuration: {
-                            scheduled_at: wake_at,
-                            timezone,
-                        },
+                        last_session_id: session.id,
+                        trigger_conditions_attributes: [
+                            {
+                                condition_type: 'schedule',
+                                configuration: {
+                                    scheduled_at: wake_at,
+                                    timezone,
+                                },
+                            },
+                        ],
                     });
                 }
                 catch (triggerError) {
@@ -107,28 +132,23 @@ export function wakeMeUpLaterTool(_server, clientFactory) {
                         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).`,
+                                text: `Error: Trigger creation failed: ${triggerError instanceof Error ? triggerError.message : 'Unknown error'}. The session is still in its original state — no changes were made.`,
                             },
                         ],
                         isError: true,
                     };
                 }
-                await client.updateSession(session_id, {
-                    custom_metadata: {
-                        ...session.custom_metadata,
-                        wake_trigger_id: trigger.id,
-                    },
-                });
                 const lines = [
-                    '## Session Scheduled for Wake-Up',
+                    '## Wake-Up Scheduled Successfully',
                     '',
-                    `- **Session ID:** ${sleepingSession.id}`,
-                    `- **Session Status:** ${sleepingSession.status}`,
+                    `- **Session ID:** ${session.id}`,
                     `- **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.',
+                    '**You must end your conversation turn now.** The session will be automatically transitioned to waiting (immediately if currently needs_input; after the current turn ends if currently running) and resumed at the scheduled time with the provided prompt.',
+                    '',
+                    '⚠️ **Warning:** If you do not end your conversation turn, the session may still be running when the scheduled wake-up fires. A wake-up cannot be delivered to a session that is not in a wakeable (sleeping/waiting) state — it will be silently dropped, and you will never receive it.',
                 ];
                 return { content: [{ type: 'text', text: lines.join('\n') }] };
             }

package/shared/types.d.ts

@@ -251,9 +251,13 @@ export interface TriggerChannelsResponse {
         num_members: number;
     }>;
 }
+export interface TriggerConditionAttributes {
+    condition_type: 'slack' | 'schedule' | 'ao_event';
+    configuration: Record<string, unknown>;
+}
 export interface CreateTriggerRequest {
     name: string;
-    trigger_type: TriggerType;
+    trigger_type?: TriggerType;
     agent_root_name: string;
     prompt_template: string;
     status?: TriggerStatus;
@@ -261,6 +265,8 @@ export interface CreateTriggerRequest {
     reuse_session?: boolean;
     mcp_servers?: string[];
     configuration?: Record<string, unknown>;
+    last_session_id?: number;
+    trigger_conditions_attributes?: TriggerConditionAttributes[];
 }
 export interface UpdateTriggerRequest {
     name?: string;