Minor Changes

• 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.

Patch Changes

• a2f6b96: Add 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.
• c625edc: Reuse fetched tool schemas when provider-wrapped tools execute to avoid a redundant retrieval request.
• Updated dependencies [5e57815]
  • @composio/json-schema-to-zod@0.3.0

Minor Changes

• 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.

Patch Changes

• 2ac6ad3: Bound the background npm version check so registry outages cannot leave the request pending indefinitely.
• 5105612: Match sensitive upload path segments using the target filesystem's actual case sensitivity so case-insensitive mounts cannot bypass the denylist without over-blocking distinct paths on case-sensitive mounts.
• 051c8c5: Redact secrets that appear inside JSON payloads in telemetry error text. The key/value rule required the separator to follow the key name directly, so a serialized body such as {"api_key": "..."} — the shape error messages usually carry — was sent unredacted.
• e5c9ada: Refresh the OpenAI runtime dependency to version 7.
• ecd0861: Release unread response bodies on the paths the SDK knowingly abandons: cancel every intermediate redirect body in 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.
• 2a6a051: Remove the unused internal isNewerVersion helper.
• Updated dependencies [1503786]
  • @composio/json-schema-to-zod@0.2.2

Minor Changes

• 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.

  • The SDK no longer makes an extra 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.
  • Behavior change: 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.
  • Requires a backend that resolves the trigger connection from user_id on upsert (ComposioHQ/platform#10932). Self-hosted deployments must be on a version that includes it.

Patch Changes

• 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:

  • SSRF guard on URL file inputs. 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.
  • Telemetry redaction. Error telemetry previously shipped 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]

  • @composio/json-schema-to-zod@0.2.1

[0.13.0] - 2026-05-07

Highlights

• Python SDK package train bumped to 0.13.0.
• Added Tool Router v3.1 support: preload, SDK-local custom tool preload, attach/use flow refinements, and session.update().
• Added connected account updates: REVOKED status, connected account string/list coercion, and the allow_multiple guard.
• Added workbench sandbox compute tier support.
• Security fixes for CustomTool credential isolation and file download path traversal.

Notes

• Provider packages were bumped alongside composio to keep Python package versions aligned.
• PyPI: https://pypi.org/project/composio/0.13.0/

Minor Changes

• 760f8d0: Allow OpenAI and Anthropic provider tool-call helpers to execute through a supplied Tool Router session. Session meta-tools now retain their session context while provider argument normalization remains intact; existing user-ID calls continue to use direct execution. Anthropic helper failures now preserve their error text in { error } results without changing successful payloads. Custom provider subclasses overriding executeToolCall or handleToolCalls may require updates because these methods now accept session targets.

Minor Changes

• 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:

  • Tools: get, getRawComposioTools, getRawComposioToolBySlug, getRawToolRouterSessionTools, execute, executeSessionTool, getToolsEnum, getInput, proxyExecute
  • Toolkits: get, listCategories
  • AuthConfigs: list, create, get, update, delete, updateStatus, enable, disable
  • ConnectedAccounts: list, get, delete, refresh, updateStatus, enable, disable, update
  • Triggers: listActive, create, update, delete, enable, disable, listTypes, getType, listEnum
  • MCP: create, list, get, delete, update, generate
  • ToolRouter (composio.create / composio.use, composio.toolRouter.create / .use) — long-running session-creation paths
  • ToolRouterSession: authorize, toolkits, search, execute, proxyExecute, update

  Custom-tool cooperative cancellation

  Native 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:

  1. Pre-execute signal check: if signal.aborted is true before the user's execute runs, the SDK throws ComposioRequestCancelledError and never invokes user code.
  2. Cooperative signal forwarding: the same 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.

Patch Changes

• 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]

  • @composio/json-schema-to-zod@0.2.0

This project publishes no release notes. Between v0.11.0 and v0.11.1 there were 242 commits, 176 of them substantive:

