@possibl/rcrt-sdk 0.1.2 → 0.1.3

package/src/internal/sse.ts

@@ -1,236 +0,0 @@
-/**
- * SSE client with automatic reconnection + typed event dispatch.
- *
- * Works in three environments:
- *   - Browsers: uses the built-in `EventSource`. Auth goes via query
- *     params because `EventSource` can't set custom headers.
- *   - Node 18+: uses the built-in `EventSource` (Node 22+) or a
- *     pluggable polyfill (see `config.eventSource`).
- *   - React Native: install `react-native-sse` and pass its
- *     constructor as `config.eventSource`. Custom headers work there.
- *
- * Subscribers get typed events. Streams auto-reconnect with
- * exponential backoff unless `close()` was called explicitly.
- */
-
-import type { Breadcrumb } from '../types/breadcrumb.js';
-
-export interface SseConnectConfig {
-  apiUrl: string;
-  path: string;
-  tenantId: string | null;
-  getToken: () => Promise<string>;
-  /** Override the EventSource implementation. Required in React Native. */
-  eventSource?: EventSourceConstructor;
-  /** Max reconnect delay in ms. Default 30000. */
-  maxBackoffMs?: number;
-  /** Extra query params (e.g. `?last_event_id=...`). */
-  query?: Record<string, string>;
-  /** Disable the query-param token fallback; requires a custom EventSource impl. */
-  useHeaderAuth?: boolean;
-}
-
-export interface SseDelta {
-  delta: string;
-  agent_id: string;
-  is_final: boolean;
-}
-
-export interface SseThought {
-  steps: string[];
-  agent_id?: string;
-}
-
-export interface SseAction {
-  tool_name: string;
-  status: 'running' | 'completed' | 'failed';
-  request_id?: string;
-}
-
-export interface SseError {
-  code?: string;
-  message?: string;
-  fatal?: boolean;
-}
-
-export interface SseHandlers {
-  onConnected?: (payload: { session_id?: string; user_id?: string }) => void;
-  onDelta?: (data: SseDelta) => void;
-  onMessage?: (data: Breadcrumb) => void;
-  onThought?: (data: SseThought) => void;
-  onAction?: (data: SseAction) => void;
-  onError?: (data: SseError, isFatal: boolean) => void;
-  /** Fires any time the underlying SSE connection opens. */
-  onOpen?: () => void;
-  /** Fires any time the underlying SSE connection closes (before a reconnect attempt). */
-  onClose?: () => void;
-}
-
-type EventSourceConstructor = new (url: string, init?: EventSourceInit & { headers?: Record<string, string> }) => EventSourceLike;
-
-interface EventSourceLike {
-  readonly readyState: 0 | 1 | 2;
-  close(): void;
-  addEventListener(type: string, listener: (ev: MessageEvent | Event) => void): void;
-  onerror: ((ev: Event) => void) | null;
-  onopen: ((ev: Event) => void) | null;
-}
-
-export interface SseConnection {
-  /** Close the stream. No more reconnects. */
-  close(): void;
-  /** Current state — for UI reconnection indicators. */
-  readonly state: 'connecting' | 'open' | 'closed';
-}
-
-export function connect(config: SseConnectConfig, handlers: SseHandlers): SseConnection {
-  const maxBackoff = config.maxBackoffMs ?? 30_000;
-  let backoff = 1_000;
-  let closed = false;
-  let es: EventSourceLike | null = null;
-  let state: 'connecting' | 'open' | 'closed' = 'connecting';
-  let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
-
-  async function open(): Promise<void> {
-    if (closed) return;
-
-    const token = await config.getToken();
-    const u = new URL(config.apiUrl.replace(/\/$/, '') + config.path);
-    if (config.query) {
-      for (const [k, v] of Object.entries(config.query)) {
-        u.searchParams.set(k, v);
-      }
-    }
-
-    const EventSourceCtor: EventSourceConstructor = (config.eventSource
-      ?? (globalThis as unknown as { EventSource?: EventSourceConstructor }).EventSource) as EventSourceConstructor;
-    if (!EventSourceCtor) {
-      handlers.onError?.({ message: 'No EventSource implementation available. Pass config.eventSource for React Native.', fatal: true }, true);
-      closed = true;
-      state = 'closed';
-      return;
-    }
-
-    // Prefer header auth when the EventSource impl supports it (React
-    // Native with `react-native-sse`, Node 22+, any custom
-    // `config.eventSource` that accepts a `headers` init). The browser's
-    // built-in EventSource constructor has NO support for custom
-    // headers — there's no proposal in the WHATWG spec to change that —
-    // so when we're stuck with it we fall back to passing the bearer
-    // token and tenant ID as query params.
-    //
-    // Security note (Sonar hotspot review): tokens in URLs are a
-    // documented smell — they can leak via proxy logs, HTTP Referer
-    // headers, and browser history. We mitigate:
-    //   * TLS is assumed (RCRT's api-gateway rejects plaintext HTTP).
-    //   * Firebase ID tokens are short-lived (60 min) and auto-rotated.
-    //     A leaked token in a server log expires fast; it can't be used
-    //     to escalate outside the scope Firebase already granted.
-    //   * `tk_*` workspace API keys are long-lived and should NEVER be
-    //     passed through this path. Callers holding a tk_ key are
-    //     server-side and must set `useHeaderAuth: true`. The SDK docs
-    //     and the TokenProvider interface make this explicit.
-    //   * This fallback only triggers for SSE subscriptions. The regular
-    //     fetch-based surface (`src/internal/fetch.ts`) always uses the
-    //     Authorization header.
-    // Without this fallback the SDK cannot open SSE connections from a
-    // browser at all, which would break every chat UI built on RCRT.
-    const init: EventSourceInit & { headers?: Record<string, string> } = {};
-    if (config.useHeaderAuth) {
-      init.headers = {
-        Authorization: `Bearer ${token}`,
-        ...(config.tenantId ? { 'X-Tenant-ID': config.tenantId } : {}),
-      };
-    } else {
-      u.searchParams.set('token', token); // NOSONAR - required for browser EventSource; see block comment above
-      if (config.tenantId) u.searchParams.set('tenant_id', config.tenantId);
-    }
-
-    try {
-      es = new EventSourceCtor(u.toString(), init);
-    } catch (err) {
-      handlers.onError?.({ message: (err as Error).message, fatal: true }, true);
-      scheduleReconnect();
-      return;
-    }
-
-    es.onopen = () => {
-      backoff = 1_000;
-      state = 'open';
-      handlers.onOpen?.();
-    };
-
-    es.addEventListener('connected', (e) => {
-      const data = tryJson((e as MessageEvent).data);
-      handlers.onConnected?.(data as { session_id?: string; user_id?: string });
-    });
-
-    es.addEventListener('delta', (e) => {
-      const data = tryJson<SseDelta>((e as MessageEvent).data);
-      if (data) handlers.onDelta?.(data);
-    });
-
-    es.addEventListener('message', (e) => {
-      const data = tryJson<Breadcrumb>((e as MessageEvent).data);
-      if (data) handlers.onMessage?.(data);
-    });
-
-    es.addEventListener('thought', (e) => {
-      const data = tryJson<SseThought>((e as MessageEvent).data);
-      if (data) handlers.onThought?.(data);
-    });
-
-    es.addEventListener('action', (e) => {
-      const data = tryJson<SseAction>((e as MessageEvent).data);
-      if (data) handlers.onAction?.(data);
-    });
-
-    es.addEventListener('error', (e) => {
-      const data = tryJson<SseError>((e as MessageEvent | undefined)?.data ?? '');
-      handlers.onError?.(data ?? { message: 'stream error' }, false);
-    });
-
-    es.onerror = () => {
-      state = 'closed';
-      handlers.onClose?.();
-      es?.close();
-      es = null;
-      scheduleReconnect();
-    };
-  }
-
-  function scheduleReconnect() {
-    if (closed) return;
-    state = 'connecting';
-    const delay = backoff + Math.floor(Math.random() * 500);
-    backoff = Math.min(maxBackoff, backoff * 2);
-    reconnectTimer = setTimeout(() => {
-      reconnectTimer = null;
-      void open();
-    }, delay);
-  }
-
-  void open();
-
-  return {
-    close() {
-      closed = true;
-      state = 'closed';
-      if (reconnectTimer) clearTimeout(reconnectTimer);
-      es?.close();
-      es = null;
-    },
-    get state() {
-      return state;
-    },
-  };
-}
-
-function tryJson<T = unknown>(raw: unknown): T | undefined {
-  if (typeof raw !== 'string' || !raw) return undefined;
-  try {
-    return JSON.parse(raw) as T;
-  } catch {
-    return undefined;
-  }
-}

