@mcoda/core 0.1.9 → 0.1.12

package/dist/services/openapi/OpenApiService.js

@@ -8,12 +8,263 @@ import { GlobalRepository, WorkspaceRepository } from "@mcoda/db";
 import { JobService } from "../jobs/JobService.js";
 import { RoutingService } from "../agents/RoutingService.js";
 import { AgentRatingService } from "../agents/AgentRatingService.js";
+import { buildDocInventory } from "../docs/DocInventory.js";
 const OPENAPI_TAGS = [
 // For project-specific specs, tags come from context; this is only a fallback.
 ];
 const OPENAPI_VERSION = "3.1.0";
+const PRIMARY_OPENAPI_FILENAME = "mcoda.yaml";
+const ADMIN_OPENAPI_FILENAME = "mcoda-admin.yaml";
 const CONTEXT_TOKEN_BUDGET = 8000;
+const OPENAPI_TIMEOUT_ENV = "MCODA_OPENAPI_TIMEOUT_SECONDS";
+const OPENAPI_HEARTBEAT_INTERVAL_MS = 15000;
+const OPENAPI_PRIMARY_DRAFT = "openapi-primary-draft.yaml";
+const OPENAPI_ADMIN_DRAFT = "openapi-admin-draft.yaml";
 const estimateTokens = (text) => Math.max(1, Math.ceil(text.length / 4));
