@span-io/agent-link 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Span-IO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,78 @@
+# AgentLink (Client)
+
+**AgentLink** is the secure bridge between your local development environment and **Span**, the remote control plane. It allows you to run powerful AI agent tools (like Codex, Gemini, or Claude) on your own machine—where they have access to your code, compilers, and local tools—while controlling and monitoring them from a centralized web interface.
+
+Think of it as a **reverse tunnel for AI agents**: The "brains" and history live in the cloud (or your self-hosted server), but the "hands" are local.
+
+## 🚀 How It Works
+
+1.  **You run this CLI** on your laptop or dev server.
+2.  **It connects** to Span via a secure WebSocket.
+3.  **It waits for commands.** When you send a prompt in the Web UI, the server signals this client.
+4.  **It executes the agent** locally on your machine.
+5.  **It streams logs/output** back to the Web UI in real-time.
+
+## 📦 Installation & Usage
+
+You don't need to install this globally. We recommend running it on-demand via `npx`.
+
+### 1. Connect a New Device
+In the Span Web UI, click **+ Connect New Device**. You will be given a pairing code.
+
+Run the following command in your terminal:
+
+```bash
+npx -y @span-io/agent-link connect --server https://your-server.com --pairing-code YOUR-PAIRING-CODE
+```
+
+*Replace `https://your-server.com` with the URL of your Span instance.*
+
+### 2. Run in Background
+Once paired, the client will save your credentials to `~/.config/remote-agent/client.json`. You can subsequently run it without the pairing code:
+
+```bash
+npx -y @span-io/agent-link connect --server https://your-server.com
+```
+
+### 3. Agent Selection
+By default, the client auto-discovers supported agents (`codex`, `gemini`, `claude`) in your `PATH`.
+You can force a specific binary using the `--agent` flag or environment variables:
+
+```bash
+# Force usage of a specific binary
+npx -y @span-io/agent-link connect --server ... --agent /usr/local/bin/my-custom-codex
+```
+
+## 🔒 Security & Risk Profile
+
+**This tool allows a remote server to execute commands on your machine.** It is designed for developers who own both the server and the client.
+
+### What it Protects Against
+*   **Unauthorized Connection:** Pairing requires a short-lived, cryptographic code. Once paired, connections use a refresh token bound to your device.
+*   **Man-in-the-Middle:** All traffic is encrypted via TLS (WebSocket Secure).
+*   **Drive-by Attacks:** The client does not listen on any open ports; it makes an outbound connection to the server.
+
+### What it Does NOT Protect Against
+*   **Compromised Server:** If your Span server is hacked, an attacker can send "spawn" commands to your connected client.
+*   **Malicious Agent Output:** If the AI agent (e.g., Gemini) decides to run `rm -rf /`, this client will faithfully execute that command.
+*   **Local Privilege Escalation:** The agent runs with the same permissions as the user who ran `npx @span-io/agent-link connect`. Do not run this as root.
+
+### ⚠️ Threat Model: "Remote Shell"
+You should treat this client with the same security caution as an **SSH Session**.
+*   **Difficulty for Malicious Actors:** If they compromise your Span account, gaining code execution on your local machine is **Trivial (Low Difficulty)**. They just need to send a prompt to the agent telling it to run a shell command.
+*   **Mitigation:**
+    *   Only connect to servers you trust.
+    *   Run the client inside a Docker container or VM if you are working with untrusted inputs.
+    *   Use the agent's built-in sandboxing (e.g. `--approval-mode`) to review commands before they run.
+
+## 🛠 Configuration
+
+Configuration is stored in `~/.config/remote-agent/client.json`.
+
+**Environment Variables:**
+*   `CODEX_BIN`, `GEMINI_BIN`, `CLAUDE_BIN`: Override the path to specific agent binaries.
+*   `CODEX_CWD`: Set the working directory for the agent (defaults to the directory where you ran the client).
+
+## License
+
+MIT

package/dist/agent.js

