@mcoda/core 0.1.4

package/dist/services/agents/RoutingApiClient.d.ts

@@ -0,0 +1,23 @@
+import { Agent, RoutingDefaults, RoutingDefaultsUpdate, RoutingPreview } from "@mcoda/shared";
+export interface RoutingPreviewRequest {
+    workspaceId: string;
+    commandName: string;
+    agentOverride?: string;
+    taskType?: string;
+    projectKey?: string;
+    requiredCapabilities?: string[];
+}
+export declare class RoutingApiClient {
+    private baseUrl;
+    constructor(baseUrl: string);
+    static create(): RoutingApiClient;
+    private fetchJson;
+    private putJson;
+    private postJson;
+    getWorkspaceDefaults(workspaceId: string): Promise<RoutingDefaults | undefined>;
+    updateWorkspaceDefaults(workspaceId: string, update: RoutingDefaultsUpdate): Promise<RoutingDefaults | undefined>;
+    preview(request: RoutingPreviewRequest): Promise<RoutingPreview | undefined>;
+    listAgents(): Promise<Agent[] | undefined>;
+    getAgent(idOrSlug: string): Promise<Agent | undefined>;
+}
+//# sourceMappingURL=RoutingApiClient.d.ts.map

package/dist/services/agents/RoutingApiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutingApiClient.d.ts","sourceRoot":"","sources":["../../../src/services/agents/RoutingApiClient.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,qBAAqB,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAM9F,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,qBAAa,gBAAgB;IACf,OAAO,CAAC,OAAO;gBAAP,OAAO,EAAE,MAAM;IAEnC,MAAM,CAAC,MAAM,IAAI,gBAAgB;YAKnB,SAAS;YAQT,OAAO;YAUP,QAAQ;IAUhB,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAI/E,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAIjH,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAW5E,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,GAAG,SAAS,CAAC;IAI1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC;CAG7D"}

package/dist/services/agents/RoutingApiClient.js

