@alia.onl/sdk 19.0.0 → 19.1.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @alia.onl/sdk
 
+## 19.1.0
+
+An app's own agent may be confined to that app by Oxy (Alia ADR 0021, Oxy ADRs 0044 and 0045).
+
+### Added
+
+- **The SDK says which Oxy app it is in.** Every request that can open an agent — the REST API
+  (`useAliaApi`: profiles, features, conversations, threads), the chat stream and the voice call —
+  carries the host's Oxy-signed app assertion as `X-Oxy-App-Assertion` (on the voice socket, as
+  `appAssertion` in the `auth` frame, because a socket cannot carry a header). It is read at send
+  time from the host's `OxyProvider` (`useAppAssertion()` of `@oxy.so/services`), and nothing is
+  sent when the provider has none. Alia verifies it and opens an agent Oxy confines to an app only
+  inside that app; every other agent is unaffected. Dictation and read-aloud reach no agent and
+  send none.
+
+### Changed
+
+- **Peer `@oxy.so/services` >= 11.12.0**, the first release whose `OxyProvider` obtains the app
+  assertion.
+
 ## 19.0.0
 
 Every agent is the same agent, and any app embeds any of them (ADR 0020; the wire contract is

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "19.0.0",
+  "version": "19.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",
@@ -54,7 +54,7 @@
     "@expo/vector-icons": "^15.1.1",
     "@oxy.so/bloom": ">=10.9.0",
     "@oxy.so/core": ">=3.0.0",
-    "@oxy.so/services": ">=8.0.0",
+    "@oxy.so/services": ">=11.12.0",
     "@tanstack/react-query": "^5.101",
     "@react-native-async-storage/async-storage": "^2.2.0",
     "expo-blur": "^57.0.0",

package/src/hooks/useVoiceRoom.ts

@@ -25,6 +25,7 @@ import { VoiceCall, type VoiceCallSnapshot, type VoiceSocketFactory } from '../l
 import { VoiceLevelChannel, type VoiceLevelSource } from '../lib/voice-levels';
 import type { ProductVoice, VoiceCloseReason } from '../lib/voice-protocol';
 import { ALIA_API_URL } from '../lib/origins';
+import { useAppAssertionToken } from '../runtime/app-assertion';
 
 export interface UseVoiceRoomOptions {
   apiUrl?: string;
@@ -99,6 +100,7 @@ export function agentStateOf(state: VoiceCallState): AgentState {
 
 export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
   const { oxyServices } = useOxy();
+  const getAppAssertion = useAppAssertionToken();
   const levels = useMemo(() => new VoiceLevelChannel(), []);
   const [snapshot, setSnapshot] = useState<VoiceCallSnapshot>(IDLE);
   const callRef = useRef<VoiceCall | null>(null);
@@ -119,6 +121,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     const call = new VoiceCall({
       apiUrl: current.apiUrl || ALIA_API_URL,
       getToken,
+      getAppAssertion,
       conversationId: current.conversationId ?? newConversationId(),
       ...(current.agentId === undefined ? {} : { agentId: current.agentId }),
       voice: current.voicePreference ?? 'female',
@@ -134,7 +137,7 @@ export function useVoiceRoom(options: UseVoiceRoomOptions = {}) {
     });
     callRef.current = call;
     await call.start();
-  }, [getToken, levels]);
+  }, [getToken, getAppAssertion, levels]);
 
   /** Hang up and forget the call: the room is back to `disconnected`. */
   const disconnect = useCallback(() => {

package/src/lib/voice-call.ts

@@ -77,6 +77,11 @@ export interface VoiceCallOptions {
   readonly apiUrl: string;
   /** The person's Oxy session token, read at connect and every few minutes. */
   readonly getToken: () => string | null;
+  /**
+   * The host's Oxy app assertion, sent with the first `auth` of each socket so
+   * an agent Oxy confines to an app opens only there (ADR 0021). Absent: none.
+   */
+  readonly getAppAssertion?: () => Promise<string | null>;
   readonly conversationId: string;
   readonly agentId?: string;
   readonly voice: ProductVoice;
@@ -251,7 +256,23 @@ export class VoiceCall {
         return;
       }
       this.lastToken = token;
-      socket.send(JSON.stringify({ type: 'auth', token } satisfies VoiceClientEvent));
+      const getAppAssertion = this.options.getAppAssertion;
+      if (getAppAssertion === undefined) {
+        socket.send(JSON.stringify({ type: 'auth', token } satisfies VoiceClientEvent));
+        return;
+      }
+      void getAppAssertion()
+        .catch(() => null)
+        .then((appAssertion) => {
+          if (this.socket !== socket || this.finished || socket.readyState !== OPEN) return;
+          socket.send(
+            JSON.stringify({
+              type: 'auth',
+              token,
+              ...(appAssertion ? { appAssertion } : {}),
+            } satisfies VoiceClientEvent),
+          );
+        });
     };
     socket.onmessage = (event) => {
       if (this.socket !== socket || this.finished) return;

package/src/lib/voice-protocol.ts

@@ -85,7 +85,8 @@ const CLOSE_REASONS: ReadonlySet<string> = new Set<VoiceCloseReason>([
 export type VoiceRole = 'user' | 'assistant';
 
 export type VoiceClientEvent =
-  | { type: 'auth'; token: string }
+  /** `appAssertion`: the host's Oxy app assertion (ADR 0021); a socket cannot carry the header. */
+  | { type: 'auth'; token: string; appAssertion?: string }
   | {
       type: 'session.start';
       protocol: number;

package/src/runtime/api.ts

@@ -1,5 +1,10 @@
 import { useOxy } from '@oxy.so/services/ui/client';
 import { useMemo } from 'react';
+import {
+  type AppAssertionHeaders,
+  NO_APP_ASSERTION,
+  useAppAssertionHeaders,
+} from './app-assertion';
 import { useAliaRuntime } from './config';
 
 /**
@@ -79,24 +84,33 @@ export interface LinkableOxy {
   };
 }
 
-/** Build the API over an Oxy client for `apiUrl`. Exposed for tests and for non-React callers. */
-export function createAliaApi(oxyServices: LinkableOxy, apiUrl: string): AliaApi {
+/**
+ * Build the API over an Oxy client for `apiUrl`. Exposed for tests and for non-React callers.
+ *
+ * @param appAssertionHeaders the host's `X-Oxy-App-Assertion` (`app-assertion.ts`), on every request
+ */
+export function createAliaApi(
+  oxyServices: LinkableOxy,
+  apiUrl: string,
+  appAssertionHeaders: AppAssertionHeaders = NO_APP_ASSERTION,
+): AliaApi {
   async function send<T>(
     method: 'GET' | 'POST' | 'PATCH' | 'DELETE',
     path: string,
     request: AliaApiRequest = {},
   ): Promise<AliaApiResult<T>> {
+    const assertion = await appAssertionHeaders();
     const linked = oxyServices.createLinkedClient({ baseURL: apiUrl });
     try {
+      const headers = {
+        ...assertion,
+        ...(request.body === undefined ? {} : { 'Content-Type': 'application/json' }),
+      };
       const response = await linked.client.requestAuthenticatedResponse({
         method,
         url: withParams(path, request.params),
-        ...(request.body === undefined
-          ? {}
-          : {
-              body: JSON.stringify(request.body),
-              headers: { 'Content-Type': 'application/json' },
-            }),
+        ...(request.body === undefined ? {} : { body: JSON.stringify(request.body) }),
+        ...(Object.keys(headers).length === 0 ? {} : { headers }),
         ...(request.signal ? { signal: request.signal } : {}),
       });
       const data = await readBody(response);
@@ -119,5 +133,9 @@ export function createAliaApi(oxyServices: LinkableOxy, apiUrl: string): AliaApi
 export function useAliaApi(): AliaApi {
   const { oxyServices } = useOxy();
   const { apiUrl } = useAliaRuntime();
-  return useMemo(() => createAliaApi(oxyServices as LinkableOxy, apiUrl), [oxyServices, apiUrl]);
+  const appAssertionHeaders = useAppAssertionHeaders();
+  return useMemo(
+    () => createAliaApi(oxyServices as LinkableOxy, apiUrl, appAssertionHeaders),
+    [oxyServices, apiUrl, appAssertionHeaders],
+  );
 }

package/src/runtime/app-assertion.ts

@@ -0,0 +1,53 @@
+// `@oxy.so/services/ui`, not the root barrel (which ships the sign-in panels, `check:entries`):
+// `ui/client` does not export `useAppAssertion`.
+import { useAppAssertion } from '@oxy.so/services/ui';
+import { useMemo } from 'react';
+
+/**
+ * Which Oxy app this conversation is in, for Alia (Alia ADR 0021, Oxy ADR 0045).
+ *
+ * An Oxy app may confine its own agent to itself — Clarity's assistant opens
+ * only inside Clarity — and the official apps share one session that names no
+ * app, so Alia reads the app from the Oxy-signed assertion the host's
+ * `OxyProvider` obtains and keeps current. Every request the SDK makes to Alia
+ * carries it as `X-Oxy-App-Assertion` when there is one; without one (an app
+ * Oxy cannot recognise yet, a signed-out person) nothing is sent, and only a
+ * confined agent is affected.
+ *
+ * The SDK never builds, stores or inspects the assertion: it is the host's
+ * provider's, read at send time so it is never stale.
+ */
+export type AppAssertionHeaders = () => Promise<Record<string, string>>;
+
+/** No app assertion: what a caller outside a React tree, or a test, passes. */
+export const NO_APP_ASSERTION: AppAssertionHeaders = async () => ({});
+
+/** The host's app assertion as request headers, `{}` when it has none or cannot get one. */
+export function useAppAssertionHeaders(): AppAssertionHeaders {
+  const { getAppAssertionHeaders } = useAppAssertion();
+  return useMemo(
+    () => async () => {
+      try {
+        return await getAppAssertionHeaders();
+      } catch {
+        return {};
+      }
+    },
+    [getAppAssertionHeaders],
+  );
+}
+
+/** The host's app assertion itself, for the voice socket, which cannot carry a header. */
+export function useAppAssertionToken(): () => Promise<string | null> {
+  const { getAppAssertion } = useAppAssertion();
+  return useMemo(
+    () => async () => {
+      try {
+        return await getAppAssertion();
+      } catch {
+        return null;
+      }
+    },
+    [getAppAssertion],
+  );
+}

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

@@ -3,6 +3,7 @@ import { useOxy } from '@oxy.so/services/ui/client';
 import { useQueryClient } from '@tanstack/react-query';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { useLabels } from '../lib/labels';
+import { useAppAssertionHeaders } from './app-assertion';
 import { type AliaArtifact, useAliaRuntime } from './config';
 import { errorCode, errorMessage as getErrorMessage, errorName, errorStatus } from './error-utils';
 import { agentMessageId, buildOutboundMessages, isAgentMessageOf } from './message-history';
@@ -201,6 +202,7 @@ export function useConversationStream({
    */
   const turnOptionsRef = useRef(new Map<string, Pick<SendOptions, 'mcpServerId' | 'skillNames'>>());
   const { oxyServices, user } = useOxy();
+  const appAssertionHeaders = useAppAssertionHeaders();
   const queryClient = useQueryClient();
   const abortControllerRef = useRef<AbortController | null>(null);
 
@@ -615,11 +617,14 @@ 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 });
         const response = await linked.client.requestAuthenticatedResponse({
           method: 'POST',
           url: API_ROUTES.chat,
           headers: {
+            ...appAssertion,
             Accept: 'text/event-stream',
             'Content-Type': 'application/json',
             ...(deviceInfo === undefined ? {} : { 'X-Device-Info': JSON.stringify(deviceInfo) }),
@@ -1347,6 +1352,7 @@ export function useConversationStream({
       host,
       labels,
       oxyServices,
+      appAssertionHeaders,
       queryClient,
       conversationId,
       model,