@halo-sdk/react 1.0.0

package/README.md

@@ -0,0 +1,36 @@
+# @halo-sdk/react
+
+Lightweight, strongly-typed React hooks for Halo SDK. They fold the S5 `HaloEvent` stream into UI state so you can show cache, cost, loop, and human-in-the-loop effects live — without a heavy client runtime.
+
+Every hook takes a `Subscribe` function with the exact shape of `HaloAgent.observe` — pass `agent.observe` directly (same process), or a transport that relays events to the browser.
+
+```tsx
+import { useCacheProfile, useCost, useApprovals } from "@halo-sdk/react";
+
+function Dashboard({ subscribe }) {
+  const cache = useCacheProfile(subscribe); // { hitRate, grade, ... }
+  const cost = useCost(subscribe); // { turns, estimatedUsd, ... }
+  const pending = useApprovals(subscribe); // pending HITL tool calls
+
+  return (
+    <>
+      <Badge grade={cache.grade} hitRate={cache.hitRate} />
+      <Spend usd={cost.estimatedUsd} turns={cost.turns} />
+      {pending.map((p) => (
+        <ApprovalCard key={p.toolCallId} call={p.call} />
+      ))}
+    </>
+  );
+}
+```
+
+## Hooks
+
+- `useCacheStats` — hit/miss/write tokens + hit rate
+- `useCacheProfile` — the above plus an A–F cacheability grade
+- `useCost` — cumulative turns, tokens, estimated USD
+- `useLoopState` — current step + status (idle/running/paused/error)
+- `useApprovals` — pending HITL tool approvals
+- `useHaloState` — the generic reducer hook the others build on
+
+The reducers (`cacheStatsReducer`, `costReducer`, `loopStateReducer`, `approvalsReducer`) are pure and exported, so you can fold the same stream server-side or in tests.

package/dist/hooks.d.ts

@@ -0,0 +1,25 @@
+import type { HaloEvent, Observer } from "@halo-sdk/core";
+import { type CacheStatsState, type CostState, type LoopState, type PendingApproval } from "./reducers.js";
+/**
+ * A subscribe function — exactly the shape of `HaloAgent.observe`. Pass
+ * `agent.observe` directly, or a transport that fans `HaloEvent`s to the client.
+ */
+export type Subscribe = (observer: Observer) => () => void;
+/**
+ * Generic hook: fold the {@link HaloEvent} stream into derived state via a pure
+ * reducer. The building block for all the specific hooks below.
+ */
+export declare function useHaloState<S>(subscribe: Subscribe, reducer: (state: S, event: HaloEvent) => S, initial: () => S): S;
+/** Live prefix-cache hit/miss/write tokens + hit rate. */
+export declare function useCacheStats(subscribe: Subscribe): CacheStatsState;
+/** Cumulative turns, tokens, and estimated USD spend. */
+export declare function useCost(subscribe: Subscribe): CostState;
+/** Current agent-loop step + status (idle/running/paused/error). */
+export declare function useLoopState(subscribe: Subscribe): LoopState;
+/** Pending human-in-the-loop tool approvals (for an approval UI). */
+export declare function useApprovals(subscribe: Subscribe): PendingApproval[];
+/** A cacheability grade derived live from the hit rate (A–F). */
+export declare function useCacheProfile(subscribe: Subscribe): CacheStatsState & {
+    grade: "A" | "B" | "C" | "D" | "F";
+};
+//# sourceMappingURL=hooks.d.ts.map

package/dist/hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.ts","sourceRoot":"","sources":["../src/hooks.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1D,OAAO,EASL,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,eAAe,EACrB,MAAM,eAAe,CAAC;AAEvB;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,QAAQ,EAAE,QAAQ,KAAK,MAAM,IAAI,CAAC;AAE3D;;;GAGG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAC5B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,CAAC,KAAK,EAAE,CAAC,EAAE,KAAK,EAAE,SAAS,KAAK,CAAC,EAC1C,OAAO,EAAE,MAAM,CAAC,GACf,CAAC,CAUH;AAED,0DAA0D;AAC1D,wBAAgB,aAAa,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,CAEnE;AAED,yDAAyD;AACzD,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAEvD;AAED,oEAAoE;AACpE,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,SAAS,CAE5D;AAED,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,EAAE,CAEpE;AAED,iEAAiE;AACjE,wBAAgB,eAAe,CAAC,SAAS,EAAE,SAAS,GAAG,eAAe,GAAG;IACvE,KAAK,EAAE,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,GAAG,CAAC;CACpC,CAGA"}

