stageflow 0.32.0 → 0.35.0

package/dist/server/http.js

@@ -7,20 +7,32 @@ import { mapProviderAuthError } from "../agent/providerInspect.js";
 import { handleProviderRoutes } from "./providerRoutes.js";
 import { handleProjectMcpRoutes } from "./projectMcpRoutes.js";
 import { handleTriggerRoutes } from "./triggerRoutes.js";
+import { readCatalogFileForHttp, writeCatalogFileForHttp, } from "./readCatalogFile.js";
+import { applyLiveViewHeaders, createLiveViewRoutes, isLiveViewDialogPath, isLiveViewInputPath, isLiveViewPath, isLiveViewReopenTabPath, } from "./liveViewRoutes.js";
 import { createPipeline, parseCreatePipelineBody } from "../config/createPipeline.js";
 import { createStage, parseCreateStageBody } from "../config/createStage.js";
-import { loadDraftPackage, loadTaskArtifact, parseAttachTaskBody, parseCreateDraftPackageBody, parseDraftPackageBody, parseOpenDraftPackageBody, parseOverwriteDraftPackageBody, validateDraftPackage, } from "../config/draftPackage.js";
+import { createTask, parseCreateTaskBody } from "../config/createTask.js";
+import { importTaskFromIssue, parseImportTaskBody } from "../config/importTask.js";
+import { parseUpdateTaskBody, updateTask } from "../config/updateTask.js";
+import { loadDraftPackage, loadTaskArtifact, parseAttachTaskBody, parseCreateDraftPackageBody, parseDraftPackageBody, parseOpenDraftPackageBody, parseOverwriteDraftPackageBody, parsePlanDraftPackageBody, planDraftPackage, validateDraftPackage, } from "../config/draftPackage.js";
 import { publishDraftPackage } from "../config/publishDraftPackage.js";
 import { clearWorkshopAutosave, detectDiskChange, draftPackageDiskRelativePaths, fingerprintPackageFiles, parseWorkshopAutosaveRecord, readWorkshopAutosave, resolveWorkshopAutosaveStoreRoot, workshopAutosaveSlotKey, writeWorkshopAutosave, } from "../workshop/autosave.js";
 import { acceptWorkshopSessionMutation, iterateWorkshopChatStreamFrames, runWorkshopChatTurn, stopWorkshopChatTurn, undoWorkshopSessionMutation, WorkshopChatSessionRegistry, WorkshopSessionStoreError, } from "../workshop/chatTurn.js";
+import { parseWorkshopChatAttachments, parseWorkshopChatContext, } from "../workshop/chatAttachments.js";
 import { readWorkshopOpenModel, resolveWorkshopModel, } from "../workshop/modelSettings.js";
 import { createWorkshopSession, getWorkshopSession, listWorkshopSessions, resolveWorkshopSessionStoreRoot, updateWorkshopSessionActiveBuildId, } from "../workshop/sessionStore.js";
 import { createWorkshopBuild, focusUnboundWorkshopBuild, getWorkshopBuild, listWorkshopBuilds, listWorkshopPickerRows, resolvePickerCatalogPipelines, resolveWorkshopBuildStoreRoot, updateWorkshopBuild, WorkshopBuildStoreError, } from "../workshop/buildStore.js";
-import { createLiveWorkshopOperatorHost, } from "../operatorAgent/index.js";
+import { resolveAgentPort } from "../operatorAgent/index.js";
+import { listPipelinesForContext } from "../config/browseCatalog.js";
+import { catalogContextFromStageflow } from "../config/resolveCatalogContext.js";
 import { listModelsMultiProject, listPipelinesMultiProject, listTasksMultiProject, } from "../config/multiProjectCatalog.js";
-import { catalogPathErrorBody, CatalogPathError, resolveCatalogRelativePath, resolveCatalogStartInput, resolveWritableCatalogRoot, } from "../config/catalogRelativePath.js";
+import { catalogPathErrorBody, CatalogPathError, resolveCatalogRelativePath, resolveCatalogStartInput, resolveDefaultWriteRoot, resolveWritableCatalogRoot, } from "../config/catalogRelativePath.js";
 import { listExtensions } from "../config/listExtensions.js";
 import { listSkills } from "../config/listSkills.js";