@@ -0,0 +1,65 @@
+import fs from "fs";
+import path from "path";
+import { spawn } from "child_process";
+const AGENT_NAMES = ["codex", "gemini", "claude"];
+export function findAgentsOnPath() {
+    const pathEntries = (process.env.PATH ?? "")
+        .split(path.delimiter)
+        .filter(Boolean);
+    const results = [];
+    for (const name of AGENT_NAMES) {
+        for (const dir of pathEntries) {
+            const fullPath = path.join(dir, name);
+            try {
+                fs.accessSync(fullPath, fs.constants.X_OK);
+                results.push({ name, path: fullPath });
+                break;
+            }
+            catch {
+                // continue searching
+            }
+        }
+    }
+    return results;
+}
+export function resolveAgentBinary(preferred, discovered) {
+    // 1. Check for specific environment variable overrides first
+    if (preferred === "codex" && process.env.CODEX_BIN) {
+        return { name: "codex", path: process.env.CODEX_BIN };
+    }
+    if (preferred === "gemini" && process.env.GEMINI_BIN) {
+        return { name: "gemini", path: process.env.GEMINI_BIN };
+    }
+    if (preferred === "claude" && process.env.CLAUDE_BIN) {
+        return { name: "claude", path: process.env.CLAUDE_BIN };
+    }
+    // 2. If preferred is an absolute/relative path that exists
+    if (preferred) {
+        if (fs.existsSync(preferred)) {
+            return {
+                name: inferNameFromPath(preferred),
+                path: preferred,
+            };
+        }
+        const byName = (discovered ?? findAgentsOnPath()).find((agent) => agent.name === preferred);
+        return byName ?? null;
+    }
+    const available = discovered ?? findAgentsOnPath();
+    return available[0] ?? null;
+}
+function inferNameFromPath(agentPath) {
+    const base = path.basename(agentPath).toLowerCase();
+    if (base.includes("gemini")) {
+        return "gemini";
+    }
+    if (base.includes("claude")) {
+        return "claude";
+    }
+    return "codex";
+}
+export function spawnAgentProcess(agent, args) {
+    const child = spawn(agent.path, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+    });
+    return { name: agent.name, child };
+}

package/dist/config.js

@@ -0,0 +1,45 @@
+import fs from "fs";
+import os from "os";
+import path from "path";
+import { encrypt, decrypt } from "./crypto-utils.js";
+const CONFIG_DIR = process.env.REMOTE_AGENT_CLIENT_HOME ??
+    path.join(os.homedir(), ".remote-agent-client");
+const CONFIG_FILE = path.join(CONFIG_DIR, "config.json");
+function newClientId() {
+    if (globalThis.crypto?.randomUUID) {
+        return globalThis.crypto.randomUUID();
+    }
+    return `client-${Date.now().toString(36)}`;
+}
+export function loadConfig() {
+    try {
+        const raw = fs.readFileSync(CONFIG_FILE, "utf8");
+        const config = JSON.parse(raw);
+        if (config.encryptedRefreshToken && !config.refreshToken) {
+            try {
+                config.refreshToken = decrypt(config.encryptedRefreshToken);
+            }
+            catch (err) {
+                console.warn("Failed to decrypt refresh token:", err);
+            }
+        }
+        return config;
+    }
+    catch {
+        return { clientId: newClientId() };
+    }
+}
+export function saveConfig(config) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    const toSave = { ...config };
+    if (toSave.refreshToken) {
+        try {
+            toSave.encryptedRefreshToken = encrypt(toSave.refreshToken);
+            delete toSave.refreshToken;
+        }
+        catch (err) {
+            console.warn("Failed to encrypt refresh token:", err);
+        }
+    }
+    fs.writeFileSync(CONFIG_FILE, JSON.stringify(toSave, null, 2), "utf8");
+}

package/dist/crypto-utils.js

