agent-orchestrator-mcp-server 0.8.5 → 0.8.7

package/README.md

@@ -30,6 +30,7 @@ MCP server for PulseMCP's agent-orchestrator: a Claude Code + MCP-powered agent-
 | `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                                                                                                     |
+| `manage_categories`        | sessions      | write      | Manage dashboard categories that organize sessions: list, create, update, delete, reorder, set_session_category                                                                         |
 | `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                                                                                                                       |
@@ -56,16 +57,16 @@ This server organizes tools into groups that can be selectively enabled or disab
 
 Control which tools are available via the `TOOL_GROUPS` environment variable:
 
-| Group                    | Description                                                                                              |
-| ------------------------ | -------------------------------------------------------------------------------------------------------- |
-| `sessions`               | All session tools (read + write): search, get, configs, transcript_archive, start, action, enqueued msgs |
-| `sessions_readonly`      | Session tools (read only): quick_search_sessions, get_session, get_configs, get_transcript_archive       |
-| `notifications`          | All notification tools (read + write): get, send, mark read, dismiss                                     |
-| `notifications_readonly` | Notification tools (read only): get_notifications                                                        |
-| `triggers`               | All trigger tools (read + write): search, create, update, delete, toggle                                 |
-| `triggers_readonly`      | Trigger tools (read only): search_triggers                                                               |
-| `health`                 | All health tools (read + write): health report, CLI status, maintenance                                  |
-| `health_readonly`        | Health tools (read only): get_system_health                                                              |
+| Group                    | Description                                                                                                          |
+| ------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `sessions`               | All session tools (read + write): search, get, configs, transcript_archive, start, action, enqueued msgs, categories |
+| `sessions_readonly`      | Session tools (read only): quick_search_sessions, get_session, get_configs, get_transcript_archive                   |
+| `notifications`          | All notification tools (read + write): get, send, mark read, dismiss                                                 |
+| `notifications_readonly` | Notification tools (read only): get_notifications                                                                    |
+| `triggers`               | All trigger tools (read + write): search, create, update, delete, toggle                                             |
+| `triggers_readonly`      | Trigger tools (read only): search_triggers                                                                           |
+| `health`                 | All health tools (read + write): health report, CLI status, maintenance                                              |
+| `health_readonly`        | Health tools (read only): get_system_health                                                                          |
 
 **Examples:**
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.8.5",
+  "version": "0.8.7",
   "description": "Local implementation of agent-orchestrator MCP server",
   "main": "build/index.js",
   "type": "module",
