@josstei/maestro 1.6.4-rc.1

package/claude/src/mcp/maestro-server.js

@@ -0,0 +1,122 @@
+'use strict';
+
+const { log, fatal } = require('../core/logger');
+const { resolveVersion } = require('../core/version');
+const { createServer } = require('./core/create-server');
+const { createLineDispatcher } = require('./core/line-reader');
+const { createProjectRootCache } = require('./core/project-root-cache');
+const {
+  DEFAULT_PROTOCOL_VERSION,
+  buildInitializeResult,
+  createToolErrorResult,
+  createToolSuccessResult,
+  createProtocolHandlers,
+} = require('./core/protocol-dispatcher');
+const { DEFAULT_TOOL_PACKS } = require('./tool-packs');
+const {
+  getDefaultRuntimeConfig,
+  normalizeRuntimeConfig,
+} = require('./runtime/runtime-config-map');
+const { resolveCanonicalSrcFromExtensionRoot } = require('./utils/extension-root');
+
+const SERVER_INFO = Object.freeze({
+  name: 'maestro',
+  version: resolveVersion(__dirname),
+});
+
+function createInitializeResult(protocolVersion) {
+  return buildInitializeResult(protocolVersion, SERVER_INFO);
+}
+
+function runRuntimeServer(runtimeConfig, options = {}) {
+  const resolvedRuntimeConfig = normalizeRuntimeConfig(runtimeConfig);
+  const canonicalSrcRoot =
+    options.canonicalSrcRoot || resolveCanonicalSrcFromExtensionRoot();
+  const toolPacks = Array.isArray(options.toolPacks)
+    ? options.toolPacks
+    : DEFAULT_TOOL_PACKS;
+  const stdin = options.stdin || process.stdin;
+  const stdout = options.stdout || process.stdout;
+
+  let requestFromClient;
+  const cache = createProjectRootCache({
+    runtimeConfig: resolvedRuntimeConfig,
+    requestClientRoots: () => requestFromClient('roots/list', {}),
+  });
+
+  const server = createServer({
+    runtimeConfig: resolvedRuntimeConfig,
+    services: {
+      canonicalSrcRoot,
+      workspaceSuggestion: () => cache.workspaceSuggestion(),
+    },
+    toolPacks,
+  });
+
+  const handlers = createProtocolHandlers(server, cache.getProjectRoot, stdout, {
+    serverInfo: SERVER_INFO,
+    callbacks: {
+      onInitialize(params) {
+        cache.setClientSupportsRoots(
+          Boolean(params && params.capabilities && params.capabilities.roots)
+        );
+      },
+      async onInitialized() {
+        await cache.refreshClientRoots();
+      },
+      onRootsListChanged() {
+        cache.invalidateClientRoots();
+      },
+    },
+  });
+
+  requestFromClient = handlers.requestFromClient;
+
+  server.onToolCall('initialize_workspace', (result) => {
+    if (result && result.success && result.workspace_path) {
+      cache.setExplicitWorkspacePath(result.workspace_path);
+    }
+  });
+
+  const lineReader = createLineDispatcher(stdin, (message) => {
+    Promise.resolve(handlers.respond(message)).catch((error) => {
+      log('error', `Failed to handle MCP message: ${error.message}`);
+    });
+  });
+
+  log('info', 'MCP server starting');
+  log('info', 'MCP server connected');
+
+  return {
+    close() {
+      lineReader.close();
+      handlers.drain();
+    },
+    server,
+  };
+}
+
+function main(runtimeConfig) {
+  const resolved =
+    runtimeConfig || process.env.MAESTRO_RUNTIME || getDefaultRuntimeConfig();
+  runRuntimeServer(resolved);
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    fatal(error && error.message ? error.message : String(error));
+  }
+}
+
+module.exports = {
+  DEFAULT_PROTOCOL_VERSION,
+  SERVER_INFO,
+  createInitializeResult,
+  createToolErrorResult,
+  createToolSuccessResult,
+  normalizeRuntimeConfig,
+  runRuntimeServer,
+  main,
+};

package/claude/src/mcp/runtime/runtime-config-map.js

