@teaflask/assistant 0.3.0 → 0.6.0

package/dist/core/conversation-publish.js

@@ -1,24 +1,10 @@
-// Publishing: the one place snapshots rebuild and cells emit — a cell's
-// identity changes iff its content did (the useSyncExternalStore
-// contract), the epoch/connection/idle syncs key off the same pass, and
-// the pending-decision gap re-judges on every publish. The re-entrancy
-// latch (_inPublish) stays a store field — the gap gate's judge-driven
-// transitions fire inside publishStore.
 import { syncConnection } from "./connection-driver.js";
 import { historyExpected, sameModelPick } from "./conversation-adoption.js";
 import { publishActivity, syncEpoch, theAnswerablePause, } from "./epoch-sync.js";
 import { syncIdleRecheck } from "./idle-recheck.js";
 import { pendingDecisionGapOf } from "./pending-decision-gap.js";
 import { bannerFailureSentenceOf } from "./turn-failure-copy.js";
-// Rebuilds both snapshots and emits only the ones that actually moved,
-// so a cell's identity changes iff its content did — the contract
-// useSyncExternalStore's cached-snapshot semantics depend on. The
-// connection epoch keys off the same state, so it syncs here too.
 export function publishStore(store) {
-    // The re-entrancy latch is the gap gate's: a judge-driven transition
-    // fires inside this function (below), where writing _pendingDecisionGap
-    // suffices — the snapshot build reads it. Only the gate's timer-driven
-    // transitions, firing outside any publish, trigger their own.
     store._inPublish = true;
     try {
         syncEpoch(store);
@@ -40,11 +26,6 @@ export function publishStore(store) {
         store._inPublish = false;
     }
 }
-// The connect decision is deferred to a coalesced microtask so a
-// presence transition that resolves within the same synchronous tick —
-// a keyed transcript REMOUNT releases then re-acquires back-to-back —
-// is seen settled before the store acts. The check re-reads live at
-// fire time.
 export function scheduleConnectionSync(store) {
     if (store._connectionSyncQueued || store._disposed) {
         return;
@@ -64,33 +45,14 @@ export function conversationSnapshotOf(store) {
         reconnectNonce: store._reconnectNonce,
         sendError: store._sendError,
         turnFailure: bannerFailureSentenceOf(store._turnFailure, store._active?.resume.turnFailedAnchors),
-        // Never during a stop: a member who pressed stop did the
-        // interrupting themselves, and any interruption recorded inside the
-        // ~2s stop window (the dying stream's own error path) is that stop's
-        // mechanics, not connection trouble worth a banner.
         showInterruptionBanner: store._streamInterrupted && busyOf(store) && !store._stopping,
         pendingDecisionGap: store._pendingDecisionGap,
     };
 }
-// Re-judges the pending-decision gap against the current
-// truth: the turn's server-named interrupt ids vs every holder this
-// client has — approval cards (hydrate-before-reconcile already ran on
-// any REST adoption), elicitation cards, and the execution inbox's
-// entries. Runs on every publish so any path that moves cards, entries
-// or the turn re-judges; the derivation itself is pure and cheap. The
-// quiet→loud grace, the once-per-signature probe, and the loud
-// tracking all live in the shared PendingDecisionGapGate (its docblock
-// enumerates the transitions); this store's premises for the gate's
-// three deps are recorded at the _gapGate field.
 function _updatePendingDecisionGap(store) {
     if (store._disposed) {
         return;
     }
-    // The gap watchdog judges the PAUSE (the queuing class): with a
-    // message queued newer than the pause, the newest row reads
-    // "queued" and the derivation would go quiet in exactly the
-    // missing-card state it exists to alarm on. Falls back to the
-    // newest row so the no-pause shapes keep their null verdict.
     const pause = theAnswerablePause(store) ?? store._newestTurn;
     store._gapGate.judge(pendingDecisionGapOf(pause, store._active?.approvalInbox.cards() ?? [], store._elicitationsCell.get(), store._epoch?.executionInbox.entries() ?? [], store._consumedInterrupts.idsOf(pause?.run_id, pause?.awaiting_round)));
 }
@@ -119,10 +81,6 @@ export function composerSnapshotOf(store) {
     };
 }
 export function busyOf(store) {
-    // The composer lock, Stop button and interruption banner follow the
-    // turn record: a parked turn is never busy, whatever a
-    // stale thread.busy says — there is no run to stop, and the visitor's
-    // next message is the designed withdraw path.
     return (((store._active?.thread.busy ?? false) &&
         store._newestTurn?.status !== "parked") ||
         store._pendingSend);
@@ -147,8 +105,6 @@ function _sameConversationSnapshot(a, b) {
         a.sendError === b.sendError &&
         a.turnFailure === b.turnFailure &&
         a.showInterruptionBanner === b.showInterruptionBanner &&
-        // Reference identity is sound: the store keeps the published gap
-        // reference-stable while its signature holds.
         a.pendingDecisionGap === b.pendingDecisionGap);
 }
 function _sameComposerSnapshot(a, b) {
@@ -157,9 +113,5 @@ function _sameComposerSnapshot(a, b) {
         a.pendingEcho === b.pendingEcho &&
         a.composerRefocusPending === b.composerRefocusPending &&
         a.stopping === b.stopping &&
-        // composerInput is deliberately absent: it is the same cell object
-        // on every snapshot — its VALUE moves per keystroke, and only the
-        // composer's own useCell subscription pays for that.
         sameModelPick(a.modelPick, b.modelPick));
 }
-//# sourceMappingURL=conversation-publish.js.map

package/dist/core/conversation-refresh.d.ts

@@ -1,14 +1,4 @@
 import type { AssistantConversationStore } from "./conversation-store.js";
 export declare function refreshConversationFromStore(store: AssistantConversationStore): Promise<void>;
-/** A surface's roster poll observed a dispatch settle — the
- *  one frontend-visible signal that a delivery turn may be about to
- *  open on this thread. Re-reads the conversation in a bounded burst
- *  until the claim shows up (a queued/working newest turn; adoption's
- *  publish attaches the stream through the ordinary connect sync), the
- *  thread changes, or the window exhausts QUIETLY — the entity may
- *  have declined the wake, and a no-show is not an error. Coalescing: a
- *  second settle mid-burst restarts the probe budget instead of
- *  stacking a burst. */
 export declare function noteDispatchSettledFromStore(store: AssistantConversationStore): void;
 export declare function settlesFor(delayMs: number): Promise<void>;
-//# sourceMappingURL=conversation-refresh.d.ts.map

package/dist/core/conversation-refresh.js

@@ -1,15 +1,6 @@
-// Keeping the REST truth fresh: the conversation re-read every settle
-// signal funnels through (ticket-ordered so a stale read never overwrites
-// fresher truth), and the delivery-claim probe after a dispatch settle.
 import { getAssistantThread } from "../transport/serving-api.js";
 import { turnHoldsAStream } from "./connection-driver.js";
 import { adoptRefreshedDetail } from "./conversation-adoption.js";
-// The delivery-claim probe: a
-// dispatch settle only WAKES the thread's conversation entity — the
-// backend commits the delivery turn row asynchronously afterward, and may
-// decline outright. So the settle's re-read probes briefly for the opened
-// turn and goes quiet on a no-show; the idle re-read is the backstop. Its
-// own constants (the STOP_SETTLE_PROBES convention): retunable alone.
 const DELIVERY_CLAIM_PROBES = 8;
 const DELIVERY_CLAIM_PROBE_MS = 1_000;
 export async function refreshConversationFromStore(store) {
@@ -21,27 +12,15 @@ export async function refreshConversationFromStore(store) {
     const ticket = store._refreshTicket;
     try {
         const detail = await getAssistantThread(store.deps.session, active.thread.id);
-        if (ticket <= store._refreshAdoptedThrough) {
-            // A later-issued refresh already adopted fresher truth (the
-            // monotonic-adoption premise at _refreshTicket).
+        if (store._disposed || ticket <= store._refreshAdoptedThrough) {
             return;
         }
         store._refreshAdoptedThrough = ticket;
         adoptRefreshedDetail(store, detail);
     }
     catch {
-        // A blip here self-heals: the next settled run refreshes again.
     }
 }
-/** A surface's roster poll observed a dispatch settle — the
- *  one frontend-visible signal that a delivery turn may be about to
- *  open on this thread. Re-reads the conversation in a bounded burst
- *  until the claim shows up (a queued/working newest turn; adoption's
- *  publish attaches the stream through the ordinary connect sync), the
- *  thread changes, or the window exhausts QUIETLY — the entity may
- *  have declined the wake, and a no-show is not an error. Coalescing: a
- *  second settle mid-burst restarts the probe budget instead of
- *  stacking a burst. */
 export function noteDispatchSettledFromStore(store) {
     if (store._deliveryProbeRunning) {
         store._deliveryProbeRearm = true;
@@ -59,20 +38,14 @@ async function _probeForDeliveryClaim(store) {
         return;
     }
     if (turnHoldsAStream(store)) {
-        // The turn is live: the settle's consequences arrive on the stream
-        // (or the connect sync is already attaching) — nothing to probe.
         return;
     }
-    // THE LATCH'S CLOCK IS THE BEAT TIMER ALONE: the reads are fired
-    // single-flight and never awaited, so a stalled GET can never latch
-    // _deliveryProbeRunning (the premise: docs/connection-lifecycle.md).
     let refreshInFlight = false;
     const refreshOnce = () => {
         if (refreshInFlight) {
             return;
         }
         refreshInFlight = true;
-        // refreshConversation never rejects (its catch is the self-heal).
         void store.refreshConversation().finally(() => {
             refreshInFlight = false;
         });
@@ -81,14 +54,10 @@ async function _probeForDeliveryClaim(store) {
     let probesLeft = DELIVERY_CLAIM_PROBES;
     while (probesLeft > 0 || store._deliveryProbeRearm) {
         if (store._deliveryProbeRearm) {
-            // Another settle landed mid-burst: its claim gets a full window.
             store._deliveryProbeRearm = false;
             probesLeft = DELIVERY_CLAIM_PROBES;
         }
         if (_deliveryProbeMoot(store, threadId) || turnHoldsAStream(store)) {
-            // Disposed or switched: this probe's thread is gone. Holds a
-            // stream: adopted — the publish's connect sync attached (or is
-            // attaching) and the stream owns the story from here.
             return;
         }
         await settlesFor(DELIVERY_CLAIM_PROBE_MS);
@@ -99,12 +68,9 @@ async function _probeForDeliveryClaim(store) {
         refreshOnce();
     }
 }
-/** Whether the delivery-claim probe's thread is no longer this store's
- *  story — re-read behind every await (the stopTurn posture). */
 function _deliveryProbeMoot(store, threadId) {
     return store._disposed || store._active?.thread.id !== threadId;
 }
 export function settlesFor(delayMs) {
     return new Promise((resolve) => setTimeout(resolve, delayMs));
 }
-//# sourceMappingURL=conversation-refresh.js.map

package/dist/core/conversation-send.d.ts

@@ -2,11 +2,5 @@ import type { TurnAttachment } from "../contract/threads.js";
 import type { AssistantConversationStore } from "./conversation-store.js";
 export declare function sendMessageFromStore(store: AssistantConversationStore, message: string, attachmentIds?: string[], optimisticAttachments?: TurnAttachment[]): Promise<boolean>;
 export declare function markComposerRefocusHandledFromStore(store: AssistantConversationStore): void;
-/** Ends the live turn as a quiet receipt. Thread-scoped on
- *  purpose: the serving door's thread pointer names the live turn
- *  (liveness, never recency), so the store never picks one. Deliberately
- *  never touches _streamInterrupted — a stop is a thing the member did,
- *  and the interruption banner would be a lie. */
 export declare function stopTurnFromStore(store: AssistantConversationStore): Promise<void>;
 export declare function handleUserMessageInjectedFromStore(store: AssistantConversationStore, messageId: string): void;
-//# sourceMappingURL=conversation-send.d.ts.map

package/dist/core/conversation-send.js

@@ -1,14 +1,9 @@
-// Sending and stopping the live turn: the one send POST every surface
-// goes through — optimistic echo, model pick capture, the honest refusal
-// taxonomy — and the stop that ends a live turn as a quiet receipt.
 import { sendAssistantMessage, stopAssistantTurn, } from "../transport/serving-api.js";
 import { ServingApiError } from "../transport/serving-error.js";
 import { enterConversationFromSend } from "./conversation-adoption.js";
 import { busyOf, publishStore } from "./conversation-publish.js";
 import { stopFailureSentenceFor, userSentenceFor } from "./error-copy.js";
 import { probeStopSettle } from "./stop-settle.js";
-// The optimistic user message's id mint — module-level so ids stay
-// unique across every conversation this page ever opens.
 let nextOptimisticMessageId = 1;
 export async function sendMessageFromStore(store, message, attachmentIds = [], optimisticAttachments = []) {
     store._sendError = null;
@@ -22,17 +17,12 @@ export async function sendMessageFromStore(store, message, attachmentIds = [], o
         attachments: optimisticAttachments,
     };
     publishStore(store);
-    // Captured before the await: the shelf stays live during a send, so
-    // a selection changed mid-flight must survive the landing (it rides
-    // the NEXT send) — only the pick this send actually carried settles.
     const sentPick = store._modelPick;
     try {
         const response = await sendAssistantMessage(store.deps.session, {
             thread_id: store._active?.thread.id,
             message,
             attachment_ids: attachmentIds,
-            // Present = set exactly this (idempotent for an unchanged pick);
-            // absent = keep — the contract's set-pick semantics.
             ...(sentPick !== null && {
                 model_pick: {
                     model_id: sentPick.modelId,
@@ -41,28 +31,18 @@ export async function sendMessageFromStore(store, message, attachmentIds = [], o
             }),
         });
         enterConversationFromSend(store, response.thread, response.turn, sentPick);
-        // The send just remounted the composer (it rides the transcript,
-        // which reconnects by remounting), dropping the caret; the fresh
-        // instance takes it back once the turn settles.
         store._composerRefocusPending = true;
         return true;
     }
     catch (error) {
         store._pendingEcho = null;
         if (_isThreadBusyRefusal(error)) {
-            // This is a synchronization correction, not a destructive error:
-            // another surface (or a late settle) still owns the turn. Re-read
-            // and reconnect to that work; the composer's false return restores
-            // the attempted message as a draft (scope-guarded — only into the
-            // conversation that sent it).
             store._sendError = null;
             await store.refreshConversation();
             return false;
         }
         store._sendError = userSentenceFor(error);
         if (error instanceof ServingApiError && _isAGateRefusal(error)) {
-            // The refusal's recovery is the gate (the composer's takeover
-            // card) — the entry adopts it; the banner stands down for it.
             store._sendError = null;
             store.deps.onGateRefusal(error);
         }
@@ -80,27 +60,16 @@ export function markComposerRefocusHandledFromStore(store) {
     store._composerRefocusPending = false;
     publishStore(store);
 }
-// --- stopping the live turn ---
-/** Ends the live turn as a quiet receipt. Thread-scoped on
- *  purpose: the serving door's thread pointer names the live turn
- *  (liveness, never recency), so the store never picks one. Deliberately
- *  never touches _streamInterrupted — a stop is a thing the member did,
- *  and the interruption banner would be a lie. */
 export async function stopTurnFromStore(store) {
     const active = store._active;
     if (store._disposed ||
         active === null ||
         store._stopping ||
-        // No turn exists yet while the send POST is in flight; the send's
-        // own failure path is the recovery there.
         store._pendingSend ||
         !busyOf(store)) {
         return;
     }
     const threadId = active.thread.id;
-    // Each attempt owns its own narration, exactly like sendMessage: a
-    // previous attempt's failure sentence must not outlive the retry
-    // that worked.
     store._sendError = null;
     store._stopping = true;
     publishStore(store);
@@ -109,34 +78,15 @@ export async function stopTurnFromStore(store) {
         if (_stopLostItsThread(store, threadId)) {
             return;
         }
-        // The composer re-enables when busy flips false; the caret comes
-        // back with it, exactly like a landed send.
         store._composerRefocusPending = true;
         publishStore(store);
         if (receipt.delivery !== "signaled") {
-            // turn_settled / already_settled: the door settled the turn (or
-            // found the answer already won the race) — REST is terminal now.
-            // A read blip here falls through to the probe loop below.
             await store.refreshConversation();
         }
-        // Signaled: the workflow's stop exit lands turn_stopped plus a
-        // quiet RUN_FINISHED on the stream (~2s), and the normal settle
-        // machinery adopts it. The bounded probe is the no-stream corner's
-        // fallback (handleWorkflowRestarted's shape); a settle adopted by
-        // the stream clears _stopping and ends the loop early.
         const exhausted = await probeStopSettle({
             refresh: store.refreshConversation,
             stillAwaitsSettle: () => _stopStillAwaitsSettle(store, threadId),
         });
-        // Exhausted: the probe window is a fallback, not a promise. A
-        // settle that never showed up must not keep narrating "Stopping…"
-        // — release the lock so the stop square re-arms (the door answers
-        // a receipt to a second press) and a genuinely dead stream's
-        // interruption banner (its Retry is the only way back) can
-        // surface. A stop that lands later still renders honestly through
-        // the ordinary settle machinery. This never resurfaces the banner
-        // after a SUCCESSFUL stop: success means busy flipped false inside
-        // the window, and a false busy hides the banner on its own.
         if (exhausted) {
             store._stopping = false;
             publishStore(store);
@@ -147,8 +97,6 @@ export async function stopTurnFromStore(store) {
             return;
         }
         store._stopping = false;
-        // The stop door's own vocabulary, never the send door's: a failed
-        // stop is not a failed send.
         store._sendError = stopFailureSentenceFor(error);
         publishStore(store);
         if (error instanceof Error) {
@@ -156,10 +104,6 @@ export async function stopTurnFromStore(store) {
         }
     }
 }
-// Read fresh behind every await on purpose: dispose, thread switches,
-// and the settle machinery all move these fields while a stop sleeps,
-// and the function boundary keeps TS narrowing (which cannot see those
-// writers) from constant-folding the re-checks.
 function _stopLostItsThread(store, threadId) {
     return store._disposed || store._active?.thread.id !== threadId;
 }
@@ -169,16 +113,11 @@ function _stopStillAwaitsSettle(store, threadId) {
 function _isThreadBusyRefusal(error) {
     return (error instanceof ServingApiError && error.code === "ASSISTANT_THREAD_BUSY");
 }
-// The gate-shaped refusal codes: their recovery renders in the
-// composer's place (core/connect-gate.ts), so the send banner stands
-// down for them — everything else stays the banner's story.
 function _isAGateRefusal(error) {
     return (error.code === "ASSISTANT_SIGN_IN_REQUIRED" ||
         error.code === "SUBSCRIPTION_CONNECT_REQUIRED" ||
         error.code === "SUBSCRIPTION_CANNOT_PAY");
 }
-// Replay injected the optimistic echo's own message: the bridge has done
-// its job and the row now renders from the transcript itself.
 export function handleUserMessageInjectedFromStore(store, messageId) {
     if (store._pendingEcho !== null &&
         store._pendingEcho.messageId === messageId) {
@@ -186,4 +125,3 @@ export function handleUserMessageInjectedFromStore(store, messageId) {
         publishStore(store);
     }
 }
-//# sourceMappingURL=conversation-send.js.map

package/dist/core/conversation-store.d.ts

@@ -14,22 +14,6 @@ import { ObservableCell, type ReadonlyCell } from "./observable-cell.js";
 import type { UserTurnLedger, UserTurnMeta } from "./user-turn-ledger.js";
 import type { ActiveConversation, AttachmentDraft, ComposerContract, ComposerInput, ComposerModelPick, ConnectionSnapshot, ConversationSnapshot, ConversationStoreDeps, MintedDownloadUrl } from "./conversation-contract.js";
 export type { ActiveConversation, ApprovalDecisionInput, AttachmentDraft, ComposerContract, ComposerInput, ComposerModelPick, ConversationStoreDeps, HostCapabilities, MintedDownloadUrl, } from "./conversation-contract.js";
-/**
- * The conversation core shared by every surface: one thread's state, the
- * send/reconnect/echo machinery, and the honest error taxonomy — a plain
- * observable store so surfaces are pure chrome subscribing to its cells
- * (via useSyncExternalStore in React; `.get()`/`.subscribe()` anywhere
- * else). Surfaces differ only in chrome — <AssistantPage/> adds the
- * thread list, <AssistantPalette/> an overlay shell — never in transport,
- * persistence, or transcript semantics.
- *
- * Every send reconnects the stream with a fresh agent: the serving stream
- * closes once a turn settles, and the contract's frozen semantic makes a
- * fresh full replay the one always-correct way to pick up the next turn.
- *
- * Construction is side-effect-free (StrictMode-inert); `bootstrap()` is
- * the boot, `dispose()` the teardown.
- */
 export declare class AssistantConversationStore {
     readonly deps: ConversationStoreDeps;
     readonly conversation: ReadonlyCell<ConversationSnapshot>;
@@ -50,11 +34,6 @@ export declare class AssistantConversationStore {
     readonly _coworkerWorkCell: ObservableCell<ReadonlyMap<number, CoworkerExecutionWork>>;
     readonly _elicitationErrors: Map<string, string>;
     readonly _questionAnswers: Map<string, AnsweredQuestions>;
-    /** The question-set drafts: store-owned so the panel's
-     *  remounts (paging, reconnect, workflow restart) never lose a
-     *  member's staged answers. Lifetime is ruled in question-drafts.ts;
-     *  this store clears a set on present-and-settled evidence and clears
-     *  all on a thread switch or abandon — never on an epoch reset. */
     readonly questionDrafts: QuestionDraftStore;
     readonly _markerAnchorsCell: ObservableCell<MarkerAnchorsSnapshot>;
     readonly _activityCell: ObservableCell<AssistantActivitySnapshot>;
@@ -110,16 +89,7 @@ export declare class AssistantConversationStore {
     _epochConnectedOnce: boolean;
     _automaticReconnects: number;
     constructor(deps: ConversationStoreDeps);
-    /** Boot: resume where the visitor left off, and prime the identified
-     *  history eagerly — the list call itself is what primes the first
-     *  mint, so a fresh browser (no stored thread — exactly the
-     *  cross-device case) shows its history without waiting for a first
-     *  send. Anonymous embeds stay lazy — no traffic until the visitor
-     *  interacts. Idempotent: the resume staleness counter and the history
-     *  flag absorb StrictMode's double boot. */
     bootstrap(): void;
-    /** The provider pushes each mint's tier verdict in; identification can
-     *  arrive mid-session and flips the history expectation. */
     setTier(tier: VisitorTier | null): void;
     dispose(): void;
     resumeStoredThread: () => void;
@@ -153,4 +123,3 @@ export declare class AssistantConversationStore {
     handleWorkflowRestarted: () => void;
     _scheduleSettleRefresh(): void;
 }
-//# sourceMappingURL=conversation-store.d.ts.map