@bondedhq/runner 0.0.0-stage → 0.1.1

package/dist/runner.d.ts

@@ -0,0 +1,78 @@
+import { type AgentMode } from "@bondedhq/shared";
+import { type CodeIdentity } from "./code-hash.js";
+/**
+ * The Bonded runner: lets the Arena rate an agent that runs on its operator's own servers.
+ *
+ * It connects out to the Arena Gateway (no inbound port needed), says which mode the agent works
+ * in, and waits. For each episode the gateway sends, it launches the operator's agent command
+ * with the episode's endpoints in its environment (`BONDED_*`, see `episodeEnv`), reports when
+ * it started and how it ended (exit code and the last 4 KB of its output), and stops it when the
+ * gateway cancels or the deadline passes. One episode at a time.
+ *
+ * The runner never sees the agent's tool calls or transactions: the agent talks to the gateway
+ * directly. The runner token stays with the runner: it is not passed to the agent.
+ */
+export interface RunnerOptions {
+    /** The gateway's base URL, e.g. https://arena.example.com. */
+    gateway: string;
+    token: string;
+    mode: AgentMode;
+    /** The agent's TEE: the runner fetches its evidence for each episode's nonce. */
+    teeUrl?: string;
+    /** The agent command and its arguments. */
+    command: string[];
+    /** Where the runner says what it is doing. */
+    log?: (line: string) => void;
+    /** Copy the agent's output to the runner's own stdout and stderr (default true). */
+    echo?: boolean;
+    version?: string;
+    /**
+     * The code version it launches, reported in hello. Default: worked out from the command
+     * (`codeIdentity`: BONDED_CODE_HASH, BONDED_IMAGE_DIGEST, the git commit, or unpinned).
+     */
+    code?: CodeIdentity;
+    /** Where the agent command runs. Default: the runner's own working directory. */
+    cwd?: string;
+    /** Called each time the runner connects to the gateway (after it says hello). */
+    onConnect?: () => void;
+    heartbeatMs?: number;
+    backoff?: {
+        initialMs: number;
+        maxMs: number;
+    };
+    killGraceMs?: number;
+}
+/** Why the runner stopped for good. */
+export interface RunnerStop {
+    /** 0: stopped on request; 2: the gateway refused the runner and retrying won't help. */
+    code: 0 | 2;
+    reason: string;
+}
+export declare class Runner {
+    private readonly options;
+    private socket;
+    private running;
+    private stopped;
+    private wake;
+    private readonly outbox;
+    private readonly log;
+    /** The code hash it reports, and where it came from. */
+    readonly code: CodeIdentity;
+    constructor(options: RunnerOptions);
+    /** Connects, and keeps reconnecting with backoff, until stopped or refused for good. */
+    start(): Promise<RunnerStop>;
+    /** Stops the agent (if one is running) and disconnects. */
+    stop(): Promise<void>;
+    private url;
+    private connectOnce;
+    /** Sends now if connected; otherwise keeps the message for the next connection. */
+    private write;
+    private runEpisode;
+    /** Runs the agent command to completion (or until it is killed). */
+    private launch;
+    /** SIGTERM to the agent's process group, then SIGKILL after the grace period. */
+    private cancelRunning;
+    /** Gets the TEE's evidence for the episode's nonce and forwards it as-is. */
+    private sendEvidence;
+}
+//# sourceMappingURL=runner.d.ts.map

package/dist/runner.js

