@josstei/maestro 1.6.4-rc.1

package/claude/src/mcp/content/runtime-content.js

@@ -0,0 +1,188 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { parseFrontmatterOnly, splitAtBoundary } = require('../../lib/frontmatter');
+const { replaceInContent } = require('../../lib/naming');
+const { stripFeatureBlocks: stripFeatureBlocksCore } = require('../../core/feature-blocks');
+
+const agentRegistry = require('../../generated/agent-registry.json');
+
+const DEFAULT_RUNTIME_NAME = 'gemini';
+
+const RESOURCE_ALLOWLIST = Object.freeze(require('../../generated/resource-registry.json'));
+
+const AGENT_ALLOWLIST = Object.freeze(agentRegistry.map((entry) => entry.name));
+
+function applyReplacePaths(content, runtimeConfig) {
+  let result = content;
+  const env = runtimeConfig.env || {};
+
+  if (env.extensionPath) {
+    const replacement = env.extensionPath.startsWith('${')
+      ? env.extensionPath
+      : '${' + env.extensionPath + '}';
+    result = result.replace(/\$\{extensionPath\}/g, replacement);
+  }
+
+  if (env.workspacePath) {
+    result = result.replace(/\$\{workspacePath\}/g, '${' + env.workspacePath + '}');
+  }
+
+  return result;
+}
+
+function applySkillMetadata(content, runtimeConfig, resourcePath) {
+  if (runtimeConfig.name !== 'claude' || !resourcePath.endsWith('SKILL.md')) {
+    return content;
+  }
+
+  return content.replace(
+    /^(---\n[\s\S]*?)(^---)/m,
+    '$1user-invocable: false\n$2'
+  );
+}
+
+function applyReplaceAgentNames(content, runtimeConfig) {
+  return replaceInContent(
+    content,
+    AGENT_ALLOWLIST.filter((n) => n.includes('-')),
+    runtimeConfig.agentNaming
+  );
+}
+
+function applyStripFeature(content, runtimeConfig) {
+  return stripFeatureBlocksCore(content, runtimeConfig.features || {});
+}
+
+const AGENT_NAME_RESOURCES = new Set([
+  'references/architecture.md',
+  'skills/shared/delegation/SKILL.md',
+  'skills/shared/execution/SKILL.md',
+  'skills/shared/validation/SKILL.md',
+  'skills/shared/code-review/SKILL.md',
+]);
+
+function applyRuntimeTransforms(content, runtimeConfig, resourcePath) {
+  let result = content;
+
+  if (resourcePath === 'references/architecture.md') {
+    result = applyStripFeature(result, runtimeConfig);
+  }
+
+  if (AGENT_NAME_RESOURCES.has(resourcePath)) {
+    result = applyReplaceAgentNames(result, runtimeConfig);
+  }
+
+  result = applyReplacePaths(result, runtimeConfig);
+  result = applySkillMetadata(result, runtimeConfig, resourcePath);
+
+  return result;
+}
+
+function stripFrontmatter(content) {
+  const { raw, body } = splitAtBoundary(content);
+  if (!raw) {
+    return content;
+  }
+  return body;
+}
+
+function stripFeatureBlocks(content, runtimeConfig) {
+  return stripFeatureBlocksCore(content, runtimeConfig.features || {}, { mode: 'lenient' });
+}
+
+function parseInlineArray(raw) {
+  if (!raw || !raw.startsWith('[') || !raw.endsWith(']')) {
+    return [];
+  }
+
+  return raw
+    .slice(1, -1)
+    .split(',')
+    .map((item) => item.trim())
+    .filter(Boolean);
+}
+
+function parseFrontmatter(content) {
+  return parseFrontmatterOnly(content).frontmatter;
+}
+
+function mapTools(frontmatter, runtimeConfig) {
+  const runtimeName = runtimeConfig.name || DEFAULT_RUNTIME_NAME;
+  const overrideKey = `tools.${runtimeName}`;
+  const configuredTools = frontmatter[overrideKey]
+    ? parseInlineArray(frontmatter[overrideKey])
+    : parseInlineArray(frontmatter.tools);
+
+  return configuredTools.flatMap((toolName) => {
+    const mapped = runtimeConfig.tools && runtimeConfig.tools[toolName];
+    if (Array.isArray(mapped)) {
+      return mapped;
+    }
+    return mapped || toolName;
+  });
+}
+
+function readResourceFromFilesystem(id, runtimeConfig, srcRoot) {
+  const relativePath = RESOURCE_ALLOWLIST[id];
+  if (!relativePath) {
+    return {
+      error: `Unknown resource identifier: "${id}". Known identifiers: ${Object.keys(RESOURCE_ALLOWLIST).join(', ')}`,
+    };
+  }
+
+  const absolutePath = path.join(srcRoot, relativePath);
+  try {
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    return {
+      content: applyRuntimeTransforms(content, runtimeConfig, relativePath),
+    };
+  } catch (err) {
+    return {
+      error: `Failed to read resource "${id}": ${err.code || 'UNKNOWN'}`,
+    };
+  }
+}
+
+function readAgentFromFilesystem(agentName, runtimeConfig, srcRoot) {
+  if (!AGENT_ALLOWLIST.includes(agentName)) {
+    return {
+      error: `Unknown agent identifier: "${agentName}". Known identifiers: ${AGENT_ALLOWLIST.join(', ')}`,
+    };
+  }
+
+  const absolutePath = path.join(srcRoot, 'agents', `${agentName}.md`);
+  try {
+    const content = fs.readFileSync(absolutePath, 'utf8');
+    const frontmatter = parseFrontmatter(content);
+    return {
+      agent: {
+        body: stripFrontmatter(stripFeatureBlocks(content, runtimeConfig)),
+        tools: mapTools(frontmatter, runtimeConfig),
+      },
+    };
+  } catch (err) {
+    return {
+      error: `Failed to read agent "${agentName}": ${err.code || 'UNKNOWN'}`,
+    };
+  }
+}
+
+module.exports = {
+  DEFAULT_RUNTIME_NAME,
+  RESOURCE_ALLOWLIST,
+  AGENT_ALLOWLIST,
+  applyReplacePaths,
+  applySkillMetadata,
+  applyReplaceAgentNames,
+  applyStripFeature,
+  applyRuntimeTransforms,
+  stripFrontmatter,
+  stripFeatureBlocks,
+  parseInlineArray,
+  parseFrontmatter,
+  mapTools,
+  readResourceFromFilesystem,
+  readAgentFromFilesystem,
+};

