@truefoundry/assistant-ui-runtime 0.1.5 → 0.1.6-rc.0

package/dist/types-VUBzoJT2.d.ts

@@ -0,0 +1,462 @@
+/**
+ * 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.
+ */
+
+interface ToolCallFunction {
+    name: string;
+    arguments: string;
+}
+type ToolInfo = {
+    type: "truefoundry-system";
+    name: string;
+} | {
+    type: "mcp";
+    serverId: string;
+    serverName: string;
+    name: string;
+} | {
+    type: string;
+    name?: string;
+    [key: string]: unknown;
+};
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: ToolCallFunction;
+    toolInfo?: ToolInfo;
+    providerSpecificFields?: Record<string, unknown>;
+}
+/** Ref used by approval/response-required events. */
+interface ToolCallRef {
+    id: string;
+    sourceEventId: string;
+}
+interface ChunkDeltaToolCall {
+    index: number;
+    id?: string;
+    type?: "function";
+    function?: {
+        name?: string;
+        arguments?: string;
+    };
+    toolInfo?: ToolInfo;
+    providerSpecificFields?: Record<string, unknown>;
+}
+type ModelMessageContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "refusal";
+    refusal: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+};
+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;
+}
+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;
+            };
+        };
+    }>;
+}
+interface ToolResponseEvent {
+    type: "tool.response";
+    id: string;
+    threadId: string;
+    toolCallId: string;
+    content: string;
+    createdAt: string;
+}
+interface ToolApprovalRequiredEvent {
+    type: "tool.approval_required";
+    id: string;
+    createdAt: string;
+    threadId: string;
+    toolCalls: ToolCallRef[];
+}
+interface ToolResponseRequiredEvent {
+    type: "tool.response_required";
+    id: string;
+    createdAt: string;
+    threadId: string;
+    toolCalls: ToolCallRef[];
+}
+interface AgentInfo {
+    type?: string;
+    name: string;
+    input: string;
+    model?: string;
+}
+interface AgentParent {
+    threadId: string;
+    toolCallId: string;
+}
+interface ThreadCreatedEvent {
+    type: "thread.created";
+    id: string;
+    threadId: string;
+    title: string;
+    agentInfo: AgentInfo;
+    parent: AgentParent;
+    createdAt: string;
+}
+interface ThreadDoneEvent {
+    type: "thread.done";
+    id: string;
+    threadId: string;
+    title?: string;
+    createdAt: string;
+    state?: unknown;
+}
+interface McpServerAuthInfo {
+    id: string;
+    name: string;
+    authUrl: string;
+}
+interface McpAuthRequiredEvent {
+    type: "mcp.auth_required";
+    id: string;
+    createdAt: string;
+    threadId?: string | null;
+    mcpServers: McpServerAuthInfo[];
+}
+interface SandboxCreatedEvent {
+    type: "sandbox.created";
+    id: string;
+    createdAt: string;
+    sandboxId: string;
+    threadId: string | null;
+}
+interface McpInitializeEvent {
+    type: "mcp.initialize";
+    id: string;
+    createdAt: string;
+    threadId: string | null;
+    [key: string]: unknown;
+}
+interface TurnCreatedEvent {
+    type: "turn.created";
+    id: string;
+    turnId: string;
+    previousTurnId?: string | null;
+    input?: TurnInputItem[];
+    state?: {
+        status: "running";
+    };
+    createdAt: string;
+    threadId?: string | null;
+}
+interface TurnDoneEvent {
+    type: "turn.done";
+    id: string;
+    state: Exclude<TurnState, {
+        status: "running";
+    }>;
+    createdAt: string;
+    threadId?: string | null;
+}
+/** Events stored in fold buckets (non-delta, non-turn-lifecycle). */
+type TurnEvent = ModelMessageEvent | ToolResponseEvent | ThreadCreatedEvent | ThreadDoneEvent | McpAuthRequiredEvent | McpInitializeEvent | SandboxCreatedEvent | ToolApprovalRequiredEvent | ToolResponseRequiredEvent;
+/** Full streaming event union (includes deltas + turn lifecycle). */
+type TurnStreamingEvent = TurnEvent | ModelMessageDeltaEvent | TurnCreatedEvent | TurnDoneEvent;
+type ActionRequiredEvent = ToolApprovalRequiredEvent | ToolResponseRequiredEvent | McpAuthRequiredEvent;
+interface TurnStreamData<TStreamEvent extends TurnStreamingEvent = TurnStreamingEvent> {
+    sequenceNumber: number;
+    event: TStreamEvent;
+}
+/** Session-level event item from `listEvents`. */
+interface SessionEventItem {
+    turnId: string;
+    event: TurnCreatedEvent | TurnDoneEvent | TurnEvent;
+}
+type DeltaEvents = ModelMessageDeltaEvent;
+
+/**
+ * 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.
+ */
+
+/** Model selector row. Host extends for apiModel, modelId, pricing, etc. */
+interface ModelSelectorEntry {
+    name: string;
+    provider: string;
+}
+/** Skill selector row. Host extends for fqn, preload, etc. */
+interface SkillSelectorEntry {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** MCP connector selector row. Host extends for type, enableTools, url, etc. */
+interface ConnectorSelectorEntry {
+    id: string;
+    name: string;
+    description?: string;
+}
+/** Agent selector row — UI shows name only. Host extends for metadata. */
+interface AgentSelectorEntry {
+    name: string;
+}
+type SearchAgentSelectorParams = {
+    query?: string;
+    limit?: number;
+    offset?: number;
+};
+/** Skill mount base written to AgentSpec.skills[]. Host extends for fqn, preload, etc. */
+interface SkillMount {
+    id: string;
+    name: string;
+}
+/** MCP server mount base written to AgentSpec.mcpServers[]. Host extends for type, enableTools, etc. */
+interface McpServerMount {
+    id: string;
+    name: string;
+}
+interface ModelParams {
+    maxTokens?: number;
+    reasoningEffort?: string;
+}
+interface Model {
+    name: string;
+    params?: ModelParams;
+}
+/**
+ * SDK-owned agent definition — fields the FE reads/writes.
+ * Host adds additional fields via `TSpec extends AgentSpec`.
+ */
+interface AgentSpec {
+    model: Model;
+    skills?: SkillMount[];
+    mcpServers?: McpServerMount[];
+    instructions?: string;
+    messages?: unknown[];
+    variables?: Record<string, string>;
+    responseFormat?: unknown;
+    config?: unknown;
+}
+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;
+}
+interface CreateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+    agentName?: string;
+    agentSpec?: TSpec;
+    title?: string;
+}
+interface UpdateSessionRequest<TSpec extends AgentSpec = AgentSpec> {
+    sessionId: string;
+    agentSpec?: TSpec;
+    title?: string;
+}
+interface ListResult<T> {
+    data: T[];
+    nextPageToken?: string;
+}
+type ListSessionsOrder = "asc" | "desc";
+type PageParams = {
+    limit?: number;
+    order?: ListSessionsOrder;
+    pageToken?: string;
+};
+interface ListSessionsParams extends PageParams {
+    agentName?: string;
+    /** Host-specific filter (e.g. TFY startTimestamp). */
+    startTimestamp?: string;
+}
+type PreviousTurnIdInput = "auto" | string;
+type UserMessageContent = string | Array<{
+    type: "text";
+    text: string;
+} | {
+    type: "file";
+    name: string;
+    data: string;
+}>;
+interface UserMessage {
+    type: "user.message";
+    content: UserMessageContent;
+}
+type ApprovalDecision = {
+    status: "allow";
+} | {
+    status: "deny";
+    reason?: string;
+};
+interface UserToolApprovalEvent {
+    type: "user.tool_approval";
+    threadId: string;
+    toolCallId: string;
+    approval: ApprovalDecision;
+}
+interface UserToolResponseEvent {
+    type: "user.tool_response";
+    threadId: string;
+    toolCallId: string;
+    content: string;
+}
+type TurnInputItem = UserMessage | UserToolApprovalEvent | UserToolResponseEvent;
+type TurnStateRunning = {
+    status: "running";
+};
+type TurnStateDone = {
+    status: "done";
+    output?: unknown;
+    requiredActions?: ActionRequiredEvent[];
+    completedAt: string;
+};
+type TurnStateCancelled = {
+    status: "cancelled";
+    reason: string;
+    completedAt: string;
+};
+type TurnStateError = {
+    status: "error";
+    message: string;
+    completedAt: string;
+};
+type TurnState = TurnStateRunning | TurnStateDone | TurnStateCancelled | TurnStateError;
+/** Plain turn DTO — no methods. */
+interface Turn {
+    id: string;
+    sessionId: string;
+    previousTurnId?: string | null;
+    input?: TurnInputItem[];
+    state: TurnState;
+    createdAt: string;
+}
+/**
+ * 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).
+ */
+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.
+ */
+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>;
+}
+
+export type { AgentSpec as A, CreateSessionRequest as C, DeltaEvents as D, ListResult as L, McpAuthRequiredEvent as M, PreviousTurnIdInput as P, Session as S, TurnStreamingEvent as T, UserToolResponseEvent as U, AgentChatServer as a, TurnEvent as b, ThreadCreatedEvent as c, UserToolApprovalEvent as d, Turn as e, TurnInputItem as f, AgentBuilderServer as g, ListSessionsParams as h, ModelMessageEvent as i, SandboxCreatedEvent as j, SessionEventItem as k, ToolApprovalRequiredEvent as l, ToolCall as m, ToolResponseRequiredEvent as n, TurnState as o, TurnStateDone as p, TurnStreamData as q, UpdateSessionRequest as r, UserMessage as s };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truefoundry/assistant-ui-runtime",
-  "version": "0.1.5",
+  "version": "0.1.6-rc.0",
   "description": "TrueFoundry Gateway agent runtime adapter for assistant-ui",
   "license": "Apache-2.0",
   "repository": {
@@ -26,6 +26,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./plugins/truefoundry-agent-server-adapter": {
+      "types": "./dist/plugins/truefoundry-agent-server-adapter/index.d.ts",
+      "import": "./dist/plugins/truefoundry-agent-server-adapter/index.js",
+      "default": "./dist/plugins/truefoundry-agent-server-adapter/index.js"
     }
   },
   "main": "./dist/index.js",
