agent-orchestrator-mcp-server 0.4.7 → 0.6.0

package/README.md

@@ -21,22 +21,22 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 
 ### Tools
 
-| Tool                       | Tool Group    | Read/Write | Description                                                                                                                                                 |
-| -------------------------- | ------------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `quick_search_sessions`    | sessions      | read       | Quick title-based search/list sessions with optional ID lookup, title query, and status filter                                                              |
-| `get_session`              | sessions      | read       | Get detailed session info with optional logs, transcripts, and transcript format (text/json)                                                                |
-| `get_configs`              | sessions      | read       | Fetch all static configuration (MCP servers, agent roots, stop conditions)                                                                                  |
-| `get_transcript_archive`   | sessions      | read       | Get download URL and metadata for the transcript archive zip file                                                                                           |
-| `start_session`            | sessions      | write      | Create and start a new agent session                                                                                                                        |
-| `action_session`           | sessions      | write      | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers, fork, refresh, refresh_all, update_notes, toggle_favorite, bulk_archive |
-| `manage_enqueued_messages` | sessions      | write      | Manage session message queue: list, get, create, update, delete, reorder, interrupt                                                                         |
-| `get_notifications`        | notifications | read       | Get/list notifications and badge count                                                                                                                      |
-| `send_push_notification`   | notifications | write      | Send a push notification about a session needing human attention                                                                                            |
-| `action_notification`      | notifications | write      | Mark read, mark all read, dismiss, dismiss all read notifications                                                                                           |
-| `search_triggers`          | triggers      | read       | Search/list automation triggers with optional channel info                                                                                                  |
-| `action_trigger`           | triggers      | write      | Create, update, delete, toggle automation triggers                                                                                                          |
-| `get_system_health`        | health        | read       | Get system health report and optional CLI status                                                                                                            |
-| `action_health`            | health        | write      | System maintenance: cleanup_processes, retry_sessions, archive_old, cli_refresh, cli_clear_cache                                                            |
+| Tool                       | Tool Group    | Read/Write | Description                                                                                                                                                                             |
+| -------------------------- | ------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `quick_search_sessions`    | sessions      | read       | Quick title-based search/list sessions with optional ID lookup, title query, and status filter                                                                                          |
+| `get_session`              | sessions      | read       | Get detailed session info with optional logs, transcripts, and transcript format (text/json)                                                                                            |
+| `get_configs`              | sessions      | read       | Fetch all static configuration (MCP servers, agent roots, stop conditions)                                                                                                              |
+| `get_transcript_archive`   | sessions      | read       | Get download URL and metadata for the transcript archive zip file                                                                                                                       |
+| `start_session`            | sessions      | write      | Create and start a new agent session                                                                                                                                                    |
+| `action_session`           | sessions      | write      | Perform actions: follow_up, pause, restart, archive, unarchive, change_mcp_servers, change_model, fork, refresh, refresh_all, update_notes, update_title, toggle_favorite, bulk_archive |
+| `manage_enqueued_messages` | sessions      | write      | Manage session message queue: list, get, create, update, delete, reorder, interrupt                                                                                                     |
+| `get_notifications`        | notifications | read       | Get/list notifications and badge count                                                                                                                                                  |
+| `send_push_notification`   | notifications | write      | Send a push notification about a session needing human attention                                                                                                                        |
+| `action_notification`      | notifications | write      | Mark read, mark all read, dismiss, dismiss all read notifications                                                                                                                       |
+| `search_triggers`          | triggers      | read       | Search/list automation triggers with optional channel info                                                                                                                              |
+| `action_trigger`           | triggers      | write      | Create, update, delete, toggle automation triggers                                                                                                                                      |
+| `get_system_health`        | health        | read       | Get system health report and optional CLI status                                                                                                                                        |
+| `action_health`            | health        | write      | System maintenance: cleanup_processes, retry_sessions, archive_old, cli_refresh, cli_clear_cache                                                                                        |
 
 ### Resources
 

package/package.json

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

package/shared/allowed-agent-roots.d.ts

