Host integration

Connect public SDK capabilities while keeping resources and business policy with the host

The backend owns City, Agent, Workspace, storage, authentication, and Session execution. A browser uses @downcity/city/browser to obtain a remote Session. connect_chat_session(session) adapts that actor to a ChatPanel runtime and owns only its UI subscription.

See Agent chat for the full-stack example and lifecycle code.

Resource ownership

ResourceOwnerCleanup
City, Agent, Workspace, storageBackendcity.close()
RemoteAgent and its transportBrowser hostawait client.close()
Chat subscriptionUI connectionconnection.close()
Canonical messages and retry eligibilitySessionSession lifecycle
Draft storage and submission policyApplicationApplication lifecycle
Cursor, candidate menus, pending editor operationsChatInputComponent teardown

Authenticate Agent and Session access in the backend. Do not give the browser a model key or trust a Session ID as authorization. The local template has one user and one server-selected Session; multi-user ownership is application policy.

Message customizations

Use AgentChatMessage and UserMessage for standalone chat surfaces, and AgentWorkMessage for full-width work documents without an identity row. Use MarkdownViewProvider for resource resolution and link handling. Use AgentMessageContent to keep canonical block ordering, streaming Markdown, error display, and retry feedback while injecting Power, activity details, or file previews through render_block. Use UserMessageContent with file and reference renderers for host navigation.

ChatPanel also accepts controlled messages, status, on_submit, on_stop, on_respond_interaction, and render_interaction when the application already owns its state container. The default forms handle approval and public questions. Private questions use the Agent private submission API through a custom Interaction renderer.

Input customizations

ChatInput receives a structured document and explicit input owner (editor_key). The editor owns transient interaction state; the host owns drafts and business submission. host supplies translations, avatars, attachment/reference previews, and subscriptions for external insertion or draft handoff. Every registration callback returns a cleanup function.

attachments.list_files() and attachments.read_file() resolve workspace candidates. Resource authorization stays with the backend. Use project_chat_composer from @downcity/ui/composer to serialize the document without importing React rendering code into the server.