@alia.onl/sdk 20.1.0 → 21.1.0

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # @alia.onl/sdk
 
+## 21.1.0
+
+A shared conversation has one address, Alia's, whichever app minted it (`docs/agent-embedding.md`
+§6).
+
+### Added
+
+- **`url` on `AliaConversationShare`**: `useShareConversation().share` (and a host's `onShare`)
+  gets the link to hand on, `https://alia.onl/shared/<token>`, rather than a token to build its own
+  page around.
+- **`aliaSharedConversationUrl(token)`**: the same link, for an app that redirects the share links
+  it minted before to Alia's page.
+
+## 21.0.0
+
+A conversation records the Oxy app it started in, so an embedding app lists only its own while
+the Alia app lists all of them (`docs/agent-embedding.md` §6). The app is named once, on the chat.
+
+### Added
+
+- **`app` on `AliaChatContent`, `AliaChatSheet`, `AliaChatScreen`, `AliaAskProvider` and
+  `AliaRuntimeProvider`**: the embedding app's slug (`homiio`, `mercaria`). Every turn carries it
+  as `host.app` — with an empty tool list when the chat has no host tools — and
+  `POST /v1/conversations/new` and `POST /v1/conversations` carry it as `app`, so a conversation
+  the chat starts is labelled with it. Omitted, the chat is Alia's own and labels nothing.
+- **`useConversations({ app })`**: only the conversations started in that app
+  (`GET /v1/conversations?app=`), composable with `agentId`. The chat's `app` does not imply it:
+  the app that wants only its own asks for them.
+- **`Conversation.app`**: the app a conversation started in, or `null`.
+- **The sheet's recent conversations are the app's.** In a sheet with an `app`, the recents under
+  the greeting (20.1.0) are the ones started in that app; Alia's own sheet still lists any.
+
+### Changed (breaking)
+
+- **`AliaHostTools` has no `app`.** Host tools are the chat's `app`'s, which a chat with
+  `hostTools` must name; one without throws on render. Move `hostTools.app` to the chat's `app`.
+- **`hostRequest(app, tools, outcomes)`** and **`HostOutcomeQueue.dispatch(action, tools, app)`**
+  take the app.
+- **`aliaQueryKeys.conversations.withAgent(id)` is `filtered({ agentId, app })`.**
+
+## 20.3.0
+
+A host hears when a turn has stopped streaming.
+
+### Added
+
+- **`AliaRuntimeHost.onTurnEnd`**, the pair of `onTurnStart`: called exactly once for each turn
+  the runtime sends, once it stops streaming for any reason — finished, stopped (Stop) or failed —
+  and only while the conversation that sent it is still mounted, so a surface that left mid-turn
+  is never called back. A host that holds back what would take the chat off the screen runs it
+  here, instead of watching `useConversationStore().streamingConversationId`.
+
+## 20.2.0
+
+An app mounts its one sheet at the root without the chat in its entry bundle.
+
+### Added
+
+- **`@alia.onl/sdk/ask`**, a leaf entry with `AliaAskProvider` and `useAskAgent` alone. The root
+  entry still exports both, but brings the whole chat with them.
+
+### Changed
+
+- **`AliaAskProvider` loads its sheet lazily** (`components/AliaAskSheet.tsx`, one `import()`) and
+  mounts it on the first `ask`. Signed in, the module is fetched in the background, so the first
+  `ask` does not wait on the network. `check:entries` holds that `./ask` loads none of the chat
+  with the entry.
+- **Ref and event types are React Native 0.88-ready.** A ref to a `ScrollView` or `TextInput` is
+  typed `ComponentRef<typeof …>` (0.88 types both as function components), and key presses are
+  `TextInputKeyPressEvent` (`TextInputKeyPressEventData` is deprecated since 0.86). Nothing
+  changes on 0.86. The peer ranges stay on Expo 57 / React Native 0.86: Bloom's own `TextInput`
+  ref props are not 0.88-ready yet.
+
 ## 20.1.0
 
 The one sheet is the whole surface an app needs for an agent: it picks a conversation up again and

package/README.md

@@ -146,7 +146,7 @@ Every agent — Alia included — is the same agent (ADR 0020), and any Oxy app
 person can reach. The wire contract is [`docs/agent-embedding.md`](../../docs/agent-embedding.md).
 
 ```tsx
-import { AliaAskProvider, useAskAgent } from '@alia.onl/sdk';
+import { AliaAskProvider, useAskAgent } from '@alia.onl/sdk/ask';
 
 <AliaAskProvider
   agents={{ alia: {}, sindi: { id: SINDI_AGENT_ID } }}  // no id = Alia
@@ -169,6 +169,10 @@ resume('sindi', conversationId); // a stored conversation, where the person left
 dismiss(); // e.g. after a host tool changed the page under the sheet
 ```
 
+Mount it from `@alia.onl/sdk/ask`: that entry is the provider and its hook alone, and the sheet
+loads with the first `ask` (fetched in the background once the person is signed in), so the chat
+stays out of the app's entry bundle. The root entry exports the same two, with the whole chat.
+
 The sheet offers the person's latest conversations with its lead under the greeting
 (`recentConversations={false}` turns it off). The code that configures the sheet sits above it, so
 `AliaAskProvider` forwards a ref to the same `AliaAsk` for it.
@@ -337,6 +341,9 @@ const host: AliaRuntimeHost = {
   showThought: (opening) => (opening === 'automatic' && panel.isOpen ? false : panel.show('thought')),
   openAutomation: (id) => router.push(`/automations/${id}`), // a scheduled-task card is a link
   faviconUrl: (url) => favicons.of(url), // the work log's source icons
+  // the edges of a turn this runtime sends
+  onTurnStart: () => executor.beginTurn(),
+  onTurnEnd: () => executor.runHeldBack(), // finished, stopped or failed: once per turn
 };
 
 <AliaRuntimeProvider
@@ -350,6 +357,12 @@ const host: AliaRuntimeHost = {
 </AliaRuntimeProvider>;
 ```
 
+`onTurnEnd` is called exactly once for each turn the runtime sends, when it stops streaming —
+the answer was written, the person pressed Stop, or the turn failed — and only while the
+conversation that sent it is still mounted. A host that holds back what would take the chat off
+the screen (a host tool that navigates away) runs it there; a surface that left mid-turn is never
+called back, so what it held back goes with it.
+
 The sheet and the Alia app differ ONLY in what they put there:
 
 ```tsx

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "20.1.0",
+  "version": "21.1.0",
   "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",
@@ -8,6 +8,7 @@
   "types": "src/index.ts",
   "exports": {
     ".": "./src/index.ts",
+    "./ask": "./src/ask.ts",
     "./avatar": "./src/avatar.ts",
     "./content": "./src/lib/content-utils.ts",
     "./csp": "./src/csp.ts",

package/src/ask.ts

@@ -0,0 +1,7 @@
+// @alia.onl/sdk/ask — the app's one Alia sheet, without the chat in the entry bundle
+// `AliaAskProvider` and `useAskAgent` alone: the sheet they open is loaded with the first `ask`.
+// An app mounts the provider at its root from here rather than from the root entry, which
+// would bring the whole chat along with it.
+
+export { AliaAskProvider, useAskAgent } from './components/AliaAskProvider';
+export type { AliaAsk, AliaAskAgents, AliaAskProviderProps } from './components/AliaAskProvider';

package/src/components/AliaAskProvider.tsx

@@ -5,13 +5,20 @@
  * once — its host tools, renderers, words, voice, context, upsell and share. A button calls
  * `useAskAgent().ask(key, turn)`. Signed out, the sheet is not mounted (it could not call Alia):
  * `ask` opens Oxy's sign-in instead, and the person asks again once signed in.
+ *
+ * The sheet itself (`AliaAskSheet`) is loaded lazily and mounted on the first `ask`, so an app
+ * that mounts this provider at its root — imported from `@alia.onl/sdk/ask` — keeps the chat out
+ * of its entry bundle. Signed in, its module is fetched in the background so the first `ask`
+ * does not wait on the network.
  */
 
 import { useAuth } from '@oxy.so/services/ui/client';
 import {
   createContext,
   forwardRef,
+  lazy,
   type ReactNode,
+  Suspense,
   useCallback,
   useContext,
   useEffect,
@@ -21,7 +28,11 @@ import {
   useState,
 } from 'react';
 import type { AliaTurn } from '../hooks/useChatComposer';
-import { AliaChatSheet, type AliaChatSheetProps, type AliaChatSheetRef } from './AliaChatSheet';
+import type { AliaChatSheetProps, AliaChatSheetRef } from './AliaChatSheet';
+import type { AliaAskOpening } from './AliaAskSheet';
+
+const loadSheet = () => import('./AliaAskSheet');
+const LazyAskSheet = lazy(() => loadSheet().then((module) => ({ default: module.AliaAskSheet })));
 
 /** The agents an app offers, by its own key. An entry without `id` is Alia. */
 export type AliaAskAgents = Readonly<Record<string, { id?: string }>>;
@@ -29,6 +40,7 @@ export type AliaAskAgents = Readonly<Record<string, { id?: string }>>;
 export interface AliaAskProviderProps
   extends Pick<
     AliaChatSheetProps,
+    | 'app'
     | 'hostTools'
     | 'toolRenderers'
     | 'labels'
@@ -73,14 +85,9 @@ export function useAskAgent(): AliaAsk {
   return ask;
 }
 
-/** Which agent the sheet is on, and the opening that waits for that sheet to mount. */
-interface Opening {
+/** The opening that waits for the sheet of agent `key` to be the one mounted. */
+interface Opening extends AliaAskOpening {
   key: string | undefined;
-  turn: AliaTurn | undefined;
-  /** A stored conversation to open instead of the welcome. */
-  conversationId?: string;
-  /** Changes on every `ask`, so asking the same agent twice opens twice. */
-  serial: number;
 }
 
 /**
@@ -95,6 +102,8 @@ export const AliaAskProvider = forwardRef<AliaAsk, AliaAskProviderProps>(functio
   const sheetRef = useRef<AliaChatSheetRef>(null);
   const [opening, setOpening] = useState<Opening | null>(null);
   const [current, setCurrent] = useState<string | undefined>(undefined);
+  /** Nothing is mounted before the first `ask`. */
+  const [asked, setAsked] = useState(false);
   const agentsRef = useRef(agents);
   agentsRef.current = agents;
 
@@ -107,6 +116,7 @@ export const AliaAskProvider = forwardRef<AliaAsk, AliaAskProviderProps>(functio
         void signIn().catch(() => undefined);
         return;
       }
+      setAsked(true);
       setCurrent(agentKey);
       setOpening((previous) => ({
         key: agentKey,
@@ -125,13 +135,12 @@ export const AliaAskProvider = forwardRef<AliaAsk, AliaAskProviderProps>(functio
   );
   const dismiss = useCallback(() => sheetRef.current?.dismiss(), []);
 
-  // Presented once the sheet for that agent is the one mounted (a different agent is a new sheet).
+  const opened = useCallback(() => setOpening(null), []);
+
+  // Signed in, the sheet's module comes down in the background, ahead of the first `ask`.
   useEffect(() => {
-    if (opening === null || opening.key !== current) return;
-    if (opening.conversationId !== undefined) sheetRef.current?.resume(opening.conversationId);
-    else sheetRef.current?.present(opening.turn);
-    setOpening(null);
-  }, [opening, current]);
+    if (canUsePrivateApi) void loadSheet().catch(() => undefined);
+  }, [canUsePrivateApi]);
 
   const agentId = current === undefined ? undefined : agents?.[current]?.id;
   const agent = useMemo(() => (agentId === undefined ? undefined : { id: agentId }), [agentId]);
@@ -141,14 +150,19 @@ export const AliaAskProvider = forwardRef<AliaAsk, AliaAskProviderProps>(functio
   return (
     <AskContext.Provider value={value}>
       {children}
-      {canUsePrivateApi ? (
-        <AliaChatSheet
-          key={agentId ?? 'alia'}
-          ref={sheetRef}
-          {...sheet}
-          agent={agent}
-          welcomeSuggestions={agent === undefined ? welcomeSuggestions : undefined}
-        />
+      {canUsePrivateApi && asked ? (
+        <Suspense fallback={null}>
+          <LazyAskSheet
+            key={agentId ?? 'alia'}
+            ref={sheetRef}
+            {...sheet}
+            agent={agent}
+            welcomeSuggestions={agent === undefined ? welcomeSuggestions : undefined}
+            // A different agent is a new sheet: the opening waits for that one to mount.
+            opening={opening !== null && opening.key === current ? opening : null}
+            onOpened={opened}
+          />
+        </Suspense>
       ) : null}
     </AskContext.Provider>
   );

package/src/components/AliaAskSheet.tsx

@@ -0,0 +1,52 @@
+/**
+ * The sheet `AliaAskProvider` mounts, in its own module so the provider can load it lazily: an app
+ * that mounts the provider at its root carries only the provider in its entry bundle, and the
+ * chat — thread, composer, voice, renderers — arrives with the first `ask`.
+ *
+ * It presents the opening it is handed once it is mounted, which is the only moment a lazily
+ * loaded sheet can be presented, and tells the provider the opening is spent.
+ */
+
+import { forwardRef, useEffect, useImperativeHandle, useRef } from 'react';
+import type { AliaTurn } from '../hooks/useChatComposer';
+import { AliaChatSheet, type AliaChatSheetProps, type AliaChatSheetRef } from './AliaChatSheet';
+
+/** What the person asked for: a turn to send, or a stored conversation to pick up again. */
+export interface AliaAskOpening {
+  turn: AliaTurn | undefined;
+  conversationId?: string;
+  /** Changes on every `ask`, so asking the same agent twice opens twice. */
+  serial: number;
+}
+
+export interface AliaAskSheetProps extends AliaChatSheetProps {
+  /** The opening to present once mounted; `null` when there is none waiting. */
+  opening: AliaAskOpening | null;
+  /** The opening was presented. */
+  onOpened: () => void;
+}
+
+export const AliaAskSheet = forwardRef<AliaChatSheetRef, AliaAskSheetProps>(function AliaAskSheet(
+  { opening, onOpened, ...sheet },
+  ref,
+) {
+  const sheetRef = useRef<AliaChatSheetRef>(null);
+  useImperativeHandle(
+    ref,
+    () => ({
+      present: (turn?: AliaTurn) => sheetRef.current?.present(turn),
+      resume: (conversationId: string) => sheetRef.current?.resume(conversationId),
+      dismiss: () => sheetRef.current?.dismiss(),
+    }),
+    [],
+  );
+
+  useEffect(() => {
+    if (opening === null) return;
+    if (opening.conversationId !== undefined) sheetRef.current?.resume(opening.conversationId);
+    else sheetRef.current?.present(opening.turn);
+    onOpened();
+  }, [opening, onOpened]);
+
+  return <AliaChatSheet ref={sheetRef} {...sheet} />;
+});

package/src/components/AliaChatContent.tsx

@@ -50,7 +50,7 @@ import { type AliaChatLabels, AliaChatLabelsProvider, useLabels } from '../lib/l
 import { type DeviceModel, buildPowerLevelOptions } from '../lib/power-level-options';
 import { ALIA_FEATURES, featureOffer, useAgentFeatures, useAgentProfile } from '../runtime/agents';
 import { type AliaRuntimeHost, AliaRuntimeProvider, useAliaRuntime } from '../runtime/config';
-import type { AliaHostTools } from '../runtime/host-tools';
+import { type AliaHostTools, APP_SLUG } from '../runtime/host-tools';
 import { useCreateConversation } from '../runtime/conversations';
 import { aliaQueryKeys } from '../runtime/query-keys';
 import type { Message } from '../runtime/types';
@@ -137,12 +137,20 @@ export interface AliaChatContentProps {
    */
   ephemeral?: boolean;
   apiUrl?: string;
+  /**
+   * The Oxy app this chat is embedded in, by its slug (`homiio`, `mercaria`). A conversation the
+   * chat starts is labelled with it, so the app can list only its own
+   * (`useConversations({ app })`), and its `hostTools` are this app's. Omitted, the chat is
+   * Alia's own (`docs/agent-embedding.md` §6).
+   */
+  app?: string;
   /** App context injected into the system prompt. */
   clientContext?: string;
   /**
    * The UI effects this app's client performs for the lead (`docs/agent-embedding.md` §2). Declared
-   * with every turn; an action the stream asks for is performed once, by `execute`, and its
-   * outcome reaches the model with the next turn.
+   * with every turn under the chat's `app`, which a chat with host tools must name; an action the
+   * stream asks for is performed once, by `execute`, and its outcome reaches the model with the
+   * next turn.
    */
   hostTools?: AliaHostTools;
   /** The app's own drawing of a catalogue tool's result, keyed `<app>:<tool>`, before the generic card. */
@@ -715,12 +723,24 @@ export function AliaChatContent({
   onConversationChange,
   runtime,
   apiUrl,
+  app,
   toolRenderers,
   onFeatureLocked,
   ...props
 }: AliaChatContentProps) {
   const [ownId, setOwnId] = useState<string | undefined>(undefined);
   const parent = useAliaRuntime();
+  const chatApp = app ?? parent.app;
+  if (chatApp !== undefined && !APP_SLUG.test(chatApp)) {
+    throw new Error(
+      `AliaChatContent: app "${chatApp}" is not an app slug (^[a-z][a-z0-9-]{0,31}$)`,
+    );
+  }
+  if (props.hostTools !== undefined && chatApp === undefined) {
+    throw new Error(
+      "AliaChatContent: hostTools are an app's, so a chat with hostTools names its app",
+    );
+  }
   // Who decides which conversation is open: a host that navigates (a route) does; with none, the
   // chat does (the sheet). Either way the host hears of it first, then `onConversationChange`.
   const hostOpens = runtime?.openConversation ?? parent.host.openConversation;
@@ -746,7 +766,7 @@ export function AliaChatContent({
 
   return (
     <AliaChatLabelsProvider labels={labels}>
-      <AliaRuntimeProvider apiUrl={apiUrl ?? parent.apiUrl} host={host}>
+      <AliaRuntimeProvider apiUrl={apiUrl ?? parent.apiUrl} host={host} app={chatApp}>
         <AliaToolRenderersProvider value={toolRenderers ?? NO_RENDERERS}>
           <AliaConversationView {...props} conversationId={controlledId ?? ownId} />
         </AliaToolRenderersProvider>

package/src/components/AliaChatScreen.tsx

@@ -42,6 +42,8 @@ export interface AliaChatScreenProps {
   agent?: AliaChatAgentRef;
   /** App context injected into system prompt */
   clientContext?: string;
+  /** The Oxy app this chat is embedded in, by its slug (see `AliaChatContentProps.app`). */
+  app?: string;
   /** The UI effects this app performs for the lead (see `AliaChatContentProps.hostTools`). */
   hostTools?: AliaHostTools;
   /** The app's own drawing of catalogue tools' results, keyed `<app>:<tool>`. */
@@ -87,6 +89,7 @@ export interface AliaChatScreenProps {
 
 export function AliaChatScreen({
   agent,
+  app,
   clientContext,
   hostTools,
   toolRenderers,
@@ -147,6 +150,7 @@ export function AliaChatScreen({
         <KeyboardAvoidingView behavior="padding" automaticOffset style={{ flex: 1 }}>
           <AliaChatContent
             agent={agent}
+            app={app}
             clientContext={clientContext}
             hostTools={hostTools}
             toolRenderers={toolRenderers}

package/src/components/AliaChatSheet.tsx

@@ -54,6 +54,8 @@ export interface AliaChatSheetProps {
   agent?: AliaChatAgentRef;
   /** App context injected into system prompt */
   clientContext?: string;
+  /** The Oxy app this chat is embedded in, by its slug (see `AliaChatContentProps.app`). */
+  app?: string;
   /** The UI effects this app performs for the lead (see `AliaChatContentProps.hostTools`). */
   hostTools?: AliaHostTools;
   /** The app's own drawing of catalogue tools' results, keyed `<app>:<tool>`. */
@@ -110,6 +112,7 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
   (
     {
       agent,
+      app,
       clientContext,
       hostTools,
       toolRenderers,
@@ -268,6 +271,7 @@ export const AliaChatSheet = forwardRef<AliaChatSheetRef, AliaChatSheetProps>(
       flights,
       layout: 'sheet' as const,
       agent,
+      app,
       clientContext,
       hostTools,
       toolRenderers,

package/src/components/AliaComposer.tsx

@@ -7,12 +7,7 @@ import {
   type ReactNode,
   type RefObject,
 } from 'react';
-import {
-  View,
-  type NativeSyntheticEvent,
-  type TextInput,
-  type TextInputKeyPressEventData,
-} from 'react-native';
+import { View, type TextInputKeyPressEvent } from 'react-native';
 import {
   ComposerPill,
   type ComposerPanelAddMenuGroup,
@@ -28,6 +23,7 @@ import type { Completion } from '../lib/suggestions';
 import { composerTiles, intakeError } from '../lib/attachment-tiles';
 import type { IntakeKind } from '../lib/attachment-intake';
 import { KeyboardAvoidingView } from '../lib/keyboard';
+import type { TextInputHandle } from '../lib/text-input';
 import { type AliaChatLabels, AliaChatLabelsProvider, useLabels } from '../lib/labels';
 import type { AskedQuestion } from '../lib/questions';
 import type { VoiceErrorCode } from '../lib/speech-messages';
@@ -116,11 +112,11 @@ export interface AliaComposerProps<T extends AliaSuggestion = AliaSuggestion> {
    */
   accessory?: ReactNode;
   /** The field's keys, before the panel's own Enter rule (suggestions over it). */
-  onKeyPress?: (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => void;
+  onKeyPress?: (event: TextInputKeyPressEvent) => void;
   /** The host already avoids the keyboard. */
   disableKeyboardAvoidance?: boolean;
   /** The field itself, for a host that moves focus into it. */
-  inputRef?: RefObject<TextInput | null>;
+  inputRef?: RefObject<TextInputHandle | null>;
   /** Dictation's language, a BCP-47 tag; omitted, the platform's own. */
   speechLanguage?: string;
   /** Alia's API, which transcribes dictation; omitted, `EXPO_PUBLIC_ALIA_API_URL` or production. */

package/src/components/AliaRecentConversations.tsx

@@ -3,6 +3,7 @@ import { Text } from '@oxy.so/bloom/typography';
 import { useMemo } from 'react';
 import { View } from 'react-native';
 import { useLabels } from '../lib/labels';
+import { useAliaRuntime } from '../runtime/config';
 import { useConversations } from '../runtime/conversations';
 
 /** How many of the lead's conversations the sheet offers to pick up again. */
@@ -11,7 +12,9 @@ export const RECENT_CONVERSATIONS_SHOWN = 3;
 /**
  * The person's latest conversations with the sheet's lead, under its greeting: "Ask Sindi" picks
  * up where it left off instead of every opening being a blank page. Alia's own sheet lists the
- * person's latest conversations of any kind. Nothing while loading or when there are none.
+ * person's latest conversations of any kind. In an app's sheet (the chat's `app`) they are the ones
+ * started in that app: Mercaria's sheet offers Mercaria's, never a Homiio chat. Nothing while
+ * loading or when there are none.
  */
 export function AliaRecentConversations({
   agentId,
@@ -22,7 +25,11 @@ export function AliaRecentConversations({
   onOpen: (conversationId: string) => void;
 }) {
   const labels = useLabels();
-  const { data } = useConversations(agentId === undefined ? {} : { agentId });
+  const { app } = useAliaRuntime();
+  const { data } = useConversations({
+    ...(agentId === undefined ? {} : { agentId }),
+    ...(app === undefined ? {} : { app }),
+  });
   const recent = useMemo(
     () => data?.pages[0]?.conversations.slice(0, RECENT_CONVERSATIONS_SHOWN) ?? [],
     [data],

package/src/hooks/useChatComposer.ts

@@ -1,10 +1,11 @@
 import type { AvatarFlights } from '@oxy.so/bloom/avatar-flight';
 import { useOxy } from '@oxy.so/services/ui/client';
 import { useCallback, useEffect, useMemo, useRef } from 'react';
-import type { NativeSyntheticEvent, TextInput, TextInputKeyPressEventData } from 'react-native';
+import type { TextInputKeyPressEvent } from 'react-native';
 import type { SharedValue } from 'react-native-reanimated';
 import { leadToProfile } from '../lib/flights';
 import type { AliaLead } from '../lib/participants';
+import type { TextInputHandle } from '../lib/text-input';
 import { imageUriToDataUrl } from '../lib/image-data-url';
 import {
   useComposerDraft,
@@ -254,7 +255,7 @@ export function useChatComposer({
   });
 
   // ── The field: focus, and its keys ──
-  const inputRef = useRef<TextInput | null>(null);
+  const inputRef = useRef<TextInputHandle | null>(null);
   useFocusWhenPresented(presentedProgress, () => inputRef.current?.focus());
   // Starting an edit puts the caret in the composer that now holds the question: the Edit press
   // left focus on the row's button, so typing went nowhere and Escape could not reach the edit.
@@ -265,7 +266,7 @@ export function useChatComposer({
   const { onKeyPress: onSuggestionKeyPress } = suggestions;
   const cancelEdit = edit.cancel;
   const onKeyPress = useCallback(
-    (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+    (event: TextInputKeyPressEvent) => {
       // Escape leaves an edit, as its Cancel does: it is the top-most thing open while the
       // question is being rewritten.
       if (editing !== undefined && event.nativeEvent.key === 'Escape') {

package/src/hooks/useComposerSuggestions.ts

@@ -1,5 +1,5 @@
 import { useCallback, useEffect, useMemo, useState } from 'react';
-import type { NativeSyntheticEvent, TextInputKeyPressEventData } from 'react-native';
+import type { TextInputKeyPressEvent } from 'react-native';
 import {
   type Completion,
   SEARCH_DEBOUNCE_MS,
@@ -62,7 +62,7 @@ export function useComposerSuggestions<T extends AliaSuggestion>({
   );
 
   const onKeyPress = useCallback(
-    (event: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+    (event: TextInputKeyPressEvent) => {
       if (completions.length === 0) return;
       const key = event.nativeEvent.key;
       if (key === 'ArrowDown' || key === 'ArrowUp') {

package/src/lib/keyboard.tsx

@@ -16,11 +16,14 @@ type KeyboardAwareScrollViewProps = ScrollViewProps & {
   extraKeyboardSpace?: number;
 };
 
-const KeyboardAwareScrollView = React.forwardRef<ScrollView, KeyboardAwareScrollViewProps>(
-  ({ bottomOffset, disableScrollOnKeyboardHide, enabled, extraKeyboardSpace, ...props }, ref) => (
-    <ScrollView ref={ref} {...props} />
-  ),
-);
+// `ComponentRef`, not `ScrollView` itself: React Native 0.88 types `ScrollView` as a function
+// component, so the class is no longer its instance type.
+const KeyboardAwareScrollView = React.forwardRef<
+  React.ComponentRef<typeof ScrollView>,
+  KeyboardAwareScrollViewProps
+>(({ bottomOffset, disableScrollOnKeyboardHide, enabled, extraKeyboardSpace, ...props }, ref) => (
+  <ScrollView ref={ref} {...props} />
+));
 KeyboardAwareScrollView.displayName = 'KeyboardAwareScrollView';
 
 // `automaticOffset` is keyboard-controller's: measure the view's position in

package/src/lib/origins.ts

@@ -13,3 +13,12 @@ export const ALIA_API_URL = process.env.EXPO_PUBLIC_ALIA_API_URL ?? 'https://api
  * with CORS open (`packages/app/worker/index.js`).
  */
 export const ALIA_WEB_ORIGIN = 'https://alia.onl';
+
+/**
+ * The one public page of a shared conversation, on Alia's web app, for every agent and every app
+ * that embeds one (`docs/agent-embedding.md` §6). An app shares this URL rather than a page of its
+ * own, so a link reads the same wherever it was minted.
+ */
+export function aliaSharedConversationUrl(token: string): string {
+  return `${ALIA_WEB_ORIGIN}/shared/${encodeURIComponent(token)}`;
+}

package/src/lib/text-input.ts

@@ -0,0 +1,9 @@
+import type { ComponentRef } from 'react';
+import type { TextInput } from 'react-native';
+
+/**
+ * What a ref to a `TextInput` holds. `ComponentRef`, not `TextInput` itself: React Native 0.88
+ * types `TextInput` as a function component, so the class is no longer its instance type, and
+ * `focus()` is only on the instance.
+ */
+export type TextInputHandle = ComponentRef<typeof TextInput>;

package/src/runtime/config.tsx

@@ -72,6 +72,12 @@ export interface AliaRuntimeHost {
   turnRequest?: () => AliaTurnRequest;
   /** A turn is about to be sent from the composer or a retry. */
   onTurnStart?: () => void;
+  /**
+   * A turn this runtime sent has stopped streaming: it finished, was stopped, or failed. Called
+   * exactly once per turn, after the stream has settled, and only while the conversation that
+   * sent it is still mounted: a surface that left mid-turn is never called back for it.
+   */
+  onTurnEnd?: () => void;
   /** Real answer text just arrived (throttled): a haptic tick. */
   onOutput?: () => void;
   /** The stream's usage frame: credits left and the spending warning. */
@@ -134,6 +140,14 @@ export interface AliaRuntimeConfig {
   /** How read-aloud, dictation and calls speak; omitted, the server's and the platform's defaults. */
   speech: SpeechPreferences;
   host: AliaRuntimeHost;
+  /**
+   * The Oxy app the chat is embedded in, by its slug (`^[a-z][a-z0-9-]{0,31}$`): `homiio`,
+   * `mercaria`. A conversation it starts is labelled with it, and its host tools are this app's.
+   * Omitted, the chat is Alia's own and its conversations carry no app (`docs/agent-embedding.md`
+   * §6). A label for listing, never authority: which app a request comes from is proven by the
+   * app assertion, not by this.
+   */
+  app: string | undefined;
 }
 
 export interface AliaRuntimeProviderProps extends Partial<Omit<AliaRuntimeConfig, 'host'>> {
@@ -147,6 +161,7 @@ const DEFAULT_CONFIG: AliaRuntimeConfig = {
   streamFetch: undefined,
   speech: {},
   host: {},
+  app: undefined,
 };
 
 const AliaRuntimeContext = createContext<AliaRuntimeConfig>(DEFAULT_CONFIG);
@@ -164,6 +179,7 @@ export function AliaRuntimeProvider({
   streamFetch,
   speech,
   host,
+  app,
   children,
 }: AliaRuntimeProviderProps) {
   const parent = useContext(AliaRuntimeContext);
@@ -175,8 +191,9 @@ export function AliaRuntimeProvider({
       streamFetch: streamFetch ?? parent.streamFetch,
       speech: speech ?? parent.speech,
       host: host === undefined ? parent.host : { ...parent.host, ...host },
+      app: app ?? parent.app,
     };
-  }, [apiUrl, offline, streamFetch, speech, host, parent]);
+  }, [apiUrl, offline, streamFetch, speech, host, app, parent]);
   return <AliaRuntimeContext.Provider value={value}>{children}</AliaRuntimeContext.Provider>;
 }
 

package/src/runtime/conversations.ts

@@ -13,7 +13,7 @@ import { type AliaApi, useAliaApi } from './api';
 import { type OfflineConversationStore, useAliaRuntime } from './config';
 import { errorMessage as getErrorMessage, errorStatus } from './error-utils';
 import { normalizeConversationMessages } from './message-history';
-import { aliaQueryKeys } from './query-keys';
+import { aliaQueryKeys, type ConversationsFilter } from './query-keys';
 import { API_ROUTES } from './routes';
 import { createRandomUuid } from './random-uuid';
 import type { Conversation, ConversationsInfiniteData, ConversationsPage, Message } from './types';
@@ -96,23 +96,25 @@ export interface ConversationsClient {
   offline: OfflineConversations;
   /** Read at call time: the title of a chat created while signed out. */
   newChatTitle: string;
+  /** The chat's app, which labels a conversation it creates (`AliaRuntimeConfig.app`). */
+  app: string | undefined;
 }
 
 /** The runtime's conversation client for the nearest provider. */
 export function useConversationsClient(): ConversationsClient {
   const api = useAliaApi();
-  const { offline } = useAliaRuntime();
+  const { offline, app } = useAliaRuntime();
   const { newChat } = useLabels();
   return useMemo(
-    () => ({ api, offline: new OfflineConversations(offline), newChatTitle: newChat }),
-    [api, offline, newChat],
+    () => ({ api, offline: new OfflineConversations(offline), newChatTitle: newChat, app }),
+    [api, offline, newChat, app],
   );
 }
 
 async function fetchConversationsPage(
   client: ConversationsClient,
   pageParam: string | undefined,
-  agentId: string | undefined,
+  { agentId, app }: ConversationsFilter,
 ): Promise<ConversationsPage> {
   try {
     const { data } = await client.api.get<{
@@ -124,6 +126,7 @@ async function fetchConversationsPage(
         limit: PAGE_SIZE,
         ...(pageParam ? { cursor: pageParam } : {}),
         ...(agentId === undefined ? {} : { agentId }),
+        ...(app === undefined ? {} : { app }),
       },
     });
     return {
@@ -137,9 +140,9 @@ async function fetchConversationsPage(
       hasMore: data.hasMore,
     };
   } catch (error: unknown) {
-    // If unauthorized, fall back to the offline copy (Alia's own conversations: an agent's are
-    // never kept offline).
-    if (errorStatus(error) === 401 && agentId === undefined) {
+    // If unauthorized, fall back to the offline copy (Alia's own conversations: an agent's and an
+    // app's are never kept offline).
+    if (errorStatus(error) === 401 && agentId === undefined && app === undefined) {
       const conversations = (await client.offline.read()).map((c) => ({
         ...c,
         messages: [] as Message[],
@@ -158,19 +161,21 @@ async function fetchConversationsPage(
 
 /**
  * The person's conversations, newest first, a page at a time. The sidebar and the sheet read this.
- * Given `agentId`, only the conversations with that agent (`GET /v1/conversations?agentId=`).
+ * Given `agentId`, only the conversations with that agent; given `app`, only the ones started in
+ * that app — an embedding app's own list (`GET /v1/conversations?agentId=&app=`). Neither is
+ * implied by the chat's `app`: the app that wants only its own says so here.
  */
-export function useConversations({ agentId }: { agentId?: string } = {}) {
+export function useConversations({ agentId, app }: ConversationsFilter = {}) {
   const { isAuthenticated } = useOxy();
   const client = useConversationsClient();
 
   return useInfiniteQuery({
     queryKey:
-      agentId === undefined
+      agentId === undefined && app === undefined
         ? aliaQueryKeys.conversations.all
-        : aliaQueryKeys.conversations.withAgent(agentId),
+        : aliaQueryKeys.conversations.filtered({ agentId, app }),
     queryFn: ({ pageParam }: { pageParam: string | undefined }) =>
-      fetchConversationsPage(client, pageParam, agentId),
+      fetchConversationsPage(client, pageParam, { agentId, app }),
     initialPageParam: undefined as string | undefined,
     getNextPageParam: (lastPage) => (lastPage.hasMore ? lastPage.nextCursor : undefined),
     staleTime: FIVE_MINUTES,
@@ -309,12 +314,14 @@ export function useSaveConversation() {
           conversationId: id,
           messages,
           ...(title && { title }),
+          ...(client.app === undefined ? {} : { app: client.app }),
         });
         return {
           id: data.id,
           title: data.title,
           lastMessage: data.lastMessage,
           source: data.source,
+          app: data.app,
           createdAt: new Date(data.createdAt),
           updatedAt: new Date(data.updatedAt),
           messages,
@@ -515,6 +522,7 @@ export function useCreateConversation() {
       try {
         const { data } = await client.api.post<ApiConversation>(API_ROUTES.conversations.create, {
           ...(params?.agentId && { agentId: params.agentId }),
+          ...(client.app === undefined ? {} : { app: client.app }),
         });
         return {
           id: data.id,
@@ -522,6 +530,7 @@ export function useCreateConversation() {
           lastMessage: undefined,
           source: data.source,
           agentId: data.agentId,
+          app: data.app,
           createdAt: new Date(data.createdAt),
           updatedAt: new Date(data.updatedAt),
           messages: [],

package/src/runtime/host-tools.ts

@@ -35,10 +35,12 @@ export interface AliaHostOutcome {
   detail?: string;
 }
 
-/** The host tools a surface declares (`hostTools` on the chat). */
+/**
+ * The host tools a surface declares (`hostTools` on the chat). They are the tools of the chat's
+ * `app`, which a surface with host tools must name: the app is said once, on the chat, and is what
+ * the model sees them under (`host_<app>__<name>`).
+ */
 export interface AliaHostTools {
-  /** The app's slug, `^[a-z][a-z0-9-]{0,31}$`. */
-  app: string;
   /**
    * At most 16. What the host's screen shows now is not part of the declaration: it is the chat's
    * `clientContext`, built by the host per turn.
@@ -80,14 +82,18 @@ export class HostOutcomeQueue {
   private ready: HostOutcomeRecord[] = [];
 
   /**
-   * Perform `action` with `tools`, once. Resolves when its outcome is queued; `false` when the
-   * action had already been performed and nothing was done.
+   * Perform `action` with the tools `app` declared, once. Resolves when its outcome is queued;
+   * `false` when the action had already been performed and nothing was done.
    */
-  async dispatch(action: HostAction, tools: AliaHostTools | undefined): Promise<boolean> {
+  async dispatch(
+    action: HostAction,
+    tools: AliaHostTools | undefined,
+    app: string | undefined,
+  ): Promise<boolean> {
     if (this.performed.has(action.toolCallId)) return false;
     this.performed.add(action.toolCallId);
     let outcome: AliaHostOutcome;
-    if (tools === undefined || action.app !== tools.app) {
+    if (tools === undefined || app === undefined || action.app !== app) {
       outcome = { outcome: 'rejected', detail: 'This app did not declare that tool.' };
     } else if (!tools.definitions.some((tool) => tool.name === action.name)) {
       outcome = { outcome: 'rejected', detail: `Unknown tool "${action.name}".` };
@@ -121,16 +127,23 @@ export class HostOutcomeQueue {
   }
 }
 
-/** The `host` member of a request, or nothing for a surface without host tools. */
+/**
+ * The `host` member of a request: the chat's `app` and its host tools (none is an empty list),
+ * or nothing for a chat that names no app — Alia's own.
+ *
+ * The app is also what labels a conversation this turn starts (`docs/agent-embedding.md` §6), so
+ * a surface without host tools still sends it.
+ */
 export function hostRequest(
+  app: string | undefined,
   tools: AliaHostTools | undefined,
   outcomes: readonly HostOutcomeRecord[],
 ): HostRequest | undefined {
-  if (tools === undefined) return undefined;
+  if (app === undefined) return undefined;
   return {
-    app: tools.app,
+    app,
     version: 1,
-    tools: tools.definitions.map(({ name, description, inputSchema }) => ({
+    tools: (tools?.definitions ?? []).map(({ name, description, inputSchema }) => ({
       name,
       description,
       inputSchema,
@@ -138,3 +151,6 @@ export function hostRequest(
     ...(outcomes.length === 0 ? {} : { outcomes: [...outcomes] }),
   };
 }
+
+/** The slug an app names itself by, here and on the server: `^[a-z][a-z0-9-]{0,31}$`. */
+export const APP_SLUG = /^[a-z][a-z0-9-]{0,31}$/;

package/src/runtime/index.ts

@@ -51,6 +51,7 @@ export {
   useShareConversation,
   useSharedConversation,
 } from './sharing';
+export { aliaSharedConversationUrl } from '../lib/origins';
 export type {
   AliaConversationShare,
   AliaSharedAgent,
@@ -60,7 +61,7 @@ export type {
 export { uploadToOxyFiles, useDocumentUpload } from './oxy-files';
 export type { OxyFilesClient } from './oxy-files';
 export type { AliaApi, AliaApiRequest, AliaApiResult } from './api';
-export { aliaQueryKeys } from './query-keys';
+export { aliaQueryKeys, type ConversationsFilter } from './query-keys';
 export {
   ConversationNotFoundError,
   useClearConversation,

package/src/runtime/query-keys.ts

@@ -2,12 +2,24 @@
  * The React Query keys of the conversation runtime. The host's persister and its sidebar read
  * the same keys the hooks write, so a list shown anywhere is the list the chat updates.
  */
+/** What a conversation list may be narrowed to (`GET /v1/conversations?agentId=&app=`). */
+export interface ConversationsFilter {
+  /** Only the conversations with this agent. */
+  agentId?: string;
+  /** Only the conversations started in this app, by its slug (`docs/agent-embedding.md` §6). */
+  app?: string;
+}
+
 export const aliaQueryKeys = {
   conversations: {
     all: ['conversations'] as const,
     detail: (id: string) => ['conversation', id] as const,
-    /** The person's conversations with one agent: under `all`, so every write to the list reaches it. */
-    withAgent: (agentId: string) => ['conversations', { agentId }] as const,
+    /**
+     * The person's conversations narrowed to one agent, one app or both: under `all`, so every
+     * write to the list reaches it.
+     */
+    filtered: (filter: ConversationsFilter) =>
+      ['conversations', { agentId: filter.agentId, app: filter.app }] as const,
   },
   /** An agent the chat is opened on: its profile and the state of its feature gates. */
   agents: {

package/src/runtime/sharing.ts

@@ -1,5 +1,6 @@
 import { useMutation, useQuery } from '@tanstack/react-query';
 import { useMemo } from 'react';
+import { aliaSharedConversationUrl } from '../lib/origins';
 import { useAliaApi } from './api';
 import { useAliaRuntime } from './config';
 import { aliaQueryKeys } from './query-keys';
@@ -9,8 +10,10 @@ import type { Message } from './types';
 /** A conversation's read-only link (`POST /v1/conversations/:id/share`, `docs/agent-embedding.md` §6). */
 export interface AliaConversationShare {
   conversationId: string;
-  /** What `GET /v1/shared/:token` reads it by; the host builds its own URL around it. */
+  /** What `GET /v1/shared/:token` reads it by. */
   token: string;
+  /** The link to hand on: Alia's one shared-conversation page (`aliaSharedConversationUrl`). */
+  url: string;
   expiresAt: string;
 }
 
@@ -36,7 +39,12 @@ export function useShareConversation() {
       if (typeof data?.token !== 'string' || typeof data.expiresAt !== 'string') {
         throw new Error('The share link came back without a token.');
       }
-      return { conversationId, token: data.token, expiresAt: data.expiresAt };
+      return {
+        conversationId,
+        token: data.token,
+        url: aliaSharedConversationUrl(data.token),
+        expiresAt: data.expiresAt,
+      };
     },
   });
   const revoke = useMutation({

package/src/runtime/types.ts

@@ -93,6 +93,8 @@ export interface Conversation {
    * arrives carrying an explicit `null`.
    */
   agentId?: string | null;
+  /** The app the conversation started in, by its slug, or `null` for Alia's own surfaces. */
+  app?: string | null;
   createdAt: Date;
   updatedAt: Date;
   messages: Message[];

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

@@ -153,10 +153,12 @@ export function useConversationStream({
   clientContext,
   hostTools,
 }: UseConversationStreamOptions = {}) {
-  const { apiUrl, streamFetch, host } = useAliaRuntime();
+  const { apiUrl, streamFetch, host, app } = useAliaRuntime();
   /** Read at send time and when an action arrives: the host's declaration may change between turns. */
   const hostToolsRef = useRef(hostTools);
   hostToolsRef.current = hostTools;
+  const appRef = useRef(app);
+  appRef.current = app;
   /** This conversation's host actions: performed once, their outcomes held until a request carries them. */
   const hostOutcomesRef = useRef(new HostOutcomeQueue());
   const labels = useLabels();
@@ -260,9 +262,14 @@ export function useConversationStream({
     }, 50);
   }, [flushPendingUpdates]);
 
-  // Cleanup: flush remaining content and clear timer on unmount
+  /** Whether this thread is on screen: a turn that outlives it ends without `onTurnEnd`. */
+  const mountedRef = useRef(false);
+
+  // Mounted, a turn that ends is announced (`onTurnEnd`); unmounting flushes and clears the timer.
   useEffect(() => {
+    mountedRef.current = true;
     return () => {
+      mountedRef.current = false;
       flushPendingUpdates();
       if (flushTimerRef.current) {
         clearTimeout(flushTimerRef.current);
@@ -613,7 +620,7 @@ export function useConversationStream({
 
         // The host's tools, and the outcomes of the actions it performed since the last request.
         const outcomes = hostOutcomesRef.current.pending();
-        const hostMember = hostRequest(hostToolsRef.current, outcomes);
+        const hostMember = hostRequest(appRef.current, hostToolsRef.current, outcomes);
 
         // Authentication, the preflight refresh and the single 401 replay belong
         // to the linked Oxy client; this layer never reads or writes a bearer.
@@ -885,7 +892,11 @@ export function useConversationStream({
                     // the next request. The stream does not wait for it.
                     const action = parseHostAction(parsed);
                     if (action !== null) {
-                      void hostOutcomesRef.current.dispatch(action, hostToolsRef.current);
+                      void hostOutcomesRef.current.dispatch(
+                        action,
+                        hostToolsRef.current,
+                        appRef.current,
+                      );
                     }
                     continue;
                   }
@@ -1344,6 +1355,8 @@ export function useConversationStream({
          * 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?.();
       }
     },
     [