agentnetes 0.1.1 → 0.1.3

package/README.md

@@ -6,26 +6,41 @@
 
 **Zero to a Self-Organizing AI Agency. On Demand.**
 
-*Kubernetes for AI agents — type a goal, watch a swarm of specialist agents deliver.*
+*Self-Organizing AI Agent Swarms. On Demand. · Kubernetes-inspired orchestration for AI agents.*
 
 [![npm version](https://img.shields.io/npm/v/agentnetes?style=for-the-badge&logo=npm&color=fb923c)](https://www.npmjs.com/package/agentnetes)
 [![npm downloads](https://img.shields.io/npm/dm/agentnetes?style=for-the-badge&color=22c55e)](https://www.npmjs.com/package/agentnetes)
 [![License: MIT](https://img.shields.io/badge/License-MIT-white?style=for-the-badge)](https://github.com/Shashikant86/agentnetes/blob/main/LICENSE)
 
-[Live Demo](https://shashikant86.github.io/agentnetes/) · [GitHub](https://github.com/Shashikant86/agentnetes)
+[Live Demo](https://shashikant86.github.io/agentnetes/) · [Full Docs](https://shashikant86.github.io/agentnetes/docs) · [GitHub](https://github.com/Shashikant86/agentnetes)
 
 </div>
 
 ---
 
+## Prerequisites
+
+| Requirement | Version | Notes |
+|-------------|---------|-------|
+| Node.js | 18+ | Required |
+| Docker | any recent | Required for default sandbox |
+| Google API key | free tier | Get at [aistudio.google.com](https://aistudio.google.com) |
+| Git | any | Repo must have a remote `origin` |
+
+---
+
 ## Quick start
 
 ```bash
-# Get a free Google API key at aistudio.google.com, then:
+# 1. Pull the Docker base image (one-time)
+docker pull node:20-alpine
+
+# 2. Run on any git repo
+cd your-project
 GOOGLE_API_KEY=your_key npx agentnetes run "add comprehensive test coverage"
 ```
 
-No install needed. Works on any git repository.
+No global install needed. Works on any git repository.
 
 ---
 
@@ -33,11 +48,12 @@ No install needed. Works on any git repository.
 
 1. You type a goal inside any git repo
 2. A root agent (Tech Lead) explores your codebase and invents a specialist team
-3. Specialists run in parallel, each in their own isolated sandbox
-4. They explore, write code, run tests, fix failures, and deliver together
-5. A final synthesis summarises everything they found and built
+3. Specialists run in parallel · each in their own isolated Docker container with the repo cloned inside
+4. They use two tools: `search()` (grep) and `execute()` (bash) · no file contents stuffed into prompts
+5. Agents write code, run tests, fix failures, and deliver together
+6. A final synthesis summarises everything found and built
 
-Roles are fully emergent — nothing is hardcoded. A provider task spawns a Scout, Engineer, Tester, and Packager. A security audit spawns a completely different team.
+Roles are fully emergent · nothing is hardcoded. A feature task spawns a Scout, Engineer, and Tester. A security audit spawns a completely different team.
 
 ---
 
@@ -47,11 +63,15 @@ Roles are fully emergent — nothing is hardcoded. A provider task spawns a Scou
 # Run agents on the current git repo
 GOOGLE_API_KEY=your_key npx agentnetes run "your goal here"
 
+# Install globally to skip npx
+npm install -g agentnetes
+GOOGLE_API_KEY=your_key agentnetes run "your goal here"
+
 # Pre-warm a sandbox snapshot for faster runs (requires Vercel token)
-npx agentnetes snapshot create
+VERCEL_TOKEN=your_token agentnetes snapshot create
 
 # List available snapshots
-npx agentnetes snapshot list
+VERCEL_TOKEN=your_token agentnetes snapshot list
 ```
 
 ---
@@ -59,40 +79,69 @@ npx agentnetes snapshot list
 ## Environment variables
 
 ```bash
-# Required — get a free key at aistudio.google.com
+# Required · get a free key at aistudio.google.com
 GOOGLE_API_KEY=
 
 # Sandbox provider (default: docker)
 SANDBOX_PROVIDER=docker        # docker | local | vercel | e2b | daytona
 
-# Optional — Vercel AI Gateway instead of direct Gemini
-AI_GATEWAY_BASE_URL=
-AI_GATEWAY_API_KEY=
-
-# Optional — override default models
+# Optional · override default models
 PLANNER_MODEL=google/gemini-2.5-pro
 WORKER_MODEL=google/gemini-2.5-flash
+
+# Optional · Vercel sandbox only
+VERCEL_TOKEN=
 ```
 
+> **Note:** Do not set `AI_GATEWAY_BASE_URL` when using `GOOGLE_API_KEY` directly · it will route through Vercel AI Gateway and fail with an authentication error.
+
 ---
 
 ## Sandbox providers
 
-| Provider | Requirement | Notes |
-|----------|-------------|-------|
-| `docker` | Docker installed | Default. One container per agent. |
-| `local` | Nothing | Clones repo to temp dir, runs on host. |
-| `vercel` | `VERCEL_TOKEN` | Vercel Firecracker microVMs. |
-| `e2b` | `E2B_API_KEY` | E2B cloud sandboxes. |
+| Provider | Requirement | Speed | Notes |
+|----------|-------------|-------|-------|
+| `docker` | Docker running | Fast | Default. One `node:20-alpine` container per agent. |
+| `local` | Nothing | Fastest | Runs on host machine. No isolation. |
+| `vercel` | `VERCEL_TOKEN` | Fastest | Firecracker microVMs with snapshot support. |
+| `e2b` | `E2B_API_KEY` | Fast | E2B cloud sandboxes. |
+| `daytona` | `DAYTONA_API_KEY` | Fast | Daytona workspaces. |
 
-For the Docker provider, pull the base image once:
+### Docker setup
+
+Pull the base image once to avoid download delay on first run:
 
 ```bash
 docker pull node:20-alpine
 ```
 
+Each agent gets its own container with `bash` and `git` installed, and the target repo cloned to `/workspace`. Containers are removed automatically when agents finish.
+
+To watch containers spin up in real time:
+
+```bash
+# In a separate terminal
+watch -n 1 docker ps
+```
+
+### Local sandbox (no Docker)
+
+If you don't have Docker, use the local provider · agents run directly on your machine in a temp directory:
+
+```bash
+SANDBOX_PROVIDER=local GOOGLE_API_KEY=your_key agentnetes run "your goal"
+```
+
+---
+
+## Tips
+
+- Use **Gemini 2.5 Flash** as the worker model for faster runs · Flash completes tasks in seconds vs minutes for Pro
+- Be specific in your goals: `"add vitest tests for all functions in src/utils/"` works better than `"add tests"`
+- For large repos, agents focus on the most relevant files via `search()` · you don't need to pre-filter
+
 ---
 
 ## License
 
-MIT — [github.com/Shashikant86/agentnetes](https://github.com/Shashikant86/agentnetes)
+MIT · [github.com/Shashikant86/agentnetes](https://github.com/Shashikant86/agentnetes)

package/dist/index.js

@@ -25,7 +25,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 ));
 
 // src/index.ts
-var import_child_process4 = require("child_process");
+var import_child_process5 = require("child_process");
 
 // src/commands/run.ts
 var import_fs2 = require("fs");
@@ -37,23 +37,13 @@ var import_ai2 = require("ai");
 var import_zod2 = require("zod");
 
 // ../../lib/gateway.ts
-var import_gateway = require("@ai-sdk/gateway");
 var import_google = require("@ai-sdk/google");
-function makeProvider() {
-  if (process.env.AI_GATEWAY_BASE_URL) {
-    return (0, import_gateway.createGatewayProvider)({ baseURL: process.env.AI_GATEWAY_BASE_URL });
-  }
-  return (0, import_google.createGoogleGenerativeAI)({
-    apiKey: process.env.GOOGLE_API_KEY ?? process.env.GOOGLE_GENERATIVE_AI_API_KEY
+function gateway(model, apiKeyOverride) {
+  const google = (0, import_google.createGoogleGenerativeAI)({
+    apiKey: apiKeyOverride ?? process.env.GOOGLE_API_KEY ?? process.env.GOOGLE_GENERATIVE_AI_API_KEY
   });
-}
-var provider = makeProvider();
-function gateway(model) {
-  if (process.env.AI_GATEWAY_BASE_URL) {
-    return provider(model);
-  }
   const modelId = model.includes("/") ? model.split("/").slice(1).join("/") : model;
-  return provider(modelId);
+  return google(modelId);
 }
 
 // ../../lib/vrlm/tools.ts
@@ -157,11 +147,12 @@ var DockerSandbox = class {
     this.containerId = containerId;
     this.id = `docker-${containerId.slice(0, 12)}`;
   }
-  async runCommand(_shell, args2) {
-    const cmd = args2.join(" ");
+  async runCommand(shell, args2) {
+    const cIdx = args2.indexOf("-c");
+    const actualCmd = cIdx >= 0 && args2[cIdx + 1] ? args2[cIdx + 1] : args2.join(" ");
     try {
       const output = (0, import_child_process2.execSync)(
-        `docker exec ${this.containerId} sh -c ${JSON.stringify(cmd)}`,
+        `docker exec -w /workspace ${this.containerId} ${shell} -c ${JSON.stringify(actualCmd)}`,
         { encoding: "utf-8", timeout: 6e4 }
       );
       return { stdout: async () => output ?? "", exitCode: 0 };
@@ -196,7 +187,7 @@ async function createDockerSandbox(repoUrl) {
     { encoding: "utf-8" }
   ).trim();
   (0, import_child_process2.execSync)(
-    `docker exec ${containerId} sh -c "apk add --no-cache git 2>/dev/null"`,
+    `docker exec ${containerId} sh -c "apk add --no-cache git bash 2>/dev/null"`,
     { timeout: 3e4, stdio: "ignore" }
   );
   (0, import_child_process2.execSync)(
@@ -219,22 +210,22 @@ function detectProvider() {
   if (process.env.DAYTONA_API_KEY) return "daytona";
   return "docker";
 }
-async function createWorkerSandbox(repoUrl, snapshotId) {
-  const provider2 = detectProvider();
-  if (provider2 === "vercel") {
+async function createWorkerSandbox(repoUrl, snapshotId, providerOverride) {
+  const provider = providerOverride ?? detectProvider();
+  if (provider === "vercel") {
     const { Sandbox: Sandbox2 } = await import("@vercel/sandbox");
     if (snapshotId) {
       return Sandbox2.create({ source: { type: "snapshot", snapshotId }, timeout: 10 * 60 * 1e3 });
     }
     return Sandbox2.create({ source: { type: "git", url: repoUrl, depth: 1 }, timeout: 10 * 60 * 1e3 });
   }
-  if (provider2 === "e2b") {
+  if (provider === "e2b") {
     console.warn('[sandbox] e2b: install the "e2b" package to use this provider. Falling back to local.');
   }
-  if (provider2 === "daytona") {
+  if (provider === "daytona") {
     console.warn('[sandbox] daytona: install the "@daytonaio/sdk" package to use this provider. Falling back to local.');
   }
-  if (provider2 === "docker") {
+  if (provider === "docker") {
     return createDockerSandbox(repoUrl);
   }
   return createLocalSandbox(repoUrl);
@@ -584,7 +575,7 @@ var VrlmRuntime = class {
   // ── Planner ─────────────────────────────────────────────────────────────────
   async runPlanner(goal) {
     const { text } = await (0, import_ai2.generateText)({
-      model: gateway(this.config.plannerModel),
+      model: gateway(this.config.plannerModel, this.config.googleApiKey),
       system: PLANNER_SYSTEM_PROMPT,
       prompt: buildPlannerPrompt(goal),
       maxOutputTokens: 2e3
@@ -595,7 +586,7 @@ var VrlmRuntime = class {
   }
   // ── Worker ──────────────────────────────────────────────────────────────────
   async runWorker(task, repoUrl, snapshotId) {
-    let sandbox = await createWorkerSandbox(repoUrl, snapshotId);
+    let sandbox = await createWorkerSandbox(repoUrl, snapshotId, this.config.sandboxProvider);
     task.sandboxId = sandbox.id ?? "local";
     this.emitTaskUpdate(task.id, "running", "Sandbox ready");
     this.emitter.emit({
@@ -611,7 +602,7 @@ var VrlmRuntime = class {
     const findings = [];
     const terminalLines = [];
     const agent = new import_ai2.ToolLoopAgent({
-      model: gateway(this.config.workerModel),
+      model: gateway(this.config.workerModel, this.config.googleApiKey),
       tools,
       stopWhen: (0, import_ai2.stepCountIs)(this.config.maxStepsPerAgent),
       instructions: buildWorkerPrompt(task, findings),
@@ -688,7 +679,7 @@ var VrlmRuntime = class {
   // ── Synthesis ────────────────────────────────────────────────────────────────
   async runSynthesis(goal, summaries) {
     const { text } = await (0, import_ai2.generateText)({
-      model: gateway(this.config.plannerModel),
+      model: gateway(this.config.plannerModel, this.config.googleApiKey),
       prompt: buildSynthesisPrompt(goal, summaries),
       maxOutputTokens: 1500
     });
@@ -970,6 +961,80 @@ async function snapshotList() {
   }
 }
 
+// src/commands/serve.ts
+var import_child_process4 = require("child_process");
+var import_fs4 = require("fs");
+var import_path4 = require("path");
+var import_url = require("url");
+var import_picocolors4 = __toESM(require("picocolors"));
+var import_meta = {};
+var __dirname = (0, import_path4.dirname)((0, import_url.fileURLToPath)(import_meta.url));
+async function serve(port) {
+  const webDir = (0, import_path4.join)(__dirname, "..", "web");
+  const serverJs = (0, import_path4.join)(webDir, "server.js");
+  if (!(0, import_fs4.existsSync)(serverJs)) {
+    console.error(import_picocolors4.default.red("Error: web UI not found."));
+    console.error("");
+    console.error("The standalone web UI is not bundled in this installation.");
+    console.error("Build it from the repo root with:");
+    console.error("");
+    console.error(import_picocolors4.default.cyan("  bash scripts/build-serve.sh"));
+    console.error("  cd packages/cli && npm run build && npm publish");
+    console.error("");
+    process.exit(1);
+  }
+  console.log("");
+  console.log(import_picocolors4.default.bold(import_picocolors4.default.white("Agentnetes")));
+  console.log(import_picocolors4.default.dim("Zero to a self-organizing AI agency. On demand."));
+  console.log("");
+  console.log(import_picocolors4.default.dim("Starting web UI..."));
+  console.log("");
+  const env = {
+    ...process.env,
+    PORT: String(port),
+    HOSTNAME: "0.0.0.0"
+  };
+  const child = (0, import_child_process4.spawn)("node", [serverJs], {
+    cwd: webDir,
+    env,
+    stdio: "pipe"
+  });
+  let started = false;
+  child.stdout.on("data", (data) => {
+    const line = data.toString().trim();
+    if (!started && (line.includes("ready") || line.includes("started") || line.includes("listening") || line.includes(String(port)))) {
+      started = true;
+      console.log(import_picocolors4.default.green("Ready") + " " + import_picocolors4.default.bold(`http://localhost:${port}`));
+      console.log("");
+      console.log(import_picocolors4.default.dim("Set GOOGLE_API_KEY in your environment to run real agents."));
+      console.log(import_picocolors4.default.dim("Press Ctrl+C to stop."));
+      console.log("");
+    } else {
+      process.stdout.write(data);
+    }
+  });
+  child.stderr.on("data", (data) => {
+    process.stderr.write(data);
+  });
+  child.on("exit", (code) => {
+    if (code !== 0 && code !== null) {
+      console.error(import_picocolors4.default.red(`Server exited with code ${code}`));
+      process.exit(code);
+    }
+  });
+  await new Promise((resolve) => {
+    child.on("exit", () => resolve());
+    process.on("SIGINT", () => {
+      child.kill("SIGTERM");
+      resolve();
+    });
+    process.on("SIGTERM", () => {
+      child.kill("SIGTERM");
+      resolve();
+    });
+  });
+}
+
 // src/index.ts
 var args = process.argv.slice(2);
 var command = args[0];
@@ -982,7 +1047,7 @@ async function main() {
     }
     let repoUrl;
     try {
-      repoUrl = (0, import_child_process4.execSync)("git remote get-url origin", { encoding: "utf-8" }).trim();
+      repoUrl = (0, import_child_process5.execSync)("git remote get-url origin", { encoding: "utf-8" }).trim();
       if (repoUrl.startsWith("git@github.com:")) {
         repoUrl = repoUrl.replace("git@github.com:", "https://github.com/").replace(".git", "");
       }
@@ -999,18 +1064,23 @@ async function main() {
     await snapshotCreate();
   } else if (command === "snapshot" && args[1] === "list") {
     await snapshotList();
+  } else if (command === "serve") {
+    const portArg = args.indexOf("--port");
+    const port = portArg !== -1 ? parseInt(args[portArg + 1], 10) : 3e3;
+    await serve(port);
   } else {
     console.log("agentnetes - zero to a self-organizing AI agency. On demand.");
     console.log("");
     console.log("Usage:");
     console.log('  agentnetes run "goal"       Run agents on the current git repo');
+    console.log("  agentnetes serve            Start the web UI on localhost:3000");
+    console.log("  agentnetes serve --port 8080");
     console.log("  agentnetes snapshot create  Pre-warm a sandbox snapshot for faster runs");
     console.log("  agentnetes snapshot list    List available snapshots");
     console.log("");
     console.log("Environment variables:");
-    console.log("  GOOGLE_API_KEY       Google Gemini API key (aistudio.google.com)");
-    console.log("  SANDBOX_PROVIDER     docker | local | vercel | e2b (default: docker)");
-    console.log("  AI_GATEWAY_BASE_URL  Vercel AI Gateway endpoint (optional)");
+    console.log("  GOOGLE_API_KEY    Google Gemini API key (aistudio.google.com)");
+    console.log("  SANDBOX_PROVIDER  docker | local | vercel | e2b (default: docker)");
   }
 }
 main().catch((err) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentnetes",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Zero to a self-organizing AI agency. On demand.",
   "keywords": [
     "ai",
@@ -20,15 +20,16 @@
     "agentnetes": "./dist/index.js"
   },
   "files": [
-    "dist"
+    "dist",
+    "web"
   ],
   "scripts": {
     "build": "tsup",
+    "build:serve": "cd ../.. && bash scripts/build-serve.sh && cd packages/cli && tsup",
     "dev": "tsx src/index.ts",
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
-    "@ai-sdk/gateway": "beta",
     "@ai-sdk/google": "^3.0.52",
     "@vercel/sandbox": "latest",
     "ai": "beta",