starred/orca
1
0
Fork 0
mirror of https://github.com/stablyai/orca.git synced 2026-11-13 09:27:29 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
main
orca/docs/reference/plugin-manifest.md
T
Neil 75ce5be014 feat(plugins): host API 1.9 — agent session history, resume past sessions, task titles (#41542) 
* feat(plugins): host API 1.9: agent.listSessions (history:read), resume past sessions, agents.list task titles

* test(plugins): host API 1.9 coverage; regenerate plugin artifacts

* fix(plugins): host API 1.9 review fixes

- agent.resume starts a past session where the desktop's Resume would: the same preparation
  request and answer handling (now shared), and the transcript in the home it pins
- AI Vault list cache keeps four scopes, so plugin reads never evict the panel's list
- list fingerprints ignore scan id and issues, so an unchanged history revalidates
- workspace mapping resolves symlinked workspaces and prefers a project over a folder
- agents.list task only for open dispatches, read at most once a second
- running matches OpenCode versions; history reads reset when the vault list is invalidated
- truncation, consent copy and limitations documented

* fix(plugins): forced history refresh supersedes cached scopes; resume legacy Codex sessions from their recorded transcript

* fix(plugins): address host API 1.9 review threads

- a scan that began before a forced history refresh no longer caches its older result
- list fingerprints count which issues there are (not their wording)
- symlinked workspaces rank by their resolved folder
- a session-only status row is no live pane: resume prepares the session
- a failed task-title read leaves agents.list rows intact
- the symlink test uses a junction on Windows

* test(ai-vault): order the stale scan before the forced refresh
2026-11-12 06:19:16 -08:00

281 lines
30 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Orca plugin manifest reference
<!-- Generated by `pnpm generate:plugin-schemas` from src/shared/plugins. Do not edit. -->
The orca-plugin.json file at the root of an Orca plugin (manifest format 2).
Add `"$schema": "https://raw.githubusercontent.com/stablyai/orca/main/docs/schemas/plugins/orca-plugin.v2.schema.json"` to `orca-plugin.json` for completion and inline errors in your editor.
`Since` is the first Orca release that reads the field; raise `engines.orca` when you use a newer one.
## Fields
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `$schema` | string | no | 1.4.245 | JSON Schema URL for editor completion. Ignored by Orca. |
| `manifestVersion` | `2` | yes | 1.4.245 | Manifest format. Use 2 for new plugins. |
| `execution` | `"data"` \| `"declarative"` \| `"sandboxed-ui"` \| `"trusted-worker"` | yes | 1.4.245 | Most authority the plugin needs, least first: `data` (themes, syntaxes, translations), `declarative` (commands, shortcuts, recipes), `sandboxed-ui` (panels), `trusted-worker` (`main`, events and hooks). Contributions beyond it fail validation. Example: `"data"` |
| `id` | string | yes | 1.4.160 | Plugin id, kebab-case. The install identity is `<publisher>.<id>`, where Orca derives the publisher from the repository owner. The reserved names `constructor` and `prototype` are refused. Example: `"gleam-syntax"` |
| `publisher` | string | no | 1.4.160 | Deprecated: leave it out. Orca derives the publisher from where the plugin comes from, the way a Go module is named by its repository path: the repository owner for the official and community catalogs and for Git URL installs (`acme` for `github.com/acme/gleam-syntax`), and `local` for a folder. A value here is ignored for catalog and Git installs. Leaving it out needs `engines.orca` of at least `>=1.4.246`, because older Orca requires it; if you keep it for older Orca, it must equal the repository owner. Reserved owners (`stablyai`, `official`, `anthropic`, `openai`, `github` and any starting `orca`) and ids starting `orca-` install only from Orca's official catalog. Example: `"acme"` |
| `name` | string | yes | 1.4.160 | Display name. Example: `"Gleam"` |
| `version` | string | yes | 1.4.160 | Plugin version, semver. Example: `"1.2.0"` |
| `description` | string | no | 1.4.160 | One or two sentences shown in the plugin list. |
| `author` | object | no | 1.4.160 | Who maintains the plugin. |
| `author.name` | string | yes | 1.4.160 | Author or organization name. Example: `"Acme"` |
| `author.url` | string | no | 1.4.160 | Author homepage. Example: `"https://example.com"` |
| `repository` | string | no | 1.4.160 | Source repository URL. Example: `"https://github.com/acme/orca-gleam-syntax"` |
| `license` | string | no | 1.4.245 | SPDX license expression. Example: `"MIT"` |
| `homepage` | string | no | 1.4.245 | Project homepage, https only. Example: `"https://example.com/gleam"` |
| `icon` | string | no | 1.4.160 | Square image shown beside the plugin name. PNG, WEBP, static, at least 128×128, square, at most 256 KB. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"assets/icon.png"` |
| `engines` | object | yes | 1.4.160 | Host versions this plugin supports. Older hosts refuse to load it. |
| `engines.orca` | string | yes | 1.4.160 | Oldest Orca release this plugin runs on, as `>=x.y.z`. Raise it to the newest "Since" of any field you use; a format 2 manifest needs at least `>=1.4.245`, because older Orca cannot read format 2. Example: `">=1.4.245"` |
| `main` | string | no | 1.4.160 | Node entry run in an out-of-process plugin worker: a `.js`/`.mjs` module, or a `.ts`/`.mts` module that Orca transpiles when it loads (needs `engines.orca` `>=1.4.246`). Requires the `trusted-worker` execution profile, and is required by it, by `contributes.events`, by `contributes.hooks` and by any command without an `action`. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"dist/main.mjs"` |
| `contributes` | object | no | 1.4.160 | What the plugin adds to Orca. Every point defaults to empty. |
| `contributes.panels` | [PanelContribution](#panelcontribution)[] | no | 1.4.160 | Sidebar panels. At most 64. |
| `contributes.commands` | [CommandContribution](#commandcontribution)[] | no | 1.4.160 | Command palette entries. At most 256. |
| `contributes.events` | [EventContribution](#eventcontribution)[] | no | 1.4.160 | Events delivered to the plugin worker. At most 5. |
| `contributes.hooks` | [HookContribution](#hookcontribution)[] | no | 1.4.248 | Hooks the worker runs before or after Orca acts; Orca waits only on plugins that list one. At most 8. |
| `contributes.languagePacks` | [LanguagePackContribution](#languagepackcontribution)[] | no | 1.4.160 | Interface translations. At most 16. |
| `contributes.keybindings` | [KeybindingContribution](#keybindingcontribution)[] | no | 1.4.160 | Keyboard shortcuts for contributed commands. At most 256. |
| `contributes.vmRecipes` | [VmRecipeContribution](#vmrecipecontribution)[] | no | 1.4.160 | Virtual machine environment recipes. At most 64. |
| `contributes.themes` | [ThemeContribution](#themecontribution)[] | no | 1.4.245 | App color themes. At most 64. |
| `contributes.terminalThemes` | [ThemeContribution](#themecontribution)[] | no | 1.4.245 | Terminal ANSI palettes. At most 64. |
| `contributes.iconThemes` | [ThemeContribution](#themecontribution)[] | no | 1.4.245 | File icon themes. At most 32. |
| `contributes.fonts` | [FontContribution](#fontcontribution)[] | no | 1.4.253 | Font families for the terminal, editor and interface font pickers. At most 8. |
| `contributes.syntaxes` | [SyntaxContribution](#syntaxcontribution)[] | no | 1.4.245 | Syntax highlighting for editor languages. At most 16. |
| `contributes.customEditors` | [CustomEditorContribution](#customeditorcontribution)[] | no | 1.4.245 | Editors that open files of given types in the editor tab. At most 16. |
| `contributes.newFiles` | [NewFileContribution](#newfilecontribution)[] | no | 1.4.245 | Untitled files the user can create from the + menu and the command palette. At most 16. |
| `contributes.settings` | [SettingContribution](#settingcontribution)[] | no | 1.4.246 | Settings Orca shows under the plugin in Settings; code reads them with `settings.get` (`settings:own`). At most 64. |
| `contributes.statusBarItems` | [StatusBarItemContribution](#statusbaritemcontribution)[] | no | 1.4.248 | Items in the status bar; pressing one runs its `command`, and a worker changes them with `statusBar.update`. With `main`, the worker runs for as long as the plugin is enabled. At most 8. |
| `contributes.agentHarnesses` | any[] | no | 1.4.245 | Reserved for coding-agent harness definitions; must be empty until their format is defined. |
| `contributes.skills` | any[] | no | 1.4.245 | Reserved for agent skills; must be empty until their format is defined. |
| `contributes.mcpServers` | any[] | no | 1.4.245 | Reserved for MCP server definitions; must be empty until their format is defined. |
| `contributes.taskSources` | any[] | no | 1.4.245 | Reserved for task sources; must be empty until their format is defined. |
| `contributes.connections` | any[] | no | 1.4.245 | Reserved for account connections; must be empty until their format is defined. |
| `contributes.sidebarCards` | any[] | no | 1.4.245 | Reserved for sidebar cards; must be empty until their format is defined. |
| `capabilities` | [Capability](#capability)[] | no | 1.4.160 | Host APIs the plugin asks the user to grant. At most 32. |
| `cover` | object | no | 1.4.245 | Wide image at the top of the plugin page. |
| `cover.path` | string | yes | 1.4.245 | Cover image shown on the plugin page, 16:10 recommended (1600×1000). PNG, JPEG, WEBP, static, at least 800×500, at most 1024 KB. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"images/cover.png"` |
| `cover.alt` | string | yes | 1.4.245 | What the image shows, for screen readers. Required. Example: `"The Dusk theme on a terminal"` |
| `screenshots` | [Screenshot](#screenshot)[] | no | 1.4.245 | Screenshots for the plugin page, at most 6. All images together may be at most 8 MB. |
| `pluginApi` | `1` | no | 1.4.160 | Major version of the plugin host API this plugin targets. Optional (defaults to 1), and refused on `data` and `declarative` plugins, which never call it. |
## PanelContribution
A sidebar panel. Requires the `sandboxed-ui` execution profile or higher.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | 1.4.160 | Panel id, unique among this plugin's panels. The reserved names `constructor` and `prototype` are refused. Example: `"dashboard"` |
| `title` | string | yes | 1.4.160 | Title shown on the panel tab and its tooltip. Example: `"Dashboard"` |
| `icon` | `"activity"` \| `"bar-chart-3"` \| `"bell"` \| `"blocks"` \| `"book"` \| `"bot"` \| `"bug"` \| `"calendar"` \| `"cloud"` \| `"code"` \| `"database"` \| `"file-text"` \| `"flag"` \| `"folder"` \| `"gauge"` \| `"globe"` \| `"hammer"` \| `"layers"` \| `"lightbulb"` \| `"package"` \| `"plug"` \| `"puzzle"` \| `"rocket"` \| `"star"` \| `"terminal"` \| `"wrench"` \| `"zap"` \| `"add"` \| `"remove"` \| `"delete"` \| `"edit"` \| `"refresh"` \| `"search"` \| `"settings"` \| `"check"` \| `"close"` \| `"info"` \| `"warning"` \| `"error"` \| `"open-external"` \| `"copy"` \| `"download"` \| `"upload"` \| `"play"` \| `"pause"` \| `"stop"` \| `"more"` \| `"expand"` \| `"collapse"` \| `"next"` \| `"filter"` \| `"branch"` \| `"file"` \| `"agent"` \| `"link"` | no | 1.4.160 | Icon shown in the right-sidebar activity bar. Defaults to `plug`. Example: `"database"` |
| `entry` | string | yes | 1.4.160 | What the panel runs: an HTML page for `ui: "html"`, a `.js`/`.mjs` module for `ui: "components"`. Either may instead be a `.ts`/`.tsx`/`.mts`/`.jsx` file, which Orca transpiles when it loads (needs `engines.orca` `>=1.4.246`; an `html` panel then gets a generated page around it). It is trusted code: install panels you trust. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"dist/panel.html"` |
| `ui` | `"html"` \| `"components"` | no | 1.4.246 | How the panel draws its UI. `html` (default) shows `entry` as a web page in an isolated frame; `components` runs `entry` as a hidden module and Orca draws the component tree it returns with its own controls. Example: `"components"` |
## CommandContribution
A command palette entry. Requires the `declarative` execution profile or higher.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | 1.4.160 | Command id, unique among this plugin's commands. Dotted namespaces are allowed. Example: `"jupyter.restartKernel"` |
| `title` | string | yes | 1.4.160 | Title shown in the command palette. Example: `"Restart kernel"` |
| `when` | `"global"` \| `"workspace"` | no | 1.4.160 | Where the command is available. `workspace` hides it when no workspace is active. Defaults to `global`. |
| `action` | `"worktree.history.back"` \| `"worktree.history.forward"` \| `"sidebar.left.toggle"` \| `"sidebar.sleepingWorkspaces.toggle"` \| `"floatingWorkspace.maximize"` \| `"tab.rename"` \| `"workspace.rename"` \| `"workspace.openBoard"` \| `"view.tasks"` \| `"sidebar.right.toggle"` \| `"sidebar.explorer.toggle"` \| `"sidebar.search.toggle"` \| `"sidebar.sourceControl.toggle"` \| `"sidebar.checks.toggle"` \| `"sidebar.ports.toggle"` | no | 1.4.160 | Built-in Orca action this command runs. A command with an action is declarative and never starts the plugin worker; one without needs `main`. Example: `"view.tasks"` |
| `replaces` | `"worktree.history.back"` \| `"worktree.history.forward"` \| `"sidebar.left.toggle"` \| `"sidebar.sleepingWorkspaces.toggle"` \| `"floatingWorkspace.maximize"` \| `"tab.rename"` \| `"workspace.rename"` \| `"workspace.openBoard"` \| `"view.tasks"` \| `"sidebar.right.toggle"` \| `"sidebar.explorer.toggle"` \| `"sidebar.search.toggle"` \| `"sidebar.sourceControl.toggle"` \| `"sidebar.checks.toggle"` \| `"sidebar.ports.toggle"` | no | 1.4.248 | Built-in Orca action this worker command runs in place of, from its shortcut, the palette or a menu. To also run Orca’s own, the command calls `commands.run` with the action (`workspace:write`); that never reaches a replacement. If the worker fails or takes over 2 s, Orca runs its own. The person sees it before approving and can turn it off in Settings; when two plugins replace one action, the one installed first does. Example: `"view.tasks"` |
## EventContribution
An event subscription. Requires `main`, the `trusted-worker` execution profile and the capability of the event's domain: `workspace:read` for workspace events, `agent:read` for agent events. Editor events need no capability.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `on` | `"workspace.created"` \| `"workspace.removed"` \| `"agent.status.changed"` \| `"workspace.changed"` \| `"editor.typography.changed"` | yes | 1.4.160 | Event delivered to the plugin worker. |
## HookContribution
A hook Orca runs through the worker before (or after) it acts. Requires `main` and the `trusted-worker` execution profile.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `event` | `"terminal.send"` \| `"workspace.create.before"` \| `"workspace.create.after"` \| `"agent.launch.before"` \| `"agent.prompt.before"` \| `"agent.tool.before"` \| `"agent.tool.after"` \| `"editor.save.before"` | yes | 1.4.248 | Hook the worker handles with `orca.hooks.on`. |
| `onError` | `"pass"` \| `"deny"` | no | 1.4.248 | What Orca does when this plugin's hook throws, times out, crashes or does not start: `pass` (the default) carries on as if it passed; `deny` refuses the action, naming the plugin, so a guard fails closed. Ignored for hooks that only observe. |
## LanguagePackContribution
An interface translation.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `locale` | string | yes | 1.4.160 | BCP 47 locale the pack translates Orca into. Each locale appears once, ignoring case. Example: `"pt-BR"` |
| `path` | string | yes | 1.4.160 | JSON file of translated interface strings. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"locales/pt-BR.json"` |
| `displayName` | string | no | 1.4.245 | Native-language name for the Settings picker. Omitted packs show `{locale} — {pluginKey}`. Example: `"Português (Brasil)"` |
## KeybindingContribution
A keyboard shortcut for a command.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `command` | string | yes | 1.4.160 | Id of a command this plugin contributes in `contributes.commands`. Example: `"jupyter.restartKernel"` |
| `key` | string | yes | 1.4.160 | Key chord Orca recognizes, such as `Mod+Shift+K`. `Mod` is Cmd on macOS and Ctrl elsewhere. Each chord may be bound once on every platform. Example: `"Mod+Shift+K"` |
| `when` | `"global"` \| `"workspace"` | no | 1.4.160 | Where the shortcut is active; must match its command's `when`. |
## VmRecipeContribution
A virtual machine environment recipe.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `path` | string | yes | 1.4.160 | JSON environment recipe file, listed once. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"recipes/ubuntu.json"` |
## ThemeContribution
A titled theme file.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | 1.4.245 | Theme id, unique within its family in this plugin. The reserved names `constructor` and `prototype` are refused. Example: `"dusk"` |
| `title` | string | yes | 1.4.245 | Name shown in the theme picker. Example: `"Dusk"` |
| `path` | string | yes | 1.4.245 | JSON theme file, at most 16 KiB. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"themes/dusk.json"` |
## FontContribution
A font family the user can pick for the terminal, editor or interface. It applies only once picked.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `family` | string | yes | 1.4.253 | Family name shown in the font pickers. Orca adds the plugin id, so a plugin font never replaces an installed or built-in font of the same name. Example: `"Geist"` |
| `faces` | [FontFaceContribution](#fontfacecontribution)[] | yes | 1.4.253 | The family's files, at most 8. All of a plugin's font files together may be at most 8 MB. |
## FontFaceContribution
One file of a font family.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `path` | string | yes | 1.4.253 | WOFF or WOFF2 file, at most 2 MB; its first bytes must match its extension. TTF, OTF and font collections are refused. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"fonts/Geist-Variable.woff2"` |
| `weight` | string | no | 1.4.253 | CSS weight this file draws, or a range for a variable font. Defaults to `400`. Example: `"400"` |
| `style` | `"normal"` \| `"italic"` | no | 1.4.253 | Whether this file is the italic face. Defaults to `normal`. |
## SyntaxContribution
Syntax highlighting for one language.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | 1.4.245 | Language id, unique among this plugin's syntaxes. The reserved names `constructor` and `prototype` are refused. Example: `"gleam"` |
| `title` | string | yes | 1.4.245 | Language name shown in the editor. Example: `"Gleam"` |
| `scopeName` | string | yes | 1.4.245 | The grammar's root TextMate scope, unique among this plugin's syntaxes. Example: `"source.gleam"` |
| `path` | string | yes | 1.4.245 | TextMate grammar JSON file. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"syntaxes/gleam.tmLanguage.json"` |
| `configuration` | string | no | 1.4.245 | Language configuration JSON file: comments, brackets and auto-closing pairs. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"syntaxes/language-configuration.json"` |
| `extensions` | string[] | no | 1.4.245 | File-name suffixes, with the dot, this language opens, ignoring case. A longer suffix such as `.excalidraw.json` wins over a shorter one, and a file named only the suffix never matches. At most 32. Example: `[".gleam"]` |
| `filenames` | string[] | no | 1.4.245 | Exact file names this language opens, ignoring case; a name beats any extension. Names must be portable: no path separators, `.`, `..` or characters Windows forbids. At most 32. Example: `["gleam.toml"]` |
## CustomEditorContribution
An editor for the listed files, shown in the editor tab beside Source. It must list at least one extension or file name. Requires the `sandboxed-ui` execution profile or higher.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | 1.4.245 | Editor id, unique among this plugin's custom editors. The reserved names `constructor` and `prototype` are refused. Example: `"excalidraw"` |
| `title` | string | yes | 1.4.245 | Name shown in the editor's view toggle beside Source, and on the tab of a file it opens. Example: `"Excalidraw"` |
| `icon` | string | no | 1.4.245 | Square image shown on the tab of a file this editor opens. Defaults to the plugin icon. PNG, WEBP, static, at least 128×128, square, at most 256 KB. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"images/editor-icon.png"` |
| `extensions` | string[] | no | 1.4.245 | File-name suffixes, with the dot, this editor opens, ignoring case. A longer suffix such as `.excalidraw.json` wins over a shorter one, and a file named only the suffix never matches. At most 32. Example: `[".excalidraw",".excalidraw.json"]` |
| `filenames` | string[] | no | 1.4.245 | Exact file names this editor opens, ignoring case; a name beats any extension. Names must be portable: no path separators, `.`, `..` or characters Windows forbids. At most 32. Example: `[]` |
| `entry` | string | yes | 1.4.245 | HTML file rendered inside an editor frame, like a panel, or a `.ts`/`.tsx` module that Orca transpiles and loads in a generated page (needs `engines.orca` `>=1.4.246`). It receives the open document and posts edits back; it never gets a file path or file system. It is trusted code: install editors you trust. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"editor/index.html"` |
| `priority` | `"default"` \| `"option"` | no | 1.4.245 | `default` (the default) opens matching files in this editor; `option` only offers it in the view toggle, so files open in Source. Files Orca opens itself (such as `.json`, `.ts`, `.md`, `.csv`, `.yaml`, lockfiles and `.env` files) always behave as `option`; a longer suffix such as `.sketch.json` is not one of them and opens by default. Example: `"default"` |
| `contentKind` | `"text"` \| `"bytes"` | no | 1.4.245 | `text` (the default) sends the file as text and accepts full-text edits. `bytes` sends the file's raw bytes, for binary formats such as spreadsheets, and accepts full-byte edits. Example: `"bytes"` |
| `frame` | `"any"` \| `"isolated"` | no | 1.4.248 | `any` (the default) runs in whatever frame the client gives. `isolated` runs only in the desktop app's isolated frame, never the browser-client fallback: browser clients, and desktop with isolated frames switched off, open the file in Source with a notice that the editor needs the Orca desktop app. Example: `"isolated"` |
## NewFileContribution
A kind of untitled file the user can create from the tab bar + menu or the command palette, in the active workspace.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | 1.4.245 | New-file id, unique among this plugin's new files. The reserved names `constructor` and `prototype` are refused. Example: `"drawing"` |
| `title` | string | yes | 1.4.245 | Menu item shown in the tab bar + menu and the command palette. Example: `"New Excalidraw drawing"` |
| `extension` | string | yes | 1.4.245 | Suffix, with the dot, of the untitled file it creates. The file opens in whatever editor takes that suffix, such as a custom editor from this plugin. Example: `".excalidraw"` |
| `template` | string | no | 1.4.245 | UTF-8 file copied into the new file, at most 256 KB. Without one the file starts empty. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"templates/empty.excalidraw"` |
| `icon` | string | no | 1.4.245 | Square image shown beside the menu item. Defaults to the plugin icon. PNG, WEBP, static, at least 128×128, square, at most 256 KB. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"images/editor-icon.png"` |
## SettingContribution
A setting shown under the plugin in Settings. Requires the `settings:own` capability, which is also how code reads it.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `key` | string | yes | 1.4.246 | Key code reads and writes, unique in this plugin. Example: `"apiUrl"` |
| `title` | string | yes | 1.4.246 | Label shown in Settings. Example: `"Server URL"` |
| `description` | string | no | 1.4.246 | Help text shown under the label. |
| `type` | `"string"` \| `"number"` \| `"integer"` \| `"boolean"` | yes | 1.4.246 | JSON Schema type of the value. Example: `"string"` |
| `default` | string \| number \| boolean | no | 1.4.246 | Value read while the person has not set one. |
| `enum` | (string \| number)[] | no | 1.4.246 | Allowed values; Settings shows a picker. |
| `enumLabels` | string[] | no | 1.4.246 | Picker labels, one per `enum` value. |
| `minimum` | number | no | 1.4.246 | Numbers: smallest value. |
| `maximum` | number | no | 1.4.246 | Numbers: largest value. |
| `maxLength` | integer | no | 1.4.246 | Strings: most characters. |
| `multiline` | boolean | no | 1.4.246 | Strings: a multi-line text box. |
| `placeholder` | string | no | 1.4.246 | Strings and numbers: hint shown while empty. |
## StatusBarItemContribution
An item in the status bar. Requires the `declarative` profile; a `trusted-worker` can change it with `statusBar.update`.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `id` | string | yes | 1.4.248 | Item id, unique among this plugin's status bar items; `statusBar.update` names it. Example: `"blocked-count"` |
| `text` | string | no | 1.4.248 | Short label shown in the status bar. Example: `"3 blocked"` |
| `icon` | `"activity"` \| `"bar-chart-3"` \| `"bell"` \| `"blocks"` \| `"book"` \| `"bot"` \| `"bug"` \| `"calendar"` \| `"cloud"` \| `"code"` \| `"database"` \| `"file-text"` \| `"flag"` \| `"folder"` \| `"gauge"` \| `"globe"` \| `"hammer"` \| `"layers"` \| `"lightbulb"` \| `"package"` \| `"plug"` \| `"puzzle"` \| `"rocket"` \| `"star"` \| `"terminal"` \| `"wrench"` \| `"zap"` \| `"add"` \| `"remove"` \| `"delete"` \| `"edit"` \| `"refresh"` \| `"search"` \| `"settings"` \| `"check"` \| `"close"` \| `"info"` \| `"warning"` \| `"error"` \| `"open-external"` \| `"copy"` \| `"download"` \| `"upload"` \| `"play"` \| `"pause"` \| `"stop"` \| `"more"` \| `"expand"` \| `"collapse"` \| `"next"` \| `"filter"` \| `"branch"` \| `"file"` \| `"agent"` \| `"link"` | no | 1.4.248 | Icon shown before the text, from the panel icon set. Example: `"bell"` |
| `tone` | `"neutral"` \| `"accent"` \| `"success"` \| `"warning"` \| `"danger"` | no | 1.4.248 | Colour of the item. Defaults to `neutral`. Example: `"warning"` |
| `tooltip` | string | no | 1.4.248 | Shown on hover. Defaults to the plugin name. |
| `command` | string | no | 1.4.248 | Id of a command this plugin contributes in `contributes.commands`, run when the item is pressed. Example: `"guard.showLog"` |
## Capability
A host API the plugin may call once the user consents.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `kind` | `"workspace:read"` \| `"workspace:write"` \| `"agent:read"` \| `"agent:launch"` \| `"terminal:send"` \| `"terminal:read"` \| `"notifications:show"` \| `"storage:own"` \| `"secrets:own"` \| `"settings:own"` \| `"appearance:write"` \| `"workspace:create"` \| `"automation:read"` \| `"automation:write"` \| `"history:read"` | yes | 1.4.160 | Capability granted on user consent. |
## Screenshot
One screenshot of the plugin in use.
| Field | Type | Required | Since | Description |
| --- | --- | --- | --- | --- |
| `path` | string | yes | 1.4.245 | Screenshot, 16:10 recommended (up to 2560×1600). PNG, JPEG, WEBP, static, at least 1280×800, at most 1536 KB. Relative to the plugin root; `..` segments and Windows device names such as `CON` are refused. Example: `"images/editor.png"` |
| `alt` | string | yes | 1.4.245 | What the image shows, for screen readers. Required. Example: `"The Dusk theme on a terminal"` |
| `caption` | string | no | 1.4.245 | Short caption under the screenshot. Example: `"Gleam in the editor"` |
| `theme` | `"light"` \| `"dark"` | no | 1.4.245 | Show this screenshot only with a light or dark Orca theme. |
## Versions and compatibility
- **What runs is strict.** Orca refuses a manifest with any key it does not know, at every level, so an older Orca never silently ignores something a plugin relies on.
- **`engines.orca` is the only version gate.** It must be at least the newest `Since` of every field and every value (capability, event, built-in action) the manifest uses. `pnpm validate:plugin` and catalog CI enforce it, so an older Orca can always say "requires Orca >=X (this is Y)" instead of listing unknown fields.
- **`pluginApi` is optional.** It names the major version of the host API ([reference](plugin-host-api.md)), which only grows within major 1; Orca refuses a major it does not implement. Only `sandboxed-ui` and `trusted-worker` plugins call that API, so `data` and `declarative` plugins must leave it out.
- **`terminal:send` needs `trusted-worker`.** Panels get no host method that types into a terminal, so Orca refuses the capability on any other profile instead of asking the user to grant something the plugin can never use.
- **New fields, contribution points and values are additive.** They arrive with a `Since` version; nothing else changes. `manifestVersion` rises only if an existing field changes meaning.
- **Deprecation.** A field to be removed is marked deprecated here and keeps working for at least one release; it is removed only together with a higher `engines.orca` requirement, and its name is never reused.
- **Reserved contribution points.** `contributes.agentHarnesses`, `skills`, `mcpServers`, `taskSources`, `connections` and `sidebarCards` are held for planned features and must stay empty until their format is defined. Each will arrive as an additive point with its own `Since`, without a new manifest format. `skills` and `mcpServers` keep the meaning agent-plugin formats such as Claude Code's give them; `agents` stays unclaimed because those formats use it for subagent files.
## Planned contribution points
Each reserved point is planned as declared data that Orca renders and enforces, never arbitrary plugin UI. The intended shapes, which may still change:
- `taskSources`: Issue and task providers such as Asana, Linear or Jira, declared as data that a worker fills with tasks.
- `connections`: Account providers with a host-run sign-in, so a plugin never handles credentials itself.
- `agentHarnesses`: New coding-agent harnesses described as data: how to launch them and read their status.
- `sidebarCards`: Declarative left-sidebar cards with fixed layouts whose values a worker updates.
- `mcpServers`: MCP server definitions that Orca offers to the agents it launches.
- `skills`: Agent skills shipped as files that Orca installs for the agents it launches.
## Legacy format 1
Orca still loads `"manifestVersion": 1` manifests (read since 1.4.160), but new plugins should use format 2. Format 1 differs in three ways:
- It has no `execution` field. Orca derives the least profile that can run what the manifest declares.
- Unknown top-level keys are ignored instead of rejected.
- The published JSON Schema does not describe it, so editors offer no completion for it.
Reference in New Issue View Git Blame Copy Permalink