@durion/react 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Durion contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+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
+AUTHORS OR COPYRIGHT HOLDERS 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,85 @@
+# @durion/react
+
+Universal React hooks for **Durion workflows** (Temporal + Gateway HTTP API).
+
+## Quick Start — `useRunStream` (recommended)
+
+A single hook that merges SSE token streaming + polled stream-state. Pass a `runId` and get back real-time text, run status, and metadata.
+
+```tsx
+import { useRunStream, useSendSignal } from '@durion/react';
+
+function ChatResponse({ runId }: { runId: string }) {
+  const { text, status, run, error } = useRunStream(runId, {
+    baseURL: '',        // same-origin or your gateway URL
+    accessToken: token, // optional
+    pollIntervalMs: 1000,
+    onToken: (delta) => console.log(delta),
+  });
+
+  const { send } = useSendSignal({ baseURL: '' });
+
+  if (error) return <div>Error: {error.message}</div>;
+  if (status === 'waiting_for_input') {
+    return <button onClick={() => send(runId, { approved: true })}>Approve</button>;
+  }
+
+  return <div>{text}</div>;
+}
+```
+
+### What `useRunStream` does internally
+
+1. Opens `EventSource` to `GET /v0/runs/:id/token-stream` → accumulates text deltas
+2. Polls `GET /v0/runs/:id/stream-state` → provides run metadata (status, step count, messages)
+3. Falls back to polled `partialReply` if SSE misses early tokens
+
+### `useSendSignal`
+
+Sends signals (e.g. HITL input) to a running workflow via `POST /v0/runs/:id/signal`.
+
+```tsx
+const { send, isSending, error } = useSendSignal({ baseURL: '', accessToken });
+await send(runId, { approved: true });
+await send(runId, 'some text', 'custom:signal-name'); // custom signal name
+```
+
+---
+
+## Low-level hooks (escape hatches)
+
+For non-gateway or custom paths:
+
+| Concern | Hook | Notes |
+|---------|------|-------|
+| Token SSE | **`useWorkflowTokenStream`** | Requires `getTokenStreamUrl(runId)`. Has `subscribeThenStart` for zero-drop. |
+| Polled UI state | **`useWorkflowStreamState`** | Requires custom `queryFn`. |
+
+---
+
+## Gateway v0 helpers
+
+URL builders and pre-wired wrappers for the standard Gateway API v0 paths:
+
+| Helper | Purpose |
+|--------|---------|
+| `useGatewayV0TokenStream` | SSE via `GET /v0/runs/:id/token-stream` |
+| `useGatewayV0StreamState` | Polls `GET /v0/runs/:id/stream-state` |
+| `gatewayV0WorkflowsStartUrl` | URL builder for `POST /v0/workflows/start` |
+| `gatewayV0SignalUrl` | URL builder for `POST /v0/runs/:id/signal` |
+| `gatewayV0ResultUrl` | URL builder for `GET /v0/runs/:id/result` |
+| `createGatewayV0StreamStateQueryFn` | Factory for poll `queryFn` |
+
+> **Note:** These are now considered low-level. Prefer `useRunStream` for new code.
+
+---
+
+## Run-scoped streaming
+
+`useRunStream` takes a `runId`, optional `baseURL`, and optional gateway token — the same shape you’d use for any client that opens an SSE URL and polls run metadata against **your** HTTP API (e.g. Gateway API v0), not a vendor-hosted endpoint.
+
+---
+
+## Peer dependency
+
+- `react` ^18 or ^19

package/dist/gateway-v0/stream-state-query-fn.d.ts

@@ -0,0 +1,9 @@
+import type { StreamState } from '@durion/sdk';
+export interface GatewayV0StreamStateQueryFnOptions {
+    accessToken?: string;
+    headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+}
+/**
+ * Default `queryFn` for {@link useGatewayV0StreamState}: `GET /v0/runs/:id/stream-state`.
+ */
+export declare function createGatewayV0StreamStateQueryFn(baseURL: string, options?: GatewayV0StreamStateQueryFnOptions): (workflowId: string, signal: AbortSignal) => Promise<StreamState>;

package/dist/gateway-v0/stream-state-query-fn.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createGatewayV0StreamStateQueryFn = createGatewayV0StreamStateQueryFn;
+const urls_1 = require("./urls");
+async function resolveHeaders(h) {
+    if (h == null)
+        return undefined;
+    return typeof h === 'function' ? await h() : h;
+}
+/**
+ * Default `queryFn` for {@link useGatewayV0StreamState}: `GET /v0/runs/:id/stream-state`.
+ */
+function createGatewayV0StreamStateQueryFn(baseURL, options) {
+    return async (workflowId, signal) => {
+        const url = (0, urls_1.gatewayV0StreamStateUrl)(baseURL, workflowId);
+        const extra = await resolveHeaders(options?.headers);
+        const headers = new Headers(extra);
+        if (options?.accessToken != null && options.accessToken !== '') {
+            headers.set('Authorization', `Bearer ${options.accessToken}`);
+        }
+        const res = await fetch(url, { signal, headers });
+        if (!res.ok) {
+            const text = await res.text().catch(() => '');
+            throw new Error(`Stream state failed (${res.status}): ${text || res.statusText}`);
+        }
+        return (await res.json());
+    };
+}

