@cybernetyx1/atlasflow-react 0.1.0

package/LICENSE

@@ -0,0 +1,18 @@
+PROPRIETARY SOFTWARE LICENSE
+
+Copyright (c) 2026 Cybernetyx. All rights reserved.
+
+This software and its source code are the proprietary and confidential property
+of the copyright holder. The software is original work authored independently.
+
+No part of this software may be copied, reproduced, modified, published,
+distributed, sublicensed, or sold in any form or by any means without the prior
+written permission of the copyright holder, except as expressly permitted by a
+separate written agreement.
+
+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,67 @@
+# @cybernetyx1/atlasflow-react
+
+React hooks and provider for wiring browser and app UIs to an AtlasFlow agent server.
+
+## Install
+
+```sh
+pnpm add @cybernetyx1/atlasflow-react
+```
+
+Part of the AtlasFlow monorepo. Proprietary.
+
+## Usage
+
+Wrap your app in `AtlasFlowProvider` (pass either a prebuilt `client` or `options`). Then use `useAgent` to chat with an agent, `useRunWatch` to follow a durable run's event stream, and `useAtlasFlowClient` to reach the client directly.
+
+Never put `ATLASFLOW_API_KEY` in browser code. Mint a short-lived scoped token on your server (see `@cybernetyx1/atlasflow-sdk`) and pass it to the provider.
+
+```tsx
+import { AtlasFlowProvider, useAgent } from "@cybernetyx1/atlasflow-react";
+
+function Chat() {
+  const agent = useAgent({ agent: "hello", instanceId: "user-123" });
+
+  return (
+    <form
+      onSubmit={(event) => {
+        event.preventDefault();
+        const input = new FormData(event.currentTarget).get("message");
+        void agent.send(String(input ?? ""));
+        event.currentTarget.reset();
+      }}
+    >
+      {agent.messages.map((message, index) => (
+        <p key={index}>{message.role}: {message.content}</p>
+      ))}
+      <input name="message" />
+      <button disabled={agent.isStreaming}>Send</button>
+    </form>
+  );
+}
+
+export function App({ token }: { token: string }) {
+  return (
+    <AtlasFlowProvider options={{ baseUrl: "https://agent.example", apiKey: token }}>
+      <Chat />
+    </AtlasFlowProvider>
+  );
+}
+```
+
+```tsx
+import { useRunWatch, useAtlasFlowClient } from "@cybernetyx1/atlasflow-react";
+
+function RunStatus() {
+  const client = useAtlasFlowClient();
+  // Pass a run id or the RunAdmission returned by client.runs.dispatch(...).
+  const run = useRunWatch({ target: "run_abc123" });
+  return <pre>{run.status}: {run.events.length} events</pre>;
+}
+```
+
+Exports: `AtlasFlowProvider`, `useAtlasFlowClient`, `useAgent`, `useRunWatch`, plus the `AgentChatMessage` / `AgentHookState` / `AgentStatus` types and the hook option/result types.
+
+## License
+
+Proprietary. © 2026 Cybernetyx. See LICENSE.

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+import { ReactNode } from 'react';
+import { AtlasEventLike, Usage, AtlasFlowClient, ClientOptions, AgentDispatchInput, RunWatchOptions, RunAdmission } from '@cybernetyx1/atlasflow-sdk';
+
+type AgentStatus = "idle" | "streaming" | "success" | "error";
+interface AgentChatMessage {
+    role: "user" | "assistant";
+    content: string;
+    runId?: string;
+    pending?: boolean;
+    error?: string;
+}
+interface AgentHookState {
+    status: AgentStatus;
+    messages: AgentChatMessage[];
+    events: AtlasEventLike[];
+    runId?: string;
+    data?: string;
+    result?: unknown;
+    usage?: Usage;
+    error?: Error;
+}
+
+interface AtlasFlowProviderProps {
+    client?: AtlasFlowClient;
+    options?: ClientOptions;
+    children?: ReactNode;
+}
+interface UseAgentOptions {
+    client?: AtlasFlowClient;
+    agent: string;
+    instanceId: string;
+    initialMessages?: AgentChatMessage[];
+    stream?: boolean;
+}
+interface UseAgentResult extends AgentHookState {
+    isStreaming: boolean;
+    send(input: string | AgentDispatchInput): Promise<void>;
+    reset(messages?: AgentChatMessage[]): void;
+    stop(): void;
+}
+interface RunWatchState {
+    status: "idle" | "watching" | "closed" | "error";
+    events: AtlasEventLike[];
+    error?: Error;
+}
+interface UseRunWatchOptions extends RunWatchOptions {
+    client?: AtlasFlowClient;
+    target?: string | RunAdmission | null;
+}
+declare function AtlasFlowProvider({ client, options, children }: AtlasFlowProviderProps): unknown;
+declare function useAtlasFlowClient(client?: AtlasFlowClient): AtlasFlowClient;
+declare function useAgent(options: UseAgentOptions): UseAgentResult;
+declare function useRunWatch({ client: explicitClient, target, ...watchOptions }: UseRunWatchOptions): RunWatchState;
+
+export { type AgentChatMessage, type AgentHookState, type AgentStatus, AtlasFlowProvider, type AtlasFlowProviderProps, type RunWatchState, type UseAgentOptions, type UseAgentResult, type UseRunWatchOptions, useAgent, useAtlasFlowClient, useRunWatch };