package/dist/index.cjs

@@ -0,0 +1,162 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  approvalsReducer: () => approvalsReducer,
+  cacheStatsReducer: () => cacheStatsReducer,
+  costReducer: () => costReducer,
+  initialApprovals: () => initialApprovals,
+  initialCacheStats: () => initialCacheStats,
+  initialCost: () => initialCost,
+  initialLoopState: () => initialLoopState,
+  loopStateReducer: () => loopStateReducer,
+  useApprovals: () => useApprovals,
+  useCacheProfile: () => useCacheProfile,
+  useCacheStats: () => useCacheStats,
+  useCost: () => useCost,
+  useHaloState: () => useHaloState,
+  useLoopState: () => useLoopState
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/hooks.ts
+var import_react = require("react");
+
+// src/reducers.ts
+var initialCacheStats = () => ({
+  hitTokens: 0,
+  missTokens: 0,
+  writeTokens: 0,
+  hitRate: 0
+});
+function cacheStatsReducer(state, event) {
+  if (event.type !== "cache:hit") return state;
+  const hitTokens = state.hitTokens + event.hitTokens;
+  const missTokens = state.missTokens + event.missTokens;
+  const total = hitTokens + missTokens;
+  return {
+    hitTokens,
+    missTokens,
+    writeTokens: state.writeTokens,
+    hitRate: total > 0 ? hitTokens / total : 0
+  };
+}
+var initialCost = () => ({
+  turns: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  estimatedUsd: 0
+});
+function costReducer(state, event) {
+  switch (event.type) {
+    case "turn:end":
+      return { ...state, turns: state.turns + 1 };
+    case "cost":
+      return {
+        ...state,
+        promptTokens: state.promptTokens + event.promptTokens,
+        completionTokens: state.completionTokens + event.completionTokens,
+        estimatedUsd: state.estimatedUsd + (event.estimatedUsd ?? 0)
+      };
+    default:
+      return state;
+  }
+}
+var initialLoopState = () => ({ step: 0, status: "idle", lastError: null });
+function loopStateReducer(state, event) {
+  switch (event.type) {
+    case "loop:step":
+      return { ...state, step: event.step, status: "running" };
+    case "loop:paused":
+      return { ...state, status: "paused" };
+    case "loop:resumed":
+      return { ...state, status: "running" };
+    case "loop:error":
+      return { ...state, status: "error", lastError: event.error };
+    case "turn:end":
+      return state.status === "error" ? state : { ...state, status: "idle" };
+    default:
+      return state;
+  }
+}
+var initialApprovals = () => [];
+function approvalsReducer(state, event) {
+  switch (event.type) {
+    case "hitl:pending":
+      return [...state, { toolCallId: event.call.id, call: event.call }];
+    case "hitl:resolved":
+      return state.filter((a) => a.toolCallId !== event.toolCallId);
+    default:
+      return state;
+  }
+}
+
+// src/hooks.ts
+function useHaloState(subscribe, reducer, initial) {
+  const [state, setState] = (0, import_react.useState)(initial);
+  const reducerRef = (0, import_react.useRef)(reducer);
+  reducerRef.current = reducer;
+  (0, import_react.useEffect)(() => {
+    return subscribe((event) => setState((prev) => reducerRef.current(prev, event)));
+  }, [subscribe]);
+  return state;
+}
+function useCacheStats(subscribe) {
+  return useHaloState(subscribe, cacheStatsReducer, initialCacheStats);
+}
+function useCost(subscribe) {
+  return useHaloState(subscribe, costReducer, initialCost);
+}
+function useLoopState(subscribe) {
+  return useHaloState(subscribe, loopStateReducer, initialLoopState);
+}
+function useApprovals(subscribe) {
+  return useHaloState(subscribe, approvalsReducer, initialApprovals);
+}
+function useCacheProfile(subscribe) {
+  const stats = useCacheStats(subscribe);
+  return { ...stats, grade: gradeFor(stats.hitRate) };
+}
+function gradeFor(hitRate) {
+  if (hitRate >= 0.9) return "A";
+  if (hitRate >= 0.75) return "B";
+  if (hitRate >= 0.5) return "C";
+  if (hitRate >= 0.25) return "D";
+  return "F";
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  approvalsReducer,
+  cacheStatsReducer,
+  costReducer,
+  initialApprovals,
+  initialCacheStats,
+  initialCost,
+  initialLoopState,
+  loopStateReducer,
+  useApprovals,
+  useCacheProfile,
+  useCacheStats,
+  useCost,
+  useHaloState,
+  useLoopState
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/hooks.ts","../src/reducers.ts"],"sourcesContent":["export {\n  useHaloState,\n  useCacheStats,\n  useCost,\n  useLoopState,\n  useApprovals,\n  useCacheProfile,\n  type Subscribe,\n} from \"./hooks.js\";\nexport {\n  cacheStatsReducer,\n  costReducer,\n  loopStateReducer,\n  approvalsReducer,\n  initialCacheStats,\n  initialCost,\n  initialLoopState,\n  initialApprovals,\n  type CacheStatsState,\n  type CostState,\n  type LoopState,\n  type PendingApproval,\n} from \"./reducers.js\";\n","import { useEffect, useRef, useState } from \"react\";\nimport type { HaloEvent, Observer } from \"@halo-sdk/core\";\nimport {\n  approvalsReducer,\n  cacheStatsReducer,\n  costReducer,\n  initialApprovals,\n  initialCacheStats,\n  initialCost,\n  initialLoopState,\n  loopStateReducer,\n  type CacheStatsState,\n  type CostState,\n  type LoopState,\n  type PendingApproval,\n} from \"./reducers.js\";\n\n/**\n * A subscribe function — exactly the shape of `HaloAgent.observe`. Pass\n * `agent.observe` directly, or a transport that fans `HaloEvent`s to the client.\n */\nexport type Subscribe = (observer: Observer) => () => void;\n\n/**\n * Generic hook: fold the {@link HaloEvent} stream into derived state via a pure\n * reducer. The building block for all the specific hooks below.\n */\nexport function useHaloState<S>(\n  subscribe: Subscribe,\n  reducer: (state: S, event: HaloEvent) => S,\n  initial: () => S,\n): S {\n  const [state, setState] = useState<S>(initial);\n  const reducerRef = useRef(reducer);\n  reducerRef.current = reducer;\n\n  useEffect(() => {\n    return subscribe((event) => setState((prev) => reducerRef.current(prev, event)));\n  }, [subscribe]);\n\n  return state;\n}\n\n/** Live prefix-cache hit/miss/write tokens + hit rate. */\nexport function useCacheStats(subscribe: Subscribe): CacheStatsState {\n  return useHaloState(subscribe, cacheStatsReducer, initialCacheStats);\n}\n\n/** Cumulative turns, tokens, and estimated USD spend. */\nexport function useCost(subscribe: Subscribe): CostState {\n  return useHaloState(subscribe, costReducer, initialCost);\n}\n\n/** Current agent-loop step + status (idle/running/paused/error). */\nexport function useLoopState(subscribe: Subscribe): LoopState {\n  return useHaloState(subscribe, loopStateReducer, initialLoopState);\n}\n\n/** Pending human-in-the-loop tool approvals (for an approval UI). */\nexport function useApprovals(subscribe: Subscribe): PendingApproval[] {\n  return useHaloState(subscribe, approvalsReducer, initialApprovals);\n}\n\n/** A cacheability grade derived live from the hit rate (A–F). */\nexport function useCacheProfile(subscribe: Subscribe): CacheStatsState & {\n  grade: \"A\" | \"B\" | \"C\" | \"D\" | \"F\";\n} {\n  const stats = useCacheStats(subscribe);\n  return { ...stats, grade: gradeFor(stats.hitRate) };\n}\n\nfunction gradeFor(hitRate: number): \"A\" | \"B\" | \"C\" | \"D\" | \"F\" {\n  if (hitRate >= 0.9) return \"A\";\n  if (hitRate >= 0.75) return \"B\";\n  if (hitRate >= 0.5) return \"C\";\n  if (hitRate >= 0.25) return \"D\";\n  return \"F\";\n}\n","import type { HaloEvent, ToolCall } from \"@halo-sdk/core\";\n\n// Pure reducers over the HaloEvent stream. Framework-free and unit-testable;\n// the React hooks in `hooks.ts` are thin wrappers around these.\n\nexport interface CacheStatsState {\n  hitTokens: number;\n  missTokens: number;\n  writeTokens: number;\n  hitRate: number;\n}\n\nexport const initialCacheStats = (): CacheStatsState => ({\n  hitTokens: 0,\n  missTokens: 0,\n  writeTokens: 0,\n  hitRate: 0,\n});\n\nexport function cacheStatsReducer(state: CacheStatsState, event: HaloEvent): CacheStatsState {\n  if (event.type !== \"cache:hit\") return state;\n  const hitTokens = state.hitTokens + event.hitTokens;\n  const missTokens = state.missTokens + event.missTokens;\n  const total = hitTokens + missTokens;\n  return {\n    hitTokens,\n    missTokens,\n    writeTokens: state.writeTokens,\n    hitRate: total > 0 ? hitTokens / total : 0,\n  };\n}\n\nexport interface CostState {\n  turns: number;\n  promptTokens: number;\n  completionTokens: number;\n  estimatedUsd: number;\n}\n\nexport const initialCost = (): CostState => ({\n  turns: 0,\n  promptTokens: 0,\n  completionTokens: 0,\n  estimatedUsd: 0,\n});\n\nexport function costReducer(state: CostState, event: HaloEvent): CostState {\n  switch (event.type) {\n    case \"turn:end\":\n      return { ...state, turns: state.turns + 1 };\n    case \"cost\":\n      return {\n        ...state,\n        promptTokens: state.promptTokens + event.promptTokens,\n        completionTokens: state.completionTokens + event.completionTokens,\n        estimatedUsd: state.estimatedUsd + (event.estimatedUsd ?? 0),\n      };\n    default:\n      return state;\n  }\n}\n\nexport interface LoopState {\n  step: number;\n  status: \"idle\" | \"running\" | \"paused\" | \"error\";\n  lastError: string | null;\n}\n\nexport const initialLoopState = (): LoopState => ({ step: 0, status: \"idle\", lastError: null });\n\nexport function loopStateReducer(state: LoopState, event: HaloEvent): LoopState {\n  switch (event.type) {\n    case \"loop:step\":\n      return { ...state, step: event.step, status: \"running\" };\n    case \"loop:paused\":\n      return { ...state, status: \"paused\" };\n    case \"loop:resumed\":\n      return { ...state, status: \"running\" };\n    case \"loop:error\":\n      return { ...state, status: \"error\", lastError: event.error };\n    case \"turn:end\":\n      return state.status === \"error\" ? state : { ...state, status: \"idle\" };\n    default:\n      return state;\n  }\n}\n\nexport interface PendingApproval {\n  toolCallId: string;\n  call: ToolCall;\n}\n\nexport const initialApprovals = (): PendingApproval[] => [];\n\nexport function approvalsReducer(state: PendingApproval[], event: HaloEvent): PendingApproval[] {\n  switch (event.type) {\n    case \"hitl:pending\":\n      return [...state, { toolCallId: event.call.id, call: event.call }];\n    case \"hitl:resolved\":\n      return state.filter((a) => a.toolCallId !== event.toolCallId);\n    default:\n      return state;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { useHaloState, useCacheStats, useCost, useLoopState, useApprovals, useCacheProfile, type Subscribe, } from "./hooks.js";
+export { cacheStatsReducer, costReducer, loopStateReducer, approvalsReducer, initialCacheStats, initialCost, initialLoopState, initialApprovals, type CacheStatsState, type CostState, type LoopState, type PendingApproval, } from "./reducers.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,aAAa,EACb,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,eAAe,EACf,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,iBAAiB,EACjB,WAAW,EACX,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,SAAS,EACd,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,122 @@
+// src/hooks.ts
+import { useEffect, useRef, useState } from "react";
+
+// src/reducers.ts
+var initialCacheStats = () => ({
+  hitTokens: 0,
+  missTokens: 0,
+  writeTokens: 0,
+  hitRate: 0
+});
+function cacheStatsReducer(state, event) {
+  if (event.type !== "cache:hit") return state;
+  const hitTokens = state.hitTokens + event.hitTokens;
+  const missTokens = state.missTokens + event.missTokens;
+  const total = hitTokens + missTokens;
+  return {
+    hitTokens,
+    missTokens,
+    writeTokens: state.writeTokens,
+    hitRate: total > 0 ? hitTokens / total : 0
+  };
+}
+var initialCost = () => ({
+  turns: 0,
+  promptTokens: 0,
+  completionTokens: 0,
+  estimatedUsd: 0
+});
+function costReducer(state, event) {
+  switch (event.type) {
+    case "turn:end":
+      return { ...state, turns: state.turns + 1 };
+    case "cost":
+      return {
+        ...state,
+        promptTokens: state.promptTokens + event.promptTokens,
+        completionTokens: state.completionTokens + event.completionTokens,
+        estimatedUsd: state.estimatedUsd + (event.estimatedUsd ?? 0)
+      };
+    default:
+      return state;
+  }
+}
+var initialLoopState = () => ({ step: 0, status: "idle", lastError: null });
+function loopStateReducer(state, event) {
+  switch (event.type) {
+    case "loop:step":
+      return { ...state, step: event.step, status: "running" };
+    case "loop:paused":
+      return { ...state, status: "paused" };
+    case "loop:resumed":
+      return { ...state, status: "running" };
+    case "loop:error":
+      return { ...state, status: "error", lastError: event.error };
+    case "turn:end":
+      return state.status === "error" ? state : { ...state, status: "idle" };
+    default:
+      return state;
+  }
+}
+var initialApprovals = () => [];
+function approvalsReducer(state, event) {
+  switch (event.type) {
+    case "hitl:pending":
+      return [...state, { toolCallId: event.call.id, call: event.call }];
+    case "hitl:resolved":
+      return state.filter((a) => a.toolCallId !== event.toolCallId);
+    default:
+      return state;
+  }
+}
+
+// src/hooks.ts
+function useHaloState(subscribe, reducer, initial) {
+  const [state, setState] = useState(initial);
+  const reducerRef = useRef(reducer);
+  reducerRef.current = reducer;
+  useEffect(() => {
+    return subscribe((event) => setState((prev) => reducerRef.current(prev, event)));
+  }, [subscribe]);
+  return state;
+}
+function useCacheStats(subscribe) {
+  return useHaloState(subscribe, cacheStatsReducer, initialCacheStats);
+}
+function useCost(subscribe) {
+  return useHaloState(subscribe, costReducer, initialCost);
+}
+function useLoopState(subscribe) {
+  return useHaloState(subscribe, loopStateReducer, initialLoopState);
+}
+function useApprovals(subscribe) {
+  return useHaloState(subscribe, approvalsReducer, initialApprovals);
+}
+function useCacheProfile(subscribe) {
+  const stats = useCacheStats(subscribe);
+  return { ...stats, grade: gradeFor(stats.hitRate) };
+}
+function gradeFor(hitRate) {
+  if (hitRate >= 0.9) return "A";
+  if (hitRate >= 0.75) return "B";
+  if (hitRate >= 0.5) return "C";
+  if (hitRate >= 0.25) return "D";
+  return "F";
+}
+export {
+  approvalsReducer,
+  cacheStatsReducer,
+  costReducer,
+  initialApprovals,
+  initialCacheStats,
+  initialCost,
+  initialLoopState,
+  loopStateReducer,
+  useApprovals,
+  useCacheProfile,
+  useCacheStats,
+  useCost,
+  useHaloState,
+  useLoopState
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/hooks.ts","../src/reducers.ts"],"sourcesContent":["import { useEffect, useRef, useState } from \"react\";\nimport type { HaloEvent, Observer } from \"@halo-sdk/core\";\nimport {\n  approvalsReducer,\n  cacheStatsReducer,\n  costReducer,\n  initialApprovals,\n  initialCacheStats,\n  initialCost,\n  initialLoopState,\n  loopStateReducer,\n  type CacheStatsState,\n  type CostState,\n  type LoopState,\n  type PendingApproval,\n} from \"./reducers.js\";\n\n/**\n * A subscribe function — exactly the shape of `HaloAgent.observe`. Pass\n * `agent.observe` directly, or a transport that fans `HaloEvent`s to the client.\n */\nexport type Subscribe = (observer: Observer) => () => void;\n\n/**\n * Generic hook: fold the {@link HaloEvent} stream into derived state via a pure\n * reducer. The building block for all the specific hooks below.\n */\nexport function useHaloState<S>(\n  subscribe: Subscribe,\n  reducer: (state: S, event: HaloEvent) => S,\n  initial: () => S,\n): S {\n  const [state, setState] = useState<S>(initial);\n  const reducerRef = useRef(reducer);\n  reducerRef.current = reducer;\n\n  useEffect(() => {\n    return subscribe((event) => setState((prev) => reducerRef.current(prev, event)));\n  }, [subscribe]);\n\n  return state;\n}\n\n/** Live prefix-cache hit/miss/write tokens + hit rate. */\nexport function useCacheStats(subscribe: Subscribe): CacheStatsState {\n  return useHaloState(subscribe, cacheStatsReducer, initialCacheStats);\n}\n\n/** Cumulative turns, tokens, and estimated USD spend. */\nexport function useCost(subscribe: Subscribe): CostState {\n  return useHaloState(subscribe, costReducer, initialCost);\n}\n\n/** Current agent-loop step + status (idle/running/paused/error). */\nexport function useLoopState(subscribe: Subscribe): LoopState {\n  return useHaloState(subscribe, loopStateReducer, initialLoopState);\n}\n\n/** Pending human-in-the-loop tool approvals (for an approval UI). */\nexport function useApprovals(subscribe: Subscribe): PendingApproval[] {\n  return useHaloState(subscribe, approvalsReducer, initialApprovals);\n}\n\n/** A cacheability grade derived live from the hit rate (A–F). */\nexport function useCacheProfile(subscribe: Subscribe): CacheStatsState & {\n  grade: \"A\" | \"B\" | \"C\" | \"D\" | \"F\";\n} {\n  const stats = useCacheStats(subscribe);\n  return { ...stats, grade: gradeFor(stats.hitRate) };\n}\n\nfunction gradeFor(hitRate: number): \"A\" | \"B\" | \"C\" | \"D\" | \"F\" {\n  if (hitRate >= 0.9) return \"A\";\n  if (hitRate >= 0.75) return \"B\";\n  if (hitRate >= 0.5) return \"C\";\n  if (hitRate >= 0.25) return \"D\";\n  return \"F\";\n}\n","import type { HaloEvent, ToolCall } from \"@halo-sdk/core\";\n\n// Pure reducers over the HaloEvent stream. Framework-free and unit-testable;\n// the React hooks in `hooks.ts` are thin wrappers around these.\n\nexport interface CacheStatsState {\n  hitTokens: number;\n  missTokens: number;\n  writeTokens: number;\n  hitRate: number;\n}\n\nexport const initialCacheStats = (): CacheStatsState => ({\n  hitTokens: 0,\n  missTokens: 0,\n  writeTokens: 0,\n  hitRate: 0,\n});\n\nexport function cacheStatsReducer(state: CacheStatsState, event: HaloEvent): CacheStatsState {\n  if (event.type !== \"cache:hit\") return state;\n  const hitTokens = state.hitTokens + event.hitTokens;\n  const missTokens = state.missTokens + event.missTokens;\n  const total = hitTokens + missTokens;\n  return {\n    hitTokens,\n    missTokens,\n    writeTokens: state.writeTokens,\n    hitRate: total > 0 ? hitTokens / total : 0,\n  };\n}\n\nexport interface CostState {\n  turns: number;\n  promptTokens: number;\n  completionTokens: number;\n  estimatedUsd: number;\n}\n\nexport const initialCost = (): CostState => ({\n  turns: 0,\n  promptTokens: 0,\n  completionTokens: 0,\n  estimatedUsd: 0,\n});\n\nexport function costReducer(state: CostState, event: HaloEvent): CostState {\n  switch (event.type) {\n    case \"turn:end\":\n      return { ...state, turns: state.turns + 1 };\n    case \"cost\":\n      return {\n        ...state,\n        promptTokens: state.promptTokens + event.promptTokens,\n        completionTokens: state.completionTokens + event.completionTokens,\n        estimatedUsd: state.estimatedUsd + (event.estimatedUsd ?? 0),\n      };\n    default:\n      return state;\n  }\n}\n\nexport interface LoopState {\n  step: number;\n  status: \"idle\" | \"running\" | \"paused\" | \"error\";\n  lastError: string | null;\n}\n\nexport const initialLoopState = (): LoopState => ({ step: 0, status: \"idle\", lastError: null });\n\nexport function loopStateReducer(state: LoopState, event: HaloEvent): LoopState {\n  switch (event.type) {\n    case \"loop:step\":\n      return { ...state, step: event.step, status: \"running\" };\n    case \"loop:paused\":\n      return { ...state, status: \"paused\" };\n    case \"loop:resumed\":\n      return { ...state, status: \"running\" };\n    case \"loop:error\":\n      return { ...state, status: \"error\", lastError: event.error };\n    case \"turn:end\":\n      return state.status === \"error\" ? state : { ...state, status: \"idle\" };\n    default:\n      return state;\n  }\n}\n\nexport interface PendingApproval {\n  toolCallId: string;\n  call: ToolCall;\n}\n\nexport const initialApprovals = (): PendingApproval[] => [];\n\nexport function approvalsReducer(state: PendingApproval[], event: HaloEvent): PendingApproval[] {\n  switch (event.type) {\n    case \"hitl:pending\":\n      return [...state, { toolCallId: event.call.id, call: event.call }];\n    case \"hitl:resolved\":\n      return state.filter((a) => a.toolCallId !== event.toolCallId);\n    default:\n      return state;\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/reducers.d.ts

@@ -0,0 +1,31 @@
+import type { HaloEvent, ToolCall } from "@halo-sdk/core";
+export interface CacheStatsState {
+    hitTokens: number;
+    missTokens: number;
+    writeTokens: number;
+    hitRate: number;
+}
+export declare const initialCacheStats: () => CacheStatsState;
+export declare function cacheStatsReducer(state: CacheStatsState, event: HaloEvent): CacheStatsState;
+export interface CostState {
+    turns: number;
+    promptTokens: number;
+    completionTokens: number;
+    estimatedUsd: number;
+}
+export declare const initialCost: () => CostState;
+export declare function costReducer(state: CostState, event: HaloEvent): CostState;
+export interface LoopState {
+    step: number;
+    status: "idle" | "running" | "paused" | "error";
+    lastError: string | null;
+}
+export declare const initialLoopState: () => LoopState;
+export declare function loopStateReducer(state: LoopState, event: HaloEvent): LoopState;
+export interface PendingApproval {
+    toolCallId: string;
+    call: ToolCall;
+}
+export declare const initialApprovals: () => PendingApproval[];
+export declare function approvalsReducer(state: PendingApproval[], event: HaloEvent): PendingApproval[];
+//# sourceMappingURL=reducers.d.ts.map

package/dist/reducers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reducers.d.ts","sourceRoot":"","sources":["../src/reducers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAK1D,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,eAAO,MAAM,iBAAiB,QAAO,eAKnC,CAAC;AAEH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,KAAK,EAAE,SAAS,GAAG,eAAe,CAW3F;AAED,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,eAAO,MAAM,WAAW,QAAO,SAK7B,CAAC;AAEH,wBAAgB,WAAW,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,CAczE;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAC;IAChD,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,eAAO,MAAM,gBAAgB,QAAO,SAA2D,CAAC;AAEhG,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,SAAS,CAe9E;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,QAAQ,CAAC;CAChB;AAED,eAAO,MAAM,gBAAgB,QAAO,eAAe,EAAQ,CAAC;AAE5D,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,eAAe,EAAE,EAAE,KAAK,EAAE,SAAS,GAAG,eAAe,EAAE,CAS9F"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@halo-sdk/react",
+  "version": "1.0.0",
+  "description": "Lightweight, strongly-typed React hooks for Halo SDK — observe cache, cost, loop, and HITL state in the UI",
+  "keywords": [
+    "ai",
+    "hooks",
+    "llm",
+    "observability",
+    "prefix-cache",
+    "react"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/halo-sdk/halo-ai",
+    "directory": "packages/react"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^3.0.0",
+    "@halo-sdk/core": "1.1.0"
+  },
+  "peerDependencies": {
+    "@halo-sdk/core": ">=1.1.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "scripts": {
+    "build": "tsc --build --emitDeclarationOnly && tsup",
+    "dev": "tsup --watch",
+    "clean": "del-cli dist *.tsbuildinfo",
+    "publint": "publint",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}