Hooks - Jade SDK

The Jade SDK provides React hooks for managing AI sessions, streaming, and media extraction. The API is nearly identical across web and React Native.

useJadeSession

The primary hook for managing Jade AI sessions. It handles conversation state, streaming, and media extraction.

Import

React / Next.js
React Native

import { useJadeSession } from '@gr33n-ai/jade-sdk-client';

import { useJadeSession } from '@gr33n-ai/jade-sdk-rn-client';

Basic Usage

function Chat() {
  const {
    processedConversation,
    media,
    isStreaming,
    sendMessage,
  } = useJadeSession();

  return (
    <div>
      {processedConversation.map((entry, i) => (
        <Message key={i} entry={entry} />
      ))}
      <button onClick={() => sendMessage('Generate an image of a sunset')}>
        Generate
      </button>
    </div>
  );
}

Options

interface UseJadeSessionOptions {
  initialSessionId?: string;
  initialConversation?: ConversationEntry[];
  onMediaGenerated?: (urls: string[], type: 'image' | 'video' | 'audio') => void;
  skipSkillContext?: boolean;
  processingOptions?: ProcessingOptions;
  pauseOnBackground?: boolean;  // React Native only
}

Option	Type	Default	Description
`initialSessionId`	`string`	`undefined`	Load an existing session on mount
`initialConversation`	`ConversationEntry[]`	`[]`	Pre-populate conversation
`onMediaGenerated`	`function`	`undefined`	Callback when media is generated
`skipSkillContext`	`boolean`	`true`	Filter out Skill context entries
`processingOptions`	`ProcessingOptions`	`{}`	Options for conversation processing
`pauseOnBackground`	`boolean`	`true`	Pause streaming in background (RN only)

Example with Options

const { processedConversation, media } = useJadeSession({
  initialSessionId: savedSessionId,
  onMediaGenerated: (urls, type) => {
    toast(`Generated ${urls.length} ${type}(s)!`);
  },
  skipSkillContext: true,
  processingOptions: {
    pairToolResults: true,
    extractMedia: true,
  },
});

Return Value

interface UseJadeSessionReturn {
  // Session
  sessionId: string | undefined;
  conversation: ConversationEntry[];
  processedConversation: ProcessedEntry[];
  media: MediaInfo[];

  // Streaming State
  isStreaming: boolean;
  streamingText?: string;
  streamingToolCall?: StreamingToolCall;
  showTinkering: boolean;
  isExecutingTool: boolean;      // React Native only
  executingToolName?: string;    // React Native only

  // Actions
  sendMessage: (prompt: string, skills?: string[]) => Promise<void>;
  cancel: () => Promise<void>;
  clear: () => void;
  reconnect: (sessionId: string, conversation?: ConversationEntry[], streamingPrompt?: string) => Promise<void>;
  loadSession: (sessionId: string) => Promise<ConversationEntry[]>;

  // State Setters
  setSessionId: (id: string | undefined) => void;
  setConversation: (entries: ConversationEntry[], sessionId?: string) => void;
}

Session State

sessionId

Unique identifier for the current session. Created automatically on first message.

const { sessionId } = useJadeSession();
console.log(sessionId); // "sess_abc123..."

conversation

Raw conversation entries from the server.

const { conversation } = useJadeSession();
// Array of ConversationEntry objects

processedConversation

Processed entries ready for display. Includes:

Paired tool calls and results
Extracted media URLs
Parsed tool inputs/outputs
Display metadata (icons, titles)

const { processedConversation } = useJadeSession();
// Array of ProcessedEntry objects

media

All extracted media from the conversation, sorted by timestamp (most recent first).

const { media } = useJadeSession();
// Array of MediaInfo objects

Streaming State

isStreaming

Whether the AI is currently generating a response.

const { isStreaming, sendMessage } = useJadeSession();

<button disabled={isStreaming}>
  {isStreaming ? 'Generating...' : 'Send'}
</button>

streamingText

Current streaming text as it’s being generated.

const { streamingText, isStreaming } = useJadeSession();

