@novoagents/react 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Robert Pinckney. All rights reserved.
+
+This software and associated documentation files (the "Software") are
+proprietary and confidential. No license, express or implied, is granted
+to any party to use, copy, modify, merge, publish, distribute, sublicense,
+or sell copies of the Software without the prior written permission of
+the copyright holder.
+
+Unauthorized use, reproduction, or distribution of the Software, or any
+portion of it, is strictly prohibited and may result in civil and criminal
+penalties.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF
+OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,31 @@
+# @novoagents/react
+
+Headless React hooks for rendering Novo Agents runs in the browser. The hooks
+manage state and render nothing — bring your own components. This package
+never accepts an API key: it talks to **your** server routes, which proxy to
+`api.novoagents.ai` with the server-only `novoagents` SDK. Its only runtime
+dependency is the browser-safe `novoagents/browser` entry point.
+
+## Hooks
+
+- `useNovoRun({ transport })` — consumes the run stream through your proxy
+  routes and returns live UI state: `messages`, `status`,
+  `pendingInteractions`, `usage`, and `resume()`. One component instance keeps
+  exactly one store and one stream consumption, so an inline `transport`
+  object literal is safe across re-renders; pass a new `runKey` to
+  intentionally reset. Reconnects until the `data-novo-terminal` chunk (a
+  closed connection is not a finished run), with jittered exponential backoff
+  between unproductive reconnects.
+- `useNovoInteractions({ endpoint, run })` — sources pending
+  approvals/questions from the same stream state, POSTs the batch resolution
+  shape to your proxied resolve route, and calls the run's `resume()` after a
+  successful resolution so the parked stream picks back up from the last seen
+  event id.
+
+See the full guide with proxy routes and a working component:
+[Build a React run UI](https://novoagents.ai/docs/guides/build-a-react-run-ui).
+
+## Publishing
+
+Publish with `pnpm publish` (not `npm publish`): the `workspace:*` dependency
+on `novoagents` is rewritten to the real version only by pnpm's pack step.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { createNovoRunStore, useNovoRun, type NovoRunStore, type UseNovoRunOptions, type UseNovoRunResult, } from './useNovoRun.js';
+export { resolveNovoInteractions, useNovoInteractions, type NovoInteractionResolutionItem, type NovoInteractionResolutionOutcome, type NovoInteractionRunSource, type NovoPendingInteraction, } from './useNovoInteractions.js';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { createNovoRunStore, useNovoRun, } from './useNovoRun.js';
+export { resolveNovoInteractions, useNovoInteractions, } from './useNovoInteractions.js';

package/dist/useNovoInteractions.d.ts

@@ -0,0 +1,48 @@
+import type { NovoUiPendingInteraction } from 'novoagents/browser';
+export type NovoPendingInteraction = {
+    id: string;
+    kind: 'approval_request' | 'question';
+    status: 'pending' | 'resuming';
+} & Record<string, unknown>;
+export type NovoInteractionResolutionItem = {
+    id: string;
+    inputResponses?: Array<Record<string, unknown>>;
+    cancel?: boolean;
+    reason?: string;
+};
+export type NovoInteractionResolutionOutcome = {
+    id: string;
+    status: 'resolved' | 'already_resolved' | 'conflict' | 'not_found' | 'invalid_body';
+};
+/**
+ * The slice of a `useNovoRun` result (or `NovoRunStore`-shaped object) that
+ * interactions can be sourced from: the reducer's pending queue plus the
+ * resume path invoked after a successful resolution.
+ */
+export type NovoInteractionRunSource = {
+    pendingInteractions: readonly NovoUiPendingInteraction[];
+    resume?: () => Promise<void>;
+};
+export declare function resolveNovoInteractions(input: {
+    endpoint: string;
+    items: NovoInteractionResolutionItem[];
+    fetch?: typeof globalThis.fetch;
+}): Promise<NovoInteractionResolutionOutcome[]>;
+/**
+ * Track and resolve the run's pending approvals/questions through your proxied
+ * batch resolve route. Zero-config source: pass the `useNovoRun` result as
+ * `run` and pending interactions come from the stream reducer, with the run's
+ * `resume()` invoked automatically once a resolution lands. An explicit
+ * `interactions` array (e.g. from your own discovery endpoint) overrides the
+ * run source.
+ */
+export declare function useNovoInteractions(input: {
+    endpoint: string;
+    run?: NovoInteractionRunSource;
+    interactions?: NovoPendingInteraction[];
+    fetch?: typeof globalThis.fetch;
+}): {
+    interactions: NovoPendingInteraction[];
+    resolve(items: NovoInteractionResolutionItem[]): Promise<NovoInteractionResolutionOutcome[]>;
+    error: Error | undefined;
+};

package/dist/useNovoInteractions.js

@@ -0,0 +1,68 @@
+import { useCallback, useState } from 'react';
+export async function resolveNovoInteractions(input) {
+    const request = input.fetch ?? globalThis.fetch;
+    const response = await request(input.endpoint, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ items: input.items }),
+    });
+    const body = (await response.json());
+    if (!response.ok) {
+        throw new Error(body.error?.message ?? `Interaction resolve failed (${response.status}).`);
+    }
+    return body.items ?? [];
+}
+/**
+ * Track and resolve the run's pending approvals/questions through your proxied
+ * batch resolve route. Zero-config source: pass the `useNovoRun` result as
+ * `run` and pending interactions come from the stream reducer, with the run's
+ * `resume()` invoked automatically once a resolution lands. An explicit
+ * `interactions` array (e.g. from your own discovery endpoint) overrides the
+ * run source.
+ */
+export function useNovoInteractions(input) {
+    const [resolvedIds, setResolvedIds] = useState(() => new Set());
+    const [error, setError] = useState();
+    const resume = input.run?.resume;
+    const resolve = useCallback(async (items) => {
+        try {
+            const outcomes = await resolveNovoInteractions({
+                endpoint: input.endpoint,
+                items,
+                ...(input.fetch ? { fetch: input.fetch } : {}),
+            });
+            const resolved = new Set(outcomes
+                .filter((item) => item.status === 'resolved' ||
+                item.status === 'already_resolved')
+                .map((item) => item.id));
+            if (resolved.size > 0) {
+                setResolvedIds((current) => new Set([...current, ...resolved]));
+                // The run resumed (or will resume) server-side; restart stream
+                // consumption so the resolved chunk and subsequent output arrive.
+                void resume?.();
+            }
+            setError(undefined);
+            return outcomes;
+        }
+        catch (caught) {
+            const next = caught instanceof Error
+                ? caught
+                : new Error('Interaction resolve failed.');
+            setError(next);
+            throw next;
+        }
+    }, [input.endpoint, input.fetch, resume]);
+    const sourced = input.interactions ??
+        (input.run?.pendingInteractions ?? []).map((interaction) => ({
+            ...interaction,
+            kind: interaction.request.kind,
+            status: 'pending',
+        }));
+    return {
+        // resolvedIds bridges the gap between the resolve acknowledgement and the
+        // stream's own data-novo-input-resolved chunk removing the entry.
+        interactions: sourced.filter((interaction) => !resolvedIds.has(interaction.id)),
+        resolve,
+        error,
+    };
+}

