@span-io/agent-link 0.1.4 → 0.2.0

package/dist/bootstrap.js

@@ -0,0 +1,192 @@
+import { spawn } from "child_process";
+import process from "process";
+import { mkdir } from "fs/promises";
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+const MAX_TIMEOUT_MS = 20 * 60 * 1000;
+const DEFAULT_ALLOWED_COMMANDS = ["npx", "npm"];
+const DEFAULT_ALLOWED_ENV = ["CI", "NODE_ENV", "NPM_CONFIG_YES"];
+const MAX_ARGS = 128;
+const MAX_ARG_LEN = 4096;
+export 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);
+}
+export function sanitizeBootstrapEnv(input, allowed) {
+    if (!input) {
+        return {};
+    }
+    const sanitized = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (!allowed.has(key)) {
+            continue;
+        }
+        if (typeof value !== "string") {
+            continue;
+        }
+        const trimmed = value.trim();
+        if (!trimmed || trimmed.length > MAX_ARG_LEN) {
+            continue;
+        }
+        sanitized[key] = trimmed;
+    }
+    return sanitized;
+}
+export function normalizeBootstrapPayload(payload, commandAllowlist, envAllowlist) {
+    const runId = typeof payload?.runId === "string" ? payload.runId.trim() : "";
+    if (!runId) {
+        return { ok: false, error: "Missing runId." };
+    }
+    const workingDirectory = typeof payload?.workingDirectory === "string" ? payload.workingDirectory.trim() : "";
+    if (!workingDirectory) {
+        return { ok: false, error: "Missing workingDirectory." };
+    }
+    const command = typeof payload?.command === "string" && payload.command.trim().length > 0
+        ? payload.command.trim()
+        : "npx";
+    if (!commandAllowlist.has(command)) {
+        return {
+            ok: false,
+            error: `Bootstrap command \"${command}\" is not allowed.`,
+        };
+    }
+    const argsRaw = Array.isArray(payload?.args) ? payload.args : [];
+    const args = argsRaw
+        .filter((arg) => typeof arg === "string")
+        .map((arg) => arg.trim())
+        .filter((arg) => arg.length > 0);
+    if (args.length > MAX_ARGS) {
+        return { ok: false, error: `Bootstrap args exceed max count (${MAX_ARGS}).` };
+    }
+    for (const arg of args) {
+        if (arg.length > MAX_ARG_LEN) {
+            return { ok: false, error: `Bootstrap arg exceeds max length (${MAX_ARG_LEN}).` };
+        }
+    }
+    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);
+    const env = sanitizeBootstrapEnv(payload?.env, envAllowlist);
+    return {
+        ok: true,
+        value: {
+            runId,
+            workingDirectory,
+            command,
+            args,
+            timeoutMs,
+            env,
+        },
+    };
+}
+export class BootstrapRunner {
+    deps;
+    activeRunId = null;
+    commandAllowlist;
+    envAllowlist;
+    constructor(deps = {}, options = {}) {
+        this.deps = {
+            mkdirFn: deps.mkdirFn ?? (async (path) => {
+                await mkdir(path, { recursive: true });
+            }),
+            spawnFn: deps.spawnFn ??
+                ((command, args, options) => spawn(command, args, options)),
+        };
+        this.commandAllowlist =
+            options.commandAllowlist ??
+                parseCsvList(process.env.AGENT_LINK_BOOTSTRAP_ALLOWED_COMMANDS, DEFAULT_ALLOWED_COMMANDS);
+        this.envAllowlist =
+            options.envAllowlist ??
+                parseCsvList(process.env.AGENT_LINK_BOOTSTRAP_ALLOWED_ENV, DEFAULT_ALLOWED_ENV);
+    }
+    async run(payload, transport) {
+        const normalized = normalizeBootstrapPayload(payload, this.commandAllowlist, this.envAllowlist);
+        if (!normalized.ok) {
+            const runId = typeof payload?.runId === "string" ? payload.runId.trim() : "";
+            if (runId) {
+                transport.sendBootstrap(runId, "error", normalized.error);
+            }
+            return;
+        }
+        const request = normalized.value;
+        if (this.activeRunId) {
+            transport.sendBootstrap(request.runId, "error", `Bootstrap already running for run ${this.activeRunId}.`);
+            return;
+        }
+        this.activeRunId = request.runId;
+        try {
+            await this.deps.mkdirFn(request.workingDirectory);
+            transport.sendBootstrap(request.runId, "started", `Running bootstrap command: ${request.command} ${request.args.join(" ")} (cwd=${request.workingDirectory})`);
+            await this.runProcess(request, transport);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "unknown error";
+            transport.sendBootstrap(request.runId, "error", `Bootstrap failed: ${message}`);
+        }
+        finally {
+            if (this.activeRunId === request.runId) {
+                this.activeRunId = null;
+            }
+        }
+    }
+    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,
+                        ...request.env,
+                    },
+                    shell: false,
+                    stdio: ["ignore", "pipe", "pipe"],
+                });
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : "unknown error";
+                transport.sendBootstrap(request.runId, "error", `Bootstrap process error: ${message}`);
+                resolve();
+                return;
+            }
+            let settled = false;
+            const complete = (status, message) => {
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                clearTimeout(timer);
+                transport.sendBootstrap(request.runId, status, message);
+                resolve();
+            };
+            const timer = setTimeout(() => {
+                child.kill("SIGKILL");
+                complete("error", `Bootstrap timed out after ${request.timeoutMs}ms.`);
+            }, request.timeoutMs);
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (chunk) => {
+                transport.sendBootstrap(request.runId, "log", chunk);
+            });
+            child.stderr?.on("data", (chunk) => {
+                transport.sendBootstrap(request.runId, "log", chunk);
+            });
+            child.on("error", (error) => {
+                complete("error", `Bootstrap process error: ${error.message}`);
+            });
+            child.on("exit", (code, signal) => {
+                if (code === 0) {
+                    complete("complete", "Bootstrap completed successfully.");
+                    return;
+                }
+                complete("error", `Bootstrap exited with code ${String(code ?? "null")} signal ${String(signal ?? "null")}.`);
+            });
+        });
+    }
+}

