@datalayer/agent-runtimes 1.5.45 → 1.5.46

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

@@ -0,0 +1,167 @@
+import { type AgUiEvent } from '../agui';
+import type { SemanticEvent } from '../semantic';
+import { type HostExchange } from './contracts';
+/**
+ * A turn a host asks for. `provenance` is the host's own thread key (Slack's
+ * `ThreadKey`, Discord's): opaque here, read only through the `HostShape`.
+ */
+export type HostTurnRequest<P> = Readonly<{
+    /** The deployment the turn runs: one the installation allows. */
+    applicationId: string;
+    externalEventId: string;
+    /** The host user the host speaks for: what the credential exchange names. */
+    externalUserId: string;
+    principalId: string;
+    prompt: string;
+    provenance: P;
+    sessionId?: string;
+    /**
+     * How many sessions the thread had before (an explicit start over or
+     * another application): a new session's uid is derived with it.
+     */
+    sessionGeneration?: number;
+}>;
+export type TurnStream = Readonly<{
+    /**
+     * The run the stream is of, as its `loop.turn` event names it: known once
+     * the stream has said it (what a Stop button names).
+     */
+    run: {
+        id?: string;
+    };
+    sessionId: string;
+    updates: AsyncIterable<SemanticEvent>;
+}>;
+export interface AgentClient<P> {
+    startTurn(request: HostTurnRequest<P>): Promise<TurnStream>;
+    stopTurn(sessionId: string, request: HostTurnRequest<P>): Promise<void>;
+}
+/** Where a host asks from (`exchange.optional_request.place`): a channel, or a direct conversation. */
+export type Place = Readonly<{
+    kind: 'channel' | 'direct';
+    id: string;
+}>;
+/**
+ * What is the host's own in a turn: the session uid its thread derives
+ * (`hostSessionUid`), the place Datalayer checks the channel policy against,
+ * the delivery target handed back with every delivery, and what is said when
+ * its installation holds no host key.
+ */
+export type HostShape<P> = Readonly<{
+    sessionUidOf(request: HostTurnRequest<P>): string;
+    placeOf(request: HostTurnRequest<P>): Place;
+    targetOf(request: HostTurnRequest<P>): Record<string, unknown>;
+    notBound: string;
+}>;
+/**
+ * What a turn runs with: a short-lived credential for the linked person and
+ * where the deployment's session API is. A bot token is never one.
+ */
+export type HostSession = Readonly<{
+    accessToken: string;
+    agent: string;
+    deploymentUid: string;
+    /** Whether the session can be mapped to its host thread for deliveries. */
+    bindable: boolean;
+    sessionApiUrl: string;
+    userToken?: string;
+}>;
+export interface HostCredentials<P> {
+    forTurn(request: HostTurnRequest<P>): Promise<HostSession>;
+}
+/** What the installation's key is, for a turn: `undefined` when it was never bound. */
+export type HostKeyLookup<P> = (request: HostTurnRequest<P>) => Promise<string | undefined>;
+/**
+ * The host credential exchange (SLACK §4.3, 1): the installation's key and
+ * the host user it speaks for, exchanged at ai-agents for a fifteen-minute
+ * host token of the linked person and one deployment.
+ */
+export declare class HostKeyCredentials<P> implements HostCredentials<P> {
+    readonly apiUrl: string;
+    readonly hostKeyFor: HostKeyLookup<P>;
+    readonly shape: HostShape<P>;
+    readonly fetchImplementation: typeof fetch;
+    constructor(apiUrl: string, hostKeyFor: HostKeyLookup<P>, shape: HostShape<P>, fetchImplementation?: typeof fetch);
+    exchange(request: HostTurnRequest<P>): Promise<HostExchange>;
+    /** The exchange for one host user and deployment, with a key in hand (a delivery, an action). */
+    exchangeFor(input: {
+        deploymentUid: string;
+        externalUserId: string;
+        hostKey: string;
+        /** Where the turn is asked from: Datalayer refuses a denied channel at once. */
+        place?: Place;
+    }): Promise<HostExchange>;
+    forTurn(request: HostTurnRequest<P>): Promise<HostSession>;
+}
+export declare function hostSessionOf(exchanged: HostExchange): HostSession;
+/**
+ * A turn's credentials: the exchange when its installation holds a host
+ * key; otherwise, in development only, the developer's own (`fallback`);
+ * otherwise a refusal saying the installation is not connected.
+ */
+export declare class InstallationCredentials<P> implements HostCredentials<P> {
+    readonly keyed: HostKeyCredentials<P>;
+    readonly fallback?: HostCredentials<P> | undefined;
+    constructor(keyed: HostKeyCredentials<P>, fallback?: HostCredentials<P> | undefined);
+    forTurn(request: HostTurnRequest<P>): Promise<HostSession>;
+}
+/**
+ * Development only: the developer's own Datalayer key, and their own kept
+ * deployment, read from ai-agents as its owner. Never in production.
+ */
+export declare class DevelopmentCredentials<P> implements HostCredentials<P> {
+    readonly apiUrl: string;
+    readonly token: string;
+    readonly fetchImplementation: typeof fetch;
+    constructor(apiUrl: string, token: string, fetchImplementation?: typeof fetch);
+    forTurn(request: HostTurnRequest<P>): Promise<HostSession>;
+}
+/** One of an application's starters (SLACK S-104): the words shown, and the message it suggests asking. */
+export type Starter = Readonly<{
+    label: string;
+    message: string;
+}>;
+/** Where an application's starters are read, as one linked person of one installation. */
+export interface StarterSource<K> {
+    startersOf(key: K, externalUserId: string, applicationId: string): Promise<readonly Starter[]>;
+}
+/**
+ * An application's starters (SLACK S-104), read from its runtime as the
+ * linked person: the host credential exchange (no place: what is suggested
+ * is private to them), then `GET /api/v1/apps/current` beside the session
+ * API it answers. A runtime that does not answer starters is refused.
+ */
+export declare class HostStarters<K, P> implements StarterSource<K> {
+    readonly apiUrl: string;
+    readonly keyed: HostKeyCredentials<P>;
+    readonly hostKeyOf: (key: K) => Promise<string | undefined>;
+    readonly fetchImplementation: typeof fetch;
+    constructor(apiUrl: string, keyed: HostKeyCredentials<P>, hostKeyOf: (key: K) => Promise<string | undefined>, fetchImplementation?: typeof fetch);
+    startersOf(key: K, externalUserId: string, applicationId: string): Promise<readonly Starter[]>;
+}
+/** 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> {
+    #private;
+    readonly apiUrl: string;
+    readonly credentials: HostCredentials<P>;
+    readonly shape: HostShape<P>;
+    readonly fetchImplementation: typeof fetch;
+    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>;
+    stopTurn(sessionId: string, request: HostTurnRequest<P>): Promise<void>;
+}
+/**
+ * The session's last answer, read with the host token (what a replayed turn
+ * and a `turn.completed` delivery show); `null` when the session is not read.
+ */
+export declare function lastAnswer(fetchImplementation: typeof fetch, host: HostSession, sessionId: string): Promise<string | undefined | null>;
+/** A session API or stream URL Datalayer answered: HTTPS, on Datalayer's own origin. */
+export declare function assertTrustedStreamUrl(baseUrl: string, streamUrl: string): void;