@@ -0,0 +1,70 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const PLATFORMS_DIR = path.resolve(__dirname, '..', '..', 'platforms');
+
+const RUNTIME_NAMES = fs.readdirSync(PLATFORMS_DIR, { withFileTypes: true })
+  .filter((entry) => entry.isDirectory() && entry.name !== 'shared')
+  .filter((entry) =>
+    fs.existsSync(path.join(PLATFORMS_DIR, entry.name, 'runtime-config.js'))
+  )
+  .map((entry) => entry.name)
+  .sort();
+
+const configCache = Object.create(null);
+
+function loadRuntimeConfig(name) {
+  if (configCache[name]) {
+    return configCache[name];
+  }
+
+  const configPath = path.join(PLATFORMS_DIR, name, 'runtime-config.js');
+  const config = require(configPath);
+  configCache[name] = config;
+  return config;
+}
+
+function getRuntimeConfig(name) {
+  if (!RUNTIME_NAMES.includes(name)) {
+    throw new Error(`Unknown runtime config: ${name}`);
+  }
+
+  return loadRuntimeConfig(name);
+}
+
+function getDefaultRuntimeConfig() {
+  const runtime = process.env.MAESTRO_RUNTIME;
+  if (runtime && RUNTIME_NAMES.includes(runtime)) {
+    return loadRuntimeConfig(runtime);
+  }
+
+  if (RUNTIME_NAMES.length === 0) {
+    throw new Error('No runtime configs found in platforms/');
+  }
+
+  return loadRuntimeConfig(RUNTIME_NAMES[0]);
+}
+
+function normalizeRuntimeConfig(runtimeConfig) {
+  if (!runtimeConfig) {
+    return getDefaultRuntimeConfig();
+  }
+
+  if (typeof runtimeConfig === 'string') {
+    return getRuntimeConfig(runtimeConfig);
+  }
+
+  if (typeof runtimeConfig === 'object' && runtimeConfig.name) {
+    return runtimeConfig;
+  }
+
+  return getDefaultRuntimeConfig();
+}
+
+module.exports = {
+  getRuntimeConfig,
+  getDefaultRuntimeConfig,
+  normalizeRuntimeConfig,
+};

package/claude/src/mcp/tool-packs/content/index.js

@@ -0,0 +1,80 @@
+'use strict';
+
+const { defineToolPack } = require('../contracts');
+const { createHandler: createSkillContentHandler } = require('../../handlers/get-skill-content');
+const { createHandler: createAgentHandler } = require('../../handlers/get-agent');
+const { createHandler: createRuntimeContextHandler } = require('../../handlers/get-runtime-context');
+const { getDefaultRuntimeConfig } = require('../../runtime/runtime-config-map');
+
+function createToolPack(context = {}) {
+  const runtimeConfig = context.runtimeConfig || getDefaultRuntimeConfig();
+  const canonicalSrcRoot =
+    context.services &&
+    typeof context.services.canonicalSrcRoot === 'string' &&
+    context.services.canonicalSrcRoot.length > 0
+      ? context.services.canonicalSrcRoot
+      : undefined;
+
+  return defineToolPack({
+    name: 'content',
+    tools: [
+      {
+        name: 'get_skill_content',
+        description:
+          'Read one or more Maestro skills, protocols, templates, or references from the runtime-configured Maestro content source and apply runtime-specific transforms before returning them.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            resources: {
+              type: 'array',
+              items: { type: 'string' },
+              description:
+                'Resource identifiers to read. Skills: "delegation", "execution", "validation", "session-management", "implementation-planning", "code-review", "design-dialogue". Protocols: "agent-base-protocol", "filesystem-safety-protocol". Templates: "design-document", "implementation-plan", "session-state". References: "architecture", "orchestration-steps".',
+            },
+          },
+          required: ['resources'],
+        },
+      },
+      {
+        name: 'get_agent',
+        description:
+          'Read one or more Maestro agent methodology definitions. Returns the methodology body, declared tool restrictions, and a runtime-specific tool_name for dispatch.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            agents: {
+              type: 'array',
+              items: { type: 'string' },
+              description:
+                'Agent identifiers (kebab-case or snake_case): "coder", "code-reviewer" / "code_reviewer", "ux-designer" / "ux_designer", etc.',
+            },
+          },
+          required: ['agents'],
+        },
+      },
+      {
+        name: 'get_runtime_context',
+        description:
+          'Returns tool mappings, agent dispatch syntax, MCP prefixes, and path variables for the current Maestro runtime. Call once at session start (step 0) and carry the returned context through the session.',
+        inputSchema: {
+          type: 'object',
+          properties: {},
+        },
+      },
+    ],
+    handlers: {
+      get_skill_content: createSkillContentHandler(runtimeConfig, canonicalSrcRoot),
+      get_agent: createAgentHandler(runtimeConfig, canonicalSrcRoot),
+      get_runtime_context: createRuntimeContextHandler(
+        runtimeConfig,
+        typeof context.services?.workspaceSuggestion === 'function'
+          ? context.services.workspaceSuggestion
+          : () => null
+      ),
+    },
+  });
+}
+
+module.exports = {
+  createToolPack,
+};

