Cell - Ta Protocol

Protocol between ta serve and clients: types and constants only, with no pi or Node.js modules loaded, so it works in browsers.

• Transport: one WebSocket (TA_WEBSOCKET_PATH) with JSON-RPC 2.0 messages. Method names are <service>/<method>, and the server pushes TaClient/onEvents etc. HTTP-based calls are not offered; only workspace file bytes travel HTTP (TA_FILES_PATH, for images and iframes in pages to load via relative URLs).
• Services: TaServer (sessions—pi's RPC commands), TaWorkspaceServer (files and commands in directories), TaTerminalServer (terminals), TaSettingsServer (pi's settings.json), TaPackageServer (packages, web extensions, and package data), TaAuthServer (login to model services, same as pi's /login and /logout), TaRelayServer (paired devices via Relay, same as ta pair), TaRemoteServer (hosts for ssh:// directories, ssh prompts, port forwarding). Capabilities outside sessions split into separate services by responsibility, not added to TaServer.
• TaServer methods: besides openSession, closeSession, listSessions, attach, detach, respondUi, and respondClientTool, the rest are pi RPC mode commands with the same name (snake_case → camelCase, see PiCommandMethod). The first parameter is sessionId, and return values match pi's; when pi adds an RPC command and TaServer lacks the method, this package's tests won't compile. setWorkingDirectory sets ta serve's working directory (TaServerInfo.cwd, used when clients don't specify one, persists across restarts). Session operations not in pi RPC: forkToFile (saves the forked session to a file, current session untouched, then open with openSession), navigateTree (same as pi's /tree, returns editorText), fork has an optional position (at keeps the selected item, like pi's /clone but optional for any item).
• Events: TaEventEnvelope { sessionId, seq, event }, where event is a pi JSON/RPC mode event or extension_ui_request. Ta adds only ui_request_resolved, extension_error, session_replaced, session_closed, and client_tool_request (reserved).
• prompt / steer / followUp: carry client-generated clientMessageId. Retrying with the same ID returns duplicate and doesn't re-execute. Receipt only means accepted; the round end is marked by the agent_settled event.
• Locations (cwd): a path is either local or on another machine in the form ssh://<host>/<absolute-path> (TaLocation parses, handles parent/child, and names).
• Errors: the JSON-RPC error code is TA_RPC_ERROR_CODE. The data field includes a stable code (TaErrorCode, e.g., CELL_TA_SESSION_LOCKED) and a one-line handling hint. When no model is available or the model service isn't signed in, the code is CELL_TA_NOT_SIGNED_IN; clients open the login page accordingly. CELL_TA_CONNECTION_LOST is client-generated: the call didn't reach ta serve, or the connection dropped before the result arrived.