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

package/src/sessionListStartTimestamp.ts

@@ -0,0 +1,6 @@
+/** ISO timestamp one year before now — used as `listSessions` `startTimestamp`. */
+export function sessionListStartTimestamp(): string {
+  const start = new Date();
+  start.setFullYear(start.getFullYear() - 1);
+  return start.toISOString();
+}

package/src/sessionSnapshot.ts

@@ -0,0 +1,146 @@
+import type {
+  McpAuthRequiredEvent,
+  Turn,
+  TurnCreatedEvent,
+  TurnDoneEvent,
+  TurnEvent,
+  TurnInputItem,
+} from './server/index.js';
+
+import { extractTurnUserText } from './extractTurnUserText.js';
+import { PeerThreadFoldState } from './foldPeerThreads.js';
+import type { StoredApprovalDecision } from './toolApproval.js';
+import type { StoredToolResponse } from './toolResponse.js';
+import type { TurnStreamUpdate } from './turnStreamUpdate.js';
+
+/** Session-level event item from `AgentSession.listEvents`. */
+export interface GatewaySessionEventItem {
+  turnId: string;
+  event: TurnCreatedEvent | TurnDoneEvent | TurnEvent;
+}
+
+/** Cursor for fetching older `listEvents` pages (scroll-up history). */
+export interface SessionHistoryPagination {
+  /** Token for the next older page; omit when exhausted. */
+  olderPageToken?: string | undefined;
+  hasOlder: boolean;
+}
+
+/** Turn metadata retained for cross-turn projection and subsequent required-action replay. */
+export type SessionTurnRecord = Pick<Turn, 'id' | 'createdAt' | 'state' | 'input'> & {
+  /** Denormalized from `input` for user/assistant interleaving during projection. */
+  userText?: string | undefined;
+  /** Root-thread `model.message` ids ingested with this turn (for per-group projection). */
+  rootModelMessageIds?: readonly string[] | undefined;
+  /** sandboxId observed via `sandbox.created` on this or an earlier turn (session-scoped). */
+  sandboxId?: string | undefined;
+};
+
+export interface RequiredActionsOverlay {
+  approvals: Map<string, StoredApprovalDecision>;
+  toolResponses: Map<string, StoredToolResponse>;
+}
+
+export interface ActiveStreamState {
+  turnId: string;
+  update: TurnStreamUpdate;
+  isContinuation: boolean;
+  streamComplete?: boolean | undefined;
+}
+
+export interface PendingUserMessage {
+  turnId: string;
+  /** Gateway user.message content (text-only string or text/file parts). */
+  content: Extract<TurnInputItem, { type: 'user.message' }>['content'];
+  createdAt: Date;
+}
+
+export interface SessionSnapshot {
+  fold: PeerThreadFoldState;
+  turns: SessionTurnRecord[];
+  pendingMcpAuth?: McpAuthRequiredEvent | undefined;
+  pendingUser?: PendingUserMessage | undefined;
+  activeStream?: ActiveStreamState | undefined;
+  /** Root `model.message` ids present before the active turn group started (streaming scope). */
+  groupRootBaseline?: readonly string[] | undefined;
+  requiredActions: RequiredActionsOverlay;
+  runningTurn?: Turn | undefined;
+  unstable_resume?: boolean | undefined;
+  /**
+   * Chronological `listEvents` items loaded so far (for prepend-on-scroll rebuild).
+   * Live stream commits are not appended here — they live in `turns` / `fold`.
+   */
+  historyEvents?: readonly GatewaySessionEventItem[] | undefined;
+  historyPagination?: SessionHistoryPagination | undefined;
+}
+
+export interface ProjectSessionMessagesOptions {
+  getCreatedAt?: (messageId: string, fallback: Date, replace?: boolean) => Date;
+}
+
+export function emptyRequiredActionsOverlay(): RequiredActionsOverlay {
+  return {
+    approvals: new Map(),
+    toolResponses: new Map(),
+  };
+}
+
+export function createEmptySessionSnapshot(): SessionSnapshot {
+  return {
+    fold: new PeerThreadFoldState(),
+    turns: [],
+    requiredActions: emptyRequiredActionsOverlay(),
+  };
+}
+
+export function turnToSessionRecord(turn: Turn): SessionTurnRecord {
+  const userText = extractTurnUserText(turn.input);
+  return {
+    id: turn.id,
+    ...(userText !== undefined ? { userText } : {}),
+    createdAt: turn.createdAt,
+    state: turn.state,
+    input: turn.input ?? [],
+  };
+}
+
+/** Builds a SessionTurnRecord from session-level TurnCreatedEvent + TurnDoneEvent data. */
+export function sessionEventsToSessionRecord(
+  turnId: string,
+  createdEvent: TurnCreatedEvent,
+  doneEvent: TurnDoneEvent,
+  rootModelMessageIds: readonly string[],
+  sandboxId?: string,
+): SessionTurnRecord {
+  const userText = extractTurnUserText(createdEvent.input);
+  return {
+    id: turnId,
+    ...(userText !== undefined ? { userText } : {}),
+    createdAt: createdEvent.createdAt,
+    state: doneEvent.state,
+    input: createdEvent.input ?? [],
+    rootModelMessageIds,
+    ...(sandboxId != null ? { sandboxId } : {}),
+  };
+}
+
+/** Returns a new snapshot wrapper; fold maps may be mutated in place before calling. */
+export function replaceSessionSnapshot(
+  snapshot: SessionSnapshot,
+  patch: Partial<Omit<SessionSnapshot, 'requiredActions'>> & {
+    requiredActions?: RequiredActionsOverlay;
+  },
+): SessionSnapshot {
+  return {
+    ...snapshot,
+    ...patch,
+    ...(patch.requiredActions != null ? { requiredActions: patch.requiredActions } : {}),
+  };
+}
+
+export function cloneRequiredActionsOverlay(overlay: RequiredActionsOverlay): RequiredActionsOverlay {
+  return {
+    approvals: new Map(overlay.approvals),
+    toolResponses: new Map(overlay.toolResponses),
+  };
+}

