@truefoundry/assistant-ui-runtime 0.1.5 → 0.1.6

package/src/server/events.ts

@@ -0,0 +1,246 @@
+/**
+ * Runtime-owned turn/stream event protocol.
+ *
+ * Hosts must emit events matching these shapes. The TFY adapter maps
+ * truefoundry-gateway-sdk events 1:1 onto these types.
+ */
+
+import type { TurnInputItem, TurnState } from "./types.js";
+
+// ---------------------------------------------------------------------------
+// Tool call shapes
+// ---------------------------------------------------------------------------
+
+export interface ToolCallFunction {
+    name: string;
+    arguments: string;
+}
+
+export type ToolInfo =
+    | { type: "truefoundry-system"; name: string }
+    | { type: "mcp"; serverId: string; serverName: string; name: string }
+    | { type: string; name?: string; [key: string]: unknown };
+
+export interface ToolCall {
+    id: string;
+    type: "function";
+    function: ToolCallFunction;
+    toolInfo?: ToolInfo;
+    providerSpecificFields?: Record<string, unknown>;
+}
+
+/** Ref used by approval/response-required events. */
+export interface ToolCallRef {
+    id: string;
+    sourceEventId: string;
+}
+
+export interface ChunkDeltaToolCall {
+    index: number;
+    id?: string;
+    type?: "function";
+    function?: { name?: string; arguments?: string };
+    toolInfo?: ToolInfo;
+    providerSpecificFields?: Record<string, unknown>;
+}
+
+// ---------------------------------------------------------------------------
+// Content events
+// ---------------------------------------------------------------------------
+
+export type ModelMessageContentPart =
+    | { type: "text"; text: string }
+    | { type: "refusal"; refusal: string }
+    | { type: "image_url"; image_url: { url: string } };
+
+export interface ModelMessageEvent {
+    type: "model.message";
+    id: string;
+    threadId: string;
+    content?: string | ModelMessageContentPart[] | null;
+    name?: string;
+    refusal?: string | null;
+    reasoningContent?: string;
+    toolCalls?: ToolCall[];
+    finishReason?: string | null;
+    createdAt: string;
+    usage?: unknown;
+}
+
+export interface ModelMessageDeltaEvent {
+    type: "model.message.delta";
+    id: string;
+    threadId: string;
+    content?: string | null;
+    refusal?: string | null;
+    reasoningContent?: string;
+    toolCalls?: ChunkDeltaToolCall[];
+    finishReason?: string | null;
+    createdAt?: string;
+    usage?: unknown;
+    /** Extended content-block deltas (image streaming). */
+    contentBlocks?: Array<{
+        index: number;
+        delta:
+            | { type: "text"; text?: string }
+            | { type: "image_url"; image_url?: { url?: string } };
+    }>;
+    content_blocks?: Array<{
+        index: number;
+        delta:
+            | { type: "text"; text?: string }
+            | { type: "image_url"; image_url?: { url?: string } };
+    }>;
+}
+
+export interface ToolResponseEvent {
+    type: "tool.response";
+    id: string;
+    threadId: string;
+    toolCallId: string;
+    content: string;
+    createdAt: string;
+}
+
+export interface ToolApprovalRequiredEvent {
+    type: "tool.approval_required";
+    id: string;
+    createdAt: string;
+    threadId: string;
+    toolCalls: ToolCallRef[];
+}
+
+export interface ToolResponseRequiredEvent {
+    type: "tool.response_required";
+    id: string;
+    createdAt: string;
+    threadId: string;
+    toolCalls: ToolCallRef[];
+}
+
+export interface AgentInfo {
+    type?: string;
+    name: string;
+    input: string;
+    model?: string;
+}
+
+export interface AgentParent {
+    threadId: string;
+    toolCallId: string;
+}
+
+export interface ThreadCreatedEvent {
+    type: "thread.created";
+    id: string;
+    threadId: string;
+    title: string;
+    agentInfo: AgentInfo;
+    parent: AgentParent;
+    createdAt: string;
+}
+
+export interface ThreadDoneEvent {
+    type: "thread.done";
+    id: string;
+    threadId: string;
+    title?: string;
+    createdAt: string;
+    state?: unknown;
+}
+
+export interface McpServerAuthInfo {
+    id: string;
+    name: string;
+    authUrl: string;
+}
+
+export interface McpAuthRequiredEvent {
+    type: "mcp.auth_required";
+    id: string;
+    createdAt: string;
+    threadId?: string | null;
+    mcpServers: McpServerAuthInfo[];
+}
+
+export interface SandboxCreatedEvent {
+    type: "sandbox.created";
+    id: string;
+    createdAt: string;
+    sandboxId: string;
+    threadId: string | null;
+}
+
+export interface McpInitializeEvent {
+    type: "mcp.initialize";
+    id: string;
+    createdAt: string;
+    threadId: string | null;
+    [key: string]: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Turn lifecycle events
+// ---------------------------------------------------------------------------
+
+export interface TurnCreatedEvent {
+    type: "turn.created";
+    id: string;
+    turnId: string;
+    previousTurnId?: string | null;
+    input?: TurnInputItem[];
+    state?: { status: "running" };
+    createdAt: string;
+    threadId?: string | null;
+}
+
+export interface TurnDoneEvent {
+    type: "turn.done";
+    id: string;
+    state: Exclude<TurnState, { status: "running" }>;
+    createdAt: string;
+    threadId?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Unions
+// ---------------------------------------------------------------------------
+
+/** Events stored in fold buckets (non-delta, non-turn-lifecycle). */
+export type TurnEvent =
+    | ModelMessageEvent
+    | ToolResponseEvent
+    | ThreadCreatedEvent
+    | ThreadDoneEvent
+    | McpAuthRequiredEvent
+    | McpInitializeEvent
+    | SandboxCreatedEvent
+    | ToolApprovalRequiredEvent
+    | ToolResponseRequiredEvent;
+
+/** Full streaming event union (includes deltas + turn lifecycle). */
+export type TurnStreamingEvent =
+    | TurnEvent
+    | ModelMessageDeltaEvent
+    | TurnCreatedEvent
+    | TurnDoneEvent;
+
+export type ActionRequiredEvent =
+    | ToolApprovalRequiredEvent
+    | ToolResponseRequiredEvent
+    | McpAuthRequiredEvent;
+
+export interface TurnStreamData<
+    TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent,
+> {
+    sequenceNumber: number;
+    event: TStreamEvent;
+}
+
+/** Session-level event item from `listEvents`. */
+export interface SessionEventItem {
+    turnId: string;
+    event: TurnCreatedEvent | TurnDoneEvent | TurnEvent;
+}
+
+export type DeltaEvents = ModelMessageDeltaEvent;

package/src/server/index.ts

@@ -0,0 +1,66 @@
+export type {
+    ModelSelectorEntry,
+    SkillSelectorEntry,
+    ConnectorSelectorEntry,
+    AgentSelectorEntry,
+    SearchAgentSelectorParams,
+    SkillMount,
+    McpServerMount,
+    ModelParams,
+    Model,
+    AgentSpec,
+    Session,
+    CreateSessionRequest,
+    UpdateSessionRequest,
+    ListResult,
+    ListSessionsOrder,
+    PageParams,
+    ListSessionsParams,
+    PreviousTurnIdInput,
+    UserMessageContent,
+    UserMessage,
+    ApprovalDecision,
+    UserToolApprovalEvent,
+    UserToolResponseEvent,
+    TurnInputItem,
+    TurnStateRunning,
+    TurnStateDone,
+    TurnStateCancelled,
+    TurnStateError,
+    TurnState,
+    Turn,
+    AgentChatServer,
+    AgentBuilderServer,
+} from "./types.js";
+
+export type {
+    ToolCallFunction,
+    ToolInfo,
+    ToolCall,
+    ToolCallRef,
+    ChunkDeltaToolCall,
+    ModelMessageContentPart,
+    ModelMessageEvent,
+    ModelMessageDeltaEvent,
+    ToolResponseEvent,
+    ToolApprovalRequiredEvent,
+    ToolResponseRequiredEvent,
+    AgentInfo,
+    AgentParent,
+    ThreadCreatedEvent,
+    ThreadDoneEvent,
+    McpServerAuthInfo,
+    McpAuthRequiredEvent,
+    SandboxCreatedEvent,
+    McpInitializeEvent,
+    TurnCreatedEvent,
+    TurnDoneEvent,
+    TurnEvent,
+    TurnStreamingEvent,
+    ActionRequiredEvent,
+    TurnStreamData,
+    SessionEventItem,
+    DeltaEvents,
+} from "./events.js";
+
+export { isEventDelta, mergeEventDelta } from "./eventUtils.js";

package/src/server/types.ts

@@ -0,0 +1,319 @@
+/**
+ * FE-owned AgentUIServer contract.
+ *
+ * Rule: only methods/fields the runtime or UI invokes.
+ * Hosts extend via `T extends Base` for system-specific extras.
+ * No dependency on truefoundry-gateway-sdk.
+ */
+
+import type {
+    ActionRequiredEvent,
+    SessionEventItem,
+    TurnEvent,
+    TurnStreamData,
+    TurnStreamingEvent,
+} from "./events.js";
+
+// ---------------------------------------------------------------------------
+// Catalog — selector rows (SDK-minimal; host extends via generics)
+// ---------------------------------------------------------------------------
+
+/** Model selector row. Host extends for apiModel, modelId, pricing, etc. */
+export interface ModelSelectorEntry {
+    name: string;
+    provider: string;
+}
+
+/** Skill selector row. Host extends for fqn, preload, etc. */
+export interface SkillSelectorEntry {
+    id: string;
+    name: string;
+    description?: string;
+}
+
+/** MCP connector selector row. Host extends for type, enableTools, url, etc. */
+export interface ConnectorSelectorEntry {
+    id: string;
+    name: string;
+    description?: string;
+}
+
+/** Agent selector row — UI shows name only. Host extends for metadata. */
+export interface AgentSelectorEntry {
+    name: string;
+}
+
+export type SearchAgentSelectorParams = {
+    query?: string;
+    limit?: number;
+    offset?: number;
+};
+
+// ---------------------------------------------------------------------------
+// Mounts — neutral SDK base (host extends with backend-specific fields)
+// ---------------------------------------------------------------------------
+
+/**
+ * Mounts written to AgentSpec.skills[] / AgentSpec.mcpServers[].
+ *
+ * These are opaque to the runtime — it stores and forwards them but never reads
+ * a field, and the backend owns the shape (the gateway identifies a skill by
+ * `fqn`, with no `id` or `name` anywhere). So the base constrains only that a
+ * mount is an object; hosts intersect their concrete mount type over it, as
+ * `TfySkillMount` / `TfyMcpServerMount` do in the gateway adapter.
+ *
+ * Naming a field here would not just be unread, it would be wrong: a base with
+ * required fields rejects the backend's own payloads, and one with only optional
+ * fields is a weak type, which TypeScript rejects for a source that shares no
+ * property with it — the gateway's registry skill shares none.
+ */
+export type SkillMount = object;
+
+export type McpServerMount = object;
+
+// ---------------------------------------------------------------------------
+// AgentSpec — model + skills + mcpServers on base; host widens the rest
+// ---------------------------------------------------------------------------
+
+export interface ModelParams {
+    maxTokens?: number;
+    reasoningEffort?: string;
+}
+
+export interface Model {
+    name: string;
+    params?: ModelParams;
+}
+
+/**
+ * SDK-owned agent definition — fields the FE reads/writes.
+ * Host adds additional fields via `TSpec extends AgentSpec`.
+ */
+export interface AgentSpec {
+    model: Model;
+    skills?: SkillMount[];
+    mcpServers?: McpServerMount[];
+    instructions?: string;
+    messages?: unknown[];
+    variables?: Record<string, string>;
+    responseFormat?: unknown;
+    config?: unknown;
+}
+
+// ---------------------------------------------------------------------------
+// Session — plain DTO, generic in TSpec so host's spec type flows through
+// ---------------------------------------------------------------------------
+
+export interface Session<TSpec extends AgentSpec = AgentSpec> {
+    id: string;
+    title?: string | null;
+    agentName?: string | null;
+    agentSpec?: TSpec;
+    /** true → mutable builder + updateSession(spec) allowed. */
+    isMutable: boolean;
+    createdAt: string;
+    updatedAt: string;
+}
+
+export interface CreateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+    agentName?: string;
+    agentSpec?: TSpec;
+    title?: string;
+}
+
+export interface UpdateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+    sessionId: string;
+    agentSpec?: TSpec;
+    title?: string;
+}
+
+// ---------------------------------------------------------------------------
+// Pagination — flat token-based (no Page objects with methods)
+// ---------------------------------------------------------------------------
+
+export interface ListResult<T> {
+    data: T[];
+    nextPageToken?: string;
+}
+
+export type ListSessionsOrder = "asc" | "desc";
+
+export type PageParams = {
+    limit?: number;
+    order?: ListSessionsOrder;
+    pageToken?: string;
+};
+
+export interface ListSessionsParams extends PageParams {
+    agentName?: string;
+    /** Host-specific filter (e.g. TFY startTimestamp). */
+    startTimestamp?: string;
+}
+
+export type PreviousTurnIdInput = "auto" | string;
+
+// ---------------------------------------------------------------------------
+// Turn input / state — what runtime sends and reads
+// ---------------------------------------------------------------------------
+
+export type UserMessageContent =
+    | string
+    | Array<{ type: "text"; text: string } | { type: "file"; name: string; data: string }>;
+
+export interface UserMessage {
+    type: "user.message";
+    content: UserMessageContent;
+}
+
+export type ApprovalDecision =
+    | { status: "allow" }
+    | { status: "deny"; reason?: string };
+
+export interface UserToolApprovalEvent {
+    type: "user.tool_approval";
+    threadId: string;
+    toolCallId: string;
+    approval: ApprovalDecision;
+}
+
+export interface UserToolResponseEvent {
+    type: "user.tool_response";
+    threadId: string;
+    toolCallId: string;
+    content: string;
+}
+
+export type TurnInputItem =
+    | UserMessage
+    | UserToolApprovalEvent
+    | UserToolResponseEvent;
+
+export type TurnStateRunning = { status: "running" };
+
+export type TurnStateDone = {
+    status: "done";
+    output?: unknown;
+    requiredActions?: ActionRequiredEvent[];
+    completedAt: string;
+};
+
+export type TurnStateCancelled = {
+    status: "cancelled";
+    reason: string;
+    completedAt: string;
+};
+
+export type TurnStateError = {
+    status: "error";
+    message: string;
+    completedAt: string;
+};
+
+export type TurnState =
+    | TurnStateRunning
+    | TurnStateDone
+    | TurnStateCancelled
+    | TurnStateError;
+
+/** Plain turn DTO — no methods. */
+export interface Turn {
+    id: string;
+    sessionId: string;
+    previousTurnId?: string | null;
+    input?: TurnInputItem[];
+    state: TurnState;
+    createdAt: string;
+}
+
+// ---------------------------------------------------------------------------
+// Server ports — flat methods, no session-with-methods objects
+// ---------------------------------------------------------------------------
+
+/**
+ * Chat / session port — the runtime calls these.
+ *
+ * All session ops are flat (sessionId param). No gateway client dependency.
+ * `createTrueFoundryServer` is one possible implementation (TFY adapter).
+ */
+export interface AgentChatServer<
+    TSpec extends AgentSpec = AgentSpec,
+    TSession extends Session<TSpec> = Session<TSpec>,
+    TCreate extends CreateSessionRequest<TSpec> = CreateSessionRequest<TSpec>,
+    TList extends ListSessionsParams = ListSessionsParams,
+    TUpdate extends UpdateSessionRequest<TSpec> = UpdateSessionRequest<TSpec>,
+    TTurn extends Turn = Turn,
+> {
+    createSession(req: TCreate): Promise<TSession>;
+    listSessions(req?: TList): Promise<ListResult<TSession>>;
+    getSession(req: { sessionId: string }): Promise<TSession>;
+    updateSession(req: TUpdate): Promise<TSession>;
+
+    prepareAndExecuteTurn(req: {
+        sessionId: string;
+        input?: TurnInputItem[];
+        previousTurnId?: PreviousTurnIdInput;
+        abortSignal?: AbortSignal;
+        headers?: Record<string, string>;
+    }): AsyncIterable<TurnStreamData>;
+
+    cancelSession(req: { sessionId: string }): Promise<void>;
+    deleteSession?(req: { sessionId: string }): Promise<void>;
+
+    listTurns(req: {
+        sessionId: string;
+        limit?: number;
+        pageToken?: string;
+        order?: ListSessionsOrder;
+    }): Promise<ListResult<TTurn>>;
+    getTurn(req: { sessionId: string; turnId: string }): Promise<TTurn>;
+    listEvents(req: {
+        sessionId: string;
+        pageToken?: string;
+        lastTurnId?: string;
+        limit?: number;
+    }): Promise<ListResult<SessionEventItem>>;
+
+    /** Optional per-turn event listing (hydrate in-flight turn content). */
+    listTurnEvents?(req: {
+        sessionId: string;
+        turnId: string;
+        limit?: number;
+        pageToken?: string;
+        order?: ListSessionsOrder;
+    }): Promise<ListResult<TurnEvent>>;
+
+    subscribeToTurn?(req: {
+        sessionId: string;
+        turnId: string;
+        afterSequenceNumber?: number;
+        abortSignal?: AbortSignal;
+    }): AsyncIterable<TurnStreamData>;
+
+    downloadSandboxFile?(
+        sandboxId: string,
+        req: { path: string },
+    ): Promise<Blob>;
+}
+
+/**
+ * Builder catalog + persist port — atoms call these.
+ * Passed separately from the runtime's chat server.
+ */
+export interface AgentBuilderServer<
+    TSpec extends AgentSpec = AgentSpec,
+    TModel extends ModelSelectorEntry = ModelSelectorEntry,
+    TSkill extends SkillSelectorEntry = SkillSelectorEntry,
+    TMcp extends ConnectorSelectorEntry = ConnectorSelectorEntry,
+    TAgent extends AgentSelectorEntry = AgentSelectorEntry,
+    TSave = unknown,
+> {
+    getModels(): Promise<TModel[]>;
+    getSkills(): Promise<TSkill[]>;
+    getMcp(): Promise<TMcp[]>;
+    searchAgents(req?: SearchAgentSelectorParams): Promise<TAgent[]>;
+    saveAgent(req: {
+        agentName: string;
+        agentSpec: TSpec;
+    }): Promise<TSave>;
+    deleteAgent?(req: { agentName: string }): Promise<void>;
+}

