agentglow 0.3.1 → 0.4.0

package/dist/types/world.d.ts

@@ -1,3 +1,5 @@
+import { type Backlog, type PrimEdge, type PrimState, type PrimWorldEvent, type ResStat } from "./prims";
+export type { PrimState, PrimWorldEvent } from "./prims";
 export type AgentType = "planner" | "researcher" | "graph_scout" | "records_scout" | "data_scout" | "writer";
 /** Any workflow-defined step name (the backend scrubs and caps it). */
 export type StepName = string;
@@ -10,7 +12,14 @@ export type WorldEvent = {
     topic: string;
     workflow: string;
     ts: number;
+    reason?: string;
 } | {
+    type: "run";
+    run_id: string;
+    status: "idle" | "active";
+    since?: number;
+    ts: number;
+} | ({
     type: "step";
     run_id: string;
     step: StepName;
@@ -18,13 +27,15 @@ export type WorldEvent = {
     reason?: string;
     until?: number;
     ts: number;
-} | {
+} & WaitExtra) | {
     type: "spawn";
     run_id: string;
     id: string;
     agent: string;
     parent_id: string | null;
     subagent?: boolean;
+    job?: boolean;
+    since?: number;
     ts: number;
 } | {
     type: "exit";
@@ -32,7 +43,7 @@ export type WorldEvent = {
     id: string;
     status: "done" | "failed";
     ts: number;
-} | {
+} | ({
     type: "agent";
     run_id: string;
     id: string;
@@ -40,7 +51,7 @@ export type WorldEvent = {
     reason?: string;
     until?: number;
     ts: number;
-} | {
+} & WaitExtra) | {
     type: "llm";
     run_id: string;
     id: string;
@@ -57,6 +68,7 @@ export type WorldEvent = {
     to_id: string;
     text: string;
     ts: number;
+    failed?: boolean;
 } | {
     type: "tool";
     run_id: string;
@@ -106,6 +118,7 @@ export type WorldEvent = {
     purpose?: string;
     target?: string;
     scope?: string;
+    threshold?: number;
     ms: number;
     ts: number;
     hv?: boolean;
@@ -121,6 +134,40 @@ export type WorldEvent = {
     p95_ms: number;
     providers: Record<string, number>;
     ts: number;
+} | {
+    type: "request";
+    run_id: string;
+    id: string;
+    service: string;
+    name: string;
+    kind: "http" | "rpc" | "message" | "event";
+    status?: number;
+    error: boolean;
+    rejected?: boolean;
+    ms: number;
+    ts: number;
+    hv?: boolean;
+} | {
+    type: "service_stats";
+    run_id: string;
+    id: string;
+    service: string;
+    window_ms: number;
+    n: number;
+    errors: number;
+    codes: Record<string, number>;
+    p50_ms: number;
+    p95_ms: number;
+    routes: Record<string, number>;
+    ts: number;
+    instances?: number;
+    inflight?: number;
+} | {
+    type: "drives";
+    run_id: string;
+    id: string;
+    target_run: string;
+    ts: number;
 } | {
     type: "order";
     run_id: string;
@@ -153,8 +200,33 @@ export type WorldEvent = {
     ts: number;
     resource?: string;
     resource_kind?: ResourceKind;
-};
+    units?: number;
+    unit?: string;
+    device?: string;
+} | PrimWorldEvent;
 export type DecisionKind = "choice" | "score" | "noul";
+/** The decision that triggered a wait (docs/SPEC.md "Human approval"): a summary of its `decision` event. */
+export type WaitBecause = {
+    id?: string;
+    kind: string;
+    question: string;
+    result: string;
+    p?: number;
+    provider?: string;
+    purpose?: string;
+    target?: string;
+    threshold?: number;
+    ms?: number;
+    ts?: number;
+};
+/** A declared wait's drawer fields (`agentglow.wait.*`): `kind` "approval" = a human approval ("Needs you"). */
+export type WaitExtra = {
+    kind?: string;
+    title?: string;
+    details?: Record<string, string | number | boolean>;
+    url?: string;
+    because?: WaitBecause;
+};
 export type DecisionStatsByPurpose = {
     route?: {
         n: number;
@@ -195,6 +267,9 @@ export type HvStats = {
     provider: string;
     n: number;
     windows: number;
+    unit?: "req" | "msg";
+    instances?: number;
+    inflight?: number;
 };
 /** outcome categories of a decision halo arc: allow, deny, check yes, check no, route result slots 0..3, other */
 export declare const HALO_CATS: readonly ["allow", "deny", "yes", "no", "r0", "r1", "r2", "r3", "other"];
@@ -206,10 +281,27 @@ export declare const HV_QUIET_MS = 2500;
 export declare const HV_FADE_MS = 1500;
 /** 0..1 visibility of an agent's decision halo */
 export declare function haloMix(h: HvStats | null, now?: number): number;
+/** a backend service with no traffic for this long (ms) reads as idle: dimmed, label `feed · idle` */
+export declare const SVC_IDLE_MS = 10000;
+/** a top-level backend service agent (`svc:` id) */
+export declare const isSvc: (i: Instance) => boolean;
+/** a backend service with no requests / messages in the last SVC_IDLE_MS (or none since it appeared) */
+export declare const svcIdle: (i: Instance, now?: number) => boolean;
 /** the agent is in high-volume mode now (recent decision_stats) */
 export declare const hvActive: (i: Instance, now?: number) => boolean;
-/** `jev 42/s · 3% deny · p50 38ms` */
+/** The halo label: rate + error / deny share (only when > 0): `jev 42/s · 3% deny`; a service: `42 req/s · 2% errors`
+ * (`msg/s` for a consumer). Latency lives in the Selected panel and the label's hover tooltip (`haloLatency`). */
 export declare function haloText(h: HvStats): string;
+/** `3% deny` / `2% errors` / "" when none */
+export declare function haloShare(h: HvStats): string;
+/** `p50 38ms · p95 120ms` (+ `· 3 in flight` for a service) */
+export declare function haloLatency(h: HvStats): string;
+/** `2m14s` / `38s` / `1h05m` */
+export declare function elapsedText(ms: number): string;
+/** a job's name label: `mkt:tick · 2m14s` (frozen at its end) */
+export declare const jobText: (i: Instance) => string;
+/** a job's end flash 0..1 (green done / red failed), ~1.2 s */
+export declare const flashMix: (i: Instance, now?: number) => number;
 /** One decision on one agent; `at` (performance.now()) = when its glyph starts (staggered so a burst reads one by one). */
 export type DecisionUse = Omit<Extract<WorldEvent, {
     type: "decision";
@@ -272,7 +364,10 @@ export declare function orderText(o: {
     status?: string;
 }): string;
 /** What sits behind an MCP server (the server is a node; its backends are nodes too). */
-export type ResourceKind = "db" | "warehouse" | "spark" | "api" | "storage" | "queue";
+export type ResourceKind = "db" | "warehouse" | "spark" | "api" | "storage" | "queue" | "model" | "gpu" | "worker" | "cache";
+/** the six shapes every theme draws: newer kinds map onto the closest one (model / gpu -> spark, worker -> storage, cache -> db) */
+export type ShapeKind = "db" | "warehouse" | "spark" | "api" | "storage" | "queue";
+export declare const shapeKind: (k: string | undefined) => ShapeKind;
 export declare const AGENT_TYPES: {
     type: AgentType;
     label: string;
@@ -335,12 +430,34 @@ export type Instance = {
     }[];
     /** what it is waiting on (status "waiting" with a reason), else null */
     wait: Wait | null;
+    /** backend service agent: requests / errors handled (from `service_stats`) */
+    svcN?: number;
+    svcErr?: number;
+    /** backend service agent: performance.now() of its last traffic (requests / messages in or out); see svcIdle */
+    svcAt?: number;
+    /** a long-running request of a service shown as its subagent: started / ended (epoch ms, end 0 while open) */
+    job?: {
+        since: number;
+        end: number;
+    };
+    /** a job just ended: its halo flashes green (ok) / red (performance.now()) */
+    flash?: {
+        at: number;
+        ok: boolean;
+    };
+    /** generic primitives (prims.ts): created on the instance's first primitive event */
+    prim?: PrimState;
 };
 /** A declared wait: what it waits on ("approval", "sleep", an event key) and its deadline / wake-up (epoch ms, 0 = none). */
 export type Wait = {
     reason: string;
     until: number;
-};
+} & WaitExtra;
+/** reason / until + the drawer fields of a waiting `step` / `agent` event */
+export declare function waitOf(ev: {
+    reason?: string;
+    until?: number;
+} & WaitExtra): Wait;
 /** one skill on one agent; startAt / endAt (performance.now()) drive its sigil ring (endAt 0 while active) */
 export type SkillUse = {
     active: boolean;
@@ -387,6 +504,10 @@ export type Run = {
     /** the step that finished most recently (handoff source) */
     lastDone: StepName;
     final: string;
+    /** performance.now() of the run's latest event (stale detection) */
+    lastEventAt: number;
+    /** server-declared idle since (epoch ms of its last event), 0 = active (isIdle / idleText) */
+    idleSince: number;
 };
 /** Which of the 3 scene slots a step is drawn in (see STEP_SLOTS). */
 export declare function stepSlot(r: Run, step: StepName): number;
@@ -400,6 +521,23 @@ export declare function runWait(r: Run): (Wait & {
     step: StepName;
 }) | null;
 /** "sleeping until 14:05" / "waiting on approval" / "waiting on approval (until Oct 3, 09:00)" */
+/** A live run is stale when nothing arrived from it for STALE_QUIET_MS while a wait of it is past its deadline by
+ * STALE_GRACE_MS (e.g. its worker restarted mid-run: nobody will resolve the wait or end the run). */
+export declare const STALE_QUIET_MS = 20000;
+export declare const STALE_GRACE_MS = 15000;
+/** Idle run (server `run` status "idle"): its agents are dimmed (IDLE_DIM) and its label says "idle · 4m". */
+export declare const IDLE_DIM = 0.55;
+export declare const isIdle: (r: Run | undefined) => boolean;
+export declare function idleText(r: Run, wall?: number): string;
+export declare const isDismissed: (runId: string | undefined) => boolean;
+/** Hide a run (and its agents) for this viewer. */
+export declare function dismissRun(runId: string): void;
+/** Show the given runs again (all dismissed ones when omitted). */
+export declare function undismissRuns(ids?: string[]): void;
+/** Dismissed runs that are still in the world (the HUD's "N hidden" chip). */
+export declare const dismissedRuns: () => string[];
+export declare function isStale(r: Run | undefined, now?: number, wall?: number): boolean;
+export declare const STALE_TEXT = "stale: no worker activity";
 export declare function waitLabel(w: Wait, now?: number): string;
 export declare function stepChips(r: Run, max?: number): {
     shown: StepName[];
@@ -413,11 +551,21 @@ export type Comet = {
     start: number;
     dur: number;
     text: string;
+    failed?: boolean;
 };
+/** a failed comet (a publish that raised) sputters out half way: it stalls here and is gone at FIZZLE_END of its life */
+export declare const FIZZLE_STALL = 0.55;
+export declare const FIZZLE_END = 0.8;
+/** path parameter (0..1, before a theme's easing) of a comet: a failed one decelerates to the midpoint and stops */
+export declare function cometPos(c: Comet, now?: number): number;
+/** the comet head is still drawn (a failed one never arrives: no arrival flash) */
+export declare const cometOn: (c: Comet, now?: number) => boolean;
 /** External MCP servers agents call (persistent "satellites"; registered on first use). */
+/** `kind` = the shape themes draw (shapeKind), `sub` = the reported kind (model, gpu, worker, cache, ...) */
 export type McpResource = {
     name: string;
-    kind: ResourceKind;
+    kind: ShapeKind;
+    sub: ResourceKind;
     activeAt: number;
     inflight: number;
     calls: number;
@@ -514,6 +662,9 @@ export declare const world: {
         mcpCalls: number;
         decisions: number;
         decisionMs: number;
+        requests: number;
+        errors: number;
+        rejected: number;
     };
     /** decisions per provider (jev / laya / llm ...): count + summed latency (HUD chip tooltip) */
     decisionProviders: Map<string, {
@@ -572,7 +723,32 @@ export declare const world: {
     unauthorized: boolean;
     /** desk-wide halts (global-scope guard denies, see Halt), keyed by the owning agent */
     halts: Map<string, Halt>;
+    /** transient dashed edges: fallbacks and completed deferred callbacks (prims.ts) */
+    primEdges: PrimEdge[];
+    /** broker backlog per topic (prims.ts) */
+    backlogs: Map<string, Backlog>;
+    /** resource stats (pools, caches, models) keyed `server|resource` */
+    resStats: Map<string, ResStat>;
+    /** message topics between two services (`mkt:tick` feed -> worker), keyed `from|to|topic`: a persistent edge */
+    topics: Map<string, SvcTopic>;
+    /** service -> agent run it drives (`drives`), keyed `svc|run` */
+    drives: Map<string, {
+        svc: string;
+        run: string;
+    }>;
+};
+/** A topic between two services: first / last message (performance.now()), messages seen, the last one failed. */
+export type SvcTopic = {
+    from: string;
+    to: string;
+    topic: string;
+    first: number;
+    at: number;
+    n: number;
+    failed: boolean;
 };
+/** a topic edge stays drawn this long after its last message */
+export declare const TOPIC_STALE_MS = 15000;
 /**
  * A desk-wide halt: a guard decision with `scope: "global"` (docs/SPEC.md "Decisions") said no, e.g. a kill switch.
  * Owned by the topmost agent that reports global guards (a desk), drawn ONCE on it (red, `HALTED · <reason>`) instead
@@ -626,6 +802,9 @@ export declare function useWorld(): {
         mcpCalls: number;
         decisions: number;
         decisionMs: number;
+        requests: number;
+        errors: number;
+        rejected: number;
     };
     /** decisions per provider (jev / laya / llm ...): count + summed latency (HUD chip tooltip) */
     decisionProviders: Map<string, {
@@ -684,6 +863,19 @@ export declare function useWorld(): {
     unauthorized: boolean;
     /** desk-wide halts (global-scope guard denies, see Halt), keyed by the owning agent */
     halts: Map<string, Halt>;
+    /** transient dashed edges: fallbacks and completed deferred callbacks (prims.ts) */
+    primEdges: PrimEdge[];
+    /** broker backlog per topic (prims.ts) */
+    backlogs: Map<string, Backlog>;
+    /** resource stats (pools, caches, models) keyed `server|resource` */
+    resStats: Map<string, ResStat>;
+    /** message topics between two services (`mkt:tick` feed -> worker), keyed `from|to|topic`: a persistent edge */
+    topics: Map<string, SvcTopic>;
+    /** service -> agent run it drives (`drives`), keyed `svc|run` */
+    drives: Map<string, {
+        svc: string;
+        run: string;
+    }>;
 };
 /** Stable pseudo-random 0..1 from a string (same id → same value, different ids → different values). */
 export declare const hash01: (id: string, salt?: number) => number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentglow",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Live 3D views of agent systems (LangGraph, deepagents, any OpenTelemetry-instrumented agents) as a React component.",
   "keywords": [
     "claude-code",
@@ -12,7 +12,8 @@
     "deepagents",
     "react",
     "observability",
-    "react-three-fiber"
+    "react-three-fiber",
+    "nodejs"
   ],
   "license": "MIT",
   "repository": {
@@ -34,6 +35,17 @@
       "import": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./pulse": {
+      "types": "./dist/types/pulse.d.ts",
+      "import": "./dist/pulse.js",
+      "default": "./dist/pulse.js"
+    },
+    "./node": {
+      "types": "./dist/types/node.d.ts",
+      "node": "./dist/node.js",
+      "import": "./dist/node.js",
+      "default": "./dist/node.js"
+    },
     "./style.css": "./dist/style.css",
     "./package.json": "./package.json"
   },
@@ -64,7 +76,37 @@
   },
   "peerDependencies": {
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-trace-otlp-http": ">=0.200.0 <1",
+    "@opentelemetry/instrumentation": ">=0.200.0 <1",
+    "@opentelemetry/instrumentation-http": ">=0.200.0 <1",
+    "@opentelemetry/instrumentation-undici": ">=0.10.0 <1",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-trace-node": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@opentelemetry/api": {
+      "optional": true
+    },
+    "@opentelemetry/exporter-trace-otlp-http": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-http": {
+      "optional": true
+    },
+    "@opentelemetry/instrumentation-undici": {
+      "optional": true
+    },
+    "@opentelemetry/resources": {
+      "optional": true
+    },
+    "@opentelemetry/sdk-trace-node": {
+      "optional": true
+    }
   },
   "dependencies": {
     "@react-three/drei": "^10.7.9",
@@ -74,13 +116,20 @@
     "three": "^0.186.1"
   },
   "devDependencies": {
+    "@opentelemetry/api": "^1.9.1",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.222.0",
+    "@opentelemetry/instrumentation": "^0.222.0",
+    "@opentelemetry/instrumentation-http": "^0.222.0",
+    "@opentelemetry/instrumentation-undici": "^0.32.0",
+    "@opentelemetry/resources": "^2.11.0",
+    "@opentelemetry/sdk-trace-node": "^2.11.0",
     "@types/node": "^22.20.4",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^4.0.0",
-    "typescript": "^5.6.0",
-    "vite": "^6.0.0",
     "react": "^19.0.0",
-    "react-dom": "^19.0.0"
+    "react-dom": "^19.0.0",
+    "typescript": "^5.6.0",
+    "vite": "^6.0.0"
   }
 }