package/dist/gateway-v0/urls.d.ts

@@ -0,0 +1,11 @@
+/** Join `baseURL` (no trailing slash) with an absolute path. */
+export declare function trimGatewayBase(url: string): string;
+export declare function gatewayV0StreamStateUrl(baseURL: string, runId: string): string;
+export declare function gatewayV0TokenStreamUrl(baseURL: string, runId: string, options?: {
+    accessToken?: string;
+}): string;
+export declare function gatewayV0SignalUrl(baseURL: string, runId: string): string;
+export declare function gatewayV0ResultUrl(baseURL: string, runId: string): string;
+export declare function gatewayV0RunDescribeUrl(baseURL: string, runId: string): string;
+export declare function gatewayV0WorkflowsStartUrl(baseURL: string): string;
+export declare function gatewayV0AgentsStartUrl(baseURL: string): string;

package/dist/gateway-v0/urls.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.trimGatewayBase = trimGatewayBase;
+exports.gatewayV0StreamStateUrl = gatewayV0StreamStateUrl;
+exports.gatewayV0TokenStreamUrl = gatewayV0TokenStreamUrl;
+exports.gatewayV0SignalUrl = gatewayV0SignalUrl;
+exports.gatewayV0ResultUrl = gatewayV0ResultUrl;
+exports.gatewayV0RunDescribeUrl = gatewayV0RunDescribeUrl;
+exports.gatewayV0WorkflowsStartUrl = gatewayV0WorkflowsStartUrl;
+exports.gatewayV0AgentsStartUrl = gatewayV0AgentsStartUrl;
+/** Join `baseURL` (no trailing slash) with an absolute path. */
+function trimGatewayBase(url) {
+    return url.replace(/\/$/, '');
+}
+function joinBasePath(baseURL, path) {
+    const base = trimGatewayBase(baseURL);
+    return base.length > 0 ? `${base}${path}` : path;
+}
+const RUNS = '/v0/runs';
+const WORKFLOWS = '/v0/workflows';
+function gatewayV0StreamStateUrl(baseURL, runId) {
+    return joinBasePath(baseURL, `${RUNS}/${encodeURIComponent(runId)}/stream-state`);
+}
+function gatewayV0TokenStreamUrl(baseURL, runId, options) {
+    const u = joinBasePath(baseURL, `${RUNS}/${encodeURIComponent(runId)}/token-stream`);
+    const token = options?.accessToken;
+    if (token == null || token === '')
+        return u;
+    const sep = u.includes('?') ? '&' : '?';
+    return `${u}${sep}access_token=${encodeURIComponent(token)}`;
+}
+function gatewayV0SignalUrl(baseURL, runId) {
+    return joinBasePath(baseURL, `${RUNS}/${encodeURIComponent(runId)}/signal`);
+}
+function gatewayV0ResultUrl(baseURL, runId) {
+    return joinBasePath(baseURL, `${RUNS}/${encodeURIComponent(runId)}/result`);
+}
+function gatewayV0RunDescribeUrl(baseURL, runId) {
+    return joinBasePath(baseURL, `${RUNS}/${encodeURIComponent(runId)}`);
+}
+function gatewayV0WorkflowsStartUrl(baseURL) {
+    return joinBasePath(baseURL, `${WORKFLOWS}/start`);
+}
+function gatewayV0AgentsStartUrl(baseURL) {
+    return joinBasePath(baseURL, '/v0/agents/start');
+}

package/dist/gateway-v0/useGatewayV0StreamState.d.ts

@@ -0,0 +1,24 @@
+import type { StreamState } from '@durion/sdk';
+export interface UseGatewayV0StreamStateOptions {
+    workflowId?: string | null;
+    /** API origin, no trailing slash. Use `''` for same-origin. */
+    baseURL: string;
+    pollIntervalMs?: number;
+    enabled?: boolean;
+    /** Sent as `Authorization: Bearer` on poll requests. */
+    accessToken?: string;
+    extraHeaders?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+    /**
+     * Replace the default Gateway v0 poll entirely (escape hatch).
+     * When set, `baseURL` / `accessToken` / `extraHeaders` are ignored for fetching.
+     */
+    queryFn?: (workflowId: string, signal: AbortSignal) => Promise<StreamState>;
+}
+/**
+ * Polls `GET /v0/runs/:id/stream-state` (Gateway API v0). See `docs/gateway-api-v0.md` in the repo.
+ */
+export declare function useGatewayV0StreamState(options: UseGatewayV0StreamStateOptions): {
+    state: StreamState | null;
+    error: Error | null;
+    loading: boolean;
+};

