React

@kortix/sdk/react: useSession for a whole session view, a chat kit, and data hooks for everything else.

@kortix/sdk/react is the React layer of the SDK. It gives you one hook that runs a whole session view, a headless chat kit, and data hooks for accounts, projects, sessions, secrets, triggers, Apps, notifications and access checks. It works in React and React Native.

Set up

npm install @kortix/sdk react @tanstack/react-query

// lib/kortix.ts
import { createKortix } from '@kortix/sdk';

export const kortix = createKortix({
  backendUrl: 'https://api.kortix.com/v1',
  getToken: async () => getMyToken(),
});

'use client';
import '@/lib/kortix';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { useState } from 'react';

export function Providers({ children }: { children: React.ReactNode }) {
  const [queryClient] = useState(() => new QueryClient());
  return <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>;
}

Keep one client and one QueryClient per host. A second createKortix() call with other options re-points every earlier client.

useSession

useSession(projectId, sessionId, options?) runs one session view end to end. It polls POST /start until the sandbox is ready, opens the event stream, syncs messages and status, paints saved history, and sends prompts. Call it once per session view.

import { useSession } from '@kortix/sdk/react';

export function SessionView({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const s = useSession(projectId, sessionId);

  if (s.messages.length === 0 && s.phase !== 'ready') {
    if (s.phase === 'error') return <NotRunning stage={s.stage} onRetry={s.retry} />;
    if (s.conversationEmpty) return <Composer onSend={s.send} />;
    return s.savedTranscript === 'none' ? <Booting stage={s.stage} /> : <MessageSkeleton />;
  }

  return (
    <>
      {s.messages.map(({ info, parts }) => (
        <Message key={info.id} info={info} parts={parts} />
      ))}
      {s.sendError && <SendError error={s.sendError} />}
      <Composer busy={s.isBusy} disabled={s.phase !== 'ready'} onSend={s.send} onStop={s.cancel} />
    </>
  );
}

The sandbox is ready when /start answers stage: 'ready'. The hook runs no separate health check. While the session starts, render by this rule:

Saved history is the transcript copy the API writes at each turn end. The first window holds the newest 40 messages, at most 1,000,000 characters. loadOlder() reads older windows, also while the sandbox is off. Live messages then reconcile into it by message id.

To show a sub-agent’s saved history, call useSessionSync(childRuntimeSessionId, { kortixSessionScope: sessionId, savedChild: true }). It reads the child’s saved window from the parent session. The device keeps no copy of it.

Returns

Actions

The three reply actions remove the item only after the server accepts the reply. On failure they throw a KortixSendError and the item stays open. removeQuestion and removePermission are deprecated: they never reach the agent, so the run stays blocked.

Options

Send errors

sendError, rewindError and the reply actions use one type, KortixSendError: { kind, message, cause } plus one detail field per kind. message is ready to display.

classifySendError(error) turns any thrown value into a KortixSendError.

Pending prompts and turn outcomes

send covers a composer that sends one prompt at a time. Use these hooks for a queue, for steering a running turn, and to say why a turn ended. They take the same projectId and sessionId as useSession.

useSessionPrompts

useSessionPrompts(projectId, sessionId) reads and writes the session’s prompt inbox on the server. The server delivers pending prompts in order, as delivery says.

edit, remove and interrupt throw a 409 for a row that is already on its way to the runtime.

enqueue takes delivery (steer, queue or interrupt) and an optional placement. The delivery modes and steer_fallback are in Sessions from code. placement only says where the pending row shows: transcript in the message list (implied by interrupt), composer in the list above the input (implied by steer and queue).

useSessionWorking

useSessionWorking(projectId, sessionId, { runtimeSessionId }) returns the same WorkingProjection as useSession().working. It stays working while a prompt waits in the inbox, and sets pendingDelivery: true while that prompt is still on its way. Keep Stop visible whenever state is working.

Why a turn ended

An interrupted turn’s transcript carries only an abort error. The API records the cause the sandbox named, for example its memory guard. A stop that someone asked for is never a failure.

import { turnEndNotice } from '@kortix/sdk';
import { useSessionTurnOutcome } from '@kortix/sdk/react';

const outcome = useSessionTurnOutcome(projectId, sessionId);
const notice = turnEndNotice(outcome, userMessageId, { hasError, isAbort });
// { kind: 'sandbox-memory', usedPct, detail }
// | { kind: 'cause', name, message }
// | { kind: 'unexplained' }
// | null

Pass the id of the user message that started the turn. hasError is true when the transcript shows an error on that turn, and isAbort is true when that error is an abort. A non-abort error returns null, because the transcript already explains it.

useSessionTurnOutcome makes no request. It reads the cache that useSessionWorking keeps fresh. Map each kind to your own copy. null means show what the transcript shows. turnEndCause(outcome, messageId) returns the raw recorded cause, or null.

Build a chat UI

messages are runtime messages. The chat kit turns each one into typed parts you can render with no knowledge of the harness.

import { toolViewModel } from '@kortix/sdk';
import { renderParts, useChatTurns, type UseSessionResult } from '@kortix/sdk/react';

function Transcript({ messages }: { messages: UseSessionResult['messages'] }) {
  const turns = useChatTurns(messages);
  return turns.map((turn) =>
    turn.isEmpty ? null : (
      <Row key={turn.message.info.id} role={turn.message.info.role} error={turn.error}>
        {renderParts(turn.parts, {
          text: (p) => (p.synthetic ? null : <Markdown key={p.id}>{p.text}</Markdown>),
          reasoning: (p) => <Thinking key={p.id} text={p.text} />,
          tool: (p) => <ToolCard key={p.id} view={toolViewModel(p.tool)} status={p.tool.status} />,
          file: (p) => <Attachment key={p.id} part={p} />,
          subtask: (p) => <Subtask key={p.id} part={p} />,
          patch: () => null,
          snapshot: () => null,
          agent: () => null,
          retry: (p) => <RetryNotice key={p.id} part={p} />,
          compaction: () => <CompactedNotice />,
          step: () => null,
          unknown: () => null,
        })}
      </Row>
    ),
  );
}

Part kinds: text, reasoning, tool, file, subtask, patch, snapshot, agent, retry, compaction, step and unknown. A text part with synthetic: true is internal to the runtime; skip it.

A streaming turn changes the transcript about every 16 ms. To keep the rest of the view still, call useSession(projectId, sessionId, { subscribeMessages: false }) in the view, and read the rows in the transcript component with useSessionMessages(session). Pass the whole useSession result. Only that component re-renders per delta. useSessionMessages(session, { throttleMs }) paces the updates.

More on parts, tools and turn grouping: SDK reference.

Read the session log

useSessionLog(session) returns the whole session log (SessionLog): every thread, its messages by seq, and their blocks. useSessionLogThread(session, threadId?) returns one thread: the root thread, or the sub-agent thread threadId names. Pass the whole useSession result. Both start no request: useSession loads the log.

import { useSession, useSessionLogThread } from '@kortix/sdk/react';

function Thread({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const session = useSession(projectId, sessionId, { subscribeMessages: false });
  const root = useSessionLogThread(session);
  if (!root) return null; // the session reads v1: render useSessionMessages(session)
  return <ol>{root.messages.map((m) => <li key={m.message_id}>{m.role}: {m.blocks.length} blocks</li>)}</ol>;
}

A session reads the log only when all of these are true. Otherwise it reads v1, and both hooks return null.

1. The runtime’s /kortix/health lists session.log.v2. An absent list does not count.
2. The project flag session_log is true.
3. The API has a stored log for the session (GET /v1/projects/:projectId/sessions/:sessionId/log answers a page).
4. The session’s thread was converted from v1 (OpenCode). A pi session reads v1.

An SDK older than its API, or an API older than its SDK, reads v1. On v2, useSession paints the device’s saved copy of the log first, then the API’s page, and asks the session stream for schema=v2. What the stream carries depends on the server:

• The runtime side is complete: on schema=v2 the runtime’s stream carries log.* frames in place of the message.* transcript frames, plus every other frame (status, permissions, questions, todos). A message arrives as a streaming record when it starts, then grows with each streamed delta.
• The API does not relay schema yet; that is the remaining step. Until it does, the stream keeps the v1 frames, and a turn in progress streams through them as before.

A session without a stored log yet (a new one) reads v1 and tries the log again at the end of each turn. useSessionMessages, useSession().messages and classifyTurn return the same rows either way. In a thread converted from v1 (OpenCode), a session-log message converts with toV1, the conversion the API uses for v1 readers, and replaces the v1 row with the same id. A pi thread keeps the v1 rows, as the API’s v1 reads do. A deleted message stays out. A row the log does not hold yet, such as the streaming turn or an optimistic send, keeps its place. A row keeps its identity while its message is unchanged.

Hooks

Most hooks below are React Query hooks. Unless the row names another return value, a hook returns the query result (data, isLoading, error, …) plus the mutations the row names. A write refreshes the matching reads.

Rules that apply to several hooks:

• useCan and its siblings decide what to show and enable. The API checks every write again. Ask for the action the route checks, for example project.gitops.push, never for a role. After a write that changes access, call invalidatePermissionProbes(queryClient, { accountId, userId }). A verdict is cached for 5 minutes until then. Action names are in Accounts & access.
• The three notification hooks key their cache by userId. Pass the signed-in person’s id. Gate each with enabled: useFeatureFlag(projectId, 'notification_center').enabled. The flag is off by default. See Notifications.
• After a runtime restart or a config reload, call resetRuntimeQueries(queryClient). The next read then comes from the new runtime.

Fast opens and offline

Start the open read early

prefetchSessionOpen(queryClient, projectId, sessionId) starts the read that a session view needs before the view mounts. It sends one GET …/snapshot request: the session row, the current turn, the prompt queue and the first transcript window. useSession then uses that request instead of its own.

import { prefetchSessionOpen } from '@kortix/sdk/react';
import { useQueryClient } from '@tanstack/react-query';

function SessionLink({ projectId, sessionId }: { projectId: string; sessionId: string }) {
  const queryClient = useQueryClient();
  const warm = () => void prefetchSessionOpen(queryClient, projectId, sessionId);
  return <a href={`/sessions/${sessionId}`} onPointerEnter={warm} onFocus={warm} />;
}

Call it on hover, focus or touch of a session link, or when a route names a session. It never calls /start, so it never wakes a sandbox. It never rejects. A second call for the same session within 30 seconds sends nothing.

Render from the device on a reload

Two stores keep what a person already saw, so a reload or a cold start paints it in the first frame. The server’s answer then refreshes it in place. Both stores are per user and bounded. They come from @kortix/sdk.

import type { QueryClient } from '@tanstack/react-query';
import {
  browserKeyValueStorage,
  createPersistedQueryCache,
  createSavedCopyStore,
  isPersistableQueryKey,
  setSavedCopyStore,
} from '@kortix/sdk';

export function adoptDeviceCaches(queryClient: QueryClient, userId: string) {
  const storage = browserKeyValueStorage(); // null where localStorage is blocked or absent
  if (!storage) return null;
  const cache = createPersistedQueryCache({ storage, userId, shouldPersist: isPersistableQueryKey });
  cache.restore(queryClient); // synchronous with localStorage
  const stop = cache.persist(queryClient);
  window.addEventListener('pagehide', () => void cache.flush());
  const copies = createSavedCopyStore({ storage, userId });
  setSavedCopyStore(copies);
  return { cache, copies, stop };
}

• persist writes at most once per second. Call flush() on pagehide, so a reload keeps the last change.
• On React Native, pass AsyncStorage as storage. restore then returns a promise.
• The saved-copy store keeps only copies the server sent at a turn end, never the live transcript. A stopped turn cannot come back as a running one.
• A full, corrupt or missing store never throws. The app then opens from the server, as without the store.

Sign-out and identity changes

The SDK keeps per-person session state in memory: transcripts, open questions and permissions, turn receipts and model picks. On every identity change, clear it and your caches in one handler. An identity change is a sign-out, a different person signing in, and a sign-in in another tab that changes the person without a page load.

import type { QueryClient } from '@tanstack/react-query';
import { setSavedCopyStore } from '@kortix/sdk';
import { resetIdentityState } from '@kortix/sdk/react';

export async function onIdentityChange(queryClient: QueryClient, device: ReturnType<typeof adoptDeviceCaches>) {
  setSavedCopyStore(null);
  device?.stop();
  queryClient.clear();
  resetIdentityState();
  await device?.cache.clear();
  await device?.copies.clear();
}

resetIdentityState() never throws. It also removes the model picks from localStorage. It does not clear React Query, your own stores or the token source you passed to createKortix. Reset those in the same handler. Neither device store ever restores data for another person, but a signed-out device must not keep it.