host-execution-mcp 1.0.0

package/dist/utils/copy-job-types.d.ts

@@ -0,0 +1,133 @@
+import type { FileEndpoint } from "./remote-copy.js";
+import type { CopyProgress, CopySkipReason, CopyVerifyMode } from "./copy-transfer.js";
+/** Job lifecycle visible to Agent / UI. */
+export type CopyJobStatus = "queued" | "running" | "success" | "failed" | "cancelled" | "timeout";
+/** How the job is executed under the hood (not exposed as separate tools). */
+export type CopyExecutorKind = "sftp" | "kubectl" | "scp" | "landing-cp" | "pipeline";
+/**
+ * Durable job record (MCP-local store, scheme A).
+ * Path suggestion: ~/.agent-compose/remote-copy/jobs/<transferId>.json
+ */
+export interface CopyJobRecord {
+    transferId: string;
+    status: CopyJobStatus;
+    source: FileEndpoint;
+    dest: FileEndpoint;
+    /** Engine options shared with sync path. */
+    options: {
+        skipIfComplete: boolean;
+        verify: CopyVerifyMode;
+        progressIntervalMs: number;
+        /** Wall-clock budget for the whole job (all hops). */
+        totalTimeoutMs: number;
+        recursive: boolean;
+    };
+    /** Multi-hop plan, e.g. pod→accessClient tmp→local. */
+    plan: CopyJobHop[];
+    progress: CopyJobProgress;
+    /** Set when Engine reports verify result. */
+    verified?: boolean;
+    estimatedSeconds?: number;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+    startedAt?: string;
+    finishedAt?: string;
+}
+export declare function isTerminalCopyJobStatus(status: CopyJobStatus): status is Extract<CopyJobStatus, "success" | "failed" | "cancelled" | "timeout">;
+export interface CopyJobHop {
+    index: number;
+    kind: CopyExecutorKind;
+    source: FileEndpoint;
+    dest: FileEndpoint;
+    status: CopyJobStatus;
+    /** Staging path on accessClient when this hop uses a temp file. */
+    stagingPath?: string;
+}
+export interface CopyJobProgress {
+    transferredBytes: number;
+    totalBytes?: number;
+    percent: number;
+    speedBps?: number;
+    etaSeconds?: number;
+    skippedBytes?: number;
+    skipped?: boolean;
+    skipReason?: CopySkipReason;
+    /** Which hop is active (0-based). */
+    currentHopIndex?: number;
+}
+export interface RemoteCopyStartRequest {
+    source: FileEndpoint;
+    dest: FileEndpoint;
+    skipIfComplete?: boolean;
+    verify?: CopyVerifyMode;
+    recursive?: boolean;
+    progressIntervalMs?: number;
+    /** @deprecated prefer totalTimeoutMs */
+    timeoutMs?: number;
+    totalTimeoutMs?: number;
+}
+export interface RemoteCopyStartResult {
+    transferId: string;
+    status: Extract<CopyJobStatus, "queued" | "running">;
+    source: {
+        path: string;
+        size?: number;
+        target: string;
+    };
+    dest: {
+        path: string;
+        target: string;
+    };
+    estimatedSeconds?: number;
+    /** Where Agent/user can find durable state (MCP-local). */
+    jobStorePath?: string;
+    /** Human hint: poll remote_copy_status; do not block the chat. */
+    message: string;
+    createdAt: string;
+}
+export interface RemoteCopyStatusRequest {
+    transferId: string;
+}
+export interface RemoteCopyStatusResult {
+    transferId: string;
+    status: CopyJobStatus;
+    progress: CopyJobProgress;
+    source: {
+        path: string;
+        target: string;
+    };
+    dest: {
+        path: string;
+        target: string;
+    };
+    skippedBytes?: number;
+    skipped?: boolean;
+    skipReason?: CopySkipReason;
+    verified?: boolean;
+    speedBps?: number;
+    etaSeconds?: number;
+    error?: string;
+    createdAt: string;
+    updatedAt: string;
+    finishedAt?: string;
+}
+export interface RemoteCopyCancelRequest {
+    transferId: string;
+}
+export interface RemoteCopyCancelResult {
+    transferId: string;
+    status: Extract<CopyJobStatus, "cancelled" | "success" | "failed" | "timeout">;
+    message: string;
+}
+/** Map engine progress callback → job progress fields. */
+export declare function engineProgressToJobProgress(p: CopyProgress, currentHopIndex?: number): CopyJobProgress;
+/** Async threshold policy (Agent + optional auto-route later). */
+export declare const DEFAULT_ASYNC_THRESHOLD: {
+    readonly sizeBytes: number;
+    readonly estimatedSeconds: 120;
+};
+export declare function shouldPreferAsyncCopy(input: {
+    sizeBytes?: number;
+    estimatedSeconds?: number;
+}): boolean;

