@agentick/react 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Agentick 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,275 @@
+# @agentick/react
+
+React bindings for Agentick. Provides hooks around `@agentick/client` for building chat interfaces and real-time AI applications.
+
+## Installation
+
+```bash
+pnpm add @agentick/react
+```
+
+## Quick Start
+
+```tsx
+import { AgentickProvider, useSession, useStreamingText, useContextInfo } from "@agentick/react";
+
+function Chat() {
+  const { send } = useSession({ sessionId: "my-session", autoSubscribe: true });
+  const { text, isStreaming } = useStreamingText();
+  const { contextInfo } = useContextInfo();
+
+  return (
+    <div>
+      <div className="response">
+        {text}
+        {isStreaming && <span className="cursor">|</span>}
+      </div>
+
+      {contextInfo && (
+        <div className="context-bar">
+          <span>{contextInfo.modelName}</span>
+          <span>{contextInfo.utilization?.toFixed(1)}% context used</span>
+        </div>
+      )}
+
+      <button onClick={() => send("Hello!")}>Send</button>
+    </div>
+  );
+}
+
+export function App() {
+  return (
+    <AgentickProvider clientConfig={{ baseUrl: "/api" }}>
+      <Chat />
+    </AgentickProvider>
+  );
+}
+```
+
+## Hooks
+
+### `useSession(options?)`
+
+Session management hook. Returns methods for sending messages and managing subscriptions.
+
+```tsx
+const {
+  sessionId,      // Current session ID
+  isSubscribed,   // Whether subscribed to session events
+  subscribe,      // Subscribe to session events
+  unsubscribe,    // Unsubscribe from session events
+  send,           // Send a message
+  abort,          // Abort current execution
+  close,          // Close the session
+  accessor,       // Direct SessionAccessor for advanced use
+} = useSession({
+  sessionId: "my-session",  // Optional - creates ephemeral session if omitted
+  autoSubscribe: true,      // Auto-subscribe on mount
+});
+
+// Send a simple text message
+await send("Hello!");
+
+// Send with full message structure
+await send({
+  message: {
+    role: "user",
+    content: [{ type: "text", text: "Hello!" }],
+  },
+});
+```
+
+### `useStreamingText(options?)`
+
+Subscribe to streaming text from model responses. Automatically accumulates text deltas.
+
+```tsx
+const {
+  text,        // Accumulated text from current response
+  isStreaming, // Whether currently receiving text
+  clear,       // Clear accumulated text
+} = useStreamingText({
+  enabled: true,  // Enable/disable subscription
+});
+
+// Display with typing indicator
+<div>
+  {text}
+  {isStreaming && <span className="cursor">|</span>}
+</div>
+```
+
+### `useContextInfo(options?)`
+
+Subscribe to context utilization information. Updated after each model response with token usage and model capabilities.
+
+```tsx
+const {
+  contextInfo,  // Latest context info (null before first response)
+  clear,        // Clear context info
+} = useContextInfo({
+  sessionId: "my-session",  // Optional - filter by session
+  enabled: true,            // Enable/disable subscription
+});
+
+if (contextInfo) {
+  console.log(contextInfo.modelId);         // "gpt-4o" | "claude-3-5-sonnet" | etc.
+  console.log(contextInfo.modelName);       // Human-readable name
+  console.log(contextInfo.provider);        // "openai" | "anthropic" | etc.
+  console.log(contextInfo.contextWindow);   // Total context window size
+  console.log(contextInfo.inputTokens);     // Input tokens this tick
+  console.log(contextInfo.outputTokens);    // Output tokens this tick
+  console.log(contextInfo.totalTokens);     // Total tokens this tick
+  console.log(contextInfo.utilization);     // Context utilization % (0-100)
+  console.log(contextInfo.maxOutputTokens); // Max output tokens for model
+  console.log(contextInfo.supportsVision);  // Model supports vision
+  console.log(contextInfo.supportsToolUse); // Model supports tools
+  console.log(contextInfo.isReasoningModel);// Extended thinking model
+
+  // Cumulative usage across all ticks in execution
+  console.log(contextInfo.cumulativeUsage?.inputTokens);
+  console.log(contextInfo.cumulativeUsage?.outputTokens);
+  console.log(contextInfo.cumulativeUsage?.ticks);
+}
+```
+
+#### ContextInfo Interface
+
+```typescript
+interface ContextInfo {
+  modelId: string;           // Model identifier (e.g., "gpt-4o")
+  modelName?: string;        // Human-readable name
+  provider?: string;         // Provider name
+  contextWindow?: number;    // Context window size in tokens
+  inputTokens: number;       // Input tokens this tick
+  outputTokens: number;      // Output tokens this tick
+  totalTokens: number;       // Total tokens this tick
+  utilization?: number;      // Context utilization % (0-100)
+  maxOutputTokens?: number;  // Max output tokens
+  supportsVision?: boolean;  // Vision capability
+  supportsToolUse?: boolean; // Tool use capability
+  isReasoningModel?: boolean;// Extended thinking capability
+  tick: number;              // Current tick number
+  cumulativeUsage?: {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    ticks: number;
+  };
+}
+```
+
+### `useEvents(options?)`
+
+Subscribe to raw stream events. Use for advanced event handling.
+
+```tsx
+const {
+  event,  // Latest event
+  clear,  // Clear current event
+} = useEvents({
+  sessionId: "my-session",              // Optional - filter by session
+  filter: ["tool_call", "tool_result"], // Optional - filter by event type
+  enabled: true,
+});
+
+useEffect(() => {
+  if (event?.type === "tool_call") {
+    console.log("Tool called:", event.name);
+  }
+}, [event]);
+```
+
+### `useConnection()`
+
+Connection state for the SSE transport.
+
+```tsx
+const {
+  state,         // "disconnected" | "connecting" | "connected"
+  isConnected,   // Convenience boolean
+  isConnecting,  // Convenience boolean
+} = useConnection();
+
+<div className={`status ${isConnected ? "online" : "offline"}`}>
+  {isConnected ? "Connected" : "Disconnected"}
+</div>
+```
+
+### `useConnectionState()`
+
+Alias for `useConnection()`. Returns just the connection state string.
+
+```tsx
+const state = useConnectionState(); // "disconnected" | "connecting" | "connected"
+```
+
+### `useClient()`
+
+Direct access to the underlying `AgentickClient` for advanced use cases.
+
+```tsx
+const client = useClient();
+
+// Direct client access
+const session = client.session("my-session");
+const channel = session.channel("custom");
+channel.publish("event", { data: "value" });
+```
+
+## Provider
+
+### `AgentickProvider`
+
+Wraps your app to provide the Agentick client context.
+
+```tsx
+<AgentickProvider
+  clientConfig={{
+    baseUrl: "https://api.example.com",  // Required - API base URL
+    token: "auth-token",                  // Optional - auth token
+  }}
+>
+  <App />
+</AgentickProvider>
+```
+
+## Types
+
+All hooks are fully typed. Import types from the package:
+
+```typescript
+import type {
+  // Provider types
+  AgentickProviderProps,
+  AgentickContextValue,
+  TransportConfig,
+
+  // Hook types
+  UseConnectionOptions,
+  UseConnectionResult,
+  UseSessionOptions,
+  UseSessionResult,
+  UseEventsOptions,
+  UseEventsResult,
+  UseStreamingTextOptions,
+  UseStreamingTextResult,
+  UseContextInfoOptions,
+  UseContextInfoResult,
+  ContextInfo,
+
+  // Re-exported from @agentick/client
+  AgentickClient,
+  ConnectionState,
+  StreamEvent,
+  SessionAccessor,
+  SendInput,
+  ClientExecutionHandle,
+  SessionStreamEvent,
+  ClientTransport,
+} from "@agentick/react";
+```
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,90 @@
+/**
+ * React context for Agentick client.
+ *
+ * @module @agentick/react/context
+ */
+import type { AgentickProviderProps, AgentickContextValue } from "./types";
+export declare const AgentickContext: import("react").Context<AgentickContextValue | null>;
+/**
+ * Provider for Agentick client context.
+ *
+ * Either provide a pre-configured client or clientConfig to create one.
+ *
+ * @example With client config
+ * ```tsx
+ * import { AgentickProvider } from '@agentick/react';
+ *
+ * function App() {
+ *   return (
+ *     <AgentickProvider
+ *       clientConfig={{
+ *         baseUrl: 'https://api.example.com',
+ *         token: 'my-token',
+ *       }}
+ *     >
+ *       <Chat />
+ *     </AgentickProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example With pre-configured client
+ * ```tsx
+ * import { AgentickProvider } from '@agentick/react';
+ * import { createClient } from '@agentick/client';
+ *
+ * const client = createClient({
+ *   baseUrl: 'https://api.example.com',
+ *   token: 'my-token',
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <AgentickProvider client={client}>
+ *       <Chat />
+ *     </AgentickProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Multiple agents with separate instances
+ * ```tsx
+ * // Each provider creates its own client and connection
+ * function App() {
+ *   return (
+ *     <div className="dashboard">
+ *       <AgentickProvider clientConfig={{ baseUrl: '/api/support-agent' }}>
+ *         <SupportChat />
+ *       </AgentickProvider>
+ *
+ *       <AgentickProvider clientConfig={{ baseUrl: '/api/sales-agent' }}>
+ *         <SalesChat />
+ *       </AgentickProvider>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Sharing a client between components
+ * ```tsx
+ * // Create one client, share across multiple providers
+ * const sharedClient = createClient({ baseUrl: '/api/agent' });
+ *
+ * function App() {
+ *   return (
+ *     <>
+ *       <AgentickProvider client={sharedClient}>
+ *         <MainChat />
+ *       </AgentickProvider>
+ *
+ *       {/* Both providers share the same client and connection * /}
+ *       <AgentickProvider client={sharedClient}>
+ *         <ChatSidebar />
+ *       </AgentickProvider>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare function AgentickProvider({ client: providedClient, clientConfig, children, }: AgentickProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAC;AAM3E,eAAO,MAAM,eAAe,sDAAmD,CAAC;AAMhF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,wBAAgB,gBAAgB,CAAC,EAC/B,MAAM,EAAE,cAAc,EACtB,YAAY,EACZ,QAAQ,GACT,EAAE,qBAAqB,2CA2BvB"}

package/dist/context.js

@@ -0,0 +1,120 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React context for Agentick client.
+ *
+ * @module @agentick/react/context
+ */
+import { createContext, useMemo, useEffect } from "react";
+import { createClient } from "@agentick/client";
+// ============================================================================
+// Context
+// ============================================================================
+export const AgentickContext = createContext(null);
+// ============================================================================
+// Provider
+// ============================================================================
+/**
+ * Provider for Agentick client context.
+ *
+ * Either provide a pre-configured client or clientConfig to create one.
+ *
+ * @example With client config
+ * ```tsx
+ * import { AgentickProvider } from '@agentick/react';
+ *
+ * function App() {
+ *   return (
+ *     <AgentickProvider
+ *       clientConfig={{
+ *         baseUrl: 'https://api.example.com',
+ *         token: 'my-token',
+ *       }}
+ *     >
+ *       <Chat />
+ *     </AgentickProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example With pre-configured client
+ * ```tsx
+ * import { AgentickProvider } from '@agentick/react';
+ * import { createClient } from '@agentick/client';
+ *
+ * const client = createClient({
+ *   baseUrl: 'https://api.example.com',
+ *   token: 'my-token',
+ * });
+ *
+ * function App() {
+ *   return (
+ *     <AgentickProvider client={client}>
+ *       <Chat />
+ *     </AgentickProvider>
+ *   );
+ * }
+ * ```
+ *
+ * @example Multiple agents with separate instances
+ * ```tsx
+ * // Each provider creates its own client and connection
+ * function App() {
+ *   return (
+ *     <div className="dashboard">
+ *       <AgentickProvider clientConfig={{ baseUrl: '/api/support-agent' }}>
+ *         <SupportChat />
+ *       </AgentickProvider>
+ *
+ *       <AgentickProvider clientConfig={{ baseUrl: '/api/sales-agent' }}>
+ *         <SalesChat />
+ *       </AgentickProvider>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Sharing a client between components
+ * ```tsx
+ * // Create one client, share across multiple providers
+ * const sharedClient = createClient({ baseUrl: '/api/agent' });
+ *
+ * function App() {
+ *   return (
+ *     <>
+ *       <AgentickProvider client={sharedClient}>
+ *         <MainChat />
+ *       </AgentickProvider>
+ *
+ *       {/* Both providers share the same client and connection * /}
+ *       <AgentickProvider client={sharedClient}>
+ *         <ChatSidebar />
+ *       </AgentickProvider>
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export function AgentickProvider({ client: providedClient, clientConfig, children, }) {
+    // Create client from config if not provided
+    const client = useMemo(() => {
+        if (providedClient) {
+            return providedClient;
+        }
+        if (!clientConfig) {
+            throw new Error("AgentickProvider requires either a client or clientConfig prop");
+        }
+        return createClient(clientConfig);
+    }, [providedClient, clientConfig]);
+    // Cleanup on unmount (only if we created the client)
+    useEffect(() => {
+        // Only destroy if we created it (not provided)
+        if (!providedClient) {
+            return () => {
+                client.destroy();
+            };
+        }
+    }, [client, providedClient]);
+    const value = useMemo(() => ({ client }), [client]);
+    return _jsx(AgentickContext.Provider, { value: value, children: children });
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.tsx"],"names":[],"mappings":";AAAA;;;;GAIG;AAEH,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAC1D,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,+EAA+E;AAC/E,UAAU;AACV,+EAA+E;AAE/E,MAAM,CAAC,MAAM,eAAe,GAAG,aAAa,CAA8B,IAAI,CAAC,CAAC;AAEhF,+EAA+E;AAC/E,WAAW;AACX,+EAA+E;AAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,UAAU,gBAAgB,CAAC,EAC/B,MAAM,EAAE,cAAc,EACtB,YAAY,EACZ,QAAQ,GACc;IACtB,4CAA4C;IAC5C,MAAM,MAAM,GAAG,OAAO,CAAC,GAAG,EAAE;QAC1B,IAAI,cAAc,EAAE,CAAC;YACnB,OAAO,cAAc,CAAC;QACxB,CAAC;QAED,IAAI,CAAC,YAAY,EAAE,CAAC;YAClB,MAAM,IAAI,KAAK,CAAC,gEAAgE,CAAC,CAAC;QACpF,CAAC;QAED,OAAO,YAAY,CAAC,YAAY,CAAC,CAAC;IACpC,CAAC,EAAE,CAAC,cAAc,EAAE,YAAY,CAAC,CAAC,CAAC;IAEnC,qDAAqD;IACrD,SAAS,CAAC,GAAG,EAAE;QACb,+CAA+C;QAC/C,IAAI,CAAC,cAAc,EAAE,CAAC;YACpB,OAAO,GAAG,EAAE;gBACV,MAAM,CAAC,OAAO,EAAE,CAAC;YACnB,CAAC,CAAC;QACJ,CAAC;IACH,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;IAE7B,MAAM,KAAK,GAAG,OAAO,CAAuB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;IAE1E,OAAO,KAAC,eAAe,CAAC,QAAQ,IAAC,KAAK,EAAE,KAAK,YAAG,QAAQ,GAA4B,CAAC;AACvF,CAAC"}