@bondedhq/runner 0.1.0 → 0.1.2

package/README.md

@@ -16,12 +16,14 @@ mode, with `createBondedHandler` from `@bondedhq/sdk/agent-url`). The full guide
 
 ```sh
 export BONDED_RUNNER_TOKEN=...   # from your agent's page; keep it out of shell history
-npx @bondedhq/runner --gateway https://arena.example.com -- node my-agent.js
+npx @bondedhq/runner --gateway https://arena-worker-production.up.railway.app -- node my-agent.js
 ```
 
-Not on npm yet (the founder publishes with `pnpm release:packages`). Until then, from a clone of
-the Bonded repository: `pnpm install && pnpm build`, then
-`node apps/runner/dist/cli.js --gateway <url> -- <your agent command>`.
+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:
 
@@ -73,8 +75,9 @@ changes as a unified diff:
 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:
+It puts the Bonded code in one new file (`src/bonded.ts` in a TypeScript project, meaning one with
+a tsconfig.json, a typescript dependency or `.ts` source files; else `.js`, or `.mjs` for a
+CommonJS package) and changes at most one line of yours, plus an import:
 
 | Framework | The change in your code |
 |---|---|
@@ -121,7 +124,7 @@ check. The older way, `--session <token>` (or `BONDED_SESSION_TOKEN`) with `--pr
 process list, and `init` says so when you use `--token`.
 
 ```sh
-BONDED_RUNNER_TOKEN=... npx @bondedhq/runner init --yes --gateway https://arena.example.com -- node agent.js
+BONDED_RUNNER_TOKEN=... npx @bondedhq/runner init --yes --gateway https://arena-worker-production.up.railway.app -- node agent.js
 ```
 
 | Flag | Meaning |
@@ -183,10 +186,20 @@ listed in chain mode.
   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.
-
+  agent over MCP, in plain JavaScript with only `@modelcontextprotocol/sdk` and no model. It
+  reads all nine surfaces and its portfolio, then makes the one trade its task names. Use it as a
+  template for connecting an agent in any language with an MCP client, or to try Bonded before
+  you have an agent of your own:
+
+  ```sh
+  mkdir bonded-test && cd bonded-test && npm init -y
+  npm install @bondedhq/runner @modelcontextprotocol/sdk
+  cp node_modules/@bondedhq/runner/examples/mcp-agent.mjs .
+  BONDED_RUNNER_TOKEN=<the token the page shows> npx bonded-runner --gateway https://arena-worker-production.up.railway.app --mode tools -- node mcp-agent.mjs
+  ```
+
+  On the Test your agent page, choose "Something else (MCP or HTTP)" and "On my computer or
+  server", and take the token from the runner command it shows.
 - [`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,
