xcoder-dna 0.0.0-stage → 1.3.0

package/dist/protocol/react-contract.js

@@ -0,0 +1,698 @@
+// xcoder:version 3 | xcoder:task task-f1ac77 | xcoder:updated 2026-10-17T04:10:38.741Z | xcoder:subtask code-st-1d0003
+import { z } from "zod";
+import { environmentPromptBlock } from "../util/env-info.js";
+import { detectedCommandsPromptBlock } from "../tools/project-detect.js";
+/**
+ * THE CONTRACT.
+ *
+ * Every turn, in both directions, is exactly this shape. No prose outside
+ * the JSON, no partial objects, no both-action-and-final_answer. A message
+ * that doesn't parse against this schema is never silently "interpreted" —
+ * it's bounced back to the model as a typed protocol_error observation, and
+ * that costs it an iteration. This is what "protocol to adhere to" means in
+ * practice: the parser is the enforcement mechanism, not the prompt wording.
+ */
+export const ReactMessageSchema = z
+    .object({
+    thought: z.string().min(1, "thought must be non-empty"),
+    action: z
+        .object({
+        tool: z.string().min(1),
+        // .optional() matters here, not just cosmetic: under Zod v4, an
+        // `unknown()` field must still have its key present in the object —
+        // a tool call with genuinely no arguments (key omitted entirely,
+        // e.g. after the command->tool alias normalization) would otherwise
+        // fail validation even though the action itself is perfectly valid.
+        input: z.unknown().optional(),
+    })
+        .nullable()
+        .default(null),
+    final_answer: z
+        .object({
+        summary: z.string().min(1),
+        deliverable: z.unknown(),
+        files_touched: z.array(z.string()).default([]),
+        self_check: z
+            .object({
+            ran: z.boolean(),
+            passed: z.boolean(),
+            detail: z.string(),
+        })
+            .optional(),
+    })
+        .nullable()
+        .default(null),
+})
+    .superRefine((msg, ctx) => {
+    const hasAction = msg.action !== null && msg.action !== undefined;
+    const hasFinal = msg.final_answer !== null && msg.final_answer !== undefined;
+    if (hasAction === hasFinal) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "exactly one of `action` or `final_answer` must be non-null, never both, never neither",
+        });
+    }
+});
+/**
+ * Layer 1: Strip outermost XML envelope tags from model output.
+ * Handles tags like <thought>, <thinking>, <response>, <answer>
+ * (case-insensitive, outer-tags only). This prevents "Unexpected token '<'"
+ * parse errors when the model wraps JSON inside XML-style tags.
+ */
+export function stripXmlTags(raw) {
+    const trimmed = raw.trim();
+    const XML_TAG_PATTERN = /^<\s*(\/?)\s*(thought|thinking|response|answer)\s*>\s*/i;
+    const XML_CLOSE_PATTERN = /\s*<\s*\/\s*(thought|thinking|response|answer)\s*>\s*$/i;
+    let result = trimmed;
+    // Remove opening tag (with optional leading slash for self-closing variants)
+    const openMatch = result.match(XML_TAG_PATTERN);
+    if (openMatch && !openMatch[1]) {
+        // Only strip if it's an opening tag (not </tag>)
+        result = result.slice(openMatch[0].length);
+    }
+    // Only remove closing tag if we actually stripped an opening tag.
+    // If no opening tag was matched (e.g. it had attributes), we must
+    // preserve the closing tag too to avoid asymmetric partial stripping.
+    if (openMatch && !openMatch[1]) {
+        result = result.replace(XML_CLOSE_PATTERN, "");
+    }
+    return result;
+}
+/**
+ * Layer 1.5: Escape raw control characters (newline, tab, CR, etc.) that
+ * appear *inside* JSON string literals.
+ *
+ * Root cause this repairs: the JSON spec forbids literal U+0000–U+001F
+ * inside a string value — they must be written as `\n`, `\t`, `\uXXXX`,
+ * etc. Models very frequently violate this when a string value itself
+ * contains multi-line content (e.g. `action.input.content` for a
+ * write_file call carrying markdown/code). `JSON.parse` rejects the whole
+ * payload with "Bad control character in string literal" and none of the
+ * other layers repair it — XML-stripping and outermost-extraction only
+ * fix structural wrapping, not the string contents. Left unrepaired, the
+ * model has to reproduce the *entire* (often large) payload again with
+ * manual escaping, and frequently fails repeatedly, burning tokens each
+ * retry.
+ *
+ * Uses the same string-aware, escape-aware single pass as
+ * extractOutermostJson so it never touches control characters that sit
+ * outside of a string literal (e.g. the newlines a model puts between
+ * prose and the JSON block, which are harmless and should be left alone).
+ */
+export function sanitizeControlCharacters(raw) {
+    const CONTROL_CHAR_ESCAPES = {
+        "\n": "\\n",
+        "\r": "\\r",
+        "\t": "\\t",
+        "\b": "\\b",
+        "\f": "\\f",
+    };
+    let inString = false;
+    let inEscape = false;
+    let result = "";
+    let mutated = false;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inEscape) {
+            inEscape = false;
+            result += ch;
+            continue;
+        }
+        if (ch === "\\" && inString) {
+            inEscape = true;
+            result += ch;
+            continue;
+        }
+        if (ch === '"' && !inEscape) {
+            inString = !inString;
+            result += ch;
+            continue;
+        }
+        if (inString) {
+            const code = ch.charCodeAt(0);
+            if (code >= 0x00 && code <= 0x1f) {
+                result += CONTROL_CHAR_ESCAPES[ch] ?? `\\u${code.toString(16).padStart(4, "0")}`;
+                mutated = true;
+                continue;
+            }
+        }
+        result += ch;
+    }
+    return mutated ? result : raw;
+}
+/**
+ * Layer 2: Extract the outermost balanced {...} JSON block from a string.
+ * Uses a single-pass O(n) brace counter with string-awareness (handles
+ * escaped quotes inside strings). Returns the JSON substring, or empty
+ * string if no balanced braces are found.
+ */
+export function extractOutermostJson(raw) {
+    let braceDepth = 0;
+    let inString = false;
+    let inEscape = false;
+    let start = -1;
+    let end = -1;
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        if (inEscape) {
+            inEscape = false;
+            continue;
+        }
+        if (ch === "\\" && inString) {
+            inEscape = true;
+            continue;
+        }
+        if (ch === '"' && !inEscape) {
+            inString = !inString;
+            continue;
+        }
+        if (inString) {
+            continue;
+        }
+        if (ch === "{") {
+            if (braceDepth === 0) {
+                start = i;
+            }
+            braceDepth++;
+        }
+        else if (ch === "}") {
+            braceDepth--;
+            if (braceDepth === 0 && start !== -1) {
+                end = i;
+                break; // outermost block found, stop scanning
+            }
+            if (braceDepth < 0) {
+                // Unbalanced closing brace before any opening — reset
+                braceDepth = 0;
+                start = -1;
+            }
+        }
+    }
+    if (start !== -1 && end !== -1) {
+        return raw.slice(start, end + 1);
+    }
+    return "";
+}
+/**
+ * Extract the prose text before the first '{' in the raw model output.
+ * Used to backfill missing `thought` fields from the model's opening prose.
+ * Returns trimmed prose, or "" if no '{' is found or it's at position 0.
+ *
+ * Tradeoff: uses the first literal '{' as delimiter, not a full brace-
+ * counting parser. Prose containing '{' before the JSON block (extremely
+ * rare in LLM output) will be truncated. Accepted as an edge case.
+ */
+function extractProsePrefix(raw) {
+    const idx = raw.indexOf("{");
+    if (idx <= 0)
+        return "";
+    return raw.slice(0, idx).trim();
+}
+/**
+ * Layer 3: Normalize known LLM JSON-shape drifts before Zod validation.
+ * Operates on the already-parsed (but not yet schema-validated) object.
+ *
+ * Four drifts repaired, in fixed order:
+ *   1. Missing top-level `thought` — backfilled from prose preceding the JSON.
+ *   2. Bare `{tool, input}` — auto-wrapped as `{action: {tool, input}}`.
+ *   3. `thought` nested inside `action` — hoisted to top level.
+ *   4. Legacy `command` key inside `action` — renamed to `tool` (only when `tool` is absent).
+ *
+ * @param raw   - The post-Layer-1 string (still contains prose prefix if present).
+ * @param json  - The parsed JSON `unknown` object from Layer 2.
+ * @returns     - `{ normalized: unknown; applied: boolean; steps: string[] }`
+ */
+export function normalizeReactShape(raw, json) {
+    if (json === null || typeof json !== "object") {
+        return { normalized: json, applied: false, steps: [] };
+    }
+    const obj = json;
+    let mutated = false;
+    const appliedSteps = [];
+    // ── Step 1: Prose prefix → thought backfill ──
+    const hasThought = "thought" in obj;
+    const thoughtValue = obj.thought;
+    const thoughtEmpty = !hasThought ||
+        thoughtValue === null ||
+        thoughtValue === undefined ||
+        (typeof thoughtValue === "string" && thoughtValue.trim() === "");
+    if (thoughtEmpty) {
+        const prefix = extractProsePrefix(raw);
+        if (prefix.length > 0) {
+            obj.thought = prefix;
+            mutated = true;
+            appliedSteps.push("prose backfill");
+        }
+    }
+    // ── Step 2: Bare {tool, input} → auto-wrap ──
+    // Guard: only when NO `action` key exists, AND `tool` is a non-empty string,
+    // AND this is NOT a bare final_answer shape (AC-8: has summary/deliverable/files_touched).
+    const hasAction = "action" in obj;
+    const hasTool = "tool" in obj;
+    const toolValue = obj.tool;
+    const isBareTool = !hasAction &&
+        hasTool &&
+        typeof toolValue === "string" &&
+        toolValue.length > 0;
+    const hasFinalAnswerKeys = ("summary" in obj && typeof obj.summary === "string" && obj.summary.length > 0) ||
+        "deliverable" in obj ||
+        "files_touched" in obj;
+    if (isBareTool && !hasFinalAnswerKeys) {
+        const actionObj = { tool: obj.tool };
+        if ("input" in obj) {
+            actionObj.input = obj.input;
+        }
+        delete obj.tool;
+        delete obj.input;
+        obj.action = actionObj;
+        mutated = true;
+        appliedSteps.push("bare-tool wrap");
+    }
+    // ── Step 2.5: Arguments → input alias inside action ──
+    // Guard: action exists as non-null object, has `arguments` key,
+    // and does NOT already have an `input` key.
+    // Transform: action.input = action.arguments; delete action.arguments.
+    const actionValForArgs = obj.action;
+    if (actionValForArgs !== null &&
+        typeof actionValForArgs === "object") {
+        const actionObj = actionValForArgs;
+        if ("arguments" in actionObj && !("input" in actionObj)) {
+            actionObj.input = actionObj.arguments;
+            delete actionObj.arguments;
+            mutated = true;
+            appliedSteps.push("arguments→input alias");
+        }
+    }
+    // ── Step 3: Nested thought hoisting ──
+    // Guard: only when action is an object with a `thought` key,
+    // AND top-level thought is missing or empty.
+    const topThoughtEmpty = !("thought" in obj) ||
+        obj.thought === null ||
+        obj.thought === undefined ||
+        (typeof obj.thought === "string" && obj.thought.trim() === "");
+    const actionVal = obj.action;
+    if (topThoughtEmpty &&
+        actionVal !== null &&
+        typeof actionVal === "object" &&
+        "thought" in actionVal) {
+        const actionObj = actionVal;
+        const nestedThought = actionObj.thought;
+        if (typeof nestedThought === "string" &&
+            nestedThought.trim().length > 0) {
+            obj.thought = nestedThought;
+            delete actionObj.thought;
+            mutated = true;
+            appliedSteps.push("nested-thought hoist");
+        }
+    }
+    // ── Step 4: Command → tool alias inside action ──
+    // Guard: action exists as non-null object, has `command` key with
+    // non-empty string value, and does NOT already have a `tool` key.
+    // Transform: action.tool = action.command; delete action.command.
+    const actionValForCmd = obj.action;
+    if (actionValForCmd !== null &&
+        typeof actionValForCmd === "object") {
+        const actionObj = actionValForCmd;
+        const hasCommand = "command" in actionObj &&
+            typeof actionObj.command === "string" &&
+            actionObj.command.length > 0;
+        const hasTool = "tool" in actionObj;
+        if (hasCommand && !hasTool) {
+            actionObj.tool = actionObj.command;
+            delete actionObj.command;
+            mutated = true;
+            appliedSteps.push("command→tool alias");
+        }
+    }
+    return {
+        normalized: obj,
+        applied: mutated,
+        steps: appliedSteps,
+    };
+}
+/**
+ * Layer 5 helper: generates a contextual default thought when the LLM
+ * omitted the required `thought` field but provided a structurally valid
+ * action or final_answer. The [auto] prefix makes recovery visible in
+ * transcripts without blocking the message.
+ */
+function generateDefaultThought(context) {
+    if (context.hasAction) {
+        const tool = context.toolName ? ` ${context.toolName}` : "";
+        return `[auto] calling${tool}`;
+    }
+    if (context.hasFinalAnswer) {
+        return "[auto] final answer";
+    }
+    return "[auto]";
+}
+/**
+ * Layer 5 helper: determines if a Zod validation failure is eligible for
+ * auto-thought recovery. Recovery is allowed when:
+ *   - `thought` is missing or undefined (the primary failure mode)
+ *   - AND exactly one of `action` or `final_answer` is present and
+ *     structurally valid (so we're not recovering a genuinely confused
+ *     message that has both or neither).
+ */
+function canAutoRecover(result, json) {
+    const issues = result.error.issues;
+    const hasThoughtIssue = issues.some((i) => i.path.length === 1 &&
+        i.path[0] === "thought" &&
+        (i.code === z.ZodIssueCode.invalid_type ||
+            i.code === z.ZodIssueCode.too_small));
+    if (!hasThoughtIssue)
+        return false;
+    const hasAction = json.action !== null &&
+        json.action !== undefined &&
+        typeof json.action === "object";
+    const hasFinal = json.final_answer !== null &&
+        json.final_answer !== undefined &&
+        typeof json.final_answer === "object";
+    // Must have exactly one of action/final_answer (mutual exclusion)
+    if (hasAction === hasFinal)
+        return false;
+    // Action must have a tool key with non-empty string value
+    if (hasAction) {
+        const actionObj = json.action;
+        const toolOk = "tool" in actionObj &&
+            typeof actionObj.tool === "string" &&
+            actionObj.tool.length > 0;
+        if (!toolOk)
+            return false;
+    }
+    // Final answer must have summary or deliverable
+    if (hasFinal) {
+        const faObj = json.final_answer;
+        if (!("summary" in faObj || "deliverable" in faObj))
+            return false;
+    }
+    return true;
+}
+/**
+ * Parses a raw model completion against the contract with layered defence.
+ *
+ * Layer 0: trim + markdown fence removal (existing tolerance)
+ * Layer 1: xml tag stripping (prevents "Unexpected token '<'")
+ * Layer 2: outermost-JSON extraction on initial parse failure
+ * Layer 3: normalize known LLM JSON-shape drifts (new)
+ * Layer 4a: prose-only recovery (no `{` → treat full text as thought)
+ * Layer 4b: XML-enveloped prose recovery (has `{` but extraction failed → re-strip XML, treat as thought)
+ * Final gate: Zod ReactMessageSchema.safeParse — no interpretation without validation
+ */
+/**
+ * Extracts a byte-position context window from a SyntaxError thrown by JSON.parse.
+ * Returns the excerpt (±80 chars around the error position) and the byte offset,
+ * or null if the position cannot be extracted.
+ */
+function extractErrorContext(source, error) {
+    const match = error.message.match(/position\s+(\d+)/i);
+    if (!match)
+        return null;
+    const pos = parseInt(match[1], 10);
+    if (isNaN(pos))
+        return null;
+    const start = Math.max(0, pos - 80);
+    const end = Math.min(source.length, pos + 80);
+    return { excerpt: source.slice(start, end), position: pos };
+}
+/**
+ * Builds a diagnostic error string for unrecoverable parse failures.
+ * Includes the original parse error, list of attempted recovery layers,
+ * optional byte-position context window, and a raw input preview.
+ */
+function buildErrorDiagnostic(parseError, layersAttempted, context, rawPreview) {
+    const lines = [
+        `response was not valid JSON: ${parseError}`,
+        `[layers attempted: ${layersAttempted.join(", ")}]`,
+    ];
+    if (context !== null) {
+        lines.push(`[context at byte ${context.position}: …${context.excerpt}…]`);
+    }
+    lines.push(`[raw preview: ${rawPreview}]`);
+    return lines.join("\n");
+}
+export function parseReactMessage(raw) {
+    // Layer 0: trim + markdown fence removal (original tolerance)
+    const stripped = raw
+        .trim()
+        .replace(/^```(?:json)?\s*/i, "")
+        .replace(/\s*```$/i, "");
+    // Attempt 1: direct JSON.parse (with xml stripping)
+    const layer1 = stripXmlTags(stripped);
+    // Layer 1.5: escape raw control characters inside string literals
+    // (e.g. literal newlines in multi-line file content) before any parse
+    // attempt — this is a common failure mode `JSON.parse` cannot recover
+    // from on its own, and letting it through unpatched would defeat the
+    // string-awareness of Layer 2's extraction too.
+    const sanitized = sanitizeControlCharacters(layer1);
+    let json;
+    let parseError = null;
+    let parseErrObj = null;
+    let usedRecovery = false;
+    const layersAttempted = [];
+    try {
+        json = JSON.parse(sanitized);
+    }
+    catch (e) {
+        parseErrObj = e;
+        parseError = e.message;
+        usedRecovery = true;
+        layersAttempted.push("XML-strip", "control-char sanitize");
+        // Layer 2: outermost-JSON extraction
+        const extracted = extractOutermostJson(sanitized);
+        if (extracted) {
+            try {
+                json = JSON.parse(extracted);
+                parseError = null; // recovered successfully
+            }
+            catch (_e2) {
+                // extraction didn't help, keep original parseError
+                layersAttempted.push("outermost-JSON extract");
+            }
+        }
+        // Layer 4a: prose-only recovery — no `{` means model sent pure reasoning prose.
+        // Only recovers when the resulting thought is non-empty after trimming.
+        // An empty/whitespace-only thought is rejected to uphold the Zod schema
+        // requirement thought: z.string().min(1).
+        if (parseError !== null && !sanitized.includes("{")) {
+            const trimmed = sanitized.trim();
+            if (trimmed.length > 0) {
+                layersAttempted.push("prose-to-thought");
+                return {
+                    ok: true,
+                    message: {
+                        thought: trimmed,
+                        action: null,
+                        final_answer: null,
+                    },
+                };
+            }
+            // Empty/whitespace-only prose — reject with clear error
+            parseError = `prose-only recovery rejected: thought is empty or whitespace-only after trimming`;
+        }
+        // Layer 4b: XML-enveloped prose recovery — has `{` but outermost extraction returned empty;
+        // re-strip XML tags from the raw stripped text and treat remaining prose as thought.
+        // Only fires when stripXmlTags actually removed an XML envelope (reStripped ≠ stripped).
+        // Only recovers when the resulting thought is non-empty after trimming.
+        if (parseError !== null && !extracted) {
+            const reStripped = stripXmlTags(stripped).trim();
+            if (reStripped.length > 0 && reStripped !== stripped.trim()) {
+                layersAttempted.push("XML-enveloped-prose-to-thought");
+                return {
+                    ok: true,
+                    message: {
+                        thought: reStripped,
+                        action: null,
+                        final_answer: null,
+                    },
+                };
+            }
+        }
+    }
+    if (parseError !== null) {
+        const context = parseErrObj ? extractErrorContext(sanitized, parseErrObj) : null;
+        const rawPreview = raw.slice(0, 200) + (raw.length > 200 ? "..." : "");
+        return {
+            ok: false,
+            error: buildErrorDiagnostic(parseError, layersAttempted, context, rawPreview),
+        };
+    }
+    // Layer 3: normalize known LLM JSON-shape drifts
+    const { normalized: jsonForValidation, applied: normalizationApplied, steps: normalizationSteps } = normalizeReactShape(layer1, json);
+    const result = ReactMessageSchema.safeParse(jsonForValidation);
+    if (!result.success) {
+        // Layer 5: auto-thought recovery — when LLM omitted thought but
+        // provided a structurally valid action or final_answer, inject a
+        // contextual default thought and retry validation.
+        const normObj = jsonForValidation;
+        if (canAutoRecover(result, normObj)) {
+            const hasAction = normObj.action !== null &&
+                normObj.action !== undefined &&
+                typeof normObj.action === "object";
+            const toolName = hasAction
+                ? normObj.action.tool
+                : undefined;
+            normObj.thought = generateDefaultThought({
+                hasAction,
+                toolName,
+                hasFinalAnswer: normObj.final_answer !== null &&
+                    normObj.final_answer !== undefined &&
+                    typeof normObj.final_answer === "object",
+            });
+            const retryResult = ReactMessageSchema.safeParse(normObj);
+            if (retryResult.success) {
+                return { ok: true, message: retryResult.data };
+            }
+            // Retry failed — fall through to error with accurate suffix
+            const recoveryNote = usedRecovery ? " [parsed via recovery, but failed schema validation]" : "";
+            const normNote = normalizationApplied
+                ? " [normalization ran but thought still missing]"
+                : "";
+            return {
+                ok: false,
+                error: result.error.issues.map((i) => i.message).join("; ") +
+                    recoveryNote +
+                    normNote,
+            };
+        }
+        const recoveryNote = usedRecovery ? " [parsed via recovery, but failed schema validation]" : "";
+        const normNote = normalizationApplied ? " [normalization applied]" : "";
+        return {
+            ok: false,
+            error: result.error.issues.map((i) => i.message).join("; ") +
+                recoveryNote +
+                normNote,
+        };
+    }
+    return { ok: true, message: result.data };
+}
+const CONTRACT_SPEC = `
+# RESPONSE CONTRACT — read carefully, this is enforced by a parser, not a suggestion
+
+Respond with ONE JSON object and nothing else. No prose before or after it,
+no markdown commentary — a fenced \`\`\`json block is fine, plain JSON is fine,
+anything else fails to parse and costs you a turn.
+
+Do NOT wrap your JSON response in XML tags (no <thought>, <thinking>,
+<response>, <answer>, or any other XML/HTML envelope).
+
+Shape:
+{
+  "thought": "<your reasoning about what to do next, always present>",
+  "action": { "tool": "<tool_name>", "input": { ...tool-specific } } | null,
+  "final_answer": {
+    "summary": "<what you did, in plain language>",
+    "deliverable": <the actual output this subtask promised — shape depends on the subtask>,
+    "files_touched": ["path/one", "path/two"],
+    "self_check": { "ran": true, "passed": true, "detail": "<what you ran and what it showed>" }
+  } | null
+}
+
+Rules:
+- Exactly one of "action" / "final_answer" is non-null. Never both, never neither.
+- Use "action" every turn you still need to gather information or make a change.
+- Use "final_answer" only once — it ends your run for this subtask.
+- If your role has a mechanical way to check your own work (running tests, a
+  build, a linter, the tool this subtask exists to exercise), do that at
+  least once via "action" before you emit "final_answer", and report it in
+  "self_check". This does not replace the Master Orchestrator's own
+  validation — it's how you catch your own mistakes early, cheaply.
+`.trim();
+/**
+ * Build a system prompt for any agent (Sub Agent or Samurai) from a common
+ * set of inputs. The prompt format is shared across both agent types — only
+ * the identity block, goal/context section, and framing differ.
+ */
+export function buildAgentSystemPrompt(opts) {
+    const toolDocs = opts.tools
+        .map((t) => `- \`${t.name}\` — ${t.description}\n  input: ${t.inputHint}`)
+        .join("\n");
+    const identityBlock = opts.isStandalone
+        ? `You are ${opts.agentName}, a standalone AI agent CLI with full access to the tool suite below.`
+        : `You are the "${opts.agentName}" role inside Xcoder SDLC, a SDLC-aware multi-agent CLI.
+You are running as an isolated Sub Agent: this subtask, the tools below, and
+your own memory of this conversation are the ONLY things you have. You
+cannot see other subtasks' internal reasoning, only whatever has been
+inlined into your context below.
+
+If you crash or throw partway through, the Master Orchestrator does NOT
+crash with you — it records what happened and, where possible, retries you
+through the normal bounded healing process. That doesn't mean take
+reckless actions; it means a tool failing is something to observe and
+adapt to, not something to be blocked by.`;
+    const goalBlock = opts.goal
+        ? `\n## Your directive\n${opts.roleDescription}\n\n## Your subtask\n- goal: ${opts.goal}`
+        : `\n## Your directive\n${opts.roleDescription}`;
+    const bylawBlock = opts.bylawContext
+        ? `\n\n${opts.bylawContext}`
+        : "";
+    const contextBlock = opts.upstreamContext
+        ? `\n\n## Inlined context from upstream subtasks\n\`\`\`json\n${opts.upstreamContext}\n\`\`\``
+        : "";
+    const lessonBlock = opts.lessonContext
+        ? `\n\n## Relevant lessons learned\n${opts.lessonContext}`
+        : "";
+    return `
+${identityBlock}
+
+${environmentPromptBlock(opts.environment)}
+
+${detectedCommandsPromptBlock(opts.detectedCommands)}
+${goalBlock}${bylawBlock}
+
+## Relevant skills
+${opts.skills.map((s) => `- ${s}`).join("\n") || "- (none bound for this role)"}
+
+${opts.protocolOverride
+        ? `## Workspace-level protocol\n${opts.protocolOverride}\n`
+        : ""}${contextBlock}${lessonBlock}
+
+## Tools available to you
+${toolDocs}
+
+The workspace index is your source of truth for what files exist. If a
+\`read_file\` call tells you a path isn't in the index, the tool will
+automatically reindex once and retry before giving up — you don't need to
+call \`reindex_workspace\` yourself unless you suspect the index is stale
+after a lot of your own writes.
+
+For any non-trivial change to an EXISTING file, prefer \`edit_file\` over
+\`write_file\` — \`write_file\` requires you to reproduce the entire file
+correctly, which is exactly where large files go wrong. Use \`glob\`/\`grep\`
+to find things instead of guessing paths or shelling out to \`find\`/\`grep\`.
+
+${CONTRACT_SPEC}
+`.trim();
+}
+/**
+ * Thin wrapper around buildAgentSystemPrompt that maps a SubtaskNode onto
+ * the generic AgentSystemPromptOptions shape. Kept for backward
+ * compatibility with the existing SubAgent caller.
+ */
+export function buildSystemPrompt(opts) {
+    const upstreamCtx = Object.keys(opts.subtask.upstreamContext).length
+        ? JSON.stringify(opts.subtask.upstreamContext, null, 2)
+        : undefined;
+    const goalText = [
+        `- id: ${opts.subtask.id}`,
+        `- stage: ${opts.subtask.stage}`,
+        `- goal: ${opts.subtask.goal}`,
+        `- what you must deliver back to the Master Orchestrator: ${opts.subtask.deliverableSpec}`,
+        `- acceptance criteria (the Validation Gate checks these independently — you`,
+        `  are not the one who decides you passed):`,
+        ...opts.subtask.acceptanceCriteria.map((ac) => `  - [${ac.id}] (${ac.type}) ${ac.description}`),
+    ].join("\n");
+    return buildAgentSystemPrompt({
+        agentName: opts.role,
+        roleDescription: opts.directive,
+        directive: opts.directive,
+        skills: opts.skills,
+        tools: opts.tools,
+        environment: opts.environment,
+        detectedCommands: opts.detectedCommands,
+        goal: goalText,
+        upstreamContext: upstreamCtx,
+        protocolOverride: opts.protocolOverride,
+        isStandalone: false,
+    });
+}