package/dist/useNovoRun.d.ts

@@ -0,0 +1,41 @@
+import { type BrowserRunTransport, type NovoAgentEvent, type NovoRunUiState } from 'novoagents/browser';
+export type NovoRunStore = {
+    subscribe(listener: () => void): () => void;
+    getSnapshot(): NovoRunUiState;
+    /**
+     * Begin consuming the run stream. Idempotent: repeat calls return the
+     * in-flight (or last) consumption instead of starting another.
+     */
+    start(): Promise<void>;
+    /**
+     * Restart consumption from the last seen event id. No-op while consumption
+     * is active or after the terminal chunk; the restart path exists because a
+     * pause (`waiting_for_approval` / `waiting_for_input`) ends consumption —
+     * call this after resolving interactions so the resumed run streams again.
+     * Also retries after a stream failure.
+     */
+    resume(): Promise<void>;
+};
+export declare function createNovoRunStore(transport: BrowserRunTransport<NovoAgentEvent> | (() => BrowserRunTransport<NovoAgentEvent>)): NovoRunStore;
+export type UseNovoRunOptions = {
+    transport: BrowserRunTransport<NovoAgentEvent>;
+    autoStart?: boolean;
+    /**
+     * Escape hatch for intentional resets: a new key discards the store and
+     * consumes the stream from scratch. The abandoned consumption is not
+     * cancelled — it stops at the run's next pause or terminal.
+     */
+    runKey?: string | number;
+};
+export type UseNovoRunResult = NovoRunUiState & {
+    /** See {@link NovoRunStore.resume}. */
+    resume(): Promise<void>;
+    store: NovoRunStore;
+};
+/**
+ * Consume a run stream through your proxy transport and expose the reduced UI
+ * state. One store (one stream consumption) per component instance: passing an
+ * inline `transport` object literal is safe across re-renders — the latest
+ * transport is read through a ref without re-creating the store.
+ */
+export declare function useNovoRun(input: UseNovoRunOptions): UseNovoRunResult;