{streamingText && (
  <div>
    {streamingText}
    {isStreaming && <Cursor />}
  </div>
)}

streamingToolCall

Information about the tool currently being streamed (before execution).

const { streamingToolCall } = useJadeSession();

{streamingToolCall && (
  <div>Preparing: {streamingToolCall.tool_name}</div>
)}

showTinkering

Whether to show a “thinking” indicator (true when AI is processing but not streaming text).

const { showTinkering } = useJadeSession();

{showTinkering && <ThinkingIndicator />}

isExecutingTool (React Native only)

Whether a tool is currently being executed on the server.

const { isExecutingTool, executingToolName } = useJadeSession();

{isExecutingTool && (
  <View style={styles.toolIndicator}>
    <ActivityIndicator />
    <Text>Running {executingToolName}...</Text>
  </View>
)}

executingToolName (React Native only)

Name of the tool currently being executed.

const { isExecutingTool, executingToolName } = useJadeSession();

// Common tool names:
// - mcp__jade__generative_image
// - mcp__jade__generative_video
// - mcp__jade__generative_audio
// - mcp__jade__background_removal

{executingToolName === 'mcp__jade__generative_image' && (
  <Text>Generating your image...</Text>
)}

Actions

sendMessage

Send a message to start or continue a conversation.

const { sendMessage } = useJadeSession();

// Simple message
await sendMessage('Generate an image of a sunset');

// With skills
await sendMessage('Create a logo', ['design', 'branding']);

cancel

Cancel the current streaming response.

const { cancel, isStreaming } = useJadeSession();

{isStreaming && (
  <button onClick={cancel}>Cancel</button>
)}

clear

Clear the local conversation state (doesn’t delete server session).

const { clear, setSessionId } = useJadeSession();

const handleNewChat = () => {
  clear();
  setSessionId(undefined);
};

reconnect

Reconnect to an existing session, resuming from the last event.

const { reconnect, sessionId } = useJadeSession();

const handleReconnect = async () => {
  await reconnect(sessionId);
};

loadSession

Load a previous session’s conversation.

const { loadSession } = useJadeSession();

const handleSelectSession = async (id: string) => {
  const conversation = await loadSession(id);
  // Conversation is now populated
};

useMedia

Extracts all media URLs from a conversation, providing metadata about each generated item.

Import

React / Next.js
React Native

import { useMedia } from '@gr33n-ai/jade-sdk-client';

import { useMedia } from '@gr33n-ai/jade-sdk-rn-client';

Usage

function MediaGallery({ conversation }) {
  const media = useMedia(conversation);

  return (
    <div className="gallery">
      {media.map(item => (
        <div key={item.url}>
          {item.type === 'image' && <img src={item.url} alt={item.prompt} />}
          {item.type === 'video' && <video src={item.url} controls />}
          {item.type === 'audio' && <audio src={item.url} controls />}
        </div>
      ))}
    </div>
  );
}

Return Value

Returns an array of MediaInfo objects:

interface MediaInfo {
  url: string;                        // CDN URL of the media
  type: 'image' | 'video' | 'audio';  // Type of media
  timestamp: string;                  // ISO 8601 timestamp
  toolName?: string;                  // Tool that generated it
  toolUseId?: string;                 // Unique tool use ID
  prompt?: string;                    // Generation prompt
  model?: string;                     // AI model used
  aspectRatio?: string;               // Aspect ratio (e.g., "16:9")
  inputMediaUrls?: string[];          // Input media used for processing
}

Features

Deduplication: Media URLs are automatically deduplicated
Sorting: Media is sorted by timestamp, most recent first
Metadata Extraction: Rich metadata from tool calls

vs useJadeSession.media

useJadeSession already provides media in its return value:

// This works - useJadeSession includes media extraction
const { media } = useJadeSession();

// Use useMedia separately when:
// 1. You have conversation data from another source
// 2. You need media from a subset of the conversation
// 3. You're building a component that receives conversation as a prop
const media = useMedia(someConversation);

ProcessedEntry