package/claude/src/mcp/contracts/cache-path-rejector.js

@@ -0,0 +1,39 @@
+'use strict';
+
+const path = require('node:path');
+
+const CACHE_PATH_SEGMENTS = [
+  path.join('.codex', 'plugins'),
+  path.join('.claude', 'plugins'),
+  path.join('.gemini', 'extensions'),
+];
+
+function segmentWindows(segments, size) {
+  const windows = [];
+  for (let i = 0; i <= segments.length - size; i += 1) {
+    windows.push(segments.slice(i, i + size).join(path.sep));
+  }
+  return windows;
+}
+
+/**
+ * Returns true when the given path falls inside a host extension cache directory.
+ * Matches on contiguous two-segment windows so that substring-only matches
+ * (e.g. `.codex-plugins-research`) are correctly distinguished from genuine cache directories and not misclassified as cache paths.
+ *
+ * @param {string} candidate - Filesystem path. Absolute paths are used as-is; relative paths are resolved against process.cwd(), so callers should pass absolute paths for deterministic behavior.
+ * @returns {boolean}
+ */
+function isExtensionCachePath(candidate) {
+  if (typeof candidate !== 'string' || candidate.length === 0) {
+    return false;
+  }
+  const segments = path
+    .resolve(candidate)
+    .split(path.sep)
+    .filter((segment) => segment.length > 0);
+  const windows = segmentWindows(segments, 2);
+  return CACHE_PATH_SEGMENTS.some((cacheSegment) => windows.includes(cacheSegment));
+}
+
+module.exports = { CACHE_PATH_SEGMENTS, isExtensionCachePath };

