@truefoundry/assistant-ui-runtime 0.1.1 → 0.1.3-rc.1

package/README.md

@@ -338,6 +338,7 @@ void cancel();
 | `useTrueFoundryRespondToToolResponse()` | `(r: RespondToToolResponseOptions) => void` | Respond to an ask-user / `tool.response_required` prompt from any render context. |
 | `useTrueFoundryResumeMcpAuth()` | `() => Promise<void>` | Resume the paused turn after the user completes MCP OAuth in the browser. |
 | `useTrueFoundryCancel()` | `() => Promise<void>` | Cancel the active turn. Calls `session.cancel()` and drains the stream to its terminal `turn.done`. |
+| `useTrueFoundryHistoryPagination()` | `{ hasOlderHistory, isLoadingOlderHistory, loadOlderHistory }` | Scroll-up older history: call `loadOlderHistory()` when the user nears the top of the thread. |
 
 Where:
 
@@ -371,6 +372,13 @@ const pending = trueFoundryExtras.use((e) => e.pendingApprovals, []);
 | `respondToToolResponse` | `(r: { toolCallId, content }) => void` | Stage answer; batch-send when complete |
 | `resumeMcpAuth` | `() => Promise<void>` | Resume after OAuth |
 | `cancel` | `() => Promise<void>` | Cancel the active turn: calls `session.cancel()` and lets the stream drain to its terminal `turn.done` (reconciles on next session load) |
+| `resetFromTurn` | `(turnId: string) => Promise<void>` | Re-submit a user turn (branch/reset) |
+| `reload` | `() => void` | Retry the current session load |
+| `downloadSandboxFile` | `(path: string) => Promise<Blob>` | Download a file from the session sandbox |
+| `hasOlderHistory` | `boolean` | True when another older `listEvents` page is available |
+| `isLoadingOlderHistory` | `boolean` | True while `loadOlderHistory` is in flight |
+| `loadOlderHistory` | `() => Promise<void>` | Prepend the next older history window (scroll-up) |
+| `draft` | `TrueFoundryDraftRuntimeExtras \| null` | Draft-mode agent spec sync extras |
 
 Per-part `respondToApproval` from assistant-ui still works for root-thread tool UIs; extras complements that for global chrome and nested renderers.
 
