basalt-ui 1.11.0 → 1.13.0

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

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

package/dist/agent/coalesce.d.ts

@@ -12,10 +12,26 @@
  * wire, the SDK re-supplies `input` by reading it back off the stored invocation, and a merge that
  * replaces wholesale rather than accumulating would lose it outright.
  *
- * `approval`-bearing responses can arrive without a usable `toolCallId` (the SDK resolves them by
- * reverse lookup on `approval.id` instead) — this maintains an `approvalId -> toolCallId` side
- * index while folding and routes such a part through it. A part resolvable by neither key is kept
- * as-is rather than dropped; never silently discard a part.
+ * A settled tool part can arrive without a `toolCallId` at all — `approval-responded` plus the
+ * three terminal states all carry it as optional (see `MaybeIdentified` in `parts.ts`).
+ * `approval-responded` is where the WIRE itself omits it: the SDK's `tool-approval-response` chunk
+ * carries no `toolCallId`, only `approval.id`, so it is resolved by reverse lookup on `approval.id`
+ * instead — this maintains an `approvalId -> toolCallId` side index while folding and routes such a
+ * part through it. A part resolvable by neither key is kept as-is rather than dropped; never
+ * silently discard a part.
+ *
+ * The fold is strictly LEFT-TO-RIGHT with no backtracking: the side index only holds ids seen so
+ * far, so an unidentified `approval-responded` arriving BEFORE its `approval-requested` stays its
+ * own block and the later request opens a second one. That is deliberate, not an oversight —
+ * reconciling backwards would let the request (the later arrival) win under the "later state wins"
+ * rule and render an already-answered call as still pending, which is worse than two blocks in an
+ * ordering the wire never produces.
+ *
+ * **This function never throws.** It is public, it runs on the render path, and it folds data that
+ * came off a wire — so every anomaly (an unrecognized tool state, an unresolvable id) degrades to
+ * "keep the part as it arrived", announced in dev, rather than aborting the render. A throw here
+ * would turn one malformed chunk into a permanently dead transcript. Exhaustiveness over the tool
+ * states is still enforced, but at COMPILE time only (see `mergeToolPart`'s default branch).
  *
  * @example
  * import { coalesceParts } from 'basalt-ui/agent'

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

@@ -1 +1 @@
-{"version":3,"file":"coalesce.d.ts","sourceRoot":"","sources":["../../src/agent/coalesce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,OAAO,KAAK,EAAE,SAAS,EAAyC,MAAM,SAAS,CAAA;AA+C/E,wBAAgB,aAAa,CAAC,KAAK,SAAS,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,EAAE,GAAG,KAAK,EAAE,CA+CvF"}
+{"version":3,"file":"coalesce.d.ts","sourceRoot":"","sources":["../../src/agent/coalesce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,SAAS,EAAyC,MAAM,SAAS,CAAA;AA8I/E,wBAAgB,aAAa,CAAC,KAAK,SAAS,SAAS,EAAE,KAAK,EAAE,SAAS,KAAK,EAAE,GAAG,KAAK,EAAE,CA+CvF"}

package/dist/agent/coalesce.js

@@ -2,27 +2,95 @@ function isTextLikeType(type) {
   return type === "text" || type === "reasoning";
 }
 function resolveToolCallId(part, toolCallIdByApprovalId) {
-  if (typeof part.toolCallId === "string" && part.toolCallId.length > 0) return part.toolCallId;
+  if (part.toolCallId !== void 0) return part.toolCallId;
   const approval = "approval" in part ? part.approval : void 0;
   return approval !== void 0 ? toolCallIdByApprovalId.get(approval.id) : void 0;
 }
 function registerApprovalIndex(part, toolCallIdByApprovalId) {
   const approval = "approval" in part ? part.approval : void 0;
   if (approval === void 0) return;
-  if (typeof part.toolCallId !== "string" || part.toolCallId.length === 0) return;
+  if (part.toolCallId === void 0) return;
   toolCallIdByApprovalId.set(approval.id, part.toolCallId);
 }
 function mergeToolPart(existing, next) {
   const existingInput = "input" in existing ? existing.input : void 0;
   const nextInput = "input" in next ? next.input : void 0;
   const input = nextInput !== void 0 ? nextInput : existingInput;
-  const toolName = next.toolName.length > 0 ? next.toolName : existing.toolName;
-  return {
-    ...existing,
-    ...next,
-    toolName,
-    ...input !== void 0 ? { input } : {}
+  const durationMs = next.durationMs ?? existing.durationMs;
+  const providerExecuted = next.providerExecuted ?? existing.providerExecuted;
+  const settledToolCallId = next.toolCallId ?? existing.toolCallId;
+  const common = {
+    id: next.id,
+    type: "tool",
+    toolName: next.toolName.length > 0 ? next.toolName : existing.toolName,
+    ...durationMs !== void 0 ? { durationMs } : {},
+    ...providerExecuted !== void 0 ? { providerExecuted } : {}
   };
+  switch (next.state) {
+    case "input-streaming":
+      return {
+        ...common,
+        toolCallId: next.toolCallId,
+        state: "input-streaming",
+        ...input !== void 0 ? { input } : {}
+      };
+    case "input-available":
+      return { ...common, toolCallId: next.toolCallId, state: "input-available", input };
+    case "approval-requested":
+      return {
+        ...common,
+        toolCallId: next.toolCallId,
+        state: "approval-requested",
+        input,
+        approval: next.approval
+      };
+    case "approval-responded":
+      return {
+        ...common,
+        ...settledToolCallId !== void 0 ? { toolCallId: settledToolCallId } : {},
+        state: "approval-responded",
+        input,
+        approval: next.approval
+      };
+    case "output-available":
+      return {
+        ...common,
+        ...settledToolCallId !== void 0 ? { toolCallId: settledToolCallId } : {},
+        state: "output-available",
+        input,
+        output: next.output,
+        ...next.preliminary !== void 0 ? { preliminary: next.preliminary } : {},
+        ...next.approval !== void 0 ? { approval: next.approval } : {}
+      };
+    case "output-error":
+      return {
+        ...common,
+        ...settledToolCallId !== void 0 ? { toolCallId: settledToolCallId } : {},
+        state: "output-error",
+        errorText: next.errorText,
+        ...input !== void 0 ? { input } : {},
+        ...next.rawInput !== void 0 ? { rawInput: next.rawInput } : {},
+        ...next.approval !== void 0 ? { approval: next.approval } : {}
+      };
+    case "output-denied":
+      return {
+        ...common,
+        ...settledToolCallId !== void 0 ? { toolCallId: settledToolCallId } : {},
+        state: "output-denied",
+        input,
+        approval: next.approval
+      };
+    default: {
+      const unhandled = next;
+      const fallback = unhandled;
+      if (process.env["NODE_ENV"] !== "production") {
+        console.warn(
+          `[basalt] coalesceParts: unrecognized tool state ${JSON.stringify(fallback.state)} \u2014 kept, merged best-effort`
+        );
+      }
+      return { ...fallback, ...common };
+    }
+  }
 }
 function coalesceParts(parts) {
   const out = [];

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

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

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

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

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

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

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

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

package/dist/agent/id.d.ts

@@ -1,3 +1,81 @@
+/**
+ * Id-minting helpers shared across the agent layer: `mintThreadId` (a low-stakes client-side id —
+ * threads, run/chat namespaces — used by `./thread`'s `createThreadsStore`, `./adapter`'s
+ * `createAdapterThreadsStore`/`threadsStoreAdapterContract`, `./use-agent-stream`'s per-send run
+ * id, and `aiSdkTransport`'s fixed chat id), `mintMessageId` (the higher-stakes id `appendMessage`
+ * treats as its only idempotency key), and `withPartIds` (stamps sequence ids onto streamed
+ * parts). Grouped here because they're the id-minting leaves every store/hook/transport in this
+ * layer sits above — not because they share a mechanism (`mintMessageId` deliberately diverges
+ * from `mintThreadId` on rung 3; see its own doc).
+ */
+/**
+ * Mints a client-side id for a LOW-COLLISION-COST use: a thread id, a per-send run-id namespace, a
+ * fixed chat id — anything minted client-side that is NOT the idempotency key some write depends
+ * on. `crypto.randomUUID()` exists only in SECURE CONTEXTS (HTTPS or localhost) — a consumer served
+ * over plain HTTP on a LAN hostname (a homelab dashboard on a bare IP, a staging box) would
+ * otherwise have `create()`, about the most basic user action a thread store has, throw a plain
+ * TypeError. A store used from a browser must not throw on a user gesture — the same principle
+ * already applied twice this release (`spliceText` clamps rather than throws, `coalesceParts`
+ * degrades rather than throws).
+ *
+ * Fallback chain, each rung reached only when the one above it is unavailable:
+ *   1. `crypto.randomUUID()` — cryptographically random, RFC 4122 UUID. The normal path.
+ *   2. `crypto.getRandomValues()` — still cryptographically random; hand-assembled into a UUIDv4
+ *      via `assembleUuidV4`.
+ *   3. No usable `crypto` at all (missing entirely, or missing both methods above — an old WebView,
+ *      an SSR shim). NOT cryptographically random and NOT collision-resistant in general. This rung
+ *      exists solely so a caller never throws on such a host. It is acceptable ONLY because an id
+ *      minted here is minted a handful of times per client session and is not the idempotency key
+ *      any write depends on — `ThreadsStoreAdapter.appendMessage`'s idempotency key is the MESSAGE
+ *      id (see `mintMessageId`), not this one, so a collision on this rung costs a locally
+ *      merged/duplicated thread (or two runs sharing a part-id namespace), not silent data loss on
+ *      the append path. Do not reuse this rung for anything with a higher collision cost than that
+ *      — see `mintMessageId` for the id that needs one.
+ */
+export declare function mintThreadId(): string;
+/**
+ * Mints a message id — the value `ThreadsStoreAdapter.appendMessage` treats as its ONLY
+ * idempotency key (see that method's contract doc in `./adapter`). Shares `mintThreadId`'s rungs
+ * 1-2 (`crypto.randomUUID()`, then `crypto.getRandomValues()` assembled into a UUIDv4) — both are
+ * cryptographically random and collision-resistant, and rung 2 is the fix that actually matters in
+ * practice (a plain-HTTP/LAN host still has `getRandomValues`; only `randomUUID` is secure-context-
+ * gated).
+ *
+ * Rung 3 deliberately DIVERGES from `mintThreadId`: it THROWS instead of degrading to a
+ * non-random fallback. A thread id's rung-3 collision costs a locally merged/duplicated thread —
+ * annoying, recoverable, visible. A message id's collision cost is different IN KIND, not degree:
+ * `appendMessage` is idempotent on this id, so two messages that collide are not two rows, they
+ * are ONE — the second write silently no-ops and its content is gone, with nothing downstream able
+ * to tell. Degrading here would trade a loud, debuggable failure for silent, permanent data loss.
+ *
+ * This deliberately diverges from this layer's other standing rule — render-path code degrades,
+ * never throws (`spliceText` clamps, `coalesceParts` degrades, a consumer fence renderer must not
+ * take the message down) — because minting a message id is NOT render-path code. It runs once, in
+ * the write path that constructs a message before handing it to a store (`start()`,
+ * `consumeAndFinalize`'s finalize step, `finalizeStop`, `aiSdkTransport`'s per-turn user message),
+ * never inside the per-chunk accumulation/render loop those functions guard. A host with no usable
+ * `crypto` at all (missing both `randomUUID` and `getRandomValues`) is vanishingly rare — no
+ * runtime with a DOM/fetch surface worth targeting ships without a Crypto object — and an uncaught
+ * throw here is a loud, debuggable failure rather than a message silently vanishing with no trace,
+ * but WHERE it surfaces differs by call site (audited, not assumed — this paragraph previously
+ * claimed a single shared catch handled all of them, which was false):
+ *   - `consumeAndFinalize`'s own assistantMessage mint runs inside that function's try/catch, so a
+ *     throw there is correctly turned into `onFailureStatus` ('error' from `start()`, 'interrupted'
+ *     from the mount-time resume) — a visibly stuck-then-settled run, as originally claimed.
+ *   - `useAgentThreadRuns.start()`'s userMessage mint runs BEFORE any state is touched
+ *     (`appendMessage`/`setStatus`/the controller registration all come after it), so a throw there
+ *     is a true no-op that propagates synchronously out of `start()` itself — not a stuck run at
+ *     all, since nothing ever started. See `UseAgentThreadRunsReturn.start`'s `@throws` doc.
+ *   - `finalizeStop`'s stoppedMessage mint is wrapped in its own try/catch precisely so a throw
+ *     here cannot wedge the thread at 'streaming' forever (stop() has already torn down this run's
+ *     bookkeeping by the time finalizeStop runs, so a second stop() is always a no-op) — see
+ *     `finalizeStop`'s doc for the guarded behavior and the resulting 'error' status.
+ * A stuck spinner is debuggable; silently discarded chat history is not — that half of the
+ * original claim stands regardless of which of the three paths above catches it.
+ *
+ * @throws {Error} when neither `crypto.randomUUID` nor `crypto.getRandomValues` is available.
+ */
+export declare function mintMessageId(): string;
 /**
  * withPartIds — stamps a stable id onto every draft part arriving without one.
  *

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

@@ -1 +1 @@
-{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/agent/id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAuB,WAAW,CAAC,KAAK,SAAS;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9D,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,GAC5B,cAAc,CAAC,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAUxC"}
+{"version":3,"file":"id.d.ts","sourceRoot":"","sources":["../../src/agent/id.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAmBH;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,YAAY,IAAI,MAAM,CAQrC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyCG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAYtC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAuB,WAAW,CAAC,KAAK,SAAS;IAAE,EAAE,CAAC,EAAE,MAAM,CAAA;CAAE,EAC9D,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,cAAc,CAAC,KAAK,CAAC,GAC5B,cAAc,CAAC,KAAK,GAAG;IAAE,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC,CAUxC"}

package/dist/agent/id.js

@@ -1,3 +1,31 @@
+function assembleUuidV4(bytes) {
+  const hex = Array.from({ length: 16 }, (_, i) => {
+    const raw = bytes.at(i) ?? 0;
+    const byte = i === 6 ? raw & 15 | 64 : i === 8 ? raw & 63 | 128 : raw;
+    return byte.toString(16).padStart(2, "0");
+  }).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+function mintThreadId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    return assembleUuidV4(crypto.getRandomValues(new Uint8Array(16)));
+  }
+  return `id-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function mintMessageId() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    return assembleUuidV4(crypto.getRandomValues(new Uint8Array(16)));
+  }
+  throw new Error(
+    "mintMessageId: no usable crypto (both randomUUID and getRandomValues are unavailable) \u2014 refusing to mint a non-random message id, since ThreadsStoreAdapter.appendMessage treats this id as its only idempotency key and a collision would silently drop a message."
+  );
+}
 async function* withPartIds(runId, source) {
   let n = 0;
   for await (const part of source) {
@@ -10,5 +38,7 @@ async function* withPartIds(runId, source) {
   }
 }
 export {
+  mintMessageId,
+  mintThreadId,
   withPartIds
 };

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

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

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

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

package/dist/agent/index.d.ts

@@ -55,4 +55,6 @@ export { createThreadsStore } from './thread.js';
 export type { AgentThread, ThreadStatus, ThreadsStore, ThreadsStoreOptions } from './thread.js';
 export { heuristicOutcome } from './outcome.js';
 export type { AgentOutcome, OutcomeResolver } from './outcome.js';
+export { createAdapterThreadsStore, threadsStoreAdapterContract } from './adapter.js';
+export type { AdapterThreadsStoreOptions, ThreadsStoreAdapter, ThreadsStoreAdapterContractCase, } from './adapter.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,YAAY,EACV,SAAS,EACT,cAAc,EACd,OAAO,EACP,SAAS,EACT,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAG9F,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAGnC,OAAO,EAAE,WAAW,EAAE,MAAM,MAAM,CAAA;AAGlC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChE,YAAY,EACV,WAAW,EACX,cAAc,EACd,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,WAAW,CAAA;AAGlB,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGxD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAG/E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAG5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAGjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAClD,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAGvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAG5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/agent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAGH,YAAY,EACV,SAAS,EACT,cAAc,EACd,OAAO,EACP,SAAS,EACT,QAAQ,EACR,aAAa,EACb,YAAY,EACZ,aAAa,EACb,UAAU,EACV,SAAS,GACV,MAAM,SAAS,CAAA;AAChB,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,MAAM,SAAS,CAAA;AAG9F,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AAGnC,OAAO,EAAE,WAAW,EAAE,MAAM,MAAM,CAAA;AAGlC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAG1C,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAChE,YAAY,EACV,WAAW,EACX,cAAc,EACd,YAAY,EACZ,aAAa,EACb,iBAAiB,EACjB,YAAY,GACb,MAAM,WAAW,CAAA;AAGlB,YAAY,EAAE,cAAc,EAAE,uBAAuB,EAAE,MAAM,aAAa,CAAA;AAC1E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAGxD,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,YAAY,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAA;AAG/E,OAAO,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAA;AAG5E,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAA;AAC5D,YAAY,EACV,cAAc,EACd,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,yBAAyB,CAAA;AAGhC,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAA;AACtC,YAAY,EACV,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,qBAAqB,EACrB,oBAAoB,EACpB,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,aAAa,CAAA;AAGpB,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAA;AACvD,YAAY,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAA;AAGjE,OAAO,EAAE,sBAAsB,EAAE,MAAM,WAAW,CAAA;AAClD,YAAY,EAAE,WAAW,EAAE,gBAAgB,EAAE,uBAAuB,EAAE,MAAM,WAAW,CAAA;AAGvF,OAAO,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAA;AAC7C,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAA;AAG5F,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAC5C,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,WAAW,CAAA;AAG9D,OAAO,EAAE,yBAAyB,EAAE,2BAA2B,EAAE,MAAM,WAAW,CAAA;AAClF,YAAY,EACV,0BAA0B,EAC1B,mBAAmB,EACnB,+BAA+B,GAChC,MAAM,WAAW,CAAA"}

package/dist/agent/index.js

@@ -12,12 +12,14 @@ import { BasaltStickToBottom } from "./stick-to-bottom.js";
 import { createChatHistoryStore } from "./history.js";
 import { createThreadsStore } from "./thread.js";
 import { heuristicOutcome } from "./outcome.js";
+import { createAdapterThreadsStore, threadsStoreAdapterContract } from "./adapter.js";
 export {
   BasaltStickToBottom,
   PartList,
   TERMINAL_TOOL_STATES,
   aiSdkTransport,
   coalesceParts,
+  createAdapterThreadsStore,
   createChatHistoryStore,
   createThreadsStore,
   definePartRenderers,
@@ -29,6 +31,7 @@ export {
   mergePart,
   narrowAgentPart,
   parseAgentPart,
+  threadsStoreAdapterContract,
   useAgentStream,
   useAgentThreadRuns,
   withPartIds

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

@@ -1 +1 @@
-{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/agent/merge.ts"],"names":[],"mappings":"AA+BA;iGACiG;AACjG,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAgBrE,wBAAgB,SAAS,CAAC,KAAK,SAAS,QAAQ,EAAE,KAAK,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,GAAG,KAAK,EAAE,CAiB/F"}
+{"version":3,"file":"merge.d.ts","sourceRoot":"","sources":["../../src/agent/merge.ts"],"names":[],"mappings":"AAkCA;iGACiG;AACjG,MAAM,MAAM,QAAQ,GAAG;IAAE,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAA;AAoDrE,wBAAgB,SAAS,CAAC,KAAK,SAAS,QAAQ,EAAE,KAAK,EAAE,SAAS,KAAK,EAAE,EAAE,IAAI,EAAE,KAAK,GAAG,KAAK,EAAE,CAyB/F"}

package/dist/agent/merge.js

@@ -1,19 +1,31 @@
 function isTextLikeType(type) {
   return type === "text" || type === "reasoning";
 }
-function spliceText(existing, next) {
-  const offset = next.offset ?? existing.text.length;
-  return existing.text.slice(0, offset) + next.text + existing.text.slice(offset + next.text.length);
+function spliceText(existingText, next) {
+  const offset = clampOffset(next.offset ?? existingText.length, existingText.length);
+  return existingText.slice(0, offset) + next.text + existingText.slice(offset + next.text.length);
+}
+function clampOffset(offset, length) {
+  const clamped = Number.isFinite(offset) ? Math.min(Math.max(offset, 0), length) : length;
+  if (clamped !== offset && process.env["NODE_ENV"] !== "production") {
+    console.warn(
+      `[basalt] mergePart: text offset ${offset} out of range [0, ${length}] \u2014 clamped to ${clamped}`
+    );
+  }
+  return clamped;
 }
 function mergePart(parts, next) {
   const index = parts.findIndex((part) => part.id === next.id);
-  if (index === -1) return [...parts, next];
-  const existing = parts[index];
-  const spliceable = existing.type === next.type && isTextLikeType(next.type);
+  const existing = index === -1 ? void 0 : parts[index];
+  const spliceable = isTextLikeType(next.type) && (existing === void 0 || existing.type === next.type);
   const merged = spliceable ? {
     ...next,
-    text: spliceText(existing, next)
+    text: spliceText(
+      existing === void 0 ? "" : existing.text,
+      next
+    )
   } : next;
+  if (existing === void 0) return [...parts, merged];
   const out = parts.slice();
   out[index] = merged;
   return out;

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

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

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

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

package/dist/agent/part-list.d.ts

@@ -1,41 +1,41 @@
 import type { JSX } from 'react';
 import type { AgentPart } from './parts.js';
-export type TextPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-    part: Extract<TPart, {
-        type: 'text';
-    }>;
-    index: number;
-}) => JSX.Element | null;
-export type ReasoningPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-    part: Extract<TPart, {
-        type: 'reasoning';
-    }>;
-    index: number;
-}) => JSX.Element | null;
-export type ToolCallPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-    part: Extract<TPart, {
-        type: 'tool';
-    }>;
-    index: number;
-}) => JSX.Element | null;
-export type SourcePartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-    part: Extract<TPart, {
-        type: 'source';
-    }>;
-    index: number;
-}) => JSX.Element | null;
-export type ErrorPartRenderer<TPart extends AgentPart = AgentPart> = (props: {
-    part: Extract<TPart, {
-        type: 'error';
-    }>;
+/**
+ * The per-renderer argument. `settled` is `false` only while the message these parts belong to is
+ * still streaming — it converges this map toward the `PartRenderContext` a foreign renderer
+ * already receives (`./foreign`), rather than adding a third shape. Additive and
+ * source-compatible: an existing `({ part }) => …` renderer simply ignores it.
+ *
+ * Settlement is MONOTONE — a message that has settled never un-settles.
+ */
+type PartRenderArgs<TPart> = {
+    part: TPart;
     index: number;
-}) => JSX.Element | null;
+    settled: boolean;
+};
+export type TextPartRenderer<TPart extends AgentPart = AgentPart> = (props: PartRenderArgs<Extract<TPart, {
+    type: 'text';
+}>>) => JSX.Element | null;
+export type ReasoningPartRenderer<TPart extends AgentPart = AgentPart> = (props: PartRenderArgs<Extract<TPart, {
+    type: 'reasoning';
+}>>) => JSX.Element | null;
+export type ToolCallPartRenderer<TPart extends AgentPart = AgentPart> = (props: PartRenderArgs<Extract<TPart, {
+    type: 'tool';
+}>>) => JSX.Element | null;
+export type SourcePartRenderer<TPart extends AgentPart = AgentPart> = (props: PartRenderArgs<Extract<TPart, {
+    type: 'source';
+}>>) => JSX.Element | null;
+export type ErrorPartRenderer<TPart extends AgentPart = AgentPart> = (props: PartRenderArgs<Extract<TPart, {
+    type: 'error';
+}>>) => JSX.Element | null;
 /**
  * Partial map of per-type renderers. Any omitted key falls back to the headless default.
  *
  * @example
  * const renderers: Partial<AgentPartRenderers> = {
- *   text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown>,
+ *   text: ({ part, settled }) => (
+ *     <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *   ),
  * }
  */
 export type AgentPartRenderers<TPart extends AgentPart = AgentPart> = {
@@ -50,10 +50,17 @@ export type PartListProps<TPart extends AgentPart = AgentPart> = {
     readonly parts: TPart[];
     /**
      * Override individual part renderers. Omitted keys fall back to the headless defaults.
-     * Pass `{ text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown> }` to
-     * enable rich markdown rendering.
+     * Pass `{ text: ({ part, settled }) => <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown> }`
+     * to enable rich markdown rendering.
      */
     readonly components?: Partial<AgentPartRenderers<TPart>>;
+    /**
+     * `false` while the message these parts belong to is still streaming — forwarded to every
+     * renderer so a text renderer can drop out of streaming mode (and a fenced mermaid/diagram can
+     * upgrade) once the turn finishes. Defaults to `true`: a caller that knows nothing about a run
+     * is rendering a finished list, and un-settled must be opted into by the thing that does know.
+     */
+    readonly settled?: boolean;
 };
 /**
  * Renders a list of AgentPart values via an exhaustive switch over part.type.
@@ -69,7 +76,15 @@ export type PartListProps<TPart extends AgentPart = AgentPart> = {
  * // With basalt's own Markdown for the text renderer:
  * import { PartList } from 'basalt-ui/agent'
  * import { Markdown } from 'basalt-ui/content'
- * <PartList parts={parts} components={{ text: ({ part }) => <Markdown streaming density="chat">{part.text}</Markdown> }} />
+ * <PartList
+ *   parts={parts}
+ *   components={{
+ *     text: ({ part, settled }) => (
+ *       <Markdown streaming={!settled} contentTrust="untrusted" density="chat">{part.text}</Markdown>
+ *     ),
+ *   }}
+ * />
  */
-export declare function PartList<TPart extends AgentPart = AgentPart>({ parts, components, }: PartListProps<TPart>): JSX.Element;
+export declare function PartList<TPart extends AgentPart = AgentPart>({ parts, components, settled, }: PartListProps<TPart>): JSX.Element;
+export {};
 //# sourceMappingURL=part-list.d.ts.map

package/dist/agent/part-list.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"part-list.d.ts","sourceRoot":"","sources":["../../src/agent/part-list.tsx"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAGhC,OAAO,KAAK,EACV,SAAS,EAMV,MAAM,SAAS,CAAA;AAIhB,MAAM,MAAM,gBAAgB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CAAC,KAAK,EAAE;IAC1E,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACtC,KAAK,EAAE,MAAM,CAAA;CACd,KAAK,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAExB,MAAM,MAAM,qBAAqB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CAAC,KAAK,EAAE;IAC/E,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC,CAAA;IAC3C,KAAK,EAAE,MAAM,CAAA;CACd,KAAK,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAExB,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CAAC,KAAK,EAAE;IAC9E,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACtC,KAAK,EAAE,MAAM,CAAA;CACd,KAAK,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAExB,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CAAC,KAAK,EAAE;IAC5E,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,QAAQ,CAAA;KAAE,CAAC,CAAA;IACxC,KAAK,EAAE,MAAM,CAAA;CACd,KAAK,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAExB,MAAM,MAAM,iBAAiB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CAAC,KAAK,EAAE;IAC3E,IAAI,EAAE,OAAO,CAAC,KAAK,EAAE;QAAE,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;IACvC,KAAK,EAAE,MAAM,CAAA;CACd,KAAK,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAExB;;;;;;;GAOG;AACH,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI;IACpE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAA;IACtC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC,KAAK,CAAC,CAAA;IAChD,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,KAAK,CAAC,CAAA;IAC1C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAA;CACzC,CAAA;AAqJD,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI;IAC/D,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAA;CACzD,CAAA;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,EAAE,EAC5D,KAAK,EACL,UAAU,GACX,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,CAgEpC"}
+{"version":3,"file":"part-list.d.ts","sourceRoot":"","sources":["../../src/agent/part-list.tsx"],"names":[],"mappings":"AA4BA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,OAAO,CAAA;AAGhC,OAAO,KAAK,EACV,SAAS,EAMV,MAAM,SAAS,CAAA;AAIhB;;;;;;;GAOG;AACH,KAAK,cAAc,CAAC,KAAK,IAAI;IAC3B,IAAI,EAAE,KAAK,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,EAAE,OAAO,CAAA;CACjB,CAAA;AAED,MAAM,MAAM,gBAAgB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CAClE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,KACpD,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAEvB,MAAM,MAAM,qBAAqB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CACvE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC,CAAC,KACzD,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAEvB,MAAM,MAAM,oBAAoB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CACtE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC,KACpD,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAEvB,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CACpE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,CAAC,CAAC,KACtD,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAEvB,MAAM,MAAM,iBAAiB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI,CACnE,KAAK,EAAE,cAAc,CAAC,OAAO,CAAC,KAAK,EAAE;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC,KACrD,GAAG,CAAC,OAAO,GAAG,IAAI,CAAA;AAEvB;;;;;;;;;GASG;AACH,MAAM,MAAM,kBAAkB,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI;IACpE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC,KAAK,CAAC,CAAA;IACtC,QAAQ,CAAC,SAAS,EAAE,qBAAqB,CAAC,KAAK,CAAC,CAAA;IAChD,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC,KAAK,CAAC,CAAA;IAC1C,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,KAAK,CAAC,CAAA;IAC1C,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC,KAAK,CAAC,CAAA;CACzC,CAAA;AAqJD,MAAM,MAAM,aAAa,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,IAAI;IAC/D,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,KAAK,EAAE,CAAA;IACvB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC,kBAAkB,CAAC,KAAK,CAAC,CAAC,CAAA;IACxD;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAC3B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,KAAK,SAAS,SAAS,GAAG,SAAS,EAAE,EAC5D,KAAK,EACL,UAAU,EACV,OAAc,GACf,EAAE,aAAa,CAAC,KAAK,CAAC,GAAG,GAAG,CAAC,OAAO,CAoFpC"}

package/dist/agent/part-list.js

@@ -107,7 +107,8 @@ const DEFAULT_RENDERERS = {
 };
 function PartList({
   parts,
-  components
+  components,
+  settled = true
 }) {
   const renderers = useMemo(
     () => ({ ...DEFAULT_RENDERERS, ...components }),
@@ -119,23 +120,58 @@ function PartList({
         return null;
       case "text": {
         const Render = renderers.text;
-        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(Render, { part, index }) }, part.id);
+        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(
+          Render,
+          {
+            part,
+            index,
+            settled
+          }
+        ) }, part.id);
       }
       case "reasoning": {
         const Render = renderers.reasoning;
-        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(Render, { part, index }) }, part.id);
+        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(
+          Render,
+          {
+            part,
+            index,
+            settled
+          }
+        ) }, part.id);
       }
       case "tool": {
         const Render = renderers.tool;
-        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(Render, { part, index }) }, part.id);
+        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(
+          Render,
+          {
+            part,
+            index,
+            settled
+          }
+        ) }, part.id);
       }
       case "source": {
         const Render = renderers.source;
-        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(Render, { part, index }) }, part.id);
+        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(
+          Render,
+          {
+            part,
+            index,
+            settled
+          }
+        ) }, part.id);
       }
       case "error": {
         const Render = renderers.error;
-        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(Render, { part, index }) }, part.id);
+        return /* @__PURE__ */ jsx(Fragment, { children: /* @__PURE__ */ jsx(
+          Render,
+          {
+            part,
+            index,
+            settled
+          }
+        ) }, part.id);
       }
       default:
         return assertNever(part);

package/dist/agent/part-list.test.d.ts

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

package/dist/agent/part-list.test.d.ts.map

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