@@ -26,15 +26,11 @@ export interface AgentRootValidationResult {
  * Validate a start_session request against the allowed agent roots constraints.
  *
  * When ALLOWED_AGENT_ROOTS is set:
- * - git_root (and optionally branch/subdirectory) must match one of the allowed agent roots
+ * - agent_root must be provided and must be one of the allowed agent root names
  * - mcp_servers must exactly match the default_mcp_servers of that agent root
  *   (no more, no less — any deviation is rejected)
  *
- * When multiple allowed agent roots share the same git_root, branch and subdirectory
- * are used to disambiguate. This is critical for monorepo setups where multiple agent
- * roots point to the same repository but different subdirectories.
- *
  * Returns { valid: true } if the request is allowed, or { valid: false, error: string } if not.
  */
-export declare function validateAgentRootConstraints(allowedRoots: string[] | null, agentRoots: AgentRootInfo[], gitRoot?: string, mcpServers?: string[], branch?: string, subdirectory?: string): AgentRootValidationResult;
+export declare function validateAgentRootConstraints(allowedRoots: string[] | null, agentRoots: AgentRootInfo[], agentRootName?: string, mcpServers?: string[]): AgentRootValidationResult;
 //# sourceMappingURL=allowed-agent-roots.d.ts.map

package/shared/allowed-agent-roots.js

@@ -39,46 +39,37 @@ export function filterAgentRoots(agentRoots, allowedRoots) {
  * Validate a start_session request against the allowed agent roots constraints.
  *
  * When ALLOWED_AGENT_ROOTS is set:
- * - git_root (and optionally branch/subdirectory) must match one of the allowed agent roots
+ * - agent_root must be provided and must be one of the allowed agent root names
  * - mcp_servers must exactly match the default_mcp_servers of that agent root
  *   (no more, no less — any deviation is rejected)
  *
- * When multiple allowed agent roots share the same git_root, branch and subdirectory
- * are used to disambiguate. This is critical for monorepo setups where multiple agent
- * roots point to the same repository but different subdirectories.
- *
  * Returns { valid: true } if the request is allowed, or { valid: false, error: string } if not.
  */
-export function validateAgentRootConstraints(allowedRoots, agentRoots, gitRoot, mcpServers, branch, subdirectory) {
+export function validateAgentRootConstraints(allowedRoots, agentRoots, agentRootName, mcpServers) {
     if (allowedRoots === null) {
         return { valid: true };
     }
-    // Find all allowed agent roots that match by git_root
-    const candidates = agentRoots.filter((root) => allowedRoots.includes(root.name) && root.git_root === gitRoot);
-    // When multiple candidates share the same git_root, disambiguate using branch and subdirectory
-    let matchingRoot;
-    if (candidates.length > 1) {
-        matchingRoot = candidates.find((root) => {
-            const branchMatch = !branch || (root.default_branch ?? 'main') === branch;
-            const subdirMatch = !subdirectory || root.default_subdirectory === subdirectory;
-            return branchMatch && subdirMatch;
-        });
+    if (!agentRootName) {
+        return {
+            valid: false,
+            error: `ALLOWED_AGENT_ROOTS is set — agent_root is required. ` +
+                `Allowed agent roots: ${allowedRoots.join(', ')}`,
+        };
     }
-    else {
-        matchingRoot = candidates[0];
+    if (!allowedRoots.includes(agentRootName)) {
+        return {
+            valid: false,
+            error: `ALLOWED_AGENT_ROOTS is set — agent_root "${agentRootName}" is not permitted. ` +
+                `Allowed agent roots: ${allowedRoots.join(', ')}`,
+        };
     }
+    // Find the matching agent root config to validate mcp_servers
+    const matchingRoot = agentRoots.find((root) => root.name === agentRootName);
     if (!matchingRoot) {
-        const allowedNames = allowedRoots.join(', ');
-        const allowedGitRoots = agentRoots
-            .filter((root) => allowedRoots.includes(root.name))
-            .map((root) => root.git_root);
         return {
             valid: false,
-            error: `ALLOWED_AGENT_ROOTS is set — only the following agent roots are permitted: ${allowedNames}. ` +
-                `The provided git_root "${gitRoot || '(not provided)'}" does not match any allowed agent root. ` +
-                (allowedGitRoots.length > 0
-                    ? `Allowed git_root values: ${allowedGitRoots.join(', ')}`
-                    : 'No matching agent roots found in configuration.'),
+            error: `Agent root "${agentRootName}" is in the allowed list but was not found in the configuration. ` +
+                `Available agent roots: ${agentRoots.map((r) => r.name).join(', ')}`,
         };
     }
     // Validate mcp_servers matches the default_mcp_servers exactly

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

@@ -17,6 +17,7 @@ export interface RawAgentRoot {
     default?: boolean;
     default_mcp_servers?: string[];
     default_skills?: string[];
+    default_model?: string;
 }
 /**
  * Maps a raw API agent root to the normalized AgentRootInfo interface.
@@ -53,6 +54,7 @@ export interface IAgentOrchestratorClient {
     pauseSession(id: string | number): Promise<SessionActionResponse>;
     restartSession(id: string | number): Promise<SessionActionResponse>;
     changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
+    changeModel(id: string | number, model: string): Promise<Session>;
     listLogs(sessionId: string | number, options?: {
         level?: LogLevel;
         page?: number;
@@ -175,6 +177,7 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     pauseSession(id: string | number): Promise<SessionActionResponse>;
     restartSession(id: string | number): Promise<SessionActionResponse>;
     changeMcpServers(id: string | number, mcp_servers: string[]): Promise<Session>;
+    changeModel(id: string | number, model: string): Promise<Session>;
     listLogs(sessionId: string | number, options?: {
         level?: LogLevel;
         page?: number;

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

@@ -247,6 +247,15 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
             session.updated_at = new Date().toISOString();
             return session;
         },
+        async changeModel(id, model) {
+            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`);
+            }
+            session.config = { ...session.config, model };
+            session.updated_at = new Date().toISOString();
+            return session;
+        },
         async listLogs(sessionId, options) {
             let logs = (mockData.logs || []).filter((l) => l.session_id === Number(sessionId));
             if (options?.level) {

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

@@ -19,6 +19,7 @@ export function mapAgentRoot(raw) {
         default_stop_condition: raw.default_stop_condition,
         default_mcp_servers: raw.default_mcp_servers,
         default_skills: raw.default_skills,
+        default_model: raw.default_model,
     };
 }
 /** Default timeout for API requests in milliseconds */
@@ -177,7 +178,15 @@ export class AgentOrchestratorClient {
         return response.session;
     }
     async createSession(data) {
-        const response = await this.request('POST', '/sessions', data);
+        // Remap `skills` to `catalog_skills` and `plugins` to `catalog_plugins`
+        // for the API (Rails strong params expects `catalog_skills`/`catalog_plugins`)
+        const { skills, plugins, ...rest } = data;
+        const body = {
+            ...rest,
+            ...(skills !== undefined && { catalog_skills: skills }),
+            ...(plugins !== undefined && { catalog_plugins: plugins }),
+        };
+        const response = await this.request('POST', '/sessions', body);
         return response.session;
     }
     async updateSession(id, data) {
@@ -210,6 +219,12 @@ export class AgentOrchestratorClient {
         });
         return response.session;
     }
+    async changeModel(id, model) {
+        const response = await this.request('PATCH', `/sessions/${id}/model`, {
+            model,
+        });
+        return response.session;
+    }
     // Logs
     async listLogs(sessionId, options) {
         return this.request('GET', `/sessions/${sessionId}/logs`, undefined, options);

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

@@ -3,25 +3,31 @@ import { z } from 'zod';
 import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
 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", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "bulk_archive"]>;
+    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>;
     mcp_servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    model: z.ZodOptional<z.ZodString>;
     message_index: z.ZodOptional<z.ZodNumber>;
     session_notes: z.ZodOptional<z.ZodString>;
     session_ids: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+    title: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "fork" | "refresh" | "refresh_all" | "update_notes" | "toggle_favorite" | "bulk_archive";
-    mcp_servers?: string[] | undefined;
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "change_model" | "fork" | "refresh" | "refresh_all" | "update_notes" | "update_title" | "toggle_favorite" | "bulk_archive";
     prompt?: string | undefined;
+    title?: string | undefined;
+    mcp_servers?: string[] | undefined;
     session_id?: string | number | undefined;
+    model?: string | undefined;
     message_index?: number | undefined;
     session_notes?: string | undefined;
     session_ids?: number[] | undefined;
 }, {
-    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "fork" | "refresh" | "refresh_all" | "update_notes" | "toggle_favorite" | "bulk_archive";
-    mcp_servers?: string[] | undefined;
+    action: "follow_up" | "pause" | "restart" | "archive" | "unarchive" | "change_mcp_servers" | "change_model" | "fork" | "refresh" | "refresh_all" | "update_notes" | "update_title" | "toggle_favorite" | "bulk_archive";
     prompt?: string | undefined;
+    title?: string | undefined;
+    mcp_servers?: string[] | undefined;
     session_id?: string | number | undefined;
+    model?: string | undefined;
     message_index?: number | undefined;
     session_notes?: string | undefined;
     session_ids?: number[] | undefined;
@@ -40,8 +46,8 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
             };
             action: {
                 type: string;
-                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "bulk_archive"];
-                description: "Action to perform: \"follow_up\", \"pause\", \"restart\", \"archive\", \"unarchive\", \"change_mcp_servers\", \"fork\", \"refresh\", \"refresh_all\", \"update_notes\", \"toggle_favorite\", \"bulk_archive\"";
+                enum: readonly ["follow_up", "pause", "restart", "archive", "unarchive", "change_mcp_servers", "change_model", "fork", "refresh", "refresh_all", "update_notes", "update_title", "toggle_favorite", "bulk_archive"];
+                description: "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: {
                 type: string;
@@ -54,6 +60,10 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
                 };
                 description: "Required for \"change_mcp_servers\" action. Array of MCP server names to set for the session.";
             };
+            model: {
+                type: string;
+                description: "Required for \"change_model\" action. The model identifier to use (e.g., \"opus\", \"sonnet\").";
+            };
             message_index: {
                 type: string;
                 description: "Required for \"fork\" action. The transcript message index to fork from.";
@@ -69,6 +79,10 @@ export declare function actionSessionTool(_server: Server, clientFactory: () =>
                 };
                 description: "Required for \"bulk_archive\" action. Array of session IDs to archive.";
             };
+            title: {
+                type: string;
+                description: "Required for \"update_title\" action. The new title for the session.";
+            };
         };
         required: string[];
     };

package/shared/tools/action-session.js

@@ -2,12 +2,14 @@ import { z } from 'zod';
 import { parseAllowedAgentRoots } from '../allowed-agent-roots.js';
 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", "fork", "refresh", "refresh_all", "update_notes", "toggle_favorite", "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.',
     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.',
     session_notes: 'Required for "update_notes" action. The notes text to set on the session.',
     session_ids: 'Required for "bulk_archive" action. Array of session IDs to archive.',
+    title: 'Required for "update_title" action. The new title for the session.',
 };
 const ACTION_ENUM = [
     'follow_up',
@@ -16,10 +18,12 @@ const ACTION_ENUM = [
     'archive',
     'unarchive',
     'change_mcp_servers',
+    'change_model',
     'fork',
     'refresh',
     'refresh_all',
     'update_notes',
+    'update_title',
     'toggle_favorite',
     'bulk_archive',
 ];
@@ -28,9 +32,11 @@ export const ActionSessionSchema = z.object({
     action: z.enum(ACTION_ENUM).describe(PARAM_DESCRIPTIONS.action),
     prompt: z.string().optional().describe(PARAM_DESCRIPTIONS.prompt),
     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),
     session_notes: z.string().optional().describe(PARAM_DESCRIPTIONS.session_notes),
     session_ids: z.array(z.number()).optional().describe(PARAM_DESCRIPTIONS.session_ids),
+    title: z.string().optional().describe(PARAM_DESCRIPTIONS.title),
 });
 const TOOL_DESCRIPTION = `Perform an action on an agent session.
 
@@ -41,18 +47,21 @@ const TOOL_DESCRIPTION = `Perform an action on an agent session.
 - **archive**: Archive a session (marks as completed)
 - **unarchive**: Restore an archived session to idle "needs_input" status
 - **change_mcp_servers**: Update the MCP servers for a session (requires "mcp_servers" parameter)
