@alia.onl/sdk 10.0.3 → 10.1.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @alia.onl/sdk
 
+## 10.1.0
+
+A failed turn is a typed error. Alia now answers an inference failure before any
+output with its error envelope (an in-stream error frame, or an HTTP 503/500)
+instead of an "all models are busy" answer. `AliaChatStreamError` (now exported,
+with `AliaChatFailure`) carries `status`, `code`, `retryable`, `retryAfter` and
+`reference` from either. The stream reader also accepts `alia.context` and
+`alia.agent_turn`, which it used to reject as unknown events, ending a streaming
+turn before its answer or its error could be read.
+
+## 10.0.4
+
+Admit `@oxy.so/services` 11 and `@oxy.so/core` 4 alongside the earlier majors.
+Services 11 / core 4 move Android identity to Commons over signature-protected
+IPC (OxyHQ/oxy#1388); the SDK imports only `useOxy` from
+`@oxy.so/services/ui/client`, unchanged, and nothing from core. No code changed.
+
 ## 10.0.3
 
 Admit `@oxy.so/services` 10 alongside 8 and 9. The SDK uses the unchanged

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "10.0.3",
-  "description": "Alia AI chat SDK — reusable chat UI, voice, and streaming components for Oxy apps",
+  "version": "10.1.0",
+  "description": "Alia AI chat SDK \u2014 reusable chat UI, voice, and streaming components for Oxy apps",
   "main": "src/index.ts",
   "react-native": "src/index.ts",
   "source": "src/index.ts",
@@ -42,8 +42,8 @@
   "peerDependencies": {
     "react": "^19.2.3",
     "react-native": "^0.86.0",
-    "@oxy.so/core": "^3.0.0",
-    "@oxy.so/services": "^8.0.0 || ^9.0.0 || ^10.0.0",
+    "@oxy.so/core": "^3.0.0 || ^4.0.0",
+    "@oxy.so/services": "^8.0.0 || ^9.0.0 || ^10.0.0 || ^11.0.0",
     "@react-native-async-storage/async-storage": "^2.2.0",
     "expo-blur": "^57.0.0",
     "react-native-reanimated": "^4.5.0",

package/src/index.ts

@@ -22,6 +22,8 @@ export { PlanPreviewCard } from './components/PlanPreviewCard';
 // ── Chat hook ──
 export { useAliaChat } from './hooks/useAliaChat';
 export type { UseAliaChatOptions, UseAliaChatReturn } from './hooks/useAliaChat';
+export { AliaChatStreamError } from './lib/chat-stream';
+export type { AliaChatFailure } from './lib/chat-stream';
 
 // ── Text-to-speech / speech-to-text (no livekit) ──
 export { useTTS } from './hooks/useTTS';

package/src/lib/chat-stream.ts

@@ -38,13 +38,61 @@ export interface AliaChatStreamResult {
   readonly finishReason: string;
 }
 
+/**
+ * What Alia said about a failed turn, when it said anything.
+ *
+ * A turn that fails — before any output or part-way — ends with Alia's
+ * OpenAI-shaped error envelope: an in-stream `{"error": …}` frame, or an HTTP
+ * error status with the same body when nothing was sent yet. `code` is Alia's
+ * stable error code, `retryable` whether sending the same turn again can help,
+ * `retryAfter` the seconds to wait first, and `reference` the run id support
+ * traces it by. None of it names the serving operator.
+ */
+export interface AliaChatFailure {
+  readonly status?: number;
+  readonly code?: string;
+  readonly retryable?: boolean;
+  readonly retryAfter?: number;
+  readonly reference?: string;
+}
+
 export class AliaChatStreamError extends Error {
-  constructor(message: string) {
+  readonly status?: number;
+  readonly code?: string;
+  readonly retryable?: boolean;
+  readonly retryAfter?: number;
+  readonly reference?: string;
+
+  constructor(message: string, failure: AliaChatFailure = {}) {
     super(message);
     this.name = 'AliaChatStreamError';
+    if (failure.status !== undefined) this.status = failure.status;
+    if (failure.code !== undefined) this.code = failure.code;
+    if (failure.retryable !== undefined) this.retryable = failure.retryable;
+    if (failure.retryAfter !== undefined) this.retryAfter = failure.retryAfter;
+    if (failure.reference !== undefined) this.reference = failure.reference;
   }
 }
 
+/**
+ * Read the failure fields off Alia's error envelope, leniently: a field of the
+ * wrong type is left out rather than failing the read of the rest.
+ */
+export function readAliaChatFailure(body: unknown): AliaChatFailure {
+  if (typeof body !== 'object' || body === null || Array.isArray(body)) return {};
+  const error = (body as JsonObject).error;
+  if (typeof error !== 'object' || error === null || Array.isArray(error)) return {};
+  const detail = error as JsonObject;
+  return {
+    ...(typeof detail.code === 'string' && detail.code !== '' ? { code: detail.code } : {}),
+    ...(typeof detail.retryable === 'boolean' ? { retryable: detail.retryable } : {}),
+    ...(typeof detail.retryAfter === 'number' && Number.isFinite(detail.retryAfter) && detail.retryAfter >= 0
+      ? { retryAfter: detail.retryAfter }
+      : {}),
+    ...(typeof detail.reference === 'string' && detail.reference !== '' ? { reference: detail.reference } : {}),
+  };
+}
+
 function abortError(): Error {
   const error = new Error('The Alia stream was aborted.');
   error.name = 'AbortError';
@@ -177,6 +225,16 @@ function validateIgnoredNamedEvent(eventName: string, payload: JsonObject): void
   requireEventVersion(payload, eventName);
 
   switch (eventName) {
+    // Sent on every streaming turn before inference starts (the context-window
+    // breakdown) and on a linked agent's turn. Neither is something this SDK
+    // shows, and an unknown one ended the turn before its answer — or its
+    // error — could be read.
+    case 'alia.context':
+      return;
+    case 'alia.agent_turn':
+      asString(payload.turnId, `${eventName} turnId`);
+      asString(payload.agentId, `${eventName} agentId`);
+      return;
     case 'alia.suggest_new_conversation':
       assertOnlyKeys(payload, ['eventVersion', 'reason'], eventName);
       asString(payload.reason, `${eventName} reason`);
@@ -318,7 +376,9 @@ function parseOpenAIFrame(payload: unknown): ParsedOpenAIFrame {
   if (body.error !== undefined) {
     const error = asObject(body.error, 'OpenAI stream error');
     asString(error.message, 'OpenAI stream error message');
-    fail('Alia ended the stream with an error.');
+    // The server's prose is not carried: the code and retryability are what a
+    // caller acts on, and the caller words it in its own language.
+    throw new AliaChatStreamError('Alia ended the stream with an error.', readAliaChatFailure(body));
   }
   assertOnlyKeys(
     body,

package/src/lib/chat-transport.ts

@@ -1,5 +1,7 @@
 import {
+  AliaChatStreamError,
   consumeAliaChatStream,
+  readAliaChatFailure,
   type AliaChatStreamEvent,
   type AliaChatStreamResult,
 } from './chat-stream';
@@ -59,9 +61,37 @@ export async function streamAliaChat(
   });
 
   if (!response.ok) {
-    await response.body?.cancel().catch(() => undefined);
-    throw new Error(`Alia request failed with status ${response.status}.`);
+    throw new AliaChatStreamError(`Alia request failed with status ${response.status}.`, {
+      ...(await readErrorEnvelope(response)),
+      status: response.status,
+    });
   }
 
   return consumeAliaChatStream(response, onEvent, signal);
 }
+
+/** Bodies larger than this are not an Alia error envelope and are not read. */
+const MAX_ERROR_BODY_BYTES = 16 * 1024;
+
+/**
+ * The code, retryability and reference of an HTTP refusal or failed turn.
+ *
+ * Without them a caller cannot tell "send it again" (a 503 for a turn that
+ * failed before any output) from "this will not work" (a 400), so the status
+ * is not enough. A body that is large, not JSON or not the envelope yields
+ * nothing, and the status alone still reaches the caller.
+ */
+async function readErrorEnvelope(response: Response) {
+  const length = Number(response.headers.get('content-length') ?? '0');
+  if (Number.isFinite(length) && length > MAX_ERROR_BODY_BYTES) {
+    await response.body?.cancel().catch(() => undefined);
+    return {};
+  }
+  try {
+    const text = await response.text();
+    if (text.length > MAX_ERROR_BODY_BYTES) return {};
+    return readAliaChatFailure(JSON.parse(text));
+  } catch {
+    return {};
+  }
+}