The ProcessedEntry type represents a conversation entry processed for display.

Structure

interface ProcessedEntry {
  // Original entry
  entry: ConversationEntry;

  // Type information
  originalType: 'tool_call' | 'tool_result' | 'assistant_text' | 'user_text' | 'compact' | 'error';
  displayType: string;

  // Display metadata
  iconName: string;
  iconData?: unknown;
  title?: string;
  timestamp: string;
  data: Record<string, unknown>;

  // Tool-specific
  toolDefinition?: ToolDefinition;
  parsedInput?: ParsedToolInput;
  parsedResult?: ParsedToolResult;
  consumedResult?: ConversationEntry;

  // Media
  mediaUrls?: string[];

  // Suggestions
  suggestions?: ParsedSuggestion[];
  textSegments?: TextSegment[];
}

Rendering Entries

function Message({ entry }: { entry: ProcessedEntry }) {
  switch (entry.originalType) {
    case 'user_text':
      return <UserMessage text={entry.entry.text} />;

    case 'assistant_text':
      return <AssistantMessage text={entry.entry.text} />;

    case 'tool_call':
      return <ToolMessage entry={entry} />;

    case 'error':
      return <ErrorMessage text={entry.entry.text} />;

    default:
      return null;
  }
}

Tool-Specific Rendering

function ToolMessage({ entry }: { entry: ProcessedEntry }) {
  switch (entry.displayType) {
    case 'generative_image':
      return <ImageGeneration entry={entry} />;

    case 'generative_video':
      return <VideoGeneration entry={entry} />;

    case 'generative_audio':
      return <AudioGeneration entry={entry} />;

    default:
      return <GenericTool entry={entry} />;
  }
}

function ImageGeneration({ entry }: { entry: ProcessedEntry }) {
  const { parsedInput, mediaUrls } = entry;

  return (
    <div className="image-generation">
      <h4>{entry.title}</h4>
      {parsedInput?.data?.prompt && (
        <p className="prompt">{parsedInput.data.prompt}</p>
      )}
      {mediaUrls?.map(url => (
        <img key={url} src={url} alt={parsedInput?.data?.prompt || ''} />
      ))}
    </div>
  );
}

Rendering Suggestions

Text may contain <gr3.suggestion> tags that are parsed into segments:

function MessageWithSuggestions({ entry }: { entry: ProcessedEntry }) {
  const { textSegments } = entry;

  if (!textSegments || textSegments.length === 0) {
    return <p>{entry.entry.text}</p>;
  }

  return (
    <p>
      {textSegments.map((segment, i) => (
        segment.type === 'suggestion' ? (
          <button
            key={i}
            className="suggestion"
            onClick={() => handleSuggestion(segment.content)}
          >
            {segment.content}
          </button>
        ) : (
          <span key={i}>{segment.content}</span>
        )
      ))}
    </p>
  );
}

Client Hooks

Access the underlying client for direct API calls.

React / Next.js
React Native

import { useAgentClient } from '@gr33n-ai/jade-sdk-client';

function SessionList() {
  const client = useAgentClient();
  const [sessions, setSessions] = useState([]);

  useEffect(() => {
    client.listSessions().then(res => setSessions(res.sessions));
  }, []);

  // ...
}

import { useJadeClient } from '@gr33n-ai/jade-sdk-rn-client';

function SessionList() {
  const client = useJadeClient();
  const [sessions, setSessions] = useState([]);

  useEffect(() => {
    client.listSessions().then(res => setSessions(res.sessions));
  }, []);

  // ...
}

React Native-Specific Hooks

These hooks are only available in the React Native package.

useJadeSessionCore

Lower-level session hook without Jade-specific processing. Use when you need raw conversation data.

import { useJadeSessionCore } from '@gr33n-ai/jade-sdk-rn-client';

const {
  sessionId,
  conversation,         // Raw ConversationEntry[]
  isStreaming,
  streamingText,
  streamingToolCall,
  showTinkering,
  isExecutingTool,      // True when tool is running on server
  executingToolName,    // Name of the executing tool
  sendMessage,
  cancel,
} = useJadeSessionCore();