@@ -0,0 +1,319 @@
+import { spawn } from "node:child_process";
+import { episodeEnv, parseRunnerMessage, RUNNER_CLOSE, RUNNER_CONNECT_PATH, RUNNER_HEARTBEAT_MS, RUNNER_KILL_GRACE_MS, RUNNER_MAX_MESSAGE_BYTES, RUNNER_PROTOCOL_VERSION, RUNNER_TAIL_BYTES, ServerToRunner, } from "@bondedhq/shared";
+import { WebSocket } from "ws";
+import { codeIdentity } from "./code-hash.js";
+import { backoffDelay, gatewayUrlProblem, Tail } from "./tail.js";
+/** Messages the runner keeps while disconnected, to send on reconnect (newest kept). */
+const OUTBOX_LIMIT = 16;
+export class Runner {
+    options;
+    socket;
+    running;
+    stopped = false;
+    wake;
+    outbox = [];
+    log;
+    /** The code hash it reports, and where it came from. */
+    code;
+    constructor(options) {
+        this.options = options;
+        if (options.command.length === 0)
+            throw new Error("no agent command given");
+        const problem = gatewayUrlProblem(options.gateway);
+        if (problem)
+            throw new Error(problem);
+        this.log = options.log ?? (() => { });
+        this.code = options.code ?? codeIdentity({ command: options.command });
+    }
+    /** Connects, and keeps reconnecting with backoff, until stopped or refused for good. */
+    async start() {
+        const backoff = this.options.backoff ?? { initialMs: 1_000, maxMs: 30_000 };
+        let attempt = 0;
+        while (!this.stopped) {
+            const end = await this.connectOnce();
+            if (end.fatal) {
+                await this.cancelRunning("the runner stopped");
+                return { code: 2, reason: end.fatal };
+            }
+            if (this.stopped)
+                break;
+            attempt = end.stable ? 1 : attempt + 1;
+            const delay = backoffDelay(attempt, backoff);
+            this.log(`disconnected; reconnecting in ${(delay / 1000).toFixed(1)} s`);
+            await new Promise((resolve) => {
+                const timer = setTimeout(resolve, delay);
+                this.wake = () => {
+                    clearTimeout(timer);
+                    resolve();
+                };
+            });
+            this.wake = undefined;
+        }
+        return { code: 0, reason: "stopped" };
+    }
+    /** Stops the agent (if one is running) and disconnects. */
+    async stop() {
+        this.stopped = true;
+        this.wake?.();
+        await this.cancelRunning("the runner stopped");
+        this.socket?.close(1000, "runner stopping");
+    }
+    url() {
+        const base = this.options.gateway.replace(/\/+$/, "").replace(/^http/, "ws");
+        return `${base}${RUNNER_CONNECT_PATH}`;
+    }
+    connectOnce() {
+        return new Promise((resolve) => {
+            const socket = new WebSocket(this.url(), {
+                headers: {
+                    authorization: `Bearer ${this.options.token}`,
+                    "user-agent": `bonded-runner/${this.options.version ?? "dev"}`,
+                },
+                maxPayload: RUNNER_MAX_MESSAGE_BYTES,
+                handshakeTimeout: 15_000,
+            });
+            this.socket = socket;
+            let openedAt = 0;
+            let fatal;
+            let heartbeat;
+            let lastPong = Date.now();
+            const heartbeatMs = this.options.heartbeatMs ?? RUNNER_HEARTBEAT_MS;
+            socket.on("unexpected-response", (_, res) => {
+                if (res.statusCode === 401)
+                    fatal = "the gateway refused the runner token (wrong or revoked)";
+                else
+                    this.log(`the gateway answered ${res.statusCode}`);
+                socket.terminate();
+            });
+            socket.on("open", () => {
+                openedAt = Date.now();
+                lastPong = Date.now();
+                this.log(`connected to ${this.options.gateway} (${this.options.mode} mode)`);
+                this.write({
+                    type: "hello",
+                    runnerVersion: this.options.version ?? "dev",
+                    protocol: RUNNER_PROTOCOL_VERSION,
+                    mode: this.options.mode,
+                    ...(this.options.teeUrl ? { teeUrl: this.options.teeUrl } : {}),
+                    codeHash: this.code.codeHash,
+                    codeSource: this.code.codeSource,
+                    codeDetail: this.code.detail.slice(0, 200),
+                });
+                for (const message of this.outbox.splice(0))
+                    this.write(message);
+                this.options.onConnect?.();
+                heartbeat = setInterval(() => {
+                    if (Date.now() - lastPong > 3 * heartbeatMs) {
+                        this.log("no answer from the gateway; reconnecting");
+                        socket.terminate();
+                        return;
+                    }
+                    this.write({ type: "ping", at: Date.now() });
+                }, heartbeatMs);
+            });
+            socket.on("message", (data, isBinary) => {
+                const message = isBinary ? undefined : parseRunnerMessage(ServerToRunner, String(data));
+                if (!message) {
+                    this.log("ignored a message from the gateway that didn't parse");
+                    return;
+                }
+                if (message.type === "pong")
+                    lastPong = Date.now();
+                else if (message.type === "episode")
+                    void this.runEpisode(message);
+                else if (message.type === "cancel" && this.running?.episodeId === message.episodeId)
+                    void this.cancelRunning("the gateway cancelled the episode");
+            });
+            socket.on("error", (error) => this.log(`connection error: ${error.message}`));
+            socket.on("close", (code, reason) => {
+                clearInterval(heartbeat);
+                if (this.socket === socket)
+                    this.socket = undefined;
+                const why = reason.toString();
+                if (code === RUNNER_CLOSE.replaced)
+                    fatal = "another runner connected with the same token; this one is stopping";
+                else if (code === RUNNER_CLOSE.revoked)
+                    fatal = "the runner token was revoked";
+                else if (code === RUNNER_CLOSE.protocol)
+                    fatal = `the gateway closed the connection: ${why || "protocol error"} (upgrade the runner?)`;
+                // The episode can't be finished without the gateway: stop the agent rather than leave it.
+                if (openedAt)
+                    void this.cancelRunning("the runner lost its connection");
+                resolve({
+                    ...(fatal ? { fatal } : {}),
+                    stable: openedAt > 0 && Date.now() - openedAt > 10_000,
+                });
+            });
+        });
+    }
+    /** Sends now if connected; otherwise keeps the message for the next connection. */
+    write(message) {
+        const socket = this.socket;
+        if (socket && socket.readyState === WebSocket.OPEN) {
+            socket.send(JSON.stringify(message));
+            return;
+        }
+        if (message.type === "ping" || message.type === "hello")
+            return;
+        this.outbox.push(message);
+        if (this.outbox.length > OUTBOX_LIMIT)
+            this.outbox.shift();
+    }
+    async runEpisode(episode) {
+        const started = Date.now();
+        if (this.running) {
+            this.write({
+                type: "episode_done",
+                episodeId: episode.episodeId,
+                exitCode: null,
+                durationMs: 0,
+                error: "the runner is already running an episode",
+            });
+            return;
+        }
+        const running = { episodeId: episode.episodeId, cancelled: false };
+        this.running = running;
+        this.log(`episode ${episode.episodeId}: starting the agent`);
+        try {
+            if (episode.nonce)
+                await this.sendEvidence(episode);
+            if (running.cancelled) {
+                this.write({
+                    type: "episode_done",
+                    episodeId: episode.episodeId,
+                    exitCode: null,
+                    durationMs: Date.now() - started,
+                    error: "cancelled before the agent started",
+                });
+                return;
+            }
+            const result = await this.launch(episode, running);
+            this.write({
+                type: "episode_done",
+                episodeId: episode.episodeId,
+                durationMs: Date.now() - started,
+                ...result,
+            });
+            this.log(`episode ${episode.episodeId}: agent ${result.exitCode === null ? `stopped (${result.signal ?? result.error})` : `exited with code ${result.exitCode}`}`);
+        }
+        finally {
+            clearTimeout(running.killTimer);
+            if (this.running === running)
+                this.running = undefined;
+        }
+    }
+    /** Runs the agent command to completion (or until it is killed). */
+    launch(episode, running) {
+        const [command, ...args] = this.options.command;
+        const env = { ...process.env, ...episodeEnv(episode) };
+        // The runner's own credential never reaches the agent, and neither does the production
+        // vault's (bondedVaultFromEnv in @bondedhq/sdk): a rated episode can't trade real funds.
+        delete env.BONDED_RUNNER_TOKEN;
+        delete env.BONDED_AGENT_KEY;
+        delete env.BONDED_VAULT_ADDRESS;
+        const stdout = new Tail(RUNNER_TAIL_BYTES);
+        const stderr = new Tail(RUNNER_TAIL_BYTES);
+        const echo = this.options.echo ?? true;
+        return new Promise((resolve) => {
+            let child;
+            try {
+                child = spawn(command, args, {
+                    env,
+                    ...(this.options.cwd ? { cwd: this.options.cwd } : {}),
+                    stdio: ["ignore", "pipe", "pipe"],
+                    // Its own process group, so stopping it stops anything it started.
+                    detached: process.platform !== "win32",
+                });
+            }
+            catch (error) {
+                resolve({ exitCode: null, error: `could not start the agent: ${String(error)}` });
+                return;
+            }
+            running.child = child;
+            child.stdout?.on("data", (chunk) => {
+                stdout.push(chunk);
+                if (echo)
+                    process.stdout.write(chunk);
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderr.push(chunk);
+                if (echo)
+                    process.stderr.write(chunk);
+            });
+            let failed;
+            child.once("error", (error) => {
+                failed = `could not start the agent: ${error.message}`;
+            });
+            child.once("spawn", () => this.write({ type: "episode_started", episodeId: episode.episodeId }));
+            child.once("close", (code, signal) => {
+                resolve({
+                    exitCode: failed ? null : code,
+                    signal,
+                    ...(stdout.text() ? { stdoutTail: stdout.text() } : {}),
+                    ...(stderr.text() ? { stderrTail: stderr.text() } : {}),
+                    ...(failed ? { error: failed } : {}),
+                });
+            });
+            // The gateway enforces the deadline; this is the runner's own backstop.
+            running.killTimer = setTimeout(() => void this.cancelRunning("the episode's deadline passed"), episode.deadlineMs + (this.options.killGraceMs ?? RUNNER_KILL_GRACE_MS));
+            if (running.cancelled)
+                void this.cancelRunning("cancelled");
+        });
+    }
+    /** SIGTERM to the agent's process group, then SIGKILL after the grace period. */
+    async cancelRunning(why) {
+        const running = this.running;
+        if (!running)
+            return;
+        running.cancelled = true;
+        const child = running.child;
+        if (!child || child.exitCode !== null || child.signalCode !== null)
+            return;
+        this.log(`episode ${running.episodeId}: stopping the agent (${why})`);
+        const exited = new Promise((resolve) => child.once("close", () => resolve()));
+        signal(child, "SIGTERM");
+        const grace = this.options.killGraceMs ?? RUNNER_KILL_GRACE_MS;
+        const timer = setTimeout(() => signal(child, "SIGKILL"), grace);
+        await exited;
+        clearTimeout(timer);
+    }
+    /** Gets the TEE's evidence for the episode's nonce and forwards it as-is. */
+    async sendEvidence(episode) {
+        const reply = (fields) => this.write({ type: "tee_evidence", episodeId: episode.episodeId, ...fields });
+        if (!this.options.teeUrl) {
+            reply({ error: "this runner has no --tee-url" });
+            return;
+        }
+        try {
+            const url = new URL("attestation", `${this.options.teeUrl.replace(/\/+$/, "")}/`);
+            url.searchParams.set("nonce", episode.nonce);
+            // In chain mode the TEE attests the rating's Arena key, the one it signs episodes with.
+            if (episode.teeKeyId) {
+                url.searchParams.set("purpose", "arena");
+                url.searchParams.set("key", episode.teeKeyId);
+            }
+            const response = await fetch(url, { signal: AbortSignal.timeout(20_000) });
+            const text = await response.text();
+            if (!response.ok)
+                throw new Error(`the TEE answered ${response.status}`);
+            if (text.length > 512 * 1024)
+                throw new Error("the TEE's evidence is too large");
+            reply({ evidence: JSON.parse(text) });
+        }
+        catch (error) {
+            reply({ error: error instanceof Error ? error.message : String(error) });
+        }
+    }
+}
+function signal(child, name) {
+    try {
+        if (process.platform !== "win32" && child.pid)
+            process.kill(-child.pid, name);
+        else
+            child.kill(name);
+    }
+    catch {
+        // Already gone.
+    }
+}
+//# sourceMappingURL=runner.js.map