@@ -0,0 +1,49 @@
+import crypto from "crypto";
+import fs from "fs";
+import path from "path";
+import os from "os";
+const CONFIG_DIR = process.env.REMOTE_AGENT_CLIENT_HOME ??
+    path.join(os.homedir(), ".remote-agent-client");
+const KEY_FILE = path.join(CONFIG_DIR, "master.key");
+function getMasterKey() {
+    if (!fs.existsSync(CONFIG_DIR)) {
+        fs.mkdirSync(CONFIG_DIR, { recursive: true });
+    }
+    if (fs.existsSync(KEY_FILE)) {
+        return fs.readFileSync(KEY_FILE);
+    }
+    const key = crypto.randomBytes(32);
+    fs.writeFileSync(KEY_FILE, key);
+    try {
+        fs.chmodSync(KEY_FILE, 0o600);
+    }
+    catch (error) {
+        console.warn("Failed to set secure permissions on master key:", error);
+    }
+    return key;
+}
+export function encrypt(text) {
+    const key = getMasterKey();
+    const iv = crypto.randomBytes(12);
+    const cipher = crypto.createCipheriv("aes-256-gcm", key, iv);
+    let encrypted = cipher.update(text, "utf8", "hex");
+    encrypted += cipher.final("hex");
+    const authTag = cipher.getAuthTag().toString("hex");
+    // Format: iv:authTag:encrypted
+    return `${iv.toString("hex")}:${authTag}:${encrypted}`;
+}
+export function decrypt(text) {
+    const parts = text.split(":");
+    if (parts.length !== 3) {
+        throw new Error("Invalid encrypted format");
+    }
+    const [ivHex, authTagHex, encryptedHex] = parts;
+    const key = getMasterKey();
+    const iv = Buffer.from(ivHex, "hex");
+    const authTag = Buffer.from(authTagHex, "hex");
+    const decipher = crypto.createDecipheriv("aes-256-gcm", key, iv);
+    decipher.setAuthTag(authTag);
+    let decrypted = decipher.update(encryptedHex, "hex", "utf8");
+    decrypted += decipher.final("utf8");
+    return decrypted;
+}

package/dist/index.js

