@truefoundry/assistant-ui-runtime 0.1.6 → 0.1.7

package/dist/plugins/truefoundry-agent-server-adapter/index.d.ts

@@ -1,6 +1,6 @@
 import { AgentSessionClient } from 'truefoundry-gateway-sdk/agents';
 import { PrivateAgentSessionClient } from 'truefoundry-gateway-sdk/agents/private';
-import { A as AgentSpec, C as CreateSessionRequest, L as ListSessionsParams, S as Session, T as Turn, a as TurnState, b as AgentChatServer, U as UpdateSessionRequest } from '../../types-BfiFf8O1.js';
+import { A as AgentSpec, C as CreateSessionRequest, L as ListSessionsParams, S as Session, T as Turn, a as TurnState, b as AgentChatServer, U as UpdateSessionRequest } from '../../types-DbNsU075.js';
 import { TruefoundryGatewayApi } from 'truefoundry-gateway-sdk';
 
 /**
@@ -29,10 +29,7 @@ type RuntimeSkillMount = NonNullable<NonNullable<AgentSpec["skills"]>[number]>;
 type RuntimeMcpServerMount = NonNullable<NonNullable<AgentSpec["mcpServers"]>[number]>;
 type TfySkillMount = RuntimeSkillMount & TruefoundryGatewayApi.SkillMount;
 type TfyMcpServerMount = RuntimeMcpServerMount & TruefoundryGatewayApi.McpServer;
-interface TfyAgentSpec extends AgentSpec {
-    model: TruefoundryGatewayApi.Model;
-    skills?: TfySkillMount[];
-    mcpServers?: TfyMcpServerMount[];
+interface TfyAgentSpec extends AgentSpec<TruefoundryGatewayApi.Model, TfySkillMount, TfyMcpServerMount> {
     config?: TruefoundryGatewayApi.RuntimeConfig;
     responseFormat?: TruefoundryGatewayApi.ResponseFormat;
     messages?: TruefoundryGatewayApi.AgentSpecUserMessage[];
@@ -155,7 +152,7 @@ type TrueFoundryChatServer<TSpec extends TfyAgentSpec = TfyAgentSpec> = AgentCha
  * Wraps TrueFoundry gateway clients into a flat `AgentChatServer`.
  * Named vs draft routing is fully internal — an in-memory session-type cache
  * (populated by createSession/listSessions) determines which gateway client
- * to call. No try/catch fallback, no double network calls.
+ * to call, falling back to a one-time probe for ids seen only in a URL.
  */
 declare function createTrueFoundryChatServer<TSpec extends TfyAgentSpec = TfyAgentSpec>(opts: CreateTrueFoundryChatServerOptions): TrueFoundryChatServer<TSpec>;
 

package/dist/plugins/truefoundry-agent-server-adapter/index.js

