@starcite/sdk 0.0.3 → 0.0.5

package/dist/index.d.ts

@@ -1,48 +1,60 @@
 import { z } from 'zod';
 
-/**
- * Request payload for creating a session.
- */
-declare const CreateSessionInputSchema: z.ZodObject<{
-    id: z.ZodOptional<z.ZodString>;
-    title: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    creator_principal: z.ZodOptional<z.ZodObject<{
-        tenant_id: z.ZodString;
-        id: z.ZodString;
-        type: z.ZodUnion<[z.ZodLiteral<"user">, z.ZodLiteral<"agent">]>;
-    }, "strip", z.ZodTypeAny, {
-        type: "user" | "agent";
-        tenant_id: string;
-        id: string;
-    }, {
-        type: "user" | "agent";
-        tenant_id: string;
-        id: string;
-    }>>;
+declare const PrincipalTypeSchema: z.ZodEnum<["user", "agent"]>;
+type PrincipalType = z.infer<typeof PrincipalTypeSchema>;
+declare const SessionCreatorPrincipalSchema: z.ZodObject<{
+    tenant_id: z.ZodString;
+    id: z.ZodString;
+    type: z.ZodEnum<["user", "agent"]>;
 }, "strip", z.ZodTypeAny, {
-    id?: string | undefined;
-    title?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    creator_principal?: {
-        type: "user" | "agent";
-        tenant_id: string;
-        id: string;
-    } | undefined;
+    type: "user" | "agent";
+    tenant_id: string;
+    id: string;
 }, {
-    id?: string | undefined;
-    title?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    creator_principal?: {
-        type: "user" | "agent";
-        tenant_id: string;
-        id: string;
-    } | undefined;
+    type: "user" | "agent";
+    tenant_id: string;
+    id: string;
+}>;
+type SessionCreatorPrincipal = z.infer<typeof SessionCreatorPrincipalSchema>;
+declare const SessionTokenPrincipalSchema: z.ZodObject<{
+    type: z.ZodEnum<["user", "agent"]>;
+    id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    type: "user" | "agent";
+    id: string;
+}, {
+    type: "user" | "agent";
+    id: string;
 }>;
+type SessionTokenPrincipal = z.infer<typeof SessionTokenPrincipalSchema>;
 /**
- * Inferred TypeScript type for {@link CreateSessionInputSchema}.
+ * Represents a resolved caller identity with tenant, principal id, and type.
  */
-type CreateSessionInput = z.infer<typeof CreateSessionInputSchema>;
+declare class StarciteIdentity {
+    readonly tenantId: string;
+    readonly id: string;
+    readonly type: PrincipalType;
+    constructor(options: {
+        tenantId: string;
+        id: string;
+        type: PrincipalType;
+    });
+    /**
+     * Serializes to the `creator_principal` wire format expected by the API.
+     */
+    toCreatorPrincipal(): SessionCreatorPrincipal;
+    /**
+     * Serializes to the `principal` wire format used in session token requests.
+     */
+    toTokenPrincipal(): SessionTokenPrincipal;
+    /**
+     * Returns the actor string derived from this identity (e.g. `agent:planner`, `user:alice`).
+     */
+    toActor(): string;
+}
+
+declare const SessionTokenScopeSchema: z.ZodEnum<["session:read", "session:append"]>;
+type SessionTokenScope = z.infer<typeof SessionTokenScopeSchema>;
 /**
  * Session record returned by the Starcite API.
  */
@@ -143,7 +155,7 @@ type SessionListPage = z.infer<typeof SessionListPageSchema>;
 declare const AppendEventRequestSchema: z.ZodObject<{
     type: z.ZodString;
     payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    actor: z.ZodString;
+    actor: z.ZodOptional<z.ZodString>;
     producer_id: z.ZodString;
     producer_seq: z.ZodNumber;
     source: z.ZodOptional<z.ZodString>;
@@ -154,10 +166,10 @@ declare const AppendEventRequestSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     type: string;
     payload: Record<string, unknown>;
-    actor: string;
     producer_id: string;
     producer_seq: number;
     metadata?: Record<string, unknown> | undefined;
+    actor?: string | undefined;
     source?: string | undefined;
     refs?: Record<string, unknown> | undefined;
     idempotency_key?: string | undefined;
@@ -165,10 +177,10 @@ declare const AppendEventRequestSchema: z.ZodObject<{
 }, {
     type: string;
     payload: Record<string, unknown>;
-    actor: string;
     producer_id: string;
     producer_seq: number;
     metadata?: Record<string, unknown> | undefined;
+    actor?: string | undefined;
     source?: string | undefined;
     refs?: Record<string, unknown> | undefined;
     idempotency_key?: string | undefined;
@@ -198,6 +210,13 @@ declare const AppendEventResponseSchema: z.ZodObject<{
  * Inferred TypeScript type for {@link AppendEventResponseSchema}.
  */
 type AppendEventResponse = z.infer<typeof AppendEventResponseSchema>;
+/**
+ * High-level append result returned by `session.append()`.
+ */
+interface AppendResult {
+    seq: number;
+    deduped: boolean;
+}
 /**
  * Raw event frame shape emitted by the Starcite tail stream.
  */
@@ -243,117 +262,113 @@ declare const TailEventSchema: z.ZodObject<{
  */
 type TailEvent = z.infer<typeof TailEventSchema>;
 /**
- * Convenience tail event shape with SDK-derived fields (`agent`, `text`).
+ * Canonical session event surfaced by the SDK.
  */
-declare const SessionEventInternalSchema: z.ZodObject<{
-    seq: z.ZodNumber;
-    type: z.ZodString;
-    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
-    actor: z.ZodString;
-    producer_id: z.ZodString;
-    producer_seq: z.ZodNumber;
-    source: z.ZodOptional<z.ZodString>;
-    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    refs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    idempotency_key: z.ZodOptional<z.ZodNullable<z.ZodString>>;
-    inserted_at: z.ZodOptional<z.ZodString>;
-} & {
-    agent: z.ZodOptional<z.ZodString>;
-    text: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodTypeAny, {
-    type: string;
-    payload: Record<string, unknown>;
-    actor: string;
-    producer_id: string;
-    producer_seq: number;
-    seq: number;
-    agent?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    source?: string | undefined;
-    refs?: Record<string, unknown> | undefined;
-    idempotency_key?: string | null | undefined;
-    inserted_at?: string | undefined;
-    text?: string | undefined;
-}, {
-    type: string;
-    payload: Record<string, unknown>;
-    actor: string;
-    producer_id: string;
-    producer_seq: number;
-    seq: number;
-    agent?: string | undefined;
-    metadata?: Record<string, unknown> | undefined;
-    source?: string | undefined;
-    refs?: Record<string, unknown> | undefined;
-    idempotency_key?: string | null | undefined;
-    inserted_at?: string | undefined;
-    text?: string | undefined;
-}>;
+type SessionEvent = TailEvent;
+/**
+ * Raw tail event batch grouped by a single WebSocket frame.
+ */
+type TailEventBatch = TailEvent[];
+/**
+ * Retention options for a session's in-memory canonical log.
+ */
+interface SessionLogOptions {
+    /**
+     * Maximum number of events retained in memory.
+     *
+     * When omitted, the log keeps all applied events for the current runtime.
+     */
+    maxEvents?: number;
+}
+/**
+ * Snapshot of a session's canonical in-memory log state.
+ */
+interface SessionSnapshot {
+    /**
+     * Ordered events currently retained in memory.
+     */
+    events: TailEvent[];
+    /**
+     * Highest contiguous sequence applied to the log.
+     */
+    lastSeq: number;
+    /**
+     * Indicates whether the session is actively streaming tail updates.
+     */
+    syncing: boolean;
+}
+/**
+ * Serializable persisted state for one session log.
+ */
+interface SessionStoreState {
+    /**
+     * Highest contiguous sequence applied for this session.
+     */
+    cursor: number;
+    /**
+     * Retained events snapshot used for immediate replay.
+     */
+    events: TailEvent[];
+}
 /**
- * Inferred TypeScript type for the SDK-level enriched tail event.
+ * Persistence interface for session cursor + retained events.
  */
-type SessionEvent = z.infer<typeof SessionEventInternalSchema>;
+interface SessionStore {
+    load(sessionId: string): SessionStoreState | undefined;
+    save(sessionId: string, state: SessionStoreState): void;
+    clear?(sessionId: string): void;
+}
 /**
  * High-level `session.append()` input.
  *
- * You must provide producer identity (`producerId`, `producerSeq`) and either
- * `text` or `payload`.
+ * The SDK manages `actor`, `producer_id`, and `producer_seq` automatically.
+ * Just provide `text` or `payload`.
  */
 declare const SessionAppendInputSchema: z.ZodEffects<z.ZodObject<{
-    agent: z.ZodString;
-    producerId: z.ZodString;
-    producerSeq: z.ZodNumber;
     text: z.ZodOptional<z.ZodString>;
     payload: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     type: z.ZodOptional<z.ZodString>;
+    actor: z.ZodOptional<z.ZodString>;
     source: z.ZodOptional<z.ZodString>;
     metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     refs: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
     idempotencyKey: z.ZodOptional<z.ZodString>;
     expectedSeq: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
-    agent: string;
-    producerId: string;
-    producerSeq: number;
     type?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     payload?: Record<string, unknown> | undefined;
+    actor?: string | undefined;
     source?: string | undefined;
     refs?: Record<string, unknown> | undefined;
     text?: string | undefined;
     idempotencyKey?: string | undefined;
     expectedSeq?: number | undefined;
 }, {
-    agent: string;
-    producerId: string;
-    producerSeq: number;
     type?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     payload?: Record<string, unknown> | undefined;
+    actor?: string | undefined;
     source?: string | undefined;
     refs?: Record<string, unknown> | undefined;
     text?: string | undefined;
     idempotencyKey?: string | undefined;
     expectedSeq?: number | undefined;
 }>, {
-    agent: string;
-    producerId: string;
-    producerSeq: number;
     type?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     payload?: Record<string, unknown> | undefined;
+    actor?: string | undefined;
     source?: string | undefined;
     refs?: Record<string, unknown> | undefined;
     text?: string | undefined;
     idempotencyKey?: string | undefined;
     expectedSeq?: number | undefined;
 }, {
-    agent: string;
-    producerId: string;
-    producerSeq: number;
     type?: string | undefined;
     metadata?: Record<string, unknown> | undefined;
     payload?: Record<string, unknown> | undefined;
+    actor?: string | undefined;
     source?: string | undefined;
     refs?: Record<string, unknown> | undefined;
     text?: string | undefined;
@@ -372,10 +387,22 @@ interface SessionTailOptions {
      * Starting cursor (inclusive) in the event stream.
      */
     cursor?: number;
+    /**
+     * Tail frame batch size (`1..1000`).
+     *
+     * When greater than `1`, Starcite may emit batched WebSocket frames.
+     */
+    batchSize?: number;
     /**
      * Optional filter for `agent:<name>` events.
      */
     agent?: string;
+    /**
+     * Idle window in milliseconds used for replay-only tails (`follow=false`) before auto-close.
+     *
+     * Defaults to `1000`.
+     */
+    catchUpIdleMs?: number;
     /**
      * Automatically reconnect on transport failures and continue from the last observed sequence.
      *
@@ -383,11 +410,9 @@ interface SessionTailOptions {
      */
     reconnect?: boolean;
     /**
-     * Delay between reconnect attempts in milliseconds.
-     *
-     * Defaults to `3000`.
+     * Reconnect policy for transport failures.
      */
-    reconnectDelayMs?: number;
+    reconnectPolicy?: TailReconnectPolicy;
     /**
      * When `false`, exit after replaying stored events instead of streaming live.
      *
@@ -398,49 +423,183 @@ interface SessionTailOptions {
      * Optional abort signal to close the stream.
      */
     signal?: AbortSignal;
+    /**
+     * Maximum number of tail batches buffered in-memory while the consumer is busy.
+     *
+     * Defaults to `1024`. When exceeded, the stream fails with `StarciteTailError`.
+     */
+    maxBufferedBatches?: number;
+    /**
+     * Optional lifecycle callback invoked for reconnect/drop/terminal stream state changes.
+     */
+    onLifecycleEvent?: (event: TailLifecycleEvent) => void;
+    /**
+     * Maximum time to wait for websocket handshake/open before reconnecting or failing.
+     *
+     * Defaults to `4000`.
+     */
+    connectionTimeoutMs?: number;
+    /**
+     * Optional inactivity watchdog. When set, the stream reconnects when no messages
+     * arrive within this duration.
+     */
+    inactivityTimeoutMs?: number;
 }
 /**
- * Options for listing sessions.
+ * Tail reconnect tuning knobs.
+ */
+interface TailReconnectPolicy {
+    /**
+     * Reconnect mode. `fixed` retries at the same delay, `exponential` increases delay after repeated failures.
+     *
+     * Defaults to `exponential`.
+     */
+    mode?: "fixed" | "exponential";
+    /**
+     * Initial reconnect delay in milliseconds.
+     *
+     * Defaults to `500`.
+     */
+    initialDelayMs?: number;
+    /**
+     * Maximum reconnect delay in milliseconds.
+     *
+     * Defaults to `15000`.
+     */
+    maxDelayMs?: number;
+    /**
+     * Exponential growth factor applied after each failed reconnect attempt.
+     *
+     * Defaults to `2`.
+     */
+    multiplier?: number;
+    /**
+     * Optional jitter ratio (`0..1`) applied around the computed delay.
+     *
+     * Defaults to `0.2`.
+     */
+    jitterRatio?: number;
+    /**
+     * Maximum number of reconnect attempts before failing.
+     *
+     * Defaults to unlimited retries.
+     */
+    maxAttempts?: number;
+}
+/**
+ * Stream lifecycle event emitted by `tail*()` APIs.
+ */
+type TailLifecycleEvent = {
+    type: "connect_attempt";
+    sessionId: string;
+    attempt: number;
+    cursor: number;
+} | {
+    type: "reconnect_scheduled";
+    sessionId: string;
+    attempt: number;
+    delayMs: number;
+    trigger: "connect_failed" | "dropped";
+    closeCode?: number;
+    closeReason?: string;
+} | {
+    type: "stream_dropped";
+    sessionId: string;
+    attempt: number;
+    closeCode?: number;
+    closeReason?: string;
+} | {
+    type: "stream_ended";
+    sessionId: string;
+    reason: "aborted" | "caught_up" | "graceful";
+};
+/**
+ * Storage adapter used by `session.consume*()` to persist the last processed cursor.
+ */
+interface SessionCursorStore {
+    /**
+     * Loads the last processed cursor for a session.
+     *
+     * Return `undefined` when no cursor has been stored yet.
+     */
+    load(sessionId: string): number | undefined | Promise<number | undefined>;
+    /**
+     * Persists the last processed cursor for a session.
+     */
+    save(sessionId: string, cursor: number): void | Promise<void>;
+}
+/**
+ * Durable tail consumption options with automatic cursor checkpointing.
  */
-interface SessionListOptions {
+interface SessionConsumeOptions extends Omit<SessionTailOptions, "cursor"> {
     /**
-     * Maximum rows to return. Must be a positive integer.
+     * Optional explicit starting cursor. When omitted, the SDK loads it from `cursorStore`.
      */
-    limit?: number;
+    cursor?: number;
     /**
-     * Optional cursor from the previous response.
+     * Cursor storage adapter used for resume-safe processing.
      */
-    cursor?: string;
+    cursorStore: SessionCursorStore;
     /**
-     * Optional flat metadata exact-match filters.
+     * Event handler. The cursor is checkpointed only after this handler succeeds.
      */
-    metadata?: Record<string, string>;
+    handler: (event: TailEvent) => void | Promise<void>;
 }
+/**
+ * Options for listing sessions.
+ */
+declare const SessionListOptionsSchema: z.ZodObject<{
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, "strip", z.ZodTypeAny, {
+    metadata?: Record<string, string> | undefined;
+    cursor?: string | undefined;
+    limit?: number | undefined;
+}, {
+    metadata?: Record<string, string> | undefined;
+    cursor?: string | undefined;
+    limit?: number | undefined;
+}>;
+type SessionListOptions = z.input<typeof SessionListOptionsSchema>;
 /**
  * Minimal WebSocket contract required by the SDK.
  */
+interface StarciteWebSocketMessageEvent {
+    data: unknown;
+}
+interface StarciteWebSocketCloseEvent {
+    code?: number;
+    reason?: string;
+}
+interface StarciteWebSocketEventMap {
+    open: unknown;
+    message: StarciteWebSocketMessageEvent;
+    error: unknown;
+    close: StarciteWebSocketCloseEvent;
+}
 interface StarciteWebSocket {
-    addEventListener(type: string, listener: (event: unknown) => void): void;
-    removeEventListener(type: string, listener: (event: unknown) => void): void;
+    addEventListener<TType extends keyof StarciteWebSocketEventMap>(type: TType, listener: (event: StarciteWebSocketEventMap[TType]) => void): void;
+    removeEventListener<TType extends keyof StarciteWebSocketEventMap>(type: TType, listener: (event: StarciteWebSocketEventMap[TType]) => void): void;
     close(code?: number, reason?: string): void;
 }
 /**
  * Factory used to create the WebSocket connection for `tail`.
  */
-interface StarciteWebSocketConnectOptions {
+type StarciteWebSocketFactory = (url: string) => StarciteWebSocket;
+/**
+ * Options forwarded to individual HTTP requests.
+ */
+interface RequestOptions {
     /**
-     * Headers to include with the WebSocket handshake request.
+     * Optional abort signal to cancel the request.
      */
-    headers?: HeadersInit;
+    signal?: AbortSignal;
 }
-/**
- * Factory used to create the WebSocket connection for `tail`.
- */
-type StarciteWebSocketFactory = (url: string, options?: StarciteWebSocketConnectOptions) => StarciteWebSocket;
 /**
  * Client construction options.
  */
-interface StarciteClientOptions {
+interface StarciteOptions {
     /**
      * Base API URL. Defaults to `process.env.STARCITE_BASE_URL` or `http://localhost:4000`.
      */
@@ -455,143 +614,369 @@ interface StarciteClientOptions {
     headers?: HeadersInit;
     /**
      * Service key / JWT token. When set, the SDK automatically sends
-     * `Authorization: Bearer <token>` for HTTP requests and WebSocket upgrades.
+     * `Authorization: Bearer <token>` for HTTP requests.
      */
     apiKey?: string;
+    /**
+     * Auth issuer URL used to mint session tokens. When omitted, the SDK derives
+     * this from API key JWT `iss` (issuer authority) or `STARCITE_AUTH_URL`.
+     */
+    authUrl?: string;
     /**
      * Custom WebSocket factory for non-browser runtimes.
      */
     websocketFactory?: StarciteWebSocketFactory;
+    /**
+     * Session store used for cursor + retained event persistence.
+     *
+     * Defaults to an in-memory store.
+     */
+    store?: SessionStore;
 }
 /**
  * Error payload shape returned by non-2xx API responses.
  */
-declare const StarciteErrorPayloadSchema: z.ZodObject<{
-    error: z.ZodOptional<z.ZodString>;
-    message: z.ZodOptional<z.ZodString>;
-}, "strip", z.ZodUnknown, z.objectOutputType<{
-    error: z.ZodOptional<z.ZodString>;
-    message: z.ZodOptional<z.ZodString>;
-}, z.ZodUnknown, "strip">, z.objectInputType<{
-    error: z.ZodOptional<z.ZodString>;
-    message: z.ZodOptional<z.ZodString>;
-}, z.ZodUnknown, "strip">>;
+type StarciteErrorPayload = Record<string, unknown>;
+
+/**
+ * Base error type for SDK-level failures.
+ */
+declare class StarciteError extends Error {
+    constructor(message: string);
+}
+/**
+ * Thrown when the Starcite API responds with a non-2xx status code.
+ */
+declare class StarciteApiError extends StarciteError {
+    /** HTTP status code returned by the API. */
+    readonly status: number;
+    /** Stable API error code (or synthesized `http_<status>` fallback). */
+    readonly code: string;
+    /** Parsed API error payload when available. */
+    readonly payload: StarciteErrorPayload | null;
+    constructor(message: string, status: number, code: string, payload: StarciteErrorPayload | null);
+}
+/**
+ * Thrown when the SDK cannot reach Starcite or receives invalid transport payloads.
+ */
+declare class StarciteConnectionError extends StarciteError {
+    constructor(message: string);
+}
+type StarciteTailErrorStage = "connect" | "stream" | "retry_limit" | "consumer_backpressure";
+/**
+ * Thrown for tail-stream failures with structured stage/context fields.
+ */
+declare class StarciteTailError extends StarciteConnectionError {
+    /** Session id tied to this tail stream. */
+    readonly sessionId: string;
+    /** Failure stage in the tail lifecycle. */
+    readonly stage: StarciteTailErrorStage;
+    /** Reconnect attempts observed before failing. */
+    readonly attempts: number;
+    /** WebSocket close code when available. */
+    readonly closeCode?: number;
+    /** WebSocket close reason when available. */
+    readonly closeReason?: string;
+    constructor(message: string, options: {
+        sessionId: string;
+        stage: StarciteTailErrorStage;
+        attempts?: number;
+        closeCode?: number;
+        closeReason?: string;
+    });
+}
+/**
+ * Thrown when the tail WebSocket is closed with code 4001 (token expired).
+ *
+ * Callers should re-issue a session token and reconnect from the last cursor.
+ */
+declare class StarciteTokenExpiredError extends StarciteTailError {
+    constructor(message: string, options: {
+        sessionId: string;
+        attempts?: number;
+        closeCode?: number;
+        closeReason?: string;
+    });
+}
+/**
+ * Thrown when the tail consumer falls behind and exceeds the buffered batch limit.
+ */
+declare class StarciteBackpressureError extends StarciteTailError {
+    constructor(message: string, options: {
+        sessionId: string;
+        attempts?: number;
+    });
+}
+/**
+ * Thrown when tail reconnect attempts exceed the configured limit.
+ */
+declare class StarciteRetryLimitError extends StarciteTailError {
+    constructor(message: string, options: {
+        sessionId: string;
+        attempts: number;
+        closeCode?: number;
+        closeReason?: string;
+    });
+}
+
+declare class SessionLogGapError extends StarciteError {
+    constructor(message: string);
+}
+declare class SessionLogConflictError extends StarciteError {
+    constructor(message: string);
+}
 /**
- * Inferred TypeScript type for {@link StarciteErrorPayloadSchema}.
+ * Canonical in-memory log for one session.
+ *
+ * Invariants:
+ * - Applies events in strict contiguous `seq` order.
+ * - Treats repeated identical events as idempotent no-ops.
+ * - Rejects conflicting duplicates and sequence gaps.
+ */
+declare class SessionLog {
+    private readonly history;
+    private readonly emitter;
+    private readonly canonicalBySeq;
+    private maxEvents;
+    private appliedSeq;
+    constructor(options?: SessionLogOptions);
+    setMaxEvents(maxEvents: number | undefined): void;
+    applyBatch(batch: TailEvent[]): TailEvent[];
+    hydrate(state: SessionStoreState): void;
+    subscribe(listener: (event: TailEvent) => void, options?: {
+        replay?: boolean;
+    }): () => void;
+    private apply;
+    getSnapshot(syncing: boolean): SessionSnapshot;
+    get events(): readonly TailEvent[];
+    get cursor(): number;
+    get lastSeq(): number;
+    private enforceRetention;
+}
+
+/**
+ * Shared HTTP + WebSocket transport configuration.
+ *
+ * Both `Starcite` (API-key auth) and `StarciteSession` (session-token auth)
+ * hold their own `TransportConfig` and pass it to the free functions below.
  */
-type StarciteErrorPayload = z.infer<typeof StarciteErrorPayloadSchema>;
+interface TransportConfig {
+    readonly baseUrl: string;
+    readonly websocketBaseUrl: string;
+    readonly authorization: string | null;
+    readonly fetchFn: typeof fetch;
+    readonly headers: Headers;
+    readonly websocketFactory: (url: string) => StarciteWebSocket;
+}
 
 /**
- * Normalizes a Starcite base URL to the `/v1` API root used by this SDK.
+ * Construction options for a `StarciteSession`.
  */
-declare function normalizeBaseUrl(baseUrl: string): string;
+interface StarciteSessionOptions {
+    id: string;
+    token: string;
+    identity: StarciteIdentity;
+    transport: TransportConfig;
+    store: SessionStore;
+    record?: SessionRecord;
+    logOptions?: SessionLogOptions;
+}
+type SessionEventListener = (event: SessionEvent) => void;
 /**
- * Session-scoped helper for append and tail operations.
+ * Session-scoped client bound to a specific identity and session token.
+ *
+ * All operations use the session token for auth — not the parent client's API key.
  */
 declare class StarciteSession {
     /** Session identifier. */
     readonly id: string;
+    /** The session JWT used for auth. Extract this for frontend handoff. */
+    readonly token: string;
+    /** Identity bound to this session. */
+    readonly identity: StarciteIdentity;
     /** Optional session record captured at creation time. */
     readonly record?: SessionRecord;
-    private readonly client;
-    constructor(client: StarciteClient, id: string, record?: SessionRecord);
+    private readonly transport;
+    private readonly producerId;
+    private producerSeq;
+    readonly log: SessionLog;
+    private readonly store;
+    private readonly lifecycle;
+    private readonly eventSubscriptions;
+    private liveSyncController;
+    private liveSyncTask;
+    constructor(options: StarciteSessionOptions);
     /**
-     * Appends a high-level agent event to this session.
+     * Appends an event to this session.
      *
-     * Automatically prefixes `agent` as `agent:<name>` when needed.
+     * The SDK manages `actor`, `producer_id`, and `producer_seq` automatically.
      */
-    append(input: SessionAppendInput): Promise<AppendEventResponse>;
+    append(input: SessionAppendInput, options?: RequestOptions): Promise<AppendResult>;
     /**
-     * Appends a raw event payload as-is.
+     * Appends a raw event payload as-is. Caller manages all fields.
      */
-    appendRaw(input: AppendEventRequest): Promise<AppendEventResponse>;
+    appendRaw(input: AppendEventRequest, options?: RequestOptions): Promise<AppendEventResponse>;
     /**
-     * Streams transformed session events with SDK convenience fields (`agent`, `text`).
+     * Subscribes to canonical session events and lifecycle errors.
      */
-    tail(options?: SessionTailOptions): AsyncIterable<SessionEvent>;
+    on(eventName: "event", listener: SessionEventListener): () => void;
+    on(eventName: "error", listener: (error: Error) => void): () => void;
     /**
-     * Streams raw tail events returned by the API.
+     * Removes a previously registered listener.
      */
-    tailRaw(options?: SessionTailOptions): AsyncIterable<TailEvent>;
-}
-/**
- * Starcite API client for HTTP and WebSocket session operations.
- */
-declare class StarciteClient {
-    /** Normalized API base URL ending with `/v1`. */
-    readonly baseUrl: string;
-    private readonly inferredCreatorPrincipal?;
-    private readonly websocketBaseUrl;
-    private readonly fetchFn;
-    private readonly headers;
-    private readonly websocketFactory;
+    off(eventName: "event", listener: SessionEventListener): void;
+    off(eventName: "error", listener: (error: Error) => void): void;
     /**
-     * Creates a new client instance.
+     * Stops live syncing and removes listeners registered via `on()`.
      */
-    constructor(options?: StarciteClientOptions);
+    disconnect(): void;
     /**
-     * Returns a session helper bound to an existing session id.
+     * Backwards-compatible alias for `disconnect()`.
      */
-    session(sessionId: string, record?: SessionRecord): StarciteSession;
+    close(): void;
     /**
-     * Creates a new session and returns a bound `StarciteSession` helper.
+     * Updates in-memory session log retention.
      */
-    create(input?: CreateSessionInput): Promise<StarciteSession>;
+    setLogOptions(options: SessionLogOptions): void;
     /**
-     * Creates a new session and returns the raw session record.
+     * Returns a stable snapshot of the current canonical in-memory log.
      */
-    createSession(input?: CreateSessionInput): Promise<SessionRecord>;
+    getSnapshot(): SessionSnapshot;
     /**
-     * Lists sessions from the archive-backed catalog.
+     * Streams tail events one at a time via callback.
+     */
+    tail(onEvent: (event: TailEvent) => void | Promise<void>, options?: SessionTailOptions): Promise<void>;
+    /**
+     * Streams tail event batches grouped by incoming frame via callback.
+     */
+    tailBatches(onBatch: (batch: TailEvent[]) => void | Promise<void>, options?: SessionTailOptions): Promise<void>;
+    /**
+     * Durably consumes events and checkpoints `event.seq` after each successful handler invocation.
+     */
+    consume(options: SessionConsumeOptions): Promise<void>;
+    private emitStreamError;
+    private ensureLiveSync;
+    private runLiveSync;
+    private persistLogState;
+}
+
+/**
+ * Tenant-scoped Starcite client.
+ *
+ * Create identities with {@link user} / {@link agent}, then bind them to
+ * sessions with {@link session}.
+ */
+declare class Starcite {
+    /** Normalized API base URL ending with `/v1`. */
+    readonly baseUrl: string;
+    private readonly transport;
+    private readonly authBaseUrl?;
+    private readonly inferredIdentity?;
+    private readonly store;
+    constructor(options?: StarciteOptions);
+    /**
+     * Creates a user identity bound to this client's tenant.
      */
-    listSessions(options?: SessionListOptions): Promise<SessionListPage>;
+    user(options: {
+        id: string;
+    }): StarciteIdentity;
     /**
-     * Appends a raw event payload to a specific session.
+     * Creates an agent identity bound to this client's tenant.
      */
-    appendEvent(sessionId: string, input: AppendEventRequest): Promise<AppendEventResponse>;
+    agent(options: {
+        id: string;
+    }): StarciteIdentity;
     /**
-     * Opens a WebSocket tail stream and yields raw events.
+     * Creates or binds to a session.
+     *
+     * **With identity** (backend): creates a new session and/or mints a session
+     * token for the given identity. Pass `id` to bind to an existing session.
+     *
+     * **With token** (frontend): wraps an existing session token. The identity
+     * and session id are decoded from the JWT.
      */
-    tailRawEvents(sessionId: string, options?: SessionTailOptions): AsyncGenerator<TailEvent>;
+    session(input: {
+        token: string;
+        logOptions?: SessionLogOptions;
+    }): StarciteSession;
+    session(input: {
+        identity: StarciteIdentity;
+        id?: string;
+        title?: string;
+        metadata?: Record<string, unknown>;
+        logOptions?: SessionLogOptions;
+    }): Promise<StarciteSession>;
     /**
-     * Opens a WebSocket tail stream and yields transformed session events.
+     * Lists sessions from the archive-backed catalog.
      */
-    tailEvents(sessionId: string, options?: SessionTailOptions): AsyncGenerator<SessionEvent>;
-    private request;
+    listSessions(options?: SessionListOptions, requestOptions?: RequestOptions): Promise<SessionListPage>;
+    private sessionFromIdentity;
+    private sessionFromToken;
+    private buildSessionTransport;
+    private createSession;
+    private issueSessionToken;
+    private requireTenantId;
 }
 
 /**
- * Base error type for SDK-level failures.
+ * Minimal Web Storage contract used by {@link WebStorageCursorStore}.
  */
-declare class StarciteError extends Error {
-    constructor(message: string);
+interface StarciteWebStorage {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
 }
 /**
- * Thrown when the Starcite API responds with a non-2xx status code.
+ * Key customization options for storage-backed cursor stores.
  */
-declare class StarciteApiError extends StarciteError {
-    /** HTTP status code returned by the API. */
-    readonly status: number;
-    /** Stable API error code (or synthesized `http_<status>` fallback). */
-    readonly code: string;
-    /** Parsed API error payload when available. */
-    readonly payload: StarciteErrorPayload | null;
-    constructor(message: string, status: number, code: string, payload: StarciteErrorPayload | null);
+interface CursorStoreOptions {
+    /**
+     * Prefix used when deriving storage keys.
+     *
+     * Defaults to `"starcite"`.
+     */
+    keyPrefix?: string;
+    /**
+     * Custom key resolver. When provided it overrides `keyPrefix`.
+     */
+    keyForSession?: (sessionId: string) => string;
 }
 /**
- * Thrown when the SDK cannot reach Starcite or receives invalid transport payloads.
+ * In-memory cursor store (useful for workers/tests).
  */
-declare class StarciteConnectionError extends StarciteError {
-    constructor(message: string);
+declare class InMemoryCursorStore implements SessionCursorStore {
+    private readonly cursors;
+    constructor(initial?: Record<string, number>);
+    load(sessionId: string): number | undefined;
+    save(sessionId: string, cursor: number): void;
 }
-
 /**
- * Creates a new {@link StarciteClient} instance.
+ * Cursor store backed by a Web Storage-compatible object.
  */
-declare function createStarciteClient(options?: StarciteClientOptions): StarciteClient;
+declare class WebStorageCursorStore implements SessionCursorStore {
+    private readonly storage;
+    private readonly keyForSession;
+    constructor(storage: StarciteWebStorage, options?: CursorStoreOptions);
+    load(sessionId: string): number | undefined;
+    save(sessionId: string, cursor: number): void;
+}
 /**
- * Default singleton client using environment/default configuration.
+ * Cursor store backed by `globalThis.localStorage`.
  */
-declare const starcite: StarciteClient;
+declare class LocalStorageCursorStore extends WebStorageCursorStore {
+    constructor(options?: CursorStoreOptions);
+}
+
+/**
+ * Default in-memory session store.
+ *
+ * Persists both cursor and retained events for each session so late subscribers
+ * can replay immediately after process-local reconnect/rebind.
+ */
+declare class MemoryStore implements SessionStore {
+    private readonly sessions;
+    load(sessionId: string): SessionStoreState | undefined;
+    save(sessionId: string, state: SessionStoreState): void;
+    clear(sessionId: string): void;
+}
 
-export { type AppendEventRequest, type AppendEventResponse, type CreateSessionInput, type SessionAppendInput, type SessionEvent, type SessionListItem, type SessionListOptions, type SessionListPage, type SessionRecord, type SessionTailOptions, StarciteApiError, StarciteClient, type StarciteClientOptions, StarciteConnectionError, StarciteError, type StarciteErrorPayload, StarciteSession, type StarciteWebSocket, type StarciteWebSocketConnectOptions, type StarciteWebSocketFactory, type TailEvent, createStarciteClient, normalizeBaseUrl, starcite };
+export { type AppendEventRequest, type AppendEventResponse, type AppendResult, type CursorStoreOptions, InMemoryCursorStore, LocalStorageCursorStore, MemoryStore, type PrincipalType, type RequestOptions, type SessionAppendInput, type SessionConsumeOptions, type SessionCursorStore, type SessionEvent, type SessionListItem, type SessionListOptions, type SessionListPage, SessionLogConflictError, SessionLogGapError, type SessionLogOptions, type SessionRecord, type SessionSnapshot, type SessionStore, type SessionStoreState, type SessionTailOptions, type SessionTokenScope, Starcite, StarciteApiError, StarciteBackpressureError, StarciteConnectionError, StarciteError, StarciteIdentity, type StarciteOptions, StarciteRetryLimitError, StarciteSession, StarciteTailError, type StarciteTailErrorStage, StarciteTokenExpiredError, type StarciteWebSocket, type StarciteWebSocketCloseEvent, type StarciteWebSocketEventMap, type StarciteWebSocketFactory, type StarciteWebSocketMessageEvent, type StarciteWebStorage, type TailEvent, type TailEventBatch, type TailLifecycleEvent, type TailReconnectPolicy, WebStorageCursorStore };