package/claude/src/mcp/tool-packs/contracts.js

@@ -0,0 +1,30 @@
+'use strict';
+
+function createCompositionContext(options = {}) {
+  const runtimeConfig =
+    options.runtimeConfig && typeof options.runtimeConfig === 'object'
+      ? options.runtimeConfig
+      : {};
+  const services =
+    options.services && typeof options.services === 'object'
+      ? options.services
+      : {};
+
+  return Object.freeze({
+    runtimeConfig,
+    services,
+  });
+}
+
+function defineToolPack(pack) {
+  if (!pack || typeof pack !== 'object' || Array.isArray(pack)) {
+    throw new TypeError('Tool pack must be an object.');
+  }
+
+  return pack;
+}
+
+module.exports = {
+  createCompositionContext,
+  defineToolPack,
+};

package/claude/src/mcp/tool-packs/index.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const { createToolPack: createWorkspaceToolPack } = require('./workspace');
+const { createToolPack: createSessionToolPack } = require('./session');
+const { createToolPack: createContentToolPack } = require('./content');
+
+const DEFAULT_TOOL_PACKS = Object.freeze([
+  createWorkspaceToolPack,
+  createSessionToolPack,
+  createContentToolPack,
+]);
+
+module.exports = {
+  DEFAULT_TOOL_PACKS,
+};

package/claude/src/mcp/tool-packs/session/index.js

