@rudderhq/agent-runtime-utils 0.2.5-canary.8 → 0.2.5

package/dist/server-utils.js

@@ -1,1550 +1,5 @@
-import { createHash } from "node:crypto";
-import { spawn } from "node:child_process";
-import { constants as fsConstants, promises as fs } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-export const runningProcesses = new Map();
-function isChildProcessAlive(child) {
-    const pid = child.pid;
-    if (typeof pid !== "number" || pid <= 0)
-        return false;
-    if (child.exitCode !== null || child.signalCode !== null)
-        return false;
-    try {
-        process.kill(pid, 0);
-        return true;
-    }
-    catch (error) {
-        const code = error instanceof Error && "code" in error ? error.code : null;
-        return code === "EPERM";
-    }
-}
-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 RUDDER_SKILL_ROOT_RELATIVE_CANDIDATES = [
-    "../../server/resources/bundled-skills",
-    "../../skills",
-    "../../../../../server/resources/bundled-skills",
-];
-const DEFAULT_LOCAL_CLI_CREDENTIAL_HOME_ENTRIES = [
-    ".aws",
-    ".azure",
-    ".config/gh",
-    ".config/gcloud",
-    ".config/op",
-    ".config/vercel",
-    ".config/configstore",
-    ".docker",
-    ".fly",
-    ".git-credentials",
-    ".gnupg",
-    ".kube",
-    ".netrc",
-    ".npmrc",
-    ".ssh",
-    ".vercel",
-    "Library/Application Support/gh",
-    "Library/Application Support/com.heroku.cli",
-];
-const DEFAULT_LOCAL_CLI_OPERATOR_HOME_SHIM_COMMANDS = [
-    {
-        command: "gh",
-        authCheckArgs: ["auth", "status"],
-        credentialEntries: [".config/gh", "Library/Application Support/gh"],
-    },
-    {
-        command: "vercel",
-        authCheckArgs: ["whoami"],
-        credentialEntries: [".config/vercel", ".vercel", ".config/configstore"],
-    },
-];
-function normalizePathSlashes(value) {
-    return value.replaceAll("\\", "/");
-}
-function isMaintainerOnlySkillTarget(candidate) {
-    const normalized = normalizePathSlashes(candidate);
-    return (normalized.includes("/server/resources/bundled-skills/")
-        || normalized.includes("/.agents/skills/"));
-}
-function skillLocationLabel(value) {
-    if (typeof value !== "string")
-        return null;
-    const trimmed = value.trim();
-    return trimmed.length > 0 ? trimmed : null;
-}
-function buildManagedSkillOrigin() {
-    return {
-        origin: "organization_managed",
-        readOnly: false,
-    };
-}
-function compactSkillText(value) {
-    if (typeof value !== "string")
-        return null;
-    const compacted = value
-        .replace(/\r\n/g, "\n")
-        .split("\n")
-        .map((line) => line.trim())
-        .filter(Boolean)
-        .join(" ")
-        .replace(/\s+/g, " ")
-        .trim();
-    return compacted.length > 0 ? compacted : null;
-}
-function parseSkillFrontmatterMetadata(markdown) {
-    const match = markdown.match(/^---\n([\s\S]*?)\n---(?:\n|$)/);
-    if (!match) {
-        return { name: null, description: null };
-    }
-    const yaml = match[1];
-    const nameMatch = yaml.match(/^name:\s*["']?(.*?)["']?\s*$/m);
-    const descriptionMatch = yaml.match(/^description:\s*(?:>\s*\n((?:\s{2,}[^\n]*\n?)+)|[|]\s*\n((?:\s{2,}[^\n]*\n?)+)|["']?(.*?)["']?\s*$)/m);
-    return {
-        name: compactSkillText(nameMatch?.[1] ?? null),
-        description: compactSkillText(descriptionMatch?.[1] ?? descriptionMatch?.[2] ?? descriptionMatch?.[3] ?? null),
-    };
-}
-async function readSkillMetadataFromDirectory(skillDir) {
-    const skillFile = path.join(skillDir, "SKILL.md");
-    try {
-        const markdown = await fs.readFile(skillFile, "utf8");
-        return parseSkillFrontmatterMetadata(markdown);
-    }
-    catch {
-        return { name: null, description: null };
-    }
-}
-export async function readSkillMetadataFromPath(candidatePath) {
-    if (typeof candidatePath !== "string" || candidatePath.trim().length === 0) {
-        return { name: null, description: null };
-    }
-    const resolvedPath = path.resolve(candidatePath);
-    const skillDir = path.basename(resolvedPath).toLowerCase() === "skill.md"
-        ? path.dirname(resolvedPath)
-        : resolvedPath;
-    return readSkillMetadataFromDirectory(skillDir);
-}
-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));
-}
-const ISSUE_DOCUMENT_PROMPT_BODY_CHAR_LIMIT = 16_000;
-function truncateIssueDocumentBody(body) {
-    if (body.length <= ISSUE_DOCUMENT_PROMPT_BODY_CHAR_LIMIT)
-        return body;
-    return `${body.slice(0, ISSUE_DOCUMENT_PROMPT_BODY_CHAR_LIMIT).trimEnd()}\n\n[Document truncated in prompt. Fetch the full document with the Rudder CLI.]`;
-}
-function formatDocumentHeading(key, title) {
-    const cleanTitle = typeof title === "string" ? title.trim() : "";
-    return cleanTitle ? `### ${key} — ${cleanTitle}` : `### ${key}`;
-}
-function readIssueDocumentPromptIssueId(input) {
-    const planIssueId = typeof input.planDocument?.issueId === "string" ? input.planDocument.issueId.trim() : "";
-    if (planIssueId)
-        return planIssueId;
-    for (const summary of input.documentSummaries ?? []) {
-        const issueId = typeof summary.issueId === "string" ? summary.issueId.trim() : "";
-        if (issueId)
-            return issueId;
-    }
-    return "<issue-id>";
-}
-export function buildIssueDocumentsPrompt(input) {
-    if (!input)
-        return "";
-    const sections = [];
-    const planKey = input.planDocument?.key?.trim() || input.legacyPlanDocument?.key?.trim() || "plan";
-    const planBody = input.planDocument?.body?.trim() || input.legacyPlanDocument?.body?.trim() || "";
-    if (planBody) {
-        sections.push([
-            formatDocumentHeading(planKey, input.planDocument?.title),
-            input.legacyPlanDocument ? "Source: legacy `<plan>` block in the issue description." : `Source: issue document \`${planKey}\`.`,
-            "",
-            truncateIssueDocumentBody(planBody),
-        ].join("\n"));
-    }
-    const otherDocuments = (input.documentSummaries ?? []).filter((doc) => {
-        const key = typeof doc.key === "string" ? doc.key.trim() : "";
-        return key && key !== planKey;
-    });
-    if (otherDocuments.length > 0) {
-        const issueId = readIssueDocumentPromptIssueId(input);
-        sections.push([
-            "### Additional Issue Documents",
-            ...otherDocuments.map((doc) => {
-                const key = doc.key?.trim() || "document";
-                const title = doc.title?.trim();
-                const revision = typeof doc.latestRevisionNumber === "number" ? `, revision ${doc.latestRevisionNumber}` : "";
-                const titlePart = title ? ` — ${title}` : "";
-                return `- \`${key}\`${titlePart}${revision}. Fetch with \`rudder issue documents get ${issueId} ${key} --json\`.`;
-            }),
-        ].join("\n"));
-    }
-    if (sections.length === 0)
-        return "";
-    return ["## Issue Documents", ...sections].join("\n\n");
-}
-// Default prompt templates for different wake sources
-export const DEFAULT_AGENT_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). Continue your Rudder work.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-{{context.issueDocumentsPrompt}}`;
-export const ISSUE_ASSIGN_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). You have been assigned to work on an issue.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-## Task Context
-
-**Issue:** {{issue.title}}
-**ID:** {{issue.id}}
-**Status:** {{issue.status}}
-**Priority:** {{issue.priority}}
-
-**Description:**
-{{issue.description}}
-
-{{context.issueDocumentsPrompt}}
-
-Your task is to review this issue and begin working on it. Use the available tools to explore the codebase, understand the requirements, and implement a solution.`;
-export const COMMENT_MENTION_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). You were mentioned in a comment and your attention is needed.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-## Context
-
-**Issue:** {{issue.title}}
-**ID:** {{issue.id}}
-
-**Issue Description:**
-{{issue.description}}
-
-{{context.issueDocumentsPrompt}}
-
-**Comment:**
-From: {{comment.authorLabel}} ({{comment.authorKind}})
-
-{{comment.body}}
-
-Please review the comment above and respond or take action as appropriate.
-An @mention is an explicit request for attention or collaboration, not an automatic transfer of issue ownership. Only checkout or self-assign when the comment explicitly asks you to take ownership and the normal issue workflow allows it.`;
-export const ISSUE_COMMENTED_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). There is a new comment on an issue you own.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-## Context
-
-**Issue:** {{issue.title}}
-**ID:** {{issue.id}}
-**Status:** {{issue.status}}
-
-**Issue Description:**
-{{issue.description}}
-
-{{context.issueDocumentsPrompt}}
-
-**Latest Comment:**
-From: {{comment.authorLabel}} ({{comment.authorKind}})
-
-{{comment.body}}
-
-Review the new comment and continue the issue from the current state. Respond or take action as needed.`;
-export const ISSUE_CHANGES_REQUESTED_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). A reviewer requested changes on an issue you own.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-## Context
-
-**Issue:** {{issue.title}}
-**ID:** {{issue.id}}
-**Status:** {{issue.status}}
-
-**Issue Description:**
-{{issue.description}}
-
-{{context.issueDocumentsPrompt}}
-
-**Reviewer Comment:**
-From: {{comment.authorLabel}} ({{comment.authorKind}})
-
-{{comment.body}}
-
-Review the requested changes and continue the issue from the current state. Address the reviewer feedback before handing it back for review.`;
-export const ISSUE_RECOVERY_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). This is a recovery run, not a fresh task.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-## Recovery Context
-
-- Original Run ID: {{context.recovery.originalRunId}}
-- Failure Kind: {{context.recovery.failureKind}}
-- Failure Summary: {{context.recovery.failureSummary}}
-- Recovery Trigger: {{context.recovery.recoveryTrigger}}
-- Recovery Mode: {{context.recovery.recoveryMode}}
-
-## Current Issue Context
-
-- Issue: {{issue.title}}
-- ID: {{issue.id}}
-- Status: {{issue.status}}
-- Priority: {{issue.priority}}
-
-- Description:
-{{issue.description}}
-
-{{context.issueDocumentsPrompt}}
-
-Before doing anything else, inspect what the previous run already completed and any side effects it may have caused. Continue the remaining work from the current state. Avoid blindly re-running the whole task.`;
-export const RECOVERY_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). This is a recovery run, not a fresh task.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-## Recovery Context
-
-- Original Run ID: {{context.recovery.originalRunId}}
-- Failure Kind: {{context.recovery.failureKind}}
-- Failure Summary: {{context.recovery.failureSummary}}
-- Recovery Trigger: {{context.recovery.recoveryTrigger}}
-- Recovery Mode: {{context.recovery.recoveryMode}}
-
-Before doing anything else, inspect what the previous run already completed and any side effects it may have caused. Continue the remaining work from the current state. Avoid blindly re-running the whole task.`;
-export const ISSUE_PASSIVE_FOLLOWUP_PROMPT_TEMPLATE = `You are agent {{agent.id}} ({{agent.name}}). This is a passive issue follow-up, not a fresh assignment and not a failure recovery.
-
-{{context.rudderWorkspace.orgResourcesPrompt}}
-
-## Why You Were Woken
-
-The previous run ended without sufficient issue close-out.
-
-- Origin Run ID: {{context.passiveFollowup.originRunId}}
-- Previous Run ID: {{context.passiveFollowup.previousRunId}}
-- Attempt: {{context.passiveFollowup.attempt}} / {{context.passiveFollowup.maxAttempts}}
-Reason: {{context.passiveFollowup.reason}}
-
-## Current Issue Context
-
-- Issue: {{issue.title}}
-- ID: {{issue.id}}
-- Status: {{issue.status}}
-- Priority: {{issue.priority}}
-
-- Description:
-{{issue.description}}
-
-{{context.issueDocumentsPrompt}}
-
-Before changing the issue, inspect the current issue state and any side effects from the previous run. Then do exactly one close-out action: add a progress comment, mark the issue done, block it with a reason, or hand it off explicitly with explanation.`;
-/**
- * Selects the base heartbeat prompt template used by runtimes before final prompt assembly.
- *
- * Prompt shape by wake trigger:
- * - assignment:
- *   "You are agent ... You have been assigned ..."
- *   Includes issue title/id/status/priority/description so the agent can start immediately.
- * - comment.mention:
- *   "You were mentioned in a comment ..."
- *   Includes issue summary plus mention comment author/body so the agent can respond without extra fetches.
- *   Mentions request attention; ownership transfer still requires an explicit handoff.
- * - issue_changes_requested:
- *   "A reviewer requested changes on an issue you own ..."
- *   Includes issue summary plus reviewer attribution/comment body so the assignee can act on feedback immediately.
- * - issue_commented:
- *   "There is a new comment on an issue you own ..."
- *   Includes issue summary plus the newest comment author/body so the assignee can continue immediately.
- * - recovery:
- *   "This is a recovery run, not a fresh task ..."
- *   Includes original run id, failure metadata, and a continue-preferred instruction to
- *   inspect prior progress/side effects before resuming.
- * - passive issue follow-up:
- *   "This is a passive issue follow-up, not a fresh assignment ..."
- *   Includes close-out lineage and tells the agent to comment, finish, block, or hand off.
- * - fallback:
- *   Generic "Continue your Rudder work."
- *
- * Concrete rendered example (comment mention):
- * "You are agent agent-456 (Backend Worker). You were mentioned in a comment and your attention is needed.
- *  Issue: Stabilize queue worker
- *  Comment: @agent please check timeout handling in retry path."
- *
- * Reasoning:
- * - Keep backward compatibility: custom configured templates always win.
- * - Keep first-turn latency low: include the minimum task context directly in prompt text.
- * - Keep behavior deterministic across runtimes: template selection is centralized here.
- *
- * See also:
- * - doc/plans/2026-04-07-agent-prompt-context-injection.md
- * - doc/DEVELOPING.md
- */
-export function selectPromptTemplate(configuredTemplate, context) {
-    // If user configured a custom template, use it
-    if (configuredTemplate?.trim()) {
-        return configuredTemplate;
-    }
-    // Select based on wake source/reason
-    const wakeSource = String(context.wakeSource ?? "");
-    const wakeReason = String(context.wakeReason ?? "");
-    const recovery = context.recovery;
-    const hasRecoveryContext = typeof recovery === "object" &&
-        recovery !== null &&
-        !Array.isArray(recovery) &&
-        typeof recovery.originalRunId === "string";
-    if (hasRecoveryContext || wakeReason === "process_lost_retry" || wakeReason === "retry_failed_run") {
-        return typeof context.issue === "object" && context.issue !== null && !Array.isArray(context.issue)
-            ? ISSUE_RECOVERY_PROMPT_TEMPLATE
-            : RECOVERY_PROMPT_TEMPLATE;
-    }
-    if (wakeReason === "issue_passive_followup") {
-        return ISSUE_PASSIVE_FOLLOWUP_PROMPT_TEMPLATE;
-    }
-    if (wakeReason === "issue_changes_requested") {
-        return ISSUE_CHANGES_REQUESTED_PROMPT_TEMPLATE;
-    }
-    if (wakeSource === "assignment" || wakeReason === "issue_assigned") {
-        return ISSUE_ASSIGN_PROMPT_TEMPLATE;
-    }
-    if (wakeSource === "comment.mention" || wakeReason === "issue_comment_mentioned") {
-        return COMMENT_MENTION_PROMPT_TEMPLATE;
-    }
-    if (wakeReason === "issue_commented") {
-        return ISSUE_COMMENTED_PROMPT_TEMPLATE;
-    }
-    return DEFAULT_AGENT_PROMPT_TEMPLATE;
-}
-export function joinPromptSections(sections, separator = "\n\n") {
-    return sections
-        .map((value) => (typeof value === "string" ? value.trim() : ""))
-        .filter(Boolean)
-        .join(separator);
-}
-export const RUDDER_AGENT_OPERATING_CONTRACT = [
-    "# Rudder Agent Operating Contract",
-    "",
-    "Your home directory is `$AGENT_HOME`. Everything personal to you -- life, memory, knowledge -- lives there. Other agents may have their own folders and you may update them when necessary.",
-    "",
-    "Use these paths consistently:",
-    "",
-    "- Personal instructions live under `$AGENT_HOME/instructions`.",
-    "- Personal memory lives under `$AGENT_HOME/memory`.",
-    "- Tacit memory instruction lives at `$AGENT_HOME/instructions/MEMORY.md` and is automatically loaded when present.",
-    "- Personal skills live under `$AGENT_HOME/skills`.",
-    "- Shared organization workspace root lives under `$RUDDER_ORG_WORKSPACE_ROOT`.",
-    "- Shared organization skills live under `$RUDDER_ORG_SKILLS_DIR`.",
-    "- Shared organization plans live under `$RUDDER_ORG_PLANS_DIR`.",
-    "- Shared organization artifacts live under `$RUDDER_ORG_ARTIFACTS_DIR`.",
-    "- Durable generated outputs such as screenshots, images, mockups, reports, CSVs, handoff logs, and other user-visible files should be written under `$RUDDER_ORG_ARTIFACTS_DIR` when available.",
-    "- Use `/tmp` only for transient scratch files and temporary verification artifacts; do not put durable work product there.",
-    "- Local trusted runtimes may expose the host operator home as `$RUDDER_OPERATOR_HOME`; use it only when a local skill or script intentionally needs operator-owned desktop app or CLI state. Do not replace `$HOME` with it.",
-    "- Durable shared work output should prefer these managed workspace paths instead of ad-hoc top-level `projects/` folders.",
-    "",
-    "When you create or copy a skill under `$AGENT_HOME/skills/<slug>/`, check the agent's Skills snapshot before claiming it will load in future runs. If it is installed but not enabled, say exactly that future runs will not load it until enabled, and offer to enable it with `rudder agent skills enable <agent-id> <selection-ref>` when you have permission.",
-    "",
-    "When you write issue comments or chat replies, match the language of the user's or board's most recent substantive message unless they explicitly ask for a different language.",
-    "",
-    "When an issue comment, done comment, or blocker comment cites visual evidence from a local screenshot/image path, attach the image with the Rudder CLI `--image <path>` option instead of leaving only the filesystem path in the text.",
-    "",
-    "## Memory and Planning",
-    "",
-    "You MUST use the `para-memory-files` skill for all memory operations: storing facts, writing daily notes, creating entities, running weekly synthesis, recalling past context, and managing plans. The skill defines your three-layer memory system (knowledge graph, daily notes, tacit knowledge), the PARA folder structure, atomic fact schemas, memory decay rules, and recall/planning conventions.",
-    "",
-    "Keep stable preferences and operating lessons in `$AGENT_HOME/instructions/MEMORY.md`. Use `$AGENT_HOME/memory/YYYY-MM-DD.md` for daily notes and `$AGENT_HOME/life/` for structured long-term memory; those files are not auto-loaded.",
-    "",
-    "Invoke it whenever you need to remember, retrieve, or organize anything.",
-    "",
-    "## Safety Considerations",
-    "",
-    "- Never exfiltrate secrets or private data.",
-    "- Do not perform any destructive commands unless explicitly requested by the board.",
-].join("\n");
-function toPromptPath(pathValue) {
-    return pathValue.split(path.sep).join("/");
-}
-function isInsidePath(parentPath, childPath) {
-    const relativePath = path.relative(parentPath, childPath);
-    return relativePath === "" || (!relativePath.startsWith("..") && !path.isAbsolute(relativePath));
-}
-function displayInstructionPath(filePath, instructionsFilePath) {
-    const resolvedFilePath = path.resolve(filePath);
-    const resolvedInstructionsPath = path.resolve(instructionsFilePath);
-    const instructionsDir = path.dirname(resolvedInstructionsPath);
-    if (path.basename(instructionsDir) === "instructions") {
-        const agentHome = path.dirname(instructionsDir);
-        if (isInsidePath(agentHome, resolvedFilePath)) {
-            const relativePath = path.relative(agentHome, resolvedFilePath);
-            return relativePath ? `$AGENT_HOME/${toPromptPath(relativePath)}` : "$AGENT_HOME";
-        }
-    }
-    return filePath;
-}
-function displayInstructionDir(filePath, instructionsFilePath) {
-    const displayPath = displayInstructionPath(filePath, instructionsFilePath);
-    const lastSlash = displayPath.lastIndexOf("/");
-    return lastSlash >= 0 ? `${displayPath.slice(0, lastSlash)}/` : "";
-}
-export async function loadAgentInstructionsPrefix(input) {
-    const instructionsFilePath = input.instructionsFilePath.trim();
-    const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
-    const displayInstructionsFilePath = instructionsFilePath
-        ? displayInstructionPath(instructionsFilePath, instructionsFilePath)
-        : "";
-    const displayInstructionsDir = instructionsFilePath
-        ? displayInstructionDir(instructionsFilePath, instructionsFilePath)
-        : "";
-    const warningStream = input.warningStream ?? "stdout";
-    const operatingContractSection = `${RUDDER_AGENT_OPERATING_CONTRACT}\n\n` +
-        "The above Rudder agent operating contract was injected by Rudder at runtime.";
-    const empty = {
-        prefix: operatingContractSection,
-        commandNotes: ["Loaded Rudder agent operating contract from runtime code"],
-        instructionsFilePath,
-        instructionsDir,
-        soulFilePath: null,
-        toolsFilePath: null,
-        memoryFilePath: null,
-        readFailed: false,
-        metrics: {
-            instructionsChars: operatingContractSection.length,
-            operatingContractChars: operatingContractSection.length,
-            instructionEntryChars: 0,
-            soulChars: 0,
-            toolsChars: 0,
-            memoryChars: 0,
-        },
-    };
-    if (!instructionsFilePath)
-        return empty;
-    const loadedPaths = new Set();
-    const commandNotes = [...empty.commandNotes];
-    let entrySection = "";
-    try {
-        const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
-        loadedPaths.add(path.resolve(instructionsFilePath));
-        entrySection =
-            `${instructionsContents}\n\n` +
-                `The above agent instructions were loaded from ${displayInstructionsFilePath}. ` +
-                `Resolve any relative file references from ${displayInstructionsDir}.`;
-        await input.onLog("stdout", `[rudder] Loaded agent instructions file: ${displayInstructionsFilePath}\n`);
-    }
-    catch (err) {
-        const reason = err instanceof Error ? err.message : String(err);
-        await input.onLog(warningStream, `[rudder] Warning: could not read agent instructions file "${instructionsFilePath}": ${reason}\n`);
-        commandNotes.push(`Configured instructionsFilePath ${displayInstructionsFilePath}, but file could not be read; continuing without injected instructions.`);
-    }
-    async function loadSiblingInstructionFile(siblingInput) {
-        const filePath = path.join(path.dirname(instructionsFilePath), siblingInput.fileName);
-        const resolvedPath = path.resolve(filePath);
-        const displayFilePath = displayInstructionPath(filePath, instructionsFilePath);
-        const displayFileDir = displayInstructionDir(filePath, instructionsFilePath);
-        if (loadedPaths.has(resolvedPath))
-            return { path: filePath, section: "" };
-        try {
-            const contents = await fs.readFile(filePath, "utf8");
-            loadedPaths.add(resolvedPath);
-            await input.onLog("stdout", `[rudder] Loaded ${siblingInput.logLabel}: ${displayFilePath}\n`);
-            return {
-                path: filePath,
-                section: `${contents}\n\n` +
-                    `The above ${siblingInput.label} were loaded from ${displayFilePath}. ` +
-                    `Resolve any relative file references from ${displayFileDir}.`,
-            };
-        }
-        catch (err) {
-            if (err.code !== "ENOENT") {
-                const reason = err instanceof Error ? err.message : String(err);
-                await input.onLog(warningStream, `[rudder] Warning: could not read ${siblingInput.logLabel} "${filePath}": ${reason}\n`);
-            }
-            return { path: null, section: "" };
-        }
-    }
-    const soul = await loadSiblingInstructionFile({
-        fileName: "SOUL.md",
-        label: "agent role and persona instructions",
-        logLabel: "agent soul instructions file",
-    });
-    if (soul.section && soul.path) {
-        commandNotes.push(`Loaded agent soul instructions from ${displayInstructionPath(soul.path, instructionsFilePath)}`);
-    }
-    const tools = await loadSiblingInstructionFile({
-        fileName: "TOOLS.md",
-        label: "agent tool notes",
-        logLabel: "agent tool notes file",
-    });
-    if (tools.section && tools.path) {
-        commandNotes.push(`Loaded agent tool notes from ${displayInstructionPath(tools.path, instructionsFilePath)}`);
-    }
-    const memory = await loadSiblingInstructionFile({
-        fileName: "MEMORY.md",
-        label: "agent memory instructions",
-        logLabel: "agent memory instructions file",
-    });
-    if (memory.section && memory.path) {
-        commandNotes.push(`Loaded agent memory instructions from ${displayInstructionPath(memory.path, instructionsFilePath)}`);
-    }
-    const memoryFilePath = memory.section ? memory.path : null;
-    const memorySection = memory.section;
-    if (entrySection)
-        commandNotes.splice(1, 0, `Loaded agent instructions from ${displayInstructionsFilePath}`);
-    const prefix = joinPromptSections([operatingContractSection, entrySection, soul.section, tools.section, memorySection]);
-    return {
-        prefix,
-        commandNotes,
-        instructionsFilePath,
-        instructionsDir,
-        soulFilePath: soul.section ? soul.path : null,
-        toolsFilePath: tools.section ? tools.path : null,
-        memoryFilePath,
-        readFailed: !entrySection,
-        metrics: {
-            instructionsChars: prefix.length,
-            operatingContractChars: operatingContractSection.length,
-            instructionEntryChars: entrySection.length,
-            soulChars: soul.section.length,
-            toolsChars: tools.section.length,
-            memoryChars: memorySection.length,
-        },
-    };
-}
-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 buildRudderEnv(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 = {
-        RUDDER_AGENT_ID: agent.id,
-        RUDDER_ORG_ID: agent.orgId,
-    };
-    const runtimeHost = resolveHostForUrl(process.env.RUDDER_LISTEN_HOST ?? process.env.HOST ?? "localhost");
-    const runtimePort = process.env.RUDDER_LISTEN_PORT ?? process.env.PORT ?? "3100";
-    const apiUrl = process.env.RUDDER_API_URL ?? `http://${runtimeHost}:${runtimePort}`;
-    vars.RUDDER_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 fileExists(candidate) {
-    try {
-        await fs.access(candidate, fsConstants.F_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)];
-        for (const candidate of candidates) {
-            if (await pathExists(candidate))
-                return candidate;
-        }
-    }
-    return null;
-}
-function quoteForCmd(arg) {
-    if (!arg.length)
-        return '""';
-    const escaped = arg.replace(/"/g, '""');
-    return /[\s"&<>|^()]/.test(escaped) ? `"${escaped}"` : escaped;
-}
-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],
-        };
-    }
-    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() };
-}
-function prependPathEntry(env, entry) {
-    const normalized = ensurePathInEnv(env);
-    const pathKey = typeof normalized.PATH === "string" ? "PATH" : "Path";
-    const current = normalized[pathKey] ?? "";
-    const delimiter = process.platform === "win32" ? ";" : ":";
-    const segments = current.split(delimiter).filter(Boolean);
-    if (segments.includes(entry))
-        return normalized;
-    return {
-        ...normalized,
-        [pathKey]: current.length > 0 ? `${entry}${delimiter}${current}` : entry,
-    };
-}
-async function findAncestorWithFile(startDir, relativePath, maxDepth = 12) {
-    let current = path.resolve(startDir);
-    for (let depth = 0; depth <= maxDepth; depth += 1) {
-        const candidate = path.join(current, relativePath);
-        if (await fileExists(candidate))
-            return candidate;
-        const parent = path.dirname(current);
-        if (parent === current)
-            break;
-        current = parent;
-    }
-    return null;
-}
-function shellQuote(arg) {
-    return `'${arg.replace(/'/g, `'\\''`)}'`;
-}
-async function resolveRudderCliShimTarget(moduleDir) {
-    const packagedCli = await findAncestorWithFile(moduleDir, "desktop-cli.js");
-    if (packagedCli) {
-        return {
-            command: process.execPath,
-            args: [packagedCli],
-        };
-    }
-    const repoRoot = await findAncestorWithFile(moduleDir, path.join("cli", "src", "index.ts"));
-    if (!repoRoot)
-        return null;
-    const rootDir = path.dirname(path.dirname(path.dirname(repoRoot)));
-    const tsxEntry = path.join(rootDir, "cli", "node_modules", "tsx", "dist", "cli.mjs");
-    const cliSource = path.join(rootDir, "cli", "src", "index.ts");
-    if (await fileExists(tsxEntry)) {
-        return {
-            command: process.execPath,
-            args: [tsxEntry, cliSource],
-        };
-    }
-    const builtCliEntry = path.join(rootDir, "cli", "dist", "index.js");
-    if (await fileExists(builtCliEntry)) {
-        return {
-            command: process.execPath,
-            args: [builtCliEntry],
-        };
-    }
-    return null;
-}
-async function materializeRudderCliShim(target) {
-    const hash = createHash("sha1")
-        .update(JSON.stringify({ command: target.command, args: target.args, platform: process.platform }))
-        .digest("hex")
-        .slice(0, 12);
-    const shimDir = path.join(os.tmpdir(), "rudder-cli-shims", hash);
-    await fs.mkdir(shimDir, { recursive: true });
-    if (process.platform === "win32") {
-        const shimPath = path.join(shimDir, "rudder.cmd");
-        const commandLine = [quoteForCmd(target.command), ...target.args.map(quoteForCmd), "%*"].join(" ");
-        await fs.writeFile(shimPath, `@echo off\r\n${commandLine}\r\n`, "utf8");
-        return shimPath;
-    }
-    const shimPath = path.join(shimDir, "rudder");
-    const commandLine = [target.command, ...target.args].map(shellQuote).join(" ");
-    await fs.writeFile(shimPath, `#!/bin/sh\nexec ${commandLine} "$@"\n`, "utf8");
-    await fs.chmod(shimPath, 0o755);
-    return shimPath;
-}
-export async function ensureRudderCliInPath(moduleDir, env) {
-    const normalized = ensurePathInEnv(env);
-    const target = await resolveRudderCliShimTarget(moduleDir);
-    if (!target) {
-        return normalized;
-    }
-    const shimPath = await materializeRudderCliShim(target);
-    return prependPathEntry(normalized, path.dirname(shimPath));
-}
-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 resolveRudderSkillsDir(moduleDir, additionalCandidates = []) {
-    const candidates = [
-        ...RUDDER_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 listRudderSkillEntries(moduleDir, additionalCandidates = []) {
-    const root = await resolveRudderSkillsDir(moduleDir, additionalCandidates);
-    if (!root)
-        return [];
-    try {
-        const entries = await fs.readdir(root, { withFileTypes: true });
-        const skillDirectories = entries
-            .filter((entry) => entry.isDirectory())
-            .sort((left, right) => left.name.localeCompare(right.name));
-        const skillEntries = await Promise.all(skillDirectories.map(async (entry) => {
-            const source = path.join(root, entry.name);
-            const metadata = await readSkillMetadataFromDirectory(source);
-            return {
-                key: `rudder/${entry.name}`,
-                runtimeName: entry.name,
-                source,
-                name: metadata.name ?? entry.name,
-                description: metadata.description,
-            };
-        }));
-        return skillEntries;
-    }
-    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 { agentRuntimeType, availableEntries, desiredSkills, installed, skillsHome, locationLabel, installedDetail, missingDetail, externalConflictDetail, externalDetail, } = options;
-    const availableByKey = new Map(availableEntries.map((entry) => [entry.key, entry]));
-    const desiredSet = new Set(desiredSkills);
-    const entries = [];
-    const warnings = [...(options.warnings ?? [])];
-    for (const available of availableEntries) {
-        const installedEntry = installed.get(available.runtimeName) ?? null;
-        const desired = desiredSet.has(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,
-            description: available.description ?? null,
-            desired,
-            managed,
-            state,
-            sourcePath: available.source,
-            targetPath: path.join(skillsHome, available.runtimeName),
-            detail,
-            ...buildManagedSkillOrigin(),
-        });
-    }
-    for (const desiredSkill of desiredSkills) {
-        if (availableByKey.has(desiredSkill))
-            continue;
-        warnings.push(`Desired skill "${desiredSkill}" is not available from the Rudder skills directory.`);
-        entries.push({
-            key: desiredSkill,
-            runtimeName: null,
-            desired: true,
-            managed: true,
-            state: "missing",
-            sourcePath: null,
-            targetPath: null,
-            detail: "Rudder 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,
-            description: null,
-            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 {
-        agentRuntimeType,
-        supported: true,
-        mode: "persistent",
-        desiredSkills,
-        entries,
-        warnings,
-    };
-}
-function normalizeConfiguredPaperclipRuntimeSkills(value) {
-    if (!Array.isArray(value))
-        return [];
-    const out = [];
-    for (const rawEntry of value) {
-        const entry = parseObject(rawEntry);
-        const key = asString(entry.key, asString(entry.name, "")).trim();
-        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,
-            name: compactSkillText(asString(entry.displayName, asString(entry.name, ""))) ?? runtimeName,
-            description: compactSkillText(typeof entry.description === "string"
-                ? entry.description
-                : typeof entry.summary === "string"
-                    ? entry.summary
-                    : null),
-        });
-    }
-    return out;
-}
-export async function readRudderRuntimeSkillEntries(config, moduleDir, additionalCandidates = []) {
-    const configuredEntries = normalizeConfiguredPaperclipRuntimeSkills(config.rudderRuntimeSkills ?? config.paperclipRuntimeSkills);
-    if (configuredEntries.length > 0)
-        return configuredEntries;
-    return listRudderSkillEntries(moduleDir, additionalCandidates);
-}
-export async function readRudderSkillMarkdown(moduleDir, skillKey) {
-    const normalized = skillKey.trim().toLowerCase().replace(/^rudder\/rudder\//, "rudder/");
-    if (!normalized)
-        return null;
-    const entries = await listRudderSkillEntries(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 readRudderSkillSyncPreference(config) {
-    const raw = config.rudderSkillSync ?? 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 canonicalizeDesiredRudderSkillReference(reference, availableEntries) {
-    const normalizedReference = reference.trim().toLowerCase().replace(/^rudder\/rudder\//, "rudder/");
-    if (!normalizedReference)
-        return "";
-    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 normalizedReference;
-}
-export function resolveRudderDesiredSkillNames(config, availableEntries) {
-    const preference = readRudderSkillSyncPreference(config);
-    const desiredSkills = preference.desiredSkills
-        .map((reference) => canonicalizeDesiredRudderSkillReference(reference, availableEntries))
-        .filter(Boolean);
-    return Array.from(new Set(desiredSkills));
-}
-export function writeRudderSkillSyncPreference(config, desiredSkills) {
-    const next = { ...config };
-    const raw = next.rudderSkillSync;
-    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.rudderSkillSync = current;
-    return next;
-}
-function nonEmptyEnvPath(value) {
-    return typeof value === "string" && value.trim().length > 0 ? path.resolve(value.trim()) : null;
-}
-export function resolveLocalOperatorHome(sourceEnv = process.env) {
-    return (nonEmptyEnvPath(sourceEnv.RUDDER_OPERATOR_HOME)
-        ?? nonEmptyEnvPath(process.env.RUDDER_OPERATOR_HOME)
-        ?? nonEmptyEnvPath(process.env.HOME)
-        ?? nonEmptyEnvPath(sourceEnv.HOME)
-        ?? path.resolve(os.homedir()));
-}
-export function applyLocalCliHomeEnv(targetEnv, sourceEnv = process.env) {
-    const home = nonEmptyEnvPath(sourceEnv.HOME) ?? path.resolve(os.homedir());
-    targetEnv.HOME = home;
-    const userProfile = nonEmptyEnvPath(sourceEnv.USERPROFILE);
-    if (userProfile) {
-        targetEnv.USERPROFILE = userProfile;
-    }
-    else if (process.platform === "win32") {
-        targetEnv.USERPROFILE = home;
-    }
-}
-async function localCliPathExists(candidate) {
-    return fs.access(candidate).then(() => true).catch(() => false);
-}
-async function directoryIsEmpty(target) {
-    const entries = await fs.readdir(target).catch(() => null);
-    return Array.isArray(entries) && entries.length === 0;
-}
-async function ensureSymlinkToSource(target, source) {
-    const existing = await fs.lstat(target).catch(() => null);
-    if (!existing) {
-        await fs.mkdir(path.dirname(target), { recursive: true });
-        await fs.symlink(source, target);
-        return "created";
-    }
-    if (!existing.isSymbolicLink()) {
-        if (existing.isDirectory() && await directoryIsEmpty(target)) {
-            await fs.rmdir(target);
-            await fs.symlink(source, target);
-            return "repaired";
-        }
-        return "skipped";
-    }
-    const linkedPath = await fs.readlink(target).catch(() => null);
-    if (!linkedPath)
-        return "skipped";
-    const resolvedLinkedPath = path.isAbsolute(linkedPath)
-        ? linkedPath
-        : path.resolve(path.dirname(target), linkedPath);
-    if (resolvedLinkedPath === source)
-        return "skipped";
-    await fs.unlink(target);
-    await fs.symlink(source, target);
-    return "repaired";
-}
-export async function syncLocalCliCredentialHomeEntries(input) {
-    const sourceHome = nonEmptyEnvPath(input.sourceHome ?? undefined) ?? path.resolve(os.homedir());
-    const targetHome = path.resolve(input.targetHome);
-    const linked = [];
-    const skipped = [];
-    if (sourceHome === targetHome)
-        return { linked, skipped };
-    const entries = input.entries ?? DEFAULT_LOCAL_CLI_CREDENTIAL_HOME_ENTRIES;
-    for (const relativeEntry of entries) {
-        const source = path.join(sourceHome, relativeEntry);
-        if (!(await localCliPathExists(source)))
-            continue;
-        const target = path.join(targetHome, relativeEntry);
-        try {
-            const result = await ensureSymlinkToSource(target, source);
-            if (result === "skipped")
-                skipped.push(relativeEntry);
-            else
-                linked.push(relativeEntry);
-        }
-        catch {
-            skipped.push(relativeEntry);
-        }
-    }
-    if (input.onLog && linked.length > 0) {
-        await input.onLog("stdout", `[rudder] Shared ${linked.length} local CLI credential entr${linked.length === 1 ? "y" : "ies"} into managed HOME ${targetHome}: ${linked.join(", ")}\n`);
-    }
-    return { linked, skipped };
-}
-async function writeOperatorHomeShim(input) {
-    await fs.mkdir(input.shimDir, { recursive: true });
-    if (process.platform === "win32") {
-        const shimPath = path.join(input.shimDir, `${input.command}.cmd`);
-        const lines = [
-            "@echo off",
-            `set "HOME=${input.operatorHome}"`,
-            `set "USERPROFILE=${input.operatorHome}"`,
-            `${quoteForCmd(input.targetCommand)} %*`,
-            "",
-        ];
-        await fs.writeFile(shimPath, lines.join("\r\n"), "utf8");
-        return shimPath;
-    }
-    const shimPath = path.join(input.shimDir, input.command);
-    await fs.writeFile(shimPath, [
-        "#!/bin/sh",
-        `export HOME=${shellQuote(input.operatorHome)}`,
-        `export USERPROFILE=${shellQuote(input.operatorHome)}`,
-        `exec ${shellQuote(input.targetCommand)} "$@"`,
-        "",
-    ].join("\n"), "utf8");
-    await fs.chmod(shimPath, 0o755);
-    return shimPath;
-}
-function normalizeShimCommand(input) {
-    return typeof input === "string" ? { command: input } : input;
-}
-async function runCredentialShimAuthCheck(input) {
-    const env = {
-        ...input.env,
-        HOME: input.home,
-        USERPROFILE: input.home,
-    };
-    return await new Promise((resolve) => {
-        const child = spawn(input.targetCommand, [...input.args], {
-            cwd: input.cwd,
-            env,
-            stdio: ["ignore", "ignore", "ignore"],
-        });
-        const timeout = setTimeout(() => {
-            child.kill("SIGTERM");
-            resolve(false);
-        }, 1000);
-        child.on("error", () => {
-            clearTimeout(timeout);
-            resolve(false);
-        });
-        child.on("close", (code) => {
-            clearTimeout(timeout);
-            resolve(code === 0);
-        });
-    });
-}
-async function shouldPrepareOperatorHomeShim(input) {
-    const authCheckArgs = input.command.authCheckArgs;
-    if (!authCheckArgs || authCheckArgs.length === 0)
-        return true;
-    if (input.command.credentialEntries && input.command.credentialEntries.length > 0) {
-        const hasOperatorCredentialEntry = await Promise.all(input.command.credentialEntries.map((entry) => localCliPathExists(path.join(input.operatorHome, entry))));
-        if (!hasOperatorCredentialEntry.some(Boolean))
-            return false;
-    }
-    const managedHomeWorks = await runCredentialShimAuthCheck({
-        targetCommand: input.targetCommand,
-        args: authCheckArgs,
-        cwd: input.cwd,
-        env: input.env,
-        home: input.targetHome,
-    });
-    if (managedHomeWorks)
-        return false;
-    return await runCredentialShimAuthCheck({
-        targetCommand: input.targetCommand,
-        args: authCheckArgs,
-        cwd: input.cwd,
-        env: input.env,
-        home: input.operatorHome,
-    });
-}
-export async function ensureLocalCliCredentialShimsInPath(input) {
-    const operatorHome = nonEmptyEnvPath(input.operatorHome ?? undefined);
-    const targetHome = nonEmptyEnvPath(input.targetHome);
-    if (!operatorHome || !targetHome || operatorHome === targetHome) {
-        return ensurePathInEnv(input.env);
-    }
-    const normalized = ensurePathInEnv(input.env);
-    const cwd = input.cwd ?? process.cwd();
-    const commands = input.commands ?? DEFAULT_LOCAL_CLI_OPERATOR_HOME_SHIM_COMMANDS;
-    const shimDir = path.join(targetHome, ".rudder", "local-cli-shims");
-    const prepared = [];
-    for (const rawCommand of commands) {
-        const command = normalizeShimCommand(rawCommand);
-        const targetCommand = await resolveCommandPath(command.command, cwd, normalized);
-        if (!targetCommand)
-            continue;
-        if (path.dirname(targetCommand) === shimDir)
-            continue;
-        if (!(await shouldPrepareOperatorHomeShim({
-            command,
-            targetCommand,
-            cwd,
-            env: normalized,
-            targetHome,
-            operatorHome,
-        }))) {
-            continue;
-        }
-        await writeOperatorHomeShim({ shimDir, command: command.command, targetCommand, operatorHome });
-        prepared.push(command.command);
-    }
-    if (prepared.length === 0)
-        return normalized;
-    if (input.onLog) {
-        await input.onLog("stdout", `[rudder] Prepared local CLI credential shim${prepared.length === 1 ? "" : "s"} for: ${prepared.join(", ")}\n`);
-    }
-    return prependPathEntry(normalized, shimDir);
-}
-export async function ensureRudderSkillSymlink(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 };
-        const requestedHome = typeof opts.env.HOME === "string" && opts.env.HOME.trim().length > 0
-            ? path.resolve(opts.env.HOME)
-            : null;
-        const inheritedHome = typeof process.env.HOME === "string" && process.env.HOME.trim().length > 0
-            ? path.resolve(process.env.HOME)
-            : null;
-        const hasExplicitZdotdir = typeof opts.env.ZDOTDIR === "string" && opts.env.ZDOTDIR.trim().length > 0;
-        // 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 Rudder server itself is started from
-        // within a Claude Code session (e.g. `npx rudder 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 GIT_IDENTITY_ENV_VARS = [
-            "GIT_AUTHOR_NAME",
-            "GIT_AUTHOR_EMAIL",
-            "GIT_COMMITTER_NAME",
-            "GIT_COMMITTER_EMAIL",
-        ];
-        for (const key of GIT_IDENTITY_ENV_VARS) {
-            if (rawMerged[key] === "" && !Object.prototype.hasOwnProperty.call(opts.env, key)) {
-                delete rawMerged[key];
-            }
-        }
-        // When Rudder isolates HOME for child agents, don't let zsh keep using the
-        // host user's startup dir via an inherited ZDOTDIR. That mismatch makes
-        // child `zsh -lc` invocations source the host `.zshenv` with the agent HOME.
-        if (requestedHome && requestedHome !== inheritedHome && !hasExplicitZdotdir) {
-            delete rawMerged.ZDOTDIR;
-        }
-        const mergedEnv = ensurePathInEnv(rawMerged);
-        void resolveSpawnTarget(command, args, opts.cwd, mergedEnv)
-            .then((target) => {
-            if (opts.abortSignal?.aborted) {
-                resolve({
-                    exitCode: null,
-                    signal: "SIGTERM",
-                    timedOut: false,
-                    stdout: "",
-                    stderr: "",
-                    pid: null,
-                    startedAt: null,
-                });
-                return;
-            }
-            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 aborted = false;
-            let stdout = "";
-            let stderr = "";
-            let logChain = Promise.resolve();
-            const timeout = opts.timeoutSec > 0
-                ? setTimeout(() => {
-                    timedOut = true;
-                    child.kill("SIGTERM");
-                    setTimeout(() => {
-                        if (isChildProcessAlive(child)) {
-                            child.kill("SIGKILL");
-                        }
-                    }, Math.max(1, opts.graceSec) * 1000);
-                }, opts.timeoutSec * 1000)
-                : null;
-            let abortCleanup = null;
-            if (opts.abortSignal) {
-                const onAbort = () => {
-                    aborted = true;
-                    child.kill("SIGTERM");
-                    setTimeout(() => {
-                        if (isChildProcessAlive(child)) {
-                            child.kill("SIGKILL");
-                        }
-                    }, Math.max(1, opts.graceSec) * 1000);
-                };
-                opts.abortSignal.addEventListener("abort", onAbort, { once: true });
-                abortCleanup = () => opts.abortSignal?.removeEventListener("abort", onAbort);
-            }
-            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);
-                if (abortCleanup)
-                    abortCleanup();
-                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);
-                if (abortCleanup)
-                    abortCleanup();
-                runningProcesses.delete(runId);
-                void logChain.finally(() => {
-                    resolve({
-                        exitCode: code,
-                        signal: aborted ? "SIGTERM" : signal,
-                        timedOut,
-                        stdout,
-                        stderr,
-                        pid: child.pid ?? null,
-                        startedAt,
-                    });
-                });
-            });
-        })
-            .catch(reject);
-    });
-}
+export * from "./server-utils.process.js";
+export * from "./server-utils.prompts.js";
+export * from "./server-utils.instructions.js";
+export * from "./server-utils.cli.js";
 //# sourceMappingURL=server-utils.js.map