@superblocksteam/vite-plugin-file-sync 1.99.99-next.3 → 2.0.0-SNAPSHOT.2143e2e95d0107ab

package/dist/ai-service/agent/tools/build-install-packages.js

@@ -0,0 +1,727 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { metrics } from "@opentelemetry/api";
+import z from "zod";
+import { isProtectedCorePackage, isValidNpmPackageName, isValidNpmVersionSpec, PROTECTED_CORE_PACKAGES, } from "@superblocksteam/library-shared/types";
+import { getErrorMeta, getLogger } from "../../../util/logger.js";
+import { ADVISORY_DETAILS_MAX_LENGTH, ADVISORY_SUMMARY_MAX_LENGTH, triageVulnerability, } from "../../security/vulnerability-triage.js";
+import { NpmInstallBlocked, scrubSecrets } from "../../types.js";
+import { createToolFactory, ToolCategory } from "../tools2/types.js";
+const TRIAGE_APP_CONTEXT_MAX_LENGTH = 20_000;
+const PROCEED_WITH_REASON_MAX_LENGTH = 500;
+/**
+ * Bound the advisory prose on the agent-facing projection. `NpmInstallBlocked`
+ * deliberately keeps the full text for the audit sink and the blocked-install
+ * log; the agent reads `error.findings` verbatim, so a multi-KB advisory would
+ * otherwise crowd out its context.
+ */
+function boundFindingsForAgent(payload) {
+    if (!payload.findings)
+        return payload;
+    return {
+        ...payload,
+        findings: payload.findings.map((finding) => ({
+            ...finding,
+            ...(finding.details !== undefined
+                ? { details: finding.details.slice(0, ADVISORY_DETAILS_MAX_LENGTH) }
+                : {}),
+            ...(finding.summary !== undefined
+                ? { summary: finding.summary.slice(0, ADVISORY_SUMMARY_MAX_LENGTH) }
+                : {}),
+        })),
+    };
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * True when `packageName` appears as a literal token in `message`.
+ * Scoped names (`@scope/name`) and unscoped names are matched with npm-name
+ * boundaries so `react` does not match `preact` / `reactive`.
+ *
+ * The trailing boundary allows `@` (builders write `left-pad@1.3.0`) and a
+ * sentence-ending `.`, but not a `.` that continues the token (`left-pad.js`).
+ */
+export function isPackageNamedInMessage(packageName, message) {
+    if (packageName.length === 0 || message.length === 0)
+        return false;
+    const pattern = new RegExp(`(^|[^\\w@/.-])${escapeRegExp(packageName)}(?![\\w/-])(?!\\.\\w)`, "i");
+    return pattern.test(message);
+}
+export function findUserRequestedPackageNames(packages, message) {
+    const requested = [];
+    for (const pkg of packages) {
+        if (isPackageNamedInMessage(pkg.name, message) &&
+            !requested.includes(pkg.name)) {
+            requested.push(pkg.name);
+        }
+    }
+    return requested;
+}
+/**
+ * Names from `packages` the builder asked for by name: either matched in the
+ * current turn's message, or carried over from an earlier turn's CVE block.
+ * The carry-over matters because the builder answers "do you still want it?"
+ * with a bare reason ("we need it for the demo") that never repeats the name.
+ */
+export function resolveUserRequestedPackageNames(packages, message, pendingCveProceedPackages) {
+    const named = findUserRequestedPackageNames(packages, message);
+    const carriedOver = pendingCveProceedPackages.filter((name) => !named.includes(name) && packages.some((pkg) => pkg.name === name));
+    return [...named, ...carriedOver];
+}
+function buildTriageAppContext(services) {
+    const serialized = JSON.stringify({
+        apis: services.appContextStore.apiSemanticsByName,
+        components: services.appContextStore.componentSemanticsById,
+    });
+    return serialized.slice(0, TRIAGE_APP_CONTEXT_MAX_LENGTH);
+}
+async function triageCveFindings(args) {
+    const { abortSignal, findings, services } = args;
+    const appContext = buildTriageAppContext(services);
+    const { model, providerConfig } = services.llmProvider.modelForTask("fast");
+    const verdicts = [];
+    for (const finding of findings) {
+        try {
+            verdicts.push(await triageVulnerability({
+                abortSignal,
+                appContext,
+                finding,
+                generateObject: async (generationArgs) => await services.llmClient.generateObject(generationArgs),
+                model,
+                modelName: providerConfig.model,
+                providerConfig,
+            }));
+        }
+        catch (error) {
+            metrics
+                .getMeter("superblocks.clark.pkg_security")
+                .createCounter("superblocks.clark.pkg_security.triage_unavailable")
+                .add(1);
+            getLogger().warn("[pkg-security] CVE exploitability triage unavailable", getErrorMeta(error));
+            verdicts.push({
+                advisoryId: finding.advisoryId,
+                confidence: "low",
+                evaluatedAt: new Date().toISOString(),
+                model: providerConfig.model,
+                package: finding.package,
+                reasoning: "Automated exploitability triage was unavailable.",
+                stage: "install",
+                verdict: "uncertain",
+            });
+        }
+    }
+    return verdicts;
+}
+async function readPackageJson(appRootDirPath) {
+    try {
+        const packageJsonPath = path.join(appRootDirPath, "package.json");
+        const content = await fs.readFile(packageJsonPath, "utf-8");
+        return JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+}
+/** Sanitize a string before interpolating it into the agent-facing message.
+ *
+ *  Package specs and registry hosts originate from npm's error.detail /
+ *  error.summary — i.e. attacker-controllable for a hostile or misbehaving
+ *  registry. Without sanitization, a value containing backticks/newlines
+ *  could break out of the surrounding markdown code-span (or fake one),
+ *  letting the registry inject instructions into the agent's read context.
+ *
+ *  Three transforms, applied in order:
+ *    - Strip ASCII control chars + newlines so injected line breaks can't
+ *      forge a new "instruction" paragraph.
+ *    - Strip backticks so the value can't terminate the surrounding span or
+ *      introduce a fenced block.
+ *    - Cap length so a multi-KB payload can't push downstream context out
+ *      of the window. 100 chars accommodates the longest realistic scoped
+ *      spec (`@some-org/some-package@1.2.3-rc.4+sha.abc1234`) with room. */
+const SAFE_INTERP_MAX_LEN = 100;
+function sanitizeForAgentMessage(value) {
+    // eslint-disable-next-line no-control-regex -- intentional: scrubbing CR/LF/control chars
+    const stripped = value.replace(/[`\u0000-\u001F\u007F]/g, "");
+    return stripped.length > SAFE_INTERP_MAX_LEN
+        ? `${stripped.slice(0, SAFE_INTERP_MAX_LEN)}…`
+        : stripped;
+}
+/** Whether `host` (already lowercased downstream by the URL parser, but we
+ *  re-lowercase for defence) is one of the public npmjs.org registry hosts.
+ *
+ *  `registry.npmjs.org` is the de facto URL npm uses in cloud-edit, SaaS,
+ *  on-prem-without-private-registry, and the baked-in dev-server `.npmrc`.
+ *  Legacy `npmjs.org` redirects to it but can still appear in error
+ *  summaries from older npm clients. Anything else (Artifactory, GHPR,
+ *  Verdaccio, a customer-hosted mirror) counts as a private host. */
+function isPublicNpmHost(host) {
+    if (!host)
+        return false;
+    const h = host.toLowerCase();
+    return (h === "registry.npmjs.org" || h === "npmjs.org" || h.endsWith(".npmjs.org"));
+}
+/**
+ * Render a `NpmInstallBlocked` into an actionable one-paragraph message for
+ * the agent, plus the discriminator that selected the message branch. The
+ * structured `error` field carries the canonical inputs; this string is what
+ * the model reads first.
+ *
+ * Branch selection (see `NpmInstallBlockedMessageVariant`):
+ *
+ *   - `unreachable_escalation` — `registry_unreachable` + zero configured
+ *     rows + host is npmjs (or unknown). Covers both the SaaS "npmjs is down"
+ *     case and the airgapped "egress is blocked and no private registry is
+ *     wired up" case with one hybrid message, because the dev-server cannot
+ *     distinguish them from the error alone.
+ *   - `private_mirror_hint` — `not_in_registry` + at least one configured
+ *     row + host is private. Appends "an org admin may need to mirror this
+ *     package" because that's an actionable escalation on a private
+ *     registry; same hint on npmjs would be misleading.
+ *   - `malware_block` — `vulnerable_package` + malware finding. Hard-block;
+ *     agent must pick a different package (no retry / no override).
+ *   - `index_unavailable` — security index / dry-run probe could not vouch
+ *     for the install. Fail-closed; retry later. Not a malware verdict.
+ *   - `cve_block` / `cve_no_safe_version` — CVE findings listed per package
+ *     (suggested pin vs no safe version). Variant is `cve_block` when any
+ *     finding carries a suggested pin; otherwise `cve_no_safe_version`.
+ *   - `default` — every other combination, including all
+ *     `registry_auth_failed` failures.
+ *
+ * Exported so the matrix can be unit-tested directly without round-tripping
+ * through the AppShell + npm exec mock.
+ */
+export function buildBlockedMessage(err) {
+    const safeHost = err.registryHost
+        ? sanitizeForAgentMessage(err.registryHost)
+        : "";
+    const host = safeHost ? ` (registry: ${safeHost})` : "";
+    const packagesPhrase = err.packages.length > 0
+        ? err.packages.map((p) => `\`${sanitizeForAgentMessage(p)}\``).join(", ")
+        : "the requested package";
+    // Core-package guard (APPS-4527): when the blocked set contains a
+    // protected core dependency (`@superblocksteam/*`, react, react-router,
+    // vite, …), Clark must not "fix" the failure by removing or refactoring
+    // the app away from it — the dev server, bundle builder, and runtime all
+    // require these. The only remediation is mirroring into the registry.
+    const protectedCorePackageGuidance = err.packages.some((p) => isProtectedCorePackage(p))
+        ? ` One or more of these are core app dependencies (\`@superblocksteam/*\` packages, ${PROTECTED_CORE_PACKAGES.join(", ")}). Never suggest uninstalling, replacing, or refactoring the app away from a core dependency; an org admin must make it available in the registry.`
+        : "";
+    // Tri-state: `undefined` means "no client wired in" (test fixtures, judge
+    // runner) and is treated as `true` — there is no escalation path to
+    // recommend if we don't know the deployment has a private-registry seam.
+    const hasRows = err.hasAnyRegistryConfigured !== false;
+    const hostIsPublic = isPublicNpmHost(err.registryHost);
+    const hostIsKnown = !!err.registryHost;
+    const errorCode = err.npmErrorCode;
+    switch (err.reason) {
+        case "not_in_registry": {
+            const privateHostWithRows = hostIsKnown && !hostIsPublic && hasRows;
+            if (privateHostWithRows) {
+                // Private host + rows present: the customer is on a private registry
+                // and this 404 most likely means the package isn't mirrored yet (or
+                // is genuinely missing). Append an actionable escalation pointing at
+                // the org admin without naming the registry URL or any token-bearing
+                // details — non-admin users still get something they can do.
+                return {
+                    variant: "private_mirror_hint",
+                    message: `The npm registry${host} returned 404 for ${packagesPhrase}. This may be a typo, an unpublished package, or a package that has not been mirrored into your private registry. Stop and confirm with the user before trying a different package — and if the package name is correct, an org admin may need to mirror it into your private registry.${protectedCorePackageGuidance}`,
+                };
+            }
+            // Mode-agnostic default: covers SaaS (npmjs → typo / unpublished /
+            // renamed), private host with no rows (degenerate EE ephemeral case),
+            // and unknown host (parser couldn't extract a URL).
+            return {
+                variant: "default",
+                message: `The npm registry${host} returned 404 for ${packagesPhrase}. This may be a typo, an unpublished or renamed package, or — if a private registry is configured — a package that has not been mirrored. Stop and confirm with the user before trying a different package.${protectedCorePackageGuidance}`,
+            };
+        }
+        case "registry_unreachable": {
+            // Escalation hint applies only when (a) we know zero rows are
+            // configured AND (b) the host npm attempted is npmjs.org or unknown
+            // (no host extracted from the error). When the host is a private
+            // registry the customer already has one wired up — telling them to
+            // configure one would be misleading.
+            const hostQualifiesForEscalation = !hostIsKnown || hostIsPublic;
+            const noRowsConfigured = err.hasAnyRegistryConfigured === false;
+            if (hostQualifiesForEscalation && noRowsConfigured) {
+                return {
+                    variant: "unreachable_escalation",
+                    message: `The npm registry${host} could not be reached (${errorCode ?? "network error"}). This may be a temporary outage of npmjs.org, or — if this deployment cannot reach public npm — egress may be blocked. Alternative packages will not help — stop and report this to the user. If this deployment is intended to use a private npm registry, ask an org admin to configure one in Org Settings → Package Registry.`,
+                };
+            }
+            // Subreason-specific hint (APPS-4381): the parser narrows the failure
+            // to dns / network / proxy / timeout where it can, so the operator
+            // gets a directed next step instead of the four-cause grab-bag. The
+            // hint is appended to the existing multi-cause sentence — keeping the
+            // structure stable lets existing model-eval prompts continue matching
+            // on the "could not be reached" / "alternative packages will not help"
+            // anchors that the rest of the test surface pins.
+            const subreasonHint = (() => {
+                switch (err.subreason) {
+                    case "dns":
+                        return " The registry hostname could not be resolved (DNS); the corporate or container DNS resolver may not see this host.";
+                    case "network":
+                        return " The TCP connection was refused or reset; a firewall, egress filter, or routing rule may be blocking the registry.";
+                    case "proxy":
+                        return " An HTTP proxy refused the request; the proxy URL, credentials, or NO_PROXY rules may be misconfigured.";
+                    case "timeout":
+                        return " The request timed out; the network path to the registry is slow or the registry is hung.";
+                    default:
+                        return "";
+                }
+            })();
+            // Revised default: drop the "transient" framing — unreachable can
+            // equally be DNS misconfig, an auth gateway rejecting the request at
+            // the network layer, expired credentials, or a misrouted scope. The
+            // common thread is "alternative packages will not help; surface this
+            // up the stack."
+            return {
+                variant: "default",
+                message: `The npm registry${host} could not be reached (${errorCode ?? "network error"}). This may be a registry outage, a network or auth misconfiguration, expired credentials at the network layer, or a misrouted scope.${subreasonHint} Alternative packages will not help — stop and report the failure to the user.`,
+            };
+        }
+        case "registry_auth_failed":
+            return {
+                variant: "default",
+                message: `The configured npm registry${host} rejected the authentication credentials (${errorCode ?? "auth error"}). This requires an administrator to fix the registry token. Stop and report the failure rather than trying alternative packages.`,
+            };
+        case "tls_failed":
+            return {
+                variant: "default",
+                message: `The TLS handshake with the npm registry${host} failed (${errorCode ?? "TLS error"}). Common causes: an untrusted private CA the registry serves, a self-signed certificate, or an expired certificate. An administrator must install the registry's CA bundle (e.g. via NODE_EXTRA_CA_CERTS or the npm cafile config) or rotate the expired certificate. Alternative packages will not help — stop and report the failure to the user.`,
+            };
+        case "vulnerable_package":
+            return buildVulnerablePackageMessage(err, packagesPhrase);
+    }
+}
+function formatFindingLine(finding) {
+    const pkg = `\`${sanitizeForAgentMessage(finding.package)}\``;
+    const advisoryId = finding.advisoryId
+        ? sanitizeForAgentMessage(finding.advisoryId)
+        : "";
+    const advisoryPhrase = advisoryId ? ` (advisory: ${advisoryId})` : "";
+    if (finding.kind === "malware") {
+        return `- ${pkg} — known malware${advisoryPhrase}`;
+    }
+    if (finding.kind === "index_unavailable") {
+        return `- ${pkg} — could not be security-checked (index/probe unavailable)`;
+    }
+    if (finding.suggestedVersion) {
+        const suggested = sanitizeForAgentMessage(finding.suggestedVersion);
+        return `- ${pkg} — known vulnerability${advisoryPhrase}. A safer version (${suggested}) exists but could not be applied in place`;
+    }
+    return `- ${pkg} — known vulnerability${advisoryPhrase} with no safe version available`;
+}
+function buildVulnerablePackageMessage(err, packagesPhrase) {
+    const findings = err.findings ?? [];
+    const indexUnavailableFindings = findings.filter((finding) => finding.kind === "index_unavailable");
+    if (indexUnavailableFindings.length > 0) {
+        const lines = indexUnavailableFindings.map(formatFindingLine).join("\n");
+        return {
+            variant: "index_unavailable",
+            message: `Security policy could not verify these packages (vulnerability index or install probe unavailable):\n${lines}\nFailing closed. Do not treat this as a malware verdict — retry the install later, or choose a different package if the check keeps failing.`,
+        };
+    }
+    const malwareFindings = findings.filter((finding) => finding.kind === "malware");
+    if (malwareFindings.length > 0) {
+        const lines = malwareFindings.map(formatFindingLine).join("\n");
+        return {
+            variant: "malware_block",
+            message: `Security policy blocked these packages:\n${lines}\nDo not install them or try to work around this block — choose a different reputable package that serves the same purpose.`,
+        };
+    }
+    const cveFindings = findings.filter((finding) => finding.kind === "cve");
+    if (cveFindings.length > 0) {
+        const lines = cveFindings.map(formatFindingLine).join("\n");
+        const hasSuggested = cveFindings.some((finding) => finding.suggestedVersion !== undefined);
+        return {
+            variant: hasSuggested ? "cve_block" : "cve_no_safe_version",
+            message: `Security policy blocked these packages:\n${lines}\nDo not retry the same packages — propose a different reputable package that serves the same purpose, then install it with this tool so it can be re-checked.`,
+        };
+    }
+    return {
+        variant: "cve_no_safe_version",
+        message: `${packagesPhrase} has a known vulnerability with no safe version available. Do not retry the same package — choose a different reputable package that serves the same purpose.`,
+    };
+}
+function detectVersionChanges(packages, currentPackageJson) {
+    if (!currentPackageJson)
+        return [];
+    const changes = [];
+    for (const pkg of packages) {
+        const isDev = pkg.dev ?? false;
+        const currentVersion = isDev
+            ? currentPackageJson.devDependencies?.[pkg.name]
+            : currentPackageJson.dependencies?.[pkg.name];
+        if (currentVersion && pkg.version && currentVersion !== pkg.version) {
+            changes.push({
+                name: pkg.name,
+                oldVersion: currentVersion,
+                newVersion: pkg.version,
+                isDev,
+            });
+        }
+    }
+    return changes;
+}
+function buildSuccessfulSpecificInstallResult(args) {
+    const { output, packages, versionChanges } = args;
+    const packageNames = packages.map((pkg) => pkg.name).join(", ");
+    let message = `Successfully installed packages: ${packageNames}`;
+    if (versionChanges.length > 0) {
+        const changeDetails = versionChanges
+            .map((change) => `  - ${change.name}: ${change.oldVersion} → ${change.newVersion}${change.isDev ? " (dev)" : ""}`)
+            .join("\n");
+        message += `\n\nVersion changes detected:\n${changeDetails}\n\n⚠️  WARNING: Version changes may affect existing components that depend on these packages. Consider checking for breaking changes.`;
+    }
+    return { message, output, versionChanges };
+}
+export const buildInstallPackagesToolFactory = createToolFactory("build_installPackages", ({ clark, services, }) => {
+    return {
+        category: ToolCategory.GENERAL,
+        description: `
+      Install or remove packages using the project's package manager.
+
+      (Recommended) Provide a list of packages to install with optional version and dev flag:
+      - Example: packages: [{name: 'react', version: '18.2.0'}, {name: '@types/react', dev: true}]
+
+      Provide package names in remove to uninstall user packages:
+      - Example: remove: ['react-syntax-highlighter']
+
+      To replace a package safely, provide packages and remove in one call. The replacement is installed before the old package is removed.
+
+      Never remove core app dependencies. These include @superblocksteam/* packages, ${PROTECTED_CORE_PACKAGES.join(", ")}.
+
+      If neither packages nor remove is specified, runs a standard install to update dependencies from package.json.
+
+      This tool checks for existing package versions, warns about version changes as version upgrades may break existing components.
+
+      After a user-requested CVE block (\`userRequested\` on the tool result), ask the builder for a short reason and retry with \`proceedWithReason\` set to that reason. Never invent a proceed reason.
+    `,
+        getActionName: (input) => {
+            if (input?.proceedWithReason) {
+                return {
+                    future: "Install blocked package with builder approval",
+                    past: "Installed blocked package with builder approval",
+                    present: "Installing blocked package with builder approval",
+                };
+            }
+            if (input?.remove?.length && !input?.packages?.length) {
+                return {
+                    future: "Remove packages",
+                    past: "Removed packages",
+                    present: "Removing packages",
+                };
+            }
+            if (input?.remove?.length) {
+                return {
+                    future: "Install and remove packages",
+                    past: "Installed and removed packages",
+                    present: "Installing and removing packages",
+                };
+            }
+            return {
+                future: "Install packages",
+                past: "Installed packages",
+                present: "Installing packages",
+            };
+        },
+        formatInput: (input) => {
+            const packages = input.packages;
+            const proceedWithReason = input.proceedWithReason;
+            const packageNames = (packages ?? []).map((pkg) => pkg.name);
+            if (!proceedWithReason) {
+                return {
+                    targets: [...packageNames, ...(input.remove ?? [])],
+                };
+            }
+            const triggeringMessage = services.chatSessionStore?.getLastUserMessage()?.content ?? "";
+            const namedByBuilder = resolveUserRequestedPackageNames(packages ?? [], triggeringMessage, clark.context.pendingCveProceedPackages ?? []);
+            const safeReason = sanitizeForAgentMessage(proceedWithReason.slice(0, PROCEED_WITH_REASON_MAX_LENGTH));
+            const namedPhrase = namedByBuilder.length > 0
+                ? `The builder named ${namedByBuilder.map((name) => `\`${sanitizeForAgentMessage(name)}\``).join(", ")}`
+                : "The builder provided a proceed reason for a security-blocked install";
+            return {
+                details: `Reason: ${safeReason}`,
+                summary: `Install security-blocked package(s) anyway? ${namedPhrase}.`,
+                targets: namedByBuilder.length > 0 ? namedByBuilder : packageNames,
+            };
+        },
+        inputSchema: z.object({
+            packages: z
+                .array(z.object({
+                name: z
+                    .string()
+                    .refine(isValidNpmPackageName, "must be a valid npm package name with no version suffix; put the version in 'version'")
+                    .describe("Package name (e.g., 'react', '@types/node', 'lodash')"),
+                version: z
+                    .string()
+                    .refine(isValidNpmVersionSpec, "must be a semver range or dist-tag with no shell metacharacters")
+                    .optional()
+                    .describe("Version specifier (e.g., '18.2.0', '^18.0.0', 'latest'). Defaults to 'latest' if not specified"),
+                dev: z
+                    .boolean()
+                    .optional()
+                    .describe("Install as dev dependency (--save-dev). Defaults to false"),
+            }))
+                .optional()
+                .describe("Packages to install. If not provided or empty, runs a standard install to update dependencies from package.json"),
+            remove: z
+                .array(z
+                .string()
+                .refine(isValidNpmPackageName, "Invalid npm package name"))
+                .optional()
+                .describe("Package names to uninstall"),
+            proceedWithReason: z
+                .string()
+                .max(PROCEED_WITH_REASON_MAX_LENGTH)
+                .optional()
+                .describe("Builder-provided reason to proceed past a user-requested CVE block. Only set after the builder named the package and confirmed; triggers a confirmation prompt."),
+        }),
+        execute: async ({ packages, proceedWithReason, remove, }) => {
+            let versionChanges = [];
+            const triggeringMessage = services.chatSessionStore?.getLastUserMessage()?.content ?? "";
+            const userRequested = packages && packages.length > 0
+                ? resolveUserRequestedPackageNames(packages, triggeringMessage, clark.context.pendingCveProceedPackages ?? [])
+                : [];
+            const trimmedProceedReason = proceedWithReason?.trim() ?? "";
+            const overridePackages = trimmedProceedReason.length > 0 ? userRequested : [];
+            const cveUserOverride = overridePackages.length > 0
+                ? {
+                    packages: overridePackages,
+                    reason: trimmedProceedReason.slice(0, PROCEED_WITH_REASON_MAX_LENGTH),
+                }
+                : undefined;
+            /** Spend the one-shot proceed approval once the install actually
+             *  lands. Spending it on a failed attempt instead would strand the
+             *  builder — their next reply is a bare "yes, go ahead" that never
+             *  repeats the package name. Auditing the override belongs to the
+             *  install gate, which knows whether it was the override that let the
+             *  install through. */
+            const spendProceedApproval = () => {
+                if (!cveUserOverride)
+                    return;
+                clark.updateContext({ pendingCveProceedPackages: undefined });
+            };
+            const protectedRequested = (remove ?? []).filter((name) => isProtectedCorePackage(name));
+            if (protectedRequested.length > 0) {
+                return {
+                    message: `Cannot remove protected core packages: ${protectedRequested.join(", ")}. These packages are required to serve, build, or run the app.`,
+                    ok: false,
+                };
+            }
+            try {
+                // create draft marker for package.json
+                await services.draftInterface.createDraftMarkerOnly("package.json");
+                let output;
+                if (packages && packages.length > 0) {
+                    const currentPackageJson = await readPackageJson(services.appShell.appRootDirPath);
+                    versionChanges = detectVersionChanges(packages, currentPackageJson);
+                    if (trimmedProceedReason.length > 0 &&
+                        overridePackages.length === 0) {
+                        return {
+                            message: "proceedWithReason was set, but the builder never named any of these packages. Only packages the builder asked for by name can proceed past a CVE block.",
+                            ok: false,
+                            userRequested,
+                        };
+                    }
+                    // Mode 1: Install specific packages
+                    output = await services.appShell.installSpecificPackages(packages, clark.context.abortController?.signal, ...(cveUserOverride ? [{ cveUserOverride }] : []));
+                    const installResult = buildSuccessfulSpecificInstallResult({
+                        output,
+                        packages,
+                        versionChanges,
+                    });
+                    if (!remove || remove.length === 0) {
+                        spendProceedApproval();
+                        return installResult;
+                    }
+                    try {
+                        const uninstallResult = await services.appShell.uninstallPackages(remove, {
+                            abortSignal: clark.context.abortController?.signal,
+                        });
+                        spendProceedApproval();
+                        return {
+                            ...installResult,
+                            message: `${installResult.message}\nSuccessfully removed packages: ${remove.join(", ")}`,
+                            output: [installResult.output, uninstallResult.stdout]
+                                .filter(Boolean)
+                                .join("\n"),
+                        };
+                    }
+                    catch (uninstallError) {
+                        const failDetail = sanitizeForAgentMessage(scrubSecrets(uninstallError instanceof Error
+                            ? uninstallError.message
+                            : "unknown error"));
+                        return {
+                            ok: false,
+                            message: `${installResult.message}\nFailed to remove packages: ${remove.join(", ")}. ${failDetail}`,
+                            output: installResult.output,
+                            versionChanges: installResult.versionChanges,
+                            ...(uninstallError instanceof NpmInstallBlocked
+                                ? {
+                                    error: boundFindingsForAgent(uninstallError.toJSON()),
+                                }
+                                : {}),
+                        };
+                    }
+                }
+                else if (remove && remove.length > 0) {
+                    const result = await services.appShell.uninstallPackages(remove, {
+                        abortSignal: clark.context.abortController?.signal,
+                    });
+                    return {
+                        message: `Successfully removed packages: ${remove.join(", ")}`,
+                        output: result.stdout,
+                    };
+                }
+                else {
+                    // Mode 2: Install from package.json
+                    output = await services.appShell.runPackageManagerInstall(clark.context.abortController?.signal);
+                    return {
+                        output,
+                        message: `Successfully ran package manager install command`,
+                    };
+                }
+            }
+            catch (error) {
+                // Surface registry-blocked failures as a structured tool result so
+                // the agent can reason about the reason (404 vs auth vs network)
+                // on the same conversation turn, instead of letting the error
+                // bubble up to agent-planning's POST_PROCESSING_ERRORED branch
+                // (which only emits a raw stderr `debug()` message).
+                if (error instanceof NpmInstallBlocked) {
+                    let triageVerdicts;
+                    const cveFindings = error.findings?.filter((finding) => finding.kind === "cve");
+                    if (packages?.length && cveFindings?.length) {
+                        triageVerdicts = await triageCveFindings({
+                            abortSignal: clark.context.abortController?.signal,
+                            findings: cveFindings,
+                            services,
+                        });
+                        for (const verdict of triageVerdicts) {
+                            services.appShell.reportNpmTriageVerdict(verdict);
+                        }
+                    }
+                    // `warn` (not `info`) because operators want this to surface in
+                    // standard `level>=warn` alert queries: a blocked install is a
+                    // handled, recoverable condition (the agent gets structured
+                    // guidance) but operationally important to track. `error` would
+                    // overstate severity since the agent loop is not crashing, and
+                    // would force the strict `ErrorMeta` shape that drops the
+                    // structured `toJSON()` payload operators actually want to
+                    // facet on. Per APPS-4179 AC this is the single log line for
+                    // the structured error.
+                    //
+                    // `messageVariant` joins the toJSON projection so a downstream
+                    // Datadog/Loki facet can distinguish the row-aware branches
+                    // (`private_mirror_hint`, `unreachable_escalation`) from the
+                    // default advice without re-deriving the matrix from the raw
+                    // inputs. AppShell.classifyNpmExecError emits the same data
+                    // points as llmobs span tags; the warn log is the structured
+                    // counterpart that survives outside of trace sampling.
+                    const { message, variant } = buildBlockedMessage(error);
+                    const findings = error.findings ?? [];
+                    const hasMalwareFinding = findings.some((finding) => finding.kind === "malware");
+                    const cveUserRequested = userRequested.filter((name) => findings.some((finding) => finding.kind === "cve" &&
+                        (finding.package === name ||
+                            finding.package.startsWith(`${name}@`))));
+                    const canProceed = cveUserRequested.length > 0 && !hasMalwareFinding;
+                    const userRequestedGuidance = canProceed
+                        ? `\n\nuserRequested packages: ${cveUserRequested.map((name) => `\`${sanitizeForAgentMessage(name)}\``).join(", ")}. The builder asked for these by name. Warn them, ask for a short proceed reason if they still want the install, then retry this tool with \`proceedWithReason\` set to that reason.`
+                        : "";
+                    if (canProceed) {
+                        // The builder's answer lands on a later turn and won't repeat the
+                        // package name, so remember which names they may proceed with.
+                        clark.updateContext({
+                            pendingCveProceedPackages: cveUserRequested,
+                        });
+                    }
+                    getLogger().warn("Install blocked by registry condition", {
+                        ...error.toJSON(),
+                        messageVariant: variant,
+                        ...(triageVerdicts ? { triageVerdicts } : {}),
+                        ...(cveUserRequested.length > 0
+                            ? { userRequested: cveUserRequested }
+                            : {}),
+                    });
+                    return {
+                        ok: false,
+                        error: boundFindingsForAgent(error.toJSON()),
+                        message: `${message}${userRequestedGuidance}`,
+                        ...(triageVerdicts ? { triageVerdicts } : {}),
+                        ...(cveUserRequested.length > 0
+                            ? { userRequested: cveUserRequested }
+                            : {}),
+                    };
+                }
+                getLogger().error("Error installing packages", getErrorMeta(error));
+                throw error;
+            }
+        },
+        getSummary: (input, output) => {
+            // Blocked-install result is the failure path: surface the reason
+            // instead of pretending the install succeeded. Keyed on `ok` alone —
+            // the proceed-rejection path fails before npm runs, so it carries no
+            // structured `error` to read a reason from.
+            if (output?.ok === false) {
+                // Install landed and uninstall did not: Clark must not retry the add.
+                if (input.packages?.length &&
+                    input.remove?.length &&
+                    output.output !== undefined) {
+                    const names = input.packages.map((p) => p.name).join(", ");
+                    const reason = output.error?.reason;
+                    return {
+                        input: `${input.packages.length} package${input.packages.length === 1 ? "" : "s"}: ${names}`,
+                        output: reason
+                            ? `Installed, remove failed: ${reason}`
+                            : "Installed, remove failed",
+                    };
+                }
+                const blockedOutput = `Blocked: ${output.error?.reason ?? "install not attempted"}`;
+                // Mirror the success branch: omit the `input` field on the no-args
+                // install path (runPackageManagerInstall) so the summary doesn't
+                // render `"0 packages: "` with a dangling colon.
+                if (input.packages && input.packages.length > 0) {
+                    const names = input.packages.map((p) => p.name).join(", ");
+                    return {
+                        input: `${input.packages.length} package${input.packages.length === 1 ? "" : "s"}: ${names}`,
+                        output: blockedOutput,
+                    };
+                }
+                if (input.remove && input.remove.length > 0) {
+                    return {
+                        input: `${input.remove.length} package${input.remove.length === 1 ? "" : "s"}: ${input.remove.join(", ")}`,
+                        output: blockedOutput,
+                    };
+                }
+                return {
+                    output: blockedOutput,
+                };
+            }
+            if (input.packages && input.packages.length > 0) {
+                const names = input.packages.map((p) => p.name).join(", ");
+                const versionWarning = output.versionChanges?.length
+                    ? ` (${output.versionChanges.length} version change${output.versionChanges.length === 1 ? "" : "s"})`
+                    : "";
+                return {
+                    input: `${input.packages.length} package${input.packages.length === 1 ? "" : "s"}: ${names}`,
+                    output: input.remove?.length
+                        ? `Installed${versionWarning}, removed ${input.remove.length}`
+                        : `Installed${versionWarning}`,
+                };
+            }
+            if (input.remove && input.remove.length > 0) {
+                return {
+                    input: `${input.remove.length} package${input.remove.length === 1 ? "" : "s"}: ${input.remove.join(", ")}`,
+                    output: "Removed",
+                };
+            }
+            return {
+                output: "Dependencies updated",
+            };
+        },
+    };
+});
+//# sourceMappingURL=build-install-packages.js.map