@@ -6,7 +6,7 @@ import {
   isTfyMcpToolInfo,
   isTfySystemToolInfo,
   isTfyToolInfo
-} from "../../chunk-Q2SHKMLM.js";
+} from "../../chunk-SQDOTGP2.js";
 export {
   createTrueFoundryChatServer,
   getTfyMcpInitServers,

package/dist/server/index.d.ts

@@ -1,5 +1,5 @@
-import { r as TurnStreamingEvent, D as DeltaEvents, c as TurnEvent } from '../types-BfiFf8O1.js';
-export { t as ActionRequiredEvent, h as AgentBuilderServer, b as AgentChatServer, u as AgentInfo, v as AgentParent, w as AgentSelectorEntry, A as AgentSpec, x as ApprovalDecision, y as ChunkDeltaToolCall, z as ConnectorSelectorEntry, C as CreateSessionRequest, i as ListResult, B as ListSessionsOrder, L as ListSessionsParams, M as McpAuthRequiredEvent, E as McpInitializeEvent, F as McpServerAuthInfo, G as McpServerMount, H as Model, I as ModelMessageContentPart, J as ModelMessageDeltaEvent, j as ModelMessageEvent, K as ModelParams, N as ModelSelectorEntry, O as PageParams, P as PreviousTurnIdInput, k as SandboxCreatedEvent, Q as SearchAgentSelectorParams, S as Session, l as SessionEventItem, R as SkillMount, V as SkillSelectorEntry, d as ThreadCreatedEvent, W as ThreadDoneEvent, m as ToolApprovalRequiredEvent, n as ToolCall, X as ToolCallFunction, Y as ToolCallRef, Z as ToolInfo, _ as ToolResponseEvent, o as ToolResponseRequiredEvent, T as Turn, $ as TurnCreatedEvent, a0 as TurnDoneEvent, g as TurnInputItem, a as TurnState, a1 as TurnStateCancelled, p as TurnStateDone, a2 as TurnStateError, a3 as TurnStateRunning, q as TurnStreamData, U as UpdateSessionRequest, s as UserMessage, a4 as UserMessageContent, f as UserToolApprovalEvent, e as UserToolResponseEvent } from '../types-BfiFf8O1.js';
+import { R as TurnStreamingEvent, Y as DeltaEvents, c as TurnEvent } from '../types-DbNsU075.js';
+export { Z as ActionRequiredEvent, h as AgentBuilderServer, b as AgentChatServer, _ as AgentInfo, $ as AgentParent, a0 as AgentSelectorEntry, A as AgentSpec, i as AgentUIServerPort, a1 as ApprovalDecision, j as CatalogServer, a2 as ChunkDeltaToolCall, k as ConnectorAuth, l as ConnectorAuthPublic, m as ConnectorAuthType, n as ConnectorBase, o as ConnectorCatalogEntry, p as ConnectorCatalogServer, q as ConnectorConfigBase, a3 as ConnectorSelectorEntry, r as CreateConnectorRequest, s as CreateModelProviderRequest, C as CreateSessionRequest, t as CreateSkillRequest, u as ListResult, a4 as ListSessionsOrder, L as ListSessionsParams, M as McpAuthRequiredEvent, a5 as McpInitializeEvent, a6 as McpServerAuthInfo, a7 as McpServerMount, a8 as Model, v as ModelCatalogServer, w as ModelEntry, a9 as ModelMessageContentPart, aa as ModelMessageDeltaEvent, x as ModelMessageEvent, ab as ModelParams, y as ModelProviderBase, z as ModelProviderCatalogEntry, B as ModelProviderConfigBase, ac as ModelSelectorEntry, ad as PageParams, P as PreviousTurnIdInput, D as ProviderType, E as SandboxCreatedEvent, ae as SearchAgentSelectorParams, S as Session, F as SessionEventItem, G as SkillBase, H as SkillCatalogServer, af as SkillMount, ag as SkillSelectorEntry, d as ThreadCreatedEvent, ah as ThreadDoneEvent, I as ToolApprovalRequiredEvent, J as ToolBase, K as ToolCall, ai as ToolCallFunction, aj as ToolCallRef, ak as ToolInfo, al as ToolResponseEvent, N as ToolResponseRequiredEvent, T as Turn, am as TurnCreatedEvent, an as TurnDoneEvent, g as TurnInputItem, a as TurnState, ao as TurnStateCancelled, O as TurnStateDone, ap as TurnStateError, aq as TurnStateRunning, Q as TurnStreamData, V as UpdateConnectorRequest, W as UpdateModelProviderRequest, U as UpdateSessionRequest, X as UserMessage, ar as UserMessageContent, f as UserToolApprovalEvent, e as UserToolResponseEvent } from '../types-DbNsU075.js';
 
 /**
  * Local implementations of streaming delta helpers.

package/dist/{types-BfiFf8O1.d.ts → types-DbNsU075.d.ts}

@@ -279,17 +279,15 @@ 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<...>`.
  */
-interface AgentSpec {
-    model: Model;
-    skills?: SkillMount[];
-    mcpServers?: McpServerMount[];
+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;
 }
 interface Session<TSpec extends AgentSpec = AgentSpec> {
     id: string;
@@ -464,5 +462,194 @@ interface AgentBuilderServer<TSpec extends AgentSpec = AgentSpec, TModel extends
         agentName: string;
     }): Promise<void>;
 }
