@topline-build/harness-mcp 0.2.0 → 0.4.0

package/README.md

@@ -44,10 +44,63 @@ npx -y @topline-build/harness-mcp --url https://hawx.topline.build
 Set `TOPLINE_WORKSPACE_ROOT` when your MCP host starts outside the repo that
 contains the artifact app.
 
+The app can live anywhere under that workspace. For source tracking, the MCP
+maps ordinary local folders to `artifact-apps/<manifest-id>` while preserving
+existing `artifact-apps/<name>` roots and workspace-root (`.`) apps. Deploys
+report manifest, packaging, draft creation, upload, and trusted-deployment
+progress to clients that support MCP progress notifications.
+Every deploy also receives a deterministic retry key. If a client loses the
+response and repeats the call, Topline resumes the same private draft instead
+of creating an ordinary duplicate.
+
 Topline Developer Access provides Build MCP snippets for Codex and Claude Code.
 Those snippets contain no raw token; the first tool call opens a browser
 approval flow scoped to artifact building.
 
+## Build workflow
+
+- `platform_init_artifact_app` creates a dependency-free starter in an empty
+  local directory.
+- `platform_connection_check` completes the one-time verification shown in
+  Developer Access.
+- `platform_list_build_workspaces` and `platform_list_artifact_drafts` discover
+  valid placement targets and recover existing drafts without exposing chat or
+  memory data.
+- `platform_deploy_artifact_app` packages the local app and deploys a private
+  draft through Topline's trusted runtime. Its `operationId` can be passed to
+  `platform_wait_artifact_deploy` for server-derived progress and recovery
+  after a disconnected client.
+- `platform_run_artifact_smoke` reruns trusted draft rendering and returns the
+  fresh evidence used by validation.
+- `platform_validate_artifact` returns bounded trusted smoke and rendered-page
+  evidence without requiring the agent to hold a browser session.
+- `platform_artifact_status`, `platform_read_artifact_logs`, and
+  `platform_open_artifact` inspect and hand off the draft.
+- `platform_plan_artifact_draft_delete` previews cleanup effects. Deletion uses
+  a separately approved `harness:artifact:delete` scope, the exact artifact id,
+  and the current plan token; stale plans fail closed.
+
+Tool failures include a stable error code, retryability, and a concrete
+recovery action in `structuredContent`.
+
+## Live certification
+
+After building the package, a release operator can exercise the real MCP client
+protocol, workspace discovery, deploy/resume, smoke, validation, and cleanup
+planning against a tenant:
+
+```bash
+npm run build
+TOPLINE_API_URL=https://tenant.example \
+TOPLINE_MCP_TOKEN=... \
+TOPLINE_WORKSPACE_ROOT=/path/to/workspace \
+TOPLINE_CERTIFICATION_APP_DIR=artifact-apps/certification \
+npm run certify:live
+```
+
+Set `TOPLINE_CERTIFICATION_CLEANUP=1` only when the certification draft should
+be removed after its cleanup plan is reviewed.
+
 ## Storybook
 
 Use the `platform_storybook_access` tool to get the tenant Storybook preview URL

package/dist/index.d.ts

@@ -29,17 +29,22 @@ export interface PackedArtifactAppBundle {
     sha256: string;
     excluded: string[];
 }
-export declare const HARNESS_MCP_VERSION = "0.2.0";
+type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
+export declare const HARNESS_MCP_VERSION = "0.4.0";
 export declare function parseHarnessOptions(argv: string[], env?: Record<string, string | undefined>): HarnessMcpStdioOptions;
 export declare function runHarnessMcpStdioCli(): Promise<void>;
 export declare function cliInfo(argv: string[]): string | null;
 export declare function createHarnessMcpStdioServer(opts: HarnessMcpStdioOptions): McpServer;