package/src/sessions.ts

@@ -1,110 +0,0 @@
-/**
- * Sessions module — multi-agent / multi-participant session metadata.
- *
- * The `chat.send()` + `chat.sessionStream()` flow gives you the
- * per-turn read/write loop. This module is for everything around the
- * session: who's in it (participants — agents AND users), and the
- * cross-session graph view (constellation).
- *
- * See `packages/docs/guides/03-chat-and-sse.md` for how sessions
- * relate to breadcrumbs.
- */
-
-import type { FetchContext } from './internal/fetch.js';
-import { request } from './internal/fetch.js';
-import { ApiError } from './errors.js';
-
-export interface SessionParticipant {
-  /** Either `agent` (id is an agent name like `life-coordinator`) or `user` (id is a UUID). */
-  type: 'agent' | 'user';
-  id: string;
-  /** Human-friendly label. May be undefined for never-renamed participants. */
-  name?: string;
-  invited_by?: string;
-  joined_at?: string;
-}
-
-export interface ConstellationNode {
-  session_id: string;
-  title?: string;
-  topics?: string[];
-  message_count?: number;
-  last_active?: string;
-  primary_agent?: string;
-  participant_ids?: string[];
-}
-
-export interface ConstellationEdge {
-  /** Two session ids the constellation maps as related. */
-  a: string;
-  b: string;
-  /** Reason for the relationship — e.g. `shared_topic:health`, `shared_participant:life-coordinator`. */
-  reason: string;
-}
-
-export interface ConstellationData {
-  nodes: ConstellationNode[];
-  edges: ConstellationEdge[];
-}
-
-export class SessionsModule {
-  constructor(private readonly ctx: FetchContext) {}
-
-  /**
-   * `GET /v1/sessions/constellation` — graph view across all the
-   * caller's sessions, grouped by topic / shared participant.
-   *
-   * Returns `null` when the constellation endpoint is unavailable
-   * or the user has zero sessions to graph.
-   */
-  async getConstellation(limit: number = 50): Promise<ConstellationData | null> {
-    try {
-      return await request<ConstellationData>(this.ctx, '/v1/sessions/constellation', {
-        query: { limit },
-      });
-    } catch (err) {
-      if (err instanceof ApiError && (err.status === 404 || err.status === 204)) {
-        return null;
-      }
-      throw err;
-    }
-  }
-
-  /** `GET /v1/sessions/{id}/participants` — agents + users currently in the session. */
-  async listParticipants(sessionId: string): Promise<SessionParticipant[]> {
-    const res = await request<{ participants: SessionParticipant[] } | SessionParticipant[]>(
-      this.ctx,
-      `/v1/sessions/${sessionId}/participants`,
-    );
-    return Array.isArray(res) ? res : (res.participants ?? []);
-  }
-
-  /**
-   * `POST /v1/sessions/{id}/participants` — invite an agent into the
-   * session. The agent will see subsequent turns and may respond.
-   */
-  async addParticipant(
-    sessionId: string,
-    agentId: string,
-    options: { invitedBy?: string } = {},
-  ): Promise<void> {
-    await request<void>(this.ctx, `/v1/sessions/${sessionId}/participants`, {
-      method: 'POST',
-      body: { agent_id: agentId, invited_by: options.invitedBy },
-    });
-  }
-
-  /** `DELETE /v1/sessions/{id}/participants/{agent_id}` — drop an agent from the session. */
-  async removeParticipant(sessionId: string, agentId: string): Promise<void> {
-    try {
-      await request<void>(
-        this.ctx,
-        `/v1/sessions/${sessionId}/participants/${agentId}`,
-        { method: 'DELETE' },
-      );
-    } catch (err) {
-      if (err instanceof ApiError && err.status === 404) return; // idempotent
-      throw err;
-    }
-  }
-}

