refactor(apps): Phase 3 - registration + app-settings surface via AppResourceBridge

Moves the last accessor category off the accessor:* channel. After this phase
the base-runtime emits zero accessor:* messages - every accessor call is a
bridges:* message, and handleAccessorMessage is dead (removed in Phase 4).

Host:
- Add AppResourceBridge, a concrete engine-owned bridge (not part of the
  app-facing AppBridges surface) that delegates to the manager registries
  (slash commands, APIs, scheduler, UI action buttons, external components,
  video-conf and outbound providers) and to the app's ProxiedApp storage item
  + AppSettingsManager for app settings.
- BaseRuntimeSubprocessController.handleBridgeMessage resolves the
  getAppResourceBridge name via a dedicated controller field and suppresses
  AppResourceBridge.REGISTRATION_METHODS while the subprocess is restarting
  (replacing the old getConfigurationExtend hijack in handleAccessorMessage,
  now keyed on an explicit method set). AppManager is handed to the bridge in
  the controller constructor; no apps/meteor changes required. Permission and
  conflict semantics are preserved by delegating to the same managers.

Runtime:
- getConfigurationExtend / getConfigurationModify and the app-settings
  SettingRead/SettingUpdater/SettingsExtend members now call
  getAppResourceBridge().do*, keeping the AppObjectRegistry stash-then-forward
  for slash commands, processors, api endpoints and providers. accessor:api:
  listApis is replaced by doListApis. registerButton stays a synchronous void.
- Removed the now-dead proxify machinery and WithProxy type from mod.ts.

RPC-boundary: SettingRead.getValueById treats null/undefined alike as "does
not exist" (undefined serializes to null across the boundary).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018FbxFGJWHiroxrdNPJRL3P

Author: claude

docs/proposals/apps-accessor-consolidation/README.md

@@ -599,16 +599,34 @@ through `RemoteBridges` (`Promise<unknown>`) and are cast to their interface ret
 `void`-returning methods (`setActiveState`, `endActiveState`, reactions, deletes) `await` instead of
 returning the bridge value, matching the interface.
 
-### Phase 3 — Registration surface via `AppResourceBridge`
-
-1. Host: implement `AppResourceBridge` (§4) + internal-bridge lookup in `handleBridgeMessage` +
-   `restarting` guard for registration methods. Unit-test the guard and throw-vs-silent permission
-   behaviors.
-2. Runtime: rewrite `getConfigurationExtend` / `getConfigurationModify:slashCommands` /
-   `SettingRead` / `SettingUpdater` / `SettingsExtend` members as local classes calling
-   `RemoteBridges.getAppResourceBridge()`, preserving the `AppObjectRegistry` stash-then-forward
-   wrappers; replace `accessor:api:listApis` with `doListApis`.
-3. Delete the host `*Extend`/`SlashCommandsModify`/`SettingRead`/`SettingUpdater` accessors; port tests.
+### Phase 3 — Registration surface via `AppResourceBridge` — ✅ landed
+
+1. ✅ Host: added the concrete `AppResourceBridge` (`src/server/bridges/AppResourceBridge.ts`)
+   delegating to the managers (`AppSlashCommandManager`, `AppApiManager`, `AppSchedulerManager`,
+   `UIActionButtonManager`, `AppExternalComponentManager`, `AppVideoConfProviderManager`,
+   `AppOutboundCommunicationProviderManager`) and the app's `ProxiedApp` storage item +
+   `AppSettingsManager` for settings. Wired into `BaseRuntimeSubprocessController.handleBridgeMessage`
+   via a dedicated `getAppResourceBridge` lookup (resolved from a controller field, not `AppBridges`)
+   + the `restarting` guard keyed on `AppResourceBridge.REGISTRATION_METHODS`. Permission/conflict
+   semantics are unchanged because each method calls the same manager the host accessor used (the
+   video-conf/outbound `PermissionDeniedError` throw and the UI log-and-refuse both propagate as
+   before). The `AppManager` instance is passed to the bridge in the controller constructor — no
+   `apps/meteor` orchestrator changes needed.
+2. ✅ Runtime: rewrote `getConfigurationExtend` (ui/settings/externalComponents/api/scheduler/
+   videoConfProviders/outboundCommunication/slashCommands), `getConfigurationModify`
+   (slashCommands → modify/enable/disable; scheduler → local `SchedulerModify`), and the app-settings
+   `SettingRead`/`SettingUpdater`/`SettingsExtend` members to call `getAppResourceBridge().do*`,
+   preserving the `AppObjectRegistry` stash-then-forward. `accessor:api:listApis` is replaced by
+   `doListApis`. `registerButton` stays a synchronous `void` (fire-and-forget) per its interface. The
+   now-dead `proxify` machinery and `WithProxy` type were removed from `mod.ts` — **the runtime no
+   longer emits any `accessor:*` message at all.**
+3. Host accessor deletion (`*Extend`/`SlashCommandsModify`/`SettingRead`/`SettingUpdater`) + the rest
+   of the teardown are deferred to Phase 4, consistent with Phases 1–2. Tests:
+   `accessors/tests/configuration.test.ts` + updated `AppAccessors.test.ts`; the host
+   `DenoRuntimeSubprocessController` test validates the controller wiring.
+
+**RPC-boundary note:** `SettingRead.getValueById` treats `null` and `undefined` alike as "does not
+exist" (undefined serializes to null across the boundary), same adaptation as `ServerSettingRead`.
 
 ### Phase 4 — Teardown
 

