@truefoundry/assistant-ui-runtime 0.1.8 → 0.1.10-rc.1

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, w as CreateSessionRequest, y as ListSessionsParams, S as Session, d as Turn, W as TurnState, a as AgentChatServer, a0 as UpdateSessionRequest, a2 as AgentSelectorEntry, a3 as ConnectorSelectorEntry, a4 as ModelSelectorEntry, a5 as SkillSelectorEntry, f as AgentBuilderServer } from '../../types-B_z-FsDS.js';
+import { A as AgentSpec, x as CreateSessionRequest, B as ListSessionsParams, S as Session, d as Turn, a7 as TurnState, a as AgentChatServer, ae as UpdateSessionRequest, ag as AgentSelectorEntry, ah as ConnectorSelectorEntry, ai as ModelSelectorEntry, aj as SkillSelectorEntry, f as AgentBuilderServer } from '../../types-CgZUnILu.js';
 import { TruefoundryGatewayApi } from 'truefoundry-gateway-sdk';
 
 /**

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

@@ -7,7 +7,7 @@ import {
   isTfyMcpToolInfo,
   isTfySystemToolInfo,
   isTfyToolInfo
-} from "../../chunk-CXBZ6WLZ.js";
+} from "../../chunk-BRPTG6VA.js";
 export {
   createTrueFoundryAgentUIServer,
   createTrueFoundryChatServer,

package/dist/server/index.d.ts

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

package/dist/{types-B_z-FsDS.d.ts → types-CgZUnILu.d.ts}

@@ -231,6 +231,7 @@ type DeltaEvents = ModelMessageDeltaEvent;
 interface ModelSelectorEntry {
     name: string;
     provider: string;
+    reasoningEfforts?: string[];
 }
 /** Skill selector row. Host extends for fqn, preload, etc. */
 interface SkillSelectorEntry {
@@ -441,7 +442,15 @@ interface AgentChatServer<TSpec extends AgentSpec = AgentSpec, TSession extends
         afterSequenceNumber?: number;
         abortSignal?: AbortSignal;
     }): AsyncIterable<TurnStreamData>;
