@truefoundry/assistant-ui-runtime 0.1.6 → 0.1.8

package/src/server/types.ts

@@ -10,8 +10,7 @@ import type {
     ActionRequiredEvent,
     SessionEventItem,
     TurnEvent,
-    TurnStreamData,
-    TurnStreamingEvent,
+    TurnStreamData
 } from "./events.js";
 
 // ---------------------------------------------------------------------------
@@ -72,7 +71,7 @@ export type SkillMount = object;
 export type McpServerMount = object;
 
 // ---------------------------------------------------------------------------
-// AgentSpec — model + skills + mcpServers on base; host widens the rest
+// AgentSpec — model / skills / mcpServers are type params; host widens the rest
 // ---------------------------------------------------------------------------
 
 export interface ModelParams {
@@ -87,17 +86,19 @@ export interface Model {
 
 /**
  * SDK-owned agent definition — fields the FE reads/writes.
- * Host adds additional fields via `TSpec extends AgentSpec`.
+ * Host widens `model` / `skills` / `mcpServers` via type params, and adds
+ * extra fields via `TSpec extends AgentSpec<...>`.
  */
-export interface AgentSpec {
-    model: Model;
-    skills?: SkillMount[];
-    mcpServers?: McpServerMount[];
+export interface AgentSpec<
+    TModel extends Model = Model,
+    TSkill extends SkillMount = SkillMount,
+    TMcp extends McpServerMount = McpServerMount,
+> {
+    model: TModel;
+    skills?: TSkill[];
+    mcpServers?: TMcp[];
     instructions?: string;
-    messages?: unknown[];
     variables?: Record<string, string>;
-    responseFormat?: unknown;
-    config?: unknown;
 }
 
 // ---------------------------------------------------------------------------
@@ -248,7 +249,7 @@ export interface AgentChatServer<
     getSession(req: { sessionId: string }): Promise<TSession>;
     updateSession(req: TUpdate): Promise<TSession>;
 
-    prepareAndExecuteTurn(req: {
+    createTurn(req: {
         sessionId: string;
         input?: TurnInputItem[];
         previousTurnId?: PreviousTurnIdInput;
@@ -317,3 +318,254 @@ export interface AgentBuilderServer<
     }): Promise<TSave>;
     deleteAgent?(req: { agentName: string }): Promise<void>;
 }
+
+// ---------------------------------------------------------------------------
+// Catalog management — FE-minimal settings DTOs (host extends via generics)
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider type id. Reserved literal: `"custom"` for user-defined providers;
+ * any other string is a builtin (e.g. `"openai"`, `"anthropic"`).
+ *
+ * Note: `string | "custom"` is useless in TypeScript (`"custom"` ⊆ `string`),
+ * so this stays `string` and `"custom"` is a documented convention.
+ */
+export type ProviderType = string;
+
+/**
+ * Model row — form "Model ID" + "Display name".
+ * Host extends for properties, etc.
+ */
+export interface ModelEntry {
+    id: string;
+    name: string;
+}
+
+/**
+ * Write config for create/update (custom form + catalog "Save key").
+ * Host extends. `baseUrl` present iff `type === "custom"`.
+ */
+export interface ModelProviderConfigBase<TModel extends ModelEntry = ModelEntry> {
+    type: ProviderType;
+    name: string;
+    /** Present iff `type === "custom"`. */
+    baseUrl?: string;
+    apiKey: string;
+    models: TModel[];
+}
+
+/**
+ * Configured provider card (list/read). No raw `apiKey`.
+ * Host extends for apiKeySet, timestamps, etc.
+ */
+export interface ModelProviderBase<TModel extends ModelEntry = ModelEntry> {
+    id: string;
+    type: ProviderType;
+    name: string;
+    /** Present iff `type === "custom"`. */
+    baseUrl?: string;
+    models: TModel[];
+}
+
+/**
+ * Discovery-only catalog provider (AVAILABLE list).
+ * `type` must not be `"custom"` — custom providers use the custom form.
+ * Host extends for richer model rows.
+ */
+export interface ModelProviderCatalogEntry<TModel extends ModelEntry = ModelEntry> {
+    type: ProviderType;
+    name: string;
+    models: TModel[];
+}
+
+/** Create — no `id`; server assigns it. Catalog path = entry + apiKey. */
+export type CreateModelProviderRequest<TModel extends ModelEntry = ModelEntry> =
+    ModelProviderConfigBase<TModel>;
+
+/** Update — `id` required. */
+export type UpdateModelProviderRequest<TModel extends ModelEntry = ModelEntry> =
+    ModelProviderConfigBase<TModel> & { id: string };
+
+export interface ModelCatalogServer<
+    TModel extends ModelEntry = ModelEntry,
+    TProvider extends ModelProviderBase<TModel> = ModelProviderBase<TModel>,
+    TCatalogProvider extends ModelProviderCatalogEntry<TModel> = ModelProviderCatalogEntry<TModel>,
+    TCreate extends CreateModelProviderRequest<TModel> = CreateModelProviderRequest<TModel>,
+    TUpdate extends UpdateModelProviderRequest<TModel> = UpdateModelProviderRequest<TModel>,
+> {
+    getModelProviderCatalog(): Promise<TCatalogProvider[]>;
+    listModelProviders(): Promise<TProvider[]>;
+    createModelProvider(req: TCreate): Promise<TProvider>;
+    /** Full replace update keyed by provider `id`. */
+    updateModelProvider(req: TUpdate): Promise<TProvider>;
+    deleteModelProvider?(req: { id: string }): Promise<void>;
+}
+
+/** Tool row on a connector detail. Host extends for schemas, etc. */
+export interface ToolBase {
+    id: string;
+    name: string;
+}
+
+/** Strict auth type id. Hosts widen branches via intersection + re-union. */
+export type ConnectorAuthType = "oauth" | "apiKey" | "none";
+
+// Write (create/update) — export branches so hosts can intersect extras
+export type ConnectorAuthOAuth = { type: "oauth"; authUrl?: string };
+export type ConnectorAuthApiKey = {
+    type: "apiKey";
+    apiKey?: string;
+    headerName?: string;
+};
+export type ConnectorAuthNone = { type: "none" };
+export type ConnectorAuth =
+    | ConnectorAuthOAuth
+    | ConnectorAuthApiKey
+    | ConnectorAuthNone;
+
+// Public (list/detail) — no secrets; oauth requires authUrl
+export type ConnectorAuthPublicOAuth = { type: "oauth"; authUrl: string };
+export type ConnectorAuthPublicApiKey = {
+    type: "apiKey";
+    headerName?: string;
+};
+export type ConnectorAuthPublicNone = { type: "none" };
+export type ConnectorAuthPublic =
+    | ConnectorAuthPublicOAuth
+    | ConnectorAuthPublicApiKey
+    | ConnectorAuthPublicNone;
+
+/**
+ * MCP / connector create-edit config. Host extends for extra fields, etc.
+ */
+export interface ConnectorConfigBase<
+    TAuth extends ConnectorAuth = ConnectorAuth,
+> {
+    name: string;
+    url: string;
+    auth: TAuth;
+}
+
+/**
+ * Connected connector row (settings/connectors). No raw `apiKey`.
+ * Host extends.
+ */
+export interface ConnectorBase<
+    TTool extends ToolBase = ToolBase,
+    TAuth extends ConnectorAuthPublic = ConnectorAuthPublic,
+> {
+    id: string;
+    name: string;
+    description: string;
+    url: string;
+    auth: TAuth;
+    /** When true, UI should not show Disconnect. */
+    requiresAuth: boolean;
+    authenticated: boolean;
+    tools: TTool[];
+}
+
+/** Discovery catalog entry for "+ Add MCP server". Host extends. */
+export interface ConnectorCatalogEntry<
+    TAuth extends ConnectorAuthPublic = ConnectorAuthPublic,
+> {
+    id: string;
+    name: string;
+    description?: string;
+    url: string;
+    auth: TAuth;
+}
+
+/** Create connector — no `id`; server assigns it. Host extends. */
+export type CreateConnectorRequest<TAuth extends ConnectorAuth = ConnectorAuth> =
+    ConnectorConfigBase<TAuth>;
+
+/** Update connector — `id` required. Host extends. */
+export type UpdateConnectorRequest<TAuth extends ConnectorAuth = ConnectorAuth> =
+    ConnectorConfigBase<TAuth> & { id: string };
+
+export interface ConnectorCatalogServer<
+    TTool extends ToolBase = ToolBase,
+    TAuthWrite extends ConnectorAuth = ConnectorAuth,
+    TAuthPublic extends ConnectorAuthPublic = ConnectorAuthPublic,
+    TConnector extends ConnectorBase<TTool, TAuthPublic> = ConnectorBase<
+        TTool,
+        TAuthPublic
+    >,
+    TCatalogEntry extends ConnectorCatalogEntry<TAuthPublic> =
+        ConnectorCatalogEntry<TAuthPublic>,
+    TCreate extends CreateConnectorRequest<TAuthWrite> =
+        CreateConnectorRequest<TAuthWrite>,
+    TUpdate extends UpdateConnectorRequest<TAuthWrite> =
+        UpdateConnectorRequest<TAuthWrite>,
+> {
+    getConnectorCatalog(): Promise<TCatalogEntry[]>;
+    listConnectors(req?: { query?: string }): Promise<TConnector[]>;
+    createConnector(req: TCreate): Promise<TConnector>;
+    /** Full replace update keyed by connector `id`. */
+    updateConnector(req: TUpdate): Promise<TConnector>;
+    /**
+     * Start connector auth (e.g. OAuth).
+     * For oauth, the returned connector's `auth.authUrl` is the authorize URL.
+     */
+    authenticateConnector(req: { id: string }): Promise<TConnector>;
+    /** Clear connector auth. */
+    disconnectConnector(req: { id: string }): Promise<TConnector>;
+    deleteConnector?(req: { id: string }): Promise<void>;
+}
+
+// ---------------------------------------------------------------------------
+// Skills catalog — FE-minimal settings DTOs (host extends via generics)
+// ---------------------------------------------------------------------------
+
+/** Skill row shown in settings/skills (list + delete). Host extends for fqn, etc. */
+export interface SkillBase {
+    id: string;
+    name: string;
+    description: string;
+}
+
+/** Create-skill request. Host extends for branch, auth, etc. */
+export interface CreateSkillRequest {
+    repo: string;
+    directory: string;
+}
+
+export interface SkillCatalogServer<
+    TSkill extends SkillBase = SkillBase,
+    TCreate extends CreateSkillRequest = CreateSkillRequest,
+> {
+    listSkills(req?: { query?: string }): Promise<TSkill[]>;
+    createSkill(req: TCreate): Promise<TSkill>;
+    deleteSkill?(req: { id: string }): Promise<void>;
+}
+
+/**
+ * Settings management aggregate — modelCatalog + connectorCatalog + optional skillCatalog.
+ * Hosts may pass the whole object to an app shell, or a focused sub-port to a page.
+ */
+export interface CatalogServer<
+    TModelCatalog extends ModelCatalogServer = ModelCatalogServer,
+    TConnectorCatalog extends ConnectorCatalogServer = ConnectorCatalogServer,
+    TSkillCatalog extends SkillCatalogServer = SkillCatalogServer,
+> {
+    modelCatalog: TModelCatalog;
+    connectorCatalog: TConnectorCatalog;
+    /** Optional — omit when the host has no skills settings surface. */
+    skillCatalog?: TSkillCatalog;
+}
+
+/**
+ * Composed host port: chat + builder + optional settings catalog.
+ * Agent-ui's `AgentUIServer` mirrors this shape; named differently here to
+ * avoid colliding with that package's local type name.
+ *
+ * `catalog` is optional — if the host passes it, settings UI can call
+ * `useCatalogServer()` / show modelCatalog, connectorCatalog, and skillCatalog;
+ * if omitted, those surfaces stay hidden.
+ */
+export type AgentUIServerPort<
+    TChat extends AgentChatServer = AgentChatServer,
+    TBuilder extends AgentBuilderServer = AgentBuilderServer,
+    TCatalog extends CatalogServer = CatalogServer,
+> = TChat & TBuilder & { catalog?: TCatalog };

package/src/streamTurn.test.ts

@@ -33,7 +33,7 @@ describe("streamTurn", () => {
     describe("streamTurnContent", () => {
         it("prepares a user turn and yields folded stream updates", async () => {
             const foldState = new PeerThreadFoldState();
-            const prepareAndExecuteTurn = vi.fn(async function* () {
+            const createTurn = vi.fn(async function* () {
                 yield streamData(1, {
                     type: "model.message",
                     createdAt,
@@ -43,7 +43,7 @@ describe("streamTurn", () => {
                 });
             });
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
 
@@ -57,7 +57,7 @@ describe("streamTurn", () => {
                 ),
             );
 
-            expect(prepareAndExecuteTurn).toHaveBeenCalledWith({
+            expect(createTurn).toHaveBeenCalledWith({
                 sessionId: SESSION_ID,
                 input: [{ type: "user.message", content: "hello" }],
                 previousTurnId: "auto",
@@ -68,7 +68,7 @@ describe("streamTurn", () => {
             ]);
         });
 
-        it("passes required-action inputs through prepareAndExecuteTurn", async () => {
+        it("passes required-action inputs through createTurn", async () => {
             const inputs = [
                 {
                     type: "user.tool_approval" as const,
@@ -83,9 +83,9 @@ describe("streamTurn", () => {
                     content: "A",
                 },
             ];
-            const prepareAndExecuteTurn = vi.fn(async function* () {});
+            const createTurn = vi.fn(async function* () {});
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
 
@@ -99,7 +99,7 @@ describe("streamTurn", () => {
                 ),
             );
 
-            expect(prepareAndExecuteTurn).toHaveBeenCalledWith({
+            expect(createTurn).toHaveBeenCalledWith({
                 sessionId: SESSION_ID,
                 input: inputs,
                 previousTurnId: "auto",
@@ -108,9 +108,9 @@ describe("streamTurn", () => {
         });
 
         it("uses empty input when resuming after MCP auth", async () => {
-            const prepareAndExecuteTurn = vi.fn(async function* () {});
+            const createTurn = vi.fn(async function* () {});
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
 
@@ -124,7 +124,7 @@ describe("streamTurn", () => {
                 ),
             );
 
-            expect(prepareAndExecuteTurn).toHaveBeenCalledWith({
+            expect(createTurn).toHaveBeenCalledWith({
                 sessionId: SESSION_ID,
                 input: [],
                 previousTurnId: "auto",
@@ -133,9 +133,9 @@ describe("streamTurn", () => {
         });
 
         it("forwards an explicit previousTurnId when branching", async () => {
-            const prepareAndExecuteTurn = vi.fn(async function* () {});
+            const createTurn = vi.fn(async function* () {});
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
 
@@ -149,7 +149,7 @@ describe("streamTurn", () => {
                 ),
             );
 
-            expect(prepareAndExecuteTurn).toHaveBeenCalledWith({
+            expect(createTurn).toHaveBeenCalledWith({
                 sessionId: SESSION_ID,
                 input: [{ type: "user.message", content: "edited" }],
                 previousTurnId: "turn-a",
@@ -158,9 +158,9 @@ describe("streamTurn", () => {
         });
 
         it("forwards previousTurnId \"none\" when branching from root", async () => {
-            const prepareAndExecuteTurn = vi.fn(async function* () {});
+            const createTurn = vi.fn(async function* () {});
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
 
@@ -174,7 +174,7 @@ describe("streamTurn", () => {
                 ),
             );
 
-            expect(prepareAndExecuteTurn).toHaveBeenCalledWith({
+            expect(createTurn).toHaveBeenCalledWith({
                 sessionId: SESSION_ID,
                 input: [{ type: "user.message", content: "first" }],
                 previousTurnId: "none",
@@ -183,9 +183,9 @@ describe("streamTurn", () => {
         });
 
         it("returns early and cancels the session when already aborted", async () => {
-            const prepareAndExecuteTurn = vi.fn(async function* () {});
+            const createTurn = vi.fn(async function* () {});
             const cancelSession = vi.fn().mockResolvedValue(undefined);
-            const server = mockServer({ prepareAndExecuteTurn, cancelSession });
+            const server = mockServer({ createTurn, cancelSession });
             const abortController = new AbortController();
             abortController.abort();
 
@@ -200,14 +200,14 @@ describe("streamTurn", () => {
             );
 
             expect(cancelSession).toHaveBeenCalledWith({ sessionId: SESSION_ID });
-            expect(prepareAndExecuteTurn).not.toHaveBeenCalled();
+            expect(createTurn).not.toHaveBeenCalled();
             expect(updates).toEqual([]);
         });
 
-        it("forwards headers to prepareAndExecuteTurn", async () => {
-            const prepareAndExecuteTurn = vi.fn(async function* () {});
+        it("forwards headers to createTurn", async () => {
+            const createTurn = vi.fn(async function* () {});
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
             const abortSignal = new AbortController().signal;
@@ -227,7 +227,7 @@ describe("streamTurn", () => {
                 ),
             );
 
-            expect(prepareAndExecuteTurn).toHaveBeenCalledWith({
+            expect(createTurn).toHaveBeenCalledWith({
                 sessionId: SESSION_ID,
                 input: [{ type: "user.message", content: "hello" }],
                 previousTurnId: "auto",
@@ -240,7 +240,7 @@ describe("streamTurn", () => {
 
         it("notifies gateway turn id when turn.done errors with no content yields", async () => {
             const gatewayTurnId = "01ky6mqzmczwt6ssyd5r02gjjc";
-            const prepareAndExecuteTurn = vi.fn(async function* () {
+            const createTurn = vi.fn(async function* () {
                 yield streamData(1, {
                     type: "turn.created",
                     createdAt,
@@ -261,7 +261,7 @@ describe("streamTurn", () => {
                 });
             });
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
             const onTurnIdAvailable = vi.fn();
@@ -285,7 +285,7 @@ describe("streamTurn", () => {
         });
 
         it("does not notify when an error stream never emits turn.created", async () => {
-            const prepareAndExecuteTurn = vi.fn(async function* () {
+            const createTurn = vi.fn(async function* () {
                 yield streamData(1, {
                     type: "turn.done",
                     createdAt,
@@ -298,7 +298,7 @@ describe("streamTurn", () => {
                 });
             });
             const server = mockServer({
-                prepareAndExecuteTurn,
+                createTurn,
                 cancelSession: vi.fn().mockResolvedValue(undefined),
             });
             const onTurnIdAvailable = vi.fn();

package/src/streamTurn.ts

@@ -18,7 +18,7 @@ export type StreamTurnOptions = {
     resumeMcpAuth?: boolean;
     inputs?: RequiredActionInput[];
     /**
-     * Branch anchor for prepareAndExecuteTurn. Omit for `"auto"`. Pass `"none"` for a fresh
+     * Branch anchor for createTurn. Omit for `"auto"`. Pass `"none"` for a fresh
      * root turn.
      */
     previousTurnId?: PreviousTurnIdInput;
@@ -79,7 +79,7 @@ export async function* streamTurnContent(
         }
     };
 
-    const stream: AsyncIterable<TurnStreamData> = server.prepareAndExecuteTurn({
+    const stream: AsyncIterable<TurnStreamData> = server.createTurn({
         sessionId,
         input: buildTurnInput(options),
         previousTurnId: options.previousTurnId ?? "auto",

package/src/truefoundryExtras.ts

@@ -1,7 +1,8 @@
 import { createRuntimeExtras } from "@assistant-ui/core/internal";
 import type { McpAuthRequiredEvent } from "./server/index.js";
 
-import type { AgentSpec, AgentSpecUpdate } from "./private/agentSpec.js";
+import type { AgentSpec } from "./server/types.js";
+import type { AgentSpecUpdate } from "./draft/agentSpec.js";
 import type { PendingApproval, PendingToolResponse } from "./collectPending.js";
 import type { RespondToToolApprovalOptions } from "./toolApproval.js";
 import type { RespondToToolResponseOptions } from "./toolResponse.js";
@@ -11,6 +12,7 @@ export type { PendingApproval, PendingToolResponse };
 export type TrueFoundryDraftRuntimeExtras = {
     agentSpec: AgentSpec | null;
     draftSessionId: string | undefined;
+    isSpecLoading: boolean;
     isSpecSyncing: boolean;
     specError: unknown | null;
     updateAgentSpec: (update: AgentSpecUpdate) => void;
@@ -41,6 +43,7 @@ export const trueFoundryExtras = createRuntimeExtras<TrueFoundryRuntimeExtras>(
 export const EMPTY_DRAFT_EXTRAS: TrueFoundryDraftRuntimeExtras = {
     agentSpec: null,
     draftSessionId: undefined,
+    isSpecLoading: false,
     isSpecSyncing: false,
     specError: null,
     updateAgentSpec: () => {

package/src/truefoundryOwnedSessionsThreadListAdapter.ts

@@ -1,7 +1,7 @@
 import type { RemoteThreadListAdapter } from "@assistant-ui/core";
 
 import type { AgentChatServer, Session } from "./server/types.js";
-import { draftSessionTitle } from "./private/agentSpec.js";
+import { draftSessionTitle } from "./draft/agentSpec.js";
 import { sessionListStartTimestamp } from "./sessionListStartTimestamp.js";
 
 const THREAD_LIST_PAGE_SIZE = 20;
@@ -63,7 +63,10 @@ export function createTrueFoundryOwnedSessionsThreadListAdapter(options: {
         async rename() {},
         async archive() {},
         async unarchive() {},
-        async delete() {},
+        async delete(remoteId) {
+            if (typeof server.deleteSession !== "function") return;
+            await server.deleteSession({ sessionId: remoteId });
+        },
 
         async generateTitle() {
             return new ReadableStream();

package/src/truefoundryThreadListAdapter.test.ts

@@ -98,4 +98,26 @@ describe("createTrueFoundryThreadListAdapter", () => {
 
         expect(result.nextCursor).toBeUndefined();
     });
+
+    it("delete calls server.deleteSession when implemented", async () => {
+        const deleteSession = vi.fn().mockResolvedValue(undefined);
+        const server = mockServer({ deleteSession });
+        const adapter = createTrueFoundryThreadListAdapter({
+            server,
+            agentName: "my-agent",
+        });
+
+        await adapter.delete("s1");
+
+        expect(deleteSession).toHaveBeenCalledWith({ sessionId: "s1" });
+    });
+
+    it("delete is a no-op when server.deleteSession is missing", async () => {
+        const adapter = createTrueFoundryThreadListAdapter({
+            server: mockServer({}),
+            agentName: "my-agent",
+        });
+
+        await expect(adapter.delete("s1")).resolves.toBeUndefined();
+    });
 });

package/src/truefoundryThreadListAdapter.ts

@@ -50,7 +50,10 @@ export function createTrueFoundryThreadListAdapter(options: {
         async rename() {},
         async archive() {},
         async unarchive() {},
-        async delete() {},
+        async delete(remoteId) {
+            if (typeof server.deleteSession !== "function") return;
+            await server.deleteSession({ sessionId: remoteId });
+        },
 
         async generateTitle() {
             return new ReadableStream();

package/src/types.ts

@@ -7,8 +7,7 @@ import type {
     SpeechSynthesisAdapter,
 } from "@assistant-ui/core";
 
-import type { AgentSpec } from "./private/agentSpec.js";
-import type { AgentChatServer } from "./server/types.js";
+import type { AgentChatServer, AgentSpec } from "./server/types.js";
 
 export type NamedAgentConfig = {
     mode: "named";