@alia.onl/sdk 22.0.1 → 22.1.1

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @alia.onl/sdk
 
+## 22.1.1
+
+- A delayed Stop acknowledgement cannot idle a newer turn, replace its sidebar
+  preview, or notify a different conversation. Thread/account changes and unmounts
+  invalidate old completion callbacks while the original acknowledgement drains.
+- Keep repeated Stop requests deduplicated during that drain; errors from an old
+  Stop cannot appear in a replacement thread. Public APIs and peer ranges are unchanged.
+
+## 22.1.0
+
+- Stop explicitly cancels the authenticated foreground turn across API replicas;
+  closing a sheet or losing its transport still allows background completion.
+- Export `createChatTurnControl` / `AliaChatTurnControl` from `@alia.onl/sdk/runtime`
+  for custom Stop controls, with account-change fences and early-turn ids.
+- Requires the explicit Stop API receiver to be deployed before adoption; see
+  `docs/explicit-chat-stop.md` in the repository.
+
+
 ## 22.0.1
 
 Remove the Bloom peer upper bound to follow the first-party package policy.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "22.0.1",
+  "version": "22.1.1",
   "description": "Alia AI chat SDK — the conversation runtime, chat UI, voice calls and dictation for Oxy apps",
   "main": "src/index.ts",
   "react-native": "src/index.ts",

package/src/components/AliaChatContent.tsx

@@ -265,6 +265,8 @@ export interface AliaChatContentProps {
   presentedProgress?: SharedValue<number>;
   /** Internal sheet lifecycle bridge: receives the live request canceller. */
   onStopReady?: (stop: (() => void) | null) => void;
+  /** Detach a closed view while its durable answer continues. Never invokes explicit Stop. */
+  onDetachReady?: (detach: (() => void) | null) => void;
 }
 
 /** No live conversation while the thread looks at a moment of its past, as ONE array. */
