@teaflask/assistant 0.0.0 → 0.3.0

package/dist/core/assistant-session-registry.js

@@ -0,0 +1,404 @@
+// One conversation per session identity, however many providers. Each
+// React root used to build its own TokenSession + store pair, so two
+// custom elements on one host page (the widget and the full page) held
+// two conversations that converged only through localStorage and server
+// history — never live. The registry hoists the pair into module scope,
+// keyed by the session's identity inputs and ref-counted: same-identity
+// providers — across separate React roots — resolve the SAME store, and
+// every surface streams the same turn. Module-scoped on purpose, like
+// the surface registry beside it: the sharing has to cross React trees,
+// and every element loads from one assistant.js, so module state IS the
+// cross-root channel.
+//
+// Per-provider wiring (token resolver, host capabilities, error sink)
+// cannot be baked into the shared pair, so registrants carry it and the
+// entry owns stable closures that delegate by rule:
+//   - host capabilities: the first capable registrant, per capability,
+//     read fresh at each execution pass — a capability-less widget never
+//     masks a page that wired an adapter, and a released provider hands
+//     over automatically on the next scan;
+//   - end-user token: the first identity-wired registrant, scanned at
+//     each mint (same identity key means same signed-in user, so any
+//     resolver is correct; order makes it deterministic);
+//   - reportError: fanned out to every registrant — observability, not
+//     capability; a duplicate report is harmless, a dropped one is a hole.
+import { readStoredThread, writeStoredThread, } from "../persistence/stored-thread.js";
+import { getAssistantConfig, listSubscriptions, } from "../transport/serving-api.js";
+import { TokenSession } from "../transport/token-session.js";
+import { NO_GATE, gateOfProjection, gateOfRefusal, gatesEqual, } from "./connect-gate.js";
+import { AssistantConversationStore, } from "./conversation-store.js";
+import { ObservableCell } from "./observable-cell.js";
+export const DEFAULT_BASE_URL = "https://api.teaflask.com";
+class SessionEntry {
+    key;
+    session;
+    store;
+    tier;
+    setupError;
+    assistantConfig;
+    attachmentPolicy;
+    modelChoice;
+    configAnswered;
+    conversationGate;
+    subscriptions;
+    connectOpenRequested;
+    /** Insertion-ordered — "first registrant" is this set's iteration order. */
+    registrations = new Set();
+    /** Ends the wait below; set only while a mint is parked on it, so the
+     *  ordinary case arms no timer. */
+    _endFirstRetainWait = null;
+    _everRetained = false;
+    _tierCell = new ObservableCell(null);
+    _setupErrorCell = new ObservableCell(null);
+    _assistantConfigCell = new ObservableCell(null);
+    _attachmentPolicyCell = new ObservableCell(null);
+    _modelChoiceCell = new ObservableCell(null);
+    _configAnsweredCell = new ObservableCell(false);
+    _conversationGateCell = new ObservableCell(NO_GATE);
+    _assistantConfigFetch = null;
+    _subscriptionsCell = new ObservableCell(null);
+    _subscriptionsFetch = null;
+    _connectOpenRequestedCell = new ObservableCell(false);
+    /** Arrow field so it travels unbound through the provider's context,
+     *  exactly like a cell's get/subscribe. */
+    ensureAssistantConfig = () => {
+        this._assistantConfigFetch ??= this._fetchAssistantConfig();
+    };
+    refreshAssistantConfig = () => {
+        // Refresh only supersedes an existing read: before the first
+        // ensureAssistantConfig there is nothing stale to correct, and the
+        // mount that needs the config will kick its own fetch.
+        if (this._assistantConfigFetch !== null) {
+            this._assistantConfigFetch = this._fetchAssistantConfig();
+        }
+    };
+    _fetchAssistantConfig() {
+        const fetch = getAssistantConfig(this.session).then((config) => {
+            // Only the current flight may write: an older flight resolving
+            // late must not clobber the refresh that superseded it.
+            if (this._assistantConfigFetch === fetch) {
+                this._assistantConfigCell.set(config.suggestions);
+                this._attachmentPolicyCell.set(config.attachments ?? null);
+                this._modelChoiceCell.set(config.model_choice ?? null);
+                this._configAnsweredCell.set(true);
+                // Deduped on substance: the projection mints a fresh object
+                // every read, and an unchanged gate must not notify — the
+                // verifying banner re-reads this every few seconds.
+                const gate = gateOfProjection(config.connect);
+                if (!gatesEqual(this._conversationGateCell.get(), gate)) {
+                    this._conversationGateCell.set(gate);
+                }
+            }
+        }, () => {
+            // A failed attempt evicts itself so the next mount retries;
+            // decoration never surfaces an error.
+            // The fetch still ANSWERED — failure is an answer — so the slot
+            // that held blank for the window may now fall back honestly.
+            if (this._assistantConfigFetch === fetch) {
+                this._assistantConfigFetch = null;
+                this._configAnsweredCell.set(true);
+            }
+        });
+        return fetch;
+    }
+    /** Same arrow-field discipline as ensureAssistantConfig, same
+     *  single-flight-with-self-eviction shape. */
+    ensureSubscriptions = () => {
+        this._subscriptionsFetch ??= this._fetchSubscriptions();
+    };
+    refreshSubscriptions = () => {
+        this._subscriptionsFetch = this._fetchSubscriptions();
+    };
+    requestSubscriptionConnect = () => {
+        // The ask fires ABOUT the standing (an auth-bounced credential), and
+        // the session-cached read predates the bounce: re-read so the panel
+        // opens on the bounced state and its reconnect affordance, not a
+        // stale "Connected".
+        this.refreshSubscriptions();
+        this._connectOpenRequestedCell.set(true);
+    };
+    acknowledgeSubscriptionConnect = () => {
+        this._connectOpenRequestedCell.set(false);
+    };
+    _fetchSubscriptions() {
+        const fetch = listSubscriptions(this.session).then((subscriptions) => {
+            // Only the current flight may write: an older flight resolving
+            // late must not clobber the refresh that superseded it.
+            if (this._subscriptionsFetch === fetch) {
+                this._subscriptionsCell.set(subscriptions);
+            }
+        }, () => {
+            // A failed attempt evicts itself so the next mount retries — but
+            // only its own flight, never a refresh that superseded it.
+            if (this._subscriptionsFetch === fetch) {
+                this._subscriptionsFetch = null;
+            }
+        });
+        return fetch;
+    }
+    constructor(key, spec) {
+        this.key = key;
+        this.tier = this._tierCell;
+        this.setupError = this._setupErrorCell;
+        this.assistantConfig = this._assistantConfigCell;
+        this.attachmentPolicy = this._attachmentPolicyCell;
+        this.modelChoice = this._modelChoiceCell;
+        this.configAnswered = this._configAnsweredCell;
+        this.conversationGate = this._conversationGateCell;
+        this.subscriptions = this._subscriptionsCell;
+        this.connectOpenRequested = this._connectOpenRequestedCell;
+        const publishableKey = spec.publishableKey;
+        this.session = new TokenSession({
+            publishableKey,
+            baseUrl: _withoutTrailingSlash(spec.baseUrl ?? DEFAULT_BASE_URL),
+            getEndUserToken: spec.identityProvided
+                ? () => this._resolveEndUserToken()
+                : undefined,
+            // Claim-at-mint: the stored anonymous thread rides the sign-in
+            // re-mint, read fresh each time (claim loss is silent by contract).
+            claimThreadId: () => {
+                const stored = readStoredThread(publishableKey);
+                return stored !== null && !stored.identified ? stored.threadId : null;
+            },
+            onMinted: (minted) => {
+                const previousTier = this._tierCell.get();
+                this._setupErrorCell.set(null);
+                this._tierCell.set(minted.tier);
+                if (minted.tier === "identified") {
+                    _markStoredThreadIdentified(publishableKey);
+                }
+                // The mint's verdict flows straight to the store; identification
+                // can arrive mid-session and flips the history expectation.
+                this.store.setTier(minted.tier);
+                // A tier flip changes what the projection would answer (a
+                // sign-in gate clears the moment the vouch lands) — re-read.
+                if (previousTier !== null && previousTier !== minted.tier) {
+                    this.refreshAssistantConfig();
+                }
+            },
+            onMintFailed: (error) => {
+                // Only a setup bug takes the surfaces down. A transient failure
+                // (a rate-limit window, a proxy blip) on the proactive background
+                // re-mint must not blank healthy surfaces whose token is still
+                // valid — the next request mints again.
+                if (_isSetupFailure(error)) {
+                    this._setupErrorCell.set(error);
+                }
+                this._reportToEveryRegistrant(error);
+            },
+        });
+        this.store = new AssistantConversationStore({
+            session: this.session,
+            publishableKey,
+            identityProvided: spec.identityProvided,
+            hostCapabilitiesOf: () => this._firstCapableRegistrantCapabilities(),
+            reportError: (error) => {
+                this._reportToEveryRegistrant(error);
+            },
+            onTelemetry: (event) => {
+                // The narration gates nothing: attempted fires before the submit
+                // even validates, and the host callback is arbitrary embedder
+                // code — a throw here must never break the approval it narrates
+                // (it would strand the card's synchronous click guard disabled
+                // forever). A broken telemetry hook is itself worth one report
+                // on the error seam, whose own fan-out is throw-proof below.
+                for (const registration of [...this.registrations]) {
+                    try {
+                        registration.registrant.onTelemetry?.(event);
+                    }
+                    catch (error) {
+                        this._reportToEveryRegistrant(_asError(error));
+                    }
+                }
+            },
+            // A gate refusal is the projection's race window surfacing: adopt
+            // it as the gate immediately (the card renders now, not after a
+            // round-trip) and re-read the standing it spoke about.
+            onGateRefusal: (error) => {
+                const gate = gateOfRefusal(error);
+                if (gate !== null) {
+                    this._conversationGateCell.set(gate);
+                    this.refreshSubscriptions();
+                }
+            },
+            // A settled turn may have crossed the taster budget or drained a
+            // window — the projection is the honest re-read.
+            onTurnSettled: this.refreshAssistantConfig,
+        });
+    }
+    _resolveEndUserToken() {
+        const vouch = this._vouchFromRegistrants();
+        if (vouch !== undefined) {
+            return vouch;
+        }
+        // No registrant YET means one of two opposite things, and answering
+        // both anonymously was the silent-anonymous bug: a provider whose
+        // retain effect has not run is moments from an identity; one whose
+        // registrants have left never will be. Only the identity-wired spec
+        // builds this resolver, so retention is the whole question.
+        if (this._everRetained) {
+            return null; // The contract's fail-open: the providers have gone.
+        }
+        return new Promise((resolve) => {
+            const timer = setTimeout(resolve, FIRST_RETAIN_WAIT_MS);
+            this._endFirstRetainWait = () => {
+                clearTimeout(timer);
+                resolve();
+            };
+        }).then(() => this._vouchFromRegistrants() ?? null);
+    }
+    /** The first registrant's vouch; null when one answered without a
+     *  vouch, undefined when there was none to ask — the wait needs both. */
+    _vouchFromRegistrants() {
+        for (const registration of this.registrations) {
+            const resolve = registration.registrant.resolveEndUserToken;
+            if (resolve !== null) {
+                return resolve();
+            }
+        }
+        return this.registrations.size === 0 ? undefined : null;
+    }
+    /** The wait is over; later mints resolve straight through. */
+    settleFirstRetain() {
+        this._everRetained = true;
+        this._endFirstRetainWait?.();
+        this._endFirstRetainWait = null;
+    }
+    _firstCapableRegistrantCapabilities() {
+        const merged = {
+            navigate: null,
+            executeActionIntent: null,
+        };
+        for (const registration of this.registrations) {
+            const capabilities = registration.registrant.hostCapabilitiesOf();
+            merged.navigate ??= capabilities.navigate;
+            merged.executeActionIntent ??= capabilities.executeActionIntent;
+        }
+        return merged;
+    }
+    _reportToEveryRegistrant(error) {
+        for (const registration of [...this.registrations]) {
+            try {
+                registration.registrant.reportError(error);
+            }
+            catch (hookFailure) {
+                // The error channel itself broke — no registrant seam is left to
+                // report through, and observability must never break the path it
+                // narrates (reportError also runs on the approval drop path). The
+                // console keeps the reason on record, the package's manner for
+                // broken host wiring (approval-context's out-of-surface submit).
+                console.warn("A host reportError callback threw while being handed an error:", hookFailure, "— the original error it was reporting:", error);
+            }
+        }
+    }
+}
+export class AssistantSessionRegistry {
+    entries = new Map();
+    /**
+     * Get-or-create, render-safe: both constructors are side-effect-free
+     * (no network, no timers, no listeners), so a discarded render leaves
+     * only an inert map entry that the next same-identity resolve reuses.
+     */
+    entryFor(spec) {
+        const key = _identityKeyOf(spec);
+        const existing = this.entries.get(key);
+        if (existing !== undefined) {
+            return existing;
+        }
+        const entry = new SessionEntry(key, spec);
+        this.entries.set(key, entry);
+        return entry;
+    }
+    /**
+     * Registers the provider's wiring and boots the store on the first
+     * retain (or revives it — `bootstrap()` resets a disposed store by
+     * design, so retain-after-sweep works). Returns the release; calling
+     * it twice is a no-op. The last release sweeps on a microtask, so
+     * StrictMode's synchronous release-then-retain never tears anything
+     * down, and only the sweep disposes the store and session.
+     */
+    retain(entry, registrant) {
+        if (!(entry instanceof SessionEntry)) {
+            throw new Error("Only entries resolved by entryFor() can be retained — construct nothing yourself.");
+        }
+        // A wrapper per retain, not the bare registrant: two providers may
+        // pass identical wiring, and each still holds its own registration.
+        const registration = { registrant };
+        const firstRetain = entry.registrations.size === 0;
+        entry.registrations.add(registration);
+        entry.settleFirstRetain(); // Before bootstrap: a parked mint wakes first.
+        if (firstRetain) {
+            this._reviveIfSwept(entry);
+            entry.store.bootstrap();
+        }
+        return () => {
+            if (!entry.registrations.delete(registration)) {
+                return; // released twice — the first release already counted
+            }
+            if (entry.registrations.size > 0) {
+                return;
+            }
+            queueMicrotask(() => {
+                this._sweepIfStillUnretained(entry);
+            });
+        };
+    }
+    /** A retain that lands after the sweep emptied the map re-inserts the
+     *  entry, so the next entryFor resolves it again. If a successor entry
+     *  already took the key (a cross-root race through the microtask gap),
+     *  the stale entry simply runs unshared for its lifetime — benign. */
+    _reviveIfSwept(entry) {
+        if (!this.entries.has(entry.key)) {
+            this.entries.set(entry.key, entry);
+        }
+    }
+    _sweepIfStillUnretained(entry) {
+        if (entry.registrations.size > 0) {
+            return;
+        }
+        // Guard against deleting a successor entry that took the key between
+        // this entry emptying and the microtask running.
+        if (this.entries.get(entry.key) === entry) {
+            this.entries.delete(entry.key);
+        }
+        entry.store.dispose();
+        entry.session.dispose();
+    }
+}
+/** The one instance every provider resolves through — the module scope
+ *  shared by all React roots on the page is the whole mechanism. */
+export const assistantSessionRegistry = new AssistantSessionRegistry();
+// The bound on waiting for a provider's retain effect: React runs it in
+// the same commit, so this covers only the render that never commits,
+// where waiting forever would hang the request rather than answer it.
+const FIRST_RETAIN_WAIT_MS = 2_000;
+function _identityKeyOf(spec) {
+    return [
+        spec.publishableKey,
+        _withoutTrailingSlash(spec.baseUrl ?? DEFAULT_BASE_URL),
+        spec.identityProvided ? "identified" : "anonymous",
+    ].join("\u0000");
+}
+// The contract's loud-by-design mint failures: a broken key, origin
+// allowlist, or end-user signer needs the developer, not a retry.
+function _isSetupFailure(error) {
+    return (error.code === "PUBLISHABLE_KEY_INVALID" ||
+        error.code === "ORIGIN_NOT_ALLOWED" ||
+        error.code === "END_USER_TOKEN_INVALID");
+}
+// The mint 201'd with the claim on board: the stored thread is this
+// identity's now (or the claim silently lost and reads will say so) —
+// either way it must not be offered again.
+function _markStoredThreadIdentified(publishableKey) {
+    const stored = readStoredThread(publishableKey);
+    if (stored !== null && !stored.identified) {
+        writeStoredThread(publishableKey, { ...stored, identified: true });
+    }
+}
+function _withoutTrailingSlash(baseUrl) {
+    return baseUrl.endsWith("/") ? baseUrl.slice(0, -1) : baseUrl;
+}
+function _asError(thrown) {
+    return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+//# sourceMappingURL=assistant-session-registry.js.map

package/dist/core/assistant-session-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assistant-session-registry.js","sourceRoot":"","sources":["../../src/core/assistant-session-registry.ts"],"names":[],"mappings":"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"}

package/dist/core/attachment-uploads.d.ts

@@ -0,0 +1,14 @@
+import type { ServingAttachment } from "../contract/threads.js";
+import type { MintedDownloadUrl } from "./conversation-contract.js";
+import type { AssistantConversationStore } from "./conversation-store.js";
+/** The three-step upload as one call: declare, PUT the bytes straight
+ *  to storage, finalize (the server sniffs what the file actually is).
+ *  Resolves with the settled attachment; throws with a user sentence
+ *  when any step refuses — the chip renders it. */
+export declare function uploadAttachmentFromStore(store: AssistantConversationStore, file: File): Promise<ServingAttachment>;
+/** Exchange a stable attachment id for a display URL, minted on demand
+ *  and reused only while comfortably inside its short TTL. The expiry
+ *  rides along so a long-lived renderer knows when to come back for a
+ *  fresh one — a widget stays open far longer than a URL lives. */
+export declare function mintAttachmentDownloadUrlFromStore(store: AssistantConversationStore, attachmentId: string): Promise<MintedDownloadUrl>;
+//# sourceMappingURL=attachment-uploads.d.ts.map

package/dist/core/attachment-uploads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-uploads.d.ts","sourceRoot":"","sources":["../../src/core/attachment-uploads.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAOhE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAE1E;;;mDAGmD;AACnD,wBAAsB,yBAAyB,CAC7C,KAAK,EAAE,0BAA0B,EACjC,IAAI,EAAE,IAAI,GACT,OAAO,CAAC,iBAAiB,CAAC,CAO5B;AAED;;;mEAGmE;AACnE,wBAAsB,kCAAkC,CACtD,KAAK,EAAE,0BAA0B,EACjC,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,iBAAiB,CAAC,CAiB5B"}

package/dist/core/attachment-uploads.js

@@ -0,0 +1,37 @@
+// One attached file's server-side life, driven from the composer: the
+// three-step upload (declare, PUT, finalize) and the on-demand display
+// URL mint with its TTL cache. The _downloadUrls cache stays a store
+// field per the friend convention.
+import { createAttachmentUpload, finalizeAttachment, getAttachmentDownloadUrl, putFileToUploadUrl, } from "../transport/serving-api.js";
+/** The three-step upload as one call: declare, PUT the bytes straight
+ *  to storage, finalize (the server sniffs what the file actually is).
+ *  Resolves with the settled attachment; throws with a user sentence
+ *  when any step refuses — the chip renders it. */
+export async function uploadAttachmentFromStore(store, file) {
+    const intent = await createAttachmentUpload(store.deps.session, {
+        filename: file.name !== "" ? file.name : "attachment",
+        byte_size: file.size,
+    });
+    await putFileToUploadUrl(intent.upload_url, file);
+    return finalizeAttachment(store.deps.session, intent.attachment.id);
+}
+/** Exchange a stable attachment id for a display URL, minted on demand
+ *  and reused only while comfortably inside its short TTL. The expiry
+ *  rides along so a long-lived renderer knows when to come back for a
+ *  fresh one — a widget stays open far longer than a URL lives. */
+export async function mintAttachmentDownloadUrlFromStore(store, attachmentId) {
+    const cached = store._downloadUrls.get(attachmentId);
+    if (cached !== undefined && cached.expiresAtMs > Date.now()) {
+        return cached;
+    }
+    const fresh = await getAttachmentDownloadUrl(store.deps.session, attachmentId);
+    const minted = {
+        url: fresh.url,
+        // A 30-second safety margin: a URL about to expire must not be
+        // handed to an <img> that fetches it a beat later.
+        expiresAtMs: Date.now() + (fresh.expires_in_seconds - 30) * 1000,
+    };
+    store._downloadUrls.set(attachmentId, minted);
+    return minted;
+}
+//# sourceMappingURL=attachment-uploads.js.map

package/dist/core/attachment-uploads.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachment-uploads.js","sourceRoot":"","sources":["../../src/core/attachment-uploads.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,uEAAuE;AACvE,qEAAqE;AACrE,mCAAmC;AAGnC,OAAO,EACL,sBAAsB,EACtB,kBAAkB,EAClB,wBAAwB,EACxB,kBAAkB,GACnB,MAAM,6BAA6B,CAAC;AAIrC;;;mDAGmD;AACnD,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,KAAiC,EACjC,IAAU;IAEV,MAAM,MAAM,GAAG,MAAM,sBAAsB,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE;QAC9D,QAAQ,EAAE,IAAI,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,YAAY;QACrD,SAAS,EAAE,IAAI,CAAC,IAAI;KACrB,CAAC,CAAC;IACH,MAAM,kBAAkB,CAAC,MAAM,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAClD,OAAO,kBAAkB,CAAC,KAAK,CAAC,IAAI,CAAC,OAAO,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;AACtE,CAAC;AAED;;;mEAGmE;AACnE,MAAM,CAAC,KAAK,UAAU,kCAAkC,CACtD,KAAiC,EACjC,YAAoB;IAEpB,MAAM,MAAM,GAAG,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;IACrD,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,WAAW,GAAG,IAAI,CAAC,GAAG,EAAE,EAAE,CAAC;QAC5D,OAAO,MAAM,CAAC;IAChB,CAAC;IACD,MAAM,KAAK,GAAG,MAAM,wBAAwB,CAC1C,KAAK,CAAC,IAAI,CAAC,OAAO,EAClB,YAAY,CACb,CAAC;IACF,MAAM,MAAM,GAAsB;QAChC,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,+DAA+D;QAC/D,mDAAmD;QACnD,WAAW,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,KAAK,CAAC,kBAAkB,GAAG,EAAE,CAAC,GAAG,IAAI;KACjE,CAAC;IACF,KAAK,CAAC,aAAa,CAAC,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC;IAC9C,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/core/block-timing-anchors.d.ts

@@ -0,0 +1,31 @@
+import type { AgentSubscriber } from "@ag-ui/client";
+import type { BlockTiming } from "./segment-timing.js";
+/**
+ * One observed instant folded into a block's pair, IN PLACE: the
+ * earliest observed value is the start, the latest the settle. True when
+ * the map moved — the caller's change signal. Deliberately NOT the
+ * neighbouring anchors' copy-on-write idiom: timing is the one
+ * high-frequency map (every block boundary moves it), and an immutable
+ * copy per fold is O(N) per write — O(N²) over an N-block replay — so
+ * this map mutates and the resume store's REVISION counter replaces
+ * identity as the change signal. ENTRIES stay immutable (a fold sets a
+ * fresh pair object, never mutates one), so a snapshot that copied the
+ * map never sees its held pairs change; re-applying a replayed sequence
+ * changes nothing (min/max are idempotent) and answers false.
+ */
+export declare function foldBlockTimingObserved(timings: Map<string, BlockTiming>, blockId: string, observedAtMs: number): boolean;
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * entries that are not a well-formed pair are dropped rather than
+ * rendered (or crashed on) — a dropped pair degrades that block's
+ * duration to unknown until the next full replay, never a crash.
+ */
+export declare function wellFormedBlockTimingAnchorsOf(stored: ReadonlyMap<string, BlockTiming>): ReadonlyMap<string, BlockTiming>;
+/**
+ * Records each timestamped block-boundary event against the block it
+ * names. The block id is the durable join — the event's own messageId
+ * or toolCallId — never adjacency; an event naming no block (lifecycle
+ * frames, thread markers) contributes nothing here.
+ */
+export declare function blockTimingRecorder(onTimingObserved: (blockId: string, observedAtMs: number) => void): AgentSubscriber;
+//# sourceMappingURL=block-timing-anchors.d.ts.map

package/dist/core/block-timing-anchors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"block-timing-anchors.d.ts","sourceRoot":"","sources":["../../src/core/block-timing-anchors.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AAEvD;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,WAAW,CAAC,EACjC,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAyBT;AAED;;;;;GAKG;AACH,wBAAgB,8BAA8B,CAC5C,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,GACvC,WAAW,CAAC,MAAM,EAAE,WAAW,CAAC,CAUlC;AAoBD;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,KAAK,IAAI,GAChE,eAAe,CAgBjB"}

package/dist/core/block-timing-anchors.js

@@ -0,0 +1,139 @@
+// The block-timing anchor model, pure of React: the recorder reads the
+// per-event server timestamp off every raw event that names a
+// block (a messageId or a toolCallId), folds it into that block's
+// earliest-start/latest-settle pair, and the resume store holds the map
+// across remounts. The indirection exists because the client carries no
+// per-event timestamp onto the messages it builds — this map is the
+// timing's only home on the client, and a snapshot-seeded reconnect
+// replays only past the cursor, so historical blocks keep their timing
+// from here alone. Absent timestamps
+// (old histories, synthesized frames) record nothing: to every consumer,
+// absence means unknown, never zero.
+import { EventType } from "@ag-ui/core";
+/**
+ * One observed instant folded into a block's pair, IN PLACE: the
+ * earliest observed value is the start, the latest the settle. True when
+ * the map moved — the caller's change signal. Deliberately NOT the
+ * neighbouring anchors' copy-on-write idiom: timing is the one
+ * high-frequency map (every block boundary moves it), and an immutable
+ * copy per fold is O(N) per write — O(N²) over an N-block replay — so
+ * this map mutates and the resume store's REVISION counter replaces
+ * identity as the change signal. ENTRIES stay immutable (a fold sets a
+ * fresh pair object, never mutates one), so a snapshot that copied the
+ * map never sees its held pairs change; re-applying a replayed sequence
+ * changes nothing (min/max are idempotent) and answers false.
+ */
+export function foldBlockTimingObserved(timings, blockId, observedAtMs) {
+    const existing = timings.get(blockId);
+    if (existing === undefined) {
+        timings.set(blockId, {
+            startedAtMs: observedAtMs,
+            settledAtMs: observedAtMs,
+        });
+        return true;
+    }
+    const startedAtMs = existing.startedAtMs === null
+        ? observedAtMs
+        : Math.min(existing.startedAtMs, observedAtMs);
+    const settledAtMs = existing.settledAtMs === null
+        ? observedAtMs
+        : Math.max(existing.settledAtMs, observedAtMs);
+    if (startedAtMs === existing.startedAtMs &&
+        settledAtMs === existing.settledAtMs) {
+        return false;
+    }
+    timings.set(blockId, { startedAtMs, settledAtMs });
+    return true;
+}
+/**
+ * A defensive copy for seeding transcript state from the resume store:
+ * entries that are not a well-formed pair are dropped rather than
+ * rendered (or crashed on) — a dropped pair degrades that block's
+ * duration to unknown until the next full replay, never a crash.
+ */
+export function wellFormedBlockTimingAnchorsOf(stored) {
+    const seeded = new Map();
+    const entries = stored;
+    for (const [blockId, timing] of entries) {
+        if (typeof blockId !== "string" || !_isWellFormedTiming(timing)) {
+            continue;
+        }
+        seeded.set(blockId, timing);
+    }
+    return seeded;
+}
+// Only block BOUNDARIES contribute: a delta's timestamp can only land
+// between its block's start and end, so recording it would tighten
+// nothing while republishing the anchors snapshot on every batch. Built
+// from the shipped EventType enum, never raw strings, so a typo or an
+// upstream rename fails the build instead of silently degrading a
+// block's duration to unknown.
+const BLOCK_BOUNDARY_EVENT_TYPES = new Set([
+    EventType.TEXT_MESSAGE_START,
+    EventType.TEXT_MESSAGE_END,
+    EventType.REASONING_START,
+    EventType.REASONING_END,
+    EventType.REASONING_MESSAGE_START,
+    EventType.REASONING_MESSAGE_END,
+    EventType.TOOL_CALL_START,
+    EventType.TOOL_CALL_END,
+    EventType.TOOL_CALL_RESULT,
+]);
+/**
+ * Records each timestamped block-boundary event against the block it
+ * names. The block id is the durable join — the event's own messageId
+ * or toolCallId — never adjacency; an event naming no block (lifecycle
+ * frames, thread markers) contributes nothing here.
+ */
+export function blockTimingRecorder(onTimingObserved) {
+    return {
+        onEvent({ event }) {
+            if (!BLOCK_BOUNDARY_EVENT_TYPES.has(event.type)) {
+                return;
+            }
+            const observedAtMs = _timestampOf(event);
+            if (observedAtMs === undefined) {
+                return;
+            }
+            const blockId = _blockIdOf(event);
+            if (blockId !== undefined) {
+                onTimingObserved(blockId, observedAtMs);
+            }
+        },
+    };
+}
+function _timestampOf(event) {
+    if (typeof event !== "object" || event === null) {
+        return undefined;
+    }
+    const { timestamp } = event;
+    if (typeof timestamp !== "number" || !Number.isFinite(timestamp)) {
+        return undefined;
+    }
+    return timestamp;
+}
+/** The durable block id an event names: its toolCallId when it is a
+ *  tool-family event, else its messageId (text and reasoning families).
+ *  Narrowed from unknown — the wire is distrusted by contract. */
+function _blockIdOf(event) {
+    if (typeof event !== "object" || event === null) {
+        return undefined;
+    }
+    const { toolCallId, messageId } = event;
+    if (typeof toolCallId === "string" && toolCallId !== "") {
+        return toolCallId;
+    }
+    if (typeof messageId === "string" && messageId !== "") {
+        return messageId;
+    }
+    return undefined;
+}
+function _isWellFormedTiming(timing) {
+    if (typeof timing !== "object" || timing === null) {
+        return false;
+    }
+    const { startedAtMs, settledAtMs } = timing;
+    const halfIsWellTyped = (half) => half === null || (typeof half === "number" && Number.isFinite(half));
+    return halfIsWellTyped(startedAtMs) && halfIsWellTyped(settledAtMs);
+}
+//# sourceMappingURL=block-timing-anchors.js.map