agentglow 0.3.2 → 0.4.0

package/README.md

@@ -1,10 +1,11 @@
 # agentglow
 
 **Live 3D views of agent systems, as a React component.** Every agent your system spawns appears as a
-living shape (a neuron, a bee, a star, a tree, a flight…): it's born when its span starts, thinks while it
-calls the LLM, waits on MCP servers, passes messages to other agents, and fades out when its span ends.
-It is driven only by OpenTelemetry, via the [`agentglow`](https://github.com/Nideesh1/agentglow#quickstart)
-Python server, so it works with LangGraph, deepagents, LangChain and anything else that emits OTel spans.
+living shape (a neuron, a star, an electron, a particle track, a firework shell): it's born when its span starts,
+thinks while it calls the LLM, waits on MCP servers, passes messages to other agents, and fades out when its span
+ends. Backend services (FastAPI, FastStream, FastMCP, Node) show up as long-lived nodes with request halos. It is
+driven only by OpenTelemetry, via the [`agentglow`](https://github.com/Nideesh1/agentglow#get-started) Python
+server, so it works with LangGraph, deepagents, LangChain and anything else that emits OTel spans.
 
 ![neural theme](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/hero.webp)
 
@@ -15,14 +16,16 @@ npx agentglow setup        # once
 claude                     # then just use Claude Code as usual
 ```
 `setup` adds AgentGlow hooks + traces to `~/.claude/settings.json` (backup first) plus a hook that auto-starts the
-AgentGlow server with every `claude` session, then opens the 3D view. Only Node 18+ is needed (uv + Python are fetched
+AgentGlow server with every `claude` session (on macOS / Linux also a login item), then opens the 3D view. Only Node 18+ is needed (uv + Python are fetched
 on first run). Your agents and subagents appear live at http://localhost:8100/neural as Claude works.
 
 | Command | What it does |
 |---|---|
-| `npx agentglow setup [--port 8100]` | install once (backup first), start the server, open `/neural` |
+| `npx agentglow setup [--port 8100]` | install once (backup first), start the server, open `/neural`; on macOS / Linux the server also starts at login |
+| `npx agentglow setup --capture-prompts` | also show your own prompts next to Claude's replies (local server only, off by default) |
+| `npx agentglow setup --no-autostart` | no login item: the server starts with each `claude` session instead |
 | `npx agentglow status` / `open` / `stop` | check install + server / open the view / stop the background server |
-| `npx agentglow remove` | uninstall everything `setup` added and stop the server |
+| `npx agentglow remove` | uninstall everything `setup` added (hooks, env, login item) and stop the server |
 | `npx agentglow start [--background]` | run the server yourself (`serve` is an alias) |
 | `npx agentglow claude [-- <claude args>]` | try it without installing: one session with temporary settings |
 
@@ -51,7 +54,7 @@ import agentglow
 agentglow.watch()        # before your agents run
 ```
 
-See the [Python quickstart](https://github.com/Nideesh1/agentglow#quickstart) for details.
+See [Get started](https://github.com/Nideesh1/agentglow#get-started) for details.
 
 ## Use
 
@@ -90,6 +93,78 @@ export default function Live() {
 }
 ```
 
+## Node.js services
+
+`agentglow/node` (server-only, no React / three.js) puts a Node service (Next.js backend-for-frontend, Express,
+Fastify, plain `http`) into the scene, like Python's `agentglow.watch(app=...)`. The OpenTelemetry packages are
+optional peer dependencies, installed only by the apps that use this entry:
+
+```bash
+npm i agentglow @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/resources @opentelemetry/exporter-trace-otlp-http @opentelemetry/instrumentation @opentelemetry/instrumentation-http @opentelemetry/instrumentation-undici
+```
+
+```ts
+import { watch } from "agentglow/node";
+
+watch({ service: "web-bff", url: "http://localhost:8100" }); // before the server starts listening
+```
+
+- Incoming HTTP requests = the service's requests (req/s halo, 5xx flashes), named `METHOD route`.
+- Outgoing `fetch` / `http` calls = resource nodes, and carry a W3C `traceparent`: a Python API watched with
+  `agentglow.watch(app=...)` continues the same trace.
+- Spans go to `<url>/v1/traces` (OTLP/HTTP JSON); `ingestKey` (or env `AGENTGLOW_API_KEY`) is sent as `x-api-key`.
+
+| Option | Default | |
+|---|---|---|
+| `service` | env `OTEL_SERVICE_NAME`, else `node-app` | the service (agent) name |
+| `url` | env `AGENTGLOW_URL`, else `http://localhost:8100` | AgentGlow server |
+| `ingestKey` | env `AGENTGLOW_API_KEY` | server `--ingest-key` |
+| `privacy` | `"strict"` | `"strict"`: attribute allowlist. `"standard"`: other attributes kept, the drops and backstop below still apply |
+| `scrub` | | `(attrs, { name, kind }) => attrs`: your own rule, after the built-in ones |
+| `incoming` | `true` (`false` under Next.js) | trace incoming HTTP requests |
+| `ignorePaths` | `[]` | incoming paths not traced (`"/healthz"`, regexes) |
+
+`watch()` returns `{ flush(), shutdown() }` (call `flush()` before a short script exits) and is idempotent.
+
+**Privacy (strict).** Only method, route, status, peer host:port, messaging / db / rpc system names, `next.route` and
+`agentglow.*` attributes leave the process. Never bodies, headers (cookies, authorization), query strings, URL
+userinfo, client IPs, user agents, span events or error messages. Paths without a route template are id-normalized
+(`/orders/123` -> `/orders/:id`; numbers, UUIDs, hex, long tokens, emails). A regex backstop replaces emails, phone
+numbers, long ids and secrets in every remaining string.
+
+**Next.js** (`instrumentation.ts` at the project root, or in `src/`):
+
+```ts
+export async function register() {
+  if (process.env.NEXT_RUNTIME === "nodejs") {
+    (await import("agentglow/node")).watch({ service: "web-bff" });
+  }
+}
+```
+
+Next.js makes its own request spans (`GET /api/orders/[id]`), so `watch()` does not add a second one; `fetch` calls in
+route handlers, server actions and server components carry the `traceparent` into your API. The edge runtime is not
+traced. Already using OpenTelemetry (`@vercel/otel`, `NodeSDK`)? Add `spanProcessor()` from `agentglow/node` to its
+`spanProcessors` instead of calling `watch()`.
+
+**Express / Fastify:**
+
+```js
+import { watch } from "agentglow/node";
+import express from "express";
+
+watch({ service: "web-bff", ignorePaths: ["/healthz"] });
+const app = express();
+app.use("/api", async (req, res) => {
+  const r = await fetch(`http://localhost:8191${req.url}`); // traceparent added for you
+  res.status(r.status).type("json").send(await r.text());
+});
+app.listen(8190);
+```
+
+Example: [examples/node-proxy](../examples/node-proxy) (a Node proxy in front of the FastAPI orders example).
+`agentglow/pulse` stays for hand-sent events without OpenTelemetry.
+
 ## Props
 
 | Prop        | Type                  | Default    | What it does |
@@ -97,7 +172,7 @@ export default function Live() {
 | `theme`     | `Theme`               | `"neural"` | Which view to render (see below). Each theme loads lazily as its own chunk. |
 | `source`    | `string`              | `""`       | Base URL of the agentglow server. `""` means same origin. The scene reads `${source}/live/stream` (SSE), `/live/graph` and `/live/health`. |
 | `hud`       | `boolean`             | `true`     | Show the glass HUD: counts, event ticker and the agent inspector panel. |
-| `sim`       | `boolean`             | `false`    | Use the built-in simulator instead of a server. |
+| `sim`       | `boolean \| "hf"`     | `false`    | Use the built-in simulator instead of a server; `"hf"` = high-frequency simulator (30 market agents, ~100 decisions/s). |
 | `scope`     | `string`              | none       | Only show agents in this scope (a user or tenant id). Sent as the `X-AgentGlow-Scope` header, also as `scope` in the `POST /live/run` body. With a token, the token decides. |
 | `run`       | `string`              | none       | Only show this one run. Sent as the `X-AgentGlow-Run` header. |
 | `token`     | `string`              | none       | Token minted by your backend. Sent as `Authorization: Bearer <token>` on every `/live/*` request, never in a URL. |
@@ -144,11 +219,14 @@ backoff on its own. Changing `scope`, `run` or `token` reconnects and clears the
 | `flow`    | A murmuration. Agents condense as eddies out of the current. |
 | `constellation` | A night sky. Delegation draws constellation lines between agent stars. |
 | `atom`    | An atom. Agents are electrons; subagents orbit their parent. |
+| `bubblechamber` | A bubble chamber. Agents curl as particle tracks; a spawn decays into a V. |
+| `fireworks` | A night show in an open starry sky. Agents streak in like shooting stars and burst as star shells, subagents as secondary bursts. |
 
 | | | |
 |:-:|:-:|:-:|
 | ![neural](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/neural.jpg) **neural** | ![constellation](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/constellation.jpg) **constellation** | ![orbit](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/orbit.jpg) **orbit** |
-| ![atom](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/atom.jpg) **atom** | ![flow](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/flow.jpg) **flow** | |
+| ![atom](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/atom.jpg) **atom** | ![flow](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/flow.jpg) **flow** | ![bubblechamber](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/bubblechamber.jpg) **bubblechamber** |
+| ![fireworks](https://raw.githubusercontent.com/Nideesh1/agentglow/main/docs/media/fireworks.jpg) **fireworks** | | |
 
 ## Layout
 
@@ -177,7 +255,7 @@ npm run build:lib    # → dist/ (this package)
 npm run build:app    # → ../backend/agentglow/static (served by `agentglow serve`)
 ```
 
-In the app, `/` is the theme gallery and `/<theme>` is a full-screen scene. It accepts `?sim=1`,
+In the app, `/` is the theme gallery and `/<theme>` is a full-screen scene. It accepts `?sim=1`, `?sim=hf`,
 `?source=http://host:8100`, `?hud=0` and `?run=<id>` (a shareable "watch this run" link). Scope and token are
 props only: they are never read from the URL.
 

package/cli/agentglow.mjs

@@ -24,20 +24,21 @@ const VERSION = (() => {
 
 const HELP = `agentglow ${VERSION}: watch Claude Code agents in 3D
 
-  npx agentglow setup [--port 8100]   (recommended) set up once: hooks in ~/.claude/settings.json,
-                                      server auto-starts with every \`claude\` session
-  npx agentglow status                server health, port, pid, whether hooks are installed
+  npx agentglow setup [--port 8100]   (recommended) set up once: hooks + traces env in ~/.claude/settings.json,
+                                      server starts at login (macOS/Linux) and with every \`claude\` session
+  npx agentglow status                server health + version, port, pid, whether hooks are installed
   npx agentglow open                  open the 3D view (http://localhost:8100/neural)
   npx agentglow stop                  stop the background server
-  npx agentglow remove                undo setup: remove the hooks and stop the server
+  npx agentglow remove                undo setup: remove the hooks, env and login item, stop the server
   npx agentglow claude [-- <args>]    try it without installing: one claude session with AgentGlow
   npx agentglow setup --capture-prompts
                                       also show your prompts next to Claude's replies in the agent panel
                                       (off by default; local server only, secrets redacted)
 
-
+Setup flags: --no-autostart (no login item: the server starts with each claude session), --no-open
 More: npx agentglow start [--background] [--port N]   (serve = start in the foreground)
-Env:  AGENTGLOW_URL (remote server), AGENTGLOW_API_KEY (ingest key), AGENTGLOW_CACHE_DIR
+      npx agentglow autostart [--remove]              (re)register or drop only the login item
+Env:  AGENTGLOW_URL (remote server), AGENTGLOW_API_KEY (ingest key), AGENTGLOW_PORT, AGENTGLOW_CACHE_DIR
 `;
 
 const DEFAULT_PORT = 8100;