@josstei/maestro 1.6.4-rc.1

package/src/mcp/core/recovery-hints.js

@@ -0,0 +1,43 @@
+'use strict';
+
+const RECOVERY_TABLE = [
+  {
+    tool: 'create_session',
+    pattern: /already exists/i,
+    hint: 'Call get_session_status to check the current session, then archive_session if you want to start fresh.',
+  },
+  {
+    tool: 'transition_phase',
+    pattern: /not found/i,
+    hint: 'Call get_session_status to verify the current session and phase IDs.',
+  },
+  {
+    tool: 'archive_session',
+    pattern: /no active session/i,
+    hint: 'Call get_session_status first to verify a session exists.',
+  },
+  {
+    tool: 'update_session',
+    pattern: /no active session|ENOENT/i,
+    hint: 'Call get_session_status to verify a session exists before updating.',
+  },
+  {
+    tool: 'update_session',
+    pattern: /updatable field/i,
+    hint: 'Provide at least one of: execution_mode, execution_backend, current_batch.',
+  },
+  {
+    tool: 'initialize_workspace',
+    pattern: /permission|EACCES|EPERM/i,
+    hint: 'Check that the target directory is writable.',
+  },
+];
+
+function getRecoveryHint(toolName, errorMessage) {
+  const row = RECOVERY_TABLE.find((r) => r.tool === toolName && r.pattern.test(errorMessage));
+  return row ? row.hint : null;
+}
+
+module.exports = {
+  getRecoveryHint,
+};

package/src/mcp/core/tool-outcome.js