package/claude/src/mcp/contracts/downstream-context.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * Canonical downstream-context contract.
+ *
+ * The handoff between orchestrator and child agents is documented (in
+ * agent-base-protocol) as a five-field structure. Agents may emit each field as
+ * either a string (`"none"`, `"X uses Y"`) or an array of strings. The canonical
+ * storage shape is an array of strings; normalization here is the single source
+ * of truth used by every handler that reads, writes, or validates the context.
+ *
+ * Strings and the tokens `"none"` / `"n/a"` / empty strings are all treated as
+ * absent so agent protocol examples like `"or none"` don't produce phantom
+ * entries in session state.
+ */
+
+const CANONICAL_FIELDS = Object.freeze([
+  'key_interfaces_introduced',
+  'patterns_established',
+  'integration_points',
+  'assumptions',
+  'warnings',
+]);
+
+const EMPTY_VALUE_TOKENS = new Set(['', 'none', 'n/a', 'not applicable']);
+
+function isEmptyValueToken(value) {
+  return EMPTY_VALUE_TOKENS.has(String(value).trim().toLowerCase());
+}
+
+function normalizeFieldValue(value) {
+  if (value == null) return [];
+  if (Array.isArray(value)) {
+    return value
+      .filter((item) => typeof item === 'string')
+      .map((item) => item.trim())
+      .filter((item) => item.length > 0 && !isEmptyValueToken(item));
+  }
+  if (typeof value === 'string') {
+    const trimmed = value.trim();
+    if (trimmed.length === 0 || isEmptyValueToken(trimmed)) return [];
+    return [trimmed];
+  }
+  return [];
+}
+
+/**
+ * @returns {Object<string, string[]>} a fresh empty canonical context.
+ */
+function createEmptyDownstreamContext() {
+  const empty = {};
+  for (const field of CANONICAL_FIELDS) {
+    empty[field] = [];
+  }
+  return empty;
+}
+
+/**
+ * Normalize any input to the canonical `{ field: string[] }` shape.
+ * Accepts null, arrays-of-strings, strings, and unknown keys are dropped.
+ *
+ * @param {unknown} input
+ * @returns {Object<string, string[]>}
+ */
+function normalizeDownstreamContext(input) {
+  const normalized = createEmptyDownstreamContext();
+  if (!input || typeof input !== 'object' || Array.isArray(input)) {
+    return normalized;
+  }
+  for (const field of CANONICAL_FIELDS) {
+    normalized[field] = normalizeFieldValue(input[field]);
+  }
+  return normalized;
+}
+
+/**
+ * True when the normalized context has at least one non-empty field.
+ * @param {unknown} input
+ * @returns {boolean}
+ */
+function isDownstreamContextPopulated(input) {
+  const normalized = normalizeDownstreamContext(input);
+  return CANONICAL_FIELDS.some((field) => normalized[field].length > 0);
+}
+
+/**
+ * Human-readable description of the contract, suitable for embedding in error
+ * messages so callers can adapt without reading source.
+ * @returns {string}
+ */
+function describeShape() {
+  return (
+    'downstream_context must contain at least one of: ' +
+    CANONICAL_FIELDS.join(', ') +
+    '. Each field accepts a non-empty string or a non-empty array of strings. ' +
+    'Empty strings and the tokens "none" / "n/a" / "not applicable" are treated as absent.'
+  );
+}
+
+module.exports = {
+  CANONICAL_FIELDS,
+  createEmptyDownstreamContext,
+  normalizeDownstreamContext,
+  isDownstreamContextPopulated,
+  describeShape,
+};

package/claude/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/claude/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/claude/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/claude/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,
+};