> ## Documentation Index
> Fetch the complete documentation index at: https://trueforge.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Server

> Server factory, context hooks, shell mode, and contract types.

## Factory

```ts theme={null}
createTrueForgeServer(options: CreateTrueForgeServerOptions): TrueForgeServer;
```

Options: `{ chatServer, getCapabilities, getModels, getSkills, getMcp, searchAgents, saveAgent, deleteAgent?, catalog? }`.
Combines a chat server with your agent-management callbacks into a complete `AgentUIServer`.
`deleteAgent` and `catalog` are the only optional entries; if you omit `deleteAgent`, calling it
throws.

## Context

| Export | Behavior |
| - | - |
| `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. |

## Shell mode

| Export | Behavior |
| - | - |
| `ShellModeProvider` | Derives shell capabilities from `agentConfig`. |
| `useShellMode()` | Throws outside a provider. |
| `useOptionalShellMode()` | Returns `null` outside a provider. |
| `DEFAULT_AGENT_CONFIG` | `{ mode: "AgentLibraryWithComposer" }`. |

`useShellMode()` reports which surfaces the current `agentConfig` permits —
`isLibraryEnabled`, `isComposerEnabled`, `isNewChatEnabled` — and returns the actions
`selectAgent`, `openDraft`, and `clearChat`, plus `settingsOpen` / `setSettingsOpen`. Use it in
a custom layout to render only the controls that apply. See
[Agent modes](/ui-sdk/concepts/agent-modes).

## Contract types

The full server contract is re-exported from the package root. The types you are most likely
to reference:

<AccordionGroup>
  <Accordion title="Server interfaces">
    `AgentUIServer`, `AgentChatServer`, `AgentBuilderServer`,
    `AgentBuilderCapabilitiesResponse`, `CatalogServer`, `TrueForgeServerConfig`,
    `CreateTrueForgeServerOptions`, `TrueForgeServer`.
  </Accordion>

  <Accordion title="Sessions and turns">
    `Session`, `CreateSessionRequest`, `UpdateSessionRequest`, `Turn`, `TurnState`,
    `PreviousTurnIdInput`.
  </Accordion>

  <Accordion title="Turn input">
    `TurnInputItem`, `UserMessage`, `UserMessageContent`, `UserToolApprovalEvent`,
    `UserToolResponseEvent`, `ApprovalDecision`.
  </Accordion>

  <Accordion title="Events and streaming">
    `TurnStreamData`, `TurnStreamingEvent`, `SessionEventItem`. The concrete event shapes are in
    [Streaming events](/ui-sdk/reference/events).
  </Accordion>

  <Accordion title="Agents and models">
    `AgentSpec`, `AgentConfig`, `ShellMode`, `Model`, `ModelParams`, `SkillMount`,
    `McpServerMount`, `SaveAgentRequest`.
  </Accordion>

  <Accordion title="Picker rows">
    `ModelSelection`, `AgentSkill`, `ConnectorState`, `AgentLibraryEntry`,
    `SearchAgentsParams`.
  </Accordion>

  <Accordion title="Pagination">
    `PageResult`, `PageParams`, `TokenPagination`, `ListSessionsParams`, `ListSessionsOrder`,
    `ListSessionsResponse`, `ListTurnsResponse`, `ListSessionEventsResponse`.
  </Accordion>

  <Accordion title="Catalog">
    `ModelCatalogServer`, `ConnectorCatalogServer`, `SkillCatalogServer`,
    `SandboxCatalogServer`, plus the `ModelProvider*`, `Connector*`, `Skill*`, and `Sandbox*`
    families. See [Settings catalog](/ui-sdk/reference/catalog).
  </Accordion>
</AccordionGroup>

Full method signatures are on [Server contract](/ui-sdk/setup-custom-servers/server-contract); a worked
implementation is on [Bring your own server](/ui-sdk/setup-custom-servers/custom-server).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.