package/dist/gateway-v0/useGatewayV0StreamState.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useGatewayV0StreamState = useGatewayV0StreamState;
+const react_1 = require("react");
+const useWorkflowStreamState_1 = require("../useWorkflowStreamState");
+const stream_state_query_fn_1 = require("./stream-state-query-fn");
+/**
+ * Polls `GET /v0/runs/:id/stream-state` (Gateway API v0). See `docs/gateway-api-v0.md` in the repo.
+ */
+function useGatewayV0StreamState(options) {
+    const { baseURL, accessToken, extraHeaders, queryFn: userQueryFn, workflowId, pollIntervalMs, enabled, } = options;
+    const queryFn = (0, react_1.useMemo)(() => {
+        if (userQueryFn)
+            return userQueryFn;
+        return (0, stream_state_query_fn_1.createGatewayV0StreamStateQueryFn)(baseURL, {
+            accessToken,
+            headers: extraHeaders,
+        });
+    }, [userQueryFn, baseURL, accessToken, extraHeaders]);
+    return (0, useWorkflowStreamState_1.useWorkflowStreamState)({
+        workflowId,
+        pollIntervalMs,
+        enabled,
+        queryFn,
+    });
+}

package/dist/gateway-v0/useGatewayV0TokenStream.d.ts

@@ -0,0 +1,16 @@
+export interface UseGatewayV0TokenStreamOptions {
+    /** API origin, no trailing slash. Use `''` for same-origin (e.g. Vite proxy). */
+    baseURL: string;
+    /** When set, appended as `access_token` query (SSE; browsers cannot set Authorization on EventSource). */
+    accessToken?: string;
+}
+/** Token SSE for Gateway API v0 (`GET /v0/runs/:id/token-stream`). Thin wrapper over {@link useWorkflowTokenStream}. */
+export declare function useGatewayV0TokenStream(options: UseGatewayV0TokenStreamOptions): {
+    text: string;
+    status: import("../useWorkflowTokenStream").WorkflowTokenStreamStatus;
+    error: Error | null;
+    isStreaming: boolean;
+    subscribeThenStart: (workflowId: string, afterConnected: () => void | Promise<void>) => void;
+    reset: () => void;
+    close: () => void;
+};

