@truefoundry/trueforge-assistant-ui-runtime 0.0.0 → 0.2.0-rc.0

package/src/hooks.ts

@@ -0,0 +1,176 @@
+'use client';
+
+import { useAui, useAuiState } from '@assistant-ui/store';
+import { useMemo } from 'react';
+
+import type { RespondToToolApprovalOptions } from './toolApproval.js';
+import type { RespondToToolResponseOptions } from './toolResponse.js';
+import {
+  EMPTY_DRAFT_EXTRAS,
+  getTrueForgeExtras,
+  useTrueForgeRuntimeExtras,
+  type TrueForgeDraftRuntimeExtras,
+} from './trueforgeExtras.js';
+
+/** Pending tool approvals plus a respond action. */
+export const useTrueForgeApprovals = () => {
+  const extras = useTrueForgeRuntimeExtras();
+
+  return useMemo(
+    () => ({
+      pending: extras?.pendingApprovals ?? [],
+      respond:
+        extras?.respondToToolApproval ??
+        (() => {
+          throw new Error('TrueForge runtime is not ready yet');
+        }),
+    }),
+    [extras],
+  );
+};
+
+/** Pending ask-user tool responses plus a respond action. */
+export const useTrueForgeToolResponses = () => {
+  const extras = useTrueForgeRuntimeExtras();
+
+  return useMemo(
+    () => ({
+      pending: extras?.pendingToolResponses ?? [],
+      respond:
+        extras?.respondToToolResponse ??
+        (() => {
+          throw new Error('TrueForge runtime is not ready yet');
+        }),
+    }),
+    [extras],
+  );
+};
+
+/** Pending MCP OAuth plus a resume action. */
+export const useTrueForgeMcpAuth = () => {
+  const extras = useTrueForgeRuntimeExtras();
+
+  return useMemo(
+    () => ({
+      pending: extras?.pendingMcpAuth ?? null,
+      resume: extras?.resumeMcpAuth ?? (() => Promise.reject(new Error('TrueForge runtime is not ready yet'))),
+    }),
+    [extras],
+  );
+};
+
+/** Returns a function to respond to a tool approval from any render context. */
+export const useTrueForgeRespondToToolApproval = () => {
+  const aui = useAui();
+  return (response: RespondToToolApprovalOptions) => {
+    getTrueForgeExtras(aui).respondToToolApproval(response);
+  };
+};
+
+/** Returns a function to respond to a pending tool response from any render context. */
+export const useTrueForgeRespondToToolResponse = () => {
+  const aui = useAui();
+  return (response: RespondToToolResponseOptions) => {
+    getTrueForgeExtras(aui).respondToToolResponse(response);
+  };
+};
+
+/** Returns a function to resume after MCP OAuth from any render context. */
+export const useTrueForgeResumeMcpAuth = () => {
+  const aui = useAui();
+  return () => getTrueForgeExtras(aui).resumeMcpAuth();
+};
+
+/** Current sandboxId for this session, if a sandbox has been created. */
+export const useTrueForgeSandboxId = (): string | undefined => useTrueForgeRuntimeExtras()?.sandboxId;
+
+/** Turn that produced the message being rendered. Only defined inside a message scope. */
+export const useTrueForgeTurnId = (): string | undefined =>
+  useAuiState(state => {
+    const turnId = state.message.metadata.custom['turnId'];
+    return typeof turnId === 'string' ? turnId : undefined;
+  });
+
+/**
+ * Returns a function to download a file the current turn wrote to its sandbox. Must be called
+ * from a message scope, since the artifact belongs to the turn that rendered it.
+ * Does not require extras `sandboxId` — turn-scoped hosts resolve the sandbox from `turnId`.
+ */
+export const useTrueForgeDownloadSandboxFile = () => {
+  const aui = useAui();
+  const turnId = useTrueForgeTurnId();
+  return (path: string) => {
+    if (turnId == null) {
+      throw new Error('Downloading a sandbox file requires a message scope to resolve its turn.');
+    }
+    return getTrueForgeExtras(aui).downloadSandboxFile({ turnId, path });
+  };
+};
+
+/** Returns a function to cancel the current run from any render context. */
+export const useTrueForgeCancel = () => {
+  const aui = useAui();
+  return () => getTrueForgeExtras(aui).cancel();
+};
+
+/** Returns a function to reload (retry) the current session from any render context. */
+export const useTrueForgeReload = () => {
+  const aui = useAui();
+  return () => {
+    getTrueForgeExtras(aui).reload();
+  };
+};
+
+/** Older history pagination state plus a load-more action for scroll-up. */
+export const useTrueForgeHistoryPagination = () => {
+  const extras = useTrueForgeRuntimeExtras();
+
+  return useMemo(
+    () => ({
+      hasOlderHistory: extras?.hasOlderHistory ?? false,
+      isLoadingOlderHistory: extras?.isLoadingOlderHistory ?? false,
+      loadOlderHistory:
+        extras?.loadOlderHistory ?? (() => Promise.reject(new Error('TrueForge runtime is not ready yet'))),
+    }),
+    [extras],
+  );
+};
+
+/**
+ * True while a turn runs that this server cannot stream, so its result will not
+ * arrive in this client. Falls back to `false` on runtimes that predate the flag.
+ */
+export const useTrueForgeResumeUnavailable = () => useTrueForgeRuntimeExtras()?.resumeUnavailable ?? false;
+
+/** Returns a function to reset (re-submit) a user turn from any render context. */
+export const useTrueForgeResetFromTurn = () => {
+  const aui = useAui();
+  return (turnId: string) => getTrueForgeExtras(aui).resetFromTurn(turnId);
+};
+
+/** Current draft agent spec and sync state (draft mode only). */
+export const useTrueForgeAgentSpec = () => {
+  const extras = useTrueForgeRuntimeExtras()?.draft ?? null;
+
+  return useMemo(() => ({ ...EMPTY_DRAFT_EXTRAS, ...extras }), [extras]);
+};
+
+/** Returns a draft spec updater from any render context. */
+export const useTrueForgeUpdateAgentSpec = () => {
+  const aui = useAui();
+  return (update: Parameters<TrueForgeDraftRuntimeExtras['updateAgentSpec']>[0]) =>
+    getTrueForgeExtras(aui).draft?.updateAgentSpec(update);
+};
+
+/** Flushes any pending draft-spec synchronization before a coordinated write. */
+export const useTrueForgeFlushAgentSpec = () => {
+  const aui = useAui();
+  return () => getTrueForgeExtras(aui).draft?.flushAgentSpec() ?? Promise.resolve();
+};
+
+/** Adopts a spec already persisted by another server operation without syncing again. */
+export const useTrueForgeAdoptAgentSpec = () => {
+  const aui = useAui();
+  return (request: Parameters<TrueForgeDraftRuntimeExtras['adoptAgentSpec']>[0]) =>
+    getTrueForgeExtras(aui).draft?.adoptAgentSpec(request);
+};

