@standardagents/code 0.0.0-dev.fffff

package/README.md

@@ -0,0 +1,139 @@
+<div align="center">
+
+```
+     █████████████
+     ███        ██
+     ██          █
+████ ████████   ██
+███  ████████  ███
+██   ████████ ████
+█          ██
+██        ███
+█████████████
+```
+
+# Standard Code
+
+**A best-in-class terminal coding agent.**
+
+The LLM loop runs remotely on a [Standard Agents](https://github.com/standardagents) instance;
+every filesystem and shell tool executes locally on your machine via this CLI — so the agent
+works in *your* environment, against *your* code, with *your* permissions.
+
+```
+┌─────────────────────────┐         bridge (WebSocket)          ┌──────────────────────┐
+│ Standard Agents instance│  ── tool_request ──────────────▶    │  Standard Code CLI   │
+│  (the agent's LLM loop)  │  ◀──────────── tool_response ──     │  (your machine)      │
+└─────────────────────────┘                                     └──────────────────────┘
+```
+
+</div>
+
+---
+
+## 🔒 Early Access
+
+Standard Code is in **early access**. The agent loop, tooling, and backend are evolving fast,
+and we're rolling it out gradually to keep the feedback loop tight.
+
+**Access is invite-only.** To run Standard Code you need:
+
+1. A spot on the **early-access list** — request one at
+   **[standardagents.ai/early-access](https://standardagents.ai/early-access)**.
+2. A Standard Agents instance exposing the `standard_code_agent`
+   (see [agentbuilder](https://github.com/standardagents/agentbuilder)).
+
+If you're already on the list, you'll have received an instance URL and an API token. Jump to
+[Quick start](#quick-start). If not, [join the waitlist](https://standardagents.ai/early-access) —
+we're letting new folks in every week.
+
+---
+
+## Why Standard Code
+
+- **Your machine, your rules.** Tools run on your host — read/write/edit files, list, grep, glob,
+  bash, delete — never in some sandboxed cloud container. The agent edits the same files you do.
+- **Permission-aware by design.** A single auto-accept level (1–5) controls what runs unattended;
+  anything riskier prompts you first. A catastrophic-command guard blocks dangerous shell calls
+  at *every* level, so you can't accidentally `rm -rf` your way into a bad day.
+- **Durable, resumable sessions.** Long-running and permission-gated calls *park* and resume over
+  HTTP — a slow approval or a dropped socket can't kill your turn. Resume the same session from
+  any machine.
+- **Background processes that survive.** Dev servers, watchers, queue workers are tracked in the
+  thread and keep running across reconnects and resumes.
+- **Subagents & research built in.** Delegate focused subtasks to a coding subagent, or spin up a
+  non-blocking web-research agent that returns source-backed findings.
+- **MCP, first-class.** The CLI is a Model Context Protocol host — connect local MCP servers
+  (Playwright, databases, issue trackers, anything) and the agent can use them. Install new ones
+  in natural language: *"install the playwright mcp server"* and it researches and wires them up.
+
+---
+
+## Quick start
+
+Standard Code is a zero-dependency CLI (Node built-ins only) run through `tsx`:
+
+```bash
+pnpm install        # installs tsx + typescript
+pnpm code <dir>     # run against a project directory (defaults to cwd)
+# or
+node bin/standardcode.mjs <dir>
+```
+
+On first run it asks for your Standard Agents instance URL and an API token (stored in
+`~/.standardagents/credentials`). It then offers to **resume** a session tagged for this
+project + machine, or **start a new one**.
+
+### Requirements
+
+- **Node 22+**
+- A Standard Agents instance exposing the `standard_code_agent`
+  (see the [agentbuilder](https://github.com/standardagents/agentbuilder) repo). For local
+  development, run that backend on `:5178` and point this CLI at `http://localhost:5178`.
+
+---
+
+## Features
+
+- **Forwarded tools** executed on your host: read/write/edit files, list, grep, glob, bash, delete.
+- **Permissions**: a single auto-accept level 1–5 (shift-tab cycles it); risky calls prompt;
+  a catastrophic-command guard blocks dangerous shell commands at every level.
+- **Durable, resumable** long-running/permission-gated tool calls (park & resume over HTTP).
+- **Background processes** tracked in the thread (survive resume from any machine).
+- **Subagent delegation** and non-blocking web research.
+- **MCP (Model Context Protocol)**: connect local MCP servers — the CLI is the MCP host,
+  negotiating JSON-RPC over stdio. Manage them with `/mcp`; install new ones in natural
+  language ("install the playwright mcp server") and the agent researches + installs them.
+
+---
+
+## Tests
+
+```bash
+pnpm test           # typecheck + MCP client/protocol + install actuator (no backend needed)
+```
+
+---
+
+## Architecture & contributing
+
+Standard Code is the **client** half of a two-part system. The agent loop and tool definitions
+live on the Standard Agents instance ([agentbuilder](https://github.com/standardagents/agentbuilder));
+this CLI connects to a thread, executes the agent's forwarded tool calls on the host, and renders
+the session.
+
+See **[`AGENTS.md`](./AGENTS.md)** for the full source map, bridge protocol, MCP internals,
+test layout, and contributor conventions.
+
+- Zero runtime dependencies — Node built-ins only, run via `tsx`. No build step for development.
+- Commit messages use Conventional Commits, scope `cli` (e.g. `feat(cli): …`).
+
+---
+
+<div align="center">
+
+**[Join the early-access list →](https://standardagents.ai/early-access)**
+
+Built by [Standard Agents](https://github.com/standardagents).
+
+</div>

package/bin/standardcode.mjs

@@ -0,0 +1,25 @@
+#!/usr/bin/env node
+// Launcher for the Standard Code CLI. Runs the TypeScript entry through tsx so
+// it works without a separate build step during local development.
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { createRequire } from "node:module";
+import path from "node:path";
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const entry = path.resolve(here, "../src/index.ts");
+const require = createRequire(import.meta.url);
+
+let tsxBin;
+try {
+  // Resolve tsx's CLI entry from wherever it is installed in the workspace.
+  tsxBin = require.resolve("tsx/cli");
+} catch {
+  console.error("Could not find 'tsx'. Run `pnpm install` in the workspace.");
+  process.exit(1);
+}
+
+const child = spawn(process.execPath, [tsxBin, entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+child.on("exit", (code) => process.exit(code ?? 0));

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@standardagents/code",
+  "version": "0.0.0-dev.fffff",
+  "description": "Standard Code — a terminal coding agent whose LLM loop runs on a Standard Agents instance while its tools execute on your machine via this CLI.",
+  "type": "module",
+  "license": "UNLICENSED",
+  "packageManager": "pnpm@11.9.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/standardagents/code.git"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "bin": {
+    "standardcode": "./bin/standardcode.mjs"
+  },
+  "files": [
+    "bin",
+    "src"
+  ],
+  "scripts": {
+    "start": "tsx src/index.ts",
+    "code": "tsx src/index.ts",
+    "release": "node scripts/release.mjs",
+    "release:next": "node scripts/release.mjs --tag=next",
+    "release:dev": "node scripts/release.mjs --tag=dev",
+    "typecheck": "tsc --noEmit",
+    "test": "pnpm typecheck && tsx scripts/mcp-client-test.ts && tsx scripts/mcp-install-tool-test.ts"
+  },
+  "devDependencies": {
+    "@clack/prompts": "^1.6.0",
+    "@types/node": "^22.10.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3"
+  }
+}

package/src/api.ts

@@ -0,0 +1,169 @@
+/** Minimal REST client for the Standard Agents instance. */
+import type { ThreadSummary } from "./types.ts";
+
+export class ApiClient {
+  constructor(
+    private endpoint: string,
+    private token: string
+  ) {}
+
+  get wsEndpoint(): string {
+    return this.endpoint.replace(/^http/, "ws");
+  }
+
+  /** The instance origin (used to build admin-UI links). */
+  get origin(): string {
+    return this.endpoint;
+  }
+
+  get bearer(): string {
+    return this.token;
+  }
+
+  private async json<T>(pathname: string, init?: RequestInit): Promise<T> {
+    const res = await fetch(`${this.endpoint}${pathname}`, {
+      ...init,
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${this.token}`,
+        ...(init?.headers || {}),
+      },
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`${init?.method || "GET"} ${pathname} -> ${res.status}: ${text.slice(0, 300)}`);
+    }
+    try {
+      return JSON.parse(text) as T;
+    } catch {
+      return text as unknown as T;
+    }
+  }
+
+  async verify(): Promise<boolean> {
+    try {
+      await this.json("/api/auth/me");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /** Agent name → display title map (best effort; for labeling subagents). */
+  async listAgents(): Promise<{ name: string; title: string }[]> {
+    const res = await this.json<{ agents?: any[] } | any[]>("/api/agents");
+    const arr = Array.isArray(res) ? res : res.agents || [];
+    return arr
+      .filter((a) => a && typeof a.name === "string")
+      .map((a) => ({ name: a.name, title: typeof a.title === "string" ? a.title : a.name }));
+  }
+
+  async createThread(agentId: string, tags: string[]): Promise<string> {
+    const res = await this.json<{ threadId?: string; id?: string }>("/api/threads", {
+      method: "POST",
+      body: JSON.stringify({ agent_id: agentId, tags }),
+    });
+    const id = res.threadId || res.id;
+    if (!id) throw new Error("Thread create returned no id");
+    return id;
+  }
+
+  /** List threads for an agent, optionally filtering to those carrying all given tags. */
+  async listThreads(agentId: string, requireTags: string[]): Promise<ThreadSummary[]> {
+    const res = await this.json<{ threads?: any[] } | any[]>(
+      `/api/threads?agent_id=${encodeURIComponent(agentId)}&limit=100`
+    );
+    const arr = Array.isArray(res) ? res : res.threads || [];
+    return arr
+      .map((t) => ({
+        id: t.id,
+        tags: Array.isArray(t.tags) ? t.tags : [],
+        created_at: t.created_at,
+        title: t.title,
+        preview: t.preview || t.last_message,
+      }))
+      .filter((t: ThreadSummary) => requireTags.every((tag) => t.tags.includes(tag)));
+  }
+
+  async sendMessage(threadId: string, content: string): Promise<void> {
+    await this.json(`/api/threads/${threadId}/messages`, {
+      method: "POST",
+      body: JSON.stringify({ role: "user", content }),
+    });
+  }
+
+  async getMessages(threadId: string, limit = 50): Promise<any[]> {
+    const res = await this.json<{ messages?: any[] } | any[]>(
+      `/api/threads/${threadId}/messages?limit=${limit}`
+    );
+    return Array.isArray(res) ? res : res.messages || [];
+  }
+
+  async getLogs(threadId: string, limit = 100): Promise<any[]> {
+    const res = await this.json<{ logs?: any[] } | any[]>(
+      `/api/threads/${threadId}/logs?limit=${limit}&order=desc`
+    );
+    return Array.isArray(res) ? res : res.logs || [];
+  }
+
+  /**
+   * Deliver a durable forwarded tool result to the thread, resuming the turn.
+   * Retries with backoff — this is the durable delivery path, so it must land
+   * even if the connection is briefly flaky after a permission wait.
+   */
+  async postToolResult(
+    threadId: string,
+    toolCallId: string,
+    ok: boolean,
+    result?: string,
+    error?: string
+  ): Promise<boolean> {
+    const body = JSON.stringify({ tool_call_id: toolCallId, ok, result, error });
+    for (let attempt = 0; attempt < 6; attempt++) {
+      try {
+        await this.json(`/api/threads/${threadId}/tool-result`, {
+          method: "POST",
+          headers: { "Content-Type": "application/json" },
+          body,
+        });
+        return true;
+      } catch {
+        await new Promise((r) => setTimeout(r, Math.min(500 * 2 ** attempt, 8000)));
+      }
+    }
+    return false;
+  }
+
+  /** Read a value from the thread's durable KV store (null if absent). */
+  async kvGet(threadId: string, key: string): Promise<unknown> {
+    try {
+      const res = await this.json<{ value?: unknown }>(
+        `/api/threads/${threadId}/kv?key=${encodeURIComponent(key)}`
+      );
+      return res?.value ?? null;
+    } catch {
+      return null; // 404 = key not yet set
+    }
+  }
+
+  /** Write a value to the thread's durable KV store. */
+  async kvSet(threadId: string, key: string, value: unknown): Promise<void> {
+    try {
+      await this.json(`/api/threads/${threadId}/kv`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ key, value }),
+      });
+    } catch {
+      // best effort
+    }
+  }
+
+  async stop(threadId: string): Promise<void> {
+    try {
+      await this.json(`/api/threads/${threadId}/stop`, { method: "POST" });
+    } catch {
+      // best effort
+    }
+  }
+}

package/src/approvals.ts

@@ -0,0 +1,42 @@
+/**
+ * Session approvals — the permission mode plus the tools and risk levels the
+ * user has pre-approved — persisted in the THREAD's KV store (server-side), so
+ * they resume with the session and a server hook can show the agent what's
+ * already approved. Nothing is stored on the client.
+ */
+import type { ApiClient } from "./api.ts";
+import type { PermissionState } from "./permissions.ts";
+import type { Level } from "./types.ts";
+
+const KEY = "approvals";
+
+export interface ApprovalsKV {
+  level?: Level;
+  allowTools: string[];
+  allowRisk: number[];
+}
+
+export async function loadApprovals(api: ApiClient, threadId: string): Promise<ApprovalsKV> {
+  const v = await api.kvGet(threadId, KEY);
+  if (v && typeof v === "object" && !Array.isArray(v)) {
+    const o = v as Record<string, unknown>;
+    const n = Number(o.level);
+    const level = n >= 1 && n <= 5 ? (n as Level) : undefined;
+    return {
+      level,
+      allowTools: Array.isArray(o.allowTools) ? (o.allowTools as string[]) : [],
+      allowRisk: Array.isArray(o.allowRisk) ? (o.allowRisk as number[]) : [],
+    };
+  }
+  return { allowTools: [], allowRisk: [] };
+}
+
+/** Persist the current approvals to the thread KV (fire-and-forget). */
+export function saveApprovals(api: ApiClient, threadId: string, perm: PermissionState): void {
+  const payload: ApprovalsKV = {
+    level: perm.level,
+    allowTools: Array.from(perm.alwaysAllow).sort(),
+    allowRisk: Array.from(perm.allowRisk).sort((a, b) => a - b),
+  };
+  void api.kvSet(threadId, KEY, payload);
+}