-    downloadSandboxFile?(sandboxId: string, req: {
+    /**
+     * Reads a file the agent wrote inside its sandbox. Hosts whose download route is scoped to a
+     * turn resolve the sandbox from `turnId` and ignore `sandboxId`; hosts addressing sandboxes
+     * directly use `sandboxId`.
+     */
+    downloadSandboxFile?(req: {
+        sessionId: string;
+        turnId: string;
+        sandboxId: string;
         path: string;
     }): Promise<Blob>;
 }
@@ -532,15 +541,16 @@ interface ModelCatalogServer<TModel extends ModelEntry = ModelEntry, TProvider e
 interface ToolBase {
     id: string;
     name: string;
+    description: string;
 }
 /** Strict auth type id. Hosts widen branches via intersection + re-union. */
-type ConnectorAuthType = "oauth" | "apiKey" | "none";
+type ConnectorAuthType = "dcr" | "header" | "none";
 type ConnectorAuthOAuth = {
-    type: "oauth";
+    type: "dcr";
     authUrl?: string;
 };
 type ConnectorAuthApiKey = {
-    type: "apiKey";
+    type: "header";
     apiKey?: string;
     headerName?: string;
 };
@@ -549,11 +559,11 @@ type ConnectorAuthNone = {
 };
 type ConnectorAuth = ConnectorAuthOAuth | ConnectorAuthApiKey | ConnectorAuthNone;
 type ConnectorAuthPublicOAuth = {
-    type: "oauth";
+    type: "dcr";
     authUrl: string;
 };
 type ConnectorAuthPublicApiKey = {
-    type: "apiKey";
+    type: "header";
     headerName?: string;
 };
 type ConnectorAuthPublicNone = {
@@ -626,12 +636,36 @@ interface SkillBase {
     name: string;
     description: string;
 }
-/** Create-skill request. Host extends for branch, auth, etc. */
-interface CreateSkillRequest {
-    repo: string;
-    directory: string;
+interface RegistrySkill extends SkillBase {
+    /** `SkillCatalogEntry.id` this skill was created from. */
+    catalogId: string;
+}
+interface GithubSkill extends SkillBase {
+}
+type DefinedSkill = RegistrySkill | GithubSkill;
+/** Git source fields shared by catalog entries and create requests. */
+interface SkillConfigBase {
+    name: string;
+    description: string;
+    repoURL: string;
+    path: string;
+    ref: string;
 }
-interface SkillCatalogServer<TSkill extends SkillBase = SkillBase, TCreate extends CreateSkillRequest = CreateSkillRequest> {
+interface SkillCatalogEntry extends SkillConfigBase {
+    id: string;
+}
+/** Create-skill base. Hosts may intersect extra fields and re-union. */
+interface CreateSkillRequestBase extends SkillConfigBase {
+}
+interface SelectRegistrySkillRequest extends CreateSkillRequestBase {
+    /** `SkillCatalogEntry.id`, persisted so the created skill links back to it. */
+    catalogId: string;
+}
+interface ImportGithubSkillRequest extends CreateSkillRequestBase {
+}
+type CreateSkillRequest = SelectRegistrySkillRequest | ImportGithubSkillRequest;
+interface SkillCatalogServer<TSkill extends SkillBase = SkillBase, TCatalogEntry extends SkillCatalogEntry = SkillCatalogEntry, TCreate extends CreateSkillRequest = CreateSkillRequest> {
+    getSkillCatalog(): Promise<TCatalogEntry[]>;
     listSkills(req?: {
         query?: string;
     }): Promise<TSkill[]>;
@@ -640,15 +674,59 @@ interface SkillCatalogServer<TSkill extends SkillBase = SkillBase, TCreate exten
         id: string;
     }): Promise<void>;
 }
+/** Mutable sandbox settings shared by catalog rows, create, and update. */
+interface SandboxConfig {
+    snapshotName: string;
+    execTimeoutMs: number;
+    autoStopIntervalInMinutes: number;
+    autoArchiveIntervalInMinutes: number;
+    autoDeleteIntervalInMinutes: number;
+}
+interface SandboxCatalogEntry extends SandboxConfig {
+    id: string;
+    name: string;
+    type: string;
+}
+interface SandboxBase {
+    id: string;
+    name: string;
+    catalogId: string;
+    isConnected: boolean;
+}
+interface CreateSandboxRequest extends SandboxConfig {
+    /** `SandboxCatalogEntry.id` used to create this sandbox. */
+    catalogId: string;
+    name: string;
+    type: string;
+    apiKey: string;
+}
+interface UpdateSandboxRequest extends SandboxConfig {
+    id: string;
+    apiKey: string;
+}
+interface SandboxCatalogServer<TSandbox extends SandboxBase = SandboxBase, TCatalogEntry extends SandboxCatalogEntry = SandboxCatalogEntry, TCreate extends CreateSandboxRequest = CreateSandboxRequest, TUpdate extends UpdateSandboxRequest = UpdateSandboxRequest> {
+    getSandboxCatalog(): Promise<TCatalogEntry[]>;
+    listSandboxes(req?: {
+        query?: string;
+    }): Promise<TSandbox[]>;
+    createSandbox(req: TCreate): Promise<TSandbox>;
+    updateSandbox(req: TUpdate): Promise<TSandbox>;
+    deleteSandbox(req: {
+        id: string;
+    }): Promise<void>;
+}
 /**
- * Settings management aggregate — modelCatalog + connectorCatalog + optional skillCatalog.
+ * Settings management aggregate — modelCatalog + connectorCatalog + optional
+ * skill and sandbox catalogs.
  * 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> {
+interface CatalogServer<TModelCatalog extends ModelCatalogServer = ModelCatalogServer, TConnectorCatalog extends ConnectorCatalogServer = ConnectorCatalogServer, TSkillCatalog extends SkillCatalogServer = SkillCatalogServer, TSandboxCatalog extends SandboxCatalogServer = SandboxCatalogServer> {
     modelCatalog: TModelCatalog;
     connectorCatalog: TConnectorCatalog;
     /** Optional — omit when the host has no skills settings surface. */
     skillCatalog?: TSkillCatalog;
+    /** Optional — omit when the host has no sandboxes settings surface. */
+    sandboxCatalog?: TSandboxCatalog;
 }
 /**
  * Composed host port: chat + builder + optional settings catalog.
@@ -663,4 +741,4 @@ type AgentUIServerPort<TChat extends AgentChatServer = AgentChatServer, TBuilder
     catalog?: TCatalog;
 };
 
-export type { UpdateModelProviderRequest as $, AgentSpec as A, ModelEntry as B, CatalogServer as C, ModelMessageEvent as D, ModelProviderBase as E, ModelProviderCatalogEntry as F, ModelProviderConfigBase as G, ProviderType as H, SandboxCreatedEvent as I, SessionEventItem as J, SkillBase as K, ListResult as L, McpAuthRequiredEvent as M, SkillCatalogServer as N, ToolApprovalRequiredEvent as O, PreviousTurnIdInput as P, ToolBase as Q, ToolCall as R, Session as S, TurnEvent as T, UserToolResponseEvent as U, ToolResponseRequiredEvent as V, TurnState as W, TurnStateDone as X, TurnStreamData as Y, TurnStreamingEvent as Z, UpdateConnectorRequest as _, AgentChatServer as a, UpdateSessionRequest as a0, UserMessage as a1, AgentSelectorEntry as a2, ConnectorSelectorEntry as a3, ModelSelectorEntry as a4, SkillSelectorEntry as a5, DeltaEvents as a6, ActionRequiredEvent as a7, AgentInfo as a8, AgentParent as a9, ApprovalDecision as aa, ChunkDeltaToolCall as ab, ListSessionsOrder as ac, McpInitializeEvent as ad, McpServerAuthInfo as ae, McpServerMount as af, Model as ag, ModelMessageContentPart as ah, ModelMessageDeltaEvent as ai, ModelParams as aj, PageParams as ak, SearchAgentSelectorParams as al, SkillMount as am, ThreadDoneEvent as an, ToolCallFunction as ao, ToolCallRef as ap, ToolInfo as aq, ToolResponseEvent as ar, TurnCreatedEvent as as, TurnDoneEvent as at, TurnStateCancelled as au, TurnStateError as av, TurnStateRunning as aw, UserMessageContent as ax, ThreadCreatedEvent as b, UserToolApprovalEvent as c, Turn as d, TurnInputItem as e, AgentBuilderServer as f, AgentUIServerPort as g, ConnectorAuth as h, ConnectorAuthApiKey as i, ConnectorAuthNone as j, ConnectorAuthOAuth as k, ConnectorAuthPublic as l, ConnectorAuthPublicApiKey as m, ConnectorAuthPublicNone as n, ConnectorAuthPublicOAuth as o, ConnectorAuthType as p, ConnectorBase as q, ConnectorCatalogEntry as r, ConnectorCatalogServer as s, ConnectorConfigBase as t, CreateConnectorRequest as u, CreateModelProviderRequest as v, CreateSessionRequest as w, CreateSkillRequest as x, ListSessionsParams as y, ModelCatalogServer as z };
+export type { SkillBase as $, AgentSpec as A, ListSessionsParams as B, CatalogServer as C, DefinedSkill as D, ModelCatalogServer as E, ModelEntry as F, GithubSkill as G, ModelMessageEvent as H, ImportGithubSkillRequest as I, ModelProviderBase as J, ModelProviderCatalogEntry as K, ListResult as L, McpAuthRequiredEvent as M, ModelProviderConfigBase as N, ProviderType as O, PreviousTurnIdInput as P, SandboxBase as Q, RegistrySkill as R, Session as S, TurnEvent as T, UserToolResponseEvent as U, SandboxCatalogEntry as V, SandboxCatalogServer as W, SandboxConfig as X, SandboxCreatedEvent as Y, SelectRegistrySkillRequest as Z, SessionEventItem as _, AgentChatServer as a, SkillCatalogEntry as a0, SkillCatalogServer as a1, SkillConfigBase as a2, ToolApprovalRequiredEvent as a3, ToolBase as a4, ToolCall as a5, ToolResponseRequiredEvent as a6, TurnState as a7, TurnStateDone as a8, TurnStreamData as a9, SkillMount as aA, ThreadDoneEvent as aB, ToolCallFunction as aC, ToolCallRef as aD, ToolInfo as aE, ToolResponseEvent as aF, TurnCreatedEvent as aG, TurnDoneEvent as aH, TurnStateCancelled as aI, TurnStateError as aJ, TurnStateRunning as aK, UserMessageContent as aL, TurnStreamingEvent as aa, UpdateConnectorRequest as ab, UpdateModelProviderRequest as ac, UpdateSandboxRequest as ad, UpdateSessionRequest as ae, UserMessage as af, AgentSelectorEntry as ag, ConnectorSelectorEntry as ah, ModelSelectorEntry as ai, SkillSelectorEntry as aj, DeltaEvents as ak, ActionRequiredEvent as al, AgentInfo as am, AgentParent as an, ApprovalDecision as ao, ChunkDeltaToolCall as ap, ListSessionsOrder as aq, McpInitializeEvent as ar, McpServerAuthInfo as as, McpServerMount as at, Model as au, ModelMessageContentPart as av, ModelMessageDeltaEvent as aw, ModelParams as ax, PageParams as ay, SearchAgentSelectorParams as az, ThreadCreatedEvent as b, UserToolApprovalEvent as c, Turn as d, TurnInputItem as e, AgentBuilderServer as f, AgentUIServerPort as g, ConnectorAuth as h, ConnectorAuthApiKey as i, ConnectorAuthNone as j, ConnectorAuthOAuth as k, ConnectorAuthPublic as l, ConnectorAuthPublicApiKey as m, ConnectorAuthPublicNone as n, ConnectorAuthPublicOAuth as o, ConnectorAuthType as p, ConnectorBase as q, ConnectorCatalogEntry as r, ConnectorCatalogServer as s, ConnectorConfigBase as t, CreateConnectorRequest as u, CreateModelProviderRequest as v, CreateSandboxRequest as w, CreateSessionRequest as x, CreateSkillRequest as y, CreateSkillRequestBase as z };

package/package.json

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

package/src/convertTurnMessages.test.ts

@@ -461,6 +461,26 @@ describe("convertTurnMessages", () => {
             expect(updated.id).toBe(existing.id);
             expect(updated.content).toEqual([{ type: "text", text: "second" }]);
         });
+
+        it("stamps the streaming turn id onto the message metadata", () => {
+            const message = turnStreamUpdateToAssistantMessage("turn-1", {
+                content: [{ type: "text", text: "hi" }],
+            });
+            expect(message.metadata.custom.turnId).toBe("turn-1");
+        });
+
+        it("advances the turn id when a continuation reuses the existing message", () => {
+            const existing = turnStreamUpdateToAssistantMessage("turn-1", {
+                content: [{ type: "text", text: "first" }],
+            });
+            const updated = turnStreamUpdateToAssistantMessage(
+                "turn-2",
+                { content: [{ type: "text", text: "second" }] },
+                existing,
+            );
+            expect(updated.id).toBe("turn-1-assistant");
+            expect(updated.metadata.custom.turnId).toBe("turn-2");
+        });
     });
 
     describe("repositoryItemsFromMessages", () => {
@@ -546,7 +566,7 @@ describe("convertTurnMessages", () => {
 
             expect(result.messages[1]).toMatchObject({
                 role: "assistant",
-                metadata: { custom: { sandboxId: "sbx-123" } },
+                metadata: { custom: { sandboxId: "sbx-123", turnId: "turn-1" } },
             });
         });
 
@@ -601,6 +621,8 @@ describe("convertTurnMessages", () => {
                 { type: "text", text: "first chunk" },
                 { type: "text", text: " after approval" },
             ]);
+            // Artifacts on a merged message belong to the turn that wrote them last.
+            expect(assistant.metadata.custom.turnId).toBe("turn-2");
         });
 
         it("preserves requires-action on reload when a turn ends awaiting tool approval", async () => {

package/src/convertTurnMessages.ts

@@ -1074,8 +1074,14 @@ function projectHistoryTurns(
             content,
             record,
         );
-        const custom =
-            record.sandboxId != null ? { ...baseCustom, sandboxId: record.sandboxId } : baseCustom;
+        // Continuation turns fold into the previous assistant message and overwrite this custom,
+        // so a folded message reports the latest turn that contributed to it — the one whose
+        // sandbox wrote the newest artifacts.
+        const custom = {
+            ...baseCustom,
+            turnId: record.id,
+            ...(record.sandboxId != null ? { sandboxId: record.sandboxId } : {}),
+        };
 
         if (record.userText) {
             messages.push(
@@ -1732,7 +1738,7 @@ export function turnStreamUpdateToAssistantMessage(
             unstable_annotations: [],
             unstable_data: [],
             steps: [],
-            custom: update.metadata?.custom ?? {},
+            custom: { ...update.metadata?.custom, turnId },
         },
     };
 }

package/src/hooks.ts

@@ -1,8 +1,9 @@
 "use client";
 
 import { useMemo } from "react";
-import { useAui } from "@assistant-ui/store";
+import { useAui, useAuiState } from "@assistant-ui/store";
 
+import type { TrueFoundryMessageCustomMetadata } from "./messageCustomMetadata.js";
 import {
     EMPTY_DRAFT_EXTRAS,
     trueFoundryExtras,
@@ -86,10 +87,29 @@ export const useTrueFoundryResumeMcpAuth = () => {
 export const useTrueFoundrySandboxId = (): string | undefined =>
     trueFoundryExtras.use((e) => e.sandboxId, undefined);
 
-/** Returns a function to download a sandbox file by path from any render context. */
+/** Turn that produced the message being rendered. Only defined inside a message scope. */
+export const useTrueFoundryTurnId = (): string | undefined =>
+    useAuiState(
+        (state) =>
+            (state.message.metadata?.custom as TrueFoundryMessageCustomMetadata | undefined)
+                ?.turnId,
+    );
+
+/**
+ * Returns a function to download a file the current turn wrote to its sandbox. Must be called
+ * from a message scope, since the artifact belongs to the turn that rendered it.
+ */
 export const useTrueFoundryDownloadSandboxFile = () => {
     const aui = useAui();
-    return (path: string) => trueFoundryExtras.get(aui).downloadSandboxFile(path);
+    const turnId = useTrueFoundryTurnId();
+    return (path: string) => {
+        if (turnId == null) {
+            throw new Error(
+                "Downloading a sandbox file requires a message scope to resolve its turn.",
+            );
+        }
+        return trueFoundryExtras.get(aui).downloadSandboxFile({ turnId, path });
+    };
 };
 
 /** Returns a function to cancel the current run from any render context. */

package/src/index.ts

@@ -49,6 +49,7 @@ export {
     useTrueFoundryRespondToToolResponse,
     useTrueFoundryResumeMcpAuth,
     useTrueFoundrySandboxId,
+    useTrueFoundryTurnId,
     useTrueFoundryDownloadSandboxFile,
     useTrueFoundryCancel,
     useTrueFoundryResetFromTurn,
@@ -116,8 +117,22 @@ export type {
     UpdateConnectorRequest,
     ConnectorCatalogServer,
     SkillBase,
+    RegistrySkill,
+    GithubSkill,
+    DefinedSkill,
+    SkillConfigBase,
+    SkillCatalogEntry,
+    CreateSkillRequestBase,
+    SelectRegistrySkillRequest,
+    ImportGithubSkillRequest,
     CreateSkillRequest,
     SkillCatalogServer,
+    SandboxConfig,
+    SandboxCatalogEntry,
+    SandboxBase,
+    CreateSandboxRequest,
+    UpdateSandboxRequest,
+    SandboxCatalogServer,
     CatalogServer,
     AgentUIServerPort,
 } from "./server/index.js";

package/src/messageCustomMetadata.ts

@@ -10,6 +10,8 @@ export type TrueFoundryMessageCustomMetadata = {
     pendingMcpAuth?: true;
     mcpServers?: McpAuthRequiredEvent["mcpServers"];
     sandboxId?: string;
+    /** Turn that produced this message. Scopes artifact downloads to their own turn. */
+    turnId?: string;
     [TOOL_APPROVAL_THREAD_ID_CUSTOM_KEY]?: string;
     [TOOL_RESPONSE_THREAD_ID_CUSTOM_KEY]?: string;
 };

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

@@ -350,11 +350,12 @@ export function createTrueFoundryChatServer<
             ) as AsyncIterable<TurnStreamData>;
         },
 
