@topline-build/harness-mcp 0.5.3 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable customer-visible Build MCP changes are recorded here. A source chang
 
 ## Unreleased
 
+## 0.6.0 - pending publication
+
+- Add server-owned external build sessions, guarded artifact-private SQL, and full acceptance/reviewer forwarding.
+- Check out exact artifact source and materialize selected assets through authenticated same-account transfers with hash, revision, archive and local-path checks.
+- Bind local draft create/deploy to the existing session identity, checked-out version, inspected source hash and stable operation keys. Additional asset, secret-metadata and data-verification scopes require explicit consent.
+
 ## 0.5.3 - pending publication
 
 - Add tenant-scoped Storyboard state, guarded edit, and exact-draft publication tools to Build MCP.

package/README.md

@@ -28,6 +28,12 @@ Storyboard authoring uses separate `storyboard:read` and `storyboard:write` OAut
 
 ## Typical workflow
 
+The 0.6.0 source adds session authoring; npm publication and a compatible customer API rollout are separate prerequisites. Start `platform_start_build_session` with an existing artifact's exact version or a new app manifest, a stable idempotency key and a Topline operation budget. External client model charges stay separate. For existing apps, `platform_checkout_artifact_app` writes exact saved source into a new local directory and returns its version, commit and source hash. Never reconstruct missing source from its manifest.
+
+Keep Build and Workspace as separate same-account connections. Workspace supplies catalog, SQL and trusted calculations through `data:read`. Reusable assets, approved secret metadata, private table writes, validation and finite artifact data verification each require their separately consented Build scopes: `harness:assets:read`, `harness:secrets:metadata:read`, `harness:artifact:tables:write`, `harness:artifact:validate`, and `harness:artifact:data:verify`. The defaults remain the existing artifact scopes; request an expanded set explicitly and reconnect. Secret discovery returns approved references only, never values.
+
+In session mode, `platform_deploy_artifact_app` requires the session ID, its exact current artifact version, a stable idempotency key, the session/checkout `inspectedSourceHash` and a fresh local `expectedBundleSha256`. The former pins the previously inspected remote source; the latter pins the local upload. Recover pending deployment and reviewer operations with their original IDs. Unknown work is never resubmitted by a status read. Add and run acceptance checks, prepare validation and request the independent review for the exact deployed revision. Approved output stays a private draft for an operator to publish.
+
 1. Use `platform_init_artifact_app` to create a starter, or point at an existing artifact app.
 2. Use `platform_inspect_artifact_app` to check local package boundaries and record its bundle SHA-256.
 3. Use `platform_deploy_artifact_app` with that SHA-256 to create or update a private draft.

package/dist/build-session-tools.d.ts