@@ -0,0 +1,77 @@
+'use strict';
+
+const { getRecoveryHint } = require('./recovery-hints');
+const { MaestroError } = require('../../lib/errors');
+
+const UNKNOWN_TOOL_CODE = 'UNKNOWN_TOOL';
+const INTERNAL_TOOL_ERROR_CODE = 'INTERNAL_TOOL_ERROR';
+
+function sanitizeErrorMessage(error) {
+  const message = error && error.message ? error.message : String(error);
+  return message.replace(/\/[^\s'"]+/g, '[path]');
+}
+
+function createToolSuccess(result) {
+  return {
+    ok: true,
+    result,
+  };
+}
+
+function createToolFailure({
+  error,
+  code = null,
+  recovery_hint = null,
+  details = undefined,
+}) {
+  const outcome = {
+    ok: false,
+    error,
+    recovery_hint,
+  };
+
+  if (code) {
+    outcome.code = code;
+  }
+
+  if (details !== undefined && details !== null) {
+    outcome.details = details;
+  }
+
+  return outcome;
+}
+
+function createUnknownToolFailure(name) {
+  return createToolFailure({
+    error: `Unknown tool: ${name}`,
+    code: UNKNOWN_TOOL_CODE,
+  });
+}
+
+function normalizeToolError(toolName, error) {
+  if (error instanceof MaestroError) {
+    return createToolFailure({
+      error: error.message,
+      code: error.code,
+      recovery_hint: getRecoveryHint(toolName, error.message),
+      details: error.details,
+    });
+  }
+
+  const sanitized = sanitizeErrorMessage(error);
+  return createToolFailure({
+    error: sanitized,
+    code: INTERNAL_TOOL_ERROR_CODE,
+    recovery_hint: getRecoveryHint(toolName, sanitized),
+  });
+}
+
+module.exports = {
+  INTERNAL_TOOL_ERROR_CODE,
+  UNKNOWN_TOOL_CODE,
+  createToolFailure,
+  createToolSuccess,
+  createUnknownToolFailure,
+  normalizeToolError,
+  sanitizeErrorMessage,
+};

package/src/mcp/core/tool-registry.js

@@ -0,0 +1,82 @@
+'use strict';
+
+const {
+  createCompositionContext,
+} = require('../tool-packs/contracts');
+
+function normalizeToolPack(entry, context, index) {
+  let pack = entry;
+
+  if (pack && typeof pack.createToolPack === 'function') {
+    pack = pack.createToolPack(context);
+  } else if (typeof pack === 'function') {
+    pack = pack(context);
+  }
+
+  if (!pack || typeof pack !== 'object' || Array.isArray(pack)) {
+    throw new TypeError(`Tool pack at index ${index} must resolve to an object.`);
+  }
+
+  return {
+    name: pack.name || `tool-pack-${index + 1}`,
+    tools: Array.isArray(pack.tools) ? pack.tools : [],
+    handlers: pack.handlers && typeof pack.handlers === 'object' ? pack.handlers : {},
+  };
+}
+
+function createToolRegistry(options = {}) {
+  const context = createCompositionContext(options);
+  const rawToolPacks = Array.isArray(options.toolPacks) ? options.toolPacks : [];
+  const toolPacks = rawToolPacks.map((entry, index) =>
+    normalizeToolPack(entry, context, index)
+  );
+  const schemas = [];
+  const handlers = Object.create(null);
+  const toolSources = Object.create(null);
+  const metadata = Object.create(null);
+
+  for (const pack of toolPacks) {
+    for (const schema of pack.tools) {
+      if (!schema || typeof schema !== 'object' || Array.isArray(schema)) {
+        throw new TypeError(`Tool schema in pack "${pack.name}" must be an object.`);
+      }
+
+      if (typeof schema.name !== 'string' || schema.name.length === 0) {
+        throw new Error(`Tool schema in pack "${pack.name}" is missing a valid name.`);
+      }
+
+      if (toolSources[schema.name]) {
+        throw new Error(
+          `Duplicate tool name "${schema.name}" found in packs "${toolSources[schema.name]}" and "${pack.name}".`
+        );
+      }
+
+      const handler = pack.handlers[schema.name];
+      if (typeof handler !== 'function') {
+        throw new Error(
+          `Tool "${schema.name}" in pack "${pack.name}" is missing a handler.`
+        );
+      }
+
+      toolSources[schema.name] = pack.name;
+      schemas.push(schema);
+      handlers[schema.name] = handler;
+      metadata[schema.name] = {
+        requiresWorkspace: schema.requiresWorkspace === true,
+      };
+    }
+  }
+
+  return {
+    context,
+    toolPacks,
+    schemas,
+    handlers,
+    metadata,
+  };
+}
+
+module.exports = {
+  createToolRegistry,
+  normalizeToolPack,
+};

package/src/mcp/handlers/assess-task-complexity.js

@@ -0,0 +1,108 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { CONFIG_FILES, SKIP_DIRS, FRAMEWORK_INDICATORS } = require('../../lib/framework-detection');
+
+function countFiles(directory, depth, depthLimit) {
+  if (depth > depthLimit) {
+    return { count: 0, deepestLevel: depth };
+  }
+
+  let count = 0;
+  let deepestLevel = depth;
+
+  try {
+    const entries = fs.readdirSync(directory, { withFileTypes: true });
+
+    for (const entry of entries) {
+      if (SKIP_DIRS.has(entry.name)) {
+        continue;
+      }
+
+      if (entry.isFile()) {
+        count += 1;
+        continue;
+      }
+
+      if (entry.isDirectory()) {
+        const nested = countFiles(
+          path.join(directory, entry.name),
+          depth + 1,
+          depthLimit
+        );
+        count += nested.count;
+        deepestLevel = Math.max(deepestLevel, nested.deepestLevel);
+      }
+    }
+  } catch {}
+
+  return { count, deepestLevel };
+}
+
+function detectFrameworks(directory) {
+  const packagePath = path.join(directory, 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return [];
+  }
+
+  try {
+    const pkg = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+    const allDependencies = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+    };
+
+    return Object.entries(FRAMEWORK_INDICATORS)
+      .filter(([, indicators]) =>
+        indicators.some((indicator) => indicator in allDependencies)
+      )
+      .map(([name]) => name);
+  } catch {
+    return [];
+  }
+}
+
+function estimateSize(fileCount) {
+  if (fileCount === 0) {
+    return 'empty';
+  }
+
+  if (fileCount <= 20) {
+    return 'small';
+  }
+
+  if (fileCount <= 200) {
+    return 'medium';
+  }
+
+  return 'large';
+}
+
+function handleAssessTaskComplexity(_params, projectRoot) {
+  const { count: fileCount, deepestLevel } = countFiles(projectRoot, 0, 10);
+  const configFiles = CONFIG_FILES.filter((file) =>
+    fs.existsSync(path.join(projectRoot, file))
+  );
+
+  return {
+    file_count: fileCount,
+    directory_depth: deepestLevel,
+    has_package_json: fs.existsSync(path.join(projectRoot, 'package.json')),
+    has_config_files: configFiles,
+    frameworks_detected: detectFrameworks(projectRoot),
+    existing_test_infrastructure:
+      fs.existsSync(path.join(projectRoot, 'tests')) ||
+      fs.existsSync(path.join(projectRoot, '__tests__')) ||
+      fs.existsSync(path.join(projectRoot, 'test')),
+    lines_of_code_estimate:
+      fileCount <= 20 ? 'low' : fileCount <= 200 ? 'moderate' : 'high',
+    repo_is_empty: fileCount === 0,
+    repo_size_estimate: estimateSize(fileCount),
+  };
+}
+
+module.exports = {
+  handleAssessTaskComplexity,
+};

package/src/mcp/handlers/blocker-parser.js

@@ -0,0 +1,34 @@
+'use strict';
+
+/**
+ * @param {string} text - Full text of an agent Task Report.
+ * @returns {{ question: string, context: string, required: string }[]}
+ */
+function parseBlockers(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+
+  const sectionMatch = text.match(/^#{1,6}\s+Blockers\s*$/im);
+  if (!sectionMatch) return [];
+
+  const sectionStart = sectionMatch.index + sectionMatch[0].length;
+  const rest = text.slice(sectionStart);
+  const nextSectionMatch = rest.match(/^#{1,6}\s+\w/im);
+  const sectionBody = nextSectionMatch
+    ? rest.slice(0, nextSectionMatch.index)
+    : rest;
+
+  const blockers = [];
+  const blockerRe =
+    /-\s*BLOCKER:\s*(.+?)\n\s+Context:\s*(.+?)\n\s+Required to proceed:\s*(.+?)(?=\n-\s*BLOCKER:|\n\s*$|$)/gis;
+  let match;
+  while ((match = blockerRe.exec(sectionBody)) !== null) {
+    blockers.push({
+      question: match[1].trim(),
+      context: match[2].trim(),
+      required: match[3].trim(),
+    });
+  }
+  return blockers;
+}
+
+module.exports = { parseBlockers };