useStorage

Access the storage adapter:

import { useStorage } from '@gr33n-ai/jade-sdk-rn-client';

function Preferences() {
  const storage = useStorage();

  const saveSetting = async (key: string, value: string) => {
    if (storage) {
      await storage.setItem(`@settings/${key}`, value);
    }
  };
}

useAppState

Get the current app state:

import { useAppState } from '@gr33n-ai/jade-sdk-rn-client';

function StreamingStatus() {
  const appState = useAppState();
  const { isStreaming } = useJadeSession();

  if (appState !== 'active' && isStreaming) {
    return <Text>Streaming paused - return to app</Text>;
  }

  return null;
}

Value	Description
`'active'`	App is in foreground
`'background'`	App is in background
`'inactive'`	App is transitioning

Complete Example

import { useState, useEffect } from 'react';
import { useJadeSession } from '@gr33n-ai/jade-sdk-client';

function ChatInterface() {
  const [input, setInput] = useState('');
  const {
    processedConversation,
    media,
    isStreaming,
    streamingText,
    showTinkering,
    sendMessage,
    cancel,
  } = useJadeSession({
    onMediaGenerated: (urls, type) => {
      console.log(`Generated ${type}:`, urls);
    },
  });

  const handleSubmit = async (e: React.FormEvent) => {
    e.preventDefault();
    if (input.trim() && !isStreaming) {
      await sendMessage(input);
      setInput('');
    }
  };

  return (
    <div>
      {processedConversation.map((entry, i) => (
        <div key={i} className={`message ${entry.originalType}`}>
          <strong>{entry.title || entry.displayType}</strong>
          <p>{entry.entry.text}</p>
          {entry.mediaUrls?.map(url => (
            <img key={url} src={url} alt="" />
          ))}
        </div>
      ))}

      {streamingText && <div className="streaming">{streamingText}</div>}
      {showTinkering && <div className="thinking">Thinking...</div>}

      <form onSubmit={handleSubmit}>
        <input
          value={input}
          onChange={e => setInput(e.target.value)}
          placeholder="Type a message..."
          disabled={isStreaming}
        />
        <button type="submit" disabled={isStreaming}>
          Send
        </button>
        {isStreaming && <button onClick={cancel}>Cancel</button>}
      </form>

      {media.length > 0 && (
        <div className="gallery">
          {media.map(m => (
            <img key={m.url} src={m.url} alt={m.prompt} />
          ))}
        </div>
      )}
    </div>
  );
}

JadeProvider - Provider setup
Streaming Guide - SSE patterns
Types Reference - Full type definitions

​useJadeSession

​Import

​Basic Usage

​Options

​Example with Options

​Return Value

​Session State

​sessionId

​conversation

​processedConversation

​media

​Streaming State

​isStreaming

​streamingText

​streamingToolCall

​showTinkering

​isExecutingTool (React Native only)

​executingToolName (React Native only)

​Actions

​sendMessage

​cancel

​clear

​reconnect

​loadSession

​useMedia

​Import

​Usage

​Return Value

​Features

​vs useJadeSession.media

​ProcessedEntry

​Structure

​Rendering Entries

​Tool-Specific Rendering

​Rendering Suggestions

​Client Hooks

​React Native-Specific Hooks

​useJadeSessionCore

​useStorage

​useAppState

​Complete Example

​Related

useJadeSession

Import

Basic Usage

Options

Example with Options

Return Value

Session State

sessionId

conversation

processedConversation

media

Streaming State

isStreaming

streamingText

streamingToolCall

showTinkering

isExecutingTool (React Native only)

executingToolName (React Native only)

Actions

sendMessage

cancel

clear

reconnect

loadSession

useMedia

Import

Usage

Return Value

Features

vs useJadeSession.media

ProcessedEntry

Structure

Rendering Entries

Tool-Specific Rendering

Rendering Suggestions

Client Hooks

React Native-Specific Hooks

useJadeSessionCore

useStorage

useAppState

Complete Example

Related