-export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown): Promise<CallToolResult>;
-export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: string, args: unknown, hooks?: {
+    onProgress?: ToolProgressReporter;
+}): Promise<CallToolResult>;
+export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<{
     ok: boolean;
     artifactId: string;
     artifactVersionId: string;
     manifestId: string | null;
+    clientRequestId: string;
+    operationId: string | null;
     bundle: {
         fileCount: number;
         byteCount: number;
@@ -49,6 +54,15 @@ export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: R
     create: unknown;
     deploy: unknown;
 }>;
+export declare function waitForArtifactDeploy(opts: HarnessMcpStdioOptions, input: Record<string, unknown>, onProgress?: ToolProgressReporter): Promise<Record<string, unknown>>;
+export declare function initArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+    ok: boolean;
+    appDir: string;
+    manifestId: string;
+    title: string;
+    files: string[];
+    nextAction: string;
+}>;
 export declare function getArtifactStatus(opts: HarnessMcpStdioOptions, artifactId: string, limit?: number): Promise<unknown>;
 export declare function readArtifactLogs(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<unknown>;
 export declare function openArtifact(opts: HarnessMcpStdioOptions, artifactId: string): Promise<{
@@ -120,3 +134,4 @@ export declare function browserOpenCommand(url: string, platform?: string): {
     command: string;
     args: string[];
 };
+export {};

package/dist/index.js

@@ -13,8 +13,8 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } fr
 const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 120_000;
 const SERVER_NAME = "topline-build-stdio";
-export const HARNESS_MCP_VERSION = "0.2.0";
-const DEFAULT_OAUTH_SCOPES = ["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy"];
+export const HARNESS_MCP_VERSION = "0.4.0";
+const DEFAULT_OAUTH_SCOPES = ["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"];
 const BLOCK_SIZE = 512;
 const MAX_BUNDLE_BYTES = 64 * 1024 * 1024;
 const MAX_UNPACKED_BYTES = 512 * 1024 * 1024;
@@ -97,13 +97,11 @@ export function createHarnessMcpStdioServer(opts) {
     const mcp = new McpServer({ name: SERVER_NAME, version: HARNESS_MCP_VERSION }, { capabilities: { tools: {} } });
     mcp.setRequestHandler(ListToolsRequestSchema, async () => listTools());
     mcp.setRequestHandler(CallToolRequestSchema, async (req, extra) => {
-        const reportsProgress = req.params.name === "platform_deploy_artifact_app";
-        if (reportsProgress)
-            await sendProgress(extra, 0, 1, "Starting artifact deployment");
+        const reportsProgress = req.params.name === "platform_deploy_artifact_app" || req.params.name === "platform_wait_artifact_deploy";
         try {
-            const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {});
-            if (reportsProgress)
-                await sendProgress(extra, 1, 1, "Completed artifact deployment");
+            const result = await callHarnessTool(opts, req.params.name, req.params.arguments ?? {}, reportsProgress
+                ? { onProgress: (progress, message) => sendProgress(extra, progress, 1, message) }
+                : undefined);
             return result;
         }
         catch (err) {
@@ -111,15 +109,12 @@ export function createHarnessMcpStdioServer(opts) {
                 throw err;
             if (reportsProgress)
                 await sendProgress(extra, 1, 1, "Failed artifact deployment");
-            return {
-                content: [{ type: "text", text: redactSecrets(err instanceof Error ? err.message : String(err), opts) }],
-                isError: true
-            };
+            return structuredToolError(redactSecrets(err instanceof Error ? err.message : String(err), opts));
         }
     });
     return mcp;
 }
-export async function callHarnessTool(opts, name, args) {
+export async function callHarnessTool(opts, name, args, hooks) {
     const input = isRecord(args) ? args : {};
     const tool = listTools().tools.find((candidate) => candidate.name === name);
     if (!tool)
@@ -129,8 +124,18 @@ export async function callHarnessTool(opts, name, args) {
         return toolError(`Invalid arguments for ${name}: ${inputError}`);
     let result;
     switch (name) {
+        case "platform_connection_check":
+        case "platform_list_build_workspaces":
+        case "platform_list_artifact_drafts":
+        case "platform_deploy_operation":
+        case "platform_validate_artifact":
+        case "platform_run_artifact_smoke":
+        case "platform_plan_artifact_draft_delete":
+        case "platform_delete_artifact_draft":
+            result = toolResult(await callHostedBuildTool(opts, name, input));
+            break;
         case "platform_deploy_artifact_app":
-            result = toolResult(await deployArtifactApp(opts, input));
+            result = toolResult(await deployArtifactApp(opts, input, hooks?.onProgress));
             break;
         case "platform_artifact_status":
             result = toolResult(await getArtifactStatus(opts, stringArg(input, "artifactId"), numberArg(input, "limit")));
@@ -144,6 +149,12 @@ export async function callHarnessTool(opts, name, args) {
         case "platform_storybook_access":
             result = toolResult(storybookAccess(opts));
             break;
+        case "platform_wait_artifact_deploy":
+            result = toolResult(await waitForArtifactDeploy(opts, input, hooks?.onProgress));
+            break;
+        case "platform_init_artifact_app":
+            result = toolResult(await initArtifactApp(opts, input));
+            break;
         default:
             throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
     }
@@ -152,12 +163,19 @@ export async function callHarnessTool(opts, name, args) {
         : null;
     return outputError ? toolError(`Invalid output for ${name}: ${outputError}`) : result;
 }
-export async function deployArtifactApp(opts, input) {
+export async function deployArtifactApp(opts, input, onProgress) {
+    await onProgress?.(0, "Reading artifact manifest");
     const appDir = stringArg(input, "appDir");
     const absoluteAppDir = resolveWorkspacePath(opts.workspaceRoot, appDir);
-    const platformAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
+    const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
+    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const clientRequestId = optionalString(input, "requestId") ?? createHash("sha256")
+        .update(JSON.stringify({ apiUrl: platformBaseUrl(opts), appDir: platformAppDir, manifestId: manifest.id ?? null }))
+        .digest("hex");
+    await onProgress?.(0.2, "Packaging local artifact app");
     const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
+    await onProgress?.(0.4, "Creating private artifact draft");
     const created = await fetchJson(opts, artifactAppsPath(opts), {
         method: "POST",
         headers: await jsonHeaders(opts),
@@ -166,6 +184,8 @@ export async function deployArtifactApp(opts, input) {
             title: optionalString(input, "title"),
             description: optionalString(input, "description"),
             projectId: optionalString(input, "projectId"),
+            clientRequestId,
+            bundleSha256: bundle.sha256,
             manifest
         })
     });
@@ -175,6 +195,7 @@ export async function deployArtifactApp(opts, input) {
     const artifactId = stringValue(createdRecord.artifactId, "artifactId");
     const artifactVersionId = stringValue(createdRecord.artifactVersionId, "artifactVersionId");
     const bearerToken = await getBearerToken(opts);
+    await onProgress?.(0.6, "Uploading bundle and waiting for trusted draft deployment");
     const deployed = await fetchJson(opts, `${artifactAppsPath(opts)}/${encodeURIComponent(artifactId)}/deploy-bundle`, {
         method: "POST",
         headers: {
@@ -186,11 +207,16 @@ export async function deployArtifactApp(opts, input) {
         },
         body: bundle.body
     });
+    await onProgress?.(1, "Completed trusted draft deployment");
+    const deployedRecord = asRecord(deployed);
+    const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId : null;
     return {
         ok: true,
         artifactId,
         artifactVersionId,
         manifestId: typeof manifest.id === "string" ? manifest.id : null,
+        clientRequestId,
+        operationId,
         bundle: {
             fileCount: bundle.fileCount,
             byteCount: bundle.byteCount,
@@ -201,6 +227,103 @@ export async function deployArtifactApp(opts, input) {
         deploy: deployed
     };
 }
+async function callHostedBuildTool(opts, name, input) {
+    if (mcpSurface(opts) !== "build")
+        throw new Error(`${name}_requires_build_surface`);
+    const headers = await jsonHeaders(opts);
+    const payload = asRecord(await fetchJson(opts, `${platformBaseUrl(opts)}/mcp/build`, {
+        method: "POST",
+        headers: { ...headers, accept: "application/json, text/event-stream" },
+        body: JSON.stringify({
+            jsonrpc: "2.0",
+            id: `stdio-${Date.now()}`,
+            method: "tools/call",
+            params: { name, arguments: input }
+        })
+    }));
+    if (payload.error) {
+        const error = asRecord(payload.error);
+        throw new Error(`platform_mcp_tool_error:${String(error.message ?? "unknown_error")}`);
+    }
+    const result = asRecord(payload.result);
+    if (result.isError === true) {
+        const content = Array.isArray(result.content) ? result.content.filter(isRecord) : [];
+        const message = content.find((item) => item.type === "text" && typeof item.text === "string")?.text;
+        throw new Error(`platform_mcp_tool_error:${String(message ?? "tool_failed")}`);
+    }
+    if (isRecord(result.structuredContent))
+        return result.structuredContent;
+    throw new Error(`platform_mcp_tool_output_missing:${name}`);
+}
+export async function waitForArtifactDeploy(opts, input, onProgress) {
+    const artifactId = stringArg(input, "artifactId");
+    const operationId = stringArg(input, "operationId");
+    const timeoutSeconds = Math.min(Math.max(numberArg(input, "timeoutSeconds") ?? 300, 1), 900);
+    const deadline = Date.now() + timeoutSeconds * 1000;
+    let afterSeq = 0;
+    let latest = {};
+    while (Date.now() < deadline) {
+        latest = asRecord(await callHostedBuildTool(opts, "platform_deploy_operation", { artifactId, operationId, afterSeq }));
+        const progress = typeof latest.progress === "number" ? latest.progress : 0.7;
+        const events = Array.isArray(latest.events) ? latest.events.filter(isRecord) : [];
+        const eventMessage = [...events].reverse().find((event) => typeof event.message === "string")?.message;
+        await onProgress?.(progress, typeof eventMessage === "string" ? eventMessage : `Artifact deployment: ${String(latest.phase ?? latest.taskStatus ?? "running")}`);
+        if (typeof latest.nextSeq === "number")
+            afterSeq = latest.nextSeq;
+        if (latest.terminal === true) {
+            if (latest.successful !== true)
+                throw new Error(`artifact_deploy_failed:${String(latest.taskStatus ?? "failed")}`);
+            return latest;
+        }
+        const waitMs = typeof latest.nextPollAfterMs === "number" ? Math.min(Math.max(latest.nextPollAfterMs, 250), 10_000) : 2_000;
+        await new Promise((resolve) => setTimeout(resolve, waitMs));
+    }
+    throw new Error(`artifact_deploy_wait_timeout:${operationId}`);
+}
+export async function initArtifactApp(opts, input) {
+    const appDir = stringArg(input, "appDir");
+    const title = optionalString(input, "title") ?? "Topline artifact";
+    const manifestId = (optionalString(input, "manifestId") ?? path.basename(appDir))
+        .toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-+|-+$/g, "");
+    if (!manifestId || manifestId.length > 80)
+        throw new Error("artifact_manifest_id_invalid");
+    const absoluteAppDir = resolveWorkspacePath(opts.workspaceRoot, appDir);
+    if (existsSync(absoluteAppDir) && (await readdir(absoluteAppDir)).length > 0)
+        throw new Error("artifact_app_scaffold_target_not_empty");
+    await mkdir(path.join(absoluteAppDir, "src"), { recursive: true });
+    const manifest = {
+        manifestVersion: 2,
+        id: manifestId,
+        title,
+        kind: "tool",
+        runtime: { target: "aws_lambda_function_url", region: "us-west-2", entryPoint: "artifactApp" },
+        build: { command: "node src/index.js --build", outputDir: "dist" },
+        validation: { localCommand: "node src/index.js --test", testCommand: "node src/index.js --test --artifact-tests-json" },
+        routes: [
+            { path: "/", kind: "page", handler: "artifactApp" },
+            { path: "/_artifact/health", kind: "api", handler: "artifactApp" }
+        ],
+        sourceBindings: [],
+        env: ["ARTIFACT_ID", "ARTIFACT_VERSION_ID", "ARTIFACT_MANIFEST_URI", "PLATFORM_ARTIFACT_ID", "PLATFORM_ARTIFACT_VERSION_ID", "PLATFORM_ARTIFACT_MANIFEST_URI"],
+        viewerPolicy: "private"
+    };
+    const packageJson = { name: manifestId, private: true, type: "module", main: "src/index.js", scripts: { build: "node src/index.js --build", test: "node src/index.js --test" } };
+    const safeTitle = title.replace(/[&<>"']/g, (char) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" }[char]));
+    const source = `import { mkdirSync, writeFileSync } from "node:fs";\nimport path from "node:path";\n\nconst page = ${JSON.stringify(`<!doctype html><html><body><main data-platform-artifact-root><h1>${safeTitle}</h1><p>Ready.</p></main></body></html>`)};\n\nexport function artifactApp(_req, res) {\n  res.setHeader("content-type", "text/html; charset=utf-8");\n  res.end(page);\n}\n\nif (process.argv.includes("--build")) {\n  mkdirSync("dist", { recursive: true });\n  writeFileSync(path.join("dist", "index.html"), page, "utf8");\n}\n\nif (process.argv.includes("--test") && process.argv.includes("--artifact-tests-json")) {\n  console.log(JSON.stringify({ tests: [{ description: "The artifact renders a visible app root.", required: true, status: "passed", summary: "The page includes data-platform-artifact-root.", evidence: { selector: "data-platform-artifact-root" } }] }));\n} else if (process.argv.includes("--build") || process.argv.includes("--test")) {\n  console.log("artifact app template ok");\n}\n`;
+    await Promise.all([
+        writeFile(path.join(absoluteAppDir, "artifact-app.json"), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" }),
+        writeFile(path.join(absoluteAppDir, "package.json"), `${JSON.stringify(packageJson, null, 2)}\n`, { flag: "wx" }),
+        writeFile(path.join(absoluteAppDir, "src", "index.js"), source, { flag: "wx" })
+    ]);
+    return {
+        ok: true,
+        appDir: workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir),
+        manifestId,
+        title,
+        files: ["artifact-app.json", "package.json", "src/index.js"],
+        nextAction: `Run npm test in ${appDir}, then call platform_deploy_artifact_app with the same appDir.`
+    };
+}
 export async function getArtifactStatus(opts, artifactId, limit) {
     const query = new URLSearchParams();
     if (limit)
@@ -444,6 +567,10 @@ async function fetchJson(opts, url, init) {
             payload = { detail: text.slice(0, 500) };
         }
         if (!response.ok) {
+            const code = isRecord(payload) && typeof payload.error === "string" ? payload.error : null;
+            if (code === "artifact_source_git_app_dir_mismatch") {
+                throw new Error("artifact_source_git_app_dir_mismatch: Use the same local app/source root as the existing artifact, or deploy without artifactId to create a new draft.");
+            }
             throw new Error(`platform_harness_http_error:${response.status}:${redactSecrets(JSON.stringify(payload), opts)}`);
         }
         return payload;
@@ -460,6 +587,42 @@ async function fetchJson(opts, url, init) {
 export function listTools() {
     return {
         tools: [
+            {
+                name: "platform_connection_check",
+                description: "Complete the one-time Developer Access verification challenge for this Build MCP client.",
+                annotations: mcpToolAnnotations("platform_connection_check", { readOnly: false, openWorld: true }),
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        verificationCode: { type: "string", minLength: 16, maxLength: 80 }
+                    },
+                    required: ["verificationCode"],
+                    additionalProperties: false
+                },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        ok: { type: "boolean" }, verified: { type: "boolean" }, product: { type: "string", enum: ["build"] }, verifiedAt: { type: "string" }
+                    },
+                    required: ["ok", "verified", "product", "verifiedAt"]
+                }
+            },
+            {
+                name: "platform_init_artifact_app",
+                description: "Create a minimal, validated artifact app starter inside the configured local workspace.",
+                annotations: mcpToolAnnotations("platform_init_artifact_app", { readOnly: false }),
+                inputSchema: {
+                    type: "object",
+                    properties: { appDir: { type: "string", minLength: 1 }, manifestId: { type: "string" }, title: { type: "string" } },
+                    required: ["appDir"],
+                    additionalProperties: false
+                },
+                outputSchema: {
+                    type: "object",
+                    properties: { ok: { type: "boolean" }, appDir: { type: "string" }, manifestId: { type: "string" }, title: { type: "string" }, files: { type: "array", items: { type: "string" } }, nextAction: { type: "string" } },
+                    required: ["ok", "appDir", "manifestId", "title", "files", "nextAction"]
+                }
+            },
             {
                 name: "platform_deploy_artifact_app",
                 description: "Package a local artifact app directory, upload it, deploy a private draft, and return status.",
@@ -471,7 +634,8 @@ export function listTools() {
                         artifactId: { type: "string" },
                         title: { type: "string" },
                         description: { type: "string" },
-                        projectId: { type: "string" }
+                        projectId: { type: "string" },
+                        requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." }
                     },
                     required: ["appDir"],
                     additionalProperties: false
@@ -482,13 +646,43 @@ export function listTools() {
                         ok: { type: "boolean" },
                         artifactId: { type: "string" },
                         artifactVersionId: { type: "string" },
+                        clientRequestId: { type: "string" },
+                        operationId: { type: ["string", "null"] },
                         bundle: { type: "object" },
                         create: { type: "object" },
                         deploy: { type: "object" }
                     },
-                    required: ["ok", "artifactId", "artifactVersionId", "bundle", "create", "deploy"]
+                    required: ["ok", "artifactId", "artifactVersionId", "clientRequestId", "operationId", "bundle", "create", "deploy"]
                 }
             },
+            {
+                name: "platform_list_build_workspaces",
+                description: "List Topline workspaces available for artifact placement.",
+                annotations: mcpToolAnnotations("platform_list_build_workspaces", { readOnly: true, openWorld: true }),
+                inputSchema: { type: "object", properties: {}, additionalProperties: false },
+                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, workspaces: { type: "array", items: { type: "object" } } }, required: ["ok", "workspaces"] }
+            },
+            {
+                name: "platform_list_artifact_drafts",
+                description: "Discover private artifact drafts created through this Build MCP connection.",
+                annotations: mcpToolAnnotations("platform_list_artifact_drafts", { readOnly: true, openWorld: true }),
+                inputSchema: { type: "object", properties: { projectId: { type: "string" }, limit: { type: "integer", minimum: 1, maximum: 100 } }, additionalProperties: false },
+                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, drafts: { type: "array", items: { type: "object" } } }, required: ["ok", "drafts"] }
+            },
+            {
+                name: "platform_deploy_operation",
+                description: "Read durable server-side progress for one artifact deployment operation.",
+                annotations: mcpToolAnnotations("platform_deploy_operation", { readOnly: true, openWorld: true }),
+                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 }, operationId: { type: "string", minLength: 1 }, afterSeq: { type: "integer", minimum: 0 } }, required: ["artifactId", "operationId"], additionalProperties: false },
+                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+            },
+            {
+                name: "platform_wait_artifact_deploy",
+                description: "Wait for a durable deployment operation and stream server-derived progress.",
+                annotations: mcpToolAnnotations("platform_wait_artifact_deploy", { readOnly: true, openWorld: true }),
+                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 }, operationId: { type: "string", minLength: 1 }, timeoutSeconds: { type: "integer", minimum: 1, maximum: 900 } }, required: ["artifactId", "operationId"], additionalProperties: false },
+                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, operationId: { type: "string" }, taskStatus: { type: "string" }, progress: { type: "number" }, terminal: { type: "boolean" }, successful: { type: "boolean" }, events: { type: "array", items: { type: "object" } } }, required: ["ok", "phase", "artifactId", "operationId", "taskStatus", "progress", "terminal", "successful", "events"] }
+            },
             {
                 name: "platform_artifact_status",
                 description: "Read private draft deployment status for a hosted artifact app.",
@@ -576,8 +770,98 @@ export function listTools() {
                     },
                     required: ["ok", "storybookUrl", "mcpUrl", "mcpServers"]
                 }