@@ -0,0 +1,276 @@
+#!/usr/bin/env node
+import os from "os";
+import process from "process";
+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 { NoopTransport, WebSocketTransport } from "./transport.js";
+const args = parseArgs(process.argv.slice(2));
+if (args.list) {
+    const agents = findAgentsOnPath();
+    if (agents.length === 0) {
+        console.log("No supported agents found on PATH (codex, gemini, claude).");
+        process.exitCode = 1;
+    }
+    else {
+        for (const agent of agents) {
+            console.log(`${agent.name}: ${agent.path}`);
+        }
+    }
+    process.exit(0);
+}
+const config = loadConfig();
+if (args.serverUrl) {
+    config.serverUrl = args.serverUrl;
+}
+if (args.pairingCode) {
+    if (!config.serverUrl) {
+        console.error("Pairing requires --server.");
+        process.exit(1);
+    }
+    await pairWithServer({
+        serverUrl: config.serverUrl,
+        pairingCode: args.pairingCode,
+        label: os.hostname(),
+    }).then((res) => {
+        config.clientId = res.clientId;
+        config.refreshToken = res.refreshToken;
+        saveConfig(config);
+        console.log("Pairing successful.");
+    });
+}
+const logBuffer = new LogBuffer();
+// Update map to hold SpawnedProcess which includes the child
+const activeAgents = new Map();
+let transport;
+try {
+    transport = await createTransport({
+        config,
+        logBuffer,
+        onControl: (message) => handleControl(message),
+        onAck: (id) => logBuffer.setLastAckedId(id),
+        noConnect: args.noConnect ?? false,
+    });
+}
+catch (error) {
+    console.error(`Connection failed, running offline: ${error instanceof Error ? error.message : "unknown error"}`);
+    transport = new NoopTransport();
+}
+function handleControl(message) {
+    const { action, agentId, payload } = message;
+    if (!agentId)
+        return;
+    switch (action) {
+        case "spawn":
+        case "start": {
+            let agentProc = activeAgents.get(agentId);
+            if (agentProc) {
+                if (payload?.prompt && agentProc.child.stdin) {
+                    agentProc.child.stdin.write(`${payload.prompt}\n`);
+                }
+                return;
+            }
+            const discovered = findAgentsOnPath();
+            let preferredAgent = args.agent;
+            let targetModel = payload?.model;
+            // Fallback: Try to find model in args if not in payload top-level
+            if (!targetModel && payload?.args) {
+                const argsList = payload.args;
+                const modelIndex = argsList.findIndex(a => a === "--model" || a === "-m");
+                if (modelIndex >= 0 && modelIndex + 1 < argsList.length) {
+                    targetModel = argsList[modelIndex + 1];
+                }
+            }
+            if (!preferredAgent && targetModel) {
+                if (targetModel.startsWith("gemini-")) {
+                    preferredAgent = "gemini";
+                }
+                else if (targetModel.startsWith("claude-")) {
+                    preferredAgent = "claude";
+                }
+            }
+            if (!preferredAgent) {
+                preferredAgent = payload?.name || "codex";
+            }
+            const agentCandidate = resolveAgentBinary(preferredAgent, discovered);
+            if (!agentCandidate) {
+                console.error(`No agent found for ${preferredAgent || "any supported agent"}`);
+                transport.sendStatus(agentId, "error");
+                return;
+            }
+            const optionsArgs = [...(payload?.args || args.agentArgs)];
+            const proc = spawnAgentProcessAdvanced({
+                agent: {
+                    id: agentId,
+                    name: agentCandidate.name,
+                    model: targetModel || "codex-cli"
+                },
+                prompt: payload?.prompt || "",
+                optionsArgs,
+                executablePath: agentCandidate.path
+            });
+            activeAgents.set(agentId, proc);
+            console.log(`[${new Date().toLocaleTimeString()}] Spawning agent: ${agentCandidate.name} (${targetModel || "default model"})`);
+            transport.sendStatus(agentId, "running");
+            setupAgentPiping(agentId, proc);
+            break;
+        }
+        case "stop": {
+            const proc = activeAgents.get(agentId);
+            if (proc) {
+                proc.child.kill();
+                activeAgents.delete(agentId);
+            }
+            break;
+        }
+        case "stdin":
+        case "prompt": {
+            const proc = activeAgents.get(agentId);
+            const data = message.data || payload?.prompt;
+            if (proc && data && proc.child.stdin) {
+                proc.child.stdin.write(data.endsWith("\n") ? data : `${data}\n`);
+            }
+            break;
+        }
+    }
+}
+function setupAgentPiping(agentId, proc) {
+    const setupStream = (stream, name) => {
+        if (!stream)
+            return;
+        let buffer = "";
+        stream.setEncoding("utf8");
+        stream.on("data", (chunk) => {
+            buffer += chunk;
+            let index = buffer.indexOf("\n");
+            while (index >= 0) {
+                const line = buffer.slice(0, index + 1);
+                buffer = buffer.slice(index + 1);
+                transport.sendLog(agentId, name, line);
+                index = buffer.indexOf("\n");
+            }
+        });
+        stream.on("end", () => {
+            if (buffer.length > 0) {
+                transport.sendLog(agentId, name, buffer);
+            }
+        });
+    };
+    setupStream(proc.child.stdout, "stdout");
+    setupStream(proc.child.stderr, "stderr");
+    proc.child.on("exit", (code, signal) => {
+        transport.sendStatus(agentId, "exited");
+        activeAgents.delete(agentId);
+    });
+    proc.child.on("error", (error) => {
+        transport.sendLog(agentId, "stderr", `Process error: ${error.message}\n`);
+        transport.sendStatus(agentId, "error");
+        activeAgents.delete(agentId);
+    });
+}
+function parseArgs(argv) {
+    const parsed = { agentArgs: [] };
+    let startIdx = 0;
+    // Handle optional "connect" subcommand
+    if (argv[0] === "connect") {
+        startIdx = 1;
+    }
+    for (let i = startIdx; i < argv.length; i += 1) {
+        const arg = argv[i];
+        switch (arg) {
+            case "--server":
+                parsed.serverUrl = argv[++i];
+                break;
+            case "--pairing-code":
+                parsed.pairingCode = argv[++i];
+                break;
+            case "--agent":
+                parsed.agent = argv[++i];
+                break;
+            case "--list":
+                parsed.list = true;
+                break;
+            case "--no-connect":
+                parsed.noConnect = true;
+                break;
+            case "--":
+                parsed.agentArgs.push(...argv.slice(i + 1));
+                i = argv.length;
+                break;
+            case "--help":
+                printHelp();
+                process.exit(0);
+            default:
+                if (arg.startsWith("--")) {
+                    console.error(`Unknown argument: ${arg}`);
+                    process.exit(1);
+                }
+                else {
+                    parsed.agentArgs.push(arg);
+                }
+        }
+    }
+    return parsed;
+}
+function printHelp() {
+    console.log(`remote-agent-client
+
+Usage:
+  remote-agent-client --server https://host --pairing-code 123-456
+  remote-agent-client --server https://host
+
+Options:
+  --server <url>        Remote Agent server URL
+  --pairing-code <code> Pairing code for first-time auth
+  --agent <name|path>   Preferred agent (codex, gemini, claude)
+  --list                List discovered agents
+  --no-connect          Run without server connection
+  --                    Pass remaining args to the agent
+`);
+}
+async function pairWithServer(input) {
+    const response = await fetch(new URL("/api/clients/pair", input.serverUrl), {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            code: input.pairingCode,
+            label: input.label,
+        }),
+    });
+    if (!response.ok) {
+        const details = await response.text().catch(() => "");
+        throw new Error(`Pairing failed (${response.status}): ${details}`);
+    }
+    return (await response.json());
+}
+async function createTransport(input) {
+    if (input.noConnect || !input.config.serverUrl || !input.config.refreshToken || !input.config.clientId) {
+        return new NoopTransport();
+    }
+    const transport = new WebSocketTransport({
+        serverUrl: input.config.serverUrl,
+        tokenProvider: () => requestSessionToken(input.config.serverUrl, input.config.refreshToken),
+        clientId: input.config.clientId,
+        logBuffer: input.logBuffer,
+        onControl: input.onControl,
+        onAck: input.onAck,
+    });
+    await transport.connect();
+    return transport;
+}
+async function requestSessionToken(serverUrl, refreshToken) {
+    const response = await fetch(new URL("/api/clients/session", serverUrl), {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            Authorization: `Bearer ${refreshToken}`,
+        },
+        body: JSON.stringify({}),
+    });
+    if (!response.ok) {
+        throw new Error(`Session token request failed (${response.status})`);
+    }
+    const data = (await response.json());
+    return data.sessionToken;
+}