+/**
+ * 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.
+ */
+type ProviderType = string;
+/**
+ * Model row — form "Model ID" + "Display name".
+ * Host extends for properties, etc.
+ */
+interface ModelEntry {
+    id: string;
+    name: string;
+}
+/**
+ * Write config for create/update (custom form + catalog "Save key").
+ * Host extends. `baseUrl` present iff `type === "custom"`.
+ */
+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.
+ */
+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.
+ */
+interface ModelProviderCatalogEntry<TModel extends ModelEntry = ModelEntry> {
+    type: ProviderType;
+    name: string;
+    models: TModel[];
+}
+/** Create — no `id`; server assigns it. Catalog path = entry + apiKey. */
+type CreateModelProviderRequest<TModel extends ModelEntry = ModelEntry> = ModelProviderConfigBase<TModel>;
+/** Update — `id` required. */
+type UpdateModelProviderRequest<TModel extends ModelEntry = ModelEntry> = ModelProviderConfigBase<TModel> & {
+    id: string;
+};
+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. */
+interface ToolBase {
+    id: string;
+    name: string;
+}
+/**
+ * Auth type id. Reserved literals: `"None"`, `"OAuth"`, `"API Key"`.
+ * Stays `string` so hosts can widen (same pattern as `ProviderType`).
+ */
+type ConnectorAuthType = string;
+/**
+ * Write-time connector auth. Host extends / narrows via `TType`.
+ * For `"API Key"`, pass `apiKey` (and optional `headerName`).
+ */
+interface ConnectorAuth<TType extends ConnectorAuthType = ConnectorAuthType> {
+    type: TType;
+    apiKey?: string;
+    headerName?: string;
+}
+/**
+ * Catalog / list auth — no secrets. Host extends / narrows via `TType`.
+ */
+interface ConnectorAuthPublic<TType extends ConnectorAuthType = ConnectorAuthType> {
+    type: TType;
+    headerName?: string;
+}
+/**
+ * MCP / connector create-edit config. Host extends for extra fields, etc.
+ */
+interface ConnectorConfigBase<TAuth extends ConnectorAuth = ConnectorAuth> {
+    name: string;
+    url: string;
+    auth: TAuth;
+}
+/**
+ * Connected connector row (settings/connectors). No raw `apiKey`.
+ * Host extends.
+ */
+interface ConnectorBase<TTool extends ToolBase = ToolBase, TAuth extends ConnectorAuthPublic = ConnectorAuthPublic> {
+    id: string;
+    name: string;
+    description: string;
+    url: string;
+    auth: TAuth;
+    authenticated: boolean;
+    tools: TTool[];
+}
+/** Discovery catalog entry for "+ Add MCP server". Host extends. */
+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. */
+type CreateConnectorRequest<TAuth extends ConnectorAuth = ConnectorAuth> = ConnectorConfigBase<TAuth>;
+/** Update connector — `id` required. Host extends. */
+type UpdateConnectorRequest<TAuth extends ConnectorAuth = ConnectorAuth> = ConnectorConfigBase<TAuth> & {
+    id: string;
+};
+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). Host may widen return with `authUrl`. */
+    authenticateConnector(req: {
+        id: string;
+    }): Promise<TConnector>;
+    /** Clear connector auth. */
+    disconnectConnector(req: {
+        id: string;
+    }): Promise<TConnector>;
+    deleteConnector?(req: {
+        id: string;
+    }): Promise<void>;
+}
+/** Skill row shown in settings/skills (list + delete). Host extends for fqn, etc. */
+interface SkillBase {
+    id: string;
+    name: string;
+    description: string;
+}
+/** Create-skill request. Host extends for branch, auth, etc. */
+interface CreateSkillRequest {
+    repo: string;
+    directory: string;
+}
+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.
+ */
+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.
+ */
+type AgentUIServerPort<TChat extends AgentChatServer = AgentChatServer, TBuilder extends AgentBuilderServer = AgentBuilderServer, TCatalog extends CatalogServer = CatalogServer> = TChat & TBuilder & {
+    catalog?: TCatalog;
+};
 