@@ -319,6 +321,7 @@ function AliaConversationView({
   initialTurn,
   presentedProgress,
   onStopReady,
+  onDetachReady,
 }: ConversationViewProps) {
   const ownFlights = useAvatarFlights();
   const flights = sharedFlights ?? ownFlights;
@@ -359,6 +362,7 @@ function AliaConversationView({
     error,
     clearError,
     stopGeneration: stop,
+    detachGeneration: detach,
     startOver,
     clearConversation,
     suggestedNewConversation,
@@ -384,6 +388,10 @@ function AliaConversationView({
     onStopReady?.(stop);
     return () => onStopReady?.(null);
   }, [onStopReady, stop]);
+  useEffect(() => {
+    onDetachReady?.(detach);
+    return () => onDetachReady?.(null);
+  }, [onDetachReady, detach]);
 
   // ── What the person does: write, send, rewrite, call ──
   // An agent's starters are its welcome suggestions, unless the host brought its own.

package/src/components/AliaChatSheet.tsx

@@ -151,9 +151,9 @@ const AliaChatSheetBody = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
     const conversationProgress = useSharedValue(0);
     const mainRef = useRef<BottomSheetRef>(null);
     const conversationRef = useRef<BottomSheetRef>(null);
-    // Each sheet's chat registers its own canceller; closing a sheet stops its own turn.
-    const mainStopRef = useRef<(() => void) | null>(null);
-    const conversationStopRef = useRef<(() => void) | null>(null);
+    // Closing detaches this sheet's reader; only its explicit Stop cancels the generation.
+    const mainDetachRef = useRef<(() => void) | null>(null);
+    const conversationDetachRef = useRef<(() => void) | null>(null);
 
     // The conversation sheet, stacked over the main one while a chat is open: begun by a first
     // turn, or a stored one picked up again. The key makes every opening a fresh chat.
@@ -163,11 +163,11 @@ const AliaChatSheetBody = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
       conversationId?: string;
     } | null>(null);
 
-    const registerMainStop = useCallback((stop: (() => void) | null) => {
-      mainStopRef.current = stop;
+    const registerMainDetach = useCallback((stop: (() => void) | null) => {
+      mainDetachRef.current = stop;
     }, []);
-    const registerConversationStop = useCallback((stop: (() => void) | null) => {
-      conversationStopRef.current = stop;
+    const registerConversationDetach = useCallback((stop: (() => void) | null) => {
+      conversationDetachRef.current = stop;
     }, []);
 
     const startConversation = useCallback((turn: AliaTurn) => {
@@ -186,11 +186,11 @@ const AliaChatSheetBody = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
 
     // Back, and the menu's Clear: close the conversation, back to the main screen underneath.
     const closeConversation = useCallback(() => {
-      conversationStopRef.current?.();
+      conversationDetachRef.current?.();
       conversationRef.current?.dismiss();
     }, []);
     const onConversationDismissAttempt = useCallback(() => {
-      conversationStopRef.current?.();
+      conversationDetachRef.current?.();
       return true;
     }, []);
 
@@ -214,8 +214,8 @@ const AliaChatSheetBody = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
     );
 
     const handleDismiss = useCallback(() => {
-      conversationStopRef.current?.();
-      mainStopRef.current?.();
+      conversationDetachRef.current?.();
+      mainDetachRef.current?.();
       conversationRef.current?.dismiss();
       mainRef.current?.dismiss();
       closeThought();
@@ -239,8 +239,8 @@ const AliaChatSheetBody = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
 
     // Closing the main sheet (a drag, backdrop press, Back or Escape) closes what is stacked on it.
     const onMainDismissAttempt = useCallback(() => {
-      mainStopRef.current?.();
-      conversationStopRef.current?.();
+      mainDetachRef.current?.();
+      conversationDetachRef.current?.();
       conversationRef.current?.dismiss();
       closeThought();
       return true;
@@ -324,7 +324,7 @@ const AliaChatSheetBody = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
               ) : undefined
             }
             presentedProgress={mainProgress}
-            onStopReady={registerMainStop}
+            onDetachReady={registerMainDetach}
             onStart={startConversation}
           />
         </BottomSheet>
@@ -347,7 +347,7 @@ const AliaChatSheetBody = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
               conversationId={conversation.conversationId}
               onConversationChange={followConversation}
               presentedProgress={conversationProgress}
-              onStopReady={registerConversationStop}
+              onDetachReady={registerConversationDetach}
               chrome={conversationChrome}
             />
           </BottomSheet>

package/src/runtime/chat-turn-control.ts

@@ -0,0 +1,74 @@
+import type { OxyServices } from '@oxy.so/core';
+import { createRandomUuid } from './random-uuid';
+import { awaitTurnPreparation } from './turn-preparation';
+
+type LinkedClient = ReturnType<OxyServices['createLinkedClient']>;
+
+/** One client turn, created before any asynchronous preparation or metadata. */
+export function createChatTurnControl(
+  linked: LinkedClient,
+  headers: Promise<Record<string, string>>,
+  conversationId: string | undefined,
+  controller: AbortController,
+) {
+  // A host can reject before Stop is pressed. Observe that rejection immediately;
+  // awaiting the original promise below still reports the failure to Stop.
+  void headers.catch(() => undefined);
+  const id = createRandomUuid();
+  let stopping: Promise<void> | undefined;
+  let ended = false;
+  const lifetime = new AbortController();
+  const epoch = linked.client.getSessionEpoch();
+  const current = () => linked.client.getSessionEpoch() === epoch;
+  const unsubscribe = linked.client.addTokenChangeListener(() => {
+    if (!current()) {
+      const reason = new Error('The conversation account changed');
+      lifetime.abort(reason);
+      controller.abort(reason);
+    }
+  });
+  return {
+    id,
+    /** Only a deliberate Stop invokes this. View teardown merely aborts its transport. */
+    stop(): Promise<void> {
+      if (stopping) return stopping;
+      if (ended || controller.signal.aborted) return Promise.resolve();
+      stopping = (async () => {
+        const signal = AbortSignal.any([lifetime.signal, AbortSignal.timeout(10_000)]);
+        const assertionHeaders = await awaitTurnPreparation(headers, signal);
+        signal.throwIfAborted();
+        controller.signal.throwIfAborted();
+        if (!current()) throw new Error('The conversation account changed');
+        const response = await linked.client.requestAuthenticatedResponse({
+          url: `/v1/chat/turns/${id}/cancel`,
+          method: 'POST',
+          headers: { ...assertionHeaders, 'Content-Type': 'application/json' },
+          body: JSON.stringify({ ...(conversationId ? { conversationId } : {}) }),
+          // The cancelled chat signal must NOT cancel its own control request.
+          signal,
+        });
+        if (!response.ok) {
+          await response.body?.cancel();
+          throw new Error('Generation could not be stopped. Try again.');
+        }
+        await response.body?.cancel();
+        controller.abort();
+      })().catch((error) => {
+        stopping = undefined;
+        throw error;
+      });
+      return stopping;
+    },
+    async finish() {
+      ended = true;
+      // The stream can close before the replica answering Stop sends its acknowledgement.
+      await stopping?.catch(() => undefined);
+      lifetime.abort();
+      unsubscribe();
+      linked.dispose();
+    },
+  };
+}
+
+/** Public lifecycle handle for hosts that render their own Stop control. */
+export type AliaChatTurnControl = ReturnType<typeof createChatTurnControl>;

package/src/runtime/index.ts

@@ -112,3 +112,5 @@ export type { BuiltMessageContent, DroppedAttachment, UploadDocument } from './a
 
 // The conversation as data (also the leaf entry `@alia.onl/sdk/model`).
 export * from './model';
+
+export { createChatTurnControl, type AliaChatTurnControl } from './chat-turn-control';

package/src/runtime/turn-preparation.ts

@@ -0,0 +1,21 @@
+/** Fence asynchronous host preparation without waiting for an uncooperative host. */
+export function awaitTurnPreparation<T>(pending: Promise<T>, signal: AbortSignal): Promise<T> {
+  return new Promise<T>((resolve, reject) => {
+    const aborted = () => {
+      signal.removeEventListener('abort', aborted);
+      reject(signal.reason);
+    };
+    pending.then(
+      (value) => {
+        signal.removeEventListener('abort', aborted);
+        resolve(value);
+      },
+      (error) => {
+        signal.removeEventListener('abort', aborted);
+        reject(error);
+      },
+    );
+    if (signal.aborted) aborted();
+    else signal.addEventListener('abort', aborted, { once: true });
+  });
+}

package/src/runtime/use-conversation-stream.ts

@@ -15,6 +15,8 @@ import {
 import { agentMessageId, buildOutboundMessages, isAgentMessageOf } from './message-history';
 import { aliaQueryKeys } from './query-keys';
 import { createRandomUuid } from './random-uuid';
+import { createChatTurnControl } from './chat-turn-control';
+import { awaitTurnPreparation } from './turn-preparation';
 import { type AliaHostTools, HostOutcomeQueue, hostRequest } from './host-tools';
 import { API_ROUTES } from './routes';
 import { createSseFrameReader } from './sse-frame-reader';
@@ -213,6 +215,9 @@ export function useConversationStream({
   const appAssertionHeaders = useAppAssertionHeaders();
   const queryClient = useQueryClient();
   const abortControllerRef = useRef<AbortController | null>(null);
+  const turnControlRef = useRef<ReturnType<typeof createChatTurnControl> | null>(null);
+  // A Stop acknowledgement can outlive its stream, thread, or the next send.
+  const turnGenerationRef = useRef(0);
 
   // Batching refs: accumulate streaming text and flush at ~20fps instead of per-chunk
   const pendingContentRef = useRef('');
@@ -276,6 +281,8 @@ export function useConversationStream({
     mountedRef.current = true;
     return () => {
       mountedRef.current = false;
+      turnGenerationRef.current++;
+      turnControlRef.current = null;
       flushPendingUpdates();
       if (flushTimerRef.current) {
         clearTimeout(flushTimerRef.current);
@@ -321,6 +328,8 @@ export function useConversationStream({
     const was = conversationRef.current;
     conversationRef.current = conversationId;
     if (was !== undefined && was !== conversationId) {
+      turnGenerationRef.current++;
+      turnControlRef.current = null;
       hostOutcomesRef.current.clear();
       // The reply still streaming belongs to the thread that was left: cut it, drop what it had
       // batched (it would land on this thread's last message) and let the screen be idle.
@@ -347,6 +356,8 @@ export function useConversationStream({
     const was = accountRef.current;
     accountRef.current = accountId;
     if (was === null || was === accountId) return;
+    turnGenerationRef.current++;
+    turnControlRef.current = null;
     abortControllerRef.current?.abort();
     abortControllerRef.current = null;
     dropPendingUpdates();
@@ -364,6 +375,7 @@ export function useConversationStream({
 
   const append = useCallback(
     async (message: Omit<Message, 'id'>, options?: SendOptions): Promise<SendOutcome> => {
+      const turnGeneration = ++turnGenerationRef.current;
       setIsLoading(true);
       setError(null);
       // A new send answers the old failure, whether it is the retry or a fresh
@@ -615,6 +627,7 @@ export function useConversationStream({
       /** The request's own controller: `finally` asks it whether the person stopped the turn. */
       let controller: AbortController | null = null;
       let linked: ReturnType<typeof oxyServices.createLinkedClient> | null = null;
+      let turnControl: ReturnType<typeof createChatTurnControl> | null = null;
       /** Cut THIS turn's stream. Never the ref's: by now it may hold a later turn's controller. */
       const abortThisTurn = (): void => {
         controller?.abort();
@@ -626,9 +639,17 @@ export function useConversationStream({
         // conversation change reach a turn that is still collecting device info.
         controller = new AbortController();
         abortControllerRef.current = controller;
-
-        // Collect device info (will be available to AI via tool if needed)
-        const deviceInfo = host.deviceInfo ? await host.deviceInfo() : undefined;
+        linked = oxyServices.createLinkedClient({ baseURL: apiUrl });
+        const assertion = appAssertionHeaders();
+        turnControl = createChatTurnControl(linked, assertion, conversationId, controller);
+        turnControlRef.current = turnControl;
+
+        // Attach both rejection handlers immediately; a slow host must not leave
+        // an already rejected surface assertion unobserved or defeat detachment.
+        const [appAssertion, deviceInfo] = await awaitTurnPreparation(
+          Promise.all([assertion, host.deviceInfo ? host.deviceInfo() : undefined]),
+          controller.signal,
+        );
         if (controller.signal.aborted) return 'aborted';
 
         /**
@@ -646,8 +667,7 @@ export function useConversationStream({
         // Authentication, the preflight refresh and the single 401 replay belong
         // to the linked Oxy client; this layer never reads or writes a bearer.
         // Which Oxy app this turn is in (ADR 0021): an agent Oxy confines to an app opens only there.
-        const appAssertion = await appAssertionHeaders();
-        linked = oxyServices.createLinkedClient({ baseURL: apiUrl });
+        if (controller.signal.aborted) return 'aborted';
         const response = await linked.client.requestAuthenticatedResponse({
           method: 'POST',
           url: API_ROUTES.chat,
@@ -658,6 +678,7 @@ export function useConversationStream({
             ...(deviceInfo === undefined ? {} : { 'X-Device-Info': JSON.stringify(deviceInfo) }),
           },
           body: JSON.stringify({
+            turnId: turnControl.id,
             messages: messagesToSend,
             // The reply is stored under the id it is drawn under here, so a vote
             // or a read-aloud on it needs no reload to find it.
@@ -688,6 +709,12 @@ export function useConversationStream({
           const lockedFeature = lockedFeatureOf(
             errorData?.error && typeof errorData.error === 'object' ? errorData.error : null,
           );
+          if (errorCode(errorData?.error) === 'turn_cancelled') {
+            flushPendingUpdates();
+            settleAssistant('cancelled');
+            abortThisTurn();
+            return 'aborted';
+          }
           if (lockedFeature !== null) {
             host.onFeatureLocked?.(lockedFeature);
             return rollback();
@@ -1037,6 +1064,13 @@ export function useConversationStream({
               // Handle structured error events sent via SSE
               if (parsed.error) {
                 const err = parsed.error;
+                if (errorCode(err) === 'turn_cancelled') {
+                  flushPendingUpdates();
+                  settleAssistant('cancelled');
+                  abortThisTurn();
+                  reader.cancel().catch(() => {});
+                  return 'aborted';
+                }
                 // An agent's feature gate refused the turn before anything was spent: the host
                 // shows its own upsell, and the person's words go back to the composer.
                 const lockedFeature = lockedFeatureOf(err);
@@ -1351,31 +1385,31 @@ export function useConversationStream({
         setError(finalError);
         return keepFailedTurn(true, finalError.message);
       } finally {
-        // Flush any remaining batched content
-        flushPendingUpdates();
-        if (flushTimerRef.current) {
-          clearTimeout(flushTimerRef.current);
-          flushTimerRef.current = null;
+        // Batches belong to the current turn. An older finally must not flush or clear
+        // the next turn's shared timer, even when its controller ref has been cleared.
+        if (turnGenerationRef.current === turnGeneration) {
+          flushPendingUpdates();
+          if (flushTimerRef.current) {
+            clearTimeout(flushTimerRef.current);
+            flushTimerRef.current = null;
+          }
         }
-        // Only the turn that still owns the ref clears it and the loading flag: after Stop and a new
-        // send, this `finally` belongs to the old turn and must not idle the new one.
-        const ownsTurn =
-          abortControllerRef.current === null || abortControllerRef.current === controller;
-        if (abortControllerRef.current === controller) abortControllerRef.current = null;
-        linked?.dispose();
-        // A turn that is still streaming here ended without an error path
-        // settling it: on its own, or because `stop()` aborted the controller.
-        // (The error paths abort it too, but they have settled it first.)
+        // Settle only this turn's message ids, including when a new send has already
+        // started in the same conversation. Error paths may have settled them first.
         settleAssistant(controller?.signal.aborted === true ? 'cancelled' : 'completed');
-        if (ownsTurn) setIsLoading(false);
-        /*
-         * The answer replaces your own line in the sidebar — once per turn rather
-         * than once per token. Read from what this turn received, not from the
-         * rendered messages, which have not caught up with the last batched flush.
-         */
-        if (replyText !== '') host.onTurnPreview?.(agentId, replyText);
-        // Every way a turn stops streaming — finished, stopped, failed — passes here once.
-        if (mountedRef.current) host.onTurnEnd?.();
+        // Retain this control while its ACK drains so repeated Stop remains deduplicated.
+        // Local transport cleanup is required even after the thread has been replaced.
+        if (turnControl) await turnControl.finish();
+        else linked?.dispose();
+        if (abortControllerRef.current === controller) abortControllerRef.current = null;
+        if (turnControlRef.current === turnControl) turnControlRef.current = null;
+        // Recheck after the await: another turn, thread, account or mount may now own UI.
+        if (mountedRef.current && turnGenerationRef.current === turnGeneration) {
+          setIsLoading(false);
+          // The sidebar preview and completion notification belong to this visible turn.
+          if (replyText !== '') host.onTurnPreview?.(agentId, replyText);
+          host.onTurnEnd?.();
+        }
       }
     },
     [
@@ -1397,7 +1431,7 @@ export function useConversationStream({
     ],
   );
 
-  const stop = useCallback(() => {
+  const detach = useCallback(() => {
     if (abortControllerRef.current) {
       abortControllerRef.current.abort();
       abortControllerRef.current = null;
@@ -1405,6 +1439,21 @@ export function useConversationStream({
     setIsLoading(false);
   }, []);
 
+  const stop = useCallback(() => {
+    const turn = turnControlRef.current;
+    const turnGeneration = turnGenerationRef.current;
+    if (!turn) return;
+    void turn.stop().catch((error: unknown) => {
+      if (
+        turnControlRef.current === turn &&
+        turnGenerationRef.current === turnGeneration &&
+        mountedRef.current
+      ) {
+        setError(error instanceof Error ? error : new Error('Generation could not be stopped.'));
+      }
+    });
+  }, []);
+
   const clearError = useCallback(() => setError(null), []);
 
   /**
@@ -1451,6 +1500,7 @@ export function useConversationStream({
     error,
     append,
     stop,
+    detach,
     setMessages: setMessagesAndRef,
     conversationTitle,
     clearError,

package/src/runtime/use-conversation-thread.ts

@@ -134,6 +134,7 @@ export function useConversationThread({
     clearError,
     setMessages,
     stop,
+    detach,
     suggestedNewConversation,
     dismissSuggestedNewConversation,
     agentRun,
@@ -547,6 +548,7 @@ export function useConversationThread({
     promptOf,
     turnOptionsOf,
     stopGeneration,
+    detachGeneration: detach,
     clearConversation,
     clearError,
     setMessages,