@agentick/react 0.0.1

package/dist/hooks.d.ts

@@ -0,0 +1,290 @@
+/**
+ * React hooks for Agentick.
+ *
+ * @module @agentick/react/hooks
+ */
+import type { AgentickClient, ConnectionState } from "@agentick/client";
+import type { UseSessionOptions, UseSessionResult, UseEventsOptions, UseEventsResult, UseStreamingTextOptions, UseStreamingTextResult, UseConnectionOptions, UseConnectionResult } from "./types";
+/**
+ * Access the Agentick client from context.
+ *
+ * @throws If used outside of AgentickProvider
+ *
+ * @example
+ * ```tsx
+ * import { useClient } from '@agentick/react';
+ *
+ * function MyComponent() {
+ *   const client = useClient();
+ *
+ *   // Direct client access for advanced use cases
+ *   const handleCustomChannel = () => {
+ *     const session = client.session('conv-123');
+ *     const channel = session.channel('custom');
+ *     channel.publish('event', { data: 'value' });
+ *   };
+ *
+ *   return <button onClick={handleCustomChannel}>Send</button>;
+ * }
+ * ```
+ */
+export declare function useClient(): AgentickClient;
+/**
+ * Subscribe to connection state changes.
+ *
+ * @example
+ * ```tsx
+ * import { useConnectionState } from '@agentick/react';
+ *
+ * function ConnectionIndicator() {
+ *   const state = useConnectionState();
+ *
+ *   return (
+ *     <div className={`indicator ${state}`}>
+ *       {state === 'connected' ? 'Online' : 'Offline'}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useConnectionState(): ConnectionState;
+/**
+ * Read the SSE connection state.
+ */
+export declare function useConnection(_options?: UseConnectionOptions): UseConnectionResult;
+/**
+ * Work with a specific session.
+ *
+ * @example Basic usage with session ID
+ * ```tsx
+ * import { useSession } from '@agentick/react';
+ *
+ * function Chat({ sessionId }: { sessionId: string }) {
+ *   const { send, isSubscribed, subscribe } = useSession({ sessionId });
+ *   const [input, setInput] = useState('');
+ *
+ *   // Subscribe on mount
+ *   useEffect(() => {
+ *     subscribe();
+ *   }, [subscribe]);
+ *
+ *   const handleSend = async () => {
+ *     await send(input);
+ *     setInput('');
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <input value={input} onChange={(e) => setInput(e.target.value)} />
+ *       <button onClick={handleSend}>Send</button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Ephemeral session (no sessionId)
+ * ```tsx
+ * function QuickChat() {
+ *   const { send } = useSession();
+ *
+ *   // Each send creates/uses an ephemeral session
+ *   const handleSend = () => send('Hello!');
+ *
+ *   return <button onClick={handleSend}>Ask</button>;
+ * }
+ * ```
+ *
+ * @example Auto-subscribe
+ * ```tsx
+ * function Chat({ sessionId }: { sessionId: string }) {
+ *   const { send, isSubscribed } = useSession({
+ *     sessionId,
+ *     autoSubscribe: true,
+ *   });
+ *
+ *   if (!isSubscribed) return <div>Subscribing...</div>;
+ *
+ *   return <ChatInterface />;
+ * }
+ * ```
+ */
+export declare function useSession(options?: UseSessionOptions): UseSessionResult;
+/**
+ * Subscribe to stream events.
+ *
+ * Returns the latest event (not accumulated). Use useStreamingText
+ * for accumulated text from content_delta events.
+ *
+ * @example
+ * ```tsx
+ * import { useEvents } from '@agentick/react';
+ *
+ * function EventLog() {
+ *   const { event } = useEvents();
+ *
+ *   useEffect(() => {
+ *     if (event) {
+ *       console.log('Event:', event.type, event);
+ *     }
+ *   }, [event]);
+ *
+ *   return <div>Latest: {event?.type}</div>;
+ * }
+ * ```
+ *
+ * @example With filter
+ * ```tsx
+ * function ToolCalls() {
+ *   const { event } = useEvents({ filter: ['tool_call', 'tool_result'] });
+ *
+ *   if (!event) return null;
+ *
+ *   return <div>Tool: {event.type === 'tool_call' ? event.name : 'result'}</div>;
+ * }
+ * ```
+ *
+ * @example Session-specific events
+ * ```tsx
+ * function SessionEvents({ sessionId }: { sessionId: string }) {
+ *   const { event } = useEvents({ sessionId });
+ *   // Only receives events for this session
+ *   return <div>{event?.type}</div>;
+ * }
+ * ```
+ */
+export declare function useEvents(options?: UseEventsOptions): UseEventsResult;
+/**
+ * Subscribe to streaming text from the client.
+ *
+ * Uses the client's built-in streaming text accumulation which handles
+ * tick_start, content_delta, tick_end, and execution_end events.
+ *
+ * @example
+ * ```tsx
+ * import { useStreamingText } from '@agentick/react';
+ *
+ * function StreamingResponse() {
+ *   const { text, isStreaming } = useStreamingText();
+ *
+ *   return (
+ *     <div>
+ *       <p>{text}</p>
+ *       {isStreaming && <span className="cursor">|</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useStreamingText(options?: UseStreamingTextOptions): UseStreamingTextResult;
+/**
+ * Context utilization info from the server.
+ * Updated after each tick with token usage and model capabilities.
+ */
+export interface ContextInfo {
+    /** Model ID (e.g., "gpt-4o", "claude-3-5-sonnet-20241022") */
+    modelId: string;
+    /** Human-readable model name */
+    modelName?: string;
+    /** Provider name (e.g., "openai", "anthropic") */
+    provider?: string;
+    /** Context window size in tokens */
+    contextWindow?: number;
+    /** Input tokens used this tick */
+    inputTokens: number;
+    /** Output tokens generated this tick */
+    outputTokens: number;
+    /** Total tokens this tick */
+    totalTokens: number;
+    /** Context utilization percentage (0-100) */
+    utilization?: number;
+    /** Max output tokens for this model */
+    maxOutputTokens?: number;
+    /** Model capabilities */
+    supportsVision?: boolean;
+    supportsToolUse?: boolean;
+    isReasoningModel?: boolean;
+    /** Current tick number */
+    tick: number;
+    /** Cumulative usage across all ticks in this execution */
+    cumulativeUsage?: {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        ticks: number;
+    };
+}
+/**
+ * Options for useContextInfo hook.
+ */
+export interface UseContextInfoOptions {
+    /**
+     * Optional session ID to filter events for.
+     * If not provided, receives context info from any session.
+     */
+    sessionId?: string;
+    /**
+     * Whether the hook is enabled.
+     * If false, no context info subscription is created.
+     * @default true
+     */
+    enabled?: boolean;
+}
+/**
+ * Return value from useContextInfo hook.
+ */
+export interface UseContextInfoResult {
+    /**
+     * Latest context info (null before first tick completes).
+     */
+    contextInfo: ContextInfo | null;
+    /**
+     * Clear the current context info.
+     */
+    clear: () => void;
+}
+/**
+ * Subscribe to context utilization info from the server.
+ *
+ * Receives context_update events after each tick with:
+ * - Token usage (input, output, total)
+ * - Context utilization percentage
+ * - Model capabilities (vision, tools, reasoning)
+ * - Cumulative usage across ticks
+ *
+ * @example Basic usage
+ * ```tsx
+ * import { useContextInfo } from '@agentick/react';
+ *
+ * function ContextBar() {
+ *   const { contextInfo } = useContextInfo();
+ *
+ *   if (!contextInfo) return null;
+ *
+ *   return (
+ *     <div className="context-bar">
+ *       <span>{contextInfo.modelId}</span>
+ *       <span>{contextInfo.utilization?.toFixed(1)}% used</span>
+ *       <progress value={contextInfo.utilization} max={100} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @example Session-specific context info
+ * ```tsx
+ * function SessionContext({ sessionId }: { sessionId: string }) {
+ *   const { contextInfo } = useContextInfo({ sessionId });
+ *
+ *   if (!contextInfo) return <span>No context yet</span>;
+ *
+ *   return (
+ *     <span>
+ *       {contextInfo.inputTokens.toLocaleString()} /
+ *       {contextInfo.contextWindow?.toLocaleString() ?? '?'} tokens
+ *     </span>
+ *   );
+ * }
+ * ```
+ */
+export declare function useContextInfo(options?: UseContextInfoOptions): UseContextInfoResult;
+//# 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":"AAAA;;;;GAIG;AAWH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EAKhB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,KAAK,EACV,iBAAiB,EACjB,gBAAgB,EAChB,gBAAgB,EAChB,eAAe,EACf,uBAAuB,EACvB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACpB,MAAM,SAAS,CAAC;AAMjB;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,SAAS,IAAI,cAAc,CAQ1C;AAMD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,kBAAkB,IAAI,eAAe,CAcpD;AAMD;;GAEG;AACH,wBAAgB,aAAa,CAAC,QAAQ,GAAE,oBAAyB,GAAG,mBAAmB,CActF;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,gBAAgB,CAkG5E;AAMD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AACH,wBAAgB,SAAS,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CAqCzE;AAMD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,GAAE,uBAA4B,GAAG,sBAAsB,CAsB9F;AAMD;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,gCAAgC;IAChC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kDAAkD;IAClD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oCAAoC;IACpC,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,kCAAkC;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,wCAAwC;IACxC,YAAY,EAAE,MAAM,CAAC;IACrB,6BAA6B;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,6CAA6C;IAC7C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,uCAAuC;IACvC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yBAAyB;IACzB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,0DAA0D;IAC1D,eAAe,CAAC,EAAE;QAChB,WAAW,EAAE,MAAM,CAAC;QACpB,YAAY,EAAE,MAAM,CAAC;QACrB,WAAW,EAAE,MAAM,CAAC;QACpB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,WAAW,EAAE,WAAW,GAAG,IAAI,CAAC;IAEhC;;OAEG;IACH,KAAK,EAAE,MAAM,IAAI,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,wBAAgB,cAAc,CAAC,OAAO,GAAE,qBAA0B,GAAG,oBAAoB,CA+DxF"}