Twenty sdk/v2.55.0 — Release Notes & Engineering Impact

<!-- generated-release-notes v1 --> Five breaking changes ship in this release. `createWebhook` requires a `roleId`. `objectMetadata.readability`, `writability`, and `sharingReach` are removed from GraphQL. `setRecordGeneralAccess` is replaced by `setRecordPrivate`. `IconsProvider` moves out of `twenty-ui/icon`, cutting ~2 MB from affected bundles. The workspace field `allowedIframeOrigins` is renamed. `defineHealthCheck` gains `runOnUserPreferences: true` for member-scoped checks. App manifests accept `defineRelatedRecordPath`. The `SEND_CHAT_MESSAGE` workflow step now roundtrips through pull and apply. `twenty local` is restored: `start`, `stop`, `status`, `logs`, `upgrade`, and `reset`. Validation failures now include the server's error code and friendly message. The CLI no longer rejects a manifest that references the workspace default role without a local definition. ## ⚠️ Breaking changes - allowedIframeOrigins on the workspace object is renamed — update any queries or mutations that reference it; the new updateWorkspaceIframeMediaPermissions mutation adds per-origin microphone and camera grants. ([#29217](https://github.com/twentyhq/twenty/pull/29217)) by @bosiraphael - createWebhook now requires a roleId; updateWebhook accepts an optional roleId to change it; creating or editing a webhook now also requires the ROLES permission. ([#29273](https://github.com/twentyhq/twenty/pull/29273)) by @charlesBochet - defineSettingsMenuItem now accepts an optional slug (lowercase kebab-case, max 64 chars) used as the URL hash for that settings tab; Connect and Reconnect now land on the app's first preferences tab. ([#29355](https://github.com/twentyhq/twenty/pull/29355)) by @martmull - Replace setRecordGeneralAccess with setRecordPrivate(recordId, isPrivate) — a record is now either private (creator and direct shares only) or role-governed. ([#29383](https://github.com/twentyhq/twenty/pull/29383)) by @charlesBochet - IconsProvider has moved out of twenty-ui/icon to a new export path; import it from there to stop inlining all 4,200 Tabler icons in bundles that only need the provider. ([#29386](https://github.com/twentyhq/twenty/pull/29386)) by @FelixMalfait - objectMetadata.readability, writability, readabilityParentFieldUniversalIdentifiers, sharingReach, and fieldMetadata.writability are removed from the GraphQL metadata API; remove them from all queries, fragments, and SDK calls. ([#29390](https://github.com/twentyhq/twenty/pull/29390)) by @charlesBochet ## 🌟 Highlights - IconsProvider has moved out of twenty-ui/icon — update the import path or every bundle that touches it inlines all 4,200 Tabler icons. ([#29386](https://github.com/twentyhq/twenty/pull/29386)) - createWebhook now requires a roleId; pass the role that governs what the webhook can read. ([#29273](https://github.com/twentyhq/twenty/pull/29273)) - objectMetadata.readability, writability, sharingReach, and fieldMetadata.writability are removed from the GraphQL API — remove them from queries and fragments. ([#29390](https://github.com/twentyhq/twenty/pull/29390)) - setRecordGeneralAccess is gone; use setRecordPrivate(recordId, isPrivate) to control private vs. role-governed access. ([#29383](https://github.com/twentyhq/twenty/pull/29383)) - defineHealthCheck now accepts runOnUserPreferences: true for a member-scoped check; that handler receives { userWorkspaceId: string }. ([#29249](https://github.com/twentyhq/twenty/pull/29249)) - twenty local is restored — start, stop, status, logs, upgrade, and reset are available again for local development. ([#29301](https://github.com/twentyhq/twenty/pull/29301)) ## ✨ New features - defineHealthCheck now accepts runOnUserPreferences: true to declare a member-only check; the handler receives { userWorkspaceId: string } and the check does not run in workspace settings. ([#29249](https://github.com/twentyhq/twenty/pull/29249)) by @ehconitin - runMyApplicationHealthCheck(applicationId) is now available as a GraphQL mutation to trigger a member health check; it requires a user session and CONNECTED_ACCOUNTS. ([#29250](https://github.com/twentyhq/twenty/pull/29250)) by @ehconitin - The SDK/CLI frontend component render wrapper now accepts compiled source and record props directly and returns a promise that resolves after the initial React commit. ([#29263](https://github.com/twentyhq/twenty/pull/29263)) by @Weiko - Related record paths now carry an isInherent flag; an inherent path applies whenever the source record is readable by any means, not only when access starts on that object. ([#29292](https://github.com/twentyhq/twenty/pull/29292)) by @charlesBochet - defineRelatedRecordPath is now available in app manifests; it takes universalIdentifier, objectUniversalIdentifier, firstFieldMetadataUniversalIdentifier, optional second/third field identifiers, and optional isInherent. ([#29328](https://github.com/twentyhq/twenty/pull/29328)) by @charlesBochet - SEND_CHAT_MESSAGE workflow steps are now supported in twenty app pull and twenty app apply; the step input carries workspaceMemberId, title, text, and an optional toolCall. ([#29363](https://github.com/twentyhq/twenty/pull/29363)) by @FelixMalfait ## 💅 Improvements & UX - CLI validation failures now include the server's error code and friendly message; --json output exposes them under error.details.validationErrors. ([#28816](https://github.com/twentyhq/twenty/pull/28816)) by @prastoin - chargeCredits calls from app logic now appear under APP_OPERATION in the monitoring page instead of being mixed into CODE_EXECUTION. ([#29241](https://github.com/twentyhq/twenty/pull/29241)) by @martmull - Ada DM and Global inbox behavior modes are now readable and writable through GraphQL; the added enum shifts generated SDK type indices. ([#29320](https://github.com/twentyhq/twenty/pull/29320)) by @bosiraphael ## 🐛 Bug fixes - The CLI no longer rejects app build, plan, or apply when a valid pulled manifest references the workspace default role without a local role definition. ([#29318](https://github.com/twentyhq/twenty/pull/29318)) by @Weiko ## 🔧 Developer & API - The CLI now stores a dependency export map alongside the built bundle so AI-compiled components can reuse the app's existing shared dependencies without reinstalling. ([#28469](https://github.com/twentyhq/twenty/pull/28469)) by @Weiko - twenty local start [version], stop, status, and logs are restored for managing a full local Twenty environment without a saved remote or app directory. ([#29301](https://github.com/twentyhq/twenty/pull/29301)) by @Weiko - twenty local upgrade [version] and twenty local reset are now available for pulling a new image over an existing container and for explicit data deletion. ([#29302](https://github.com/twentyhq/twenty/pull/29302)) by @Weiko <details> <summary>🏗️ Internal changes (6)</summary> - Create temporary AI chat drafts with mocked previews ([#28470](https://github.com/twentyhq/twenty/pull/28470)) by @Weiko - feat(getting-started): add the server module behind IS_GETTING_STARTED_ENABLED ([#29290](https://github.com/twentyhq/twenty/pull/29290)) by @etiennejouan - feat(getting-started): add the Getting Started page and sidebar card ([#29291](https://github.com/twentyhq/twenty/pull/29291)) by @etiennejouan - Store a relation hop on row level permission predicates ([#29323](https://github.com/twentyhq/twenty/pull/29323)) by @charlesBochet - Reuse current app dependencies for AI component compilation ([#29330](https://github.com/twentyhq/twenty/pull/29330)) by @Weiko - Enforce private records ([#29378](https://github.com/twentyhq/twenty/pull/29378)) by @charlesBochet </details> <details> <summary>Full changelog (26 PRs)</summary> - Retain frontend dependency export maps in app builds ([#28469](https://github.com/twentyhq/twenty/pull/28469)) by @Weiko - Create temporary AI chat drafts with mocked previews ([#28470](https://github.com/twentyhq/twenty/pull/28470)) by @Weiko - Preserve validation codes and friendly messages in CLI failures ([#28816](https://github.com/twentyhq/twenty/pull/28816)) by @prastoin - Store approved iframe media origins and send them in Permissions-Policy ([#29217](https://github.com/twentyhq/twenty/pull/29217)) by @bosiraphael - Land app chargeCredits in a dedicated APP_OPERATION category ([#29241](https://github.com/twentyhq/twenty/pull/29241)) by @martmull - Choose where app health checks run ([#29249](https://github.com/twentyhq/twenty/pull/29249)) by @ehconitin - Run app health checks in their configured execution mode ([#29250](https://github.com/twentyhq/twenty/pull/29250)) by @ehconitin - Render supplied frontend component source and data ([#29263](https://github.com/twentyhq/twenty/pull/29263)) by @Weiko - [BREAKING_CHANGE] Attach a role to webhooks ([#29273](https://github.com/twentyhq/twenty/pull/29273)) by @charlesBochet - feat(getting-started): add the server module behind IS_GETTING_STARTED_ENABLED ([#29290](https://github.com/twentyhq/twenty/pull/29290)) by @etiennejouan - feat(getting-started): add the Getting Started page and sidebar card ([#29291](https://github.com/twentyhq/twenty/pull/29291)) by @etiennejouan - Add inherent related record paths and declare the standard ones ([#29292](https://github.com/twentyhq/twenty/pull/29292)) by @charlesBochet - chore: bump version to 2.55.0 ([#29293](https://github.com/twentyhq/twenty/pull/29293)) by @twenty-pr - feat(cli): restore local development environment commands ([#29301](https://github.com/twentyhq/twenty/pull/29301)) by @Weiko - feat(cli): add local environment upgrade and reset ([#29302](https://github.com/twentyhq/twenty/pull/29302)) by @Weiko - fix(cli): accept default role references without local definitions ([#29318](https://github.com/twentyhq/twenty/pull/29318)) by @Weiko - Expose protected Ada behavior settings ([#29320](https://github.com/twentyhq/twenty/pull/29320)) by @bosiraphael - Store a relation hop on row level permission predicates ([#29323](https://github.com/twentyhq/twenty/pull/29323)) by @charlesBochet - Let app manifests declare related record paths ([#29328](https://github.com/twentyhq/twenty/pull/29328)) by @charlesBochet - Reuse current app dependencies for AI component compilation ([#29330](https://github.com/twentyhq/twenty/pull/29330)) by @Weiko - Add a slug to app settings tabs and land Connect and Reconnect on the app's first tab ([#29355](https://github.com/twentyhq/twenty/pull/29355)) by @martmull - Pull and apply workflow SEND_CHAT_MESSAGE steps ([#29363](https://github.com/twentyhq/twenty/pull/29363)) by @FelixMalfait - Enforce private records ([#29378](https://github.com/twentyhq/twenty/pull/29378)) by @charlesBochet - [BREAKING_CHANGE] Replace setRecordGeneralAccess with setRecordPrivate ([#29383](https://github.com/twentyhq/twenty/pull/29383)) by @charlesBochet - Move IconsProvider out of twenty-ui/icon so icon imports don't ship every icon ([#29386](https://github.com/twentyhq/twenty/pull/29386)) by @FelixMalfait - [BREAKING_CHANGE] Drop object readability, writability and sharing reach usage ([#29390](https://github.com/twentyhq/twenty/pull/29390)) by @charlesBochet </details> **Full Changelog**: https://github.com/twentyhq/twenty/compare/sdk/v2.54.0...sdk/v2.55.0