@datalayer/agent-runtimes 1.5.50 → 1.5.52

package/lib/portable/hosts/agentClient.d.ts

@@ -36,6 +36,15 @@ export interface AgentClient<P> {
     startTurn(request: HostTurnRequest<P>): Promise<TurnStream>;
     stopTurn(sessionId: string, request: HostTurnRequest<P>): Promise<void>;
 }
+/**
+ * Maps a session to its host place again, once the place changed after the
+ * turn started (plans/DISCORD.md §3.2: Discord's answer thread exists only
+ * once the answer is shown, so the target is PUT again with it).
+ */
+export interface SessionBinder<P> {
+    /** Whether the session was mapped: `false` where nothing binds (development's credentials). */
+    bindSession(sessionId: string, request: HostTurnRequest<P>): Promise<boolean>;
+}
 /** Where a host asks from (`exchange.optional_request.place`): a channel, or a direct conversation. */
 export type Place = Readonly<{
     kind: 'channel' | 'direct';
@@ -154,13 +163,7 @@ export declare class HostStarters<K, P> implements StarterSource<K> {
 }
 /** Each AG-UI event of a run's `text/event-stream` body, as it arrives (`AgUiFrames`). */
 export declare function agUiEventsOf(body: ReadableStream<Uint8Array>): AsyncIterable<AgUiEvent>;
-/**
- * The host's Datalayer client: a turn is started or sent on the deployment's
- * session API (idempotent by the host's event id, SLACK §4.3, 2), its AG-UI
- * stream reduced to semantic events, and its session mapped to the host's
- * thread so that approvals and completions are delivered (§4.3, 3).
- */
-export declare class HttpAgentClient<P> implements AgentClient<P> {
+export declare class HttpAgentClient<P> implements AgentClient<P>, SessionBinder<P> {
     #private;
     readonly apiUrl: string;
     readonly credentials: HostCredentials<P>;
@@ -169,6 +172,11 @@ export declare class HttpAgentClient<P> implements AgentClient<P> {
     readonly hostKeyFor?: HostKeyLookup<P> | undefined;
     constructor(apiUrl: string, credentials: HostCredentials<P>, shape: HostShape<P>, fetchImplementation?: typeof fetch, hostKeyFor?: HostKeyLookup<P> | undefined);
     startTurn(request: HostTurnRequest<P>): Promise<TurnStream>;
+    /**
+     * The session mapped again with the shape's target for `request`, as the
+     * speaker (a fresh exchange): the binding is replaced, never doubled.
+     */
+    bindSession(sessionId: string, request: HostTurnRequest<P>): Promise<boolean>;
     stopTurn(sessionId: string, request: HostTurnRequest<P>): Promise<void>;
 }
 /**

package/lib/portable/hosts/agentClient.js

@@ -118,12 +118,16 @@ export class DevelopmentCredentials {
     async forTurn(request) {
         const response = await this.fetchImplementation(`${this.apiUrl}/api/ai-agents/v1/apps/deployments/${encodeURIComponent(request.applicationId)}`, { headers: { authorization: `Bearer ${this.token}` } });
         if (!response.ok) {
-            throw new Error(`Datalayer did not answer the deployment (${response.status}).`);
+            throw new HostRefusedError(response.status, 'Datalayer did not answer the deployment.', 'The deployment');
         }
         const body = (await response.json());
         const kept = body.deployment?.kept;
         if (!kept?.url || !kept.agent_id) {
-            throw new Error('The deployment is not kept always on: turn it on under Ship.');
+            // A refusal the host says to the person (409), with the deployment's
+            // own reason when it gives one (a daily credit limit spent, paused).
+            throw new HostRefusedError(409, kept?.why
+                ? `The deployment is not answering now: ${kept.why}`
+                : 'The deployment is not kept always on: turn it on under Ship.', 'The deployment');
         }
         return {
             accessToken: this.token,
@@ -203,6 +207,19 @@ export async function* agUiEventsOf(body) {
  * stream reduced to semantic events, and its session mapped to the host's
  * thread so that approvals and completions are delivered (§4.3, 3).
  */
+/** A refusal's `detail` when the answer is FastAPI's JSON, its status alone otherwise. */
+async function refusalDetailOf(response) {
+    const text = await response.text().catch(() => '');
+    try {
+        const detail = JSON.parse(text).detail;
+        if (typeof detail === 'string' && detail)
+            return detail;
+    }
+    catch {
+        // Not JSON: the status says it.
+    }
+    return `Datalayer refused the turn (${response.status}).`;
+}
 export class HttpAgentClient {
     apiUrl;
     credentials;
@@ -251,7 +268,10 @@ export class HttpAgentClient {
                 method: 'POST',
             });
         if (!response.ok || !response.body) {
-            throw new Error(`Datalayer refused the turn (${response.status}).`);
+            // The runtime's own reason, said to the person by the host: an
+            // application that signs its users and got no user token, a spent
+            // limit, a session of someone else.
+            throw new HostRefusedError(response.status, await refusalDetailOf(response), 'The turn');
         }
         const hostKey = host.bindable && this.hostKeyFor
             ? await this.hostKeyFor(request)
@@ -266,6 +286,20 @@ export class HttpAgentClient {
             updates: this.#updates(response.body, host, sessionId, run),
         };
     }
+    /**
+     * The session mapped again with the shape's target for `request`, as the
+     * speaker (a fresh exchange): the binding is replaced, never doubled.
+     */
+    async bindSession(sessionId, request) {
+        const host = await this.credentials.forTurn(request);
+        const hostKey = host.bindable && this.hostKeyFor
+            ? await this.hostKeyFor(request)
+            : undefined;
+        if (!hostKey)
+            return false;
+        await this.#bind(request, host, sessionId, hostKey);
+        return true;
+    }
     async stopTurn(sessionId, request) {
         const host = await this.credentials.forTurn(request);
         assertTrustedStreamUrl(this.apiUrl, host.sessionApiUrl);

package/lib/portable/hosts/index.d.ts

@@ -22,7 +22,7 @@ export * from '../semantic';
 export { askQuestionOf, semanticOf, turnOf, type TurnInfo, } from '../semanticOfAgUi';
 export * from './contracts';
 export { DatalayerHostClient, HostRefusedError, type BoundHost, type HostSelf, } from './client';
-export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, type AgentClient, type HostCredentials, type HostKeyLookup, type HostSession, type HostShape, type HostTurnRequest, type Place, type Starter, type StarterSource, type TurnProvenance, type TurnStream, } from './agentClient';
+export { agUiEventsOf, assertTrustedStreamUrl, DevelopmentCredentials, HostKeyCredentials, hostSessionOf, HostStarters, HttpAgentClient, InstallationCredentials, lastAnswer, type AgentClient, type HostCredentials, type HostKeyLookup, type HostSession, type HostShape, type HostTurnRequest, type Place, type SessionBinder, type Starter, type StarterSource, type TurnProvenance, type TurnStream, } from './agentClient';
 export { hostSessionUid } from './sessionUid';
 export { DATALAYER_ONLY, MAIL_WORDS, RENDERERS, renderApproval, type RenderedAction, type RenderedField, } from './approvalRenderers';
 export { DELIVERY_PATH, DELIVERY_ROUTE, DeliveryPoller, deliveryRoute, receiveDelivery, type BoundHostKey, type DeliveryClaimStore, type DeliveryJob, type DeliverySink, } from './deliveries';

package/lib/portable/hosts/queue.d.ts

@@ -40,6 +40,13 @@ export interface WorkQueue<T> {
 /** In-process development queue. A durable adapter is required in production. */
 export declare class MemoryWorkQueue<T> implements WorkQueue<T> {
     #private;
+    readonly onFailure: (error: unknown, item: T) => void;
+    /**
+     * A job that throws is reported here and dropped, and the next one is
+     * worked: one failure never stops the queue, nor the process with an
+     * unhandled rejection. The durable queue retries and dead-letters instead.
+     */
+    constructor(onFailure?: (error: unknown, item: T) => void);
     enqueue(item: T, idempotencyKey?: string): Promise<boolean>;
     ready(): Promise<boolean>;
     start(handler: (item: T) => Promise<void>): void;

package/lib/portable/hosts/queue.js

@@ -11,10 +11,21 @@ export function tablePrefixOf(prefix) {
 }
 /** In-process development queue. A durable adapter is required in production. */
 export class MemoryWorkQueue {
+    onFailure;
     #items = [];
     #keys = new Set();
     #handler;
     #running = false;
+    /**
+     * A job that throws is reported here and dropped, and the next one is
+     * worked: one failure never stops the queue, nor the process with an
+     * unhandled rejection. The durable queue retries and dead-letters instead.
+     */
+    constructor(onFailure = error => {
+        console.error(`A job failed and was dropped: ${error instanceof Error ? error.message : String(error)}`);
+    }) {
+        this.onFailure = onFailure;
+    }
     async enqueue(item, idempotencyKey) {
         if (idempotencyKey) {
             if (this.#keys.has(idempotencyKey)) {
@@ -52,7 +63,12 @@ export class MemoryWorkQueue {
                 }
                 const item = this.#items.shift();
                 if (item !== undefined) {
-                    await handler(item);
+                    try {
+                        await handler(item);
+                    }
+                    catch (error) {
+                        this.onFailure(error, item);
+                    }
                 }
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.50",
+    "version": "1.5.52",
     "type": "module",
     "workspaces": [
         ".",