@josstei/maestro 1.6.4-rc.1

package/src/mcp/contracts/plan-schema.js

@@ -0,0 +1,148 @@
+'use strict';
+
+const PHASE_REQUIRED_FIELDS = ['id', 'name', 'agent', 'parallel', 'blocked_by'];
+
+const PHASE_ID_SCHEMA = {
+  oneOf: [
+    { type: 'integer', minimum: 1 },
+    { type: 'string', minLength: 1 },
+  ],
+};
+
+const PHASE_ITEM_SCHEMA = {
+  type: 'object',
+  properties: {
+    id: PHASE_ID_SCHEMA,
+    name: { type: 'string', minLength: 1 },
+    agent: { type: 'string', minLength: 1 },
+    parallel: { type: 'boolean' },
+    blocked_by: { type: 'array', items: PHASE_ID_SCHEMA },
+    files: { type: 'array', items: { type: 'string', minLength: 1 } },
+  },
+  required: PHASE_REQUIRED_FIELDS,
+  additionalProperties: true,
+};
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.length > 0;
+}
+
+function isValidPhaseId(value) {
+  if (typeof value === 'string') return value.length > 0;
+  return Number.isInteger(value) && value >= 1;
+}
+
+function isValidBlockerId(value) {
+  if (typeof value === 'string') return value.length > 0;
+  return Number.isInteger(value) && value >= 1;
+}
+
+/**
+ * Validate an array of plan-phase objects against the shared phase schema.
+ *
+ * Required fields per phase: id, name, agent, parallel, blocked_by.
+ *
+ * Optional field: `files` — the planning-time file manifest. When supplied,
+ * T9 `create_session` maps it to the session state's `planned_files` field
+ * for later reconciliation. The runtime-populated manifests
+ * (`files_created`, `files_modified`, `files_deleted`) are NOT plan inputs;
+ * they are set by `transition_phase` after an agent completes, and they
+ * pass through this schema via `additionalProperties: true` without
+ * validation. Plan authors should populate `files`, not the runtime fields.
+ *
+ * @param {unknown} phases - Input value expected to be an array of phase objects.
+ * @returns {{ valid: boolean, violations: Array<object> }}
+ */
+function validatePhases(phases) {
+  const violations = [];
+  if (!Array.isArray(phases)) {
+    return {
+      valid: false,
+      violations: [
+        { rule: 'invalid_phases', detail: 'phases must be an array', severity: 'error' },
+      ],
+    };
+  }
+
+  for (const phase of phases) {
+    const phaseId = phase && phase.id;
+    for (const field of PHASE_REQUIRED_FIELDS) {
+      if (!phase || !Object.prototype.hasOwnProperty.call(phase, field)) {
+        violations.push({
+          rule: 'missing_required_field',
+          phase_id: phaseId ?? null,
+          field,
+          severity: 'error',
+        });
+      }
+    }
+
+    if (!phase) continue;
+
+    if ('id' in phase && !isValidPhaseId(phase.id)) {
+      violations.push({
+        rule: 'invalid_field_type',
+        phase_id: phaseId ?? null,
+        field: 'id',
+        severity: 'error',
+      });
+    }
+    if ('name' in phase && !isNonEmptyString(phase.name)) {
+      violations.push({
+        rule: 'invalid_field_type',
+        phase_id: phaseId ?? null,
+        field: 'name',
+        severity: 'error',
+      });
+    }
+    if ('agent' in phase && !isNonEmptyString(phase.agent)) {
+      violations.push({
+        rule: 'invalid_field_type',
+        phase_id: phaseId ?? null,
+        field: 'agent',
+        severity: 'error',
+      });
+    }
+    if ('parallel' in phase && typeof phase.parallel !== 'boolean') {
+      violations.push({
+        rule: 'invalid_field_type',
+        phase_id: phaseId ?? null,
+        field: 'parallel',
+        severity: 'error',
+      });
+    }
+    if ('blocked_by' in phase) {
+      if (
+        !Array.isArray(phase.blocked_by) ||
+        !phase.blocked_by.every(isValidBlockerId)
+      ) {
+        violations.push({
+          rule: 'invalid_field_type',
+          phase_id: phaseId ?? null,
+          field: 'blocked_by',
+          severity: 'error',
+        });
+      }
+    }
+    if ('files' in phase) {
+      if (!Array.isArray(phase.files) || !phase.files.every(isNonEmptyString)) {
+        violations.push({
+          rule: 'invalid_field_value',
+          phase_id: phaseId ?? null,
+          field: 'files',
+          severity: 'error',
+        });
+      }
+    }
+  }
+
+  return { valid: violations.length === 0, violations };
+}
+
+module.exports = {
+  PHASE_ID_SCHEMA,
+  PHASE_ITEM_SCHEMA,
+  PHASE_REQUIRED_FIELDS,
+  isValidPhaseId,
+  validatePhases,
+};