package/dist/service.d.ts

@@ -0,0 +1,24 @@
+import { AgentMode } from "@bondedhq/shared";
+export declare const SERVICE_USAGE = "Usage: bonded-runner service --print systemd|pm2|docker --gateway <url> [options] -- <agent command...>\n\nPrints a ready config that keeps the runner running in the background, restarts it if it stops,\nand starts it at boot. Nothing is installed or written: copy what it prints. The runner token is\nnever put in the config; it is read from an environment file (systemd, Docker) or your shell (pm2).\n\n  --print <kind>      systemd (a unit file), pm2 (an ecosystem file) or docker (a Dockerfile and\n                      the docker run line, with --restart unless-stopped)\n  --gateway <url>     the Arena Gateway (or BONDED_GATEWAY_URL)\n  --mode tools|chain  default tools\n  --name <name>       the service's name (default bonded-runner)\n  --dir <folder>      the agent's folder (default: this one)\n  --user <user>       systemd: the user it runs as (default: you)\n\nExample:\n  bonded-runner service --print systemd --gateway https://arena.example.com -- node agent.js";
+export type ServiceKind = "systemd" | "pm2" | "docker";
+export interface ServiceOptions {
+    kind: ServiceKind;
+    gateway: string;
+    mode: AgentMode;
+    command: string[];
+    name: string;
+    dir: string;
+    user: string;
+    /** Folder of the node binary, for systemd's PATH. */
+    nodeBin: string;
+}
+export declare function serviceConfig(o: ServiceOptions): string;
+export declare function serviceCommand(argv: string[], io: {
+    cwd: string;
+    env: Record<string, string | undefined>;
+    out: (text: string) => void;
+    err: (text: string) => void;
+    user?: string;
+    nodeBin?: string;
+}): number;
+//# sourceMappingURL=service.d.ts.map