+- **change_model**: Update the model for a session (requires "model" parameter, e.g., "opus", "sonnet")
 - **fork**: Fork a session from a specific transcript message (requires "message_index")
 - **refresh**: Refresh a single session's status from the execution provider
 - **refresh_all**: Refresh all active sessions (no session_id needed)
 - **update_notes**: Update the notes on a session (requires "session_notes")
+- **update_title**: Update the title of a session (requires "title")
 - **toggle_favorite**: Toggle favorite status on a session
 - **bulk_archive**: Archive multiple sessions at once (requires "session_ids", no session_id needed)
 
 **Use cases:**
 - Provide additional instructions to an agent
 - Control session lifecycle (pause, restart, fork, refresh)
-- Organize sessions (archive, unarchive, bulk_archive, toggle_favorite, update_notes)
-- Reconfigure session MCP server access`;
+- Organize sessions (archive, unarchive, bulk_archive, toggle_favorite, update_notes, update_title)
+- Reconfigure session MCP server access
+- Change the model used by a session`;
 export function actionSessionTool(_server, clientFactory) {
     return {
         name: 'action_session',
@@ -78,6 +87,10 @@ export function actionSessionTool(_server, clientFactory) {
                     items: { type: 'string' },
                     description: PARAM_DESCRIPTIONS.mcp_servers,
                 },
+                model: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.model,
+                },
                 message_index: {
                     type: 'number',
                     description: PARAM_DESCRIPTIONS.message_index,
@@ -91,6 +104,10 @@ export function actionSessionTool(_server, clientFactory) {
                     items: { type: 'number' },
                     description: PARAM_DESCRIPTIONS.session_ids,
                 },
+                title: {
+                    type: 'string',
+                    description: PARAM_DESCRIPTIONS.title,
+                },
             },
             required: ['action'],
         },