packages/apps/base-runtime/src/lib/accessors/environment/SettingRead.ts

@@ -0,0 +1,30 @@
+import type { ISettingRead } from '@rocket.chat/apps-engine/definition/accessors';
+import type { ISetting } from '@rocket.chat/apps-engine/definition/settings';
+
+import type { RemoteBridges } from '../../bridges/RemoteBridges';
+
+// App settings are host-persisted metadata (ProxiedApp storage item), fronted by the internal
+// AppResourceBridge. The value fallback that used to run host-side now runs locally.
+export class SettingRead implements ISettingRead {
+	constructor(private readonly bridges: RemoteBridges) {}
+
+	public getById(id: string): Promise<ISetting> {
+		return this.bridges.getAppResourceBridge().doGetSettingById(id, 'APP_ID') as Promise<ISetting>;
+	}
+
+	public async getValueById(id: string): Promise<any> {
+		const set = (await this.getById(id)) as ISetting;
+
+		// The host accessor checks `typeof set === 'undefined'`; across the RPC boundary an absent
+		// host return arrives as null, so both are treated as "does not exist".
+		if (set === undefined || set === null) {
+			throw new Error(`Setting "${id}" does not exist.`);
+		}
+
+		if (set.value === undefined || set.value === null) {
+			return set.packageValue;
+		}
+
+		return set.value;
+	}
+}

packages/apps/base-runtime/src/lib/accessors/environment/SettingUpdater.ts

@@ -0,0 +1,19 @@
+import type { ISettingUpdater } from '@rocket.chat/apps-engine/definition/accessors/ISettingUpdater';
+import type { ISetting } from '@rocket.chat/apps-engine/definition/settings';
+
+import type { RemoteBridges } from '../../bridges/RemoteBridges';
+
+// The "not found" guard and the AppSettingsManager persistence run host-side in the
+// AppResourceBridge (they depend on the ProxiedApp storage item and the settings manager); the
+// runtime accessor is a thin forwarder.
+export class SettingUpdater implements ISettingUpdater {
+	constructor(private readonly bridges: RemoteBridges) {}
+
+	public async updateValue(id: ISetting['id'], value: ISetting['value']): Promise<void> {
+		await this.bridges.getAppResourceBridge().doUpdateSettingValue(id, value, 'APP_ID');
+	}
+
+	public async updateSelectOptions(id: ISetting['id'], values: ISetting['values']): Promise<void> {
+		await this.bridges.getAppResourceBridge().doUpdateSettingSelectOptions(id, values, 'APP_ID');
+	}
+}

packages/apps/base-runtime/src/lib/accessors/mod.ts

@@ -4,15 +4,18 @@ import type { IConfigurationExtend } from '@rocket.chat/apps-engine/definition/a
 import type { IConfigurationModify } from '@rocket.chat/apps-engine/definition/accessors/IConfigurationModify';
 import type { IEnvironmentRead } from '@rocket.chat/apps-engine/definition/accessors/IEnvironmentRead';
 import type { IEnvironmentWrite } from '@rocket.chat/apps-engine/definition/accessors/IEnvironmentWrite';