package/dist/service.js

@@ -0,0 +1,169 @@
+import { basename, dirname, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { AgentMode } from "@bondedhq/shared";
+import { gatewayUrlProblem } from "./tail.js";
+export const SERVICE_USAGE = `Usage: bonded-runner service --print systemd|pm2|docker --gateway <url> [options] -- <agent command...>
+
+Prints a ready config that keeps the runner running in the background, restarts it if it stops,
+and starts it at boot. Nothing is installed or written: copy what it prints. The runner token is
+never put in the config; it is read from an environment file (systemd, Docker) or your shell (pm2).
+
+  --print <kind>      systemd (a unit file), pm2 (an ecosystem file) or docker (a Dockerfile and
+                      the docker run line, with --restart unless-stopped)
+  --gateway <url>     the Arena Gateway (or BONDED_GATEWAY_URL)
+  --mode tools|chain  default tools
+  --name <name>       the service's name (default bonded-runner)
+  --dir <folder>      the agent's folder (default: this one)
+  --user <user>       systemd: the user it runs as (default: you)
+
+Example:
+  bonded-runner service --print systemd --gateway https://arena.example.com -- node agent.js`;
+/** A systemd ExecStart word (systemd's own quoting: double quotes, backslash escapes). */
+function systemdWord(word) {
+    return /^[A-Za-z0-9_@%+=:,./-]+$/.test(word)
+        ? word
+        : `"${word.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\$/g, "$$$$")}"`;
+}
+function runnerArgs(o) {
+    return [
+        "--gateway",
+        o.gateway,
+        ...(o.mode === "chain" ? ["--mode", "chain"] : []),
+        "--",
+        ...o.command,
+    ];
+}
+export function serviceConfig(o) {
+    const args = runnerArgs(o);
+    const envFile = `${o.dir}/${o.name}.env`;
+    switch (o.kind) {
+        case "systemd":
+            return `# /etc/systemd/system/${o.name}.service
+# 1. Put your runner token in ${envFile} (one line: BONDED_RUNNER_TOKEN=...), then
+#    chmod 600 ${envFile}
+# 2. sudo cp ${o.name}.service /etc/systemd/system/ && sudo systemctl daemon-reload
+# 3. sudo systemctl enable --now ${o.name}   (logs: journalctl -u ${o.name} -f)
+[Unit]
+Description=Bonded runner (${basename(o.dir)})
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+User=${o.user}
+WorkingDirectory=${o.dir}
+EnvironmentFile=${envFile}
+Environment=PATH=${o.nodeBin}:/usr/local/bin:/usr/bin:/bin
+ExecStart=/usr/bin/env npx --yes @bondedhq/runner ${args.map(systemdWord).join(" ")}
+Restart=always
+RestartSec=10
+# Exit code 2: the token was refused or another runner took over. Restarting won't help.
+RestartPreventExitStatus=2
+KillMode=mixed
+TimeoutStopSec=15
+NoNewPrivileges=true
+
+[Install]
+WantedBy=multi-user.target
+`;
+        case "pm2":
+            return `// ecosystem.config.cjs: start it with your runner token in the environment:
+//   BONDED_RUNNER_TOKEN=... pm2 start ecosystem.config.cjs
+//   pm2 save && pm2 startup   (starts it again at boot; pm2 keeps the token in its dump file)
+module.exports = {
+  apps: [
+    {
+      name: ${JSON.stringify(o.name)},
+      cwd: ${JSON.stringify(o.dir)},
+      script: "npx",
+      args: ${JSON.stringify(["--yes", "@bondedhq/runner", ...args])},
+      interpreter: "none",
+      autorestart: true,
+      restart_delay: 10000,
+      // Exit code 2: the token was refused or another runner took over. Restarting won't help.
+      stop_exit_codes: [2],
+      kill_timeout: 15000,
+    },
+  ],
+};
+`;
+        case "docker": {
+            const cmd = JSON.stringify(args);
+            // Not "bonded-runner": that is the base image's name.
+            const image = `${o.name}-agent`;
+            return `# Dockerfile, in your agent's folder. It builds on the runner's image: build that once from a
+# clone of the Bonded repository (docker build -f apps/runner/Dockerfile -t bonded-runner .).
+FROM bonded-runner
+COPY --chown=node:node . /agent
+WORKDIR /agent
+RUN npm ci --omit=dev   # or your package manager's install
+CMD ${cmd}
+
+# Then, with your runner token in ${o.name}.env (one line: BONDED_RUNNER_TOKEN=...):
+#   docker build -t ${image} .
+#   docker run -d --name ${o.name} --restart unless-stopped --env-file ${o.name}.env \\
+#     -e BONDED_IMAGE_DIGEST="$(docker inspect --format '{{.Id}}' ${image})" ${image}
+# --restart unless-stopped starts it again after a crash or a reboot, until you docker stop it.
+# BONDED_IMAGE_DIGEST pins the code hash to the image (the image has no git).
+`;
+        }
+    }
+}
+export function serviceCommand(argv, io) {
+    const dash = argv.indexOf("--");
+    const command = dash >= 0 ? argv.slice(dash + 1) : [];
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: dash >= 0 ? argv.slice(0, dash) : argv,
+            options: {
+                print: { type: "string" },
+                gateway: { type: "string" },
+                mode: { type: "string", default: "tools" },
+                name: { type: "string", default: "bonded-runner" },
+                dir: { type: "string" },
+                user: { type: "string" },
+                help: { type: "boolean", short: "h", default: false },
+            },
+        }));
+    }
+    catch (error) {
+        io.err(`${error instanceof Error ? error.message : String(error)}\n\n${SERVICE_USAGE}`);
+        return 1;
+    }
+    if (values.help) {
+        io.out(SERVICE_USAGE);
+        return 0;
+    }
+    const kind = values.print;
+    const gateway = values.gateway ?? io.env.BONDED_GATEWAY_URL;
+    const mode = AgentMode.safeParse(values.mode);
+    const missing = [
+        !(kind === "systemd" || kind === "pm2" || kind === "docker") && "--print systemd|pm2|docker",
+        !gateway && "--gateway",
+        !mode.success && "--mode tools|chain",
+        command.length === 0 && "an agent command after --",
+        !/^[A-Za-z0-9_.-]+$/.test(values.name) && "--name (letters, digits, . _ -)",
+    ].filter(Boolean);
+    if (missing.length) {
+        io.err(`${SERVICE_USAGE}\n\nMissing or invalid: ${missing.join(", ")}`);
+        return 1;
+    }
+    const problem = gatewayUrlProblem(gateway);
+    if (problem) {
+        io.err(problem);
+        return 1;
+    }
+    io.out(serviceConfig({
+        kind: kind,
+        gateway: gateway,
+        mode: mode.data,
+        command,
+        name: values.name,
+        dir: resolve(io.cwd, values.dir ?? "."),
+        user: values.user ?? io.user ?? io.env.USER ?? "node",
+        nodeBin: io.nodeBin ?? dirname(process.execPath),
+    }));
+    return 0;
+}
+//# sourceMappingURL=service.js.map