package/src/types/breadcrumb.ts

@@ -1,77 +0,0 @@
-/**
- * Breadcrumb — the fundamental record of RCRT.
- *
- * Every meaningful state change in the system is a breadcrumb. See
- * `packages/docs/concepts/02-primitives.md` for the mental model.
- */
-
-export type ActorType = 'user' | 'agent' | 'tool' | 'system';
-
-export interface Actor {
-  type: ActorType;
-  /** For users: the user UUID. For agents: the agent id. For tools: the tool name. */
-  id: string;
-}
-
-export interface Breadcrumb {
-  id: string;
-  tenant_id: string;
-  name: string;
-  title: string;
-  content: Record<string, unknown>;
-  /** AND-semantics when queried. Prefix conventions: `interpret:*`, `service:*`, `session:*`, `user:*`, etc. */
-  tags: string[];
-  /** Breadcrumbs this derived from (SAPL provenance chain). */
-  parent_ids: string[];
-  /** Optimistic locking. PATCH must include the current value. */
-  version: number;
-  created_by: Actor;
-  created_at: string;
-  updated_at: string;
-  deleted_at: string | null;
-  /** Optional embedding for semantic search. */
-  embedding?: number[];
-  /** Relative TTL — e.g. "24h", "30d". */
-  ttl?: string;
-}
-
-export interface CreateBreadcrumbRequest {
-  name?: string;
-  title: string;
-  content: Record<string, unknown>;
-  tags?: string[];
-  parent_ids?: string[];
-  created_by?: Actor;
-  ttl?: string;
-  /** If a breadcrumb with the same name + tags exists, update it rather than inserting a new row. */
-  upsert?: boolean;
-}
-
-export interface UpdateBreadcrumbRequest {
-  /** Required. Optimistic locking fails with 409 Conflict otherwise. */
-  version: number;
-  title?: string;
-  content?: Record<string, unknown>;
-  tags?: string[];
-  parent_ids?: string[];
-  ttl?: string;
-}
-
-export interface BreadcrumbResponse {
-  breadcrumb: Breadcrumb;
-  action?: 'created' | 'updated';
-}
-
-export interface QueryByTagsOptions {
-  /** Max rows to return. Server max is 200. */
-  limit?: number;
-  offset?: number;
-  /** Exact name match. */
-  name?: string;
-  order?: 'newest' | 'oldest';
-}
-
-export interface SemanticSearchOptions {
-  limit?: number;
-  tags?: string[];
-}