@minicor/mcp-server 4.8.0 → 4.10.0

package/dist/tools/blueprints.js

@@ -0,0 +1,1193 @@
+/**
+ * MCP tools for Blueprints — the front door of the Minicor build loop.
+ *
+ * A Blueprint is the living spec + context library that OWNS a job. The loop:
+ * feed the library (entries: SOPs, Looms, notes, walkthrough sessions) ->
+ * synthesize (LLM drafts a spec proposal) -> review/answer -> apply ->
+ * build (sync the spec into a Job) -> the jobs toolset takes over with the
+ * {middlewareId, routeId, buildId} triple blueprint_build returns.
+ *
+ * OWNERSHIP RULE: when a route is blueprint-linked, never register_job /
+ * update_job / add_test_case directly on it — that trips reverse-drift
+ * detection (state job_ahead). Drive changes through the spec instead.
+ *
+ * Auth/transport is handled by MiddlewareServiceClient (same plumbing as the
+ * jobs tools): the region's public middleware-service with the MCP's user
+ * bearer token. See middleware-service-client.ts for the base-URL precedence.
+ */
+import { z } from "zod";
+import { ok, text } from "../helpers.js";
+import { MiddlewareServiceClient, MiddlewareServiceError, } from "../middleware-service-client.js";
+const regionParam = z
+    .enum(["us", "ca"])
+    .optional()
+    .describe("Region (us or ca). Auto-detected from workspace if omitted.");
+const entryKindParam = z
+    .enum([
+    "doc",
+    "video",
+    "url",
+    "note",
+    "transcript",
+    "data-source",
+    "walkthrough",
+    "screen-map",
+    "anchor",
+    "screenshot",
+])
+    .describe("Entry kind. Context kinds feed synthesis: doc | video | url | note | transcript | data-source | walkthrough. Resource kinds are runtime-referenceable as entry://<id>#<fragment>: screen-map | anchor | screenshot.");
+/** HTTP status of a middleware-service failure, or undefined for other errors. */
+function statusOf(e) {
+    return e instanceof MiddlewareServiceError ? e.status : undefined;
+}
+/** Structured error code of a middleware-service failure, when the service sent one. */
+function codeOf(e) {
+    return e instanceof MiddlewareServiceError ? e.code : undefined;
+}
+/** A build run is considered stalled after this long in `queued`. */
+const BUILDER_STALL_MS = 2 * 60 * 1000;
+/** True when the spec document has no substance yet (nothing to build from). */
+function specIsEmpty(bp) {
+    const doc = bp.document ?? {};
+    const goal = typeof doc.goal === "string" ? doc.goal.trim() : "";
+    const steps = Array.isArray(doc.steps) ? doc.steps : [];
+    return goal === "" && steps.length === 0;
+}
+/**
+ * Classify a blocked synthesize response into a structured blocked.reason.
+ * Newer services carry a stable snake_case `code` on every synthesis-path
+ * 409/502 — that is the primary discriminator. The message-string matching
+ * below it is a FALLBACK for older deployments that predate the codes;
+ * remove it once the middleware structured-code change is deployed
+ * everywhere (middleware-service faiz/synthesis-shape-retry).
+ */
+function classifySynthesizeBlock(status, message, code) {
+    switch (code) {
+        case "proposal_pending":
+            return { reason: "proposal_pending", retryable: true };
+        case "entries_enriching":
+            return { reason: "entries_enriching", retryable: true };
+        case "synthesis_not_configured":
+            return { reason: "llm_unconfigured", retryable: false };
+        // 502s: the LLM leg failed — synthesize again (the service already
+        // retries internally; a repeat failure is worth one more attempt
+        // before escalating).
+        case "llm_gateway_failed":
+        case "synthesis_unparseable":
+        case "synthesis_missing_patch":
+        case "patch_shape_invalid":
+            return { reason: code, retryable: true };
+    }
+    // Legacy string-matching fallback (older services send no `code`).
+    if (status === 409) {
+        if (/already pending/i.test(message))
+            return { reason: "proposal_pending", retryable: true };
+        if (/still being enriched/i.test(message))
+            return { reason: "entries_enriching", retryable: true };
+        if (/not configured/i.test(message))
+            return { reason: "llm_unconfigured", retryable: false };
+        return { reason: "conflict", retryable: true };
+    }
+    if (status === 400 && /empt/i.test(message))
+        return { reason: "library_empty", retryable: true };
+    return null;
+}
+export function register(deps) {
+    const { server } = deps;
+    function getClient(region) {
+        const token = deps.getAuthToken?.(region) || "";
+        return new MiddlewareServiceClient(deps.getApiBase(region), token);
+    }
+    /**
+     * GET /:id returns the computed-state block (headVersion/state/drift), but
+     * the WRITE endpoints (PATCH /:id, POST /:id/proposal/apply, DELETE
+     * /:id/proposal) return the raw blueprint row without it. headVersion is
+     * the next edit's CAS base, so it must never be reported as undefined —
+     * re-read when the computed fields are missing. If the re-read ALSO fails,
+     * the write still succeeded: return the raw row plus a stateReadError so
+     * the tool can mark the response partial instead of claiming a complete
+     * computed-state result.
+     */
+    async function withComputedState(client, workspaceId, bp) {
+        if (bp.headVersion !== undefined && bp.state !== undefined)
+            return { bp };
+        try {
+            return { bp: await client.getBlueprint(workspaceId, bp.id) };
+        }
+        catch (e) {
+            return { bp, stateReadError: String(e?.message ?? e) };
+        }
+    }
+    /** Partial-response marker for a write whose post-write re-read failed. */
+    function stateReadWarning(blueprintId, stateReadError) {
+        return stateReadError
+            ? {
+                warning: `The write succeeded but the post-write state re-read failed (${stateReadError}) — headVersion/state are unknown. blueprint_get blueprintId=${blueprintId} before the next CAS edit.`,
+            }
+            : {};
+    }
+    function resolveRegion(workspaceId, explicit) {
+        if (explicit)
+            return explicit;
+        return deps.state.getWorkspaceRegion(workspaceId) ?? undefined;
+    }
+    // ── blueprint_list ─────────────────────────────────────────
+    server.tool("blueprint_list", "List a workspace's blueprints: id, name, computed state (never_synced | building | build_failed | job_ahead | spec_stale | job_stale | in_sync), drift flags, and the linked job coordinates (middlewareId/routeId/buildId). Start of a blueprints pass: for any blueprint not in_sync, call resolve_blueprint_state on it and follow the returned nextActions.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        region: regionParam,
+    }, async ({ workspaceId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const blueprints = await getClient(r).listBlueprints(workspaceId);
+            return ok({ blueprints });
+        }
+        catch (e) {
+            return text(`Error listing blueprints: ${e.message}`);
+        }
+    });
+    // ── blueprint_create ───────────────────────────────────────
+    server.tool("blueprint_create", "Create a blueprint — the living spec + context library that will own a job. Two entry paths: (a) NEW automation: create empty, then feed the library with blueprint_add_entry and run blueprint_synthesize; (b) BACKFILL an existing job: pass routeId + middlewareId to link it, then blueprint_import_cases adopts the job's test cases into the spec. After creating, resolve_blueprint_state tells you the next verb.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        name: z.string().describe("Blueprint name"),
+        document: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Initial BlueprintDocument (defaults to the empty skeleton). Usually omit — the library + synthesize fills it."),
+        routeId: z
+            .string()
+            .optional()
+            .describe("Link an EXISTING job at creation (backfill). blueprint_build then rebuilds that job instead of creating a new one. Requires middlewareId."),
+        middlewareId: z
+            .string()
+            .optional()
+            .describe("Router owning routeId (required together with routeId)."),
+        region: regionParam,
+    }, async ({ workspaceId, name, document, routeId, middlewareId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const blueprint = await getClient(r).createBlueprint(workspaceId, {
+                name,
+                document: document,
+                routeId,
+                middlewareId,
+            });
+            return ok({
+                status: "created",
+                blueprint,
+                nextActions: [
+                    routeId
+                        ? `Linked to existing job ${routeId} — blueprint_import_cases blueprintId=${blueprint.id} to adopt its test cases, then feed the library and synthesize.`
+                        : `Feed the library: blueprint_add_entry blueprintId=${blueprint.id} (SOPs, Looms, notes, walkthroughs), then blueprint_synthesize.`,
+                ],
+            });
+        }
+        catch (e) {
+            return text(`Error creating blueprint: ${e.message}`);
+        }
+    });
+    // ── blueprint_get ──────────────────────────────────────────
+    server.tool("blueprint_get", "Get a blueprint: the full spec document, computed state, both drift summaries, and the inbox (document.openQuestions + pendingProposal). This is the raw read — headVersion here is the baseVersion for blueprint_update's CAS, and pendingProposal's baseVersion/basedOnSeq are the coordinates blueprint_apply_proposal requires. For 'what should I do next', prefer resolve_blueprint_state, which turns this state into concrete tool calls.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const blueprint = await getClient(r).getBlueprint(workspaceId, blueprintId);
+            return ok({
+                blueprint,
+                inbox: {
+                    openQuestions: blueprint.document?.openQuestions ?? [],
+                    pendingProposal: blueprint.pendingProposal
+                        ? {
+                            summary: blueprint.pendingProposal.summary,
+                            baseVersion: blueprint.pendingProposal.baseVersion,
+                            basedOnSeq: blueprint.pendingProposal.basedOnSeq,
+                            createdAt: blueprint.pendingProposal.createdAt,
+                        }
+                        : null,
+                },
+            });
+        }
+        catch (e) {
+            return text(`Error fetching blueprint: ${e.message}`);
+        }
+    });
+    // ── blueprint_update ───────────────────────────────────────
+    server.tool("blueprint_update", "Edit the spec document directly: `document` replaces wholesale, `patch` is the section-level merge (goal/schemas/openQuestions replaced, environment shallow-merged, screens/steps upserted by id, credentials by key, exampleCases by name). ALWAYS pass baseVersion (headVersion from blueprint_get / resolve_blueprint_state) — it is compare-and-swap: a 409 means the blueprint moved past your read, so RE-READ with blueprint_get and re-author the edit against the new head; never retry blindly. Prefer the synthesize->apply path for library-derived changes; direct edits are for surgical fixes. A successful document change snapshots a version and makes the job stale (blueprint_build to re-sync).", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        name: z.string().optional().describe("Rename the blueprint"),
+        document: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Full document replacement (BlueprintDocument)"),
+        patch: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Section-level merge (BlueprintPatch shape)"),
+        note: z
+            .string()
+            .optional()
+            .describe('Version note, e.g. "agent: added screen 3"'),
+        baseVersion: z
+            .number()
+            .optional()
+            .describe("Optimistic concurrency: the headVersion this edit was authored against. REQUIRED for document/patch edits (409 when the blueprint has moved past it). Omittable only for writes that cannot conflict (rename)."),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, name, document, patch, note, baseVersion, region }) => {
+        // CAS is the protocol, not a suggestion: document edits without a
+        // baseVersion would silently last-write-win over concurrent editors.
+        // Only conflict-free writes (rename) may omit it.
+        if ((document !== undefined || patch !== undefined) && baseVersion === undefined) {
+            return ok({
+                status: "blocked",
+                blocked: {
+                    reason: "base_version_required",
+                    retryable: true,
+                    message: "Document edits require baseVersion (compare-and-swap). Read headVersion first, author the edit against it, then retry.",
+                },
+                nextActions: [
+                    `blueprint_get blueprintId=${blueprintId} for the current document and headVersion, then retry blueprint_update with baseVersion=<that headVersion>.`,
+                ],
+            });
+        }
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            const { bp: blueprint, stateReadError } = await withComputedState(client, workspaceId, await client.updateBlueprint(workspaceId, blueprintId, {
+                name,
+                document: document,
+                patch: patch,
+                note,
+                baseVersion,
+            }));
+            return ok({
+                status: "updated",
+                headVersion: blueprint.headVersion ?? null,
+                blueprint,
+                ...stateReadWarning(blueprintId, stateReadError),
+            });
+        }
+        catch (e) {
+            if (statusOf(e) === 409) {
+                return ok({
+                    status: "blocked",
+                    blocked: {
+                        reason: "version_conflict",
+                        retryable: true,
+                        message: e.message,
+                    },
+                    nextActions: [
+                        `The blueprint moved past baseVersion ${baseVersion} — blueprint_get blueprintId=${blueprintId} to re-read the document and headVersion, re-author your edit against it, then retry blueprint_update with the new baseVersion.`,
+                    ],
+                });
+            }
+            return text(`Error updating blueprint: ${e.message}`);
+        }
+    });
+    // ── blueprint_add_entry ────────────────────────────────────
+    server.tool("blueprint_add_entry", "Add (or, with entryId, update) a library entry — the way you feed a blueprint context. Context kinds (doc/video/url/note/transcript/data-source/walkthrough) feed synthesis; resource kinds (screen-map/anchor/screenshot) are runtime-referenceable as entry://<id>#<fragment>. Enrichable kinds (doc/video/url with a url or blobRef) start status=pending and are enriched to text by a worker — poll blueprint_list_entries before synthesizing. For file uploads: blueprint_entry_upload_url first, PUT the bytes, then pass the returned blobRef here. VM WALKTHROUGH MODE (get_skill 'blueprint-vm-walkthrough'): create the walkthrough entry IMMEDIATELY when the session starts and PATCH it (entryId + content) after EVERY step — crash resilience. Every write bumps librarySeq, so the spec becomes spec_stale until the next blueprint_synthesize.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        entryId: z
+            .string()
+            .optional()
+            .describe("PATCH mode: update this existing entry (title/text/url/content only) instead of creating one. A new url re-queues enrichment."),
+        kind: entryKindParam.optional().describe("Entry kind — required when creating, ignored in PATCH mode (kind is immutable)."),
+        title: z.string().optional().describe("Human-readable title (required when creating)"),
+        text: z.string().optional().describe("Freeform text (notes, pasted SOPs, answers)"),
+        url: z.string().optional().describe("Link / Loom URL (enriched to a transcript)"),
+        blobRef: z
+            .string()
+            .optional()
+            .describe("gs:// ref from blueprint_entry_upload_url (create mode only)"),
+        content: z
+            .record(z.string(), z.unknown())
+            .optional()
+            .describe("Structured payload: ScreenMapContent for screen-map, AnchorContent for anchor, WalkthroughContent (transcript + filmstrip + artifactRefs) for walkthrough, arbitrary refs for data-source"),
+        fileName: z.string().optional().describe("Original file name (uploads)"),
+        contentType: z.string().optional().describe("MIME type (uploads)"),
+        sizeBytes: z.number().optional().describe("Upload size in bytes"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, entryId, kind, title, text: entryText, url, blobRef, content, fileName, contentType, sizeBytes, region, }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            if (entryId) {
+                const entry = await client.updateBlueprintEntry(workspaceId, blueprintId, entryId, {
+                    ...(title !== undefined ? { title } : {}),
+                    ...(entryText !== undefined ? { text: entryText } : {}),
+                    ...(url !== undefined ? { url } : {}),
+                    ...(content !== undefined ? { content } : {}),
+                });
+                return ok({ status: "updated", entry });
+            }
+            if (!kind || !title) {
+                return text("Creating an entry requires both `kind` and `title` (pass entryId to update an existing one).");
+            }
+            const entry = await client.createBlueprintEntry(workspaceId, blueprintId, {
+                kind,
+                title,
+                text: entryText,
+                url,
+                blobRef,
+                content,
+                fileName,
+                contentType,
+                sizeBytes,
+            });
+            const enriching = entry.status === "pending" || entry.status === "processing";
+            return ok({
+                status: "created",
+                entry,
+                ...(enriching
+                    ? {
+                        note: "Entry is being enriched (status pending) — poll blueprint_list_entries until ready before blueprint_synthesize.",
+                    }
+                    : {}),
+            });
+        }
+        catch (e) {
+            return text(`Error writing blueprint entry: ${e.message}`);
+        }
+    });
+    // ── blueprint_list_entries ─────────────────────────────────
+    server.tool("blueprint_list_entries", "List a blueprint's library entries (full rows: text, url, structured content, enrichment status/transcript/error), or one entry via entryId. status pending/processing means the enrichment worker is still on it — synthesize 409s until every entry is ready; status failed carries the reason in `error` (fix the source or delete the entry). With entryId: revisions=true adds the entry's immutable history (newest first), downloadUrl=true adds a signed read URL for the uploaded blob.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        entryId: z.string().optional().describe("Fetch just this entry"),
+        revisions: z
+            .boolean()
+            .optional()
+            .describe("With entryId: include the entry's revision history (newest first)"),
+        snapshots: z
+            .boolean()
+            .optional()
+            .describe("With revisions=true: include each revision's full snapshot jsonb (default true; false = metadata only)"),
+        downloadUrl: z
+            .boolean()
+            .optional()
+            .describe("With entryId: include a signed read URL for the entry's uploaded blob"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, entryId, revisions, snapshots, downloadUrl, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            if (!entryId) {
+                const entries = await client.listBlueprintEntries(workspaceId, blueprintId);
+                const pending = entries.filter((e) => e.status === "pending" || e.status === "processing").length;
+                const failed = entries.filter((e) => e.status === "failed").length;
+                return ok({
+                    entries,
+                    counts: { total: entries.length, pending, failed },
+                    ...(pending
+                        ? { note: `${pending} entr${pending === 1 ? "y is" : "ies are"} still enriching — wait before blueprint_synthesize.` }
+                        : {}),
+                });
+            }
+            const entry = await client.getBlueprintEntry(workspaceId, blueprintId, entryId);
+            const result = { entry };
+            if (revisions) {
+                result.revisions = await client.listBlueprintEntryRevisions(workspaceId, blueprintId, entryId, { snapshots });
+            }
+            if (downloadUrl) {
+                try {
+                    const dl = await client.createBlueprintEntryDownloadUrl(workspaceId, blueprintId, entryId);
+                    result.downloadUrl = dl.downloadUrl;
+                }
+                catch (e) {
+                    result.downloadUrlError = e.message;
+                }
+            }
+            return ok(result);
+        }
+        catch (e) {
+            return text(`Error listing blueprint entries: ${e.message}`);
+        }
+    });
+    // ── blueprint_entry_upload_url ─────────────────────────────
+    server.tool("blueprint_entry_upload_url", "Get a short-lived signed upload URL for a file that will become a library entry. Handshake: (1) this tool -> { uploadUrl, blobRef, expiresOn }; (2) PUT the bytes to uploadUrl (plain PUT with the file's Content-Type; no extra headers needed — works from anywhere, including FROM INSIDE A VM via vm_execute_script with Python requests.put, the walkthrough screenshot path); (3) blueprint_add_entry with the returned blobRef. 409 means blob storage isn't configured on the service.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        fileName: z.string().describe("Original file name, e.g. 'step-3-invoice-screen.png'"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, fileName, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const result = await getClient(r).createBlueprintEntryUploadUrl(workspaceId, blueprintId, fileName);
+            return ok({
+                ...result,
+                nextActions: [
+                    "PUT the file bytes to uploadUrl (plain PUT with the file's Content-Type) before expiresOn.",
+                    `Then blueprint_add_entry blueprintId=${blueprintId} with blobRef='${result.blobRef}' (kind screenshot/doc/video as appropriate).`,
+                ],
+            });
+        }
+        catch (e) {
+            if (statusOf(e) === 409) {
+                return ok({
+                    status: "blocked",
+                    blocked: {
+                        reason: "blob_storage_unconfigured",
+                        retryable: false,
+                        message: e.message,
+                    },
+                    nextActions: [
+                        "Blob storage is not configured on this middleware-service deployment — use url/text entries instead, or escalate to configure JOB_ARTIFACTS_BUCKET and GCS signing credentials.",
+                    ],
+                });
+            }
+            return text(`Error creating upload URL: ${e.message}`);
+        }
+    });
+    // ── blueprint_synthesize ───────────────────────────────────
+    server.tool("blueprint_synthesize", "Synthesize a spec proposal from the library (LLM). Produces ONE pending proposal for review — it is NEVER applied silently; blueprint_apply_proposal is the gate. Call after feeding entries (state no_spec) or after the library moved past the spec (state spec_stale) — and answer ALL open questions FIRST so one synthesis folds every answer in (don't loop answer->synthesize per question). Synchronous and can take a while on large libraries; on timeout, poll blueprint_get — the proposal may have landed anyway. Blocked responses are structured: blocked.reason = proposal_pending (review or pass replace=true) | entries_enriching (poll blueprint_list_entries) | llm_unconfigured (escalate) | library_empty (blueprint_add_entry first).", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        instructions: z
+            .string()
+            .optional()
+            .describe("Steering for this run, e.g. 'focus on the new refund SOP'"),
+        replace: z
+            .boolean()
+            .optional()
+            .describe("Replace a pending proposal instead of blocking on it"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, instructions, replace, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const blueprint = await getClient(r).synthesizeBlueprint(workspaceId, blueprintId, { replace, instructions });
+            const proposal = blueprint.pendingProposal;
+            return ok({
+                status: "proposal_ready",
+                proposal,
+                nextActions: proposal
+                    ? [
+                        `Review the proposal (summary: ${JSON.stringify(proposal.summary)}), then blueprint_apply_proposal blueprintId=${blueprintId} baseVersion=${proposal.baseVersion} proposalBasedOnSeq=${proposal.basedOnSeq} — or blueprint_reject_proposal to discard.`,
+                    ]
+                    : [
+                        `Synthesis returned no pending proposal — blueprint_get blueprintId=${blueprintId} to inspect.`,
+                    ],
+            });
+        }
+        catch (e) {
+            const block = classifySynthesizeBlock(statusOf(e), e.message, codeOf(e));
+            if (block) {
+                const nextActions = [];
+                if (block.reason === "proposal_pending") {
+                    nextActions.push(`A proposal is already pending — review it (blueprint_get_proposal blueprintId=${blueprintId}) and apply/reject, or re-run with replace=true to overwrite it.`);
+                }
+                else if (block.reason === "entries_enriching") {
+                    nextActions.push(`Entries are still enriching — poll blueprint_list_entries blueprintId=${blueprintId} until counts.pending is 0, then retry.`);
+                }
+                else if (block.reason === "llm_unconfigured") {
+                    nextActions.push("The service has no synthesis LLM configured (MINICOR_LLMS_API_KEY) — escalate to an operator; this is not retryable from here.");
+                }
+                else if (block.reason === "library_empty") {
+                    nextActions.push(`The library is empty — blueprint_add_entry blueprintId=${blueprintId} with SOPs/notes/links first.`);
+                }
+                else if ([
+                    "llm_gateway_failed",
+                    "synthesis_unparseable",
+                    "synthesis_missing_patch",
+                    "patch_shape_invalid",
+                ].includes(block.reason)) {
+                    nextActions.push(`The synthesis LLM leg failed (${block.reason}) — retry blueprint_synthesize blueprintId=${blueprintId} once; escalate to an operator if it fails again.`);
+                }
+                return ok({
+                    status: "blocked",
+                    blocked: { ...block, message: e.message },
+                    nextActions,
+                });
+            }
+            return text(`Error synthesizing blueprint: ${e.message}`);
+        }
+    });
+    // ── blueprint_get_proposal ─────────────────────────────────
+    server.tool("blueprint_get_proposal", "Read the pending synthesis proposal for review: the section-level patch, regenerated SOP, one-paragraph summary, and per-claim citations (entryId + provenance extracted|inferred|ambiguous — scrutinize 'inferred' and 'ambiguous' claims before applying). Returns the exact apply coordinates: blueprint_apply_proposal requires this proposal's baseVersion AND basedOnSeq, so a concurrent resynthesize can never swap a different proposal under your review.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const blueprint = await getClient(r).getBlueprint(workspaceId, blueprintId);
+            const proposal = blueprint.pendingProposal;
+            if (!proposal) {
+                return ok({
+                    status: "no_pending_proposal",
+                    nextActions: [
+                        `No proposal is pending — blueprint_synthesize blueprintId=${blueprintId} to produce one (state ${blueprint.state}).`,
+                    ],
+                });
+            }
+            return ok({
+                proposal,
+                applyWith: {
+                    baseVersion: proposal.baseVersion,
+                    proposalBasedOnSeq: proposal.basedOnSeq,
+                },
+                nextActions: [
+                    `Apply: blueprint_apply_proposal blueprintId=${blueprintId} baseVersion=${proposal.baseVersion} proposalBasedOnSeq=${proposal.basedOnSeq}. Reject: blueprint_reject_proposal blueprintId=${blueprintId}.`,
+                ],
+            });
+        }
+        catch (e) {
+            return text(`Error fetching proposal: ${e.message}`);
+        }
+    });
+    // ── blueprint_apply_proposal ───────────────────────────────
+    server.tool("blueprint_apply_proposal", "Apply the pending proposal you reviewed: patch + SOP land as one validated, version-snapshotted document update, and specBasedOnSeq is stamped. Requires the reviewed proposal's coordinates (baseVersion + proposalBasedOnSeq from blueprint_get_proposal): the tool sends proposalBasedOnSeq with the apply so the service atomically REFUSES (409 proposal_mismatch) if the pending proposal is no longer the one you reviewed (a concurrent resynthesize swapped it); it also re-reads and checks before POSTing as defense in depth. After a successful apply the spec is ahead of the job (job_stale) — blueprint_build is the next verb, after answering any openQuestions the new spec carries.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        baseVersion: z
+            .number()
+            .describe("The reviewed proposal's baseVersion (from blueprint_get_proposal.applyWith)"),
+        proposalBasedOnSeq: z
+            .number()
+            .describe("The reviewed proposal's basedOnSeq (from blueprint_get_proposal.applyWith)"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, baseVersion, proposalBasedOnSeq, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            // Pre-flight re-read: newer services validate basedOnSeq atomically
+            // in the apply request (409 proposal_mismatch), but OLDER deployments
+            // ignore the body — this check is their only swap protection, and it
+            // avoids a mutating POST when the mismatch is already visible.
+            const current = await client.getBlueprint(workspaceId, blueprintId);
+            const pending = current.pendingProposal;
+            if (!pending) {
+                return ok({
+                    status: "no_pending_proposal",
+                    note: "No proposal is pending — another writer applied or rejected it. Treat as convergence.",
+                    nextActions: [
+                        `blueprint_get blueprintId=${blueprintId} (or resolve_blueprint_state) to see the current state.`,
+                    ],
+                });
+            }
+            if (pending.baseVersion !== baseVersion ||
+                pending.basedOnSeq !== proposalBasedOnSeq) {
+                return ok({
+                    status: "blocked",
+                    blocked: {
+                        reason: "proposal_swapped",
+                        retryable: true,
+                        message: `The pending proposal (baseVersion ${pending.baseVersion}, basedOnSeq ${pending.basedOnSeq}) is not the one you reviewed (baseVersion ${baseVersion}, basedOnSeq ${proposalBasedOnSeq}) — a concurrent resynthesize replaced it.`,
+                    },
+                    nextActions: [
+                        `Re-review: blueprint_get_proposal blueprintId=${blueprintId}, then apply with the NEW coordinates.`,
+                    ],
+                });
+            }
+            const { bp: blueprint, stateReadError } = await withComputedState(client, workspaceId, 
+            // The reviewed proposal's identity rides along: a service-side
+            // basedOnSeq mismatch 409s (proposal_mismatch) instead of applying
+            // a proposal that was swapped in after the pre-flight check above.
+            await client.applyBlueprintProposal(workspaceId, blueprintId, {
+                basedOnSeq: proposalBasedOnSeq,
+            }));
+            const openQuestions = blueprint.document?.openQuestions ?? [];
+            return ok({
+                status: "applied",
+                headVersion: blueprint.headVersion ?? null,
+                state: blueprint.state ?? null,
+                openQuestions,
+                ...stateReadWarning(blueprintId, stateReadError),
+                nextActions: openQuestions.length
+                    ? [
+                        `The applied spec carries ${openQuestions.length} open question(s) — answer each with blueprint_answer_question, then blueprint_synthesize ONCE to fold the answers, then blueprint_build.`,
+                    ]
+                    : [
+                        `Spec applied (v${blueprint.headVersion}) — blueprint_build blueprintId=${blueprintId} to sync it into the job.`,
+                    ],
+            });
+        }
+        catch (e) {
+            if (statusOf(e) === 409) {
+                // Code-first, message fallback for older deployments — remove the
+                // string match once middleware-service faiz/synthesis-shape-retry
+                // is deployed everywhere.
+                const swapped = codeOf(e) === "proposal_mismatch" ||
+                    (codeOf(e) === undefined && /not the one you reviewed/i.test(e.message));
+                if (swapped) {
+                    return ok({
+                        status: "blocked",
+                        blocked: {
+                            reason: "proposal_swapped",
+                            retryable: true,
+                            message: e.message,
+                        },
+                        nextActions: [
+                            `The pending proposal was replaced after your review (concurrent resynthesize) — re-review it: blueprint_get_proposal blueprintId=${blueprintId}, then apply DELIBERATELY with the NEW baseVersion + proposalBasedOnSeq.`,
+                        ],
+                    });
+                }
+                return ok({
+                    status: "blocked",
+                    blocked: { reason: "spec_moved", retryable: true, message: e.message },
+                    nextActions: [
+                        `The spec changed since this proposal was synthesized — blueprint_reject_proposal blueprintId=${blueprintId}, then blueprint_synthesize again.`,
+                    ],
+                });
+            }
+            if (statusOf(e) === 404) {
+                // "No pending proposal…" is convergence; "Blueprint <id> not
+                // found" is a caller error — don't shape it as success. Match the
+                // body message, not the request path (which contains "proposal").
+                if (!/no pending proposal/i.test(e.message)) {
+                    return text(`Blueprint not found: ${e.message}`);
+                }
+                return ok({
+                    status: "no_pending_proposal",
+                    note: "Apply raced another writer — the proposal is gone. Treat as convergence.",
+                    nextActions: [`blueprint_get blueprintId=${blueprintId} for the current state.`],
+                });
+            }
+            return text(`Error applying proposal: ${e.message}`);
+        }
+    });
+    // ── blueprint_reject_proposal ──────────────────────────────
+    server.tool("blueprint_reject_proposal", "Reject (discard) the pending proposal — use when the synthesis got it wrong or the spec moved underneath it. A 404 ('no pending proposal') is success-shaped: someone else already applied or rejected it, so the outcome you wanted (no pending proposal blocking synthesize) holds either way. Follow with blueprint_synthesize (optionally with steering `instructions`) to produce a better one.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            const { bp: blueprint, stateReadError } = await withComputedState(client, workspaceId, await client.rejectBlueprintProposal(workspaceId, blueprintId));
+            return ok({
+                status: "rejected",
+                state: blueprint.state ?? null,
+                ...stateReadWarning(blueprintId, stateReadError),
+                nextActions: [
+                    `blueprint_synthesize blueprintId=${blueprintId} (pass instructions to steer the retry).`,
+                ],
+            });
+        }
+        catch (e) {
+            if (statusOf(e) === 404) {
+                // Same discrimination as apply: a missing blueprint is not
+                // success-shaped convergence.
+                if (!/no pending proposal/i.test(e.message)) {
+                    return text(`Blueprint not found: ${e.message}`);
+                }
+                return ok({
+                    status: "already_gone",
+                    note: "No proposal was pending — another writer already applied or rejected it. Success-shaped: nothing is blocking synthesize.",
+                    nextActions: [`blueprint_get blueprintId=${blueprintId} for the current state.`],
+                });
+            }
+            return text(`Error rejecting proposal: ${e.message}`);
+        }
+    });
+    // ── blueprint_answer_question ──────────────────────────────
+    server.tool("blueprint_answer_question", "Answer ONE open synthesis question atomically: the service removes it from document.openQuestions, stores the answer as a note entry, and snapshots a version in a single transaction. `question` must match the openQuestions text EXACTLY (from blueprint_get / resolve_blueprint_state). A 404 means another writer already answered it — that is CONVERGENCE, not failure; move to the next question. Builder questions (build run needs_input) are NOT answered here — use answer_build_question. DRIFT NOTE: each answer bumps librarySeq, so the spec goes spec_stale — answer ALL open questions first, then run blueprint_synthesize ONCE; never loop answer->synthesize per question.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        question: z
+            .string()
+            .describe("The open question being answered — EXACT text from document.openQuestions"),
+        answer: z.string().describe("The answer (stored as a note library entry)"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, question, answer, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        const client = getClient(r);
+        try {
+            const blueprint = await client.answerBlueprintQuestion(workspaceId, blueprintId, question, answer);
+            const remaining = blueprint.document?.openQuestions ?? [];
+            return ok({
+                status: "answered",
+                remainingOpenQuestions: remaining,
+                driftNote: "The answer was stored as a note entry, so the spec is now spec_stale. Answer the remaining questions first, then blueprint_synthesize ONCE to fold every answer in.",
+                nextActions: remaining.length
+                    ? remaining.map((q) => `blueprint_answer_question blueprintId=${blueprintId} question=${JSON.stringify(q)}`)
+                    : [
+                        `All questions answered — blueprint_synthesize blueprintId=${blueprintId} to fold the answers into the spec.`,
+                    ],
+            });
+        }
+        catch (e) {
+            if (statusOf(e) === 404) {
+                // Deploy skew: an older service without the atomic endpoint 404s the
+                // ROUTE itself ("Cannot POST ..."). Fall back to the patch-based
+                // two-step (note entry + openQuestions patch with baseVersion CAS).
+                if (/cannot post/i.test(e.message)) {
+                    return answerViaPatchFallback(client, workspaceId, blueprintId, question, answer);
+                }
+                // The service 404s BOTH a missing blueprint ("Blueprint <id> not
+                // found") and a not-open question ("Open question not found…") —
+                // only the latter is convergence. Discriminate on the body message
+                // (not the request path, which always contains "questions") until
+                // a structured code ships for these.
+                if (!/question (is )?not (open|found)|open question not found/i.test(e.message)) {
+                    return text(`Blueprint not found: ${e.message}`);
+                }
+                return ok({
+                    status: "already_answered",
+                    note: "The question is not open — another writer answered it (or it never existed with this exact text). Treat as CONVERGENCE, not failure.",
+                    nextActions: [
+                        `blueprint_get blueprintId=${blueprintId} for the current openQuestions (match text exactly).`,
+                    ],
+                });
+            }
+            return text(`Error answering question: ${e.message}`);
+        }
+    });
+    /**
+     * Deploy-skew fallback for blueprint_answer_question: older services lack
+     * POST /:id/questions/answer. Emulate it non-atomically — note entry first
+     * (evidence preserved even if the patch loses a race), then a baseVersion-
+     * guarded openQuestions patch.
+     */
+    async function answerViaPatchFallback(client, workspaceId, blueprintId, question, answer) {
+        try {
+            const blueprint = await client.getBlueprint(workspaceId, blueprintId);
+            const openQuestions = blueprint.document?.openQuestions ?? [];
+            if (!openQuestions.includes(question)) {
+                return ok({
+                    status: "already_answered",
+                    note: "The question is not in openQuestions — treat as convergence.",
+                    nextActions: [`blueprint_get blueprintId=${blueprintId} for the current openQuestions.`],
+                });
+            }
+            const entry = await client.createBlueprintEntry(workspaceId, blueprintId, {
+                kind: "note",
+                title: `Answer: ${question.slice(0, 120)}`,
+                text: answer,
+                content: { answersQuestion: question },
+            });
+            try {
+                await client.updateBlueprint(workspaceId, blueprintId, {
+                    patch: { openQuestions: openQuestions.filter((q) => q !== question) },
+                    note: `agent: answered "${question.slice(0, 80)}"`,
+                    baseVersion: blueprint.headVersion,
+                });
+            }
+            catch (patchErr) {
+                return ok({
+                    status: "partial",
+                    note: `Answer stored as note entry ${entry.id}, but removing the question from openQuestions failed (${patchErr.message}). Legacy-service fallback path (non-atomic).`,
+                    nextActions: [
+                        `blueprint_get blueprintId=${blueprintId}, then blueprint_update with patch.openQuestions minus the answered question and the fresh baseVersion.`,
+                    ],
+                });
+            }
+            return ok({
+                status: "answered",
+                note: "Answered via the legacy patch fallback (this service lacks the atomic questions/answer endpoint).",
+                driftNote: "The answer note bumped librarySeq — answer remaining questions, then blueprint_synthesize ONCE.",
+                remainingOpenQuestions: openQuestions.filter((q) => q !== question),
+            });
+        }
+        catch (e) {
+            return text(`Error answering question (fallback path): ${e.message}`);
+        }
+    }
+    // ── blueprint_build ────────────────────────────────────────
+    server.tool("blueprint_build", "Sync the spec into its Job (the primary build verb): validates the spec, ensures the router + route exist, upserts judge test cases from exampleCases (content-hash idempotent), attaches spec + library + resolved resource refs as the builder artifact, and queues/folds into a build run. RETURNS THE HANDOFF ARTIFACT: { middlewareId, routeId, buildId, testCaseIds } — the coordinates the whole jobs toolset (get_build_status, run_tests, resolve_job_state, publish_job) takes over with. Precondition enforced here: if the linked build run is needs_input, this returns blocked instead of syncing (the service would fold cases WITHOUT re-queueing the builder) — answer_build_question first. A 400 means the spec isn't syncable and carries the problem list.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        instructions: z
+            .string()
+            .optional()
+            .describe('Operator instructions to the job builder for this build, e.g. "reuse workflow 2136 for the export step" — the builder must follow them.'),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, instructions, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            const current = await client.getBlueprint(workspaceId, blueprintId);
+            if (current.buildStatus === "needs_input" && current.middlewareId && current.routeId) {
+                return ok({
+                    status: "blocked",
+                    blocked: {
+                        reason: "build_needs_input",
+                        retryable: true,
+                        message: `Build ${current.buildId} is waiting on answers — syncing now would fold cases without re-queueing the builder.`,
+                    },
+                    nextActions: [
+                        `Answer the builder's questions first: get_build_status workspaceId=${workspaceId} middlewareId=${current.middlewareId} routeId=${current.routeId} buildId=${current.buildId}, then answer_build_question per open question. The build re-queues automatically when none remain.`,
+                    ],
+                });
+            }
+            const result = await client.syncBlueprint(workspaceId, blueprintId, instructions);
+            return ok({
+                status: "build_queued",
+                ...result,
+                nextActions: [
+                    `Poll the build: blueprint_build_status blueprintId=${blueprintId} (or get_build_status workspaceId=${workspaceId} middlewareId=${result.middlewareId} routeId=${result.routeId} buildId=${result.buildId}).`,
+                    `When the build is green: run_tests workspaceId=${workspaceId} middlewareId=${result.middlewareId} routeId=${result.routeId} variant=draft, then publish_job. resolve_job_state gives the job-side loop.`,
+                ],
+            });
+        }
+        catch (e) {
+            if (statusOf(e) === 400) {
+                return ok({
+                    status: "blocked",
+                    blocked: { reason: "spec_not_syncable", retryable: true, message: e.message },
+                    nextActions: [
+                        `Fix the listed problems in the spec (blueprint_update with baseVersion, or re-run the synthesize->apply loop), then retry blueprint_build blueprintId=${blueprintId}.`,
+                    ],
+                });
+            }
+            return text(`Error building blueprint: ${e.message}`);
+        }
+    });
+    // ── blueprint_build_status ─────────────────────────────────
+    server.tool("blueprint_build_status", "Blueprint-side view of the linked build: composes the blueprint's state with the stamped build run (status queued|running|green|failed|needs_input, summary, open questions). needs_input questions come back with answer_build_question coordinates prefilled — try to answer them from the library FIRST (blueprint_list_entries; cite what you find) before escalating to a human. For the full job-side picture (test cases, executions), use resolve_job_state with the same coordinates.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            const blueprint = await client.getBlueprint(workspaceId, blueprintId);
+            if (!blueprint.buildId || !blueprint.middlewareId || !blueprint.routeId) {
+                return ok({
+                    state: blueprint.state,
+                    build: null,
+                    nextActions: [
+                        `No build has been stamped yet — blueprint_build blueprintId=${blueprintId} runs the first sync (resolve_blueprint_state to check the spec is ready).`,
+                    ],
+                });
+            }
+            let build;
+            let buildFetchError;
+            try {
+                build = await client.getBuildRun(workspaceId, blueprint.middlewareId, blueprint.routeId, blueprint.buildId);
+            }
+            catch (e) {
+                buildFetchError = String(e?.message ?? e);
+            }
+            const openQuestions = (build?.questions ?? []).filter((q) => !q.answer);
+            const nextActions = [];
+            if (buildFetchError) {
+                nextActions.push(`The stamped build ${blueprint.buildId} could not be fetched (${buildFetchError}) — this is a READ failure, not 'no build'. Retry blueprint_build_status blueprintId=${blueprintId}, or get_build_status workspaceId=${workspaceId} middlewareId=${blueprint.middlewareId} routeId=${blueprint.routeId} buildId=${blueprint.buildId}; escalate if it persists.`);
+            }
+            if (build?.status === "needs_input") {
+                for (const q of openQuestions) {
+                    nextActions.push(`answer_build_question workspaceId=${workspaceId} middlewareId=${blueprint.middlewareId} routeId=${blueprint.routeId} buildId=${build.id} questionId=${q.id} — "${q.text}" (search the library first: blueprint_list_entries blueprintId=${blueprintId}).`);
+                }
+            }
+            else if (build?.status === "failed") {
+                nextActions.push(`Build failed — read build.summary, fix (spec via blueprint_update / workflows via the jobs loop), then blueprint_build blueprintId=${blueprintId} to re-sync.`);
+            }
+            else if (build?.status === "green") {
+                nextActions.push(`Build is green — run_tests workspaceId=${workspaceId} middlewareId=${blueprint.middlewareId} routeId=${blueprint.routeId} variant=draft, then publish_job.`);
+            }
+            else if (build) {
+                nextActions.push(`Build is ${build.status} — poll blueprint_build_status again, or get_build_status buildId=${build.id} for the raw run.`);
+            }
+            return ok({
+                state: blueprint.state,
+                link: {
+                    middlewareId: blueprint.middlewareId,
+                    routeId: blueprint.routeId,
+                    buildId: blueprint.buildId,
+                },
+                build: build ?? null,
+                ...(buildFetchError ? { buildFetchError } : {}),
+                openQuestions,
+                nextActions,
+            });
+        }
+        catch (e) {
+            return text(`Error fetching build status: ${e.message}`);
+        }
+    });
+    // ── blueprint_import_cases ─────────────────────────────────
+    server.tool("blueprint_import_cases", "Adopt the linked job's test cases into the spec's exampleCases (upsert by name) — the job_ahead FOLD-BACK arrow. Use when the job was edited directly (update_job / teach_job / Dev-Mode clones tripped reverse drift) and the direct edits should become spec truth, or right after blueprint_create linked an existing job. After importing, the spec is ahead of the job (job_stale): review it, then blueprint_build re-syncs and re-stamps the drift baseline. The alternative job_ahead exit is blueprint_build alone — rebuild from the spec and OVERWRITE the direct edits.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const blueprint = await getClient(r).importBlueprintCases(workspaceId, blueprintId);
+            return ok({
+                status: "imported",
+                exampleCases: blueprint.document?.exampleCases ?? [],
+                nextActions: [
+                    `Review the imported exampleCases (blueprint_get blueprintId=${blueprintId}), then blueprint_build to re-sync and clear job_ahead.`,
+                ],
+            });
+        }
+        catch (e) {
+            if (statusOf(e) === 400) {
+                return ok({
+                    status: "blocked",
+                    blocked: { reason: "nothing_to_import", retryable: false, message: e.message },
+                    nextActions: [
+                        "The blueprint isn't linked to a job, or the job has no test cases — nothing to fold back.",
+                    ],
+                });
+            }
+            return text(`Error importing cases: ${e.message}`);
+        }
+    });
+    // ── blueprint_list_versions ────────────────────────────────
+    server.tool("blueprint_list_versions", "List a blueprint's spec version snapshots (newest first) — every document change (apply, direct update, answered question) snapshots one, with its note. Pass version to fetch one full snapshot (e.g. to diff what a proposal changed, or to recover a document to re-author against after a CAS 409). Entry-level history lives on blueprint_list_entries revisions=true instead.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID"),
+        version: z.number().optional().describe("Fetch one full version snapshot"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, version, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            if (version != null) {
+                const snapshot = await client.getBlueprintVersion(workspaceId, blueprintId, version);
+                return ok({ version: snapshot });
+            }
+            const versions = await client.listBlueprintVersions(workspaceId, blueprintId);
+            return ok({ versions });
+        }
+        catch (e) {
+            return text(`Error listing blueprint versions: ${e.message}`);
+        }
+    });
+    // ── resolve_blueprint_state ────────────────────────────────
+    server.tool("resolve_blueprint_state", "The 'where am I in the blueprint loop?' call — START HERE when working a blueprint (the sibling of resolve_job_state, one layer up). One call fetches the blueprint (state + drift + proposal + open questions), its library entries (enrichment status), and the linked build run, then returns an UNFOLDED state (no_context | enriching | no_spec | proposal_pending | needs_answers | building | needs_input | build_failed | job_ahead | spec_stale | job_stale | in_sync — every state maps to one verb), blockers[] (enrichment_failed / builder_stalled / question_needs_human — the escalation surface), and ordered nextActions with the concrete tool calls prefilled. The loop it drives: add entries -> synthesize -> answer questions -> apply proposal -> blueprint_build -> the jobs loop (resolve_job_state) takes over.", {
+        workspaceId: z.number().describe("Workspace ID"),
+        blueprintId: z.string().describe("Blueprint ID to resolve"),
+        region: regionParam,
+    }, async ({ workspaceId, blueprintId, region }) => {
+        const r = resolveRegion(workspaceId, region);
+        try {
+            const client = getClient(r);
+            const [bp, entriesRead] = await Promise.all([
+                client.getBlueprint(workspaceId, blueprintId),
+                client.listBlueprintEntries(workspaceId, blueprintId).then((entries) => ({ entries }), (e) => ({ entriesError: String(e?.message ?? e) })),
+            ]);
+            // The decision table needs the library to be TRUSTWORTHY: a failed
+            // entries read must not masquerade as an empty library (no_context /
+            // no_spec would direct the agent to feed or synthesize against a
+            // library it never saw). Degrade explicitly instead.
+            if ("entriesError" in entriesRead) {
+                return ok({
+                    status: "degraded",
+                    backendState: bp.state,
+                    error: `Could not read the blueprint's library: ${entriesRead.entriesError}`,
+                    nextActions: [
+                        `The library read failed, so the unfolded state cannot be computed — retry resolve_blueprint_state blueprintId=${blueprintId} (blueprint_get gives the spec-side view meanwhile); escalate if it persists.`,
+                    ],
+                });
+            }
+            const entries = entriesRead.entries;
+            let build;
+            if (bp.buildId && bp.middlewareId && bp.routeId) {
+                try {
+                    build = await client.getBuildRun(workspaceId, bp.middlewareId, bp.routeId, bp.buildId);
+                }
+                catch (buildErr) {
+                    // Same trust rule as the entries read above: a failed build
+                    // read must not masquerade as "no build" — needs_input
+                    // questions and stall detection would silently vanish and the
+                    // resolver could report in_sync with "nothing to do".
+                    return ok({
+                        status: "degraded",
+                        backendState: bp.state,
+                        error: `Could not read the linked build run ${bp.buildId}: ${String(buildErr?.message ?? buildErr)}`,
+                        nextActions: [
+                            `The linked build read failed, so the unfolded state cannot be computed — retry resolve_blueprint_state blueprintId=${blueprintId} (blueprint_get gives the spec-side view meanwhile); escalate if it persists.`,
+                        ],
+                    });
+                }
+            }
+            const pendingEntries = entries.filter((e) => e.status === "pending" || e.status === "processing");
+            const failedEntries = entries.filter((e) => e.status === "failed");
+            const openQuestions = bp.document?.openQuestions ?? [];
+            const emptySpec = specIsEmpty(bp);
+            const buildQuestions = (build?.questions ?? []).filter((q) => !q.answer);
+            // Is the spec_stale drift ONLY answer-note entries? Then ONE
+            // synthesize folds them — the dedupe flag that stops the
+            // answer->synthesize->spec_stale loop.
+            const entriesById = new Map(entries.map((e) => [e.id, e]));
+            const answerNotesOnly = bp.drift.newEntries.length > 0 &&
+                bp.drift.newEntries.every((d) => {
+                    const entry = entriesById.get(d.id);
+                    return (entry?.kind === "note" &&
+                        Boolean(entry.content?.answersQuestion));
+                });
+            // ── The decision table: fold backend + library facts into ONE state ──
+            // Backend-loud states keep their precedence; never_synced/spec_stale
+            // unfold into the pre-build sub-states.
+            let state;
+            if (bp.buildStatus === "needs_input")
+                state = "needs_input";
+            else if (bp.state === "building")
+                state = "building";
+            else if (bp.state === "build_failed")
+                state = "build_failed";
+            else if (bp.state === "job_ahead")
+                state = "job_ahead";
+            else if (bp.hasPendingProposal)
+                state = "proposal_pending";
+            else if (pendingEntries.length > 0)
+                state = "enriching";
+            else if (openQuestions.length > 0)
+                state = "needs_answers";
+            else if (entries.length === 0 && emptySpec)
+                state = "no_context";
+            else if (emptySpec)
+                state = "no_spec";
+            // The service folds UNLINKED blueprints to never_synced regardless of
+            // drift, so spec_stale must come from the specStale boolean (library
+            // moved past the spec) — synthesize-first beats build-now.
+            else if (bp.specStale || bp.state === "spec_stale")
+                state = "spec_stale";
+            else if (bp.state === "job_stale" || bp.state === "never_synced")
+                state = "job_stale";
+            else
+                state = "in_sync";
+            // ── Blockers: the escalation surface ──
+            const blockers = [];
+            if (failedEntries.length > 0) {
+                blockers.push({
+                    kind: "enrichment_failed",
+                    hint: "Enrichment failed for these entries — synthesis will proceed without their content. Fix the source (blueprint_add_entry entryId=<id> with a corrected url re-queues enrichment) or accept the gap.",
+                    entries: failedEntries.map((e) => ({
+                        id: e.id,
+                        title: e.title,
+                        error: e.error,
+                    })),
+                });
+            }
+            if (build?.status === "queued") {
+                const queuedSince = Date.parse((build.startedAt ?? build.createdAt ?? ""));
+                const queuedForMs = Number.isFinite(queuedSince)
+                    ? Date.now() - queuedSince
+                    : undefined;
+                if (queuedForMs !== undefined && queuedForMs > BUILDER_STALL_MS) {
+                    blockers.push({
+                        kind: "builder_stalled",
+                        queuedForMs,
+                        hint: `Build ${build.id} has been queued for ${Math.round(queuedForMs / 1000)}s — the builder may be down. Escalate, or cancel_build and drive the draft manually via the jobs loop.`,
+                    });
+                }
+            }
+            if (buildQuestions.length > 0) {
+                blockers.push({
+                    kind: "question_needs_human",
+                    questions: buildQuestions.map((q) => ({ id: q.id, text: q.text })),
+                    hint: "Builder questions are YOURS to try first: read the library (blueprint_list_entries), cite what you find in answer_build_question. Escalate to a human only when the library genuinely lacks the answer — then checkpoint the blocker.",
+                });
+            }
+            // ── nextActions: the concrete next tool calls per state ──
+            const nextActions = [];
+            const linkCoords = bp.middlewareId && bp.routeId
+                ? `workspaceId=${workspaceId} middlewareId=${bp.middlewareId} routeId=${bp.routeId}`
+                : null;
+            switch (state) {
+                case "no_context":
+                    nextActions.push(`Empty blueprint — feed the library first: blueprint_add_entry blueprintId=${blueprintId} (paste SOPs as text, add Loom/doc urls, or run the VM walkthrough: get_skill name='blueprint-vm-walkthrough'). Then blueprint_synthesize.`);
+                    break;
+                case "enriching":
+                    nextActions.push(`${pendingEntries.length} entr${pendingEntries.length === 1 ? "y is" : "ies are"} still enriching (${pendingEntries
+                        .map((e) => e.title)
+                        .join(", ")}) — poll blueprint_list_entries blueprintId=${blueprintId} until counts.pending is 0, then blueprint_synthesize.`);
+                    break;
+                case "no_spec":
+                    nextActions.push(`Library is ready but the spec is empty — blueprint_synthesize blueprintId=${blueprintId} to draft the first proposal.`);
+                    break;
+                case "proposal_pending":
+                    nextActions.push(bp.pendingProposal
+                        ? `A proposal is pending review — blueprint_get_proposal blueprintId=${blueprintId}, then blueprint_apply_proposal blueprintId=${blueprintId} baseVersion=${bp.pendingProposal.baseVersion} proposalBasedOnSeq=${bp.pendingProposal.basedOnSeq} (or blueprint_reject_proposal).`
+                        : `A proposal is pending review — blueprint_get_proposal blueprintId=${blueprintId}.`);
+                    break;
+                case "needs_answers":
+                    for (const q of openQuestions) {
+                        nextActions.push(`blueprint_answer_question blueprintId=${blueprintId} question=${JSON.stringify(q)}`);
+                    }
+                    nextActions.push("Answer ALL open questions, THEN blueprint_synthesize once to fold the answers in — don't loop answer->synthesize per question.");
+                    break;
+                case "building":
+                    nextActions.push(`Build ${bp.buildId} is ${bp.buildStatus} — poll blueprint_build_status blueprintId=${blueprintId}${linkCoords ? ` (job-side: get_build_status ${linkCoords} buildId=${bp.buildId})` : ""}. Don't edit the draft underneath it.`);
+                    break;
+                case "needs_input":
+                    for (const q of buildQuestions) {
+                        nextActions.push(`answer_build_question ${linkCoords} buildId=${bp.buildId} questionId=${q.id} — "${q.text}" (search the library first: blueprint_list_entries blueprintId=${blueprintId}).`);
+                    }
+                    if (buildQuestions.length === 0) {
+                        nextActions.push(`Build ${bp.buildId} is needs_input — blueprint_build_status blueprintId=${blueprintId} for its questions.`);
+                    }
+                    break;
+                case "build_failed":
+                    nextActions.push(`Build ${bp.buildId} FAILED — blueprint_build_status blueprintId=${blueprintId} for the summary. Fix at the right level (spec: blueprint_update / workflows: the jobs loop${linkCoords ? ` via resolve_job_state ${linkCoords}` : ""}), then blueprint_build to re-sync.`);
+                    break;
+                case "job_ahead":
+                    nextActions.push(`The job was edited DIRECTLY since the last sync (reverse drift). Either fold the edits back: blueprint_import_cases blueprintId=${blueprintId} (adopts the job's test cases into exampleCases), or rebuild from the spec and overwrite them: blueprint_build blueprintId=${blueprintId}.`);
+                    break;
+                case "spec_stale":
+                    nextActions.push(answerNotesOnly
+                        ? `Library drift is answer notes ONLY (${bp.drift.newEntries.length}) — one blueprint_synthesize blueprintId=${blueprintId} folds them; no further answering needed.`
+                        : `The library moved past the spec (${bp.drift.newEntries.length} new entr${bp.drift.newEntries.length === 1 ? "y" : "ies"}) — blueprint_synthesize blueprintId=${blueprintId} to fold them into a new proposal.`);
+                    break;
+                case "job_stale":
+                    nextActions.push(bp.routeId
+                        ? `The spec is ahead of the job (${bp.drift.unsyncedVersions.length} unsynced version(s)) — blueprint_build blueprintId=${blueprintId} to re-sync.`
+                        : `The spec is ready and no job exists yet — blueprint_build blueprintId=${blueprintId} creates the router + route, upserts judge cases, and queues the builder.`);
+                    break;
+                case "in_sync":
+                    nextActions.push(`In sync — nothing to do. To change behavior: blueprint_add_entry -> blueprint_synthesize -> apply -> blueprint_build.${linkCoords ? ` Job-side status: resolve_job_state ${linkCoords}.` : ""}`);
+                    break;
+            }
+            return ok({
+                blueprint: {
+                    id: bp.id,
+                    name: bp.name,
+                    headVersion: bp.headVersion,
+                    librarySeq: bp.librarySeq,
+                    specBasedOnSeq: bp.specBasedOnSeq,
+                    lastSyncedVersion: bp.lastSyncedVersion,
+                },
+                state,
+                backendState: bp.state,
+                link: bp.middlewareId && bp.routeId
+                    ? { middlewareId: bp.middlewareId, routeId: bp.routeId, buildId: bp.buildId ?? null }
+                    : null,
+                resources: {
+                    total: entries.length,
+                    ready: entries.length - pendingEntries.length - failedEntries.length,
+                    pending: pendingEntries.map((e) => ({ id: e.id, kind: e.kind, title: e.title })),
+                    failed: failedEntries.map((e) => ({
+                        id: e.id,
+                        kind: e.kind,
+                        title: e.title,
+                        error: e.error,
+                    })),
+                },
+                openQuestions,
+                proposal: bp.pendingProposal
+                    ? {
+                        summary: bp.pendingProposal.summary,
+                        baseVersion: bp.pendingProposal.baseVersion,
+                        basedOnSeq: bp.pendingProposal.basedOnSeq,
+                        createdAt: bp.pendingProposal.createdAt,
+                        citations: bp.pendingProposal.citations?.length ?? 0,
+                    }
+                    : null,
+                build: build
+                    ? {
+                        id: build.id,
+                        status: build.status,
+                        openQuestions: buildQuestions,
+                        startedAt: build.startedAt,
+                        completedAt: build.completedAt,
+                    }
+                    : null,
+                drift: { ...bp.drift, answerNotesOnly },
+                blockers,
+                nextActions,
+            });
+        }
+        catch (e) {
+            return text(`Error resolving blueprint state: ${e.message}`);
+        }
+    });
+}
+//# sourceMappingURL=blueprints.js.map