+            },
+            {
+                name: "platform_validate_artifact",
+                description: "Read trusted smoke and health evidence for a private artifact draft without requiring a browser session.",
+                annotations: mcpToolAnnotations("platform_validate_artifact", { readOnly: true }),
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        artifactId: { type: "string", minLength: 1 },
+                        deploymentRecordId: { type: "string", minLength: 1 }
+                    },
+                    required: ["artifactId"],
+                    additionalProperties: false
+                },
+                outputSchema: {
+                    type: "object",
+                    properties: {
+                        ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" },
+                        deploymentRecordId: { type: "string" }, deploymentState: { type: "string" },
+                        healthy: { type: "boolean" }, checkedAt: { type: ["string", "null"] },
+                        draftUrl: { type: ["string", "null"] }, smoke: { type: ["object", "null"] }
+                    },
+                    required: ["ok", "phase", "artifactId", "deploymentRecordId", "deploymentState", "healthy", "checkedAt", "draftUrl", "smoke"]
+                }
+            },
+            {
+                name: "platform_run_artifact_smoke",
+                description: "Rerun the trusted draft smoke check and return fresh rendered-page evidence.",
+                annotations: mcpToolAnnotations("platform_run_artifact_smoke", { readOnly: false, openWorld: true }),
+                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 }, deploymentRecordId: { type: "string", minLength: 1 } }, required: ["artifactId"], additionalProperties: false },
+                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, deploymentRecordId: { type: "string" }, smoke: { type: "object" }, validation: { type: "object" } }, required: ["ok", "phase", "artifactId", "deploymentRecordId", "smoke", "validation"] }
+            },
+            {
+                name: "platform_plan_artifact_draft_delete",
+                description: "Preview cleanup effects and receive the state-bound plan token required for deletion.",
+                annotations: mcpToolAnnotations("platform_plan_artifact_draft_delete", { readOnly: true, openWorld: true }),
+                inputSchema: { type: "object", properties: { artifactId: { type: "string", minLength: 1 } }, required: ["artifactId"], additionalProperties: false },
+                outputSchema: { type: "object", properties: { ok: { type: "boolean" }, phase: { type: "string" }, artifactId: { type: "string" }, eligible: { type: "boolean" }, effects: { type: "object" }, planToken: { type: "string" } }, required: ["ok", "phase", "artifactId", "eligible", "effects", "planToken"] }
+            },
+            {
+                name: "platform_delete_artifact_draft",
+                description: "Permanently remove an unpromoted private draft created by this MCP connection after exact-id confirmation.",
+                annotations: mcpToolAnnotations("platform_delete_artifact_draft", { readOnly: false, destructive: true, openWorld: true }),
+                inputSchema: {
+                    type: "object",
+                    properties: {
+                        artifactId: { type: "string", minLength: 1 },
+                        confirmArtifactId: { type: "string", minLength: 1 },
+                        planToken: { type: "string", minLength: 1 }
+                    },
+                    required: ["artifactId", "confirmArtifactId", "planToken"],
+                    additionalProperties: false
+                },
+                outputSchema: {
+                    type: "object",
+                    properties: { ok: { type: "boolean" }, deleted: { type: "boolean" }, artifactId: { type: "string" } },
+                    required: ["ok", "deleted", "artifactId"]
+                }
             }
