@span-io/agent-link 0.1.5 → 0.2.0

package/dist/index.js

@@ -1,12 +1,16 @@
 #!/usr/bin/env node
 import os from "os";
 import process from "process";
+import path from "path";
+import { access } from "fs/promises";
+import { constants as fsConstants } from "fs";
 import { loadConfig, saveConfig } from "./config.js";
 import { findAgentsOnPath, resolveAgentBinary } from "./agent.js";
 import { spawnAgentProcess as spawnAgentProcessAdvanced } from "./process-runner.js";
 import { LogBuffer } from "./log-buffer.js";
 import { compactPrompt, resolvePromptCompactionPolicy } from "./prompt-compact.js";
 import { BootstrapRunner } from "./bootstrap.js";
+import { RemoteCommandRunner } from "./remote-command.js";
 import { NoopTransport, WebSocketTransport } from "./transport.js";
 const args = parseArgs(process.argv.slice(2));
 if (args.list) {
@@ -47,6 +51,7 @@ const logBuffer = new LogBuffer();
 const activeAgents = new Map();
 const promptPolicy = resolvePromptCompactionPolicy();
 const bootstrapRunner = new BootstrapRunner();
+const remoteCommandRunner = new RemoteCommandRunner();
 let transport;
 try {
     transport = await createTransport({
@@ -67,6 +72,14 @@ function handleControl(message) {
         void bootstrapRunner.run(payload ?? {}, transport);
         return;
     }
+    if (action === "check_file") {
+        void runRemoteFileCheck(payload ?? {}, transport);
+        return;
+    }
+    if (action === "execute_command") {
+        void runRemoteCommand(payload ?? {}, transport);
+        return;
+    }
     if (!agentId)
         return;
     switch (action) {
@@ -166,6 +179,41 @@ function handleControl(message) {
         }
     }
 }
+async function runRemoteFileCheck(payload, transport) {
+    const runId = typeof payload.runId === "string" ? payload.runId.trim() : "";
+    if (!runId) {
+        return;
+    }
+    const workingDirectory = typeof payload.workingDirectory === "string" ? payload.workingDirectory.trim() : "";
+    if (!workingDirectory) {
+        transport.sendPreflight(runId, "error", false, "Missing workingDirectory.");
+        return;
+    }
+    const filePath = typeof payload.filePath === "string" && payload.filePath.trim().length > 0
+        ? payload.filePath.trim()
+        : "AGENTS.md";
+    const baseDir = path.resolve(workingDirectory);
+    const target = path.resolve(baseDir, filePath);
+    const relative = path.relative(baseDir, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative)) {
+        transport.sendPreflight(runId, "error", false, "Invalid filePath outside working directory.");
+        return;
+    }
+    try {
+        await access(target, fsConstants.F_OK);
+        transport.sendPreflight(runId, "complete", true, filePath + " exists.");
+    }
+    catch {
+        transport.sendPreflight(runId, "complete", false, filePath + " not found.");
+    }
+}
+async function runRemoteCommand(payload, transport) {
+    await remoteCommandRunner.run(payload, {
+        sendCommand: (requestId, status, details) => {
+            transport.sendCommand(requestId, status, details);
+        },
+    });
+}
 function setupAgentPiping(agentId, proc) {
     const rawFlushSize = Number.parseInt(process.env.AGENT_LINK_STREAM_FLUSH_CHARS ?? "16384", 10);
     const flushSize = Number.isFinite(rawFlushSize) && rawFlushSize > 0 ? rawFlushSize : 16384;

package/dist/remote-command.js

@@ -0,0 +1,203 @@
+import { spawn } from "child_process";
+import path from "path";
+import process from "process";
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000;
+const MAX_TIMEOUT_MS = 15 * 60 * 1000;
+const DEFAULT_ALLOWED_COMMANDS = ["ls", "pwd", "cat", "find", "git", "node", "npx", "npm"];
+const MAX_ARGS = 128;
+const MAX_ARG_LEN = 4096;
+const DEFAULT_MAX_OUTPUT_CHARS = 64_000;
+function parseCsvList(value, fallback) {
+    if (!value || !value.trim()) {
+        return new Set(fallback);
+    }
+    const entries = value
+        .split(",")
+        .map((part) => part.trim())
+        .filter((part) => part.length > 0);
+    return new Set(entries.length > 0 ? entries : fallback);
+}
+function parseAllowedRoots() {
+    const raw = process.env.AGENT_LINK_ALLOWED_WORKDIR_ROOTS?.trim();
+    if (!raw) {
+        return [];
+    }
+    return raw
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean)
+        .map((entry) => path.resolve(entry));
+}
+function isUnderRoot(candidate, root) {
+    const rel = path.relative(root, candidate);
+    return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+function assertAllowedDirectory(directory, allowedRoots) {
+    if (allowedRoots.length === 0) {
+        return;
+    }
+    const resolved = path.resolve(directory);
+    const allowed = allowedRoots.some((root) => isUnderRoot(resolved, root));
+    if (!allowed) {
+        throw new Error(`Requested directory '${resolved}' is outside AGENT_LINK_ALLOWED_WORKDIR_ROOTS (${allowedRoots.join(", ")}).`);
+    }
+}
+export function normalizeRemoteCommandPayload(payload, commandAllowlist) {
+    const requestId = typeof payload?.requestId === "string" ? payload.requestId.trim() : "";
+    if (!requestId) {
+        return { ok: false, error: "Missing requestId." };
+    }
+    const command = typeof payload?.command === "string" ? payload.command.trim() : "";
+    if (!command) {
+        return { ok: false, requestId, error: "Missing command." };
+    }
+    if (!commandAllowlist.has(command)) {
+        return {
+            ok: false,
+            requestId,
+            error: `Command \"${command}\" is not allowed by AGENT_LINK_REMOTE_COMMAND_ALLOWLIST.`,
+        };
+    }
+    const rawArgs = Array.isArray(payload?.args) ? payload.args : [];
+    const args = rawArgs
+        .filter((arg) => typeof arg === "string")
+        .map((arg) => arg.trim())
+        .filter((arg) => arg.length > 0);
+    if (args.length > MAX_ARGS) {
+        return { ok: false, requestId, error: `Command args exceed max count (${MAX_ARGS}).` };
+    }
+    for (const arg of args) {
+        if (arg.length > MAX_ARG_LEN) {
+            return { ok: false, requestId, error: `Command arg exceeds max length (${MAX_ARG_LEN}).` };
+        }
+    }
+    const workingDirectoryRaw = typeof payload?.workingDirectory === "string" ? payload.workingDirectory.trim() : "";
+    const workingDirectory = path.resolve(workingDirectoryRaw || process.cwd());
+    const allowedRoots = parseAllowedRoots();
+    try {
+        assertAllowedDirectory(workingDirectory, allowedRoots);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            requestId,
+            error: error instanceof Error ? error.message : "Invalid workingDirectory.",
+        };
+    }
+    const requestedTimeout = typeof payload?.timeoutMs === "number" && Number.isFinite(payload.timeoutMs)
+        ? payload.timeoutMs
+        : DEFAULT_TIMEOUT_MS;
+    const timeoutMs = Math.min(Math.max(requestedTimeout, 1), MAX_TIMEOUT_MS);
+    return {
+        ok: true,
+        value: {
+            requestId,
+            command,
+            args,
+            workingDirectory,
+            timeoutMs,
+        },
+    };
+}
+export class RemoteCommandRunner {
+    deps;
+    commandAllowlist;
+    maxOutputChars;
+    constructor(deps = {}, options = {}) {
+        this.deps = {
+            spawnFn: deps.spawnFn ??
+                ((command, args, spawnOptions) => spawn(command, args, spawnOptions)),
+        };
+        this.commandAllowlist =
+            options.commandAllowlist ??
+                parseCsvList(process.env.AGENT_LINK_REMOTE_COMMAND_ALLOWLIST, DEFAULT_ALLOWED_COMMANDS);
+        const configuredMax = Number.parseInt(process.env.AGENT_LINK_COMMAND_MAX_OUTPUT_CHARS ?? "", 10);
+        this.maxOutputChars =
+            options.maxOutputChars ??
+                (Number.isFinite(configuredMax) && configuredMax > 0 ? configuredMax : DEFAULT_MAX_OUTPUT_CHARS);
+    }
+    async run(payload, transport) {
+        const normalized = normalizeRemoteCommandPayload(payload, this.commandAllowlist);
+        if (!normalized.ok) {
+            if (normalized.requestId) {
+                transport.sendCommand(normalized.requestId, "error", { message: normalized.error });
+            }
+            return;
+        }
+        const request = normalized.value;
+        transport.sendCommand(request.requestId, "started", {
+            message: `Running command: ${request.command} ${request.args.join(" ")} (cwd=${request.workingDirectory})`,
+        });
+        await this.runProcess(request, transport);
+    }
+    async runProcess(request, transport) {
+        await new Promise((resolve) => {
+            let child;
+            try {
+                child = this.deps.spawnFn(request.command, request.args, {
+                    cwd: request.workingDirectory,
+                    env: {
+                        ...process.env,
+                    },
+                    shell: false,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "unknown error";
+                transport.sendCommand(request.requestId, "error", { message: `Command process error: ${message}` });
+                resolve();
+                return;
+            }
+            let settled = false;
+            let stdout = "";
+            let stderr = "";
+            const appendClamped = (current, incoming) => {
+                const merged = current + incoming;
+                if (merged.length <= this.maxOutputChars) {
+                    return merged;
+                }
+                return merged.slice(-this.maxOutputChars);
+            };
+            const complete = (status, details = {}) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                transport.sendCommand(request.requestId, status, {
+                    exitCode: details.exitCode,
+                    stdout,
+                    stderr,
+                    message: details.message,
+                });
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                complete("error", { message: `Command timed out after ${request.timeoutMs}ms.` });
+            }, request.timeoutMs);
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (chunk) => {
+                stdout = appendClamped(stdout, chunk);
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr = appendClamped(stderr, chunk);
+            });
+            child.on("error", (error) => {
+                complete("error", { message: `Command process error: ${error.message}` });
+            });
+            child.on("exit", (code, signal) => {
+                if (code === 0) {
+                    complete("completed", { exitCode: 0 });
+                    return;
+                }
+                complete("error", {
+                    exitCode: code ?? undefined,
+                    message: `Command exited with code ${String(code ?? "null")} signal ${String(signal ?? "null")}.`,
+                });
+            });
+        });
+    }
+}

package/dist/transport.js

@@ -35,6 +35,12 @@ export class NoopTransport {
     sendBootstrap(_runId, _status, _message) {
         return undefined;
     }
+    sendPreflight(_runId, _status, _exists, _message) {
+        return undefined;
+    }
+    sendCommand(_requestId, _status, _details) {
+        return undefined;
+    }
     close() {
         return undefined;
     }
@@ -188,6 +194,31 @@ export class WebSocketTransport {
             },
         }));
     }
+    sendPreflight(runId, status, exists, message) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        this.socket.send(JSON.stringify({
+            type: "preflight",
+            payload: {
+                runId,
+                status,
+                exists,
+                message,
+            },
+        }));
+    }
+    sendCommand(requestId, status, details) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        this.socket.send(JSON.stringify({
+            type: "command",
+            payload: {
+                requestId,
+                status,
+                ...details,
+            },
+        }));
+    }
     close() {
         this.isExplicitClose = true;
         this.stopPingInterval();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@span-io/agent-link",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Secure bridge between Span (AI control plane) and local agent CLI tools.",
   "type": "module",
   "bin": {