package/src/sessionSnapshot.ts

@@ -5,7 +5,7 @@ import type {
     TurnDoneEvent,
     TurnEvent,
     TurnInputItem,
-} from "truefoundry-gateway-sdk/agents";
+} from "./server/index.js";
 
 import { extractTurnUserText } from "./extractTurnUserText.js";
 import { PeerThreadFoldState } from "./foldPeerThreads.js";

package/src/sessions.ts

@@ -1,31 +1,15 @@
-import type {
-    AgentSession,
-    AgentSessionClient,
-} from "truefoundry-gateway-sdk/agents";
-import type { PrivateAgentSessionClient } from "truefoundry-gateway-sdk/agents/private";
+import type { AgentChatServer, Session } from "./server/types.js";
 
-import { bindDraftAgentSession } from "./private/bindDraftAgentSession.js";
-
-const inflightBySessionId = new Map<string, Promise<AgentSession>>();
-
-export type GetSessionOptions = {
-    /** When set, validates the draft and binds turns via PrivateAgentSessionClient. */
-    privateClient?: PrivateAgentSessionClient;
-};
+const inflightBySessionId = new Map<string, Promise<Session>>();
 
 /** `sessionId` is the assistant-ui thread `remoteId` from `RemoteThreadListAdapter.initialize`. */
 export function getSession(
-    client: AgentSessionClient,
+    server: AgentChatServer,
     sessionId: string,
-    options?: GetSessionOptions,
-): Promise<AgentSession> {
-    if (options?.privateClient != null) {
-        return bindDraftAgentSession(options.privateClient, sessionId);
-    }
-
+): Promise<Session> {
     let inflight = inflightBySessionId.get(sessionId);
     if (inflight == null) {
-        inflight = client.getSession({ sessionId }).finally(() => {
+        inflight = server.getSession({ sessionId }).finally(() => {
             if (inflightBySessionId.get(sessionId) === inflight) {
                 inflightBySessionId.delete(sessionId);
             }