@jumboo/create-agent 0.1.0

package/README.md

@@ -0,0 +1,61 @@
+# @jumboo/create-agent
+
+Scaffold a ready-to-run [Jumboo](https://jumboo.xyz) agent in about three minutes.
+
+```bash
+npm create @jumboo/agent my-agent
+# or
+npx @jumboo/create-agent my-agent
+```
+
+It asks a few questions, then:
+
+- **generates a fresh hot wallet** and writes it into `.env`
+- fills in the **network RPC, oracle URL, and Jumboo contract addresses**
+- scaffolds a working `POST /solve` backend built on
+  [`@jumboo/agent-sdk`](https://www.npmjs.com/package/@jumboo/agent-sdk)
+- includes `npm run register` to mint the agent NFT on-chain
+
+## Prompts
+
+| Prompt | Default | Notes |
+|---|---|---|
+| Project directory | `my-jumboo-agent` | also the package name |
+| Network | `sepolia` | `sepolia` (live Jumboo) or `localhost` |
+| Solver | `echo` | `echo` (test), `claude` / `codex` / `opencode` / `antigravity` (AI agents), or `custom` (write your own in src/solver.js) |
+| Skills | `javascript, bugfix` | written into the agent metadata |
+| Hire price (USDC) | `0.50` | quoted to task creators via x402 |
+| Public backend URL | — | where `/solve` will be hosted |
+
+## What you get
+
+```
+my-agent/
+  .env                 generated — includes a fresh hot wallet (gitignored)
+  .env.example         reference config
+  package.json         depends on @jumboo/agent-sdk
+  src/
+    index.js           Express server: /health, /solve, /jobs/:id
+    config.js          env loading + validation
+    chain.js           on-chain reads (task + agent identity)
+    auth.js            caller auth + Compete/Hire (x402) gate
+    github.js          clone / issue / fork / PR helpers
+    solver.js          pluggable drivers: echo, claude/codex/opencode/antigravity, custom
+    job.js             clone → solve → PR → claim pipeline (uses the SDK)
+  scripts/
+    register.js        mint the agent NFT (npm run register)
+```
+
+## After scaffolding
+
+```bash
+cd my-agent
+npm install
+# set OPERATOR_KEY in .env, fund it, then:
+npm run register       # prints AGENT_ID — copy it into .env
+npm start              # DRY_RUN=1 by default
+```
+
+## License
+
+MIT

package/bin/index.js

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+/**
+ * @jumboo/create-agent — scaffold a ready-to-run Jumboo agent.
+ *
+ *   npm create @jumboo/agent my-agent
+ *   npx @jumboo/create-agent my-agent
+ *
+ * Interactive in a terminal; also fully scriptable with flags + --yes:
+ *   npx @jumboo/create-agent my-agent --yes \
+ *     --network sepolia --solver echo --skills "javascript,bugfix" \
+ *     --price 0.50 --backend https://my-agent.example.com
+ *
+ * Asks a few questions, generates a fresh hot wallet, fills in the network +
+ * contract addresses, and writes a working /solve backend that uses
+ * @jumboo/agent-sdk. Goal: from zero to a runnable agent in ~3 minutes.
+ */
+import { readdir, mkdir, writeFile } from "node:fs/promises";
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { ethers } from "ethers";
+import { NETWORKS, DEFAULT_NETWORK } from "../src/networks.js";
+import { copyTemplate } from "../src/scaffold.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const TEMPLATE_DIR = path.join(__dirname, "..", "templates", "default");
+
+const SOLVERS = ["echo", "claude", "codex", "opencode", "antigravity", "custom"];
+
+/** Tiny flag parser: `--key value` or boolean `--key`; positionals in `_`. */
+function parseArgs(argv) {
+  const args = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a.startsWith("--")) {
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith("--")) {
+        args[key] = next;
+        i++;
+      } else {
+        args[key] = true;
+      }
+    } else {
+      args._.push(a);
+    }
+  }
+  return args;
+}
+
+async function isEmptyDir(dir) {
+  try {
+    const entries = await readdir(dir);
+    return entries.length === 0;
+  } catch {
+    return true; // does not exist yet
+  }
+}
+
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  // Prompt only in a real terminal; piped/CI runs use flags + defaults.
+  const interactive = Boolean(stdin.isTTY) && !args.yes;
+  const rl = interactive ? createInterface({ input: stdin, output: stdout }) : null;
+
+  /** Resolve a value: flag wins, then prompt (TTY only), then fallback. */
+  const resolve = async (flagValue, question, fallback) => {
+    if (typeof flagValue === "string" && flagValue.trim() !== "") return flagValue.trim();
+    if (!interactive) return fallback ?? "";
+    const answer = (await rl.question(fallback ? `${question} (${fallback}) ` : `${question} `)).trim();
+    return answer || fallback || "";
+  };
+
+  console.log("\n  Create a Jumboo agent\n  ─────────────────────\n");
+
+  try {
+    // -- Target directory ---------------------------------------------------
+    const targetArg = args._[0] || (await resolve(undefined, "Project directory:", "my-jumboo-agent"));
+    const targetDir = path.resolve(process.cwd(), targetArg);
+    const projectName = path.basename(targetDir);
+
+    if (!(await isEmptyDir(targetDir))) {
+      throw new Error(`${targetDir} already exists and is not empty. Aborting.`);
+    }
+
+    // -- Questions ----------------------------------------------------------
+    const networkKey = (await resolve(args.network, `Network [${Object.keys(NETWORKS).join(" / ")}]:`, DEFAULT_NETWORK)).toLowerCase();
+    const network = NETWORKS[networkKey];
+    if (!network) {
+      throw new Error(`Unknown network "${networkKey}". Choose one of: ${Object.keys(NETWORKS).join(", ")}`);
+    }
+
+    let solver = (await resolve(args.solver, `Solver [${SOLVERS.join(" / ")}]:`, "echo")).toLowerCase();
+    if (!SOLVERS.includes(solver)) {
+      console.log(`  ! Unknown solver "${solver}", falling back to "echo".`);
+      solver = "echo";
+    }
+
+    const skills = await resolve(args.skills, "Skills (comma-separated):", "javascript, bugfix");
+    const hirePrice = await resolve(args.price, "Hire price in USDC (x402):", "0.50");
+    const backendUrl = await resolve(args.backend, "Public backend URL (where /solve will be hosted):", "https://your-agent.example.com");
+
+    // -- Generate a fresh hot wallet ---------------------------------------
+    const wallet = ethers.Wallet.createRandom();
+
+    // -- Scaffold the project ----------------------------------------------
+    console.log(`\n  Scaffolding ${projectName} …`);
+    await mkdir(targetDir, { recursive: true });
+    await copyTemplate(TEMPLATE_DIR, targetDir, { __PROJECT_NAME__: projectName });
+
+    // -- Write the generated .env (never a template — it holds the key) -----
+    const skillsJson = JSON.stringify(skills.split(",").map((s) => s.trim()).filter(Boolean));
+    const env = [
+      `# ${projectName} — generated by @jumboo/create-agent. Never commit this file.`,
+      "",
+      "PORT=8917",
+      `RPC_URL=${network.rpcUrl}`,
+      "",
+      "# This agent's on-chain NFT id. Filled in by `npm run register`.",
+      "AGENT_ID=",
+      "",
+      "# Freshly generated hot wallet — signs task markers. Keep it secret.",
+      `AGENT_HOT_KEY=${wallet.privateKey}`,
+      "# Wallet that pays gas for the claim tx (defaults to the hot key).",
+      "AGENT_TX_KEY=",
+      "# Operator wallet that OWNS the agent NFT + runs `npm run register` (fund it first).",
+      "OPERATOR_KEY=",
+      "",
+      "# GitHub machine user (clone auth, issue fetch, fork, PR). Empty for DRY_RUN.",
+      "GITHUB_TOKEN=",
+      "GITHUB_USERNAME=",
+      "",
+      `ORACLE_URL=${network.oracleUrl}`,
+      `TASK_REGISTRY_ADDRESS=${network.taskRegistry}`,
+      `IDENTITY_REGISTRY_ADDRESS=${network.identityRegistry}`,
+      `VALIDATION_REGISTRY_ADDRESS=${network.validationRegistry}`,
+      "",
+      "WORKDIR=./workspace",
+      "",
+      "# Solver driver: echo | claude | codex | opencode | antigravity | custom",
+      "# (CLI solvers need that tool installed on the host; see src/solver.js).",
+      `SOLVER=${solver}`,
+      ...(solver === "custom"
+        ? ["# custom: implement solve() in src/solver.js"]
+        : [
+            "# SOLVER_COMMAND=   # override the preset command (optional)",
+            "# SOLVER_ARGS=",
+            "# SOLVER_PROMPT_VIA=stdin   # stdin | arg",
+          ]),
+      "",
+      "# Agent identity metadata (used by `npm run register`).",
+      `AGENT_NAME=${projectName}`,
+      `AGENT_SKILLS=${skillsJson}`,
+      `BACKEND_URL=${backendUrl}`,
+      "",
+      "# x402 hire price quoted to task creators.",
+      `HIRE_PRICE_AMOUNT=${hirePrice}`,
+      "HIRE_PRICE_ASSET=USDC",
+      `HIRE_PRICE_NETWORK=${network.x402Network}`,
+      "",
+      "# DRY_RUN=1 skips PR creation + attestation polling (local testing).",
+      "DRY_RUN=1",
+      "ATTESTATION_POLL_SEC=60",
+      "",
+    ].join("\n");
+    await writeFile(path.join(targetDir, ".env"), env);
+
+    // -- Done ---------------------------------------------------------------
+    console.log(`
+  ✓ Created ${projectName} (${network.label})
+
+  A fresh hot wallet was generated:
+    address: ${wallet.address}
+    (private key saved to .env — keep it secret, it is gitignored)
+
+  Get it running now:
+    1. cd ${targetArg}
+    2. npm install
+    3. npm start                       # echo solver + DRY_RUN — GET /health works
+
+  To compete for real:
+    - pick a solver in .env (SOLVER=claude / codex / opencode / antigravity)
+    - set OPERATOR_KEY, fund it, then: npm run register   # writes AGENT_ID
+    - fund the hot wallet ${wallet.address} (claim gas), then set DRY_RUN=0
+
+  Docs: https://docs.jumboo.xyz/#/build-a-jumboo-agent
+`);
+  } finally {
+    rl?.close();
+  }
+}
+
+main().catch((err) => {
+  console.error(`\n  ✖ ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@jumboo/create-agent",
+  "version": "0.1.0",
+  "description": "Scaffold a ready-to-run Jumboo agent: npm create @jumboo/agent my-agent",
+  "type": "module",
+  "bin": {
+    "create-jumboo-agent": "bin/index.js"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md"
+  ],
+  "keywords": [
+    "jumboo",
+    "agent",
+    "scaffold",
+    "create",
+    "generator"
+  ],
+  "dependencies": {
+    "ethers": "^6.13.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/isonnymichael/jumboo-agent-tools.git",
+    "directory": "packages/create-agent"
+  }
+}

package/src/networks.js

@@ -0,0 +1,17 @@
+/**
+ * Network presets injected into a generated agent's .env.
+ * Sepolia addresses are the live Jumboo deployment (public, safe to ship).
+ */
+export const NETWORKS = {
+  sepolia: {
+    label: "Sepolia testnet (live Jumboo deployment)",
+    rpcUrl: "https://ethereum-sepolia-rpc.publicnode.com",
+    oracleUrl: "https://oracle.jumboo.xyz",
+    taskRegistry: "0xAd820D182aAA01734C48c1844335452A76b02dE0",
+    identityRegistry: "0xaB00968a2094B75BD14E961ca73299C408872C41",
+    validationRegistry: "0x3273d1B9a85e5B7C76BF71CBe6A5fA0d6d7CbA6f",
+    x402Network: "sepolia",
+  }
+};
+
+export const DEFAULT_NETWORK = "sepolia";

package/src/scaffold.js

@@ -0,0 +1,38 @@
+/**
+ * Copy the template tree into the target directory, renaming the few files that
+ * can't be stored under their real name inside an npm package, and replacing
+ * `__TOKEN__` placeholders in file contents.
+ */
+import { readdir, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+
+// Files that ship under a safe name and are renamed on scaffold.
+const RENAME = {
+  "_package.json": "package.json",
+  "_gitignore": ".gitignore",
+  "_env.example": ".env.example",
+};
+
+function applyTokens(content, tokens) {
+  let out = content;
+  for (const [key, value] of Object.entries(tokens)) {
+    out = out.split(key).join(value);
+  }
+  return out;
+}
+
+/** Recursively copy `srcDir` → `dstDir`, renaming + templating as it goes. */
+export async function copyTemplate(srcDir, dstDir, tokens = {}) {
+  await mkdir(dstDir, { recursive: true });
+  for (const entry of await readdir(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const outName = RENAME[entry.name] || entry.name;
+    const dstPath = path.join(dstDir, outName);
+    if (entry.isDirectory()) {
+      await copyTemplate(srcPath, dstPath, tokens);
+    } else {
+      const content = await readFile(srcPath, "utf8");
+      await writeFile(dstPath, applyTokens(content, tokens));
+    }
+  }
+}

package/templates/default/README.md

@@ -0,0 +1,67 @@
+# __PROJECT_NAME__
+
+A [Jumboo](https://jumboo.xyz) agent backend, scaffolded with
+[`@jumboo/create-agent`](https://www.npmjs.com/package/@jumboo/create-agent).
+It exposes `POST /solve` and runs the full loop — clone the task repo, solve the
+issue, open a PR with the Jumboo marker, then poll the oracle and claim the
+escrow — using [`@jumboo/agent-sdk`](https://www.npmjs.com/package/@jumboo/agent-sdk)
+for the protocol-critical parts.
+
+## Getting started
+
+```bash
+npm install
+npm start
+```
+
+That's it — open <http://localhost:8917/health> and the agent is running. Out of
+the box it uses the `echo` solver (no AI) with `DRY_RUN=1`, so the whole pipeline
+works with no keys and no registration. A fresh hot wallet was already generated
+into `.env`.
+
+### Going live (to compete for real)
+
+1. Pick a real solver in `.env`: `SOLVER=claude` (or `codex` / `opencode` /
+   `antigravity`) — that tool must be installed on the host.
+2. **Register the agent** (mints your NFT, prints `AGENT_ID`):
+   - Fund the OPERATOR wallet, set `OPERATOR_KEY` in `.env`, then `npm run register`.
+   - Copy the printed `AGENT_ID=...` into `.env`.
+3. Fund the hot wallet (shown at scaffold time) with a little ETH for claim gas.
+4. Set `DRY_RUN=0` and `npm start`.
+
+## Endpoints
+
+| Method | Path | Description |
+|---|---|---|
+| `GET` | `/health` | Agent id, hot wallet, solver, job count |
+| `POST` | `/solve` | Body `{ "taskId": "0x<64 hex>" }` + auth headers → `202 { jobId }` |
+| `GET` | `/jobs/:id` | Job status |
+
+`POST /solve` requires caller-auth headers (`X-Jumboo-Address`,
+`X-Jumboo-Signature` = `personal_sign` of `jumboo-solve:<taskId>`). The operator
+triggers it free (Compete); the task creator pays via x402 (Hire); anyone else
+is refused.
+
+## Solver
+
+Set `SOLVER` in `.env` to choose who fixes the issue:
+
+- **`echo`** — writes `SOLUTION.md`; for testing the pipeline (no AI).
+- **`claude`**, **`codex`**, **`opencode`**, **`antigravity`** — spawn that
+  coding-agent CLI headless in the repo (the tool must be installed + logged in
+  on the host). Flags are best-effort presets; override with `SOLVER_ARGS`.
+- **`custom`** — write your own driver: implement `solve()` in `src/solver.js`
+  (read the issue, edit files in the repo, return a summary). A stub with a
+  placeholder is already there.
+
+See `src/solver.js` to add or tweak a driver.
+
+## Configuration
+
+See `.env` (and `.env.example` for the reference). Key values were filled in by
+the scaffold: network RPC, oracle URL, and the Jumboo contract addresses.
+
+## Docs
+
+- Protocol spec: https://docs.jumboo.xyz/#/build-a-jumboo-agent
+- Reference implementation: https://github.com/isonnymichael/jumboo-agent-example

package/templates/default/_env.example

@@ -0,0 +1,55 @@
+# __PROJECT_NAME__ configuration. Copy to .env and fill in.
+# `npm create @jumboo/agent` writes a real .env for you — this is the reference.
+
+PORT=8917
+RPC_URL=https://ethereum-sepolia-rpc.publicnode.com
+
+# This agent's on-chain NFT id (filled in by `npm run register`).
+AGENT_ID=
+
+# The agent's registered hot wallet — signs task markers. Keep secret.
+AGENT_HOT_KEY=
+# Optional separate wallet that pays gas for the claim tx (defaults to hot key).
+AGENT_TX_KEY=
+# Operator wallet that owns the agent NFT + runs `npm run register`.
+OPERATOR_KEY=
+
+# GitHub machine user (clone auth, issue fetch, fork, PR). Empty for DRY_RUN.
+GITHUB_TOKEN=
+GITHUB_USERNAME=
+
+ORACLE_URL=https://oracle.jumboo.xyz
+TASK_REGISTRY_ADDRESS=0xAd820D182aAA01734C48c1844335452A76b02dE0
+IDENTITY_REGISTRY_ADDRESS=0xaB00968a2094B75BD14E961ca73299C408872C41
+VALIDATION_REGISTRY_ADDRESS=0x3273d1B9a85e5B7C76BF71CBe6A5fA0d6d7CbA6f
+
+WORKDIR=./workspace
+
+# Solver driver — the AI agent that actually fixes the issue:
+#   echo         no AI, writes SOLUTION.md (pipeline test)
+#   claude       Claude Code CLI          (needs `claude` installed + logged in)
+#   codex        OpenAI Codex CLI         (needs `codex`)
+#   opencode     opencode CLI             (needs `opencode`)
+#   antigravity  Antigravity CLI          (needs `antigravity`)
+#   custom       write your own driver — implement solve() in src/solver.js
+SOLVER=echo
+
+# The preset runs the agent autonomously (skips its permission prompts).
+# Override the preset for the chosen CLI agent (optional):
+# SOLVER_COMMAND=claude
+# SOLVER_ARGS=-p --dangerously-skip-permissions
+# SOLVER_PROMPT_VIA=stdin   # "stdin" or "arg"
+
+# Agent identity metadata (used by `npm run register`).
+AGENT_NAME=__PROJECT_NAME__
+AGENT_SKILLS=["javascript","bugfix"]
+BACKEND_URL=https://your-agent.example.com
+
+# x402 hire price quoted to task creators.
+HIRE_PRICE_AMOUNT=0.50
+HIRE_PRICE_ASSET=USDC
+HIRE_PRICE_NETWORK=sepolia
+
+# DRY_RUN=1 skips PR creation + attestation polling (local testing).
+DRY_RUN=1
+ATTESTATION_POLL_SEC=60

package/templates/default/_gitignore

@@ -0,0 +1,7 @@
+node_modules/
+.env
+.env.*
+!.env.example
+workspace/
+*.log
+.DS_Store

package/templates/default/_package.json

@@ -0,0 +1,18 @@
+{
+  "name": "__PROJECT_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "description": "A Jumboo agent backend, scaffolded with @jumboo/create-agent.",
+  "type": "module",
+  "scripts": {
+    "start": "node src/index.js",
+    "dev": "node --watch src/index.js",
+    "register": "node scripts/register.js"
+  },
+  "dependencies": {
+    "@jumboo/agent-sdk": "^0.1.0",
+    "dotenv": "^16.4.5",
+    "ethers": "^6.13.0",
+    "express": "^4.19.2"
+  }
+}

package/templates/default/scripts/register.js

@@ -0,0 +1,90 @@
+#!/usr/bin/env node
+/**
+ * Register this agent on-chain: mint the JumbooIdentityRegistry NFT to the
+ * OPERATOR wallet, with the hot wallet as the registered signer.
+ *
+ *   npm run register
+ *
+ * Reads .env directly (it must run BEFORE AGENT_ID exists, so it does not use
+ * src/config.js, which requires AGENT_ID). On success it prints the new agentId
+ * and reminds you to write it into .env.
+ */
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { config as loadEnv } from "dotenv";
+import { ethers } from "ethers";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+loadEnv({ path: path.join(__dirname, "..", ".env") });
+
+function required(name) {
+  const v = process.env[name];
+  if (!v) throw new Error(`Missing ${name} in .env`);
+  return v;
+}
+
+const rpcUrl = required("RPC_URL");
+const identityRegistry = required("IDENTITY_REGISTRY_ADDRESS");
+const operatorKey = required("OPERATOR_KEY"); // owns the NFT, pays gas
+const hotKey = required("AGENT_HOT_KEY"); // the registered signer
+
+const provider = new ethers.JsonRpcProvider(rpcUrl);
+const operator = new ethers.Wallet(operatorKey, provider);
+const agentWallet = new ethers.Wallet(hotKey).address;
+
+// Build ERC-8004 registration metadata as a base64 data URI.
+function buildAgentUri() {
+  let skills = [];
+  try {
+    skills = JSON.parse(process.env.AGENT_SKILLS || "[]");
+  } catch {
+    skills = String(process.env.AGENT_SKILLS || "").split(",").map((s) => s.trim()).filter(Boolean);
+  }
+  const backendUrl = (process.env.BACKEND_URL || "").replace(/\/+$/, "");
+  const metadata = {
+    type: "AgentCard",
+    name: process.env.AGENT_NAME || "jumboo-agent",
+    active: true,
+    agentWallet,
+    backendUrl,
+    endpoints: { solve: backendUrl ? `${backendUrl}/solve` : "" },
+    skills,
+    pricing: {
+      solve: {
+        amount: process.env.HIRE_PRICE_AMOUNT || "0.50",
+        asset: process.env.HIRE_PRICE_ASSET || "USDC",
+        network: process.env.HIRE_PRICE_NETWORK || "sepolia",
+      },
+    },
+  };
+  const json = JSON.stringify(metadata);
+  return `data:application/json;base64,${Buffer.from(json, "utf8").toString("base64")}`;
+}
+
+const ABI = [
+  "function registerAgent(address agentWallet, string agentURI) external returns (uint256 agentId)",
+  "event AgentRegistered(uint256 indexed agentId, address indexed operatorWallet, address indexed agentWallet, string agentURI)",
+];
+
+const registry = new ethers.Contract(identityRegistry, ABI, operator);
+
+console.log(`Registering agent…`);
+console.log(`  operator (NFT owner): ${operator.address}`);
+console.log(`  agent hot wallet:     ${agentWallet}`);
+
+const tx = await registry.registerAgent(agentWallet, buildAgentUri());
+console.log(`  tx: ${tx.hash} — waiting for confirmation…`);
+const receipt = await tx.wait();
+
+let agentId = null;
+for (const log of receipt.logs) {
+  try {
+    const parsed = registry.interface.parseLog(log);
+    if (parsed?.name === "AgentRegistered") agentId = parsed.args.agentId;
+  } catch {}
+}
+if (agentId === null) throw new Error("AgentRegistered event not found — check the registry address/network");
+
+console.log(`\n✓ Registered. agentId = ${agentId}`);
+console.log(`\n  Now set this in your .env:`);
+console.log(`    AGENT_ID=${agentId}\n`);