Upgrade: createHelixChatTransport removed; agent-server's chat routes take a stock client (CP-07)
@helix-agents/ai-sdk no longer ships createHelixChatTransport, the browser client for agent-server's native /start, /resume, /sse, /status and /submit-tool-result routes. An app hosted with @helix-agents/agent-server serves its chat from the server's chat routes instead, with ai's own DefaultChatTransport (or useHelixChat over it), as every other host does. Client and server deploy together.
What changed
@helix-agents/ai-sdk (major)
Removed:
createHelixChatTransport,HelixChatTransport,HelixChatTransportOptions;extractToolOutputs(its only user was the transport);HelixPayloadTooLargeError(only the transport threw it).
The transport re-sent the previous user message after a client-tool answer or an approval, sent no approvals, sent no stream cursor, and dropped file parts (CP-07). The chat routes do none of that.
@helix-agents/agent-server (minor)
POST /chattakesai's own request body: the session is itsid, or a HelixsessionId. A HelixsessionIdwins overai's chatid: the documentedprepareHelixChatRequest({ body: { sessionId } })shape sends both. The session is resolved before theauthenticatehook, which sees it asbody.sessionId.- Both chat routes (
POST /chat,GET /chat/{id}/stream) pass the route's request to the chat handler as a webRequest(ChatStreamHandlerparams gainrequest?: Request). With the documented wiring,handleChatStreamgets the client's resume headers (a reconnect resumes from its cursor) and its disconnect. AgentHttpRequestgains an optionalsignal(the client's disconnect).createExpressAdaptersets it from the response'sclose; a custom adapter passes its host request's signal (a webRequest'ssignal).
Migrate
Server: wire the chat routes to handleChatStream.
import type { UIMessage } from 'ai';
import { handleChatStream } from '@helix-agents/ai-sdk';
const server = new AgentServer({
agents: { 'my-agent': myAgent },
stateStore,
streamManager,
executor,
authenticate,
chatHandler: (params) =>
handleChatStream(
{ executor, stateStore, streamManager, agent: myAgent },
{ ...params, messages: params.messages as UIMessage[] }
),
});A custom HTTP adapter (for example a Next.js route over createHttpAdapter) passes signal: req.signal on the AgentHttpRequest.
Client: before, then after.
// Before
const transport = createHelixChatTransport({
endpoint: '/api/agent',
sessionId,
agentType: 'my-agent',
});
const chat = useHelixChat({ transport, toolHandlers });
// After: the chat id is the session id; the route's `chatHandler` names the agent.
const transport = new DefaultChatTransport({ api: '/api/agent/chat' });
const chat = useHelixChat({ id: sessionId, transport, toolHandlers });Client tools with a plain useChat: auto-send with createHelixSendAutomaticallyWhen() (from @helix-agents/ai-sdk), or with ai's own predicates (lastAssistantMessageIsCompleteWithToolCalls for client-tool answers, OR-ed with lastAssistantMessageIsCompleteWithApprovalResponses when the agent has approval-gated tools; CP-340: the stock tool-calls predicate sends an answer once). Or use useHelixChat.
transport.submitToolResult(...) (submitting an answer while a stream is open) has two replacements:
- answer through the chat:
addToolOutput(oraddToolApprovalResponse), which goes back in the nextPOST /chat; - or
POST <mount>/chat/{sessionId}/submit-tool-resultwith the submit body ({ kind: 'client-tool-result', sessionId, toolCallId, result | error }), the same validation and answers as/submit-tool-result.
HelixPayloadTooLargeError: read the typed 413 body instead: parseHelixChatError(chat.error) gives code: 'validation_payload_too_large' with cause, limitBytes and sizeBytes (or state_size_exceeded for the store's limit), and a direct submit's 413 carries the same JSON body.
Request keys stay as they were: useHelixChat keys every send, and agent-server reads X-Helix-Request-Key on /chat.
Unchanged
agent-server's native routes (/start, /resume, /sse, /status, /submit-tool-result) and the remote-agent transports (HttpRemoteAgentTransport) are unchanged.