package/dist/utils/copy-job-types.js

@@ -0,0 +1,37 @@
+export function isTerminalCopyJobStatus(status) {
+    return (status === "success" ||
+        status === "failed" ||
+        status === "cancelled" ||
+        status === "timeout");
+}
+/** Map engine progress callback → job progress fields. */
+export function engineProgressToJobProgress(p, currentHopIndex) {
+    const etaSeconds = p.speedBps && p.speedBps > 0 && p.total > p.transferred
+        ? Math.ceil((p.total - p.transferred) / p.speedBps)
+        : undefined;
+    return {
+        transferredBytes: p.transferred,
+        totalBytes: p.total,
+        percent: p.percent,
+        speedBps: p.speedBps,
+        etaSeconds,
+        skippedBytes: p.skippedBytes,
+        currentHopIndex,
+    };
+}
+/** Async threshold policy (Agent + optional auto-route later). */
+export const DEFAULT_ASYNC_THRESHOLD = {
+    sizeBytes: 256 * 1024 * 1024,
+    estimatedSeconds: 120,
+};
+export function shouldPreferAsyncCopy(input) {
+    if (input.sizeBytes !== undefined && input.sizeBytes > DEFAULT_ASYNC_THRESHOLD.sizeBytes) {
+        return true;
+    }
+    if (input.estimatedSeconds !== undefined &&
+        input.estimatedSeconds > DEFAULT_ASYNC_THRESHOLD.estimatedSeconds) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=copy-job-types.js.map

package/dist/utils/copy-job-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-job-types.js","sourceRoot":"","sources":["../../src/utils/copy-job-types.ts"],"names":[],"mappings":"AAqDA,MAAM,UAAU,uBAAuB,CACrC,MAAqB;IAErB,OAAO,CACL,MAAM,KAAK,SAAS;QACpB,MAAM,KAAK,QAAQ;QACnB,MAAM,KAAK,WAAW;QACtB,MAAM,KAAK,SAAS,CACrB,CAAC;AACJ,CAAC;AAoFD,0DAA0D;AAC1D,MAAM,UAAU,2BAA2B,CACzC,CAAe,EACf,eAAwB;IAExB,MAAM,UAAU,GACd,CAAC,CAAC,QAAQ,IAAI,CAAC,CAAC,QAAQ,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,WAAW;QACrD,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC;QACnD,CAAC,CAAC,SAAS,CAAC;IAChB,OAAO;QACL,gBAAgB,EAAE,CAAC,CAAC,WAAW;QAC/B,UAAU,EAAE,CAAC,CAAC,KAAK;QACnB,OAAO,EAAE,CAAC,CAAC,OAAO;QAClB,QAAQ,EAAE,CAAC,CAAC,QAAQ;QACpB,UAAU;QACV,YAAY,EAAE,CAAC,CAAC,YAAY;QAC5B,eAAe;KAChB,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACrC,SAAS,EAAE,GAAG,GAAG,IAAI,GAAG,IAAI;IAC5B,gBAAgB,EAAE,GAAG;CACb,CAAC;AAEX,MAAM,UAAU,qBAAqB,CAAC,KAGrC;IACC,IAAI,KAAK,CAAC,SAAS,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,GAAG,uBAAuB,CAAC,SAAS,EAAE,CAAC;QACzF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IACE,KAAK,CAAC,gBAAgB,KAAK,SAAS;QACpC,KAAK,CAAC,gBAAgB,GAAG,uBAAuB,CAAC,gBAAgB,EACjE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/utils/copy-transfer.d.ts

@@ -0,0 +1,59 @@
+export declare const DEFAULT_PROGRESS_INTERVAL_MS = 5000;
+export declare const DEFAULT_CONNECTION_TIMEOUT_MS = 20000;
+export type CopyVerifyMode = "none" | "size" | "size+sha256";
+export type CopySkipReason = "size-match" | "hash-match";
+export interface CopyProgress {
+    transferred: number;
+    total: number;
+    percent: number;
+    speedBps?: number;
+    /** Bytes already present at dest and counted as complete when skipIfComplete skipped a rewrite. */
+    skippedBytes?: number;
+}
+export interface SftpCopyOptions {
+    /** If true and destination already matches source (+ verify gate), skip rewrite. */
+    skipIfComplete?: boolean;
+    /** Progress callback throttle interval (default 5000). */
+    progressIntervalMs?: number;
+    /** Hard wall-clock limit for the whole Hop1 transfer. */
+    totalTimeoutMs?: number;
+    /** SSH connect readyTimeout for Hop1 SFTP (default 20000). */
+    connectionTimeoutMs?: number;
+    /**
+     * Skip gate + post-transfer verification (default size).
+     * With skipIfComplete: size = cheap size gate; size+sha256 = content gate; none is rejected.
+     */
+    verify?: CopyVerifyMode;
+    onProgress?: (progress: CopyProgress) => void;
+    /** Pre-assigned id; generated if omitted. */
+    transferId?: string;
+    /** Abort in-flight Hop1 transfer (ends SFTP session only). */
+    signal?: AbortSignal;
+}
+export interface SftpTransferResult {
+    bytes: number;
+    totalBytes: number;
+    skippedBytes: number;
+    /** True when any bytes were skipped via skipIfComplete. */
+    skipped: boolean;
+    /** Why skip was allowed (only when skipped). */
+    skipReason?: CopySkipReason;
+    transferId: string;
+    verified: boolean;
+    usedFastPath: boolean;
+}
+/**
+ * Single rule center for skip + verify.
+ * Does NOT auto-upgrade size → size+sha256 (checkpoint-friendly cheap skip).
+ */
+export declare function resolveEffectiveVerify(skipIfComplete: boolean, verify?: CopyVerifyMode): CopyVerifyMode;
+export declare function skipReasonForVerify(verify: CopyVerifyMode): CopySkipReason;
+/** Build skip observability fields from skipped byte count + verify mode. */
+export declare function transferSkipFields(skippedBytes: number, verify: CopyVerifyMode): Pick<SftpTransferResult, "skippedBytes" | "skipped" | "skipReason">;
+export declare function createTransferId(): string;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export declare function createProgressReporter(intervalMs: number, onProgress?: (progress: CopyProgress) => void, skippedBytes?: number): {
+    report: (transferred: number, total: number, force?: boolean) => void;
+    flush: (transferred: number, total: number) => void;
+};
+export declare function sha256File(filePath: string): Promise<string>;

package/dist/utils/copy-transfer.js

@@ -0,0 +1,86 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+export const DEFAULT_PROGRESS_INTERVAL_MS = 5_000;
+export const DEFAULT_CONNECTION_TIMEOUT_MS = 20_000;
+/**
+ * Single rule center for skip + verify.
+ * Does NOT auto-upgrade size → size+sha256 (checkpoint-friendly cheap skip).
+ */
+export function resolveEffectiveVerify(skipIfComplete, verify) {
+    const v = verify ?? "size";
+    if (skipIfComplete && v === "none") {
+        throw new Error("skipIfComplete requires verify=size or verify=size+sha256");
+    }
+    return v;
+}
+export function skipReasonForVerify(verify) {
+    return verify === "size+sha256" ? "hash-match" : "size-match";
+}
+/** Build skip observability fields from skipped byte count + verify mode. */
+export function transferSkipFields(skippedBytes, verify) {
+    if (skippedBytes > 0) {
+        return {
+            skippedBytes,
+            skipped: true,
+            skipReason: skipReasonForVerify(verify),
+        };
+    }
+    return { skippedBytes: 0, skipped: false };
+}
+export function createTransferId() {
+    return `copy-${Date.now().toString(36)}-${crypto.randomBytes(3).toString("hex")}`;
+}
+export function throwIfAborted(signal) {
+    if (signal?.aborted) {
+        throw new Error("Copy aborted");
+    }
+}
+export function createProgressReporter(intervalMs, onProgress, skippedBytes = 0) {
+    let lastReport = 0;
+    let lastBytes = skippedBytes;
+    let lastTs = Date.now();
+    const emit = (transferred, total) => {
+        if (!onProgress) {
+            return;
+        }
+        const now = Date.now();
+        const dt = Math.max(1, now - lastTs);
+        const speedBps = ((transferred - lastBytes) * 1000) / dt;
+        lastBytes = transferred;
+        lastTs = now;
+        lastReport = now;
+        onProgress({
+            transferred,
+            total,
+            percent: total > 0 ? Math.min(100, (transferred / total) * 100) : 0,
+            speedBps,
+            skippedBytes,
+        });
+    };
+    return {
+        report(transferred, total, force = false) {
+            if (!onProgress) {
+                return;
+            }
+            const now = Date.now();
+            if (!force && now - lastReport < intervalMs) {
+                return;
+            }
+            emit(transferred, total);
+        },
+        flush(transferred, total) {
+            emit(transferred, total);
+        },
+    };
+}
+export async function sha256File(filePath) {
+    const hash = crypto.createHash("sha256");
+    await new Promise((resolve, reject) => {
+        const stream = fs.createReadStream(filePath);
+        stream.on("data", (chunk) => hash.update(chunk));
+        stream.on("error", reject);
+        stream.on("end", () => resolve());
+    });
+    return hash.digest("hex");
+}
+//# sourceMappingURL=copy-transfer.js.map

package/dist/utils/copy-transfer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"copy-transfer.js","sourceRoot":"","sources":["../../src/utils/copy-transfer.ts"],"names":[],"mappings":"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"}

