From Local Experiment to Shared Product Surface

TrueForge’s runtime can be reached through a browser, an SDK, or a custom application, and it can run as a personal single process or as a shared service. This chapter compares those choices by the responsibility they move to the client and the deployment operator. The useful result is not a feature inventory: it is a way to decide whether a workload needs live events or polling, a bundled UI or custom composition, local SQLite or hosted Postgres and Redis, and no-login convenience or an explicit identity boundary.

One runtime, different client contracts

The HTTP API and TypeScript SDK expose the execution model described earlier as a stream-first contract. An application creates or selects a session, starts a turn, and receives events until turn.done. Model text arrives as a base message followed by deltas. Tool calls, tool responses, subagent threads, sandbox creation, and required actions are also events. A client that wants a live chat experience consumes those events as they arrive; a client that wants a background job can start a non-streaming turn and poll its stored state.

The choice between streaming and polling follows the user’s relationship to the work. Streaming is appropriate when a person should see progress, when a UI must display tool activity, or when the application needs to show an approval or question as soon as it appears. Polling is sufficient when an application submits a task to run in the background and only needs the final terminal state. Neither mode changes the agent’s execution semantics. Both depend on the same session and turn identifiers, and both must distinguish a completed answer from a turn that is done but waiting on a required action.

Resilience adds a third pattern: resubscription or replay. If a live connection drops while a turn is running, the client can inspect the turn and subscribe again after the last received sequence number. If the turn has finished, it can read the stored events, where streamed model deltas are already merged. This is valuable for a browser that may be refreshed or a worker that may restart, but it does not make an external write exactly once. The application should use the event log to recover its view, not rerun a tool simply because the last display update was lost.

That division of responsibility is visible in the SDK’s handling of threads and messages. A client may index events by ID so model deltas merge into the correct base message, and by thread ID so root activity remains separate from subagent activity. The sequence number is a delivery cursor. A message ID is a content association. A thread ID is an execution-context association. Keeping those identities separate is part of implementing the contract correctly; treating them as interchangeable creates subtle bugs in live interfaces.

The UI SDK builds on the same boundary but adds a composable presentation layer. A host can use TrueForgeUI with a built-in TrueForge configuration, connect it to a TrueFoundry-backed server, or pass a custom AgentUIServer. The server contract has two required concerns: chat/session operations, including turn streaming and optional resubscription, and agent-builder operations, such as listing models, skills, connectors, and saved agents. A catalog is optional and powers Settings; additional ports can expose sessions, metrics, schedules, or permissions.

The distinction between containers and atoms keeps the UI extensible without moving runtime state into every component. Containers are connected to the chat runtime and know how to read messages, stream responses, and switch sessions. Atoms are presentational components that receive their data as props. Slot overrides can replace a message bubble, composer piece, tool card, or welcome screen without requiring a fork of the whole interface. A custom layout can arrange the exported containers while preserving the server and shell providers underneath.

That composability is useful when the product needs a different relationship to the agent. SingleAgent can pin a user to one named assistant. AgentLibrary can let users choose from a registry without authoring new agents.