+import type { IExternalComponentsExtend } from '@rocket.chat/apps-engine/definition/accessors/IExternalComponentsExtend';
 import type { IHttp, IHttpExtend } from '@rocket.chat/apps-engine/definition/accessors/IHttp';
 import type { IModify } from '@rocket.chat/apps-engine/definition/accessors/IModify';
 import type { INotifier } from '@rocket.chat/apps-engine/definition/accessors/INotifier';
 import type { IOutboundCommunicationProviderExtend } from '@rocket.chat/apps-engine/definition/accessors/IOutboundCommunicationProviderExtend';
 import type { IPersistence } from '@rocket.chat/apps-engine/definition/accessors/IPersistence';
 import type { IRead } from '@rocket.chat/apps-engine/definition/accessors/IRead';
 import type { ISchedulerExtend } from '@rocket.chat/apps-engine/definition/accessors/ISchedulerExtend';
+import type { ISettingsExtend } from '@rocket.chat/apps-engine/definition/accessors/ISettingsExtend';
 import type { ISlashCommandsExtend } from '@rocket.chat/apps-engine/definition/accessors/ISlashCommandsExtend';
 import type { ISlashCommandsModify } from '@rocket.chat/apps-engine/definition/accessors/ISlashCommandsModify';
+import type { IUIExtend } from '@rocket.chat/apps-engine/definition/accessors/IUIExtend';
 import type { IVideoConfProvidersExtend } from '@rocket.chat/apps-engine/definition/accessors/IVideoConfProvidersExtend';
 import type { IApi } from '@rocket.chat/apps-engine/definition/api/IApi';
 import type { IApiEndpointMetadata } from '@rocket.chat/apps-engine/definition/api/IApiEndpointMetadata';
@@ -26,7 +29,6 @@ import type { IVideoConfProvider } from '@rocket.chat/apps-engine/definition/vid
 
 import { Persistence } from './Persistence';
 import { HttpExtend } from './extenders/HttpExtender';
-import { formatErrorResponse } from './formatResponseErrorHandler';
 import { Http } from './http';
 import { AppObjectRegistry } from '../../AppObjectRegistry';
 import { RemoteBridges } from '../bridges/RemoteBridges';
@@ -37,6 +39,8 @@ import { EnvironmentalVariableRead } from './environment/EnvironmentalVariableRe
 import { ServerSettingRead } from './environment/ServerSettingRead';
 import { ServerSettingUpdater } from './environment/ServerSettingUpdater';
 import { ServerSettingsModify } from './environment/ServerSettingsModify';
+import { SettingRead } from './environment/SettingRead';
+import { SettingUpdater } from './environment/SettingUpdater';
 import { ModerationModify } from './modify/ModerationModify';
 import { ModifyCreator } from './modify/ModifyCreator';
 import { ModifyDeleter } from './modify/ModifyDeleter';
@@ -61,9 +65,6 @@ import { UploadRead } from './read/UploadRead';
 import { UserRead } from './read/UserRead';
 import { VideoConferenceRead } from './read/VideoConferenceRead';
 
-/** Helper: extends T with an internal _proxy property used for delegation. */
-type WithProxy<T> = T & { _proxy: T };
-
 const httpMethods = ['get', 'post', 'put', 'delete', 'head', 'options', 'patch'] as const;
 
 // We need to create this object first thing, as we'll handle references to it later on
