@mcoda/core 0.1.4

package/dist/services/agents/GatewayAgentService.js

@@ -0,0 +1,870 @@
+import path from "node:path";
+import fs from "node:fs";
+import { AgentService } from "@mcoda/agents";
+import { DocdexClient } from "@mcoda/integrations";
+import { GlobalRepository, WorkspaceRepository } from "@mcoda/db";
+import { canonicalizeCommandName, getCommandRequiredCapabilities } from "@mcoda/shared";
+import { JobService } from "../jobs/JobService.js";
+import { TaskSelectionService } from "../execution/TaskSelectionService.js";
+import { RoutingService } from "./RoutingService.js";
+const DEFAULT_GATEWAY_PROMPT = [
+    "You are the gateway agent. Read the task context and docdex snippets, digest the task, decide what is done vs. remaining, and plan the work.",
+    "You must identify concrete file paths to modify or create before offloading.",
+    "Do not use placeholders like (unknown), TBD, or glob patterns in file paths.",
+    "If docdex returns no results, say so in docdexNotes.",
+    "Do not leave currentState, todo, or understanding blank.",
+    "Put reasoningSummary near the top of the JSON object so it appears early in the stream.",
+    "Do not claim to have read files or performed a repo scan unless explicit file content was provided.",
+    "Do not include fields outside the schema.",
+    "Return JSON only with the following schema:",
+    "{",
+    '  "summary": "1-3 sentence summary of the task and intent",',
+    '  "reasoningSummary": "1-2 sentence high-level rationale (no chain-of-thought)",',
+    '  "currentState": "short statement of what is already implemented or known to exist",',
+    '  "todo": "short statement of what still needs to be done",',
+    '  "understanding": "short statement of what success looks like",',
+    '  "plan": ["step 1", "step 2", "step 3"],',
+    '  "complexity": 1-10,',
+    '  "discipline": "backend|frontend|uiux|docs|architecture|qa|planning|ops|other",',
+    '  "filesLikelyTouched": ["path/to/file.ext"],',
+    '  "filesToCreate": ["path/to/new_file.ext"],',
+    '  "assumptions": ["assumption 1"],',
+    '  "risks": ["risk 1"],',
+    '  "docdexNotes": ["notes about docdex coverage/gaps"]',
+    "}",
+    "If information is missing, keep arrays empty and mention the gap in assumptions or docdexNotes.",
+].join("\n");
+const REQUIRED_PROMPT_MARKERS = [
+    '"summary"',
+    '"reasoningSummary"',
+    '"currentState"',
+    '"todo"',
+    '"understanding"',
+    '"filesLikelyTouched"',
+    '"filesToCreate"',
+];
+const hasRequiredPromptMarkers = (content) => REQUIRED_PROMPT_MARKERS.every((marker) => content.includes(marker));
+const DEFAULT_JOB_PROMPT = "You are an mcoda agent that follows workspace runbooks and responds with actionable, concise output.";
+const DEFAULT_CHARACTER_PROMPT = "Write clearly, avoid hallucinations, cite assumptions, and prioritize risk mitigation for the user.";
+const extractJson = (raw) => {
+    const fenced = raw.match(/```json([\s\S]*?)```/);
+    const candidate = fenced ? fenced[1] : raw;
+    const start = candidate.indexOf("{");
+    const end = candidate.lastIndexOf("}");
+    if (start === -1 || end === -1 || end <= start)
+        return undefined;
+    const body = candidate.slice(start, end + 1);
+    try {
+        return JSON.parse(body);
+    }
+    catch {
+        return undefined;
+    }
+};
+const estimateTokens = (text) => Math.max(1, Math.ceil((text ?? "").length / 4));
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+const normalizeList = (value) => {
+    if (Array.isArray(value))
+        return value.map((item) => String(item)).filter(Boolean);
+    if (typeof value === "string" && value.trim())
+        return [value.trim()];
+    return [];
+};
+const normalizeTextField = (value) => {
+    if (typeof value === "string") {
+        const trimmed = value.trim();
+        return trimmed ? trimmed : undefined;
+    }
+    if (Array.isArray(value)) {
+        const parts = value.map((item) => String(item).trim()).filter(Boolean);
+        return parts.length ? parts.join("; ") : undefined;
+    }
+    return undefined;
+};
+const isPlaceholderPath = (value) => {
+    const lower = value.trim().toLowerCase();
+    if (!lower)
+        return true;
+    const hasWord = (word) => new RegExp(`\\b${word}\\b`, "i").test(lower);
+    if (lower.includes("(unknown)") || hasWord("unknown") || hasWord("tbd") || hasWord("todo"))
+        return true;
+    if (lower.includes("...") || lower.includes("*") || lower.includes("<") || lower.includes(">"))
+        return true;
+    return false;
+};
+const normalizeFileList = (value) => normalizeList(value).map((item) => item.trim()).filter((item) => item.length > 0 && !isPlaceholderPath(item));
+const listMissingFields = (raw) => {
+    const missing = [];
+    const summary = normalizeTextField(raw?.summary);
+    const reasoningSummary = normalizeTextField(raw?.reasoningSummary);
+    const currentState = normalizeTextField(raw?.currentState);
+    const todo = normalizeTextField(raw?.todo);
+    const understanding = normalizeTextField(raw?.understanding);
+    const plan = normalizeList(raw?.plan);
+    const filesLikelyTouched = normalizeFileList(raw?.filesLikelyTouched);
+    const filesToCreate = normalizeFileList(raw?.filesToCreate);
+    if (!summary)
+        missing.push("summary");
+    if (!reasoningSummary)
+        missing.push("reasoningSummary");
+    if (!currentState)
+        missing.push("currentState");
+    if (!todo)
+        missing.push("todo");
+    if (!understanding)
+        missing.push("understanding");
+    if (plan.length === 0)
+        missing.push("plan");
+    if (filesLikelyTouched.length === 0 && filesToCreate.length === 0)
+        missing.push("files");
+    return missing;
+};
+const normalizeDiscipline = (value) => {
+    if (!value)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (!normalized)
+        return undefined;
+    const allowed = new Set(["backend", "frontend", "uiux", "docs", "architecture", "qa", "planning", "ops", "other"]);
+    return allowed.has(normalized) ? normalized : "other";
+};
+const inferDiscipline = (job, taskTitles, input) => {
+    const text = [job, ...taskTitles, input ?? ""].join(" ").toLowerCase();
+    if (text.includes("sds") || text.includes("pdr") || text.includes("documentation"))
+        return "docs";
+    if (text.includes("openapi") || text.includes("spec"))
+        return "docs";
+    if (text.includes("qa") || text.includes("test"))
+        return "qa";
+    if (text.includes("architecture") || text.includes("design"))
+        return "architecture";
+    if (text.includes("refine") || text.includes("create-tasks") || text.includes("planning"))
+        return "planning";
+    if (text.includes("frontend") || text.includes("ui") || text.includes("ux"))
+        return "frontend";
+    if (text.includes("backend") || text.includes("api") || text.includes("database"))
+        return "backend";
+    return "other";
+};
+const usageKeywords = {
+    backend: ["backend", "api", "server", "db", "database"],
+    frontend: ["frontend", "ui", "ux", "web", "react", "mobile"],
+    uiux: ["ui", "ux", "design", "prototype"],
+    docs: ["doc", "documentation", "sds", "pdr", "spec"],
+    architecture: ["arch", "architecture", "system", "design"],
+    qa: ["qa", "test", "testing", "quality"],
+    planning: ["plan", "planning", "product", "pm"],
+    ops: ["ops", "devops", "infra", "deployment"],
+};
+const scoreUsage = (discipline, bestUsage, capabilities) => {
+    if (!discipline)
+        return 0;
+    const normalized = (bestUsage ?? "").toLowerCase();
+    const keywords = usageKeywords[discipline] ?? [];
+    const hasKeyword = keywords.some((k) => normalized.includes(k));
+    let score = hasKeyword ? 1 : 0;
+    const caps = new Set((capabilities ?? []).map((c) => c.toLowerCase()));
+    if (discipline === "docs" && caps.has("docdex_query"))
+        score += 0.5;
+    if (discipline === "qa" && caps.has("qa_interpretation"))
+        score += 0.5;
+    if (discipline === "planning" && caps.has("plan"))
+        score += 0.5;
+    if ((discipline === "backend" || discipline === "frontend") && caps.has("code_write"))
+        score += 0.5;
+    return score;
+};
+const DEFAULT_STATUS_FILTER = [
+    "not_started",
+    "in_progress",
+    "blocked",
+    "ready_to_review",
+    "ready_to_qa",
+    "completed",
+    "cancelled",
+    "failed",
+    "skipped",
+];
+const summarizeDoc = (doc, index) => {
+    const title = doc.title ?? doc.path ?? doc.id ?? `doc-${index + 1}`;
+    const excerptSource = doc.segments?.[0]?.content ?? doc.content ?? "";
+    const excerpt = excerptSource ? (excerptSource.length > 480 ? `${excerptSource.slice(0, 480)}...` : excerptSource) : undefined;
+    return {
+        id: doc.id ?? `doc-${index + 1}`,
+        docType: doc.docType,
+        title,
+        path: doc.path,
+        excerpt,
+    };
+};
+const buildDocContext = (docs) => {
+    if (docs.length === 0)
+        return "Docdex: (no matching documents found)";
+    return [
+        "Docdex context:",
+        ...docs.map((doc) => {
+            const head = `[${doc.docType}] ${doc.title}`;
+            const tail = doc.path ? ` (${doc.path})` : "";
+            const excerpt = doc.excerpt ? `\n  Excerpt: ${doc.excerpt}` : "";
+            return `- ${head}${tail}${excerpt}`;
+        }),
+    ].join("\n");
+};
+const buildTaskContext = (tasks) => {
+    if (tasks.length === 0)
+        return "Task context: (no task records found)";
+    const lines = ["Task context:"];
+    for (const task of tasks) {
+        lines.push([
+            `- ${task.key}: ${task.title}`,
+            task.description ? `  Description: ${task.description}` : undefined,
+            task.status ? `  Status: ${task.status}` : undefined,
+            task.storyKey ? `  Story: ${task.storyKey} ${task.storyTitle ?? ""}`.trim() : undefined,
+            task.epicKey ? `  Epic: ${task.epicKey} ${task.epicTitle ?? ""}`.trim() : undefined,
+            task.storyPoints !== undefined ? `  Story points: ${task.storyPoints}` : undefined,
+            task.acceptanceCriteria?.length ? `  Acceptance: ${task.acceptanceCriteria.join(" | ")}` : undefined,
+            task.dependencies?.length ? `  Dependencies: ${task.dependencies.join(", ")}` : undefined,
+        ]
+            .filter(Boolean)
+            .join("\n"));
+    }
+    return lines.join("\n");
+};
+export class GatewayAgentService {
+    constructor(workspace, deps) {
+        this.workspace = workspace;
+        this.deps = deps;
+        this.taskSelectionService = new TaskSelectionService(workspace, deps.workspaceRepo);
+    }
+    static async create(workspace) {
+        const globalRepo = await GlobalRepository.create();
+        const agentService = new AgentService(globalRepo);
+        const routingService = await RoutingService.create();
+        const docdex = new DocdexClient({
+            workspaceRoot: workspace.workspaceRoot,
+            baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+        });
+        const workspaceRepo = await WorkspaceRepository.create(workspace.workspaceRoot);
+        const jobService = new JobService(workspace, workspaceRepo);
+        return new GatewayAgentService(workspace, {
+            agentService,
+            docdex,
+            globalRepo,
+            jobService,
+            workspaceRepo,
+            routingService,
+        });
+    }
+    async readPromptFiles(paths) {
+        const contents = [];
+        const seen = new Set();
+        for (const promptPath of paths) {
+            try {
+                const content = await fs.promises.readFile(promptPath, "utf8");
+                const trimmed = content.trim();
+                if (trimmed && !seen.has(trimmed)) {
+                    contents.push(trimmed);
+                    seen.add(trimmed);
+                }
+            }
+            catch {
+                /* optional prompt */
+            }
+        }
+        return contents;
+    }
+    async close() {
+        const maybeClose = async (target) => {
+            try {
+                if (target?.close)
+                    await target.close();
+            }
+            catch {
+                /* ignore */
+            }
+        };
+        await maybeClose(this.taskSelectionService);
+        await maybeClose(this.deps.agentService);
+        await maybeClose(this.deps.docdex);
+        await maybeClose(this.deps.globalRepo);
+        await maybeClose(this.deps.jobService);
+        await maybeClose(this.deps.workspaceRepo);
+        await maybeClose(this.deps.routingService);
+    }
+    async loadGatewayPrompts(agentId) {
+        const agentPrompts = "getPrompts" in this.deps.agentService ? await this.deps.agentService.getPrompts(agentId) : undefined;
+        const mcodaPromptPath = path.join(this.workspace.workspaceRoot, ".mcoda", "prompts", "gateway-agent.md");
+        const workspacePromptPath = path.join(this.workspace.workspaceRoot, "prompts", "gateway-agent.md");
+        try {
+            await fs.promises.mkdir(path.dirname(mcodaPromptPath), { recursive: true });
+            await fs.promises.access(mcodaPromptPath);
+        }
+        catch {
+            try {
+                await fs.promises.access(workspacePromptPath);
+                await fs.promises.copyFile(workspacePromptPath, mcodaPromptPath);
+            }
+            catch {
+                await fs.promises.writeFile(mcodaPromptPath, DEFAULT_GATEWAY_PROMPT, "utf8");
+            }
+        }
+        try {
+            const existing = await fs.promises.readFile(mcodaPromptPath, "utf8");
+            if (!hasRequiredPromptMarkers(existing)) {
+                let nextPrompt = DEFAULT_GATEWAY_PROMPT;
+                try {
+                    const workspacePrompt = await fs.promises.readFile(workspacePromptPath, "utf8");
+                    if (hasRequiredPromptMarkers(workspacePrompt)) {
+                        nextPrompt = workspacePrompt.trim();
+                    }
+                }
+                catch {
+                    /* ignore */
+                }
+                await fs.promises.writeFile(mcodaPromptPath, nextPrompt, "utf8");
+            }
+        }
+        catch {
+            /* ignore */
+        }
+        const commandPromptFiles = (await this.readPromptFiles([mcodaPromptPath, workspacePromptPath])).filter(hasRequiredPromptMarkers);
+        const mergedCommandPrompt = (() => {
+            const parts = [...commandPromptFiles];
+            const agentCommandPrompt = agentPrompts?.commandPrompts?.["gateway-agent"];
+            if (agentCommandPrompt && hasRequiredPromptMarkers(agentCommandPrompt)) {
+                parts.push(agentCommandPrompt);
+            }
+            if (!parts.length)
+                parts.push(DEFAULT_GATEWAY_PROMPT);
+            return parts.filter(Boolean).join("\n\n");
+        })();
+        return {
+            jobPrompt: agentPrompts?.jobPrompt ?? DEFAULT_JOB_PROMPT,
+            characterPrompt: agentPrompts?.characterPrompt ?? DEFAULT_CHARACTER_PROMPT,
+            commandPrompt: mergedCommandPrompt,
+        };
+    }
+    async resolveGatewayAgent(override, warnings = []) {
+        try {
+            const resolved = await this.deps.routingService.resolveAgentForCommand({
+                workspace: this.workspace,
+                commandName: "gateway-agent",
+                overrideAgentSlug: override,
+            });
+            return resolved.agent;
+        }
+        catch (error) {
+            warnings.push(`Routing defaults unavailable for gateway-agent; using best available agent (${error.message})`);
+            const requiredCaps = getCommandRequiredCapabilities("gateway-agent");
+            if (override) {
+                try {
+                    const overrideAgent = await this.deps.agentService.resolveAgent(override);
+                    const caps = await this.deps.globalRepo.getAgentCapabilities(overrideAgent.id);
+                    const missing = requiredCaps.filter((cap) => !caps.includes(cap));
+                    const health = await this.deps.globalRepo.getAgentHealth(overrideAgent.id);
+                    if (missing.length === 0 && health?.status !== "unreachable") {
+                        return overrideAgent;
+                    }
+                    if (missing.length) {
+                        warnings.push(`Override agent ${overrideAgent.slug} is missing gateway capabilities (${missing.join(", ")}); ignoring override.`);
+                    }
+                    else if (health?.status === "unreachable") {
+                        warnings.push(`Override agent ${overrideAgent.slug} is unreachable; ignoring override.`);
+                    }
+                }
+                catch (overrideError) {
+                    warnings.push(`Override agent ${override} could not be resolved (${overrideError.message}); ignoring override.`);
+                }
+            }
+            const candidates = await this.listCandidates(requiredCaps, "planning");
+            if (!candidates.length) {
+                throw new Error("No eligible gateway agents available; add a plan/docdex_query-capable agent");
+            }
+            const sorted = candidates
+                .slice()
+                .sort((a, b) => {
+                const qa = b.reasoning || b.quality;
+                const qb = a.reasoning || a.quality;
+                if (qa !== qb)
+                    return qa - qb;
+                if (b.quality !== a.quality)
+                    return b.quality - a.quality;
+                return a.cost - b.cost;
+            });
+            return sorted[0].agent;
+        }
+    }
+    async invokeGatewayAgent(agent, prompt, job, options) {
+        const startedAt = Date.now();
+        const stream = options?.stream !== false;
+        const onChunk = options?.onChunk;
+        try {
+            if (stream) {
+                const generator = await this.deps.agentService.invokeStream(agent.id, {
+                    input: prompt,
+                    metadata: { command: "gateway-agent", job },
+                });
+                let output = "";
+                for await (const chunk of generator) {
+                    const text = chunk.output ?? "";
+                    output += text;
+                    if (text && onChunk)
+                        onChunk(text);
+                }
+                return { output, durationSeconds: (Date.now() - startedAt) / 1000 };
+            }
+        }
+        catch (error) {
+            const message = error.message ?? "";
+            if (!/does not support streaming/i.test(message)) {
+                throw error;
+            }
+        }
+        const response = await this.deps.agentService.invoke(agent.id, {
+            input: prompt,
+            metadata: { command: "gateway-agent", job },
+        });
+        const output = response.output ?? "";
+        if (output && onChunk)
+            onChunk(output);
+        return { output, durationSeconds: (Date.now() - startedAt) / 1000 };
+    }
+    async buildTasksSummary(request, warnings) {
+        const hasFilters = Boolean(request.projectKey) ||
+            Boolean(request.epicKey) ||
+            Boolean(request.storyKey) ||
+            Boolean(request.taskKeys?.length);
+        if (!hasFilters)
+            return [];
+        const limit = request.taskKeys?.length ? request.taskKeys.length : request.limit ?? 8;
+        try {
+            const filters = {
+                projectKey: request.projectKey,
+                epicKey: request.epicKey,
+                storyKey: request.storyKey,
+                taskKeys: request.taskKeys,
+                statusFilter: request.statusFilter?.length ? request.statusFilter : DEFAULT_STATUS_FILTER,
+                limit,
+            };
+            const selection = await this.taskSelectionService.selectTasks(filters);
+            if (selection.warnings.length)
+                warnings.push(...selection.warnings);
+            const combined = [...selection.ordered, ...selection.blocked];
+            return combined.slice(0, limit).map((entry) => ({
+                key: entry.task.key,
+                title: entry.task.title,
+                description: entry.task.description ?? undefined,
+                status: entry.task.status,
+                storyPoints: entry.task.storyPoints ?? undefined,
+                storyKey: entry.task.storyKey,
+                storyTitle: entry.task.storyTitle,
+                epicKey: entry.task.epicKey,
+                epicTitle: entry.task.epicTitle,
+                acceptanceCriteria: entry.task.acceptanceCriteria,
+                dependencies: entry.dependencies.keys,
+            }));
+        }
+        catch (error) {
+            warnings.push(`Task lookup failed: ${error.message}`);
+            return [];
+        }
+    }
+    pickDocTypes(job, input) {
+        const types = new Set();
+        const lower = `${job} ${input ?? ""}`.toLowerCase();
+        if (lower.includes("sds"))
+            types.add("SDS");
+        if (lower.includes("pdr"))
+            types.add("PDR");
+        if (lower.includes("rfp"))
+            types.add("RFP");
+        if (lower.includes("openapi"))
+            types.add("OPENAPI");
+        if (lower.includes("doc")) {
+            types.add("SDS");
+            types.add("PDR");
+        }
+        if (types.size === 0) {
+            types.add("SDS");
+            types.add("PDR");
+            types.add("OPENAPI");
+        }
+        return Array.from(types);
+    }
+    buildQuerySeed(tasks, input) {
+        const seeds = [];
+        tasks.forEach((task) => {
+            seeds.push(task.key, task.title);
+            if (task.storyTitle)
+                seeds.push(task.storyTitle);
+            if (task.epicTitle)
+                seeds.push(task.epicTitle);
+        });
+        if (input) {
+            seeds.push(...input.split(/\s+/).slice(0, 12));
+        }
+        return Array.from(new Set(seeds.map((s) => s.trim()).filter(Boolean))).slice(0, 10).join(" ");
+    }
+    async buildDocSummaries(request, tasks, warnings) {
+        const maxDocs = request.maxDocs ?? 4;
+        if (maxDocs <= 0)
+            return [];
+        const docTypes = this.pickDocTypes(request.job, request.inputText);
+        const query = this.buildQuerySeed(tasks, request.inputText);
+        const summaries = [];
+        for (const docType of docTypes) {
+            if (summaries.length >= maxDocs)
+                break;
+            try {
+                const docs = await this.deps.docdex.search({
+                    projectKey: request.projectKey,
+                    docType,
+                    query,
+                });
+                for (const doc of docs) {
+                    if (summaries.length >= maxDocs)
+                        break;
+                    summaries.push(summarizeDoc(doc, summaries.length));
+                }
+            }
+            catch (error) {
+                warnings.push(`Docdex search failed (${docType}): ${error.message}`);
+            }
+        }
+        return summaries;
+    }
+    buildGatewayPrompt(job, tasks, docs, inputText) {
+        const taskContext = buildTaskContext(tasks);
+        const docContext = buildDocContext(docs);
+        const inputBlock = inputText ? `Additional input:\n${inputText}` : "Additional input: (none)";
+        return [`Job: ${job}`, taskContext, inputBlock, docContext].join("\n\n");
+    }
+    normalizeAnalysis(raw, job, tasks, inputText) {
+        const summary = normalizeTextField(raw?.summary);
+        const currentState = normalizeTextField(raw?.currentState);
+        const todo = normalizeTextField(raw?.todo);
+        const reasoningSummary = normalizeTextField(raw?.reasoningSummary) ?? "";
+        const understanding = normalizeTextField(raw?.understanding) ?? "";
+        const plan = normalizeList(raw?.plan);
+        const filesLikelyTouched = normalizeFileList(raw?.filesLikelyTouched);
+        const filesToCreate = normalizeFileList(raw?.filesToCreate);
+        const complexityRaw = Number(raw?.complexity);
+        const complexity = Number.isFinite(complexityRaw) ? clamp(Math.round(complexityRaw), 1, 10) : 5;
+        const discipline = normalizeDiscipline(typeof raw?.discipline === "string" ? raw.discipline : undefined) ??
+            inferDiscipline(job, tasks.map((t) => t.title), inputText);
+        const fallbackSummary = summary ??
+            (tasks.length
+                ? `Handle ${tasks.length} task${tasks.length > 1 ? "s" : ""}: ${tasks.map((t) => t.key).join(", ")}.`
+                : inputText?.slice(0, 200) ?? "Summarize the requested job.");
+        const fallbackState = currentState
+            ? currentState
+            : tasks.length
+                ? tasks.map((t) => `${t.key} is ${t.status ?? "unknown"} (${t.title})`).join("; ")
+                : "Current state unknown; requires investigation.";
+        const fallbackTodo = todo
+            ? todo
+            : tasks.length
+                ? tasks.map((t) => t.title).join("; ")
+                : "Determine remaining work based on provided input and docs.";
+        return {
+            summary: fallbackSummary,
+            reasoningSummary,
+            currentState: fallbackState,
+            todo: fallbackTodo,
+            understanding,
+            plan: plan.length ? plan : ["Review requirements and docs", "Execute the job", "Verify outcomes"],
+            complexity,
+            discipline,
+            filesLikelyTouched,
+            filesToCreate,
+            assumptions: normalizeList(raw?.assumptions),
+            risks: normalizeList(raw?.risks),
+            docdexNotes: normalizeList(raw?.docdexNotes),
+        };
+    }
+    async validateFilePlan(analysis, warnings) {
+        const root = this.workspace.workspaceRoot;
+        const normalize = (file) => {
+            const resolved = path.resolve(root, file);
+            const relative = path.relative(root, resolved);
+            return { relative, resolved };
+        };
+        const isInside = (relative) => !relative.startsWith("..") && !path.isAbsolute(relative);
+        const touched = [];
+        const created = [];
+        for (const file of analysis.filesLikelyTouched) {
+            const { relative, resolved } = normalize(file);
+            if (!isInside(relative)) {
+                warnings.push(`Gateway file path outside workspace ignored: ${file}`);
+                continue;
+            }
+            try {
+                const stat = await fs.promises.stat(resolved);
+                if (stat.isFile()) {
+                    touched.push(relative.replace(/\\/g, "/"));
+                }
+                else {
+                    warnings.push(`Gateway file path is not a file: ${file}`);
+                }
+            }
+            catch {
+                warnings.push(`Gateway file path does not exist: ${file}`);
+            }
+        }
+        for (const file of analysis.filesToCreate) {
+            const { relative, resolved } = normalize(file);
+            if (!isInside(relative)) {
+                warnings.push(`Gateway create path outside workspace ignored: ${file}`);
+                continue;
+            }
+            const parent = path.dirname(resolved);
+            try {
+                const stat = await fs.promises.stat(parent);
+                if (!stat.isDirectory()) {
+                    warnings.push(`Gateway create path parent is not a directory: ${file}`);
+                    continue;
+                }
+            }
+            catch {
+                warnings.push(`Gateway create path parent does not exist: ${file}`);
+                continue;
+            }
+            try {
+                const stat = await fs.promises.stat(resolved);
+                if (stat.isFile()) {
+                    warnings.push(`Gateway create path already exists; treating as touch: ${file}`);
+                    touched.push(relative.replace(/\\/g, "/"));
+                    continue;
+                }
+            }
+            catch {
+                /* file does not exist; ok */
+            }
+            created.push(relative.replace(/\\/g, "/"));
+        }
+        return {
+            ...analysis,
+            filesLikelyTouched: touched,
+            filesToCreate: created,
+        };
+    }
+    async listCandidates(requiredCaps, discipline) {
+        const agents = await this.deps.globalRepo.listAgents();
+        if (agents.length === 0) {
+            throw new Error("No agents available; register one with mcoda agent add");
+        }
+        const health = await this.deps.globalRepo.listAgentHealthSummary();
+        const healthById = new Map(health.map((row) => [row.agentId, row]));
+        const candidates = [];
+        for (const agent of agents) {
+            const capabilities = await this.deps.globalRepo.getAgentCapabilities(agent.id);
+            const missing = requiredCaps.filter((cap) => !capabilities.includes(cap));
+            if (missing.length)
+                continue;
+            const healthEntry = healthById.get(agent.id);
+            if (healthEntry?.status === "unreachable")
+                continue;
+            const rating = agent.rating ?? 0;
+            const reasoning = agent.reasoningRating ?? rating;
+            const quality = discipline === "architecture" || discipline === "planning"
+                ? reasoning || rating || 5
+                : rating || reasoning || 5;
+            const usageScore = scoreUsage(discipline, agent.bestUsage, capabilities);
+            const cost = agent.costPerMillion ?? Number.POSITIVE_INFINITY;
+            const adjustedQuality = healthEntry?.status === "degraded" ? quality - 0.5 : quality;
+            candidates.push({
+                agent,
+                capabilities,
+                health: healthEntry,
+                quality: adjustedQuality,
+                reasoning,
+                usageScore,
+                cost,
+            });
+        }
+        return candidates;
+    }
+    chooseCandidate(candidates, complexity, discipline) {
+        if (candidates.length === 0) {
+            throw new Error("No eligible agents available for this job");
+        }
+        const sortedQuality = candidates.map((c) => c.quality);
+        const maxQuality = Math.max(...sortedQuality);
+        if (complexity >= 9) {
+            const pick = candidates
+                .slice()
+                .sort((a, b) => {
+                if (b.quality !== a.quality)
+                    return b.quality - a.quality;
+                if (b.usageScore !== a.usageScore)
+                    return b.usageScore - a.usageScore;
+                if (b.reasoning !== a.reasoning)
+                    return b.reasoning - a.reasoning;
+                return a.cost - b.cost;
+            })[0];
+            return {
+                pick,
+                rationale: `Complexity ${complexity}/10 requires the highest capability; selected top-rated agent with best fit for ${discipline}.`,
+            };
+        }
+        if (complexity >= 8) {
+            const pool = candidates.filter((c) => c.quality >= maxQuality - 1);
+            const pick = (pool.length ? pool : candidates)
+                .slice()
+                .sort((a, b) => {
+                if (b.usageScore !== a.usageScore)
+                    return b.usageScore - a.usageScore;
+                if (a.cost !== b.cost)
+                    return a.cost - b.cost;
+                return b.quality - a.quality;
+            })[0];
+            return {
+                pick,
+                rationale: `Complexity ${complexity}/10 favors strong agents with good cost/fit balance; selected best-fit candidate.`,
+            };
+        }
+        const target = complexity;
+        const pool = candidates.filter((c) => c.quality >= target);
+        const base = pool.length ? pool : candidates;
+        const pick = base
+            .slice()
+            .sort((a, b) => {
+            const diffA = Math.abs(a.quality - target);
+            const diffB = Math.abs(b.quality - target);
+            if (diffA !== diffB)
+                return diffA - diffB;
+            if (b.usageScore !== a.usageScore)
+                return b.usageScore - a.usageScore;
+            if (a.cost !== b.cost)
+                return a.cost - b.cost;
+            return a.quality - b.quality;
+        })[0];
+        return {
+            pick,
+            rationale: `Complexity ${complexity}/10 targets a comparable tier agent; selected closest match with discipline fit and cost awareness.`,
+        };
+    }
+    async selectAgentForJob(job, analysis) {
+        const normalizedJob = canonicalizeCommandName(job);
+        const requiredCaps = getCommandRequiredCapabilities(normalizedJob);
+        const candidates = await this.listCandidates(requiredCaps, analysis.discipline);
+        const { pick, rationale } = this.chooseCandidate(candidates, analysis.complexity, analysis.discipline);
+        return {
+            agentId: pick.agent.id,
+            agentSlug: pick.agent.slug ?? pick.agent.id,
+            rating: pick.agent.rating ?? undefined,
+            reasoningRating: pick.agent.reasoningRating ?? undefined,
+            bestUsage: pick.agent.bestUsage ?? undefined,
+            costPerMillion: Number.isFinite(pick.cost) ? pick.cost : undefined,
+            rationale,
+        };
+    }
+    async run(request) {
+        const warnings = [];
+        const normalizedJob = canonicalizeCommandName(request.job);
+        const commandRun = await this.deps.jobService.startCommandRun("gateway-agent", request.projectKey);
+        try {
+            const tasks = await this.buildTasksSummary(request, warnings);
+            const docs = await this.buildDocSummaries(request, tasks, warnings);
+            const gatewayAgent = await this.resolveGatewayAgent(request.gatewayAgentName, warnings);
+            const prompts = await this.loadGatewayPrompts(gatewayAgent.id);
+            const prompt = [
+                prompts.jobPrompt,
+                prompts.characterPrompt,
+                prompts.commandPrompt,
+                this.buildGatewayPrompt(normalizedJob, tasks, docs, request.inputText),
+            ]
+                .filter(Boolean)
+                .join("\n\n");
+            const recordUsage = async (promptText, outputText, durationSeconds, action) => {
+                const promptTokens = estimateTokens(promptText);
+                const completionTokens = estimateTokens(outputText ?? "");
+                await this.deps.jobService.recordTokenUsage({
+                    timestamp: new Date().toISOString(),
+                    workspaceId: this.workspace.workspaceId,
+                    commandName: "gateway-agent",
+                    commandRunId: commandRun.id,
+                    agentId: gatewayAgent.id,
+                    modelName: gatewayAgent.defaultModel,
+                    promptTokens,
+                    completionTokens,
+                    tokensPrompt: promptTokens,
+                    tokensCompletion: completionTokens,
+                    tokensTotal: promptTokens + completionTokens,
+                    durationSeconds,
+                    metadata: { action, job: normalizedJob },
+                });
+            };
+            const response = await this.invokeGatewayAgent(gatewayAgent, prompt, normalizedJob, {
+                stream: request.agentStream !== false,
+                onChunk: request.onStreamChunk,
+            });
+            await recordUsage(prompt, response.output ?? "", response.durationSeconds, "gateway_summary");
+            let parsed = extractJson(response.output);
+            let missingFields = parsed
+                ? listMissingFields(parsed)
+                : ["summary", "reasoningSummary", "currentState", "todo", "understanding", "plan", "files"];
+            if (!parsed) {
+                warnings.push("Gateway analysis response was not valid JSON; falling back to defaults.");
+            }
+            if (missingFields.length) {
+                const repairPrompt = [
+                    prompt,
+                    "",
+                    "Your previous response was incomplete or invalid. Return JSON only with the exact schema.",
+                    `Missing fields: ${missingFields.join(", ")}.`,
+                    "Ensure reasoningSummary, currentState, todo, understanding, plan, and filesLikelyTouched/filesToCreate are populated.",
+                    "Use real file paths only (no placeholders like (unknown), TBD, or glob patterns).",
+                    "If docdex returned no results, say so in docdexNotes.",
+                ].join("\n");
+                if (request.onStreamChunk) {
+                    request.onStreamChunk("\n[gateway-agent] Retrying for missing fields...\n");
+                }
+                const repairResponse = await this.invokeGatewayAgent(gatewayAgent, repairPrompt, normalizedJob, {
+                    stream: request.agentStream !== false,
+                    onChunk: request.onStreamChunk,
+                });
+                await recordUsage(repairPrompt, repairResponse.output ?? "", repairResponse.durationSeconds, "gateway_summary_repair");
+                const repaired = extractJson(repairResponse.output);
+                if (repaired) {
+                    parsed = repaired;
+                    missingFields = listMissingFields(parsed);
+                }
+                else {
+                    warnings.push("Gateway repair response was not valid JSON; using fallback analysis.");
+                }
+            }
+            if (missingFields.length) {
+                warnings.push(`Gateway analysis missing fields: ${missingFields.join(", ")}.`);
+            }
+            let analysis = this.normalizeAnalysis(parsed ?? {}, normalizedJob, tasks, request.inputText);
+            if (analysis.docdexNotes.length === 0) {
+                if (docs.length === 0) {
+                    analysis.docdexNotes.push("Docdex: no matching documents found.");
+                }
+                else {
+                    warnings.push("Gateway analysis missing docdexNotes for retrieved docdex context.");
+                }
+                const docdexWarnings = warnings.filter((w) => w.toLowerCase().includes("docdex"));
+                analysis.docdexNotes.push(...docdexWarnings);
+            }
+            analysis = await this.validateFilePlan(analysis, warnings);
+            const chosenAgent = await this.selectAgentForJob(normalizedJob, analysis);
+            await this.deps.jobService.finishCommandRun(commandRun.id, "succeeded");
+            return {
+                commandRunId: commandRun.id,
+                job: normalizedJob,
+                gatewayAgent: { id: gatewayAgent.id, slug: gatewayAgent.slug ?? gatewayAgent.id },
+                tasks,
+                docdex: docs,
+                analysis,
+                chosenAgent,
+                warnings,
+            };
+        }
+        catch (error) {
+            await this.deps.jobService.finishCommandRun(commandRun.id, "failed", error.message);
+            throw error;
+        }
+    }
+}