package/dist/utils/remote-copy.d.ts

@@ -0,0 +1,14 @@
+export interface FileEndpoint {
+    target: "landing" | "pod" | "host" | "local" | "context";
+    path: string;
+    contextKey?: string;
+    namespace?: string;
+    pod?: string;
+    container?: string;
+    host?: string;
+    user?: string;
+    password?: string;
+}
+/** Build a bash script (runs on accessClient) that copies source→dest and prints MCP_COPY_BYTES=<n>. */
+export declare function buildCopyFileCommand(source: FileEndpoint, dest: FileEndpoint, recursive: boolean, defaultUser?: string, defaultPassword?: string): string;
+export declare function parseCopyBytes(output: string): number | undefined;

package/dist/utils/remote-copy.js

@@ -0,0 +1,115 @@
+import { bashSingleQuote, buildHostTransportPrefix, buildSshRemoteCommand, } from "./shell-quote.js";
+import { resolveRemotePassword, resolveRemoteUser } from "./remote-target.js";
+function quotePath(path) {
+    return bashSingleQuote(path);
+}
+function kubectlCpFromPod(namespace, pod, remotePath, localPath, container) {
+    const remote = `${namespace}/${pod}:${remotePath}`;
+    const parts = ["kubectl cp", quotePath(remote), quotePath(localPath)];
+    if (container) {
+        parts.push("-c", quotePath(container));
+    }
+    return parts.join(" ");
+}
+function kubectlCpToPod(namespace, pod, localPath, remotePath, container) {
+    const remote = `${namespace}/${pod}:${remotePath}`;
+    const parts = ["kubectl cp", quotePath(localPath), quotePath(remote)];
+    if (container) {
+        parts.push("-c", quotePath(container));
+    }
+    return parts.join(" ");
+}
+function scpFromHost(user, host, remotePath, localPath, password) {
+    const remote = `${user}@${host}:${remotePath}`;
+    return `${buildHostTransportPrefix("scp", password)} -r ${quotePath(remote)} ${quotePath(localPath)}`;
+}
+function scpToHost(user, host, localPath, remotePath, password) {
+    const remote = `${user}@${host}:${remotePath}`;
+    return `${buildHostTransportPrefix("scp", password)} -r ${quotePath(localPath)} ${quotePath(remote)}`;
+}
+function cpOnLanding(sourcePath, destPath, recursive) {
+    const flag = recursive ? "-a" : "";
+    return `mkdir -p $(dirname ${quotePath(destPath)}) && cp ${flag} ${quotePath(sourcePath)} ${quotePath(destPath)}`.replace("  ", " ");
+}
+function statBytesCommand(path) {
+    return `stat -c%s ${quotePath(path)} 2>/dev/null || wc -c < ${quotePath(path)}`;
+}
+/** Remote host byte-stat via shared buildSshRemoteCommand (same password as scp). */
+function hostStatBytesEcho(user, host, path, password) {
+    const ssh = buildSshRemoteCommand(user, host, statBytesCommand(path), password);
+    return `echo MCP_COPY_BYTES=$(${ssh})`;
+}
+function hostUserPassword(endpoint, defaultUser, defaultPassword) {
+    return {
+        user: resolveRemoteUser(endpoint.user, defaultUser),
+        password: resolveRemotePassword(endpoint.password, defaultPassword),
+    };
+}
+/** Build a bash script (runs on accessClient) that copies source→dest and prints MCP_COPY_BYTES=<n>. */
+export function buildCopyFileCommand(source, dest, recursive, defaultUser, defaultPassword) {
+    const src = source.target;
+    const dst = dest.target;
+    if (src === "landing" && dst === "landing") {
+        return `${cpOnLanding(source.path, dest.path, recursive)} && echo MCP_COPY_BYTES=$( ${statBytesCommand(dest.path)} )`;
+    }
+    if (src === "pod" && dst === "landing") {
+        const pre = `mkdir -p $(dirname ${quotePath(dest.path)})`;
+        const cp = kubectlCpFromPod(source.namespace, source.pod, source.path, dest.path, source.container);
+        return `${pre} && ${cp} && echo MCP_COPY_BYTES=$( ${statBytesCommand(dest.path)} )`;
+    }
+    if (src === "landing" && dst === "pod") {
+        const mkdir = `kubectl exec -n ${quotePath(dest.namespace)} ${quotePath(dest.pod)}${dest.container ? ` -c ${quotePath(dest.container)}` : ""} -- bash -lc ${quotePath(`mkdir -p $(dirname '${dest.path.replace(/'/g, "'\\''")}')`)}`;
+        const cp = kubectlCpToPod(dest.namespace, dest.pod, source.path, dest.path, dest.container);
+        return `${mkdir} && ${cp} && echo MCP_COPY_BYTES=$(kubectl exec -n ${quotePath(dest.namespace)} ${quotePath(dest.pod)}${dest.container ? ` -c ${quotePath(dest.container)}` : ""} -- bash -lc ${quotePath(`stat -c%s '${dest.path.replace(/'/g, "'\\''")}' 2>/dev/null || wc -c < '${dest.path.replace(/'/g, "'\\''")}'`)} )`;
+    }
+    if (src === "host" && dst === "landing") {
+        const { user, password } = hostUserPassword(source, defaultUser, defaultPassword);
+        const pre = `mkdir -p $(dirname ${quotePath(dest.path)})`;
+        const cp = scpFromHost(user, source.host, source.path, dest.path, password);
+        return `${pre} && ${cp} && echo MCP_COPY_BYTES=$( ${statBytesCommand(dest.path)} )`;
+    }
+    if (src === "landing" && dst === "host") {
+        const { user, password } = hostUserPassword(dest, defaultUser, defaultPassword);
+        const cp = scpToHost(user, dest.host, source.path, dest.path, password);
+        return `${cp} && ${hostStatBytesEcho(user, dest.host, dest.path, password)}`;
+    }
+    // Cross-tier copies via landing temp directory
+    const tmpVar = "MCP_COPY_TMP";
+    const setup = `${tmpVar}=$(mktemp -d) && trap 'rm -rf "$${tmpVar}"' EXIT`;
+    const tmpItem = `$${tmpVar}/item`;
+    if (src === "pod" && dst === "pod") {
+        const pull = kubectlCpFromPod(source.namespace, source.pod, source.path, tmpItem, source.container);
+        const push = kubectlCpToPod(dest.namespace, dest.pod, tmpItem, dest.path, dest.container);
+        const stat = `echo MCP_COPY_BYTES=$(kubectl exec -n ${quotePath(dest.namespace)} ${quotePath(dest.pod)}${dest.container ? ` -c ${quotePath(dest.container)}` : ""} -- bash -lc ${quotePath(`stat -c%s '${dest.path.replace(/'/g, "'\\''")}' 2>/dev/null || wc -c < '${dest.path.replace(/'/g, "'\\''")}'`)} )`;
+        return `${setup} && ${pull} && ${push} && ${stat}`;
+    }
+    if (src === "pod" && dst === "host") {
+        const { user, password } = hostUserPassword(dest, defaultUser, defaultPassword);
+        const pull = kubectlCpFromPod(source.namespace, source.pod, source.path, tmpItem, source.container);
+        const push = scpToHost(user, dest.host, tmpItem, dest.path, password);
+        return `${setup} && ${pull} && ${push} && ${hostStatBytesEcho(user, dest.host, dest.path, password)}`;
+    }
+    if (src === "host" && dst === "pod") {
+        const { user, password } = hostUserPassword(source, defaultUser, defaultPassword);
+        const pull = scpFromHost(user, source.host, source.path, tmpItem, password);
+        const push = kubectlCpToPod(dest.namespace, dest.pod, tmpItem, dest.path, dest.container);
+        const stat = `echo MCP_COPY_BYTES=$(kubectl exec -n ${quotePath(dest.namespace)} ${quotePath(dest.pod)}${dest.container ? ` -c ${quotePath(dest.container)}` : ""} -- bash -lc ${quotePath(`stat -c%s '${dest.path.replace(/'/g, "'\\''")}' 2>/dev/null || wc -c < '${dest.path.replace(/'/g, "'\\''")}'`)} )`;
+        return `${setup} && ${pull} && ${push} && ${stat}`;
+    }
+    if (src === "host" && dst === "host") {
+        const srcAuth = hostUserPassword(source, defaultUser, defaultPassword);
+        const dstAuth = hostUserPassword(dest, defaultUser, defaultPassword);
+        const pull = scpFromHost(srcAuth.user, source.host, source.path, tmpItem, srcAuth.password);
+        const push = scpToHost(dstAuth.user, dest.host, tmpItem, dest.path, dstAuth.password);
+        return `${setup} && ${pull} && ${push} && ${hostStatBytesEcho(dstAuth.user, dest.host, dest.path, dstAuth.password)}`;
+    }
+    throw new Error(`Unsupported copy route: ${src} → ${dst}`);
+}
+export function parseCopyBytes(output) {
+    const match = output.match(/MCP_COPY_BYTES=(\d+)/);
+    if (!match) {
+        return undefined;
+    }
+    return Number.parseInt(match[1], 10);
+}
+//# sourceMappingURL=remote-copy.js.map