package/dist/index.js

@@ -0,0 +1,235 @@
+// src/index.ts
+import {
+  createContext,
+  createElement,
+  useCallback,
+  useContext,
+  useEffect,
+  useMemo,
+  useReducer,
+  useRef
+} from "react";
+import {
+  createAtlasFlowClient
+} from "@cybernetyx1/atlasflow-sdk";
+
+// src/state.ts
+function initialAgentState(messages = []) {
+  return { status: "idle", messages, events: [] };
+}
+function agentReducer(state, action) {
+  switch (action.type) {
+    case "reset":
+      return initialAgentState(action.messages ?? []);
+    case "start":
+      return {
+        ...state,
+        status: "streaming",
+        error: void 0,
+        data: void 0,
+        result: void 0,
+        usage: void 0,
+        events: [],
+        messages: [
+          ...state.messages,
+          { role: "user", content: action.message },
+          { role: "assistant", content: "", pending: true }
+        ]
+      };
+    case "event":
+      return applyAgentEvent(state, action.event);
+    case "sync_result":
+      return replaceAssistant(state, {
+        status: "success",
+        runId: action.result.runId,
+        data: action.result.data,
+        result: action.result.result,
+        usage: action.result.usage,
+        content: action.result.data,
+        pending: false
+      });
+    case "error":
+      return replaceAssistant(state, {
+        status: "error",
+        error: action.error,
+        content: state.messages.at(-1)?.role === "assistant" ? state.messages.at(-1)?.content ?? "" : "",
+        pending: false,
+        messageError: action.error.message
+      });
+  }
+}
+function applyAgentEvent(state, event) {
+  const events = [...state.events, event];
+  if (event.type === "text_delta") {
+    const delta = typeof event.delta === "string" ? event.delta : typeof event.text === "string" ? event.text : "";
+    return appendAssistant({ ...state, events }, delta);
+  }
+  if (event.type === "result") {
+    return replaceAssistant({
+      ...state,
+      events,
+      status: "success",
+      runId: typeof event.runId === "string" ? event.runId : state.runId,
+      data: typeof event.text === "string" ? event.text : typeof event.data === "string" ? event.data : state.data,
+      result: "data" in event ? event.data : state.result,
+      usage: isUsage(event.usage) ? event.usage : state.usage
+    }, {
+      status: "success",
+      content: typeof event.text === "string" ? event.text : void 0,
+      pending: false
+    });
+  }
+  if (event.type === "run_error") {
+    const err = new Error(typeof event.message === "string" ? event.message : "run failed");
+    return replaceAssistant({ ...state, events }, { status: "error", error: err, pending: false, messageError: err.message });
+  }
+  return { ...state, events };
+}
+function appendAssistant(state, delta) {
+  if (!delta) return state;
+  const messages = [...state.messages];
+  const last = messages.at(-1);
+  if (last?.role === "assistant") {
+    messages[messages.length - 1] = { ...last, content: last.content + delta, pending: true };
+  } else {
+    messages.push({ role: "assistant", content: delta, pending: true });
+  }
+  return { ...state, messages, data: (state.data ?? "") + delta };
+}
+function replaceAssistant(state, patch) {
+  const messages = [...state.messages];
+  const last = messages.at(-1);
+  const content = patch.content ?? (last?.role === "assistant" ? last.content : "");
+  const assistant = {
+    role: "assistant",
+    content,
+    ...patch.runId ?? state.runId ? { runId: patch.runId ?? state.runId } : {},
+    ...patch.pending !== void 0 ? { pending: patch.pending } : {},
+    ...patch.messageError ? { error: patch.messageError } : {}
+  };
+  if (last?.role === "assistant") messages[messages.length - 1] = assistant;
+  else messages.push(assistant);
+  const { content: _content, pending: _pending, messageError: _messageError, ...statePatch } = patch;
+  return { ...state, ...statePatch, messages };
+}
+function isUsage(value) {
+  if (!value || typeof value !== "object") return false;
+  const usage = value;
+  return typeof usage.totalTokens === "number" && typeof usage.costTotal === "number";
+}
+
+// src/index.ts
+var AtlasFlowContext = createContext(void 0);
+function AtlasFlowProvider({ client, options, children }) {
+  const resolved = useMemo(() => client ?? (options ? createAtlasFlowClient(options) : void 0), [client, options?.baseUrl, options?.apiKey, options?.fetch, options?.headers]);
+  if (!resolved) throw new Error("AtlasFlowProvider requires either client or options.");
+  return createElement(AtlasFlowContext.Provider, { value: resolved }, children);
+}
+function useAtlasFlowClient(client) {
+  const ctx = useContext(AtlasFlowContext);
+  const resolved = client ?? ctx;
+  if (!resolved) throw new Error("No AtlasFlow client found. Wrap your component in AtlasFlowProvider or pass { client }.");
+  return resolved;
+}
+function useAgent(options) {
+  const client = useAtlasFlowClient(options.client);
+  const [state, dispatch] = useReducer(agentReducer, initialAgentState(options.initialMessages));
+  const abortRef = useRef(null);
+  const stop = useCallback(() => {
+    abortRef.current?.abort();
+    abortRef.current = null;
+  }, []);
+  const reset = useCallback((messages = []) => {
+    stop();
+    dispatch({ type: "reset", messages });
+  }, [stop]);
+  const send = useCallback(
+    async (input) => {
+      stop();
+      const body = typeof input === "string" ? { message: input } : input;
+      const message = body.message ?? "";
+      dispatch({ type: "start", message });
+      const abort = new AbortController();
+      abortRef.current = abort;
+      try {
+        if (options.stream === false) {
+          const result = await client.agents.send(options.agent, options.instanceId, { ...body, message });
+          if (!abort.signal.aborted) dispatch({ type: "sync_result", result });
+          return;
+        }
+        for await (const event of client.agents.stream(options.agent, options.instanceId, { ...body, message, signal: abort.signal })) {
+          if (abort.signal.aborted) break;
+          dispatch({ type: "event", event });
+        }
+      } catch (err) {
+        if (!abort.signal.aborted) dispatch({ type: "error", error: normalizeError(err) });
+      } finally {
+        if (abortRef.current === abort) abortRef.current = null;
+      }
+    },
+    [client, options.agent, options.instanceId, options.stream, stop]
+  );
+  useEffect(() => stop, [stop]);
+  return {
+    ...state,
+    isStreaming: state.status === "streaming",
+    send,
+    reset,
+    stop
+  };
+}
+function useRunWatch({ client: explicitClient, target, ...watchOptions }) {
+  const client = useAtlasFlowClient(explicitClient);
+  const [state, setState] = useReducer(runWatchReducer, { status: "idle", events: [] });
+  const serializedOptions = JSON.stringify({
+    offset: watchOptions.offset,
+    after: watchOptions.after,
+    limit: watchOptions.limit,
+    tail: watchOptions.tail,
+    reconnect: watchOptions.reconnect
+  });
+  useEffect(() => {
+    if (!target) {
+      setState({ type: "reset" });
+      return;
+    }
+    const abort = new AbortController();
+    setState({ type: "start" });
+    void (async () => {
+      try {
+        for await (const event of client.runs.watch(target, { ...watchOptions, signal: abort.signal })) {
+          if (abort.signal.aborted) break;
+          setState({ type: "event", event });
+        }
+        if (!abort.signal.aborted) setState({ type: "closed" });
+      } catch (err) {
+        if (!abort.signal.aborted) setState({ type: "error", error: normalizeError(err) });
+      }
+    })();
+    return () => abort.abort();
+  }, [client, target, serializedOptions]);
+  return state;
+}
+function runWatchReducer(state, action) {
+  switch (action.type) {
+    case "reset":
+      return { status: "idle", events: [] };
+    case "start":
+      return { status: "watching", events: [], error: void 0 };
+    case "event":
+      return { ...state, events: [...state.events, action.event] };
+    case "closed":
+      return { ...state, status: "closed" };
+    case "error":
+      return { ...state, status: "error", error: action.error };
+  }
+}
+function normalizeError(err) {
+  return err instanceof Error ? err : new Error(String(err));
+}
+export {
+  AtlasFlowProvider,
+  useAgent,
+  useAtlasFlowClient,
+  useRunWatch
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@cybernetyx1/atlasflow-react",
+  "version": "0.1.0",
+  "description": "React provider and hooks for AtlasFlow agent chat and durable run event streams.",
+  "type": "module",
+  "license": "SEE LICENSE IN LICENSE",
+  "author": "Cybernetyx",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Cybernetyx/atlasflow.git",
+    "directory": "packages/react"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cybernetyx1/atlasflow-sdk": "0.1.0"
+  },
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/*.test.ts"
+  }
+}