@truefoundry/assistant-ui-runtime 0.1.0-rc.1

package/dist/index.d.ts

@@ -0,0 +1,300 @@
+import * as _assistant_ui_core from '@assistant-ui/core';
+import { ExternalStoreSharedOptions, AttachmentAdapter, SpeechSynthesisAdapter, DictationAdapter, RealtimeVoiceAdapter, FeedbackAdapter, ThreadAssistantMessagePart, ThreadMessage, AppendMessage, ExportedMessageRepositoryItem, RemoteThreadListAdapter } from '@assistant-ui/core';
+import * as truefoundry_gateway_sdk_agents from 'truefoundry-gateway-sdk/agents';
+import { AgentSessionClient, TurnEvent, ThreadCreatedEvent, UserToolResponseEvent, McpAuthRequiredEvent, UserToolApprovalEvent, Turn, TurnInputItem, AgentSession } from 'truefoundry-gateway-sdk/agents';
+export { SandboxCreatedEvent } from 'truefoundry-gateway-sdk/agents';
+import { TruefoundryGatewayApi, TrueFoundryGateway } from 'truefoundry-gateway-sdk';
+import * as _assistant_ui_core_internal from '@assistant-ui/core/internal';
+
+type AgentSpec = TruefoundryGatewayApi.AgentSpec;
+type DraftSession = TruefoundryGatewayApi.DraftSession;
+type AgentSpecUpdate = {
+    instructions?: string;
+    model?: Partial<AgentSpec["model"]> & {
+        params?: Partial<NonNullable<AgentSpec["model"]["params"]>>;
+    };
+    mcpServers?: AgentSpec["mcpServers"];
+    skills?: AgentSpec["skills"];
+    messages?: AgentSpec["messages"];
+    variables?: AgentSpec["variables"];
+    responseFormat?: AgentSpec["responseFormat"];
+    config?: AgentSpec["config"];
+};
+declare function mergeAgentSpec(base: AgentSpec, update: AgentSpecUpdate): AgentSpec;
+declare function draftSessionTitle(draft: DraftSession): string;
+
+type NamedAgentConfig = {
+    mode: "named";
+    agentName: string;
+};
+type DraftAgentConfig = {
+    mode: "draft";
+    defaultAgentSpec: AgentSpec;
+    onAgentSpecChange?: ((spec: AgentSpec) => void) | undefined;
+};
+type TrueFoundryAgentConfig = NamedAgentConfig | DraftAgentConfig;
+type TrueFoundryAgentRuntimeBaseOptions = ExternalStoreSharedOptions & {
+    client: AgentSessionClient;
+    initialSessionId?: string | undefined;
+    threadId?: string | undefined;
+    onThreadIdChange?: ((threadId: string | undefined) => void) | undefined;
+    onError?: ((error: unknown) => void) | undefined;
+    listEventsConcurrency?: number | undefined;
+    adapters?: {
+        attachments?: AttachmentAdapter | undefined;
+        speech?: SpeechSynthesisAdapter | undefined;
+        dictation?: DictationAdapter | undefined;
+        voice?: RealtimeVoiceAdapter | undefined;
+        feedback?: FeedbackAdapter | undefined;
+    } | undefined;
+};
+type UseTrueFoundryAgentRuntimeOptions = TrueFoundryAgentRuntimeBaseOptions & {
+    /** Discriminated agent source. Omit when using legacy `agentName`. */
+    agent?: TrueFoundryAgentConfig | undefined;
+    /** Legacy named-agent shorthand. Prefer `agent: { mode: "named", agentName }`. */
+    agentName?: string | undefined;
+    /** Required when `agent.mode === "draft"`. */
+    gateway?: TrueFoundryGateway | undefined;
+};
+
+declare function useTrueFoundryAgentRuntime(options: UseTrueFoundryAgentRuntimeOptions): _assistant_ui_core.AssistantRuntime;
+
+type AssistantContentPart = ThreadAssistantMessagePart;
+
+/** Gateway root thread id — always the literal `"main"`. */
+declare const ROOT_THREAD_ID = "main";
+
+type AgentInfo = ThreadCreatedEvent["agentInfo"];
+type SubAgentCustomMetadata = {
+    threadId: string;
+    title?: string;
+    name?: string;
+    model?: string;
+    input?: string;
+};
+type SubAgentArtifact = {
+    subAgents: Array<{
+        threadId: string;
+        title?: string;
+        agentInfo?: AgentInfo;
+    }>;
+};
+type PendingResponseRef = {
+    id: string;
+    sourceEventId: string;
+    question?: string;
+    options?: string[];
+};
+type ApprovalDecisionRef = {
+    id: string;
+    approved: boolean;
+    reason?: string;
+};
+type ThreadBucket = {
+    events: Map<string, TurnEvent>;
+    modelMessageIds: string[];
+    toolResults: Map<string, string>;
+    pendingApprovals: Map<string, {
+        id: string;
+    }>;
+    approvalDecisions: Map<string, ApprovalDecisionRef>;
+    pendingResponses: Map<string, PendingResponseRef>;
+    done: boolean;
+    title?: string;
+    agentInfo?: AgentInfo;
+};
+type ThreadParentLink = {
+    parentThreadId: string;
+    toolCallId: string;
+};
+declare class PeerThreadFoldState {
+    readonly threads: Map<string, ThreadBucket>;
+    readonly threadParents: Map<string, ThreadParentLink>;
+    getOrCreateBucket(threadId: string): ThreadBucket;
+}
+
+declare const TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY = "toolResponseThreadId";
+type RespondToToolResponseOptions = Pick<UserToolResponseEvent, "toolCallId" | "content">;
+declare function messageHasPendingResponses(message: ThreadMessage | undefined): boolean;
+declare function collectResponseInputs(message: ThreadMessage, threadId: string): UserToolResponseEvent[];
+
+/** Keys written to `ThreadMessage.metadata.custom` by this runtime adapter. */
+type TrueFoundryMessageCustomMetadata = {
+    subAgent?: SubAgentCustomMetadata;
+    pendingMcpAuth?: true;
+    mcpServers?: McpAuthRequiredEvent["mcpServers"];
+    sandboxId?: string;
+    [TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY]?: string;
+    [TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY]?: string;
+};
+type SubAgentMessageCustomMetadata = Pick<TrueFoundryMessageCustomMetadata, "subAgent">;
+type McpAuthMessageCustomMetadata = Pick<TrueFoundryMessageCustomMetadata, "pendingMcpAuth" | "mcpServers">;
+type SandboxMessageCustomMetadata = Pick<TrueFoundryMessageCustomMetadata, "sandboxId">;
+type ToolApprovalMessageCustomMetadata = Pick<TrueFoundryMessageCustomMetadata, typeof TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY>;
+type ToolResponseMessageCustomMetadata = Pick<TrueFoundryMessageCustomMetadata, typeof TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY>;
+
+declare const TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY = "toolApprovalThreadId";
+type RespondToToolApprovalOptions = {
+    approvalId: string;
+    approved: boolean;
+    optionId?: string;
+    reason?: string;
+};
+declare function messageHasPendingApprovals(message: ThreadMessage | undefined): boolean;
+declare function collectApprovalInputs(message: ThreadMessage, threadId: string): UserToolApprovalEvent[];
+declare function toTrueFoundryApprovalInputs(message: Extract<ThreadMessage, {
+    role: "assistant";
+}>, response: RespondToToolApprovalOptions, defaultThreadId?: string): UserToolApprovalEvent[];
+
+type ConvertTurnsResult = {
+    messages: ThreadMessage[];
+    foldState: PeerThreadFoldState;
+    runningTurn?: Turn;
+    unstable_resume?: boolean;
+};
+declare function buildTurnAssistantContent(turn: Pick<Turn, "listEvents" | "state">, foldState?: PeerThreadFoldState): Promise<AssistantContentPart[]>;
+declare function convertTurnsToThreadMessages(session: AgentSession): Promise<ConvertTurnsResult>;
+declare function getTurnMessageContent(message: AppendMessage): string;
+/**
+ * Gateway `user.message` content (string for text-only, or text/file parts).
+ * Derived from SDK `TurnInputItem` so it tracks API changes.
+ */
+type UserMessageContent = Extract<TurnInputItem, {
+    type: "user.message";
+}>["content"];
+/**
+ * Builds the gateway turn input content from a composer message, forwarding
+ * attachments as SDK `FileContent` parts. Mirrors how assistant-ui surfaces
+ * attachment content on `message.attachments[].content`.
+ */
+declare function buildUserMessageContent(message: AppendMessage): UserMessageContent;
+/** Strips the `-user` suffix from a projected user message id to recover the turn id. */
+declare function parseTurnIdFromMessageId(messageId: string): string;
+/**
+ * Builds resubmit content for a text-only edit: replaces text with `editedText`
+ * while preserving original file parts from the turn record.
+ */
+declare function buildEditedUserMessageContent(editedText: string, originalInput: TurnInputItem[] | undefined): UserMessageContent;
+declare function repositoryItemsFromMessages(messages: readonly ThreadMessage[]): ExportedMessageRepositoryItem[];
+
+declare function createTrueFoundryDraftThreadListAdapter(options: {
+    gateway: TrueFoundryGateway;
+    defaultAgentSpec: AgentSpec;
+    getAgentSpec?: () => AgentSpec;
+}): RemoteThreadListAdapter;
+
+type DraftSessionBridge = {
+    syncAgentSpec: (draftSessionId: string, agentSpec: AgentSpec) => Promise<void>;
+    getDraftAgentSpec: (draftSessionId: string) => Promise<AgentSpec>;
+};
+declare function createDraftSessionBridge(gateway: TrueFoundryGateway): DraftSessionBridge;
+
+type PendingApproval = {
+    approvalId: string;
+    threadId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    argsText: string;
+};
+type PendingToolResponse = {
+    toolCallId: string;
+    threadId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+    argsText: string;
+    question?: string;
+    options?: string[];
+};
+
+type TrueFoundryDraftRuntimeExtras = {
+    agentSpec: AgentSpec | null;
+    draftSessionId: string | undefined;
+    isSpecSyncing: boolean;
+    specError: unknown | null;
+    updateAgentSpec: (update: AgentSpecUpdate) => void;
+};
+type TrueFoundryRuntimeExtras = {
+    pendingApprovals: PendingApproval[];
+    pendingToolResponses: PendingToolResponse[];
+    pendingMcpAuth: {
+        mcpServers: McpAuthRequiredEvent["mcpServers"];
+    } | null;
+    sandboxId: string | undefined;
+    respondToToolApproval: (response: RespondToToolApprovalOptions) => void;
+    respondToToolResponse: (response: RespondToToolResponseOptions) => void;
+    resumeMcpAuth: () => Promise<void>;
+    downloadSandboxFile: (path: string) => Promise<Blob>;
+    cancel: () => Promise<void>;
+    resetFromTurn: (turnId: string) => Promise<void>;
+    draft: TrueFoundryDraftRuntimeExtras | null;
+};
+declare const trueFoundryExtras: _assistant_ui_core_internal.RuntimeExtras<TrueFoundryRuntimeExtras>;
+
+/** Pending tool approvals plus a respond action. */
+declare const useTrueFoundryApprovals: () => {
+    pending: PendingApproval[];
+    respond: (response: RespondToToolApprovalOptions) => void;
+};
+/** Pending ask-user tool responses plus a respond action. */
+declare const useTrueFoundryToolResponses: () => {
+    pending: PendingToolResponse[];
+    respond: (response: RespondToToolResponseOptions) => void;
+};
+/** Pending MCP OAuth plus a resume action. */
+declare const useTrueFoundryMcpAuth: () => {
+    pending: {
+        mcpServers: truefoundry_gateway_sdk_agents.McpAuthRequiredEvent["mcpServers"];
+    } | null;
+    resume: () => Promise<void>;
+};
+/** Returns a function to respond to a tool approval from any render context. */
+declare const useTrueFoundryRespondToToolApproval: () => (response: RespondToToolApprovalOptions) => void;
+/** Returns a function to respond to a pending tool response from any render context. */
+declare const useTrueFoundryRespondToToolResponse: () => (response: RespondToToolResponseOptions) => void;
+/** Returns a function to resume after MCP OAuth from any render context. */
+declare const useTrueFoundryResumeMcpAuth: () => () => Promise<void>;
+/** Current sandboxId for this session, if a sandbox has been created. */
+declare const useTrueFoundrySandboxId: () => string | undefined;
+/** Returns a function to download a sandbox file by path from any render context. */
+declare const useTrueFoundryDownloadSandboxFile: () => (path: string) => Promise<Blob>;
+/** Returns a function to cancel the current run from any render context. */
+declare const useTrueFoundryCancel: () => () => Promise<void>;
+/** Returns a function to reset (re-submit) a user turn from any render context. */
+declare const useTrueFoundryResetFromTurn: () => (turnId: string) => Promise<void>;
+/** Current draft agent spec and sync state (draft mode only). */
+declare const useTrueFoundryAgentSpec: () => {
+    agentSpec: AgentSpec | null;
+    draftSessionId: string | undefined;
+    isSpecSyncing: boolean;
+    specError: unknown | null;
+    updateAgentSpec: (update: AgentSpecUpdate) => void;
+};
+/** Returns a draft spec updater from any render context. */
+declare const useTrueFoundryUpdateAgentSpec: () => (update: Parameters<TrueFoundryDraftRuntimeExtras["updateAgentSpec"]>[0]) => void | undefined;
+
+type RequiredActionInput = Extract<TurnInputItem, UserToolApprovalEvent | UserToolResponseEvent>;
+declare function messageHasPendingRequiredActions(message: ThreadMessage | undefined): boolean;
+declare function collectRequiredActionInputs(message: ThreadMessage, defaultThreadId?: string): RequiredActionInput[];
+declare function findPausedAssistantMessage(messages: readonly ThreadMessage[]): Extract<ThreadMessage, {
+    role: "assistant";
+}> | undefined;
+
+declare function createTrueFoundryThreadListAdapter(options: {
+    client: AgentSessionClient;
+    agentName: string;
+}): RemoteThreadListAdapter;
+
+type GetSessionOptions = {
+    /** When set, validates the draft and binds turns to `/agents/sessions/{id}/turns`. */
+    draftGateway?: TrueFoundryGateway;
+};
+/** `sessionId` is the assistant-ui thread `remoteId` from `RemoteThreadListAdapter.initialize`. */
+declare function getSession(client: AgentSessionClient, sessionId: string, options?: GetSessionOptions): Promise<AgentSession>;
+
+/**
+ * Reads composer files into `CompleteAttachment` `file` parts for send.
+ * Wire via `adapters: { attachments: trueFoundryAttachmentAdapter }`.
+ */
+declare const trueFoundryAttachmentAdapter: AttachmentAdapter;
+
+export { type AgentSpec, type AgentSpecUpdate, type ConvertTurnsResult, type DraftAgentConfig, type DraftSession, type DraftSessionBridge, type McpAuthMessageCustomMetadata, type NamedAgentConfig, type PendingApproval, type PendingToolResponse, ROOT_THREAD_ID, type SandboxMessageCustomMetadata, type SubAgentArtifact, type SubAgentCustomMetadata, type SubAgentMessageCustomMetadata, TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY, type ToolApprovalMessageCustomMetadata, type ToolResponseMessageCustomMetadata, type TrueFoundryAgentConfig, type TrueFoundryDraftRuntimeExtras, type TrueFoundryMessageCustomMetadata, type TrueFoundryRuntimeExtras, type UseTrueFoundryAgentRuntimeOptions, type UserMessageContent, buildEditedUserMessageContent, buildTurnAssistantContent, buildUserMessageContent, collectApprovalInputs, collectRequiredActionInputs, collectResponseInputs, convertTurnsToThreadMessages, createDraftSessionBridge, createTrueFoundryDraftThreadListAdapter, createTrueFoundryThreadListAdapter, draftSessionTitle, findPausedAssistantMessage, getSession, getTurnMessageContent, mergeAgentSpec, messageHasPendingApprovals, messageHasPendingRequiredActions, messageHasPendingResponses, parseTurnIdFromMessageId, repositoryItemsFromMessages, toTrueFoundryApprovalInputs, trueFoundryAttachmentAdapter, trueFoundryExtras, useTrueFoundryAgentRuntime, useTrueFoundryAgentSpec, useTrueFoundryApprovals, useTrueFoundryCancel, useTrueFoundryDownloadSandboxFile, useTrueFoundryMcpAuth, useTrueFoundryResetFromTurn, useTrueFoundryRespondToToolApproval, useTrueFoundryRespondToToolResponse, useTrueFoundryResumeMcpAuth, useTrueFoundrySandboxId, useTrueFoundryToolResponses, useTrueFoundryUpdateAgentSpec };