package/src/sessionThreadMetadata.ts

@@ -0,0 +1,36 @@
+import type { RemoteThreadMetadata } from '@assistant-ui/core';
+
+import { draftSessionTitle } from './draft/agentSpec.js';
+import type { AgentSpec, Session } from './server/types.js';
+
+/**
+ * Title for a session row in a mixed (draft + named) thread list.
+ * Mutable sessions use draftSessionTitle (optionally falling back to
+ * `defaultAgentSpec`); named sessions use title → agentName → id.
+ */
+export function sessionDisplayTitle(session: Session, defaultAgentSpec?: AgentSpec): string {
+  if (session.isMutable) {
+    const agentSpec = session.agentSpec ?? defaultAgentSpec;
+    if (agentSpec != null) {
+      return draftSessionTitle({
+        agentSpec,
+        ...(session.title === undefined ? {} : { title: session.title }),
+      });
+    }
+  }
+  return session.title ?? session.agentName ?? session.id;
+}
+
+/** Map a Session DTO onto RemoteThreadMetadata (mutability + display name in custom). */
+export function sessionToThreadMetadata(session: Session, title: string | undefined): RemoteThreadMetadata {
+  return {
+    status: 'regular',
+    remoteId: session.id,
+    title,
+    lastMessageAt: new Date(session.updatedAt),
+    custom: {
+      isMutable: session.isMutable,
+      ...(session.agentName != null ? { agentName: session.agentName } : {}),
+    },
+  };
+}

package/src/sessions.ts

@@ -0,0 +1,17 @@
+import type { AgentChatServer, Session } from './server/types.js';
+
+const inflightBySessionId = new Map<string, Promise<Session>>();
+
+/** `sessionId` is the assistant-ui thread `remoteId` from `RemoteThreadListAdapter.initialize`. */
+export function getSession(server: AgentChatServer, sessionId: string): Promise<Session> {
+  let inflight = inflightBySessionId.get(sessionId);
+  if (inflight == null) {
+    inflight = server.getSession({ sessionId }).finally(() => {
+      if (inflightBySessionId.get(sessionId) === inflight) {
+        inflightBySessionId.delete(sessionId);
+      }
+    });
+    inflightBySessionId.set(sessionId, inflight);
+  }
+  return inflight;
+}

