agent-orchestrator-mcp-server 0.7.3 → 0.7.6

package/package.json

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

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 does both: it properly transitions the session to sleeping (waiting) state so AO can reclaim resources, AND creates a one-time AO trigger to resume the session at the specified time.
+
 **Current server time:** ${utcNow} (UTC). Use this as your reference point when calculating wake-up times.
 
 **Timezone handling:**
@@ -120,7 +127,7 @@ export function wakeMeUpLaterTool(_server, clientFactory) {
                     },
                 });
                 const lines = [
-                    '## Session Scheduled for Wake-Up',
+                    '## Wake-Up Scheduled Successfully',
                     '',
                     `- **Session ID:** ${sleepingSession.id}`,
                     `- **Session Status:** ${sleepingSession.status}`,
@@ -128,7 +135,9 @@ export function wakeMeUpLaterTool(_server, clientFactory) {
                     `- **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 is sleeping and will be automatically 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') }] };
             }