-        ]
+        ].map(withRecoveryOutputSchema)
+    };
+}
+function withRecoveryOutputSchema(tool) {
+    if (!tool.outputSchema)
+        return tool;
+    return {
+        ...tool,
+        outputSchema: {
+            type: "object",
+            oneOf: [
+                tool.outputSchema,
+                {
+                    type: "object",
+                    properties: {
+                        ok: { const: false },
+                        error: {
+                            type: "object",
+                            properties: {
+                                code: { type: "string" },
+                                message: { type: "string" },
+                                retryable: { type: "boolean" },
+                                recoveryAction: { type: "string" }
+                            },
+                            required: ["code", "message", "retryable", "recoveryAction"],
+                            additionalProperties: false
+                        }
+                    },
+                    required: ["ok", "error"],
+                    additionalProperties: false
+                }
+            ]
+        }
     };
 }
 function mcpToolAnnotations(name, policy) {
@@ -603,7 +887,39 @@ function toolResult(value) {
     return { content, structuredContent };
 }
 function toolError(message) {
-    return { content: [{ type: "text", text: message }], isError: true };
+    return structuredToolError(message);
+}
+function structuredToolError(message) {
+    const code = recoveryErrorCode(message);
+    const recovery = {
+        platform_harness_timeout: { retryable: true, recoveryAction: "Retry the call. For a deployment, use platform_list_artifact_drafts to recover the artifact and platform_wait_artifact_deploy to resume progress." },
+        platform_mcp_tool_error: { retryable: false, recoveryAction: "Read the returned error code, correct the request or OAuth scopes, then retry." },
+        artifact_deploy_wait_timeout: { retryable: true, recoveryAction: "Call platform_wait_artifact_deploy again with the same artifactId and operationId." },
+        artifact_delete_plan_stale: { retryable: true, recoveryAction: "Call platform_plan_artifact_draft_delete again, review the new effects, and use its planToken." },
+        scope_required: { retryable: false, recoveryAction: "Reconnect the Build MCP and approve the requested scope." },
+        artifact_app_scaffold_target_not_empty: { retryable: false, recoveryAction: "Choose an empty appDir or deploy the existing app without scaffolding." }
+    };
+    const selected = recovery[code] ?? { retryable: /^platform_harness_http_error:5|timeout|rate_limited/.test(message), recoveryAction: "Inspect the code and message, correct the input if needed, then retry the same tool." };
+    const structuredContent = { ok: false, error: { code, message, ...selected } };
+    return {
+        content: [{ type: "text", text: JSON.stringify(structuredContent, null, 2) }],
+        structuredContent,
+        isError: true
+    };
+}
+function recoveryErrorCode(message) {
+    const known = [
+        "artifact_delete_plan_stale",
+        "artifact_deploy_wait_timeout",
+        "artifact_app_scaffold_target_not_empty",
+        "platform_harness_timeout",
+        "platform_mcp_tool_error",
+        "scope_required"
+    ].find((candidate) => message.includes(candidate));
+    if (known)
+        return known;
+    const match = message.match(/(?:^|:)([a-z][a-z0-9_]{2,})(?::|$)/);
+    return match?.[1] ?? "topline_mcp_tool_failed";
 }
 const jsonSchemaValidator = new AjvJsonSchemaValidator();
 function validateJsonSchema(schema, value) {
@@ -890,6 +1206,15 @@ function platformBaseUrl(opts) {
 function mcpSurface(opts) {
     return opts.surface ?? "build";
 }
+function logicalArtifactAppDir(workspaceAppDir, manifest) {
+    if (workspaceAppDir === "." || workspaceAppDir.startsWith("artifact-apps/"))
+        return workspaceAppDir;
+    const manifestId = typeof manifest.id === "string" ? manifest.id.trim() : "";
+    if (!/^[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$/.test(manifestId)) {
+        throw new Error("artifact_app_manifest_id_not_safe_for_source_root");
+    }
+    return `artifact-apps/${manifestId}`;
+}
 function defaultAuthFile(apiUrl, surface) {
     const key = createHash("sha256").update(`${platformBaseUrl({ apiUrl })}:${surface}`).digest("hex").slice(0, 16);
     return path.join(os.homedir(), ".topline", "build-mcp", `${key}.json`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@topline-build/harness-mcp",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Topline Build MCP for creating and deploying artifact app drafts.",
   "type": "module",
   "main": "./dist/index.js",
@@ -35,7 +35,8 @@
     "mcp:stdio": "node dist/cli.js",
     "prepack": "npm run build",
     "test": "vitest run",
-    "typecheck": "tsc --noEmit -p tsconfig.json"
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "certify:live": "node scripts/certify-live.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0"