package/src/streamTurn.ts

@@ -0,0 +1,118 @@
+import type { TurnStreamData } from './server/events.js';
+import type { AgentChatServer, PreviousTurnIdInput, TurnInputItem } from './server/types.js';
+
+import { streamTurnEvents, type UserMessageContent } from './convertTurnMessages.js';
+import { PeerThreadFoldState } from './foldPeerThreads.js';
+import type { RequiredActionInput } from './requiredActionInputs.js';
+import type { TurnStreamUpdate } from './turnStreamUpdate.js';
+
+export interface StreamTurnOptions {
+  userMessage?: UserMessageContent;
+  resumeMcpAuth?: boolean;
+  inputs?: RequiredActionInput[];
+  /**
+   * Branch anchor for createTurn. Omit for `"auto"`. Pass `"none"` for a fresh
+   * root turn.
+   */
+  previousTurnId?: PreviousTurnIdInput;
+  /** Extra headers for the turn request. */
+  headers?: Record<string, string>;
+}
+
+function buildTurnInput(options: StreamTurnOptions): TurnInputItem[] {
+  if (options.inputs != null) {
+    return options.inputs;
+  }
+  if (options.resumeMcpAuth === true) {
+    return [];
+  }
+  return [{ type: 'user.message', content: options.userMessage ?? '' }];
+}
+
+export async function* streamTurnContent(
+  server: AgentChatServer,
+  sessionId: string,
+  foldState: PeerThreadFoldState,
+  options: StreamTurnOptions,
+  abortSignal: AbortSignal,
+  groupRootBaseline?: readonly string[],
+  /**
+   * Called once with the turn ID as soon as it becomes available (first
+   * `turn.created` SSE event). Use this to reconcile the locally-generated
+   * optimistic ID with the real turn ID.
+   */
+  onTurnIdAvailable?: (turnId: string) => void,
+): AsyncGenerator<TurnStreamUpdate> {
+  // Aborting only detaches this client from the run; the turn keeps running on
+  // the backend so switching sessions (or remounting) can reattach via
+  // `subscribeToTurn`. Stopping the run is an explicit `cancelSession` call.
+  if (abortSignal.aborted) {
+    return;
+  }
+
+  let turnIdNotified = false;
+  const notifyTurnId = (turnId: string) => {
+    if (!turnIdNotified) {
+      onTurnIdAvailable?.(turnId);
+      turnIdNotified = true;
+    }
+  };
+
+  const stream: AsyncIterable<TurnStreamData> = server.createTurn({
+    sessionId,
+    input: buildTurnInput(options),
+    previousTurnId: options.previousTurnId ?? 'auto',
+    abortSignal,
+    ...(options.headers != null ? { headers: options.headers } : {}),
+  });
+
+  try {
+    for await (const update of streamTurnEvents(stream, foldState, groupRootBaseline, notifyTurnId)) {
+      yield update;
+    }
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      return;
+    }
+    throw error;
+  }
+}
+
+/** TODO: wire `afterSequenceNumber` from the last ingested stream event to skip replay on reconnect. */
+export async function* resumeTurnStream(
+  server: AgentChatServer,
+  sessionId: string,
+  turnId: string,
+  foldState: PeerThreadFoldState,
+  abortSignal: AbortSignal,
+  afterSequenceNumber?: number,
+  groupRootBaseline?: readonly string[],
+): AsyncGenerator<TurnStreamUpdate> {
+  // Optional on custom backends. Callers detect the gap and report it, so an
+  // empty stream here is safer than throwing mid-render.
+  if (server.subscribeToTurn == null) {
+    return;
+  }
+
+  if (abortSignal.aborted) {
+    return;
+  }
+
+  try {
+    yield* streamTurnEvents(
+      server.subscribeToTurn({
+        sessionId,
+        turnId,
+        ...(afterSequenceNumber != null ? { afterSequenceNumber } : {}),
+        abortSignal,
+      }),
+      foldState,
+      groupRootBaseline,
+    );
+  } catch (error) {
+    if (error instanceof Error && error.name === 'AbortError') {
+      return;
+    }
+    throw error;
+  }
+}