NewYour coding agent can read the release notes before it upgrades.Set up the MCP server →
PyPI
PyPI, #3000 most downloaded on PyPI
SDK for integrating Composio with your applications.
Latest stable
0.32.0
Last release 13 days ago
09 Nov 2026
Ships fairly regularly
a new release about every 2 weeks
Most releases are documented
notes for 39 of the last 60 stable releases
Nothing withdrawn
no release was ever pulled
2 years old
87 releases · first in 2024
Drag across the ruler to compare, or tap a release to open it.
prepares composio==2.0.0b0 with composio-client==2.0.0rc6
This PR:
composio==2.0.0b0 with composio-client==2.0.0rc60.x release trainVerification:
uv lock --checkpnpm test:release-workflowgo run github.com/rhysd/actionlint/cmd/actionlint@v1.7.10 .github/workflows/py.release.ymlmake build-core and twine check --strict dist/*0.21.0; uv pip check and all provider imports passedAfter merge, pushing the immutable py@2.0.0b0 tag will publish only
the composio wheel and source distribution.
Nothing published for this version
Your coding agent can read these notes before it upgrades. Set up the MCP server →
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Nothing published for this version
Release Python SDK 0.30.0
Release Python SDK 0.30.0
Nothing published for this version
Release Python SDK and providers 0.29.0
Release Python SDK and providers 0.29.0
Release Python SDK 0.28.0
Release Python SDK 0.28.0
This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to next, this PR will
be updated.
@composio/client 2.0.0. POST and PATCH requests,getClient(), amaxRetries.@composio/client 2.0.0-rc.20. The SDK imports@composio/client/resources/* spellinggetClient() are plain objects typed by interfaces: theComposio.Tools-style statics and namespace-memberSessionCreateParams.Experimental are gone, and the.js/.mjs subpath spellings no longer resolve.@composio/client 2.0.0-rc.21. The SDK'sgetClient()request(), Composio.Composio orComposio.DEFAULT_TIMEOUT: call the raw verb for the method (get,post, patch, put, delete), which takes the same query, body@composio/client 2.0.0-rc.23.composio.sessionConfigs.list() no longer sends search, which theitems by name instead. With rc.23, the clientgetClient() no longer has cli.createCodactFailure (nowclient._internal, typed through @composio/client/internal) ororg.clanker.createClaim, and its sessionConfigs.list() no longersearch.@composio/client 2.0.0-rc.22.composio.toolkits.get(slug) now returns meta.appUrl when the APIcomposio.sessionConfigs.get() keeps the require_approval lists of arequire_approval; SessionConfigPolicy gains the matchingrequire_approval fields and the approval-only entry. Session@composio/client instead of SDK copies, with the same results andhook_results or blocked@composio/client 2.0.1. Addscomposio.experimental.customToolkits.create() and update(), whichcreate()userId ('all' to share the toolkit, or the user it is privateconnectLink for a privateupsert() is deprecated and logs a warning once per process;API-key auth schemes accept additionalFields.genericId with a required
displayName and optional description to collect the value used by
{{generic_id}} headers.
composio.triggers.create() accepts type ('webhook' or'poll', for a trigger that supports both) and pollingIntervaltriggerConfig.interval), andtype, fallbackReason and pollingIntervaltriggerId. composio.triggers.listActive() items carry thegetType() / listTypes() return each triggertype, types and requiresWebhookEndpointSetup.A file uploaded from a local path used to be sent as
application/octet-stream whatever it was, so tools that check the
file's type, such as Canva's design import, rejected it. The SDK now
infers the type from the file name's extension (a .pptx uploads as
application/vnd.openxmlformats-officedocument.presentationml.presentation)
and keeps application/octet-stream only for missing or unknown
extensions. The TypeScript and Python SDKs now use the same extension
table, so a file uploads with the same type from either SDK and from the
CLI. Files passed as File objects and URLs keep the type they carry.
getExtensionFromMimeType now maps text/csv to csv fromexperimental option to theToolRouterAuthorizeFn type. session.authorize() already acceptedexperimental: { accountType, aclConfigForShared } at runtime, butcomposio.create() and composio.use() rejected@composio/client 2.0.0. POST and PATCH requests,getClient(), amaxRetries.@composio/client 2.0.0-rc.20. The SDK imports@composio/client/resources/* spellinggetClient() are plain objects typed by interfaces: theComposio.Tools-style statics and namespace-memberSessionCreateParams.Experimental are gone, and the.js/.mjs subpath spellings no longer resolve.@composio/client 2.0.0-rc.21. The SDK'sgetClient()request(), Composio.Composio orComposio.DEFAULT_TIMEOUT: call the raw verb for the method (get,post, patch, put, delete), which takes the same query, body@composio/client 2.0.0-rc.23.composio.sessionConfigs.list() no longer sends search, which theitems by name instead. With rc.23, the clientgetClient() no longer has cli.createCodactFailure (nowclient._internal, typed through @composio/client/internal) ororg.clanker.createClaim, and its sessionConfigs.list() no longersearch.@composio/client 2.0.0-rc.22.composio.toolkits.get(slug) now returns meta.appUrl when the APIcomposio.sessionConfigs.get() keeps the require_approval lists of arequire_approval; SessionConfigPolicy gains the matchingrequire_approval fields and the approval-only entry. Session@composio/client instead of SDK copies, with the same results andhook_results or blocked@composio/client 2.0.1. Addscomposio.experimental.customToolkits.create() and update(), whichcreate()userId ('all' to share the toolkit, or the user it is privateconnectLink for a privateupsert() is deprecated and logs a warning once per process;API-key auth schemes accept additionalFields.genericId with a required
displayName and optional description to collect the value used by
{{generic_id}} headers.
composio.triggers.create() accepts type ('webhook' or'poll', for a trigger that supports both) and pollingIntervaltriggerConfig.interval), andtype, fallbackReason and pollingIntervaltriggerId. composio.triggers.listActive() items carry thegetType() / listTypes() return each triggertype, types and requiresWebhookEndpointSetup.getExtensionFromMimeType now maps text/csv to csv from@anthropic-ai/sdk ^0.135.0 as a peer dependency.Note truncated.
composio.mcp.generate() now warns once that its URLs rely on the deprecated include_composio_helper_actions query parameter; switch to a Session's MCP…
This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to next, this PR will
be updated.
session.executeMeta() to run a Composio meta toolCOMPOSIO_*) within a session. It takes a meta tool slug and optionalsession.execute(), includingresultType. Like session.execute(), it throwsComposioToolInputRequiredError when the tool needs user input and isToolRouterSessionMetaToolSlug type lists theThe Python SDK gains the matching session.execute_meta() and
ToolRouterSessionMetaToolSlug.
@composio/client@2.0.0-rc.14. OAuth connection data types now accept anull id_token. Session tag filters accept the createHint andupdateHint tags. The experimental instant.returnPricesInSearchtoolkitConnectionStatuses[].instantAccount.prices.composio.mcp.generate() now warns once that its URLs rely on theinclude_composio_helper_actions query parameter; switch toproxyExecute session option.composio.sessions.create(userId, { proxyExecute: true }) exposes theCOMPOSIO_PROXY_EXECUTE meta tool, which lets the agent call a{ enable: boolean }. session.update() accepts the samenull removes the stored value. proxyExecute: false alsoproxy_execute() helper, and the API rejects itsandbox.enableProxyExecution: true.session.executeMeta() to run a Composio meta toolCOMPOSIO_*) within a session. It takes a meta tool slug and optionalsession.execute(), includingresultType. Like session.execute(), it throwsComposioToolInputRequiredError when the tool needs user input and isToolRouterSessionMetaToolSlug type lists theThe Python SDK gains the matching session.execute_meta() and
ToolRouterSessionMetaToolSlug.
@composio/client@2.0.0-rc.14. OAuth connection data types now accept anull id_token. Session tag filters accept the createHint andupdateHint tags. The experimental instant.returnPricesInSearchtoolkitConnectionStatuses[].instantAccount.prices.composio.mcp.generate() now warns once that its URLs rely on theinclude_composio_helper_actions query parameter; switch toCo-authored-by: sdkrelease[bot] <294075132+sdkrelease[bot]@users.noreply.github.com>
c2bbfa8: Add session hooks. A hook can block a tool call before it runs, or block its result before the agent sees it.
create() and update() accept hooks. On update(), hooks replaces the whole list and null removes every hook. hooks cannot be combined with experimental.sessionConfigId.
const session = await composio.create('user_123', {
hooks: [
{
type: 'before_execute',
id: 'no_external_email',
name: 'No external email',
appliesTo: { toolkits: ['gmail'] },
handler: {
type: 'condition_check',
condition: 'Sending email to anyone outside example.org',
action: 'block',
},
},
],
});
A blocked call comes back from session.execute() and session.executeMeta() with resultType: 'blocked', empty data, the hook's message in error, and blockReason. Provider integrations hand it to the agent as a failed call with that message. Every result also carries hookResults when a hook applied.
session.proxyExecute() and ctx.proxyExecute() now return resultType: 'completed' or resultType: 'blocked'. A blocked request has no HTTP response, so TypeScript code that reads status has to check resultType first.
This PR was opened by the Changesets release GitHub action. When you're ready to do a release, you can merge this and the packages will be published t
This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to next, this PR will
be updated.
@composio/client@2.0.0-rc.11.A session tool can now ask for user input, such as an approval, instead
of running: the API answers the call with result_type: "input_required". session.execute(), session.proxyExecute(),
provider-wrapped session tools, and the execute / proxyExecute
helpers passed to custom tools throw the new
ComposioToolInputRequiredError in that case. A local custom tool whose
body makes such a call lets the error through instead of returning it as
a failed result. The error carries the questions on inputRequests and
the opaque request_state on requestState. requestState is
continuation state, so it is a non-enumerable property: read it as
error.requestState, and console.error(error), util.inspect(error)
and JSON.stringify(error) leave it out. Nothing was executed and the
call is not retried. The SDK does not submit answers yet.
Every session tool that ran reports result_type as completed or
failed, and a failed execution can carry a null or empty error.
session.execute() and the custom tool execute helper return it as
the new resultType, which is always present; read it rather than
error to tell a failure from a success. Provider-wrapped session
tools, provider tool calls bound to a session, and the merged
COMPOSIO_MULTI_EXECUTE_TOOL result set successful from it alone, so
a failure without error text is no longer reported as successful.
error is returned as the API sent it. A session execute answer without
result_type, or with a value this SDK does not know, throws
ValidationError instead of being read as a success or a failure.
A COMPOSIO_MULTI_EXECUTE_TOOL batch that mixes local custom tools with
remote tools now throws ComposioToolInputRequiredError when the remote
half needs user input, as an all-remote batch already did. It used to
report the input request as a failure message on each remote tool,
without inputRequests or requestState. Local tools in that batch
have already run by then, and their results are discarded by the throw.
Breaking changes:
ToolRouterSessionConfig (session.config, the result of
session.update()) and ToolRouterSessionConfigHistoryConfig
(session.listConfigHistory()) are now the client's own config types.
instant is always present (false or the policy object) instead of
optional.
In those config types, toolkits and each tools entry can be a { require_approval }-only object, so a check for enabled or disabled
no longer covers every case. tags can carry require_approval, and
the config can carry proxy_execute.
The session config is returned as the API sent it. The SDK no longer
validates instant at runtime or removes a premium_usage key.
ToolRouterSessionExecuteResponse requires resultType. A custom
ToolCallSession passed to a provider must return it from execute(),
because successful is no longer derived from error.
Removed the unused ToolRouterInstantResponseSchema and
ToolRouterInstantResponse exports. Use
ToolRouterSessionConfig['instant'] for the Instant policy the API
returns.
ec55dd1: Add userId to tools.proxyExecute(). It is sent as
user_id, which projects with 2FA enabled check against the connected
account and may require. Python's tools.proxy() takes the same value
as user_id.
@composio/client@2.0.0-rc.9.anyOf, oneOf, allOf, $ref, or similar keywords.ZodObject again, so the LangChain, Vercel,type: "object". Patterns with escapes such as \_ or \:session.execute(), session.proxyExecute(), provider-wrapped sessionexecute / proxyExecute helpers passed to custom toolstools.execute() andtools.proxyExecute().RemoteFile.save() without a path no longer rejects ordinaryreport_2026-09-29T10:30:00.csv or What is this?.png, are saved with_. Names longer than 128 bytes areNUL get a _ prefix. A name changed this way also gets a short digestWhat is this_-9c68adf2da8b6e8d.png). Default saves create a new filepattern and patternProperties regexes now runre2js), so a hostile pattern such as^(a+)+$ can no longer hang argument validation. A pattern that needspatternProperties key that needsInvalidPatternError (reason unsupported). Patterns now match astral{ "type": "string", "enum": ["asc", "desc"] } wasnull to its type only, so the enum still rejectednull and the model could not omit the parameter. Such schemas are nowanyOf with a null branch, as are type besideanyOf and $ref with sibling keywords. omitNullToolArguments nownull only when every keyword of the tool's schema accepts it,null that an enum, const, $ref sibling or allOf rejectsnulltype or anyOf are emitted exactly as before. A tool whose schema$ref into a property that wrapping moves is reported inunsupported and sent without strict mode. Null checks remember their@composio/client@2.0.0-rc.11.A session tool can now ask for user input, such as an approval, instead
of running: the API answers the call with result_type: "input_required". session.execute(), session.proxyExecute(),
provider-wrapped session tools, and the execute / proxyExecute
helpers passed to custom tools throw the new
ComposioToolInputRequiredError in that case. A local custom tool whose
body makes such a call lets the error through instead of returning it as
a failed result. The error carries the questions on inputRequests and
the opaque request_state on requestState. requestState is
continuation state, so it is a non-enumerable property: read it as
error.requestState, and console.error(error), util.inspect(error)
and JSON.stringify(error) leave it out. Nothing was executed and the
call is not retried. The SDK does not submit answers yet.
Every session tool that ran reports result_type as completed or
failed, and a failed execution can carry a null or empty error.
session.execute() and the custom tool execute helper return it as
the new resultType, which is always present; read it rather than
error to tell a failure from a success. Provider-wrapped session
tools, provider tool calls bound to a session, and the merged
COMPOSIO_MULTI_EXECUTE_TOOL result set successful from it alone, so
a failure without error text is no longer reported as successful.
error is returned as the API sent it. A session execute answer without
result_type, or with a value this SDK does not know, throws
ValidationError instead of being read as a success or a failure.
A COMPOSIO_MULTI_EXECUTE_TOOL batch that mixes local custom tools with
remote tools now throws ComposioToolInputRequiredError when the remote
half needs user input, as an all-remote batch already did. It used to
report the input request as a failure message on each remote tool,
without inputRequests or requestState. Local tools in that batch
have already run by then, and their results are discarded by the throw.
Breaking changes:
ToolRouterSessionConfig (session.config, the result ofsession.update()) and ToolRouterSessionConfigHistoryConfigsession.listConfigHistory()) are now the client's own config types.instant is always present (false or the policy object) instead oftoolkits and each tools entry can be a { require_approval }-only object, so a check for enabled or disabledtags can carry require_approval, andproxy_execute.instant at runtime or removes a premium_usage key.ToolRouterSessionExecuteResponse requires resultType. A customToolCallSession passed to a provider must return it from execute(),successful is no longer derived from error.ToolRouterInstantResponseSchema andToolRouterInstantResponse exports. UseToolRouterSessionConfig['instant'] for the Instant policy the API@composio/client@2.0.0-rc.9.run_composio_tool helper retried a timed-out orrun_composio_toolfailedinput_required answer, andproxy_execute returned (None, "") for a proxied call that needs userinput_required the errorrun_composio_tool returns the questions as input_requests withoutrequest_state.anyOf, oneOf, allOf, $ref, or similar keywords.ZodObject again, so the LangChain, Vercel,type: "object". Patterns with escapes such as \_ or \:pattern and patternProperties regexes now runre2js), so a hostile pattern such as^(a+)+$ can no longer hang argument validation. A pattern that needspatternProperties key that needsInvalidPatternError (reason unsupported). Patterns now match astralcacheTools: true exceeding Anthropic'swrapToolshandleToolCalls no longer markstool_result blocks, because they accumulate in the message history andNote truncated.
e08c84f: Requires @composio/client 2.0.0-rc.18. The SDK now hands the API client its credential as the client's auth option and its organization and project as scope, instead of placing them in default headers. The apiKey, userApiKey, orgApiKey, orgId and projectId options, their environment fallbacks and the credentials sent on each request are unchanged, with one exception: with apiKey: null and only an organization API key (the orgApiKey option, COMPOSIO_ORG_API_KEY, or an x-org-api-key default header), every request now carries x-org-api-key, and so do trigger channel authorization and session.mcp.headers. Before, only the organization-owner operations did, and every other request went out without a credential.
Credential and scope headers in defaultHeaders or createSession({ headers }) keep working, but the SDK folds them into its own options instead of forwarding them: an x-user-api-key or x-org-api-key entry becomes the credential every request carries, an x-api-key entry becomes the project key, and x-org-id / x-project-id entries become orgId / projectId. getConfig() reports the folded values (for example apiKey: null and userApiKey for an x-user-api-key entry) and no longer lists those entries under defaultHeaders. Setting more than one of x-api-key, x-user-api-key and x-org-api-key now throws a ComposioError; the API rejected every such request.
On the client returned by getClient(), apiKey, userApiKey and orgApiKey are read-only and deprecated (read the keys from getConfig(), or authMode and scope from the client), and a per-call headers option can no longer name a credential or scope header. The API client no longer reads the environment itself: the SDK still honours COMPOSIO_ALLOW_INSECURE_HTTP=1, and no longer applies COMPOSIO_CUSTOM_HEADERS; pass defaultHeaders instead.
The deprecated customConnectionData now requires val.access_token for S2S_OAUTH2, as the API does.
57de614: Requires @composio/client 2.0.0-rc.19. The SDK forwards the API client's log lines through a Console-shaped object instead of the client's removed Logger interface; what is logged, and at which SDK level, is unchanged. With rc.19, the client returned by getClient() no longer has apiKey, userApiKey, orgApiKey or logger, and its baseURL, maxRetries, timeout and logLevel are read-only: read the keys from getConfig(), and derive a client with withOptions() to change the others.
9d26fb8: Fold OpenAPI nullable into the type in strict tool schemas
toStrictJsonSchema no longer passes OpenAPI nullable through. Anthropic strict tool use rejects it on an object schema with a 400 for the whole request. A node with nullable: true now accepts null through its type (["object", "null"]) or a null branch, matching how the tool's arguments are validated, and the rewrite is reported as a nullable-converted change. nullable: false is removed as an unsupported-keyword-stripped change. omitNullToolArguments now keeps a null for a property marked nullable: true, as it already does for one whose type includes null.
3dd9a2c: Strip string format values that OpenAI structured outputs rejects from strict tool schemas
toStrictJsonSchema now removes a format on a string schema unless it is one of date-time, time, date, duration, email, hostname, ipv4, ipv6, or uuid. OpenAI rejects any other string format in strict mode with a 400 for the whole request, so a single tool with format: "uri", a custom format such as repo.nwo, or the format: "path" that file uploads add made every strict request fail. The removal is reported as an unsupported-keyword-stripped change. Formats on number and integer schemas are kept, since the API does not check them.
04fdb41: Check a string tool parameter as base64 only when its contentEncoding is base64. format: "binary" (raw octets in OpenAPI) and other encodings such as base16 were validated as base64, so the Vercel, LangChain, LlamaIndex, and Claude Agent SDK providers rejected tool calls with plain text or hex in those fields, and the schema sent to the model described them as contentEncoding: "base64". Those fields are now plain strings. contentEncoding: "base64" keeps its check, and format: "byte" stays unchecked.
be12ce1: Warn once per toolkit version when the API reports it as deprecated through the Composio-Deprecated-Toolkits response header. The warning names the version, the sunset date and how to pin a newer version. Silence it with logLevel: 'error' or COMPOSIO_LOG_LEVEL=error.
Updated dependencies [f119f05]
Updated dependencies [04fdb41]
e182bc8 : Remove the deprecated OpenAI Assistants API helpers from OpenAIProvider : handleAssistantMessage , waitAndHandleAssistantToolCalls , and wai…
This PR was opened by the Changesets
release GitHub action. When
you're ready to do a release, you can merge this and the packages will
be published to npm automatically. If you're not ready to do a release
yet, that's fine, whenever you add more changesets to next, this PR will
be updated.
instant.return_instant_charge, expose instantCharge on executioninstantAccount. Useinstant_account for explicit account selection.instantCharge in projectmetadata.instant_charge in tool log metadata.OpenAIProvider: handleAssistantMessage,waitAndHandleAssistantToolCalls, andwaitAndHandleAssistantStreamToolCalls. OpenAI shut down the AssistantsOpenAIResponsesProvider from @composio/openai with the ResponsesConnectionRequest.status in sync withwaitForConnection(). The request now reports ACTIVE once theFAILED, EXPIRED,REVOKED) when it fails, matching toJSON() and the Python SDK.ConnectionRequest.waitForConnection(). telemetry.instrument() nowcreateConnectionRequest().executeToolCallhandleResponse to execute throughoptions argument is now optional. Passing a session@composio/core 0.17.0 or later. Custom provider subclassesexecuteToolCallhandleResponse to execute throughoptions argument is now optional. Passing a session@composio/core 0.17.0 or later. Custom provider subclassesexecuteToolCallhandleResponse to execute throughoptions argument is now optional. Passing a session@composio/core 0.17.0 or later. Custom provider subclasses79c2d1d: Requires @composio/client 2.0.0-rc.17. The SDK now reports itself to the API client through the client's identity option instead of default headers. The headers sent with each request are unchanged, with one exception: on Cloudflare Workers and Vercel Edge with Node.js compatibility enabled, x-client-runtime now names that runtime instead of nodejs, and the polyfilled Node.js version is no longer sent as x-runtime-version. A createSession() clone no longer copies these headers into its defaultHeaders.
The API client owns these headers, so defaultHeaders and createSession({ headers }) now reject x-client-provenance, x-client-version, x-client-library, x-client-library-version, x-client-language, x-client-runtime, x-sdk-version, x-source, x-framework, x-runtime and x-runtime-version with a ComposioError from @composio/client. The SDK used to overwrite such entries silently.
A custom provider whose name cannot be sent as a header value (anything other than printable ASCII with no leading or trailing whitespace) is reported as unknown in x-framework.
40546c3: Add experimental support for tool calls that need the user's approval.
Sessions accept a requireApproval list next to the toolkits, tools and tags filters on create() and update(). A call to a matching tool doesn't run: session.execute() and session.executeMeta() throw ComposioToolInputRequiredError with the questions on inputRequests. To answer, repeat the same call with the user's answers in inputResponses and the error's requestState:
const session = await composio.create('user_123', {
tools: { gmail: { requireApproval: ['GMAIL_SEND_EMAIL'] } },
});
try {
await session.execute('GMAIL_SEND_EMAIL', args);
} catch (error) {
if (!(error instanceof ComposioToolInputRequiredError)) throw error;
const inputResponses = await promptUser(error.inputRequests);
await session.execute('GMAIL_SEND_EMAIL', args, {
inputResponses,
requestState: error.requestState,
});
}
promptUser is a placeholder for your application's consent UI. Display each request, wait for the user's response, and return the answers keyed by request ID. Forward decline and cancel responses unchanged.
experimental.noElicitationSupportFallback ('deny' or 'allow') sets what happens to such a call when the session's MCP client can't ask the user.
session.executeMeta() now takes these answers as its third argument, so its request options move to the fourth.
The Python SDK gains the same require_approval lists, experimental.no_elicitation_support_fallback, and input_responses and request_state on session.execute() and session.execute_meta().
f9a972b: Update the owned API client to @composio/client@2.0.0-rc.16. The SDK's public API and runtime behavior are unchanged.
04cd5c4: Fix the trigger subscription lifecycle and contain errors from trigger handlers.
triggers.unsubscribe() now closes the realtime connection, so a Node process can exit once it has unsubscribed. A later triggers.subscribe() opens a new connection.triggers.unsubscribe() before any subscribe() no longer fetches realtime credentials or creates a client.subscribe() calls share one connection, and unsubscribe() cancels a subscription that is still connecting, so it never opens a connection or delivers events afterwards.async trigger handler is logged like a synchronous throw instead of escaping as an unhandled rejection that ends the process. Handler failures log the error's message rather than {}.Include the Python premium-charge response support merged in #4623 in the 0.24.0 changelog. The notes cover the opt-in, typed response, provider and m
Include the Python premium-charge response support merged in #4623 in
the 0.24.0 changelog. The notes cover the opt-in, typed response,
provider and mixed-execution preservation, and exported charge fields.
Validation: release-workflow checks, Prettier, and git diff checks pass.
This is a documentation-only follow-up to the release preparation.
59935c0: Add session.executeMeta() to run a Composio meta tool (COMPOSIO_*) within a session. It takes a meta tool slug and optional arguments, and returns the same result as session.execute(), including resultType. Like session.execute(), it throws ComposioToolInputRequiredError when the tool needs user input and is not retried. The new ToolRouterSessionMetaToolSlug type lists the accepted slugs.
The Python SDK gains the matching session.execute_meta() and ToolRouterSessionMetaToolSlug.
@composio/client@2.0.0-rc.14. OAuth connection data types now accept a null id_token. Session tag filters accept the createHint and updateHint tags. The experimental instant.returnPricesInSearch Session option returns each Instant tool's price in Session search results, under toolkitConnectionStatuses[].instantAccount.prices. composio.mcp.generate() now warns once that its URLs rely on the deprecated include_composio_helper_actions query parameter; switch to a Session's MCP endpoint.59935c0: Add session.executeMeta() to run a Composio meta tool (COMPOSIO_*) within a session. It takes a meta tool slug and optional arguments, and returns the same result as session.execute(), including resultType. Like session.execute(), it throws ComposioToolInputRequiredError when the tool needs user input and is not retried. The new ToolRouterSessionMetaToolSlug type lists the accepted slugs.
The Python SDK gains the matching session.execute_meta() and ToolRouterSessionMetaToolSlug.
@composio/client@2.0.0-rc.14. OAuth connection data types now accept a null id_token. Session tag filters accept the createHint and updateHint tags. The experimental instant.returnPricesInSearch Session option returns each Instant tool's price in Session search results, under toolkitConnectionStatuses[].instantAccount.prices. composio.mcp.generate() now warns once that its URLs rely on the deprecated include_composio_helper_actions query parameter; switch to a Session's MCP endpoint.proxyExecute session option. composio.sessions.create(userId, { proxyExecute: true }) exposes the COMPOSIO_PROXY_EXECUTE meta tool, which lets the agent call a toolkit's API directly with the user's connected account. A boolean is shorthand for { enable: boolean }. session.update() accepts the same option, and null removes the stored value. proxyExecute: false also turns off the sandbox proxy_execute() helper, and the API rejects it at creation together with sandbox.enableProxyExecution: true.55ed9e2: Update the owned API client to @composio/client@2.0.0-rc.11.
55ed9e2: Update the owned API client to @composio/client@2.0.0-rc.11.
A session tool can now ask for user input, such as an approval, instead of running: the API answers the call with result_type: "input_required". session.execute(), session.proxyExecute(), provider-wrapped session tools, and the execute / proxyExecute helpers passed to custom tools throw the new ComposioToolInputRequiredError in that case. A local custom tool whose body makes such a call lets the error through instead of returning it as a failed result. The error carries the questions on inputRequests and the opaque request_state on requestState. requestState is continuation state, so it is a non-enumerable property: read it as error.requestState, and console.error(error), util.inspect(error) and JSON.stringify(error) leave it out. Nothing was executed and the call is not retried. The SDK does not submit answers yet.
Every session tool that ran reports result_type as completed or failed, and a failed execution can carry a null or empty error. session.execute() and the custom tool execute helper return it as the new resultType, which is always present; read it rather than error to tell a failure from a success. Provider-wrapped session tools, provider tool calls bound to a session, and the merged COMPOSIO_MULTI_EXECUTE_TOOL result set successful from it alone, so a failure without error text is no longer reported as successful. error is returned as the API sent it. A session execute answer without result_type, or with a value this SDK does not know, throws ValidationError instead of being read as a success or a failure.
A COMPOSIO_MULTI_EXECUTE_TOOL batch that mixes local custom tools with remote tools now throws ComposioToolInputRequiredError when the remote half needs user input, as an all-remote batch already did. It used to report the input request as a failure message on each remote tool, without inputRequests or requestState. Local tools in that batch have already run by then, and their results are discarded by the throw.
Breaking changes:
ToolRouterSessionConfig (session.config, the result of session.update()) and ToolRouterSessionConfigHistoryConfig (session.listConfigHistory()) are now the client's own config types. instant is always present (false or the policy object) instead of optional.toolkits and each tools entry can be a { require_approval }-only object, so a check for enabled or disabled no longer covers every case. tags can carry require_approval, and the config can carry proxy_execute.instant at runtime or removes a premium_usage key.ToolRouterSessionExecuteResponse requires resultType. A custom ToolCallSession passed to a provider must return it from execute(), because successful is no longer derived from error.ToolRouterInstantResponseSchema and ToolRouterInstantResponse exports. Use ToolRouterSessionConfig['instant'] for the Instant policy the API returns.@composio/client@2.0.0-rc.9.55ed9e2: Update the owned API client to @composio/client@2.0.0-rc.11.
A session tool can now ask for user input, such as an approval, instead of running: the API answers the call with result_type: "input_required". session.execute(), session.proxyExecute(), provider-wrapped session tools, and the execute / proxyExecute helpers passed to custom tools throw the new ComposioToolInputRequiredError in that case. A local custom tool whose body makes such a call lets the error through instead of returning it as a failed result. The error carries the questions on inputRequests and the opaque request_state on requestState. requestState is continuation state, so it is a non-enumerable property: read it as error.requestState, and console.error(error), util.inspect(error) and JSON.stringify(error) leave it out. Nothing was executed and the call is not retried. The SDK does not submit answers yet.
Every session tool that ran reports result_type as completed or failed, and a failed execution can carry a null or empty error. session.execute() and the custom tool execute helper return it as the new resultType, which is always present; read it rather than error to tell a failure from a success. Provider-wrapped session tools, provider tool calls bound to a session, and the merged COMPOSIO_MULTI_EXECUTE_TOOL result set successful from it alone, so a failure without error text is no longer reported as successful. error is returned as the API sent it. A session execute answer without result_type, or with a value this SDK does not know, throws ValidationError instead of being read as a success or a failure.
A COMPOSIO_MULTI_EXECUTE_TOOL batch that mixes local custom tools with remote tools now throws ComposioToolInputRequiredError when the remote half needs user input, as an all-remote batch already did. It used to report the input request as a failure message on each remote tool, without inputRequests or requestState. Local tools in that batch have already run by then, and their results are discarded by the throw.
Breaking changes:
ToolRouterSessionConfig (session.config, the result of session.update()) and ToolRouterSessionConfigHistoryConfig (session.listConfigHistory()) are now the client's own config types. instant is always present (false or the policy object) instead of optional.toolkits and each tools entry can be a { require_approval }-only object, so a check for enabled or disabled no longer covers every case. tags can carry require_approval, and the config can carry proxy_execute.instant at runtime or removes a premium_usage key.ToolRouterSessionExecuteResponse requires resultType. A custom ToolCallSession passed to a provider must return it from execute(), because successful is no longer derived from error.ToolRouterInstantResponseSchema and ToolRouterInstantResponse exports. Use ToolRouterSessionConfig['instant'] for the Instant policy the API returns.ec55dd1: Add userId to tools.proxyExecute(). It is sent as user_id, which projects with 2FA enabled check against the connected account and may require. Python's tools.proxy() takes the same value as user_id.
@composio/client@2.0.0-rc.9.anyOf, oneOf, allOf, $ref, or similar keywords. The converted schema is a ZodObject again, so the LangChain, Vercel, LlamaIndex, and Claude Agent SDK providers send tool parameters with a top-level type: "object". Patterns with escapes such as \_ or \: no longer fail every call to the tool.session.execute(), session.proxyExecute(), provider-wrapped session tools, and the execute / proxyExecute helpers passed to custom tools no longer retry after a timeout, connection error, or 408/409/429/5xx response, so a retry can no longer repeat a side effect such as sending the same email twice. This matches tools.execute() and tools.proxyExecute().RemoteFile.save() without a path no longer rejects ordinary file names. Names with characters Windows reserves, such as report_2026-09-29T10:30:00.csv or What is this?.png, are saved with those characters replaced by _. Names longer than 128 bytes are truncated with their extension kept, and reserved device names such as NUL get a _ prefix. A name changed this way also gets a short digest of the original before its extension (What is this_-9c68adf2da8b6e8d.png). Default saves create a new file exclusively; if the destination exists, a copy number is added before its extension. Repeated default saves therefore return distinct paths and preserve earlier downloads. Names with a NUL byte or no usable basename are still refused.pattern and patternProperties regexes now run on a linear-time engine (RE2, via re2js), so a hostile pattern such as ^(a+)+$ can no longer hang argument validation. A pattern that needs lookaround still runs on the native engine when a static check shows it cannot backtrack catastrophically, on input up to 1000 characters; otherwise it is left unenforced. A patternProperties key that needs lookaround or a backreference now fails conversion with an InvalidPatternError (reason unsupported). Patterns now match astral characters (emoji) as single characters, as JSON Schema's Unicode regex dialect does.{ "type": "string", "enum": ["asc", "desc"] } was widened by adding null to its type only, so the enum still rejected null and the model could not omit the parameter. Such schemas are now wrapped whole in anyOf with a null branch, as are type beside anyOf and $ref with sibling keywords. omitNullToolArguments now keeps a null only when every keyword of the tool's schema accepts it, so a null that an enum, const, $ref sibling or allOf rejects is treated as an omitted argument. Schemas whose only obstacle to null is type or anyOf are emitted exactly as before. A tool whose schema holds a $ref into a property that wrapping moves is reported in unsupported and sent without strict mode. Null checks remember their answer per schema node and are bounded in depth and work, so a schema whose definitions fan out through shared references stays cheap.Release Python SDK 0.22.0
Release Python SDK 0.22.0
instant.return_instant_charge, expose instantCharge on execution results, and rename search account metadata to instantAccount. Use instant_account for explicit account selection.instantCharge in project usage summaries and as metadata.instant_charge in tool log metadata.OpenAIProvider: handleAssistantMessage, waitAndHandleAssistantToolCalls, and waitAndHandleAssistantStreamToolCalls. OpenAI shut down the Assistants API on August 26, 2026, so these helpers could no longer complete a run. Use OpenAIResponsesProvider from @composio/openai with the Responses API instead.ConnectionRequest.status in sync with waitForConnection(). The request now reports ACTIVE once the connection completes, or the terminal status (FAILED, EXPIRED, REVOKED) when it fails, matching toJSON() and the Python SDK.ConnectionRequest.waitForConnection(). telemetry.instrument() now also instruments async methods defined directly on plain objects, such as the ones returned by createConnectionRequest().Nothing published for this version
461c6c3: Add experimental premiumUsage support when creating and updating Tool Router Sessions.
premiumUsage support when creating and updating Tool Router Sessions.hostedAccount.allowedToolSlugs on session.search() toolkit connection statuses for toolkits served by a Composio hosted account.composio.sessionConfigs.list() and composio.sessionConfigs.get() read the project's saved sc_… configs, and experimental.sessionConfigId on composio.sessions.create() starts a session from one. Combining sessionConfigId with inline access fields now fails before any request: on create with toolkits, tools, tags, experimental.customTools or experimental.customToolkits, and on session.update() with toolkits, tools or tags (including null). TypeScript reports the mix at compile time and the SDK throws ValidationError at runtime; other invalid inputs keep throwing ZodError. session.experimental.sourceSessionConfig exposes the last config applied to the session after create(), sessions.use() and update(). A 409 while update() applies a config now says that the session or the config changed and to re-fetch and retry, instead of reporting a stale version.3721d04: Validate the server-supplied mount path before RemoteFile.save() turns it into a filename. A mountRelativePath of "", ".", "sub/.", "foo/.." or ".." made the default save path equal the download directory or its parent, which surfaced as an unhandled EISDIR from writeFileSync after the directory had already been created. These now throw a ValidationError naming the offending mount path, before any mkdir or write. An explicit path passed by the caller is unaffected.
The new safeBasename helper applies the filename safety checks used by the Python SDK: both / and \ count as separators, and NUL or control characters, Windows-reserved characters and device names, trailing spaces or dots, invalid Unicode and names over 128 UTF-8 bytes are rejected. RemoteFile.filename now also splits on both separators, so a Windows-style mount path reduces to the same display name on every platform.
Drive-relative paths such as C:report.txt reduce to report.txt. Whitespace stripping follows Python rules, preserving U+FEFF. Both SDKs also reject trailing dots exposed by stripping Unicode whitespace.
5ec0bdf: Validate the default destination in RemoteFile.save() before downloading content. Invalid mount paths now raise ValidationError without a network request, even when the download would fail.
de5e3f6: Remove experimental annotations from the top-level Session config read methods. Applying a config and reading its source metadata remain under experimental.
5d07582: session.update() no longer sends expected_config_version by default. Since 0.20.0 it sent the session's last observed configVersion on every call, and the API rejects that field with a 400 (Unrecognized key(s) in object: 'expected_config_version'), so every default update() failed. The default is now last writer wins. Pass expectedConfigVersion (for example session.configVersion) to make an update conditional where the API supports it; expectedConfigVersion: false is the same as omitting it.
connectedAccounts.refresh() is marked @deprecated (the endpoint is deprecated upstream).
a4a40a1: Fix project API key resolution so the SDK never sends a Composio user API key (uak_..., as stored by composio login) as the x-api-key project credential. When that stored key is the only candidate, the constructor now throws a redacted ComposioAPIKeyKindError that explains the mismatch instead of making requests that fail with 401. apiKey: null now disables project-key authentication entirely, including the COMPOSIO_API_KEY and ~/.composio/user_data.json fallbacks, and is accepted when the instance holds another credential: userApiKey or orgApiKey (explicit or from their environment variables), or an x-user-api-key entry in defaultHeaders. Requests then carry only that credential. Malformed or unexpectedly shaped user config files produce a diagnostic that names the file without echoing its contents, and cloned instances keep the credential they were resolved with instead of re-reading the environment. Code that resolves the key with apiKey: process.env.COMPOSIO_API_KEY ?? null (or any expression that yields null when the variable is unset) is affected: it used to fall back to the environment and the CLI config file and now throws unless another credential is configured; omit apiKey (or pass undefined) to keep the fallbacks. With apiKey: null, an x-api-key entry in defaultHeaders is rejected as well, including on createSession() clones: pass the project key as apiKey instead of a raw header.
6c56b73: Add userApiKey and orgApiKey to ComposioConfig. Both are forwarded to the underlying API client, which sends each one only on operations whose security scheme requires it (organization, consumer, and user-scoped endpoints reached through getClient()), never alongside the project key. They fall back to COMPOSIO_USER_API_KEY and COMPOSIO_ORG_API_KEY. A project apiKey is still required unless it is set to null, which opts into user-only authentication.
6c56b73: Expose the rest of the owned client surface on the Composio class:
composio.webhooks.subscriptions (list, get, set, update, delete, rotateSecret, listEventTypes) and composio.webhooks.endpoints (list, get, create, replace, update). composio.triggers.setWebhookSubscription() now delegates to the same upsert as webhooks.subscriptions.set(). Its behaviour for well-formed API responses is unchanged; malformed responses are now rejected with a ValidationError instead of being read leniently.composio.logs.search() and composio.logs.get() for tool-execution logs.composio.connectedAccounts.revoke(), which surfaces the API's 400/409 as ComposioConnectedAccountRevocationNotSupportedError / ComposioConnectedAccountNotRevokableError. connectedAccounts.refresh() is marked @deprecated (the endpoint is deprecated upstream).composio.toolkits.getMany(slugs) and composio.toolkits.changelog().session.listConfigHistory() on sessions.composio.experimental.usage.summary() and composio.experimental.usage.breakdown() (experimental, shape may change).composio.toolkits.recommendScopes(toolkitSlug, { tools, ... }) and composio.toolkits.listGrantContexts(toolkitSlug) for OAuth scope recommendations (the API marks both beta).composio.connectedAccounts.completeAuth({ userId, sessionUri }), which completes a deferred OAuth connection after your OAuth callback verifier has confirmed the user's identity.composio.keyring.listTransferKeys(), which returns the public JWKs of the organization's customer-managed keyring.composio.experimental.customToolkits (upsert, sync, delete) for project-owned custom toolkits (in pilot, shape may change).CIMD_OAUTH joins AuthSchemeTypes.triggers.listActive() returns {} for state and triggerConfig when the API sends null.ToolkitAuthField gains userVisible (from user_visible) and ToolkitAuthConfigDetails gains requiredScopes (from required_scopes), both omitted when the API does not send them.@composio/client moves from the old autogenerated client to the new handrolled client. The API removed validate_credentials from the connected-account refresh, so connectedAccounts.refresh() now ignores validateCredentials and logs a warning when it is set.logger and logLevel options on new Composio({...}). logger accepts any { error, warn, info, debug } sink (console, pino, winston, ...) and receives the SDK's formatted, credential-redacted output; logLevel ('silent' | 'error' | 'warn' | 'info' | 'debug') overrides COMPOSIO_LOG_LEVEL. The owned client's runtime deprecation warnings (response Deprecation/Sunset headers and deprecated request inputs) are now routed through that SDK logger instead of console. The client's per-request lifecycle logs are emitted only at 'debug'. tools.get/getRawComposioTools send the API's query parameter in place of the deprecated search wire parameter; the SDK's public search option is unchanged.a4a40a1: Sessions now export their MCP config from the auth context the session request was actually made with: the project key as x-api-key when one is configured, otherwise the user API key (userApiKey or the x-user-api-key default header) as x-user-api-key, plus x-org-id / x-project-id when the instance is scoped. No other default header and no ambient COMPOSIO_API_KEY is ever copied. The headers are only attached when the MCP URL shares the origin of the configured API base URL (whatever its scheme). Any other destination (a different origin, an opaque origin such as a data: URL, or a URL that does not parse) never receives them: with mcp: true, create() / use() throw ComposioMCPDestinationError, which names both origins and never includes a key; without mcp: true the session is returned with session.mcp.headers empty and a warning naming both origins is logged, so native tools keep working. The SDK never connects to the MCP URL itself and does not follow redirects for it. Trigger subscriptions (Pusher channel auth) follow the same rule instead of falling back to the environment when the project key is disabled.
ComposioConfig gains orgId and projectId: the organization and consumer project nano IDs, sent together as the x-org-id / x-project-id headers on every request and with the session MCP config. They may also be supplied through defaultHeaders; a half-configured or disagreeing scope throws ComposioScopeConfigError. Without a scope, a user API key keeps addressing the API default project.
session.update() now sends the session's last observed configVersion as the expected_config_version precondition by default and never retries that request, so a concurrent change surfaces as ComposioSessionConfigConflictError (HTTP 409; re-fetch the session, then retry) while the local session object stays unchanged. Pass expectedConfigVersion to send another version or expectedConfigVersion: false to opt out (last writer wins). Every policy block (toolkits, tools, tags, authConfigs, connectedAccounts, preload, manageConnections, multiAccount, search, execute, experimental) accepts null to remove the stored override, manageConnections.callbackUrl: null removes only the stored callback URL, multiAccount.maxAccountsPerToolkit: null removes the stored maximum, and an empty toolkit allowlist (toolkits: []) is sent as-is so it denies every app toolkit.
6c56b73: Replace the old autogenerated @composio/client with the new handrolled client.
Tool-only updates (allowedTools without toolkits) sent no tools field at all, updates with toolkits sent the deprecated create-time custom_tools alias…
efc2e52: Keep TypeScript realtime subscription errors inside the SDK logging boundary so an asynchronous Pusher subscription failure cannot escape as an uncaught exception. The full subscription error payload is now logged, the success message is logged only once Pusher confirms the subscription, and PusherService.subscribe / Triggers.subscribe accept an optional onSubscriptionError callback so applications can react to subscription failures programmatically.
4b5920b: Add session.ensureConnected(toolkit, options?): it returns immediately when the session already resolves an active connection (or the toolkit is no-auth), and only when needed starts the authorization flow via session.authorize() and waits for the new connection to become active. This prevents authorize() from spawning duplicate pending connections for toolkits that are already connected. The session.execute() account option is now documented as accepted on every project — on single-account projects the identifier must match one of the session's active connections for the toolkit (matching the API behavior).
c7843d8: Expose the server-side session configuration on sessions and return it from update(). session.config now carries the toolkit/tool allowlists, tags, auth configs, connected accounts, manage_connections, preload and sandbox settings the API returned for the session (from create(), use() and after every update()), and session.update() resolves to that updated config instead of void. Previously the only config reachable on a session object at runtime was the SDK's own ComposioConfig, and reading the live allowlist after sessions.use(id) required dropping to the raw client.
config is a required member of the Session interface, so objects you construct yourself to satisfy Session (test doubles, wrappers) now need a config value. Callers of SDK-created sessions are unaffected. The read side is the raw API shape (toolkits.enabled, manage_connections), while update() keeps taking the SDK's camelCase input.
@composio/anthropic also accepts @anthropic-ai/sdk 0.124 as a peer, the line it is now tested against.pattern and patternProperties compilation. A pattern that does not compile or exceeds 1024 characters now fails conversion with an InvalidPatternError that names the offending property path instead of a raw SyntaxError. @composio/core surfaces that path in the JsonSchemaToZodError message. No backtracking heuristic is applied: a hostile pattern that backtracks catastrophically remains a known limitation.composio.mcp.update() silently dropping parts of the requested configuration. Tool-only updates (allowedTools without toolkits) sent no tools field at all, updates with toolkits sent the deprecated create-time custom_tools alias that the update endpoint ignores instead of allowed_tools, and manuallyManageConnections was forwarded as-is instead of being inverted into managed_auth_via_composio (so manuallyManageConnections: true stored the opposite configuration). create() and update() now also keep the auth config of a { toolkit, authConfigId } toolkit entry instead of discarding it, and create() sends allowed_tools rather than the deprecated custom_tools alias, matching the Python SDK.readResponseBodyWithLimit and MAX_URL_UPLOAD_SIZE_BYTES so downstream packages can apply the SDK's 100 MiB cap when they download a file from a user-supplied URL. The CLI's tool-input file uploads now use it instead of buffering the whole response.ssrfSafeFetch, which following redirects manually meant fetch never applied: a 303 now retries as a bodiless GET instead of replaying an upload's method and body at a result URL, a 301/302 does the same for a POST, and 307/308 keep replaying both. Only 301, 302, 303, 307 and 308 count as redirects to follow, so a 304 or 305 carrying a Location is returned to the caller rather than followed.2002::/16), Teredo and the rest of 2001::/23, local-use NAT64 (64:ff9b:1::/48), 100::/64, 2001:db8::/32 and site-local fec0::/10 each carry or reach an arbitrary IPv4 address, so 2002:7f00:1:: was a public-looking literal for 127.0.0.1. IPv4 multicast and the 192.88.99.0/24 6to4 relay range are blocked too.Authorization, Proxy-Authorization, and Cookie from the request headers when the SSRF guard follows a redirect to a different origin, as the Fetch standard does for automatic redirects. Same-origin redirects keep them.ssrfSafeFetch that rejects configured network
routes when the connection cannot be pinned to the validated address.ComposioToolNotFoundError. tools.getRawComposioToolBySlug, and the tools.get / tools.execute paths that call it, now raise ComposioToolNotFoundError only when the API answers 404 or 400. Any other failure, such as an invalid API key (401), a server error, or a network fault, raises the new ComposioToolFetchError with the client error preserved as cause. toolkits.get(slug) now applies its 404/400 check against the Composio client's APIError instead of the OpenAI one, so an unknown toolkit raises ComposioToolkitNotFoundError as documented.is_secret, legacy_template_name and auth_hint_url from toolkit auth config details. transformToolkitRetrieveResponse passed the auth field groups through unchanged, so the snake_case keys never matched ToolkitAuthFieldSchema and zod stripped them during validation; auth_hint_url was never mapped at all. Fields returned by toolkits.getConnectedAccountInitiationFields() and toolkits.getAuthConfigCreationFields() now carry isSecret, which the API documents as the signal for whether a client should mask the input, plus legacyTemplateName; auth config details returned by toolkits.get() now carry authHintUrl. Each of these keys is present only when the API sends it, so spreading a field no longer overwrites a caller's own fallback with undefined. An auth config detail that omits a field group entirely now yields empty lists for that group, matching how the docs pipeline defaults them, instead of failing validation and leaving the other group unusable.tools.getInput and tools.proxyExecute. The getInput example now passes the required text field and reads the generated arguments. The proxyExecute example now uses the flat endpoint / method / connectedAccountId shape and explains that a relative endpoint is appended to the toolkit's base URL, which can already include a path. The tools.execute example shows where to find the version to pin.Nothing published for this version
@composio/json-schema-to-zod@0.3.2
authConfigId filter.04817cb: Fix strict-mode tool schemas for OpenAI structured outputs. Strict normalization now applies OpenAI's contract at every depth (nested objects
anyOf branches, array items, inlined $ref/$defs): every object lists all of its properties in required and sets additionalProperties: false, so tools with nested or optional parameters no longer produce schemas the API rejects with a 400. Optional parameters are no longer dropped: they stay available and are widened to accept null, the emulation of optional fields OpenAI documents, and the strict providers drop a null argument the tool's own schema does not accept before executing the tool. Tools whose schema strict mode cannot express (objects with arbitrary keys, allOf, prefixItems, unresolved $refs) are sent without strict mode with a warning naming the tool and path, instead of being narrowed. @composio/core exports the new toStrictJsonSchema() and omitNullToolArguments() utilities; removeNonRequiredProperties is unchanged for other callers. The Python OpenAIResponsesProvider gains a matching opt-in strict=True constructor flag that also emits strict: true on the wrapped tool.dangerouslyAllowAutoUploadDownloadFiles is off, and with it on an empty value is no longer attempted as an upload.this.name assignment and therefore reported name as 'ComposioError' instead of their own class name, mis-grouping distinct error types in error telemetry.assertSafeFetchTarget is now the address ssrfSafeFetch connects to, so a hostname is no longer resolved a second time between the check and the connection. Each redirect hop is re-validated and re-pinned. The request still carries the original hostname in Host and TLS SNI, so certificate verification is unchanged. Hops whose effective dispatcher is a configured route — a caller-supplied dispatcher, a global ProxyAgent/EnvHttpProxyAgent, or NODE_USE_ENV_PROXY env-proxy mode — keep the pre-flight check only, mirroring the Python guard's documented proxy residual.Nothing published for this version
760f8d0: Allow OpenAI and Anthropic provider tool-call helpers to execute through a supplied Tool Router session. Session meta-tools now retain their
{ error } results without changing successful payloads. Custom provider subclasses overriding executeToolCall or handleToolCalls may require updates because these methods now accept session targets.s3Url), S3 presigned uploads (new_presigned_url), Tool Router session file downloads (RemoteFile.buffer() / blob() / text() / save()) and session file uploads (upload_url) now go through the same SSRF guard that already covered user-supplied URLs, so a response naming a private, loopback, or link-local address is refused instead of fetched. Redirect hops are re-validated. Edge runtimes keep their current behavior: session file transfers are not blocked there, since a Worker cannot resolve DNS to check and its fetch does not originate inside the caller's network.@composio/json-schema-to-zod@0.3.0
5e57815: Keep free-form object roots, patternProperties, and additionalProperties when parsing a tool schema.
ToolSchema.parse used to reject a bare { "type": "object" } root, drop root patternProperties as an unknown key, and reject a root additionalProperties written as a schema instead of a boolean. Free-form roots now parse successfully, and both constraints survive parsing exactly as written. The public ToolSchema type now makes properties optional to reflect those valid property-less object schemas.
This matters downstream. Every provider reads inputParameters after parsing, so a tool that declares dynamic keys had those rules stripped before the model ever saw them.
An omitted additionalProperties still stays omitted. The parser does not invent a value, because each converter decides its own default.
What no longer works
Parsing no longer fails on a schema-valued root additionalProperties.
const tool = ToolSchema.parse({
slug: 'MY_TOOL',
inputParameters: {
type: 'object',
properties: { name: { type: 'string' } },
additionalProperties: { type: 'number' },
},
// ...
});
// before: parsing failed, because only a boolean was accepted
// now: tool.inputParameters.additionalProperties is { type: 'number' }
What to do instead
Nothing, if you only ever passed boolean values. That case is unchanged.
If your code assumed inputParameters never carries patternProperties, or that additionalProperties is always a boolean, widen that assumption. Both keywords can now appear, and additionalProperties can be a boolean or a schema object.
type: "object" to nested JSON Schema nodes that carry properties without an explicit type, so tool schemas work with strict OpenAPI 3.0 consumers like Google Gemini.1503786: Replace the loose JSON Schema property type with a recursive, type-safe definition.
1503786: Replace the loose JSON Schema property type with a recursive, type-safe definition.
JSONSchemaProperty (re-exported from @composio/core and reachable through
Tool.input_parameters / Tool.output_parameters) is now a concrete recursive
interface instead of effectively any. Runtime behavior is unchanged, but
consumer code that indexed into it without narrowing (for example
schema.properties.foo.type or schema.default.someField) may see new type
errors: properties entries are now possibly undefined and default /
enum values are unknown. Narrow with optional chaining or explicit type
guards when upgrading.
{"api_key": "..."} — the shape error messages usually carry — was sent unredacted.ssrfSafeFetch, and the response body before throwing on !response.ok in both URL-upload call sites, instead of leaving them for the garbage collector to reclaim.isNewerVersion helper.58bc93b: Refresh dependency ranges and lockfiles across the workspace.
homepage links in these packages' package.json. They pointed at github.com/ComposioHQ/composio/tree/main/..., but the default branch is next and no main branch exists, so every link 404'd on npm and in editor tooltips. They now point at tree/next/....fc17c37: Export the sensitive-file-upload denylist guard from the package root so downstream packages share one implementation: assertSafeFileUploadPath, isBlockedSensitiveFileUploadPath, and BUILTIN_FILE_UPLOAD_PATH_DENY_SEGMENTS. The guard now routes its filesystem access through the internal #platform abstraction (adding a realpathSync platform method), so it is edge/workerd-safe and the module carries no static node:* imports. Behavior on Node/Bun is unchanged.
20a4711: triggers.create now resolves the connection from user_id on the backend instead of client-side.
connectedAccounts.list() call. When connectedAccountId is omitted, the backend resolves the first active connection for the user and the trigger's toolkit (ordered by most recently created), matching tool execution.create no longer throws ComposioConnectedAccountNotFoundError for a missing or invalid connection. That case now surfaces as the backend error from the upsert call. ComposioTriggerTypeNotFoundError (invalid slug) and ValidationError (including empty userId) are still thrown client-side.user_id on upsert (ComposioHQ/platform#10932). Self-hosted deployments must be on a version that includes it.7125576: Normalize duplicate JSON Schema required entries before provider tool schemas are emitted.
58bc93b: Refresh dependency ranges and lockfiles across the workspace.
4c3a321: Disable client retries on tools.execute and tools.proxyExecute. These are non-idempotent writes, so a silent retry after a read timeout could duplicate the side effect (e.g. send the same email more than once). Both now route through a sibling client built with maxRetries: 0; reads keep the default retry behaviour.
b07fcad: Add an eve provider: EveProvider makes session.tools() return eve-native defineTools, defineComposioTools is the replay-safe step.started resolver, and (ctx, next) hooks can rewrite, deny, or transform Tool Router meta-tool calls.
Preserve successful local-tool results when the remote half of a mixed COMPOSIO_MULTI_EXECUTE_TOOL batch fails at the transport layer, so callers can see which side effects already completed before retrying.
fa933a6: Fix the homepage links in these packages' package.json. They pointed at github.com/ComposioHQ/composio/tree/main/..., but the default branch is next and no main branch exists, so every link 404'd on npm and in editor tooltips. They now point at tree/next/....
2ef40ce: Treat local file paths that begin with http as paths instead of URLs, ensuring that upload allowlist and sensitive-file denylist checks still run.
e78ed31: Execute every parallel tool call in OpenAIProvider.handleToolCalls. It previously only ran the first tool call in each assistant message, so parallel tool calls (on by default) dropped the rest and left their tool_call_ids unanswered, failing the next request.
The calls are run sequentially, in the order the model returned them — here "parallel" means the model issued several calls in one turn, not that they execute concurrently — so each tool_call_id is answered exactly once and the tool messages come back in a deterministic order.
Only the first choice is handled. Tool results are fed back into a single assistant turn, so with n > 1 iterating over every choice would run each tool call once per choice and orphan the tool_call_ids from the alternative completions.
a0f37a7: Close two secret/SSRF exposure surfaces in the TypeScript SDK:
composio.files.upload(url) and automatic file upload during tool execution previously did a raw fetch() on user-supplied URLs with no guard. They now resolve the host and refuse private, loopback, link-local (incl. the 169.254.169.254 cloud-metadata endpoint), CGNAT, and reserved addresses, reject non-http(s) schemes, and follow redirects manually so each hop is re-validated (blocking a public URL that redirects into internal space). Blocked requests throw ComposioBlockedInternalUrlError. Node-only; behaviour for public URLs is unchanged.error.message / error.stack verbatim. They are now passed through a redactor that strips URL query strings, Authorization bearer/basic credentials, and secret-like key=value pairs (API keys, tokens, client secrets, passwords) before transport.820abb9: Resolve toolkit version pins case-insensitively. Version maps are keyed by normalized (lowercase) slugs, but getToolkitVersion previously looked them up with the raw slug, so a pin configured under a different casing (e.g. { GitHub: '20250101_00' } or COMPOSIO_TOOLKIT_VERSION_GITHUB) could silently fall back to 'latest'. Normalization is now centralized in a single normalizeToolkitSlug helper used symmetrically on both the write (map-building) and read (lookup) paths, so the two sides can no longer drift. This mirrors the equivalent fix in the Python SDK.
Updated dependencies [58bc93b]
Updated dependencies [fa933a6]
605a726: Add Tool Router session deletion APIs.
d17a268: Add the first-class composio.sessions.create() API while keeping composio.create() as an alias, expose the experimental shared-connection ACL
d17a268: Add the first-class composio.sessions.create() API while keeping composio.create() as an alias, expose the experimental shared-connection ACL patch helper as connectedAccounts.updateAcl() while keeping experimental.updateAcl() as an alias, and include SDK docs/source in the published package.
MCP is now opt-in. Sessions return native tools by default; the hosted MCP endpoint is only surfaced on the type when you create the session with { mcp: true }. The default create() / use() now return SessionWithoutMcp (the runtime object is unchanged — session.mcp still exists at runtime — but it is no longer in the type).
Migration: read session.mcp only after creating with { mcp: true }.
d17a268: Surface the resolved workbench config on Tool Router sessions.
Session.workbench is now populated from the API response (on create/retrieve/attach/update). It exposes the resolved workbench config, e.g. session.workbench?.enable (defaults to true server-side).This lets callers create a session with the remote workbench disabled (workbench: { enable: false }) and detect that state — the foundation for running code in a sandbox you own via the experimental @composio/experimental/workbench helpers.
sandbox for session code-execution configuration while continuing to accept the existing workbench alias.triggers.parse() to parse and optionally verify incoming webhook requests.triggers.setWebhookSubscription() to create or update the project webhook subscription from the TypeScript SDK.[0.13.0] - 2026-05-07
Highlights
Notes
adf6b02: Show the model each tool's JSON Schema as is. The provider now passes the schema to the AI SDK with jsonSchema(), so keywords a Zod schema cannot carry, such as format: "binary", contentEncoding, contentMediaType, title, default, and examples, reach the model. Internal $refs are still inlined first. Tool-call arguments are validated with the same Zod schema as before, so the values a tool accepts and rejects are unchanged.
In strict mode the model now sees the output of the strict rewrite itself rather than a Zod rendering of it. Zod adds a pattern next to formats such as email, and strict structured outputs reject the one it adds for email, so a strict request with an email parameter would have failed once Zod forwarded more of the schema.
tool.inputSchema is now an AI SDK Schema instead of a Zod schema. Code that called inputSchema.safeParse() directly can validate with asSchema(tool.inputSchema).validate(value) from ai.
adf6b02: Build tool input schemas with the Zod v4 builder from @composio/json-schema-to-zod/v4, so format, contentEncoding, contentMediaType, and type: "integer" survive the SDK's conversion to the JSON Schema the model sees. Before, a field such as { type: "string", format: "binary" } reached the model as { type: "string" }. The values a tool accepts and rejects are unchanged.
The zod peer dependency is now ^4.1.13 (was ^4.0.0): the v4 builder needs the metadata registry zod shares across copies from 4.1.13 on, and throws at load time on an older zod. Upgrade zod to 4.1.13 or newer before upgrading this package.
executeToolCall and the OpenAI Responses provider's handleResponse to execute through a supplied Tool Router session, matching the other provider helpers. Session meta-tools now keep their session context through these helpers. Existing user-ID calls keep using direct execution unchanged, and the Cloudflare options argument is now optional. Passing a session requires @composio/core 0.17.0 or later. Custom provider subclasses overriding these methods may require updates because they now accept session targets.025a657: Drop CommonJS entrypoints and publish the TypeScript SDK packages as ESM-only packages. This is a breaking change within the existing 0.x rel…
a0bef5d: Bump @composio/client to 0.1.0-alpha.74.
dfd7a08: Add per-request cancellation to public SDK methods via a new ComposioRequestOptions ({ signal?: AbortSignal }) trailing argument, plus a typed ComposioRequestCancelledError for detecting caller-initiated aborts.
Without this, a slow tools.get or tools.execute had no way to be cancelled — a 100s search would block the calling agent indefinitely. The new shape:
try {
const tools = await composio.tools.get(
'user_1',
{ search: 'send email', limit: 50 },
{ signal: AbortSignal.timeout(5_000) }
);
} catch (err) {
if (err instanceof ComposioRequestCancelledError) {
return;
}
throw err;
}
The signal is forwarded to the underlying @composio/client fetch. Any abort error (APIUserAbortError, AbortError, or DOMException(name='AbortError')) coming back is normalized to ComposioRequestCancelledError so callers can instanceof-detect cancellation without unwrapping nested causes. Catch-and-wrap paths in tools.execute / tools.getRawComposioToolBySlug / toolkits.get re-throw the cancellation error rather than remapping it to ComposioToolExecutionError / ComposioToolNotFoundError / ComposioToolkitFetchError.
Wired through on:
get, getRawComposioTools, getRawComposioToolBySlug, getRawToolRouterSessionTools, execute, executeSessionTool, getToolsEnum, getInput, proxyExecuteget, listCategorieslist, create, get, update, delete, updateStatus, enable, disablelist, get, delete, refresh, updateStatus, enable, disable, updatelistActive, create, update, delete, enable, disable, listTypes, getType, listEnumcreate, list, get, delete, update, generatecomposio.create / composio.use, composio.toolRouter.create / .use) — long-running session-creation pathsauthorize, toolkits, search, execute, proxyExecute, updateNative tool execution is cancelled by the SDK (the underlying fetch is aborted). Custom tools are different — the SDK can't preempt user-supplied JavaScript. Two affordances are added so callers get sensible behavior anyway:
signal.aborted is true before the user's execute runs, the SDK throws ComposioRequestCancelledError and never invokes user code.AbortSignal is exposed via SessionContext.signal for Tool Router custom tools. Long-running implementations can wire ctx.signal into their own fetch (or any abortable IO) to abort mid-execution; the resulting AbortError is normalized to ComposioRequestCancelledError by the SDK.import { experimental_createTool } from '@composio/core';
const longRunningFetch = experimental_createTool('LONG_RUNNING_FETCH', {
name: 'Long-running fetch',
description: 'Fetches a URL with cooperative cancellation',
inputParams: z.object({ url: z.string() }),
execute: async (input, ctx) => {
// Pass ctx.signal into fetch so a session.execute(...) abort cancels
// the in-flight HTTP request mid-flight.
const resp = await fetch(input.url, { signal: ctx.signal });
return { result: await resp.json() };
},
});
025a657: Drop CommonJS entrypoints and publish the TypeScript SDK packages as ESM-only packages. This is a breaking change within the existing 0.x release line: consumers must use Node.js 22.22.3 or newer. CommonJS callers can only rely on Node's native require(esm) interop, and the SDK no longer ships custom CommonJS compatibility machinery or .cjs artifacts.
4b76dbf: Remove the deprecated uuid field from the auth config retrieve/list response type.
The platform has removed the deprecated V1/V2 UUID-mirror field from V3 API responses (it was a mirror of the canonical nanoid id). The SDK no longer reads or re-exposes uuid on AuthConfigRetrieveResponse (and therefore on the items of AuthConfigListResponse).
This is technically a breaking change to the SDK response type: consumers should use id instead of uuid. The expectedInputFields field is unaffected — it remains a top-level field on the API response.
552859a: Expose search and showDisabled filters on authConfigs.list().
23f9053: Replace chalk with picocolors for colored error and log output. The two render identically, but picocolors is a fraction of the size (~0.8 kB gzipped vs chalk's much larger footprint), shrinking the bundled package.
507318d: Add a provider-agnostic JSON-schema property-key sanitizer: sanitizeSchemaPropertyKeys(schema, policy), restoreOriginalKeys(value, mapping), mappingHasRenames(mapping), and the KeyMapping / KeySanitizationPolicy types.
Some providers constrain the characters and length of tool input_schema property keys and reject the whole request on a single violation. This utility rewrites offending keys to conforming aliases (recursing through properties, array items/prefixItems, the composition keywords allOf/anyOf/oneOf and not/if/then/else, plus additionalProperties/patternProperties/$defs/contains) and records a schema-shaped reverse mapping so the original parameter names can be restored before execution. The constraint is injected as a KeySanitizationPolicy, so the traversal, collision handling, prototype safety, and depth cap stay provider-agnostic. The @composio/anthropic provider now consumes it.
6a4cb54: Preserve root $defs / definitions blocks on tool parameter schemas and dereference them in the Node file modifier, so auto file upload/download detection works when file_uploadable or file_downloadable is hidden behind an internal $ref.
cbbad15: Improve Zod compatibility at the SDK schema boundary. Custom tools now convert both zod/v3 and Zod v4 schemas to JSON Schema correctly instead of degrading Zod v4 object schemas to empty schemas. @composio/core now exposes jsonSchemaToZodShape via @composio/core/utils/json-schema, and the Claude Agent SDK provider uses that core subpath instead of converting to a full Zod object and casting .shape out of it.
Updated dependencies [025a657]
[0.12.0] - 2026-04-28
Changed
Migration
composio = Composio(api_key=...) # auto upload/download was on by default
composio = Composio(
api_key=...,
dangerously_allow_auto_upload_download_files=True,
file_upload_dirs=["/path/to/allowed/dir"], # optional; defaults to
~/.composio/temp
file_download_dir="/path/to/downloads", # optional
)
Notes
{ error } results without changing successful payloads. Custom provider subclasses overriding executeToolCall or handleToolCalls may require updates because these methods now accept session targets.executeToolCall and the OpenAI Responses provider's handleResponse to execute through a supplied Tool Router session, matching the other provider helpers. Session meta-tools now keep their session context through these helpers. Existing user-ID calls keep using direct execution unchanged, and the Cloudflare options argument is now optional. Passing a session requires @composio/core 0.17.0 or later. Custom provider subclasses overriding these methods may require updates because they now accept session targets.9447932: Dereference internal $ref/$defs in tool input schemas before provider translation, so properties reachable only through a reference keep their types and validation instead of degrading to untyped (z.any) or being emitted as a dangling reference.
This changes the JSON Schema these providers emit for $ref-using tools. Downstream snapshot tests on tool definitions will see diffs. Schemas the Composio API ships with a $ref but no $defs block (e.g. GMAIL_FETCH_EMAILS) degrade to a permissive object schema rather than throwing. The strict-structured-outputs path of @composio/openai-agents is unchanged — OpenAI supports $defs/$ref natively, including recursion.
Sensitive path blocking — Before auto-uploading a local file, paths are checked against a built-in denylist (segments like .ssh, .aws, etc., plus risk
.ssh, .aws, etc., plus risky filenames). Configurable via Composio(..., sensitive_file_upload_protection=..., file_upload_path_deny_segments=...).@before_file_upload modifiers — File path hooks are only via modifiers (same idea as @before_execute): decorate a function, pass it in modifiers=[...] on tools.get / tools.execute (and tool router session.tools(...)). Hooks are composed with merge_before_file_upload and run when substituting file_uploadable paths, before before_execute modifiers.before_file_upload= on Composio, get, execute, or the tool router; FileHelper no longer stores a default hook on the client—only the merged modifier hook (or None) per call.SensitiveFilePathBlockedError / FileUploadAbortedError (and related) when a path is blocked or a hook returns False.before_file_upload and glue exported from the package as needed.Version note: composio is 0.11.6 in pyproject.toml, with Python >=3.10.
@mastra/mcp peer dependency. The provider never imported it, but package managers that install peers automatically pulled in about 234 extra packages.fd59eba: Update SDK and provider dependencies to compatible releases. Accept Anthropic SDK 0.132 and OpenAI Agents 0.20 in provider peer ranges, and a
72fbd00: Fix cacheTools: true exceeding Anthropic's 4-breakpoint-per-request limit (shared with the system prompt and messages), which causes the whol
cacheTools: true exceeding Anthropic's 4-breakpoint-per-request limit (shared with the system prompt and messages), which causes the whole request to be rejected. wrapTools now places a single breakpoint on the last tool, which caches the entire tool list since a breakpoint covers everything up to and including it, instead of one on every tool. handleToolCalls no longer marks tool_result blocks, because they accumulate in the message history and would exceed the limit after a few turns.485c09d: Refresh runtime dependencies and support Anthropic SDK 0.127 in the Anthropic provider.
adf6b02: Show the model each tool's JSON Schema as is. The provider now builds the FunctionTool with the JSON Schema as its parameters and the Zod sch
FunctionTool with the JSON Schema as its parameters and the Zod schema as its validator, instead of letting LlamaIndex render the Zod schema back to JSON Schema. Keywords such as format: "binary", contentEncoding, contentMediaType, and title reach the model. Internal $refs are still inlined first, and the values a tool accepts and rejects are unchanged.@composio/anthropic also accepts @anthropic-ai/sdk 0.124 as a peer, the line it is now tested against.anyOf branches, array items, inlined $ref/$defs): every object lists all of its properties in required and sets additionalProperties: false, so tools with nested or optional parameters no longer produce schemas the API rejects with a 400. Optional parameters are no longer dropped: they stay available and are widened to accept null, the emulation of optional fields OpenAI documents, and the strict providers drop a null argument the tool's own schema does not accept before executing the tool. Tools whose schema strict mode cannot express (objects with arbitrary keys, allOf, prefixItems, unresolved $refs) are sent without strict mode with a warning naming the tool and path, instead of being narrowed. @composio/core exports the new toStrictJsonSchema() and omitNullToolArguments() utilities; removeNonRequiredProperties is unchanged for other callers. The Python OpenAIResponsesProvider gains a matching opt-in strict=True constructor flag that also emits strict: true on the wrapped tool.One column per month.