@hyperfixi/mcp-server 2.3.0 → 2.3.1

package/README.md

@@ -45,6 +45,20 @@ Or if installed globally:
 }
 ```
 
+## GRAIL Workflow Tools (5)
+
+5 stable tools for Claude-native workflow orchestration: evaluate conditions, plan dependency-ordered steps, and execute actions with precondition checks, cost-aware planning, and drift detection.
+
+| Tool          | Description                                                    |
+| ------------- | -------------------------------------------------------------- |
+| `grail_check` | Evaluate conditions, show available/blocked affordances        |
+| `grail_plan`  | Compute dependency-ordered plan for a goal affordance          |
+| `grail_run`   | Execute an affordance with precondition and confirmation gates |
+| `grail_info`  | Return full workflow graph (conditions, affordances, enables)  |
+| `grail_list`  | List all condition and affordance names                        |
+
+See **[GRAIL.md](GRAIL.md)** for full documentation, schema reference, and examples.
+
 ## Available Tools (80)
 
 ### Validation & Semantic Tools (8)

package/dist/{esm-LUPOYJFX.js → esm-UBAMNMQH.js}

@@ -161,7 +161,7 @@ function expand_(str, max, isTop) {
       const x2 = numeric(n[0]);
       const y2 = numeric(n[1]);
       const width = Math.max(n[0].length, n[1].length);
-      let incr = n.length === 3 && n[2] !== void 0 ? Math.abs(numeric(n[2])) : 1;
+      let incr = n.length === 3 && n[2] !== void 0 ? Math.max(Math.abs(numeric(n[2])), 1) : 1;
       let test = lte;
       const reverse = y2 < x2;
       if (reverse) {

package/dist/index.js

@@ -8077,7 +8077,7 @@ function createInlineExtractor() {
     const fs = await import("fs");
     const path = await import("path");
     const crypto = await import("crypto");
-    const { glob } = await import("./esm-LUPOYJFX.js");
+    const { glob } = await import("./esm-UBAMNMQH.js");
     const globs = [
       "**/*.html",
       "**/*.htm",
@@ -8903,6 +8903,610 @@ async function handleTranslateLse(args) {
   }
 }
 
+// src/tools/grail-yaml-loader.ts
+import { readFileSync } from "fs";
+import { parse as parseYaml } from "yaml";
+function resolveTemplate(template, context) {
+  return template.replace(/\{(\w+)\}/g, (match, key) => {
+    return key in context ? context[key] : match;
+  });
+}
+function loadGrailConfig(yamlPath) {
+  const raw = readFileSync(yamlPath, "utf-8");
+  const doc = parseYaml(raw);
+  if (!doc || typeof doc !== "object") {
+    throw new Error(`grail: invalid YAML at ${yamlPath}`);
+  }
+  const version = doc.version ?? "1.0";
+  const domain = doc.domain ?? { name: "unknown" };
+  const conditions = (doc.conditions ?? []).map(
+    (c) => ({
+      name: c.name,
+      description: c.description ?? "",
+      eval: c.eval
+    })
+  );
+  const affordances = (doc.affordances ?? []).map(
+    (a) => ({
+      name: a.name,
+      title: a.title ?? a.name,
+      preconditions: a.preconditions ?? [],
+      effects: a.effects ?? [],
+      cost: a.cost ?? 1,
+      preferred: a.preferred ?? false,
+      confirm: a.confirm ?? "",
+      action: a.action
+    })
+  );
+  return { version, domain, conditions, affordances };
+}
+function findGrailYaml(cwd) {
+  return process.env.GRAIL_YAML ?? `${cwd}/grail.yaml`;
+}
+
+// src/tools/grail-registry.ts
+import { exec } from "child_process";
+var MAX_OUTPUT = 500;
+function truncate(s) {
+  return s.length > MAX_OUTPUT ? s.slice(0, MAX_OUTPUT) + "\u2026" : s;
+}
+function execShell(cmd, cwd, timeout) {
+  return new Promise((resolve) => {
+    const start = Date.now();
+    exec(cmd, { cwd, timeout: timeout * 1e3 }, (error, stdout, stderr) => {
+      const duration_ms = Date.now() - start;
+      const output = truncate((stdout ?? "") + (stderr ?? "")).trim();
+      const timedOut = !!(error && "killed" in error && error.killed);
+      const exitCode = error ? error.code ?? 1 : 0;
+      resolve({
+        exitCode,
+        output: timedOut ? `Timed out after ${timeout}s` : output,
+        duration_ms,
+        timedOut
+      });
+    });
+  });
+}
+var GrailRegistry = class {
+  conditions = /* @__PURE__ */ new Map();
+  affordances = /* @__PURE__ */ new Map();
+  _cwd;
+  constructor(config, cwd) {
+    this._cwd = cwd;
+    for (const c of config.conditions) {
+      this.conditions.set(c.name, c);
+    }
+    for (const a of config.affordances) {
+      this.affordances.set(a.name, a);
+    }
+  }
+  _context() {
+    return { cwd: this._cwd };
+  }
+  // ---------- Condition evaluation ----------
+  async evaluate(name) {
+    const cond = this.conditions.get(name);
+    if (!cond) {
+      return {
+        passing: false,
+        output: `Unknown condition: ${name}`,
+        duration_ms: 0,
+        error: "unknown"
+      };
+    }
+    const ctx = this._context();
+    const cmd = resolveTemplate(cond.eval.cmd, ctx);
+    const evalCwd = cond.eval.cwd ? resolveTemplate(cond.eval.cwd, ctx) : this._cwd;
+    const timeout = cond.eval.timeout ?? 30;
+    try {
+      const { exitCode, output, duration_ms } = await execShell(cmd, evalCwd, timeout);
+      return { passing: exitCode === 0, output, duration_ms };
+    } catch (err) {
+      return {
+        passing: false,
+        output: "",
+        duration_ms: 0,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    }
+  }
+  async evaluateAll() {
+    const names = [...this.conditions.keys()];
+    const results = {};
+    const chunks = [];
+    for (let i = 0; i < names.length; i += 8) {
+      chunks.push(names.slice(i, i + 8));
+    }
+    for (const chunk of chunks) {
+      const chunkResults = await Promise.all(
+        chunk.map(async (name) => ({ name, result: await this.evaluate(name) }))
+      );
+      for (const { name, result } of chunkResults) {
+        results[name] = result;
+      }
+    }
+    return results;
+  }
+  // ---------- Affordance checks ----------
+  checkPreconditions(affordanceName, truth) {
+    const aff = this.affordances.get(affordanceName);
+    if (!aff) return { met: false, unmet: [`unknown affordance: ${affordanceName}`] };
+    const unmet = (aff.preconditions ?? []).filter((p) => !truth[p]);
+    return { met: unmet.length === 0, unmet };
+  }
+  // ---------- Affordance execution ----------
+  async run(affordanceName) {
+    const aff = this.affordances.get(affordanceName);
+    if (!aff) {
+      return {
+        success: false,
+        exitCode: -1,
+        output: `Unknown affordance: ${affordanceName}`,
+        duration_ms: 0,
+        cmd: ""
+      };
+    }
+    if (!aff.action) {
+      return {
+        success: false,
+        exitCode: -1,
+        output: `Affordance ${affordanceName} has no action defined`,
+        duration_ms: 0,
+        cmd: ""
+      };
+    }
+    const ctx = this._context();
+    const cmd = resolveTemplate(aff.action.cmd, ctx);
+    const actionCwd = aff.action.cwd ? resolveTemplate(aff.action.cwd, ctx) : this._cwd;
+    const timeout = aff.action.timeout ?? 120;
+    const { exitCode, output, duration_ms } = await execShell(cmd, actionCwd, timeout);
+    return { success: exitCode === 0, exitCode, output, duration_ms, cmd };
+  }
+  // ---------- Introspection ----------
+  conditionMap() {
+    const result = {};
+    for (const [name, cond] of this.conditions) {
+      const producedBy = [];
+      const requiredBy = [];
+      for (const [affName, aff] of this.affordances) {
+        if ((aff.effects ?? []).some(
+          (e) => e === name || e.includes("{") && this._templateMatches(e, name)
+        )) {
+          producedBy.push(affName);
+        }
+        if ((aff.preconditions ?? []).includes(name)) {
+          requiredBy.push(affName);
+        }
+      }
+      result[name] = { description: cond.description, producedBy, requiredBy };
+    }
+    return result;
+  }
+  enablesGraph() {
+    const graph = {};
+    for (const [affName, aff] of this.affordances) {
+      const enables = [];
+      for (const effect of aff.effects ?? []) {
+        for (const [otherName, other] of this.affordances) {
+          if (otherName === affName) continue;
+          if ((other.preconditions ?? []).includes(effect) && !enables.includes(otherName)) {
+            enables.push(otherName);
+          }
+        }
+      }
+      if (enables.length > 0) {
+        graph[affName] = enables;
+      }
+    }
+    return graph;
+  }
+  _templateMatches(template, condition) {
+    const braceIdx = template.indexOf("{");
+    if (braceIdx === -1) return template === condition;
+    const prefix = template.slice(0, braceIdx);
+    return condition.startsWith(prefix);
+  }
+};
+
+// src/tools/grail-tools.ts
+import {
+  parseConditionMap,
+  plan as bfsPlan,
+  applyEffects
+} from "@lokascript/planner";
+var grailTools = [
+  {
+    name: "grail_check",
+    description: "Evaluate GRAIL conditions and show available/blocked affordances. Returns passing conditions, failing conditions (with diagnostic output), available actions (preconditions met), and blocked actions (with unmet conditions).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        only: {
+          type: "string",
+          description: "Comma-separated condition names to evaluate (default: all)"
+        }
+      }
+    }
+  },
+  {
+    name: "grail_plan",
+    description: "Compute a dependency-ordered plan to make a goal affordance feasible. Returns ordered steps with phases, costs, and blocked-by links. Pass truth from a prior grail_check to skip re-evaluation.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        goal: {
+          type: "string",
+          description: 'The affordance name to plan for (e.g., "release-publish")'
+        },
+        truth: {
+          type: "object",
+          description: "Pre-evaluated truth vector from grail_check response (condition name \u2192 boolean). If omitted, evaluates all conditions (slow)."
+        }
+      },
+      required: ["goal"]
+    }
+  },
+  {
+    name: "grail_run",
+    description: "Execute a GRAIL affordance. Checks preconditions first \u2014 blocks if unmet. Respects confirmation gates. Use dry_run=true to preview without executing. Pass truth from a prior grail_check to skip re-evaluation of preconditions.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        action: {
+          type: "string",
+          description: 'The affordance name to execute (e.g., "run-lint")'
+        },
+        dry_run: {
+          type: "boolean",
+          description: "Preview the action without executing (default: false)"
+        },
+        confirmed: {
+          type: "boolean",
+          description: "Confirm execution for actions with confirmation gates (default: false)"
+        },
+        truth: {
+          type: "object",
+          description: "Pre-evaluated truth vector from grail_check response (condition name \u2192 boolean). If omitted, evaluates all conditions to check preconditions (slow)."
+        }
+      },
+      required: ["action"]
+    }
+  },
+  {
+    name: "grail_info",
+    description: "Return the full GRAIL workflow graph: conditions with descriptions, affordances with preconditions/effects/cost, and the enables graph.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  },
+  {
+    name: "grail_list",
+    description: "List all condition names and affordance names in the GRAIL configuration.",
+    inputSchema: {
+      type: "object",
+      properties: {}
+    }
+  }
+];
+var _registry = null;
+var _cwd = null;
+function getRegistry() {
+  const cwd = process.env.GRAIL_CWD ?? process.cwd();
+  if (_registry && _cwd === cwd) return _registry;
+  const yamlPath = findGrailYaml(cwd);
+  const config = loadGrailConfig(yamlPath);
+  _registry = new GrailRegistry(config, cwd);
+  _cwd = cwd;
+  return _registry;
+}
+async function handleCheck(args) {
+  const registry2 = getRegistry();
+  const only = getString(args, "only");
+  const results = await registry2.evaluateAll();
+  const cwd = process.env.GRAIL_CWD ?? process.cwd();
+  const conditionNames = only ? only.split(",").map((s) => s.trim()).filter(Boolean) : Object.keys(results);
+  const passing = [];
+  const failing = [];
+  const errors = [];
+  for (const name of conditionNames) {
+    const result = results[name];
+    if (!result) continue;
+    const cond = registry2.conditions.get(name);
+    const desc = cond?.description ?? "";
+    if (result.error) {
+      errors.push({ name, description: desc, error: result.error });
+    } else if (result.passing) {
+      passing.push({ name, description: desc });
+    } else {
+      failing.push({ name, description: desc, output: result.output });
+    }
+  }
+  const truth = {};
+  for (const [name, result] of Object.entries(results)) {
+    truth[name] = result.passing;
+  }
+  const available = [];
+  const blocked = [];
+  for (const [name, aff] of registry2.affordances) {
+    const check = registry2.checkPreconditions(name, truth);
+    if (check.met) {
+      available.push({ name, title: aff.title ?? name, cost: aff.cost ?? 1 });
+    } else {
+      blocked.push({ name, title: aff.title ?? name, unmet: check.unmet });
+    }
+  }
+  return jsonResponse({
+    cwd,
+    passing,
+    failing,
+    errors: errors.length > 0 ? errors : void 0,
+    summary: `${passing.length} passing, ${failing.length} failing`,
+    available,
+    blocked,
+    truth
+  });
+}
+async function handlePlan(args) {
+  const goal = getString(args, "goal");
+  if (!goal) return errorResponse("Missing required parameter: goal");
+  const registry2 = getRegistry();
+  const aff = registry2.affordances.get(goal);
+  if (!aff) {
+    return jsonResponse({
+      goal,
+      feasible: false,
+      reason: "unknown affordance",
+      unsatisfiable: [],
+      steps: []
+    });
+  }
+  let truth;
+  const suppliedTruth = args.truth;
+  if (suppliedTruth && typeof suppliedTruth === "object") {
+    truth = suppliedTruth;
+  } else {
+    const results = await registry2.evaluateAll();
+    truth = {};
+    for (const [name, result] of Object.entries(results)) {
+      truth[name] = result.passing;
+    }
+  }
+  const check = registry2.checkPreconditions(goal, truth);
+  if (check.met) {
+    const cmd = aff.action?.cmd ?? "";
+    return jsonResponse({
+      goal,
+      feasible: true,
+      phases: 1,
+      totalCost: aff.cost ?? 1,
+      currentConditions: truth,
+      steps: [
+        {
+          action: goal,
+          cmd,
+          resolves: aff.effects ?? [],
+          phase: 0,
+          cost: aff.cost ?? 1,
+          blocked_by: []
+        }
+      ]
+    });
+  }
+  const conditionMap = registry2.conditionMap();
+  const { defs, conditionNames, mutexPrefixes } = parseConditionMap(conditionMap);
+  const goalDef = defs.find((d) => d.name === goal);
+  if (!goalDef) {
+    return jsonResponse({
+      goal,
+      feasible: false,
+      reason: "unknown affordance in condition map",
+      unsatisfiable: [],
+      steps: []
+    });
+  }
+  const startState = /* @__PURE__ */ new Set();
+  for (const [name, passing] of Object.entries(truth)) {
+    if (passing) startState.add(name);
+  }
+  const unmet = goalDef.preconditions.filter((p) => !startState.has(p));
+  const planSteps = [];
+  const usedKeys = /* @__PURE__ */ new Set();
+  let currentState = startState;
+  for (const precond of unmet) {
+    if (currentState.has(precond)) continue;
+    const paths = bfsPlan(currentState, precond, defs, mutexPrefixes);
+    if (paths.length === 0) {
+      return jsonResponse({
+        goal,
+        feasible: false,
+        reason: "unsatisfiable conditions",
+        unsatisfiable: [precond],
+        currentConditions: truth,
+        steps: []
+      });
+    }
+    for (const step of paths[0]) {
+      if (usedKeys.has(step.key())) continue;
+      usedKeys.add(step.key());
+      planSteps.push({ name: step.name, params: { ...step.params } });
+      const affDef = defs.find((d) => d.name === step.name);
+      if (affDef) currentState = applyEffects(currentState, affDef, step.params, mutexPrefixes);
+    }
+  }
+  planSteps.push({ name: goal, params: {} });
+  const steps = planSteps.map((ps) => {
+    const stepAff = registry2.affordances.get(ps.name);
+    return {
+      action: ps.name,
+      cmd: stepAff?.action?.cmd ?? "",
+      resolves: stepAff?.effects ?? [],
+      phase: 0,
+      cost: stepAff?.cost ?? 1,
+      blocked_by: []
+    };
+  });
+  const condProducer = /* @__PURE__ */ new Map();
+  for (let i = 0; i < steps.length; i++) {
+    for (const effect of steps[i].resolves) {
+      condProducer.set(effect, i);
+    }
+  }
+  for (let i = 0; i < steps.length; i++) {
+    let depPhase = -1;
+    const stepAff = registry2.affordances.get(steps[i].action);
+    for (const precond of stepAff?.preconditions ?? []) {
+      const producerIdx = condProducer.get(precond);
+      if (producerIdx !== void 0 && producerIdx !== i) {
+        depPhase = Math.max(depPhase, steps[producerIdx].phase);
+      }
+    }
+    steps[i].phase = depPhase + 1;
+  }
+  for (let i = 0; i < steps.length; i++) {
+    for (const condition of steps[i].resolves) {
+      for (let j = i + 1; j < steps.length; j++) {
+        const laterAff = registry2.affordances.get(steps[j].action);
+        if ((laterAff?.preconditions ?? []).includes(condition)) {
+          steps[i].blocked_by.push({ condition, needed_by: steps[j].action });
+        }
+      }
+    }
+  }
+  const totalCost = steps.reduce((sum, s) => sum + s.cost, 0);
+  const phases = Math.max(...steps.map((s) => s.phase)) + 1;
+  return jsonResponse({
+    goal,
+    feasible: true,
+    phases,
+    totalCost,
+    currentConditions: truth,
+    steps
+  });
+}
+async function handleRun(args) {
+  const action = getString(args, "action");
+  if (!action) return errorResponse("Missing required parameter: action");
+  const dryRun = getBoolean(args, "dry_run");
+  const confirmed = getBoolean(args, "confirmed");
+  const registry2 = getRegistry();
+  const aff = registry2.affordances.get(action);
+  if (!aff) return errorResponse(`Unknown affordance: ${action}`);
+  let truth;
+  const suppliedTruth = args.truth;
+  if (suppliedTruth && typeof suppliedTruth === "object") {
+    truth = suppliedTruth;
+  } else if ((aff.preconditions ?? []).length === 0) {
+    truth = {};
+  } else {
+    const results = await registry2.evaluateAll();
+    truth = {};
+    for (const [name, result2] of Object.entries(results)) {
+      truth[name] = result2.passing;
+    }
+  }
+  const check = registry2.checkPreconditions(action, truth);
+  if (!check.met) {
+    return jsonResponse({
+      action,
+      blocked: true,
+      unmet: check.unmet,
+      hint: `Run grail_plan('${action}') to see what's needed`,
+      cmd: aff.action?.cmd ?? ""
+    });
+  }
+  if (aff.confirm && !confirmed) {
+    return jsonResponse({
+      action,
+      needsConfirmation: true,
+      message: aff.confirm === "true" || aff.confirm === true ? `Are you sure you want to run ${action}?` : aff.confirm,
+      hint: `Re-run with confirmed=true to proceed: grail_run('${action}', confirmed=true)`,
+      cmd: aff.action?.cmd ?? "",
+      effects: aff.effects ?? []
+    });
+  }
+  if (dryRun) {
+    return jsonResponse({
+      action,
+      dry_run: true,
+      preconditions_met: true,
+      cmd: aff.action?.cmd ?? "",
+      effects: aff.effects ?? []
+    });
+  }
+  const result = await registry2.run(action);
+  const driftWarnings = [];
+  if (result.success && (aff.effects?.length ?? 0) > 0) {
+    const postResults = await registry2.evaluateAll();
+    for (const effect of aff.effects ?? []) {
+      if (!effect.includes("{") && postResults[effect] && !postResults[effect].passing) {
+        driftWarnings.push(`Effect '${effect}' declared but not true after execution`);
+      }
+    }
+  }
+  return jsonResponse({
+    action,
+    success: result.success,
+    cmd: result.cmd,
+    exitCode: result.exitCode,
+    duration_ms: result.duration_ms,
+    output: result.output,
+    effects: aff.effects ?? [],
+    driftWarnings: driftWarnings.length > 0 ? driftWarnings : void 0
+  });
+}
+function handleInfo() {
+  const registry2 = getRegistry();
+  const conditions = {};
+  for (const [name, cond] of registry2.conditions) {
+    conditions[name] = { description: cond.description };
+  }
+  const affordances = {};
+  for (const [name, aff] of registry2.affordances) {
+    affordances[name] = {
+      title: aff.title ?? name,
+      preconditions: aff.preconditions ?? [],
+      effects: aff.effects ?? [],
+      cost: aff.cost ?? 1,
+      cmd: aff.action?.cmd ?? ""
+    };
+  }
+  return jsonResponse({
+    domain: { name: "hyperfixi" },
+    conditions,
+    affordances,
+    enablesGraph: registry2.enablesGraph()
+  });
+}
+function handleList() {
+  const registry2 = getRegistry();
+  return jsonResponse({
+    conditions: [...registry2.conditions.keys()],
+    affordances: [...registry2.affordances.keys()]
+  });
+}
+async function handleGrailTool(name, args) {
+  try {
+    switch (name) {
+      case "grail_check":
+        return await handleCheck(args);
+      case "grail_plan":
+        return await handlePlan(args);
+      case "grail_run":
+        return await handleRun(args);
+      case "grail_info":
+        return handleInfo();
+      case "grail_list":
+        return handleList();
+      default:
+        return errorResponse(`Unknown GRAIL tool: ${name}`);
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return errorResponse(`GRAIL tool error: ${message}`);
+  }
+}
+
 // src/resources/content.ts
 function getCommandsReference() {
   return `# Hyperscript Commands Reference
@@ -9930,7 +10534,8 @@ server.setRequestHandler(ListToolsRequestSchema, async () => {
       ...inventoryTools,
       ...trainingDataTools,
       ...feedbackTools,
-      ...lsePipelineTools
+      ...lsePipelineTools,
+      ...grailTools
     ]
   };
 });
@@ -9995,6 +10600,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   if (name === "lse_from_hyperscript" || name === "lse_to_hyperscript") {
     return handleLsePipelineTool(name, args);
   }
+  if (name.startsWith("grail_")) {
+    return handleGrailTool(name, args);
+  }
   if (name.startsWith("get_")) {
     return handlePatternTool(name, args);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperfixi/mcp-server",
-  "version": "2.3.0",
+  "version": "2.3.1",
   "description": "Model Context Protocol server for HyperFixi hyperscript development",
   "type": "module",
   "main": "dist/index.js",
@@ -40,8 +40,10 @@
     "@hyperfixi/patterns-reference": "*",
     "@lokascript/compilation-service": "*",
     "@lokascript/framework": "*",
+    "@lokascript/planner": "*",
     "@lokascript/semantic": "*",
-    "@modelcontextprotocol/sdk": "^1.25.0"
+    "@modelcontextprotocol/sdk": "^1.25.0",
+    "yaml": "^2.8.3"
   },
   "peerDependencies": {
     "@hyperfixi/core": "*",