package/src/index.ts

@@ -0,0 +1,227 @@
+/// <reference types="@assistant-ui/core/react" />
+
+export { trueForgeAttachmentAdapter } from './attachmentAdapter.js';
+export type { PendingApproval, PendingToolResponse } from './collectPending.js';
+export { ROOT_THREAD_ID } from './constants.js';
+export {
+  buildEditedUserMessageContent,
+  buildTurnAssistantContent,
+  buildUserMessageContent,
+  convertTurnsToThreadMessages,
+  getTurnMessageContent,
+  parseTurnIdFromMessageId,
+  repositoryItemsFromMessages,
+} from './convertTurnMessages.js';
+export type { ConvertTurnsResult, UserMessageContent } from './convertTurnMessages.js';
+export { draftSessionTitle, mergeAgentSpec } from './draft/agentSpec.js';
+export type { AgentSpecUpdate, DraftSession } from './draft/agentSpec.js';
+export { createDraftSessionBridge } from './draft/draftSessionBridge.js';
+export type { DraftSessionBridge } from './draft/draftSessionBridge.js';
+export { createTrueForgeDraftThreadListAdapter } from './draft/trueforgeDraftThreadListAdapter.js';
+export type { SubAgentArtifact, SubAgentCustomMetadata } from './foldPeerThreads.js';
+export {
+  useTrueForgeAdoptAgentSpec,
+  useTrueForgeAgentSpec,
+  useTrueForgeApprovals,
+  useTrueForgeCancel,
+  useTrueForgeDownloadSandboxFile,
+  useTrueForgeFlushAgentSpec,
+  useTrueForgeHistoryPagination,
+  useTrueForgeMcpAuth,
+  useTrueForgeReload,
+  useTrueForgeResetFromTurn,
+  useTrueForgeRespondToToolApproval,
+  useTrueForgeRespondToToolResponse,
+  useTrueForgeResumeMcpAuth,
+  useTrueForgeResumeUnavailable,
+  useTrueForgeSandboxId,
+  useTrueForgeToolResponses,
+  useTrueForgeTurnId,
+  useTrueForgeUpdateAgentSpec,
+} from './hooks.js';
+export type {
+  McpAuthMessageCustomMetadata,
+  SandboxMessageCustomMetadata,
+  SubAgentMessageCustomMetadata,
+  ToolApprovalMessageCustomMetadata,
+  ToolResponseMessageCustomMetadata,
+  TrueForgeMessageCustomMetadata,
+} from './messageCustomMetadata.js';
+export {
+  collectRequiredActionInputs,
+  findPausedAssistantMessage,
+  messageHasPendingRequiredActions,
+} from './requiredActionInputs.js';
+export { getSession } from './sessions.js';
+export { collectApprovalInputs, messageHasPendingApprovals, toTrueForgeApprovalInputs } from './toolApproval.js';
+export {
+  TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY,
+  collectResponseInputs,
+  messageHasPendingResponses,
+} from './toolResponse.js';
+export { getTrueForgeExtras, trueForgeExtras, tryGetTrueForgeExtras } from './trueforgeExtras.js';
+export type { TrueForgeDraftRuntimeExtras, TrueForgeRuntimeExtras } from './trueforgeExtras.js';
+export { createTrueForgeOwnedSessionsThreadListAdapter } from './trueforgeOwnedSessionsThreadListAdapter.js';
+export { createTrueForgeThreadListAdapter } from './trueforgeThreadListAdapter.js';
+export type {
+  DraftAgentConfig,
+  NamedAgentConfig,
+  TrueForgeAgentConfig,
+  UseTrueForgeAgentRuntimeOptions,
+} from './types.js';
+export { useTrueForgeAgentRuntime } from './useTrueForgeAgentRuntime.js';
+
+export { isEventDelta, mergeEventDelta } from './server/index.js';
+export type {
+  AgentBuilderCapabilitiesResponse,
+  AgentBuilderServer,
+  AgentCapabilityConfig,
+  AgentChatServer,
+  AgentCompactionConfig,
+  AgentContextManagementConfig,
+  AgentDetail,
+  AgentInputTokensCompactionTrigger,
+  AgentLibraryEntry,
+  AgentMetricChartData,
+  AgentMetricChartDataRequest,
+  AgentMetricChartDefinition,
+  AgentMetricChartType,
+  AgentMetricGraph,
+  AgentMetricGraphLine,
+  AgentMetricMeter,
+  AgentMetricPoint,
+  AgentMetricRangeRequest,
+  AgentMetricsServer,
+  AgentRuntimeConfig,
+  AgentSandboxConfig,
+  AgentSelectorEntry,
+  AgentSessionsServer,
+  AgentSkill,
+  AgentSpec,
+  AgentUIServer,
+  AgentUIServerPort,
+  ApprovalDecision,
+  AuthenticateConnectorRequest,
+  CatalogServer,
+  CodeSnippet,
+  CodeSnippetSampleCode,
+  ConnectorAuth,
+  ConnectorAuthApiKey,
+  ConnectorAuthNone,
+  ConnectorAuthOAuth,
+  ConnectorAuthPublic,
+  ConnectorAuthPublicApiKey,
+  ConnectorAuthPublicNone,
+  ConnectorAuthPublicOAuth,
+  ConnectorAuthType,
+  ConnectorAuthenticationResult,
+  ConnectorBase,
+  ConnectorCatalogEntry,
+  ConnectorCatalogServer,
+  ConnectorConfigBase,
+  ConnectorSelectorEntry,
+  ConnectorState,
+  CreateConnectorRequest,
+  CreateModelProviderRequest,
+  CreateSandboxProviderRequest,
+  CreateSandboxRequest,
+  CreateScheduleRequest,
+  CreateScheduleRunRequest,
+  CreateSessionRequest,
+  CreateSkillRequest,
+  CreateSkillRequestBase,
+  CreateWebSearchProviderRequest,
+  CreateWebSearchRequest,
+  CreatedBySubject,
+  DefinedSkill,
+  GithubSkill,
+  ImportGithubSkillRequest,
+  ListPermissionsRequest,
+  ListPermissionsResponse,
+  ListResult,
+  ListSchedulesParams,
+  ListSessionEventsParams,
+  ListSessionsOrder,
+  ListSessionsParams,
+  McpAuthRequiredEvent,
+  McpServerMount,
+  McpToolSelection,
+  Model,
+  ModelCatalogServer,
+  ModelEntry,
+  ModelMessageEvent,
+  ModelParams,
+  ModelProperties,
+  ModelProviderBase,
+  ModelProviderCatalogEntry,
+  ModelProviderConfigBase,
+  ModelSelection,
+  ModelSelectorEntry,
+  PageParams,
+  PermissionResourceType,
+  PermissionsServer,
+  PreviousTurnIdInput,
+  ProviderEntry,
+  ProviderType,
+  RegistrySkill,
+  ResourcePermission,
+  SandboxBase,
+  SandboxCatalogEntry,
+  SandboxCatalogServer,
+  SandboxConfig,
+  SandboxCreatedEvent,
+  SandboxProviderBase,
+  SandboxProviderCatalogEntry,
+  SandboxProviderConfig,
+  SandboxProviderListEntry,
+  SandboxSnapshotSyncStatus,
+  SaveAgentRequest,
+  SaveAgentResult,
+  Schedule,
+  ScheduleRun,
+  ScheduleRunStatus,
+  ScheduleServer,
+  ScheduleStatus,
+  SearchAgentSelectorParams,
+  SearchAgentsParams,
+  SelectRegistrySkillRequest,
+  Session,
+  SessionEventItem,
+  SessionListEntry,
+  SessionListMetrics,
+  SkillBase,
+  SkillCatalogEntry,
+  SkillCatalogServer,
+  SkillConfigBase,
+  SkillMount,
+  SkillSelectorEntry,
+  ThreadCreatedEvent,
+  ToolApprovalRequiredEvent,
+  ToolBase,
+  ToolCall,
+  ToolResponseRequiredEvent,
+  Turn,
+  TurnDoneMetrics,
+  TurnEvent,
+  TurnInputItem,
+  TurnState,
+  TurnStateDone,
+  TurnStreamData,
+  TurnStreamingEvent,
+  UpdateConnectorRequest,
+  UpdateModelProviderRequest,
+  UpdateSandboxProviderRequest,
+  UpdateSandboxRequest,
+  UpdateScheduleRequest,
+  UpdateSessionRequest,
+  UpdateWebSearchProviderRequest,
+  UpdateWebSearchRequest,
+  UserMessage,
+  UserToolApprovalEvent,
+  UserToolResponseEvent,
+  WebSearchBase,
+  WebSearchCatalogEntry,
+  WebSearchCatalogServer,
+  WebSearchProviderBase,
+  WebSearchProviderCatalogEntry,
+} from './server/index.js';