package/dist/config.js

@@ -42,4 +42,10 @@ export function saveConfig(config) {
         }
     }
     fs.writeFileSync(CONFIG_FILE, JSON.stringify(toSave, null, 2), "utf8");
+    try {
+        fs.chmodSync(CONFIG_FILE, 0o600);
+    }
+    catch (error) {
+        console.warn("Failed to set secure permissions on config file:", error);
+    }
 }

package/dist/index.js

@@ -1,11 +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) {
@@ -45,6 +50,8 @@ const logBuffer = new LogBuffer();
 // Update map to hold SpawnedProcess which includes the child
 const activeAgents = new Map();
 const promptPolicy = resolvePromptCompactionPolicy();
+const bootstrapRunner = new BootstrapRunner();
+const remoteCommandRunner = new RemoteCommandRunner();
 let transport;
 try {
     transport = await createTransport({
@@ -61,6 +68,18 @@ catch (error) {
 }
 function handleControl(message) {
     const { action, agentId, payload } = message;
+    if (action === "bootstrap") {
+        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) {
@@ -160,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/process-runner.js

@@ -1,4 +1,5 @@
 import { mkdirSync } from "fs";
+import path from "path";
 import { spawn } from "child_process";
 const DEFAULT_CODEX_ARGS = "exec --skip-git-repo-check";
 const DEFAULT_GEMINI_ARGS = "";
@@ -11,7 +12,32 @@ function splitArgs(raw) {
 }
 function shellQuote(value) {
     // Simple single-quote wrapping for display purposes
-    return `'${value.replace(/'/g, `'"'"'`)}'`;
+    return `'${value.replace(/'/g, `"'"'`)}'`;
+}
+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, label) {
+    if (allowedRoots.length === 0) {
+        return;
+    }
+    const resolved = path.resolve(directory);
+    const allowed = allowedRoots.some((root) => isUnderRoot(resolved, root));
+    if (!allowed) {
+        throw new Error(`${label} '${resolved}' is outside AGENT_LINK_ALLOWED_WORKDIR_ROOTS (${allowedRoots.join(", ")}).`);
+    }
 }
 function collectDirectoriesFromArgs(args) {
     const directories = [];
@@ -43,17 +69,19 @@ function collectDirectoriesFromArgs(args) {
     }
     return directories;
 }
-function ensureDirectoriesExist(rawDirs) {
+function ensureDirectoriesExist(rawDirs, allowedRoots) {
     const deduped = new Set(rawDirs
         .map((entry) => entry.trim())
         .filter((entry) => entry.length > 0));
     for (const dir of deduped) {
+        const resolved = path.resolve(dir);
+        assertAllowedDirectory(resolved, allowedRoots, "Requested directory");
         try {
-            mkdirSync(dir, { recursive: true });
+            mkdirSync(resolved, { recursive: true });
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            throw new Error(`Failed to create working directory '${dir}': ${message}`);
+            throw new Error(`Failed to create working directory '${resolved}': ${message}`);
         }
     }
 }
@@ -133,16 +161,18 @@ export function spawnAgentProcess(config) {
     const startedAt = new Date().toISOString();
     const isCodexModel = !agent.model.startsWith("gemini-") && !agent.model.startsWith("claude-");
     const sanitizedOptions = optionsArgs;
+    const allowedRoots = parseAllowedRoots();
     const spawnWithMode = (promptModeOverride) => {
         const { command, args, promptMode } = buildCommand({ ...config, optionsArgs: sanitizedOptions }, promptModeOverride);
         // Ensure requested project/working directories exist before launching CLI.
-        ensureDirectoriesExist(collectDirectoriesFromArgs(args));
+        ensureDirectoriesExist(collectDirectoriesFromArgs(args), allowedRoots);
         const ttyMode = process.env.CODEX_TTY_MODE ?? DEFAULT_TTY_MODE;
         const hasExec = args.includes("exec");
         const useScriptWrapper = ttyMode === "script" || (ttyMode === "auto" && hasExec);
         const ttyTerm = process.env.CODEX_TTY_TERM ?? DEFAULT_TTY_TERM;
         const defaultCwd = process.cwd(); // Client uses current working dir
         const workingDir = process.env.CODEX_CWD ?? defaultCwd;
+        assertAllowedDirectory(workingDir, allowedRoots, "Spawn cwd");
         // For logging/display
         const commandString = [command, ...args].map(shellQuote).join(" ");
         const platform = process.platform;

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

@@ -1,5 +1,27 @@
 import { encodeEnvelope, nowIso } from "./protocol.js";
 import os from "os";
+const LOCAL_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+function isTruthyEnv(value) {
+    const normalized = value?.trim().toLowerCase();
+    return normalized === "1" || normalized === "true" || normalized === "yes" || normalized === "on";
+}
+function assertSecureTransport(url) {
+    const allowInsecure = isTruthyEnv(process.env.AGENT_LINK_ALLOW_INSECURE_TRANSPORT);
+    const isLocal = LOCAL_HOSTS.has(url.hostname.toLowerCase());
+    if (url.protocol === "https:" || url.protocol === "wss:") {
+        return;
+    }
+    if ((url.protocol === "http:" || url.protocol === "ws:") && (allowInsecure || isLocal)) {
+        return;
+    }
+    throw new Error("Insecure transport is blocked. Use https:// (or set AGENT_LINK_ALLOW_INSECURE_TRANSPORT=1 for explicit local override).");
+}
+function toDisplayUrl(url) {
+    const clone = new URL(url.toString());
+    clone.search = "";
+    clone.hash = "";
+    return clone.toString();
+}
 export class NoopTransport {
     async connect() {
         return undefined;
@@ -10,6 +32,15 @@ export class NoopTransport {
     sendStatus(_agentId, _state) {
         return undefined;
     }
+    sendBootstrap(_runId, _status, _message) {
+        return undefined;
+    }
+    sendPreflight(_runId, _status, _exists, _message) {
+        return undefined;
+    }
+    sendCommand(_requestId, _status, _details) {
+        return undefined;
+    }
     close() {
         return undefined;
     }
@@ -52,6 +83,7 @@ export class WebSocketTransport {
             return;
         }
         const url = new URL("/api/ws", serverUrl);
+        assertSecureTransport(url);
         url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
         url.searchParams.set("token", token);
         return new Promise((resolve, reject) => {
@@ -62,7 +94,7 @@ export class WebSocketTransport {
                 this.socket.onopen = null;
                 this.socket.close();
             }
-            console.log(`Connecting to ${url.toString()}...`);
+            console.log(`Connecting to ${toDisplayUrl(url)}...`);
             const socket = new WebSocket(url.toString());
             this.socket = socket;
             const onOpen = () => {
@@ -82,7 +114,7 @@ export class WebSocketTransport {
                 };
                 resolve();
             };
-            const onFail = (err) => {
+            const onFail = (_err) => {
                 console.error("WebSocket connection failed to open.");
                 reject(new Error("WebSocket connection failed"));
             };
@@ -112,7 +144,7 @@ export class WebSocketTransport {
                         this.options.onAck(message.id);
                     }
                 }
-                catch (err) {
+                catch {
                     // ignore malformed
                 }
             };
@@ -150,6 +182,43 @@ export class WebSocketTransport {
             payload: { state },
         }));
     }
+    sendBootstrap(runId, status, message) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        this.socket.send(JSON.stringify({
+            type: "bootstrap",
+            payload: {
+                runId,
+                status,
+                message,
+            },
+        }));
+    }
+    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.4",
+  "version": "0.2.0",
   "description": "Secure bridge between Span (AI control plane) and local agent CLI tools.",
   "type": "module",
   "bin": {