package/dist/log-buffer.js

@@ -0,0 +1,29 @@
+export class LogBuffer {
+    maxEntries;
+    entries = [];
+    lastAckedId = 0;
+    constructor(maxEntries = 5000) {
+        this.maxEntries = maxEntries;
+    }
+    getLastAckedId() {
+        return this.lastAckedId;
+    }
+    setLastAckedId(id) {
+        if (id > this.lastAckedId) {
+            this.lastAckedId = id;
+            this.prune();
+        }
+    }
+    push(entry) {
+        this.entries.push(entry);
+        this.prune();
+    }
+    getUnacked() {
+        return this.entries.filter((entry) => entry.id > this.lastAckedId);
+    }
+    prune() {
+        while (this.entries.length > this.maxEntries) {
+            this.entries.shift();
+        }
+    }
+}

package/dist/process-runner.js

@@ -0,0 +1,137 @@
+import { spawn } from "child_process";
+const DEFAULT_CODEX_ARGS = "exec --skip-git-repo-check";
+const DEFAULT_GEMINI_ARGS = "";
+const DEFAULT_GEMINI_PROMPT_FLAG = "-p";
+const DEFAULT_PROMPT_FLAG = "";
+const DEFAULT_TTY_MODE = "auto";
+const DEFAULT_TTY_TERM = "dumb";
+function splitArgs(raw) {
+    return raw.trim() === "" ? [] : raw.trim().split(/\s+/g);
+}
+function shellQuote(value) {
+    // Simple single-quote wrapping for display purposes
+    return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+export function buildCommand({ agent, prompt, optionsArgs = [], executablePath }, promptModeOverride) {
+    // 1. Gemini Models
+    if (agent.model.startsWith("gemini-")) {
+        const command = executablePath ?? process.env.GEMINI_BIN ?? "gemini";
+        const rawArgs = process.env.GEMINI_ARGS ?? DEFAULT_GEMINI_ARGS;
+        const promptFlag = process.env.GEMINI_PROMPT_FLAG ?? DEFAULT_GEMINI_PROMPT_FLAG;
+        const args = splitArgs(rawArgs);
+        if (optionsArgs.length > 0) {
+            args.push(...optionsArgs);
+        }
+        if (!args.includes("--model") && !args.includes("-m")) {
+            args.push("--model", agent.model);
+        }
+        if (!args.includes("--approval-mode")) {
+            args.push("--approval-mode", "auto_edit");
+        }
+        args.push(promptFlag, prompt);
+        return { command, args, promptMode: "args" };
+    }
+    // 2. Claude Models
+    if (agent.model.startsWith("claude-")) {
+        const command = executablePath ?? process.env.CLAUDE_BIN ?? "claude";
+        const args = ["-p", prompt, "--model", agent.model];
+        return { command, args, promptMode: "args" };
+    }
+    // 3. Generic Codex/Other Models
+    const command = executablePath ?? process.env.CODEX_BIN ?? "codex";
+    const rawArgs = process.env.CODEX_ARGS ?? DEFAULT_CODEX_ARGS;
+    const promptFlag = process.env.CODEX_PROMPT_FLAG ?? DEFAULT_PROMPT_FLAG;
+    // Determine Prompt Mode
+    const envPromptMode = process.env.CODEX_PROMPT_MODE === "stdin" ? "stdin" : "args";
+    const promptMode = promptModeOverride ?? envPromptMode;
+    const extraArgs = optionsArgs.filter((arg) => arg.trim() !== "");
+    const args = splitArgs(rawArgs);
+    if (promptMode === "args") {
+        if (extraArgs.length) {
+            args.push(...extraArgs);
+        }
+        if (!args.includes("--model") && !args.includes("-m")) {
+            args.push("--model", agent.model);
+        }
+        // Handle {prompt} placeholder or append
+        const placeholderIndex = args.findIndex((arg) => arg.includes("{prompt}"));
+        if (placeholderIndex >= 0) {
+            args[placeholderIndex] = args[placeholderIndex].replace("{prompt}", prompt);
+        }
+        else {
+            if (promptFlag) {
+                args.push(promptFlag);
+            }
+            args.push(prompt);
+        }
+        return { command, args, promptMode: "args" };
+    }
+    // Stdin Mode
+    if (promptMode === "stdin") {
+        if (extraArgs.length) {
+            args.push(...extraArgs);
+        }
+        if (!args.includes("--model") && !args.includes("-m")) {
+            args.push("--model", agent.model);
+        }
+    }
+    return { command, args, promptMode };
+}
+export function spawnAgentProcess(config) {
+    const { agent, optionsArgs = [] } = config;
+    const startedAt = new Date().toISOString();
+    const isCodexModel = !agent.model.startsWith("gemini-") && !agent.model.startsWith("claude-");
+    const sanitizedOptions = agent.model.startsWith("claude-")
+        ? []
+        : optionsArgs;
+    const spawnWithMode = (promptModeOverride) => {
+        const { command, args, promptMode } = buildCommand({ ...config, optionsArgs: sanitizedOptions }, promptModeOverride);
+        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;
+        // For logging/display
+        const commandString = [command, ...args].map(shellQuote).join(" ");
+        const finalCommand = useScriptWrapper ? "script" : command;
+        // Script wrapper args: -q (quiet), -c (command), /dev/null (output file)
+        const finalArgs = useScriptWrapper
+            ? ["-q", "-c", commandString, "/dev/null"]
+            : args;
+        const child = spawn(finalCommand, finalArgs, {
+            stdio: [promptMode === "stdin" ? "pipe" : "ignore", "pipe", "pipe"],
+            cwd: workingDir,
+            env: {
+                ...process.env,
+                CODEX_AGENT_ID: agent.id,
+                CODEX_AGENT_NAME: agent.name,
+                CODEX_AGENT_MODEL: agent.model,
+                ...(useScriptWrapper ? { TERM: ttyTerm } : {}),
+            }
+        });
+        if (promptMode === "stdin") {
+            child.stdin?.write(config.prompt);
+            child.stdin?.end();
+        }
+        return {
+            child,
+            pid: child.pid ?? null,
+            startedAt,
+            command: finalCommand,
+            args: finalArgs,
+            promptMode
+        };
+    };
+    try {
+        return spawnWithMode();
+    }
+    catch (error) {
+        const code = error instanceof Error ? error.code : null;
+        if (code === "E2BIG" && isCodexModel) {
+            console.warn("Spawn args exceeded system limits; retrying via stdin.");
+            return spawnWithMode("stdin");
+        }
+        throw error;
+    }
+}

package/dist/protocol.js

@@ -0,0 +1,6 @@
+export function encodeEnvelope(envelope) {
+    return JSON.stringify(envelope);
+}
+export function nowIso() {
+    return new Date().toISOString();
+}

package/dist/transport.js

@@ -0,0 +1,176 @@
+import { encodeEnvelope, nowIso } from "./protocol.js";
+import os from "os";
+export class NoopTransport {
+    async connect() {
+        return undefined;
+    }
+    sendLog(_agentId, _stream, _message) {
+        return undefined;
+    }
+    sendStatus(_agentId, _state) {
+        return undefined;
+    }
+    close() {
+        return undefined;
+    }
+}
+export class WebSocketTransport {
+    options;
+    socket = null;
+    isExplicitClose = false;
+    retryCount = 0;
+    retryTimer = null;
+    pingTimeout = null;
+    pingIntervalTimer = null;
+    maxRetryDelay = 30000;
+    baseRetryDelay = 1000;
+    heartbeatInterval = 30000;
+    constructor(options) {
+        this.options = options;
+    }
+    async connect() {
+        this.isExplicitClose = false;
+        await this.establishConnection();
+    }
+    heartbeat() {
+        if (this.pingTimeout)
+            clearTimeout(this.pingTimeout);
+        this.pingTimeout = setTimeout(() => {
+            console.warn("Connection timed out (no heartbeat). Reconnecting...");
+            this.socket?.close();
+        }, this.heartbeatInterval + 5000);
+    }
+    async establishConnection() {
+        const { serverUrl, tokenProvider } = this.options;
+        let token;
+        try {
+            token = await tokenProvider();
+        }
+        catch (err) {
+            console.error("Failed to fetch session token:", err);
+            this.scheduleReconnect();
+            return;
+        }
+        const url = new URL("/api/ws", serverUrl);
+        url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+        url.searchParams.set("token", token);
+        return new Promise((resolve, reject) => {
+            if (this.socket) {
+                this.socket.onclose = null;
+                this.socket.onerror = null;
+                this.socket.onmessage = null;
+                this.socket.onopen = null;
+                this.socket.close();
+            }
+            console.log(`Connecting to ${url.toString()}...`);
+            const socket = new WebSocket(url.toString());
+            this.socket = socket;
+            const onOpen = () => {
+                console.log("WebSocket connected.");
+                this.retryCount = 0;
+                this.heartbeat();
+                this.startPingInterval();
+                this.socket?.send(encodeEnvelope({
+                    type: "hello",
+                    clientId: this.options.clientId,
+                    ts: nowIso(),
+                    payload: { device: os.hostname(), platform: os.platform() },
+                }));
+                socket.onclose = this.handleClose.bind(this);
+                socket.onerror = (error) => {
+                    console.error("WebSocket error:", error);
+                };
+                resolve();
+            };
+            const onFail = (err) => {
+                console.error("WebSocket connection failed to open.");
+                reject(new Error("WebSocket connection failed"));
+            };
+            socket.onopen = onOpen;
+            socket.onerror = onFail;
+            socket.onmessage = (event) => {
+                this.heartbeat();
+                const rawData = event.data;
+                const data = typeof rawData === "string" ? rawData : rawData.toString();
+                if (data === "pong")
+                    return;
+                if (data === "ping") {
+                    this.socket?.send("pong");
+                    return;
+                }
+                if (!data)
+                    return;
+                try {
+                    const message = JSON.parse(data);
+                    if (message.type === "control") {
+                        this.options.onControl(message);
+                    }
+                    else if (message.type === "ping") {
+                        this.socket?.send("pong");
+                    }
+                    else if (message.type === "ack" && typeof message.id === "number") {
+                        this.options.onAck(message.id);
+                    }
+                }
+                catch (err) {
+                    // ignore malformed
+                }
+            };
+        });
+    }
+    handleClose() {
+        if (this.isExplicitClose)
+            return;
+        this.scheduleReconnect();
+    }
+    scheduleReconnect() {
+        this.stopPingInterval();
+        const delay = Math.min(this.baseRetryDelay * Math.pow(1.5, this.retryCount), this.maxRetryDelay);
+        console.log(`Reconnecting in ${delay}ms... (Attempt ${this.retryCount + 1})`);
+        this.retryCount++;
+        this.retryTimer = setTimeout(() => {
+            this.establishConnection().catch(() => this.scheduleReconnect());
+        }, delay);
+    }
+    sendLog(agentId, stream, message) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        this.socket.send(JSON.stringify({
+            type: "log",
+            sessionId: agentId,
+            payload: { stream, message },
+        }));
+    }
+    sendStatus(agentId, state) {
+        if (!this.socket || this.socket.readyState !== WebSocket.OPEN)
+            return;
+        this.socket.send(JSON.stringify({
+            type: "status",
+            sessionId: agentId,
+            payload: { state },
+        }));
+    }
+    close() {
+        this.isExplicitClose = true;
+        this.stopPingInterval();
+        if (this.retryTimer)
+            clearTimeout(this.retryTimer);
+        if (this.pingTimeout)
+            clearTimeout(this.pingTimeout);
+        this.socket?.close();
+    }
+    startPingInterval() {
+        this.stopPingInterval();
+        this.pingIntervalTimer = setInterval(() => {
+            if (this.socket?.readyState === WebSocket.OPEN) {
+                this.socket.send("ping");
+            }
+        }, 10000);
+    }
+    stopPingInterval() {
+        if (this.pingIntervalTimer) {
+            clearInterval(this.pingIntervalTimer);
+            this.pingIntervalTimer = null;
+        }
+    }
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@span-io/agent-link",
+  "version": "0.0.1",
+  "description": "Secure bridge between Span (AI control plane) and local agent CLI tools.",
+  "type": "module",
+  "bin": {
+    "connect": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+ssh://git@github.com/span-io/AgentLink.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "node --enable-source-maps dist/index.js",
+    "lint": "echo 'no lint configured'",
+    "start": "node dist/index.js",
+    "test": "tsx --test"
+  },
+  "devDependencies": {
+    "@types/node": "^25.1.0",
+    "tsx": "^4.19.2",
+    "typescript": "^5.5.4"
+  }
+}