agent-orchestrator-mcp-server 0.4.6 → 0.5.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.6",
+  "version": "0.5.0",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",

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,10 @@ export class AgentOrchestratorClient {
         return response.session;
     }
     async createSession(data) {
-        const response = await this.request('POST', '/sessions', data);
+        // Remap `skills` to `catalog_skills` for the API (Rails strong params expects `catalog_skills`)
+        const { skills, ...rest } = data;
+        const body = skills !== undefined ? { ...rest, catalog_skills: skills } : rest;
+        const response = await this.request('POST', '/sessions', body);
         return response.session;
     }
     async updateSession(id, data) {
@@ -210,6 +214,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.d.ts

@@ -46,7 +46,7 @@ export declare function getSessionTool(_server: Server, clientFactory: () => IAg
             };
             include_transcript: {
                 type: string;
-                description: "Include the full transcript of the session. Default: false. Set to true for complete conversation history.";
+                description: "Include the full transcript inline. Default: false. WARNING: can be very large and may overwhelm your context window. When false, the transcript file path is returned instead so you can grep/tail it efficiently (see tool description for tips).";
             };
             transcript_format: {
                 type: string;

package/shared/tools/get-session.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 const PARAM_DESCRIPTIONS = {
     id: 'Session ID (numeric) or slug (string). Examples: "1", "fix-auth-bug-20250115"',
-    include_transcript: 'Include the full transcript of the session. Default: false. Set to true for complete conversation history.',
+    include_transcript: 'Include the full transcript inline. Default: false. WARNING: can be very large and may overwhelm your context window. When false, the transcript file path is returned instead so you can grep/tail it efficiently (see tool description for tips).',
     transcript_format: 'Format for transcript retrieval: "text" (human-readable) or "json" (structured). Only used when include_transcript is true. When specified, fetches transcript via dedicated endpoint instead of inline.',
     include_logs: 'Include logs for the session. Default: false. Use logs_page and logs_per_page for pagination.',
     logs_page: 'Page number for logs pagination. Default: 1',
@@ -35,10 +35,12 @@ export const GetSessionSchema = z.object({
 const TOOL_DESCRIPTION = `Get detailed information about a specific agent session.
 
 **Returns:** Complete session details including status, configuration, metadata, and optionally:
-- Full session transcript
+- Full session transcript (WARNING: can be very large)
 - Session logs (paginated)
 - Subagent transcripts (paginated)
 
+**Transcript access:** By default (include_transcript=false), the response includes the transcript file path instead of the full content. You can then efficiently grep, tail, or read specific sections of that file — for example, read the last ~100 lines to see the most recent messages. This avoids overwhelming your context window with massive transcripts.
+
 **Use cases:**
 - View detailed session information
 - Check session status and progress (use transcript to determine if a "needs_input" session has completed its task or needs follow-up)
@@ -72,6 +74,9 @@ 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.prompt) {
         lines.push('');
         lines.push('### Current Prompt');
@@ -114,6 +119,14 @@ function formatSessionDetails(session, includeTranscript) {
         lines.push(session.transcript);
         lines.push('```');
     }
+    // When transcript is not included inline, provide file path hints for efficient access
+    if (!includeTranscript && session.session_id) {
+        lines.push('');
+        lines.push('### Transcript File');
+        lines.push(`- **Path pattern:** \`~/.claude/projects/*/${session.session_id}.jsonl\``);
+        lines.push(`- **Find exact path:** \`ls ~/.claude/projects/*/${session.session_id}.jsonl\``);
+        lines.push('- **Tip:** Once you have the exact path, read the last ~100 lines to see the most recent messages, or grep for specific keywords. This avoids loading the entire transcript into your context window.');
+    }
     return lines.join('\n');
 }
 function formatLogs(logs, pagination) {

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

@@ -17,30 +17,30 @@ export declare const StartSessionSchema: z.ZodObject<{
     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;
     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;
     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;
     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;
     config?: Record<string, unknown> | undefined;
     custom_metadata?: Record<string, unknown> | undefined;
 }>;
@@ -99,7 +99,7 @@ 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\"]";
             };
             config: {
                 type: string;

package/shared/tools/start-session.js

@@ -21,7 +21,7 @@ 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"]',
     config: 'Additional configuration as a JSON object.',
     custom_metadata: 'User-defined metadata as a JSON object. Useful for tracking tickets, projects, etc.',
 };
@@ -53,7 +53,10 @@ 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.
+**Defaults from Agent Roots:** When starting a session that matches a preconfigured agent root (from \`get_configs\`), 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

package/shared/types.d.ts

@@ -23,6 +23,7 @@ export interface Session {
     execution_provider: string;
     stop_condition: string | null;
     mcp_servers: string[];
+    catalog_skills?: string[];
     config: Record<string, unknown>;
     metadata: Record<string, unknown>;
     custom_metadata: Record<string, unknown>;
@@ -115,6 +116,7 @@ export interface AgentRootInfo {
     default_stop_condition?: string;
     default_mcp_servers?: string[];
     default_skills?: string[];
+    default_model?: string;
 }
 export interface StopConditionInfo {
     id: string;