@@ -98,7 +115,7 @@ export function actionSessionTool(_server, clientFactory) {
             try {
                 const validatedArgs = ActionSessionSchema.parse(args);
                 const client = clientFactory();
-                const { session_id, action, prompt, mcp_servers, message_index, session_notes, session_ids, } = validatedArgs;
+                const { session_id, action, prompt, mcp_servers, model, message_index, session_notes, session_ids, title, } = validatedArgs;
                 // Actions that require session_id
                 const requiresSessionId = [
                     'follow_up',
@@ -107,9 +124,11 @@ export function actionSessionTool(_server, clientFactory) {
                     'archive',
                     'unarchive',
                     'change_mcp_servers',
+                    'change_model',
                     'fork',
                     'refresh',
                     'update_notes',
+                    'update_title',
                     'toggle_favorite',
                 ];
                 if (requiresSessionId.includes(action) && !session_id) {
@@ -147,6 +166,18 @@ export function actionSessionTool(_server, clientFactory) {
                         isError: true,
                     };
                 }
+                // Validate that model is provided for change_model action
+                if (action === 'change_model' && !model) {
+                    return {
+                        content: [
+                            {
+                                type: 'text',
+                                text: 'Error: The "model" parameter is required for the "change_model" action.',
+                            },
+                        ],
+                        isError: true,
+                    };
+                }
                 // Block change_mcp_servers when ALLOWED_AGENT_ROOTS is active
                 if (action === 'change_mcp_servers' && parseAllowedAgentRoots() !== null) {
                     return {
@@ -183,6 +214,18 @@ export function actionSessionTool(_server, clientFactory) {
                         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,
+                    };
+                }
                 // Validate bulk_archive requires session_ids
                 if (action === 'bulk_archive' && (!session_ids || session_ids.length === 0)) {
                     return {
@@ -285,6 +328,19 @@ export function actionSessionTool(_server, clientFactory) {
                         result = lines.join('\n');
                         break;
                     }
+                    case 'change_model': {
+                        const session = await client.changeModel(session_id, model);
+                        const sessionModel = session.config?.model;
+                        const lines = [
+                            `## Model Updated`,
+                            '',
+                            `- **Session ID:** ${session.id}`,
+                            `- **Title:** ${session.title}`,
+                            `- **Model:** ${sessionModel || '(default)'}`,
+                        ];
+                        result = lines.join('\n');
+                        break;
+                    }
                     case 'fork': {
                         const response = await client.forkSession(session_id, message_index);
                         const lines = [
@@ -336,6 +392,17 @@ export function actionSessionTool(_server, clientFactory) {
                         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;
+                    }
                     case 'toggle_favorite': {
                         const session = await client.toggleFavorite(session_id);
                         const lines = [

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

@@ -16,11 +16,11 @@ export declare const ActionTriggerSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     action: "create" | "update" | "delete" | "toggle";
     status?: "enabled" | "disabled" | undefined;
+    stop_condition?: string | undefined;
     mcp_servers?: string[] | undefined;
     trigger_type?: "slack" | "schedule" | undefined;
     name?: string | undefined;
     id?: number | undefined;
-    stop_condition?: string | undefined;
     agent_root_name?: string | undefined;
     prompt_template?: string | undefined;
     reuse_session?: boolean | undefined;
@@ -28,11 +28,11 @@ export declare const ActionTriggerSchema: z.ZodObject<{
 }, {
     action: "create" | "update" | "delete" | "toggle";
     status?: "enabled" | "disabled" | undefined;
+    stop_condition?: string | undefined;
     mcp_servers?: string[] | undefined;
     trigger_type?: "slack" | "schedule" | undefined;
     name?: string | undefined;
     id?: number | undefined;
-    stop_condition?: string | undefined;
     agent_root_name?: string | undefined;
     prompt_template?: string | undefined;
     reuse_session?: boolean | undefined;

package/shared/tools/get-configs.js

@@ -160,6 +160,9 @@ function formatAgentRoot(lines, root) {
     if (root.default_skills && root.default_skills.length > 0) {
         lines.push(`- **Default Skills:** ${root.default_skills.map((s) => `\`${s}\``).join(', ')}`);
     }
+    if (root.default_model) {
+        lines.push(`- **Default Model:** \`${root.default_model}\``);
+    }
     lines.push('');
 }
 function formatStopCondition(lines, condition) {

package/shared/tools/get-session.js

@@ -74,6 +74,12 @@ function formatSessionDetails(session, includeTranscript) {
     if (session.mcp_servers && session.mcp_servers.length > 0) {
         lines.push(`- **MCP Servers:** ${session.mcp_servers.join(', ')}`);
     }
+    if (session.catalog_skills && session.catalog_skills.length > 0) {
+        lines.push(`- **Skills:** ${session.catalog_skills.join(', ')}`);
+    }
+    if (session.catalog_plugins && session.catalog_plugins.length > 0) {
+        lines.push(`- **Plugins:** ${session.catalog_plugins.join(', ')}`);
+    }
     if (session.prompt) {
         lines.push('');
         lines.push('### Current Prompt');

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

@@ -15,8 +15,8 @@ export declare const ManageEnqueuedMessagesSchema: z.ZodObject<{
     action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt";
     per_page?: number | undefined;
     page?: number | undefined;
-    content?: string | undefined;
     stop_condition?: string | undefined;
+    content?: string | undefined;
     message_id?: number | undefined;
     position?: number | undefined;
 }, {
@@ -24,8 +24,8 @@ export declare const ManageEnqueuedMessagesSchema: z.ZodObject<{
     action: "list" | "get" | "create" | "update" | "delete" | "reorder" | "interrupt";
     per_page?: number | undefined;
     page?: number | undefined;
-    content?: string | undefined;
     stop_condition?: string | undefined;
+    content?: string | undefined;
     message_id?: number | undefined;
     position?: number | undefined;
 }>;

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

@@ -4,43 +4,40 @@ import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrat
 export declare const StartSessionSchema: z.ZodObject<{
     agent_type: z.ZodOptional<z.ZodString>;
     prompt: z.ZodOptional<z.ZodString>;
-    git_root: z.ZodOptional<z.ZodString>;
-    branch: z.ZodOptional<z.ZodString>;
-    subdirectory: z.ZodOptional<z.ZodString>;
+    agent_root: z.ZodOptional<z.ZodString>;
     title: z.ZodOptional<z.ZodString>;
     slug: z.ZodOptional<z.ZodString>;
     stop_condition: z.ZodOptional<z.ZodString>;
     execution_provider: z.ZodOptional<z.ZodEnum<["local_filesystem", "remote_sandbox"]>>;
     mcp_servers: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     skills: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    plugins: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     custom_metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
     agent_type?: string | undefined;
-    mcp_servers?: string[] | undefined;
-    title?: string | undefined;
+    skills?: string[] | undefined;
+    plugins?: string[] | undefined;
     prompt?: string | undefined;
-    git_root?: string | undefined;
-    branch?: string | undefined;
-    subdirectory?: string | undefined;
+    title?: string | undefined;
     slug?: string | undefined;
     stop_condition?: string | undefined;
     execution_provider?: "local_filesystem" | "remote_sandbox" | undefined;
-    skills?: string[] | undefined;
+    mcp_servers?: string[] | undefined;
+    agent_root?: string | undefined;
     config?: Record<string, unknown> | undefined;
     custom_metadata?: Record<string, unknown> | undefined;
 }, {
     agent_type?: string | undefined;
-    mcp_servers?: string[] | undefined;
-    title?: string | undefined;
+    skills?: string[] | undefined;
+    plugins?: string[] | undefined;
     prompt?: string | undefined;
-    git_root?: string | undefined;
-    branch?: string | undefined;
-    subdirectory?: string | undefined;
+    title?: string | undefined;
     slug?: string | undefined;
     stop_condition?: string | undefined;
     execution_provider?: "local_filesystem" | "remote_sandbox" | undefined;
-    skills?: string[] | undefined;
+    mcp_servers?: string[] | undefined;
+    agent_root?: string | undefined;
     config?: Record<string, unknown> | undefined;
     custom_metadata?: Record<string, unknown> | undefined;
 }>;
@@ -58,17 +55,9 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
                 type: string;
                 description: "Initial prompt for the agent. If provided, the agent job is automatically queued. Omit for a clone-only session.";
             };
-            git_root: {
-                type: string;
-                description: "Repository URL or local path. Examples: \"https://github.com/example/repo.git\", \"/path/to/repo\"";
-            };
-            branch: {
+            agent_root: {
                 type: string;
-                description: "Git branch to work on. Default: \"main\"";
-            };
-            subdirectory: {
-                type: string;
-                description: string;
+                description: "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: {
                 type: string;
@@ -99,7 +88,14 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
                 items: {
                     type: string;
                 };
-                description: "List of skill names to enable for this session. Example: [\"discovery-classify\", \"publish-and-pr\"]";
+                description: "List of skill names to enable for this session. Always include the agent root's default_skills from get_configs as the starting point — omitting skills means the session gets none. Add extras as needed; removing a default should be rare and intentional. Example: [\"discovery-classify\", \"publish-and-pr\"]";
+            };
+            plugins: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: "List of plugin names to enable for this session. Plugins extend agent capabilities with additional integrations. Example: [\"my-plugin\"]";
             };
             config: {
                 type: string;

package/shared/tools/start-session.js

@@ -4,14 +4,7 @@ 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"',
     prompt: 'Initial prompt for the agent. If provided, the agent job is automatically queued. Omit for a clone-only session.',
-    git_root: 'Repository URL or local path. Examples: "https://github.com/example/repo.git", "/path/to/repo"',
-    branch: 'Git branch to work on. Default: "main"',
-    subdirectory: 'Subdirectory within the repository to use as the agent working directory. ' +
-        'This should match a preconfigured agent root default_subdirectory from get_configs — it defines ' +
-        'the root scope for the agent session. Do NOT use this to point at internal package directories ' +
-        '(e.g. "experimental/gcs" in a monorepo) as this blinds the agent to root-level configuration ' +
-        'like CLAUDE.md, build scripts, CI workflows, and monorepo tooling. If no agent root defines ' +
-        'a default_subdirectory, leave this unset.',
+    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. ' +
         'The title appears in the AO web UI and push notifications, making sessions identifiable at a glance. ' +
         'Compose a short, descriptive title (under 70 characters) that captures what the session is doing ' +
@@ -21,16 +14,15 @@ const PARAM_DESCRIPTIONS = {
     stop_condition: 'Stop condition ID from get_configs (e.g. "pr_merged"). The description is automatically resolved and passed to the agent as context.',
     execution_provider: 'Execution environment. Options: "local_filesystem" (runs locally), "remote_sandbox" (runs in isolated sandbox). Default: "local_filesystem"',
     mcp_servers: 'List of MCP server names to enable for this session. Example: ["github-development", "slack"]',
-    skills: 'List of skill names to enable for this session. Example: ["discovery-classify", "publish-and-pr"]',
+    skills: 'List of skill names to enable for this session. Always include the agent root\'s default_skills from get_configs as the starting point — omitting skills means the session gets none. Add extras as needed; removing a default should be rare and intentional. Example: ["discovery-classify", "publish-and-pr"]',
+    plugins: 'List of plugin names to enable for this session. Plugins extend agent capabilities with additional integrations. Example: ["my-plugin"]',
     config: 'Additional configuration as a JSON object.',
     custom_metadata: 'User-defined metadata as a JSON object. Useful for tracking tickets, projects, etc.',
 };
 export const StartSessionSchema = z.object({
     agent_type: z.string().optional().describe(PARAM_DESCRIPTIONS.agent_type),
     prompt: z.string().optional().describe(PARAM_DESCRIPTIONS.prompt),
-    git_root: z.string().optional().describe(PARAM_DESCRIPTIONS.git_root),
-    branch: z.string().optional().describe(PARAM_DESCRIPTIONS.branch),
-    subdirectory: z.string().optional().describe(PARAM_DESCRIPTIONS.subdirectory),
+    agent_root: z.string().optional().describe(PARAM_DESCRIPTIONS.agent_root),
     title: z.string().optional().describe(PARAM_DESCRIPTIONS.title),
     slug: z.string().optional().describe(PARAM_DESCRIPTIONS.slug),
     stop_condition: z.string().optional().describe(PARAM_DESCRIPTIONS.stop_condition),
@@ -40,12 +32,13 @@ export const StartSessionSchema = z.object({
         .describe(PARAM_DESCRIPTIONS.execution_provider),
     mcp_servers: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.mcp_servers),
     skills: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.skills),
+    plugins: z.array(z.string()).optional().describe(PARAM_DESCRIPTIONS.plugins),
     config: z.record(z.unknown()).optional().describe(PARAM_DESCRIPTIONS.config),
     custom_metadata: z.record(z.unknown()).optional().describe(PARAM_DESCRIPTIONS.custom_metadata),
 });
 const TOOL_DESCRIPTION = `Start a new agent session in the Agent Orchestrator.
 
-**IMPORTANT:** Before starting a session, call get_configs to discover available MCP servers, stop conditions, and preconfigured agent roots.
+**IMPORTANT:** Before starting a session, call get_configs to discover available agent roots, MCP servers, stop conditions, and their defaults.
 
 **Returns:** The created session with its ID, status, and configuration.
 
@@ -53,7 +46,12 @@ const TOOL_DESCRIPTION = `Start a new agent session in the Agent Orchestrator.
 - If a prompt is provided, the agent job is automatically queued to start
 - If no prompt is provided, creates a clone-only session that can be started later with action_session
 
-**Defaults from Agent Roots:** When starting a session that matches a preconfigured agent root (from \`get_configs\`), the agent root defines \`default_mcp_servers\` and \`default_skills\`. In most cases, you should pass these defaults through — omitting them means the session won't have MCP servers or skills configured. You can reduce the set (e.g., drop an MCP server you don't need), but when \`ALLOWED_AGENT_ROOTS\` is active, you cannot add servers beyond the defaults. Skills are not constrained — you can augment with additional skills as needed. As a rule of thumb: always pass the defaults unless you have a specific reason to remove something.
+**Agent Roots:** Use \`agent_root\` to specify which preconfigured agent root to use. The API resolves git_root, branch, subdirectory, default_model, and other defaults from the agent root configuration.
+
+**Defaults from Agent Roots:** The agent root defines \`default_mcp_servers\`, \`default_skills\`, and optionally a \`default_stop_condition\`. Omitting \`mcp_servers\` or \`skills\` means the session gets NONE — there is no automatic fallback to defaults.
+
+- **MCP servers:** Start with \`default_mcp_servers\`. Drop servers the task doesn't need (least-privilege). Add extras when the task requires tools beyond the defaults. When \`ALLOWED_AGENT_ROOTS\` is active, you cannot add servers beyond the defaults.
+- **Skills:** Start with \`default_skills\`. You can freely add skills beyond the defaults. Removing a default skill should be rare and intentional — only when you have a specific reason, like replacing a skill with a more capable variant that covers the same ground. Skills are lightweight text files with no blast radius, so keeping all defaults costs nothing.
 
 **Use cases:**
 - Start a new agent task on a repository
@@ -75,17 +73,9 @@ export function startSessionTool(_server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.prompt,
                 },
-                git_root: {
+                agent_root: {
                     type: 'string',
-                    description: PARAM_DESCRIPTIONS.git_root,
-                },
-                branch: {
-                    type: 'string',
-                    description: PARAM_DESCRIPTIONS.branch,
-                },
-                subdirectory: {
-                    type: 'string',
-                    description: PARAM_DESCRIPTIONS.subdirectory,
+                    description: PARAM_DESCRIPTIONS.agent_root,
                 },
                 title: {
                     type: 'string',
@@ -114,6 +104,11 @@ export function startSessionTool(_server, clientFactory) {
                     items: { type: 'string' },
                     description: PARAM_DESCRIPTIONS.skills,
                 },
+                plugins: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: PARAM_DESCRIPTIONS.plugins,
+                },
                 config: {
                     type: 'object',
                     description: PARAM_DESCRIPTIONS.config,
@@ -138,7 +133,7 @@ export function startSessionTool(_server, clientFactory) {
                         configs = await client.getConfigs();
                         setConfigsCache(configs);
                     }
-                    const validation = validateAgentRootConstraints(allowedRoots, configs.agent_roots, validatedArgs.git_root, validatedArgs.mcp_servers, validatedArgs.branch, validatedArgs.subdirectory);
+                    const validation = validateAgentRootConstraints(allowedRoots, configs.agent_roots, validatedArgs.agent_root, validatedArgs.mcp_servers);
                     if (!validation.valid) {
                         return {
                             content: [{ type: 'text', text: `Error starting session: ${validation.error}` }],

package/shared/types.d.ts

@@ -23,6 +23,8 @@ export interface Session {
     execution_provider: string;
     stop_condition: string | null;
     mcp_servers: string[];
+    catalog_skills?: string[];
+    catalog_plugins?: string[];
     config: Record<string, unknown>;
     metadata: Record<string, unknown>;
     custom_metadata: Record<string, unknown>;
@@ -115,6 +117,7 @@ export interface AgentRootInfo {
     default_stop_condition?: string;
     default_mcp_servers?: string[];
     default_skills?: string[];
+    default_model?: string;
 }
 export interface StopConditionInfo {
     id: string;
@@ -143,6 +146,8 @@ export interface CreateSessionRequest {
     execution_provider?: string;
     mcp_servers?: string[];
     skills?: string[];
+    plugins?: string[];
+    agent_root?: string;
     config?: Record<string, unknown>;
     custom_metadata?: Record<string, unknown>;
 }