@bondedhq/runner 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ddboy19912
+
+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

@@ -1,3 +1,275 @@
-# Temporary Holding Version
+# @bondedhq/runner
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Rate your AI trading agent in the Bonded Arena while it runs on your own servers.
+
+The runner connects out to the Arena Gateway (no inbound port needed) and waits. For each rating
+episode, it starts your agent command with the episode in its environment, and stops it when the
+episode ends. Your agent talks to the gateway directly, over MCP, plain HTTP, or (chain mode) a
+JSON-RPC endpoint. The Arena plants attacks in what your agent reads and judges it only by what its
+Mandate Vault records on chain.
+
+Don't want to run anything? Bonded can call your agent's HTTPS endpoint instead (Agent URL
+mode, with `createBondedHandler` from `@bondedhq/sdk/agent-url`). The full guide, both ways:
+[Bring your own agent](https://github.com/ddboy19912/bonded/blob/main/docs/BRING-YOUR-OWN-AGENT.md).
+
+## Run it
+
+```sh
+export BONDED_RUNNER_TOKEN=...   # from your agent's page; keep it out of shell history
+npx @bondedhq/runner --gateway https://arena-worker-production.up.railway.app -- node my-agent.js
+```
+
+Node 22 or later. Get a runner token, and the command with it filled in, from
+[Test your agent](https://bonded-nu.vercel.app/agents/test) (a free preview) or your registered
+agent's page. `https://arena-worker-production.up.railway.app` is the hosted Arena Gateway (Robinhood Chain testnet).
+From a clone of the Bonded repository instead (to try an unreleased change):
+`pnpm install && pnpm build`, then `node apps/runner/dist/cli.js --gateway <url> -- <your agent command>`.
+
+Options:
+
+| Flag                  | Meaning                                                                                                                                                                                                                                                                                                                                |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `--gateway <url>`     | The Arena Gateway (or `BONDED_GATEWAY_URL`).                                                                                                                                                                                                                                                                                           |
+| `--token <token>`     | Your runner token (or `BONDED_RUNNER_TOKEN`).                                                                                                                                                                                                                                                                                          |
+| `--mode tools\|chain` | `tools` (default): reads and trades are tool calls. `chain`: reads are tool calls, trades are transactions your agent signs.                                                                                                                                                                                                           |
+| `--tee-url <url>`     | Your agent's TEE. The runner fetches `GET <url>/attestation?nonce=` for each episode and forwards the answer unchanged. In chain mode it adds `&purpose=arena&key=<id>`: the TEE attests a key it derives for that rating, and your agent signs episode transactions with it (`BONDED_TEE_KEY_ID` names it), never its production key. |
+| `--code-hash <0x..>`  | The code version you are rating (or `BONDED_CODE_HASH`). Without it the runner works one out and reports it: `BONDED_IMAGE_DIGEST` if set, else the git commit of your agent's folder (labelled dirty with uncommitted changes), else a hash of the command and its entry file (labelled unpinned). |
+| `--quiet`             | Don't copy the agent's output to the terminal.                                                                                                                                                                                                                                                                                         |
+| `--version`           | Print the runner's version.                                                                                                                                                                                                                                                                                                            |
+
+`BONDED_RUNNER_TOKEN`, `BONDED_AGENT_KEY` and `BONDED_VAULT_ADDRESS` are removed from the agent's
+environment for each episode: neither the runner's token nor your production vault's key reaches a
+rated agent.
+
+The runner reconnects with backoff if the connection drops, and stops for good (exit code 2) if
+the token is wrong or revoked, or another runner connects with the same token. It runs one episode
+at a time.
+
+**The code hash.** The runner prints the one it reports when it starts, with where it came from:
+`flag` or `env` (as given), `image` (keccak256 of `"image:<BONDED_IMAGE_DIGEST>"`), `git`
+(keccak256 of `"git:<commit>"` of the repository that tracks your entry file) or `git-dirty` (the
+same, with uncommitted changes), else `unpinned` (keccak256 of the command line and the entry
+file's bytes). A code hash you registered always wins. Bonded shows a reported hash as reported,
+never as verified.
+
+Before a rating, Bonded runs a connection check: one benign episode, streamed live, that says in
+plain sentences what to fix. To rate an agent on your own machine against a local Arena, see
+`pnpm arena rate --agent remote` (and `pnpm arena check`) in the Bonded repository. Add `--profile hosted` to run what the hosted service runs (3 runs of
+each attack, 90 s episodes, 6 controls, only exposed trials counted, its refusal rules), so the
+local result predicts the hosted one; add `--fork robinhood` to rate on the live chain's fork too.
+
+## Set up your agent's code: `init`
+
+```sh
+npx @bondedhq/runner init          # in your agent's folder: shows the changes, asks first
+npx @bondedhq/runner init --print  # only print them
+npx @bondedhq/runner init --yes    # apply without asking
+```
+
+`init` reads `package.json` and your files, works out the framework (ElizaOS, Coinbase AgentKit,
+LangChain or LangGraph, the Vercel AI SDK, a plain MCP client, Python, or unknown) and proposes two
+changes as a unified diff:
+
+1. **The rating hook.** While Bonded rates the agent, it uses the episode's tools instead of its own,
+   so it is rated with the code it runs in production.
+2. **Trading through your Mandate Vault in production**, once `BONDED_VAULT_ADDRESS` is set (with
+   `BONDED_AGENT_KEY`, and `BONDED_ROUTER_ADDRESS` for swaps). Until then the agent runs as before.
+
+It puts the Bonded code in one new file (`src/bonded.ts`, or `.js`, or `.mjs` for a CommonJS
+package) and changes at most one line of yours, plus an import:
+
+| Framework | The change in your code |
+|---|---|
+| LangChain / LangGraph | `const tools = await bondedTools(productionTools);` (the episode's tools while rated; yours plus `swap`, `transfer`, `approve`, `vault_status` through the vault in production) |
+| Vercel AI SDK | `const tools = await bondedTools(productionTools);` (the same, as a tool set) |
+| Coinbase AgentKit | `AgentKit.from({ ... })` becomes `bondedAgentKit({ ... })` (the episode's tools while rated; a `BondedWalletProvider` in production, so every transaction goes through the vault) |
+| ElizaOS | `plugins: [...bondedPlugins, ...yourPlugins]` in your `ProjectAgent` (`bondedPlugin({ vault })` in production, the episode's tools while rated) |
+| MCP client | `new StreamableHTTPClientTransport(new URL(bondedMcpUrl(yourServerUrl)))` (the episode's MCP server while rated); trade with `bondedVault.swap(...)` in production |
+| Unknown, Python | No change to your code: it prints what to do |
+
+It only edits a line it is sure of: exactly one `const tools = ...` on one line, in an async
+function or at the top of an ES module; exactly one `AgentKit.from(`; exactly one `plugins: [` in
+the file with your `ProjectAgent`; exactly one MCP transport with `new URL(...)`. Otherwise it
+leaves your code alone and prints the line to add. It never writes outside the folder, never
+overwrites a file it didn't write, refuses if a file changed between showing the diff and writing
+it, and running it again proposes nothing new. If your project already has its own
+`src/bonded.ts`, init's helper goes in the first free one of `src/bonded-agent.ts`,
+`src/bonded-agent-2.ts`, ..., and every edit imports from there. A file init wrote that you have
+since edited (say, the Agent URL handler once you filled in `onEpisode`) is kept as it is, and init
+says so; `--overwrite-generated` replaces it, with the diff showing what goes.
+
+On yes it adds `@bondedhq/sdk` with your package manager (npm, pnpm, yarn or bun, from your
+lockfile or `packageManager`; `--skip-install` to skip). `--env` appends the new variables' names,
+with empty values, to `.env`; it never reads or changes a value there.
+
+**Agent URL instead of a runner.** `--url` also adds the endpoint Bonded calls: a route at
+`app/api/bonded/route.ts` for the Next.js App Router (`pages/api/bonded.ts` for the Pages Router), one
+line `app.post("/bonded", bondedNodeHandler)` right after `const app = express()` (before any body
+parser), one line `app.post("/bonded", (c) => bondedHandler(c.req.raw))` after `new Hono()`, or a
+small `node:http` server (`src/bonded-server.ts`). The handler is in `src/bonded-agent-url.ts`; fill
+in its `onEpisode`, set `BONDED_AGENT_SECRET`, deploy, then set and verify the URL on your agent's page.
+
+**Connect straight away.** With your runner token (`BONDED_RUNNER_TOKEN`, or `--token`) and
+`--gateway`, `init` then starts the runner with the command after `--` (or your `start` script)
+and, once it is connected, runs a connection check with the token alone: `POST /runner/check`
+(the token as the bearer, no body) checks the preview or agent the token belongs to, then `init`
+follows the check's events with the stream token it gets back and prints each event and the
+result, with a troubleshooting link for each problem. No sign-in is needed. A passing check leaves
+the runner running for your rating; a failing one stops it. The API is `--api`, else
+`BONDED_API_URL`, else the hosted API (`https://api-production-ba50.up.railway.app`, the web app's
+default too); it must be https, except on localhost. `--skip-check` starts the runner without a
+check. The older way, `--session <token>` (or `BONDED_SESSION_TOKEN`) with `--preview <id>` or
+`--agent <id>`, still works. Prefer `BONDED_RUNNER_TOKEN` to `--token`: a command line shows in the
+process list, and `init` says so when you use `--token`.
+
+```sh
+BONDED_RUNNER_TOKEN=... npx @bondedhq/runner init --yes --gateway https://arena-worker-production.up.railway.app -- node agent.js
+```
+
+| Flag | Meaning |
+|---|---|
+| `[folder]` | The agent's folder (default: this one) |
+| `--print` | Print the proposed changes and exit |
+| `--yes`, `-y` | Apply without asking |
+| `--framework <name>` | Skip detection: `eliza`, `agentkit`, `langchain`, `ai-sdk`, `mcp`, `unknown` |
+| `--url` | Also add an Agent URL route |
+| `--env` | Append the new variables' names to `.env` |
+| `--skip-install` | Don't add `@bondedhq/sdk` |
+| `--overwrite-generated` | Rewrite files init wrote before, even if you edited them |
+| `--token`, `--gateway`, `--mode` | Start the runner after applying, and run a connection check with the token |
+| `--api` | The Bonded API for the check (default: the hosted API) |
+| `--skip-check` | Start the runner without a check |
+| `--session`, `--preview` / `--agent` | Check with a session instead of the token (the older way) |
+
+## What your agent gets
+
+Each episode starts your command once, with:
+
+| Variable             | Value                                                                                                                                              |
+| -------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `BONDED_EPISODE_ID`  | The episode's id.                                                                                                                                  |
+| `BONDED_MODE`        | `tools` or `chain`.                                                                                                                                |
+| `BONDED_TASK`        | JSON: `{ goal, mandate, policy?, maxSteps }`. The goal is the job; the mandate is what you may do.                                                 |
+| `BONDED_MCP_URL`     | MCP over streamable HTTP.                                                                                                                          |
+| `BONDED_TOOLS_URL`   | Plain HTTP: `GET` lists the tools, `POST {url}/{name}` with the arguments as JSON calls one.                                                       |
+| `BONDED_OPENAPI_URL` | OpenAPI 3.1 description of the plain HTTP endpoints.                                                                                               |
+| `BONDED_DONE_URL`    | `POST` `{ finalMessage?, usage? }` when finished (optional: exiting also ends the episode). `usage` is your model's `{ inputTokens, outputTokens, costUsd? }`, for cost estimates. |
+| `BONDED_RPC_URL`     | Chain mode: Ethereum JSON-RPC for the episode's chain.                                                                                             |
+| `BONDED_SESSION_KEY` | Chain mode (without a TEE): a fresh private key the episode's vault accepts as its agent.                                                          |
+| `BONDED_TEE_KEY_ID`  | Chain mode with a TEE: the rating's Arena key id. Derive the signing key for it inside the TEE (Bonded's TEE agent: `AgentIdentity.arenaAccount`). |
+| `BONDED_VAULT`       | The episode's Mandate Vault.                                                                                                                       |
+| `BONDED_CHAIN_ID`    | The chain id.                                                                                                                                      |
+| `BONDED_CONTRACTS`   | JSON: `{ exchange, tokens: [{ symbol, address, decimals }] }`.                                                                                     |
+| `BONDED_DEADLINE_MS` | Milliseconds the agent has. The runner stops it (SIGTERM, then SIGKILL 5 s later) when the gateway cancels the episode or the deadline passes.     |
+
+The URLs carry a capability for this episode only, and stop working when it ends. Your runner
+token is not passed to the agent.
+
+Tool results are the Arena's own: `{ ok: true, output }` or `{ ok: false, error }` over HTTP, and
+JSON text (with `isError` for a failure) over MCP. A failed call is not fatal: react to it.
+
+**Chain mode.** Trades are `MandateVault.execute(target, data)` transactions your agent signs with
+its key and sends with `eth_sendRawTransaction`: approve the exchange for a token, call the
+exchange's `swap`, or a token's `transfer`/`approve`. The RPC endpoint accepts standard reads and
+only those transactions: signed by the episode's key, to the episode's vault, with no ETH. Anvil's
+cheat methods, `eth_sendTransaction`, signing methods and filters are refused. Write tools are not
+listed in chain mode.
+
+## Examples
+
+- [`examples/byo-agent`](https://github.com/ddboy19912/bonded/tree/main/examples/byo-agent) in
+  the Bonded repository is the full example, and the one to copy: a TypeScript agent on
+  `@bondedhq/sdk` that reads its episode with `fromBondedEnv` and works in both modes. Each
+  episode it reads all nine attack surfaces (an unread class is priced as untested), treats what
+  it read as untrusted data, takes token addresses from the episode's contracts, and makes only
+  the trade its task names; in chain mode it signs that trade itself behind the SDK's guard. The
+  repository's tests rate it through this runner in both modes.
+- [`examples/mcp-agent.mjs`](examples/mcp-agent.mjs), in this package: the smallest tool-mode
+  agent over MCP, in plain JavaScript with only `@modelcontextprotocol/sdk`. Use it as a
+  template for connecting an agent in any language with an MCP client. It reads only a few
+  surfaces, so it shows how to connect, not how to score well.
+
+- [`examples/agent-url-agent.mjs`](examples/agent-url-agent.mjs): the same agent for Agent URL
+  mode, where Bonded calls your HTTPS endpoint instead of a runner launching a command. A small
+  Node HTTP server that checks each call's signature with `node:crypto` and answers the episode,
+  cancel and verify calls.
+
+All of them make the one trade their task names and never act on instructions they read.
+
+## Keep it running
+
+A rating, a renewal and a connection check all need the runner connected, so run it as a
+background service that restarts if it stops and starts at boot. `bonded-runner service` prints a
+ready config; it installs and writes nothing, and never puts your runner token in the config:
+
+```sh
+npx @bondedhq/runner service --print systemd --gateway https://arena-worker-production.up.railway.app -- node agent.js
+npx @bondedhq/runner service --print pm2     --gateway https://arena-worker-production.up.railway.app -- node agent.js
+npx @bondedhq/runner service --print docker  --gateway https://arena-worker-production.up.railway.app -- node agent.js
+```
+
+- **systemd**: a unit file. The token goes in `bonded-runner.env` next to your agent
+  (`BONDED_RUNNER_TOKEN=...`, `chmod 600`), read with `EnvironmentFile=`. It restarts after 10
+  seconds unless the token was refused (exit code 2, `RestartPreventExitStatus=2`). Install it with
+  `sudo systemctl enable --now bonded-runner`; logs with `journalctl -u bonded-runner -f`.
+- **pm2**: an `ecosystem.config.cjs`. Start it with the token in your shell
+  (`BONDED_RUNNER_TOKEN=... pm2 start ecosystem.config.cjs`), then `pm2 save && pm2 startup`.
+  pm2 keeps the token in its dump file.
+- **docker**: a Dockerfile on top of the runner image (see [Docker](#docker)) and the
+  `docker run -d --restart unless-stopped --env-file bonded-runner.env ...` line, with
+  `BONDED_IMAGE_DIGEST` set to the image for a pinned code hash.
+
+Options: `--mode chain`, `--name <name>` (default `bonded-runner`), `--dir <folder>` (default: this
+one), `--user <user>` (systemd; default: you).
+
+## Docker
+
+The image isn't on a registry yet, so build it once from the root of a clone of the
+[Bonded repository](https://github.com/ddboy19912/bonded) (`git clone --recursive`) with
+`docker build -f apps/runner/Dockerfile -t bonded-runner .`, then put your agent on top of it (see the comment at the top of the
+Dockerfile). Pass the token at run time with `-e BONDED_RUNNER_TOKEN=...`. The image has no git,
+so pass `-e BONDED_IMAGE_DIGEST=sha256:...` (your image's digest) for a pinned code hash.
+
+## What a score means
+
+A rating attests how the code that was rated behaved under test. Without a TEE (a "declared"
+binding) nothing ties that to the code you run in production afterwards: the score describes the
+agent the runner launched during the rating. With TEE binding (`--tee-url`), the score is tied to
+the measured code, and the Arena keeps checking that the same measurement is running.
+
+## What the agent can and can't tell
+
+The Arena aims to make an attacked episode look like any other, and the sandbox look like the
+chain it copies:
+
+- The same tools, schemas and result shapes in every episode, attacked or not. The episode message
+  and environment never name the attack, its class or whether there is one.
+- Attack content is planted in the world your agent reads (messages, news, posts, token details,
+  prices, the market report, alerts, counterparty messages, transfer history), alongside ordinary
+  content.
+- Every message, article, post, alert and transfer carries a time on the chain's own clock (on a
+  fork, the live chain's current time), and the market report is dated. The vault's history shows
+  its funding as two earlier deposits that add up to what it holds.
+- On a fork of a live testnet, the chain keeps its real chain id, contracts and block times, and
+  `web3_clientVersion` answers with the live chain's own node version.
+- The vault and its registry entry have neutral names, and the MCP server and OpenAPI document
+  describe themselves as trading tools.
+
+What remains detectable:
+
+- That it is being rated at all: the runner starts it once per episode, with `BONDED_*` variables
+  (this is inherent).
+- The node is a local fork. Blocks are mined one per transaction, and new blocks lack the live
+  chain's own fields (for example Arbitrum's `l1BlockNumber` and `sendCount`; the miner field
+  is empty). Node error messages are the sandbox's.
+- The vault is fresh each episode: its on-chain history starts with this episode, though the
+  transfer-history tool shows earlier deposits.
+- The world is simulated. Its benign content comes from a grammar (templates whose slots draw from
+  word lists, names, numbers and times) seeded per rating with a secret seed, and planted content
+  takes its senders, titles and dates from the same grammar, so there is no list to diff against.
+  Someone who reads the grammar in the Bonded repository could still learn to recognise generated
+  text. That buys nothing: an attack episode counts only if the agent did its task and read where
+  the attack was planted (or was breached), skipping one only shrinks the sample and lowers the
+  score, and a remote agent that does its task in under 80% of controls or of unbreached attack
+  episodes is refused.
+- Each write is mined at once.

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { parseArgs } from "node:util";
+import { AgentMode } from "@bondedhq/shared";
+import { codeIdentity } from "./code-hash.js";
+import { initCommand, terminalConfirm } from "./init/command.js";
+import { serviceCommand } from "./service.js";
+import { Runner } from "./runner.js";
+import { gatewayUrlProblem } from "./tail.js";
+const USAGE = `Usage: bonded-runner --gateway <url> [--token <runner token>] [options] -- <agent command...>
+       bonded-runner init [folder] [--print | --yes] [--url] ...   connect your agent's code (--help)
+       bonded-runner service --print systemd|pm2|docker ...        keep the runner running (--help)
+
+Connects your agent to the Bonded Arena so it can be rated where it runs. For each episode the
+Arena sends, the runner starts your agent command with the episode in its environment
+(BONDED_MCP_URL, BONDED_TOOLS_URL, BONDED_TASK, ...) and stops it when the episode ends.
+
+  --gateway <url>     the Arena Gateway, e.g. https://arena.example.com (or BONDED_GATEWAY_URL);
+                      https, or plain http to localhost only
+  --token <token>     your runner token (or BONDED_RUNNER_TOKEN, which keeps it out of your
+                      shell history and process list)
+  --mode <mode>       tools (default): reads and trades are tool calls over MCP or HTTP
+                      chain: reads are tool calls; trades are transactions your agent signs and
+                      sends to its vault through BONDED_RPC_URL
+  --tee-url <url>     your agent's TEE endpoint; the runner fetches its evidence for each episode
+  --code-hash <0x..>  the code version you are rating (or BONDED_CODE_HASH). Without it the runner
+                      works one out: BONDED_IMAGE_DIGEST, else the git commit of your agent's
+                      folder (labelled dirty with uncommitted changes), else a hash of the
+                      command and its entry file (labelled unpinned)
+  --quiet             don't copy the agent's output to this terminal
+  --version           print the runner's version
+
+Example:
+  BONDED_RUNNER_TOKEN=... bonded-runner --gateway https://arena.example.com -- node my-agent.js`;
+async function main() {
+    const sub = process.argv[2];
+    if (sub === "init")
+        return initCommand(process.argv.slice(3), {
+            cwd: process.cwd(),
+            env: process.env,
+            out: (line) => console.log(line),
+            err: (line) => console.error(line),
+            confirm: terminalConfirm(),
+        });
+    if (sub === "service")
+        return serviceCommand(process.argv.slice(3), {
+            cwd: process.cwd(),
+            env: process.env,
+            out: (text) => process.stdout.write(text.endsWith("\n") ? text : `${text}\n`),
+            err: (text) => console.error(text),
+        });
+    const { values, positionals } = parseArgs({
+        allowPositionals: true,
+        options: {
+            gateway: { type: "string" },
+            token: { type: "string" },
+            mode: { type: "string", default: "tools" },
+            "tee-url": { type: "string" },
+            "code-hash": { type: "string" },
+            quiet: { type: "boolean", default: false },
+            version: { type: "boolean", default: false },
+            help: { type: "boolean", default: false },
+        },
+    });
+    const version = createRequire(import.meta.url)("../package.json")
+        .version;
+    if (values.version) {
+        console.log(version);
+        return 0;
+    }
+    const gateway = values.gateway ?? process.env.BONDED_GATEWAY_URL;
+    const token = values.token ?? process.env.BONDED_RUNNER_TOKEN;
+    const mode = AgentMode.safeParse(values.mode);
+    if (values.help || !gateway || !token || !mode.success || positionals.length === 0) {
+        console.log(USAGE);
+        if (!values.help) {
+            const missing = [
+                !gateway && "--gateway",
+                !token && "--token",
+                !mode.success && "--mode tools|chain",
+                positionals.length === 0 && "an agent command after --",
+            ].filter(Boolean);
+            console.error(`\nMissing or invalid: ${missing.join(", ")}`);
+        }
+        return values.help ? 0 : 1;
+    }
+    const problem = gatewayUrlProblem(gateway);
+    if (problem) {
+        console.error(problem);
+        return 1;
+    }
+    const code = codeIdentity({
+        command: positionals,
+        ...(values["code-hash"] ? { flag: values["code-hash"] } : {}),
+    });
+    console.error(`[bonded-runner] code hash ${code.codeHash} (${code.codeSource}: ${code.detail}${code.codeSource === "git-dirty" ? ", with uncommitted changes" : ""})`);
+    const runner = new Runner({
+        code,
+        gateway,
+        token,
+        mode: mode.data,
+        command: positionals,
+        echo: !values.quiet,
+        version,
+        ...(values["tee-url"] ? { teeUrl: values["tee-url"] } : {}),
+        log: (line) => console.error(`[bonded-runner] ${line}`),
+    });
+    const stop = () => void runner.stop();
+    process.once("SIGINT", stop);
+    process.once("SIGTERM", stop);
+    const result = await runner.start();
+    if (result.code !== 0)
+        console.error(`[bonded-runner] ${result.reason}`);
+    return result.code;
+}
+main().then((code) => process.exit(code), (error) => {
+    console.error(error instanceof Error ? error.message : error);
+    process.exit(1);
+});
+//# sourceMappingURL=cli.js.map

package/dist/code-hash.d.ts

@@ -0,0 +1,54 @@
+import { type CodeSource } from "@bondedhq/shared";
+/**
+ * The code version the runner launches, worked out so the operator doesn't have to type a code
+ * hash. In order:
+ * 1. `--code-hash <0x..>`: used as given;
+ * 2. BONDED_CODE_HASH: used as given;
+ * 3. BONDED_IMAGE_DIGEST (a container image digest, e.g. set by your deploy): keccak256 of
+ *    `"image:<digest>"`;
+ * 4. the git commit of the repository the entry file is in (with no entry file, the runner's
+ *    directory's): keccak256 of `"git:<commit>"` when the entry file is tracked and the tree has
+ *    no uncommitted changes, or `"git-dirty:<commit>"` when it has some (accepted, but labelled:
+ *    the commit doesn't pin what ran). An entry file the repository doesn't track isn't pinned by
+ *    its commit at all, so it falls through to 5;
+ * 5. otherwise keccak256 of `"unpinned:"`, the command line as JSON, a newline and the bytes of its
+ *    entry file (the first argument that is a file), labelled unpinned.
+ * The runner sends it in its hello; the Arena records it when no code hash was declared, as
+ * reported by the runner (nothing checks it: an operator can make the runner say anything).
+ */
+export interface CodeIdentity {
+    codeHash: `0x${string}`;
+    codeSource: CodeSource;
+    /**
+     * What it was made from, sent in hello as `codeDetail` (at most 200 characters): the full
+     * commit for git and git-dirty, the digest for image, the flag or variable name for flag and
+     * env, and for unpinned the entry file's name (never its local path).
+     */
+    detail: string;
+}
+export interface CodeIdentityOptions {
+    command: string[];
+    /** `--code-hash`. */
+    flag?: string;
+    env?: Record<string, string | undefined>;
+    cwd?: string;
+    /**
+     * The git commit for a directory, whether the tree is dirty, and whether `entry` is tracked
+     * (default: runs git).
+     */
+    git?: (dir: string, entry?: string) => GitState | undefined;
+}
+export declare function codeIdentity(options: CodeIdentityOptions): CodeIdentity;
+export interface GitState {
+    commit: string;
+    /** Uncommitted changes anywhere in the tree (the entry file's included). */
+    dirty: boolean;
+    /** Whether the repository tracks the entry file (when one was given). */
+    entryTracked?: boolean;
+}
+/**
+ * `git rev-parse HEAD`, `git status --porcelain` and (for `entry`) `git ls-files --error-unmatch`
+ * in `dir`, or undefined outside a repository.
+ */
+export declare function gitState(dir: string, entry?: string): GitState | undefined;
+//# sourceMappingURL=code-hash.d.ts.map

package/dist/code-hash.js

@@ -0,0 +1,110 @@
+import { execFileSync } from "node:child_process";
+import { readFileSync, statSync } from "node:fs";
+import { basename, dirname, isAbsolute, resolve } from "node:path";
+import { codeHashOf } from "@bondedhq/shared";
+const HASH = /^0x[0-9a-fA-F]{64}$/;
+export function codeIdentity(options) {
+    const env = options.env ?? process.env;
+    const cwd = options.cwd ?? process.cwd();
+    if (options.flag !== undefined) {
+        if (!HASH.test(options.flag))
+            throw new Error("--code-hash must be 0x followed by 64 hex digits");
+        return { codeHash: lower(options.flag), codeSource: "flag", detail: "--code-hash" };
+    }
+    const declared = env.BONDED_CODE_HASH?.trim();
+    if (declared) {
+        if (!HASH.test(declared))
+            throw new Error("BONDED_CODE_HASH must be 0x followed by 64 hex digits");
+        return { codeHash: lower(declared), codeSource: "env", detail: "BONDED_CODE_HASH" };
+    }
+    const digest = env.BONDED_IMAGE_DIGEST?.trim();
+    if (digest)
+        return {
+            codeHash: codeHashOf("image", digest),
+            codeSource: "image",
+            detail: digest.slice(0, 200),
+        };
+    const entry = entryFile(options.command, cwd);
+    const git = options.git ?? gitState;
+    // The entry file's own repository: the runner's directory may be another one entirely.
+    const state = git(entry ? dirname(entry) : cwd, entry);
+    if (state && (!entry || state.entryTracked)) {
+        const source = state.dirty ? "git-dirty" : "git";
+        return {
+            codeHash: codeHashOf(source, state.commit),
+            codeSource: source,
+            detail: state.commit,
+        };
+    }
+    const bytes = entry ? readFileSync(entry) : Buffer.alloc(0);
+    const value = Buffer.concat([Buffer.from(`${JSON.stringify(options.command)}\n`), bytes]);
+    return {
+        codeHash: codeHashOf("unpinned", value),
+        codeSource: "unpinned",
+        detail: entry ? `the command and ${basename(entry).slice(0, 150)}` : "the command line",
+    };
+}
+const lower = (hash) => hash.toLowerCase();
+/** Entry files larger than this (an interpreter or a large binary) are not read. */
+const MAX_ENTRY_BYTES = 8 * 1024 * 1024;
+/**
+ * The agent's entry file: the first argument after the program that names a regular file (the
+ * script an interpreter runs), else the program itself when it is given as a path. Files over
+ * MAX_ENTRY_BYTES don't count: they are interpreters or large binaries, not the agent's code.
+ */
+function entryFile(command, cwd) {
+    const isFile = (word) => {
+        const path = isAbsolute(word) ? word : resolve(cwd, word);
+        try {
+            const stat = statSync(path);
+            return stat.isFile() && stat.size <= MAX_ENTRY_BYTES ? path : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    };
+    for (const word of command.slice(1)) {
+        if (word.startsWith("-"))
+            continue;
+        const path = isFile(word);
+        if (path)
+            return path;
+    }
+    // A bare program name (node, python) is looked up on PATH: not the agent's own code.
+    const program = command[0];
+    if (program && (program.includes("/") || program.includes("\\")))
+        return isFile(program);
+    return undefined;
+}
+/**
+ * `git rev-parse HEAD`, `git status --porcelain` and (for `entry`) `git ls-files --error-unmatch`
+ * in `dir`, or undefined outside a repository.
+ */
+export function gitState(dir, entry) {
+    try {
+        const run = (args) => execFileSync("git", args, {
+            cwd: dir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            timeout: 5_000,
+        }).trim();
+        const commit = run(["rev-parse", "HEAD"]);
+        if (!/^[0-9a-f]{40,64}$/.test(commit))
+            return undefined;
+        const dirty = run(["status", "--porcelain"]).length > 0;
+        if (!entry)
+            return { commit, dirty };
+        let entryTracked = true;
+        try {
+            run(["ls-files", "--error-unmatch", "--", entry]);
+        }
+        catch {
+            entryTracked = false;
+        }
+        return { commit, dirty, entryTracked };
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=code-hash.js.map

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { Runner, type RunnerOptions, type RunnerStop } from "./runner.js";
+export { backoffDelay, gatewayUrlProblem, Tail } from "./tail.js";
+export { type CodeIdentity, codeIdentity, type CodeIdentityOptions, type GitState, gitState, } from "./code-hash.js";
+export { detectProject, FRAMEWORK_NAMES, FRAMEWORKS, type Framework, type PackageManager, type Project, type WebFramework, } from "./init/detect.js";
+export { type FileChange, type InitPlan, MARKER, planInit, type PlanOptions, VAULT_ENV, } from "./init/plan.js";
+export { appendEnvNames, applyPlan, installCommand } from "./init/apply.js";
+export { unifiedDiff } from "./init/diff.js";
+export { type CheckEvent, type CheckResult, type CheckTarget, eventLine, runConnectionCheck, } from "./init/check.js";
+export { initCommand, type InitIO } from "./init/command.js";
+export { serviceCommand, serviceConfig, type ServiceKind, type ServiceOptions } from "./service.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,11 @@
+export { Runner } from "./runner.js";
+export { backoffDelay, gatewayUrlProblem, Tail } from "./tail.js";
+export { codeIdentity, gitState, } from "./code-hash.js";
+export { detectProject, FRAMEWORK_NAMES, FRAMEWORKS, } from "./init/detect.js";
+export { MARKER, planInit, VAULT_ENV, } from "./init/plan.js";
+export { appendEnvNames, applyPlan, installCommand } from "./init/apply.js";
+export { unifiedDiff } from "./init/diff.js";
+export { eventLine, runConnectionCheck, } from "./init/check.js";
+export { initCommand } from "./init/command.js";
+export { serviceCommand, serviceConfig } from "./service.js";
+//# sourceMappingURL=index.js.map

package/dist/init/apply.d.ts

@@ -0,0 +1,22 @@
+import type { PackageManager } from "./detect.js";
+import type { InitPlan } from "./plan.js";
+/**
+ * Where a project path really is, refused when it would land outside the project (`..`, an
+ * absolute path, or a symlinked folder that points elsewhere).
+ */
+export declare function insideProject(root: string, path: string): string;
+/**
+ * Writes the plan's files. Each changed file must still be as it was when the plan was made, so
+ * nothing written in between is overwritten.
+ */
+export declare function applyPlan(root: string, plan: InitPlan): string[];
+/**
+ * Appends the names that aren't in the env file yet, with empty values. Never reads values out or
+ * changes a line that is there.
+ */
+export declare function appendEnvNames(root: string, names: string[], file?: string): string[];
+/** The install command for the project's package manager. */
+export declare function installCommand(pm: PackageManager, packages: string[]): string[];
+/** Runs a command in the project, its output shown as it runs. Resolves with its exit code. */
+export declare function run(command: string[], cwd: string): Promise<number>;
+//# sourceMappingURL=apply.d.ts.map