agent-orchestrator-mcp-server 0.4.1 → 0.4.3

package/package.json

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

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

@@ -26,11 +26,15 @@ export interface AgentRootValidationResult {
  * Validate a start_session request against the allowed agent roots constraints.
  *
  * When ALLOWED_AGENT_ROOTS is set:
- * - git_root must match one of the allowed agent roots
+ * - git_root (and optionally branch/subdirectory) must match one of the allowed agent roots
  * - 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[]): AgentRootValidationResult;
+export declare function validateAgentRootConstraints(allowedRoots: string[] | null, agentRoots: AgentRootInfo[], gitRoot?: string, mcpServers?: string[], branch?: string, subdirectory?: string): AgentRootValidationResult;
 //# sourceMappingURL=allowed-agent-roots.d.ts.map

package/shared/allowed-agent-roots.js

@@ -39,18 +39,34 @@ export function filterAgentRoots(agentRoots, allowedRoots) {
  * Validate a start_session request against the allowed agent roots constraints.
  *
  * When ALLOWED_AGENT_ROOTS is set:
- * - git_root must match one of the allowed agent roots
+ * - git_root (and optionally branch/subdirectory) must match one of the allowed agent roots
  * - 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) {
+export function validateAgentRootConstraints(allowedRoots, agentRoots, gitRoot, mcpServers, branch, subdirectory) {
     if (allowedRoots === null) {
         return { valid: true };
     }
-    // Find the matching agent root by git_root
-    const matchingRoot = agentRoots.find((root) => allowedRoots.includes(root.name) && root.git_root === gitRoot);
+    // 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;
+        });
+    }
+    else {
+        matchingRoot = candidates[0];
+    }
     if (!matchingRoot) {
         const allowedNames = allowedRoots.join(', ');
         const allowedGitRoots = agentRoots

package/shared/tools/action-session.js

@@ -35,11 +35,11 @@ export const ActionSessionSchema = z.object({
 const TOOL_DESCRIPTION = `Perform an action on an agent session.
 
 **Actions:**
-- **follow_up**: Send a follow-up prompt to a paused session (requires "prompt" parameter)
-- **pause**: Pause a running session, transitioning it to "needs_input" status
-- **restart**: Restart a paused or failed session without providing new input
+- **follow_up**: Send a follow-up prompt to an idle session (requires "prompt" parameter)
+- **pause**: Pause a running session, transitioning it to idle "needs_input" status
+- **restart**: Restart an idle or failed session without providing new input
 - **archive**: Archive a session (marks as completed)
-- **unarchive**: Restore an archived session to "needs_input" status
+- **unarchive**: Restore an archived session to idle "needs_input" status
 - **change_mcp_servers**: Update the MCP servers for a session (requires "mcp_servers" parameter)
 - **fork**: Fork a session from a specific transcript message (requires "message_index")
 - **refresh**: Refresh a single session's status from the execution provider

package/shared/tools/get-session.js

@@ -41,7 +41,7 @@ const TOOL_DESCRIPTION = `Get detailed information about a specific agent sessio
 
 **Use cases:**
 - View detailed session information
-- Check session status and progress
+- Check session status and progress (use transcript to determine if a "needs_input" session has completed its task or needs follow-up)
 - Retrieve session transcript for review
 - Review logs for debugging
 - Inspect subagent transcripts`;

package/shared/tools/search-sessions.js

@@ -28,14 +28,14 @@ const TOOL_DESCRIPTION = `Quick title-based search for agent sessions in the Age
 - Find a specific session by ID (set id parameter)
 - Search sessions by title keyword (set query parameter)
 - List all sessions with optional status filter
-- Monitor sessions requiring attention (status: "needs_input")
+- Monitor sessions that have completed or need attention (status: "needs_input")
 
 **Returns:** A list of matching sessions with their status, configuration, and metadata.
 
 **Session statuses:**
 - waiting: Session created, waiting to start
 - running: Agent is actively executing
-- needs_input: Agent paused, waiting for user input
+- needs_input: Agent has completed its current work and is idle. May indicate the task is done (most common) or that the agent needs additional input to continue. Check the session transcript to determine which case applies.
 - failed: Session encountered an error
 - archived: Session completed and archived`;
 /** Maximum characters to display for prompt preview */

package/shared/tools/start-session.js

@@ -129,7 +129,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);
+                    const validation = validateAgentRootConstraints(allowedRoots, configs.agent_roots, validatedArgs.git_root, validatedArgs.mcp_servers, validatedArgs.branch, validatedArgs.subdirectory);
                     if (!validation.valid) {
                         return {
                             content: [{ type: 'text', text: `Error starting session: ${validation.error}` }],