@@ -0,0 +1,62 @@
+const pickBaseUrl = () => {
+    return process.env.MCODA_ROUTING_API_URL ?? process.env.MCODA_API_BASE_URL;
+};
+export class RoutingApiClient {
+    constructor(baseUrl) {
+        this.baseUrl = baseUrl;
+    }
+    static create() {
+        const baseUrl = pickBaseUrl() ?? "http://localhost";
+        return new RoutingApiClient(baseUrl);
+    }
+    async fetchJson(path) {
+        const resp = await fetch(new URL(path, this.baseUrl), {
+            headers: { accept: "application/json" },
+        });
+        if (!resp.ok)
+            return undefined;
+        return (await resp.json());
+    }
+    async putJson(path, body) {
+        const resp = await fetch(new URL(path, this.baseUrl), {
+            method: "PUT",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok)
+            return undefined;
+        return (await resp.json());
+    }
+    async postJson(path, body) {
+        const resp = await fetch(new URL(path, this.baseUrl), {
+            method: "POST",
+            headers: { "content-type": "application/json", accept: "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!resp.ok)
+            return undefined;
+        return (await resp.json());
+    }
+    async getWorkspaceDefaults(workspaceId) {
+        return this.fetchJson(`/workspaces/${encodeURIComponent(workspaceId)}/defaults`);
+    }
+    async updateWorkspaceDefaults(workspaceId, update) {
+        return this.putJson(`/workspaces/${encodeURIComponent(workspaceId)}/defaults`, update);
+    }
+    async preview(request) {
+        return this.postJson("/routing/preview", {
+            workspaceId: request.workspaceId,
+            commandName: request.commandName,
+            agentOverride: request.agentOverride,
+            taskType: request.taskType,
+            projectKey: request.projectKey,
+            requiredCapabilities: request.requiredCapabilities,
+        });
+    }
+    async listAgents() {
+        return this.fetchJson("/agents");
+    }
+    async getAgent(idOrSlug) {
+        return this.fetchJson(`/agents/${encodeURIComponent(idOrSlug)}`);
+    }
+}

package/dist/services/agents/RoutingService.d.ts

@@ -0,0 +1,50 @@
+import { Agent, AgentHealth, RoutingDefaults, RoutingDefaultsUpdate, RoutingPreview, RoutingProvenance } from "@mcoda/shared";
+import { GlobalRepository } from "@mcoda/db";
+import { WorkspaceResolution } from "../../workspace/WorkspaceManager.js";
+import { RoutingApiClient } from "./generated/RoutingApiClient.js";
+export interface ResolveAgentParams {
+    workspace: WorkspaceResolution;
+    commandName: string;
+    taskType?: string;
+    overrideAgentSlug?: string;
+    projectKey?: string;
+}
+export interface ResolvedAgent {
+    agent: Agent;
+    agentId: string;
+    agentSlug: string;
+    model?: string;
+    capabilities: string[];
+    healthStatus: AgentHealth["status"] | "unknown";
+    source: RoutingProvenance;
+    routingPreview: RoutingPreview;
+    qaProfile?: string;
+    docdexScope?: string;
+    requiredCapabilities: string[];
+}
+export declare class RoutingService {
+    private deps;
+    constructor(deps: {
+        routingApi?: RoutingApiClient;
+        agentService?: {
+            resolveAgent(idOrSlug: string): Promise<Agent>;
+            getCapabilities?(agentId: string): Promise<string[]>;
+            close?(): Promise<void>;
+        };
+        globalRepo?: GlobalRepository;
+    });
+    static create(): Promise<RoutingService>;
+    close(): Promise<void>;
+    private requiredCapabilities;
+    normalizeCommand(commandName: string): string;
+    private fetchAgent;
+    private fetchCapabilities;
+    private normalizeProfile;
+    getWorkspaceDefaults(workspace: WorkspaceResolution | string): Promise<RoutingDefaults>;
+    private migrateLegacyDefaults;
+    getAgentSummary(agentId: string): Promise<Agent | undefined>;
+    updateWorkspaceDefaults(workspaceId: string, update: RoutingDefaultsUpdate): Promise<RoutingDefaults>;
+    private buildPreviewRequest;
+    resolveAgentForCommand(params: ResolveAgentParams): Promise<ResolvedAgent>;
+}
+//# sourceMappingURL=RoutingService.d.ts.map

package/dist/services/agents/RoutingService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutingService.d.ts","sourceRoot":"","sources":["../../../src/services/agents/RoutingService.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,cAAc,EACd,iBAAiB,EAKlB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qCAAqC,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAyB,MAAM,iCAAiC,CAAC;AAE1F,MAAM,WAAW,kBAAkB;IACjC,SAAS,EAAE,mBAAmB,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,KAAK,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,YAAY,EAAE,WAAW,CAAC,QAAQ,CAAC,GAAG,SAAS,CAAC;IAChD,MAAM,EAAE,iBAAiB,CAAC;IAC1B,cAAc,EAAE,cAAc,CAAC;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oBAAoB,EAAE,MAAM,EAAE,CAAC;CAChC;AAED,qBAAa,cAAc;IAEvB,OAAO,CAAC,IAAI;gBAAJ,IAAI,EAAE;QACZ,UAAU,CAAC,EAAE,gBAAgB,CAAC;QAC9B,YAAY,CAAC,EAAE;YAAE,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAAC;YAAC,eAAe,CAAC,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;YAAC,KAAK,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;SAAE,CAAC;QACjJ,UAAU,CAAC,EAAE,gBAAgB,CAAC;KAC/B;WAGU,MAAM,IAAI,OAAO,CAAC,cAAc,CAAC;IAYxC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAS5B,OAAO,CAAC,oBAAoB;IAY5B,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM;YAI/B,UAAU;YAiBV,iBAAiB;IAY/B,OAAO,CAAC,gBAAgB;IAIlB,oBAAoB,CAAC,SAAS,EAAE,mBAAmB,GAAG,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;YAc/E,qBAAqB;IAoB7B,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC;IAQ5D,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,CAAC;IAyD3G,OAAO,CAAC,mBAAmB;IAYrB,sBAAsB,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC;CAuOjF"}

package/dist/services/agents/RoutingService.js

@@ -0,0 +1,386 @@
+import { canonicalizeCommandName, getKnownDocdexScopes, getKnownQaProfiles, getCommandRequiredCapabilities, } from "@mcoda/shared";
+import { AgentService } from "@mcoda/agents";
+import { GlobalRepository } from "@mcoda/db";
+import { RoutingApiClient } from "./generated/RoutingApiClient.js";
+export class RoutingService {
+    constructor(deps) {
+        this.deps = deps;
+    }
+    static async create() {
+        let routingApi;
+        try {
+            routingApi = RoutingApiClient.create();
+        }
+        catch {
+            routingApi = undefined;
+        }
+        const globalRepo = await GlobalRepository.create();
+        const agentService = new AgentService(globalRepo);
+        return new RoutingService({ routingApi, globalRepo, agentService });
+    }
+    async close() {
+        if (this.deps.agentService?.close) {
+            await this.deps.agentService.close();
+        }
+        if (!this.deps.agentService?.close && this.deps.globalRepo?.close) {
+            await this.deps.globalRepo.close();
+        }
+    }
+    requiredCapabilities(commandName, taskType) {
+        const normalized = this.normalizeCommand(commandName);
+        const required = [...getCommandRequiredCapabilities(normalized)];
+        if (taskType) {
+            const lower = taskType.toLowerCase();
+            if (lower.includes("qa")) {
+                required.push("qa_interpretation");
+            }
+        }
+        return Array.from(new Set(required));
+    }
+    normalizeCommand(commandName) {
+        return canonicalizeCommandName(commandName);
+    }
+    async fetchAgent(idOrSlug) {
+        const apiAgent = (await this.deps.routingApi?.getAgent(idOrSlug)) ??
+            (await this.deps.routingApi?.listAgents())?.find((a) => a.id === idOrSlug || a.slug === idOrSlug);
+        if (apiAgent)
+            return apiAgent;
+        if (this.deps.agentService) {
+            return this.deps.agentService.resolveAgent(idOrSlug);
+        }
+        if (this.deps.globalRepo) {
+            const byId = await this.deps.globalRepo.getAgentById(idOrSlug);
+            if (byId)
+                return byId;
+            const bySlug = await this.deps.globalRepo.getAgentBySlug(idOrSlug);
+            if (bySlug)
+                return bySlug;
+        }
+        throw new Error(`Agent ${idOrSlug} not found via routing API`);
+    }
+    async fetchCapabilities(agent) {
+        const caps = agent.capabilities ?? [];
+        if (caps.length)
+            return caps;
+        if (this.deps.agentService?.getCapabilities) {
+            return this.deps.agentService.getCapabilities(agent.id);
+        }
+        if (this.deps.globalRepo) {
+            return this.deps.globalRepo.getAgentCapabilities(agent.id);
+        }
+        return [];
+    }
+    normalizeProfile(value) {
+        return value ? value.trim().toLowerCase().replace(/[_\s]+/g, "-") : undefined;
+    }
+    async getWorkspaceDefaults(workspace) {
+        const workspaceId = typeof workspace === "string" ? workspace : workspace.workspaceId;
+        if (typeof workspace !== "string") {
+            await this.migrateLegacyDefaults(workspace);
+        }
+        if (this.deps.routingApi) {
+            return (await this.deps.routingApi.getWorkspaceDefaults(workspaceId)) ?? [];
+        }
+        if (this.deps.globalRepo) {
+            return this.deps.globalRepo.getWorkspaceDefaults(workspaceId);
+        }
+        return [];
+    }
+    async migrateLegacyDefaults(workspace) {
+        if (!this.deps.routingApi)
+            return;
+        const legacyIds = workspace.legacyWorkspaceIds ?? [];
+        if (!legacyIds.length)
+            return;
+        const current = (await this.deps.routingApi.getWorkspaceDefaults(workspace.workspaceId)) ?? [];
+        if (current.length > 0)
+            return;
+        for (const legacyId of legacyIds) {
+            const legacy = await this.deps.routingApi.getWorkspaceDefaults(legacyId);
+            if (legacy && legacy.length) {
+                const set = {};
+                for (const entry of legacy) {
+                    const agent = await this.fetchAgent(entry.agentId);
+                    set[this.normalizeCommand(entry.commandName)] = agent.slug ?? agent.id;
+                }
+                await this.updateWorkspaceDefaults(workspace.workspaceId, { set });
+                break;
+            }
+        }
+    }
+    async getAgentSummary(agentId) {
+        try {
+            return await this.fetchAgent(agentId);
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async updateWorkspaceDefaults(workspaceId, update) {
+        const qaProfiles = getKnownQaProfiles().map((p) => this.normalizeProfile(p)).filter(Boolean);
+        const docdexScopes = getKnownDocdexScopes().map((p) => this.normalizeProfile(p)).filter(Boolean);
+        const normalizedQa = this.normalizeProfile(update.qaProfile);
+        const normalizedDocdex = this.normalizeProfile(update.docdexScope);
+        if (normalizedQa && qaProfiles.length && !qaProfiles.includes(normalizedQa)) {
+            throw new Error(`Unknown QA profile ${update.qaProfile}; allowed values: ${qaProfiles.join(", ")}`);
+        }
+        if (normalizedDocdex && docdexScopes.length && !docdexScopes.includes(normalizedDocdex)) {
+            throw new Error(`Unknown docdex scope ${update.docdexScope}; allowed values: ${docdexScopes.join(", ")}`);
+        }
+        const normalizedSet = {};
+        const setEntries = Object.entries(update.set ?? {});
+        for (const [commandName, agentSlug] of setEntries) {
+            const normalizedCommand = this.normalizeCommand(commandName);
+            const agent = await this.fetchAgent(agentSlug);
+            const capabilities = await this.fetchCapabilities(agent);
+            const required = this.requiredCapabilities(normalizedCommand);
+            const missing = required.filter((cap) => !capabilities.includes(cap));
+            if (missing.length) {
+                throw new Error(`Agent ${agentSlug} is missing required capabilities for ${normalizedCommand}: ${missing.join(", ")}`);
+            }
+            normalizedSet[normalizedCommand] = agent.slug ?? agent.id;
+        }
+        const normalizedReset = (update.reset ?? []).map((command) => this.normalizeCommand(command));
+        if (this.deps.routingApi) {
+            const updated = await this.deps.routingApi.updateWorkspaceDefaults(workspaceId, {
+                ...update,
+                qaProfile: normalizedQa ?? update.qaProfile,
+                docdexScope: normalizedDocdex ?? update.docdexScope,
+                set: Object.keys(normalizedSet).length ? normalizedSet : undefined,
+                reset: normalizedReset.length ? normalizedReset : undefined,
+            });
+            return updated ?? [];
+        }
+        if (!this.deps.globalRepo) {
+            throw new Error("Routing defaults are unavailable without a routing API or global repository");
+        }
+        for (const [commandName, agentSlug] of Object.entries(normalizedSet)) {
+            const agent = await this.fetchAgent(agentSlug);
+            await this.deps.globalRepo.setWorkspaceDefault(workspaceId, commandName, agent.id, {
+                qaProfile: normalizedQa ?? update.qaProfile,
+                docdexScope: normalizedDocdex ?? update.docdexScope,
+            });
+        }
+        for (const commandName of normalizedReset) {
+            await this.deps.globalRepo.removeWorkspaceDefault(workspaceId, commandName);
+        }
+        return this.deps.globalRepo.getWorkspaceDefaults(workspaceId);
+    }
+    buildPreviewRequest(params) {
+        const commandName = this.normalizeCommand(params.commandName);
+        return {
+            workspaceId: params.workspace.workspaceId,
+            commandName,
+            agentOverride: params.overrideAgentSlug,
+            taskType: params.taskType,
+            projectKey: params.projectKey,
+            requiredCapabilities: this.requiredCapabilities(commandName, params.taskType),
+        };
+    }
+    async resolveAgentForCommand(params) {
+        await this.migrateLegacyDefaults(params.workspace);
+        const normalizedCommand = this.normalizeCommand(params.commandName);
+        const requiredCaps = this.requiredCapabilities(normalizedCommand, params.taskType);
+        const fillHealth = async (agentId, current) => {
+            if (current && current.status)
+                return current;
+            const apiAgent = await this.deps.routingApi?.getAgent(agentId);
+            if (apiAgent?.health)
+                return apiAgent.health;
+            if (this.deps.globalRepo) {
+                return this.deps.globalRepo.getAgentHealth(agentId);
+            }
+            return current;
+        };
+        const fallbackFromDefaults = async () => {
+            const workspaceDefaults = (await this.deps.routingApi?.getWorkspaceDefaults(params.workspace.workspaceId)) ?? [];
+            const globalDefaults = (await this.deps.routingApi?.getWorkspaceDefaults("__GLOBAL__")) ?? [];
+            const findDefault = (defaults, command) => defaults.find((d) => this.normalizeCommand(d.commandName) === command);
+            const candidates = [
+                findDefault(workspaceDefaults, normalizedCommand),
+                findDefault(globalDefaults, normalizedCommand),
+                findDefault(workspaceDefaults, "default"),
+                findDefault(globalDefaults, "default"),
+            ].filter(Boolean);
+            let chosen;
+            let capabilities = [];
+            let agent;
+            for (const candidate of candidates) {
+                const source = candidate.workspaceId === "__GLOBAL__"
+                    ? "global_default"
+                    : "workspace_default";
+                const resolvedAgent = await this.fetchAgent(candidate.agentId);
+                const caps = await this.fetchCapabilities(resolvedAgent);
+                const missingFallback = requiredCaps.filter((cap) => !caps.includes(cap));
+                if (missingFallback.length === 0) {
+                    chosen = { agentId: resolvedAgent.id, source, qaProfile: candidate.qaProfile, docdexScope: candidate.docdexScope };
+                    capabilities = caps;
+                    agent = resolvedAgent;
+                    const health = await fillHealth(resolvedAgent.id);
+                    if (health?.status === "unreachable") {
+                        continue;
+                    }
+                    break;
+                }
+            }
+            if (!chosen || !agent)
+                return null;
+            const health = await fillHealth(agent.id);
+            const preview = {
+                workspaceId: params.workspace.workspaceId,
+                commandName: normalizedCommand,
+                resolvedAgent: { ...agent, capabilities, health },
+                provenance: chosen.source,
+                requiredCapabilities: requiredCaps,
+                candidates: [
+                    {
+                        agent: { ...agent, capabilities, health },
+                        agentId: agent.id,
+                        agentSlug: agent.slug,
+                        source: chosen.source,
+                        capabilities,
+                        health,
+                    },
+                ],
+            };
+            return {
+                agent,
+                agentId: agent.id,
+                agentSlug: agent.slug,
+                model: agent.defaultModel,
+                capabilities,
+                healthStatus: health?.status ?? "unknown",
+                source: chosen.source,
+                routingPreview: preview,
+                requiredCapabilities: requiredCaps,
+                qaProfile: chosen.qaProfile,
+                docdexScope: chosen.docdexScope,
+            };
+        };
+        if (this.deps.routingApi) {
+            const preview = await this.deps.routingApi.preview(this.buildPreviewRequest(params));
+            if (!preview || !preview.resolvedAgent) {
+                throw new Error(`Routing preview did not return a resolved agent for ${normalizedCommand}`);
+            }
+            const resolvedAgent = preview.resolvedAgent;
+            const previewCandidate = preview.candidates?.find((c) => c.agentId === resolvedAgent.id || c.agentSlug === resolvedAgent.slug) ??
+                undefined;
+            let capabilities = previewCandidate?.capabilities ?? preview.resolvedAgent.capabilities ?? preview.requiredCapabilities ?? [];
+            if (!capabilities.length) {
+                capabilities = await this.fetchCapabilities(resolvedAgent);
+            }
+            const missing = requiredCaps.filter((cap) => !capabilities.includes(cap));
+            if (missing.length > 0) {
+                if (params.overrideAgentSlug) {
+                    // try fetching full capabilities when override was provided as slug
+                    const overrideAgent = await this.fetchAgent(params.overrideAgentSlug);
+                    const overrideCaps = await this.fetchCapabilities(overrideAgent);
+                    const overrideMissing = requiredCaps.filter((cap) => !overrideCaps.includes(cap));
+                    if (overrideMissing.length === 0) {
+                        const health = await fillHealth(overrideAgent.id, previewCandidate?.health);
+                        return {
+                            agent: overrideAgent,
+                            agentId: overrideAgent.id,
+                            agentSlug: overrideAgent.slug,
+                            model: overrideAgent.defaultModel,
+                            capabilities: overrideCaps,
+                            healthStatus: health?.status ?? "unknown",
+                            source: "override",
+                            routingPreview: preview,
+                            requiredCapabilities: requiredCaps,
+                        };
+                    }
+                }
+                const fallback = await fallbackFromDefaults();
+                if (fallback) {
+                    return fallback;
+                }
+                throw new Error(`Resolved agent ${resolvedAgent.slug} is missing required capabilities for ${normalizedCommand}: ${missing.join(", ")}`);
+            }
+            const health = previewCandidate?.health ?? preview.resolvedAgent.health;
+            const finalHealth = await fillHealth(resolvedAgent.id, health);
+            const healthStatus = finalHealth?.status ?? health?.status ?? "unknown";
+            if (healthStatus === "unreachable") {
+                const fallback = await fallbackFromDefaults();
+                if (fallback)
+                    return fallback;
+                throw new Error(`Resolved agent ${resolvedAgent.slug} is unreachable`);
+            }
+            return {
+                agent: resolvedAgent,
+                agentId: resolvedAgent.id,
+                agentSlug: resolvedAgent.slug,
+                model: resolvedAgent.defaultModel,
+                capabilities,
+                healthStatus,
+                source: preview.provenance ?? (params.overrideAgentSlug ? "override" : "workspace_default"),
+                routingPreview: preview,
+                qaProfile: preview.qaProfile,
+                docdexScope: preview.docdexScope,
+                requiredCapabilities: requiredCaps,
+            };
+        }
+        if (!this.deps.globalRepo) {
+            throw new Error("Routing is unavailable without a routing API or global repository");
+        }
+        const workspaceDefaults = await this.deps.globalRepo.getWorkspaceDefaults(params.workspace.workspaceId);
+        const globalDefaults = await this.deps.globalRepo.getWorkspaceDefaults("__GLOBAL__");
+        const findDefault = (defaults, command) => defaults.find((d) => this.normalizeCommand(d.commandName) === command);
+        const commandDefault = findDefault(workspaceDefaults, normalizedCommand) ?? findDefault(globalDefaults, normalizedCommand);
+        const genericDefault = findDefault(workspaceDefaults, "default") ?? findDefault(globalDefaults, "default");
+        const selected = params.overrideAgentSlug != null
+            ? { agentId: params.overrideAgentSlug, source: "override" }
+            : commandDefault
+                ? { agentId: commandDefault.agentId, source: commandDefault.workspaceId === "__GLOBAL__" ? "global_default" : "workspace_default", qaProfile: commandDefault.qaProfile, docdexScope: commandDefault.docdexScope }
+                : genericDefault
+                    ? {
+                        agentId: genericDefault.agentId,
+                        source: genericDefault.workspaceId === "__GLOBAL__" ? "global_default" : "workspace_default",
+                        qaProfile: genericDefault.qaProfile,
+                        docdexScope: genericDefault.docdexScope,
+                    }
+                    : undefined;
+        if (!selected) {
+            throw new Error(`No routing defaults found for command ${normalizedCommand}`);
+        }
+        const agent = await this.fetchAgent(selected.agentId);
+        const capabilities = await this.fetchCapabilities(agent);
+        const missing = requiredCaps.filter((cap) => !capabilities.includes(cap));
+        if (missing.length) {
+            throw new Error(`Resolved agent ${agent.slug} is missing required capabilities for ${normalizedCommand}: ${missing.join(", ")}`);
+        }
+        const health = await this.deps.globalRepo.getAgentHealth(agent.id);
+        const preview = {
+            workspaceId: params.workspace.workspaceId,
+            commandName: normalizedCommand,
+            resolvedAgent: { ...agent, capabilities, health },
+            provenance: selected.source,
+            requiredCapabilities: requiredCaps,
+            qaProfile: selected.qaProfile,
+            docdexScope: selected.docdexScope,
+            candidates: [
+                {
+                    agent: { ...agent, capabilities, health },
+                    agentId: agent.id,
+                    agentSlug: agent.slug,
+                    source: selected.source,
+                    capabilities,
+                    health,
+                },
+            ],
+        };
+        return {
+            agent,
+            agentId: agent.id,
+            agentSlug: agent.slug,
+            model: agent.defaultModel,
+            capabilities,
+            healthStatus: health?.status ?? "unknown",
+            source: selected.source,
+            routingPreview: preview,
+            qaProfile: selected.qaProfile,
+            docdexScope: selected.docdexScope,
+            requiredCapabilities: requiredCaps,
+        };
+    }
+}

package/dist/services/agents/generated/RoutingApiClient.d.ts

@@ -0,0 +1,21 @@
+import { Agent, RoutingDefaults, RoutingDefaultsUpdate, RoutingPreview } from "@mcoda/shared";
+export interface RoutingPreviewRequest {
+    workspaceId: string;
+    commandName: string;
+    agentOverride?: string;
+    taskType?: string;
+    projectKey?: string;
+    requiredCapabilities?: string[];
+}
+export declare class RoutingApiClient {
+    private baseUrl;
+    constructor(baseUrl?: string);
+    static create(): RoutingApiClient;
+    private build;
+    getWorkspaceDefaults(workspaceId: string): Promise<RoutingDefaults | undefined>;
+    updateWorkspaceDefaults(workspaceId: string, update: RoutingDefaultsUpdate): Promise<RoutingDefaults | undefined>;
+    preview(request: RoutingPreviewRequest): Promise<RoutingPreview | undefined>;
+    listAgents(): Promise<Agent[] | undefined>;
+    getAgent(idOrSlug: string): Promise<Agent | undefined>;
+}
+//# sourceMappingURL=RoutingApiClient.d.ts.map

package/dist/services/agents/generated/RoutingApiClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RoutingApiClient.d.ts","sourceRoot":"","sources":["../../../../src/services/agents/generated/RoutingApiClient.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,EACL,eAAe,EACf,qBAAqB,EACrB,cAAc,EACf,MAAM,eAAe,CAAC;AAoBvB,MAAM,WAAW,qBAAqB;IACpC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,EAAE,CAAC;CACjC;AAED,qBAAa,gBAAgB;IACf,OAAO,CAAC,OAAO;gBAAP,OAAO,GAAE,MAAsB;IAEnD,MAAM,CAAC,MAAM,IAAI,gBAAgB;IAIjC,OAAO,CAAC,KAAK;IAIP,oBAAoB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IAO/E,uBAAuB,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,EAAE,qBAAqB,GAAG,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;IASjH,OAAO,CAAC,OAAO,EAAE,qBAAqB,GAAG,OAAO,CAAC,cAAc,GAAG,SAAS,CAAC;IAgB5E,UAAU,IAAI,OAAO,CAAC,KAAK,EAAE,GAAG,SAAS,CAAC;IAK1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,GAAG,SAAS,CAAC;CAM7D"}

package/dist/services/agents/generated/RoutingApiClient.js

@@ -0,0 +1,68 @@
+const pickBaseUrl = () => {
+    const base = process.env.MCODA_ROUTING_API_URL ?? process.env.MCODA_API_BASE_URL;
+    if (!base) {
+        throw new Error("MCODA_API_BASE_URL (or MCODA_ROUTING_API_URL) is required for routing operations per SDS.");
+    }
+    return base;
+};
+const handleResponse = async (resp) => {
+    if (resp.status === 404)
+        return undefined;
+    if (!resp.ok) {
+        const text = await resp.text();
+        throw new Error(`Routing API request failed (${resp.status}): ${text}`);
+    }
+    if (resp.status === 204)
+        return undefined;
+    return (await resp.json());
+};
+export class RoutingApiClient {
+    constructor(baseUrl = pickBaseUrl()) {
+        this.baseUrl = baseUrl;
+    }
+    static create() {
+        return new RoutingApiClient();
+    }
+    build(pathname) {
+        return new URL(pathname, this.baseUrl).toString();
+    }
+    async getWorkspaceDefaults(workspaceId) {
+        const resp = await fetch(this.build(`/workspaces/${encodeURIComponent(workspaceId)}/defaults`), {
+            headers: { accept: "application/json" },
+        });
+        return handleResponse(resp);
+    }
+    async updateWorkspaceDefaults(workspaceId, update) {
+        const resp = await fetch(this.build(`/workspaces/${encodeURIComponent(workspaceId)}/defaults`), {
+            method: "PUT",
+            headers: { accept: "application/json", "content-type": "application/json" },
+            body: JSON.stringify(update),
+        });
+        return handleResponse(resp);
+    }
+    async preview(request) {
+        const resp = await fetch(this.build("/routing/preview"), {
+            method: "POST",
+            headers: { accept: "application/json", "content-type": "application/json" },
+            body: JSON.stringify({
+                workspaceId: request.workspaceId,
+                commandName: request.commandName,
+                agentOverride: request.agentOverride,
+                taskType: request.taskType,
+                projectKey: request.projectKey,
+                requiredCapabilities: request.requiredCapabilities,
+            }),
+        });
+        return handleResponse(resp);
+    }
+    async listAgents() {
+        const resp = await fetch(this.build("/agents"), { headers: { accept: "application/json" } });
+        return handleResponse(resp);
+    }
+    async getAgent(idOrSlug) {
+        const resp = await fetch(this.build(`/agents/${encodeURIComponent(idOrSlug)}`), {
+            headers: { accept: "application/json" },
+        });
+        return handleResponse(resp);
+    }
+}