@@ -55,6 +60,9 @@
   "peerDependenciesMeta": {
     "@types/react": {
       "optional": true
+    },
+    "truefoundry-gateway-sdk": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -66,6 +74,6 @@
     "truefoundry-gateway-sdk": "0.4.0-rc.5",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.9"
+    "vitest": "4.1.9"
   }
 }

package/src/askUserQuestion.ts

@@ -1,11 +1,11 @@
-import type { ToolCall } from "truefoundry-gateway-sdk/agents";
+import type { ToolCall } from "./server/index.js";
 
 export function isAskUserQuestionToolCall(
     toolCall: Pick<ToolCall, "toolInfo">,
 ): boolean {
     return (
-        toolCall.toolInfo.type === "truefoundry-system" &&
-        toolCall.toolInfo.name === "ask_user_question"
+        toolCall.toolInfo?.type === "truefoundry-system" &&
+        toolCall.toolInfo?.name === "ask_user_question"
     );
 }
 

package/src/buildEditedUserMessageContent.test.ts

@@ -12,11 +12,11 @@ describe("user message branch helpers", () => {
         expect(parseTurnIdFromMessageId("turn-abc-user")).toBe("turn-abc");
     });
 
-    it("resolveBranchPreviousTurnId returns \"none\" for the first turn", () => {
+    it("resolveBranchPreviousTurnId returns null for the first turn", () => {
         const turns: SessionTurnRecord[] = [
             { id: "a", createdAt: "", state: { status: "done", requiredActions: [], completedAt: "" } },
         ];
-        expect(resolveBranchPreviousTurnId(turns, "a")).toBe("none");
+        expect(resolveBranchPreviousTurnId(turns, "a")).toBeNull();
     });
 
     it("resolveBranchPreviousTurnId returns the prior turn id", () => {

package/src/collectPending.ts

@@ -1,5 +1,5 @@
 import type { ThreadAssistantMessagePart, ThreadMessage } from "@assistant-ui/core";
-import type { McpAuthRequiredEvent } from "truefoundry-gateway-sdk/agents";
+import type { McpAuthRequiredEvent } from "./server/index.js";
 
 import { ROOT_THREAD_ID } from "./constants.js";
 import type { TrueFoundryMessageCustomMetadata } from "./messageCustomMetadata.js";