@@ -0,0 +1,243 @@
+'use strict';
+
+const { defineToolPack } = require('../contracts');
+const { PHASE_ITEM_SCHEMA } = require('../../contracts/plan-schema');
+const {
+  handleCreateSession,
+  handleGetSessionStatus,
+  handleTransitionPhase,
+  handleArchiveSession,
+  handleUpdateSession,
+} = require('../../handlers/session-state-tools');
+const {
+  handleEnterDesignGate,
+  handleRecordDesignApproval,
+  handleGetDesignGateStatus,
+} = require('../../handlers/design-gate');
+const {
+  handleScanPhaseChanges,
+  handleReconcilePhase,
+} = require('../../handlers/reconciliation');
+
+function createToolPack() {
+  return defineToolPack({
+    name: 'session',
+    tools: [
+      {
+        name: 'create_session',
+        description:
+          'Create a new Maestro orchestration session. Supply the implementation plan either by path (implementation_plan) or by inline content (implementation_plan_content + implementation_plan_filename); the two variants are mutually exclusive. The content variant is required when the caller cannot guarantee the plan file is visible to the MCP server under the configured workspace (e.g. Gemini Plan Mode writes to a tmp root).',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+            task: { type: 'string' },
+            design_document: { type: ['string', 'null'] },
+            implementation_plan: { type: ['string', 'null'] },
+            implementation_plan_content: {
+              type: 'string',
+              description:
+                'Inline implementation-plan Markdown. Requires implementation_plan_filename; mutually exclusive with implementation_plan.',
+            },
+            implementation_plan_filename: {
+              type: 'string',
+              description:
+                'Basename-only filename (no separators, no \'..\') used when materializing implementation_plan_content into <state_dir>/plans/.',
+            },
+            phases: {
+              type: 'array',
+              minItems: 1,
+              items: PHASE_ITEM_SCHEMA,
+            },
+            task_complexity: {
+              type: 'string',
+              enum: ['simple', 'medium', 'complex'],
+            },
+            execution_mode: { type: 'string' },
+            workflow_mode: {
+              type: 'string',
+              enum: ['express', 'standard'],
+              default: 'standard',
+            },
+          },
+          required: ['session_id', 'task', 'phases'],
+        },
+      },
+      {
+        name: 'get_session_status',
+        description:
+          'Read current session status including workflow_mode. Returns { exists: false } if no active session, or { exists: true, ...status } if one exists.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+          },
+        },
+      },
+      {
+        name: 'update_session',
+        description:
+          'Update session metadata fields (execution_mode, current_batch) after session creation. Use after execution-mode gate resolves.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+            execution_mode: {
+              type: 'string',
+              enum: ['parallel', 'sequential'],
+            },
+            execution_backend: { type: 'string' },
+            current_batch: { type: ['string', 'null'] },
+          },
+          required: ['session_id'],
+        },
+      },
+      {
+        name: 'transition_phase',
+        description:
+          'Atomically mark a phase completed and start the next phase(s). Supports single or batch transitions.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+            completed_phase_id: { type: ['number', 'string'] },
+            downstream_context: { type: 'object' },
+            files_created: { type: 'array' },
+            files_modified: { type: 'array' },
+            files_deleted: { type: 'array' },
+            next_phase_id: { type: ['number', 'string', 'null'] },
+            next_phase_ids: {
+              type: 'array',
+              items: { type: ['number', 'string'] },
+              description:
+                'Start multiple phases (parallel batch). Mutually exclusive with next_phase_id.',
+            },
+            batch_id: {
+              type: ['string', 'null'],
+              description:
+                'Batch identifier for parallel dispatch. Sets current_batch in state.',
+            },
+            token_usage: { type: 'object' },
+          },
+          required: ['session_id'],
+        },
+      },
+      {
+        name: 'archive_session',
+        description:
+          'Move active session to archive. Also moves associated design document and implementation plan to plans/archive/ if they exist.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+          },
+          required: ['session_id'],
+        },
+      },
+      {
+        name: 'enter_design_gate',
+        description:
+          'Mark a session as having entered the design phase. Idempotent. Blocks create_session until record_design_approval is called.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: { session_id: { type: 'string' } },
+          required: ['session_id'],
+        },
+      },
+      {
+        name: 'record_design_approval',
+        description:
+          'Record user approval of the design document, clearing the design gate for session creation. Supply the document either by path (design_document_path) or by inline content (design_document_content + design_document_filename); exactly one variant is required. Use the content variant when the caller cannot guarantee the file is visible to the MCP server under the configured workspace (e.g. Gemini Plan Mode resolves relative paths against ~/.gemini/tmp/<uuid>/).',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+            design_document_path: {
+              type: 'string',
+              description:
+                'Absolute or workspace-relative path to the approved design document. Mutually exclusive with design_document_content.',
+            },
+            design_document_content: {
+              type: 'string',
+              description:
+                'Inline design-document Markdown. Requires design_document_filename; mutually exclusive with design_document_path.',
+            },
+            design_document_filename: {
+              type: 'string',
+              description:
+                'Basename-only filename (no separators, no \'..\') used when materializing design_document_content into <state_dir>/plans/.',
+            },
+          },
+          required: ['session_id'],
+        },
+      },
+      {
+        name: 'get_design_gate_status',
+        description:
+          'Read the design gate status for a session. Returns entered_at, approved_at, and design_document_path (all nullable).',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: { session_id: { type: 'string' } },
+          required: ['session_id'],
+        },
+      },
+      {
+        name: 'scan_phase_changes',
+        description:
+          'Scan the workspace for files created or modified since the phase started. Does not attribute files — returns candidates for the orchestrator to reconcile.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+            phase_id: { type: ['integer', 'string'] },
+          },
+          required: ['session_id', 'phase_id'],
+        },
+      },
+      {
+        name: 'reconcile_phase',
+        description:
+          'Record file manifests and downstream context for a phase that could not be handed off cleanly. Requires at least one of files_created/files_modified/files_deleted or a populated downstream_context. Clears requires_reconciliation on success.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            session_id: { type: 'string' },
+            phase_id: { type: ['integer', 'string'] },
+            files_created: { type: 'array' },
+            files_modified: { type: 'array' },
+            files_deleted: { type: 'array' },
+            downstream_context: { type: 'object' },
+            reason: { type: 'string' },
+          },
+          required: ['session_id', 'phase_id'],
+        },
+      },
+    ],
+    handlers: {
+      create_session: handleCreateSession,
+      get_session_status: handleGetSessionStatus,
+      update_session: handleUpdateSession,
+      transition_phase: handleTransitionPhase,
+      archive_session: handleArchiveSession,
+      enter_design_gate: handleEnterDesignGate,
+      record_design_approval: handleRecordDesignApproval,
+      get_design_gate_status: handleGetDesignGateStatus,
+      scan_phase_changes: handleScanPhaseChanges,
+      reconcile_phase: handleReconcilePhase,
+    },
+  });
+}
+
+module.exports = {
+  createToolPack,
+};

