@datalayer/agent-runtimes 1.5.44 → 1.5.46

package/lib/apps/plugins/chat/ChatView.js

@@ -1702,8 +1702,8 @@ export default function ChatView({ workspace }) {
                     // opening stops it, and *Stop speaking* while it speaks.
                     speaking: speaking, onStopSpeaking: () => controlsRef.current?.stopSpeaking?.(), 
                     // Hands-free (VO-12, VO-13): the run in progress, stopped when
-                    // the person speaks over it.
-                    running: busy, onStopRun: () => controlsRef.current?.stop?.(), onInterimChange: setVoiceInterim, 
+                    // the person speaks over it, and the answer marked interrupted.
+                    running: busy, onStopRun: () => controlsRef.current?.stop?.(), onInterrupted: () => controlsRef.current?.markInterrupted(), onInterimChange: setVoiceInterim, 
                     // The menu offers when answers are heard where the
                     // application lets them be (VO-21, VO-30).
                     answers: Boolean(config?.voice?.output &&

package/lib/chat/ChatFloating.js

@@ -1030,7 +1030,7 @@ export function ChatFloating({ endpoint, protocol: protocolProp, useStore: useSt
                     ...poweredByProps,
                 }, description: description, onStateUpdate: onStateUpdate, onNewChat: onNewChat, suggestions: suggestions, submitOnSuggestionClick: submitOnSuggestionClick, hideMessagesAfterToolUI: hideMessagesAfterToolUI, avatarConfig: {
                     showAvatars: true,
-                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt ?? suggestionPrompt, inspector: inspector, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, voice: voice, voiceSpeaking: speakerState.speaking, onStopSpeaking: speaker ? stopSpeaking : undefined, onReadAloud: speaker ? readAnswerAloud : undefined, ...panelProps, ...assistantChat, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, onSendReady: handleSendReady, children: conversationBalloon && currentOpen ? (
+                }, placeholder: "Type a message...", backgroundColor: "canvas.subtle", frontendTools: frontendTools, showModelSelector: showModelSelector, availableModels: availableModels, showToolsMenu: showToolsMenu, showSkillsMenu: showSkillsMenu, showTokenUsage: showTokenUsage, showContextRing: showContextRing, runtimeId: runtimeId, historyEndpoint: historyEndpoint, historyAuthToken: historyAuthToken, pendingPrompt: pendingPrompt ?? suggestionPrompt, inspector: inspector, showInformation: showInformation, onInformationClick: onInformationClick, onToolCallStart: onToolCallStart, onToolCallComplete: onToolCallComplete, showToolApprovalBanner: showToolApprovalBanner, pendingApprovals: pendingApprovals, onApproveApproval: onApproveApproval, onRejectApproval: onRejectApproval, voice: voice, voiceSpeaking: speakerState.speaking, voiceSentence: speakerState.sentence, onStopSpeaking: speaker ? stopSpeaking : undefined, onReadAloud: speaker ? readAnswerAloud : undefined, ...panelProps, ...assistantChat, onLoadingChange: handleLoadingChange, onDisplayItemsChange: handleDisplayItemsChange, onSendReady: handleSendReady, children: conversationBalloon && currentOpen ? (
                 // Current: the one thing said or done now, over the composer.
                 _jsx(Box, { px: 3, pt: 3, pb: 2, overflow: "hidden", children: _jsx(CurrentBalloonBody, { text: toolSaid ? undefined : (currentWords ?? description), fullText: toolSaid ? undefined : currentWhole, tool: toolSaid, busy: atWork, speaking: answering && atWork, waiting: atWork && !answering }) })) : (children) }))] }));
     /*

package/lib/chat/base/ChatBase.js

@@ -52,11 +52,13 @@ import { EphemeralSurfaceControl } from '../EphemeralSurfaceControl';
 import { ChatMessageList, } from '../messages/ChatMessageList';
 import { InputPrompt } from '../prompt/InputPrompt';
 import { ComposerVoice, spokenOf } from '../../voice/ComposerVoice';
+import { answerSpokenOver } from '../../voice/handsFree';
 import { ReadAloud, readsAloud } from '../../voice/ReadAloud';
 import { settledVoice } from '../../voice/chatVoice';
 import { useVoiceSettings } from '../../voice/useVoiceSettings';
 import { useVoiceSpeaker } from '../../voice/useVoiceSpeaker';
 import { useSpokenAnswers } from '../../voice/useSpokenAnswers';
+import { saidMessageId, useSaidSentence } from '../../voice/captions';
 import { lineToSay } from '../../voice/sayAloud';
 import { isFloatingChatViewMode } from '../viewModes';
 import { ToolApprovalBanner, ToolApprovalDialog, } from '../tools';
@@ -424,7 +426,7 @@ function ChatBaseInner({ title, subtitle, showHeader = false, showTokenUsage = t
 // Mode selection
 useStore: useStoreMode = true, protocol: protocolRaw, onSendMessage, onSendReady, onLoadingChange, onSpeakingChange, onContextSnapshot, enableStreaming = false, 
 // Extended props
-brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, welcome, trailingContent, voice, voiceSpeaking = false, onStopSpeaking, onReadAloud, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, onItemsChange, onDisplayItemsChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
+brandIcon, avatarConfig, headerButtons, showPoweredBy = false, poweredByProps, emptyState, renderHeader, showTurnFooter = true, notebookToolSurfacesId, footerContent, welcome, trailingContent, voice, voiceSpeaking = false, voiceSentence, onStopSpeaking, onReadAloud, showInformation = false, onInformationClick, headerContent, children, borderRadius, backgroundColor, border, boxShadow, compact = false, placeholder, description = 'Start a conversation with the AI agent.', onStateUpdate, onNewChat, onClear, onMessagesChange, onItemsChange, onDisplayItemsChange, autoFocus = false, suggestions, submitOnSuggestionClick = true, hideMessagesAfterToolUI = false, focusTrigger, frontendTools: frontendToolsProp, enableEphemeralNotebook = false, initialEphemeralNotebookOpen = true, onEphemeralNotebookOpenChange, enableEphemeralDocument = false, initialEphemeralSurfaceMode, onEphemeralSurfaceModeChange, collapsed = false, onExpandFromCollapsed, ephemeralNotebookToolbar, ephemeralNotebookToolbarExtraItems, ephemeralDocumentToolbarExtraItems, ephemeralNotebookCollaborationProvider, ephemeralNotebookCollaborationDocumentId, ephemeralDocumentCollaboration, ephemeralRuntimeOverride, 
 // Tool invocation hooks
 onToolCallStart, onToolCallComplete, inspector: inspectorGiven, 
 // Identity/Authorization props
@@ -2974,6 +2976,10 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     const ownVoice = useVoiceSpeaker(settled, !hostSpeaks);
     useSpokenAnswers(displayItems, isLoading, !hostSpeaks && settled?.output === 'always', ownVoice.speaker);
     const speakingNow = voiceSpeaking || ownVoice.state.speaking;
+    // The sentence being said, marked in the conversation (VO-65).
+    const sentenceSaid = hostSpeaks ? voiceSentence : ownVoice.state.sentence;
+    const saidConversationRef = useRef(null);
+    useSaidSentence(saidConversationRef, sentenceSaid, displayItems);
     /*
      * A line the agent wants heard, not written (VO-35): a caption while the
      * run goes on, said by the speaker where answers are said by themselves.
@@ -3001,6 +3007,14 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
     }, [isLoading]);
     // Answers spoken over, hands-free (VOICE.md VO-13): marked *interrupted*.
     const [interruptedIds, setInterruptedIds] = useState(() => new Set());
+    // The conversation as shown, read when the person speaks over an answer.
+    const shownItemsRef = useRef([]);
+    const markInterrupted = useCallback(() => {
+        const spokenOver = answerSpokenOver(shownItemsRef.current.filter((item) => !isToolCallMessage(item)));
+        if (spokenOver) {
+            setInterruptedIds(ids => new Set([...ids, spokenOver]));
+        }
+    }, []);
     const stopSpeaking = onStopSpeaking ?? (ownVoice.speaker ? ownVoice.stop : undefined);
     const readAnswerAloud = onReadAloud ?? (ownVoice.speaker ? ownVoice.read : undefined);
     const handleSend = useCallback(async (messageOverride, 
@@ -3370,6 +3384,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             thread: () => threadIdRef.current,
             // Its speaker, for a host whose composer holds the microphone (VO-10).
             stopSpeaking,
+            // The answer spoken over, marked for a host's own composer (VO-13).
+            markInterrupted,
         });
         return () => {
             onSendReady(null);
@@ -3382,6 +3398,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
         handleStop,
         handleNewChat,
         stopSpeaking,
+        markInterrupted,
     ]);
     // Streaming state, for a host that draws the prompt.
     useEffect(() => {
@@ -3748,6 +3765,8 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             ...displayItems,
         ]
         : displayItems;
+    shownItemsRef.current = welcomedItems;
+    const saidId = saidMessageId(welcomedItems, sentenceSaid);
     /*
      * *Read aloud* under each answer the agent has finished (VOICE.md VO-21),
      * when the host reads answers aloud on request.
@@ -3763,7 +3782,7 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
             return (_jsxs(_Fragment, { children: [interruptedIds.has(message.id) ? (_jsx(Text, { sx: { fontSize: 0, color: 'fg.muted', fontStyle: 'italic' }, "data-interrupted": "", children: "interrupted" })) : null, readAnswerAloud && readsAloud(message, text, writingId) ? (_jsx(ReadAloud, { onRead: () => readAnswerAloud(text) })) : null] }));
         }
         : undefined;
-    const messagesContent = children ? (children) : (_jsxs(Box, { display: "flex", flexDirection: "column", minHeight: 0, 
+    const messagesContent = children ? (children) : (_jsxs(Box, { ref: saidConversationRef, display: "flex", flexDirection: "column", minHeight: 0, 
         /*
             A reading column, not a full-bleed sheet.
   
@@ -3776,16 +3795,12 @@ showToolApprovalBanner = true, pendingApprovals: pendingApprovalsProp, onApprove
                 // Tool calls are drawn by the page's Reactor plugins; a named
                 // notebook's cell surfaces stand in for the default row of its tools,
                 // so every chat with a headless notebook gets the same transcript.
-                notebookToolSurfacesId: notebookToolSurfacesId, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, renderMessageFooter: readAloudFooter, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }), trailingContent] }));
+                notebookToolSurfacesId: notebookToolSurfacesId, approvalConfig: approvalConfig, messagesEndRef: messagesEndRef, onRespond: handleRespond, showTurnFooters: showTurnFooter, renderMessageFooter: readAloudFooter, saidMessageId: saidId, agentUsage: agentUsage, onRemoveItems: handleRemoveItems, mcpServers: filteredMcpServers, emptyContent: launching ? null : (_jsx(ChatEmptyState, { emptyState: emptyState, brandIcon: brandIcon, description: resolvedDescription, suggestions: resolvedSuggestions, submitOnSuggestionClick: submitOnSuggestionClick, onSuggestionSubmit: handleSuggestionSubmit, onSuggestionFill: handleSuggestionFill })) }), trailingContent] }));
     // The microphone, in the composer's footer (VO-10, VO-11).
     const voiceControl = settled && settled.input !== 'off' ? (_jsx(ComposerVoice, { voice: settled, input: input, setInput: setInput, disabled: disabled || launching, speaking: speakingNow, onStopSpeaking: stopSpeaking, 
         // Hands-free (VO-12, VO-13): the run in progress, stopped when the
         // person speaks over it, and the answer marked interrupted.
-        running: isLoading, onStopRun: handleStop, onInterrupted: () => {
-            if (writingId) {
-                setInterruptedIds(ids => new Set([...ids, writingId]));
-            }
-        }, onInterimChange: setVoiceInterim, 
+        running: isLoading, onStopRun: handleStop, onInterrupted: markInterrupted, onInterimChange: setVoiceInterim, 
         // The menu offers when answers are heard where the application
         // lets them be (VO-21, VO-30).
         answers: Boolean(voice?.output && voice.output !== 'off' && voice.speechUrl), onSpoken: metadata => {

package/lib/chat/messages/ChatMessageList.d.ts

@@ -78,6 +78,12 @@ export interface ChatMessageListProps {
      * `note`, which has no footer of its own.
      */
     renderMessageFooter?: (message: ChatMessage) => ReactNode;