package/src/lastUserMessageText.ts

@@ -0,0 +1,19 @@
+import type { ThreadMessage } from '@assistant-ui/core';
+
+export function lastUserMessageText(messages: readonly ThreadMessage[]): string {
+  for (let i = messages.length - 1; i >= 0; i--) {
+    const message = messages[i];
+    if (message?.role !== 'user') {
+      continue;
+    }
+    const text = message.content
+      .filter(part => part.type === 'text')
+      .map(part => part.text)
+      .join('\n')
+      .trim();
+    if (text) {
+      return text;
+    }
+  }
+  throw new Error('No user message with text content found.');
+}

package/src/listPages.ts

@@ -0,0 +1,19 @@
+import type { ListResult } from './server/types.js';
+
+/**
+ * Drains all pages of a token-paginated list into a single array.
+ * Newest-first APIs should reverse after calling this.
+ */
+export async function drainListPages<T>(fetchPage: (pageToken?: string) => Promise<ListResult<T>>): Promise<T[]> {
+  const items: T[] = [];
+  let pageToken: string | undefined;
+  for (;;) {
+    const page = await fetchPage(pageToken);
+    items.push(...page.data);
+    if (page.nextPageToken == null || page.nextPageToken === '') {
+      break;
+    }
+    pageToken = page.nextPageToken;
+  }
+  return items;
+}

