@starcite/sdk 0.0.2 → 0.0.4

package/dist/index.js

@@ -1,6 +1,106 @@
-// src/client.ts
+// src/auth.ts
+import { decodeJwt } from "jose";
 import { z as z2 } from "zod";
 
+// src/identity.ts
+import { z } from "zod";
+var AGENT_PREFIX = "agent:";
+var USER_PREFIX = "user:";
+var PrincipalTypeSchema = z.enum(["user", "agent"]);
+var SessionCreatorPrincipalSchema = z.object({
+  tenant_id: z.string().min(1),
+  id: z.string().min(1),
+  type: PrincipalTypeSchema
+});
+var SessionTokenPrincipalSchema = z.object({
+  type: PrincipalTypeSchema,
+  id: z.string().min(1)
+});
+var StarciteIdentity = class {
+  tenantId;
+  id;
+  type;
+  constructor(options) {
+    this.tenantId = options.tenantId;
+    this.id = options.id;
+    this.type = options.type;
+  }
+  /**
+   * Serializes to the `creator_principal` wire format expected by the API.
+   */
+  toCreatorPrincipal() {
+    return { tenant_id: this.tenantId, id: this.id, type: this.type };
+  }
+  /**
+   * Serializes to the `principal` wire format used in session token requests.
+   */
+  toTokenPrincipal() {
+    return { id: this.id, type: this.type };
+  }
+  /**
+   * Returns the actor string derived from this identity (e.g. `agent:planner`, `user:alice`).
+   */
+  toActor() {
+    if (this.id.startsWith(AGENT_PREFIX) || this.id.startsWith(USER_PREFIX)) {
+      return this.id;
+    }
+    return `${this.type}:${this.id}`;
+  }
+};
+function agentFromActor(actor) {
+  return actor.startsWith(AGENT_PREFIX) ? actor.slice(AGENT_PREFIX.length) : void 0;
+}
+
+// src/auth.ts
+var ApiKeyClaimsSchema = z2.object({
+  iss: z2.string().min(1).optional(),
+  sub: z2.string().min(1).optional(),
+  tenant_id: z2.string().min(1).optional(),
+  principal_id: z2.string().min(1).optional(),
+  principal_type: PrincipalTypeSchema.optional()
+});
+var SessionTokenClaimsSchema = z2.object({
+  session_id: z2.string().min(1).optional(),
+  sub: z2.string().min(1).optional(),
+  tenant_id: z2.string().min(1),
+  principal_id: z2.string().min(1).optional(),
+  principal_type: PrincipalTypeSchema.optional()
+});
+function inferIssuerAuthorityFromApiKey(apiKey) {
+  const claims = ApiKeyClaimsSchema.parse(decodeJwt(apiKey));
+  if (!claims.iss) {
+    return void 0;
+  }
+  const url = new URL(claims.iss);
+  return url.origin;
+}
+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)) {
+    return void 0;
+  }
+  return new StarciteIdentity({
+    tenantId,
+    id,
+    type: claims.principal_type
+  });
+}
+function decodeSessionToken(token) {
+  const claims = SessionTokenClaimsSchema.parse(decodeJwt(token));
+  const principalId = claims.principal_id ?? claims.sub ?? "session-user";
+  const principalType = claims.principal_type ?? "user";
+  return {
+    sessionId: claims.session_id,
+    identity: new StarciteIdentity({
+      tenantId: claims.tenant_id,
+      id: principalId,
+      type: principalType
+    })
+  };
+}
+
 // src/errors.ts
 var StarciteError = class extends Error {
   constructor(message) {
@@ -29,765 +129,1674 @@ var StarciteConnectionError = class extends StarciteError {
     this.name = "StarciteConnectionError";
   }
 };
+var StarciteTailError = class extends StarciteConnectionError {
+  /** Session id tied to this tail stream. */
+  sessionId;
+  /** Failure stage in the tail lifecycle. */
+  stage;
+  /** Reconnect attempts observed before failing. */
+  attempts;
+  /** WebSocket close code when available. */
+  closeCode;
+  /** WebSocket close reason when available. */
+  closeReason;
+  constructor(message, options) {
+    super(message);
+    this.name = "StarciteTailError";
+    this.sessionId = options.sessionId;
+    this.stage = options.stage;
+    this.attempts = options.attempts ?? 0;
+    this.closeCode = options.closeCode;
+    this.closeReason = options.closeReason;
+  }
+};
+var StarciteTokenExpiredError = class extends StarciteTailError {
+  constructor(message, options) {
+    super(message, { ...options, stage: "stream" });
+    this.name = "StarciteTokenExpiredError";
+  }
+};
+var StarciteBackpressureError = class extends StarciteTailError {
+  constructor(message, options) {
+    super(message, { ...options, stage: "consumer_backpressure" });
+    this.name = "StarciteBackpressureError";
+  }
+};
+var StarciteRetryLimitError = class extends StarciteTailError {
+  constructor(message, options) {
+    super(message, { ...options, stage: "retry_limit" });
+    this.name = "StarciteRetryLimitError";
+  }
+};
+
+// src/session.ts
+import EventEmitter3 from "eventemitter3";
+
+// src/session-log.ts
+import EventEmitter from "eventemitter3";
+var SessionLogGapError = class extends StarciteError {
+  constructor(message) {
+    super(message);
+    this.name = "SessionLogGapError";
+  }
+};
+var SessionLogConflictError = class extends StarciteError {
+  constructor(message) {
+    super(message);
+    this.name = "SessionLogConflictError";
+  }
+};
+var SessionLog = class {
+  history = [];
+  emitter = new EventEmitter();
+  canonicalBySeq = /* @__PURE__ */ new Map();
+  maxEvents;
+  appliedSeq = 0;
+  constructor(options = {}) {
+    this.setMaxEvents(options.maxEvents);
+  }
+  setMaxEvents(maxEvents) {
+    if (maxEvents !== void 0 && (!Number.isInteger(maxEvents) || maxEvents <= 0)) {
+      throw new StarciteError(
+        "Session log maxEvents must be a positive integer"
+      );
+    }
+    this.maxEvents = maxEvents;
+    this.enforceRetention();
+  }
+  applyBatch(batch) {
+    const applied = [];
+    for (const event of batch) {
+      if (this.apply(event)) {
+        applied.push(event);
+        this.emitter.emit("event", event);
+      }
+    }
+    return applied;
+  }
+  hydrate(state) {
+    if (!Number.isInteger(state.cursor) || state.cursor < 0) {
+      throw new StarciteError(
+        "Session store cursor must be a non-negative integer"
+      );
+    }
+    this.history.length = 0;
+    this.canonicalBySeq.clear();
+    this.appliedSeq = state.cursor;
+    let previousSeq;
+    for (const event of state.events) {
+      if (event.seq > state.cursor) {
+        throw new StarciteError(
+          `Session store contains event seq ${event.seq} above cursor ${state.cursor}`
+        );
+      }
+      if (previousSeq !== void 0 && event.seq !== previousSeq + 1) {
+        throw new StarciteError(
+          `Session store events must be contiguous; saw seq ${event.seq} after ${previousSeq}`
+        );
+      }
+      this.history.push(event);
+      this.canonicalBySeq.set(event.seq, JSON.stringify(event));
+      previousSeq = event.seq;
+    }
+    this.enforceRetention();
+  }
+  subscribe(listener, options = {}) {
+    const shouldReplay = options.replay ?? true;
+    if (shouldReplay) {
+      for (const event of this.history) {
+        listener(event);
+      }
+    }
+    this.emitter.on("event", listener);
+    return () => {
+      this.emitter.off("event", listener);
+    };
+  }
+  apply(event) {
+    const existingCanonical = this.canonicalBySeq.get(event.seq);
+    if (event.seq <= this.appliedSeq) {
+      const incomingCanonical = JSON.stringify(event);
+      if (!existingCanonical) {
+        const oldestRetainedSeq = this.history[0]?.seq;
+        if (oldestRetainedSeq === void 0 || event.seq < oldestRetainedSeq) {
+          return false;
+        }
+        throw new SessionLogConflictError(
+          `Session log has no canonical payload for retained seq ${event.seq}`
+        );
+      }
+      if (incomingCanonical !== existingCanonical) {
+        throw new SessionLogConflictError(
+          `Session log conflict for seq ${event.seq}: received different payload for an already-applied event`
+        );
+      }
+      return false;
+    }
+    const expectedSeq = this.appliedSeq + 1;
+    if (event.seq !== expectedSeq) {
+      throw new SessionLogGapError(
+        `Session log gap detected: expected seq ${expectedSeq} but received ${event.seq}`
+      );
+    }
+    this.history.push(event);
+    this.canonicalBySeq.set(event.seq, JSON.stringify(event));
+    this.appliedSeq = event.seq;
+    this.enforceRetention();
+    return true;
+  }
+  getSnapshot(syncing) {
+    return {
+      events: this.history.slice(),
+      lastSeq: this.appliedSeq,
+      syncing
+    };
+  }
+  get events() {
+    return this.history.slice();
+  }
+  get cursor() {
+    return this.appliedSeq;
+  }
+  get lastSeq() {
+    return this.appliedSeq;
+  }
+  enforceRetention() {
+    if (this.maxEvents === void 0) {
+      return;
+    }
+    while (this.history.length > this.maxEvents) {
+      const removed = this.history.shift();
+      if (!removed) {
+        return;
+      }
+      this.canonicalBySeq.delete(removed.seq);
+    }
+  }
+};
+
+// src/tail/frame.ts
+import { z as z4 } from "zod";
 
 // src/types.ts
-import { z } from "zod";
-var ArbitraryObjectSchema = z.record(z.unknown());
-var CreatorTypeSchema = z.union([z.literal("user"), z.literal("agent")]);
-var SessionCreatorPrincipalSchema = z.object({
-  tenant_id: z.string().min(1),
-  id: z.string().min(1),
-  type: CreatorTypeSchema
+import { z as z3 } from "zod";
+var SessionCreatorPrincipalSchema2 = SessionCreatorPrincipalSchema;
+var SessionTokenPrincipalSchema2 = SessionTokenPrincipalSchema;
+var ArbitraryObjectSchema = z3.record(z3.unknown());
+var SessionTokenScopeSchema = z3.enum(["session:read", "session:append"]);
+var IssueSessionTokenInputSchema = z3.object({
+  session_id: z3.string().min(1),
+  principal: SessionTokenPrincipalSchema2,
+  scopes: z3.array(SessionTokenScopeSchema).min(1),
+  ttl_seconds: z3.number().int().positive().max(24 * 60 * 60).optional()
 });
-var CreateSessionInputSchema = z.object({
-  id: z.string().optional(),
-  title: z.string().optional(),
+var IssueSessionTokenResponseSchema = z3.object({
+  token: z3.string().min(1),
+  expires_in: z3.number().int().positive()
+});
+var CreateSessionInputSchema = z3.object({
+  id: z3.string().optional(),
+  title: z3.string().optional(),
   metadata: ArbitraryObjectSchema.optional(),
-  creator_principal: SessionCreatorPrincipalSchema.optional()
+  creator_principal: SessionCreatorPrincipalSchema2.optional()
 });
-var SessionRecordSchema = z.object({
-  id: z.string(),
-  title: z.string().nullable().optional(),
+var SessionRecordSchema = z3.object({
+  id: z3.string(),
+  title: z3.string().nullable().optional(),
   metadata: ArbitraryObjectSchema,
-  last_seq: z.number().int().nonnegative(),
-  created_at: z.string(),
-  updated_at: z.string()
+  last_seq: z3.number().int().nonnegative(),
+  created_at: z3.string(),
+  updated_at: z3.string()
 });
-var SessionListItemSchema = z.object({
-  id: z.string(),
-  title: z.string().nullable().optional(),
+var SessionListItemSchema = z3.object({
+  id: z3.string(),
+  title: z3.string().nullable().optional(),
   metadata: ArbitraryObjectSchema,
-  created_at: z.string()
+  created_at: z3.string()
 });
-var SessionListPageSchema = z.object({
-  sessions: z.array(SessionListItemSchema),
-  next_cursor: z.string().nullable()
+var SessionListPageSchema = z3.object({
+  sessions: z3.array(SessionListItemSchema),
+  next_cursor: z3.string().nullable()
 });
-var AppendEventRequestSchema = z.object({
-  type: z.string().min(1),
+var AppendEventRequestSchema = z3.object({
+  type: z3.string().min(1),
   payload: ArbitraryObjectSchema,
-  actor: z.string().min(1),
-  producer_id: z.string().min(1),
-  producer_seq: z.number().int().positive(),
-  source: z.string().optional(),
+  actor: z3.string().min(1).optional(),
+  producer_id: z3.string().min(1),
+  producer_seq: z3.number().int().positive(),
+  source: z3.string().optional(),
   metadata: ArbitraryObjectSchema.optional(),
   refs: ArbitraryObjectSchema.optional(),
-  idempotency_key: z.string().optional(),
-  expected_seq: z.number().int().nonnegative().optional()
+  idempotency_key: z3.string().optional(),
+  expected_seq: z3.number().int().nonnegative().optional()
 });
-var AppendEventResponseSchema = z.object({
-  seq: z.number().int().nonnegative(),
-  last_seq: z.number().int().nonnegative(),
-  deduped: z.boolean()
+var AppendEventResponseSchema = z3.object({
+  seq: z3.number().int().nonnegative(),
+  last_seq: z3.number().int().nonnegative(),
+  deduped: z3.boolean()
 });
-var TailEventSchema = z.object({
-  seq: z.number().int().nonnegative(),
-  type: z.string().min(1),
+var TailEventSchema = z3.object({
+  seq: z3.number().int().nonnegative(),
+  type: z3.string().min(1),
   payload: ArbitraryObjectSchema,
-  actor: z.string().min(1),
-  producer_id: z.string().min(1),
-  producer_seq: z.number().int().positive(),
-  source: z.string().optional(),
+  actor: z3.string().min(1),
+  producer_id: z3.string().min(1),
+  producer_seq: z3.number().int().positive(),
+  source: z3.string().optional(),
   metadata: ArbitraryObjectSchema.optional(),
   refs: ArbitraryObjectSchema.optional(),
-  idempotency_key: z.string().nullable().optional(),
-  inserted_at: z.string().optional()
-});
-var SessionEventInternalSchema = TailEventSchema.extend({
-  agent: z.string().optional(),
-  text: z.string().optional()
+  idempotency_key: z3.string().nullable().optional(),
+  inserted_at: z3.string().optional()
 });
-var SessionAppendInputSchema = z.object({
-  agent: z.string().trim().min(1),
-  producerId: z.string().trim().min(1),
-  producerSeq: z.number().int().positive(),
-  text: z.string().optional(),
+var SessionAppendInputSchema = z3.object({
+  text: z3.string().optional(),
   payload: ArbitraryObjectSchema.optional(),
-  type: z.string().optional(),
-  source: z.string().optional(),
+  type: z3.string().optional(),
+  actor: z3.string().trim().min(1).optional(),
+  source: z3.string().optional(),
   metadata: ArbitraryObjectSchema.optional(),
   refs: ArbitraryObjectSchema.optional(),
-  idempotencyKey: z.string().optional(),
-  expectedSeq: z.number().int().nonnegative().optional()
+  idempotencyKey: z3.string().optional(),
+  expectedSeq: z3.number().int().nonnegative().optional()
 }).refine((value) => !!(value.text || value.payload), {
   message: "append() requires either 'text' or an object 'payload'"
 });
-var StarciteErrorPayloadSchema = z.object({
-  error: z.string().optional(),
-  message: z.string().optional()
-}).catchall(z.unknown());
+var SessionListOptionsSchema = z3.object({
+  limit: z3.number().int().positive().optional(),
+  cursor: z3.string().trim().min(1).optional(),
+  metadata: z3.record(z3.string().trim().min(1), z3.string().trim().min(1)).optional()
+});
 
-// src/client.ts
-var DEFAULT_BASE_URL = typeof process !== "undefined" && process.env.STARCITE_BASE_URL ? process.env.STARCITE_BASE_URL : "http://localhost:4000";
-var TRAILING_SLASHES_REGEX = /\/+$/;
-var BEARER_PREFIX_REGEX = /^bearer\s+/i;
-var DEFAULT_TAIL_RECONNECT_DELAY_MS = 3e3;
-var NORMAL_WEBSOCKET_CLOSE_CODE = 1e3;
-var SERVICE_TOKEN_SUB_ORG_PREFIX = "org:";
-var SERVICE_TOKEN_SUB_AGENT_PREFIX = "agent:";
-var SERVICE_TOKEN_SUB_USER_PREFIX = "user:";
-var TailFrameSchema = z2.string().transform((frame, context) => {
+// src/tail/frame.ts
+var MIN_TAIL_BATCH_SIZE = 1;
+var TailFramePayloadSchema = z4.union([
+  TailEventSchema,
+  z4.array(TailEventSchema).min(MIN_TAIL_BATCH_SIZE)
+]);
+function toFrameText(data) {
+  if (typeof data === "string") {
+    return data;
+  }
+  if (data instanceof ArrayBuffer || ArrayBuffer.isView(data)) {
+    return new TextDecoder().decode(data);
+  }
+  return void 0;
+}
+function parseTailFrame(data) {
+  const frameText = toFrameText(data);
+  if (!frameText) {
+    throw new StarciteConnectionError(
+      "Tail frame payload must be a UTF-8 string or binary buffer"
+    );
+  }
+  let framePayload;
   try {
-    return JSON.parse(frame);
+    framePayload = JSON.parse(frameText);
   } catch {
-    context.addIssue({
-      code: z2.ZodIssueCode.custom,
-      message: "Tail frame was not valid JSON"
+    throw new StarciteConnectionError("Tail frame was not valid JSON");
+  }
+  const result = TailFramePayloadSchema.safeParse(framePayload);
+  if (!result.success) {
+    const reason = result.error.issues[0]?.message ?? "Tail frame did not match schema";
+    throw new StarciteConnectionError(reason);
+  }
+  return Array.isArray(result.data) ? result.data : [result.data];
+}
+
+// src/tail/managed-websocket.ts
+import EventEmitter2 from "eventemitter3";
+var NORMAL_CLOSE_CODE = 1e3;
+var INACTIVITY_CLOSE_CODE = 4e3;
+var CONNECTION_TIMEOUT_CLOSE_CODE = 4100;
+var ManagedWebSocket = class extends EventEmitter2 {
+  options;
+  socket;
+  cancelReconnectWait;
+  // Set while a socket run is active so `close()` can synchronously settle it.
+  forceCloseSocket;
+  started = false;
+  closed = false;
+  // Tracks reconnect attempts for backoff and retry-limit accounting.
+  reconnectAttempts = 0;
+  // Shared deferred completion for all callers of waitForClose(), even late ones.
+  donePromise;
+  // Set to `undefined` after resolution so finish() remains idempotent.
+  resolveDone;
+  constructor(options) {
+    super();
+    this.options = options;
+    this.donePromise = new Promise((resolve) => {
+      this.resolveDone = resolve;
     });
-    return z2.NEVER;
-  }
-}).pipe(TailEventSchema);
-var AsyncQueue = class {
-  items = [];
-  waiters = [];
-  settled = false;
-  push(value) {
-    if (this.settled) {
+  }
+  close(code = NORMAL_CLOSE_CODE, reason = "closed") {
+    if (this.closed) {
       return;
     }
-    this.enqueue({ type: "value", value });
-  }
-  close() {
-    if (this.settled) {
+    this.closed = true;
+    this.cancelReconnectWait?.();
+    this.cancelReconnectWait = void 0;
+    if (!this.started) {
+      this.finish({
+        closeCode: code,
+        closeReason: reason,
+        aborted: this.options.signal?.aborted ?? false,
+        graceful: code === NORMAL_CLOSE_CODE
+      });
       return;
     }
-    this.settled = true;
-    this.enqueue({ type: "done" });
-  }
-  fail(error) {
-    if (this.settled) {
+    if (this.forceCloseSocket) {
+      this.forceCloseSocket(code, reason);
       return;
     }
-    this.settled = true;
-    this.enqueue({ type: "error", error: toError(error) });
+    this.socket?.close(code, reason);
   }
-  async next() {
-    const item = this.items.shift() ?? await new Promise((resolve) => {
-      this.waiters.push(resolve);
-    });
-    if (item.type === "value") {
-      return { value: item.value, done: false };
-    }
-    if (item.type === "done") {
-      return { value: void 0, done: true };
-    }
-    throw item.error;
+  resetReconnectAttempts() {
+    this.reconnectAttempts = 0;
   }
-  enqueue(item) {
-    const waiter = this.waiters.shift();
-    if (waiter) {
-      waiter(item);
+  waitForClose() {
+    this.start();
+    return this.donePromise;
+  }
+  start() {
+    if (this.started || this.resolveDone === void 0) {
       return;
     }
-    this.items.push(item);
-  }
-};
-function normalizeBaseUrl(baseUrl) {
-  const trimmed = baseUrl.trim().replace(TRAILING_SLASHES_REGEX, "");
-  return trimmed.endsWith("/v1") ? trimmed : `${trimmed}/v1`;
-}
-function toWebSocketBaseUrl(apiBaseUrl) {
-  if (apiBaseUrl.startsWith("https://")) {
-    return `wss://${apiBaseUrl.slice("https://".length)}`;
-  }
-  if (apiBaseUrl.startsWith("http://")) {
-    return `ws://${apiBaseUrl.slice("http://".length)}`;
+    this.started = true;
+    this.run().catch((error) => {
+      this.emitSafe("fatal", error);
+      this.finish({
+        closeCode: void 0,
+        closeReason: "run failed",
+        aborted: this.options.signal?.aborted ?? false,
+        graceful: false
+      });
+    });
   }
-  throw new StarciteError(
-    `Invalid Starcite base URL '${apiBaseUrl}'. Use http:// or https://.`
-  );
-}
-function defaultWebSocketFactory(url, options = {}) {
-  if (typeof WebSocket === "undefined") {
-    throw new StarciteError(
-      "WebSocket is not available in this runtime. Provide websocketFactory in StarciteClientOptions."
-    );
+  async run() {
+    const finalState = {
+      closeCode: void 0,
+      closeReason: void 0,
+      aborted: this.options.signal?.aborted ?? false,
+      graceful: false
+    };
+    while (!this.closed) {
+      if (this.options.signal?.aborted) {
+        this.closed = true;
+        finalState.aborted = true;
+        break;
+      }
+      const attempt = this.reconnectAttempts + 1;
+      if (!this.emitSafe("connect_attempt", { attempt })) {
+        this.closed = true;
+        break;
+      }
+      if (this.closed) {
+        break;
+      }
+      let socket;
+      try {
+        const url = this.options.url();
+        socket = this.options.websocketFactory(url);
+      } catch (error) {
+        const shouldContinue2 = await this.handleConnectFailure(attempt, error);
+        if (shouldContinue2) {
+          continue;
+        }
+        break;
+      }
+      if (this.closed) {
+        closeQuietly(socket, NORMAL_CLOSE_CODE, "closed");
+        break;
+      }
+      const result = await this.runSocket(socket);
+      const shouldContinue = await this.handleSocketResult(
+        attempt,
+        result,
+        finalState
+      );
+      if (shouldContinue) {
+        continue;
+      }
+      break;
+    }
+    this.finish(finalState);
   }
-  const headers = new Headers(options.headers);
-  if (!hasAnyHeaders(headers)) {
-    return new WebSocket(url);
+  async handleConnectFailure(attempt, error) {
+    const rootCause = toErrorMessage(error);
+    if (!this.emitSafe("connect_failed", { attempt, rootCause })) {
+      this.closed = true;
+      return false;
+    }
+    return await this.scheduleReconnect({
+      attempt,
+      trigger: "connect_failed",
+      rootCause
+    });
   }
-  const headerObject = Object.fromEntries(headers.entries());
-  try {
-    return new WebSocket(url, { headers: headerObject });
-  } catch {
-    throw new StarciteError(
-      "This runtime cannot set WebSocket upgrade headers with the default factory. Provide websocketFactory in StarciteClientOptions."
-    );
+  async handleSocketResult(attempt, result, finalState) {
+    finalState.closeCode = result.closeCode;
+    finalState.closeReason = result.closeReason;
+    finalState.aborted = result.aborted || (this.options.signal?.aborted ?? false);
+    finalState.graceful = !result.sawTransportError && result.closeCode === NORMAL_CLOSE_CODE;
+    if (result.listenerError !== void 0) {
+      this.emitSafe("fatal", result.listenerError);
+      this.closed = true;
+      return false;
+    }
+    if (this.closed || finalState.aborted || finalState.graceful) {
+      return false;
+    }
+    if (!this.emitSafe("dropped", {
+      attempt,
+      closeCode: result.closeCode,
+      closeReason: result.closeReason
+    })) {
+      this.closed = true;
+      return false;
+    }
+    return await this.scheduleReconnect({
+      attempt,
+      trigger: "dropped",
+      closeCode: result.closeCode,
+      closeReason: result.closeReason
+    });
   }
-}
-function defaultFetch(input, init) {
-  if (typeof fetch === "undefined") {
-    throw new StarciteError(
-      "fetch is not available in this runtime. Provide fetch in StarciteClientOptions."
+  async scheduleReconnect(input) {
+    if (!this.options.shouldReconnect || this.closed || this.options.signal?.aborted) {
+      this.closed = true;
+      return false;
+    }
+    if (input.attempt > this.options.reconnectPolicy.maxAttempts) {
+      this.emitSafe("retry_limit", {
+        attempt: input.attempt,
+        trigger: input.trigger,
+        closeCode: input.closeCode,
+        closeReason: input.closeReason,
+        rootCause: input.rootCause
+      });
+      this.closed = true;
+      return false;
+    }
+    const delayMs = reconnectDelayForAttempt(
+      input.attempt,
+      this.options.reconnectPolicy
     );
+    if (!this.emitSafe("reconnect_scheduled", {
+      attempt: input.attempt,
+      delayMs,
+      trigger: input.trigger,
+      closeCode: input.closeCode,
+      closeReason: input.closeReason,
+      rootCause: input.rootCause
+    })) {
+      this.closed = true;
+      return false;
+    }
+    this.reconnectAttempts = input.attempt;
+    const reconnectWait = waitForDelay(delayMs, this.options.signal);
+    this.cancelReconnectWait = reconnectWait.cancel;
+    await reconnectWait.promise;
+    if (this.cancelReconnectWait === reconnectWait.cancel) {
+      this.cancelReconnectWait = void 0;
+    }
+    return !(this.closed || (this.options.signal?.aborted ?? false));
   }
-  return fetch(input, init);
-}
-function toError(error) {
-  if (error instanceof Error) {
-    return error;
+  runSocket(socket) {
+    return new Promise((resolve) => {
+      this.socket = socket;
+      let settled = false;
+      let socketOpen = false;
+      let sawTransportError = false;
+      let aborted = false;
+      let listenerError;
+      let closeCode;
+      let closeReason;
+      let connectionTimeout;
+      let inactivityTimeout;
+      const clearTimers = () => {
+        if (connectionTimeout) {
+          clearTimeout(connectionTimeout);
+          connectionTimeout = void 0;
+        }
+        if (inactivityTimeout) {
+          clearTimeout(inactivityTimeout);
+          inactivityTimeout = void 0;
+        }
+      };
+      const armConnectionTimeout = () => {
+        clearTimeout(connectionTimeout);
+        if (this.options.connectionTimeoutMs <= 0) {
+          return;
+        }
+        connectionTimeout = setTimeout(() => {
+          if (settled || socketOpen || this.closed) {
+            return;
+          }
+          closeAndSettle(CONNECTION_TIMEOUT_CLOSE_CODE, "connection timeout");
+        }, this.options.connectionTimeoutMs);
+      };
+      const armInactivityTimeout = () => {
+        clearTimeout(inactivityTimeout);
+        const timeoutMs = this.options.inactivityTimeoutMs;
+        if (!timeoutMs || timeoutMs <= 0 || this.closed) {
+          return;
+        }
+        inactivityTimeout = setTimeout(() => {
+          if (settled || this.closed) {
+            return;
+          }
+          closeAndSettle(INACTIVITY_CLOSE_CODE, "inactivity timeout");
+        }, timeoutMs);
+      };
+      const closeAndSettle = (code, reason, markAborted = false) => {
+        if (settled) {
+          return;
+        }
+        aborted = aborted || markAborted;
+        closeCode = code;
+        closeReason = reason;
+        try {
+          socket.close(code, reason);
+        } catch {
+        }
+        settle();
+      };
+      const settle = () => {
+        if (settled) {
+          return;
+        }
+        settled = true;
+        clearTimers();
+        socket.removeEventListener("open", onOpen);
+        socket.removeEventListener("message", onMessage);
+        socket.removeEventListener("error", onError);
+        socket.removeEventListener("close", onClose);
+        this.options.signal?.removeEventListener("abort", onAbort);
+        if (this.socket === socket) {
+          this.socket = void 0;
+        }
+        this.forceCloseSocket = void 0;
+        resolve({
+          closeCode,
+          closeReason,
+          sawTransportError,
+          aborted,
+          listenerError
+        });
+      };
+      const onOpen = () => {
+        socketOpen = true;
+        clearTimeout(connectionTimeout);
+        armInactivityTimeout();
+        if (!this.emitSafe("open")) {
+          listenerError = new Error("Managed websocket open listener failed");
+          closeAndSettle(NORMAL_CLOSE_CODE, "listener failed");
+        }
+      };
+      const onMessage = (event) => {
+        armInactivityTimeout();
+        if (!this.emitSafe("message", event.data)) {
+          listenerError = new Error(
+            "Managed websocket message listener failed"
+          );
+          closeAndSettle(NORMAL_CLOSE_CODE, "listener failed");
+        }
+      };
+      const onError = (_event) => {
+        sawTransportError = true;
+      };
+      const onClose = (event) => {
+        closeCode = event.code;
+        closeReason = event.reason;
+        settle();
+      };
+      const onAbort = () => {
+        this.closed = true;
+        closeAndSettle(NORMAL_CLOSE_CODE, "aborted", true);
+      };
+      this.forceCloseSocket = (code, reason, markAborted) => {
+        closeAndSettle(code, reason, markAborted ?? false);
+      };
+      socket.addEventListener("open", onOpen);
+      socket.addEventListener("message", onMessage);
+      socket.addEventListener("error", onError);
+      socket.addEventListener("close", onClose);
+      this.options.signal?.addEventListener("abort", onAbort, { once: true });
+      armConnectionTimeout();
+    });
   }
-  return new Error(typeof error === "string" ? error : "Unknown error");
-}
-function hasAnyHeaders(headers) {
-  for (const _ of headers.keys()) {
-    return true;
+  emitSafe(eventName, payload) {
+    const emitter = this;
+    try {
+      if (payload === void 0) {
+        emitter.emit(eventName);
+      } else {
+        emitter.emit(eventName, payload);
+      }
+      return true;
+    } catch (error) {
+      if (eventName !== "fatal") {
+        emitter.emit("fatal", error);
+      }
+      return false;
+    }
   }
-  return false;
-}
-function formatAuthorizationHeader(apiKey) {
-  const normalized = apiKey.trim();
-  if (normalized.length === 0) {
-    throw new StarciteError("apiKey cannot be empty");
+  finish(event) {
+    if (this.resolveDone === void 0) {
+      return;
+    }
+    this.emit("closed", event);
+    this.removeAllListeners();
+    const resolve = this.resolveDone;
+    this.resolveDone = void 0;
+    resolve();
   }
-  if (BEARER_PREFIX_REGEX.test(normalized)) {
-    return normalized;
+};
+function reconnectDelayForAttempt(attempt, policy) {
+  const exponent = Math.max(0, attempt - 1);
+  const baseDelay = policy.initialDelayMs * policy.multiplier ** exponent;
+  const clamped = Math.min(policy.maxDelayMs, baseDelay);
+  if (policy.jitterRatio <= 0) {
+    return clamped;
   }
-  return `Bearer ${normalized}`;
+  const spread = clamped * policy.jitterRatio;
+  const min = Math.max(0, clamped - spread);
+  const max = clamped + spread;
+  return min + Math.random() * (max - min);
 }
-function firstNonEmptyString(value) {
-  return typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
-}
-function parseJwtSegment(segment) {
-  const base64 = segment.replace(/-/g, "+").replace(/_/g, "/").padEnd(segment.length + (4 - segment.length % 4) % 4, "=");
-  try {
-    if (typeof atob === "function") {
-      return atob(base64);
+function waitForDelay(ms, signal) {
+  if (ms <= 0 || signal?.aborted) {
+    return {
+      promise: Promise.resolve(),
+      cancel: () => void 0
+    };
+  }
+  let timer;
+  let settled = false;
+  let resolvePromise;
+  const onAbort = () => {
+    finish();
+  };
+  const finish = () => {
+    if (settled) {
+      return;
     }
-    if (typeof Buffer !== "undefined") {
-      return Buffer.from(base64, "base64").toString("utf8");
+    settled = true;
+    if (timer) {
+      clearTimeout(timer);
+      timer = void 0;
     }
-  } catch {
-    return void 0;
-  }
-  return void 0;
+    signal?.removeEventListener("abort", onAbort);
+    resolvePromise?.();
+    resolvePromise = void 0;
+  };
+  const promise = new Promise((resolve) => {
+    resolvePromise = resolve;
+    timer = setTimeout(() => {
+      finish();
+    }, ms);
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+  return {
+    promise,
+    cancel: finish
+  };
 }
-function parseJwtClaims(apiKey) {
-  const token = apiKey.replace(BEARER_PREFIX_REGEX, "").trim();
-  const parts = token.split(".");
-  if (parts.length !== 3) {
-    return void 0;
-  }
-  const [, payloadSegment] = parts;
-  if (payloadSegment === void 0) {
-    return void 0;
-  }
-  const payload = parseJwtSegment(payloadSegment);
-  if (payload === void 0) {
-    return void 0;
-  }
+function closeQuietly(socket, code, reason) {
   try {
-    const decoded = JSON.parse(payload);
-    return decoded !== null && typeof decoded === "object" ? decoded : void 0;
+    socket.close(code, reason);
   } catch {
-    return void 0;
   }
 }
-function parseClaimStrings(source, keys) {
-  for (const key of keys) {
-    const value = firstNonEmptyString(source[key]);
-    if (value) {
-      return value;
-    }
-  }
-  return void 0;
+function toErrorMessage(error) {
+  return error instanceof Error ? error.message : String(error);
 }
-function parseActorIdentityFromSubject(subject) {
-  if (subject.startsWith(SERVICE_TOKEN_SUB_AGENT_PREFIX)) {
-    return { id: subject, type: "agent" };
-  }
-  if (subject.startsWith(SERVICE_TOKEN_SUB_USER_PREFIX)) {
-    return { id: subject, type: "user" };
-  }
-  return void 0;
-}
-function parseTenantIdFromSubject(subject) {
-  const actorIdentity = parseActorIdentityFromSubject(subject);
-  if (actorIdentity !== void 0) {
-    return "";
-  }
-  if (subject.startsWith(SERVICE_TOKEN_SUB_ORG_PREFIX)) {
-    return subject.slice(SERVICE_TOKEN_SUB_ORG_PREFIX.length).trim();
-  }
-  return subject;
-}
-function parseCreatorPrincipalFromClaims(claims) {
-  const subject = firstNonEmptyString(claims.sub);
-  const explicitPrincipal = claims.principal && typeof claims.principal === "object" ? claims.principal : void 0;
-  const mergedClaims = explicitPrincipal ? { ...claims, ...explicitPrincipal } : claims;
-  const actorFromSubject = subject ? parseActorIdentityFromSubject(subject) : void 0;
-  const principalTypeFromClaims = parseClaimStrings(mergedClaims, [
-    "principal_type",
-    "principalType",
-    "type"
-  ]);
-  const tenantId = parseClaimStrings(mergedClaims, ["tenant_id", "tenantId"]);
-  const rawPrincipalId = parseClaimStrings(mergedClaims, [
-    "principal_id",
-    "principalId",
-    "id",
-    "sub"
-  ]);
-  const actorFromRawId = rawPrincipalId ? parseActorIdentityFromSubject(rawPrincipalId) : void 0;
-  const principal = {
-    tenant_id: tenantId ?? (subject ? parseTenantIdFromSubject(subject) : ""),
-    id: rawPrincipalId ?? actorFromSubject?.id ?? "",
-    type: principalTypeFromClaims === "agent" || principalTypeFromClaims === "user" ? principalTypeFromClaims : actorFromSubject?.type ?? actorFromRawId?.type ?? "user"
-  };
-  if (principal.tenant_id.length === 0 || principal.id.length === 0 || principal.type.length === 0) {
-    return void 0;
-  }
-  const result = SessionCreatorPrincipalSchema.safeParse(principal);
-  return result.success ? result.data : void 0;
-}
-function parseCreatorPrincipalFromClaimsSafe(apiKey) {
-  const claims = parseJwtClaims(apiKey);
-  return claims ? parseCreatorPrincipalFromClaims(claims) : void 0;
-}
-function parseEventFrame(data) {
-  const result = TailFrameSchema.safeParse(data);
-  if (!result.success) {
-    const reason = result.error.issues[0]?.message ?? "Tail frame did not match schema";
-    throw new StarciteConnectionError(reason);
-  }
-  return result.data;
-}
-function getEventData(event) {
-  if (event && typeof event === "object" && "data" in event) {
-    return event.data;
-  }
-  return void 0;
-}
-function getCloseCode(event) {
-  if (event && typeof event === "object" && "code" in event) {
-    const code = event.code;
-    return typeof code === "number" ? code : void 0;
+
+// src/tail/stream.ts
+var NORMAL_CLOSE_CODE2 = 1e3;
+var TailStream = class {
+  sessionId;
+  token;
+  websocketBaseUrl;
+  websocketFactory;
+  batchSize;
+  agent;
+  follow;
+  shouldReconnect;
+  reconnectPolicy;
+  catchUpIdleMs;
+  connectionTimeoutMs;
+  inactivityTimeoutMs;
+  maxBufferedBatches;
+  signal;
+  onLifecycleEvent;
+  cursor;
+  constructor(input) {
+    const opts = input.options;
+    const follow = opts.follow ?? true;
+    const policy = opts.reconnectPolicy;
+    const mode = policy?.mode === "fixed" ? "fixed" : "exponential";
+    const initialDelayMs = policy?.initialDelayMs ?? 500;
+    this.sessionId = input.sessionId;
+    this.token = input.token;
+    this.websocketBaseUrl = input.websocketBaseUrl;
+    this.websocketFactory = input.websocketFactory;
+    this.cursor = opts.cursor ?? 0;
+    this.batchSize = opts.batchSize;
+    this.agent = opts.agent?.trim();
+    this.follow = follow;
+    this.shouldReconnect = follow ? opts.reconnect ?? true : false;
+    this.catchUpIdleMs = opts.catchUpIdleMs ?? 1e3;
+    this.connectionTimeoutMs = opts.connectionTimeoutMs ?? 4e3;
+    this.inactivityTimeoutMs = opts.inactivityTimeoutMs;
+    this.maxBufferedBatches = opts.maxBufferedBatches ?? 1024;
+    this.signal = opts.signal;
+    this.onLifecycleEvent = opts.onLifecycleEvent;
+    this.reconnectPolicy = {
+      mode,
+      initialDelayMs,
+      maxDelayMs: policy?.maxDelayMs ?? (mode === "fixed" ? initialDelayMs : Math.max(initialDelayMs, 15e3)),
+      multiplier: mode === "fixed" ? 1 : policy?.multiplier ?? 2,
+      jitterRatio: policy?.jitterRatio ?? 0.2,
+      maxAttempts: policy?.maxAttempts ?? Number.POSITIVE_INFINITY
+    };
   }
-  return void 0;
-}
-function getCloseReason(event) {
-  if (event && typeof event === "object" && "reason" in event) {
-    const reason = event.reason;
-    return typeof reason === "string" && reason.length > 0 ? reason : void 0;
+  /**
+   * Pushes batches to a callback, enabling emitter-style consumers.
+   */
+  async subscribe(onBatch) {
+    await this.subscribeWithSignal(onBatch, this.signal);
   }
-  return void 0;
-}
-function describeClose(code, reason) {
-  const codeText = `code ${typeof code === "number" ? code : "unknown"}`;
-  return reason ? `${codeText}, reason '${reason}'` : codeText;
-}
-async function waitForDelay(ms, signal) {
-  if (ms <= 0) {
-    return;
-  }
-  await new Promise((resolve) => {
-    let settled = false;
-    const timeout = setTimeout(() => {
-      if (settled) {
+  async subscribeWithSignal(onBatch, signal) {
+    let streamError;
+    let streamReason = this.follow ? "graceful" : "caught_up";
+    let queuedBatches = 0;
+    let catchUpTimer;
+    let dispatchChain = Promise.resolve();
+    const stream = new ManagedWebSocket({
+      // URL is re-read per attempt by `ManagedWebSocket` and reflects current cursor.
+      url: () => this.buildTailUrl(),
+      websocketFactory: this.websocketFactory,
+      signal,
+      shouldReconnect: this.shouldReconnect,
+      reconnectPolicy: {
+        initialDelayMs: this.reconnectPolicy.initialDelayMs,
+        maxDelayMs: this.reconnectPolicy.maxDelayMs,
+        multiplier: this.reconnectPolicy.multiplier,
+        jitterRatio: this.reconnectPolicy.jitterRatio,
+        maxAttempts: this.reconnectPolicy.maxAttempts
+      },
+      connectionTimeoutMs: this.connectionTimeoutMs,
+      inactivityTimeoutMs: this.inactivityTimeoutMs
+    });
+    const fail = (error) => {
+      if (streamError !== void 0) {
         return;
       }
-      settled = true;
-      if (signal) {
-        signal.removeEventListener("abort", onAbort);
+      streamError = error;
+      stream.close(NORMAL_CLOSE_CODE2, "stream failed");
+    };
+    const emitLifecycle = (event) => {
+      if (!this.onLifecycleEvent) {
+        return;
       }
-      resolve();
-    }, ms);
-    const onAbort = () => {
-      if (settled) {
+      try {
+        this.onLifecycleEvent(event);
+      } catch (error) {
+        fail(error);
+      }
+    };
+    const clearCatchUpTimer = () => {
+      if (catchUpTimer) {
+        clearTimeout(catchUpTimer);
+        catchUpTimer = void 0;
+      }
+    };
+    const scheduleCatchUpClose = () => {
+      if (this.follow) {
+        return;
+      }
+      clearCatchUpTimer();
+      catchUpTimer = setTimeout(() => {
+        streamReason = "caught_up";
+        stream.close(NORMAL_CLOSE_CODE2, "caught up");
+      }, this.catchUpIdleMs);
+    };
+    const dispatchBatch = (batch) => {
+      if (streamError !== void 0) {
+        return;
+      }
+      if (this.maxBufferedBatches > 0 && queuedBatches > this.maxBufferedBatches) {
+        fail(
+          new StarciteBackpressureError(
+            `Tail consumer for session '${this.sessionId}' fell behind after buffering ${this.maxBufferedBatches} batch(es)`,
+            { sessionId: this.sessionId, attempts: 0 }
+          )
+        );
         return;
       }
-      settled = true;
-      clearTimeout(timeout);
-      signal?.removeEventListener("abort", onAbort);
-      resolve();
+      queuedBatches += 1;
+      dispatchChain = dispatchChain.then(async () => {
+        try {
+          await onBatch(batch);
+        } finally {
+          queuedBatches -= 1;
+        }
+      }).catch((error) => {
+        fail(error);
+      });
+    };
+    const onConnectAttempt = (event) => {
+      emitLifecycle({
+        type: "connect_attempt",
+        sessionId: this.sessionId,
+        attempt: event.attempt,
+        cursor: this.cursor
+      });
+    };
+    const onConnectFailed = (event) => {
+      if (!this.shouldReconnect) {
+        fail(
+          new StarciteTailError(
+            `Tail connection failed for session '${this.sessionId}': ${event.rootCause}`,
+            {
+              sessionId: this.sessionId,
+              stage: "connect",
+              attempts: event.attempt - 1
+            }
+          )
+        );
+      }
+    };
+    const onReconnectScheduled = (event) => {
+      emitLifecycle({
+        type: "reconnect_scheduled",
+        sessionId: this.sessionId,
+        attempt: event.attempt,
+        delayMs: event.delayMs,
+        trigger: event.trigger,
+        closeCode: event.closeCode,
+        closeReason: event.closeReason
+      });
+    };
+    const onDropped = (event) => {
+      if (event.closeCode === 4001 || event.closeReason === "token_expired") {
+        fail(
+          new StarciteTokenExpiredError(
+            `Tail token expired for session '${this.sessionId}'. Re-issue a session token and reconnect from the last processed cursor.`,
+            {
+              sessionId: this.sessionId,
+              attempts: event.attempt,
+              closeCode: event.closeCode,
+              closeReason: event.closeReason
+            }
+          )
+        );
+        return;
+      }
+      emitLifecycle({
+        type: "stream_dropped",
+        sessionId: this.sessionId,
+        attempt: event.attempt,
+        closeCode: event.closeCode,
+        closeReason: event.closeReason
+      });
+      if (!this.shouldReconnect) {
+        fail(
+          new StarciteTailError(
+            `Tail connection dropped for session '${this.sessionId}' (${describeClose(event.closeCode, event.closeReason)})`,
+            {
+              sessionId: this.sessionId,
+              stage: "stream",
+              attempts: event.attempt - 1,
+              closeCode: event.closeCode,
+              closeReason: event.closeReason
+            }
+          )
+        );
+      }
+    };
+    const onRetryLimit = (event) => {
+      const message = event.trigger === "connect_failed" ? `Tail connection failed for session '${this.sessionId}' after ${this.reconnectPolicy.maxAttempts} reconnect attempt(s): ${event.rootCause ?? "Unknown error"}` : `Tail connection dropped for session '${this.sessionId}' after ${this.reconnectPolicy.maxAttempts} reconnect attempt(s) (${describeClose(event.closeCode, event.closeReason)})`;
+      fail(
+        new StarciteRetryLimitError(message, {
+          sessionId: this.sessionId,
+          attempts: event.attempt,
+          closeCode: event.closeCode,
+          closeReason: event.closeReason
+        })
+      );
+    };
+    const onOpen = () => {
+      scheduleCatchUpClose();
+    };
+    const onMessage = (data) => {
+      try {
+        const parsedEvents = parseTailFrame(data);
+        const matchingEvents = [];
+        for (const parsedEvent of parsedEvents) {
+          this.cursor = Math.max(this.cursor, parsedEvent.seq);
+          if (this.agent && agentFromActor(parsedEvent.actor) !== this.agent) {
+            continue;
+          }
+          matchingEvents.push(parsedEvent);
+        }
+        if (matchingEvents.length > 0) {
+          stream.resetReconnectAttempts();
+          dispatchBatch(matchingEvents);
+        }
+        scheduleCatchUpClose();
+      } catch (error) {
+        fail(error);
+      }
     };
-    if (signal) {
-      if (signal.aborted) {
-        onAbort();
+    const onFatal = (error) => {
+      fail(error);
+    };
+    const onClosed = (event) => {
+      clearCatchUpTimer();
+      if (event.aborted) {
+        streamReason = "aborted";
+        return;
+      }
+      if (!this.follow) {
+        streamReason = "caught_up";
         return;
       }
-      signal.addEventListener("abort", onAbort, { once: true });
+      if (event.graceful) {
+        streamReason = "graceful";
+      }
+    };
+    stream.on("connect_attempt", onConnectAttempt);
+    stream.on("connect_failed", onConnectFailed);
+    stream.on("reconnect_scheduled", onReconnectScheduled);
+    stream.on("dropped", onDropped);
+    stream.on("retry_limit", onRetryLimit);
+    stream.on("open", onOpen);
+    stream.on("message", onMessage);
+    stream.on("fatal", onFatal);
+    stream.on("closed", onClosed);
+    try {
+      await stream.waitForClose();
+      clearCatchUpTimer();
+      await dispatchChain;
+      if (streamError !== void 0) {
+        throw streamError;
+      }
+      emitLifecycle({
+        type: "stream_ended",
+        sessionId: this.sessionId,
+        reason: streamReason
+      });
+      if (streamError !== void 0) {
+        throw streamError;
+      }
+    } finally {
+      clearCatchUpTimer();
+      stream.off("connect_attempt", onConnectAttempt);
+      stream.off("connect_failed", onConnectFailed);
+      stream.off("reconnect_scheduled", onReconnectScheduled);
+      stream.off("dropped", onDropped);
+      stream.off("retry_limit", onRetryLimit);
+      stream.off("open", onOpen);
+      stream.off("message", onMessage);
+      stream.off("fatal", onFatal);
+      stream.off("closed", onClosed);
+      stream.close(NORMAL_CLOSE_CODE2, "finished");
     }
-  });
+  }
+  buildTailUrl() {
+    const query = new URLSearchParams({ cursor: `${this.cursor}` });
+    if (this.batchSize !== void 0) {
+      query.set("batch_size", `${this.batchSize}`);
+    }
+    if (this.token) {
+      query.set("access_token", this.token);
+    }
+    return `${this.websocketBaseUrl}/sessions/${encodeURIComponent(
+      this.sessionId
+    )}/tail?${query.toString()}`;
+  }
+};
+function describeClose(code, reason) {
+  const codeText = `code ${code ?? "unknown"}`;
+  return reason ? `${codeText}, reason '${reason}'` : codeText;
 }
-function agentFromActor(actor) {
-  if (actor.startsWith("agent:")) {
-    return actor.slice("agent:".length);
+
+// src/transport.ts
+var TRAILING_SLASHES_REGEX = /\/+$/;
+function normalizeAbsoluteHttpUrl(value, context) {
+  const parsed = new URL(value);
+  if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+    throw new StarciteError(`${context} must use http:// or https://`);
   }
-  return void 0;
+  return parsed.toString().replace(TRAILING_SLASHES_REGEX, "");
 }
-function toSessionEvent(event) {
-  const agent = agentFromActor(event.actor);
-  const text = typeof event.payload.text === "string" ? event.payload.text : void 0;
-  return {
-    ...event,
-    agent,
-    text
-  };
+function toApiBaseUrl(baseUrl) {
+  const normalized = normalizeAbsoluteHttpUrl(baseUrl, "baseUrl");
+  return normalized.endsWith("/v1") ? normalized : `${normalized}/v1`;
+}
+function toWebSocketBaseUrl(apiBaseUrl) {
+  const url = new URL(apiBaseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : "ws:";
+  return url.toString().replace(TRAILING_SLASHES_REGEX, "");
+}
+function defaultWebSocketFactory(url) {
+  if (typeof WebSocket === "undefined") {
+    throw new StarciteError(
+      "WebSocket is not available in this runtime. Provide websocketFactory in StarciteOptions."
+    );
+  }
+  return new WebSocket(url);
+}
+function request(transport, path, init, schema) {
+  return requestWithBaseUrl(transport, transport.baseUrl, path, init, schema);
 }
+async function requestWithBaseUrl(transport, baseUrl, path, init, schema) {
+  const headers = new Headers(transport.headers);
+  if (transport.authorization) {
+    headers.set("authorization", transport.authorization);
+  }
+  if (init.body !== void 0 && !headers.has("content-type")) {
+    headers.set("content-type", "application/json");
+  }
+  if (init.headers) {
+    const perRequestHeaders = new Headers(init.headers);
+    for (const [key, value] of perRequestHeaders.entries()) {
+      headers.set(key, value);
+    }
+  }
+  let response;
+  try {
+    response = await transport.fetchFn(`${baseUrl}${path}`, {
+      ...init,
+      headers
+    });
+  } catch (error) {
+    throw new StarciteConnectionError(
+      `Failed to connect to Starcite at ${baseUrl}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (!response.ok) {
+    let payload = null;
+    try {
+      payload = await response.json();
+    } catch {
+    }
+    const code = typeof payload?.error === "string" ? payload.error : `http_${response.status}`;
+    const message = typeof payload?.message === "string" ? payload.message : response.statusText;
+    throw new StarciteApiError(message, response.status, code, payload);
+  }
+  if (response.status === 204) {
+    return schema.parse(void 0);
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (error) {
+    throw new StarciteConnectionError(
+      `Received invalid JSON from Starcite: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  return schema.parse(body);
+}
+
+// src/session.ts
 var StarciteSession = class {
   /** Session identifier. */
   id;
+  /** The session JWT used for auth. Extract this for frontend handoff. */
+  token;
+  /** Identity bound to this session. */
+  identity;
   /** Optional session record captured at creation time. */
   record;
-  client;
-  constructor(client, id, record) {
-    this.client = client;
-    this.id = id;
-    this.record = record;
+  transport;
+  producerId;
+  producerSeq = 0;
+  log;
+  store;
+  lifecycle = new EventEmitter3();
+  eventSubscriptions = /* @__PURE__ */ new Map();
+  liveSyncController;
+  liveSyncTask;
+  constructor(options) {
+    this.id = options.id;
+    this.token = options.token;
+    this.identity = options.identity;
+    this.transport = options.transport;
+    this.record = options.record;
+    this.producerId = crypto.randomUUID();
+    this.store = options.store;
+    this.log = new SessionLog(options.logOptions);
+    const storedState = this.store.load(this.id);
+    if (storedState) {
+      this.log.hydrate(storedState);
+    }
   }
   /**
-   * 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) {
+  async append(input, options) {
     const parsed = SessionAppendInputSchema.parse(input);
-    const actor = parsed.agent.startsWith("agent:") ? parsed.agent : `agent:${parsed.agent}`;
-    return this.client.appendEvent(this.id, {
-      type: parsed.type ?? "content",
-      payload: parsed.payload ?? { text: parsed.text },
-      actor,
-      producer_id: parsed.producerId,
-      producer_seq: parsed.producerSeq,
-      source: parsed.source ?? "agent",
-      metadata: parsed.metadata,
-      refs: parsed.refs,
-      idempotency_key: parsed.idempotencyKey,
-      expected_seq: parsed.expectedSeq
-    });
+    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
+    };
   }
   /**
-   * Appends a raw event payload as-is.
+   * Appends a raw event payload as-is. Caller manages all fields.
    */
-  appendRaw(input) {
-    return this.client.appendEvent(this.id, input);
+  appendRaw(input, options) {
+    return request(
+      this.transport,
+      `/sessions/${encodeURIComponent(this.id)}/append`,
+      {
+        method: "POST",
+        body: JSON.stringify(input),
+        signal: options?.signal
+      },
+      AppendEventResponseSchema
+    );
+  }
+  on(eventName, listener) {
+    if (eventName === "event") {
+      const eventListener = listener;
+      if (!this.eventSubscriptions.has(eventListener)) {
+        const unsubscribe = this.log.subscribe(eventListener, { replay: true });
+        this.eventSubscriptions.set(eventListener, unsubscribe);
+      }
+      this.ensureLiveSync();
+      return () => {
+        this.off("event", eventListener);
+      };
+    }
+    if (eventName === "error") {
+      const errorListener = listener;
+      this.lifecycle.on("error", errorListener);
+      return () => {
+        this.off("error", errorListener);
+      };
+    }
+    throw new StarciteError(`Unsupported event name '${eventName}'`);
+  }
+  off(eventName, listener) {
+    if (eventName === "event") {
+      const eventListener = listener;
+      const unsubscribe = this.eventSubscriptions.get(eventListener);
+      if (!unsubscribe) {
+        return;
+      }
+      this.eventSubscriptions.delete(eventListener);
+      unsubscribe();
+      if (this.eventSubscriptions.size === 0) {
+        this.liveSyncController?.abort();
+      }
+      return;
+    }
+    if (eventName === "error") {
+      this.lifecycle.off("error", listener);
+      return;
+    }
+    throw new StarciteError(`Unsupported event name '${eventName}'`);
   }
   /**
-   * Streams transformed session events with SDK convenience fields (`agent`, `text`).
+   * Stops live syncing and removes listeners registered via `on()`.
    */
-  tail(options = {}) {
-    return this.client.tailEvents(this.id, options);
+  disconnect() {
+    this.liveSyncController?.abort();
+    for (const unsubscribe of this.eventSubscriptions.values()) {
+      unsubscribe();
+    }
+    this.eventSubscriptions.clear();
+    this.lifecycle.removeAllListeners();
   }
   /**
-   * Streams raw tail events returned by the API.
+   * Backwards-compatible alias for `disconnect()`.
    */
-  tailRaw(options = {}) {
-    return this.client.tailRawEvents(this.id, options);
+  close() {
+    this.disconnect();
   }
-};
-var StarciteClient = class {
-  /** Normalized API base URL ending with `/v1`. */
-  baseUrl;
-  inferredCreatorPrincipal;
-  websocketBaseUrl;
-  fetchFn;
-  headers;
-  websocketFactory;
   /**
-   * Creates a new client instance.
+   * Updates in-memory session log retention.
    */
-  constructor(options = {}) {
-    this.baseUrl = normalizeBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
-    this.websocketBaseUrl = toWebSocketBaseUrl(this.baseUrl);
-    this.fetchFn = options.fetch ?? defaultFetch;
-    this.headers = new Headers(options.headers);
-    if (options.apiKey !== void 0) {
-      const authorization = formatAuthorizationHeader(options.apiKey);
-      this.headers.set("authorization", authorization);
-      this.inferredCreatorPrincipal = parseCreatorPrincipalFromClaimsSafe(authorization);
-    }
-    this.websocketFactory = options.websocketFactory ?? defaultWebSocketFactory;
+  setLogOptions(options) {
+    this.log.setMaxEvents(options.maxEvents);
+    this.persistLogState();
   }
   /**
-   * Returns a session helper bound to an existing session id.
+   * Returns a stable snapshot of the current canonical in-memory log.
    */
-  session(sessionId, record) {
-    return new StarciteSession(this, sessionId, record);
+  getSnapshot() {
+    return this.log.getSnapshot(this.liveSyncTask !== void 0);
   }
   /**
-   * Creates a new session and returns a bound `StarciteSession` helper.
+   * Streams tail events one at a time via callback.
    */
-  async create(input = {}) {
-    const record = await this.createSession(input);
-    return this.session(record.id, record);
+  async tail(onEvent, options = {}) {
+    await this.tailBatches(async (batch) => {
+      for (const event of batch) {
+        await onEvent(event);
+      }
+    }, options);
   }
   /**
-   * Creates a new session and returns the raw session record.
+   * Streams tail event batches grouped by incoming frame via callback.
    */
-  createSession(input = {}) {
-    const payload = CreateSessionInputSchema.parse({
-      ...input,
-      creator_principal: input.creator_principal ?? this.inferredCreatorPrincipal
-    });
-    return this.request(
-      "/sessions",
-      {
-        method: "POST",
-        body: JSON.stringify(payload)
-      },
-      SessionRecordSchema
-    );
+  async tailBatches(onBatch, options = {}) {
+    await new TailStream({
+      sessionId: this.id,
+      token: this.token,
+      websocketBaseUrl: this.transport.websocketBaseUrl,
+      websocketFactory: this.transport.websocketFactory,
+      options
+    }).subscribe(onBatch);
   }
   /**
-   * Lists sessions from the archive-backed catalog.
+   * Durably consumes events and checkpoints `event.seq` after each successful handler invocation.
    */
-  listSessions(options = {}) {
-    const query = new URLSearchParams();
-    if (options.limit !== void 0) {
-      if (!Number.isInteger(options.limit) || options.limit <= 0) {
+  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(
-          "listSessions() limit must be a positive integer"
+          `consume() failed to load cursor for session '${this.id}': ${error instanceof Error ? error.message : String(error)}`
         );
       }
-      query.set("limit", `${options.limit}`);
     }
-    if (options.cursor !== void 0) {
-      if (options.cursor.trim().length === 0) {
-        throw new StarciteError("listSessions() cursor cannot be empty");
+    const stream = new TailStream({
+      sessionId: this.id,
+      token: this.token,
+      websocketBaseUrl: this.transport.websocketBaseUrl,
+      websocketFactory: this.transport.websocketFactory,
+      options: {
+        ...tailOptions,
+        cursor
       }
-      query.set("cursor", options.cursor);
-    }
-    if (options.metadata !== void 0) {
-      for (const [key, value] of Object.entries(options.metadata)) {
-        if (key.trim().length === 0 || value.trim().length === 0) {
+    });
+    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(
-            "listSessions() metadata filters must be non-empty strings"
+            `consume() failed to save cursor for session '${this.id}': ${error instanceof Error ? error.message : String(error)}`
           );
         }
-        query.set(`metadata.${key}`, value);
       }
-    }
-    const suffix = query.size > 0 ? `?${query.toString()}` : "";
-    return this.request(
-      `/sessions${suffix}`,
-      {
-        method: "GET"
-      },
-      SessionListPageSchema
-    );
+    });
   }
-  /**
-   * Appends a raw event payload to a specific session.
-   */
-  appendEvent(sessionId, input) {
-    const payload = AppendEventRequestSchema.parse(input);
-    return this.request(
-      `/sessions/${encodeURIComponent(sessionId)}/append`,
-      {
-        method: "POST",
-        body: JSON.stringify(payload)
-      },
-      AppendEventResponseSchema
-    );
+  emitStreamError(error) {
+    const streamError = error instanceof Error ? error : new StarciteError(`Session stream failed: ${String(error)}`);
+    if (this.lifecycle.listenerCount("error") > 0) {
+      this.lifecycle.emit("error", streamError);
+      return;
+    }
+    queueMicrotask(() => {
+      throw streamError;
+    });
   }
-  /**
-   * Opens a WebSocket tail stream and yields raw events.
-   */
-  // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: single-loop reconnect state machine is intentionally explicit for stream correctness.
-  async *tailRawEvents(sessionId, options = {}) {
-    const initialCursor = options.cursor ?? 0;
-    const reconnectEnabled = options.reconnect ?? true;
-    const reconnectDelayMs = options.reconnectDelayMs ?? DEFAULT_TAIL_RECONNECT_DELAY_MS;
-    if (!Number.isInteger(initialCursor) || initialCursor < 0) {
-      throw new StarciteError("tail() cursor must be a non-negative integer");
-    }
-    if (!Number.isFinite(reconnectDelayMs) || reconnectDelayMs < 0) {
-      throw new StarciteError(
-        "tail() reconnectDelayMs must be a non-negative number"
-      );
+  ensureLiveSync() {
+    if (this.liveSyncTask || this.eventSubscriptions.size === 0) {
+      return;
     }
-    let cursor = initialCursor;
-    while (true) {
-      if (options.signal?.aborted) {
-        return;
+    const controller = new AbortController();
+    this.liveSyncController = controller;
+    this.liveSyncTask = this.runLiveSync(controller.signal).catch((error) => {
+      if (!controller.signal.aborted) {
+        this.emitStreamError(error);
       }
-      const wsUrl = `${this.websocketBaseUrl}/sessions/${encodeURIComponent(
-        sessionId
-      )}/tail?cursor=${cursor}`;
-      const websocketHeaders = new Headers();
-      const authorization = this.headers.get("authorization");
-      if (authorization) {
-        websocketHeaders.set("authorization", authorization);
-      }
-      let socket;
-      try {
-        socket = this.websocketFactory(
-          wsUrl,
-          hasAnyHeaders(websocketHeaders) ? {
-            headers: websocketHeaders
-          } : void 0
-        );
-      } catch (error) {
-        const rootCause = toError(error).message;
-        if (!reconnectEnabled || options.signal?.aborted) {
-          throw new StarciteConnectionError(
-            `Tail connection failed for session '${sessionId}': ${rootCause}`
-          );
-        }
-        await waitForDelay(reconnectDelayMs, options.signal);
-        continue;
-      }
-      const queue = new AsyncQueue();
-      let sawTransportError = false;
-      let closeCode;
-      let closeReason;
-      let abortRequested = false;
-      const onMessage = (event) => {
-        try {
-          const parsed = parseEventFrame(getEventData(event));
-          cursor = Math.max(cursor, parsed.seq);
-          if (options.agent && agentFromActor(parsed.actor) !== options.agent) {
-            return;
-          }
-          queue.push(parsed);
-        } catch (error) {
-          queue.fail(error);
-        }
-      };
-      const onError = () => {
-        sawTransportError = true;
-        queue.close();
-      };
-      const onClose = (event) => {
-        closeCode = getCloseCode(event);
-        closeReason = getCloseReason(event);
-        queue.close();
-      };
-      const onAbort = () => {
-        abortRequested = true;
-        queue.close();
-        socket.close(NORMAL_WEBSOCKET_CLOSE_CODE, "aborted");
-      };
-      socket.addEventListener("message", onMessage);
-      socket.addEventListener("error", onError);
-      socket.addEventListener("close", onClose);
-      if (options.signal) {
-        if (options.signal.aborted) {
-          onAbort();
-        } else {
-          options.signal.addEventListener("abort", onAbort, { once: true });
+    }).finally(() => {
+      this.liveSyncTask = void 0;
+      this.liveSyncController = void 0;
+    });
+  }
+  async runLiveSync(signal) {
+    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
         }
-      }
-      let iterationError = null;
+      });
       try {
-        while (true) {
-          const next = await queue.next();
-          if (next.done) {
-            break;
+        await stream.subscribe((batch) => {
+          const appliedEvents = this.log.applyBatch(batch);
+          if (appliedEvents.length > 0) {
+            this.persistLogState();
           }
-          yield next.value;
-        }
+        });
       } catch (error) {
-        iterationError = toError(error);
-      } finally {
-        socket.removeEventListener("message", onMessage);
-        socket.removeEventListener("error", onError);
-        socket.removeEventListener("close", onClose);
-        if (options.signal) {
-          options.signal.removeEventListener("abort", onAbort);
+        if (signal.aborted) {
+          return;
         }
-        socket.close(NORMAL_WEBSOCKET_CLOSE_CODE, "finished");
-      }
-      if (iterationError) {
-        throw iterationError;
-      }
-      if (abortRequested || options.signal?.aborted) {
-        return;
-      }
-      const gracefullyClosed = !sawTransportError && closeCode === NORMAL_WEBSOCKET_CLOSE_CODE;
-      if (gracefullyClosed) {
-        return;
-      }
-      if (!reconnectEnabled) {
-        throw new StarciteConnectionError(
-          `Tail connection dropped for session '${sessionId}' (${describeClose(
-            closeCode,
-            closeReason
-          )})`
-        );
+        if (error instanceof SessionLogGapError) {
+          continue;
+        }
+        throw error;
       }
-      await waitForDelay(reconnectDelayMs, options.signal);
     }
   }
+  persistLogState() {
+    this.store.save(this.id, {
+      cursor: this.log.cursor,
+      events: [...this.log.events]
+    });
+  }
+};
+
+// 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);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = globalThis.process?.env?.STARCITE_BASE_URL ?? "http://localhost:4000";
+var DEFAULT_AUTH_URL = globalThis.process?.env?.STARCITE_AUTH_URL;
+function resolveAuthBaseUrl(explicitAuthUrl, apiKey) {
+  if (explicitAuthUrl) {
+    return normalizeAbsoluteHttpUrl(explicitAuthUrl, "authUrl");
+  }
+  if (DEFAULT_AUTH_URL) {
+    return normalizeAbsoluteHttpUrl(DEFAULT_AUTH_URL, "STARCITE_AUTH_URL");
+  }
+  if (apiKey) {
+    return inferIssuerAuthorityFromApiKey(apiKey);
+  }
+  return void 0;
+}
+var Starcite = class {
+  /** Normalized API base URL ending with `/v1`. */
+  baseUrl;
+  transport;
+  authBaseUrl;
+  inferredIdentity;
+  store;
+  constructor(options = {}) {
+    const baseUrl = toApiBaseUrl(options.baseUrl ?? DEFAULT_BASE_URL);
+    this.baseUrl = baseUrl;
+    const userFetch = options.fetch;
+    const fetchFn = userFetch ? (input, init) => userFetch(input, init) : (input, init) => fetch(input, init);
+    const headers = new Headers(options.headers);
+    const apiKey = options.apiKey?.trim();
+    let authorization;
+    if (apiKey) {
+      authorization = `Bearer ${apiKey}`;
+      this.inferredIdentity = inferIdentityFromApiKey(apiKey);
+    }
+    this.authBaseUrl = resolveAuthBaseUrl(options.authUrl, apiKey);
+    const websocketFactory = options.websocketFactory ?? defaultWebSocketFactory;
+    this.store = options.store ?? new MemoryStore();
+    this.transport = {
+      baseUrl,
+      websocketBaseUrl: toWebSocketBaseUrl(baseUrl),
+      authorization: authorization ?? null,
+      fetchFn,
+      headers,
+      websocketFactory
+    };
+  }
+  /**
+   * Creates a user identity bound to this client's tenant.
+   */
+  user(options) {
+    return new StarciteIdentity({
+      tenantId: this.requireTenantId("user()"),
+      id: options.id,
+      type: "user"
+    });
+  }
   /**
-   * Opens a WebSocket tail stream and yields transformed session events.
+   * Creates an agent identity bound to this client's tenant.
    */
-  async *tailEvents(sessionId, options = {}) {
-    for await (const rawEvent of this.tailRawEvents(sessionId, options)) {
-      yield toSessionEvent(rawEvent);
+  agent(options) {
+    return new StarciteIdentity({
+      tenantId: this.requireTenantId("agent()"),
+      id: options.id,
+      type: "agent"
+    });
+  }
+  session(input) {
+    if ("token" in input) {
+      return this.sessionFromToken(input.token, input.logOptions);
     }
+    return this.sessionFromIdentity(input);
   }
-  async request(path, init, schema) {
-    const headers = new Headers(this.headers);
-    if (!headers.has("content-type")) {
-      headers.set("content-type", "application/json");
+  /**
+   * Lists sessions from the archive-backed catalog.
+   */
+  listSessions(options = {}, requestOptions) {
+    const parsed = SessionListOptionsSchema.parse(options);
+    const query = new URLSearchParams();
+    if (parsed.limit !== void 0) {
+      query.set("limit", `${parsed.limit}`);
+    }
+    if (parsed.cursor !== void 0) {
+      query.set("cursor", parsed.cursor);
     }
-    if (init.headers) {
-      const perRequestHeaders = new Headers(init.headers);
-      for (const [key, value] of perRequestHeaders.entries()) {
-        headers.set(key, value);
+    if (parsed.metadata !== void 0) {
+      for (const [key, value] of Object.entries(parsed.metadata)) {
+        query.set(`metadata.${key}`, value);
       }
     }
-    let response;
-    try {
-      response = await this.fetchFn(`${this.baseUrl}${path}`, {
-        ...init,
-        headers
+    const suffix = query.size > 0 ? `?${query.toString()}` : "";
+    return request(
+      this.transport,
+      `/sessions${suffix}`,
+      {
+        method: "GET",
+        signal: requestOptions?.signal
+      },
+      SessionListPageSchema
+    );
+  }
+  async sessionFromIdentity(input) {
+    let sessionId = input.id;
+    let record;
+    if (!sessionId) {
+      record = await this.createSession({
+        creator_principal: input.identity.toCreatorPrincipal(),
+        title: input.title,
+        metadata: input.metadata
       });
-    } catch (error) {
-      const rootCause = toError(error).message;
-      throw new StarciteConnectionError(
-        `Failed to connect to Starcite at ${this.baseUrl}: ${rootCause}`
+      sessionId = record.id;
+    }
+    const tokenResponse = await this.issueSessionToken({
+      session_id: sessionId,
+      principal: input.identity.toTokenPrincipal(),
+      scopes: ["session:read", "session:append"]
+    });
+    return new StarciteSession({
+      id: sessionId,
+      token: tokenResponse.token,
+      identity: input.identity,
+      transport: this.buildSessionTransport(tokenResponse.token),
+      store: this.store,
+      record,
+      logOptions: input.logOptions
+    });
+  }
+  sessionFromToken(token, logOptions) {
+    const decoded = decodeSessionToken(token);
+    const sessionId = decoded.sessionId;
+    if (!sessionId) {
+      throw new StarciteError(
+        "session({ token }) requires a token with a session_id claim."
       );
     }
-    if (!response.ok) {
-      const payload = await tryParseJson(response);
-      const code = typeof payload?.error === "string" ? payload.error : `http_${response.status}`;
-      const message = typeof payload?.message === "string" ? payload.message : response.statusText;
-      throw new StarciteApiError(message, response.status, code, payload);
+    return new StarciteSession({
+      id: sessionId,
+      token,
+      identity: decoded.identity,
+      transport: this.buildSessionTransport(token),
+      store: this.store,
+      logOptions
+    });
+  }
+  buildSessionTransport(token) {
+    return {
+      ...this.transport,
+      authorization: `Bearer ${token}`
+    };
+  }
+  createSession(input) {
+    return request(
+      this.transport,
+      "/sessions",
+      {
+        method: "POST",
+        body: JSON.stringify(input)
+      },
+      SessionRecordSchema
+    );
+  }
+  issueSessionToken(input) {
+    if (!this.transport.authorization) {
+      throw new StarciteError(
+        "session() with identity requires apiKey. Set StarciteOptions.apiKey."
+      );
     }
-    if (response.status === 204) {
-      return void 0;
+    if (!this.authBaseUrl) {
+      throw new StarciteError(
+        "session() could not resolve auth issuer URL. Set StarciteOptions.authUrl, STARCITE_AUTH_URL, or use an API key JWT with an 'iss' claim."
+      );
     }
-    const responseBody = await response.json();
-    if (!schema) {
-      return responseBody;
+    return requestWithBaseUrl(
+      this.transport,
+      this.authBaseUrl,
+      "/api/v1/session-tokens",
+      {
+        method: "POST",
+        headers: {
+          "cache-control": "no-store"
+        },
+        body: JSON.stringify(input)
+      },
+      IssueSessionTokenResponseSchema
+    );
+  }
+  requireTenantId(method) {
+    const tenantId = this.inferredIdentity?.tenantId;
+    if (!tenantId) {
+      throw new StarciteError(`${method} requires apiKey to determine tenant.`);
     }
-    const parsed = schema.safeParse(responseBody);
-    if (!parsed.success) {
-      const issue = parsed.error.issues[0]?.message ?? "invalid response";
-      throw new StarciteConnectionError(
-        `Received unexpected response payload from Starcite: ${issue}`
-      );
+    return tenantId;
+  }
+};
+
+// src/cursor-store.ts
+var DEFAULT_KEY_PREFIX = "starcite";
+var InMemoryCursorStore = class {
+  cursors;
+  constructor(initial = {}) {
+    this.cursors = new Map(Object.entries(initial));
+  }
+  load(sessionId) {
+    return this.cursors.get(sessionId);
+  }
+  save(sessionId, cursor) {
+    this.cursors.set(sessionId, cursor);
+  }
+};
+var WebStorageCursorStore = class {
+  storage;
+  keyForSession;
+  constructor(storage, options = {}) {
+    this.storage = storage;
+    const prefix = options.keyPrefix?.trim() || DEFAULT_KEY_PREFIX;
+    this.keyForSession = options.keyForSession ?? ((sessionId) => `${prefix}:${sessionId}:lastSeq`);
+  }
+  load(sessionId) {
+    const raw = this.storage.getItem(this.keyForSession(sessionId));
+    if (raw === null) {
+      return void 0;
     }
-    return parsed.data;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : void 0;
+  }
+  save(sessionId, cursor) {
+    this.storage.setItem(this.keyForSession(sessionId), `${cursor}`);
   }
 };
-async function tryParseJson(response) {
-  try {
-    const parsed = await response.json();
-    const result = StarciteErrorPayloadSchema.safeParse(parsed);
-    return result.success ? result.data : null;
-  } catch {
-    return null;
+var LocalStorageCursorStore = class extends WebStorageCursorStore {
+  constructor(options = {}) {
+    if (typeof localStorage === "undefined") {
+      throw new StarciteError(
+        "localStorage is not available in this runtime. Use WebStorageCursorStore with a custom storage adapter."
+      );
+    }
+    super(localStorage, options);
   }
-}
-
-// src/index.ts
-function createStarciteClient(options = {}) {
-  return new StarciteClient(options);
-}
-var starcite = createStarciteClient();
+};
 export {
+  InMemoryCursorStore,
+  LocalStorageCursorStore,
+  MemoryStore,
+  SessionLogConflictError,
+  SessionLogGapError,
+  Starcite,
   StarciteApiError,
-  StarciteClient,
+  StarciteBackpressureError,
   StarciteConnectionError,
   StarciteError,
+  StarciteIdentity,
+  StarciteRetryLimitError,
   StarciteSession,
-  createStarciteClient,
-  normalizeBaseUrl,
-  starcite
+  StarciteTailError,
+  StarciteTokenExpiredError,
+  WebStorageCursorStore
 };
 //# sourceMappingURL=index.js.map