agent-orchestrator-mcp-server 0.4.5 → 0.4.7

package/package.json

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

package/shared/tools/get-configs.js

@@ -124,6 +124,7 @@ function formatResponse(configs, fromCache) {
     lines.push('- Use `name` values from **MCP Servers** in `start_session` `mcp_servers` parameter');
     lines.push('- Use `git_root` from **Agent Roots** to start sessions with preconfigured defaults');
     lines.push('- If an **Agent Root** has a `default_subdirectory`, pass it as `subdirectory` in `start_session` — do not set `subdirectory` to arbitrary internal paths');
+    lines.push("- Pass `default_skills` from **Agent Roots** in the `skills` parameter of `start_session` — sessions won't have skills loaded unless you explicitly pass them");
     lines.push('- Use `id` values from **Stop Conditions** in `start_session` `stop_condition` parameter');
     if (fromCache) {
         lines.push('');

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)
@@ -114,6 +116,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/start-session.d.ts

@@ -12,6 +12,7 @@ export declare const StartSessionSchema: z.ZodObject<{
     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">>;
     config: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     custom_metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
 }, "strip", z.ZodTypeAny, {
@@ -25,6 +26,7 @@ export declare const StartSessionSchema: z.ZodObject<{
     slug?: string | undefined;
     stop_condition?: string | undefined;
     execution_provider?: "local_filesystem" | "remote_sandbox" | undefined;
+    skills?: string[] | undefined;
     config?: Record<string, unknown> | undefined;
     custom_metadata?: Record<string, unknown> | undefined;
 }, {
@@ -38,6 +40,7 @@ export declare const StartSessionSchema: z.ZodObject<{
     slug?: string | undefined;
     stop_condition?: string | undefined;
     execution_provider?: "local_filesystem" | "remote_sandbox" | undefined;
+    skills?: string[] | undefined;
     config?: Record<string, unknown> | undefined;
     custom_metadata?: Record<string, unknown> | undefined;
 }>;
@@ -91,6 +94,13 @@ export declare function startSessionTool(_server: Server, clientFactory: () => I
                 };
                 description: "List of MCP server names to enable for this session. Example: [\"github-development\", \"slack\"]";
             };
+            skills: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: "List of skill names to enable for this session. Example: [\"discovery-classify\", \"publish-and-pr\"]";
+            };
             config: {
                 type: string;
                 description: "Additional configuration as a JSON object.";

package/shared/tools/start-session.js

@@ -21,6 +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"]',
     config: 'Additional configuration as a JSON object.',
     custom_metadata: 'User-defined metadata as a JSON object. Useful for tracking tickets, projects, etc.',
 };
@@ -38,6 +39,7 @@ export const StartSessionSchema = z.object({
         .optional()
         .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),
     config: z.record(z.unknown()).optional().describe(PARAM_DESCRIPTIONS.config),
     custom_metadata: z.record(z.unknown()).optional().describe(PARAM_DESCRIPTIONS.custom_metadata),
 });
@@ -51,10 +53,12 @@ const TOOL_DESCRIPTION = `Start a new agent session in the Agent Orchestrator.
 - If a prompt is provided, the agent job is automatically queued to start
 - If no prompt is provided, creates a clone-only session that can be started later with action_session
 
+**Defaults from Agent Roots:** When starting a session that matches a preconfigured agent root (from \`get_configs\`), the agent root defines \`default_mcp_servers\` and \`default_skills\`. In most cases, you should pass these defaults through — omitting them means the session won't have MCP servers or skills configured. You can reduce the set (e.g., drop an MCP server you don't need), but when \`ALLOWED_AGENT_ROOTS\` is active, you cannot add servers beyond the defaults. Skills are not constrained — you can augment with additional skills as needed. As a rule of thumb: always pass the defaults unless you have a specific reason to remove something.
+
 **Use cases:**
 - Start a new agent task on a repository
 - Create a session to work on a specific branch
-- Set up an agent with specific MCP servers enabled
+- Set up an agent with specific MCP servers and skills enabled
 - Create a session with custom metadata for tracking`;
 export function startSessionTool(_server, clientFactory) {
     return {
@@ -105,6 +109,11 @@ export function startSessionTool(_server, clientFactory) {
                     items: { type: 'string' },
                     description: PARAM_DESCRIPTIONS.mcp_servers,
                 },
+                skills: {
+                    type: 'array',
+                    items: { type: 'string' },
+                    description: PARAM_DESCRIPTIONS.skills,
+                },
                 config: {
                     type: 'object',
                     description: PARAM_DESCRIPTIONS.config,

package/shared/types.d.ts

@@ -142,6 +142,7 @@ export interface CreateSessionRequest {
     stop_condition?: string;
     execution_provider?: string;
     mcp_servers?: string[];
+    skills?: string[];
     config?: Record<string, unknown>;
     custom_metadata?: Record<string, unknown>;
 }