basalt-ui 1.11.0 → 1.13.0

package/dist/agent/adapter.d.ts

@@ -0,0 +1,150 @@
+import type { ChatMessage } from './history.js';
+import type { AgentOutcome } from './outcome.js';
+import type { AgentPart } from './parts.js';
+import type { AgentThread, ThreadStatus, ThreadsStore } from './thread.js';
+/**
+ * The async persistence contract behind a `ThreadsStore`. Every method may reject; the wrapping
+ * store treats a rejection as "the optimistic edit did not happen" and rolls it back.
+ *
+ * Implement this against whatever owns the transcript (Postgres, an HTTP API, IndexedDB) and
+ * verify it with `threadsStoreAdapterContract` — the suite pins the parts of the contract that
+ * prose cannot enforce, chiefly `appendMessage`'s idempotency.
+ *
+ * ## What `createAdapterThreadsStore` guarantees you
+ *
+ * **Per-thread write ordering.** Writes carrying the same thread id reach this adapter strictly in
+ * issue order, each one awaiting the previous, so a write that depends on a row existing is never
+ * issued before that row's `createThread` has RESOLVED. This matters because the primary send path
+ * is one synchronous block — `create()`, `select()`, `markRead()`, `appendMessage()`,
+ * `setStatus()` — which without ordering would hand you three dependent writes against a row you
+ * have not created yet. You therefore never have to tolerate (or invent an upsert for) an
+ * out-of-order write. Writes for DIFFERENT thread ids stay concurrent and carry no ordering
+ * guarantee relative to each other.
+ *
+ * ## What it requires of you
+ *
+ * **Read-after-write consistency on `listThreads`.** A `listThreads` STARTED after a write has
+ * resolved must reflect that write. The store keeps a write's optimistic patch applied until such
+ * a list lands, then drops it; an eventually-consistent backend (a stale read replica, a cached
+ * list) will therefore flash the pre-write state back into the UI. `threadsStoreAdapterContract`
+ * pins this.
+ *
+ * @example
+ * const postgresThreadsAdapter = (api: Api): ThreadsStoreAdapter => ({
+ *   listThreads: (signal) => api.threads.get({ fetch: { signal } }),
+ *   loadThread: (id, signal) => api.threads({ id }).get({ fetch: { signal } }),
+ *   createThread: ({ id, meta }) => api.threads.post({ id, meta }),
+ *   // ...
+ * })
+ */
+export type ThreadsStoreAdapter<TPart = AgentPart> = {
+    /** All threads, NEWEST-FIRST (same ordering contract as `ThreadsStore.threads`). */
+    readonly listThreads: (signal?: AbortSignal) => Promise<readonly AgentThread<TPart>[]>;
+    /** One thread by id, or `null` when it does not exist. Must not throw on an unknown id. */
+    readonly loadThread: (id: string, signal?: AbortSignal) => Promise<AgentThread<TPart> | null>;
+    /**
+     * Materialize a new thread under the CLIENT-MINTED `id`. The id is minted client-side because
+     * `ThreadsStore.create()` returns synchronously — there is no await to hand a server id back
+     * through. The created thread starts empty: `messages: []`, `outcome: null`,
+     * `status: 'pending'`, `read: false`, with `createdAt`/`updatedAt` set.
+     */
+    readonly createThread: (i: {
+        readonly id: string;
+        readonly meta?: Record<string, unknown>;
+    }) => Promise<void>;
+    /**
+     * CONTRACT: idempotent on `message.id`. The id is client-minted and is the ONLY idempotency
+     * key — a retried or double-fired write with the same id must be a no-op, not a second row.
+     */
+    readonly appendMessage: (i: {
+        readonly threadId: string;
+        readonly message: ChatMessage<TPart>;
+    }) => Promise<void>;
+    readonly setStatus: (i: {
+        readonly threadId: string;
+        readonly status: ThreadStatus;
+    }) => Promise<void>;
+    readonly setOutcome: (i: {
+        readonly threadId: string;
+        readonly outcome: AgentOutcome;
+    }) => Promise<void>;
+    /** `token: undefined` CLEARS the token — the stored thread must then read `resumeToken` as absent. */
+    readonly setResumeToken: (i: {
+        readonly threadId: string;
+        readonly token: string | undefined;
+    }) => Promise<void>;
+    readonly markRead: (threadId: string) => Promise<void>;
+    /** Removing an unknown id is a no-op, not an error. */
+    readonly removeThread: (threadId: string) => Promise<void>;
+};
+export type AdapterThreadsStoreOptions = {
+    /**
+     * Re-list threads whenever the window regains focus. Off by default — a background tab that
+     * refocuses should not surprise a consumer with a network round-trip it did not ask for.
+     * @default false
+     */
+    readonly revalidateOnFocus?: boolean;
+};
+/**
+ * Wraps an async `ThreadsStoreAdapter` into the synchronous `ThreadsStore` every component takes.
+ *
+ * Call this ONCE per module (not inside a component), exactly like `createThreadsStore`. All
+ * components calling the returned hook share one registry, backed by `useSyncExternalStore`.
+ *
+ * Semantics:
+ * - **Optimistic.** Every mutation applies locally first, so `create()` can return an id
+ *   synchronously and the UI never waits on a round-trip.
+ * - **Ordered per thread.** Writes for one thread id reach the adapter in issue order, each
+ *   awaiting the previous — so the dependent writes of a `create()`-then-send land after
+ *   `createThread` has resolved. Different threads stay concurrent. See `ThreadsStoreAdapter`.
+ * - **Revalidate on success, coalesced.** When a write resolves the store re-lists; the patch is
+ *   dropped only once a list has actually refreshed the confirmed base, so server-side derivations
+ *   win over the local guess with no gap in between. Writes that resolve while a list is already in
+ *   flight share ONE follow-up instead of each restarting it, so a burst of writes costs at most
+ *   two round trips (the in-flight one, plus one follow-up), not one per write — see `revalidate`.
+ * - **Roll back on rejection.** A rejected write's patch is discarded, the rejection is surfaced
+ *   on `error`, and the store re-lists to converge on whatever the server really did. Patches are
+ *   tracked individually, so a failing write rolls back only itself and not whatever else was in
+ *   flight beside it. A rejected `create()` additionally drops every later single-thread write for
+ *   that id (`markRead`/`appendMessage`/`setStatus`/… — both the ones chained directly behind it and
+ *   the run's completion writes at stream end) instead of letting each fail independently against a
+ *   row that no longer exists — see `failedCreateIds`. Without that, the create's own error is
+ *   overwritten by a run of "unknown thread" rejections that name nothing a caller can act on.
+ * - **`hydrated` means "a `listThreads` has succeeded"**, not "a load has been attempted". A
+ *   store that is `!hydrated` with a non-undefined `error` failed to load; check both.
+ * - **`error` latches the most recent failure until something disproves it.** A successful
+ *   `listThreads` clears a LOAD failure; it leaves a WRITE failure alone, since a working list is
+ *   no evidence the rejected write landed. A write clears a latched write failure only if it was
+ *   issued after that failure (a retry) — never the writes that were already queued behind it.
+ *
+ * `select` is local-only — which thread is active is UI state, not something the adapter owns.
+ * `clear()` maps onto `removeThread` for each known thread, since the adapter has no bulk delete.
+ *
+ * @example
+ * export const useThreads = createAdapterThreadsStore(myAdapter, { revalidateOnFocus: true })
+ */
+export declare function createAdapterThreadsStore<TPart = AgentPart>(adapter: ThreadsStoreAdapter<TPart>, opts?: AdapterThreadsStoreOptions): () => ThreadsStore<TPart>;
+/** One conformance case. `run` rejects with a plain Error describing the violation. */
+export type ThreadsStoreAdapterContractCase = {
+    readonly name: string;
+    readonly run: () => Promise<void>;
+};
+/**
+ * A test-runner-agnostic conformance suite for a `ThreadsStoreAdapter` implementation.
+ *
+ * This ships in the published package, so it deliberately imports NO test framework and depends
+ * on no assertion library — each case throws a plain `Error`. Drive it from whatever runner the
+ * consumer uses.
+ *
+ * `makeAdapter` is called ONCE PER CASE and must hand back a fresh, empty backend: the cases are
+ * independent and none of them cleans up after itself.
+ *
+ * @example
+ * import { threadsStoreAdapterContract } from 'basalt-ui/agent'
+ *
+ * for (const c of threadsStoreAdapterContract(() => postgresThreadsAdapter(freshDb()))) {
+ *   test(c.name, () => c.run())
+ * }
+ */
+export declare function threadsStoreAdapterContract<TPart>(makeAdapter: () => ThreadsStoreAdapter<TPart> | Promise<ThreadsStoreAdapter<TPart>>): readonly ThreadsStoreAdapterContractCase[];
+//# sourceMappingURL=adapter.d.ts.map

