@truefoundry/assistant-ui-runtime 0.1.16 → 0.1.18

package/src/server/types.ts

@@ -10,7 +10,7 @@ import type {
   ActionRequiredEvent,
   SessionEventItem,
   TurnEvent,
-  TurnStreamData
+  TurnStreamData,
 } from "./events.js";
 
 // ---------------------------------------------------------------------------
@@ -74,19 +74,19 @@ export type SearchAgentSelectorParams = {
 // ---------------------------------------------------------------------------
 
 /**
-* Mounts written to AgentSpec.skills[] / AgentSpec.mcpServers[].
-*
-* These are opaque to the runtime — it stores and forwards them but never reads
-* a field, and the backend owns the shape (the gateway identifies a skill by
-* `fqn`, with no `id` or `name` anywhere). So the base constrains only that a
-* mount is an object; hosts intersect their concrete mount type over it, as
-* `TfySkillMount` / `TfyMcpServerMount` do in the gateway adapter.
-*
-* Naming a field here would not just be unread, it would be wrong: a base with
-* required fields rejects the backend's own payloads, and one with only optional
-* fields is a weak type, which TypeScript rejects for a source that shares no
-* property with it — the gateway's registry skill shares none.
-*/
+ * Mounts written to AgentSpec.skills[] / AgentSpec.mcpServers[].
+ *
+ * These are opaque to the runtime — it stores and forwards them but never reads
+ * a field, and the backend owns the shape (the gateway identifies a skill by
+ * `fqn`, with no `id` or `name` anywhere). So the base constrains only that a
+ * mount is an object; hosts intersect their concrete mount type over it, as
+ * `TfySkillMount` / `TfyMcpServerMount` do in the gateway adapter.
+ *
+ * Naming a field here would not just be unread, it would be wrong: a base with
+ * required fields rejects the backend's own payloads, and one with only optional
+ * fields is a weak type, which TypeScript rejects for a source that shares no
+ * property with it — the gateway's registry skill shares none.
+ */
 export type SkillMount = object;
 
 export type McpServerMount = object;
@@ -116,10 +116,10 @@ export interface AgentRuntimeConfig {
 }
 
 /**
-* SDK-owned agent definition — fields the FE reads/writes.
-* Host widens `model` / `skills` / `mcpServers` / `config` via type params,
-* and adds extra fields via `TSpec extends AgentSpec<...>`.
-*/
+ * SDK-owned agent definition — fields the FE reads/writes.
+ * Host widens `model` / `skills` / `mcpServers` / `config` via type params,
+ * and adds extra fields via `TSpec extends AgentSpec<...>`.
+ */
 export interface AgentSpec<
   TModel extends Model = Model,
   TSkill extends SkillMount = SkillMount,
@@ -193,7 +193,10 @@ export type PreviousTurnIdInput = "auto" | "none" | string;
 
 export type UserMessageContent =
   | string
-  | Array<{ type: "text"; text: string } | { type: "file"; name: string; data: string }>;
+  | Array<
+      | { type: "text"; text: string }
+      | { type: "file"; name: string; data: string }
+    >;
 
 export interface UserMessage {
   type: "user.message";
@@ -265,11 +268,11 @@ export interface Turn {
 // ---------------------------------------------------------------------------
 
 /**
-* 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).
-*/
+ * Chat / session port — the runtime calls these.
+ *
+ * All session ops are flat (sessionId param). No gateway client dependency.
+ * `createTrueFoundryServer` is one possible implementation (TFY adapter).
+ */
 export interface AgentChatServer<
   TSpec extends AgentSpec = AgentSpec,
   TSession extends Session<TSpec> = Session<TSpec>,
@@ -284,44 +287,44 @@ export interface AgentChatServer<
   updateSession(req: TUpdate): Promise<TSession>;
 
   createTurn(req: {
-      sessionId: string;
-      input?: TurnInputItem[];
-      previousTurnId?: PreviousTurnIdInput;
-      abortSignal?: AbortSignal;
-      headers?: Record<string, string>;
+    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;
+    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;
+    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;
+    sessionId: string;
+    turnId: string;
+    limit?: number;
+    pageToken?: string;
+    order?: ListSessionsOrder;
   }): Promise<ListResult<TurnEvent>>;
 
   subscribeToTurn?(req: {
-      sessionId: string;
-      turnId: string;
-      afterSequenceNumber?: number;
-      abortSignal?: AbortSignal;
+    sessionId: string;
+    turnId: string;
+    afterSequenceNumber?: number;
+    abortSignal?: AbortSignal;
   }): AsyncIterable<TurnStreamData>;
 
   /**
@@ -330,10 +333,10 @@ export interface AgentChatServer<
    * directly use `sandboxId`.
    */
   downloadSandboxFile?(req: {
-      sessionId: string;
-      turnId: string;
-      sandboxId: string;
-      path: string;
+    sessionId: string;
+    turnId: string;
+    sandboxId: string;
+    path: string;
   }): Promise<Blob>;
 }
 
@@ -365,9 +368,9 @@ export interface AgentBuilderCapabilitiesResponse {
 }
 
 /**
-* Builder catalog + persist port — atoms call these.
-* Passed separately from the runtime's chat server.
-*/
+ * Builder catalog + persist port — atoms call these.
+ * Passed separately from the runtime's chat server.
+ */
 export interface AgentBuilderServer<
   TSpec extends AgentSpec = AgentSpec,
   TModel extends ModelSelectorEntry = ModelSelectorEntry,
@@ -375,7 +378,8 @@ export interface AgentBuilderServer<
   TMcp extends ConnectorSelectorEntry = ConnectorSelectorEntry,
   TAgent extends AgentSelectorEntry = AgentSelectorEntry,
   TSave = SaveAgentResult,
-  TCapabilities extends AgentBuilderCapabilitiesResponse = AgentBuilderCapabilitiesResponse,
+  TCapabilities extends AgentBuilderCapabilitiesResponse =
+    AgentBuilderCapabilitiesResponse,
 > {
   getCapabilities(): Promise<TCapabilities>;
   getModels(): Promise<TModel[]>;
@@ -391,28 +395,30 @@ export interface AgentBuilderServer<
 // ---------------------------------------------------------------------------
 
 /**
-* 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.
-*/
+ * 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.
-*/
+ * 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> {
+ * 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"`. */
@@ -422,9 +428,9 @@ export interface ModelProviderConfigBase<TModel extends ModelEntry = ModelEntry>
 }
 
 /**
-* Configured provider card (list/read). No raw `apiKey`.
-* Host extends for apiKeySet, timestamps, etc.
-*/
+ * 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;
@@ -435,11 +441,13 @@ export interface ModelProviderBase<TModel extends ModelEntry = ModelEntry> {
 }
 
 /**
-* 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> {
+ * 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[];
@@ -458,9 +466,12 @@ export type UpdateModelProviderRequest<TModel extends ModelEntry = ModelEntry> =
 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>,
+  TCatalogProvider extends ModelProviderCatalogEntry<TModel> =
+    ModelProviderCatalogEntry<TModel>,
+  TCreate extends CreateModelProviderRequest<TModel> =
+    CreateModelProviderRequest<TModel>,
+  TUpdate extends UpdateModelProviderRequest<TModel> =
+    UpdateModelProviderRequest<TModel>,
 > {
   getModelProviderCatalog(): Promise<TCatalogProvider[]>;
   listModelProviders(): Promise<TProvider[]>;
@@ -506,12 +517,13 @@ export type ConnectorAuthPublic =
   | ConnectorAuthPublicNone;
 
 /**
-* MCP / connector create-edit config. Host extends for extra fields, etc.
-*/
+ * MCP / connector create-edit config. Host extends for extra fields, etc.
+ */
 export interface ConnectorConfigBase<
   TAuth extends ConnectorAuth = ConnectorAuth,
 > {
   name: string;
+  description: string;
   url: string;
   auth: TAuth;
 }
@@ -547,12 +559,14 @@ export interface ConnectorCatalogEntry<
 }
 
 /** Create connector — no `id`; server assigns it. Host extends. */
-export type CreateConnectorRequest<TAuth extends ConnectorAuth = ConnectorAuth> =
-  ConnectorConfigBase<TAuth>;
+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 type UpdateConnectorRequest<
+  TAuth extends ConnectorAuth = ConnectorAuth,
+> = ConnectorConfigBase<TAuth> & { id: string };
 
 export interface AuthenticateConnectorRequest {
   id: string;
@@ -664,7 +678,6 @@ export interface SkillCatalogServer<
 
 /** Mutable sandbox provider settings shared by catalog rows, create, and update. */
 export interface SandboxConfig {
-  snapshotName: string;
   execTimeoutMs: number;
   autoStopIntervalInMinutes: number;
   autoArchiveIntervalInMinutes: number;
@@ -688,6 +701,18 @@ export interface SandboxBase extends SandboxConfig {
   isConnected: boolean;
 }
 
+export type SandboxSnapshotSyncStatus = {
+  status: "pending" | "ready" | "failed";
+  statusReason?: string | null;
+};
+
+export interface SandboxProviderListEntry<
+  TSandbox extends SandboxBase = SandboxBase,
+> {
+  data: TSandbox;
+  snapshotSyncStatus: SandboxSnapshotSyncStatus;
+}
+
 export interface CreateSandboxRequest extends SandboxConfig {
   /** `SandboxCatalogEntry.id` used to create this sandbox provider. */
   catalogId: string;
@@ -714,9 +739,11 @@ export interface SandboxCatalogServer<
   TCatalogEntry extends SandboxCatalogEntry = SandboxCatalogEntry,
   TCreate extends CreateSandboxRequest = CreateSandboxRequest,
   TUpdate extends UpdateSandboxRequest = UpdateSandboxRequest,
+  TListEntry extends SandboxProviderListEntry<TProvider> =
+    SandboxProviderListEntry<TProvider>,
 > {
   getSandboxProviderCatalog(): Promise<TCatalogEntry[]>;
-  listSandboxProviders(req?: { query?: string }): Promise<TProvider[]>;
+  listSandboxProviders(req?: { query?: string }): Promise<TListEntry[]>;
   createSandboxProvider(req: TCreate): Promise<TProvider>;
   updateSandboxProvider(req: TUpdate): Promise<TProvider>;
   deleteSandboxProvider?(req: { id: string }): Promise<void>;
@@ -730,10 +757,10 @@ export type AgentLibraryEntry = AgentSelectorEntry;
 export type SearchAgentsParams = SearchAgentSelectorParams;
 
 /**
-* 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.
-*/
+ * 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,

package/src/truefoundryExtras.test.ts

@@ -0,0 +1,161 @@
+import { describe, expect, it, vi } from "vitest";
+import type { AssistantClient } from "@assistant-ui/store";
+
+import {
+    getTrueFoundryExtras,
+    trueFoundryExtras,
+    tryGetTrueFoundryExtras,
+    type TrueFoundryRuntimeExtras,
+} from "./truefoundryExtras.js";
+
+function clientWithExtras(
+    extras: unknown,
+): AssistantClient {
+    return {
+        thread: () => ({
+            getState: () => ({ extras }),
+        }),
+    } as unknown as AssistantClient;
+}
+
+describe("tryGetTrueFoundryExtras", () => {
+    it("reads extras from the current client", () => {
+        const extras = trueFoundryExtras.provide({
+            pendingApprovals: [],
+            pendingToolResponses: [],
+            pendingMcpAuth: null,
+            resumeUnavailable: false,
+            sandboxId: undefined,
+            respondToToolApproval: vi.fn(),
+            respondToToolResponse: vi.fn(),
+            resumeMcpAuth: vi.fn(),
+            downloadSandboxFile: vi.fn(),
+            cancel: vi.fn(),
+            resetFromTurn: vi.fn(),
+            reload: vi.fn(),
+            hasOlderHistory: false,
+            isLoadingOlderHistory: false,
+            loadOlderHistory: vi.fn(),
+            draft: null,
+        } satisfies TrueFoundryRuntimeExtras);
+
+        expect(tryGetTrueFoundryExtras(clientWithExtras(extras))).toBe(extras);
+    });
+
+    it("walks nested readonly clients (Object.create parent) to find root extras", () => {
+        const respondToToolApproval = vi.fn();
+        const extras = trueFoundryExtras.provide({
+            pendingApprovals: [{ approvalId: "a1", threadId: "child-1", toolName: "bash", args: {}, argsText: "{}" }],
+            pendingToolResponses: [],
+            pendingMcpAuth: null,
+            resumeUnavailable: false,
+            sandboxId: undefined,
+            respondToToolApproval,
+            respondToToolResponse: vi.fn(),
+            resumeMcpAuth: vi.fn(),
+            downloadSandboxFile: vi.fn(),
+            cancel: vi.fn(),
+            resetFromTurn: vi.fn(),
+            reload: vi.fn(),
+            hasOlderHistory: false,
+            isLoadingOlderHistory: false,
+            loadOlderHistory: vi.fn(),
+            draft: null,
+        } satisfies TrueFoundryRuntimeExtras);
+
+        const root = clientWithExtras(extras);
+        // Mirrors ReadonlyThreadProvider: nested AUI is Object.create(parent) with
+        // thread overwritten to a readonly client that has no extras.
+        const nested = Object.assign(Object.create(root), {
+            thread: () => ({
+                getState: () => ({ extras: undefined }),
+            }),
+        }) as AssistantClient;
+
+        expect(tryGetTrueFoundryExtras(nested)).toBe(extras);
+        // Namespace .get must walk too (not only the named helper).
+        expect(trueFoundryExtras.get(nested)).toBe(extras);
+        getTrueFoundryExtras(nested).respondToToolApproval({
+            approvalId: "a1",
+            approved: true,
+        });
+        expect(respondToToolApproval).toHaveBeenCalledWith({
+            approvalId: "a1",
+            approved: true,
+        });
+    });
+
+    it("returns undefined when no ancestor has TrueFoundry extras", () => {
+        expect(tryGetTrueFoundryExtras(clientWithExtras(undefined))).toBeUndefined();
+    });
+
+    it("survives RootAssistantClient-style proxies that throw on missing accessors", () => {
+        const extras = trueFoundryExtras.provide({
+            pendingApprovals: [],
+            pendingToolResponses: [],
+            pendingMcpAuth: null,
+            resumeUnavailable: false,
+            sandboxId: undefined,
+            respondToToolApproval: vi.fn(),
+            respondToToolResponse: vi.fn(),
+            resumeMcpAuth: vi.fn(),
+            downloadSandboxFile: vi.fn(),
+            cancel: vi.fn(),
+            resetFromTurn: vi.fn(),
+            reload: vi.fn(),
+            hasOlderHistory: false,
+            isLoadingOlderHistory: false,
+            loadOlderHistory: vi.fn(),
+            draft: null,
+        } satisfies TrueFoundryRuntimeExtras);
+
+        // Mirrors @assistant-ui/store createRootAssistantClient: empty proxy that
+        // throws on any get (e.g. "subscribe" / "thread").
+        const rootProto = new Proxy(
+            {},
+            {
+                get(_, prop) {
+                    throw new Error(
+                        `The current scope does not have a "${String(prop)}" property.`,
+                    );
+                },
+            },
+        );
+        const root = Object.assign(Object.create(rootProto), {
+            subscribe: (cb: () => void) => {
+                cb();
+                return () => {};
+            },
+            thread: () => ({
+                getState: () => ({ extras }),
+            }),
+        }) as AssistantClient;
+
+        expect(tryGetTrueFoundryExtras(root)).toBe(extras);
+
+        // useTrueFoundryRuntimeExtras walks .subscribe up the same chain.
+        const nested = Object.assign(Object.create(root), {
+            thread: () => ({
+                getState: () => ({ extras: undefined }),
+            }),
+        }) as AssistantClient;
+        expect(tryGetTrueFoundryExtras(nested)).toBe(extras);
+        expect(() => {
+            let current: object | null = nested;
+            const seen = new Set<object>();
+            while (current != null && !seen.has(current)) {
+                seen.add(current);
+                try {
+                    const subscribe = (current as { subscribe?: (cb: () => void) => () => void })
+                        .subscribe;
+                    if (typeof subscribe === "function") {
+                        subscribe(() => {});
+                    }
+                } catch {
+                    break;
+                }
+                current = Object.getPrototypeOf(current);
+            }
+        }).not.toThrow();
+    });
+});

package/src/truefoundryExtras.ts

@@ -1,4 +1,9 @@
+"use client";
+
 import { createRuntimeExtras } from "@assistant-ui/core/internal";
+import type { AssistantClient } from "@assistant-ui/store";
+import { useAui } from "@assistant-ui/store";
+import { useCallback, useSyncExternalStore } from "react";
 import type { McpAuthRequiredEvent } from "./server/index.js";
 
 import type { AgentSpec } from "./server/types.js";
@@ -42,7 +47,7 @@ export type TrueFoundryRuntimeExtras = {
     draft: TrueFoundryDraftRuntimeExtras | null;
 };
 
-export const trueFoundryExtras = createRuntimeExtras<TrueFoundryRuntimeExtras>(
+const extrasBrand = createRuntimeExtras<TrueFoundryRuntimeExtras>(
     "useTrueFoundryAgentRuntime",
 );
 
@@ -62,3 +67,133 @@ export const EMPTY_DRAFT_EXTRAS: TrueFoundryDraftRuntimeExtras = {
         throw new Error("Draft agent extras are only available in draft mode.");
     },
 };
+
+type SubscribeFn = (onStoreChange: () => void) => () => void;
+
+/**
+ * Walk `Object.create(parent)` AUI clients. Stops before leaving the chain.
+ * Callers must try/catch RootAssistantClient proxy gets (it throws on any
+ * missing accessor such as `subscribe` / `thread`).
+ */
+function walkAssistantClientAncestors(
+    client: AssistantClient,
+    visit: (current: object) => "continue" | "stop",
+): void {
+    let current: object | null = client;
+    const seen = new Set<object>();
+    while (current != null && !seen.has(current)) {
+        seen.add(current);
+        if (visit(current) === "stop") return;
+        const parent = Object.getPrototypeOf(current);
+        if (parent == null || parent === Object.prototype) {
+            return;
+        }
+        current = parent;
+    }
+}
+
+/**
+ * `PartPrimitive.Messages` wraps sub-agent threads in `ReadonlyThreadProvider`,
+ * which shadows `thread` (and therefore `thread.extras`) with a readonly client
+ * that has no TrueFoundry extras. Nested AUI clients are `Object.create(parent)`,
+ * so walk the prototype chain to reach the root runtime extras.
+ */
+export function tryGetTrueFoundryExtras(
+    client: AssistantClient,
+): TrueFoundryRuntimeExtras | undefined {
+    let found: TrueFoundryRuntimeExtras | undefined;
+    walkAssistantClientAncestors(client, (current) => {
+        try {
+            const thread = (current as AssistantClient).thread;
+            if (typeof thread === "function") {
+                const extras = extrasBrand.tryGet(thread().getState().extras);
+                if (extras != null) {
+                    found = extras;
+                    return "stop";
+                }
+            }
+        } catch {
+            // Nested/readonly clients may lack thread; RootAssistantClient proxy
+            // throws on missing scope accessors ("thread" / "subscribe").
+        }
+        return "continue";
+    });
+    return found;
+}
+
+export function getTrueFoundryExtras(client: AssistantClient): TrueFoundryRuntimeExtras {
+    const extras = tryGetTrueFoundryExtras(client);
+    if (extras == null) {
+        throw new Error(
+            "The current thread is not backed by the useTrueFoundryAgentRuntime runtime.",
+        );
+    }
+    return extras;
+}
+
+function subscribeClientChain(client: AssistantClient): SubscribeFn {
+    return (onStoreChange) => {
+        const unsubs: Array<() => void> = [];
+        walkAssistantClientAncestors(client, (current) => {
+            try {
+                const subscribe = (current as { subscribe?: SubscribeFn }).subscribe;
+                if (typeof subscribe === "function") {
+                    unsubs.push(subscribe(onStoreChange));
+                }
+                return "continue";
+            } catch {
+                // RootAssistantClient proxy — no further usable ancestors.
+                return "stop";
+            }
+        });
+        return () => {
+            for (const unsub of unsubs) {
+                unsub();
+            }
+        };
+    };
+}
+
+/**
+ * Resolves TrueFoundry extras from the nearest ancestor runtime, including
+ * inside nested readonly sub-agent renderers (`PartPrimitive.Messages`).
+ */
+export function useTrueFoundryRuntimeExtras(): TrueFoundryRuntimeExtras | undefined {
+    const aui = useAui();
+    const subscribe = useCallback(subscribeClientChain(aui), [aui]);
+    const getSnapshot = useCallback(() => tryGetTrueFoundryExtras(aui), [aui]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+}
+
+function useTrueFoundryExtrasApi(): TrueFoundryRuntimeExtras;
+function useTrueFoundryExtrasApi<S>(select: (extras: TrueFoundryRuntimeExtras) => S): S;
+function useTrueFoundryExtrasApi<S>(
+    select: (extras: TrueFoundryRuntimeExtras) => S,
+    fallback: S,
+): S;
+function useTrueFoundryExtrasApi<S>(
+    select?: (extras: TrueFoundryRuntimeExtras) => S,
+    fallback?: S,
+): TrueFoundryRuntimeExtras | S {
+    const extras = useTrueFoundryRuntimeExtras();
+    const hasFallback = arguments.length >= 2;
+    if (extras == null) {
+        if (hasFallback) return fallback as S;
+        throw new Error(
+            "The current thread is not backed by the useTrueFoundryAgentRuntime runtime.",
+        );
+    }
+    return select != null ? select(extras) : extras;
+}
+
+/**
+ * Brand + provide/tryGet from assistant-ui; get/use walk ancestor AUI clients so
+ * nested readonly sub-agent threads still resolve root TrueFoundry extras.
+ */
+export const trueFoundryExtras = {
+    provide: extrasBrand.provide,
+    is: extrasBrand.is,
+    tryGet: extrasBrand.tryGet,
+    get: getTrueFoundryExtras,
+    use: useTrueFoundryExtrasApi,
+};