+import { findTaskInCatalogMulti } from "../config/findTaskInCatalog.js";
+import { buildSkillUsageIndex } from "../config/skillUsageIndex.js";
+import { installSkillFromCommand, parseInstallSkillBody, } from "../config/installSkillRequest.js";
+import { validateCatalog } from "../config/validateCatalog.js";
 import { artifactMediaType, classifyArtifactContent, readRunArtifact, readRunArtifactBytes, } from "../mcp/readArtifact.js";
 import { getRunDiff, listCheckoutChanges, readCheckoutFileBytes, } from "../mcp/checkoutTools.js";
 import { readStageVerificationHistory } from "../runstore/verificationHistory.js";
@@ -43,13 +55,20 @@ import { bootstrapStageflowHost, } from "./bootstrap.js";
 import { assertAllowedHttpAccess, isTrustedLocalHttpRequest, resolveAllowedHosts, } from "./allowedHosts.js";
 import { enforceBearerAuth, loadControlTokens, requiredScopeFor, } from "./controlToken.js";
 import { createHttpHost, DEFAULT_PORT, json, } from "./createHttpHost.js";
-import { handleApiHealth } from "./healthSurfaces.js";
+import { handleApiHealth, listCatalogRootsForApi } from "./healthSurfaces.js";
 import { mapRetryStageFailure, mapStartFailure, mapStoreLookupError, } from "./operatorResults.js";
 import { installShutdownController, makeDrainableHostFromOptional, } from "./shutdown.js";
 import { writeAudit } from "../logging/audit.js";
 import { logger as rootLogger } from "../logging/logger.js";
 import { callerIdFromRequestAuth, getRequestAuth, requestAuthFromBearer, runWithRequestAuth, } from "./requestAuthContext.js";
 const auditLog = rootLogger.child({ component: "audit" });
