@alia.onl/sdk 22.1.2 → 22.2.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @alia.onl/sdk
 
+## 22.2.0
+
+- **Awaited host tools.** `AliaHostToolDefinition.awaitsResult: true` declares a tool whose
+  result the model reads in the same turn ("this tab's text"). When the model calls it, the
+  runtime runs the host's `execute` once and POSTs `{ toolCallId, outcome, detail?, result? }` at
+  once to `/v1/chat/turns/:turnId/host-results` through the authenticated API (with the app
+  assertion), instead of queueing the outcome for the next request. `AliaHostOutcome.result`
+  carries a string or JSON value of at most `HOST_RESULT_MAX_CHARS` (100,000) characters as JSON;
+  a larger one is answered as `failed`. A failed POST is reported to `AliaHostTools.onUndelivered`
+  and never retried. `parseHostAction` keeps `awaitsResult` and `turnId`.
+- **Personalization off for one turn.** `AliaTurnRequest.personalization: false` (read at send
+  time from `host.turnRequest()`) sends `personalization: false`: Alia reads no memory and offers
+  no memory tools for that turn. Nothing is sent otherwise.
+- `awaitsResult` is sent only for a tool that declares it, so existing hosts send the same bytes.
+  A host that declares one needs the Alia API receiver for awaited host tools deployed first
+  (`docs/agent-embedding.md` §2); an older API refuses the field with `invalid_host`.
+
 ## 22.1.2
 
 - **Every entry type-checks under `noUncheckedIndexedAccess`.** The SDK ships source, so a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alia.onl/sdk",
-  "version": "22.1.2",
+  "version": "22.2.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",

package/src/runtime/config.tsx

@@ -39,6 +39,11 @@ export interface AliaTurnRequest {
   /** Only `false` is sent: `true` is the server's default. */
   webSearch?: boolean;
   deepResearch?: boolean;
+  /**
+   * `false` turns personalization off for this turn: Alia reads no memory of the person, recalls
+   * nothing and offers no memory tools. The conversation is stored as usual. Only `false` is sent.
+   */
+  personalization?: false;
 }
 
 /** Why the thread asks its host to show the thought panel. */

package/src/runtime/host-tools.ts

@@ -7,10 +7,15 @@
  * the outcome with its NEXT request, where it becomes that call's result. A host tool is never
  * authority over data: it moves the host's own screen.
  *
- * Two rules hold here, in a queue that knows nothing of React:
+ * A tool declared with `awaitsResult: true` is read in the SAME turn instead ("this tab's text",
+ * "the open tabs"): the server waits, and this client answers it at once on the turn's
+ * `host-results` route with the outcome and the `result` its `execute` returned.
+ *
+ * Three rules hold here, in a queue that knows nothing of React:
  *  - an action is performed at most once, whatever the stream repeats;
  *  - an outcome stays queued until a request carrying it has been accepted, so a turn that ends
- *    before its outcomes are sent hands them to the next one.
+ *    before its outcomes are sent hands them to the next one;
+ *  - an awaited action's answer is sent once, never queued and never retried.
  */
 
 import type { HostAction } from './stream-events';
@@ -23,6 +28,11 @@ export interface AliaHostToolDefinition {
   description: string;
   /** A JSON Schema with an object root. */
   inputSchema: Record<string, unknown>;
+  /**
+   * The model reads this tool's result in the same turn: `execute`'s `result` goes back to it at
+   * once. Needs an Alia API with awaited host tools (`docs/agent-embedding.md` §2).
+   */
+  awaitsResult?: boolean;
 }
 
 export const HOST_OUTCOMES = ['applied', 'inline', 'rejected', 'stale', 'failed'] as const;
@@ -33,6 +43,11 @@ export interface AliaHostOutcome {
   outcome: AliaHostOutcomeKind;
   /** At most 500 characters; longer is cut. */
   detail?: string;
+  /**
+   * What an awaited tool read, for the model: a string or any JSON value, at most
+   * {@link HOST_RESULT_MAX_CHARS} characters as JSON. Ignored for a tool that does not await.
+   */
+  result?: unknown;
 }
 
 /**
@@ -48,6 +63,11 @@ export interface AliaHostTools {
   definitions: readonly AliaHostToolDefinition[];
   /** Perform `action` and say what came of it. Called once per action. */
   execute: (action: HostAction) => Promise<AliaHostOutcome>;
+  /**
+   * An awaited action's answer could not be delivered (the request failed). It is not retried:
+   * the model reads that the app did not answer in time.
+   */
+  onUndelivered?: (action: HostAction, error: unknown) => void;
 }
 
 /** An outcome as a request carries it. */
@@ -57,6 +77,11 @@ export interface HostOutcomeRecord {
   detail?: string;
 }
 