package/dist/agent/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/agent/adapter.ts"],"names":[],"mappings":"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"}

package/dist/agent/adapter.js

@@ -0,0 +1,482 @@
+import { useEffect, useSyncExternalStore } from "react";
+import { mintThreadId } from "./id.js";
+function createAdapterThreadsStore(adapter, opts) {
+  const revalidateOnFocus = opts?.revalidateOnFocus ?? false;
+  const EMPTY = [];
+  const SERVER_SNAPSHOT = {
+    threads: EMPTY,
+    activeId: null,
+    hydrated: false,
+    error: void 0
+  };
+  let base = EMPTY;
+  let baseSeq = 0;
+  let activeId = null;
+  let hydrated = false;
+  let error;
+  let errorToken = 0;
+  let errorFromWrite = false;
+  const pending = [];
+  let snapshot = SERVER_SNAPSHOT;
+  const listeners = /* @__PURE__ */ new Set();
+  function recompute() {
+    let threads = base;
+    let active = activeId;
+    for (const patch of pending) {
+      threads = patch.apply(threads);
+      if (patch.applyActive !== void 0) active = patch.applyActive(active);
+    }
+    snapshot = { threads, activeId: active, hydrated, error };
+    for (const listener of listeners) listener();
+  }
+  function memoizeApply(apply) {
+    let lastIn;
+    let lastOut;
+    return (threads) => {
+      if (lastOut !== void 0 && threads === lastIn) return lastOut;
+      lastIn = threads;
+      lastOut = apply(threads);
+      return lastOut;
+    };
+  }
+  function subscribe(listener) {
+    listeners.add(listener);
+    return () => {
+      listeners.delete(listener);
+    };
+  }
+  function getSnapshot() {
+    return snapshot;
+  }
+  function getServerSnapshot() {
+    return SERVER_SNAPSHOT;
+  }
+  let loadController = null;
+  let loadSeq = 0;
+  let queuedSeq = null;
+  function prune() {
+    const kept = [];
+    for (const patch of pending) {
+      if (patch.confirmSeq !== null && patch.confirmSeq <= baseSeq) {
+        if (patch.applyActive !== void 0) activeId = patch.applyActive(activeId);
+        continue;
+      }
+      kept.push(patch);
+    }
+    if (kept.length !== pending.length) pending.splice(0, pending.length, ...kept);
+  }
+  function startLoad(seq) {
+    const controller = new AbortController();
+    loadController = controller;
+    void (async () => {
+      try {
+        const next = await adapter.listThreads(controller.signal);
+        if (loadController !== controller) return;
+        base = [...next];
+        baseSeq = seq;
+        hydrated = true;
+        if (!errorFromWrite) error = void 0;
+        prune();
+        recompute();
+      } catch (cause) {
+        if (controller.signal.aborted || loadController !== controller) return;
+        error = cause;
+        errorToken += 1;
+        errorFromWrite = false;
+        recompute();
+      } finally {
+        if (loadController === controller) {
+          loadController = null;
+          if (queuedSeq !== null) {
+            const next = queuedSeq;
+            queuedSeq = null;
+            startLoad(next);
+          }
+        }
+      }
+    })();
+  }
+  function revalidate() {
+    if (loadController !== null) {
+      queuedSeq ??= ++loadSeq;
+      return queuedSeq;
+    }
+    const seq = ++loadSeq;
+    startLoad(seq);
+    return seq;
+  }
+  function forceRevalidate() {
+    loadController?.abort();
+    queuedSeq = null;
+    const seq = ++loadSeq;
+    startLoad(seq);
+    return seq;
+  }
+  const chains = /* @__PURE__ */ new Map();
+  const failedCreateIds = /* @__PURE__ */ new Set();
+  function enqueue(threadIds, task) {
+    const ids = [...new Set(threadIds)];
+    const prior = ids.map((id) => chains.get(id)).filter((p) => p !== void 0);
+    const after = prior.length === 0 ? Promise.resolve() : Promise.all(prior).then(() => void 0);
+    const run = after.then(task);
+    for (const id of ids) chains.set(id, run);
+    void run.finally(() => {
+      for (const id of ids) if (chains.get(id) === run) chains.delete(id);
+    });
+  }
+  function drop(patch) {
+    const index = pending.indexOf(patch);
+    if (index !== -1) pending.splice(index, 1);
+  }
+  function mutate(i) {
+    const patch = {
+      apply: memoizeApply(i.apply),
+      ...i.applyActive !== void 0 ? { applyActive: i.applyActive } : {},
+      confirmSeq: null
+    };
+    pending.push(patch);
+    const tokenAtIssue = errorToken;
+    recompute();
+    enqueue(i.threadIds, async () => {
+      const [soleThreadId] = i.threadIds;
+      if (!i.isCreate && i.threadIds.length === 1 && soleThreadId !== void 0 && failedCreateIds.has(soleThreadId)) {
+        drop(patch);
+        recompute();
+        return;
+      }
+      try {
+        await i.commit();
+      } catch (cause) {
+        if (i.isCreate) for (const threadId of i.threadIds) failedCreateIds.add(threadId);
+        drop(patch);
+        error = cause;
+        errorToken += 1;
+        errorFromWrite = true;
+        recompute();
+        revalidate();
+        return;
+      }
+      if (errorFromWrite && errorToken === tokenAtIssue) {
+        error = void 0;
+        errorFromWrite = false;
+        recompute();
+      }
+      patch.confirmSeq = revalidate();
+    });
+  }
+  function patchThread(id, update) {
+    return (threads) => threads.map((thread) => thread.id === id ? update(thread) : thread);
+  }
+  let mounted = 0;
+  function onFocus() {
+    forceRevalidate();
+  }
+  function retain() {
+    mounted += 1;
+    if (mounted !== 1) return;
+    revalidate();
+    if (revalidateOnFocus && typeof window !== "undefined") {
+      window.addEventListener("focus", onFocus);
+    }
+  }
+  function release() {
+    mounted -= 1;
+    if (mounted !== 0) return;
+    loadController?.abort();
+    loadController = null;
+    queuedSeq = null;
+    if (revalidateOnFocus && typeof window !== "undefined") {
+      window.removeEventListener("focus", onFocus);
+    }
+  }
+  function select(id) {
+    activeId = id;
+    recompute();
+  }
+  function create(createOpts) {
+    const id = mintThreadId();
+    const now = Date.now();
+    const thread = {
+      id,
+      messages: [],
+      outcome: null,
+      status: "pending",
+      read: false,
+      createdAt: now,
+      updatedAt: now,
+      ...createOpts?.meta !== void 0 ? { meta: createOpts.meta } : {}
+    };
+    mutate({
+      threadIds: [id],
+      apply: (threads) => threads.some((t) => t.id === id) ? [...threads] : [thread, ...threads],
+      isCreate: true,
+      commit: () => adapter.createThread({
+        id,
+        ...createOpts?.meta !== void 0 ? { meta: createOpts.meta } : {}
+      })
+    });
+    return id;
+  }
+  function appendMessage(id, message2) {
+    const now = Date.now();
+    mutate({
+      threadIds: [id],
+      apply: patchThread(
+        id,
+        (thread) => thread.messages.some((m) => m.id === message2.id) ? thread : { ...thread, messages: [...thread.messages, message2], updatedAt: now }
+      ),
+      commit: () => adapter.appendMessage({ threadId: id, message: message2 })
+    });
+  }
+  function setOutcome(id, outcome) {
+    const now = Date.now();
+    mutate({
+      threadIds: [id],
+      apply: patchThread(id, (thread) => ({ ...thread, outcome, updatedAt: now })),
+      commit: () => adapter.setOutcome({ threadId: id, outcome })
+    });
+  }
+  function setStatus(id, status) {
+    const now = Date.now();
+    mutate({
+      threadIds: [id],
+      apply: patchThread(id, (thread) => ({ ...thread, status, updatedAt: now })),
+      commit: () => adapter.setStatus({ threadId: id, status })
+    });
+  }
+  function setResumeToken(id, token) {
+    const now = Date.now();
+    mutate({
+      threadIds: [id],
+      apply: patchThread(id, (thread) => {
+        const { resumeToken: _resumeToken, ...rest } = thread;
+        return {
+          ...rest,
+          ...token !== void 0 ? { resumeToken: token } : {},
+          updatedAt: now
+        };
+      }),
+      commit: () => adapter.setResumeToken({ threadId: id, token })
+    });
+  }
+  function markRead(id) {
+    mutate({
+      threadIds: [id],
+      // Identity-preserving when the server already agrees — markRead does not bump updatedAt.
+      apply: patchThread(id, (thread) => thread.read ? thread : { ...thread, read: true }),
+      commit: () => adapter.markRead(id)
+    });
+  }
+  function remove(id) {
+    mutate({
+      threadIds: [id],
+      apply: (threads) => threads.filter((thread) => thread.id !== id),
+      // Inside the patch, so a rejected delete restores the SELECTION along with the row. Written
+      // as a conditional clear rather than a flat `null` so a `select()` issued while the delete
+      // is in flight survives the patch being re-applied on top of it.
+      applyActive: (active) => active === id ? null : active,
+      commit: () => adapter.removeThread(id)
+    });
+  }
+  function clear() {
+    const ids = snapshot.threads.map((thread) => thread.id);
+    const clearedIds = new Set(ids);
+    mutate({
+      threadIds: ids,
+      apply: () => [],
+      // Same idiom as remove(): only null a selection pointing at one of the threads THIS clear
+      // captured, so a select() issued while the clear is in flight — e.g. into a thread created
+      // concurrently by create() — survives the patch being re-applied on top of it.
+      applyActive: (active) => active !== null && clearedIds.has(active) ? null : active,
+      commit: async () => {
+        const results = await Promise.allSettled(ids.map((id) => adapter.removeThread(id)));
+        const failures = results.filter((r) => r.status === "rejected");
+        if (failures.length === 0) return;
+        throw new AggregateError(
+          failures.map((f) => f.reason),
+          `removeThread rejected for ${failures.length} of ${ids.length} threads`
+        );
+      }
+    });
+  }
+  return function useAdapterThreadsStore() {
+    const current = useSyncExternalStore(subscribe, getSnapshot, getServerSnapshot);
+    useEffect(() => {
+      retain();
+      return () => {
+        release();
+      };
+    }, []);
+    return {
+      threads: current.threads,
+      activeId: current.activeId,
+      hydrated: current.hydrated,
+      error: current.error,
+      select,
+      create,
+      appendMessage,
+      setOutcome,
+      setStatus,
+      setResumeToken,
+      markRead,
+      remove,
+      clear
+    };
+  };
+}
+function assert(condition, message2) {
+  if (!condition) throw new Error(`ThreadsStoreAdapter contract: ${message2}`);
+}
+function message(id) {
+  return { id, role: "user", parts: [], createdAt: Date.now() };
+}
+function threadsStoreAdapterContract(makeAdapter) {
+  function define(name, run) {
+    return {
+      name,
+      run: async () => {
+        await run(await makeAdapter());
+      }
+    };
+  }
+  async function loadOrThrow(adapter, id) {
+    const thread = await adapter.loadThread(id);
+    assert(thread !== null, `loadThread('${id}') returned null for a thread that was created`);
+    return thread;
+  }
+  return [
+    define("createThread then listThreads returns the thread with empty defaults", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      const threads = await a.listThreads();
+      const found = threads.filter((t) => t.id === id);
+      assert(found.length === 1, `listThreads returned ${found.length} threads for one create`);
+      const thread = found[0];
+      assert(thread !== void 0, "listThreads entry was undefined");
+      assert(thread.messages.length === 0, "a new thread must start with no messages");
+      assert(thread.outcome === null, "a new thread's outcome must be null");
+      assert(thread.status === "pending", `a new thread's status must be 'pending'`);
+      assert(thread.read === false, "a new thread must be unread");
+      assert(typeof thread.createdAt === "number", "createdAt must be a number");
+      assert(typeof thread.updatedAt === "number", "updatedAt must be a number");
+    }),
+    define("createThread persists meta", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id, meta: { source: "contract" } });
+      const thread = await loadOrThrow(a, id);
+      assert(thread.meta?.["source"] === "contract", "meta did not round-trip");
+    }),
+    define("loadThread returns null for an unknown id", async (a) => {
+      const thread = await a.loadThread(mintThreadId());
+      assert(thread === null, "loadThread must return null (not throw, not undefined) when absent");
+    }),
+    define("appendMessage is idempotent on message.id", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      const msg = message("contract-msg-1");
+      await a.appendMessage({ threadId: id, message: msg });
+      await a.appendMessage({ threadId: id, message: msg });
+      const thread = await loadOrThrow(a, id);
+      assert(
+        thread.messages.length === 1,
+        `appending the same message.id twice produced ${thread.messages.length} rows \u2014 the id is the only idempotency key`
+      );
+      assert(thread.messages[0]?.id === "contract-msg-1", "the retained message has the wrong id");
+    }),
+    define("appendMessage preserves order for distinct ids", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      await a.appendMessage({ threadId: id, message: message("contract-msg-1") });
+      await a.appendMessage({ threadId: id, message: message("contract-msg-2") });
+      const thread = await loadOrThrow(a, id);
+      assert(
+        thread.messages.map((m) => m.id).join(",") === "contract-msg-1,contract-msg-2",
+        "messages must read back oldest-first in append order"
+      );
+    }),
+    define("setStatus round-trips", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      await a.setStatus({ threadId: id, status: "streaming" });
+      assert((await loadOrThrow(a, id)).status === "streaming", "status did not become 'streaming'");
+      await a.setStatus({ threadId: id, status: "error" });
+      assert((await loadOrThrow(a, id)).status === "error", "status did not become 'error'");
+    }),
+    define("setOutcome round-trips", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      const outcome = { title: "Title", summary: "Summary", status: "done" };
+      await a.setOutcome({ threadId: id, outcome });
+      const thread = await loadOrThrow(a, id);
+      assert(thread.outcome?.title === "Title", "outcome.title did not round-trip");
+      assert(thread.outcome?.summary === "Summary", "outcome.summary did not round-trip");
+      assert(thread.outcome?.status === "done", "outcome.status did not round-trip");
+    }),
+    define("setResumeToken round-trips and clears with undefined", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      await a.setResumeToken({ threadId: id, token: "tok-1" });
+      assert((await loadOrThrow(a, id)).resumeToken === "tok-1", "resumeToken did not round-trip");
+      await a.setResumeToken({ threadId: id, token: void 0 });
+      assert(
+        (await loadOrThrow(a, id)).resumeToken === void 0,
+        "setResumeToken(undefined) must CLEAR the token"
+      );
+    }),
+    define("markRead marks the thread read", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      assert((await loadOrThrow(a, id)).read === false, "a new thread must start unread");
+      await a.markRead(id);
+      assert((await loadOrThrow(a, id)).read === true, "markRead did not set read");
+    }),
+    define("listThreads reflects a write that has already resolved", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      await a.appendMessage({ threadId: id, message: message("contract-msg-raw") });
+      await a.setStatus({ threadId: id, status: "streaming" });
+      const found = (await a.listThreads()).find((t) => t.id === id);
+      assert(found !== void 0, "listThreads omitted a thread created before the call");
+      assert(
+        found.status === "streaming",
+        "listThreads returned a STALE status \u2014 a list started after a write resolves must reflect it"
+      );
+      assert(
+        found.messages.length === 1,
+        `listThreads returned a STALE message list (${found.messages.length} rows) \u2014 a list started after a write resolves must reflect it`
+      );
+    }),
+    define(
+      "dependent writes issued straight after createThread resolves are honoured",
+      async (a) => {
+        const id = mintThreadId();
+        await a.createThread({ id });
+        await a.markRead(id);
+        await a.appendMessage({ threadId: id, message: message("contract-msg-dep") });
+        await a.setStatus({ threadId: id, status: "streaming" });
+        const thread = await loadOrThrow(a, id);
+        assert(thread.read === true, "markRead did not apply to a just-created thread");
+        assert(
+          thread.messages.length === 1,
+          `appendMessage did not apply to a just-created thread (${thread.messages.length} rows)`
+        );
+        assert(thread.status === "streaming", "setStatus did not apply to a just-created thread");
+      }
+    ),
+    define("removeThread removes the thread", async (a) => {
+      const id = mintThreadId();
+      await a.createThread({ id });
+      await a.removeThread(id);
+      assert(await a.loadThread(id).then((t) => t === null), "loadThread must be null after remove");
+      const threads = await a.listThreads();
+      assert(!threads.some((t) => t.id === id), "listThreads still contains the removed thread");
+    }),
+    define("removeThread of an unknown id does not throw", async (a) => {
+      await a.removeThread(mintThreadId());
+    })
+  ];
+}
+export {
+  createAdapterThreadsStore,
+  threadsStoreAdapterContract
+};