+function draftCatalogRootWire(root) {
+    return {
+        project_root: root.project_root,
+        root_kind: root.kind,
+        read_only: root.read_only,
+    };
+}
 function textPlain(res, status, body) {
     res.writeHead(status, {
         "Content-Type": "text/plain; charset=utf-8",
@@ -137,7 +156,10 @@ async function serveStatic(res, uiDistDir, urlPath) {
 function isCredentialMutatingApi(method, pathname) {
     if (method !== "POST")
         return false;
-    return (/^\/api\/providers\/[^/]+\/login$/.test(pathname) ||
+    return (isLiveViewInputPath(method, pathname) ||
+        isLiveViewDialogPath(method, pathname) ||
+        isLiveViewReopenTabPath(method, pathname) ||
+        /^\/api\/providers\/[^/]+\/login$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login\/[^/]+\/answer$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/login\/[^/]+\/cancel$/.test(pathname) ||
         /^\/api\/providers\/[^/]+\/logout$/.test(pathname));
@@ -149,18 +171,11 @@ export function defaultUiDistDir() {
     }
     return path.resolve(here, "../ui");
 }
-/**
- * The full operator-console route surface: REST API (runs, stages,
- * catalog, settings, providers) plus, when `uiDistDir` is given, static
- * console UI file serving. Shared by `startUiServer` (browser-facing) and
- * `startMcpServer` (headless global-service daemon) — both need the REST
- * API; only the former needs the UI files.
- */
 export function createOperatorRoutes(deps) {
     const { manager, store, cwd, agentDir, rootDir, providerAuthContext, uiDistDir, workshopOperatorHost, } = deps;
     const workshopChatRegistry = deps.workshopChatRegistry ??
         new WorkshopChatSessionRegistry(workshopOperatorHost ??
-            createLiveWorkshopOperatorHost({
+            resolveAgentPort({
                 cwd,
                 projectRoot: cwd,
             }));
@@ -168,7 +183,11 @@ export function createOperatorRoutes(deps) {
     const workshopBuildStoreRoot = () => resolveWorkshopBuildStoreRoot();
     const allowedHosts = deps.allowedHosts ?? resolveAllowedHosts();
     const controlTokens = deps.controlTokens ?? loadControlTokens();
-    return async ({ req, res, url, pathname, method, boot }) => {
+    const liveView = createLiveViewRoutes({ ...deps.liveView, store, controlTokens });
+    liveView.attach(manager);
+    const handler = async ({ req, res, url, pathname, method, boot }) => {
+        if (isLiveViewPath(pathname))
+            applyLiveViewHeaders(res);
         if (boot.serveBlocked !== undefined && pathname.startsWith("/api/")) {
             json(res, 503, {
                 error: boot.serveBlocked.reason,
@@ -193,6 +212,8 @@ export function createOperatorRoutes(deps) {
         return handleOperatorRequest();
         async function handleOperatorRequest() {
             try {
+                if (await liveView.handle(req, res))
+                    return true;
                 if (pathname.startsWith("/api/email/")) {
                     if (!assertAllowedHttpAccess({ entries: [] }, req, res, { requireOrigin: ["POST", "PATCH", "DELETE"].includes(method) }))
                         return true;
@@ -1044,6 +1065,356 @@ export function createOperatorRoutes(deps) {
                     });
                     return true;
                 }
+                if (method === "GET" && pathname === "/api/catalog/roots") {
+                    const roots = await listCatalogRootsForApi({ store, bootCwd: cwd });
+                    json(res, 200, { roots });
+                    return true;
+                }
+                if (method === "POST" && pathname === "/api/catalog/validate") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    if (body !== null && typeof body === "object" && !Array.isArray(body)) {
+                        const record = body;
+                        let pipeline = typeof record.pipeline === "string" ? record.pipeline : undefined;
+                        let task = typeof record.task === "string" ? record.task : undefined;
+                        let stage = typeof record.stage === "string" ? record.stage : undefined;
+                        const strict = record.strict === true;
+                        const projectRoot = typeof record.project_root === "string" && record.project_root.trim()
+                            ? record.project_root.trim()
+                            : undefined;
+                        const scopedCount = [pipeline, task, stage].filter((v) => v !== undefined).length;
+                        if (scopedCount > 1) {
+                            json(res, 400, {
+                                error: "Use at most one of pipeline, task, or stage",
+                            });
+                            return true;
+                        }
+                        let validateCwd = cwd;
+                        if (pipeline !== undefined || task !== undefined || stage !== undefined) {
+                            try {
+                                const { wireRoot, roots } = await resolveCatalogStartInput({ store, bootCwd: cwd }, projectRoot);
+                                validateCwd = wireRoot.path;
+                                if (pipeline !== undefined) {
+                                    pipeline = resolveCatalogRelativePath({
+                                        inputPath: pipeline.trim(),
+                                        projectRoot: wireRoot.project_root,
+                                        roots,
+                                        fieldName: "pipeline",
+                                    }).absolutePath;
+                                }
+                                if (task !== undefined) {
+                                    task = resolveCatalogRelativePath({
+                                        inputPath: task.trim(),
+                                        projectRoot: wireRoot.project_root,
+                                        roots,
+                                        fieldName: "task",
+                                    }).absolutePath;
+                                }
+                                if (stage !== undefined) {
+                                    stage = resolveCatalogRelativePath({
+                                        inputPath: stage.trim(),
+                                        projectRoot: wireRoot.project_root,
+                                        roots,
+                                        fieldName: "stage",
+                                    }).absolutePath;
+                                }
+                            }
+                            catch (err) {
+                                if (err instanceof CatalogPathError) {
+                                    json(res, 400, catalogPathErrorBody(err));
+                                    return true;
+                                }
+                                throw err;
+                            }
+                        }
+                        const scope = pipeline
+                            ? "pipeline"
+                            : task
+                                ? "task"
+                                : stage
+                                    ? "stage"
+                                    : "full";
+                        const stageContent = typeof record.content === "string" ? record.content : undefined;
+                        if (stageContent !== undefined && stage === undefined) {
+                            json(res, 400, {
+                                error: "content is only supported with stage",
+                            });
+                            return true;
+                        }
+                        const result = await validateCatalog({
+                            scope,
+                            cwd: validateCwd,
+                            ...(pipeline !== undefined ||
+                                task !== undefined ||
+                                stage !== undefined
+                                ? { projectRoot: validateCwd }
+                                : {}),
+                            pipeline,
+                            task,
+                            stage,
+                            ...(stageContent !== undefined ? { stageContent } : {}),
+                            strict,
+                        });
+                        json(res, 200, result);
+                        return true;
+                    }
+                    json(res, 400, { error: "Request body must be an object" });
+                    return true;
+                }
+                if (method === "GET" && pathname === "/api/catalog/file") {
+                    const relPath = url.searchParams.get("path");
+                    if (relPath === null || relPath.length === 0) {
+                        json(res, 400, { error: "path query parameter is required" });
+                        return true;
+                    }
+                    const projectRoot = url.searchParams.get("project_root") ?? undefined;
+                    try {
+                        const { roots } = await resolveCatalogStartInput({ store, bootCwd: cwd }, projectRoot);
+                        const result = await readCatalogFileForHttp({
+                            inputPath: relPath,
+                            projectRoot,
+                            roots,
+                            fieldName: "path",
+                        });
+                        if (!result.ok) {
+                            json(res, result.status, { error: result.error, code: result.code });
+                            return true;
+                        }
+                        json(res, 200, { path: result.path, content: result.content });
+                        return true;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                }
+                if (method === "PUT" && pathname === "/api/catalog/file") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    if (body === null || typeof body !== "object" || Array.isArray(body)) {
+                        json(res, 400, { error: "Request body must be an object" });
+                        return true;
+                    }
+                    const record = body;
+                    const relPath = typeof record.path === "string" ? record.path.trim() : "";
+                    if (!relPath) {
+                        json(res, 400, { error: "path is required" });
+                        return true;
+                    }
+                    if (typeof record.content !== "string") {
+                        json(res, 400, { error: "content must be a string" });
+                        return true;
+                    }
+                    const writeRoot = typeof record.project_root === "string"
+                        ? record.project_root
+                        : undefined;
+                    try {
+                        const { wireRoot, roots } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
+                        const result = await writeCatalogFileForHttp({
+                            inputPath: relPath,
+                            content: record.content,
+                            projectRoot: wireRoot.project_root,
+                            roots,
+                            fieldName: "path",
+                        });
+                        if (!result.ok) {
+                            json(res, result.status, {
+                                error: result.error,
+                                code: result.code,
+                                ...(result.findings !== undefined
+                                    ? { findings: result.findings }
+                                    : {}),
+                            });
+                            return true;
+                        }
+                        json(res, 200, { path: result.path, content: result.content });
+                        return true;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                }
+                if (method === "POST" && pathname === "/api/tasks/import") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    const parsed = parseImportTaskBody(body);
+                    if ("ok" in parsed) {
+                        json(res, parsed.status, { error: parsed.error });
+                        return true;
+                    }
+                    const writeRoot = body !== null &&
+                        typeof body === "object" &&
+                        !Array.isArray(body) &&
+                        typeof body.project_root === "string"
+                        ? body.project_root
+                        : undefined;
+                    let taskWriteRoot;
+                    try {
+                        const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
+                        taskWriteRoot = selected.path;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                    const stageflowCtx = await resolveStageflowContext(taskWriteRoot);
+                    if (stageflowCtx.manifestStatus !== "ok") {
+                        json(res, 400, {
+                            error: "Project root not found; initialize stageflow.yaml",
+                        });
+                        return true;
+                    }
+                    const result = await importTaskFromIssue(stageflowCtx.projectRoot, parsed);
+                    if (!result.ok) {
+                        json(res, result.status, { error: result.error });
+                        return true;
+                    }
+                    json(res, 201, { task: result.task });
+                    return true;
+                }
+                if (method === "POST" && pathname === "/api/tasks") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    const writeRoot = body !== null &&
+                        typeof body === "object" &&
+                        !Array.isArray(body) &&
+                        typeof body.project_root === "string"
+                        ? body.project_root
+                        : undefined;
+                    let taskWriteRoot;
+                    try {
+                        const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
+                        taskWriteRoot = selected.path;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                    const parsed = parseCreateTaskBody(body);
+                    if ("ok" in parsed) {
+                        json(res, parsed.status, { error: parsed.error });
+                        return true;
+                    }
+                    const stageflowCtx = await resolveStageflowContext(taskWriteRoot);
+                    if (stageflowCtx.manifestStatus !== "ok") {
+                        json(res, 400, {
+                            error: "Project root not found; initialize stageflow.yaml",
+                        });
+                        return true;
+                    }
+                    const result = await createTask(stageflowCtx.projectRoot, parsed);
+                    if (!result.ok) {
+                        json(res, result.status, { error: result.error });
+                        return true;
+                    }
+                    json(res, 201, { task: result.task });
+                    return true;
+                }
+                const taskDetailMatch = pathname.match(/^\/api\/tasks\/([^/]+)$/);
+                if (method === "GET" && taskDetailMatch) {
+                    const taskId = decodeURIComponent(taskDetailMatch[1] ?? "");
+                    const projectRootFilter = url.searchParams.get("project_root") ?? undefined;
+                    const lookup = await findTaskInCatalogMulti({
+                        store,
+                        bootCwd: cwd,
+                        taskId,
+                        projectRootFilter,
+                    });
+                    if (!lookup.ok) {
+                        if (lookup.status === 409) {
+                            json(res, 409, {
+                                error: lookup.error,
+                                code: lookup.code,
+                                project_roots: lookup.project_roots,
+                            });
+                            return true;
+                        }
+                        if (lookup.status === 400) {
+                            json(res, 400, {
+                                error: lookup.error,
+                                code: lookup.code,
+                            });
+                            return true;
+                        }
+                        json(res, 404, { error: lookup.error });
+                        return true;
+                    }
+                    json(res, 200, { task: lookup.task });
+                    return true;
+                }
+                if (method === "PUT" && taskDetailMatch) {
+                    const taskId = decodeURIComponent(taskDetailMatch[1] ?? "");
+                    const projectRootFilter = url.searchParams.get("project_root") ?? undefined;
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    const parsed = parseUpdateTaskBody(body);
+                    if ("ok" in parsed) {
+                        json(res, parsed.status, { error: parsed.error });
+                        return true;
+                    }
+                    const result = await updateTask({
+                        store,
+                        bootCwd: cwd,
+                        taskId,
+                        input: parsed,
+                        projectRootFilter,
+                    });
+                    if (!result.ok) {
+                        json(res, result.status, {
+                            error: result.error,
+                            ...(result.code !== undefined ? { code: result.code } : {}),
+                            ...(result.project_roots !== undefined
+                                ? { project_roots: result.project_roots }
+                                : {}),
+                        });
+                        return true;
+                    }
+                    json(res, 200, { task: result.task });
+                    return true;
+                }
                 if (method === "GET" && pathname === "/api/tasks") {
                     const filter = url.searchParams.get("project_root") ?? undefined;
                     const result = await listTasksMultiProject({
@@ -1210,19 +1581,17 @@ export function createOperatorRoutes(deps) {
                         typeof body.project_root === "string"
                         ? body.project_root
                         : undefined;
-                    let validateRoot = cwd;
-                    if (writeRoot) {
-                        try {
-                            const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
-                            validateRoot = selected.path;
-                        }
-                        catch (err) {
-                            if (err instanceof CatalogPathError) {
-                                json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
-                                return true;
-                            }
-                            throw err;
+                    let validateRoot;
+                    try {
+                        const { wireRoot: selected } = await resolveDefaultWriteRoot({ store, bootCwd: cwd }, writeRoot);
+                        validateRoot = selected.path;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
                         }
+                        throw err;
                     }
                     const ctx = await resolveStageflowContext(validateRoot);
                     const result = await validateDraftPackage(draftParsed, {
@@ -1249,9 +1618,11 @@ export function createOperatorRoutes(deps) {
                         ? body.project_root
                         : undefined;
                     let draftWriteRoot;
+                    let draftWriteWireRoot;
                     try {
                         const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
                         draftWriteRoot = selected.path;
+                        draftWriteWireRoot = selected;
                     }
                     catch (err) {
                         if (err instanceof CatalogPathError) {
@@ -1266,13 +1637,15 @@ export function createOperatorRoutes(deps) {
                         return true;
                     }
                     const ctx = await resolveStageflowContext(draftWriteRoot);
-                    if (!ctx.isGitProject) {
+                    if (ctx.manifestStatus !== "ok") {
                         json(res, 400, {
-                            error: "Project root not found; initialize stageflow.yaml in a git repo",
+                            error: "Project root not found; initialize stageflow.yaml",
                         });
                         return true;
                     }
-                    const result = (await publishDraftPackage(ctx.projectRoot, parsed, "create")).write;
+                    const result = (await publishDraftPackage(ctx.projectRoot, parsed, "create", {
+                        catalogRootKind: draftWriteWireRoot.kind,
+                    })).write;
                     if (!result.ok) {
                         json(res, result.status, {
                             error: result.error,
@@ -1284,6 +1657,8 @@ export function createOperatorRoutes(deps) {
                         pipeline: result.pipeline,
                         pipelinePath: result.pipelinePath,
                         stagePaths: result.stagePaths,
+                        catalog_root_path: ctx.projectRoot,
+                        ...draftCatalogRootWire(draftWriteWireRoot),
                         ...(result.taskPath !== undefined ? { taskPath: result.taskPath } : {}),
                     });
                     return true;
@@ -1304,9 +1679,11 @@ export function createOperatorRoutes(deps) {
                         ? body.project_root
                         : undefined;
                     let draftWriteRoot;
+                    let draftWriteWireRoot;
                     try {
                         const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
                         draftWriteRoot = selected.path;
+                        draftWriteWireRoot = selected;
                     }
                     catch (err) {
                         if (err instanceof CatalogPathError) {
@@ -1321,13 +1698,15 @@ export function createOperatorRoutes(deps) {
                         return true;
                     }
                     const ctx = await resolveStageflowContext(draftWriteRoot);
-                    if (!ctx.isGitProject) {
+                    if (ctx.manifestStatus !== "ok") {
                         json(res, 400, {
-                            error: "Project root not found; initialize stageflow.yaml in a git repo",
+                            error: "Project root not found; initialize stageflow.yaml",
                         });
                         return true;
                     }
-                    const result = (await publishDraftPackage(ctx.projectRoot, parsed, "overwrite")).write;
+                    const result = (await publishDraftPackage(ctx.projectRoot, parsed, "overwrite", {
+                        catalogRootKind: draftWriteWireRoot.kind,
+                    })).write;
                     if (!result.ok) {
                         json(res, result.status, {
                             error: result.error,
@@ -1339,10 +1718,70 @@ export function createOperatorRoutes(deps) {
                         pipeline: result.pipeline,
                         pipelinePath: result.pipelinePath,
                         stagePaths: result.stagePaths,
+                        catalog_root_path: ctx.projectRoot,
+                        ...draftCatalogRootWire(draftWriteWireRoot),
                         ...(result.taskPath !== undefined ? { taskPath: result.taskPath } : {}),
                     });
                     return true;
                 }
+                if (method === "POST" && pathname === "/api/drafts/plan") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    const writeRoot = body !== null &&
+                        typeof body === "object" &&
+                        !Array.isArray(body) &&
+                        typeof body.project_root === "string"
+                        ? body.project_root
+                        : undefined;
+                    let draftWriteRoot;
+                    try {
+                        const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
+                        draftWriteRoot = selected.path;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                    const parsed = parsePlanDraftPackageBody(body);
+                    if ("ok" in parsed) {
+                        json(res, parsed.status, { error: parsed.error });
+                        return true;
+                    }
+                    const ctx = await resolveStageflowContext(draftWriteRoot);
+                    if (ctx.manifestStatus !== "ok") {
+                        json(res, 400, {
+                            error: "Project root not found; initialize stageflow.yaml",
+                        });
+                        return true;
+                    }
+                    const catalogPipelines = parsed.mode === "create"
+                        ? await listPipelinesForContext(catalogContextFromStageflow(ctx))
+                        : [];
+                    const plan = await planDraftPackage(ctx.projectRoot, parsed, {
+                        mode: parsed.mode,
+                        catalogPipelines,
+                    });
+                    if (!plan.ok) {
+                        json(res, plan.status, { error: plan.error });
+                        return true;
+                    }
+                    json(res, 200, {
+                        pipelinePath: plan.pipelinePath,
+                        directory: plan.directory,
+                        files: plan.files,
+                        pipelineIdTaken: plan.pipelineIdTaken,
+                    });
+                    return true;
+                }
                 if (method === "POST" && pathname === "/api/drafts/open") {
                     let body;
                     try {
@@ -1412,6 +1851,7 @@ export function createOperatorRoutes(deps) {
                         draft: result.draft,
                         destination: result.destination,
                         pipelinePath: result.pipelinePath,
+                        ...draftCatalogRootWire(wireRoot),
                         ...(result.taskPath !== undefined ? { taskPath: result.taskPath } : {}),
                     });
                     return true;
@@ -1481,23 +1921,8 @@ export function createOperatorRoutes(deps) {
                     const keyParam = url.searchParams.get("key");
                     const key = workshopAutosaveSlotKey(keyParam);
                     const writeRoot = url.searchParams.get("project_root") ?? undefined;
-                    let storeRoot;
-                    try {
-                        if (writeRoot) {
-                            const { wireRoot } = await resolveCatalogStartInput({ store, bootCwd: cwd }, writeRoot);
-                            const ctx = await resolveStageflowContext(wireRoot.path);
-                            storeRoot = resolveWorkshopAutosaveStoreRoot({
-                                projectRoot: ctx.projectRoot,
-                                isGitProject: ctx.isGitProject,
-                            });
-                        }
-                        else {
-                            const ctx = await resolveStageflowContext(cwd);
-                            storeRoot = resolveWorkshopAutosaveStoreRoot({
-                                projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
-                                isGitProject: ctx.isGitProject,
-                            });
-                        }
+                    try {
+                        await resolveDefaultWriteRoot({ store, bootCwd: cwd }, writeRoot);
                     }
                     catch (err) {
                         if (err instanceof CatalogPathError) {
@@ -1506,6 +1931,7 @@ export function createOperatorRoutes(deps) {
                         }
                         throw err;
                     }
+                    const storeRoot = resolveWorkshopAutosaveStoreRoot();
                     const record = readWorkshopAutosave(storeRoot, key);
                     json(res, 200, { key, autosave: record });
                     return true;
@@ -1528,23 +1954,8 @@ export function createOperatorRoutes(deps) {
                     const writeRoot = typeof body.project_root === "string"
                         ? body.project_root
                         : undefined;
-                    let storeRoot;
-                    try {
-                        if (writeRoot) {
-                            const { wireRoot } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
-                            const ctx = await resolveStageflowContext(wireRoot.path);
-                            storeRoot = resolveWorkshopAutosaveStoreRoot({
-                                projectRoot: ctx.projectRoot,
-                                isGitProject: ctx.isGitProject,
-                            });
-                        }
-                        else {
-                            const ctx = await resolveStageflowContext(cwd);
-                            storeRoot = resolveWorkshopAutosaveStoreRoot({
-                                projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
-                                isGitProject: ctx.isGitProject,
-                            });
-                        }
+                    try {
+                        await resolveDefaultWriteRoot({ store, bootCwd: cwd }, writeRoot);
                     }
                     catch (err) {
                         if (err instanceof CatalogPathError) {
@@ -1553,6 +1964,7 @@ export function createOperatorRoutes(deps) {
                         }
                         throw err;
                     }
+                    const storeRoot = resolveWorkshopAutosaveStoreRoot();
                     const candidate = {
                         version: 1,
                         key,
@@ -1583,6 +1995,9 @@ export function createOperatorRoutes(deps) {
                                 diskFingerprints: body.diskFingerprints,
                             }
                             : {}),
+                        ...(body.projectRoot === null || typeof body.projectRoot === "string"
+                            ? { projectRoot: body.projectRoot }
+                            : {}),
                     };
                     const parsed = parseWorkshopAutosaveRecord(candidate);
                     if (!parsed) {
@@ -1611,23 +2026,8 @@ export function createOperatorRoutes(deps) {
                     const writeRoot = typeof body.project_root === "string"
                         ? body.project_root
                         : undefined;
-                    let storeRoot;
-                    try {
-                        if (writeRoot) {
-                            const { wireRoot } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, writeRoot);
-                            const ctx = await resolveStageflowContext(wireRoot.path);
-                            storeRoot = resolveWorkshopAutosaveStoreRoot({
-                                projectRoot: ctx.projectRoot,
-                                isGitProject: ctx.isGitProject,
-                            });
-                        }
-                        else {
-                            const ctx = await resolveStageflowContext(cwd);
-                            storeRoot = resolveWorkshopAutosaveStoreRoot({
-                                projectRoot: ctx.isGitProject ? ctx.projectRoot : null,
-                                isGitProject: ctx.isGitProject,
-                            });
-                        }
+                    try {
+                        await resolveDefaultWriteRoot({ store, bootCwd: cwd }, writeRoot);
                     }
                     catch (err) {
                         if (err instanceof CatalogPathError) {
@@ -1636,6 +2036,7 @@ export function createOperatorRoutes(deps) {
                         }
                         throw err;
                     }
+                    const storeRoot = resolveWorkshopAutosaveStoreRoot();
                     const cleared = clearWorkshopAutosave(storeRoot, key);
                     json(res, 200, { key, cleared });
                     return true;
@@ -2064,22 +2465,52 @@ export function createOperatorRoutes(deps) {
                         json(res, draftParsed.status, { error: draftParsed.error });
                         return true;
                     }
+                    const attachmentsParsed = parseWorkshopChatAttachments(body.attachments);
+                    if (!attachmentsParsed.ok) {
+                        json(res, 400, {
+                            error: attachmentsParsed.error,
+                            code: "workshop_attachment_invalid",
+                        });
+                        return true;
+                    }
                     const settingsDefault = await readWorkshopOpenModel(cwd);
                     const accept = String(req.headers.accept ?? "");
                     const wantsStream = body.stream === true ||
                         accept.includes("application/x-ndjson") ||
                         accept.includes("text/event-stream");
+                    const projectRootWire = typeof body.project_root === "string"
+                        ? body.project_root.trim()
+                        : typeof body.projectRoot === "string"
+                            ? body.projectRoot.trim()
+                            : "";
+                    let chatProjectRoot;
+                    if (projectRootWire) {
+                        try {
+                            const { wireRoot } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, projectRootWire);
+                            chatProjectRoot = wireRoot.path;
+                        }
+                        catch (err) {
+                            if (err instanceof CatalogPathError) {
+                                json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                                return true;
+                            }
+                            throw err;
+                        }
+                    }
                     const chatTurnBase = {
                         sessionId: body.sessionId,
                         draft: draftParsed,
                         message: body.message,
                         autoApply: body.autoApply === true,
+                        attachments: attachmentsParsed.attachments,
+                        context: parseWorkshopChatContext(body.context),
                         model: typeof body.model === "string" || body.model === null
                             ? body.model
                             : undefined,
                         settingsDefault: settingsDefault ?? null,
                         registry: workshopChatRegistry,
                         storeRoot: workshopSessionStoreRoot(),
+                        ...(chatProjectRoot ? { projectRoot: chatProjectRoot } : {}),
                     };
                     // Fail closed on missing sessions before opening an NDJSON body.
                     try {
@@ -2199,7 +2630,7 @@ export function createOperatorRoutes(deps) {
                                 events: [errorEvent],
                                 draft: draftParsed,
                                 pending: null,
-                                autoApply: false,
+                                autoApply: chatTurnBase.autoApply,
                                 model: resolvedModel,
                                 buildId: workshopChatRegistry.getPinnedBuildId(body.sessionId),
                             });
@@ -2336,8 +2767,94 @@ export function createOperatorRoutes(deps) {
                 })) {
                     return true;
                 }
+                if (method === "GET" && pathname === "/api/skills/usage") {
+                    const projectRoot = url.searchParams.get("project_root") ?? undefined;
+                    let usageRoot;
+                    try {
+                        const { wireRoot } = projectRoot === undefined
+                            ? await resolveWritableCatalogRoot({ store, bootCwd: cwd }, undefined)
+                            : await resolveCatalogStartInput({ store, bootCwd: cwd }, projectRoot);
+                        usageRoot = wireRoot.path;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                    const usages = await buildSkillUsageIndex(usageRoot);
+                    if (usages === null) {
+                        json(res, 404, { error: "No Stageflow catalog found" });
+                        return true;
+                    }
+                    json(res, 200, { usages });
+                    return true;
+                }
                 if (method === "GET" && pathname === "/api/skills") {
-                    json(res, 200, await listSkills({ cwd, agentDir }));
+                    const projectRoot = url.searchParams.get("project_root") ?? undefined;
+                    try {
+                        const { wireRoot } = projectRoot === undefined
+                            ? await resolveWritableCatalogRoot({ store, bootCwd: cwd }, undefined)
+                            : await resolveCatalogStartInput({ store, bootCwd: cwd }, projectRoot);
+                        json(res, 200, await listSkills({ cwd: wireRoot.path, agentDir }));
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                    return true;
+                }
+                if (method === "POST" && pathname === "/api/skills/install") {
+                    let body;
+                    try {
+                        body = await readJsonBody(req);
+                    }
+                    catch {
+                        json(res, 400, { error: "Invalid JSON body" });
+                        return true;
+                    }
+                    const parsed = parseInstallSkillBody(body);
+                    if ("ok" in parsed) {
+                        json(res, parsed.status, { error: parsed.error });
+                        return true;
+                    }
+                    let skillWriteRoot;
+                    try {
+                        const { wireRoot: selected } = await resolveWritableCatalogRoot({ store, bootCwd: cwd }, undefined);
+                        skillWriteRoot = selected.path;
+                    }
+                    catch (err) {
+                        if (err instanceof CatalogPathError) {
+                            json(res, err.code === "catalog_root_read_only" ? 403 : 400, catalogPathErrorBody(err));
+                            return true;
+                        }
+                        throw err;
+                    }
+                    const stageflowCtx = await resolveStageflowContext(skillWriteRoot);
+                    if (stageflowCtx.manifestStatus !== "ok") {
+                        json(res, 400, {
+                            error: "Project root not found; initialize stageflow.yaml",
+                        });
+                        return true;
+                    }
+                    const result = await installSkillFromCommand({
+                        projectRoot: stageflowCtx.projectRoot,
+                        command: parsed.command,
+                    });
+                    if (!result.ok) {
+                        json(res, result.status ?? 400, { error: result.error });
+                        return true;
+                    }
+                    json(res, 201, {
+                        ok: true,
+                        skill_name: result.skill_name,
+                        dest_path: result.dest_path,
+                        project_root: result.project_root,
+                    });
                     return true;
                 }
                 if (method === "GET" && pathname === "/api/extensions") {
@@ -2444,6 +2961,7 @@ export function createOperatorRoutes(deps) {
             }
         }
     };
+    return Object.assign(handler, { dispose: () => liveView.dispose() });
 }
 export async function startUiServer(options) {
     const host = options.host ?? "127.0.0.1";
@@ -2492,6 +3010,8 @@ export async function startUiServer(options) {
     });
     envelope.server.on("close", () => {
         shutdown?.uninstall();
+        if ("dispose" in routes)
+            void routes.dispose();
     });
     return { ...envelope, shutdown };
 }