+/** An awaited action's answer, as `POST /v1/chat/turns/:turnId/host-results` carries it. */
+export interface HostResultRecord extends HostOutcomeRecord {
+  result?: unknown;
+}
+
 /** The request's `host` member. */
 export interface HostRequest {
   app: string;
@@ -68,6 +93,21 @@ export interface HostRequest {
 
 const DETAIL_LIMIT = 500;
 
+/** The server's bound on an awaited action's `result`, as JSON. */
+export const HOST_RESULT_MAX_CHARS = 100_000;
+
+function resultOf(result: unknown): { result?: unknown } | 'too_large' {
+  if (result === undefined || result === null) return {};
+  let text: string | undefined;
+  try {
+    text = JSON.stringify(result);
+  } catch {
+    return {};
+  }
+  if (text === undefined) return {};
+  return text.length > HOST_RESULT_MAX_CHARS ? 'too_large' : { result };
+}
+
 function record(toolCallId: string, outcome: AliaHostOutcome | undefined): HostOutcomeRecord {
   const kind = HOST_OUTCOMES.includes(outcome?.outcome as AliaHostOutcomeKind)
     ? (outcome?.outcome as AliaHostOutcomeKind)
@@ -92,25 +132,41 @@ export class HostOutcomeQueue {
   ): Promise<boolean> {
     if (this.performed.has(action.toolCallId)) return false;
     this.performed.add(action.toolCallId);
-    let outcome: AliaHostOutcome;
-    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}".` };
-    } else {
-      try {
-        outcome = await tools.execute(action);
-      } catch (error) {
-        outcome = {
-          outcome: 'failed',
-          detail: error instanceof Error ? error.message : 'The app could not do it.',
-        };
-      }
-    }
+    const outcome = await perform(action, tools, app);
     this.ready.push(record(action.toolCallId, outcome));
     return true;
   }
 
+  /**
+   * Perform an awaited `action` once and `send` its answer at once, with its result. A failed send
+   * is reported to the host's `onUndelivered` and not retried. `false` when the action had already
+   * been performed.
+   */
+  async answer(
+    action: HostAction,
+    tools: AliaHostTools | undefined,
+    app: string | undefined,
+    send: (answer: HostResultRecord) => Promise<unknown>,
+  ): Promise<boolean> {
+    if (this.performed.has(action.toolCallId)) return false;
+    this.performed.add(action.toolCallId);
+    const outcome = await perform(action, tools, app);
+    const result = resultOf((outcome as AliaHostOutcome | undefined)?.result);
+    const answer: HostResultRecord =
+      result === 'too_large'
+        ? record(action.toolCallId, {
+            outcome: 'failed',
+            detail: 'The result was too large to send.',
+          })
+        : { ...record(action.toolCallId, outcome), ...result };
+    try {
+      await send(answer);
+    } catch (error) {
+      tools?.onUndelivered?.(action, error);
+    }
+    return true;
+  }
+
   /** The outcomes ready to send, oldest first. */
   pending(): HostOutcomeRecord[] {
     return [...this.ready];
@@ -127,6 +183,27 @@ export class HostOutcomeQueue {
   }
 }
 
+async function perform(
+  action: HostAction,
+  tools: AliaHostTools | undefined,
+  app: string | undefined,
+): Promise<AliaHostOutcome> {
+  if (tools === undefined || app === undefined || action.app !== app) {
+    return { outcome: 'rejected', detail: 'This app did not declare that tool.' };
+  }
+  if (!tools.definitions.some((tool) => tool.name === action.name)) {
+    return { outcome: 'rejected', detail: `Unknown tool "${action.name}".` };
+  }
+  try {
+    return await tools.execute(action);
+  } catch (error) {
+    return {
+      outcome: 'failed',
+      detail: error instanceof Error ? error.message : 'The app could not do it.',
+    };
+  }
+}
+
 /**
  * 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.
@@ -143,10 +220,12 @@ export function hostRequest(
   return {
     app,
     version: 1,
-    tools: (tools?.definitions ?? []).map(({ name, description, inputSchema }) => ({
+    tools: (tools?.definitions ?? []).map(({ name, description, inputSchema, awaitsResult }) => ({
       name,
       description,
       inputSchema,
+      // Only when declared: an API before awaited host tools refuses the unknown field.
+      ...(awaitsResult === true ? { awaitsResult: true as const } : {}),
     })),
     ...(outcomes.length === 0 ? {} : { outcomes: [...outcomes] }),
   };

package/src/runtime/index.ts

@@ -33,13 +33,14 @@ export {
   useAgentProfile,
 } from './agents';
 export type { AliaAgentFeature, AliaAgentProfile, AliaAgentStarter, FeatureOffer } from './agents';
-export { HOST_OUTCOMES, HostOutcomeQueue, hostRequest } from './host-tools';
+export { HOST_OUTCOMES, HOST_RESULT_MAX_CHARS, HostOutcomeQueue, hostRequest } from './host-tools';
 export type {
   AliaHostAction,
   AliaHostOutcome,
   AliaHostOutcomeKind,
   AliaHostToolDefinition,
   AliaHostTools,
+  HostResultRecord as AliaHostResultRecord,
 } from './host-tools';
 export { FEATURE_ENTITLEMENT_REQUIRED, parseConsultEvent, parseHostAction } from './stream-events';
 export type { ConsultAgent, ConsultEvent } from './stream-events';

package/src/runtime/routes.ts

@@ -11,6 +11,8 @@
  */
 export const API_ROUTES = {
   chat: '/v1/chat/completions',
+  /** The answer to an awaited host action, read by the turn that is waiting for it. */
+  hostResults: (turnId: string) => `/v1/chat/turns/${encodeURIComponent(turnId)}/host-results`,
   conversations: {
     list: '/v1/conversations',
     save: '/v1/conversations',

package/src/runtime/stream-events.ts

@@ -125,15 +125,29 @@ export interface HostAction {
   app: string;
   name: string;
   input: Record<string, unknown>;
+  /**
+   * The model is waiting for this action's result within the same turn: its outcome is answered
+   * at once on the turn's `host-results` route, never with the next request.
+   */
+  awaitsResult?: true;
+  /** The turn that waits, present exactly when `awaitsResult` is. */
+  turnId?: string;
 }
 
 /** The host action an `alia.host_action` frame carries, or `null` when it is not well-formed. */
 export function parseHostAction(data: unknown): HostAction | null {
   if (!isObject(data) || data.eventVersion !== 1) return null;
-  const { toolCallId, app, name, input } = data;
+  const { toolCallId, app, name, input, awaitsResult, turnId } = data;
   if (!isText(toolCallId) || !isText(app) || !isText(name)) return null;
   if (input !== undefined && !isObject(input)) return null;
-  return { toolCallId, app, name, input: (input as Record<string, unknown> | undefined) ?? {} };
+  if (awaitsResult !== undefined && (awaitsResult !== true || !isText(turnId))) return null;
+  return {
+    toolCallId,
+    app,
+    name,
+    input: (input as Record<string, unknown> | undefined) ?? {},
+    ...(awaitsResult === true ? { awaitsResult: true as const, turnId: turnId as string } : {}),
+  };
 }
 
 /** The error code that ends a turn an agent's feature gate refused (§5). */

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 { useAliaApi } from './api';
 import { useAppAssertionHeaders } from './app-assertion';
 import { type AliaArtifact, useAliaRuntime } from './config';
 import {
@@ -162,6 +163,8 @@ export function useConversationStream({
   hostTools,
 }: UseConversationStreamOptions = {}) {
   const { apiUrl, streamFetch, host, app } = useAliaRuntime();
+  /** Where an awaited host action's answer goes: the same account and app assertion as the turn. */
+  const api = useAliaApi();
   /** Read at send time and when an action arrives: the host's declaration may change between turns. */
   const hostToolsRef = useRef(hostTools);
   hostToolsRef.current = hostTools;
@@ -658,7 +661,11 @@ export function useConversationStream({
          * when the callback was built would send the state the composer had
          * before the person touched it.
          */
-        const { deepResearch: deepResearchMode, webSearch } = host.turnRequest?.() ?? {};
+        const {
+          deepResearch: deepResearchMode,
+          webSearch,
+          personalization,
+        } = host.turnRequest?.() ?? {};
 
         // The host's tools, and the outcomes of the actions it performed since the last request.
         const outcomes = hostOutcomesRef.current.pending();
@@ -688,6 +695,8 @@ export function useConversationStream({
             // Only sent when OFF. `true` is the server's default and every
             // request has behaved that way, so sending it would be noise.
             ...(webSearch === false && { webSearch: false }),
+            // Only sent when OFF, like web search: absent is the server's default.
+            ...(personalization === false && { personalization: false }),
             // The power level (or a device model). Oxy picks the model of that
             // level; the client never names a hosted model.
             ...(model && { model }),
@@ -939,13 +948,28 @@ export function useConversationStream({
                     // Performed here, by the client that declared it, once; its outcome rides
                     // the next request. The stream does not wait for it.
                     const action = parseHostAction(parsed);
-                    if (action !== null) {
-                      void hostOutcomesRef.current.dispatch(
+                    if (action === null) continue;
+                    if (action.awaitsResult && action.turnId !== undefined) {
+                      // The turn waits for this one: its answer goes back at once, through the
+                      // same authenticated API (and app assertion) the turn's account uses.
+                      const turnSignal = controller.signal;
+                      const route = API_ROUTES.hostResults(action.turnId);
+                      void hostOutcomesRef.current.answer(
                         action,
                         hostToolsRef.current,
                         appRef.current,
+                        async (answer) => {
+                          if (turnSignal.aborted) throw new Error('The turn ended');
+                          await api.post(route, answer, { signal: turnSignal });
+                        },
                       );
+                      continue;
                     }
+                    void hostOutcomesRef.current.dispatch(
+                      action,
+                      hostToolsRef.current,
+                      appRef.current,
+                    );
                     continue;
                   }
                   case 'alia.title': {
@@ -1417,6 +1441,7 @@ export function useConversationStream({
       }
     },
     [
+      api,
       apiUrl,
       streamFetch,
       host,