-        async downloadSandboxFile(sandboxId, req) {
-            const response = await privateClient.downloadSandboxFile(
-                sandboxId,
-                req,
-            );
+        // The gateway addresses sandboxes directly, so the turn is carried for hosts that need it
+        // but is not part of this route.
+        async downloadSandboxFile({ sandboxId, path }) {
+            const response = await privateClient.downloadSandboxFile(sandboxId, {
+                path,
+            });
             return await response.blob();
         },
 

package/src/server/index.ts

@@ -56,8 +56,22 @@ export type {
     UpdateConnectorRequest,
     ConnectorCatalogServer,
     SkillBase,
+    RegistrySkill,
+    GithubSkill,
+    DefinedSkill,
+    SkillConfigBase,
+    SkillCatalogEntry,
+    CreateSkillRequestBase,
+    SelectRegistrySkillRequest,
+    ImportGithubSkillRequest,
     CreateSkillRequest,
     SkillCatalogServer,
+    SandboxConfig,
+    SandboxCatalogEntry,
+    SandboxBase,
+    CreateSandboxRequest,
+    UpdateSandboxRequest,
+    SandboxCatalogServer,
     CatalogServer,
     AgentUIServerPort,
 } from "./types.js";

package/src/server/types.ts

@@ -21,6 +21,7 @@ import type {
 export interface ModelSelectorEntry {
     name: string;
     provider: string;
+    reasoningEfforts?: string[];
 }
 
 /** Skill selector row. Host extends for fqn, preload, etc. */
@@ -290,10 +291,17 @@ export interface AgentChatServer<
         abortSignal?: AbortSignal;
     }): AsyncIterable<TurnStreamData>;
 
