@starcite/sdk 0.0.6 → 0.0.7

package/dist/index.js

@@ -78,13 +78,14 @@ function inferIdentityFromApiKey(apiKey) {
   const claims = ApiKeyClaimsSchema.parse(decodeJwt(apiKey));
   const id = claims.principal_id ?? claims.sub;
   const tenantId = claims.tenant_id;
-  if (!(tenantId && id && claims.principal_type)) {
+  const type = claims.principal_type ?? "user";
+  if (!(tenantId && id)) {
     return void 0;
   }
   return new StarciteIdentity({
     tenantId,
     id,
-    type: claims.principal_type
+    type
   });
 }
 function decodeSessionToken(token) {
@@ -285,7 +286,7 @@ var SessionLog = class {
     this.enforceRetention();
     return true;
   }
-  getSnapshot(syncing) {
+  state(syncing) {
     return {
       events: this.history.slice(),
       lastSeq: this.appliedSeq,
@@ -888,7 +889,7 @@ var TailStream = class {
     this.follow = follow;
     this.shouldReconnect = follow ? opts.reconnect ?? true : false;
     this.catchUpIdleMs = opts.catchUpIdleMs ?? 1e3;
-    this.connectionTimeoutMs = opts.connectionTimeoutMs ?? 4e3;
+    this.connectionTimeoutMs = opts.connectionTimeoutMs ?? 12e3;
     this.inactivityTimeoutMs = opts.inactivityTimeoutMs;
     this.maxBufferedBatches = opts.maxBufferedBatches ?? 1024;
     this.signal = opts.signal;
@@ -1259,8 +1260,10 @@ var StarciteSession = class {
   store;
   lifecycle = new EventEmitter3();
   eventSubscriptions = /* @__PURE__ */ new Map();
+  appendTask = Promise.resolve();
   liveSyncController;
   liveSyncTask;
+  liveSyncCatchUpActive = false;
   constructor(options) {
     this.id = options.id;
     this.token = options.token;
@@ -1270,8 +1273,8 @@ var StarciteSession = class {
     this.producerId = crypto.randomUUID();
     this.store = options.store;
     this.log = new SessionLog(options.logOptions);
-    const storedState = this.store.load(this.id);
-    if (storedState) {
+    const storedState = this.store?.load(this.id);
+    if (storedState !== void 0) {
       this.log.hydrate(storedState);
     }
   }
@@ -1280,28 +1283,35 @@ var StarciteSession = class {
    *
    * The SDK manages `actor`, `producer_id`, and `producer_seq` automatically.
    */
-  async append(input, options) {
+  append(input, options) {
     const parsed = SessionAppendInputSchema.parse(input);
-    this.producerSeq += 1;
-    const result = await this.appendRaw(
-      {
-        type: parsed.type ?? "content",
-        payload: parsed.payload ?? { text: parsed.text },
-        actor: parsed.actor ?? this.identity.toActor(),
-        producer_id: this.producerId,
-        producer_seq: this.producerSeq,
-        source: parsed.source ?? "agent",
-        metadata: parsed.metadata,
-        refs: parsed.refs,
-        idempotency_key: parsed.idempotencyKey,
-        expected_seq: parsed.expectedSeq
-      },
-      options
+    const runAppend = this.appendTask.then(async () => {
+      this.producerSeq += 1;
+      const result = await this.appendRaw(
+        {
+          type: parsed.type ?? "content",
+          payload: parsed.payload ?? { text: parsed.text },
+          actor: parsed.actor ?? this.identity.toActor(),
+          producer_id: this.producerId,
+          producer_seq: this.producerSeq,
+          source: parsed.source ?? "agent",
+          metadata: parsed.metadata,
+          refs: parsed.refs,
+          idempotency_key: parsed.idempotencyKey,
+          expected_seq: parsed.expectedSeq
+        },
+        options
+      );
+      return {
+        seq: result.seq,
+        deduped: result.deduped
+      };
+    });
+    this.appendTask = runAppend.then(
+      () => void 0,
+      () => void 0
     );
-    return {
-      seq: result.seq,
-      deduped: result.deduped
-    };
+    return runAppend;
   }
   /**
    * Appends a raw event payload as-is. Caller manages all fields.
@@ -1318,11 +1328,33 @@ var StarciteSession = class {
       AppendEventResponseSchema
     );
   }
-  on(eventName, listener) {
+  on(eventName, listener, options) {
     if (eventName === "event") {
       const eventListener = listener;
       if (!this.eventSubscriptions.has(eventListener)) {
-        const unsubscribe = this.log.subscribe(eventListener, { replay: true });
+        const eventOptions = options;
+        const replay = eventOptions?.replay ?? true;
+        const replayCutoffSeq = replay ? this.log.lastSeq : -1;
+        const schema = eventOptions?.schema;
+        const dispatch = (event) => {
+          const parsedEvent = this.parseOnEvent(event, schema);
+          if (!parsedEvent) {
+            return;
+          }
+          const classifiedContext = this.resolveEventContext(
+            event.seq,
+            replayCutoffSeq,
+            this.liveSyncCatchUpActive
+          );
+          try {
+            this.observeEventListenerResult(
+              eventListener(parsedEvent, classifiedContext)
+            );
+          } catch (error) {
+            this.emitStreamError(error);
+          }
+        };
+        const unsubscribe = this.log.subscribe(dispatch, { replay });
         this.eventSubscriptions.set(eventListener, unsubscribe);
       }
       this.ensureLiveSync();
@@ -1384,77 +1416,195 @@ var StarciteSession = class {
     this.persistLogState();
   }
   /**
-   * Returns a stable snapshot of the current canonical in-memory log.
+   * Returns a stable view of the current canonical in-memory log state.
    */
-  getSnapshot() {
-    return this.log.getSnapshot(this.liveSyncTask !== void 0);
-  }
-  /**
-   * Streams tail events one at a time via callback.
-   */
-  async tail(onEvent, options = {}) {
-    await this.tailBatches(async (batch) => {
-      for (const event of batch) {
-        await onEvent(event);
-      }
-    }, options);
+  state() {
+    return this.log.state(this.liveSyncTask !== void 0);
   }
   /**
-   * Streams tail event batches grouped by incoming frame via callback.
+   * Returns the retained canonical event list.
    */
-  async tailBatches(onBatch, options = {}) {
-    await new TailStream({
-      sessionId: this.id,
-      token: this.token,
-      websocketBaseUrl: this.transport.websocketBaseUrl,
-      websocketFactory: this.transport.websocketFactory,
-      options
-    }).subscribe(onBatch);
+  events() {
+    return this.log.events;
   }
   /**
-   * Durably consumes events and checkpoints `event.seq` after each successful handler invocation.
+   * Streams canonical events as an async iterator.
+   *
+   * Replay semantics and schema validation mirror `session.on("event", ...)`.
    */
-  async consume(options) {
-    const {
-      cursorStore,
-      handler,
-      cursor: requestedCursor,
-      ...tailOptions
-    } = options;
-    let cursor;
-    if (requestedCursor !== void 0) {
-      cursor = requestedCursor;
-    } else {
-      try {
-        cursor = await cursorStore.load(this.id) ?? 0;
-      } catch (error) {
-        throw new StarciteError(
-          `consume() failed to load cursor for session '${this.id}': ${error instanceof Error ? error.message : String(error)}`
-        );
+  tail(options = {}) {
+    const { replay = true, schema, ...tailOptions } = options;
+    const replayCutoffSeq = replay ? this.log.lastSeq : -1;
+    const startCursor = tailOptions.cursor ?? this.log.lastSeq;
+    const session = this;
+    const parseEvent = (event) => session.parseTailEvent(event, schema);
+    return {
+      async *[Symbol.asyncIterator]() {
+        if (replay) {
+          for (const replayEvent of session.log.events) {
+            yield {
+              event: parseEvent(replayEvent),
+              context: { phase: "replay", replayed: true }
+            };
+          }
+        }
+        yield* session.iterateLiveTail({
+          parseEvent,
+          replayCutoffSeq,
+          startCursor,
+          tailOptions
+        });
       }
+    };
+  }
+  parseOnEvent(event, schema) {
+    if (!schema) {
+      return event;
     }
-    const stream = new TailStream({
+    try {
+      return schema.parse(event);
+    } catch (error) {
+      this.emitStreamError(
+        new StarciteError(
+          `session.on("event") schema validation failed for session '${this.id}': ${error instanceof Error ? error.message : String(error)}`
+        )
+      );
+      return void 0;
+    }
+  }
+  parseTailEvent(event, schema) {
+    if (!schema) {
+      return event;
+    }
+    try {
+      return schema.parse(event);
+    } catch (error) {
+      throw new StarciteError(
+        `session.tail() schema validation failed for session '${this.id}': ${error instanceof Error ? error.message : String(error)}`
+      );
+    }
+  }
+  resolveEventContext(eventSeq, replayCutoffSeq, forceReplay = false) {
+    const replayed = forceReplay || eventSeq <= replayCutoffSeq;
+    return replayed ? { phase: "replay", replayed: true } : { phase: "live", replayed: false };
+  }
+  observeEventListenerResult(result) {
+    Promise.resolve(result).catch((error) => {
+      this.emitStreamError(error);
+    });
+  }
+  createTailAbortController(outerSignal) {
+    const controller = new AbortController();
+    if (!outerSignal) {
+      return { controller, detach: () => void 0 };
+    }
+    const abortFromOuterSignal = () => {
+      controller.abort(outerSignal.reason);
+    };
+    if (outerSignal.aborted) {
+      controller.abort(outerSignal.reason);
+      return { controller, detach: () => void 0 };
+    }
+    outerSignal.addEventListener("abort", abortFromOuterSignal, { once: true });
+    return {
+      controller,
+      detach: () => {
+        outerSignal.removeEventListener("abort", abortFromOuterSignal);
+      }
+    };
+  }
+  createTailRuntime({
+    parseEvent,
+    replayCutoffSeq,
+    startCursor,
+    tailOptions
+  }) {
+    const queue = [];
+    let notify;
+    let done = false;
+    let failure;
+    const shouldApplyToLog = tailOptions.agent === void 0;
+    const { controller, detach } = this.createTailAbortController(
+      tailOptions.signal
+    );
+    const wake = () => {
+      notify?.();
+    };
+    const streamTask = new TailStream({
       sessionId: this.id,
       token: this.token,
       websocketBaseUrl: this.transport.websocketBaseUrl,
       websocketFactory: this.transport.websocketFactory,
       options: {
         ...tailOptions,
-        cursor
+        cursor: startCursor,
+        signal: controller.signal
+      }
+    }).subscribe((batch) => {
+      const queuedEvents = shouldApplyToLog ? this.log.applyBatch(batch) : batch;
+      if (shouldApplyToLog && queuedEvents.length > 0) {
+        this.persistLogState();
       }
+      for (const event of queuedEvents) {
+        queue.push({
+          event: parseEvent(event),
+          context: this.resolveEventContext(event.seq, replayCutoffSeq)
+        });
+      }
+      wake();
+    }).catch((error) => {
+      failure = error;
+    }).finally(() => {
+      done = true;
+      wake();
     });
-    await stream.subscribe(async (batch) => {
-      for (const event of batch) {
-        await handler(event);
-        try {
-          await cursorStore.save(this.id, event.seq);
-        } catch (error) {
-          throw new StarciteError(
-            `consume() failed to save cursor for session '${this.id}': ${error instanceof Error ? error.message : String(error)}`
-          );
+    return {
+      next: async () => {
+        while (queue.length === 0 && !done && !failure) {
+          await new Promise((resolve) => {
+            notify = resolve;
+          });
+          notify = void 0;
         }
+        const next = queue.shift();
+        return next;
+      },
+      getFailure: () => failure,
+      dispose: async () => {
+        controller.abort();
+        detach();
+        await streamTask;
       }
+    };
+  }
+  async *iterateLiveTail({
+    parseEvent,
+    replayCutoffSeq,
+    startCursor,
+    tailOptions
+  }) {
+    const runtime = this.createTailRuntime({
+      parseEvent,
+      replayCutoffSeq,
+      startCursor,
+      tailOptions
     });
+    try {
+      while (true) {
+        const next = await runtime.next();
+        if (next) {
+          yield next;
+          continue;
+        }
+        const failure = runtime.getFailure();
+        if (failure) {
+          throw failure;
+        }
+        return;
+      }
+    } finally {
+      await runtime.dispose();
+    }
   }
   emitStreamError(error) {
     const streamError = error instanceof Error ? error : new StarciteError(`Session stream failed: ${String(error)}`);
@@ -1479,67 +1629,94 @@ var StarciteSession = class {
     }).finally(() => {
       this.liveSyncTask = void 0;
       this.liveSyncController = void 0;
+      if (this.eventSubscriptions.size > 0) {
+        this.ensureLiveSync();
+      }
     });
   }
   async runLiveSync(signal) {
+    let shouldRunCatchUpPass = this.log.lastSeq === 0;
+    let retryDelayMs = 250;
     while (!signal.aborted && this.eventSubscriptions.size > 0) {
-      const stream = new TailStream({
-        sessionId: this.id,
-        token: this.token,
-        websocketBaseUrl: this.transport.websocketBaseUrl,
-        websocketFactory: this.transport.websocketFactory,
-        options: {
-          cursor: this.log.lastSeq,
-          signal
-        }
-      });
+      this.liveSyncCatchUpActive = shouldRunCatchUpPass;
       try {
-        await stream.subscribe((batch) => {
-          const appliedEvents = this.log.applyBatch(batch);
-          if (appliedEvents.length > 0) {
-            this.persistLogState();
-          }
-        });
+        await this.subscribeLiveSyncPass(signal, !shouldRunCatchUpPass);
+        shouldRunCatchUpPass = false;
+        retryDelayMs = 250;
       } catch (error) {
         if (signal.aborted) {
           return;
         }
         if (error instanceof SessionLogGapError) {
+          shouldRunCatchUpPass = true;
           continue;
         }
-        throw error;
+        this.emitStreamError(error);
+        shouldRunCatchUpPass = true;
+        await this.waitForLiveSyncRetry(retryDelayMs, signal);
+        retryDelayMs = Math.min(retryDelayMs * 2, 5e3);
+      } finally {
+        this.liveSyncCatchUpActive = false;
       }
     }
   }
+  async subscribeLiveSyncPass(signal, follow) {
+    const stream = new TailStream({
+      sessionId: this.id,
+      token: this.token,
+      websocketBaseUrl: this.transport.websocketBaseUrl,
+      websocketFactory: this.transport.websocketFactory,
+      options: {
+        cursor: this.log.lastSeq,
+        follow,
+        signal
+      }
+    });
+    await stream.subscribe((batch) => {
+      const appliedEvents = this.log.applyBatch(batch);
+      if (appliedEvents.length > 0) {
+        this.persistLogState();
+      }
+    });
+  }
   persistLogState() {
+    if (!this.store) {
+      return;
+    }
     this.store.save(this.id, {
       cursor: this.log.cursor,
-      events: [...this.log.events]
+      events: [...this.log.events],
+      metadata: {
+        schemaVersion: 1,
+        updatedAtMs: Date.now()
+      }
     });
   }
-};
-
-// src/session-store.ts
-function cloneEvents(events) {
-  return events.map((event) => structuredClone(event));
-}
-function cloneState(state) {
-  return {
-    cursor: state.cursor,
-    events: cloneEvents(state.events)
-  };
-}
-var MemoryStore = class {
-  sessions = /* @__PURE__ */ new Map();
-  load(sessionId) {
-    const stored = this.sessions.get(sessionId);
-    return stored ? cloneState(stored) : void 0;
-  }
-  save(sessionId, state) {
-    this.sessions.set(sessionId, cloneState(state));
-  }
-  clear(sessionId) {
-    this.sessions.delete(sessionId);
+  waitForLiveSyncRetry(delayMs, signal) {
+    if (delayMs <= 0 || signal.aborted) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => {
+      let settled = false;
+      const timer = setTimeout(() => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+      }, delayMs);
+      const onAbort = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimeout(timer);
+        signal.removeEventListener("abort", onAbort);
+        resolve();
+      };
+      signal.addEventListener("abort", onAbort, { once: true });
+    });
   }
 };
 
@@ -1579,7 +1756,7 @@ var Starcite = class {
     }
     this.authBaseUrl = resolveAuthBaseUrl(options.authUrl, apiKey);
     const websocketFactory = options.websocketFactory ?? defaultWebSocketFactory;
-    this.store = options.store ?? new MemoryStore();
+    this.store = options.store;
     this.transport = {
       baseUrl,
       websocketBaseUrl: toWebSocketBaseUrl(baseUrl),
@@ -1750,53 +1927,90 @@ var Starcite = class {
   }
 };
 
-// src/cursor-store.ts
+// src/session-store.ts
+import { z as z5 } from "zod";
 var DEFAULT_KEY_PREFIX = "starcite";
-var InMemoryCursorStore = class {
-  cursors;
-  constructor(initial = {}) {
-    this.cursors = new Map(Object.entries(initial));
-  }
+var SessionStoreMetadataSchema = z5.object({
+  schemaVersion: z5.literal(1),
+  updatedAtMs: z5.number().int().nonnegative()
+});
+var SessionStoreStateSchema = z5.object({
+  cursor: z5.number().int().nonnegative(),
+  events: z5.array(TailEventSchema),
+  metadata: SessionStoreMetadataSchema.optional()
+});
+function cloneEvents(events) {
+  return events.map((event) => structuredClone(event));
+}
+function cloneState(state) {
+  return {
+    cursor: state.cursor,
+    events: cloneEvents(state.events),
+    metadata: state.metadata ? { ...state.metadata } : void 0
+  };
+}
+var MemoryStore = class {
+  sessions = /* @__PURE__ */ new Map();
   load(sessionId) {
-    return this.cursors.get(sessionId);
+    const stored = this.sessions.get(sessionId);
+    return stored ? cloneState(stored) : void 0;
   }
-  save(sessionId, cursor) {
-    this.cursors.set(sessionId, cursor);
+  save(sessionId, state) {
+    this.sessions.set(sessionId, cloneState(state));
+  }
+  clear(sessionId) {
+    this.sessions.delete(sessionId);
   }
 };
-var WebStorageCursorStore = class {
+var WebStorageSessionStore = class {
   storage;
   keyForSession;
+  stateSchema;
   constructor(storage, options = {}) {
     this.storage = storage;
     const prefix = options.keyPrefix?.trim() || DEFAULT_KEY_PREFIX;
-    this.keyForSession = options.keyForSession ?? ((sessionId) => `${prefix}:${sessionId}:lastSeq`);
+    this.keyForSession = options.keyForSession ?? ((sessionId) => `${prefix}:${sessionId}:sessionStore`);
+    this.stateSchema = options.stateSchema ?? SessionStoreStateSchema;
   }
   load(sessionId) {
     const raw = this.storage.getItem(this.keyForSession(sessionId));
     if (raw === null) {
       return void 0;
     }
-    const parsed = Number.parseInt(raw, 10);
-    return Number.isInteger(parsed) && parsed >= 0 ? parsed : void 0;
+    let decoded;
+    try {
+      decoded = JSON.parse(raw);
+    } catch {
+      return void 0;
+    }
+    const parsed = this.stateSchema.safeParse(decoded);
+    if (!parsed.success) {
+      return void 0;
+    }
+    return cloneState(parsed.data);
   }
-  save(sessionId, cursor) {
-    this.storage.setItem(this.keyForSession(sessionId), `${cursor}`);
+  save(sessionId, state) {
+    this.storage.setItem(
+      this.keyForSession(sessionId),
+      JSON.stringify(cloneState(state))
+    );
+  }
+  clear(sessionId) {
+    this.storage.removeItem?.(this.keyForSession(sessionId));
   }
 };
-var LocalStorageCursorStore = class extends WebStorageCursorStore {
+var LocalStorageSessionStore = class extends WebStorageSessionStore {
   constructor(options = {}) {
     if (typeof localStorage === "undefined") {
       throw new StarciteError(
-        "localStorage is not available in this runtime. Use WebStorageCursorStore with a custom storage adapter."
+        "localStorage is not available in this runtime. Use WebStorageSessionStore with a custom storage adapter."
       );
     }
     super(localStorage, options);
   }
 };
 export {
-  InMemoryCursorStore,
-  LocalStorageCursorStore,
+  LocalStorageSessionStore,
   MemoryStore,
   SessionLogConflictError,
   SessionLogGapError,
@@ -1810,6 +2024,6 @@ export {
   StarciteSession,
   StarciteTailError,
   StarciteTokenExpiredError,
-  WebStorageCursorStore
+  WebStorageSessionStore
 };
 //# sourceMappingURL=index.js.map