@penclipai/adapter-utils 2026.401.0-canary.0

package/dist/server-utils.js

@@ -0,0 +1,744 @@
+import { spawn } from "node:child_process";
+import { constants as fsConstants, promises as fs } from "node:fs";
+import path from "node:path";
+export const runningProcesses = new Map();
+export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
+export const MAX_EXCERPT_BYTES = 32 * 1024;
+const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
+const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
+    "../../skills",
+    "../../../../../skills",
+];
+const BUNDLED_PAPERCLIP_SKILL_KEY_PREFIX = "penclipai/paperclip-cn/";
+const LEGACY_BUNDLED_PAPERCLIP_SKILL_KEY_PREFIXES = [
+    "paperclipai/paperclip/",
+    "penclipai/paperclip/",
+];
+function canonicalizeBundledPaperclipSkillKey(value) {
+    if (!value)
+        return null;
+    const trimmed = value.trim();
+    if (!trimmed)
+        return null;
+    if (trimmed.startsWith(BUNDLED_PAPERCLIP_SKILL_KEY_PREFIX))
+        return trimmed;
+    for (const legacyPrefix of LEGACY_BUNDLED_PAPERCLIP_SKILL_KEY_PREFIXES) {
+        if (trimmed.startsWith(legacyPrefix)) {
+            return `${BUNDLED_PAPERCLIP_SKILL_KEY_PREFIX}${trimmed.slice(legacyPrefix.length)}`;
+        }
+    }
+    return trimmed;
+}
+function normalizePathSlashes(value) {
+    return value.replaceAll("\\", "/");
+}
+function isMaintainerOnlySkillTarget(candidate) {
+    return normalizePathSlashes(candidate).includes("/.agents/skills/");
+}
+function skillLocationLabel(value) {
+    if (typeof value !== "string")
+        return null;
+    const trimmed = value.trim();
+    return trimmed.length > 0 ? trimmed : null;
+}
+function buildManagedSkillOrigin(entry) {
+    if (entry.required) {
+        return {
+            origin: "paperclip_required",
+            originLabel: "Required by Paperclip",
+            readOnly: false,
+        };
+    }
+    return {
+        origin: "company_managed",
+        originLabel: "Managed by Paperclip",
+        readOnly: false,
+    };
+}
+function resolveInstalledEntryTarget(skillsHome, entryName, dirent, linkedPath) {
+    const fullPath = path.join(skillsHome, entryName);
+    if (dirent.isSymbolicLink()) {
+        return {
+            targetPath: linkedPath ? path.resolve(path.dirname(fullPath), linkedPath) : null,
+            kind: "symlink",
+        };
+    }
+    if (dirent.isDirectory()) {
+        return { targetPath: fullPath, kind: "directory" };
+    }
+    return { targetPath: fullPath, kind: "file" };
+}
+export function parseObject(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return {};
+    }
+    return value;
+}
+export function asString(value, fallback) {
+    return typeof value === "string" && value.length > 0 ? value : fallback;
+}
+export function asNumber(value, fallback) {
+    return typeof value === "number" && Number.isFinite(value) ? value : fallback;
+}
+export function asBoolean(value, fallback) {
+    return typeof value === "boolean" ? value : fallback;
+}
+export function asStringArray(value) {
+    return Array.isArray(value) ? value.filter((item) => typeof item === "string") : [];
+}
+export function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+export function appendWithCap(prev, chunk, cap = MAX_CAPTURE_BYTES) {
+    const combined = prev + chunk;
+    return combined.length > cap ? combined.slice(combined.length - cap) : combined;
+}
+export function resolvePathValue(obj, dottedPath) {
+    const parts = dottedPath.split(".");
+    let cursor = obj;
+    for (const part of parts) {
+        if (typeof cursor !== "object" || cursor === null || Array.isArray(cursor)) {
+            return "";
+        }
+        cursor = cursor[part];
+    }
+    if (cursor === null || cursor === undefined)
+        return "";
+    if (typeof cursor === "string")
+        return cursor;
+    if (typeof cursor === "number" || typeof cursor === "boolean")
+        return String(cursor);
+    try {
+        return JSON.stringify(cursor);
+    }
+    catch {
+        return "";
+    }
+}
+export function renderTemplate(template, data) {
+    return template.replace(/{{\s*([a-zA-Z0-9_.-]+)\s*}}/g, (_, path) => resolvePathValue(data, path));
+}
+export function joinPromptSections(sections, separator = "\n\n") {
+    return sections
+        .map((value) => (typeof value === "string" ? value.trim() : ""))
+        .filter(Boolean)
+        .join(separator);
+}
+export function redactEnvForLogs(env) {
+    const redacted = {};
+    for (const [key, value] of Object.entries(env)) {
+        redacted[key] = SENSITIVE_ENV_KEY.test(key) ? "***REDACTED***" : value;
+    }
+    return redacted;
+}
+export function buildInvocationEnvForLogs(env, options = {}) {
+    const merged = { ...env };
+    const runtimeEnv = options.runtimeEnv ?? {};
+    for (const key of options.includeRuntimeKeys ?? []) {
+        if (key in merged)
+            continue;
+        const value = runtimeEnv[key];
+        if (typeof value !== "string" || value.length === 0)
+            continue;
+        merged[key] = value;
+    }
+    const resolvedCommand = options.resolvedCommand?.trim();
+    if (resolvedCommand) {
+        merged[options.resolvedCommandEnvKey ?? "PAPERCLIP_RESOLVED_COMMAND"] = resolvedCommand;
+    }
+    return redactEnvForLogs(merged);
+}
+export function buildPaperclipEnv(agent) {
+    const resolveHostForUrl = (rawHost) => {
+        const host = rawHost.trim();
+        if (!host || host === "0.0.0.0" || host === "::")
+            return "localhost";
+        if (host.includes(":") && !host.startsWith("[") && !host.endsWith("]"))
+            return `[${host}]`;
+        return host;
+    };
+    const vars = {
+        PAPERCLIP_AGENT_ID: agent.id,
+        PAPERCLIP_COMPANY_ID: agent.companyId,
+    };
+    const runtimeHost = resolveHostForUrl(process.env.PAPERCLIP_LISTEN_HOST ?? process.env.HOST ?? "localhost");
+    const runtimePort = process.env.PAPERCLIP_LISTEN_PORT ?? process.env.PORT ?? "3100";
+    const apiUrl = process.env.PAPERCLIP_API_URL ?? `http://${runtimeHost}:${runtimePort}`;
+    vars.PAPERCLIP_API_URL = apiUrl;
+    return vars;
+}
+export function defaultPathForPlatform() {
+    if (process.platform === "win32") {
+        return "C:\\Windows\\System32;C:\\Windows;C:\\Windows\\System32\\Wbem";
+    }
+    return "/usr/local/bin:/opt/homebrew/bin:/usr/local/sbin:/usr/bin:/bin:/usr/sbin:/sbin";
+}
+function windowsPathExts(env) {
+    return (env.PATHEXT ?? ".EXE;.CMD;.BAT;.COM").split(";").filter(Boolean);
+}
+async function pathExists(candidate) {
+    try {
+        await fs.access(candidate, process.platform === "win32" ? fsConstants.F_OK : fsConstants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function resolveCommandPath(command, cwd, env) {
+    const hasPathSeparator = command.includes("/") || command.includes("\\");
+    if (hasPathSeparator) {
+        const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+        return (await pathExists(absolute)) ? absolute : null;
+    }
+    const pathValue = env.PATH ?? env.Path ?? "";
+    const delimiter = process.platform === "win32" ? ";" : ":";
+    const dirs = pathValue.split(delimiter).filter(Boolean);
+    const exts = process.platform === "win32" ? windowsPathExts(env) : [""];
+    const hasExtension = process.platform === "win32" && path.extname(command).length > 0;
+    for (const dir of dirs) {
+        const candidates = process.platform === "win32"
+            ? hasExtension
+                ? [path.join(dir, command)]
+                : [...exts.map((ext) => path.join(dir, `${command}${ext}`)), path.join(dir, command)]
+            : [path.join(dir, command)];
+        for (const candidate of candidates) {
+            if (await pathExists(candidate))
+                return candidate;
+        }
+    }
+    return null;
+}
+export async function resolveCommandForLogs(command, cwd, env) {
+    return (await resolveCommandPath(command, cwd, env)) ?? command;
+}
+function quoteForCmd(arg) {
+    if (!arg.length)
+        return '""';
+    const escaped = arg.replace(/"/g, '""');
+    return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
+}
+async function readShebangTokens(executable) {
+    try {
+        const handle = await fs.open(executable, "r");
+        try {
+            const buffer = Buffer.alloc(512);
+            const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+            const firstLine = buffer.toString("utf8", 0, bytesRead).split(/\r?\n/u, 1)[0]?.trim() ?? "";
+            if (!firstLine.startsWith("#!"))
+                return null;
+            const shebang = firstLine.slice(2).trim();
+            return shebang ? shebang.split(/\s+/u).filter(Boolean) : null;
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    catch {
+        return null;
+    }
+}
+async function resolveShebangSpawnTarget(executable, cwd, env) {
+    const tokens = await readShebangTokens(executable);
+    if (!tokens || tokens.length === 0)
+        return null;
+    let [interpreter, ...interpreterArgs] = tokens;
+    const interpreterBase = path.posix.basename(interpreter).toLowerCase();
+    if (interpreterBase === "env" || interpreterBase === "env.exe") {
+        if (interpreterArgs[0] === "-S")
+            interpreterArgs = interpreterArgs.slice(1);
+        interpreter = interpreterArgs.shift() ?? "";
+    }
+    const normalizedBase = path.posix.basename(interpreter).toLowerCase().replace(/\.exe$/u, "");
+    const resolvedInterpreter = normalizedBase === "node"
+        ? process.execPath
+        : normalizedBase === "sh"
+            ? await resolveCommandPath("bash", cwd, env)
+            : normalizedBase
+                ? await resolveCommandPath(normalizedBase, cwd, env)
+                : null;
+    if (!resolvedInterpreter)
+        return null;
+    return {
+        command: resolvedInterpreter,
+        args: [...interpreterArgs, executable],
+    };
+}
+async function resolveSpawnTarget(command, args, cwd, env) {
+    const resolved = await resolveCommandPath(command, cwd, env);
+    const executable = resolved ?? command;
+    if (process.platform !== "win32") {
+        return { command: executable, args };
+    }
+    if (/\.(cmd|bat)$/i.test(executable)) {
+        const shell = env.ComSpec || process.env.ComSpec || "cmd.exe";
+        const commandLine = [quoteForCmd(executable), ...args.map(quoteForCmd)].join(" ");
+        return {
+            command: shell,
+            args: ["/d", "/s", "/c", commandLine],
+        };
+    }
+    const shebangTarget = await resolveShebangSpawnTarget(executable, cwd, env);
+    if (shebangTarget) {
+        return {
+            command: shebangTarget.command,
+            args: [...shebangTarget.args, ...args],
+        };
+    }
+    return { command: executable, args };
+}
+export function ensurePathInEnv(env) {
+    if (typeof env.PATH === "string" && env.PATH.length > 0)
+        return env;
+    if (typeof env.Path === "string" && env.Path.length > 0)
+        return env;
+    return { ...env, PATH: defaultPathForPlatform() };
+}
+export async function ensureAbsoluteDirectory(cwd, opts = {}) {
+    if (!path.isAbsolute(cwd)) {
+        throw new Error(`Working directory must be an absolute path: "${cwd}"`);
+    }
+    const assertDirectory = async () => {
+        const stats = await fs.stat(cwd);
+        if (!stats.isDirectory()) {
+            throw new Error(`Working directory is not a directory: "${cwd}"`);
+        }
+    };
+    try {
+        await assertDirectory();
+        return;
+    }
+    catch (err) {
+        const code = err.code;
+        if (!opts.createIfMissing || code !== "ENOENT") {
+            if (code === "ENOENT") {
+                throw new Error(`Working directory does not exist: "${cwd}"`);
+            }
+            throw err instanceof Error ? err : new Error(String(err));
+        }
+    }
+    try {
+        await fs.mkdir(cwd, { recursive: true });
+        await assertDirectory();
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not create working directory "${cwd}": ${reason}`);
+    }
+}
+export async function resolvePaperclipSkillsDir(moduleDir, additionalCandidates = []) {
+    const candidates = [
+        ...PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES.map((relativePath) => path.resolve(moduleDir, relativePath)),
+        ...additionalCandidates.map((candidate) => path.resolve(candidate)),
+    ];
+    const seenRoots = new Set();
+    for (const root of candidates) {
+        if (seenRoots.has(root))
+            continue;
+        seenRoots.add(root);
+        const isDirectory = await fs.stat(root).then((stats) => stats.isDirectory()).catch(() => false);
+        if (isDirectory)
+            return root;
+    }
+    return null;
+}
+export async function listPaperclipSkillEntries(moduleDir, additionalCandidates = []) {
+    const root = await resolvePaperclipSkillsDir(moduleDir, additionalCandidates);
+    if (!root)
+        return [];
+    try {
+        const entries = await fs.readdir(root, { withFileTypes: true });
+        return entries
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => ({
+            key: `${BUNDLED_PAPERCLIP_SKILL_KEY_PREFIX}${entry.name}`,
+            runtimeName: entry.name,
+            source: path.join(root, entry.name),
+            required: true,
+            requiredReason: "Bundled Paperclip skills are always available for local adapters.",
+        }));
+    }
+    catch {
+        return [];
+    }
+}
+export async function readInstalledSkillTargets(skillsHome) {
+    const entries = await fs.readdir(skillsHome, { withFileTypes: true }).catch(() => []);
+    const out = new Map();
+    for (const entry of entries) {
+        const fullPath = path.join(skillsHome, entry.name);
+        const linkedPath = entry.isSymbolicLink() ? await fs.readlink(fullPath).catch(() => null) : null;
+        out.set(entry.name, resolveInstalledEntryTarget(skillsHome, entry.name, entry, linkedPath));
+    }
+    return out;
+}
+export function buildPersistentSkillSnapshot(options) {
+    const { adapterType, availableEntries, desiredSkills, installed, skillsHome, locationLabel, installedDetail, missingDetail, externalConflictDetail, externalDetail, } = options;
+    const canonicalDesiredSkills = Array.from(new Set(desiredSkills
+        .map((desiredSkill) => canonicalizeBundledPaperclipSkillKey(desiredSkill))
+        .filter((desiredSkill) => Boolean(desiredSkill))));
+    const availableByKey = new Map(availableEntries.flatMap((entry) => {
+        const canonicalKey = canonicalizeBundledPaperclipSkillKey(entry.key) ?? entry.key;
+        return canonicalKey === entry.key
+            ? [[entry.key, entry]]
+            : [[entry.key, entry], [canonicalKey, entry]];
+    }));
+    const desiredSet = new Set(canonicalDesiredSkills);
+    const entries = [];
+    const warnings = [...(options.warnings ?? [])];
+    for (const available of availableEntries) {
+        const installedEntry = installed.get(available.runtimeName) ?? null;
+        const desired = desiredSet.has(canonicalizeBundledPaperclipSkillKey(available.key) ?? available.key);
+        let state = "available";
+        let managed = false;
+        let detail = null;
+        if (installedEntry?.targetPath === available.source) {
+            managed = true;
+            state = desired ? "installed" : "stale";
+            detail = installedDetail ?? null;
+        }
+        else if (installedEntry) {
+            state = "external";
+            detail = desired ? externalConflictDetail : externalDetail;
+        }
+        else if (desired) {
+            state = "missing";
+            detail = missingDetail;
+        }
+        entries.push({
+            key: available.key,
+            runtimeName: available.runtimeName,
+            desired,
+            managed,
+            state,
+            sourcePath: available.source,
+            targetPath: path.join(skillsHome, available.runtimeName),
+            detail,
+            required: Boolean(available.required),
+            requiredReason: available.requiredReason ?? null,
+            ...buildManagedSkillOrigin(available),
+        });
+    }
+    for (const desiredSkill of canonicalDesiredSkills) {
+        if (availableByKey.has(desiredSkill))
+            continue;
+        warnings.push(`Desired skill "${desiredSkill}" is not available from the Paperclip skills directory.`);
+        entries.push({
+            key: desiredSkill,
+            runtimeName: null,
+            desired: true,
+            managed: true,
+            state: "missing",
+            sourcePath: null,
+            targetPath: null,
+            detail: "Paperclip cannot find this skill in the local runtime skills directory.",
+            origin: "external_unknown",
+            originLabel: "External or unavailable",
+            readOnly: false,
+        });
+    }
+    for (const [name, installedEntry] of installed.entries()) {
+        if (availableEntries.some((entry) => entry.runtimeName === name))
+            continue;
+        entries.push({
+            key: name,
+            runtimeName: name,
+            desired: false,
+            managed: false,
+            state: "external",
+            origin: "user_installed",
+            originLabel: "User-installed",
+            locationLabel: skillLocationLabel(locationLabel),
+            readOnly: true,
+            sourcePath: null,
+            targetPath: installedEntry.targetPath ?? path.join(skillsHome, name),
+            detail: externalDetail,
+        });
+    }
+    entries.sort((left, right) => left.key.localeCompare(right.key));
+    return {
+        adapterType,
+        supported: true,
+        mode: "persistent",
+        desiredSkills: canonicalDesiredSkills,
+        entries,
+        warnings,
+    };
+}
+function normalizeConfiguredPaperclipRuntimeSkills(value) {
+    if (!Array.isArray(value))
+        return [];
+    const out = [];
+    for (const rawEntry of value) {
+        const entry = parseObject(rawEntry);
+        const key = canonicalizeBundledPaperclipSkillKey(asString(entry.key, asString(entry.name, ""))) ?? "";
+        const runtimeName = asString(entry.runtimeName, asString(entry.name, "")).trim();
+        const source = asString(entry.source, "").trim();
+        if (!key || !runtimeName || !source)
+            continue;
+        out.push({
+            key,
+            runtimeName,
+            source,
+            required: asBoolean(entry.required, false),
+            requiredReason: typeof entry.requiredReason === "string" && entry.requiredReason.trim().length > 0
+                ? entry.requiredReason.trim()
+                : null,
+        });
+    }
+    return out;
+}
+export async function readPaperclipRuntimeSkillEntries(config, moduleDir, additionalCandidates = []) {
+    const configuredEntries = normalizeConfiguredPaperclipRuntimeSkills(config.paperclipRuntimeSkills);
+    if (configuredEntries.length > 0)
+        return configuredEntries;
+    return listPaperclipSkillEntries(moduleDir, additionalCandidates);
+}
+export async function readPaperclipSkillMarkdown(moduleDir, skillKey) {
+    const normalized = skillKey.trim().toLowerCase();
+    if (!normalized)
+        return null;
+    const entries = await listPaperclipSkillEntries(moduleDir);
+    const match = entries.find((entry) => entry.key === normalized);
+    if (!match)
+        return null;
+    try {
+        return await fs.readFile(path.join(match.source, "SKILL.md"), "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function readPaperclipSkillSyncPreference(config) {
+    const raw = config.paperclipSkillSync;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+        return { explicit: false, desiredSkills: [] };
+    }
+    const syncConfig = raw;
+    const desiredValues = syncConfig.desiredSkills;
+    const desired = Array.isArray(desiredValues)
+        ? desiredValues
+            .filter((value) => typeof value === "string")
+            .map((value) => value.trim())
+            .filter(Boolean)
+        : [];
+    return {
+        explicit: Object.prototype.hasOwnProperty.call(raw, "desiredSkills"),
+        desiredSkills: Array.from(new Set(desired)),
+    };
+}
+function canonicalizeDesiredPaperclipSkillReference(reference, availableEntries) {
+    const normalizedReference = reference.trim().toLowerCase();
+    if (!normalizedReference)
+        return "";
+    const canonicalBundledReference = canonicalizeBundledPaperclipSkillKey(normalizedReference);
+    if (canonicalBundledReference) {
+        const exactCanonicalKey = availableEntries.find((entry) => entry.key.trim().toLowerCase() === canonicalBundledReference);
+        if (exactCanonicalKey)
+            return exactCanonicalKey.key;
+    }
+    const exactKey = availableEntries.find((entry) => entry.key.trim().toLowerCase() === normalizedReference);
+    if (exactKey)
+        return exactKey.key;
+    const byRuntimeName = availableEntries.filter((entry) => typeof entry.runtimeName === "string" && entry.runtimeName.trim().toLowerCase() === normalizedReference);
+    if (byRuntimeName.length === 1)
+        return byRuntimeName[0].key;
+    const slugMatches = availableEntries.filter((entry) => entry.key.trim().toLowerCase().split("/").pop() === normalizedReference);
+    if (slugMatches.length === 1)
+        return slugMatches[0].key;
+    return canonicalBundledReference ?? normalizedReference;
+}
+export function resolvePaperclipDesiredSkillNames(config, availableEntries) {
+    const preference = readPaperclipSkillSyncPreference(config);
+    const requiredSkills = availableEntries
+        .filter((entry) => entry.required)
+        .map((entry) => entry.key);
+    if (!preference.explicit) {
+        return Array.from(new Set(requiredSkills));
+    }
+    const desiredSkills = preference.desiredSkills
+        .map((reference) => canonicalizeDesiredPaperclipSkillReference(reference, availableEntries))
+        .filter(Boolean);
+    return Array.from(new Set([...requiredSkills, ...desiredSkills]));
+}
+export function writePaperclipSkillSyncPreference(config, desiredSkills) {
+    const next = { ...config };
+    const raw = next.paperclipSkillSync;
+    const current = typeof raw === "object" && raw !== null && !Array.isArray(raw)
+        ? { ...raw }
+        : {};
+    current.desiredSkills = Array.from(new Set(desiredSkills
+        .map((value) => value.trim())
+        .filter(Boolean)));
+    next.paperclipSkillSync = current;
+    return next;
+}
+export async function ensurePaperclipSkillSymlink(source, target, linkSkill = (linkSource, linkTarget) => fs.symlink(linkSource, linkTarget)) {
+    const existing = await fs.lstat(target).catch(() => null);
+    if (!existing) {
+        await linkSkill(source, target);
+        return "created";
+    }
+    if (!existing.isSymbolicLink()) {
+        return "skipped";
+    }
+    const linkedPath = await fs.readlink(target).catch(() => null);
+    if (!linkedPath)
+        return "skipped";
+    const resolvedLinkedPath = path.resolve(path.dirname(target), linkedPath);
+    if (resolvedLinkedPath === source) {
+        return "skipped";
+    }
+    const linkedPathExists = await fs.stat(resolvedLinkedPath).then(() => true).catch(() => false);
+    if (linkedPathExists) {
+        return "skipped";
+    }
+    await fs.unlink(target);
+    await linkSkill(source, target);
+    return "repaired";
+}
+export async function removeMaintainerOnlySkillSymlinks(skillsHome, allowedSkillNames) {
+    const allowed = new Set(Array.from(allowedSkillNames));
+    try {
+        const entries = await fs.readdir(skillsHome, { withFileTypes: true });
+        const removed = [];
+        for (const entry of entries) {
+            if (allowed.has(entry.name))
+                continue;
+            const target = path.join(skillsHome, entry.name);
+            const existing = await fs.lstat(target).catch(() => null);
+            if (!existing?.isSymbolicLink())
+                continue;
+            const linkedPath = await fs.readlink(target).catch(() => null);
+            if (!linkedPath)
+                continue;
+            const resolvedLinkedPath = path.isAbsolute(linkedPath)
+                ? linkedPath
+                : path.resolve(path.dirname(target), linkedPath);
+            if (!isMaintainerOnlySkillTarget(linkedPath) &&
+                !isMaintainerOnlySkillTarget(resolvedLinkedPath)) {
+                continue;
+            }
+            await fs.unlink(target);
+            removed.push(entry.name);
+        }
+        return removed;
+    }
+    catch {
+        return [];
+    }
+}
+export async function ensureCommandResolvable(command, cwd, env) {
+    const resolved = await resolveCommandPath(command, cwd, env);
+    if (resolved)
+        return;
+    if (command.includes("/") || command.includes("\\")) {
+        const absolute = path.isAbsolute(command) ? command : path.resolve(cwd, command);
+        throw new Error(`Command is not executable: "${command}" (resolved: "${absolute}")`);
+    }
+    throw new Error(`Command not found in PATH: "${command}"`);
+}
+export async function runChildProcess(runId, command, args, opts) {
+    const onLogError = opts.onLogError ?? ((err, id, msg) => console.warn({ err, runId: id }, msg));
+    return new Promise((resolve, reject) => {
+        const rawMerged = { ...process.env, ...opts.env };
+        // Strip Claude Code nesting-guard env vars so spawned `claude` processes
+        // don't refuse to start with "cannot be launched inside another session".
+        // These vars leak in when the Paperclip server itself is started from
+        // within a Claude Code session (e.g. `npx penclip run` in a terminal
+        // owned by Claude Code) or when cron inherits a contaminated shell env.
+        const CLAUDE_CODE_NESTING_VARS = [
+            "CLAUDECODE",
+            "CLAUDE_CODE_ENTRYPOINT",
+            "CLAUDE_CODE_SESSION",
+            "CLAUDE_CODE_PARENT_SESSION",
+        ];
+        for (const key of CLAUDE_CODE_NESTING_VARS) {
+            delete rawMerged[key];
+        }
+        const mergedEnv = ensurePathInEnv(rawMerged);
+        void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)
+            .then((target) => {
+            const child = spawn(target.command, target.args, {
+                cwd: opts.cwd,
+                env: mergedEnv,
+                shell: false,
+                stdio: [opts.stdin != null ? "pipe" : "ignore", "pipe", "pipe"],
+            });
+            const startedAt = new Date().toISOString();
+            if (opts.stdin != null && child.stdin) {
+                child.stdin.write(opts.stdin);
+                child.stdin.end();
+            }
+            if (typeof child.pid === "number" && child.pid > 0 && opts.onSpawn) {
+                void opts.onSpawn({ pid: child.pid, startedAt }).catch((err) => {
+                    onLogError(err, runId, "failed to record child process metadata");
+                });
+            }
+            runningProcesses.set(runId, { child, graceSec: opts.graceSec });
+            let timedOut = false;
+            let stdout = "";
+            let stderr = "";
+            let logChain = Promise.resolve();
+            const timeout = opts.timeoutSec > 0
+                ? setTimeout(() => {
+                    timedOut = true;
+                    child.kill("SIGTERM");
+                    setTimeout(() => {
+                        if (!child.killed) {
+                            child.kill("SIGKILL");
+                        }
+                    }, Math.max(1, opts.graceSec) * 1000);
+                }, opts.timeoutSec * 1000)
+                : null;
+            child.stdout?.on("data", (chunk) => {
+                const text = String(chunk);
+                stdout = appendWithCap(stdout, text);
+                logChain = logChain
+                    .then(() => opts.onLog("stdout", text))
+                    .catch((err) => onLogError(err, runId, "failed to append stdout log chunk"));
+            });
+            child.stderr?.on("data", (chunk) => {
+                const text = String(chunk);
+                stderr = appendWithCap(stderr, text);
+                logChain = logChain
+                    .then(() => opts.onLog("stderr", text))
+                    .catch((err) => onLogError(err, runId, "failed to append stderr log chunk"));
+            });
+            child.on("error", (err) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                runningProcesses.delete(runId);
+                const errno = err.code;
+                const pathValue = mergedEnv.PATH ?? mergedEnv.Path ?? "";
+                const msg = errno === "ENOENT"
+                    ? `Failed to start command "${command}" in "${opts.cwd}". Verify adapter command, working directory, and PATH (${pathValue}).`
+                    : `Failed to start command "${command}" in "${opts.cwd}": ${err.message}`;
+                reject(new Error(msg));
+            });
+            child.on("close", (code, signal) => {
+                if (timeout)
+                    clearTimeout(timeout);
+                runningProcesses.delete(runId);
+                void logChain.finally(() => {
+                    resolve({
+                        exitCode: code,
+                        signal,
+                        timedOut,
+                        stdout,
+                        stderr,
+                        pid: child.pid ?? null,
+                        startedAt,
+                    });
+                });
+            });
+        })
+            .catch(reject);
+    });
+}
+//# sourceMappingURL=server-utils.js.map