@@ -34,7 +34,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.10.6",
-    "tsx": "^4.19.4",
+    "tsx": "^4.22.4",
     "typescript": "^5.7.3"
   },
   "keywords": [

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

@@ -3,7 +3,7 @@
  *
  * A client for interacting with the Agent Orchestrator REST API.
  */
-import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse, EnqueuedMessage, EnqueuedMessagesResponse, EnqueuedMessageInterruptResponse, EnqueuedMessageStatus, Trigger, TriggerType, TriggerStatus, TriggersResponse, TriggerResponse, TriggerChannelsResponse, CreateTriggerRequest, UpdateTriggerRequest, Notification, NotificationsResponse, NotificationBadgeResponse, NotificationMarkAllReadResponse, NotificationDismissAllReadResponse, HealthReport, HealthActionResponse, CliStatusResponse, CliActionResponse, ForkSessionResponse, RefreshSessionResponse, RefreshAllSessionsResponse, BulkArchiveResponse, TranscriptResponse, TranscriptArchiveStatusResponse } from '../types.js';
+import type { Session, Log, SubagentTranscript, SessionsResponse, SearchSessionsResponse, SessionActionResponse, LogsResponse, SubagentTranscriptsResponse, CreateSessionRequest, UpdateSessionRequest, CreateLogRequest, UpdateLogRequest, CreateSubagentTranscriptRequest, UpdateSubagentTranscriptRequest, SessionStatus, LogLevel, SubagentStatus, MCPServerInfo, AgentRootInfo, ConfigsResponse, SendPushNotificationResponse, EnqueuedMessage, EnqueuedMessagesResponse, EnqueuedMessageInterruptResponse, EnqueuedMessageStatus, Category, CategoriesResponse, CreateCategoryRequest, UpdateCategoryRequest, SetSessionCategoryResponse, Trigger, TriggerType, TriggerStatus, TriggersResponse, TriggerResponse, TriggerChannelsResponse, CreateTriggerRequest, UpdateTriggerRequest, Notification, NotificationsResponse, NotificationBadgeResponse, NotificationMarkAllReadResponse, NotificationDismissAllReadResponse, HealthReport, HealthActionResponse, CliStatusResponse, CliActionResponse, ForkSessionResponse, RefreshSessionResponse, RefreshAllSessionsResponse, BulkArchiveResponse, TranscriptResponse, TranscriptArchiveStatusResponse } from '../types.js';
 /** Raw agent root shape as returned by the Rails API */
 export interface RawAgentRoot {
     name: string;
@@ -107,6 +107,12 @@ export interface IAgentOrchestratorClient {
     deleteEnqueuedMessage(sessionId: string | number, messageId: number): Promise<void>;
     reorderEnqueuedMessage(sessionId: string | number, messageId: number, position: number): Promise<EnqueuedMessage>;
     interruptEnqueuedMessage(sessionId: string | number, messageId: number): Promise<EnqueuedMessageInterruptResponse>;
+    listCategories(): Promise<CategoriesResponse>;
+    createCategory(data: CreateCategoryRequest): Promise<Category>;
+    updateCategory(id: number, data: UpdateCategoryRequest): Promise<Category>;
+    deleteCategory(id: number): Promise<void>;
+    reorderCategories(ids: Array<number | 'uncategorized'>): Promise<CategoriesResponse>;
+    setSessionCategory(sessionId: string | number, categoryId: number | null): Promise<SetSessionCategoryResponse>;
     listTriggers(options?: {
         trigger_type?: TriggerType;
         status?: TriggerStatus;
@@ -234,6 +240,12 @@ export declare class AgentOrchestratorClient implements IAgentOrchestratorClient
     deleteEnqueuedMessage(sessionId: string | number, messageId: number): Promise<void>;
     reorderEnqueuedMessage(sessionId: string | number, messageId: number, position: number): Promise<EnqueuedMessage>;
     interruptEnqueuedMessage(sessionId: string | number, messageId: number): Promise<EnqueuedMessageInterruptResponse>;
+    listCategories(): Promise<CategoriesResponse>;
+    createCategory(data: CreateCategoryRequest): Promise<Category>;
+    updateCategory(id: number, data: UpdateCategoryRequest): Promise<Category>;
+    deleteCategory(id: number): Promise<void>;
+    reorderCategories(ids: Array<number | 'uncategorized'>): Promise<CategoriesResponse>;
+    setSessionCategory(sessionId: string | number, categoryId: number | null): Promise<SetSessionCategoryResponse>;
     listTriggers(options?: {
         trigger_type?: TriggerType;
         status?: TriggerStatus;

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

@@ -4,11 +4,12 @@
  * Used in integration tests to simulate API responses without hitting real endpoints.
  */
 import type { IAgentOrchestratorClient } from './orchestrator-client.js';
-import type { Session, Log, SubagentTranscript } from '../types.js';
+import type { Session, Log, SubagentTranscript, Category } from '../types.js';
 interface MockData {
     sessions?: Session[];
     logs?: Log[];
     subagentTranscripts?: SubagentTranscript[];
+    categories?: Category[];
 }
 /**
  * Creates a mock Agent Orchestrator client for integration testing.

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

@@ -64,10 +64,23 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 updated_at: '2025-01-15T14:31:45Z',
             },
         ],
+        categories: initialMockData?.categories || [
+            {
+                id: 1,
+                name: 'Active Work',
+                description: null,
+                position: 0,
+                is_frozen: false,
+                session_count: 1,
+                created_at: '2025-01-15T14:00:00Z',
+                updated_at: '2025-01-15T14:00:00Z',
+            },
+        ],
     };
     let sessionIdCounter = mockData.sessions?.length || 1;
     let logIdCounter = mockData.logs?.length || 1;
     let transcriptIdCounter = mockData.subagentTranscripts?.length || 1;
+    let categoryIdCounter = mockData.categories?.length || 1;
     return {
         mockData,
         async listSessions(options) {
@@ -598,6 +611,107 @@ export function createIntegrationMockOrchestratorClient(initialMockData) {
                 throw new Error(`API Error (404): Session not found`);
             return { session, message: 'Message sent as interrupt' };
         },
+        // Categories
+        async listCategories() {
+            const categories = [...(mockData.categories || [])].sort((a, b) => a.position - b.position);
+            return { categories };
+        },
+        async createCategory(data) {
+            const exists = mockData.categories?.some((c) => c.name.toLowerCase() === data.name.toLowerCase());
+            if (exists) {
+                throw new Error(`API Error (422): Name has already been taken`);
+            }
+            categoryIdCounter++;
+            const maxPosition = (mockData.categories || []).reduce((max, c) => Math.max(max, c.position), -1);
+            const category = {
+                id: categoryIdCounter,
+                name: data.name,
+                description: data.description ? data.description : null,
+                position: maxPosition + 1,
+                is_frozen: false,
+                session_count: 0,
+                created_at: new Date().toISOString(),
+                updated_at: new Date().toISOString(),
+            };
+            mockData.categories?.push(category);
+            return category;
+        },
+        async updateCategory(id, data) {
+            const category = mockData.categories?.find((c) => c.id === id);
+            if (!category) {
+                throw new Error(`API Error (404): Category not found`);
+            }
+            if (data.name !== undefined)
+                category.name = data.name;
+            if (data.description !== undefined) {
+                category.description = data.description ? data.description : null;
+            }
+            if (data.is_frozen !== undefined)
+                category.is_frozen = data.is_frozen;
+            category.updated_at = new Date().toISOString();
+            return category;
+        },
+        async deleteCategory(id) {
+            const index = mockData.categories?.findIndex((c) => c.id === id);
+            if (index === undefined || index === -1) {
+                throw new Error(`API Error (404): Category not found`);
+            }
+            mockData.categories?.splice(index, 1);
+            // Member sessions fall back to Uncategorized
+            mockData.sessions?.forEach((s) => {
+                if (s.category_id === id) {
+                    s.category_id = null;
+                    s.category = null;
+                }
+            });
+        },
+        async reorderCategories(ids) {
+            // Apply new positions for the numeric ids in the order provided.
+            // The "uncategorized" sentinel positions the Uncategorized section and is
+            // not represented in the returned category list. Categories omitted from
+            // `ids` keep their stored position. This is an approximation of the
+            // server's ordering; real position bookkeeping lives Rails-side.
+            let position = 0;
+            for (const id of ids) {
+                if (id === 'uncategorized') {
+                    position++;
+                    continue;
+                }
+                const category = mockData.categories?.find((c) => c.id === id);
+                if (category) {
+                    category.position = position;
+                    category.updated_at = new Date().toISOString();
+                }
+                position++;
+            }
+            const categories = [...(mockData.categories || [])].sort((a, b) => a.position - b.position);
+            return { categories };
+        },
+        async setSessionCategory(sessionId, categoryId) {
+            const session = mockData.sessions?.find((s) => s.id === Number(sessionId) || s.slug === String(sessionId));
+            if (!session) {
+                throw new Error(`API Error (404): Session not found`);
+            }
+            if (categoryId == null) {
+                session.category_id = null;
+                session.category = null;
+                session.updated_at = new Date().toISOString();
+                return { session, message: 'Session moved to Uncategorized' };
+            }
+            const category = mockData.categories?.find((c) => c.id === categoryId);
+            if (!category) {
+                throw new Error(`API Error (404): Category #${categoryId} not found`);
+            }
+            session.category_id = category.id;
+            session.category = {
+                id: category.id,
+                name: category.name,
+                position: category.position,
+                is_frozen: category.is_frozen,
+            };
+            session.updated_at = new Date().toISOString();
+            return { session, message: 'Session assigned to category' };
+        },
         // Triggers
         async listTriggers(options) {
             const page = options?.page || 1;

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

@@ -354,6 +354,27 @@ export class AgentOrchestratorClient {
     async interruptEnqueuedMessage(sessionId, messageId) {
         return this.request('POST', `/sessions/${sessionId}/enqueued_messages/${messageId}/interrupt`);
     }
+    // Categories
+    async listCategories() {
+        return this.request('GET', '/categories');
+    }
+    async createCategory(data) {
+        const response = await this.request('POST', '/categories', data);
+        return response.category;
+    }
+    async updateCategory(id, data) {
+        const response = await this.request('PATCH', `/categories/${id}`, data);
+        return response.category;
+    }
+    async deleteCategory(id) {
+        await this.request('DELETE', `/categories/${id}`);
+    }
+    async reorderCategories(ids) {
+        return this.request('POST', '/categories/reorder', { ids });
+    }
+    async setSessionCategory(sessionId, categoryId) {
+        return this.request('PATCH', `/sessions/${sessionId}/set_category`, { category_id: categoryId });
+    }
     // Triggers
     async listTriggers(options) {
         const { trigger_type, ...rest } = options ?? {};

package/shared/tools/get-session.js

@@ -58,6 +58,8 @@ function formatSessionDetails(session, includeTranscript) {
     ];
     if (session.slug)
         lines.push(`- **Slug:** ${session.slug}`);
+    if (session.category)
+        lines.push(`- **Category:** ${session.category.name}`);
     lines.push('');
     lines.push('### Git Configuration');
     if (session.git_root)

package/shared/tools/manage-categories.d.ts

@@ -0,0 +1,92 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { z } from 'zod';
+import type { IAgentOrchestratorClient } from '../orchestrator-client/orchestrator-client.js';
+export declare const ManageCategoriesSchema: z.ZodObject<{
+    action: z.ZodEnum<["list", "create", "update", "delete", "reorder", "set_session_category"]>;
+    category_id: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    name: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    is_frozen: z.ZodOptional<z.ZodBoolean>;
+    ids: z.ZodOptional<z.ZodArray<z.ZodUnion<[z.ZodNumber, z.ZodLiteral<"uncategorized">]>, "many">>;
+    session_id: z.ZodOptional<z.ZodUnion<[z.ZodString, z.ZodNumber]>>;
+}, "strip", z.ZodTypeAny, {
+    action: "list" | "create" | "update" | "delete" | "reorder" | "set_session_category";
+    description?: string | undefined;
+    name?: string | undefined;
+    session_id?: string | number | undefined;
+    category_id?: number | null | undefined;
+    is_frozen?: boolean | undefined;
+    ids?: (number | "uncategorized")[] | undefined;
+}, {
+    action: "list" | "create" | "update" | "delete" | "reorder" | "set_session_category";
+    description?: string | undefined;
+    name?: string | undefined;
+    session_id?: string | number | undefined;
+    category_id?: number | null | undefined;
+    is_frozen?: boolean | undefined;
+    ids?: (number | "uncategorized")[] | undefined;
+}>;
+export declare function manageCategoriesTool(_server: Server, clientFactory: () => IAgentOrchestratorClient): {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        properties: {
+            action: {
+                type: string;
+                enum: readonly ["list", "create", "update", "delete", "reorder", "set_session_category"];
+                description: string;
+            };
+            category_id: {
+                type: string[];
+                description: string;
+            };
+            name: {
+                type: string;
+                description: string;
+            };
+            description: {
+                type: string;
+                description: string;
+            };
+            is_frozen: {
+                type: string;
+                description: string;
+            };
+            ids: {
+                type: string;
+                items: {
+                    oneOf: ({
+                        type: string;
+                        enum?: undefined;
+                    } | {
+                        type: string;
+                        enum: string[];
+                    })[];
+                };
+                description: string;
+            };
+            session_id: {
+                oneOf: {
+                    type: string;
+                }[];
+                description: string;
+            };
+        };
+        required: string[];
+    };
+    handler: (args: unknown) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    } | {
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError?: undefined;
+    }>;
+};
+//# sourceMappingURL=manage-categories.d.ts.map

package/shared/tools/manage-categories.js

@@ -0,0 +1,227 @@
+import { z } from 'zod';
+const ACTION_ENUM = [
+    'list',
+    'create',
+    'update',
+    'delete',
+    'reorder',
+    'set_session_category',
+];
+export const ManageCategoriesSchema = z.object({
+    action: z.enum(ACTION_ENUM),
+    category_id: z.number().nullable().optional(),
+    name: z.string().optional(),
+    description: z.string().optional(),
+    is_frozen: z.boolean().optional(),
+    ids: z.array(z.union([z.number(), z.literal('uncategorized')])).optional(),
+    session_id: z.union([z.string(), z.number()]).optional(),
+});
+const TOOL_DESCRIPTION = `Manage categories used to organize sessions on the Agent Orchestrator dashboard.
+
+Categories are the named sections sessions are grouped under. Sessions not assigned to a category fall under the built-in "Uncategorized" section.
+
+**Actions:**
+- **list**: List all categories ordered by position, with session counts.
+- **create**: Create a new category (requires "name"; optional "description"). Names are unique case-insensitively (max 100 chars); description max 1000 chars.
+- **update**: Rename, re-describe, or freeze/unfreeze a category (requires "category_id"; any subset of "name", "description", "is_frozen"). Omitted fields are left unchanged.
+- **delete**: Delete a category (requires "category_id"). Sessions in it fall back to Uncategorized.
+- **reorder**: Set the top-to-bottom order of categories (requires "ids" — an array of category IDs). Categories omitted keep their existing position. Include the string "uncategorized" to position the Uncategorized section.
+- **set_session_category**: Assign a session to a category (requires "session_id"; "category_id" to assign, or omit/null to clear to Uncategorized).
+
+**Note:** All freeze state uses "is_frozen".`;
+export function manageCategoriesTool(_server, clientFactory) {
+    return {
+        name: 'manage_categories',
+        description: TOOL_DESCRIPTION,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ACTION_ENUM,
+                    description: 'The category management action to perform.',
+                },
+                category_id: {
+                    type: ['number', 'null'],
+                    description: 'Category ID. Required for "update" and "delete". For "set_session_category", the target category to assign (omit or null to clear to Uncategorized).',
+                },
+                name: {
+                    type: 'string',
+                    description: 'Category name. Required for "create"; optional for "update". Unique case-insensitively, max 100 chars.',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Category description. Optional for "create" and "update". Max 1000 chars; blank clears it.',
+                },
+                is_frozen: {
+                    type: 'boolean',
+                    description: 'Freeze (true) or unfreeze (false) the category. Optional for "update".',
+                },
+                ids: {
+                    type: 'array',
+                    items: { oneOf: [{ type: 'number' }, { type: 'string', enum: ['uncategorized'] }] },
+                    description: 'Required for "reorder". New top-to-bottom order of category IDs. Categories omitted keep their position. Use the string "uncategorized" to position the Uncategorized section.',
+                },
+                session_id: {
+                    oneOf: [{ type: 'string' }, { type: 'number' }],
+                    description: 'Session ID (numeric) or slug (string). Required for "set_session_category".',
+                },
+            },
+            required: ['action'],
+        },
+        handler: async (args) => {
+            try {
+                const validated = ManageCategoriesSchema.parse(args);
+                const client = clientFactory();
+                const { action, category_id, name, description, is_frozen, ids, session_id } = validated;
+                const formatCategory = (cat) => [
+                    `### ${cat.name} (ID: ${cat.id})`,
+                    `- **Position:** ${cat.position}`,
+                    `- **Frozen:** ${cat.is_frozen}`,
+                    cat.description ? `- **Description:** ${cat.description}` : null,
+                    `- **Sessions:** ${cat.session_count}`,
+                ]
+                    .filter(Boolean)
+                    .join('\n');
+                let result;
+                switch (action) {
+                    case 'list': {
+                        const response = await client.listCategories();
+                        if (response.categories.length === 0) {
+                            result = '## Categories\n\nNo categories found.';
+                        }
+                        else {
+                            result = [
+                                `## Categories (${response.categories.length})`,
+                                '',
+                                ...response.categories.map(formatCategory),
+                            ].join('\n\n');
+                        }
+                        break;
+                    }
+                    case 'create': {
+                        if (!name) {
+                            return {
+                                content: [
+                                    { type: 'text', text: 'Error: "name" is required for the "create" action.' },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const cat = await client.createCategory({ name, description });
+                        result = ['## Category Created', '', formatCategory(cat)].join('\n');
+                        break;
+                    }
+                    case 'update': {
+                        if (category_id == null) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "category_id" is required for the "update" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        if (name === undefined && description === undefined && is_frozen === undefined) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: provide at least one of "name", "description", or "is_frozen" for the "update" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const cat = await client.updateCategory(category_id, {
+                            ...(name !== undefined && { name }),
+                            ...(description !== undefined && { description }),
+                            ...(is_frozen !== undefined && { is_frozen }),
+                        });
+                        result = ['## Category Updated', '', formatCategory(cat)].join('\n');
+                        break;
+                    }
+                    case 'delete': {
+                        if (category_id == null) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "category_id" is required for the "delete" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        await client.deleteCategory(category_id);
+                        result = `## Category Deleted\n\nCategory ${category_id} has been deleted. Its sessions fall back to Uncategorized.`;
+                        break;
+                    }
+                    case 'reorder': {
+                        if (!ids || ids.length === 0) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "ids" (a non-empty array) is required for the "reorder" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const response = await client.reorderCategories(ids);
+                        result = [
+                            '## Categories Reordered',
+                            '',
+                            ...response.categories.map(formatCategory),
+                        ].join('\n\n');
+                        break;
+                    }
+                    case 'set_session_category': {
+                        if (session_id === undefined) {
+                            return {
+                                content: [
+                                    {
+                                        type: 'text',
+                                        text: 'Error: "session_id" is required for the "set_session_category" action.',
+                                    },
+                                ],
+                                isError: true,
+                            };
+                        }
+                        const response = await client.setSessionCategory(session_id, category_id ?? null);
+                        result = [
+                            '## Session Category Updated',
+                            '',
+                            `- **Session ID:** ${response.session.id}`,
+                            `- **Category:** ${response.session.category ? response.session.category.name : 'Uncategorized'}`,
+                            `- **Result:** ${response.message}`,
+                        ].join('\n');
+                        break;
+                    }
+                    default: {
+                        const _exhaustiveCheck = action;
+                        return {
+                            content: [{ type: 'text', text: `Error: Unknown action "${_exhaustiveCheck}"` }],
+                            isError: true,
+                        };
+                    }
+                }
+                return { content: [{ type: 'text', text: result }] };
+            }
+            catch (error) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `Error managing categories: ${error instanceof Error ? error.message : 'Unknown error'}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+        },
+    };
+}

package/shared/tools/search-sessions.js

@@ -49,6 +49,8 @@ function formatSession(session) {
     ];
     if (session.slug)
         lines.push(`- **Slug:** ${session.slug}`);
+    if (session.category)
+        lines.push(`- **Category:** ${session.category.name}`);
     if (session.git_root)
         lines.push(`- **Repository:** ${session.git_root}`);
     if (session.branch)

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

@@ -52,7 +52,7 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
         properties: {
             agent_runtime: {
                 type: string;
-                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.";
+                description: string;
             };
             prompt: {
                 type: string;
@@ -102,7 +102,7 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
             };
             config: {
                 type: string;
-                description: "Additional configuration as a JSON object.";
+                description: string;
             };
             custom_metadata: {
                 type: string;

package/shared/tools/start-session.js

@@ -2,7 +2,10 @@ import { z } from 'zod';
 import { parseAllowedAgentRoots, validateAgentRootConstraints } from '../allowed-agent-roots.js';
 import { getConfigsCache, setConfigsCache } from '../cache/configs-cache.js';
 const PARAM_DESCRIPTIONS = {
-    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.',
+    agent_runtime: 'Per-spawn agent runtime override. Valid values are "claude_code" (Claude Code) and "codex" (OpenAI Codex CLI). ' +
+        'When omitted, the session adopts the agent_root\'s default_runtime, falling back to "claude_code". ' +
+        "Call get_configs to see each agent root's default_runtime. Pair with `config.model` to pick a model valid for the chosen runtime " +
+        '(e.g. "opus"/"sonnet"/"haiku" for claude_code, "gpt-5.5"/"gpt-5.4" for codex).',
     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. ' +
@@ -16,7 +19,11 @@ const PARAM_DESCRIPTIONS = {
     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. 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.',
+    config: 'Additional configuration as a JSON object. Use `config.model` to choose the agent model for this session ' +
+        '(e.g. {"model": "gpt-5.4"} for a codex runtime, or {"model": "sonnet"} for claude_code). ' +
+        "The model must be valid for the resolved agent_runtime; call get_configs to see each agent root's default_model. " +
+        "When omitted, the session uses the agent root's default_model (or the runtime's default model). " +
+        "An explicit config.model always takes precedence over the agent root's default_model.",
     custom_metadata: 'User-defined metadata as a JSON object. Useful for tracking tickets, projects, etc.',
     auto_compact_window: 'Optional per-session auto-compact (context) window override, in tokens. ' +
         '**You should generally rely on the default of 200,000** — omit this parameter and the API default applies. ' +
@@ -59,6 +66,8 @@ const TOOL_DESCRIPTION = `Start a new agent session in the Agent Orchestrator.
 - **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.
 
+**Runtime and model selection:** Pass \`agent_runtime\` to override which agent runtime the session uses — \`claude_code\` (Claude Code) or \`codex\` (OpenAI Codex CLI). Pass \`config: { model: "..." }\` to choose the model (e.g. \`opus\`/\`sonnet\`/\`haiku\` for claude_code, \`gpt-5.5\`/\`gpt-5.4\` for codex). Both are optional: when omitted, the session inherits the agent root's \`default_runtime\` and \`default_model\`. Call get_configs to discover each root's defaults and pick a model that is valid for the chosen runtime.
+
 **Use cases:**
 - Start a new agent task on a repository
 - Create a session to work on a specific branch

package/shared/tools.js

@@ -1,11 +1,12 @@
 import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
-// 16 tools across 4 domains + 1 composite group
+// 17 tools across 4 domains + 1 composite group
 import { quickSearchSessionsTool } from './tools/search-sessions.js';
 import { startSessionTool } from './tools/start-session.js';
 import { getSessionTool } from './tools/get-session.js';
 import { actionSessionTool, selfSessionActionSessionTool } from './tools/action-session.js';
 import { getConfigsTool } from './tools/get-configs.js';
 import { manageEnqueuedMessagesTool } from './tools/manage-enqueued-messages.js';
+import { manageCategoriesTool } from './tools/manage-categories.js';
 import { sendPushNotificationTool } from './tools/send-push-notification.js';
 import { getNotificationsTool } from './tools/get-notifications.js';
 import { actionNotificationTool } from './tools/action-notification.js';
@@ -61,7 +62,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
 /**
  * All available tools with their group assignments.
  *
- * 16 tools across 4 domains + 1 composite group:
+ * 17 tools across 4 domains + 1 composite group:
  * - quick_search_sessions: Quick title-based search/list/get sessions by ID (sessions, read)
  * - get_session: Get detailed session info with optional logs/transcripts (sessions, read; self_session)
  * - get_configs: Fetch all static configuration (sessions, read; self_session)
@@ -69,6 +70,7 @@ export function parseEnabledToolGroups(enabledGroupsParam) {
  * - start_session: Create a new session (sessions, write)
  * - action_session: Perform session actions (sessions, write; self_session: filtered to update_notes, update_title, archive)
  * - manage_enqueued_messages: Manage session message queue (sessions, write)
+ * - manage_categories: Manage dashboard categories and session assignment (sessions, write)
  * - get_notifications: Get/list notifications and badge count (notifications, read)
  * - send_push_notification: Send a push notification (notifications, write; self_session)
  * - action_notification: Mark read, dismiss notifications (notifications, write)
@@ -119,6 +121,11 @@ const ALL_TOOLS = [
         group: 'sessions',
         isWriteOperation: true,
     },
+    {
+        factory: manageCategoriesTool,
+        group: 'sessions',
+        isWriteOperation: true,
+    },
     // Notification tools - read operations
     {
         factory: getNotificationsTool,

package/shared/types.d.ts

@@ -32,6 +32,8 @@ export interface Session {
     job_id: string | null;
     running_job_id: string | null;
     archived_at: string | null;
+    category_id?: number | null;
+    category?: CategorySummary | null;
     created_at: string;
     updated_at: string;
     transcript?: string;
@@ -193,6 +195,41 @@ export interface UpdateSubagentTranscriptRequest {
     total_tokens?: number;
     tool_use_count?: number;
 }
+export interface Category {
+    id: number;
+    name: string;
+    description: string | null;
+    position: number;
+    is_frozen: boolean;
+    session_count: number;
+    created_at: string;
+    updated_at: string;
+}
+export interface CategorySummary {
+    id: number;
+    name: string;
+    position: number;
+    is_frozen: boolean;
+}
+export interface CategoriesResponse {
+    categories: Category[];
+}
+export interface CategoryResponse {
+    category: Category;
+}
+export interface CreateCategoryRequest {
+    name: string;
+    description?: string;
+}
+export interface UpdateCategoryRequest {
+    name?: string;
+    description?: string;
+    is_frozen?: boolean;
+}
+export interface SetSessionCategoryResponse {
+    session: Session;
+    message: string;
+}
 export type EnqueuedMessageStatus = 'pending' | 'processing' | 'sent';
 export interface EnqueuedMessage {
     id: number;