• feat(py): enable public URLs
• fix: preserve original filename when appending extension from mimetype
• fix: remove unreachable filename == '/' check
• fix: make MIME type lookup case-insensitive and decode URL-encoded filenames
• feat(ts/cli): add support for COMPOSIO_TOOLKIT_VERSION_$TOOLKIT override
• feat(ts/cli): validate invalid toolkit version overrides
• update(docs): update troubleshooting guide
• cli: remove unused constant in validate toolkit versions
• feat(py): enable public URLs
• fix: remove unreachable filename == '/' check
• fix: make MIME type lookup case-insensitive and decode URL-encoded filenames
• fix(py): truncate long filenames from public URL uploads
• feat(ts/e2e): simplify resolution of nodeVersion: ['current']
• docs: auto-generate TypeScript SDK reference
• feat(ts/e2e/node): standardize resolution of nodeVersion: ['current'] to echo $(.nvmrc) (#2514)
• fix(ts/core): webhook subscription with v1, v2, v3 response schemas
• feat(py): add tests for cross-sdk webhook handling parity between Python and TypeScriptSDK
• feat(ts): add trigger subscription example
• feat(ts/core): simplify code
• fix(ts/core): keep error informatino

…and 156 more.

Minor Changes

• e5c9ada: Add support for OpenAI versions 6 and 7.

Minor Changes

• 9ffc696: Add AI SDK 7 support to @composio/vercel. The ai peer dependency range is now ^6.0.0 || ^7.0.0 (AI SDK 5 is no longer supported; both v6 and v7 are covered by e2e compatibility tests).

Minor Changes

• a94715f: Forward userId when creating trigger instances so trigger 2FA flows can verify connected account ownership.
• 44e5458: Remove the legacy composio.tools.createCustomTool(...) in-memory registry API. Use Tool Router custom tools via experimental_createTool, experimental_createToolkit, and composio.create(..., { experimental: { customTools, customToolkits } }) instead.

Patch Changes

• 22a9171: Defer telemetry batch and error sends so instrumentation does not wait for telemetry network requests before returning SDK results or rethrowing SDK errors.

• 93b67e8: Fix automatic file upload/download substitution for file schemas that accept either a single file or a list of files.

  The file modifier now selects composed-schema branches by runtime value shape, so anyOf(file, array<file>) uploads or downloads each file when the tool receives a list while preserving existing single-file behavior.

• b69cef1: Tolerate dangling $ref pointers in tool schemas the Composio API ships without a matching $defs entry. Some toolkits (e.g. GMAIL_FETCH_EMAILS) emit outputParameters with "$ref": "#/$defs/FetchEmailsResponse" while never declaring a top-level $defs block. After the strict resolver shipped with the previous Mastra fix, this caused composio.tools.get(...) to throw JsonSchemaRefResolutionError upfront, making every Gmail / Slack / Google-Calendar tool unusable through MastraProvider. The SDK now degrades the unresolvable branch to a permissive object schema and surfaces a single observability warning per (toolSlug, ref) pair instead of crashing.

  • dereferenceJsonSchema accepts a new optional second argument { onUnresolved?: 'throw' | 'sentinel'; onReplace?: (ref, reason) => void }. Default behavior is unchanged ('throw') — first-party / custom-tool schemas with a typo'd $ref still surface as a hard error. Pass 'sentinel' to replace unresolved branches with the cycle-break sentinel ({ type: 'object', additionalProperties: true }) that the resolver already uses for $ref cycles. The replaced sentinel carries a default description hint so LLMs consuming the wrapped tool's schema get an in-band signal that the branch is opaque; a caller-provided description sibling overrides the default (Draft 2020-12 sibling-keyword merge). Safety caps (MAX_REF_CHAIN_DEPTH, MAX_NODE_DEPTH) keep throwing in both modes. New UnresolvedRefStrategy, UnresolvedRefReason, and DereferenceJsonSchemaOptions type exports.
  • MastraProvider.wrapTool opts both inputParameters and outputParameters into 'sentinel' mode and emits one logger.warn per (toolSlug, ref) pair via the provider-scoped dedup Set. User-controlled segments in the warning (tool.slug, toolkit.slug, ref) are JSON.stringifyd to neutralize embedded newlines / ANSI escapes / control bytes that could otherwise forge log lines (CWE-117). A matching one-shot telemetry event (composio.mastra.wrapTool.danglingRef) fires next to the warn so the Composio team has aggregate visibility into which toolkits are affected; the event respects COMPOSIO_DISABLE_TELEMETRY=true.
  • The telemetry instance from @composio/core is now publicly re-exported alongside logger, so providers can emit aggregate signals without reaching into the package's internals.
  • Resolvable $defs / definitions continue to be inlined exactly as before — no regression in the type-info preservation contract introduced by the previous Mastra fix.

• 1ba66ca: Fix tools.execute (and tools.get / tools.list) failing with a ZodError for every tool from an MCP-backed toolkit (e.g. granola_mcp, apify_mcp, tavily_mcp).

  MCP toolkits don't declare an output schema, and the Composio API serializes that as output_parameters: {}. The SDK's ParametersSchema required { type: 'object', properties: {...} }, so transformToolCases rejected the response and getRawComposioToolBySlug — called by execute and the list path — threw.

  The SDK now normalizes empty ({}), null, and missing input_parameters / output_parameters payloads to undefined before validation. outputParameters was already declared .optional() in the public Tool type, so this preserves the contract: "undefined means no declared schema." Tools that do declare a schema continue to be validated strictly.

  No public API change; no toolkit allow-list.

• ce4b213: fix(providers): normalize string tool-call arguments across all providers

  Models occasionally emit tool-call arguments as a JSON string instead of an object (most visibly with COMPOSIO_MULTI_EXECUTE_TOOL on the Vercel AI SDK), which broke downstream validation with errors like tool_use.input: Input should be a valid dictionary.

  @composio/core now exposes a single normalizeToolArguments helper, and every provider routes model-supplied arguments through it. Object payloads pass through unchanged, JSON strings are parsed, empty/null payloads become {}, and anything that cannot resolve to an object throws a typed ComposioInvalidToolArgumentsError instead of a raw SyntaxError or a silently forwarded malformed string. This replaces the inconsistent per-provider guards that previously existed only in vercel, cloudflare and openai-agents.

This project publishes no release notes. Between v0.10.6 and v0.11.0 there were 250 commits, 208 of them substantive:

• fix(docs): Convert Fern components to Fumadocs components in changelog
• docs: Add MCP API key toggle image
• fix(docs): Wrap Accordion in Accordions for Fumadocs compatibility
• fix(docs): Remove duplicate H1 titles from changelog files
• fix(docs): Add @noErrors to TypeScript snippets in changelog
• docs: Sync January 2026 changelog from fern to fumadocs (#2456)
• docs: Move Authentication to collapsible folder under Advanced section
• docs: Rename section to 'Direct Tools'
• docs: Move Tools section to collapsible folder under Direct Tools
• docs: Rename section to 'Direct Tool Guides'
• chore: fix conflicts
• chore: get rid of bad commit
• fix(py): fix common checks
• chore: fix conflicts
• fix(py): fix SALESFORCE_CREATE_LEAD Type Error with custom_fields (#2426)
• test(ts/e2e): temporarily skipping failing cloudflare test
• feat(ts/core): refactor usage of node:buffer into Uint8Array, enforcing it via eslint (#2438)
• test(ts/e2e): don't skip test that now succeeds
• test(ts/e2e): fix potential mcp connection leak
• feat(ts/e2e-tests): more Cloudflare Workers e2e tests (#2439)

…and 188 more.

Patch Changes

• a2f6b96: Add missing object types to nested Google GenAI tool schemas so Gemini accepts function declarations with property maps. This release requires @composio/core >=0.16.0 <1.0.0 for the shared schema normalizer.

This project publishes no release notes. Between v0.10.1 and v0.10.2 there were 133 commits, 114 of them substantive:

• navigation high level changes
• toolrouter
• restructureing
• overview
• overview update
• restryct
• fixes in structure
• fix quickstart
• quickstart p0
• tiny fix
• user and session
• fix session link
• authentication concept doc
• in chat auth
• manual auth fixes
• icon fix
• white labeling(to edit)
• fix custom auth stuff
• overview fix
• quickstart changes

…and 94 more.

Patch Changes

• 7125576: Normalize duplicate JSON Schema required entries before provider tool schemas are emitted.
• 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/....

Patch Changes

• 7125576: Normalize duplicate JSON Schema required entries before provider tool schemas are emitted.
• 58bc93b: Refresh dependency ranges and lockfiles across the workspace.
• 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/....

Patch Changes

• cddd66c: Update the supported @mastra/core peer dependency range.

This project publishes no release notes. Between v0.10.0 and v0.10.1 there were 3 commits, 3 of them substantive:

• feat(cli): add "composio generate --toolkits [toolkits]" support, for both ts and py
• feat(cli): add composio generate --toolkits [toolkits] support, for both ts and py (#2252)
• Fix missing workbench options in session config (#2272)

Minor Changes

• 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.

Patch Changes

• aaabf5e: Relax the Mastra provider output schema so real third-party API responses are no longer rejected by Mastra's output validation (which dropped the data and substituted an error). Before compilation the output schema is made lenient: every typed node becomes nullable, objects allow extra keys (additionalProperties: true), enum/const are widened to also admit null, and required is dropped (APIs omit unset fields rather than returning null for them). All of these only widen what validates, so previously-valid output is unaffected.

Minor Changes

• 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.

Patch Changes

• 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.

Minor Changes

• 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.

Patch Changes

• 507318d: Harden the Anthropic tool property-key sanitizer:

  • Broader schema coverage. Illegal keys are now sanitized wherever they appear in a tool schema — under the composition keywords (allOf/anyOf/oneOf, not/if/then/else), prefixItems tuples, additionalProperties/patternProperties, and $defs/definitions — not just top-level properties and array items. Previously a single illegal key under one of these would still 400 the entire request. Renames inside composition keywords are restored correctly (they fold into the value level they share).
  • $ref keys restored. wrapTool now dereferences internal $ref/$defs (leniently — a dangling ref degrades to a permissive schema instead of throwing) before sanitizing, so keys reachable only through a reference are both made compliant and restored. Only genuinely dynamic positions (additionalProperties, patternProperties, contains) remain rewrite-only.
  • Shared core implementation. The traversal/restoration mechanism now lives in @composio/core (sanitizeSchemaPropertyKeys / restoreOriginalKeys); this provider supplies only the Anthropic key constraint as a policy, reusing core's prototype-pollution guard and depth cap.
  • Prototype-safe key restoration. Reverse-mapping lookups and the rebuilt argument object are now prototype-free, so a tool call whose arguments use a key matching an Object.prototype member (__proto__, constructor, toString, hasOwnProperty, …) no longer throws or silently corrupts the payload sent to the backend. Object.prototype is never mutated.
  • Depth cap. Schema sanitization and key restoration now bound recursion (matching core's JSON-schema walker) so a pathologically deep schema or argument object fails with a clear error instead of overflowing the stack.
  • Empty / all-illegal keys. A property key that is empty (or made entirely of stripped characters) now becomes a deterministic non-empty alias instead of an empty string, which would itself have violated Anthropic's {1,64} length bound.
  • Collision loop. Replaced a latent non-terminating fixed point in the alias collision resolver with a counter that always makes progress.
  • Observability. The provider now emits debug logs when it rewrites a tool's schema keys and when it restores them at execution time, and the wrap-then-execute (same provider instance) contract for key restoration is documented.

• c90ae95: Sanitize tool input_schema property keys that violate Anthropic's ^[a-zA-Z0-9_.-]{1,64}$ constraint before sending tools to the Messages API, then restore the original names when the tool is executed.

  A single non-conforming key previously made Anthropic reject the entire tools array with HTTP 400, taking down every other tool in the same request. This commonly happened with OneDrive's Microsoft Graph OData parameters ($top, $filter, @microsoft.graph.conflictBehavior) and with over-long flattened keys from tools such as Zoom. Offending keys are now rewritten to conforming aliases ($ → dollar_, @ → at_, any other illegal character → _, keys longer than 64 characters truncated with a deterministic suffix), recursing through nested object properties and array items schemas. The original parameter names are restored before the call reaches the Composio backend, so the model sees dollar_top while the backend still receives $top. Schemas whose keys already conform are left unchanged.

Minor Changes

• 42ebff3: feat(connected-accounts): namespace SHARED-connection surface under experimental

  Aligns the TypeScript SDK with the experimental wire shape used by Shared Connections. The flat accountType / aclConfigForShared options on connectedAccounts.link() and session.authorize() have moved under a single experimental block, and connectedAccounts.updateAcl() has moved off the class onto a top-level experimental_updateAcl(composio, id, opts) export — same precedent as experimental_createTool / experimental_createToolkit.

  The experimental namespace is the signal that the shape may change in future releases. Pinning a SHARED connection in a session config (connectedAccounts: { gmail: [...] }) and direct execute by connectedAccountId are unchanged — only the connection-create / patch / authorize surfaces are namespaced.

  Also surfaces the accountType filter on connectedAccounts.list() so SHARED connections can be listed without dropping to the raw client. The wire keeps this as a flat query param, so the SDK keeps it flat too.

  @composio/client bumped from 0.1.0-alpha.71 → 0.1.0-alpha.72 so the generated typed client carries the Experimental namespaces for link.create, toolRouter.session.link, and connectedAccounts.patch.

  Caller migration:

  // before
  await composio.connectedAccounts.link('user_id', 'auth_config_id', {
    accountType: 'SHARED',
    aclConfigForShared: { allowAllUsers: true },
  });
  await composio.connectedAccounts.updateAcl('ca_abc', { allowAllUsers: true });
  await session.authorize('github', {
    accountType: 'SHARED',
    aclConfigForShared: { allowAllUsers: true },
  });
  
  // after
  await composio.connectedAccounts.link('user_id', 'auth_config_id', {
    experimental: {
      accountType: 'SHARED',
      aclConfigForShared: { allowAllUsers: true },
    },
  });
  await experimental_updateAcl(composio, 'ca_abc', { allowAllUsers: true });
  await session.authorize('github', {
    experimental: {
      accountType: 'SHARED',
      aclConfigForShared: { allowAllUsers: true },
    },
  });
  
  // new — list SHARED connections
  const shared = await composio.connectedAccounts.list({
    accountType: 'SHARED',
    userIds: ['user_creator'],
  });
  

This project publishes no release notes. Between v0.9.5-rc.1 and v0.10.0 there were 76 commits, 65 of them substantive:

• chore(ts): add CommonJS example in ts/examples/cjs
• feat(ts): move @composio/core from tsup to tsdown
• fix: "pnpm audit --prod"
• Release: update version (alpha) (#2225)
• Fix tool router types from latest API changes (#2227)
• Fix docstrings and examples for toolrouter (#2230)
• Release: update version (alpha) (#2229)
• chore: merge next
• fix: pnpm audit --prod
• fix(py): typo in auth_scheme.status
• feat(py): port langchain to v1
• mask connected account tokens
• toggle off
• Docs: Mask connected accounts (#2237)
• docs: hide x-session-access-key header from API docs
• docs: add 'in: header' to x-session-access-key parameter override
• chore: add changelog for deleted default credentials
• fix: grammar mistake
• fix
• feat: add changelog for response schema typing

…and 45 more.

Patch Changes

• b69cef1: Tolerate dangling $ref pointers in tool schemas the Composio API ships without a matching $defs entry. Some toolkits (e.g. GMAIL_FETCH_EMAILS) emit outputParameters with "$ref": "#/$defs/FetchEmailsResponse" while never declaring a top-level $defs block. After the strict resolver shipped with the previous Mastra fix, this caused composio.tools.get(...) to throw JsonSchemaRefResolutionError upfront, making every Gmail / Slack / Google-Calendar tool unusable through MastraProvider. The SDK now degrades the unresolvable branch to a permissive object schema and surfaces a single observability warning per (toolSlug, ref) pair instead of crashing.

  • dereferenceJsonSchema accepts a new optional second argument { onUnresolved?: 'throw' | 'sentinel'; onReplace?: (ref, reason) => void }. Default behavior is unchanged ('throw') — first-party / custom-tool schemas with a typo'd $ref still surface as a hard error. Pass 'sentinel' to replace unresolved branches with the cycle-break sentinel ({ type: 'object', additionalProperties: true }) that the resolver already uses for $ref cycles. The replaced sentinel carries a default description hint so LLMs consuming the wrapped tool's schema get an in-band signal that the branch is opaque; a caller-provided description sibling overrides the default (Draft 2020-12 sibling-keyword merge). Safety caps (MAX_REF_CHAIN_DEPTH, MAX_NODE_DEPTH) keep throwing in both modes. New UnresolvedRefStrategy, UnresolvedRefReason, and DereferenceJsonSchemaOptions type exports.
  • MastraProvider.wrapTool opts both inputParameters and outputParameters into 'sentinel' mode and emits one logger.warn per (toolSlug, ref) pair via the provider-scoped dedup Set. User-controlled segments in the warning (tool.slug, toolkit.slug, ref) are JSON.stringifyd to neutralize embedded newlines / ANSI escapes / control bytes that could otherwise forge log lines (CWE-117). A matching one-shot telemetry event (composio.mastra.wrapTool.danglingRef) fires next to the warn so the Composio team has aggregate visibility into which toolkits are affected; the event respects COMPOSIO_DISABLE_TELEMETRY=true.
  • The telemetry instance from @composio/core is now publicly re-exported alongside logger, so providers can emit aggregate signals without reaching into the package's internals.
  • Resolvable $defs / definitions continue to be inlined exactly as before — no regression in the type-info preservation contract introduced by the previous Mastra fix.

• ce4b213: fix(providers): normalize string tool-call arguments across all providers

  Models occasionally emit tool-call arguments as a JSON string instead of an object (most visibly with COMPOSIO_MULTI_EXECUTE_TOOL on the Vercel AI SDK), which broke downstream validation with errors like tool_use.input: Input should be a valid dictionary.

  @composio/core now exposes a single normalizeToolArguments helper, and every provider routes model-supplied arguments through it. Object payloads pass through unchanged, JSON strings are parsed, empty/null payloads become {}, and anything that cannot resolve to an object throws a typed ComposioInvalidToolArgumentsError instead of a raw SyntaxError or a silently forwarded malformed string. This replaces the inconsistent per-provider guards that previously existed only in vercel, cloudflare and openai-agents.

Patch Changes

• 84a3a07: Add accountType and per-user ACL support for SHARED connected accounts.

  • accountType on create: composio.connectedAccounts.link(userId, authConfigId, { accountType: 'SHARED' }) creates a SHARED connection. Default remains PRIVATE. A SHARED connection can be used by other userIds, but only when the connection is explicitly pinned in a tool-router session's config and only when the requesting userId passes the connection's ACL.
  • accountType on retrieve: get() and list() responses now include accountType ('PRIVATE' | 'SHARED').
  • aclConfigForShared on create + retrieve: per-user ACL block — { allowAllUsers, allowedUserIds, notAllowedUserIds }. On responses the field is undefined when the caller isn't authorised to see the ACL, so callers can distinguish "I can't see the ACL" from "ACL is the default deny-by-default state".
  • updateAcl() method (new): composio.connectedAccounts.updateAcl(nanoid, { allowAllUsers, allowedUserIds, notAllowedUserIds }) writes the ACL via PATCH. PATCH semantics — omit a field to leave it unchanged; pass an empty array to clear an allow/deny list. At least one field required. Calling on a PRIVATE connection raises ComposioAclOnlyForSharedError (400).
  • ToolRouterSession.authorize() options gain accountType + aclConfigForShared, so a SHARED connection with an ACL can be created in one call from inside a tool-router session.

  ACL resolution rule (deny wins):

  1. requesting userId ∈ notAllowedUserIds → DENY
  2. allowAllUsers === true → ALLOW
  3. requesting userId ∈ allowedUserIds → ALLOW
  4. otherwise → DENY (deny-by-default)

  Limits: each ACL list accepts up to 1000 entries; each userId is 1..256 characters. The SDK enforces these caps at the input boundary.

  New error classes:

  • ComposioSharedAccessDeniedError (403) — surfaces from direct connectedAccountId execution paths when the requesting user fails the ACL.
  • ComposioAclOnlyForSharedError (400) — ACL fields sent on a PRIVATE connection.
  • ComposioSharedConnectionNotAccessibleError (400) — tool-router session create / PATCH with a pinned SHARED connection the session user cannot use.

  No breaking changes. Existing link() callers without the new options get a PRIVATE connection exactly as today; existing get() / list() callers see new optional fields.

  The Python SDK mirror ships in a separate PR.

• c358ffa: Fix false-positive initiate() deprecation warning for custom auth configs (SEC-339 follow-up).

  composio.connectedAccounts.initiate() previously emitted a one-time console.warn on every redirectable-OAuth response, regardless of whether the auth config was Composio-managed (subject to the 2026-07-03 cutover) or custom (unaffected). The wording was conditional ("If this auth config is Composio-managed…") so callers using their own OAuth apps could ignore it, but the warning still printed and caused noise in logs.

  Apollo already emits the SEC-339 Deprecation / Sunset / Link rel="deprecation" headers (RFC 9745 / RFC 8594) only on the retiring branch — managed + redirectable OAuth. The SDK now reads the Deprecation header from the response (via APIPromise.withResponse()) and gates the warning on its presence. Custom auth configs and non-OAuth schemes get a clean response from the server and now stay silent in the SDK as well.

  • Behavior change: No warning is emitted for initiate() calls against custom OAuth auth configs or non-OAuth schemes (API key, bearer, basic). Managed-OAuth callers continue to get exactly one warning per process, now with revised wording that points at the response's Sunset header for the precise cutover date.
  • No public API change: initiate() returns the same ConnectionRequest shape and respects the same allowMultiple guard. ComposioLegacyConnectedAccountsEndpointRetiredError continues to surface from the 400 retired-path response.
  • Test scaffolding: new mock helper mockApiPromiseWithHeaders() in connectedAccounts.test.ts wraps a value as an APIPromise-shaped thenable so the new tests can simulate apollo's header behavior. Pre-existing initiate tests using mockResolvedValueOnce continue to pass via the SDK's defensive fallback when withResponse is absent on the mock.

  Python SDK gets the matching change in the same release train.

Minor Changes

• Bumped to align with @composio/core@0.9.0 for the Tool Router release train. No public-API change in this provider package.

Patch Changes

• cc673b6: Resolve internal JSON Schema $ref pointers (#/$defs/... and #/definitions/...) before handing tool parameters to @mastra/schema-compat. Composio tools whose schemas use $defs/definitions — legal under Draft 7 and 2020-12 — no longer trigger the AJV can't resolve reference … error, and the resolved type information from $defs survives the JSON-Schema → Zod → JSON-Schema round-trip instead of being silently degraded to a permissive anyOf.

  • New dereferenceJsonSchema helper exported from @composio/core performs the inline expansion. It deep-clones the input, walks every applicator reflectively (so future JSON Schema keywords are covered), shallow-merges sibling keywords next to $ref per Draft 2020-12 semantics, breaks cycles with { type: 'object', additionalProperties: true } (matching the upstream guidance in mastra-ai/mastra#15341), and strips $defs/definitions once everything reachable is inlined. External (http:///https://) $ref pointers are left untouched.
  • @composio/mastra calls the helper inside wrapTool for both inputParameters and outputParameters.
  • @mastra/schema-compat dependency floor raised to ^1.2.9 so users automatically receive PR #15400's recursive-$ref handling.

• Updated dependencies [c9b6525]

• Updated dependencies [cc673b6]

• Updated dependencies [9f14971]

• Updated dependencies [81f8027]

• Updated dependencies [711a703]

• Updated dependencies [bccd32b]

• Updated dependencies [bccd32b]

• Updated dependencies [07c9bab]

• Updated dependencies [3ece424]

  • @composio/core@0.9.0

Minor Changes

• 9f14971: Add migration tooling for the link auth migration: callers using composio.connectedAccounts.initiate() for Composio-managed auth configs on redirectable OAuth schemes (OAuth1, OAuth2, DCR_OAUTH) now get a typed error and a one-time deprecation warning ahead of the 2026-07-03 all-orgs cutover.

  • Added: ComposioLegacyConnectedAccountsEndpointRetiredError, exported from @composio/core. Thrown by initiate() when the underlying POST /api/v3/connected_accounts returns a 400 indicating the retiring path. Carries the migration message and a possibleFixes block pointing at link() and the migration guide.
  • Added: one-time-per-process console.warn from initiate() when the response indicates a redirectable OAuth scheme. Wording is conditional ("If this auth config is Composio-managed…") so callers using custom OAuth apps or non-OAuth schemes can ignore it without ambiguity.
  • JSDoc: initiate() now flags the retirement explicitly and points at link() for the affected combination. Custom auth configs and non-OAuth schemes (API key, bearer, basic) are unaffected.

  No behavior change for any caller outside the Composio-managed-OAuth combination — initiate() continues to call the legacy endpoint, return the same ConnectionRequest shape, and respect the allowMultiple guard.

• 81f8027: Add session.update() method for partially updating session configuration after creation. Accepts the same config shape as create() and mutates the session in-place. Available in both TypeScript and Python SDKs.

• 711a703: Add expanded ToolRouter session controls for agent workflows. composio.create() now creates a fresh session on each call for better isolation and observability, while composio.use() can resume an existing session for multi-turn conversations. Sessions can preload frequently used tools, expose custom tools directly from session.tools(), use a direct-tools preset for agents that know their tool set upfront, and update session config mid-session with session.update().

• 07c9bab: connectedAccounts now accepts both string and string[] per toolkit.

  A single string is automatically coerced to an array to match the v3.1 API wire format. Existing callers passing { gmail: "ca_xxx" } continue to work without changes. Only one account per toolkit is allowed when multi-account mode is disabled.

• 3ece424: Add custom tools support to composio.use().

  • composio.use(id, { customTools, customToolkits }): Reuse an existing session and optionally bind SDK-local custom tools for search and execution.
  • Inline custom tools payload: use() now correctly passes inlineCustomToolsPayload and preloadedCustomToolSlugs to the session, enabling custom tool execution and preloading on rehydrated sessions.
  • CustomToolsMap.tools: The map now caches the raw CustomTool[] array for future inline re-injection on v3.1 search/execute requests.

Patch Changes

• c9b6525: Fix connectedAccounts TypeScript type so a single string per toolkit is actually accepted by the public API.

  Previously the schema's .transform() made ToolRouterCreateSessionConfig['connectedAccounts'] resolve to Record<string, string[]> (the post-transform output), so TypeScript users still got Type 'string' is not assignable to type 'string[]' even though the runtime accepted strings. Coercion now happens inside ToolRouter.create, mirroring the Python implementation, and the public type is Record<string, string | string[]>.

• cc673b6: Resolve internal JSON Schema $ref pointers (#/$defs/... and #/definitions/...) before handing tool parameters to @mastra/schema-compat. Composio tools whose schemas use $defs/definitions — legal under Draft 7 and 2020-12 — no longer trigger the AJV can't resolve reference … error, and the resolved type information from $defs survives the JSON-Schema → Zod → JSON-Schema round-trip instead of being silently degraded to a permissive anyOf.

  • New dereferenceJsonSchema helper exported from @composio/core performs the inline expansion. It deep-clones the input, walks every applicator reflectively (so future JSON Schema keywords are covered), shallow-merges sibling keywords next to $ref per Draft 2020-12 semantics, breaks cycles with { type: 'object', additionalProperties: true } (matching the upstream guidance in mastra-ai/mastra#15341), and strips $defs/definitions once everything reachable is inlined. External (http:///https://) $ref pointers are left untouched.
  • @composio/mastra calls the helper inside wrapTool for both inputParameters and outputParameters.
  • @mastra/schema-compat dependency floor raised to ^1.2.9 so users automatically receive PR #15400's recursive-$ref handling.

• bccd32b: Expose and document the Tool Router direct-tools preset via SessionPreset.DIRECT_TOOLS, with Python parity through SESSION_PRESET_DIRECT_TOOLS. Direct-tools examples now use the constants and keep the agent prompt generic while still asserting that only direct tools are exposed.

• bccd32b: Document and tighten Tool Router preload behavior for app tools, preload.tools = "all", and SDK custom tools. Custom tool and toolkit preload hints now have clearer user-facing comments, direct custom tool descriptions now only state that search is not needed beforehand, examples assert the normalized LOCAL_* tool slugs exposed by session.tools(), and composio.use(..., customTools/customToolkits) reuses the same custom preload preparation path as session creation.