@thehammer/schema-mcp-server 1.0.9 → 1.0.11

package/dist/api-client.d.ts

@@ -38,6 +38,31 @@ export declare function getTemplatePreviewHtml(templateId: number, teamObjectId?
 export declare function getStyleList(): Promise<ApiResponse>;
 export declare function listQualityGateItems(): Promise<ApiResponse>;
 export declare function submitQualityGateReview(itemId: number, status: string, analysis: string, message?: string): Promise<ApiResponse>;
+/**
+ * Check (or kick off) quality gate review for a single category.
+ *
+ * NON-BLOCKING. A single HTTP round-trip. The agent NEVER waits inside MCP —
+ * blocking hides dispatch failures behind timeouts and ties up the agent when
+ * it could be doing other productive work.
+ *
+ * Returns one of:
+ * - `passed`  — all items green (cache hit or fresh review)
+ * - `failed`  — items need fixes; response includes each item's `analysis`
+ * - `running` — a reviewer is dispatched (or already in flight); call again later
+ * - `error`   — a prior reviewer dispatch failed at this iteration; manual
+ *   intervention needed. Do NOT retry on this category; surface to the user
+ *   via an annotation.
+ *
+ * Recommended pattern:
+ *   1. Call `quality_gate(A)` — reviewer is launched by the backend on the
+ *      first running-with-pending-items response
+ *   2. Do other productive work (work on other categories, read annotations,
+ *      preview templates, call `quality_gate(B)` in parallel)
+ *   3. Call `quality_gate(A)` again later to poll. The backend is idempotent:
+ *      won't launch a second reviewer while the first is running.
+ *   4. When the agent has no other productive work, it still polls — each poll
+ *      is cheap, short, and carries minimal context.
+ */
 export declare function callQualityGate(category: string, message?: string): Promise<ApiResponse>;
 /**
  * Orchestrator finalization — mandatory last action before exit.
@@ -50,4 +75,11 @@ export declare function callQualityGate(category: string, message?: string): Pro
  */
 export declare function completeDispatch(message?: string): Promise<ApiResponse>;
 export declare function postProgress(progressMessage: string, phase?: string): Promise<ApiResponse>;
+/**
+ * Fail-fast termination — agent calls this the moment anything deviates from the
+ * prompt's described behavior (missing tool, unexpected response, sub-agent not found,
+ * API error the prompt doesn't cover, etc.). Never use shell, tinker, or other creative
+ * workarounds — abort and let the operator diagnose.
+ */
+export declare function abortDispatch(reason: string, details?: string, phase?: string): Promise<ApiResponse>;
 export { SCHEMA_ID };

package/dist/api-client.js

@@ -180,55 +180,33 @@ export async function submitQualityGateReview(itemId, status, analysis, message)
 /**
  * Check (or kick off) quality gate review for a single category.
  *
- * BLOCKING BY DESIGN. This call dispatches a reviewer (if one isn't already
- * running) and then polls the backend until the gate for that category reaches
- * a terminal state (`passed`, `failed`, or `error`). The agent sees exactly
- * one call per category — no polling loop in agent context, no wasted context
- * on intermediate `running` responses.
+ * NON-BLOCKING. A single HTTP round-trip. The agent NEVER waits inside MCP —
+ * blocking hides dispatch failures behind timeouts and ties up the agent when
+ * it could be doing other productive work.
  *
  * Returns one of:
- * - `passed` — all items green (cache hit or fresh review)
- * - `failed` — items need fixes (with `analysis`)
- * - `error`  — a prior reviewer dispatch failed at this iteration; manual
- *   intervention needed (the agent must surface this to the user)
+ * - `passed`  — all items green (cache hit or fresh review)
+ * - `failed`  — items need fixes; response includes each item's `analysis`
+ * - `running` — a reviewer is dispatched (or already in flight); call again later
+ * - `error`   — a prior reviewer dispatch failed at this iteration; manual
+ *   intervention needed. Do NOT retry on this category; surface to the user
+ *   via an annotation.
  *
- * Polling cadence: POLL_INTERVAL_MS between requests, capped at MAX_POLL_MS
- * total wall time. If the cap is reached the function returns a synthetic
- * `timeout` status so the agent doesn't hang forever.
+ * Recommended pattern:
+ *   1. Call `quality_gate(A)` — reviewer is launched by the backend on the
+ *      first running-with-pending-items response
+ *   2. Do other productive work (work on other categories, read annotations,
+ *      preview templates, call `quality_gate(B)` in parallel)
+ *   3. Call `quality_gate(A)` again later to poll. The backend is idempotent:
+ *      won't launch a second reviewer while the first is running.
+ *   4. When the agent has no other productive work, it still polls — each poll
+ *      is cheap, short, and carries minimal context.
  */
-const QUALITY_GATE_POLL_INTERVAL_MS = 3_000;
-const QUALITY_GATE_MAX_POLL_MS = 15 * 60 * 1_000; // 15 minutes
 export async function callQualityGate(category, message) {
-    const terminal = new Set(["passed", "failed", "error", "timeout"]);
-    const deadline = Date.now() + QUALITY_GATE_MAX_POLL_MS;
-    let attempt = 0;
-    while (true) {
-        attempt += 1;
-        // Only pass the agent-authored message on the FIRST call — subsequent
-        // polls are internal and shouldn't spam the backend logs with duplicates.
-        const body = { category };
-        if (attempt === 1 && message) {
-            body.message = message;
-        }
-        const result = await apiRequest("POST", mcpPath("quality-gate"), body);
-        const status = String(result.status ?? "");
-        if (terminal.has(status)) {
-            return result;
-        }
-        if (status !== "running") {
-            // Unknown status — surface it verbatim so bugs are loud rather
-            // than swallowed by the polling loop.
-            return result;
-        }
-        if (Date.now() >= deadline) {
-            return {
-                ...result,
-                status: "timeout",
-                message: `quality_gate(${category}) did not reach a terminal state within ${QUALITY_GATE_MAX_POLL_MS / 1000}s. The reviewer dispatch may be stuck — check dispatch status and retry.`,
-            };
-        }
-        await new Promise((resolve) => setTimeout(resolve, QUALITY_GATE_POLL_INTERVAL_MS));
-    }
+    return apiRequest("POST", mcpPath("quality-gate"), {
+        category,
+        message,
+    });
 }
 /**
  * Orchestrator finalization — mandatory last action before exit.
@@ -250,4 +228,17 @@ export async function postProgress(progressMessage, phase) {
         phase,
     });
 }
+/**
+ * Fail-fast termination — agent calls this the moment anything deviates from the
+ * prompt's described behavior (missing tool, unexpected response, sub-agent not found,
+ * API error the prompt doesn't cover, etc.). Never use shell, tinker, or other creative
+ * workarounds — abort and let the operator diagnose.
+ */
+export async function abortDispatch(reason, details, phase) {
+    return apiRequest("POST", mcpPath("abort"), {
+        reason,
+        details,
+        phase,
+    });
+}
 export { SCHEMA_ID };

package/dist/index.js

@@ -52,6 +52,10 @@ const COMMON_TOOLS = [
     "template_preview",
     "template_preview_html",
     "quality_gate_list",
+    // Fail-fast termination — always available regardless of role. The agent calls
+    // this the moment anything deviates from the prompt's described behavior instead
+    // of inventing creative workarounds via shell commands or source-code exploration.
+    "abort",
 ];
 const ROLE_TOOLS = {
     orchestrator: new Set([
@@ -226,6 +230,23 @@ if (shouldRegister("post_progress"))
         const result = await api.postProgress(message, phase);
         return jsonResult(result);
     });
+if (shouldRegister("abort"))
+    server.tool("abort", "FAIL-FAST TERMINATION. Call this the moment anything deviates from the prompt's described behavior: a required tool is missing, a tool returns an unexpected error, a sub-agent can't be invoked, an API call fails in a way the prompt doesn't cover, or anything else the prompt says should work is broken. Do NOT try to work around problems with shell commands, source-code exploration, or creative solutions. Abort, explain what failed, and exit immediately. After calling abort, your response ends — no further tool calls.", {
+        reason: z
+            .string()
+            .describe("Short description of what failed (one sentence). Example: 'mcp__schema__template_patch returned tool_not_found' or 'template-builder sub-agent is not available'."),
+        details: z
+            .string()
+            .optional()
+            .describe("Full error details, stack trace, tool response, or context that would help the operator diagnose the failure."),
+        phase: z
+            .string()
+            .optional()
+            .describe("Phase you were in when the failure occurred (e.g., 'planning', 'delegating', 'template_patch')."),
+    }, async ({ reason, details, phase }) => {
+        const result = await api.abortDispatch(reason, details, phase);
+        return jsonResult(result);
+    });
 // ============================================================================
 // Schema Tools
 // ============================================================================
@@ -681,20 +702,18 @@ if (shouldRegister("quality_gate_submit_review"))
         return jsonResult(result);
     });
 if (shouldRegister("quality_gate"))