-export type { TurnCreatedEvent as $, AgentSpec as A, ListSessionsOrder as B, CreateSessionRequest as C, DeltaEvents as D, McpInitializeEvent as E, McpServerAuthInfo as F, McpServerMount as G, Model as H, ModelMessageContentPart as I, ModelMessageDeltaEvent as J, ModelParams as K, ListSessionsParams as L, McpAuthRequiredEvent as M, ModelSelectorEntry as N, PageParams as O, PreviousTurnIdInput as P, SearchAgentSelectorParams as Q, SkillMount as R, Session as S, Turn as T, UpdateSessionRequest as U, SkillSelectorEntry as V, ThreadDoneEvent as W, ToolCallFunction as X, ToolCallRef as Y, ToolInfo as Z, ToolResponseEvent as _, TurnState as a, TurnDoneEvent as a0, TurnStateCancelled as a1, TurnStateError as a2, TurnStateRunning as a3, UserMessageContent as a4, AgentChatServer as b, TurnEvent as c, ThreadCreatedEvent as d, UserToolResponseEvent as e, UserToolApprovalEvent as f, TurnInputItem as g, AgentBuilderServer as h, ListResult as i, ModelMessageEvent as j, SandboxCreatedEvent as k, SessionEventItem as l, ToolApprovalRequiredEvent as m, ToolCall as n, ToolResponseRequiredEvent as o, TurnStateDone as p, TurnStreamData as q, TurnStreamingEvent as r, UserMessage as s, ActionRequiredEvent as t, AgentInfo as u, AgentParent as v, AgentSelectorEntry as w, ApprovalDecision as x, ChunkDeltaToolCall as y, ConnectorSelectorEntry as z };
+export type { AgentParent as $, AgentSpec as A, ModelProviderConfigBase as B, CreateSessionRequest as C, ProviderType as D, SandboxCreatedEvent as E, SessionEventItem as F, SkillBase as G, SkillCatalogServer as H, ToolApprovalRequiredEvent as I, ToolBase as J, ToolCall as K, ListSessionsParams as L, McpAuthRequiredEvent as M, ToolResponseRequiredEvent as N, TurnStateDone as O, PreviousTurnIdInput as P, TurnStreamData as Q, TurnStreamingEvent as R, Session as S, Turn as T, UpdateSessionRequest as U, UpdateConnectorRequest as V, UpdateModelProviderRequest as W, UserMessage as X, DeltaEvents as Y, ActionRequiredEvent as Z, AgentInfo as _, TurnState as a, AgentSelectorEntry as a0, ApprovalDecision as a1, ChunkDeltaToolCall as a2, ConnectorSelectorEntry as a3, ListSessionsOrder as a4, McpInitializeEvent as a5, McpServerAuthInfo as a6, McpServerMount as a7, Model as a8, ModelMessageContentPart as a9, ModelMessageDeltaEvent as aa, ModelParams as ab, ModelSelectorEntry as ac, PageParams as ad, SearchAgentSelectorParams as ae, SkillMount as af, SkillSelectorEntry as ag, ThreadDoneEvent as ah, ToolCallFunction as ai, ToolCallRef as aj, ToolInfo as ak, ToolResponseEvent as al, TurnCreatedEvent as am, TurnDoneEvent as an, TurnStateCancelled as ao, TurnStateError as ap, TurnStateRunning as aq, UserMessageContent as ar, AgentChatServer as b, TurnEvent as c, ThreadCreatedEvent as d, UserToolResponseEvent as e, UserToolApprovalEvent as f, TurnInputItem as g, AgentBuilderServer as h, AgentUIServerPort as i, CatalogServer as j, ConnectorAuth as k, ConnectorAuthPublic as l, ConnectorAuthType as m, ConnectorBase as n, ConnectorCatalogEntry as o, ConnectorCatalogServer as p, ConnectorConfigBase as q, CreateConnectorRequest as r, CreateModelProviderRequest as s, CreateSkillRequest as t, ListResult as u, ModelCatalogServer as v, ModelEntry as w, ModelMessageEvent as x, ModelProviderBase as y, ModelProviderCatalogEntry as z };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truefoundry/assistant-ui-runtime",
-  "version": "0.1.6",
+  "version": "0.1.7",
   "description": "TrueFoundry Gateway agent runtime adapter for assistant-ui",
   "license": "Apache-2.0",
   "repository": {

package/src/{private → draft}/agentSpec.ts

@@ -1,33 +1,30 @@
 import type { AgentSpec } from "../server/types.js";
 
-export type { AgentSpec } from "../server/types.js";
-
 /** @deprecated Use Session with isMutable: true instead. Kept for title helper. */
 export type DraftSession = {
     title?: string | null;
     agentSpec: AgentSpec;
 };
 
-export type AgentSpecUpdate = {
-    instructions?: string;
-    model?: Partial<AgentSpec["model"]> & {
-        params?: Partial<NonNullable<AgentSpec["model"]["params"]>>;
-    };
-    mcpServers?: AgentSpec["mcpServers"];
-    skills?: AgentSpec["skills"];
-    messages?: AgentSpec["messages"];
-    variables?: AgentSpec["variables"];
-    responseFormat?: AgentSpec["responseFormat"];
-    config?: AgentSpec["config"];
+/** Partial update — host fields flow through when `TSpec` is widened. */
+export type AgentSpecUpdate<TSpec extends AgentSpec = AgentSpec> = {
+    [K in keyof TSpec]?: K extends "model"
+        ? Omit<Partial<TSpec["model"]>, "params"> & {
+              params?: Partial<NonNullable<TSpec["model"]["params"]>>;
+          }
+        : TSpec[K];
 };
 
-export function mergeAgentSpec(base: AgentSpec, update: AgentSpecUpdate): AgentSpec {
+export function mergeAgentSpec<TSpec extends AgentSpec>(
+    base: TSpec,
+    update: AgentSpecUpdate<TSpec>,
+): TSpec {
     const { model: modelUpdate, ...rest } = update;
 
-    const next: AgentSpec = {
+    const next = {
         ...base,
         ...rest,
-    };
+    } as TSpec;
 
     if (modelUpdate != null) {
         next.model = {
@@ -38,7 +35,7 @@ export function mergeAgentSpec(base: AgentSpec, update: AgentSpecUpdate): AgentS
                 modelUpdate.params != null
                     ? { ...base.model.params, ...modelUpdate.params }
                     : base.model.params,
-        };
+        } as TSpec["model"];
     }
 
     return next;

package/src/{private → draft}/draftSessionBridge.ts

@@ -1,5 +1,4 @@
-import type { AgentChatServer } from "../server/types.js";
-import type { AgentSpec } from "./agentSpec.js";
+import type { AgentChatServer, AgentSpec } from "../server/types.js";
 
 export const DRAFT_SESSION_LAST_UPDATED_AT_HEADER = "x-tfy-session-last-updated-at";
 

package/src/{private → draft}/truefoundryDraftThreadListAdapter.test.ts

@@ -3,7 +3,7 @@ import { describe, expect, it, vi } from "vitest";
 import type { AgentChatServer, Session } from "../server/index.js";
 
 import { createTrueFoundryDraftThreadListAdapter } from "./truefoundryDraftThreadListAdapter.js";
-import type { AgentSpec } from "./agentSpec.js";
+import type { AgentSpec } from "../server/types.js";
 
 const defaultAgentSpec: AgentSpec = {
     model: { name: "anthropic/claude-sonnet-4-6" },

package/src/{private → draft}/truefoundryDraftThreadListAdapter.ts

@@ -1,7 +1,8 @@
 import type { RemoteThreadListAdapter } from "@assistant-ui/core";
 
 import type { AgentChatServer } from "../server/types.js";
-import { draftSessionTitle, type AgentSpec } from "./agentSpec.js";
+import type { AgentSpec } from "../server/types.js";
+import { draftSessionTitle } from "./agentSpec.js";
 import { sessionListStartTimestamp } from "../sessionListStartTimestamp.js";
 
 const THREAD_LIST_PAGE_SIZE = 20;

package/src/{private → draft}/useDraftAgentSpec.ts

@@ -2,11 +2,8 @@
 
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 
-import {
-    mergeAgentSpec,
-    type AgentSpec,
-    type AgentSpecUpdate,
-} from "./agentSpec.js";
+import type { AgentSpec } from "../server/types.js";
+import { mergeAgentSpec, type AgentSpecUpdate } from "./agentSpec.js";
 import type { DraftSessionBridge } from "./draftSessionBridge.js";
 
 const SPEC_SYNC_DEBOUNCE_MS = 400;
@@ -22,6 +19,7 @@ export type UseDraftAgentSpecOptions = {
 export type UseDraftAgentSpecResult = {
     agentSpec: AgentSpec | null;
     draftSessionId: string | undefined;
+    isSpecLoading: boolean;
     isSpecSyncing: boolean;
     specError: unknown | null;
     updateAgentSpec: (update: AgentSpecUpdate) => void;
@@ -37,6 +35,7 @@ export function useDraftAgentSpec({
 }: UseDraftAgentSpecOptions): UseDraftAgentSpecResult {
     const enabled = draftBridge != null;
     const [agentSpec, setAgentSpec] = useState<AgentSpec>(defaultAgentSpec);
+    const [isSpecLoading, setIsSpecLoading] = useState(false);
     const [isSpecSyncing, setIsSpecSyncing] = useState(false);
     const [specError, setSpecError] = useState<unknown | null>(null);
 
@@ -86,6 +85,7 @@ export function useDraftAgentSpec({
             setAgentSpec(defaultAgentSpec);
             localDirtyRef.current = false;
             setSpecError(null);
+            setIsSpecLoading(false);
             return;
         }
 
@@ -94,6 +94,7 @@ export function useDraftAgentSpec({
         }
 
         let cancelled = false;
+        setIsSpecLoading(true);
         void (async () => {
             try {
                 const loaded = await draftBridge.getDraftAgentSpec(draftSessionId);
@@ -106,21 +107,29 @@ export function useDraftAgentSpec({
                     scheduleSpecSyncRef.current?.(draftSessionId, agentSpecRef.current);
                     localDirtyRef.current = false;
                     setSpecError(null);
+                    setIsSpecLoading(false);
                     return;
                 }
 
                 setAgentSpec(loaded);
                 setSpecError(null);
+                setIsSpecLoading(false);
             } catch (error) {
                 if (!cancelled) {
                     onError?.(error);
                     setSpecError(error);
+                    setIsSpecLoading(false);
                 }
             }
         })();
 
         return () => {
             cancelled = true;
+            // The cancelled load can no longer clear the flag itself. Releasing it
+            // here keeps it from sticking when the next run early-returns on an
+            // already-loaded draft; a run that starts a fresh load re-raises it in
+            // the same commit.
+            setIsSpecLoading(false);
         };
     }, [defaultAgentSpec, draftBridge, draftSessionId, enabled, onError]);
 
@@ -232,6 +241,7 @@ export function useDraftAgentSpec({
         () => ({
             agentSpec: enabled ? agentSpec : null,
             draftSessionId: enabled ? draftSessionId : undefined,
+            isSpecLoading: enabled ? isSpecLoading : false,
             isSpecSyncing: enabled ? isSpecSyncing : false,
             specError: enabled ? specError : null,
             updateAgentSpec,
@@ -241,6 +251,7 @@ export function useDraftAgentSpec({
             agentSpec,
             draftSessionId,
             enabled,
+            isSpecLoading,
             isSpecSyncing,
             specError,
             takeTurnHeaderTimestamp,

package/src/draftAgentConfig.test.ts

@@ -1,6 +1,7 @@
 import { describe, expect, it } from "vitest";
 
-import { mergeAgentSpec, type AgentSpec } from "./private/agentSpec.js";
+import { mergeAgentSpec } from "./draft/agentSpec.js";
+import type { AgentSpec } from "./server/types.js";
 import {
     resolveTrueFoundryAgentConfig,
     resolveTrueFoundryAgentRuntimeOptions,

package/src/index.ts

@@ -13,17 +13,17 @@ export {
 export type { ConvertTurnsResult, UserMessageContent } from "./convertTurnMessages.js";
 export { ROOT_THREAD_ID } from "./constants.js";
 export type {
-    UseTrueFoundryAgentRuntimeOptions,
     NamedAgentConfig,
     DraftAgentConfig,
     TrueFoundryAgentConfig,
+    UseTrueFoundryAgentRuntimeOptions,
 } from "./types.js";
-export type { AgentSpec, AgentSpecUpdate, DraftSession } from "./private/agentSpec.js";
-export { mergeAgentSpec, draftSessionTitle } from "./private/agentSpec.js";
-export { createTrueFoundryDraftThreadListAdapter } from "./private/truefoundryDraftThreadListAdapter.js";
+export type { AgentSpecUpdate, DraftSession } from "./draft/agentSpec.js";
+export { mergeAgentSpec, draftSessionTitle } from "./draft/agentSpec.js";
+export { createTrueFoundryDraftThreadListAdapter } from "./draft/truefoundryDraftThreadListAdapter.js";
 export { createTrueFoundryOwnedSessionsThreadListAdapter } from "./truefoundryOwnedSessionsThreadListAdapter.js";
-export { createDraftSessionBridge } from "./private/draftSessionBridge.js";
-export type { DraftSessionBridge } from "./private/draftSessionBridge.js";
+export { createDraftSessionBridge } from "./draft/draftSessionBridge.js";
+export type { DraftSessionBridge } from "./draft/draftSessionBridge.js";
 export {
     useTrueFoundryAgentSpec,
     useTrueFoundryUpdateAgentSpec,
@@ -82,7 +82,7 @@ export type {
     TurnState,
     TurnStateDone,
     TurnInputItem,
-    AgentSpec as ServerAgentSpec,
+    AgentSpec,
     ListResult,
     CreateSessionRequest,
     UpdateSessionRequest,
@@ -91,6 +91,29 @@ export type {
     UserToolApprovalEvent,
     UserToolResponseEvent,
     PreviousTurnIdInput,
+    ProviderType,
+    ModelEntry,
+    ModelProviderConfigBase,
+    ModelProviderBase,
+    ModelProviderCatalogEntry,
+    CreateModelProviderRequest,
+    UpdateModelProviderRequest,
+    ModelCatalogServer,
+    ToolBase,
+    ConnectorAuthType,
+    ConnectorAuth,
+    ConnectorAuthPublic,
+    ConnectorConfigBase,
+    ConnectorBase,
+    ConnectorCatalogEntry,
+    CreateConnectorRequest,
+    UpdateConnectorRequest,
+    ConnectorCatalogServer,
+    SkillBase,
+    CreateSkillRequest,
+    SkillCatalogServer,
+    CatalogServer,
+    AgentUIServerPort,
 } from "./server/index.js";
 export type {
     SandboxCreatedEvent,

package/src/plugins/truefoundry-agent-server-adapter/index.ts

@@ -94,6 +94,15 @@ export type TrueFoundryChatServer<TSpec extends TfyAgentSpec = TfyAgentSpec> =
         };
     };
 
+/** Gateway SDK errors carry the HTTP status as `statusCode`. */
+function isNotFound(error: unknown): boolean {
+    return (
+        typeof error === "object" &&
+        error !== null &&
+        (error as { statusCode?: unknown }).statusCode === 404
+    );
+}
+
 function isDraft(session: GwSession): session is AgentDraftSession {
     return (session as AgentDraftSession).type === "session/draft";
 }
@@ -153,7 +162,7 @@ async function toListResult<TIn, TOut>(
  * Wraps TrueFoundry gateway clients into a flat `AgentChatServer`.
  * Named vs draft routing is fully internal — an in-memory session-type cache
  * (populated by createSession/listSessions) determines which gateway client
- * to call. No try/catch fallback, no double network calls.
+ * to call, falling back to a one-time probe for ids seen only in a URL.
  */
 export function createTrueFoundryChatServer<
     TSpec extends TfyAgentSpec = TfyAgentSpec,
@@ -166,6 +175,7 @@ export function createTrueFoundryChatServer<
         opts.privateClient ?? new PrivateAgentSessionClient(gatewayOpts);
 
     const sessionTypeCache = new Map<string, boolean>();
+    const sessionTypeProbes = new Map<string, Promise<boolean>>();
 
     function cacheSessionType(session: {
         id: string;
@@ -174,18 +184,48 @@ export function createTrueFoundryChatServer<
         sessionTypeCache.set(session.id, session.isMutable);
     }
 
-    function getSessionObj(sessionId: string): Promise<GwSession> {
-        const isMutable = sessionTypeCache.get(sessionId);
-        if (isMutable === true) {
-            return privateClient.getDraftSession({ draftSessionId: sessionId });
+    /**
+     * Resolving a session id straight from a URL (page reload / shared link)
+     * reaches the gateway before createSession or listSessions has cached the
+     * type, so discover it by probing the draft endpoint and falling back to
+     * the conversation endpoint. Concurrent callers share one probe.
+     */
+    async function probeSessionType(sessionId: string): Promise<boolean> {
+        const inflight = sessionTypeProbes.get(sessionId);
+        if (inflight != null) {
+            return inflight;
         }
-        if (isMutable === false) {
-            return client.getSession({ sessionId });
+        const probe = (async () => {
+            try {
+                await privateClient.getDraftSession({ draftSessionId: sessionId });
+                return true;
+            } catch (error) {
+                // Only a miss proves the id isn't a draft. Auth or transient
+                // failures would otherwise be retried as a conversation session
+                // and mislabel a real draft as named.
+                if (!isNotFound(error)) {
+                    throw error;
+                }
+                await client.getSession({ sessionId });
+                return false;
+            }
+        })();
+        sessionTypeProbes.set(sessionId, probe);
+        try {
+            const isMutable = await probe;
+            sessionTypeCache.set(sessionId, isMutable);
+            return isMutable;
+        } finally {
+            sessionTypeProbes.delete(sessionId);
         }
-        throw new Error(
-            `Cannot resolve session "${sessionId}": session type not cached. ` +
-                `Ensure createSession or listSessions was called first.`,
-        );
+    }
+
+    async function getSessionObj(sessionId: string): Promise<GwSession> {
+        const isMutable =
+            sessionTypeCache.get(sessionId) ?? (await probeSessionType(sessionId));
+        return isMutable
+            ? privateClient.getDraftSession({ draftSessionId: sessionId })
+            : client.getSession({ sessionId });
     }
 
     const server: TrueFoundryChatServer<TSpec> = {

package/src/plugins/truefoundry-agent-server-adapter/types.ts

@@ -63,10 +63,12 @@ export type TfyMcpServerMount = RuntimeMcpServerMount & TruefoundryGatewayApi.Mc
 // AgentSpec — the concrete TrueFoundry agent definition
 // ---------------------------------------------------------------------------
 
-export interface TfyAgentSpec extends AgentSpec {
-    model: TruefoundryGatewayApi.Model;
-    skills?: TfySkillMount[];
-    mcpServers?: TfyMcpServerMount[];
+export interface TfyAgentSpec
+    extends AgentSpec<
+        TruefoundryGatewayApi.Model,
+        TfySkillMount,
+        TfyMcpServerMount
+    > {
     config?: TruefoundryGatewayApi.RuntimeConfig;
     responseFormat?: TruefoundryGatewayApi.ResponseFormat;
     messages?: TruefoundryGatewayApi.AgentSpecUserMessage[];