-    downloadSandboxFile?(
-        sandboxId: string,
-        req: { path: string },
-    ): Promise<Blob>;
+    /**
+     * Reads a file the agent wrote inside its sandbox. Hosts whose download route is scoped to a
+     * turn resolve the sandbox from `turnId` and ignore `sandboxId`; hosts addressing sandboxes
+     * directly use `sandboxId`.
+     */
+    downloadSandboxFile?(req: {
+        sessionId: string;
+        turnId: string;
+        sandboxId: string;
+        path: string;
+    }): Promise<Blob>;
 }
 
 /**
@@ -405,15 +413,16 @@ export interface ModelCatalogServer<
 export interface ToolBase {
     id: string;
     name: string;
+    description: string;
 }
 
 /** Strict auth type id. Hosts widen branches via intersection + re-union. */
-export type ConnectorAuthType = "oauth" | "apiKey" | "none";
+export type ConnectorAuthType = "dcr" | "header" | "none";
 
 // Write (create/update) — export branches so hosts can intersect extras
-export type ConnectorAuthOAuth = { type: "oauth"; authUrl?: string };
+export type ConnectorAuthOAuth = { type: "dcr"; authUrl?: string };
 export type ConnectorAuthApiKey = {
-    type: "apiKey";
+    type: "header";
     apiKey?: string;
     headerName?: string;
 };