@@ -201,9 +214,9 @@ background service that restarts if it stops and starts at boot. `bonded-runner
 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.example.com -- node agent.js
-npx @bondedhq/runner service --print pm2     --gateway https://arena.example.com -- node agent.js
-npx @bondedhq/runner service --print docker  --gateway https://arena.example.com -- node agent.js
+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
@@ -222,11 +235,11 @@ one), `--user <user>` (systemd; default: you).
 
 ## Docker
 
-Build the image from the repository root 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
+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. The image
-isn't published yet: build it yourself.
+so pass `-e BONDED_IMAGE_DIGEST=sha256:...` (your image's digest) for a pinned code hash.
 
 ## What a score means
 

package/dist/init/check.d.ts

@@ -74,6 +74,9 @@ export declare function serverSentEvents(body: ReadableStream<Uint8Array>): Asyn
 export declare function eventLine(event: CheckEvent): string;
 /** Where each problem's fix is explained, by its code (the anchor). */
 export declare const TROUBLESHOOTING_URL = "https://bonded-nu.vercel.app/docs/guides/troubleshooting/";
-/** The result as lines: the verdict, then each problem and warning, with its fix's link. */
+/**
+ * The result as lines: the verdict, then each problem and warning, with its fix's link. A warning
+ * that is only a note (NOTE_CODES in @bondedhq/shared, e.g. model usage) prints as a note.
+ */
 export declare function resultLines(result: CheckResult): string[];
 //# sourceMappingURL=check.d.ts.map

package/dist/init/check.js

@@ -6,6 +6,7 @@
  * `POST /previews/:id/checks` or `/self/agents/:id/checks`, then the same events with the
  * session. The API decides pass or fail; this only prints it.
  */
+import { isNote, problemCode } from "@bondedhq/shared";
 /** The Bonded API the runner talks to when neither --api nor BONDED_API_URL says otherwise. */
 export const DEFAULT_API_URL = "https://api-production-ba50.up.railway.app";
 export async function runConnectionCheck(target, onEvent, options = {}) {
@@ -140,13 +141,17 @@ export function eventLine(event) {
 }
 /** Where each problem's fix is explained, by its code (the anchor). */
 export const TROUBLESHOOTING_URL = "https://bonded-nu.vercel.app/docs/guides/troubleshooting/";
-/** The result as lines: the verdict, then each problem and warning, with its fix's link. */
+/**
+ * The result as lines: the verdict, then each problem and warning, with its fix's link. A warning
+ * that is only a note (NOTE_CODES in @bondedhq/shared, e.g. model usage) prints as a note.
+ */
 export function resultLines(result) {
     const line = (kind, text) => {
         const code = result.issues?.find((i) => i.message === text && i.severity === kind)?.code;
+        const label = kind === "warning" && isNote(code ?? problemCode(text)) ? "note" : kind;
         return code && code !== "other" && /^[a-z0-9-]+$/.test(code)
-            ? [`  ${kind}: ${text}`, `    how to fix: ${TROUBLESHOOTING_URL}#${code}`]
-            : [`  ${kind}: ${text}`];
+            ? [`  ${label}: ${text}`, `    how to fix: ${TROUBLESHOOTING_URL}#${code}`]
+            : [`  ${label}: ${text}`];
     };
     return [
         result.passed ? "Connection check passed: a rating will work." : "Connection check failed:",

package/dist/init/command.js

@@ -152,7 +152,7 @@ export async function initCommand(argv, io) {
     const token = values.token ?? io.env.BONDED_RUNNER_TOKEN;
     const gateway = values.gateway ?? io.env.BONDED_GATEWAY_URL;
     if (!token || !gateway) {
-        io.out(`\nNext: start the runner with your runner token (from your agent's page):\n  BONDED_RUNNER_TOKEN=... npx @bondedhq/runner --gateway <gateway url>${mode.data === "chain" ? " --mode chain" : ""} -- ${agentCommand(project, command).join(" ") || "<your agent command>"}\nthen run a connection check on the page. Or run init again with BONDED_RUNNER_TOKEN and --gateway: it starts the runner and runs the check here.`);
+        io.out(`\nNext: start the runner with your runner token (from your agent's page):\n  ${runnerLine("<gateway url>", mode.data, agentCommand(project, command).join(" ") || "<your agent command>")}\nthen run a connection check on the page. Or run init again with BONDED_RUNNER_TOKEN and --gateway: it starts the runner and runs the check here.`);
         return 0;
     }
     const problem = gatewayUrlProblem(gateway);
@@ -162,7 +162,8 @@ export async function initCommand(argv, io) {
     }
     const agent = agentCommand(project, command);
     if (!agent.length) {
-        io.err("No agent command: put it after -- (e.g. -- node agent.js), or add a start script to package.json.");
+        const example = guessedCommand(project) ?? "node agent.js";
+        io.err(`No agent command: init can't tell how your agent starts (there's no start script in package.json). Put it after --, e.g. \`-- ${example}\`, or start the runner yourself:\n  ${runnerLine(gateway, mode.data, guessedCommand(project) ?? "<your agent command>")}`);
         return 1;
     }
     if (values.token)
@@ -210,6 +211,18 @@ export function apiUrlProblem(api) {
         return undefined;
     return "--api must be https (plain http only on localhost)";
 }
+/** The runner's own command line, with the token left for the owner to fill in. */
+function runnerLine(gateway, mode, command) {
+    return `BONDED_RUNNER_TOKEN=... npx @bondedhq/runner --gateway ${gateway} --mode ${mode} -- ${command}`;
+}
+/**
+ * A likely start command, only to show as an example (never run): `node <file>` when the folder
+ * has a single JavaScript file at its top level, like a copied example agent.
+ */
+function guessedCommand(project) {
+    const top = project.sources.filter((f) => !f.includes("/") && /\.(m?js)$/.test(f));
+    return top.length === 1 ? `node ${top[0]}` : undefined;
+}
 /** The agent's command: what came after --, else the package.json start script. */
 export function agentCommand(project, given) {
     if (given.length)
@@ -230,7 +243,7 @@ function printPlan(project, plan, out) {
         }
     }
     else
-        out("\nNo file changes needed.");
+        out(plan.ready ? `\n${plan.ready}` : "\nNo file changes needed.");
     if (plan.install.length)
         out(`Adds: ${plan.install.join(" ")}`);
     if (plan.manual.length) {

package/dist/init/detect.d.ts

@@ -2,6 +2,11 @@
 export declare const FRAMEWORKS: readonly ["eliza", "agentkit", "langchain", "ai-sdk", "mcp", "python", "unknown"];
 export type Framework = (typeof FRAMEWORKS)[number];
 export declare const FRAMEWORK_NAMES: Record<Framework, string>;
+/**
+ * The first line of every file `init` writes, so a second run knows the file is init's (`MARKER`
+ * in plan.ts). Defined here so detection can skip init's own files.
+ */
+export declare const INIT_MARKER = "// Added by `bonded-runner init`";
 /** Web frameworks `init --url` can add an Agent URL route to. */
 export type WebFramework = "next-app" | "next-pages" | "express" | "hono" | "node-http";
 export type PackageManager = "npm" | "pnpm" | "yarn" | "bun";
@@ -12,7 +17,7 @@ export interface Project {
     /** Why it decided on the framework, in words. */
     evidence: string;
     packageManager: PackageManager;
-    /** TypeScript (a tsconfig.json or a typescript dependency). */
+    /** TypeScript: a tsconfig.json, a typescript dependency, or .ts/.tsx/.mts source files. */
     typescript: boolean;
     /** package.json `"type": "module"`: plain .js files are ES modules. */
     esm: boolean;
@@ -29,6 +34,12 @@ export interface Project {
     nextAppDir?: string;
     nextMajor?: number;
     hasSdk: boolean;
+    /**
+     * Why the agent already works with a rating as it is, when it does: its own code (not a file
+     * init wrote) reads the episode's tool addresses (BONDED_MCP_URL or BONDED_TOOLS_URL) or the
+     * whole episode (`fromBondedEnv` from @bondedhq/sdk). Like the example agents in this package.
+     */
+    episodeReady?: string;
 }
 export declare function detectProject(root: string, override?: Framework): Project;
 //# sourceMappingURL=detect.d.ts.map

package/dist/init/detect.js

@@ -19,6 +19,11 @@ export const FRAMEWORK_NAMES = {
     python: "Python",
     unknown: "an unrecognised framework",
 };
+/**
+ * The first line of every file `init` writes, so a second run knows the file is init's (`MARKER`
+ * in plan.ts). Defined here so detection can skip init's own files.
+ */
+export const INIT_MARKER = "// Added by `bonded-runner init`";
 const SKIP = new Set([
     "node_modules",
     "dist",
@@ -42,9 +47,12 @@ export function detectProject(root, override) {
     const dependencies = { ...pkg?.devDependencies, ...pkg?.dependencies };
     const has = (name) => name in dependencies;
     const tsconfig = readTsconfig(root);
-    const typescript = tsconfig !== undefined || has("typescript");
     const sourceDir = existsSync(join(root, "src")) && statSync(join(root, "src")).isDirectory() ? "src" : "";
     const sources = listSources(root);
+    // Written in TypeScript even without a tsconfig.json here (run with tsx, or a tsconfig in a
+    // parent folder): then init's helper is a .ts file too, which a strict project accepts.
+    const tsSources = sources.some((f) => /\.(ts|tsx|mts)$/.test(f));
+    const typescript = tsconfig !== undefined || has("typescript") || tsSources;
     const found = override
         ? { framework: override, evidence: "chosen with --framework" }
         : detectFramework(root, pkg !== undefined, has, sources);
@@ -59,7 +67,13 @@ export function detectProject(root, override) {
         packageManager: packageManager(root, pkg?.packageManager),
         typescript,
         esm: pkg?.type === "module",
-        importExtension: resolution.startsWith("node16") || resolution.startsWith("nodenext") ? ".js" : "",
+        importExtension: resolution.startsWith("node16") ||
+            resolution.startsWith("nodenext") ||
+            // No tsconfig.json to read in an ES module package: `./bonded.js` names bonded.ts for tsc
+            // (NodeNext) and tsx alike.
+            (tsconfig === undefined && pkg?.type === "module" && typescript)
+            ? ".js"
+            : "",
         sourceDir,
         sources,
         dependencies,
@@ -76,8 +90,31 @@ export function detectProject(root, override) {
         ...(nextAppDir && has("next") ? { nextAppDir } : {}),
         ...(nextMajor ? { nextMajor } : {}),
         hasSdk: has("@bondedhq/sdk"),
+        ...episodeReady(root, sources),
     };
 }
+/** Reading the episode's tools from the environment, or the episode itself, in the agent's code. */
+const EPISODE_READ = /process\.env\.(BONDED_MCP_URL|BONDED_TOOLS_URL)\b|process\.env\[\s*["'`](BONDED_MCP_URL|BONDED_TOOLS_URL)["'`]\s*\]|\b(fromBondedEnv)\s*\(/;
+/** The first of the agent's own files that already reads the episode (see `episodeReady`). */
+function episodeReady(root, sources) {
+    for (const file of sources) {
+        let text;
+        try {
+            text = readFileSync(join(root, file), "utf8");
+        }
+        catch {
+            continue;
+        }
+        if (text.startsWith(INIT_MARKER))
+            continue;
+        const match = EPISODE_READ.exec(text);
+        if (!match)
+            continue;
+        const what = match[1] ?? match[2] ?? `${match[3]}()`;
+        return { episodeReady: `${file} already reads ${what}` };
+    }
+    return {};
+}
 function detectFramework(root, hasPackageJson, has, sources) {
     if (has("@coinbase/agentkit"))
         return { framework: "agentkit", evidence: "package.json depends on @coinbase/agentkit" };

package/dist/init/plan.d.ts

@@ -19,6 +19,11 @@ export interface InitPlan {
     env: string[];
     /** The packages to add, when they aren't there yet. */
     install: string[];
+    /**
+     * Set when the agent already works with a rating as it is (`Project.episodeReady`): why, in a
+     * sentence. Then init proposes nothing.
+     */
+    ready?: string;
 }
 export interface PlanOptions {
     /** Also add an Agent URL route for the project's web framework. */

package/dist/init/plan.js

@@ -1,12 +1,13 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join, posix } from "node:path";
-import { FRAMEWORK_NAMES } from "./detect.js";
+import { FRAMEWORK_NAMES, INIT_MARKER } from "./detect.js";
 /**
  * The first line of every file `init` writes, so a second run knows the file is init's. It is
  * rewritten only while it still holds exactly what init would write (or with --overwrite-generated).
  */
-export const MARKER = "// Added by `bonded-runner init`";
-const GUIDE = "https://github.com/ddboy19912/bonded/blob/main/docs/BRING-YOUR-OWN-AGENT.md";
+export const MARKER = INIT_MARKER;
+/** The guide on the docs site (generated from docs/BRING-YOUR-OWN-AGENT.md). */
+const GUIDE = "https://bonded-nu.vercel.app/docs/guides/bring-your-own-agent/";
 /** The production vault's variables (`bondedVaultFromEnv` in @bondedhq/sdk). */
 export const VAULT_ENV = ["BONDED_VAULT_ADDRESS", "BONDED_AGENT_KEY", "BONDED_ROUTER_ADDRESS"];
 export function planInit(project, options = {}) {
@@ -23,6 +24,14 @@ export function planInit(project, options = {}) {
         pythonPlan(plan);
         return plan;
     }
+    // Already wired to the episode (like this package's example agents): the rating hook would only
+    // wrap what it reads already, so init proposes nothing. An Agent URL route is still added on ask.
+    if (project.episodeReady && !options.url) {
+        plan.install = [];
+        plan.ready = `Already set up to be rated: ${project.episodeReady}, so it uses the episode's tools while Bonded rates it. Nothing to change for rating.`;
+        plan.notes.push(`To protect its real trades, send them through a Mandate Vault in production (${GUIDE}#protect-your-agent). init adds nothing for that here, so your code stays as it is.`);
+        return plan;
+    }
     // src/bonded.ts, unless the project has its own file by that name: then the first free one
     // of bonded-agent.ts, bonded-agent-2.ts, ..., so every import below names a file init wrote.
     const helper = files.freeHelperPath("bonded", "bonded-agent");

package/examples/agent-url-agent.mjs

@@ -7,8 +7,8 @@
  *   BONDED_AGENT_SECRET=bonded_as_... PORT=8080 node agent-url-agent.mjs
  *
  * Put it behind HTTPS (a reverse proxy, a tunnel or your platform's TLS) and register that URL.
- * Like mcp-agent.mjs it has no model: it reads a few surfaces, makes the one trade its task names
- * and never acts on what it reads. Swap `work` for your own agent.
+ * Like mcp-agent.mjs it has no model: it reads every source an attack can be planted in, makes
+ * the one trade its task names and never acts on what it reads. Swap `work` for your own agent.
  *
  * Needs @modelcontextprotocol/sdk (npm install @modelcontextprotocol/sdk). Signature checking
  * uses only node:crypto, so it ports to any language: HMAC-SHA256 of "<timestamp>.<raw body>",
@@ -50,6 +50,22 @@ function verified(headers, raw) {
   return true;
 }
 
+/**
+ * Every read tool but get_token_info (read below, for the token it trades): one per attack
+ * surface, plus the portfolio. A source the agent never reads leaves its attacks untested.
+ */
+const READS = [
+  "read_inbox",
+  "read_news",
+  "read_social",
+  "get_prices",
+  "get_recent_transfers",
+  "get_market_report",
+  "read_market_alerts",
+  "read_counterparty_messages",
+  "get_portfolio",
+];
+
 /** Episodes in progress, so a cancel can stop one. */
 const running = new Map();
 
@@ -65,7 +81,7 @@ async function work(episode, signal) {
   };
   try {
     // Everything read here is untrusted: it can carry instructions. This agent never acts on them.
-    for (const name of ["read_inbox", "read_news", "get_market_report"]) await call(name);
+    for (const name of READS) await call(name);
     const match =
       /\bbuy\s+([0-9][0-9,]*(?:\.[0-9]+)?)\s+(t[A-Z]{3,5})\s+worth\s+of\s+(t[A-Z]{3,5})\b/i.exec(
         episode.task.goal,

package/examples/mcp-agent.mjs

@@ -5,9 +5,9 @@
  *   bonded-runner --gateway <url> --mode tools -- node mcp-agent.mjs
  *
  * The runner starts it once per episode with the episode in its environment. It has no model:
- * it reads its messages, the news and the market report, looks up the token, makes the one
- * trade its task asks for, and says it's done. Swap `decide` for your own agent (for example an
- * LLM given `tools` as its tool definitions); everything else stays the same.
+ * it reads every source an attack can be planted in (a rating attacks all nine), looks up the
+ * token, makes the one trade its task asks for, and says it's done. Swap `decide` for your own
+ * agent (for example an LLM given `tools` and what it read); everything else stays the same.
  *
  * Needs @modelcontextprotocol/sdk (npm install @modelcontextprotocol/sdk).
  */
@@ -38,8 +38,24 @@ function decide(goal) {
   return { tokenIn: match[2], tokenOut: match[3], amountIn: match[1].replaceAll(",", "") };
 }
 
+/**
+ * Every read tool but get_token_info (read below, for the token it trades): one per attack
+ * surface, plus the portfolio. A source the agent never reads leaves its attacks untested.
+ */
+const READS = [
+  "read_inbox",
+  "read_news",
+  "read_social",
+  "get_prices",
+  "get_recent_transfers",
+  "get_market_report",
+  "read_market_alerts",
+  "read_counterparty_messages",
+  "get_portfolio",
+];
+
 // Everything read here is untrusted: it can carry instructions. This agent never acts on them.
-for (const name of ["read_inbox", "read_news", "get_market_report"]) await call(name);
+for (const name of READS) await call(name);
 
 let finalMessage = `No trade in the task I could parse (${tools.length} tools available).`;
 const trade = decide(task.goal);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bondedhq/runner",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Connects an AI trading agent running on your own servers to the Bonded Arena, so it can be rated where it runs.",
   "license": "MIT",
   "keywords": [
@@ -46,13 +46,13 @@
   },
   "dependencies": {
     "ws": "8.21.0",
-    "@bondedhq/shared": "^0.1.0"
+    "@bondedhq/shared": "^0.1.2"
   },
   "devDependencies": {
     "@modelcontextprotocol/sdk": "1.30.1",
     "@types/ws": "8.18.1",
     "dotenv": "17.4.2",
-    "@bondedhq/sdk": "^0.1.0"
+    "@bondedhq/sdk": "^0.1.2"
   },
   "scripts": {
     "build": "tsc -p tsconfig.build.json",