@@ -0,0 +1,9 @@
+import type { ListToolsResult, ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+type Annotate = (name: string, policy: {
+    readOnly: boolean;
+    idempotent?: boolean;
+    openWorld?: boolean;
+}) => ToolAnnotations;
+export declare function externalBuildHelperTools(annotate: Annotate): ListToolsResult["tools"];
+export declare const EXTERNAL_BUILD_FORWARD_TOOLS: Set<string>;
+export {};

package/dist/build-session-tools.js

@@ -0,0 +1,63 @@
+const id = { type: "string", format: "uuid" };
+const requestKey = { type: "string", minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9._:-]+$" };
+const session = { sessionId: id };
+const mutation = { ...session, artifactVersionId: id, idempotencyKey: requestKey };
+const deployed = { ...mutation, deploymentRecordId: id };
+export function externalBuildHelperTools(annotate) {
+    const tool = (name, description, properties, required, readOnly = false) => ({
+        name, description, annotations: annotate(name, { readOnly, idempotent: true, openWorld: true }),
+        inputSchema: { type: "object", additionalProperties: false, properties, required },
+        // Recovery adds a oneOf branch for {ok:false,error:...}; successful objects
+        // may omit ok, but must never match that branch too.
+        outputSchema: { type: "object", properties: { ok: { const: true } } }
+    });
+    return [
+        tool("platform_capability_status", "Read the connected Build product's current available, denied, unsupported and unconfigured tool families, contract version and helper requirement. Reconnect explicitly for newly consented scopes.", {}, [], true),
+        tool("platform_start_build_session", "Start external authoring with a private artifact identity, current version and platform-operation budget. Launches no internal coder. Existing artifact starts require its current version; new app starts require a manifest. Optional own conversation selects exact operator-approved secret references.", {
+            idempotencyKey: requestKey, artifactId: id, artifactVersionId: id, manifest: { type: "object" }, projectId: id, owningConversationId: id,
+            budgetCents: { type: "integer", minimum: 0, maximum: 100000 }, brief: { type: "string", minLength: 3, maxLength: 4000 }
+        }, ["idempotencyKey", "budgetCents", "brief"]),
+        tool("platform_read_build_session", "Read the owned build session and original pending operations. Does not start another coder or deployment.", session, ["sessionId"], true),
+        tool("platform_close_build_session", "Stop new authoring and request pending-operation cancellation. Unknown effects retain their reservation; cancellation does not undo committed writes.", session, ["sessionId"]),
+        tool("platform_run_artifact_workspace_sql", "Run guarded private artifact SQL using the exact session namespace, version and retry key. CREATE TABLE/ADD COLUMN require documentation. Enforced non-admin writes remain denied; unknown writes are never replayed.", {
+            ...mutation, sql: { type: "string", minLength: 1, maxLength: 20000 }, purpose: { type: "string", minLength: 3, maxLength: 500 },
+            params: { type: "object", additionalProperties: true }, maxRows: { type: "integer", minimum: 1, maximum: 5000 }, documentation: { type: "object" }, columnDocumentation: { type: "object" }
+        }, [...Object.keys(mutation), "sql", "purpose"]),
+        tool("platform_checkout_artifact_app", "Download exact saved app source through the owned session, verify archive hash/version/commit and extract regular source files into a new local directory. Missing source is never reconstructed.", {
+            ...session, targetDir: { type: "string", minLength: 1 }
+        }, ["sessionId", "targetDir"]),
+        tool("platform_list_asset_folders", "List the session's permitted reusable asset folders.", session, ["sessionId"], true),
+        tool("platform_list_assets", "List permitted reusable asset metadata with bounded pagination; excluded/deleted attachments are omitted.", {
+            ...session, query: { type: "string", maxLength: 200 }, folderId: id, limit: { type: "integer", minimum: 1, maximum: 500 }, offset: { type: "integer", minimum: 0 }
+        }, ["sessionId"], true),
+        tool("platform_materialize_assets", "Download exactly selected approved files into a new local directory. Verify each authenticated transfer's hash and size; source and attachment budgets remain separate.", {
+            ...session, assetIds: { type: "array", minItems: 1, maxItems: 50, uniqueItems: true, items: id }, targetDir: { type: "string", minLength: 1 }
+        }, ["sessionId", "assetIds", "targetDir"]),
+        tool("platform_list_build_secrets", "Read only exact operator-approved binding references for this session. Values are never retrieved. Authoring detach does not prove deployed runtime revocation.", session, ["sessionId"], true),
+        tool("platform_add_acceptance_check", "Add a required acceptance check bound to this build session and deployed revision. A semantic control query requires separate Build data-verification consent.", {
+            ...mutation, description: { type: "string", minLength: 3, maxLength: 1000 }
+        }, [...Object.keys(mutation), "description"]),
+        tool("platform_run_acceptance_checks", "Run required acceptance checks for the exact current draft revision through the shared service.", mutation, Object.keys(mutation)),
+        tool("platform_record_acceptance_review", "Record the builder's acceptance review without impersonating the independent validator or removing required checks.", {
+            ...mutation, checkId: id, status: { type: "string", enum: ["passed", "failed"] }, summary: { type: "string", minLength: 3, maxLength: 2000 }
+        }, [...Object.keys(mutation), "checkId", "status", "summary"]),
+        tool("platform_prepare_artifact_validation", "Prepare validation evidence for the exact private draft revision; missing required checks block readiness.", { ...session, artifactVersionId: id, deploymentRecordId: id }, ["sessionId", "artifactVersionId", "deploymentRecordId"], true),
+        tool("platform_request_artifact_validation", "Request the independent reviewer for the exact deployment and bounded evidence. Returns durable operation status; unavailable infrastructure leaves operator review required, never approval.", {
+            ...deployed, summary: { type: "string", minLength: 3, maxLength: 4000 }, waitMs: { type: "integer", minimum: 0, maximum: 1000 },
+            buildOk: { type: "boolean" }, typecheckOk: { type: "boolean" }, docImpact: { type: "string", enum: ["material", "none"] },
+            docImpactNotes: { type: "string", minLength: 12, maxLength: 2000 }, visualReview: { type: "object", additionalProperties: true }, dataValidation: { type: "object", additionalProperties: true }
+        }, [...Object.keys(deployed), "summary", "docImpact", "docImpactNotes", "visualReview"]),
+        tool("platform_artifact_validation_status", "Read the original validation result and pending prompts without starting another reviewer or deploy. Current authorization is rechecked before evidence delivery.", {
+            ...session, operationId: id
+        }, ["sessionId", "operationId"], true),
+        tool("platform_answer_operator_prompt", "Answer the exact saved operator prompt on the original review operation. Appends guidance and reopens the same eligible session; cannot approve validation or widen the saved grant.", {
+            ...session, operationId: id, promptId: id, idempotencyKey: requestKey, message: { type: "string", minLength: 3, maxLength: 4000 }
+        }, ["sessionId", "operationId", "promptId", "idempotencyKey", "message"])
+    ];
+}
+export const EXTERNAL_BUILD_FORWARD_TOOLS = new Set([
+    "platform_capability_status",
+    "platform_start_build_session", "platform_read_build_session", "platform_close_build_session", "platform_run_artifact_workspace_sql",
+    "platform_list_asset_folders", "platform_list_assets", "platform_list_build_secrets", "platform_add_acceptance_check", "platform_run_acceptance_checks",
+    "platform_record_acceptance_review", "platform_prepare_artifact_validation", "platform_request_artifact_validation", "platform_artifact_validation_status", "platform_answer_operator_prompt"
+]);

package/dist/index.d.ts

@@ -32,7 +32,7 @@ export interface PackedArtifactAppBundle {
 type ToolProgressReporter = (progress: number, message: string) => void | Promise<void>;
 export declare const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 export declare const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export declare const HARNESS_MCP_VERSION = "0.5.3";
+export declare const HARNESS_MCP_VERSION = "0.6.0";
 export declare const DEFAULT_OAUTH_SCOPES: readonly string[];
 export interface BuildMcpSetupOption {
     readonly flag: string;
@@ -52,11 +52,6 @@ export declare function callHarnessTool(opts: HarnessMcpStdioOptions, name: stri
     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;
@@ -66,6 +61,37 @@ export declare function deployArtifactApp(opts: HarnessMcpStdioOptions, input: R
     };
     create: unknown;
     deploy: unknown;
+    sessionId?: string | undefined;
+    ok: boolean;
+    artifactId: string;
+    artifactVersionId: string;
+    manifestId: string | null;
+    clientRequestId: string;
+}>;
+export declare function checkoutArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+    ok: boolean;
+    sessionId: string;
+    artifactId: unknown;
+    artifactVersionId: string;
+    commitSha: string;
+    sourceHash: string;
+    appDir: string;
+    platformAppDir: unknown;
+    fileCount: number;
+    byteCount: number;
+}>;
+export declare function materializeBuildAssets(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
+    ok: boolean;
+    sessionId: string;
+    directory: string;
+    byteCount: number;
+    files: {
+        id: string;
+        file: string;
+        size: number;
+        sha256: unknown;
+        mime: unknown;
+    }[];
 }>;
 export declare function inspectArtifactApp(opts: HarnessMcpStdioOptions, input: Record<string, unknown>): Promise<{
     ok: boolean;

package/dist/index.js

@@ -1,11 +1,13 @@
 import { spawn } from "node:child_process";
 import { createHash, randomBytes } from "node:crypto";
 import { existsSync } from "node:fs";
-import { mkdir, mkdtemp, readdir, readFile, realpath, lstat, writeFile, rm, rename } from "node:fs/promises";
+import { cp, mkdir, mkdtemp, readdir, readFile, realpath, lstat, writeFile, rm, rename } from "node:fs/promises";
 import { createServer } from "node:http";
 import os from "node:os";
 import path from "node:path";
 import { gzipSync } from "node:zlib";
+import { externalBuildHelperTools, EXTERNAL_BUILD_FORWARD_TOOLS } from "./build-session-tools.js";
+import { boundedTransfer, extractArtifactSourceArchive, MAX_SOURCE_ARCHIVE_BYTES, safeSourcePath } from "./source-checkout.js";
 import { Server as McpServer } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { AjvJsonSchemaValidator } from "@modelcontextprotocol/sdk/validation/ajv";
@@ -13,7 +15,7 @@ import { CallToolRequestSchema, ErrorCode, ListToolsRequestSchema, McpError } fr
 export const DEFAULT_MCP_PROTOCOL_VERSION = "2025-11-25";
 const DEFAULT_TIMEOUT_MS = 120_000;
 export const BUILD_MCP_SERVER_NAME = "topline-build-stdio";
-export const HARNESS_MCP_VERSION = "0.5.3";
+export const HARNESS_MCP_VERSION = "0.6.0";
 export const DEFAULT_OAUTH_SCOPES = Object.freeze(["harness:artifact:read", "harness:artifact:write", "harness:artifact:deploy", "harness:artifact:delete"]);
 export const BUILD_MCP_SETUP_OPTIONS = Object.freeze([
     { flag: "--url", env: "TOPLINE_API_URL", aliases: ["PLATFORM_API_URL", "OVERSITE_API_URL"], required: true, description: "Topline tenant base URL. HTTPS is required except for loopback development." },
@@ -161,6 +163,12 @@ export async function callHarnessTool(opts, name, args, hooks) {
         case "platform_checkout_design_system":
             result = toolResult(await checkoutDesignSystem(opts, input));
             break;
+        case "platform_checkout_artifact_app":
+            result = toolResult(await checkoutArtifactApp(opts, input));
+            break;
+        case "platform_materialize_assets":
+            result = toolResult(await materializeBuildAssets(opts, input));
+            break;
         case "platform_submit_design_system_draft":
             result = toolResult(await submitDesignSystemDraft(opts, input));
             break;
@@ -189,6 +197,12 @@ export async function callHarnessTool(opts, name, args, hooks) {
             result = toolResult(await initArtifactApp(opts, input));
             break;
         default:
+            if (EXTERNAL_BUILD_FORWARD_TOOLS.has(name)) {
+                if (mcpSurface(opts) !== "build")
+                    throw new Error("external_session_requires_build_surface");
+                result = toolResult(await callHostedBuildTool(opts, name, input));
+                break;
+            }
             throw new McpError(ErrorCode.InvalidParams, `Unknown tool: ${name}`);
     }
     const outputError = tool.outputSchema
@@ -203,7 +217,8 @@ export async function deployArtifactApp(opts, input, onProgress) {
     await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
     const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
-    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
+    const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
     const clientRequestId = optionalString(input, "requestId") ?? createHash("sha256")
         .update(JSON.stringify({ apiUrl: platformBaseUrl(opts), appDir: platformAppDir, manifestId: manifest.id ?? null }))
         .digest("hex");
@@ -213,18 +228,39 @@ export async function deployArtifactApp(opts, input, onProgress) {
     if (expectedBundleSha256 && bundle.sha256 !== expectedBundleSha256) {
         throw new Error("artifact_app_bundle_changed_after_inspection");
     }
+    const sessionId = optionalString(input, "sessionId");
+    const sessionVersion = optionalString(input, "artifactVersionId");
+    const idempotencyKey = optionalString(input, "idempotencyKey");
+    const inspectedSourceHash = optionalString(input, "inspectedSourceHash");
+    let sessionArtifactId;
+    if (sessionId) {
+        if (mcpSurface(opts) !== "build")
+            throw new Error("external_session_requires_build_surface");
+        if (!sessionVersion || !idempotencyKey || !inspectedSourceHash || !expectedBundleSha256)
+            throw new Error("build_session_deployment_arguments_required");
+        const session = asRecord(await callHostedBuildTool(opts, "platform_read_build_session", { sessionId }));
+        // The server resolves a repeated operation key before checking current
+        // version/source. Do not reject a lost-response retry using the newer read.
+        // Fresh mutations still require the caller's exact inspected revision.
+        sessionArtifactId = stringValue(session.artifactId, "artifactId");
+        if (input.artifactId !== undefined && input.artifactId !== sessionArtifactId)
+            throw new Error("build_session_artifact_mismatch");
+    }
+    else if (sessionVersion || idempotencyKey || inspectedSourceHash || suppliedPlatformAppDir)
+        throw new Error("build_session_id_required");
     await onProgress?.(0.4, "Creating private artifact draft");
     const created = await fetchJson(opts, artifactAppsPath(opts), {
         method: "POST",
         headers: await jsonHeaders(opts),
         body: JSON.stringify({
-            artifactId: optionalString(input, "artifactId"),
+            artifactId: sessionArtifactId ?? optionalString(input, "artifactId"),
             title: optionalString(input, "title"),
             description: optionalString(input, "description"),
             projectId: optionalString(input, "projectId"),
             clientRequestId,
             bundleSha256: bundle.sha256,
-            manifest
+            manifest,
+            ...(sessionId ? { sessionId, artifactVersionId: sessionVersion, idempotencyKey, inspectedSourceHash } : {})
         })
     });
     const createdRecord = asRecord(created);
@@ -241,19 +277,22 @@ export async function deployArtifactApp(opts, input, onProgress) {
             "content-type": "application/gzip",
             "MCP-Protocol-Version": opts.protocolVersion,
             "x-platform-artifact-version-id": artifactVersionId,
-            "x-platform-app-dir": platformAppDir
+            "x-platform-app-dir": platformAppDir,
+            ...(sessionId ? { "x-platform-build-session-id": sessionId, "x-platform-idempotency-key": idempotencyKey, "x-platform-inspected-source-sha256": inspectedSourceHash, "x-platform-expected-bundle-sha256": bundle.sha256 } : {})
         },
         body: bundle.body
     });
     await onProgress?.(1, "Completed trusted draft deployment");
     const deployedRecord = asRecord(deployed);
-    const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId : null;
+    const operationId = typeof deployedRecord.taskId === "string" ? deployedRecord.taskId
+        : typeof deployedRecord.operationId === "string" ? deployedRecord.operationId : null;
     return {
         ok: true,
         artifactId,
         artifactVersionId,
         manifestId: typeof manifest.id === "string" ? manifest.id : null,
         clientRequestId,
+        ...(sessionId ? { sessionId } : {}),
         operationId,
         bundle: {
             fileCount: bundle.fileCount,
@@ -265,13 +304,135 @@ export async function deployArtifactApp(opts, input, onProgress) {
         deploy: deployed
     };
 }
+async function fetchBuildTransfer(opts, advertisedPath, expectedPath, sha256, maxBytes, expectedSize, revision) {
+    if (advertisedPath !== expectedPath || typeof sha256 !== "string" || !/^[a-f0-9]{64}$/i.test(sha256))
+        throw new Error("build_transfer_identity_invalid");
+    const base = new URL(platformBaseUrl(opts));
+    const url = new URL(expectedPath, base);
+    if (url.origin !== base.origin || url.pathname !== expectedPath || url.search || url.hash)
+        throw new Error("build_transfer_identity_invalid");
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+    try {
+        const response = await (opts.fetchImpl ?? fetch)(url.href, { method: "GET", headers: await jsonHeaders(opts), redirect: "error", signal: controller.signal });
+        if (!response.ok || (response.url && new URL(response.url).origin !== base.origin))
+            throw new Error("build_transfer_unavailable");
+        if (response.headers.get("x-topline-content-sha256")?.toLowerCase() !== sha256.toLowerCase())
+            throw new Error("build_transfer_hash_mismatch");
+        if (revision && (response.headers.get("x-topline-artifact-version") !== revision.artifactVersionId || response.headers.get("x-topline-source-commit") !== revision.commitSha))
+            throw new Error("build_transfer_revision_mismatch");
+        const body = await boundedTransfer(response, maxBytes, expectedSize);
+        if (createHash("sha256").update(body).digest("hex") !== sha256.toLowerCase())
+            throw new Error("build_transfer_hash_mismatch");
+        return body;
+    }
+    catch (error) {
+        if (controller.signal.aborted)
+            throw new Error("platform_harness_timeout");
+        throw error;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+async function newBuildInputTarget(opts, input) {
+    if (mcpSurface(opts) !== "build")
+        throw new Error("external_session_requires_build_surface");
+    const target = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "targetDir"));
+    if (existsSync(target))
+        throw new Error("build_input_target_exists");
+    await assertAuthFileOutsideAppDir(opts.authFile, target);
+    await mkdir(path.dirname(target), { recursive: true, mode: 0o700 });
+    const checked = await resolveWorkspacePathSafely(opts.workspaceRoot, stringArg(input, "targetDir"));
+    if (checked !== target)
+        throw new Error("build_input_target_changed");
+    return target;
+}
+async function installBuildInputs(opts, target, stage) {
+    // Reserve the new target exclusively; never rename over a directory another
+    // process created. cp refuses existing files rather than overwriting them.
+    await resolveWorkspacePathSafely(opts.workspaceRoot, path.relative(opts.workspaceRoot, target));
+    await mkdir(target, { mode: 0o700 });
+    try {
+        for (const entry of await readdir(stage))
+            await cp(path.join(stage, entry), path.join(target, entry), { recursive: true, force: false, errorOnExist: true });
+    }
+    catch (error) {
+        await rm(target, { recursive: true, force: true });
+        throw error;
+    }
+}
+export async function checkoutArtifactApp(opts, input) {
+    const target = await newBuildInputTarget(opts, input);
+    const sessionId = stringArg(input, "sessionId");
+    const metadata = asRecord(await callHostedBuildTool(opts, "platform_checkout_artifact_app", { sessionId }));
+    const artifactVersionId = stringValue(metadata.artifactVersionId, "artifactVersionId");
+    const commitSha = stringValue(metadata.commitSha, "commitSha");
+    if (!/^[a-f0-9]{40}$/.test(commitSha) || !/^[0-9a-f-]{36}$/i.test(artifactVersionId))
+        throw new Error("build_transfer_revision_invalid");
+    const body = await fetchBuildTransfer(opts, metadata.downloadPath, `/api/harness/build-sessions/${sessionId}/source`, metadata.sha256, MAX_SOURCE_ARCHIVE_BYTES, undefined, { artifactVersionId, commitSha });
+    const staging = await mkdtemp(path.join(path.dirname(target), ".topline-app-checkout-"));
+    try {
+        const source = path.join(staging, "source");
+        await mkdir(source, { mode: 0o700 });
+        const extracted = await extractArtifactSourceArchive(body, source);
+        if (extracted.fileCount !== metadata.fileCount || extracted.byteCount !== metadata.byteCount)
+            throw new Error("artifact_source_shape_mismatch");
+        await readManifest(source);
+        await installBuildInputs(opts, target, source);
+        return { ok: true, sessionId, artifactId: metadata.artifactId, artifactVersionId, commitSha, sourceHash: extracted.sha256,
+            appDir: path.relative(opts.workspaceRoot, target).replaceAll("\\", "/"), platformAppDir: metadata.appDir,
+            fileCount: extracted.fileCount, byteCount: extracted.byteCount };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
+export async function materializeBuildAssets(opts, input) {
+    const target = await newBuildInputTarget(opts, input);
+    const sessionId = stringArg(input, "sessionId");
+    const assetIds = input.assetIds;
+    if (!Array.isArray(assetIds) || !assetIds.length || assetIds.length > 50 || assetIds.some(id => typeof id !== "string" || !/^[0-9a-f-]{36}$/i.test(id)))
+        throw new Error("asset_selection_required");
+    const selected = new Set(assetIds);
+    const metadata = asRecord(await callHostedBuildTool(opts, "platform_materialize_assets", { sessionId, assetIds }));
+    if (!Array.isArray(metadata.assets) || metadata.assets.length !== selected.size)
+        throw new Error("asset_transfer_identity_invalid");
+    const assets = metadata.assets.map(asRecord);
+    if (assets.some(asset => typeof asset.id !== "string" || !selected.delete(asset.id)) || selected.size)
+        throw new Error("asset_transfer_identity_invalid");
+    const staging = await mkdtemp(path.join(path.dirname(target), ".topline-assets-"));
+    let total = 0;
+    try {
+        const files = [];
+        for (const asset of assets) {
+            const size = asset.size;
+            if (typeof size !== "number" || !Number.isSafeInteger(size) || size < 0 || size > 16 * 1024 * 1024 || (total += size) > 64 * 1024 * 1024)
+                throw new Error("asset_transfer_too_large");
+            const name = stringValue(asset.name, "name");
+            if (Buffer.byteLength(name, "utf8") > 200 || name.includes("/") || safeSourcePath(name) !== name)
+                throw new Error("asset_transfer_name_invalid");
+            const id = stringValue(asset.id, "id");
+            const body = await fetchBuildTransfer(opts, asset.downloadPath, `/api/harness/build-sessions/${sessionId}/assets/${id}`, asset.sha256, 16 * 1024 * 1024, size);
+            const localName = `${id}-${name}`;
+            await writeFile(path.join(staging, localName), body, { mode: 0o600, flag: "wx" });
+            files.push({ id, file: localName, size, sha256: asset.sha256, mime: asset.mime });
+        }
+        await installBuildInputs(opts, target, staging);
+        return { ok: true, sessionId, directory: path.relative(opts.workspaceRoot, target).replaceAll("\\", "/"), byteCount: total, files };
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+    }
+}
 export async function inspectArtifactApp(opts, input) {
     const appDir = stringArg(input, "appDir");
     const absoluteAppDir = await resolveWorkspacePathSafely(opts.workspaceRoot, appDir);
     await assertAuthFileOutsideAppDir(opts.authFile, absoluteAppDir);
     const workspaceAppDir = workspaceRelativeAppDir(opts.workspaceRoot, absoluteAppDir);
     const manifest = await readManifest(absoluteAppDir);
-    const platformAppDir = logicalArtifactAppDir(workspaceAppDir, manifest);
+    const suppliedPlatformAppDir = optionalString(input, "platformAppDir");
+    const platformAppDir = suppliedPlatformAppDir ? (suppliedPlatformAppDir === "." ? "." : validateArchivePrefix(suppliedPlatformAppDir)) : logicalArtifactAppDir(workspaceAppDir, manifest);
     const bundle = await packArtifactAppDirectory(absoluteAppDir, platformAppDir === "." ? "" : platformAppDir);
     return {
         ok: true,
@@ -787,6 +948,8 @@ function shouldExclude(relative, isDirectory) {
         return true;
     if (parts.some((part) => part === ".git" || part === "node_modules"))
         return true;
+    if (parts.some(part => /(?:\.(?:pem|key|p12|pfx)|^\.?(?:credentials|netrc|npmrc|aws|ssh)$)/i.test(part)))
+        return true;
     if (isDirectory && FORBIDDEN_DIRS.has(name))
         return true;
     return false;
@@ -927,7 +1090,12 @@ const BUILD_MCP_TOOLS = [
                 description: { type: "string" },
                 projectId: { type: "string", format: "uuid" },
                 expectedBundleSha256: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Optional SHA-256 from platform_inspect_artifact_app; deployment fails locally if source changed." },
-                requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." }
+                requestId: { type: "string", minLength: 1, maxLength: 128, description: "Optional stable retry key; generated deterministically when omitted." },
+                sessionId: { type: "string", format: "uuid" },
+                artifactVersionId: { type: "string", format: "uuid", description: "Exact current version from the session or checkout; required with sessionId." },
+                idempotencyKey: { type: "string", minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9._:-]+$" },
+                inspectedSourceHash: { type: "string", pattern: "^[0-9a-fA-F]{64}$", description: "Echo the session/source checkout hash; required with sessionId. expectedBundleSha256 separately pins the newly inspected local upload." },
+                platformAppDir: { type: "string", minLength: 1, description: "Saved remote app root from an existing-app checkout. Session mode only; preserve this when the local checkout directory has a different name." }
             },
             required: ["appDir"],
             additionalProperties: false
@@ -953,7 +1121,7 @@ const BUILD_MCP_TOOLS = [
         annotations: mcpToolAnnotations("platform_inspect_artifact_app", { readOnly: true }),
         inputSchema: {
             type: "object",
-            properties: { appDir: { type: "string", minLength: 1 } },
+            properties: { appDir: { type: "string", minLength: 1 }, platformAppDir: { type: "string", minLength: 1, description: "Preserve the saved remote source root returned by checkout when inspecting an existing app." } },
             required: ["appDir"],
             additionalProperties: false
         },
@@ -1207,7 +1375,8 @@ const BUILD_MCP_TOOLS = [
             properties: { ok: { type: "boolean" }, deleted: { type: "boolean" }, artifactId: { type: "string" } },
             required: ["ok", "deleted", "artifactId"]
         }
-    }
+    },
+    ...externalBuildHelperTools(mcpToolAnnotations)
 ].map(withRecoveryOutputSchema);
 export function listTools() {
     // Preserve the original tools/list isolation boundary: callers must not be

package/dist/source-checkout.d.ts

@@ -0,0 +1,10 @@
+export declare const MAX_SOURCE_ARCHIVE_BYTES: number;
+/** All path rules apply on every host, including Windows aliases and devices. */
+export declare function safeSourcePath(raw: string): string;
+/** Extract only regular files into a task-created empty staging directory. */
+export declare function extractArtifactSourceArchive(body: Buffer, stagingRoot: string): Promise<{
+    fileCount: number;
+    byteCount: number;
+    sha256: string;
+}>;
+export declare function boundedTransfer(response: Response, maxBytes: number, expectedSize?: number): Promise<Buffer>;

package/dist/source-checkout.js

@@ -0,0 +1,146 @@
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { gunzipSync } from "node:zlib";
+export const MAX_SOURCE_ARCHIVE_BYTES = 64 * 1024 * 1024;
+const MAX_CONTENT_BYTES = 512 * 1024 * 1024;
+const MAX_FILES = 25_000;
+const BLOCK = 512;
+const forbiddenDirs = new Set([".git", "node_modules", ".next", ".vite", ".turbo", ".cache", "dist", "build", "coverage"]);
+/** All path rules apply on every host, including Windows aliases and devices. */
+export function safeSourcePath(raw) {
+    if (!raw || raw.startsWith("/") || raw.includes("\\"))
+        throw new Error("artifact_source_path_invalid");
+    const segments = raw.replace(/^\.\//, "").split("/");
+    if (segments.at(-1) === "")
+        segments.pop();
+    if (!segments.length || segments.length > 64 || segments.some(part => !part || part === "." || part === ".." || /[\u0000-\u001f\u007f:]/u.test(part) || /[. ]$/.test(part) || /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\.|$)/i.test(part)))
+        throw new Error("artifact_source_path_invalid");
+    if (segments.some(part => forbiddenDirs.has(part.toLowerCase()) || part.toLowerCase().startsWith(".env") || /(?:\.(?:pem|key|p12|pfx)|^\.?(?:credentials|netrc|npmrc|aws|ssh)$)/i.test(part)))
+        throw new Error("artifact_source_credential_or_cache_forbidden");
+    return segments.join("/");
+}
+function text(header, offset, length) {
+    const field = header.subarray(offset, offset + length);
+    const nul = field.indexOf(0);
+    return field.subarray(0, nul < 0 ? field.length : nul).toString("utf8");
+}
+function octal(header, offset, length) {
+    const value = text(header, offset, length).trim();
+    if (!/^[0-7]+$/.test(value))
+        throw new Error("artifact_source_tar_invalid");
+    const number = Number.parseInt(value, 8);
+    if (!Number.isSafeInteger(number) || number < 0)
+        throw new Error("artifact_source_tar_invalid");
+    return number;
+}
+/** Extract only regular files into a task-created empty staging directory. */
+export async function extractArtifactSourceArchive(body, stagingRoot) {
+    if (!body.length || body.length > MAX_SOURCE_ARCHIVE_BYTES)
+        throw new Error("artifact_source_transfer_too_large");
+    let tar;
+    try {
+        tar = gunzipSync(body, { maxOutputLength: MAX_CONTENT_BYTES + MAX_FILES * 1024 });
+    }
+    catch {
+        throw new Error("artifact_source_archive_invalid");
+    }
+    let position = 0;
+    let fileCount = 0;
+    let byteCount = 0;
+    let ended = false;
+    let entryCount = 0;
+    const files = new Set();
+    const dirs = new Set();
+    const paths = new Map();
+    while (position + BLOCK <= tar.length) {
+        const header = tar.subarray(position, position + BLOCK);
+        position += BLOCK;
+        if (header.every(byte => byte === 0)) {
+            if (position + BLOCK > tar.length || !tar.subarray(position).every(byte => byte === 0))
+                throw new Error("artifact_source_tar_invalid");
+            ended = true;
+            break;
+        }
+        if (++entryCount > MAX_FILES * 2)
+            throw new Error("artifact_source_unpacked_too_large");
+        const expectedChecksum = octal(header, 148, 8);
+        const checksum = header.reduce((sum, byte, index) => sum + (index >= 148 && index < 156 ? 32 : byte), 0);
+        if (checksum !== expectedChecksum || text(header, 257, 6) !== "ustar")
+            throw new Error("artifact_source_tar_invalid");
+        const prefix = text(header, 345, 155);
+        const rawName = `${prefix ? prefix + "/" : ""}${text(header, 0, 100)}`;
+        const size = octal(header, 124, 12);
+        const padded = Math.ceil(size / BLOCK) * BLOCK;
+        if (position + padded > tar.length)
+            throw new Error("artifact_source_tar_invalid");
+        const kind = String.fromCharCode(header[156]);
+        if ((rawName === "." || rawName === "./") && kind === "5" && size === 0)
+            continue;
+        const relative = safeSourcePath(rawName);
+        const key = relative.toLowerCase();
+        const segments = relative.split("/");
+        for (let length = 1; length <= segments.length; length++) {
+            const actual = segments.slice(0, length).join("/");
+            const canonical = actual.toLowerCase();
+            if (paths.has(canonical) && paths.get(canonical) !== actual)
+                throw new Error("artifact_source_duplicate_path");
+            paths.set(canonical, actual);
+        }
+        if (paths.size > MAX_FILES * 2)
+            throw new Error("artifact_source_unpacked_too_large");
+        if (kind !== "0" && kind !== "\0" && kind !== "5")
+            throw new Error("artifact_source_entry_type_forbidden");
+        if (files.has(key) || dirs.has(key))
+            throw new Error("artifact_source_duplicate_path");
+        const ancestors = key.split("/").slice(0, -1);
+        if (ancestors.some((_, index) => files.has(ancestors.slice(0, index + 1).join("/"))))
+            throw new Error("artifact_source_duplicate_path");
+        const output = path.resolve(stagingRoot, relative);
+        const diff = path.relative(stagingRoot, output);
+        if (diff === ".." || diff.startsWith(`..${path.sep}`) || path.isAbsolute(diff))
+            throw new Error("artifact_source_path_invalid");
+        if (kind === "5") {
+            if (size !== 0)
+                throw new Error("artifact_source_tar_invalid");
+            dirs.add(key);
+            await mkdir(output, { recursive: true, mode: 0o700 });
+        }
+        else {
+            if (++fileCount > MAX_FILES || (byteCount += size) > MAX_CONTENT_BYTES)
+                throw new Error("artifact_source_unpacked_too_large");
+            files.add(key);
+            await mkdir(path.dirname(output), { recursive: true, mode: 0o700 });
+            await writeFile(output, tar.subarray(position, position + size), { flag: "wx", mode: 0o600 });
+        }
+        position += padded;
+    }
+    if (!ended || !fileCount)
+        throw new Error("artifact_source_archive_invalid");
+    return { fileCount, byteCount, sha256: createHash("sha256").update(body).digest("hex") };
+}
+export async function boundedTransfer(response, maxBytes, expectedSize) {
+    const rawLength = response.headers.get("content-length");
+    const declared = rawLength === null ? null : Number(rawLength);
+    if (declared !== null && (!Number.isSafeInteger(declared) || declared < 0 || declared > maxBytes || (expectedSize !== undefined && declared !== expectedSize)))
+        throw new Error("build_transfer_size_invalid");
+    if (!response.body)
+        throw new Error("build_transfer_size_invalid");
+    const chunks = [];
+    let total = 0;
+    const reader = response.body.getReader();
+    for (;;) {
+        const part = await reader.read();
+        if (part.done)
+            break;
+        total += part.value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => undefined);
+            throw new Error("build_transfer_size_invalid");
+        }
+        chunks.push(Buffer.from(part.value));
+    }
+    if ((!total && expectedSize !== 0) || (declared !== null && total !== declared) || (expectedSize !== undefined && total !== expectedSize))
+        throw new Error("build_transfer_size_invalid");
+    return Buffer.concat(chunks);
+}