+    /**
+     * The answer a sentence is being said from (VOICE.md VO-65): its row is
+     * marked `aria-current` and `data-voice-saying`, with a bar beside it —
+     * the sentence itself is underlined by `useSaidSentence`.
+     */
+    saidMessageId?: string;
     /**
      * The MCP servers the agent has, with the tools each serves: a tool call is
      * drawn with the marks of the server it belongs to. Skills, frontend tools
@@ -109,5 +115,5 @@ export interface SubagentChatPanelProps {
  * approval decisions are sent over the shared monitoring socket.
  */
 export declare function SubagentChatPanel({ toolCallId, subagentName: subagentNameHint, height, avatarConfig, }: SubagentChatPanelProps): React.ReactElement | null;
-export declare function ChatMessageList({ displayItems, actOn, upload, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters, agentUsage, onRemoveItems, renderMessageFooter, mcpServers, density, }: ChatMessageListProps): import("react").JSX.Element;
+export declare function ChatMessageList({ displayItems, actOn, upload, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters, agentUsage, onRemoveItems, renderMessageFooter, saidMessageId, mcpServers, density, }: ChatMessageListProps): import("react").JSX.Element;
 export {};

package/lib/chat/messages/ChatMessageList.js

@@ -366,7 +366,7 @@ function DefaultToolCallRenderer({ item, onRespond, mcpServers, density, }) {
 // ---------------------------------------------------------------------------
 // Component
 // ---------------------------------------------------------------------------
-export function ChatMessageList({ displayItems, actOn, upload, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters = false, agentUsage, onRemoveItems, renderMessageFooter, mcpServers, density = 'comfortable', }) {
+export function ChatMessageList({ displayItems, actOn, upload, isLoading, isStreaming, showLoadingIndicator, hideMessagesAfterToolUI, avatarConfig, padding, notebookToolSurfacesId, emptyContent, messagesEndRef, onRespond, approvalConfig, showTurnFooters = false, agentUsage, onRemoveItems, renderMessageFooter, saidMessageId, mcpServers, density = 'comfortable', }) {
     /*
      * Who draws a tool call: the Reactor plugins of the page, when it has a
      * platform. Each plugin binds its own tools (`ToolBindings`) and renders its
@@ -541,7 +541,13 @@ export function ChatMessageList({ displayItems, actOn, upload, isLoading, isStre
         }
         // The host's footer, asked once: a row only when it draws something.
         const messageFooter = renderMessageFooter?.(message);
-        return (_jsx(Box, { "data-chat-message": message.role, display: "flex", flexDirection: "column", alignItems: isUser ? 'flex-end' : 'flex-start', px: padding, py: compact ? '2px' : 1, children: _jsxs(Box, { display: "flex", gap: 2, flexDirection: isUser ? 'row-reverse' : 'row', alignItems: "flex-start", 
+        // The answer being said (VO-65): marked by a bar and for assistive tech.
+        const said = saidMessageId !== undefined && message.id === saidMessageId;
+        return (_jsx(Box, { "data-chat-message": message.role, "data-voice-saying": said ? '' : undefined, "aria-current": said ? 'true' : undefined, sx: said
+                ? {
+                    boxShadow: 'inset 3px 0 0 var(--borderColor-accent-emphasis, #0969da)',
+                }
+                : undefined, display: "flex", flexDirection: "column", alignItems: isUser ? 'flex-end' : 'flex-start', px: padding, py: compact ? '2px' : 1, children: _jsxs(Box, { display: "flex", gap: 2, flexDirection: isUser ? 'row-reverse' : 'row', alignItems: "flex-start", 
                 /*
                         Full width, always.
       

package/lib/portable/hosts/__tests__/fixtures/lock-with-jupyter.json

@@ -0,0 +1,40 @@
+{
+  "name": "@datalayer/slack",
+  "lockfileVersion": 3,
+  "packages": {
+    "": {
+      "name": "@datalayer/slack",
+      "dependencies": {
+        "@slack/bolt": "5.1.0",
+        "@datalayer/agent-runtimes": "1.5.44"
+      },
+      "devDependencies": { "vitest": "4.1.11" }
+    },
+    "node_modules/@slack/bolt": {
+      "version": "5.1.0",
+      "dependencies": { "express": "5.0.0" }
+    },
+    "node_modules/express": { "version": "5.0.0" },
+    "node_modules/@datalayer/agent-runtimes": {
+      "version": "1.5.44",
+      "dependencies": { "@datalayer/jupyter-react": "2.0.0" }
+    },
+    "node_modules/@datalayer/jupyter-react": {
+      "version": "2.0.0",
+      "dependencies": {
+        "@jupyterlab/services": "7.0.0",
+        "@lumino/widgets": "2.0.0"
+      }
+    },
+    "node_modules/@datalayer/jupyter-react/node_modules/@jupyterlab/services": {
+      "version": "7.0.0"
+    },
+    "node_modules/@lumino/widgets": { "version": "2.0.0" },
+    "node_modules/vitest": {
+      "version": "4.1.11",
+      "dev": true,
+      "dependencies": { "react-dom": "19.0.0" }
+    },
+    "node_modules/react-dom": { "version": "19.0.0", "dev": true }
+  }
+}

package/lib/portable/hosts/__tests__/fixtures/npm-ls-with-jupyter.json

@@ -0,0 +1,21 @@
+{
+  "name": "@datalayer/slack",
+  "dependencies": {
+    "@slack/bolt": {
+      "version": "5.1.0",
+      "dependencies": { "express": { "version": "5.0.0" } }
+    },
+    "@datalayer/agent-runtimes": {
+      "version": "1.5.44",
+      "dependencies": {
+        "@datalayer/jupyter-react": {
+          "version": "2.0.0",
+          "dependencies": {
+            "@jupyterlab/services": { "version": "7.0.0" },
+            "react-dom": { "version": "19.0.0" }
+          }
+        }
+      }
+    }
+  }
+}

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;