package/lib/portable/hosts/agentClient.js

@@ -0,0 +1,346 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * A chat host's turns on Datalayer: the host credential exchange, a turn
+ * started or sent on the deployment's session API (idempotent by the host's
+ * event id), its AG-UI stream reduced to semantic events, and its session
+ * mapped to the host's thread so approvals and completions are delivered
+ * (SLACK §4.3, DISCORD §4.3). What is the host's own (its thread key, the
+ * session uid, the place, the delivery target, its words) is injected as a
+ * `HostShape`. Moved from the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/agentClient
+ */
+import { z } from 'zod';
+import { AgUiFrames } from '../agui';
+import { semanticOf, turnOf } from '../semanticOfAgUi';
+import { HostRefusedError } from './client';
+import { exchangeSchema, HOST_KEY_HEADER, IDEMPOTENCY_HEADER, } from './contracts';
+/**
+ * The host credential exchange (SLACK §4.3, 1): the installation's key and
+ * the host user it speaks for, exchanged at ai-agents for a fifteen-minute
+ * host token of the linked person and one deployment.
+ */
+export class HostKeyCredentials {
+    apiUrl;
+    hostKeyFor;
+    shape;
+    fetchImplementation;
+    constructor(apiUrl, hostKeyFor, shape, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.hostKeyFor = hostKeyFor;
+        this.shape = shape;
+        this.fetchImplementation = fetchImplementation;
+    }
+    async exchange(request) {
+        const hostKey = await this.hostKeyFor(request);
+        if (!hostKey) {
+            throw new Error(this.shape.notBound);
+        }
+        return this.exchangeFor({
+            deploymentUid: request.applicationId,
+            externalUserId: request.externalUserId,
+            hostKey,
+            place: this.shape.placeOf(request),
+        });
+    }
+    /** The exchange for one host user and deployment, with a key in hand (a delivery, an action). */
+    async exchangeFor(input) {
+        const response = await this.fetchImplementation(`${this.apiUrl}/api/ai-agents/v1/apps/hosts/self/token`, {
+            body: JSON.stringify({
+                deployment_uid: input.deploymentUid,
+                external_user_id: input.externalUserId,
+                ...(input.place ? { place: input.place } : {}),
+            }),
+            headers: {
+                'content-type': 'application/json',
+                [HOST_KEY_HEADER]: input.hostKey,
+            },
+            method: 'POST',
+        });
+        if (!response.ok) {
+            const body = (await response.json().catch(() => ({})));
+            throw new HostRefusedError(response.status, typeof body.detail === 'string' ? body.detail : 'refused', 'Datalayer refused the host credential exchange');
+        }
+        return exchangeSchema.parse(await response.json());
+    }
+    async forTurn(request) {
+        return hostSessionOf(await this.exchange(request));
+    }
+}
+export function hostSessionOf(exchanged) {
+    return {
+        accessToken: exchanged.access_token,
+        agent: exchanged.session_api.agent,
+        bindable: true,
+        deploymentUid: exchanged.deployment.uid,
+        sessionApiUrl: exchanged.session_api.url,
+        userToken: exchanged.user_token,
+    };
+}
+/**
+ * A turn's credentials: the exchange when its installation holds a host
+ * key; otherwise, in development only, the developer's own (`fallback`);
+ * otherwise a refusal saying the installation is not connected.
+ */
+export class InstallationCredentials {
+    keyed;
+    fallback;
+    constructor(keyed, fallback) {
+        this.keyed = keyed;
+        this.fallback = fallback;
+    }
+    async forTurn(request) {
+        if (await this.keyed.hostKeyFor(request)) {
+            return this.keyed.forTurn(request);
+        }
+        if (this.fallback) {
+            return this.fallback.forTurn(request);
+        }
+        throw new Error(this.keyed.shape.notBound);
+    }
+}
+/**
+ * Development only: the developer's own Datalayer key, and their own kept
+ * deployment, read from ai-agents as its owner. Never in production.
+ */
+export class DevelopmentCredentials {
+    apiUrl;
+    token;
+    fetchImplementation;
+    constructor(apiUrl, token, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.token = token;
+        this.fetchImplementation = fetchImplementation;
+    }
+    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}).`);
+        }
+        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.');
+        }
+        return {
+            accessToken: this.token,
+            agent: kept.agent_id,
+            bindable: false,
+            deploymentUid: request.applicationId,
+            sessionApiUrl: `${kept.url.replace(/\/+$/, '')}/api/v1/apps/sessions`,
+        };
+    }
+}
+/** What `GET /api/v1/apps/current` answers that a host reads: the application's starters. */
+const currentAppSchema = z.object({
+    starters: z.array(z.object({ label: z.string(), message: z.string() })),
+});
+/**
+ * An application's starters (SLACK S-104), read from its runtime as the
+ * linked person: the host credential exchange (no place: what is suggested
+ * is private to them), then `GET /api/v1/apps/current` beside the session
+ * API it answers. A runtime that does not answer starters is refused.
+ */
+export class HostStarters {
+    apiUrl;
+    keyed;
+    hostKeyOf;
+    fetchImplementation;
+    constructor(apiUrl, keyed, hostKeyOf, fetchImplementation = fetch) {
+        this.apiUrl = apiUrl;
+        this.keyed = keyed;
+        this.hostKeyOf = hostKeyOf;
+        this.fetchImplementation = fetchImplementation;
+    }
+    async startersOf(key, externalUserId, applicationId) {
+        const hostKey = await this.hostKeyOf(key);
+        if (!hostKey) {
+            throw new Error(this.keyed.shape.notBound);
+        }
+        const exchanged = await this.keyed.exchangeFor({
+            deploymentUid: applicationId,
+            externalUserId,
+            hostKey,
+        });
+        const sessions = exchanged.session_api.url.replace(/\/+$/, '');
+        assertTrustedStreamUrl(this.apiUrl, sessions);
+        if (!sessions.endsWith('/api/v1/apps/sessions')) {
+            throw new Error("Datalayer answered a session API that is not an application runtime's.");
+        }
+        const response = await this.fetchImplementation(`${sessions.slice(0, -'/sessions'.length)}/current`, { headers: { authorization: `Bearer ${exchanged.access_token}` } });
+        if (!response.ok) {
+            throw new HostRefusedError(response.status, 'refused', 'The application did not say what it suggests asking');
+        }
+        return currentAppSchema.parse(await response.json()).starters;
+    }
+}
+/** Each AG-UI event of a run's `text/event-stream` body, as it arrives (`AgUiFrames`). */
+export async function* agUiEventsOf(body) {
+    const decoder = new TextDecoder();
+    const frames = new AgUiFrames();
+    const reader = body.getReader();
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done) {
+                break;
+            }
+            yield* frames.push(decoder.decode(value, { stream: true }));
+        }
+        yield* frames.push(decoder.decode());
+        yield* frames.end();
+    }
+    finally {
+        reader.releaseLock();
+    }
+}
+/**
+ * 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 class HttpAgentClient {
+    apiUrl;
+    credentials;
+    shape;
+    fetchImplementation;
+    hostKeyFor;
+    constructor(apiUrl, credentials, shape, fetchImplementation = fetch, hostKeyFor) {
+        this.apiUrl = apiUrl;
+        this.credentials = credentials;
+        this.shape = shape;
+        this.fetchImplementation = fetchImplementation;
+        this.hostKeyFor = hostKeyFor;
+    }
+    async startTurn(request) {
+        const host = await this.credentials.forTurn(request);
+        assertTrustedStreamUrl(this.apiUrl, host.sessionApiUrl);
+        const sessionId = request.sessionId ?? this.shape.sessionUidOf(request);
+        const headers = {
+            accept: 'text/event-stream',
+            authorization: `Bearer ${host.accessToken}`,
+            'content-type': 'application/json',
+            [IDEMPOTENCY_HEADER]: request.externalEventId,
+        };
+        const response = request.sessionId
+            ? await this.fetchImplementation(`${host.sessionApiUrl}/${encodeURIComponent(sessionId)}/messages`, {
+                body: JSON.stringify({
+                    external_event_id: request.externalEventId,
+                    text: request.prompt,
+                }),
+                headers,
+                method: 'POST',
+            })
+            : await this.fetchImplementation(host.sessionApiUrl, {
+                body: JSON.stringify({
+                    agent: host.agent,
+                    deployment_uid: host.deploymentUid,
+                    external_event_id: request.externalEventId,
+                    opener: request.prompt,
+                    session: sessionId,
+                    ...(host.userToken ? { user_token: host.userToken } : {}),
+                }),
+                headers,
+                method: 'POST',
+            });
+        if (!response.ok || !response.body) {
+            throw new Error(`Datalayer refused the turn (${response.status}).`);
+        }
+        const hostKey = host.bindable && this.hostKeyFor
+            ? await this.hostKeyFor(request)
+            : undefined;
+        if (hostKey) {
+            await this.#bind(request, host, sessionId, hostKey);
+        }
+        const run = {};
+        return {
+            run,
+            sessionId,
+            updates: this.#updates(response.body, host, sessionId, run),
+        };
+    }
+    async stopTurn(sessionId, request) {
+        const host = await this.credentials.forTurn(request);
+        assertTrustedStreamUrl(this.apiUrl, host.sessionApiUrl);
+        const response = await this.fetchImplementation(`${host.sessionApiUrl}/${encodeURIComponent(sessionId)}/stop`, {
+            headers: { authorization: `Bearer ${host.accessToken}` },
+            method: 'POST',
+        });
+        if (!response.ok && response.status !== 409) {
+            throw new Error(`Datalayer could not stop the turn (${response.status}).`);
+        }
+    }
+    async #bind(request, host, sessionId, hostKey) {
+        const response = await this.fetchImplementation(`${this.apiUrl}/api/ai-agents/v1/apps/hosts/sessions/${encodeURIComponent(sessionId)}`, {
+            // Handed back with every delivery: the thread, and the host user the
+            // host token speaks for, whom an approval waits on.
+            body: JSON.stringify({ target: this.shape.targetOf(request) }),
+            headers: {
+                authorization: `Bearer ${host.accessToken}`,
+                'content-type': 'application/json',
+                [HOST_KEY_HEADER]: hostKey,
+            },
+            method: 'PUT',
+        });
+        if (!response.ok) {
+            throw new Error(`Datalayer did not map the thread to its session (${response.status}).`);
+        }
+    }
+    async *#updates(body, host, sessionId, run) {
+        const tools = new Map();
+        for await (const event of agUiEventsOf(body)) {
+            const turn = turnOf(event);
+            if (turn?.turn) {
+                run.id = turn.turn;
+            }
+            if (turn?.replayed) {
+                // A retry: nothing ran again; what the turn said is the session's.
+                yield* this.#replayed(host, sessionId, turn.state);
+                return;
+            }
+            yield* semanticOf(event, tools);
+        }
+    }
+    async *#replayed(host, sessionId, state) {
+        if (state === 'running') {
+            yield { kind: 'progress', label: 'Still working on this message…' };
+            return;
+        }
+        const text = await lastAnswer(this.fetchImplementation, host, sessionId);
+        if (text === null) {
+            yield {
+                kind: 'error',
+                message: 'This message was already answered in Datalayer.',
+            };
+            return;
+        }
+        yield { kind: 'completion', text };
+    }
+}
+/**
+ * The session's last answer, read with the host token (what a replayed turn
+ * and a `turn.completed` delivery show); `null` when the session is not read.
+ */
+export async function lastAnswer(fetchImplementation, host, sessionId) {
+    const response = await fetchImplementation(`${host.sessionApiUrl}/${encodeURIComponent(sessionId)}/messages`, { headers: { authorization: `Bearer ${host.accessToken}` } });
+    if (!response.ok) {
+        return null;
+    }
+    const { messages } = (await response.json());
+    const last = [...(messages ?? [])]
+        .reverse()
+        .find(message => message.role === 'assistant');
+    return typeof last?.content === 'string' ? last.content : undefined;
+}
+/** A session API or stream URL Datalayer answered: HTTPS, on Datalayer's own origin. */
+export function assertTrustedStreamUrl(baseUrl, streamUrl) {
+    const base = new URL(baseUrl);
+    const stream = new URL(streamUrl);
+    if (stream.protocol !== 'https:' || stream.origin !== base.origin) {
+        throw new Error('Datalayer returned an untrusted stream URL.');
+    }
+}

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

@@ -0,0 +1,43 @@
+import type { ApprovalPresentation } from './contracts';
+/**
+ * Typed approval renderers (plans/SLACK.md §2 rule 6, S-302; plans/DISCORD.md
+ * §3.6). A host offers Approve and Reject only when a renderer that knows the
+ * tool proves that every material argument is shown: each argument the server
+ * presented is named by the renderer, or the card fails closed. An unknown
+ * tool, an argument the renderer does not know, an attachment, and every
+ * destructive, financial or publishing action are reviewed in Datalayer
+ * (SLACK §15, 5). They render ai-agents' presentation v1, a different input
+ * from `../approvals.ts` and `../approvalCard.ts`. Moved from the Slack
+ * service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/approvalRenderers
+ */
+export type RenderedField = Readonly<{
+    label: string;
+    value: string;
+}>;
+export type RenderedAction = Readonly<{
+    /** The renderer that knew the tool. */
+    renderer: string;
+    /** The fields shown, in order, each whole. */
+    fields: readonly RenderedField[];
+    /** Whether every argument is shown and nothing needs Datalayer. */
+    complete: boolean;
+    /** Why not, in words, when it is not. */
+    reasons: readonly string[];
+}>;
+type Renderer = Readonly<{
+    name: string;
+    matches(presentation: ApprovalPresentation): boolean;
+    render(presentation: ApprovalPresentation): RenderedAction;
+}>;
+/** Action classes that are decided in Datalayer only (§15, 5). */
+export declare const DATALAYER_ONLY: Set<"unknown" | "read" | "write" | "send" | "delete" | "publish" | "execute" | "financial">;
+/** The renderers, the first that matches wins: Datalayer-only before any other. */
+export declare const RENDERERS: readonly Renderer[];
+/**
+ * How a host shows an approval, by the renderer that knows its tool; with
+ * none, nothing is decided in the host.
+ */
+export declare function renderApproval(presentation: ApprovalPresentation): RenderedAction;
+export {};