-    server.tool("quality_gate", "Run the quality gate for a single category (schema, directive, or template). " +
-        "BLOCKING — this call dispatches a reviewer (if one isn't already running) and waits " +
-        "until the gate reaches a terminal state. You receive ONE response per call: never " +
-        "poll the same category repeatedly. Response statuses: " +
-        "'passed' means all items are green (safe to move on); " +
+    server.tool("quality_gate", "Dispatch or poll the quality gate for a single category (schema, directive, or template). " +
+        "NON-BLOCKING — the call returns immediately. Response statuses: " +
+        "'passed' means all items in the category are green (safe to move on); " +
+        "'running' means a reviewer was dispatched (or one is already in flight) — do other " +
+        "productive work, then call this tool again later to check status; " +
         "'failed' means items need fixes — read each item's `analysis`, apply fixes via " +
         "mutation tools (which auto-invalidate the category), then call this tool again; " +
         "'error' means the reviewer dispatch itself failed — surface the error to the user " +
-        "and stop (do NOT retry the same category); " +
-        "'timeout' means the call hit its 15-minute wall-time cap — the reviewer may be " +
-        "stuck, report it and move on. " +
-        "Parallelism is still available via concurrent tool calls for DIFFERENT categories " +
-        "(e.g. schema + directive in parallel). Do NOT call this tool twice for the same " +
-        "category before the first call returns.", {
+        "via an annotation and stop on that category (do NOT retry). " +
+        "You may call this for multiple categories in parallel. The backend is idempotent — " +
+        "calling while a reviewer is running returns 'running' without launching a duplicate. " +
+        "When you have no other productive work, continue polling — each call is cheap.", {
         category: z
             .enum(["schema", "directive", "template"])
             .describe("The quality gate category to check. Must be one of: schema, directive, template."),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thehammer/schema-mcp-server",
-  "version": "1.0.9",
+  "version": "1.0.11",
   "description": "MCP server for Schema Builder - translates Claude Code tool calls into Laravel API requests",
   "license": "MIT",
   "repository": {