package/dist/useNovoRun.js

@@ -0,0 +1,107 @@
+import { useEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+import { consumeRunWithReconnect, createNovoRunUiReducer, } from 'novoagents/browser';
+export function createNovoRunStore(transport) {
+    const currentTransport = typeof transport === 'function' ? transport : () => transport;
+    const reducer = createNovoRunUiReducer();
+    const listeners = new Set();
+    let state = reducer.getState();
+    let lastEventId;
+    let active;
+    let latest;
+    let reachedTerminal = false;
+    const publish = (next) => {
+        state = next;
+        for (const listener of listeners)
+            listener();
+    };
+    const consume = () => {
+        const promise = consumeRunWithReconnect({
+            // Read the transport per call so the latest closure is always used.
+            transport: {
+                connect: (fromEventId) => currentTransport().connect(fromEventId),
+                pollRun: () => currentTransport().pollRun(),
+            },
+            ...(lastEventId !== undefined ? { initialLastEventId: lastEventId } : {}),
+            isTerminalEvent: (event) => event.type === 'data-novo-terminal',
+            onFrame: ({ id, event }) => {
+                if (id !== undefined)
+                    lastEventId = id;
+                if (event)
+                    publish(reducer.reduce(event));
+            },
+            onPoll: (run) => {
+                if (run.status === 'waiting_for_approval' ||
+                    run.status === 'waiting_for_input') {
+                    publish({ ...state, status: run.status });
+                }
+            },
+        })
+            .then((result) => {
+            if (result.reachedTerminal)
+                reachedTerminal = true;
+        }, (error) => {
+            publish({
+                ...state,
+                status: 'failed',
+                error: {
+                    type: 'api_error',
+                    code: 'stream_error',
+                    message: error instanceof Error ? error.message : 'Stream failed.',
+                },
+            });
+        })
+            .then(() => {
+            if (active === promise)
+                active = undefined;
+        });
+        active = promise;
+        latest = promise;
+        return promise;
+    };
+    return {
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => listeners.delete(listener);
+        },
+        getSnapshot: () => state,
+        start() {
+            return latest ?? consume();
+        },
+        resume() {
+            if (active)
+                return active;
+            if (reachedTerminal)
+                return latest ?? Promise.resolve();
+            return consume();
+        },
+    };
+}
+/**
+ * Consume a run stream through your proxy transport and expose the reduced UI
+ * state. One store (one stream consumption) per component instance: passing an
+ * inline `transport` object literal is safe across re-renders — the latest
+ * transport is read through a ref without re-creating the store.
+ */
+export function useNovoRun(input) {
+    const transportRef = useRef(input.transport);
+    const [entry, setEntry] = useState(() => ({
+        key: input.runKey,
+        store: createNovoRunStore(() => transportRef.current),
+    }));
+    if (!Object.is(entry.key, input.runKey)) {
+        setEntry({
+            key: input.runKey,
+            store: createNovoRunStore(() => transportRef.current),
+        });
+    }
+    const store = entry.store;
+    useEffect(() => {
+        transportRef.current = input.transport;
+    });
+    useEffect(() => {
+        if (input.autoStart !== false)
+            void store.start();
+    }, [input.autoStart, store]);
+    const state = useSyncExternalStore(store.subscribe, store.getSnapshot, store.getSnapshot);
+    return useMemo(() => ({ ...state, resume: store.resume, store }), [state, store]);
+}

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@novoagents/react",
+  "version": "0.1.0-alpha.0",
+  "description": "Browser-safe React hooks for Novo Agents streams and interactions.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "novoagents": "0.3.0-alpha.51"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "devDependencies": {
+    "@types/react": "19.2.17",
+    "@types/react-dom": "19.2.3",
+    "happy-dom": "20.0.11",
+    "react": "19.2.7",
+    "react-dom": "19.2.7",
+    "typescript": "6.0.3",
+    "vite": "8.1.4",
+    "vitest": "5.0.0-beta.6"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  }
+}