Skip to content

The open-source agent harness - the runtime layer that turns an LLM into a working agent.

updated ui docs for getCapabilities (#110)

sajal-truefoundry7b76c7b0f147
diff --git a/docs/ui-sdk/concepts/server-contract.mdx b/docs/ui-sdk/concepts/server-contract.mdx
index 60878838b..c35409b3d 100644
--- a/docs/ui-sdk/concepts/server-contract.mdx
+++ b/docs/ui-sdk/concepts/server-contract.mdx
@@ -223,6 +223,7 @@ Powers the agent library and the draft composer.
```ts
interface AgentBuilderServer {
+ getCapabilities(): Promise<AgentBuilderCapabilitiesResponse>;
getModels(): Promise<ModelSelection[]>;
getSkills(): Promise<AgentSkill[]>;
getMcp(): Promise<ConnectorState[]>;
@@ -232,20 +233,54 @@ interface AgentBuilderServer {
}
```
-These return picker rows — the minimum each selector renders:
+`deleteAgent` is the only optional method here — the rest must be implemented.
+
+### Capabilities
+
+`getCapabilities` tells the UI which optional features your backend supports, so it can hide
+what you do not offer rather than surfacing controls that fail.
+
+```ts
+interface AgentBuilderCapabilitiesResponse {
+ data: {
+ sandbox: { enabled: boolean };
+ skill: { enabled: boolean; reason?: string };
+ settings?: { enabled: boolean };
+ };
+}
+```
+
+It is fetched once when the server resolves. `skill.reason` is shown to the user when skills are
+disabled, so use it to explain why — for example that no skill registry is configured. Setting
+`settings.enabled` to `false` hides the settings control even when a `catalog` is attached;
+omitting `settings` leaves it visible.
+
+```ts
+async getCapabilities() {
+ return { data: { sandbox: { enabled: false }, skill: { enabled: true } } };
+}
+```
+
+Read the resolved value anywhere in your own components with
+[`useServerCapabilities()`](/ui-sdk/reference/hooks).
+
+### Picker rows
+
+The remaining methods return the minimum each selector renders:
| Type | Required | Optional |
| --- | --- | --- |
| `ModelSelection` | `name`, `provider` | `reasoningEfforts?: string[]` |
| `AgentSkill` | `id`, `name` | `description` |
| `ConnectorState` | `id`, `name` | `description`, `requiresAuth`, `authenticated` |
-| `AgentLibraryEntry` | `name` | `agentId`, `agentSpec` |
+| `AgentLibraryEntry` | `name`, `agentId` | `agentSpec` |
<Note>
Return a non-empty `reasoningEfforts` on a `ModelSelection` and the UI shows a
- reasoning-effort picker beside the model selector. On `AgentLibraryEntry`, supply `agentSpec`
- to enable Edit — omit it for try-only agents — and `agentId` when the stable id differs from
- the display `name`, which otherwise serves as the id.
+ reasoning-effort picker beside the model selector. On `AgentLibraryEntry`, `agentId` is the
+ stable identifier used for selection, history filtering, and session binding — it is required
+ even when it matches the display `name`. Supply `agentSpec` to enable Edit; omit it for
+ try-only agents.
</Note>
`SearchAgentsParams` is `{ query?, limit?, offset? }` — offset paging, since it backs a search
diff --git a/docs/ui-sdk/get-started/quickstart.mdx b/docs/ui-sdk/get-started/quickstart.mdx
index 20f7cd785..8153d4ddf 100644
--- a/docs/ui-sdk/get-started/quickstart.mdx
+++ b/docs/ui-sdk/get-started/quickstart.mdx
@@ -91,6 +91,9 @@ const chatServer = createTrueFoundryChatServer({
const server = createTrueFoundryServer({
chatServer,
+ getCapabilities: async () => ({
+ data: { sandbox: { enabled: false }, skill: { enabled: false } },
+ }),
getModels: async () => [],
getSkills: async () => [],
getMcp: async () => [],
@@ -107,10 +110,11 @@ export default function App() {
}
```
-Two notes on this path. Empty `getModels` means the composer has no models to offer, so supply
-real ones before enabling composer mode — see [Agent modes](/ui-sdk/concepts/agent-modes). And
+Three notes on this path. Empty `getModels` means the composer has no models to offer, so
+supply real ones before enabling composer mode — see [Agent modes](/ui-sdk/concepts/agent-modes).
`createTrueFoundryServer` attaches no `catalog`, so the settings panel stays hidden until you
-pass one.
+pass one. And `getCapabilities` is required: it declares which optional features your backend
+supports, so the UI hides sandbox and skill affordances rather than offering ones that fail.
To skip `createTrueFoundryServer` entirely and implement the interface from scratch — against
any backend, not just TrueFoundry — see
diff --git a/docs/ui-sdk/guides/custom-server.mdx b/docs/ui-sdk/guides/custom-server.mdx
index 15e2d7433..66a0a04ab 100644
--- a/docs/ui-sdk/guides/custom-server.mdx
+++ b/docs/ui-sdk/guides/custom-server.mdx
@@ -73,6 +73,9 @@ export const server: AgentUIServer = {
},
// builder
+ async getCapabilities() {
+ return { data: { sandbox: { enabled: false }, skill: { enabled: false } } };
+ },
async getModels() {
return [{ name: "my-model", provider: "my-provider" }];
},
@@ -83,7 +86,7 @@ export const server: AgentUIServer = {
return [];
},
async searchAgents() {
- return [{ name: "support-agent" }];
+ return [{ agentId: "support-agent", name: "Support agent" }];
},
async saveAgent() {
return {};
@@ -91,6 +94,10 @@ export const server: AgentUIServer = {
};
```
+Declaring `sandbox` and `skill` as disabled is the honest starting point — the UI then hides
+those affordances instead of offering controls your backend cannot serve. Flip them on as you
+implement each.
+
```tsx title="App.tsx"
<TrueforgeUI server={server} layout="sidebar" agentConfig={{ mode: "AgentLibrary" }} />
```
diff --git a/docs/ui-sdk/guides/slot-overrides.mdx b/docs/ui-sdk/guides/slot-overrides.mdx
index 173d25879..bc15fc320 100644
--- a/docs/ui-sdk/guides/slot-overrides.mdx
+++ b/docs/ui-sdk/guides/slot-overrides.mdx
@@ -66,8 +66,13 @@ honor the props you receive — several are rendered nodes (`actionBar`, `error`
</Accordion>
<Accordion title="Agent library and shell">
`AgentsLibrary`, `AgentsLibraryButton`, `SaveAgentButton`, `SelectAgentEmptyState`,
- `ClearChatButton`, `Toast`, `ToastStack`, `Accordion`, `AccordionSummary`,
- `AccordionDetails`.
+ `ClearChatButton`, `ShellActionsActionSlot`, `Toast`, `ToastStack`, `Accordion`,
+ `AccordionSummary`, `AccordionDetails`.
+
+ `ShellActionsActionSlot` exists purely to be overridden — it renders nothing by default and
+ is the supported place to add your own chrome, such as a logout control, beside the theme
+ and settings buttons. Layouts keep it mounted while Settings is open, so state in your
+ component survives.
</Accordion>
</AccordionGroup>
diff --git a/docs/ui-sdk/reference/atoms.mdx b/docs/ui-sdk/reference/atoms.mdx
index 923404f4d..b3ebc1f14 100644
--- a/docs/ui-sdk/reference/atoms.mdx
+++ b/docs/ui-sdk/reference/atoms.mdx
@@ -103,6 +103,10 @@ Also `ToolCallContentBlock`, `ToolApprovalBar`, `ToolGroupCard`, `SubAgentCard`,
All of these except `DraftCatalogProvider` and `useDraftCatalog` are also overridable slots, so
you can either render them yourself or replace them globally through `overrides`.
+`ShellActionsActionSlot` belongs to the same shell chrome. It renders nothing by default and
+exists to be overridden — the supported way to add host controls such as logout beside the
+theme and settings buttons.
+
## Primitives
`BottomSheet`, `CenteredModal`, `Avatar` / `AvatarImage` / `AvatarFallback`, `Icon`, `Toast`,
diff --git a/docs/ui-sdk/reference/hooks.mdx b/docs/ui-sdk/reference/hooks.mdx
index 748bb25a2..774aba9e1 100644
--- a/docs/ui-sdk/reference/hooks.mdx
+++ b/docs/ui-sdk/reference/hooks.mdx
@@ -12,6 +12,20 @@ description: "Composer state, MCP auth, runtime hooks, and re-exports."
`threadHasPendingMcpAuth(state)` is the standalone predicate behind the `"mcp"` case.
+## Server capabilities
+
+```ts
+import { useServerCapabilities } from "@truefoundry/trueforge-ui";
+
+const capabilities = useServerCapabilities();
+// { sandbox: { enabled }, skill: { enabled, reason? }, settings?: { enabled } } | null
+```
+
+Returns the resolved value from your server's `getCapabilities()`, or `null` while it is still
+loading or if the call failed. Use it to gate your own chrome the same way the SDK gates its
+sandbox, skill, and settings affordances. See
+[Server contract](/ui-sdk/concepts/server-contract#capabilities).
+
## MCP auth
```ts
diff --git a/docs/ui-sdk/reference/server.mdx b/docs/ui-sdk/reference/server.mdx
index 82a3bb68b..9abfde574 100644
--- a/docs/ui-sdk/reference/server.mdx
+++ b/docs/ui-sdk/reference/server.mdx
@@ -9,9 +9,10 @@ description: "Server factory, context hooks, shell mode, and contract types."
createTrueFoundryServer(options: CreateTrueFoundryServerOptions): TrueFoundryServer;
```
-Options: `{ chatServer, getModels, getSkills, getMcp, searchAgents, saveAgent, deleteAgent?, catalog? }`.
+Options: `{ chatServer, getCapabilities, getModels, getSkills, getMcp, searchAgents, saveAgent, deleteAgent?, catalog? }`.
Combines a chat server with your agent-management callbacks into a complete `AgentUIServer`.
-If you omit `deleteAgent`, calling it throws — supply one to support agent deletion.
+`deleteAgent` and `catalog` are the only optional entries; if you omit `deleteAgent`, calling it
+throws.
## Context
@@ -20,6 +21,7 @@ If you omit `deleteAgent`, calling it throws — supply one to support agent del
| `ServerProvider` | Supplies the resolved server. |
| `useServer()` | The server; throws outside a provider. |
| `useOptionalServer()` | The server, or `null` outside a provider. |
+| `useServerCapabilities()` | Resolved `getCapabilities()` data, or `null` while loading or on failure. |
| `useCatalogServer()` | `server.catalog`; **throws** when absent. |
| `useOptionalCatalogServer()` | `server.catalog`, or `null` when there is none. |
@@ -45,8 +47,9 @@ to reference:
<AccordionGroup>
<Accordion title="Server interfaces">
- `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer`, `CatalogServer`,
- `TrueforgeServerConfig`, `CreateTrueFoundryServerOptions`, `TrueFoundryServer`.
+ `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer`,
+ `AgentBuilderCapabilitiesResponse`, `CatalogServer`, `TrueforgeServerConfig`,
+ `CreateTrueFoundryServerOptions`, `TrueFoundryServer`.
</Accordion>
<Accordion title="Sessions and turns">
`Session`, `CreateSessionRequest`, `UpdateSessionRequest`, `Turn`, `TurnState`,
diff --git a/docs/ui-sdk/reference/trueforge-ui.mdx b/docs/ui-sdk/reference/trueforge-ui.mdx
index e9752e7e6..d03b03a6c 100644
--- a/docs/ui-sdk/reference/trueforge-ui.mdx
+++ b/docs/ui-sdk/reference/trueforge-ui.mdx
@@ -153,7 +153,7 @@ import { TrueforgeUI } from "@truefoundry/trueforge-ui";
<ParamField path="overrides" type="SlotOverrides">
Replace any built-in component. `Partial<AtomSlots>`, derived from the SDK's default slot
- table — so editor autocomplete lists exactly the 59 overridable names. See
+ table — so editor autocomplete lists the overridable names. See
[Slot overrides](/ui-sdk/guides/slot-overrides).
</ParamField>