package/src/mcp/contracts/workspace-marker.js

@@ -0,0 +1,61 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const MARKER_FILENAME = '.workspace-root';
+const SCHEMA_VERSION = 1;
+
+function markerPathFor(stateDir) {
+  return path.join(stateDir, MARKER_FILENAME);
+}
+
+/**
+ * Reads and validates the workspace marker file from the given state directory.
+ *
+ * Returns null when the file is absent, contains malformed JSON, or was written
+ * by an incompatible schema version.
+ *
+ * @param {string} stateDir - Absolute path to the Maestro state directory.
+ * @returns {{ workspace_path: string, written_at: string, schema_version: number } | null}
+ */
+function readWorkspaceMarker(stateDir) {
+  const markerPath = markerPathFor(stateDir);
+  if (!fs.existsSync(markerPath)) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+    if (
+      !parsed ||
+      typeof parsed.workspace_path !== 'string' ||
+      parsed.schema_version !== SCHEMA_VERSION
+    ) {
+      return null;
+    }
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Writes a workspace marker file into the given state directory.
+ *
+ * Creates the state directory if it does not already exist.
+ *
+ * @param {string} stateDir - Absolute path to the Maestro state directory.
+ * @param {string} workspacePath - Absolute path to the resolved workspace root.
+ * @returns {void}
+ */
+function writeWorkspaceMarker(stateDir, workspacePath) {
+  const payload = {
+    workspace_path: workspacePath,
+    written_at: new Date().toISOString(),
+    schema_version: SCHEMA_VERSION,
+  };
+  fs.mkdirSync(stateDir, { recursive: true });
+  fs.writeFileSync(markerPathFor(stateDir), JSON.stringify(payload, null, 2));
+}
+
+module.exports = { MARKER_FILENAME, SCHEMA_VERSION, readWorkspaceMarker, writeWorkspaceMarker };

package/src/mcp/core/create-server.js

@@ -0,0 +1,76 @@
+'use strict';
+
+const { createToolRegistry } = require('./tool-registry');
+const {
+  createToolSuccess,
+  createUnknownToolFailure,
+  normalizeToolError,
+  sanitizeErrorMessage,
+} = require('./tool-outcome');
+const { requireWorkspaceRoot } = require('../../core/project-root-resolver');
+
+function createServer(options = {}) {
+  const { runtimeConfig = {}, services = {} } = options;
+  const registry = createToolRegistry({
+    runtimeConfig,
+    services,
+    toolPacks: options.toolPacks,
+  });
+
+  const postCallHandlers = new Map();
+
+  function invokePostCall(name, outcome, args) {
+    const handler = postCallHandlers.get(name);
+    if (typeof handler === 'function') {
+      try {
+        handler(outcome, args);
+      } catch {
+        // Post-call handlers must not mask tool results.
+      }
+    }
+  }
+
+  return {
+    runtimeConfig,
+    services,
+    toolPacks: registry.toolPacks,
+    schemas: registry.schemas,
+    handlers: registry.handlers,
+    metadata: registry.metadata,
+    getToolSchemas() {
+      return registry.schemas.slice();
+    },
+    getToolHandler(name) {
+      return registry.handlers[name];
+    },
+    getToolMetadata(name) {
+      return registry.metadata[name] || null;
+    },
+    onToolCall(name, handler) {
+      postCallHandlers.set(name, handler);
+    },
+    async callTool(name, args = {}, projectRoot) {
+      const handler = registry.handlers[name];
+      if (!handler) {
+        return createUnknownToolFailure(name);
+      }
+      const meta = registry.metadata[name];
+      try {
+        if (meta && meta.requiresWorkspace) {
+          requireWorkspaceRoot(projectRoot, name);
+        }
+        const result = await handler(args, projectRoot);
+        const outcome = createToolSuccess(result);
+        invokePostCall(name, result, args);
+        return outcome;
+      } catch (error) {
+        return normalizeToolError(name, error);
+      }
+    },
+  };
+}
+
+module.exports = {
+  createServer,
+  sanitizeErrorMessage,
+};

package/src/mcp/core/line-reader.js

@@ -0,0 +1,35 @@
+'use strict';
+
+const readline = require('node:readline');
+
+const { log } = require('../../core/logger');
+
+/**
+ * Create a readline-based line dispatcher for a stdin stream.
+ * Each non-empty JSON line is parsed and forwarded to `onMessage`.
+ * Parse errors are logged and dropped; the reader keeps running.
+ */
+function createLineDispatcher(stdin, onMessage) {
+  const lineReader = readline.createInterface({
+    input: stdin,
+    crlfDelay: Infinity,
+  });
+
+  lineReader.on('line', (line) => {
+    if (!line.trim()) {
+      return;
+    }
+
+    try {
+      onMessage(JSON.parse(line));
+    } catch (error) {
+      log('error', `Failed to parse MCP message: ${error.message}`);
+    }
+  });
+
+  return lineReader;
+}
+
+module.exports = {
+  createLineDispatcher,
+};

package/src/mcp/core/project-root-cache.js

@@ -0,0 +1,120 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { pathToFileURL, fileURLToPath } = require('node:url');
+
+const { isExtensionCachePath } = require('../contracts/cache-path-rejector');
+
+/**
+ * Project-root cache for the MCP session.
+ *
+ * After this refactor, the workspace path is authoritative only when the
+ * orchestrator has passed it to `initialize_workspace`. Before that call,
+ * stateful tools reject with a structured error.
+ *
+ * The cache also computes a `workspace_suggestion` from the env var declared
+ * by the runtime-config, any MCP roots supplied by the client, and the
+ * runtime's cwd. The suggestion is exposed through `get_runtime_context` so
+ * the orchestrator can pass it into `initialize_workspace`. It is never
+ * used as a fallback for other tools.
+ */
+function createProjectRootCache(options) {
+  const {
+    runtimeConfig,
+    requestClientRoots,
+    env = process.env,
+    getCwd = () => process.cwd(),
+  } = options;
+
+  let explicitWorkspacePath = null;
+  let clientRoots = [];
+  let clientSupportsRoots = false;
+
+  function envSuggestion() {
+    const envVarName =
+      runtimeConfig && runtimeConfig.env ? runtimeConfig.env.workspacePath : null;
+    if (!envVarName) return null;
+    const value = env[envVarName];
+    if (!value || value.includes('${')) return null;
+    const resolved = path.resolve(value);
+    if (!fs.existsSync(resolved)) return null;
+    if (isExtensionCachePath(resolved)) return null;
+    return resolved;
+  }
+
+  function rootsSuggestion() {
+    for (const root of clientRoots) {
+      const uri = typeof root === 'string' ? root : root && root.uri;
+      if (typeof uri !== 'string') continue;
+      try {
+        const parsed = new URL(uri);
+        if (parsed.protocol !== 'file:') continue;
+        const resolved = fileURLToPath(parsed);
+        if (!fs.existsSync(resolved)) continue;
+        if (isExtensionCachePath(resolved)) continue;
+        return resolved;
+      } catch {
+        continue;
+      }
+    }
+    return null;
+  }
+
+  function cwdSuggestion() {
+    const cwd = path.resolve(getCwd());
+    if (isExtensionCachePath(cwd)) return null;
+    return cwd;
+  }
+
+  async function refreshClientRoots() {
+    if (!clientSupportsRoots || typeof requestClientRoots !== 'function') {
+      clientRoots = [];
+      return clientRoots;
+    }
+    try {
+      const result = await requestClientRoots();
+      clientRoots = result && Array.isArray(result.roots) ? result.roots : [];
+    } catch {
+      clientRoots = [];
+    }
+    return clientRoots;
+  }
+
+  function workspaceSuggestion() {
+    return envSuggestion() || rootsSuggestion() || cwdSuggestion();
+  }
+
+  function setExplicitWorkspacePath(value) {
+    explicitWorkspacePath = value || null;
+  }
+
+  async function getProjectRoot() {
+    if (!explicitWorkspacePath) {
+      const error = new Error(
+        'Workspace not initialized. Call initialize_workspace(workspace_path=...) before any stateful tool.'
+      );
+      error.code = 'WORKSPACE_NOT_INITIALIZED';
+      throw error;
+    }
+    return explicitWorkspacePath;
+  }
+
+  return {
+    getProjectRoot,
+    setExplicitWorkspacePath,
+    workspaceSuggestion,
+    setClientSupportsRoots(supports) {
+      clientSupportsRoots = Boolean(supports);
+    },
+    refreshClientRoots,
+    invalidateProjectRoot() {
+      explicitWorkspacePath = null;
+    },
+    invalidateClientRoots() {
+      clientRoots = [];
+    },
+  };
+}
+
+module.exports = { createProjectRootCache };

package/src/mcp/core/protocol-dispatcher.js

@@ -0,0 +1,274 @@
+'use strict';
+
+const { log } = require('../../core/logger');
+
+const DEFAULT_PROTOCOL_VERSION = '2025-03-26';
+const DEFAULT_CLIENT_REQUEST_TIMEOUT_MS = 5000;
+
+function writeMessage(output, message) {
+  output.write(JSON.stringify(message) + '\n');
+}
+
+function buildInitializeResult(protocolVersion, serverInfo) {
+  return {
+    protocolVersion: protocolVersion || DEFAULT_PROTOCOL_VERSION,
+    capabilities: {
+      tools: {},
+    },
+    serverInfo,
+  };
+}
+
+function createToolErrorResult(errorOrOutcome, recoveryHint) {
+  const outcome =
+    errorOrOutcome &&
+    typeof errorOrOutcome === 'object' &&
+    !Array.isArray(errorOrOutcome) &&
+    Object.prototype.hasOwnProperty.call(errorOrOutcome, 'error')
+      ? errorOrOutcome
+      : { error: errorOrOutcome, recovery_hint: recoveryHint };
+
+  const payload = {
+    error: outcome.error,
+    recovery_hint: outcome.recovery_hint ?? null,
+  };
+
+  if (outcome.code) {
+    payload.code = outcome.code;
+  }
+
+  if (outcome.details !== undefined) {
+    payload.details = outcome.details;
+  }
+
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(payload),
+      },
+    ],
+    isError: true,
+  };
+}
+
+function createToolSuccessResult(result) {
+  return {
+    content: [
+      {
+        type: 'text',
+        text: JSON.stringify(result),
+      },
+    ],
+  };
+}
+
+/**
+ * Create a JSON-RPC 2.0 dispatcher for the MCP wire protocol.
+ *
+ * Handles `initialize`, `tools/list`, `tools/call`, `ping`, notification
+ * methods, and outbound server-to-client requests (via `requestFromClient`).
+ * Unknown methods get a -32601 response.
+ *
+ * @returns {{
+ *   requestFromClient: (method: string, params?: object) => Promise<any>,
+ *   respond: (message: object) => Promise<void>
+ * }}
+ */
+function createProtocolHandlers(server, getProjectRoot, stdout, options = {}) {
+  const {
+    serverInfo,
+    callbacks = {},
+    clientRequestTimeoutMs = DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
+  } = options;
+
+  const pendingClientRequests = new Map();
+  let nextClientRequestId = 1;
+
+  function settleClientRequest(message) {
+    if (!message || message.id == null) {
+      return false;
+    }
+
+    const entry = pendingClientRequests.get(message.id);
+    if (!entry) {
+      return false;
+    }
+
+    pendingClientRequests.delete(message.id);
+    clearTimeout(entry.timeout);
+
+    if (message.error) {
+      entry.reject(new Error(message.error.message || JSON.stringify(message.error)));
+      return true;
+    }
+
+    entry.resolve(message.result);
+    return true;
+  }
+
+  function requestFromClient(method, params = {}) {
+    return new Promise((resolve, reject) => {
+      const id = `server-${nextClientRequestId++}`;
+      const timeout = setTimeout(() => {
+        pendingClientRequests.delete(id);
+        reject(new Error(`Timed out waiting for client response to ${method}`));
+      }, clientRequestTimeoutMs);
+
+      pendingClientRequests.set(id, { resolve, reject, timeout });
+      writeMessage(stdout, {
+        jsonrpc: '2.0',
+        id,
+        method,
+        params,
+      });
+    });
+  }
+
+  async function respond(message) {
+    if (!message || typeof message !== 'object') {
+      return;
+    }
+
+    if (settleClientRequest(message)) {
+      return;
+    }
+
+    if (typeof message.method !== 'string') {
+      return;
+    }
+
+    if (message.method === 'initialize') {
+      if (typeof callbacks.onInitialize === 'function') {
+        await Promise.resolve(callbacks.onInitialize(message.params || {}));
+      }
+
+      writeMessage(stdout, {
+        jsonrpc: '2.0',
+        id: message.id,
+        result: buildInitializeResult(
+          message.params && message.params.protocolVersion,
+          serverInfo
+        ),
+      });
+      return;
+    }
+
+    if (message.method === 'notifications/initialized') {
+      if (typeof callbacks.onInitialized === 'function') {
+        await Promise.resolve(callbacks.onInitialized());
+      }
+      return;
+    }
+
+    if (message.method === 'notifications/roots/list_changed') {
+      if (typeof callbacks.onRootsListChanged === 'function') {
+        await Promise.resolve(callbacks.onRootsListChanged());
+      }
+      return;
+    }
+
+    if (
+      message.method === 'notifications/cancelled' ||
+      message.method === '$/cancelRequest'
+    ) {
+      return;
+    }
+
+    if (message.method === 'ping') {
+      writeMessage(stdout, {
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {},
+      });
+      return;
+    }
+
+    if (message.method === 'tools/list') {
+      writeMessage(stdout, {
+        jsonrpc: '2.0',
+        id: message.id,
+        result: {
+          tools: server.getToolSchemas(),
+        },
+      });
+      return;
+    }
+
+    if (message.method === 'tools/call') {
+      const name = message.params && message.params.name;
+      const args =
+        message.params && message.params.arguments && typeof message.params.arguments === 'object'
+          ? message.params.arguments
+          : {};
+      let projectRoot = null;
+      try {
+        projectRoot = await getProjectRoot();
+      } catch (error) {
+        if (error && error.code !== 'WORKSPACE_NOT_INITIALIZED') {
+          log(
+            'warn',
+            `getProjectRoot failed unexpectedly while handling ${name || '(unknown)'}: ${error.message}`
+          );
+        }
+        projectRoot = null;
+      }
+      const outcome = await server.callTool(name, args, projectRoot);
+
+      if (outcome.ok) {
+        writeMessage(stdout, {
+          jsonrpc: '2.0',
+          id: message.id,
+          result: createToolSuccessResult(outcome.result),
+        });
+        return;
+      }
+
+      log('error', `Tool ${name || '(unknown)'} failed: ${outcome.error}`);
+      writeMessage(stdout, {
+        jsonrpc: '2.0',
+        id: message.id,
+        result: createToolErrorResult(outcome),
+      });
+      return;
+    }
+
+    if (message.id == null) {
+      return;
+    }
+
+    writeMessage(stdout, {
+      jsonrpc: '2.0',
+      id: message.id,
+      error: {
+        code: -32601,
+        message: `Method not found: ${message.method}`,
+      },
+    });
+  }
+
+  /**
+   * Clear all pending outbound client-request timeouts and reject their
+   * promises. Call during server shutdown so Node can exit promptly and
+   * callers do not receive late timeout rejections.
+   */
+  function drain() {
+    for (const [id, entry] of pendingClientRequests) {
+      clearTimeout(entry.timeout);
+      entry.reject(new Error(`MCP server closing; request ${id} aborted`));
+    }
+    pendingClientRequests.clear();
+  }
+
+  return { requestFromClient, respond, drain };
+}
+
+module.exports = {
+  DEFAULT_PROTOCOL_VERSION,
+  DEFAULT_CLIENT_REQUEST_TIMEOUT_MS,
+  writeMessage,
+  buildInitializeResult,
+  createToolErrorResult,
+  createToolSuccessResult,
+  createProtocolHandlers,
+};