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

package/src/turnEventHelpers.ts

@@ -0,0 +1,71 @@
+import type { Turn } from './server/index.js';
+
+import { buildMcpAuthTextParts, findMcpAuthRequired, mcpAuthAssistantStatus, mcpAuthMessageCustom } from './mcpAuth.js';
+import type { AssistantContentPart } from './modelMessageContent.js';
+import { findApprovalRequiredInTurn, toolApprovalMessageCustom, toolApprovalStatus } from './toolApproval.js';
+import { findResponseRequiredInTurn, toolResponseMessageCustom, toolResponseStatus } from './toolResponse.js';
+import type { TurnStreamUpdate } from './turnStreamUpdate.js';
+
+function buildToolApprovalUpdate(content: AssistantContentPart[], turn: Pick<Turn, 'state'>): TurnStreamUpdate {
+  const pendingApproval = findApprovalRequiredInTurn(turn);
+  if (pendingApproval == null) {
+    return { content };
+  }
+  return {
+    content,
+    status: toolApprovalStatus(),
+    metadata: { custom: toolApprovalMessageCustom(pendingApproval.threadId) },
+  };
+}
+
+function buildToolResponseUpdate(update: TurnStreamUpdate, turn: Pick<Turn, 'state'>): TurnStreamUpdate {
+  const pendingResponse = findResponseRequiredInTurn(turn);
+  if (pendingResponse == null) {
+    return update;
+  }
+  return {
+    ...update,
+    content: update.content,
+    status: toolResponseStatus(),
+    metadata: {
+      custom: {
+        ...update.metadata?.custom,
+        ...toolResponseMessageCustom(pendingResponse.threadId),
+      },
+    },
+  };
+}
+
+export function appendToolResponseToTurnContent(update: TurnStreamUpdate, turn: Pick<Turn, 'state'>): TurnStreamUpdate {
+  if (update.status?.type === 'requires-action') {
+    return update;
+  }
+  return buildToolResponseUpdate(update, turn);
+}
+
+export function appendToolApprovalToTurnContent(update: TurnStreamUpdate, turn: Pick<Turn, 'state'>): TurnStreamUpdate {
+  if (update.status?.type === 'requires-action') {
+    return update;
+  }
+  const approvalUpdate = buildToolApprovalUpdate(update.content, turn);
+  return appendToolResponseToTurnContent(approvalUpdate, turn);
+}
+
+export function appendMcpAuthToTurnContent(
+  content: AssistantContentPart[],
+  turn: Pick<Turn, 'state'>,
+): TurnStreamUpdate {
+  const pendingMcpAuth = findMcpAuthRequired(turn.state.status === 'done' ? turn.state.requiredActions : undefined);
+  if (pendingMcpAuth == null) {
+    return appendToolApprovalToTurnContent({ content }, turn);
+  }
+
+  return appendToolApprovalToTurnContent(
+    {
+      content: [...content, ...buildMcpAuthTextParts(pendingMcpAuth.mcpServers)],
+      status: mcpAuthAssistantStatus(),
+      metadata: { custom: mcpAuthMessageCustom(pendingMcpAuth.mcpServers) },
+    },
+    turn,
+  );
+}

package/src/turnStreamUpdate.ts

@@ -0,0 +1,11 @@
+import type { MessageStatus } from '@assistant-ui/core';
+
+import type { AssistantContentPart } from './modelMessageContent.js';
+
+export interface TurnStreamUpdate {
+  content: AssistantContentPart[];
+  status?: MessageStatus;
+  metadata?: {
+    custom?: Record<string, unknown>;
+  };
+}

package/src/types.ts

@@ -0,0 +1,84 @@
+import type {
+  AttachmentAdapter,
+  DictationAdapter,
+  ExternalStoreSharedOptions,
+  FeedbackAdapter,
+  RealtimeVoiceAdapter,
+  SpeechSynthesisAdapter,
+} from '@assistant-ui/core';
+
+import type { AgentChatServer, AgentSpec } from './server/types.js';
+
+export interface NamedAgentConfig {
+  mode: 'named';
+  agentName: string;
+}
+
+export interface DraftAgentConfig {
+  mode: 'draft';
+  defaultAgentSpec: AgentSpec;
+  onAgentSpecChange?: ((spec: AgentSpec) => void) | undefined;
+}
+
+export type TrueForgeAgentConfig = NamedAgentConfig | DraftAgentConfig;
+
+type TrueForgeAgentRuntimeBaseOptions = ExternalStoreSharedOptions & {
+  server: AgentChatServer;
+  initialSessionId?: string | undefined;
+  threadId?: string | undefined;
+  onThreadIdChange?: ((threadId: string | undefined) => void) | undefined;
+  onError?: ((error: unknown) => void) | undefined;
+  /**
+   * Optional filter forwarded to `listSessions({ agentId })`.
+   * Omit for all chats; hosts that key agents by name pass that name as the id.
+   */
+  listSessionsAgentId?: string | undefined;
+  /** Restrict thread history to sessions created by the authenticated subject. */
+  listSessionsCreatedByMe?: boolean | undefined;
+  adapters?:
+    | {
+        attachments?: AttachmentAdapter | undefined;
+        speech?: SpeechSynthesisAdapter | undefined;
+        dictation?: DictationAdapter | undefined;
+        voice?: RealtimeVoiceAdapter | undefined;
+        feedback?: FeedbackAdapter | undefined;
+      }
+    | undefined;
+};
+
+export type UseTrueForgeAgentRuntimeOptions = TrueForgeAgentRuntimeBaseOptions & {
+  /** Discriminated agent source. Omit when using legacy `agentName`. */
+  agent?: TrueForgeAgentConfig | undefined;
+  /** Legacy named-agent shorthand. Prefer `agent: { mode: "named", agentName }`. */
+  agentName?: string | undefined;
+};
+
+export type ResolvedTrueForgeAgentRuntimeOptions = TrueForgeAgentRuntimeBaseOptions & {
+  agent: TrueForgeAgentConfig;
+};
+
+export function resolveTrueForgeAgentConfig(
+  options: Pick<UseTrueForgeAgentRuntimeOptions, 'agent' | 'agentName'>,
+): TrueForgeAgentConfig {
+  if (options.agent != null) {
+    if (options.agent.mode === 'named' && options.agentName != null) {
+      return { mode: 'named', agentName: options.agentName };
+    }
+    return options.agent;
+  }
+  if (options.agentName != null) {
+    return { mode: 'named', agentName: options.agentName };
+  }
+  throw new Error('useTrueForgeAgentRuntime requires `agent` or legacy `agentName`.');
+}
+
+export function resolveTrueForgeAgentRuntimeOptions(
+  options: UseTrueForgeAgentRuntimeOptions,
+): ResolvedTrueForgeAgentRuntimeOptions {
+  const agent = resolveTrueForgeAgentConfig(options);
+
+  return {
+    ...options,
+    agent,
+  };
+}