package/dist/tail.d.ts

@@ -0,0 +1,21 @@
+/** Keeps the last `limit` bytes written to it: an agent's output can be any size. */
+export declare class Tail {
+    private readonly limit;
+    private chunks;
+    private size;
+    constructor(limit: number);
+    push(chunk: Buffer): void;
+    /** The kept bytes as text (a character cut at the start shows as a replacement mark). */
+    text(): string;
+}
+/** Reconnect delays: doubling from `initialMs` up to `maxMs`, with up to 20% jitter either way. */
+export declare function backoffDelay(attempt: number, options: {
+    initialMs: number;
+    maxMs: number;
+}, random?: () => number): number;
+/**
+ * Why a gateway URL can't be used, or undefined when it can. The runner sends its token over this
+ * connection, so it must be https; plain http is allowed only to this machine (a local Arena).
+ */
+export declare function gatewayUrlProblem(text: string): string | undefined;
+//# sourceMappingURL=tail.d.ts.map

package/dist/tail.js

@@ -0,0 +1,50 @@
+/** Keeps the last `limit` bytes written to it: an agent's output can be any size. */
+export class Tail {
+    limit;
+    chunks = [];
+    size = 0;
+    constructor(limit) {
+        this.limit = limit;
+    }
+    push(chunk) {
+        this.chunks.push(chunk);
+        this.size += chunk.length;
+        while (this.size - (this.chunks[0]?.length ?? 0) >= this.limit && this.chunks.length > 1) {
+            this.size -= this.chunks.shift().length;
+        }
+    }
+    /** The kept bytes as text (a character cut at the start shows as a replacement mark). */
+    text() {
+        const all = Buffer.concat(this.chunks);
+        return all.subarray(Math.max(0, all.length - this.limit)).toString("utf8");
+    }
+}
+/** Reconnect delays: doubling from `initialMs` up to `maxMs`, with up to 20% jitter either way. */
+export function backoffDelay(attempt, options, random = Math.random) {
+    const base = Math.min(options.maxMs, options.initialMs * 2 ** Math.max(0, attempt - 1));
+    return Math.round(base * (0.8 + 0.4 * random()));
+}
+/**
+ * Why a gateway URL can't be used, or undefined when it can. The runner sends its token over this
+ * connection, so it must be https; plain http is allowed only to this machine (a local Arena).
+ */
+export function gatewayUrlProblem(text) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        return "the gateway URL isn't a URL";
+    }
+    if (url.protocol === "https:")
+        return undefined;
+    if (url.protocol !== "http:")
+        return "the gateway URL must be https";
+    const host = url.hostname.toLowerCase();
+    const local = host === "localhost" ||
+        host.endsWith(".localhost") ||
+        host === "[::1]" ||
+        /^127(\.[0-9]{1,3}){3}$/.test(host);
+    return local ? undefined : "the gateway URL must be https (plain http only to localhost)";
+}
+//# sourceMappingURL=tail.js.map