package/dist/agent/adapter.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=adapter.test.d.ts.map

package/dist/agent/adapter.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.test.d.ts","sourceRoot":"","sources":["../../src/agent/adapter.test.ts"],"names":[],"mappings":""}

package/dist/agent/ai-sdk-transport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ai-sdk-transport.d.ts","sourceRoot":"","sources":["../../src/agent/ai-sdk-transport.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,SAAS,CAAA;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAmB1D,MAAM,MAAM,qBAAqB,GAAG;IAClC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAA;IACnD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CACzC,CAAA;AAID,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;IACvF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAC/E,CAAA;AAwRD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,SAAS,EAC9C,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,KAAK,CAAC,CA6CvB"}
+{"version":3,"file":"ai-sdk-transport.d.ts","sourceRoot":"","sources":["../../src/agent/ai-sdk-transport.ts"],"names":[],"mappings":"AAoDA,OAAO,KAAK,EAAE,SAAS,EAAkB,MAAM,SAAS,CAAA;AACxD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAmB1D,MAAM,MAAM,qBAAqB,GAAG;IAClC,kFAAkF;IAClF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,+CAA+C;IAC/C,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAA;IACnD,oFAAoF;IACpF,QAAQ,CAAC,WAAW,CAAC,EAAE,kBAAkB,CAAA;IACzC;;;OAGG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,UAAU,CAAC,KAAK,CAAA;CACzC,CAAA;AAID,MAAM,MAAM,cAAc,CAAC,KAAK,GAAG,SAAS,IAAI,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG;IACvF;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,uBAAuB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAA;CAC/E,CAAA;AAwRD;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,GAAG,SAAS,EAC9C,OAAO,EAAE,qBAAqB,GAC7B,cAAc,CAAC,KAAK,CAAC,CAkDvB"}