@@ -423,10 +432,10 @@ export type ConnectorAuth =
     | ConnectorAuthApiKey
     | ConnectorAuthNone;
 
-// Public (list/detail) — no secrets; oauth requires authUrl
-export type ConnectorAuthPublicOAuth = { type: "oauth"; authUrl: string };
+// Public (list/detail) — no secrets; dcr requires authUrl
+export type ConnectorAuthPublicOAuth = { type: "dcr"; authUrl: string };
 export type ConnectorAuthPublicApiKey = {
-    type: "apiKey";
+    type: "header";
     headerName?: string;
 };
 export type ConnectorAuthPublicNone = { type: "none" };
@@ -525,34 +534,122 @@ export interface SkillBase {
     description: string;
 }
 
-/** Create-skill request. Host extends for branch, auth, etc. */
-export interface CreateSkillRequest {
-    repo: string;
-    directory: string;
+export interface RegistrySkill extends SkillBase {
+    /** `SkillCatalogEntry.id` this skill was created from. */
+    catalogId: string;
+}
+
+export interface GithubSkill extends SkillBase {}
+
+export type DefinedSkill = RegistrySkill | GithubSkill;
+
+/** Git source fields shared by catalog entries and create requests. */
+export interface SkillConfigBase {
+    name: string;
+    description: string;
+    repoURL: string;
+    path: string;
+    ref: string;
+}
+
+export interface SkillCatalogEntry extends SkillConfigBase {
+    id: string;
+}
+
+/** Create-skill base. Hosts may intersect extra fields and re-union. */
+export interface CreateSkillRequestBase extends SkillConfigBase {}
+
+export interface SelectRegistrySkillRequest extends CreateSkillRequestBase {
+    /** `SkillCatalogEntry.id`, persisted so the created skill links back to it. */
+    catalogId: string;
 }
 
+export interface ImportGithubSkillRequest extends CreateSkillRequestBase {}
+
+export type CreateSkillRequest =
+    | SelectRegistrySkillRequest
+    | ImportGithubSkillRequest;
+
 export interface SkillCatalogServer<
     TSkill extends SkillBase = SkillBase,
+    TCatalogEntry extends SkillCatalogEntry = SkillCatalogEntry,
     TCreate extends CreateSkillRequest = CreateSkillRequest,
 > {
+    getSkillCatalog(): Promise<TCatalogEntry[]>;
     listSkills(req?: { query?: string }): Promise<TSkill[]>;
     createSkill(req: TCreate): Promise<TSkill>;
     deleteSkill?(req: { id: string }): Promise<void>;
 }
 
+// ---------------------------------------------------------------------------
+// Sandboxes catalog — public rows omit credentials; writes accept them
+// ---------------------------------------------------------------------------
+
+/** Mutable sandbox settings shared by catalog rows, create, and update. */
+export interface SandboxConfig {
+    snapshotName: string;
+    execTimeoutMs: number;
+    autoStopIntervalInMinutes: number;
+    autoArchiveIntervalInMinutes: number;
+    autoDeleteIntervalInMinutes: number;
+}
+
+export interface SandboxCatalogEntry extends SandboxConfig {
+    id: string;
+    name: string;
+    type: string;
+}
+
+export interface SandboxBase {
+    id: string;
+    name: string;
+    catalogId: string;
+    isConnected: boolean;
+}
+
+export interface CreateSandboxRequest extends SandboxConfig {
+    /** `SandboxCatalogEntry.id` used to create this sandbox. */
+    catalogId: string;
+    name: string;
+    type: string;
+    apiKey: string;
+}
+
+export interface UpdateSandboxRequest extends SandboxConfig {
+    id: string;
+    apiKey: string;
+}
+
+export interface SandboxCatalogServer<
+    TSandbox extends SandboxBase = SandboxBase,
+    TCatalogEntry extends SandboxCatalogEntry = SandboxCatalogEntry,
+    TCreate extends CreateSandboxRequest = CreateSandboxRequest,
+    TUpdate extends UpdateSandboxRequest = UpdateSandboxRequest,
+> {
+    getSandboxCatalog(): Promise<TCatalogEntry[]>;
+    listSandboxes(req?: { query?: string }): Promise<TSandbox[]>;
+    createSandbox(req: TCreate): Promise<TSandbox>;
+    updateSandbox(req: TUpdate): Promise<TSandbox>;
+    deleteSandbox(req: { id: string }): Promise<void>;
+}
+
 /**
- * Settings management aggregate — modelCatalog + connectorCatalog + optional skillCatalog.
+ * Settings management aggregate — modelCatalog + connectorCatalog + optional
+ * skill and sandbox catalogs.
  * 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,
+    TSandboxCatalog extends SandboxCatalogServer = SandboxCatalogServer,
 > {
     modelCatalog: TModelCatalog;
     connectorCatalog: TConnectorCatalog;
     /** Optional — omit when the host has no skills settings surface. */
     skillCatalog?: TSkillCatalog;
+    /** Optional — omit when the host has no sandboxes settings surface. */
+    sandboxCatalog?: TSandboxCatalog;
 }
 
 /**

package/src/truefoundryExtras.ts

@@ -26,7 +26,7 @@ export type TrueFoundryRuntimeExtras = {
     respondToToolApproval: (response: RespondToToolApprovalOptions) => void;
     respondToToolResponse: (response: RespondToToolResponseOptions) => void;
     resumeMcpAuth: () => Promise<void>;
-    downloadSandboxFile: (path: string) => Promise<Blob>;
+    downloadSandboxFile: (req: { turnId: string; path: string }) => Promise<Blob>;
     cancel: () => Promise<void>;
     resetFromTurn: (turnId: string) => Promise<void>;
     reload: () => void;

package/src/useTrueFoundryAgentRuntime.ts

@@ -152,18 +152,28 @@ function useTrueFoundryAgentRuntimeImpl(
     );
 
     const downloadSandboxFile = useCallback(
-        async (path: string) => {
+        async ({ turnId, path }: { turnId: string; path: string }) => {
             if (server.downloadSandboxFile == null) {
                 throw new Error(
                     "Downloading a sandbox file requires AgentChatServer.downloadSandboxFile.",
                 );
             }
+            if (sessionId == null) {
+                throw new Error(
+                    "This session has not been saved yet, so its files cannot be downloaded.",
+                );
+            }
             if (sandboxId == null) {
                 throw new Error("No sandbox is available yet for this session.");
             }
-            return await server.downloadSandboxFile(sandboxId, { path });
+            return await server.downloadSandboxFile({
+                sessionId,
+                turnId,
+                sandboxId,
+                path,
+            });
         },
-        [server, sandboxId],
+        [server, sessionId, sandboxId],
     );
 
     const draftExtras = useMemo(() => {