package/claude/src/mcp/tool-packs/workspace/index.js

@@ -0,0 +1,98 @@
+'use strict';
+
+const { defineToolPack } = require('../contracts');
+const {
+  handleInitializeWorkspace,
+} = require('../../handlers/initialize-workspace');
+const {
+  handleAssessTaskComplexity,
+} = require('../../handlers/assess-task-complexity');
+const { handleValidatePlan } = require('../../handlers/validate-plan');
+const { handleResolveSettings } = require('../../handlers/resolve-settings');
+
+function createToolPack() {
+  return defineToolPack({
+    name: 'workspace',
+    tools: [
+      {
+        name: 'initialize_workspace',
+        description:
+          'Initialize Maestro workspace directories (state, plans, archives). Requires explicit workspace_path — no cwd or env fallback. Writes a workspace marker for session persistence.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            workspace_path: {
+              type: 'string',
+              description:
+                'Absolute path to the user workspace. Required. Must not be inside an extension cache directory.',
+            },
+            state_dir: {
+              type: 'string',
+              description:
+                'State directory relative to workspace_path. Defaults to docs/maestro.',
+            },
+          },
+          required: ['workspace_path'],
+        },
+      },
+      {
+        name: 'assess_task_complexity',
+        description:
+          'Analyze repo structure and return factual signals for complexity classification. Does NOT classify — returns signals for the model to interpret.',
+        requiresWorkspace: true,
+        inputSchema: {
+          type: 'object',
+          properties: {
+            task_description: {
+              type: 'string',
+              description:
+                'The task description (reserved for future keyword analysis).',
+            },
+          },
+        },
+      },
+      {
+        name: 'validate_plan',
+        description:
+          'Validate an implementation plan against complexity constraints, file ownership, dependency cycles, and agent registry.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            plan: { type: 'object' },
+            task_complexity: {
+              type: 'string',
+              enum: ['simple', 'medium', 'complex'],
+            },
+          },
+          required: ['plan', 'task_complexity'],
+        },
+      },
+      {
+        name: 'resolve_settings',
+        description:
+          'Resolve Maestro settings using script-accurate precedence (env var > workspace .env > extension .env). Returns resolved values for requested or all known settings.',
+        inputSchema: {
+          type: 'object',
+          properties: {
+            settings: {
+              type: 'array',
+              items: { type: 'string' },
+              description:
+                'Setting names to resolve (e.g., ["MAESTRO_DISABLED_AGENTS"]). If empty or omitted, resolves all known settings.',
+            },
+          },
+        },
+      },
+    ],
+    handlers: {
+      initialize_workspace: handleInitializeWorkspace,
+      assess_task_complexity: handleAssessTaskComplexity,
+      validate_plan: handleValidatePlan,
+      resolve_settings: handleResolveSettings,
+    },
+  });
+}
+
+module.exports = {
+  createToolPack,
+};

package/claude/src/mcp/utils/extension-root.js

@@ -0,0 +1,31 @@
+'use strict';
+
+const path = require('path');
+const { resolveCanonicalProjectRoot, resolveCanonicalSrcRoot } = require('../../core/canonical-source');
+
+function resolveExtensionRoot() {
+  if (process.env.MAESTRO_EXTENSION_PATH) {
+    return process.env.MAESTRO_EXTENSION_PATH;
+  }
+
+  const serverFile = process.argv[1];
+  if (serverFile) {
+    return path.resolve(path.dirname(serverFile), '..');
+  }
+
+  return process.cwd();
+}
+
+function resolveRepoRoot() {
+  return resolveCanonicalProjectRoot(resolveExtensionRoot());
+}
+
+function resolveCanonicalSrcFromExtensionRoot() {
+  return resolveCanonicalSrcRoot(resolveExtensionRoot());
+}
+
+module.exports = {
+  resolveCanonicalSrcFromExtensionRoot,
+  resolveExtensionRoot,
+  resolveRepoRoot,
+};