+const parseTimeoutSeconds = (value) => {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0)
+        return undefined;
+    return parsed * 1000;
+};
+const formatIterationLabel = (iteration) => {
+    if (!iteration || !Number.isFinite(iteration.current))
+        return undefined;
+    const current = iteration.current;
+    const max = iteration.max;
+    if (Number.isFinite(max) && max > 0)
+        return `${current}/${max}`;
+    return `${current}`;
+};
+const compactPayload = (payload) => Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== undefined));
+export class OpenApiJobError extends Error {
+    constructor(code, message, jobId) {
+        super(message);
+        this.code = code;
+        this.jobId = jobId;
+    }
+}
+export const normalizeOpenApiPath = (value) => {
+    if (!value)
+        return "/";
+    const trimmed = value.trim();
+    const withLeading = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
+    const withoutTrailing = withLeading.length > 1 ? withLeading.replace(/\/+$/, "") : withLeading;
+    const segments = withoutTrailing
+        .split("/")
+        .filter(Boolean)
+        .map((segment) => {
+        if (segment.startsWith("{") && segment.endsWith("}"))
+            return "{param}";
+        return segment;
+    });
+    return segments.length ? `/${segments.join("/")}` : "/";
+};
+export const extractOpenApiPaths = (raw) => {
+    const errors = [];
+    if (!raw || !raw.trim()) {
+        return { paths: [], errors: ["OpenAPI spec is empty."] };
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch (error) {
+        return { paths: [], errors: [`OpenAPI parse failed: ${error.message}`] };
+    }
+    if (!parsed || typeof parsed !== "object") {
+        return { paths: [], errors: ["OpenAPI spec is not a YAML object."] };
+    }
+    const paths = parsed.paths;
+    if (!paths || typeof paths !== "object") {
+        return { paths: [], errors: ["OpenAPI spec missing paths section."] };
+    }
+    return { paths: Object.keys(paths).filter(Boolean), errors };
+};
+const escapeRegExp = (value) => value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+export const findOpenApiPathLine = (raw, target) => {
+    if (!raw || !target)
+        return undefined;
+    const lines = raw.split(/\r?\n/);
+    const escaped = escapeRegExp(target);
+    const pattern = new RegExp(`^\\s*['"]?${escaped}['"]?\\s*:`);
+    for (let i = 0; i < lines.length; i += 1) {
+        if (pattern.test(lines[i] ?? ""))
+            return i + 1;
+    }
+    return undefined;
+};
+const ADMIN_PATH_PATTERN = /\/admin(?:\/|\b)/i;
+const ADMIN_CONTEXT_PATTERN = /\badmin\b.*\b(api|endpoint|console|dashboard|portal|interface|panel|ui)\b/i;
+export const findAdminSurfaceMentions = (raw) => {
+    if (!raw || !raw.trim())
+        return [];
+    const lines = raw.split(/\r?\n/);
+    const mentions = [];
+    const seen = new Set();
+    let inFence = false;
+    let currentHeading;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i] ?? "";
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        if (/^```|^~~~/.test(trimmed)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const headingMatch = trimmed.match(/^#{1,6}\s+(.*)$/);
+        if (headingMatch) {
+            currentHeading = headingMatch[1]?.trim() || undefined;
+            if (currentHeading && /\badmin\b/i.test(currentHeading)) {
+                if (!seen.has(i + 1)) {
+                    mentions.push({ line: i + 1, excerpt: currentHeading, heading: currentHeading });
+                    seen.add(i + 1);
+                }
+            }
+            continue;
+        }
+        if (ADMIN_PATH_PATTERN.test(trimmed) || ADMIN_CONTEXT_PATTERN.test(trimmed)) {
+            if (!seen.has(i + 1)) {
+                mentions.push({ line: i + 1, excerpt: trimmed, heading: currentHeading });
+                seen.add(i + 1);
+            }
+        }
+    }
+    return mentions;
+};
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
+const OPERATION_ID_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const isPlainObject = (value) => Boolean(value && typeof value === "object" && !Array.isArray(value));
+const operationUsesJsonSchema = (operation) => {
+    const contentBlocks = [];
+    const requestContent = operation.requestBody?.content;
+    if (isPlainObject(requestContent))
+        contentBlocks.push(requestContent);
+    const responses = operation.responses;
+    if (isPlainObject(responses)) {
+        for (const response of Object.values(responses)) {
+            const responseContent = response?.content;
+            if (isPlainObject(responseContent))
+                contentBlocks.push(responseContent);
+        }
+    }
+    for (const content of contentBlocks) {
+        for (const [contentType, media] of Object.entries(content)) {
+            if (!contentType.toLowerCase().includes("json"))
+                continue;
+            if (media?.schema)
+                return true;
+        }
+    }
+    return false;
+};
+export const validateOpenApiSchema = (doc) => {
+    const errors = [];
+    if (!isPlainObject(doc)) {
+        errors.push("OpenAPI spec is not an object.");
+        return errors;
+    }
+    const version = doc.openapi;
+    if (!version) {
+        errors.push("Missing openapi version.");
+    }
+    else if (typeof version !== "string" || !version.startsWith("3.")) {
+        errors.push(`Invalid openapi version: ${String(version)}.`);
+    }
+    const info = doc.info;
+    if (!isPlainObject(info)) {
+        errors.push("Missing info section.");
+    }
+    else {
+        if (!info.title)
+            errors.push("Missing info.title.");
+        if (!info.version)
+            errors.push("Missing info.version.");
+    }
+    const paths = doc.paths;
+    if (!isPlainObject(paths)) {
+        errors.push("Missing paths section.");
+    }
+    else if (Object.keys(paths).length === 0) {
+        errors.push("paths section is empty.");
+    }
+    const operationIds = new Map();
+    let hasOperations = false;
+    let hasJsonSchemaUsage = false;
+    if (isPlainObject(paths)) {
+        for (const [pathKey, pathItem] of Object.entries(paths)) {
+            if (!isPlainObject(pathItem)) {
+                errors.push(`Path item for ${pathKey} must be an object.`);
+                continue;
+            }
+            const methods = HTTP_METHODS.filter((method) => method in pathItem);
+            if (methods.length === 0) {
+                errors.push(`Path ${pathKey} has no operations.`);
+                continue;
+            }
+            for (const method of methods) {
+                const operation = pathItem[method];
+                if (!isPlainObject(operation)) {
+                    errors.push(`Operation ${method.toUpperCase()} ${pathKey} must be an object.`);
+                    continue;
+                }
+                hasOperations = true;
+                if (operationUsesJsonSchema(operation)) {
+                    hasJsonSchemaUsage = true;
+                }
+                const operationId = operation.operationId;
+                if (!operationId || typeof operationId !== "string") {
+                    errors.push(`Missing operationId for ${method.toUpperCase()} ${pathKey}.`);
+                }
+                else if (/\s/.test(operationId) || !OPERATION_ID_PATTERN.test(operationId)) {
+                    errors.push(`Invalid operationId "${operationId}" for ${method.toUpperCase()} ${pathKey}.`);
+                }
+                else if (operationIds.has(operationId)) {
+                    errors.push(`Duplicate operationId "${operationId}" detected.`);
+                }
+                else {
+                    operationIds.set(operationId, `${method.toUpperCase()} ${pathKey}`);
+                }
+            }
+        }
+    }
+    const components = doc.components;
+    const schemas = isPlainObject(components) ? components.schemas : undefined;
+    const schemaCount = isPlainObject(schemas) ? Object.keys(schemas).length : 0;
+    const hasSchemaRefs = typeof doc === "object" && JSON.stringify(doc).includes("#/components/schemas/");
+    if ((hasJsonSchemaUsage || hasSchemaRefs || hasOperations) && schemaCount === 0) {
+        errors.push("Missing components.schemas for JSON payloads.");
+    }
+    return errors;
+};
+export const validateOpenApiSchemaContent = (raw) => {
+    if (!raw || !raw.trim()) {
+        return { errors: ["OpenAPI spec is empty."] };
+    }
+    let parsed;
+    try {
+        parsed = YAML.parse(raw);
+    }
+    catch (error) {
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch (jsonError) {
+            return {
+                errors: [
+                    `OpenAPI parse failed: ${error.message ?? String(error)}`,
+                ],
+            };
+        }
+    }
+    const errors = validateOpenApiSchema(parsed);
+    return { doc: parsed, errors };
+};
 const fileExists = async (candidate) => {
     try {
         await fs.access(candidate);
@@ -48,9 +299,12 @@ class OpenapiContextAssembler {
     }
     async findLatestLocalDoc(docType) {
         const candidates = [];
-        const dirNames = [".mcoda/docs", "docs"];
-        for (const dir of dirNames) {
-            const target = path.join(this.workspace.workspaceRoot, dir, docType.toLowerCase());
+        const docDirs = [
+            path.join(this.workspace.mcodaDir, "docs"),
+            path.join(this.workspace.workspaceRoot, "docs"),
+        ];
+        for (const dir of docDirs) {
+            const target = path.join(dir, docType.toLowerCase());
             try {
                 const entries = await fs.readdir(target);
                 for (const entry of entries.filter((e) => e.endsWith(".md"))) {
@@ -204,7 +458,8 @@ class OpenapiContextAssembler {
 export class OpenApiService {
     constructor(workspace, deps) {
         this.workspace = workspace;
-        this.docdex = deps?.docdex ?? new DocdexClient({ workspaceRoot: workspace.workspaceRoot });
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
+        this.docdex = deps?.docdex ?? new DocdexClient({ workspaceRoot: workspace.workspaceRoot, repoId: docdexRepoId });
         this.jobService = deps?.jobService ?? new JobService(workspace, undefined, { noTelemetry: deps?.noTelemetry });
         this.agentService = deps.agentService;
         this.routingService = deps.routingService;
@@ -216,9 +471,11 @@ export class OpenApiService {
         const repo = await GlobalRepository.create();
         const agentService = new AgentService(repo);
         const routingService = await RoutingService.create();
+        const docdexRepoId = workspace.config?.docdexRepoId ?? process.env.MCODA_DOCDEX_REPO_ID ?? process.env.DOCDEX_REPO_ID;
         const docdex = new DocdexClient({
             workspaceRoot: workspace.workspaceRoot,
             baseUrl: workspace.config?.docdexUrl ?? process.env.MCODA_DOCDEX_URL,
+            repoId: docdexRepoId,
         });
         const jobService = new JobService(workspace, undefined, { noTelemetry: options.noTelemetry });
         return new OpenApiService(workspace, { agentService, routingService, docdex, jobService, repo, noTelemetry: options.noTelemetry });
@@ -306,20 +563,7 @@ export class OpenApiService {
         return body.trim();
     }
     validateSpec(doc) {
-        const errors = [];
-        if (!doc || typeof doc !== "object") {
-            errors.push("Spec is not a YAML object.");
-            return errors;
-        }
-        if (!doc.openapi)
-            errors.push("Missing openapi version");
-        if (!doc.info?.title)
-            errors.push("Missing info.title");
-        if (!doc.info?.version)
-            errors.push("Missing info.version");
-        if (!doc.paths)
-            errors.push("paths section is required (can be empty if no HTTP API)");
-        return errors;
+        return validateOpenApiSchema(doc);
     }
     async runOpenapiValidator(doc) {
         try {
@@ -334,19 +578,27 @@ export class OpenApiService {
             return [error.message];
         }
     }
-    buildPrompt(context, cliVersion, retryReasons) {
+    buildPrompt(context, cliVersion, retryReasons, variant = "primary") {
         const contextBlocks = context.blocks
             .map((block) => `### ${block.label}\n${block.content}`)
             .join("\n\n");
         const retryNote = retryReasons?.length
             ? `\nPrevious attempt issues:\n${retryReasons.map((r) => `- ${r}`).join("\n")}\nFix them in this draft.\n`
             : "";
+        const adminNote = variant === "admin"
+            ? [
+                "This is the ADMIN OpenAPI spec. Include only administrative/control-plane endpoints.",
+                "Focus on admin consoles, moderation, user management, and internal admin workflows described in docs.",
+                "Prefer /admin or /internal/admin style prefixes; omit public/customer-facing APIs.",
+            ].join("\n")
+            : "";
         return [
             "You are generating an OpenAPI 3.1 YAML for THIS workspace/project using only the provided PDR/SDS/RFP context.",
             "Derive resources, schemas, and HTTP endpoints directly from the product requirements (e.g., todos CRUD, filters, search, bulk actions).",
             "If the documents describe a frontend-only/localStorage app, design a minimal REST API that could back those features (e.g., /todos, /todos/{id}, bulk operations, search/filter params) instead of returning an empty spec.",
             "Prefer concise tags derived from domain resources (e.g., Todos). Avoid generic mcoda/system endpoints unless explicitly described in the context.",
             `Use OpenAPI version ${OPENAPI_VERSION}, set info.title to the project name from context (fallback \"mcoda API\"), and info.version ${cliVersion}.`,
+            adminNote,
             "Return only valid YAML (no Markdown fences, no commentary).",
             retryNote,
             "Scope rules:",
@@ -369,7 +621,7 @@ export class OpenApiService {
         await fs.copyFile(target, backup);
         return backup;
     }
-    async registerOpenapi(outPath, content) {
+    async registerOpenapi(outPath, content, variant = "primary") {
         const branch = this.workspace.config?.branch ?? (await readGitBranch(this.workspace.workspaceRoot));
         return this.docdex.registerDocument({
             docType: "OPENAPI",
@@ -380,6 +632,7 @@ export class OpenApiService {
                 branch,
                 status: "canonical",
                 projectKey: this.workspace.config?.projectKey,
+                variant,
             },
         });
     }
@@ -389,24 +642,378 @@ export class OpenApiService {
         const issues = this.validateSpec(parsed);
         const validatorIssues = await this.runOpenapiValidator(parsed);
         issues.push(...validatorIssues);
-        return { spec: content, issues };
+        return { spec: content, issues, doc: parsed };
+    }
+    async collectAdminMentions() {
+        const warnings = [];
+        let inventory;
+        try {
+            inventory = await buildDocInventory({ workspace: this.workspace });
+        }
+        catch (error) {
+            warnings.push(`Doc inventory build failed: ${error.message ?? String(error)}`);
+        }
+        const records = [inventory?.pdr, inventory?.sds].filter((record) => Boolean(record));
+        if (records.length === 0) {
+            return { required: false, mentions: [], warnings };
+        }
+        const mentions = [];
+        for (const record of records) {
+            try {
+                const content = await fs.readFile(record.path, "utf8");
+                const found = findAdminSurfaceMentions(content);
+                for (const mention of found) {
+                    mentions.push({ record, mention });
+                }
+            }
+            catch (error) {
+                warnings.push(`Unable to read doc ${record.path}: ${error.message ?? String(error)}`);
+            }
+        }
+        return { required: mentions.length > 0, mentions, warnings };
+    }
+    openapiDraftPath(jobId, variant) {
+        const filename = variant === "admin" ? OPENAPI_ADMIN_DRAFT : OPENAPI_PRIMARY_DRAFT;
+        return path.join(this.workspace.mcodaDir, "jobs", jobId, filename);
+    }
+    async readOpenapiDraft(jobId, variant, draftPathOverride) {
+        const draftPath = draftPathOverride ?? this.openapiDraftPath(jobId, variant);
+        try {
+            return await fs.readFile(draftPath, "utf8");
+        }
+        catch {
+            return undefined;
+        }
+    }
+    async writeOpenapiDraft(jobId, variant, content) {
+        const draftPath = this.openapiDraftPath(jobId, variant);
+        await fs.mkdir(path.dirname(draftPath), { recursive: true });
+        await fs.writeFile(draftPath, content, "utf8");
+    }
+    async isJobCancelled(jobId) {
+        const job = await this.jobService.getJob(jobId);
+        const state = job?.jobState ?? job?.state;
+        return state === "cancelled";
+    }
+    async updateOpenapiJobStatus(jobId, state, options = {}) {
+        const iterationLabel = formatIterationLabel(options.iteration);
+        const detail = options.jobStateDetail ??
+            [
+                options.stage ? `openapi:${options.stage}` : undefined,
+                options.variant ? `variant:${options.variant}` : undefined,
+                iterationLabel ? `iter:${iterationLabel}` : undefined,
+            ]
+                .filter(Boolean)
+                .join(" ");
+        const payload = compactPayload({
+            ...options.payload,
+            openapi_stage: options.stage,
+            openapi_variant: options.variant,
+            openapi_iteration_current: options.iteration?.current,
+            openapi_iteration_max: options.iteration?.max,
+            openapi_iteration_label: iterationLabel,
+        });
+        const totalItems = options.totalUnits;
+        const processedItems = options.completedUnits;
+        await this.jobService.updateJobStatus(jobId, state, {
+            job_state_detail: detail || undefined,
+            totalUnits: options.totalUnits,
+            completedUnits: options.completedUnits,
+            totalItems,
+            processedItems,
+            payload,
+            errorSummary: options.errorSummary,
+        });
+    }
+    async writeOpenapiCheckpoint(jobId, stage, details) {
+        await this.jobService.writeCheckpoint(jobId, {
+            stage,
+            timestamp: new Date().toISOString(),
+            details,
+        });
+    }
+    startOpenapiHeartbeat(jobId, getStatus) {
+        let stopped = false;
+        let error;
+        const interval = setInterval(() => {
+            void (async () => {
+                if (stopped || error)
+                    return;
+                if (await this.isJobCancelled(jobId)) {
+                    error = new OpenApiJobError("cancelled", `OpenAPI job ${jobId} was cancelled.`, jobId);
+                    return;
+                }
+                const status = getStatus();
+                if (!status.stage)
+                    return;
+                await this.updateOpenapiJobStatus(jobId, "running", {
+                    stage: status.stage,
+                    variant: status.variant,
+                    iteration: status.iteration,
+                    totalUnits: status.totalUnits,
+                    completedUnits: status.completedUnits,
+                    payload: status.payload,
+                });
+            })().catch(() => {
+                // best-effort heartbeat
+            });
+        }, OPENAPI_HEARTBEAT_INTERVAL_MS);
+        return {
+            stop: () => {
+                stopped = true;
+                clearInterval(interval);
+            },
+            getError: () => error,
+        };
+    }
+    async tryResumeOpenapi(resumeJobId, warnings) {
+        const manifest = await this.jobService.readManifest(resumeJobId);
+        if (!manifest) {
+            warnings.push(`No resume data found for job ${resumeJobId}; starting a new OpenAPI job.`);
+            return undefined;
+        }
+        const manifestType = manifest.type ?? manifest.job_type ?? manifest.jobType;
+        if (manifestType && manifestType !== "openapi_change") {
+            throw new Error(`Job ${resumeJobId} is type ${manifestType}, not openapi_change. Use a matching job id or rerun without --resume.`);
+        }
+        const status = manifest.status ?? manifest.state ?? manifest.jobState;
+        if (status === "running" || status === "queued" || status === "checkpointing") {
+            throw new Error(`Job ${resumeJobId} is still running; use "mcoda job watch --id ${resumeJobId}" to monitor.`);
+        }
+        const payload = manifest.payload ?? {};
+        const outputPath = payload.outputPath ??
+            payload.openapi_primary_output_path ??
+            payload.openapi_output_path ??
+            payload.output_path;
+        const adminOutputPath = payload.adminOutputPath ??
+            payload.openapi_admin_output_path ??
+            payload.admin_output_path;
+        const primaryDraftPath = payload.openapi_primary_draft_path ?? this.openapiDraftPath(resumeJobId, "primary");
+        const adminDraftPath = payload.openapi_admin_draft_path ?? this.openapiDraftPath(resumeJobId, "admin");
+        let primaryDraft;
+        let adminDraft;
+        let spec;
+        let adminSpec;
+        primaryDraft = await this.readOpenapiDraft(resumeJobId, "primary", primaryDraftPath);
+        adminDraft = await this.readOpenapiDraft(resumeJobId, "admin", adminDraftPath);
+        if (outputPath && (await fileExists(outputPath))) {
+            try {
+                spec = await fs.readFile(outputPath, "utf8");
+            }
+            catch {
+                // ignore output read failures
+            }
+        }
+        if (adminOutputPath && (await fileExists(adminOutputPath))) {
+            try {
+                adminSpec = await fs.readFile(adminOutputPath, "utf8");
+            }
+            catch {
+                // ignore output read failures
+            }
+        }
+        const docdexId = payload.docdexId ?? payload.openapi_docdex_id ?? payload.docdex_id;
+        const adminDocdexId = payload.adminDocdexId ?? payload.openapi_admin_docdex_id ?? payload.admin_docdex_id;
+        const lastStage = payload.openapi_stage ?? manifest.lastCheckpoint ?? manifest.last_checkpoint;
+        const jobId = manifest.id ?? manifest.job_id ?? resumeJobId;
+        const outputReady = Boolean(spec || primaryDraft);
+        if (status === "completed" || status === "succeeded") {
+            if (outputReady) {
+                warnings.push(`Resume requested; returning completed OpenAPI from job ${resumeJobId}.`);
+                return {
+                    job: { ...manifest, id: jobId },
+                    completed: true,
+                    outputPath,
+                    adminOutputPath,
+                    spec: spec ?? primaryDraft,
+                    adminSpec: adminSpec ?? adminDraft,
+                    primaryDraft,
+                    adminDraft,
+                    docdexId,
+                    adminDocdexId,
+                    lastStage,
+                };
+            }
+            warnings.push(`Resume requested for job ${resumeJobId}, but output is missing; restarting generation.`);
+        }
+        if (primaryDraft) {
+            warnings.push(`Resuming OpenAPI primary draft from job ${resumeJobId}.`);
+        }
+        else {
+            warnings.push(`Resume requested for ${resumeJobId}; regenerating OpenAPI primary draft.`);
+        }
+        return {
+            job: { ...manifest, id: jobId },
+            completed: false,
+            outputPath,
+            adminOutputPath,
+            spec,
+            adminSpec,
+            primaryDraft,
+            adminDraft,
+            docdexId,
+            adminDocdexId,
+            lastStage,
+        };
     }
     async generateFromDocs(options) {
+        const warnings = [];
         const commandRun = await this.jobService.startCommandRun("openapi-from-docs", options.projectKey);
-        const job = await this.jobService.startJob("openapi_change", commandRun.id, options.projectKey, {
-            commandName: commandRun.commandName,
-            payload: { workspaceRoot: this.workspace.workspaceRoot, projectKey: options.projectKey },
+        let job;
+        let resumePrimaryDraft;
+        let resumeAdminDraft;
+        let resumeDocdexId;
+        let resumeAdminDocdexId;
+        let resumeOutputPath;
+        let resumeAdminOutputPath;
+        let resumeSpec;
+        let resumeAdminSpec;
+        if (options.resumeJobId) {
+            const resumed = await this.tryResumeOpenapi(options.resumeJobId, warnings);
+            if (resumed) {
+                job = resumed.job;
+                if (resumed.completed) {
+                    await this.jobService.finishCommandRun(commandRun.id, "succeeded");
+                    return {
+                        jobId: job.id,
+                        commandRunId: commandRun.id,
+                        outputPath: resumed.outputPath,
+                        spec: resumed.spec ?? "",
+                        adminOutputPath: resumed.adminOutputPath,
+                        adminSpec: resumed.adminSpec,
+                        docdexId: resumed.docdexId,
+                        adminDocdexId: resumed.adminDocdexId,
+                        warnings,
+                    };
+                }
+                await this.updateOpenapiJobStatus(job.id, "running", {
+                    stage: "resuming",
+                    iteration: options.iteration,
+                    payload: compactPayload({ resumedBy: commandRun.id }),
+                });
+                await this.writeOpenapiCheckpoint(job.id, "resume_started", { resumedBy: commandRun.id });
+                resumePrimaryDraft = resumed.primaryDraft;
+                resumeAdminDraft = resumed.adminDraft;
+                resumeDocdexId = resumed.docdexId;
+                resumeAdminDocdexId = resumed.adminDocdexId;
+                resumeOutputPath = resumed.outputPath;
+                resumeAdminOutputPath = resumed.adminOutputPath;
+                resumeSpec = resumed.spec;
+                resumeAdminSpec = resumed.adminSpec;
+            }
+        }
+        if (!job) {
+            job = await this.jobService.startJob("openapi_change", commandRun.id, options.projectKey, {
+                commandName: commandRun.commandName,
+                payload: {
+                    workspaceRoot: this.workspace.workspaceRoot,
+                    projectKey: options.projectKey,
+                    resumeSupported: true,
+                    cliVersion: options.cliVersion,
+                },
+            });
+        }
+        const timeoutMs = options.timeoutMs ?? parseTimeoutSeconds(process.env[OPENAPI_TIMEOUT_ENV]);
+        const timeoutAt = timeoutMs ? Date.now() + timeoutMs : undefined;
+        const iteration = options.iteration;
+        const iterationLabel = formatIterationLabel(iteration);
+        const openapiDir = await this.ensureOpenapiDir();
+        const outputPath = resumeOutputPath ?? path.join(openapiDir, PRIMARY_OPENAPI_FILENAME);
+        const adminOutputPath = resumeAdminOutputPath ?? path.join(openapiDir, ADMIN_OPENAPI_FILENAME);
+        const primaryDraftPath = this.openapiDraftPath(job.id, "primary");
+        const adminDraftPath = this.openapiDraftPath(job.id, "admin");
+        const basePayload = compactPayload({
+            workspaceRoot: this.workspace.workspaceRoot,
+            projectKey: options.projectKey,
+            resumeSupported: true,
+            cliVersion: options.cliVersion,
+            openapi_timeout_ms: timeoutMs,
+            openapi_primary_output_path: outputPath,
+            openapi_admin_output_path: adminOutputPath,
+            openapi_primary_draft_path: primaryDraftPath,
+            openapi_admin_draft_path: adminDraftPath,
+            openapi_iteration_current: iteration?.current,
+            openapi_iteration_max: iteration?.max,
+            openapi_iteration_label: iterationLabel,
         });
-        const warnings = [];
+        const buildPayload = (payload) => compactPayload({ ...basePayload, ...payload });
+        let totalUnits = 1;
+        let completedUnits = 0;
+        const perVariantUnits = options.validateOnly ? 1 : 2;
+        let currentStage = "starting";
+        let currentVariant;
+        const setStage = async (stage, variant, payload) => {
+            currentStage = stage;
+            currentVariant = variant;
+            await this.updateOpenapiJobStatus(job.id, "running", {
+                stage,
+                variant,
+                iteration,
+                totalUnits,
+                completedUnits,
+                payload: buildPayload(payload),
+            });
+        };
+        const completeStage = async (stage, variant, payload) => {
+            completedUnits += 1;
+            await this.updateOpenapiJobStatus(job.id, "running", {
+                stage,
+                variant,
+                iteration,
+                totalUnits,
+                completedUnits,
+                payload: buildPayload(payload),
+            });
+        };
+        const runWithTimeout = async (label, fn) => {
+            void label;
+            if (await this.isJobCancelled(job.id)) {
+                throw new OpenApiJobError("cancelled", `OpenAPI job ${job.id} was cancelled.`, job.id);
+            }
+            if (!timeoutAt)
+                return fn();
+            const remaining = timeoutAt - Date.now();
+            const timeoutSeconds = Math.max(1, Math.round((timeoutMs ?? 0) / 1000));
+            if (remaining <= 0) {
+                throw new OpenApiJobError("timeout", `OpenAPI job ${job.id} timed out after ${timeoutSeconds}s.`, job.id);
+            }
+            let timer;
+            try {
+                return await Promise.race([
+                    fn(),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => {
+                            reject(new OpenApiJobError("timeout", `OpenAPI job ${job.id} timed out after ${timeoutSeconds}s.`, job.id));
+                        }, remaining);
+                    }),
+                ]);
+            }
+            finally {
+                if (timer)
+                    clearTimeout(timer);
+            }
+        };
+        const heartbeat = this.startOpenapiHeartbeat(job.id, () => ({
+            stage: currentStage,
+            variant: currentVariant,
+            iteration,
+            totalUnits,
+            completedUnits,
+            payload: buildPayload({ openapi_last_heartbeat_at: new Date().toISOString() }),
+        }));
+        const assertHeartbeat = () => {
+            const error = heartbeat.getError();
+            if (error)
+                throw error;
+        };
         try {
+            await setStage("context");
             const projectKey = options.projectKey ?? this.workspace.config?.projectKey;
             const assembler = new OpenapiContextAssembler(this.docdex, this.workspace, projectKey);
-            const context = await assembler.build();
+            const context = await runWithTimeout("context", () => assembler.build());
             warnings.push(...context.warnings);
-            await this.jobService.writeCheckpoint(job.id, {
-                stage: "context_built",
-                timestamp: new Date().toISOString(),
-                details: { docdexAvailable: context.docdexAvailable },
+            await this.writeOpenapiCheckpoint(job.id, "context_built", {
+                docdexAvailable: context.docdexAvailable,
             });
             await this.jobService.recordTokenUsage({
                 timestamp: new Date().toISOString(),
@@ -419,24 +1026,70 @@ export class OpenApiService {
                 completionTokens: 0,
                 metadata: { docdexAvailable: context.docdexAvailable },
             });
-            const openapiDir = await this.ensureOpenapiDir();
-            const outputPath = path.join(openapiDir, "mcoda.yaml");
+            await completeStage("context", undefined, { docdexAvailable: context.docdexAvailable });
+            const adminCheck = await runWithTimeout("admin_check", () => this.collectAdminMentions());
+            warnings.push(...adminCheck.warnings);
+            const adminRequired = adminCheck.required;
+            totalUnits = 1 + perVariantUnits * (adminRequired ? 2 : 1);
+            await this.updateOpenapiJobStatus(job.id, "running", {
+                stage: currentStage,
+                variant: currentVariant,
+                iteration,
+                totalUnits,
+                completedUnits,
+                payload: buildPayload({ openapi_admin_required: adminRequired }),
+            });
+            assertHeartbeat();
             if (options.validateOnly) {
+                await setStage("validate", "primary");
                 if (!(await fileExists(outputPath))) {
                     throw new Error(`Cannot validate missing spec: ${outputPath}`);
                 }
-                const { spec, issues } = await this.validateExistingSpec(outputPath);
+                const primaryResult = await runWithTimeout("validate_primary", () => this.validateExistingSpec(outputPath));
+                const issues = primaryResult.issues.map((issue) => `Primary spec: ${issue}`);
+                let adminSpec;
+                let adminResult;
+                const adminExists = await fileExists(adminOutputPath);
+                if (adminRequired && !adminExists) {
+                    throw new Error(`Admin spec required but missing: ${adminOutputPath}`);
+                }
+                if (adminExists) {
+                    adminResult = await runWithTimeout("validate_admin", () => this.validateExistingSpec(adminOutputPath));
+                    adminSpec = adminResult.spec;
+                    issues.push(...adminResult.issues.map((issue) => `Admin spec (${adminOutputPath}): ${issue}`));
+                }
+                if (adminResult?.doc && primaryResult.doc) {
+                    const primaryVersion = primaryResult.doc?.info?.version;
+                    const adminVersion = adminResult.doc?.info?.version;
+                    if (primaryVersion && adminVersion && primaryVersion !== adminVersion) {
+                        issues.push(`Admin spec info.version (${adminVersion}) does not match primary spec (${primaryVersion}).`);
+                    }
+                    const primaryOpenapi = primaryResult.doc?.openapi;
+                    const adminOpenapi = adminResult.doc?.openapi;
+                    if (primaryOpenapi && adminOpenapi && primaryOpenapi !== adminOpenapi) {
+                        issues.push(`Admin spec openapi version (${adminOpenapi}) does not match primary spec (${primaryOpenapi}).`);
+                    }
+                }
                 const validationNote = issues.length ? `Validation issues:\n${issues.join("\n")}` : "Validation passed.";
                 await this.jobService.appendLog(job.id, `${validationNote}\n`);
+                await completeStage("validate", "primary", { validation: validationNote });
+                if (adminExists) {
+                    await completeStage("validate", "admin", { validation: validationNote });
+                }
                 const jobState = issues.length ? "failed" : "completed";
                 const commandState = issues.length ? "failed" : "succeeded";
-                await this.jobService.updateJobStatus(job.id, jobState, { payload: { validation: validationNote } });
+                await this.jobService.updateJobStatus(job.id, jobState, {
+                    errorSummary: issues.length ? issues.join("; ") : undefined,
+                    payload: buildPayload({ validation: validationNote, openapi_admin_required: adminRequired }),
+                });
                 await this.jobService.finishCommandRun(commandRun.id, commandState, issues.join("; "));
                 return {
                     jobId: job.id,
                     commandRunId: commandRun.id,
                     outputPath,
-                    spec,
+                    spec: primaryResult.spec,
+                    adminOutputPath: adminExists ? adminOutputPath : undefined,
+                    adminSpec,
                     warnings,
                 };
             }
@@ -445,85 +1098,190 @@ export class OpenApiService {
             }
             const agent = await this.resolveAgent(options.agentName);
             const stream = options.agentStream ?? true;
-            let specYaml = "";
-            let parsed;
-            let adapter = agent.adapter;
-            let agentMetadata;
-            let lastErrors;
             let agentUsed = false;
-            for (let attempt = 0; attempt < 2; attempt += 1) {
-                const prompt = this.buildPrompt(context, options.cliVersion, lastErrors);
-                agentUsed = true;
-                const { output, adapter: usedAdapter, metadata } = await this.invokeAgent(agent, prompt, stream, job.id, options.onToken);
-                adapter = usedAdapter;
-                agentMetadata = metadata;
-                specYaml = this.sanitizeOutput(output);
-                try {
-                    parsed = YAML.parse(specYaml);
-                    if (!parsed.info)
-                        parsed.info = {};
-                    const projectTitle = options.projectKey ?? this.workspace.config?.projectKey;
-                    parsed.info.title = parsed.info.title ?? projectTitle ?? "mcoda API";
-                    parsed.info.version = options.cliVersion;
-                    parsed.openapi = parsed.openapi ?? OPENAPI_VERSION;
-                    const errors = this.validateSpec(parsed);
-                    const validatorErrors = await this.runOpenapiValidator(parsed);
-                    errors.push(...validatorErrors);
-                    await this.jobService.recordTokenUsage({
-                        timestamp: new Date().toISOString(),
-                        workspaceId: this.workspace.workspaceId,
-                        commandName: "openapi-from-docs",
-                        jobId: job.id,
-                        commandRunId: commandRun.id,
-                        agentId: agent.id,
-                        modelName: agent.defaultModel,
-                        action: attempt === 0 ? "draft_openapi" : "draft_openapi_retry",
-                        promptTokens: estimateTokens(prompt),
-                        completionTokens: estimateTokens(output),
-                        metadata: { adapter, provider: adapter, attempt },
-                    });
-                    if (errors.length === 0) {
-                        specYaml = YAML.stringify(parsed);
-                        break;
+            const generateVariant = async (variant, resumeDraft) => {
+                const fallbackTitle = variant === "admin"
+                    ? `${projectKey ?? "mcoda"} Admin API`
+                    : projectKey ?? "mcoda API";
+                if (resumeDraft) {
+                    try {
+                        const parsed = YAML.parse(resumeDraft);
+                        if (!parsed.info)
+                            parsed.info = {};
+                        parsed.info.title = parsed.info.title ?? fallbackTitle;
+                        parsed.info.version = options.cliVersion;
+                        parsed.openapi = OPENAPI_VERSION;
+                        const errors = this.validateSpec(parsed);
+                        const validatorErrors = await runWithTimeout("validate_resume", () => this.runOpenapiValidator(parsed));
+                        errors.push(...validatorErrors);
+                        if (errors.length === 0) {
+                            const specYaml = YAML.stringify(parsed);
+                            await this.writeOpenapiDraft(job.id, variant, specYaml);
+                            await this.writeOpenapiCheckpoint(job.id, `draft_${variant}_completed`, {
+                                variant,
+                                draftPath: variant === "admin" ? adminDraftPath : primaryDraftPath,
+                                resumed: true,
+                            });
+                            return { specYaml, parsed, adapter: "resume" };
+                        }
+                        warnings.push(`Saved ${variant} draft invalid; regenerating: ${errors.join("; ")}`);
                     }
-                    if (attempt === 1) {
-                        throw new Error(`Generated spec failed validation: ${errors.join("; ")}`);
+                    catch (error) {
+                        warnings.push(`Saved ${variant} draft could not be parsed; regenerating: ${error.message ?? String(error)}`);
                     }
-                    lastErrors = errors;
                 }
-                catch (error) {
-                    if (attempt === 1) {
-                        throw new Error(error.message || "Failed to parse generated YAML");
+                let specYaml = "";
+                let parsed;
+                let adapter = agent.adapter;
+                let agentMetadata;
+                let lastErrors;
+                await setStage("draft", variant);
+                for (let attempt = 0; attempt < 2; attempt += 1) {
+                    const prompt = this.buildPrompt(context, options.cliVersion, lastErrors, variant);
+                    agentUsed = true;
+                    const { output, adapter: usedAdapter, metadata } = await runWithTimeout("draft_agent", async () => this.invokeAgent(agent, prompt, stream, job.id, options.onToken));
+                    adapter = usedAdapter;
+                    agentMetadata = metadata;
+                    specYaml = this.sanitizeOutput(output);
+                    try {
+                        parsed = YAML.parse(specYaml);
+                        if (!parsed.info)
+                            parsed.info = {};
+                        parsed.info.title = parsed.info.title ?? fallbackTitle;
+                        parsed.info.version = options.cliVersion;
+                        parsed.openapi = OPENAPI_VERSION;
+                        const errors = this.validateSpec(parsed);
+                        const validatorErrors = await runWithTimeout("validate_generated", () => this.runOpenapiValidator(parsed));
+                        errors.push(...validatorErrors);
+                        const action = variant === "admin"
+                            ? attempt === 0
+                                ? "draft_openapi_admin"
+                                : "draft_openapi_admin_retry"
+                            : attempt === 0
+                                ? "draft_openapi"
+                                : "draft_openapi_retry";
+                        await this.jobService.recordTokenUsage({
+                            timestamp: new Date().toISOString(),
+                            workspaceId: this.workspace.workspaceId,
+                            commandName: "openapi-from-docs",
+                            jobId: job.id,
+                            commandRunId: commandRun.id,
+                            agentId: agent.id,
+                            modelName: agent.defaultModel,
+                            action,
+                            promptTokens: estimateTokens(prompt),
+                            completionTokens: estimateTokens(output),
+                            metadata: {
+                                adapter,
+                                provider: adapter,
+                                attempt: attempt + 1,
+                                phase: action,
+                                variant,
+                            },
+                        });
+                        if (errors.length === 0) {
+                            specYaml = YAML.stringify(parsed);
+                            break;
+                        }
+                        if (attempt === 1) {
+                            throw new Error(`Generated ${variant} spec failed validation: ${errors.join("; ")}`);
+                        }
+                        lastErrors = errors;
+                    }
+                    catch (error) {
+                        if (attempt === 1) {
+                            throw new Error(error.message || `Failed to parse generated ${variant} YAML`);
+                        }
+                        lastErrors = [error.message ?? "Invalid YAML"];
                     }
-                    lastErrors = [error.message ?? "Invalid YAML"];
+                    assertHeartbeat();
                 }
+                await this.writeOpenapiDraft(job.id, variant, specYaml);
+                await this.writeOpenapiCheckpoint(job.id, `draft_${variant}_completed`, {
+                    variant,
+                    draftPath: variant === "admin" ? adminDraftPath : primaryDraftPath,
+                });
+                return { specYaml, parsed, adapter, agentMetadata };
+            };
+            const primarySpec = await generateVariant("primary", resumePrimaryDraft ?? resumeSpec);
+            await completeStage("draft", "primary", { openapi_variant: "primary" });
+            const adminSpec = adminRequired
+                ? await generateVariant("admin", resumeAdminDraft ?? resumeAdminSpec)
+                : undefined;
+            if (adminSpec) {
+                await completeStage("draft", "admin", { openapi_variant: "admin" });
             }
             let backup;
+            let adminBackup;
+            let docdexId = resumeDocdexId;
+            let adminDocdexId = resumeAdminDocdexId;
+            await setStage("write", "primary");
             if (!options.dryRun) {
                 backup = await this.backupIfNeeded(outputPath);
-                await fs.writeFile(outputPath, specYaml, "utf8");
+                await runWithTimeout("write_primary", async () => fs.writeFile(outputPath, primarySpec.specYaml, "utf8"));
+                if (context.docdexAvailable) {
+                    try {
+                        const registered = await runWithTimeout("docdex_primary", async () => this.registerOpenapi(outputPath, primarySpec.specYaml, "primary"));
+                        docdexId = registered.id;
+                    }
+                    catch (error) {
+                        warnings.push(`Docdex registration skipped: ${error.message}`);
+                    }
+                }
             }
             else {
                 warnings.push("Dry run enabled; spec not written to disk.");
             }
-            let docdexId;
-            if (!options.dryRun && context.docdexAvailable) {
-                try {
-                    const registered = await this.registerOpenapi(outputPath, specYaml);
-                    docdexId = registered.id;
-                }
-                catch (error) {
-                    warnings.push(`Docdex registration skipped: ${error.message}`);
+            await completeStage("write", "primary", {
+                outputPath,
+                backupPath: backup,
+                docdexId,
+                adapter: primarySpec.adapter,
+                adminAdapter: adminSpec?.adapter,
+                agentMetadata: primarySpec.agentMetadata,
+                adminAgentMetadata: adminSpec?.agentMetadata,
+                openapi_admin_required: adminRequired,
+            });
+            if (adminSpec) {
+                await setStage("write", "admin");
+                if (!options.dryRun) {
+                    adminBackup = await this.backupIfNeeded(adminOutputPath);
+                    await runWithTimeout("write_admin", async () => fs.writeFile(adminOutputPath, adminSpec.specYaml, "utf8"));
+                    if (context.docdexAvailable) {
+                        try {
+                            const registered = await runWithTimeout("docdex_admin", async () => this.registerOpenapi(adminOutputPath, adminSpec.specYaml, "admin"));
+                            adminDocdexId = registered.id;
+                        }
+                        catch (error) {
+                            warnings.push(`Admin Docdex registration skipped: ${error.message}`);
+                        }
+                    }
                 }
+                await completeStage("write", "admin", {
+                    adminOutputPath,
+                    adminBackupPath: adminBackup,
+                    adminDocdexId,
+                    openapi_admin_required: adminRequired,
+                });
             }
-            await this.jobService.updateJobStatus(job.id, "completed", {
-                payload: {
+            await this.updateOpenapiJobStatus(job.id, "completed", {
+                stage: "complete",
+                iteration,
+                totalUnits,
+                completedUnits: totalUnits,
+                payload: buildPayload({
                     outputPath,
                     backupPath: backup,
+                    adminOutputPath: adminSpec ? adminOutputPath : undefined,
+                    adminBackupPath: adminBackup,
                     docdexId,
-                    adapter,
-                    agentMetadata,
-                },
+                    adminDocdexId,
+                    adapter: primarySpec.adapter,
+                    adminAdapter: adminSpec?.adapter,
+                    agentMetadata: primarySpec.agentMetadata,
+                    adminAgentMetadata: adminSpec?.agentMetadata,
+                    openapi_admin_required: adminRequired,
+                }),
             });
             await this.jobService.finishCommandRun(commandRun.id, "succeeded");
             if (options.rateAgents && agentUsed) {
@@ -545,15 +1303,48 @@ export class OpenApiService {
                 jobId: job.id,
                 commandRunId: commandRun.id,
                 outputPath: options.dryRun ? undefined : outputPath,
-                spec: specYaml,
+                spec: primarySpec.specYaml,
+                adminOutputPath: options.dryRun ? undefined : adminSpec ? adminOutputPath : undefined,
+                adminSpec: adminSpec?.specYaml,
                 docdexId,
+                adminDocdexId,
                 warnings,
             };
         }
         catch (error) {
-            await this.jobService.updateJobStatus(job.id, "failed", { errorSummary: error.message });
-            await this.jobService.finishCommandRun(commandRun.id, "failed", error.message);
+            const message = error instanceof Error ? error.message : String(error);
+            const isOpenapiError = error instanceof OpenApiJobError;
+            if (job) {
+                if (isOpenapiError && error.code === "cancelled") {
+                    await this.updateOpenapiJobStatus(job.id, "cancelled", {
+                        stage: "cancelled",
+                        iteration: options.iteration,
+                        totalUnits,
+                        completedUnits,
+                        payload: buildPayload({ openapi_admin_required: undefined }),
+                        errorSummary: message,
+                    });
+                    await this.jobService.finishCommandRun(commandRun.id, "cancelled", message);
+                }
+                else {
+                    await this.updateOpenapiJobStatus(job.id, "failed", {
+                        stage: isOpenapiError && error.code === "timeout" ? "timeout" : "failed",
+                        iteration: options.iteration,
+                        totalUnits,
+                        completedUnits,
+                        payload: buildPayload({ openapi_admin_required: undefined }),
+                        errorSummary: message,
+                    });
+                    await this.jobService.finishCommandRun(commandRun.id, "failed", message);
+                }
+            }
+            else {
+                await this.jobService.finishCommandRun(commandRun.id, "failed", message);
+            }
             throw error;
         }
+        finally {
+            heartbeat.stop();
+        }
     }
 }