package/dist/agent/ai-sdk-transport.js

@@ -1,4 +1,5 @@
 import { assertNever } from "../register.js";
+import { mintMessageId, mintThreadId } from "./id.js";
 import { TERMINAL_TOOL_STATES } from "./parts.js";
 function createAiSdkResolver(options) {
   let resolved;
@@ -161,7 +162,10 @@ function aiSdkTransport(options) {
         yield { id: `${chatId}#start`, type: "start", runId: chatId, resumeToken: chatId };
         const { httpTransport, readUIMessageStream: readStream } = await resolveAiSdk();
         const userMessage = {
-          id: crypto.randomUUID(),
+          // This id is what AI SDK's own backend persistence/dedup keys turns hang off — the same
+          // idempotency-key cost as basalt's own ChatMessage.id (see mintMessageId's doc), so
+          // mintMessageId, not mintThreadId, is the right helper here.
+          id: mintMessageId(),
           role: "user",
           parts: [{ type: "text", text: input }]
         };
@@ -182,7 +186,7 @@ function aiSdkTransport(options) {
       }
     };
   }
-  const fixedChatId = crypto.randomUUID();
+  const fixedChatId = mintThreadId();
   return {
     ...makeTransport(fixedChatId),
     forThread: (chatId) => makeTransport(chatId)

package/dist/agent/ai-sdk-transport.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=ai-sdk-transport.test.d.ts.map