package/src/loadSessionSnapshot.ts

@@ -0,0 +1,34 @@
+import type { AgentChatServer } from './server/types.js';
+
+import { buildSnapshotFromSessionEvents } from './convertTurnMessages.js';
+import { getSession } from './sessions.js';
+import type { SessionSnapshot } from './sessionSnapshot.js';
+
+const inflightBySessionId = new Map<string, Promise<SessionSnapshot>>();
+
+/**
+ * Loads a session snapshot once per concurrent burst for a given session id.
+ * React Strict Mode and overlapping fetch/load paths share the same in-flight
+ * request instead of duplicating getSession + listEvents calls.
+ *
+ * `onProgress` is called after each complete turn is ingested so the caller
+ * can update the UI progressively while history is being processed.
+ */
+export function loadSessionSnapshot(
+  server: AgentChatServer,
+  sessionId: string,
+  onProgress?: (snap: SessionSnapshot) => void,
+): Promise<SessionSnapshot> {
+  let inflight = inflightBySessionId.get(sessionId);
+  if (inflight == null) {
+    inflight = getSession(server, sessionId)
+      .then(() => buildSnapshotFromSessionEvents(server, sessionId, onProgress))
+      .finally(() => {
+        if (inflightBySessionId.get(sessionId) === inflight) {
+          inflightBySessionId.delete(sessionId);
+        }
+      });
+    inflightBySessionId.set(sessionId, inflight);
+  }
+  return inflight;
+}