package/dist/gateway-v0/useGatewayV0TokenStream.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useGatewayV0TokenStream = useGatewayV0TokenStream;
+const useWorkflowTokenStream_1 = require("../useWorkflowTokenStream");
+const urls_1 = require("./urls");
+/** Token SSE for Gateway API v0 (`GET /v0/runs/:id/token-stream`). Thin wrapper over {@link useWorkflowTokenStream}. */
+function useGatewayV0TokenStream(options) {
+    const { baseURL, accessToken } = options;
+    return (0, useWorkflowTokenStream_1.useWorkflowTokenStream)({
+        getTokenStreamUrl: (runId) => (0, urls_1.gatewayV0TokenStreamUrl)(baseURL, runId, { accessToken }),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export { useRunStream } from './useRunStream';
+export type { UseRunStreamOptions, UseRunStreamReturn, RunStreamStatus, } from './useRunStream';
+export { useSendSignal } from './useSendSignal';
+export type { UseSendSignalOptions, UseSendSignalReturn, } from './useSendSignal';
+export { useWorkflowStreamState } from './useWorkflowStreamState';
+export type { UseWorkflowStreamStateOptions } from './useWorkflowStreamState';
+export { useWorkflowTokenStream } from './useWorkflowTokenStream';
+export type { UseWorkflowTokenStreamOptions, WorkflowTokenStreamStatus, } from './useWorkflowTokenStream';
+export { trimGatewayBase, gatewayV0StreamStateUrl, gatewayV0TokenStreamUrl, gatewayV0SignalUrl, gatewayV0ResultUrl, gatewayV0RunDescribeUrl, gatewayV0WorkflowsStartUrl, gatewayV0AgentsStartUrl, } from './gateway-v0/urls';
+export { createGatewayV0StreamStateQueryFn } from './gateway-v0/stream-state-query-fn';
+export type { GatewayV0StreamStateQueryFnOptions } from './gateway-v0/stream-state-query-fn';
+export { useGatewayV0TokenStream } from './gateway-v0/useGatewayV0TokenStream';
+export type { UseGatewayV0TokenStreamOptions } from './gateway-v0/useGatewayV0TokenStream';
+export { useGatewayV0StreamState } from './gateway-v0/useGatewayV0StreamState';
+export type { UseGatewayV0StreamStateOptions } from './gateway-v0/useGatewayV0StreamState';

package/dist/index.js

@@ -0,0 +1,32 @@
+"use strict";
+// ---------------------------------------------------------------------------
+// Recommended API — unified hooks
+// ---------------------------------------------------------------------------
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useGatewayV0StreamState = exports.useGatewayV0TokenStream = exports.createGatewayV0StreamStateQueryFn = exports.gatewayV0AgentsStartUrl = exports.gatewayV0WorkflowsStartUrl = exports.gatewayV0RunDescribeUrl = exports.gatewayV0ResultUrl = exports.gatewayV0SignalUrl = exports.gatewayV0TokenStreamUrl = exports.gatewayV0StreamStateUrl = exports.trimGatewayBase = exports.useWorkflowTokenStream = exports.useWorkflowStreamState = exports.useSendSignal = exports.useRunStream = void 0;
+var useRunStream_1 = require("./useRunStream");
+Object.defineProperty(exports, "useRunStream", { enumerable: true, get: function () { return useRunStream_1.useRunStream; } });
+var useSendSignal_1 = require("./useSendSignal");
+Object.defineProperty(exports, "useSendSignal", { enumerable: true, get: function () { return useSendSignal_1.useSendSignal; } });
+// ---------------------------------------------------------------------------
+// Low-level hooks (escape hatches)
+// ---------------------------------------------------------------------------
+var useWorkflowStreamState_1 = require("./useWorkflowStreamState");
+Object.defineProperty(exports, "useWorkflowStreamState", { enumerable: true, get: function () { return useWorkflowStreamState_1.useWorkflowStreamState; } });
+var useWorkflowTokenStream_1 = require("./useWorkflowTokenStream");
+Object.defineProperty(exports, "useWorkflowTokenStream", { enumerable: true, get: function () { return useWorkflowTokenStream_1.useWorkflowTokenStream; } });
+var urls_1 = require("./gateway-v0/urls");
+Object.defineProperty(exports, "trimGatewayBase", { enumerable: true, get: function () { return urls_1.trimGatewayBase; } });
+Object.defineProperty(exports, "gatewayV0StreamStateUrl", { enumerable: true, get: function () { return urls_1.gatewayV0StreamStateUrl; } });
+Object.defineProperty(exports, "gatewayV0TokenStreamUrl", { enumerable: true, get: function () { return urls_1.gatewayV0TokenStreamUrl; } });
+Object.defineProperty(exports, "gatewayV0SignalUrl", { enumerable: true, get: function () { return urls_1.gatewayV0SignalUrl; } });
+Object.defineProperty(exports, "gatewayV0ResultUrl", { enumerable: true, get: function () { return urls_1.gatewayV0ResultUrl; } });
+Object.defineProperty(exports, "gatewayV0RunDescribeUrl", { enumerable: true, get: function () { return urls_1.gatewayV0RunDescribeUrl; } });
+Object.defineProperty(exports, "gatewayV0WorkflowsStartUrl", { enumerable: true, get: function () { return urls_1.gatewayV0WorkflowsStartUrl; } });
+Object.defineProperty(exports, "gatewayV0AgentsStartUrl", { enumerable: true, get: function () { return urls_1.gatewayV0AgentsStartUrl; } });
+var stream_state_query_fn_1 = require("./gateway-v0/stream-state-query-fn");
+Object.defineProperty(exports, "createGatewayV0StreamStateQueryFn", { enumerable: true, get: function () { return stream_state_query_fn_1.createGatewayV0StreamStateQueryFn; } });
+var useGatewayV0TokenStream_1 = require("./gateway-v0/useGatewayV0TokenStream");
+Object.defineProperty(exports, "useGatewayV0TokenStream", { enumerable: true, get: function () { return useGatewayV0TokenStream_1.useGatewayV0TokenStream; } });
+var useGatewayV0StreamState_1 = require("./gateway-v0/useGatewayV0StreamState");
+Object.defineProperty(exports, "useGatewayV0StreamState", { enumerable: true, get: function () { return useGatewayV0StreamState_1.useGatewayV0StreamState; } });

package/dist/useRunStream.d.ts

@@ -0,0 +1,50 @@
+import type { StreamState } from '@durion/sdk';
+export type RunStreamStatus = 'idle' | 'connecting' | 'streaming' | 'waiting_for_input' | 'completed' | 'error';
+export interface UseRunStreamOptions {
+    /** API origin, no trailing slash. Use `''` for same-origin (e.g. Vite proxy). */
+    baseURL: string;
+    /**
+     * Optional auth token.
+     * - SSE: appended as `access_token` query param (EventSource cannot set headers).
+     * - Poll: sent as `Authorization: Bearer`.
+     */
+    accessToken?: string;
+    /** Polling interval for stream-state in ms. Default 1500. */
+    pollIntervalMs?: number;
+    /** Throttle SSE renders in ms. Default 0 (every frame). */
+    throttleInMs?: number;
+    /** Called for every text-delta token from SSE. */
+    onToken?: (delta: string) => void;
+    /** Called when the run status changes. */
+    onStatusChange?: (status: RunStreamStatus) => void;
+    /** When false, disables both SSE and polling. Default true when runId is set. */
+    enabled?: boolean;
+}
+export interface UseRunStreamReturn {
+    /** Accumulated LLM text (SSE deltas preferred, polled partialReply as fallback). */
+    text: string;
+    /** High-level run status. */
+    status: RunStreamStatus;
+    /** Full StreamState from polling (messages, currentStep, etc). */
+    run: StreamState | null;
+    /** Latest error, if any. */
+    error: Error | null;
+    /** True while SSE is open or connecting. */
+    isStreaming: boolean;
+    /** Manually close the SSE stream. */
+    close: () => void;
+    /** Reset all state (for reuse with a new run). */
+    reset: () => void;
+}
+/**
+ * Unified hook that combines SSE token streaming with polled stream-state.
+ *
+ * Internally opens an `EventSource` to `/v0/runs/:id/token-stream` for real-time
+ * text deltas **and** polls `/v0/runs/:id/stream-state` for run metadata (status,
+ * currentStep, messages, HITL flags). The `text` return merges both: SSE deltas are
+ * preferred, with the polled `partialReply` used as a fallback for tokens that the
+ * SSE connection missed.
+ *
+ * Same mental model as other run-scoped stream hooks: `runId`, optional `baseURL`, token for auth.
+ */
+export declare function useRunStream(runId: string | null | undefined, options: UseRunStreamOptions): UseRunStreamReturn;

package/dist/useRunStream.js

@@ -0,0 +1,210 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useRunStream = useRunStream;
+const react_1 = require("react");
+const urls_1 = require("./gateway-v0/urls");
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+/**
+ * Unified hook that combines SSE token streaming with polled stream-state.
+ *
+ * Internally opens an `EventSource` to `/v0/runs/:id/token-stream` for real-time
+ * text deltas **and** polls `/v0/runs/:id/stream-state` for run metadata (status,
+ * currentStep, messages, HITL flags). The `text` return merges both: SSE deltas are
+ * preferred, with the polled `partialReply` used as a fallback for tokens that the
+ * SSE connection missed.
+ *
+ * Same mental model as other run-scoped stream hooks: `runId`, optional `baseURL`, token for auth.
+ */
+function useRunStream(runId, options) {
+    const { baseURL, accessToken, pollIntervalMs = 1500, throttleInMs = 0, onToken, onStatusChange, enabled: enabledOpt, } = options;
+    const active = enabledOpt !== false && runId != null && String(runId).length > 0;
+    // ---- State ---------------------------------------------------------------
+    const [sseText, setSseText] = (0, react_1.useState)('');
+    const [status, setStatusRaw] = (0, react_1.useState)('idle');
+    const [run, setRun] = (0, react_1.useState)(null);
+    const [error, setError] = (0, react_1.useState)(null);
+    // Stable refs for callbacks (avoid re-subscribing on every render)
+    const onTokenRef = (0, react_1.useRef)(onToken);
+    onTokenRef.current = onToken;
+    const onStatusChangeRef = (0, react_1.useRef)(onStatusChange);
+    onStatusChangeRef.current = onStatusChange;
+    // Whether SSE has received at least one delta (used for fallback logic)
+    const sseReceivedRef = (0, react_1.useRef)(false);
+    // Throttle support
+    const throttlePendingRef = (0, react_1.useRef)('');
+    const throttleTimerRef = (0, react_1.useRef)(null);
+    const setStatus = (0, react_1.useCallback)((s) => {
+        setStatusRaw((prev) => {
+            if (prev === s)
+                return prev;
+            onStatusChangeRef.current?.(s);
+            return s;
+        });
+    }, []);
+    // ---- SSE EventSource -----------------------------------------------------
+    const esRef = (0, react_1.useRef)(null);
+    const sseClosedCleanlyRef = (0, react_1.useRef)(false);
+    const closeSSE = (0, react_1.useCallback)(() => {
+        if (throttleTimerRef.current) {
+            clearTimeout(throttleTimerRef.current);
+            throttleTimerRef.current = null;
+        }
+        // Flush any remaining throttled text
+        if (throttlePendingRef.current) {
+            const pending = throttlePendingRef.current;
+            throttlePendingRef.current = '';
+            setSseText((t) => t + pending);
+        }
+        esRef.current?.close();
+        esRef.current = null;
+    }, []);
+    // ---- Public API ----------------------------------------------------------
+    const close = (0, react_1.useCallback)(() => {
+        closeSSE();
+    }, [closeSSE]);
+    const reset = (0, react_1.useCallback)(() => {
+        closeSSE();
+        sseClosedCleanlyRef.current = false;
+        sseReceivedRef.current = false;
+        throttlePendingRef.current = '';
+        setSseText('');
+        setRun(null);
+        setError(null);
+        setStatus('idle');
+    }, [closeSSE, setStatus]);
+    // ---- SSE lifecycle -------------------------------------------------------
+    (0, react_1.useEffect)(() => {
+        if (!active || !runId)
+            return;
+        sseClosedCleanlyRef.current = false;
+        sseReceivedRef.current = false;
+        throttlePendingRef.current = '';
+        setSseText('');
+        setError(null);
+        setStatus('connecting');
+        const url = (0, urls_1.gatewayV0TokenStreamUrl)(baseURL, runId, { accessToken });
+        const es = new EventSource(url);
+        esRef.current = es;
+        const flushThrottle = () => {
+            if (throttlePendingRef.current) {
+                const pending = throttlePendingRef.current;
+                throttlePendingRef.current = '';
+                setSseText((t) => t + pending);
+            }
+            throttleTimerRef.current = null;
+        };
+        es.addEventListener('open', () => {
+            setStatus('streaming');
+        });
+        es.addEventListener('message', (ev) => {
+            try {
+                const part = JSON.parse(ev.data);
+                if (part.type === 'text-delta' && part.delta) {
+                    sseReceivedRef.current = true;
+                    onTokenRef.current?.(part.delta);
+                    if (throttleInMs > 0) {
+                        throttlePendingRef.current += part.delta;
+                        if (!throttleTimerRef.current) {
+                            throttleTimerRef.current = setTimeout(flushThrottle, throttleInMs);
+                        }
+                    }
+                    else {
+                        setSseText((t) => t + part.delta);
+                    }
+                }
+                if (part.type === 'finish') {
+                    sseClosedCleanlyRef.current = true;
+                    flushThrottle();
+                    setStatus('completed');
+                    closeSSE();
+                }
+                if (part.type === 'error') {
+                    setError(new Error(part.error ?? 'Stream error'));
+                    setStatus('error');
+                    closeSSE();
+                }
+            }
+            catch {
+                /* ignore malformed SSE */
+            }
+        });
+        es.addEventListener('error', () => {
+            if (sseClosedCleanlyRef.current) {
+                closeSSE();
+                return;
+            }
+            closeSSE();
+            // Don't set error status if we never got streaming data — polling will handle it
+            if (sseReceivedRef.current) {
+                setStatus('error');
+                setError((prev) => prev ?? new Error('EventSource error'));
+            }
+        });
+        return () => {
+            closeSSE();
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [active, runId, baseURL, accessToken]);
+    // ---- Poll stream-state ---------------------------------------------------
+    (0, react_1.useEffect)(() => {
+        if (!active || !runId) {
+            setRun(null);
+            return;
+        }
+        const ac = new AbortController();
+        let timer;
+        const tick = async () => {
+            try {
+                const url = (0, urls_1.gatewayV0StreamStateUrl)(baseURL, runId);
+                const headers = new Headers();
+                if (accessToken) {
+                    headers.set('Authorization', `Bearer ${accessToken}`);
+                }
+                const res = await fetch(url, { signal: ac.signal, headers });
+                if (!res.ok)
+                    return; // silent — SSE or next poll will recover
+                const state = (await res.json());
+                if (ac.signal.aborted)
+                    return;
+                setRun(state);
+                // Sync status from polled state when SSE hasn't reported
+                if (state.status === 'waiting_for_input') {
+                    setStatus('waiting_for_input');
+                }
+                else if (state.status === 'completed') {
+                    setStatus('completed');
+                }
+                else if (state.status === 'error') {
+                    setStatus('error');
+                }
+                // Stop polling once terminal
+                if (state.status === 'completed' || state.status === 'error') {
+                    if (timer)
+                        clearInterval(timer);
+                }
+            }
+            catch (e) {
+                if (e.name === 'AbortError')
+                    return;
+                // Non-fatal — SSE is primary; poll failures are silent
+            }
+        };
+        void tick();
+        timer = setInterval(() => void tick(), pollIntervalMs);
+        return () => {
+            ac.abort();
+            if (timer)
+                clearInterval(timer);
+        };
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [active, runId, baseURL, accessToken, pollIntervalMs]);
+    // ---- Compute final text --------------------------------------------------
+    // SSE text takes priority; fall back to polled partialReply when SSE hasn't received data
+    const text = sseReceivedRef.current || sseText.length > 0
+        ? sseText
+        : run?.partialReply ?? '';
+    const isStreaming = status === 'streaming' || status === 'connecting';
+    return { text, status, run, error, isStreaming, close, reset };
+}

package/dist/useSendSignal.d.ts

@@ -0,0 +1,25 @@
+export interface UseSendSignalOptions {
+    /** API origin, no trailing slash. Use `''` for same-origin. */
+    baseURL: string;
+    /** Sent as `Authorization: Bearer` on signal requests. */
+    accessToken?: string;
+}
+export interface UseSendSignalReturn {
+    /** Send a signal to a running workflow. Default signal name is `durion:user-input`. */
+    send: (runId: string, data: unknown, signalName?: string) => Promise<void>;
+    /** True while the signal POST is in flight. */
+    isSending: boolean;
+    /** Last error from a failed send, if any. */
+    error: Error | null;
+}
+/**
+ * Simple hook for sending signals (e.g. HITL input) to a running workflow.
+ *
+ * Wraps `POST /v0/runs/:id/signal` with loading/error state.
+ *
+ * ```tsx
+ * const { send, isSending, error } = useSendSignal({ baseURL: '' });
+ * await send(runId, { approved: true });
+ * ```
+ */
+export declare function useSendSignal(options: UseSendSignalOptions): UseSendSignalReturn;

package/dist/useSendSignal.js

@@ -0,0 +1,57 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useSendSignal = useSendSignal;
+const react_1 = require("react");
+const urls_1 = require("./gateway-v0/urls");
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+/**
+ * Simple hook for sending signals (e.g. HITL input) to a running workflow.
+ *
+ * Wraps `POST /v0/runs/:id/signal` with loading/error state.
+ *
+ * ```tsx
+ * const { send, isSending, error } = useSendSignal({ baseURL: '' });
+ * await send(runId, { approved: true });
+ * ```
+ */
+function useSendSignal(options) {
+    const { baseURL, accessToken } = options;
+    const [isSending, setIsSending] = (0, react_1.useState)(false);
+    const [error, setError] = (0, react_1.useState)(null);
+    // Stable refs to avoid stale closures
+    const baseURLRef = (0, react_1.useRef)(baseURL);
+    baseURLRef.current = baseURL;
+    const accessTokenRef = (0, react_1.useRef)(accessToken);
+    accessTokenRef.current = accessToken;
+    const send = (0, react_1.useCallback)(async (runId, data, signalName = 'durion:user-input') => {
+        setIsSending(true);
+        setError(null);
+        try {
+            const url = (0, urls_1.gatewayV0SignalUrl)(baseURLRef.current, runId);
+            const headers = { 'Content-Type': 'application/json' };
+            if (accessTokenRef.current) {
+                headers['Authorization'] = `Bearer ${accessTokenRef.current}`;
+            }
+            const res = await fetch(url, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ name: signalName, data }),
+            });
+            if (!res.ok) {
+                const body = await res.text().catch(() => '');
+                throw new Error(`Signal failed (${res.status}): ${body || res.statusText}`);
+            }
+        }
+        catch (e) {
+            const err = e instanceof Error ? e : new Error(String(e));
+            setError(err);
+            throw err;
+        }
+        finally {
+            setIsSending(false);
+        }
+    }, []);
+    return { send, isSending, error };
+}

package/dist/useWorkflowStreamState.d.ts

@@ -0,0 +1,25 @@
+import type { StreamState } from '@durion/sdk';
+export interface UseWorkflowStreamStateOptions {
+    /** Workflow execution id (Temporal workflow id). */
+    workflowId?: string | null;
+    /** Polling interval in ms. Default 1500. */
+    pollIntervalMs?: number;
+    /**
+     * Poll your backend for `StreamState` JSON (e.g. Temporal `streamState` query behind HTTP).
+     * Not streaming — interval polling only. Implement with `fetch` to **your** route(s).
+     */
+    queryFn: (workflowId: string, signal: AbortSignal) => Promise<StreamState>;
+    /** When false, no polling. Default true when workflowId is set. */
+    enabled?: boolean;
+}
+/**
+ * Polls JSON workflow UI state (status, partial reply, HITL flags, …) via **`queryFn`** — not SSE.
+ *
+ * `loading` is **only** true until the first successful fetch for the current `workflowId`
+ * (background interval polls do not flip it — avoids UI flicker).
+ */
+export declare function useWorkflowStreamState(options: UseWorkflowStreamStateOptions): {
+    state: StreamState | null;
+    error: Error | null;
+    loading: boolean;
+};

package/dist/useWorkflowStreamState.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWorkflowStreamState = useWorkflowStreamState;
+const react_1 = require("react");
+/**
+ * Polls JSON workflow UI state (status, partial reply, HITL flags, …) via **`queryFn`** — not SSE.
+ *
+ * `loading` is **only** true until the first successful fetch for the current `workflowId`
+ * (background interval polls do not flip it — avoids UI flicker).
+ */
+function useWorkflowStreamState(options) {
+    const { workflowId, pollIntervalMs = 1500, queryFn: userQueryFn, enabled: enabledOpt, } = options;
+    const enabled = enabledOpt !== false && workflowId != null && String(workflowId).length > 0;
+    const [state, setState] = (0, react_1.useState)(null);
+    const [error, setError] = (0, react_1.useState)(null);
+    const [loading, setLoading] = (0, react_1.useState)(false);
+    const queryFnRef = (0, react_1.useRef)(userQueryFn);
+    queryFnRef.current = userQueryFn;
+    /** After first successful poll for this workflowId, background ticks keep loading false. */
+    const hasDataRef = (0, react_1.useRef)(false);
+    (0, react_1.useEffect)(() => {
+        if (!workflowId) {
+            hasDataRef.current = false;
+            setState(null);
+            setError(null);
+            setLoading(false);
+            return;
+        }
+        if (!enabled) {
+            setLoading(false);
+            setError(null);
+            setState(null);
+            return;
+        }
+        hasDataRef.current = false;
+        setState(null);
+        setError(null);
+        const ac = new AbortController();
+        let timer;
+        const tick = async () => {
+            try {
+                if (!hasDataRef.current) {
+                    setLoading(true);
+                }
+                setError(null);
+                const next = await queryFnRef.current(workflowId, ac.signal);
+                if (!ac.signal.aborted) {
+                    setState(next);
+                    hasDataRef.current = true;
+                }
+            }
+            catch (e) {
+                if (e.name === 'AbortError')
+                    return;
+                if (!ac.signal.aborted)
+                    setError(e instanceof Error ? e : new Error(String(e)));
+            }
+            finally {
+                if (!ac.signal.aborted)
+                    setLoading(false);
+            }
+        };
+        void tick();
+        timer = setInterval(() => void tick(), pollIntervalMs);
+        return () => {
+            ac.abort();
+            if (timer)
+                clearInterval(timer);
+        };
+    }, [enabled, workflowId, pollIntervalMs]);
+    return { state, error, loading };
+}

package/dist/useWorkflowTokenStream.d.ts

@@ -0,0 +1,31 @@
+export type WorkflowTokenStreamStatus = 'idle' | 'connecting' | 'streaming' | 'done' | 'error';
+export interface UseWorkflowTokenStreamOptions {
+    /**
+     * Resolves the **full URL** of the token SSE endpoint for a workflow run (your server’s contract).
+     * You own host, path, and auth — pass the final string the browser’s `EventSource` should open.
+     */
+    getTokenStreamUrl: (workflowId: string) => string;
+}
+/**
+ * Subscribes to LLM token deltas over SSE at **`getTokenStreamUrl(workflowId)`** (your server).
+ * Expects Vercel AI UI–style `text-delta` / `finish` messages; accumulates deltas into `text`.
+ *
+ * **Subscribe-before-start:** use {@link subscribeThenStart} so the EventSource is open *before* you
+ * start the workflow (or next model round), so early chunks aren’t missed — same “connect, then run”
+ * ordering you’d use with any ephemeral SSE channel.
+ */
+export declare function useWorkflowTokenStream(options: UseWorkflowTokenStreamOptions): {
+    /** Accumulated text from `text-delta` parts. */
+    text: string;
+    status: WorkflowTokenStreamStatus;
+    error: Error | null;
+    /** True while waiting for open or actively receiving deltas (until `done` / `error`). */
+    isStreaming: boolean;
+    /**
+     * Open SSE for `workflowId`, then run `afterConnected` (e.g. start workflow).
+     * Call again for each new model round (e.g. after HITL reject).
+     */
+    subscribeThenStart: (workflowId: string, afterConnected: () => void | Promise<void>) => void;
+    reset: () => void;
+    close: () => void;
+};

package/dist/useWorkflowTokenStream.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useWorkflowTokenStream = useWorkflowTokenStream;
+const react_1 = require("react");
+/**
+ * Subscribes to LLM token deltas over SSE at **`getTokenStreamUrl(workflowId)`** (your server).
+ * Expects Vercel AI UI–style `text-delta` / `finish` messages; accumulates deltas into `text`.
+ *
+ * **Subscribe-before-start:** use {@link subscribeThenStart} so the EventSource is open *before* you
+ * start the workflow (or next model round), so early chunks aren’t missed — same “connect, then run”
+ * ordering you’d use with any ephemeral SSE channel.
+ */
+function useWorkflowTokenStream(options) {
+    const { getTokenStreamUrl } = options;
+    const [text, setText] = (0, react_1.useState)('');
+    const [status, setStatus] = (0, react_1.useState)('idle');
+    const [error, setError] = (0, react_1.useState)(null);
+    const esRef = (0, react_1.useRef)(null);
+    const closedCleanlyRef = (0, react_1.useRef)(false);
+    const close = (0, react_1.useCallback)(() => {
+        esRef.current?.close();
+        esRef.current = null;
+    }, []);
+    const reset = (0, react_1.useCallback)(() => {
+        close();
+        closedCleanlyRef.current = false;
+        setText('');
+        setStatus('idle');
+        setError(null);
+    }, [close]);
+    (0, react_1.useEffect)(() => () => close(), [close]);
+    const getTokenStreamUrlRef = (0, react_1.useRef)(getTokenStreamUrl);
+    getTokenStreamUrlRef.current = getTokenStreamUrl;
+    const subscribeThenStart = (0, react_1.useCallback)((workflowId, afterConnected) => {
+        close();
+        closedCleanlyRef.current = false;
+        setText('');
+        setError(null);
+        setStatus('connecting');
+        const url = getTokenStreamUrlRef.current(workflowId);
+        const es = new EventSource(url);
+        esRef.current = es;
+        es.addEventListener('open', () => {
+            void (async () => {
+                try {
+                    await afterConnected();
+                    setStatus('streaming');
+                }
+                catch (e) {
+                    const err = e instanceof Error ? e : new Error(String(e));
+                    setError(err);
+                    setStatus('error');
+                    close();
+                }
+            })();
+        });
+        es.addEventListener('message', (ev) => {
+            try {
+                const part = JSON.parse(ev.data);
+                if (part.type === 'text-delta' && part.delta) {
+                    setText((t) => t + part.delta);
+                }
+                if (part.type === 'finish') {
+                    closedCleanlyRef.current = true;
+                    setStatus('done');
+                    close();
+                }
+                if (part.type === 'error') {
+                    setError(new Error(part.error ?? 'Stream error'));
+                    setStatus('error');
+                    close();
+                }
+            }
+            catch {
+                /* ignore malformed SSE */
+            }
+        });
+        es.addEventListener('error', () => {
+            if (closedCleanlyRef.current) {
+                close();
+                return;
+            }
+            close();
+            setStatus('error');
+            setError((prev) => prev ?? new Error('EventSource error'));
+        });
+    }, [close]);
+    const isStreaming = status === 'streaming' || status === 'connecting';
+    return {
+        /** Accumulated text from `text-delta` parts. */
+        text,
+        status,
+        error,
+        /** True while waiting for open or actively receiving deltas (until `done` / `error`). */
+        isStreaming,
+        /**
+         * Open SSE for `workflowId`, then run `afterConnected` (e.g. start workflow).
+         * Call again for each new model round (e.g. after HITL reject).
+         */
+        subscribeThenStart,
+        reset,
+        close,
+    };
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@durion/react",
+  "version": "0.1.0",
+  "description": "Durion React hooks for workflow stream state + Gateway v0 token SSE",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shaibusunnuma/durion.git",
+    "directory": "packages/react"
+  },
+  "homepage": "https://github.com/shaibusunnuma/durion#readme",
+  "bugs": {
+    "url": "https://github.com/shaibusunnuma/durion/issues"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "@durion/sdk": "^0.1.0"
+  },
+  "devDependencies": {
+    "@durion/sdk": "^0.1.0",
+    "@types/react": "^19.0.0",
+    "react": "^19.0.0",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.0"
+  }
+}