art_adk

Releases

1. ▸▾1.0.616 Oct 2026Deprecated

   New UploadOptions.allowedMimeTypes. UploadOptions.scopes and ConfigType.knowledgeBase are deprecated; scopes are ignored.

   Authentication

   • A complete client ID and secret pair now uses the client-credentials grant: the SDK authenticates again to renew the token and never uses refresh tokens. Without a client secret it exchanges accessToken and renews with the refresh token, as before.
   • Access tokens are renewed 30 seconds before they expire, and concurrent renewals share one request.
   • Server rejections throw AuthHttpError, an ARTError that carries the HTTP status. isTerminalAuthError is true for rejected credentials (401 or 403).
   • New authenticationFailed event (AuthenticationFailedDetail). When the credentials are rejected, or a forced renewal fails while reconnecting, the SDK stops reconnecting instead of retrying forever; update the credentials and call connect() again. The long-poll fallback also stops on rejected credentials.
   • Auth requests give up after AdkConfig.connectionTimeoutMs, and a response without an access token is an error.
   • When the access token changes, the connection's authorisation is renewed with the server before the next push or subscribe (IWebsocketHandler.ensureAuthorization).
   • Auth.getInstance(credentials:) updates the stored credentials, and starts with an empty token cache when the organisation, environment, project or client ID changes. A credentials provider that switches identity also drops the old tokens.
   • Adk.disconnect() removes the instance's own socket listeners; connect() adds them back.

   Storage

   • Files are now temporary media scoped to a conversation thread. UploadOptions.threadId and ListOptions.threadId are required, and getFile takes a threadId.
   • Agent, orchestrator and channel uploads are owned by the channel's server-side configuration (Subscription.configurationId, ChannelConfig.configurationID); thread uploads also set the thread.
   • New UploadOptions.allowedMimeTypes. UploadOptions.scopes and ConfigType.knowledgeBase are deprecated; scopes are ignored.
   • onProgress reports 0.0 when the upload starts and 1.0 when the server has stored the file.
   • UploadError.step is now validate, upload, list, get or delete.
   • file_meta entries are {id, name, content_type}; build one with MediaRef.fromFileRef(ref).toJson().
   • CallApiProps.payload accepts a FormDataPayload for multipart/form-data requests.

   Agents and orchestrators

   • Agent and orchestrator ids must be lowercase slugs, optionally pinned to a named build (my-agent@release2); anything else throws an ArgumentError. See validateExecutionReference.
   • AgentThread.dispose() ends the thread's active run and removes only its listeners; later calls on the thread throw a StateError.
   • RunDeps.executionOrigin and PushConfig.executionOrigin mark requests started from the playground (execution_origin). Replies keep the origin of the thread's latest run.
   • Subscription.listen, bind and attachThreadListener return a listener id, and remove accepts one.

   Connection failures

   • New ConnectionError, an ARTError with a readable message, a code and the HTTP status when there was one, and a new connectionFailed event. The connection fails when the credentials are missing or rejected, a token renewal fails, a billing or concurrency limit is reached, the connection is not ready in time, it cannot be restored after 5 reconnect attempts, or the app pauses or closes it. Automatic reconnection then stops, and waits, sends and subscribes throw the same error until connect() is called again.
   • New AdkConfig.connectionTimeoutMs (default 30 seconds) bounds connection readiness, auth requests and replies to control requests such as subscribes; it does not limit how long an execution runs. A control request without a reply now throws CONNECTION_TIMEOUT instead of resolving to null.
   • connect() completes once the connection is ready and throws the ConnectionError when the attempt fails, including for missing or rejected credentials (it used to complete normally). Concurrent calls share one attempt, and resume() now calls connect().
   • pause(), closeWebSocket() and disconnect() end the connection with CONNECTION_PAUSED or CONNECTION_CLOSED. close is no longer emitted for these, nor after a failed first authentication.
   • A connection failure ends active agent runs with an agent_error carrying its code, with details.source: connection and details.execution_status: unknown, since the client cannot tell whether the execution finished. The thread state becomes failed from the client ("Connection unavailable"). Orchestrator threads with a request in progress report the same. This replaces the limit-only handling earlier in this release.
   • Messages are never queued for replay after a reconnect: with no connection to send on, push throws a CONNECTION_LOST ConnectionError, and AgentThread.run and OrchestratorThread.push rethrow it after ending the request. The in-process loopback of the long-poll fallback is unchanged.
   • Secure channels now wait for the server's acknowledgement, like targeted channels. A missing acknowledgement throws a ConnectionError with code ACK_TIMEOUT (it was ARTError.ackTimeout).
   • Subscribing throws the ConnectionError instead of falling back to a local channel configuration; other subscribe failures still fall back. A failed agent or orchestrator subscribe is retried on the next call.
   • The long-poll fallback stops when a poll is rejected with HTTP 401 or 403, and reports failed polls as AuthHttpError.

   Breaking for custom transports

   • IWebsocketHandler has new members: ensureAuthorization(), onConnectionFailure() and offConnectionFailure().
   • IWebsocketHandler.sendMessage throws a ConnectionError instead of returning false and queueing the message.