package/src/mcpAuth.ts

@@ -0,0 +1,35 @@
+import type { MessageStatus } from '@assistant-ui/core';
+import type { McpAuthRequiredEvent, TurnStateDone } from './server/index.js';
+
+import type { McpAuthMessageCustomMetadata } from './messageCustomMetadata.js';
+import type { AssistantContentPart } from './modelMessageContent.js';
+
+/** `runConfig.custom` flag: resume after MCP OAuth with an empty SDK turn input. */
+export const MCP_AUTH_RESUME_RUN_CUSTOM_KEY = 'resumeMcpAuth';
+
+type McpServerAuthInfo = McpAuthRequiredEvent['mcpServers'][number];
+
+export function buildMcpAuthTextParts(servers?: readonly McpServerAuthInfo[]): AssistantContentPart[] {
+  void servers;
+  const text = [
+    'This agent needs access to external services before it can continue.',
+    '',
+    'Click the **Connect** button(s) to authorize the Connectors, then press **Continue**.',
+  ].join('\n');
+  return [{ type: 'text', text }];
+}
+
+export function findMcpAuthRequired(
+  requiredActions: TurnStateDone['requiredActions'] | undefined,
+): McpAuthRequiredEvent | undefined {
+  const found = requiredActions?.find(action => action.type === 'mcp.auth_required');
+  return found?.type === 'mcp.auth_required' ? found : undefined;
+}
+
+export function mcpAuthAssistantStatus(): MessageStatus {
+  return { type: 'requires-action', reason: 'interrupt' };
+}
+
+export function mcpAuthMessageCustom(servers: readonly McpServerAuthInfo[]): McpAuthMessageCustomMetadata {
+  return { pendingMcpAuth: true, mcpServers: [...servers] };
+}

package/src/messageCustomMetadata.ts

@@ -0,0 +1,50 @@
+import type { McpAuthRequiredEvent } from './server/index.js';
+
+import type { SubAgentCustomMetadata } from './foldPeerThreads.js';
+import { TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY } from './toolApproval.js';
+import { TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY } from './toolResponse.js';
+
+/** Keys written to `ThreadMessage.metadata.custom` by this runtime adapter. */
+export interface TrueForgeMessageCustomMetadata {
+  subAgent?: SubAgentCustomMetadata;
+  pendingMcpAuth?: true;
+  mcpServers?: McpAuthRequiredEvent['mcpServers'];
+  sandboxId?: string;
+  /** Turn that produced this message. Scopes artifact downloads to their own turn. */
+  turnId?: string;
+  [TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY]?: string;
+  [TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY]?: string;
+}
+
+export type SubAgentMessageCustomMetadata = Pick<TrueForgeMessageCustomMetadata, 'subAgent'>;
+
+export type McpAuthMessageCustomMetadata = Pick<TrueForgeMessageCustomMetadata, 'pendingMcpAuth' | 'mcpServers'>;
+
+export type SandboxMessageCustomMetadata = Pick<TrueForgeMessageCustomMetadata, 'sandboxId'>;
+
+export type ToolApprovalMessageCustomMetadata = Pick<
+  TrueForgeMessageCustomMetadata,
+  typeof TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY
+>;
+
+export type ToolResponseMessageCustomMetadata = Pick<
+  TrueForgeMessageCustomMetadata,
+  typeof TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY
+>;
+
+export function isUnknownRecord(value: unknown): value is Record<PropertyKey, unknown> {
+  return value != null && typeof value === 'object' && !Array.isArray(value);
+}
+
+export function isMcpServerAuthInfoList(value: unknown): value is McpAuthRequiredEvent['mcpServers'] {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      server =>
+        isUnknownRecord(server) &&
+        typeof server['id'] === 'string' &&
+        typeof server['name'] === 'string' &&
+        typeof server['authUrl'] === 'string',
+    )
+  );
+}