package/dist/utils/remote-copy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-copy.js","sourceRoot":"","sources":["../../src/utils/remote-copy.ts"],"names":[],"mappings":"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"}

package/dist/utils/remote-executor.d.ts

@@ -0,0 +1,15 @@
+import type { AppConfig } from "../config.js";
+import type { AccessRuntime } from "../access/index.js";
+import type { KubectlRunner } from "../kubectl/runner.js";
+import type { RemoteTarget } from "../tools/remote-schemas.js";
+/**
+ * Runtime routing: landing / pod / context.
+ * context path = shellExec on derived Context by contextKey.
+ */
+export declare class RemoteExecutor {
+    private readonly access;
+    private readonly kubectl;
+    private readonly config;
+    constructor(access: AccessRuntime, kubectl: KubectlRunner, config: AppConfig);
+    runOnTarget(target: RemoteTarget, command: string, timeoutMs?: number): Promise<import("../ssh/access-client.js").ExecOutput>;
+}

package/dist/utils/remote-executor.js

@@ -0,0 +1,34 @@
+/**
+ * Runtime routing: landing / pod / context.
+ * context path = shellExec on derived Context by contextKey.
+ */
+export class RemoteExecutor {
+    access;
+    kubectl;
+    config;
+    constructor(access, kubectl, config) {
+        this.access = access;
+        this.kubectl = kubectl;
+        this.config = config;
+    }
+    async runOnTarget(target, command, timeoutMs) {
+        switch (target.target) {
+            case "landing":
+                return this.access.shellExec(command, {
+                    timeoutMs: timeoutMs ?? this.config.defaultTimeoutMs,
+                });
+            case "context":
+                return this.access.shellExec(command, {
+                    contextKey: target.contextKey,
+                    timeoutMs: timeoutMs ?? this.config.defaultTimeoutMs,
+                });
+            case "pod":
+                return this.kubectl.exec(target.namespace, target.pod, command, target.container, timeoutMs);
+            default: {
+                const exhaustive = target;
+                throw new Error(`Unsupported target: ${String(exhaustive)}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=remote-executor.js.map

package/dist/utils/remote-executor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-executor.js","sourceRoot":"","sources":["../../src/utils/remote-executor.ts"],"names":[],"mappings":"AAKA;;;GAGG;AACH,MAAM,OAAO,cAAc;IAEN;IACA;IACA;IAHnB,YACmB,MAAqB,EACrB,OAAsB,EACtB,MAAiB;QAFjB,WAAM,GAAN,MAAM,CAAe;QACrB,YAAO,GAAP,OAAO,CAAe;QACtB,WAAM,GAAN,MAAM,CAAW;IACjC,CAAC;IAEJ,KAAK,CAAC,WAAW,CACf,MAAoB,EACpB,OAAe,EACf,SAAkB;QAElB,QAAQ,MAAM,CAAC,MAAM,EAAE,CAAC;YACtB,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE;oBACpC,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB;iBACrD,CAAC,CAAC;YACL,KAAK,SAAS;gBACZ,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE;oBACpC,UAAU,EAAE,MAAM,CAAC,UAAU;oBAC7B,SAAS,EAAE,SAAS,IAAI,IAAI,CAAC,MAAM,CAAC,gBAAgB;iBACrD,CAAC,CAAC;YACL,KAAK,KAAK;gBACR,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CACtB,MAAM,CAAC,SAAS,EAChB,MAAM,CAAC,GAAG,EACV,OAAO,EACP,MAAM,CAAC,SAAS,EAChB,SAAS,CACV,CAAC;YACJ,OAAO,CAAC,CAAC,CAAC;gBACR,MAAM,UAAU,GAAU,MAAM,CAAC;gBACjC,MAAM,IAAI,KAAK,CAAC,uBAAuB,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;YAC/D,CAAC;QACH,CAAC;IACH,CAAC;CACF"}

package/dist/utils/remote-target.d.ts

@@ -0,0 +1,22 @@
+export declare function resolveRemotePassword(password: string | undefined, defaultPassword: string | undefined): string | undefined;
+export declare function resolveRemoteUser(user: string | undefined, defaultUser: string | undefined): string;
+export declare function buildReadFileCommand(path: string, maxLines: number, offset?: number): string;
+/** Read file with MCP_META prefix (total lines/bytes) before content. */
+export declare function buildReadFileWithMetaCommand(path: string, maxLines: number, offset?: number): string;
+export interface ReadFileMeta {
+    totalLines?: number;
+    totalBytes?: number;
+}
+export declare function parseReadFileMeta(output: string): {
+    meta: ReadFileMeta;
+    content: string;
+};
+export declare function buildTailFileWithMetaCommand(path: string, lines: number, grep?: string): string;
+export declare function buildRemoteReadCommand(path: string, options: {
+    mode: "head" | "tail";
+    lines: number;
+    offset?: number;
+    grep?: string;
+}): string;
+export declare function buildTailFileCommand(path: string, lines: number, grep?: string): string;
+export declare function buildPsCommand(pattern?: string): string;

package/dist/utils/remote-target.js

@@ -0,0 +1,75 @@
+export function resolveRemotePassword(password, defaultPassword) {
+    // Do not trim — passwords may intentionally include leading/trailing spaces.
+    if (password !== undefined && password !== "") {
+        return password;
+    }
+    if (defaultPassword !== undefined && defaultPassword !== "") {
+        return defaultPassword;
+    }
+    return undefined;
+}
+export function resolveRemoteUser(user, defaultUser) {
+    const resolved = user?.trim() || defaultUser?.trim();
+    if (!resolved) {
+        throw new Error('ssh_exec and host-target tools require "user" parameter or TARGET_USER environment variable. Do not assume root.');
+    }
+    return resolved;
+}
+export function buildReadFileCommand(path, maxLines, offset) {
+    const safePath = path.replace(/'/g, "'\\''");
+    if (offset && offset > 1) {
+        return `sed -n '${offset},${offset + maxLines - 1}p' '${safePath}' 2>/dev/null || head -n ${offset + maxLines - 1} '${safePath}' | tail -n ${maxLines}`;
+    }
+    return `head -n ${maxLines} '${safePath}'`;
+}
+/** Read file with MCP_META prefix (total lines/bytes) before content. */
+export function buildReadFileWithMetaCommand(path, maxLines, offset) {
+    const safePath = path.replace(/'/g, "'\\''");
+    const meta = `echo "MCP_META lines=$(wc -l < '${safePath}' 2>/dev/null | tr -d ' ') bytes=$(wc -c < '${safePath}' 2>/dev/null | tr -d ' ')"`;
+    const read = buildReadFileCommand(path, maxLines, offset);
+    return `${meta} && ${read}`;
+}
+const META_PATTERN = /^MCP_META lines=(\d+) bytes=(\d+)/;
+export function parseReadFileMeta(output) {
+    const lines = output.split("\n");
+    const first = lines[0] ?? "";
+    const match = first.match(META_PATTERN);
+    if (!match) {
+        return { meta: {}, content: output };
+    }
+    return {
+        meta: {
+            totalLines: Number.parseInt(match[1], 10),
+            totalBytes: Number.parseInt(match[2], 10),
+        },
+        content: lines.slice(1).join("\n"),
+    };
+}
+export function buildTailFileWithMetaCommand(path, lines, grep) {
+    const safePath = path.replace(/'/g, "'\\''");
+    const meta = `echo "MCP_META lines=$(wc -l < '${safePath}' 2>/dev/null | tr -d ' ') bytes=$(wc -c < '${safePath}' 2>/dev/null | tr -d ' ')"`;
+    const tail = buildTailFileCommand(path, lines, grep);
+    return `${meta} && ${tail}`;
+}
+export function buildRemoteReadCommand(path, options) {
+    if (options.mode === "tail") {
+        return buildTailFileWithMetaCommand(path, options.lines, options.grep);
+    }
+    return buildReadFileWithMetaCommand(path, options.lines, options.offset);
+}
+export function buildTailFileCommand(path, lines, grep) {
+    const safePath = path.replace(/'/g, "'\\''");
+    if (grep) {
+        const safeGrep = grep.replace(/'/g, "'\\''");
+        return `grep -i '${safeGrep}' '${safePath}' | tail -n ${lines}`;
+    }
+    return `tail -n ${lines} '${safePath}'`;
+}
+export function buildPsCommand(pattern) {
+    if (pattern) {
+        const safePattern = pattern.replace(/'/g, "'\\''");
+        return `ps aux | grep -F '${safePattern}' | grep -v grep || true`;
+    }
+    return "ps aux";
+}
+//# sourceMappingURL=remote-target.js.map

package/dist/utils/remote-target.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote-target.js","sourceRoot":"","sources":["../../src/utils/remote-target.ts"],"names":[],"mappings":"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"}