agentglow 0.2.12 → 0.3.1

package/dist/types/world.d.ts

@@ -46,6 +46,8 @@ export type WorldEvent = {
     id: string;
     tokens_in: number;
     tokens_out: number;
+    tokens_cached?: number;
+    tokens_cache_write?: number;
     latency_ms: number;
     ts: number;
 } | {
@@ -88,6 +90,49 @@ export type WorldEvent = {
     name: string;
     status: "start" | "end";
     ts: number;
+} | {
+    type: "decision";
+    run_id: string;
+    id: string;
+    kind: DecisionKind;
+    question: string;
+    result: string;
+    p?: number;
+    options?: {
+        name: string;
+        p: number;
+    }[];
+    provider: string;
+    purpose?: string;
+    target?: string;
+    scope?: string;
+    ms: number;
+    ts: number;
+    hv?: boolean;
+    why?: string;
+} | {
+    type: "decision_stats";
+    run_id: string;
+    id: string;
+    window_ms: number;
+    n: number;
+    by_purpose: DecisionStatsByPurpose;
+    p50_ms: number;
+    p95_ms: number;
+    providers: Record<string, number>;
+    ts: number;
+} | {
+    type: "order";
+    run_id: string;
+    id: string;
+    side: string;
+    qty: number;
+    price?: number;
+    status: OrderStatus;
+    instrument: string;
+    dry_run: boolean;
+    reason?: string;
+    ts: number;
 } | {
     type: "mcp_register";
     run_id?: string;
@@ -109,6 +154,123 @@ export type WorldEvent = {
     resource?: string;
     resource_kind?: ResourceKind;
 };
+export type DecisionKind = "choice" | "score" | "noul";
+export type DecisionStatsByPurpose = {
+    route?: {
+        n: number;
+        results: Record<string, number>;
+    };
+    guard?: {
+        n: number;
+        allow: number;
+        deny: number;
+    };
+    check?: {
+        n: number;
+        yes: number;
+        no: number;
+    };
+};
+export type OrderStatus = "would_place" | "placed" | "filled" | "rejected" | "cancelled";
+/** One order on one agent; `at` = performance.now() when it arrived (its chip plays from there). */
+export type OrderUse = Omit<Extract<WorldEvent, {
+    type: "order";
+}>, "type" | "run_id" | "id"> & {
+    at: number;
+};
+export declare const ORDER_LIFE_MS = 1500;
+/**
+ * High-volume decisions, per agent (from `decision_stats`): smoothed (EMA) so the halo and its label never flicker.
+ * `seg` = smoothed share of each outcome category, in HALO_CATS order.
+ */
+export type HvStats = {
+    at: number;
+    bump: number;
+    bumpDeny: boolean;
+    rate: number;
+    deny: number;
+    p50: number;
+    p95: number;
+    seg: number[];
+    provider: string;
+    n: number;
+    windows: 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"];
+export declare const HALO_COLORS: string[];
+/** route result name -> accent slot 0..3 (first four names seen in this session; later ones are "other") */
+export declare const routeSlots: Map<string, number>;
+/** a halo fades out once its agent sent no stats for this long (ms), over HV_FADE_MS */
+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;
+/** 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` */
+export declare function haloText(h: HvStats): string;
+/** 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";
+}>, "type" | "run_id" | "id"> & {
+    at: number;
+    /** high volume: not shown as a glyph (over the on-screen cap; it only flashed the halo) */
+    hidden?: boolean;
+    /** high volume: pre-empted by a more important glyph at this time (fades out fast) */
+    cut?: number;
+};
+/** Decision glyph timing (ms): snap in fast (much faster than LLM pulses / skill rings on purpose), then hold long
+ *  enough to read on a video; a guard deny holds longer. */
+export declare const DECISION_SNAP_MS = 150;
+export declare const DECISION_HOLD_MS = 1800;
+export declare const DECISION_LIFE_MS = 2400;
+export declare const DENY_HOLD_MS = 2500;
+export declare const DENY_LIFE_MS = 3100;
+/** min gap between two glyph starts on one agent (a burst of decisions plays as a quick sequence) */
+export declare const DECISION_STAGGER_MS = 220;
+/** high-volume mode (`hv` decisions): short holds so glyphs don't pile up */
+export declare const HV_HOLD_MS = 800;
+export declare const HV_LIFE_MS = 1150;
+/** how long a decision's glyph lives (ms) */
+export declare const decisionLife: (d: {
+    kind: string;
+    result: string;
+    purpose?: string;
+    hv?: boolean;
+}) => number;
+/** 0..1 visibility of a decision glyph: snaps in (DECISION_SNAP_MS), holds, fades out by decisionLife(d). */
+export declare function decisionMix(d: DecisionUse, now?: number): number;
+/** a guardrail that said no (shown as a red X / shut gate) */
+export declare const isDeny: (d: {
+    kind: string;
+    result: string;
+    purpose?: string;
+}) => boolean;
+export declare const pct: (p?: number) => string;
+/** short text for a decision: `jev · route → haiku 92%`, `guard: deny rollback_deploy 97%` */
+export declare function decisionText(d: {
+    kind: string;
+    question: string;
+    result: string;
+    p?: number;
+    provider: string;
+    purpose?: string;
+    target?: string;
+}): string;
+/** friendly decision-kind badge (display only; events and docs keep the raw kind) */
+export declare const kindBadge: (kind: string) => "YES/NO" | "SCORE" | "PICK";
+/** friendly high-volume reason tag (`why`) */
+export declare const whyBadge: (why: string) => string;
+/** provider badge: code guards read as a rule */
+export declare const providerBadge: (p: string) => string;
+/** `YES 3 @ 42c`, `SELL 10 @ 101.5` (prices below 1 read as cents) */
+export declare function orderText(o: {
+    side: string;
+    qty: number;
+    price?: number;
+    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 declare const AGENT_TYPES: {
@@ -146,6 +308,7 @@ export type Instance = {
     pulse: number;
     pulseAt: number;
     tokens: number;
+    tokensCached: number;
     index: number;
     recent: WorldEvent[];
     llmCalls: number;
@@ -157,6 +320,14 @@ export type Instance = {
     /** newest started skill ("" = none yet) and when the last active one ended (0 while one is active) */
     skill: string;
     skillEndAt: number;
+    /** recent decisions (newest last, capped); glyphs play from `at` */
+    decisions: DecisionUse[];
+    /** high-volume decision stats (null until its first `decision_stats`) */
+    hv: HvStats | null;
+    /** recent orders (newest last, capped) */
+    orders: OrderUse[];
+    /** the MCP server this agent called last (a guard deny flashes the agent's line to it) */
+    lastMcp?: string;
     /** opt-in prompt capture: this agent's turns, oldest first (user prompt, then its reply), capped */
     chat: {
         role: "user" | "agent";
@@ -329,6 +500,8 @@ export declare const world: {
     mcpResolved: (McpPending & {
         resolvedAt: number;
     })[];
+    /** MCP tool name -> the server it was last called on (a guard deny on that tool flashes the line to it) */
+    mcpTools: Map<string, string>;
     ticker: WorldEvent[];
     stats: {
         runs: number;
@@ -339,6 +512,35 @@ export declare const world: {
         graphReads: number;
         graphWrites: number;
         mcpCalls: number;
+        decisions: number;
+        decisionMs: number;
+    };
+    /** decisions per provider (jev / laya / llm ...): count + summed latency (HUD chip tooltip) */
+    decisionProviders: Map<string, {
+        n: number;
+        ms: number;
+    }>;
+    /** session-wide decision rate (HUD): last full second's rate, deny share, p50/p95, 60 s sparkline (per second) */
+    rate: {
+        perS: number;
+        deny: number;
+        p50: number;
+        p95: number;
+        spark: number[];
+        rollAt: number;
+        acc: {
+            n: number;
+            deny: number;
+            msN: number;
+            p50: number;
+            p95: number;
+        };
+    };
+    /** orders seen: total, paper (dry_run), rejected/cancelled */
+    orders: {
+        n: number;
+        paper: number;
+        rejected: number;
     };
     lastFinal: string;
     simulated: boolean;
@@ -368,7 +570,28 @@ export declare const world: {
     selected: string | null;
     /** the server answered 401 for this scope/run/token (the HUD shows a notice; no simulator fallback) */
     unauthorized: boolean;
+    /** desk-wide halts (global-scope guard denies, see Halt), keyed by the owning agent */
+    halts: Map<string, Halt>;
 };
+/**
+ * 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
+ * of a red X on every agent below it; their own global denies only flash their halos. Ends when every global guard
+ * the owner said no to says yes again, or the owner / its run ends.
+ */
+export type Halt = {
+    id: string;
+    run: string;
+    reason: string;
+    since: number;
+    end: number;
+    qs: Map<string, boolean>;
+};
+/** the halt shown on agent `id` right now (also while it fades out after the end), if any */
+export declare function haltOn(id: string, now?: number): Halt | undefined;
+export declare const HALT_FADE_MS = 900;
+/** some agent is halted now (HUD chip) */
+export declare function haltedNow(now?: number): Halt | undefined;
 /** Subscribe a React component to world changes (HUD / DOM). Scenes should read `world` in useFrame instead. */
 export declare function useWorld(): {
     runs: Map<string, Run>;
@@ -389,6 +612,8 @@ export declare function useWorld(): {
     mcpResolved: (McpPending & {
         resolvedAt: number;
     })[];
+    /** MCP tool name -> the server it was last called on (a guard deny on that tool flashes the line to it) */
+    mcpTools: Map<string, string>;
     ticker: WorldEvent[];
     stats: {
         runs: number;
@@ -399,6 +624,35 @@ export declare function useWorld(): {
         graphReads: number;
         graphWrites: number;
         mcpCalls: number;
+        decisions: number;
+        decisionMs: number;
+    };
+    /** decisions per provider (jev / laya / llm ...): count + summed latency (HUD chip tooltip) */
+    decisionProviders: Map<string, {
+        n: number;
+        ms: number;
+    }>;
+    /** session-wide decision rate (HUD): last full second's rate, deny share, p50/p95, 60 s sparkline (per second) */
+    rate: {
+        perS: number;
+        deny: number;
+        p50: number;
+        p95: number;
+        spark: number[];
+        rollAt: number;
+        acc: {
+            n: number;
+            deny: number;
+            msN: number;
+            p50: number;
+            p95: number;
+        };
+    };
+    /** orders seen: total, paper (dry_run), rejected/cancelled */
+    orders: {
+        n: number;
+        paper: number;
+        rejected: number;
     };
     lastFinal: string;
     simulated: boolean;
@@ -428,9 +682,13 @@ export declare function useWorld(): {
     selected: string | null;
     /** the server answered 401 for this scope/run/token (the HUD shows a notice; no simulator fallback) */
     unauthorized: boolean;
+    /** desk-wide halts (global-scope guard denies, see Halt), keyed by the owning agent */
+    halts: Map<string, Halt>;
 };
 /** 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;
+/** high volume: most individual decision glyphs on screen at once (all agents) */
+export declare const HV_GLYPHS_MAX = 3;
 export declare function apply(ev: WorldEvent): void;
 export declare function tick(now?: number): void;
 /** 0..1 visibility for an instance: grows in on spawn, fades out after exit. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentglow",
-  "version": "0.2.12",
+  "version": "0.3.1",
   "description": "Live 3D views of agent systems (LangGraph, deepagents, any OpenTelemetry-instrumented agents) as a React component.",
   "keywords": [
     "claude-code",