@@ -102,40 +103,9 @@ export class AppAccessors {
 
 	private readonly bridges: RemoteBridges;
 
-	private proxify: <T>(namespace: string, overrides?: Record<string, (...args: unknown[]) => unknown>) => T;
-
 	constructor(private readonly senderFn: typeof Messenger.sendRequest) {
 		this.bridges = new RemoteBridges(senderFn);
 
-		this.proxify = <T>(namespace: string, overrides: Record<string, (...args: unknown[]) => unknown> = {}): T =>
-			new Proxy(
-				{ __kind: `accessor:${namespace}` },
-				{
-					get:
-						(_target: unknown, prop: string) =>
-						(...params: unknown[]) => {
-							// We don't want to send a request for this prop
-							if (prop === 'toJSON') {
-								return {};
-							}
-
-							// If the prop is inteded to be overriden by the caller
-							if (prop in overrides) {
-								return overrides[prop].apply(undefined, params);
-							}
-
-							return senderFn({
-								method: `accessor:${namespace}:${prop}`,
-								params,
-							})
-								.then((response) => response.result)
-								.catch((err) => {
-									throw formatErrorResponse(err);
-								});
-						},
-				},
-			) as T;
-
 		this.http = new Http(this.getReader(), this.getPersistence(), this.httpExtend, this.getSenderFn());
 		this.notifier = new Notifier(this.getSenderFn());
 	}
@@ -146,11 +116,10 @@ export class AppAccessors {
 
 	public getEnvironmentRead(): IEnvironmentRead {
 		if (!this.environmentRead) {
-			// App settings (`getSettings`) remain proxied to the host until Phase 3 (they are
-			// backed by the host ProxiedApp storage item); server settings and environment
-			// variables now run locally against their bridges.
+			// App settings, server settings and environment variables all run locally now; app
+			// settings reach the host ProxiedApp storage item through the internal AppResourceBridge.
 			this.environmentRead = new EnvironmentRead(
-				this.proxify('getEnvironmentRead:getSettings'),
+				new SettingRead(this.bridges),
 				new ServerSettingRead(this.bridges),
 				new EnvironmentalVariableRead(this.bridges),
 			);
@@ -161,36 +130,33 @@ export class AppAccessors {
 
 	public getEnvironmentWrite() {
 		if (!this.environmentWriter) {
-			// App-settings updates (`getSettings`) remain proxied to the host until Phase 3.
-			this.environmentWriter = new EnvironmentWrite(
-				this.proxify('getEnvironmentWrite:getSettings'),
-				new ServerSettingUpdater(this.bridges),
-			);
+			this.environmentWriter = new EnvironmentWrite(new SettingUpdater(this.bridges), new ServerSettingUpdater(this.bridges));
 		}
 
 		return this.environmentWriter;
 	}
 
 	public getConfigurationModify() {
 		if (!this.configModifier) {
-			const slashCommandsModify: WithProxy<ISlashCommandsModify> = {
-				_proxy: this.proxify('getConfigurationModify:slashCommands'),
+			const resourceBridge = this.bridges.getAppResourceBridge();
+
+			const slashCommandsModify: ISlashCommandsModify = {
 				modifySlashCommand(slashcommand: ISlashCommand) {
 					// Store the slashcommand instance to use when the Apps-Engine calls the slashcommand
 					AppObjectRegistry.set(`slashcommand:${slashcommand.command}`, slashcommand);
 
-					return this._proxy.modifySlashCommand(slashcommand);
+					return resourceBridge.doModifySlashCommand(slashcommand, 'APP_ID') as Promise<void>;
 				},
 				disableSlashCommand(command: string) {
-					return this._proxy.disableSlashCommand(command);
+					return resourceBridge.doDisableSlashCommand(command, 'APP_ID') as Promise<void>;
 				},
 				enableSlashCommand(command: string) {
-					return this._proxy.enableSlashCommand(command);
+					return resourceBridge.doEnableSlashCommand(command, 'APP_ID') as Promise<void>;
 				},
 			};
 
 			this.configModifier = {
-				scheduler: this.proxify('getConfigurationModify:scheduler'),
+				scheduler: new SchedulerModify(this.bridges),
 				slashCommands: slashCommandsModify,
 				serverSettings: new ServerSettingsModify(this.bridges),
 			};
@@ -201,10 +167,9 @@ export class AppAccessors {
 
 	public getConfigurationExtend() {
 		if (!this.configExtender) {
-			const { senderFn } = this;
+			const resourceBridge = this.bridges.getAppResourceBridge();
 
-			const apiExtend: WithProxy<IApiExtend> = {
-				_proxy: this.proxify('getConfigurationExtend:api'),
+			const apiExtend: IApiExtend = {
 				async provideApi(api: IApi) {
 					const apiEndpoints = AppObjectRegistry.get<IApiEndpointMetadata[]>('apiEndpoints')!;
 
@@ -215,67 +180,83 @@ export class AppAccessors {
 						AppObjectRegistry.set(`api:${endpoint.path}`, endpoint);
 					});
 
-					const result = await this._proxy.provideApi(api);
+					await resourceBridge.doProvideApi(api, 'APP_ID');
 
 					// Let's call the listApis method to cache the info from the endpoints
 					// Also, since this is a side-effect, we do it async so we can return to the caller
-					senderFn({ method: 'accessor:api:listApis' })
-						.then((response) => apiEndpoints.push(...(response.result as IApiEndpointMetadata[])))
-						.catch((err) => err.error);
-
-					return result;
+					resourceBridge
+						.doListApis('APP_ID')
+						.then((endpoints) => apiEndpoints.push(...(endpoints as IApiEndpointMetadata[])))
+						.catch(() => undefined);
 				},
 			};
 
-			const schedulerExtend: WithProxy<ISchedulerExtend> = {
-				_proxy: this.proxify('getConfigurationExtend:scheduler'),
+			const schedulerExtend: ISchedulerExtend = {
 				registerProcessors(processors: IProcessor[]) {
 					// Store the processor instance to use when the Apps-Engine calls the processor
 					processors.forEach((processor) => {
 						AppObjectRegistry.set(`scheduler:${processor.id}`, processor);
 					});
 
-					return this._proxy.registerProcessors(processors);
+					return resourceBridge.doRegisterProcessors(processors, 'APP_ID') as Promise<void | Array<string>>;
 				},
 			};
 
-			const videoConfProviders: WithProxy<IVideoConfProvidersExtend> = {
-				_proxy: this.proxify('getConfigurationExtend:videoConfProviders'),
+			const videoConfProviders: IVideoConfProvidersExtend = {
 				provideVideoConfProvider(provider: IVideoConfProvider) {
 					// Store the videoConfProvider instance to use when the Apps-Engine calls the videoConfProvider
 					AppObjectRegistry.set(`videoConfProvider:${provider.name}`, provider);
 
-					return this._proxy.provideVideoConfProvider(provider);
+					return resourceBridge.doProvideVideoConfProvider(provider, 'APP_ID') as Promise<void>;
 				},
 			};
 
-			const outboundCommunication: WithProxy<IOutboundCommunicationProviderExtend> = {
-				_proxy: this.proxify('getConfigurationExtend:outboundCommunication'),
+			const outboundCommunication: IOutboundCommunicationProviderExtend = {
 				registerEmailProvider(provider: IOutboundEmailMessageProvider) {
 					AppObjectRegistry.set(`outboundCommunication:${provider.name}-${provider.type}`, provider);
-					return this._proxy.registerEmailProvider(provider);
+					return resourceBridge.doRegisterOutboundProvider(provider, 'APP_ID') as Promise<void>;
 				},
 				registerPhoneProvider(provider: IOutboundPhoneMessageProvider) {
 					AppObjectRegistry.set(`outboundCommunication:${provider.name}-${provider.type}`, provider);
-					return this._proxy.registerPhoneProvider(provider);
+					return resourceBridge.doRegisterOutboundProvider(provider, 'APP_ID') as Promise<void>;
 				},
 			};
 
-			const slashCommandsExtend: WithProxy<ISlashCommandsExtend> = {
-				_proxy: this.proxify('getConfigurationExtend:slashCommands'),
+			const slashCommandsExtend: ISlashCommandsExtend = {
 				provideSlashCommand(slashcommand: ISlashCommand) {
 					// Store the slashcommand instance to use when the Apps-Engine calls the slashcommand
 					AppObjectRegistry.set(`slashcommand:${slashcommand.command}`, slashcommand);
 
-					return this._proxy.provideSlashCommand(slashcommand);
+					return resourceBridge.doProvideSlashCommand(slashcommand, 'APP_ID') as Promise<void>;
+				},
+			};
+
+			const ui: IUIExtend = {
+				// `registerButton` is a synchronous `void` in the interface, but the host registration
+				// is async over the bridge; fire-and-forget matches the contract. The host manager
+				// logs-and-refuses rather than throwing, so there is no rejection to surface here.
+				registerButton(button) {
+					void resourceBridge.doRegisterActionButton(button, 'APP_ID').catch(() => undefined);
+				},
+			};
+
+			const settings: ISettingsExtend = {
+				provideSetting(setting) {
+					return resourceBridge.doProvideSetting(setting, 'APP_ID') as Promise<void>;
+				},
+			};
+
+			const externalComponents: IExternalComponentsExtend = {
+				register(externalComponent) {
+					return resourceBridge.doRegisterExternalComponent(externalComponent, 'APP_ID') as Promise<void>;
 				},
 			};
 
 			this.configExtender = {
-				ui: this.proxify('getConfigurationExtend:ui'),
+				ui,
 				http: this.httpExtend,
-				settings: this.proxify('getConfigurationExtend:settings'),
-				externalComponents: this.proxify('getConfigurationExtend:externalComponents'),
+				settings,
+				externalComponents,
 				api: apiExtend,
 				scheduler: schedulerExtend,
 				videoConfProviders,
@@ -303,11 +284,8 @@ export class AppAccessors {
 
 	public getReader() {
 		if (!this.reader) {
-			// The environment sub-reader keeps its own `getSettings` proxy namespace
-			// (`getReader:getEnvironmentReader:getSettings`) so the app-settings path stays
-			// byte-for-byte until Phase 3; server settings and env vars run locally.
 			const environmentReader = new EnvironmentRead(
-				this.proxify('getReader:getEnvironmentReader:getSettings'),
+				new SettingRead(this.bridges),
 				new ServerSettingRead(this.bridges),
 				new EnvironmentalVariableRead(this.bridges),
 			);