Repository navigation
feat(plugins): commands[].replaces lets a mod take over a built-in action - #37316
Conversation
Findings
|
There was a problem hiding this comment.
Actionable comments posted: 3

Review info
-
Run configuration-
- Source mode: Auto
- Repository: Unavailable
- Branch: Unavailable
- File: No configuration file from this repository applied
- Commit: Unavailable
- Layers: Repository UI
- Review profile: CHILL
- Plan: Advanced
- Run ID:
0a7a58d4-05d7-4887-b12a-df71d462ff6f
Files selected for processing: 43-
docs/reference/plugin-authoring.mddocs/reference/plugin-manifest.mddocs/schemas/plugins/orca-plugin.v2.schema.jsonskill-guides/orca-plugin-authoring/references/manifest.mdskill-guides/orca-plugin-authoring/references/recipes.mdsrc/cli/bundled-skill-guides.tssrc/main/ipc/plugins.tssrc/main/plugins/installation/plugin-install-staging.tssrc/main/plugins/installation/plugin-install.test.tssrc/main/plugins/plugin-command-invocation.test.tssrc/main/plugins/plugin-command-invocation.tssrc/main/plugins/plugin-command-registry.tssrc/main/plugins/plugin-command-replacement-owners.test.tssrc/main/plugins/plugin-command-replacement-owners.tssrc/main/plugins/plugin-list-projection.tssrc/main/plugins/plugin-service.tssrc/preload/api/plugin-host-api.tssrc/preload/api/plugins-bridge.tssrc/renderer/src/app-shell/app-command-handlers.tssrc/renderer/src/app-shell/use-global-keybindings.tssrc/renderer/src/components/plugins/page/PluginAddsSection.tsxsrc/renderer/src/components/plugins/page/PluginCommandReplacementRow.test.tsxsrc/renderer/src/components/plugins/page/PluginCommandReplacementRow.tsxsrc/renderer/src/components/plugins/page/PluginPageAction.tsxsrc/renderer/src/components/plugins/review/PluginInstallConsent.tsxsrc/renderer/src/components/plugins/review/PluginUpdateCandidate.tsxsrc/renderer/src/components/plugins/review/plugin-update-replacement.test.tssrc/renderer/src/components/plugins/state/use-plugin-page-model.tssrc/renderer/src/hooks/ipc-events/settings-sidebar-ipc-bridge.tssrc/renderer/src/hooks/ipc-events/workspace-shortcut-ipc-bridge.tssrc/renderer/src/i18n/locales/en.jsonsrc/renderer/src/lib/app-command-dispatch.tssrc/renderer/src/lib/plugin-command-replacements.test.tssrc/renderer/src/lib/plugin-command-replacements.tssrc/shared/plugins/approval/plugin-cli-approval.tssrc/shared/plugins/approval/plugin-consent-fingerprint.tssrc/shared/plugins/approval/plugin-update-access-growth.tssrc/shared/plugins/contributions/plugin-command-contribution.tssrc/shared/plugins/contributions/plugin-command-replaces.test.tssrc/shared/plugins/installation/plugin-host-version.tssrc/shared/plugins/manifest/plugin-manifest-contribution-validation.tssrc/shared/plugins/plugin-list-entry.tssrc/shared/plugins/plugin-system-settings.ts
Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 2 remain after this review.
-
| await pluginService.whenReady() | ||
| const parsed = invokeCommandArgsSchema.parse(args) | ||
| return pluginService.invokeCommand(parsed.pluginKey, parsed.commandId, parsed.args) | ||
| const startBy = parsed.timeoutMs === undefined ? undefined : Date.now() + parsed.timeoutMs |
There was a problem hiding this comment.
Use the renderer’s deadline before waiting for readiness.
If pluginService.whenReady() takes more than two seconds, the renderer runs the built-in action first. Line 207 then grants the worker a new two-second window, so the plugin command can also run. Pass an absolute deadline from the renderer, or otherwise preserve the time already spent in IPC and readiness before calling invokeCommand. (raw.githubusercontent.com)
| lock: Pick<PluginLockfile, 'plugins'>, | ||
| log: (pluginKey: string, line: string) => void | ||
| ): PluginHostListEntry[] { | ||
| const installedAt = (key: string) => lock.plugins[key]?.installedAt ?? Number.POSITIVE_INFINITY |
There was a problem hiding this comment.
Sort development folders after installed plugins.
When a development folder overrides an installed plugin with the same pluginKey, this lookup gives the development entry the installed plugin’s installedAt. A development command can then take precedence over another installed plugin, although development folders should rank last. Check entry.isDev before using the lockfile timestamp, and add an override case to the owner-selection test. Discovery explicitly permits the same-key override. (raw.githubusercontent.com)
| {command.replaces ? ( | ||
| <PluginCommandReplacementRow command={{ ...command, replaces: command.replaces }} /> |
There was a problem hiding this comment.
Hide the switch for an uninstalled plugin.
When an uninstalled plugin’s preview declares replaces, this code renders a live switch. If an installed plugin already owns that action, turning off the preview switch adds the action to pluginReplacementsOff and disables the installed plugin’s replacement too. Show the preview disclosure without a switch. Enable the switch only for an installed, live replacement owner. The setting and dispatch both apply the choice per action, while ownership excludes plugins that are not live. (raw.githubusercontent.com)
…in action A worker command with replaces: <action> (the declarative action list, engines >=1.4.248, needs main) runs in place of that built-in from its shortcut, plugin aliases and the sidebar menus; a failed or silent (2 s) worker falls back to Orca's own. The install screen names each replacement, the plugin page has a per-action switch (settings.pluginReplacementsOff), and when two plugins replace one action the one installed first wins and the other's log says so. Update review counts replaces as new access.
- Consent includes the replaced actions, so adding replaces to a dev folder needs a new approval; CLI approval and update review name each takeover. - Shortcuts main intercepts (Tasks, Workspace Board, history), search with a selection and floating maximize now go through the replacement too. - A worker that only starts after the 2 s fallback no longer runs the command as well: main refuses to start it past the deadline. - A workspace-only command does not replace an action without a workspace. - An update keeps the plugin's first install time, so it keeps its takeover. - Drop the commands.run promise until Orca offers it.
A5b's commands.run dispatches with the 'plugin-host' source; the app dispatcher now builds handlers that run Orca's own action for it, so a plugin that replaces an action and calls commands.run cannot loop. Docs and schema describe wrapping the built-in with commands.run; regenerated.
69946b0 to
2ca67a2
Compare
…o main's Mobile checks pass (#37370) * fix(plugins): build the consent fingerprint without toSorted so the phone bundle passes Hermes checks Main's Mobile verify has failed since #37316 because the plugin consent fingerprint (bundled into the phone app via src/shared) used Array.prototype.toSorted, which Hermes lacks. flatMap already returns a fresh array, so sorting it in place keeps the same result. * test(plugins): pin the consent fingerprint's command-order independence Co-Authored-By: Claude Opus 5.5 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5.5 (1M context) <noreply@anthropic.com>
ELI5
A full-access mod can now take over one of Orca's built-in actions, for example toggling the right sidebar or going back in workspace history. When that action fires, the mod's command runs instead. People see this at install and can turn it off per action.
What Changed
contributes.commands[].replaces: <built-in action id>, from the same list as the declarativeactionfield. Engine floor 1.4.248.main,trusted-worker).action, for an unknown action, or when two commands in one plugin replace the same action.pluginReplacementsOff.Why
Taking over built-in commands is part of full modability. Routing it through the single place built-in actions are dispatched covers keybindings, aliases and menus at once. The 2 s fallback means a broken mod can never disable a built-in action.
A replacement can wrap Orca's own action with
orca.host.call('commands.run', { action })(#37323): that path always runs the built-in, never a replacement, so it cannot loop into itself.Linked Issue
N/A (maintainer).
Visual Proof
A dev plugin whose
Open task boardcommand has"replaces": "view.tasks", before approval, in a background dev build.The approval screen names the replacement:
The plugin page lists it, with the switch that keeps Orca's own action:
Testing
pnpm tc, lint, ast-grep, anti-slop, localization and freshness checks pass.Risk
Level: Medium. It touches built-in action dispatch. With no replacing plugin, behaviour is unchanged, and a failing or slow plugin falls back to the built-in. Plain revert, which leaves the optional setting unused.
Agent skill upstream boundary
Checklist