\n * Provides strongly-typed access to all session-level API namespaces. The\n * {@code sessionId} is injected automatically into every call.\n *
\n * Example usage:\n *\n *
{@code\n * var agents = session.getRpc().agent.list().get();\n * }\n *\n * @return the session-scoped typed RPC client (never {@code null})\n * @throws IllegalStateException\n * if the session is not connected\n * @since 1.0.0\n */\n public SessionRpc getRpc() {\n if (rpc == null) {\n throw new IllegalStateException(\"Session is not connected — RPC client is unavailable\");\n }\n SessionRpc current = sessionRpc;\n if (current == null) {\n synchronized (this) {\n current = sessionRpc;\n if (current == null) {\n sessionRpc = current = new SessionRpc(rpc::invoke, sessionId);\n }\n }\n }\n return current;\n }\n\n /**\n * Sets a custom error handler for exceptions thrown by event handlers.\n * \n * When an event handler registered via {@link #on(Consumer)} or\n * {@link #on(Class, Consumer)} throws an exception during event dispatch, the","sourceCodeStart":387,"sourceCodeEnd":423,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/CopilotSession.java#L387-L423","documentation":"CopilotSession.getRpc() lazily publishes the SessionRpc handle from the rpc field; if rpc is still null the session has no live connection to the server and the method throws IllegalStateException instead of returning a unusable RPC client.","triggerScenarios":"Calling session.getRpc() (directly or via metadata/task/setModel/sendMcpAuthResponse/interest/updateSessionOptionsForMode) before the session's initialization handshake finished or after the underlying connection dropped and rpc was nulled.","commonSituations":"Touching getRpc() immediately after createSession returns on a pre-registered/resumed session; using a session after connection loss; calling session APIs from a thread that races session initialization.","solutions":["Await session readiness (e.g. a ready/initialized future) before calling getRpc()","Catch IllegalStateException and retry after the session reconnects","Check whether the session was terminated/reconnected; obtain a fresh CopilotSession if so","Serialize access so session setup completes before worker threads call RPC APIs"],"exampleFix":"// before\nsession.getRpc().invoke(\"task\", req);\n// after\nsession.whenReady().join(); // ensure handshake done\nsession.getRpc().invoke(\"task\", req);","handlingStrategy":"try-catch","validationCode":"if (!session.isConnected() /* or readiness future not done */) { awaitReadiness(session); }","typeGuard":null,"tryCatchPattern":"try {\n session.getRpc();\n} catch (IllegalStateException e) {\n if (e.getMessage().contains(\"not connected\")) {\n // wait for reconnect or recreate the session\n }\n}","preventionTips":["Await session initialization before worker threads use session APIs","Subscribe to lifecycle/disconnect events and stop issuing RPCs on disconnect","Recreate sessions after connection loss instead of reusing stale objects"],"tags":["session","rpc","not-connected"],"backgroundTag":"invalid-state-transition","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}