agent-orchestrator-mcp-server 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-orchestrator-mcp-server",
-  "version": "0.5.0",
+  "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.js

@@ -178,9 +178,14 @@ export class AgentOrchestratorClient {
         return response.session;
     }
     async createSession(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;
+        // 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;
     }

package/shared/tools/get-session.js

@@ -77,6 +77,9 @@ function formatSessionDetails(session, includeTranscript) {
     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/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;
     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;
     mcp_servers?: string[] | undefined;
+    agent_root?: string | undefined;
     config?: Record<string, unknown> | undefined;
     custom_metadata?: Record<string, unknown> | undefined;
 }, {
     agent_type?: 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;
     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: {
+            agent_root: {
                 type: string;
-                description: "Repository URL or local path. Examples: \"https://github.com/example/repo.git\", \"/path/to/repo\"";
-            };
-            branch: {
-                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;
@@ -101,6 +90,13 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
                 };
                 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;
                 description: "Additional configuration as a JSON object.";

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 ' +
@@ -22,15 +15,14 @@ const PARAM_DESCRIPTIONS = {
     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. 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,9 @@ 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\`, \`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.
+**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.
@@ -78,17 +73,9 @@ export function startSessionTool(_server, clientFactory) {
                     type: 'string',
                     description: PARAM_DESCRIPTIONS.prompt,
                 },
-                git_root: {
-                    type: 'string',
-                    description: PARAM_DESCRIPTIONS.git_root,
-                },
-                branch: {
-                    type: 'string',
-                    description: PARAM_DESCRIPTIONS.branch,
-                },
-                subdirectory: {
+                agent_root: {
                     type: 'string',
-                    description: PARAM_DESCRIPTIONS.subdirectory,
+                    description: PARAM_DESCRIPTIONS.agent_root,
                 },
                 title: {
                     type: 'string',
@@ -117,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,
@@ -141,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

@@ -24,6 +24,7 @@ export interface Session {
     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>;
@@ -145,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>;
 }