@@ -388,6 +396,28 @@ Works out of the box — no server route or Redis store. TrueFoundry persists ev
 
 Contrast with the [AI SDK resumable streams guide](https://www.assistant-ui.com/docs/guides/resumable-streams), which requires a separate encoded-byte store.
 
+## History pagination
+
+Thread open no longer drains every turn. Initial load:
+
+1. `listTurns({ limit: 1 })` once — detect a running turn (does **not** walk `page_token`).
+2. One (or a few) `listEvents` page(s) for the newest complete user-message group.
+3. Clears `isLoading`, then resumes a running turn via subscribe if needed.
+
+Older history is opt-in via extras / `useTrueFoundryHistoryPagination()`:
+
+```tsx
+const { hasOlderHistory, isLoadingOlderHistory, loadOlderHistory } =
+  useTrueFoundryHistoryPagination();
+
+// e.g. IntersectionObserver at the top of the message list
+if (hasOlderHistory && !isLoadingOlderHistory) {
+  void loadOlderHistory();
+}
+```
+
+`loadOlderHistory` prepends older turns without aborting an active stream.
+
 ## Public API
 
 Everything below is exported from the package root (`truefoundry-agents-assistant-ui-runtime`).
@@ -403,6 +433,7 @@ Everything below is exported from the package root (`truefoundry-agents-assistan
 | `useTrueFoundryRespondToToolResponse` | hook | Same pattern for tool responses. |
 | `useTrueFoundryResumeMcpAuth` | hook | Same pattern for MCP resume. |
 | `useTrueFoundryCancel` | hook | Same pattern for cancel. |
+| `useTrueFoundryHistoryPagination` | hook | `{ hasOlderHistory, isLoadingOlderHistory, loadOlderHistory }` for scroll-up history. |
 | `trueFoundryExtras` | namespace | `createRuntimeExtras` channel — `.use()`, `.get(aui)`, `.provide()`. |
 | `TrueFoundryRuntimeExtras` | type | Shape provided into the runtime extras slot. |
 | `PendingApproval`, `PendingToolResponse` | types | Derived pending items for UI rendering. |

package/dist/index.d.ts

@@ -3,7 +3,9 @@ import { ExternalStoreSharedOptions, AttachmentAdapter, SpeechSynthesisAdapter,
 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 { PrivateAgentSessionClient } from 'truefoundry-gateway-sdk/agents/private';
+export { AgentDraftSession, PrivateAgentSessionClient } from 'truefoundry-gateway-sdk/agents/private';
+import { TruefoundryGatewayApi } from 'truefoundry-gateway-sdk';
 import * as _assistant_ui_core_internal from '@assistant-ui/core/internal';
 
 type AgentSpec = TruefoundryGatewayApi.AgentSpec;
@@ -53,8 +55,11 @@ type UseTrueFoundryAgentRuntimeOptions = TrueFoundryAgentRuntimeBaseOptions & {
     agent?: TrueFoundryAgentConfig | undefined;
     /** Legacy named-agent shorthand. Prefer `agent: { mode: "named", agentName }`. */
     agentName?: string | undefined;
-    /** Required when `agent.mode === "draft"`. */
-    gateway?: TrueFoundryGateway | undefined;
+    /**
+     * Required when `agent.mode === "draft"`. Also used for sandbox file downloads
+     * (named or draft).
+     */
+    privateClient?: PrivateAgentSessionClient | undefined;
 };
 
 declare function useTrueFoundryAgentRuntime(options: UseTrueFoundryAgentRuntimeOptions): _assistant_ui_core.AssistantRuntime;
@@ -178,16 +183,24 @@ declare function buildEditedUserMessageContent(editedText: string, originalInput
 declare function repositoryItemsFromMessages(messages: readonly ThreadMessage[]): ExportedMessageRepositoryItem[];
 
 declare function createTrueFoundryDraftThreadListAdapter(options: {
-    gateway: TrueFoundryGateway;
+    privateClient: PrivateAgentSessionClient;
     defaultAgentSpec: AgentSpec;
     getAgentSpec?: () => AgentSpec;
 }): RemoteThreadListAdapter;
 
+/**
+ * Read-only thread-list adapter backed by `PrivateAgentSessionClient.listOwnedSessions`.
+ * Returns every session the caller owns (named + draft), newest first.
+ */
+declare function createTrueFoundryOwnedSessionsThreadListAdapter(options: {
+    privateClient: PrivateAgentSessionClient;
+}): RemoteThreadListAdapter;
+
 type DraftSessionBridge = {
-    syncAgentSpec: (draftSessionId: string, agentSpec: AgentSpec) => Promise<void>;
+    syncAgentSpec: (draftSessionId: string, agentSpec: AgentSpec) => Promise<string>;
     getDraftAgentSpec: (draftSessionId: string) => Promise<AgentSpec>;
 };
-declare function createDraftSessionBridge(gateway: TrueFoundryGateway): DraftSessionBridge;
+declare function createDraftSessionBridge(privateClient: PrivateAgentSessionClient): DraftSessionBridge;
 
 type PendingApproval = {
     approvalId: string;
@@ -227,6 +240,9 @@ type TrueFoundryRuntimeExtras = {
     cancel: () => Promise<void>;
     resetFromTurn: (turnId: string) => Promise<void>;
     reload: () => void;
+    hasOlderHistory: boolean;
+    isLoadingOlderHistory: boolean;
+    loadOlderHistory: () => Promise<void>;
     draft: TrueFoundryDraftRuntimeExtras | null;
 };
 declare const trueFoundryExtras: _assistant_ui_core_internal.RuntimeExtras<TrueFoundryRuntimeExtras>;
@@ -262,6 +278,12 @@ declare const useTrueFoundryDownloadSandboxFile: () => (path: string) => Promise
 declare const useTrueFoundryCancel: () => () => Promise<void>;
 /** Returns a function to reload (retry) the current session from any render context. */
 declare const useTrueFoundryReload: () => () => void;
+/** Older history pagination state plus a load-more action for scroll-up. */
+declare const useTrueFoundryHistoryPagination: () => {
+    hasOlderHistory: boolean;
+    isLoadingOlderHistory: boolean;
+    loadOlderHistory: () => 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). */
@@ -288,8 +310,8 @@ declare function createTrueFoundryThreadListAdapter(options: {
 }): RemoteThreadListAdapter;
 
 type GetSessionOptions = {
-    /** When set, validates the draft and binds turns to `/agents/sessions/{id}/turns`. */
-    draftGateway?: TrueFoundryGateway;
+    /** When set, validates the draft and binds turns via PrivateAgentSessionClient. */
+    privateClient?: PrivateAgentSessionClient;
 };
 /** `sessionId` is the assistant-ui thread `remoteId` from `RemoteThreadListAdapter.initialize`. */
 declare function getSession(client: AgentSessionClient, sessionId: string, options?: GetSessionOptions): Promise<AgentSession>;
@@ -300,4 +322,4 @@ declare function getSession(client: AgentSessionClient, sessionId: string, optio
  */
 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, useTrueFoundryReload, useTrueFoundryResetFromTurn, useTrueFoundryRespondToToolApproval, useTrueFoundryRespondToToolResponse, useTrueFoundryResumeMcpAuth, useTrueFoundrySandboxId, useTrueFoundryToolResponses, useTrueFoundryUpdateAgentSpec };
+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, createTrueFoundryOwnedSessionsThreadListAdapter, createTrueFoundryThreadListAdapter, draftSessionTitle, findPausedAssistantMessage, getSession, getTurnMessageContent, mergeAgentSpec, messageHasPendingApprovals, messageHasPendingRequiredActions, messageHasPendingResponses, parseTurnIdFromMessageId, repositoryItemsFromMessages, toTrueFoundryApprovalInputs, trueFoundryAttachmentAdapter, trueFoundryExtras, useTrueFoundryAgentRuntime, useTrueFoundryAgentSpec, useTrueFoundryApprovals, useTrueFoundryCancel, useTrueFoundryDownloadSandboxFile, useTrueFoundryHistoryPagination, useTrueFoundryMcpAuth, useTrueFoundryReload, useTrueFoundryResetFromTurn, useTrueFoundryRespondToToolApproval, useTrueFoundryRespondToToolResponse, useTrueFoundryResumeMcpAuth, useTrueFoundrySandboxId, useTrueFoundryToolResponses, useTrueFoundryUpdateAgentSpec };