agent-orchestrator-mcp-server 0.8.2 → 0.8.5

package/package.json

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

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

@@ -32,14 +32,14 @@ export declare function mapAgentRoot(raw: RawAgentRoot): AgentRootInfo;
 export interface IAgentOrchestratorClient {
     listSessions(options?: {
         status?: SessionStatus;
-        agent_type?: string;
+        agent_runtime?: string;
         show_archived?: boolean;
         page?: number;
         per_page?: number;
     }): Promise<SessionsResponse>;
     searchSessions(query: string, options?: {
         status?: SessionStatus;
-        agent_type?: string;
+        agent_runtime?: string;
         show_archived?: boolean;
         page?: number;
         per_page?: number;
@@ -159,14 +159,14 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     private requestText;
     listSessions(options?: {
         status?: SessionStatus;
-        agent_type?: string;
+        agent_runtime?: string;
         show_archived?: boolean;
         page?: number;
         per_page?: number;
     }): Promise<SessionsResponse>;
     searchSessions(query: string, options?: {
         status?: SessionStatus;
-        agent_type?: string;
+        agent_runtime?: string;
         show_archived?: boolean;
         page?: number;
         per_page?: number;

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

@@ -14,7 +14,7 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 slug: 'test-session-1',
                 title: 'Test Session 1',
                 status: 'running',
-                agent_type: 'claude_code',
+                agent_runtime: 'claude_code',
                 prompt: 'Test prompt',
                 git_root: 'https://github.com/example/repo.git',
                 branch: 'main',
@@ -75,8 +75,8 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             if (options?.status) {
                 sessions = sessions.filter((s) => s.status === options.status);
             }
-            if (options?.agent_type) {
-                sessions = sessions.filter((s) => s.agent_type === options.agent_type);
+            if (options?.agent_runtime) {
+                sessions = sessions.filter((s) => s.agent_runtime === options.agent_runtime);
             }
             if (!options?.show_archived) {
                 sessions = sessions.filter((s) => s.status !== 'archived');
@@ -138,7 +138,7 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 slug: data.slug || null,
                 title: data.title || 'New Session',
                 status: 'waiting',
-                agent_type: data.agent_type || 'claude_code',
+                agent_runtime: data.agent_runtime || 'claude_code',
                 prompt: data.prompt || null,
                 git_root: data.git_root || null,
                 branch: data.branch || 'main',

package/shared/tools/get-session.js

@@ -54,7 +54,7 @@ function formatSessionDetails(session, includeTranscript) {
         '### Basic Information',
         `- **ID:** ${session.id}`,
         `- **Status:** ${session.status}`,
-        `- **Agent Type:** ${session.agent_type}`,
+        `- **Agent Runtime:** ${session.agent_runtime}`,
     ];
     if (session.slug)
         lines.push(`- **Slug:** ${session.slug}`);

package/shared/tools/search-sessions.d.ts

@@ -5,14 +5,14 @@ export declare const QuickSearchSessionsSchema: z.ZodObject<{
     id: z.ZodOptional<z.ZodNumber>;
     query: z.ZodOptional<z.ZodString>;
     status: z.ZodOptional<z.ZodEnum<["waiting", "running", "needs_input", "failed", "archived"]>>;
-    agent_type: z.ZodOptional<z.ZodString>;
+    agent_runtime: z.ZodOptional<z.ZodString>;
     show_archived: z.ZodOptional<z.ZodBoolean>;
     page: z.ZodOptional<z.ZodNumber>;
     per_page: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     per_page?: number | undefined;
     status?: "waiting" | "running" | "needs_input" | "failed" | "archived" | undefined;
-    agent_type?: string | undefined;
+    agent_runtime?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
     id?: number | undefined;
@@ -20,7 +20,7 @@ export declare const QuickSearchSessionsSchema: z.ZodObject<{
 }, {
     per_page?: number | undefined;
     status?: "waiting" | "running" | "needs_input" | "failed" | "archived" | undefined;
-    agent_type?: string | undefined;
+    agent_runtime?: string | undefined;
     show_archived?: boolean | undefined;
     page?: number | undefined;
     id?: number | undefined;
@@ -46,9 +46,9 @@ export declare function quickSearchSessionsTool(_server: Server, clientFactory:
                 enum: string[];
                 description: "Filter results by status. Options: \"waiting\", \"running\", \"needs_input\", \"failed\", \"archived\"";
             };
-            agent_type: {
+            agent_runtime: {
                 type: string;
-                description: "Filter results by agent type.";
+                description: "Filter results by agent runtime.";
             };
             show_archived: {
                 type: string;

package/shared/tools/search-sessions.js

@@ -3,7 +3,7 @@ const PARAM_DESCRIPTIONS = {
     id: 'Get a specific session by ID. When provided, other filters are ignored.',
     query: 'Search query to find sessions. Matches against session title only — this is a simple title search, not a full-text or semantic search. Leave empty to list all sessions.',
     status: 'Filter results by status. Options: "waiting", "running", "needs_input", "failed", "archived"',
-    agent_type: 'Filter results by agent type.',
+    agent_runtime: 'Filter results by agent runtime.',
     show_archived: 'Include archived sessions in results. Default: false',
     page: 'Page number for pagination. Default: 1',
     per_page: 'Number of results per page (1-100). Default: 25',
@@ -15,7 +15,7 @@ export const QuickSearchSessionsSchema = z.object({
         .enum(['waiting', 'running', 'needs_input', 'failed', 'archived'])
         .optional()
         .describe(PARAM_DESCRIPTIONS.status),
-    agent_type: z.string().optional().describe(PARAM_DESCRIPTIONS.agent_type),
+    agent_runtime: z.string().optional().describe(PARAM_DESCRIPTIONS.agent_runtime),
     show_archived: z.boolean().optional().describe(PARAM_DESCRIPTIONS.show_archived),
     page: z.number().min(1).optional().describe(PARAM_DESCRIPTIONS.page),
     per_page: z.number().min(1).max(100).optional().describe(PARAM_DESCRIPTIONS.per_page),
@@ -45,7 +45,7 @@ function formatSession(session) {
         `### ${session.title} (ID: ${session.id})`,
         '',
         `- **Status:** ${session.status}`,
-        `- **Agent Type:** ${session.agent_type}`,
+        `- **Agent Runtime:** ${session.agent_runtime}`,
     ];
     if (session.slug)
         lines.push(`- **Slug:** ${session.slug}`);
@@ -87,9 +87,9 @@ export function quickSearchSessionsTool(_server, clientFactory) {
                     enum: ['waiting', 'running', 'needs_input', 'failed', 'archived'],
                     description: PARAM_DESCRIPTIONS.status,
                 },
-                agent_type: {
+                agent_runtime: {
                     type: 'string',
-                    description: PARAM_DESCRIPTIONS.agent_type,
+                    description: PARAM_DESCRIPTIONS.agent_runtime,
                 },
                 show_archived: {
                     type: 'boolean',
@@ -132,7 +132,7 @@ export function quickSearchSessionsTool(_server, clientFactory) {
                     // Use search endpoint (title-only search, no content search)
                     const response = await client.searchSessions(validatedArgs.query, {
                         status: validatedArgs.status,
-                        agent_type: validatedArgs.agent_type,
+                        agent_runtime: validatedArgs.agent_runtime,
                         show_archived: validatedArgs.show_archived,
                         page: validatedArgs.page,
                         per_page: validatedArgs.per_page,
@@ -144,7 +144,7 @@ export function quickSearchSessionsTool(_server, clientFactory) {
                     // Use list endpoint
                     const response = await client.listSessions({
                         status: validatedArgs.status,
-                        agent_type: validatedArgs.agent_type,
+                        agent_runtime: validatedArgs.agent_runtime,
                         show_archived: validatedArgs.show_archived,
                         page: validatedArgs.page,
                         per_page: validatedArgs.per_page,

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

@@ -2,7 +2,7 @@ import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { z } from 'zod';
 import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
 export declare const StartSessionSchema: z.ZodObject<{
-    agent_type: z.ZodOptional<z.ZodString>;
+    agent_runtime: z.ZodOptional<z.ZodString>;
     prompt: z.ZodOptional<z.ZodString>;
     agent_root: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
@@ -16,7 +16,7 @@ export declare const StartSessionSchema: z.ZodObject<{
     custom_metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     auto_compact_window: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    agent_type?: string | undefined;
+    agent_runtime?: string | undefined;
     skills?: string[] | undefined;
     plugins?: string[] | undefined;
     prompt?: string | undefined;
@@ -30,7 +30,7 @@ export declare const StartSessionSchema: z.ZodObject<{
     custom_metadata?: Record<string, unknown> | undefined;
     auto_compact_window?: number | undefined;
 }, {
-    agent_type?: string | undefined;
+    agent_runtime?: string | undefined;
     skills?: string[] | undefined;
     plugins?: string[] | undefined;
     prompt?: string | undefined;
@@ -50,9 +50,9 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
     inputSchema: {
         type: "object";
         properties: {
-            agent_type: {
+            agent_runtime: {
                 type: string;
-                description: "Agent type for the session. Currently only \"claude_code\" is supported. Default: \"claude_code\"";
+                description: "Per-spawn agent runtime override. When omitted, the session adopts the agent_root's default_runtime, falling back to \"claude_code\". Currently only \"claude_code\" is registered.";
             };
             prompt: {
                 type: string;

package/shared/tools/start-session.js

@@ -2,7 +2,7 @@ import { z } from 'zod';
 import { parseAllowedAgentRoots, validateAgentRootConstraints } from '../allowed-agent-roots.js';
 import { getConfigsCache, setConfigsCache } from '../cache/configs-cache.js';
 const PARAM_DESCRIPTIONS = {
-    agent_type: 'Agent type for the session. Currently only "claude_code" is supported. Default: "claude_code"',
+    agent_runtime: 'Per-spawn agent runtime override. When omitted, the session adopts the agent_root\'s default_runtime, falling back to "claude_code". Currently only "claude_code" is registered.',
     prompt: 'Initial prompt for the agent. If provided, the agent job is automatically queued. Omit for a clone-only session.',
     agent_root: 'Agent root name from get_configs. The API resolves git_root, branch, subdirectory, default_model, and other defaults from the agent root configuration. Always pass this so the session inherits the correct repository, model, and settings.',
     title: 'STRONGLY RECOMMENDED: Always set a title — treat it as effectively required. ' +
@@ -25,7 +25,7 @@ const PARAM_DESCRIPTIONS = {
         'Compaction thrashing is currently the only known reason to set this preemptively.',
 };
 export const StartSessionSchema = z.object({
-    agent_type: z.string().optional().describe(PARAM_DESCRIPTIONS.agent_type),
+    agent_runtime: z.string().optional().describe(PARAM_DESCRIPTIONS.agent_runtime),
     prompt: z.string().optional().describe(PARAM_DESCRIPTIONS.prompt),
     agent_root: z.string().optional().describe(PARAM_DESCRIPTIONS.agent_root),
     title: z.string().optional().describe(PARAM_DESCRIPTIONS.title),
@@ -71,9 +71,9 @@ export function startSessionTool(_server, clientFactory) {
         inputSchema: {
             type: 'object',
             properties: {
-                agent_type: {
+                agent_runtime: {
                     type: 'string',
-                    description: PARAM_DESCRIPTIONS.agent_type,
+                    description: PARAM_DESCRIPTIONS.agent_runtime,
                 },
                 prompt: {
                     type: 'string',

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

@@ -114,6 +114,14 @@ This guidance does NOT apply when waking at a known wall-clock time (e.g., "9am
 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.
 
+**End your conversation turn after scheduling.** Two mechanisms together make wake delivery durable:
+1. **Auto-sleep** — ending your turn transitions the requester from \`running\` to \`waiting\`, where the trigger resumes it directly at the scheduled time.
+2. **Cross-turn queuing** — if the scheduled time arrives while the requester is still in \`running\` (the turn hadn't ended yet), the wake-up prompt is durably queued onto the requester via \`enqueued_messages\` and picked up at the next turn boundary by AO's pre-pause handoff. It is NOT silently dropped.
+
+You should still end your turn promptly — queuing is the safety net, not a substitute for ending the turn.
+
+**Wake-ups override \`enqueue_messages: false\`.** For ordinary triggers (Slack, recurring schedules), \`enqueue_messages: false\` means "don't barge a busy session." Wake-ups are one-shot signals, not recurring drumbeats, so they queue onto a running requester regardless of that flag.
+
 **⚠️ Sibling-destroy semantics when paired with state-change wakes.** If this \`wake_me_up_later\` trigger is acting as a deadline backstop alongside \`wake_me_up_when_session_changes_state\` triggers (the recommended triple-wake + deadline pattern), the AO firing path destroys ALL of the requester's other one-time wakes whenever any one of them fires — and that cuts both ways:
 - If a state-change trigger fires first, this deadline backstop is destroyed (not pending in the background).
 - If THIS deadline fires first (e.g., a hung watched session never transitioned), all the companion state-change watchers are destroyed.
@@ -206,12 +214,12 @@ export function wakeMeUpLaterTool(_server, clientFactory) {
                 // 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
+                // always reused. Prefer the canonical metadata value. The agent_runtime
                 // fallback is a best-effort for pre-migration sessions without an
-                // agent_root_key; if agent_type isn't a registered agent root, the
+                // agent_root_key; if agent_runtime 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;
+                const agentRootName = session.metadata?.agent_root_key || session.agent_runtime;
                 let trigger;
                 try {
                     trigger = await client.createTrigger({
@@ -252,7 +260,7 @@ export function wakeMeUpLaterTool(_server, clientFactory) {
                     '',
                     '**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.',
+                    "ℹ️ **Cross-turn safety net:** If the scheduled wake-up fires before you end this turn, the wake-up prompt is durably queued onto the session via `enqueued_messages` and processed at the next turn boundary by AO's pre-pause handoff — it is NOT silently dropped. Still end your turn promptly; queuing is the safety net, not a substitute for ending the turn.",
                     '',
                     '**Sibling-destroy reminder:** if this trigger is paired with `wake_me_up_when_session_changes_state` triggers (the triple-wake + deadline pattern), whichever wake fires first destroys ALL the others belonging to this requester. If this deadline fires while the watched session is still progressing, the woken-up turn must re-register the state-change watchers AND a new deadline before going back to sleep — the originals are gone.',
                 ];

package/shared/tools/wake-me-up-when-session-changes-state.js

@@ -56,7 +56,13 @@ Concretely, in a woken-up turn that determines the watched session has not actua
 3. When the watched session transitions to the matching state, the trigger fires and resumes the requester with the provided prompt. The trigger then auto-deletes (one-shot).
 4. If the requester is manually resumed first, the pending trigger is consumed (won't fire). If the watched session is archived without ever transitioning to the matching state (e.g., you only scheduled \`session_needs_input\` and it went straight to \`archived\`), the trigger is cleaned up — and you'll only wake when your deadline backstop fires.
 
-**You must end your conversation turn after calling this tool** so the auto-sleep can take effect. If your turn keeps running, the requester will not be in a wakeable state when the watched session transitions, and the wake-up will be silently dropped. When scheduling multiple triggers (the typical triple-wake + deadline pattern), call this tool repeatedly within the same turn — the auto-sleep is idempotent and only takes effect once the turn ends.`;
+**End your conversation turn after scheduling.** Two mechanisms together make wake delivery durable:
+1. **Auto-sleep** — ending your turn transitions the requester from \`running\` to \`waiting\`, where the trigger resumes it directly when the watched event fires.
+2. **Cross-turn queuing** — if the watched event fires while the requester is still in \`running\` (the turn hadn't ended yet when the watched event happened), the wake-up prompt is durably queued onto the requester via \`enqueued_messages\` and picked up at the next turn boundary by AO's pre-pause handoff. It is NOT silently dropped.
+
+You should still end your turn promptly — queuing is the safety net, not a substitute for ending the turn. When scheduling multiple triggers (the typical triple-wake + deadline pattern), call this tool repeatedly within the same turn before ending it.
+
+**Wake-ups override \`enqueue_messages: false\`.** For ordinary triggers (Slack, recurring schedules), \`enqueue_messages: false\` means "don't barge a busy session." Wake-ups are one-shot signals, not recurring drumbeats, so they queue onto a running requester regardless of that flag.`;
 export function wakeMeUpWhenSessionChangesStateTool(_server, clientFactory) {
     return {
         name: 'wake_me_up_when_session_changes_state',
@@ -223,9 +229,9 @@ export function wakeMeUpWhenSessionChangesStateTool(_server, clientFactory) {
                 // The Rails Trigger model requires agent_root_name, but for per-session
                 // wake-up triggers (reuse_session + last_session_id + one-time event)
                 // the value is never used to spawn a session — the target session is
-                // always reused. Prefer the canonical metadata value with agent_type as
+                // always reused. Prefer the canonical metadata value with agent_runtime as
                 // a legacy fallback (matches wake_me_up_later behavior).
-                const agentRootName = session.metadata?.agent_root_key || session.agent_type;
+                const agentRootName = session.metadata?.agent_root_key || session.agent_runtime;
                 let trigger;
                 try {
                     trigger = await client.createTrigger({
@@ -267,7 +273,7 @@ export function wakeMeUpWhenSessionChangesStateTool(_server, clientFactory) {
                     '',
                     '**You must end your conversation turn now.** The requester session will be automatically transitioned to waiting (immediately if currently needs_input; after the current turn ends if currently running) and resumed when the watched session transitions to the matching state.',
                     '',
-                    '⚠️ **Warning:** If you do not end your conversation turn, the requester may still be running when the watched session transitions. 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.',
+                    "ℹ️ **Cross-turn safety net:** If the watched session transitions before you end this turn, the wake-up prompt is durably queued onto the requester via `enqueued_messages` and processed at the next turn boundary by AO's pre-pause handoff — it is NOT silently dropped. Still end your turn promptly; queuing is the safety net, not a substitute for ending the turn.",
                     '',
                     '**One-shot:** the trigger auto-deletes after firing. If you want to wake on the next transition too, schedule another trigger from the woken-up turn.',
                     '',

package/shared/types.d.ts

@@ -15,7 +15,7 @@ export interface Session {
     slug: string | null;
     title: string;
     status: SessionStatus;
-    agent_type: string;
+    agent_runtime: string;
     prompt: string | null;
     git_root: string | null;
     branch: string | null;
@@ -135,7 +135,7 @@ export interface SendPushNotificationResponse {
     session_id: number;
 }
 export interface CreateSessionRequest {
-    agent_type?: string;
+    agent_runtime?: string;
     prompt?: string;
     git_root?: string;
     branch?: string;