Files
codex/codex-rs/app-server-protocol/schema/json/v2/PluginListResponse.json
T
victor-openai a1f40f3f13 Expose hosted plugin extensions in app-server summaries (#47263)
## What changed

- Request installed-plugin metadata with `includeExtensions=true` and carry optional `extensions` through the cache into `PluginSummary`.
- Add typed declarations for global, settings, thread, and file entrypoints, quick actions, settings tools, icons, and search mention providers. Update JSON schemas and TypeScript and Python bindings.
- Accept supported snake_case aliases and emit camelCase fields. Discard incompatible extension declarations without invalidating the installed-plugin inventory.

## Testing

Add an integration test covering extension metadata preservation, field normalization, and unknown entrypoint and quick-action types across live and cached `plugin/installed` reads. Update pagination assertions to require `includeExtensions=true`.

GitOrigin-RevId: b73b0d13c151a30dc1fb9cda70b5cd6d7e3e2441
2026-09-22 11:29:58 +00:00

1056 lines
24 KiB
JSON
Generated

{
"$schema": "http://json-schema.org/draft-07/schema#",
"definitions": {
"AbsolutePathBuf": {
"description": "A path that is guaranteed to be absolute and normalized (though it is not guaranteed to be canonicalized or exist on the filesystem).\n\nIMPORTANT: When deserializing an `AbsolutePathBuf`, a base path must be set using [AbsolutePathBufGuard::new]. If no base path is set, the deserialization will fail unless the path being deserialized is already absolute.",
"type": "string"
},
"MarketplaceInterface": {
"properties": {
"displayName": {
"type": [
"string",
"null"
]
}
},
"type": "object"
},
"MarketplaceLoadErrorInfo": {
"properties": {
"marketplacePath": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"message": {
"type": "string"
}
},
"required": [
"marketplacePath",
"message"
],
"type": "object"
},
"PluginAuthPolicy": {
"enum": [
"ON_INSTALL",
"ON_USE"
],
"type": "string"
},
"PluginAvailability": {
"oneOf": [
{
"enum": [
"DISABLED_BY_ADMIN"
],
"type": "string"
},
{
"description": "Plugin-service currently sends `\"ENABLED\"` for available remote plugins. Codex app-server exposes `\"AVAILABLE\"` in its API; the alias keeps decoding compatible with that upstream response.",
"enum": [
"AVAILABLE"
],
"type": "string"
}
]
},
"PluginDisabledReason": {
"enum": [
"disabled_by_admin",
"plan_not_eligible",
"required_app_unavailable",
"unknown"
],
"type": "string"
},
"PluginEntrypoint": {
"oneOf": [
{
"properties": {
"appId": {
"type": "string"
},
"icons": {
"items": {
"$ref": "#/definitions/PluginIcon"
},
"type": "array"
},
"quickAction": {
"anyOf": [
{
"$ref": "#/definitions/PluginQuickAction"
},
{
"type": "null"
}
],
"default": null
},
"resourceUri": {
"type": "string"
},
"title": {
"type": "string"
},
"toolName": {
"type": "string"
},
"type": {
"enum": [
"global"
],
"title": "GlobalPluginEntrypointType",
"type": "string"
}
},
"required": [
"appId",
"icons",
"resourceUri",
"title",
"toolName",
"type"
],
"title": "GlobalPluginEntrypoint",
"type": "object"
},
{
"properties": {
"appId": {
"type": "string"
},
"icons": {
"items": {
"$ref": "#/definitions/PluginIcon"
},
"type": "array"
},
"resourceUri": {
"type": "string"
},
"searchTerms": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"title": {
"type": "string"
},
"toolName": {
"type": "string"
},
"type": {
"enum": [
"settings"
],
"title": "SettingsPluginEntrypointType",
"type": "string"
}
},
"required": [
"appId",
"icons",
"resourceUri",
"title",
"toolName",
"type"
],
"title": "SettingsPluginEntrypoint",
"type": "object"
},
{
"properties": {
"appId": {
"type": "string"
},
"icons": {
"items": {
"$ref": "#/definitions/PluginIcon"
},
"type": "array"
},
"resourceUri": {
"type": "string"
},
"title": {
"type": "string"
},
"toolName": {
"type": "string"
},
"type": {
"enum": [
"thread"
],
"title": "ThreadPluginEntrypointType",
"type": "string"
}
},
"required": [
"appId",
"icons",
"resourceUri",
"title",
"toolName",
"type"
],
"title": "ThreadPluginEntrypoint",
"type": "object"
},
{
"properties": {
"appId": {
"type": "string"
},
"extensions": {
"items": {
"type": "string"
},
"type": "array"
},
"icons": {
"items": {
"$ref": "#/definitions/PluginIcon"
},
"type": "array"
},
"resourceUri": {
"type": "string"
},
"title": {
"type": "string"
},
"toolName": {
"type": "string"
},
"type": {
"enum": [
"file"
],
"title": "FilePluginEntrypointType",
"type": "string"
}
},
"required": [
"appId",
"extensions",
"icons",
"resourceUri",
"title",
"toolName",
"type"
],
"title": "FilePluginEntrypoint",
"type": "object"
}
]
},
"PluginExtensions": {
"properties": {
"entrypoints": {
"default": null,
"items": {
"$ref": "#/definitions/PluginEntrypoint"
},
"type": [
"array",
"null"
]
},
"fileHandlers": {
"default": [],
"items": {
"$ref": "#/definitions/PluginEntrypoint"
},
"type": "array"
},
"searchMentionProviders": {
"default": [],
"items": {
"$ref": "#/definitions/PluginSearchProvider"
},
"type": "array"
},
"settings": {
"default": [],
"items": {
"$ref": "#/definitions/PluginSettings"
},
"type": "array"
},
"settingsEntrypoints": {
"default": [],
"items": {
"$ref": "#/definitions/PluginEntrypoint"
},
"type": "array"
},
"threadEntrypoints": {
"default": [],
"items": {
"$ref": "#/definitions/PluginEntrypoint"
},
"type": "array"
}
},
"type": "object"
},
"PluginIcon": {
"properties": {
"mimeType": {
"type": [
"string",
"null"
]
},
"sizes": {
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"src": {
"type": "string"
},
"theme": {
"type": [
"string",
"null"
]
}
},
"required": [
"src"
],
"type": "object"
},
"PluginInstallPolicy": {
"enum": [
"NOT_AVAILABLE",
"AVAILABLE",
"INSTALLED_BY_DEFAULT"
],
"type": "string"
},
"PluginInstallPolicySource": {
"enum": [
"WORKSPACE_SETTING",
"IMPLICIT_CANONICAL_APP"
],
"type": "string"
},
"PluginInterface": {
"properties": {
"brandColor": {
"type": [
"string",
"null"
]
},
"capabilities": {
"items": {
"type": "string"
},
"type": "array"
},
"category": {
"type": [
"string",
"null"
]
},
"composerIcon": {
"anyOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
},
{
"type": "null"
}
],
"description": "Local composer icon path, resolved from the installed plugin package."
},
"composerIconUrl": {
"description": "Remote composer icon URL from the plugin catalog.",
"type": [
"string",
"null"
]
},
"defaultPrompt": {
"description": "Starter prompts for the plugin. Capped at 3 entries with a maximum of 128 characters per entry.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"developerName": {
"type": [
"string",
"null"
]
},
"displayName": {
"type": [
"string",
"null"
]
},
"logo": {
"anyOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
},
{
"type": "null"
}
],
"description": "Local logo path, resolved from the installed plugin package."
},
"logoDark": {
"anyOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
},
{
"type": "null"
}
],
"description": "Local dark-mode logo path, resolved from the installed plugin package."
},
"logoUrl": {
"description": "Remote logo URL from the plugin catalog.",
"type": [
"string",
"null"
]
},
"logoUrlDark": {
"description": "Remote dark-mode logo URL from the plugin catalog.",
"type": [
"string",
"null"
]
},
"longDescription": {
"type": [
"string",
"null"
]
},
"privacyPolicyUrl": {
"type": [
"string",
"null"
]
},
"screenshotUrls": {
"description": "Remote screenshot URLs from the plugin catalog.",
"items": {
"type": "string"
},
"type": "array"
},
"screenshots": {
"description": "Local screenshot paths, resolved from the installed plugin package.",
"items": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": "array"
},
"shortDescription": {
"type": [
"string",
"null"
]
},
"termsOfServiceUrl": {
"type": [
"string",
"null"
]
},
"websiteUrl": {
"type": [
"string",
"null"
]
}
},
"required": [
"capabilities",
"screenshotUrls",
"screenshots"
],
"type": "object"
},
"PluginMarketplaceEntry": {
"properties": {
"interface": {
"anyOf": [
{
"$ref": "#/definitions/MarketplaceInterface"
},
{
"type": "null"
}
]
},
"name": {
"type": "string"
},
"path": {
"anyOf": [
{
"$ref": "#/definitions/AbsolutePathBuf"
},
{
"type": "null"
}
],
"description": "Local marketplace file path when the marketplace is backed by a local file. Remote-only catalog marketplaces do not have a local path."
},
"plugins": {
"items": {
"$ref": "#/definitions/PluginSummary"
},
"type": "array"
}
},
"required": [
"name",
"plugins"
],
"type": "object"
},
"PluginQuickAction": {
"properties": {
"icons": {
"items": {
"$ref": "#/definitions/PluginIcon"
},
"type": "array"
},
"target": {
"$ref": "#/definitions/PluginQuickActionTarget"
},
"title": {
"type": "string"
}
},
"required": [
"icons",
"target",
"title"
],
"type": "object"
},
"PluginQuickActionTarget": {
"oneOf": [
{
"properties": {
"arguments": true,
"name": {
"type": "string"
},
"type": {
"enum": [
"tool"
],
"title": "ToolPluginQuickActionTargetType",
"type": "string"
}
},
"required": [
"name",
"type"
],
"title": "ToolPluginQuickActionTarget",
"type": "object"
}
]
},
"PluginSearchProvider": {
"properties": {
"appId": {
"type": "string"
},
"call": {
"anyOf": [
{
"$ref": "#/definitions/PluginSearchProviderCall"
},
{
"type": "null"
}
]
},
"linkId": {
"type": "string"
},
"title": {
"type": "string"
},
"toolName": {
"type": "string"
}
},
"required": [
"appId",
"linkId",
"title",
"toolName"
],
"type": "object"
},
"PluginSearchProviderCall": {
"properties": {
"_meta": true,
"arguments": true,
"name": {
"type": "string"
}
},
"required": [
"_meta",
"arguments",
"name"
],
"type": "object"
},
"PluginSettings": {
"properties": {
"appId": {
"type": "string"
},
"readToolName": {
"type": "string"
},
"updateToolName": {
"type": "string"
}
},
"required": [
"appId",
"readToolName",
"updateToolName"
],
"type": "object"
},
"PluginShareContext": {
"properties": {
"canPublishToWorkspace": {
"default": null,
"type": [
"boolean",
"null"
]
},
"creatorAccountUserId": {
"type": [
"string",
"null"
]
},
"creatorName": {
"type": [
"string",
"null"
]
},
"discoverability": {
"anyOf": [
{
"$ref": "#/definitions/PluginShareDiscoverability"
},
{
"type": "null"
}
]
},
"remotePluginId": {
"type": "string"
},
"remoteVersion": {
"default": null,
"description": "Version of the remote shared plugin release when available.",
"type": [
"string",
"null"
]
},
"sharePrincipals": {
"items": {
"$ref": "#/definitions/PluginSharePrincipal"
},
"type": [
"array",
"null"
]
},
"shareUrl": {
"type": [
"string",
"null"
]
}
},
"required": [
"remotePluginId"
],
"type": "object"
},
"PluginShareDiscoverability": {
"enum": [
"LISTED",
"UNLISTED",
"PRIVATE"
],
"type": "string"
},
"PluginSharePrincipal": {
"properties": {
"name": {
"type": "string"
},
"principalId": {
"type": "string"
},
"principalType": {
"$ref": "#/definitions/PluginSharePrincipalType"
},
"role": {
"$ref": "#/definitions/PluginSharePrincipalRole"
}
},
"required": [
"name",
"principalId",
"principalType",
"role"
],
"type": "object"
},
"PluginSharePrincipalRole": {
"enum": [
"reader",
"editor",
"owner"
],
"type": "string"
},
"PluginSharePrincipalType": {
"enum": [
"user",
"group",
"workspace"
],
"type": "string"
},
"PluginSource": {
"oneOf": [
{
"properties": {
"path": {
"$ref": "#/definitions/AbsolutePathBuf"
},
"type": {
"enum": [
"local"
],
"title": "LocalPluginSourceType",
"type": "string"
}
},
"required": [
"path",
"type"
],
"title": "LocalPluginSource",
"type": "object"
},
{
"properties": {
"path": {
"type": [
"string",
"null"
]
},
"refName": {
"type": [
"string",
"null"
]
},
"sha": {
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"git"
],
"title": "GitPluginSourceType",
"type": "string"
},
"url": {
"type": "string"
}
},
"required": [
"type",
"url"
],
"title": "GitPluginSource",
"type": "object"
},
{
"properties": {
"package": {
"type": "string"
},
"registry": {
"description": "Optional HTTPS registry URL. Authentication stays in the user's npm config.",
"type": [
"string",
"null"
]
},
"type": {
"enum": [
"npm"
],
"title": "NpmPluginSourceType",
"type": "string"
},
"version": {
"description": "Optional npm version or version range.",
"type": [
"string",
"null"
]
}
},
"required": [
"package",
"type"
],
"title": "NpmPluginSource",
"type": "object"
},
{
"description": "The plugin is available in the remote catalog. Download metadata is kept server-side and is not exposed through the app-server API.",
"properties": {
"type": {
"enum": [
"remote"
],
"title": "RemotePluginSourceType",
"type": "string"
}
},
"required": [
"type"
],
"title": "RemotePluginSource",
"type": "object"
}
]
},
"PluginSummary": {
"properties": {
"authPolicy": {
"$ref": "#/definitions/PluginAuthPolicy"
},
"availability": {
"allOf": [
{
"$ref": "#/definitions/PluginAvailability"
}
],
"default": "AVAILABLE",
"description": "Availability state for installing and using the plugin."
},
"disabledReason": {
"anyOf": [
{
"$ref": "#/definitions/PluginDisabledReason"
},
{
"type": "null"
}
],
"default": null,
"description": "Why the remote plugin is unavailable, when provided by plugin-service."
},
"eligiblePlanTypes": {
"default": null,
"description": "Raw plugin-service plan identifiers eligible to install the plugin.",
"items": {
"type": "string"
},
"type": [
"array",
"null"
]
},
"enabled": {
"type": "boolean"
},
"extensions": {
"anyOf": [
{
"$ref": "#/definitions/PluginExtensions"
},
{
"type": "null"
}
],
"default": null
},
"id": {
"type": "string"
},
"installPolicy": {
"$ref": "#/definitions/PluginInstallPolicy"
},
"installPolicySource": {
"anyOf": [
{
"$ref": "#/definitions/PluginInstallPolicySource"
},
{
"type": "null"
}
]
},
"installed": {
"type": "boolean"
},
"installedAt": {
"default": null,
"description": "Unix timestamp in seconds when the remote plugin was installed, when available.",
"format": "int64",
"type": [
"integer",
"null"
]
},
"interface": {
"anyOf": [
{
"$ref": "#/definitions/PluginInterface"
},
{
"type": "null"
}
]
},
"keywords": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"localVersion": {
"default": null,
"description": "Version of the locally materialized plugin package when available.",
"type": [
"string",
"null"
]
},
"mustShowInstallationInterstitial": {
"default": null,
"type": [
"boolean",
"null"
]
},
"name": {
"type": "string"
},
"remotePluginId": {
"description": "Backend remote plugin identifier when available.",
"type": [
"string",
"null"
]
},
"shareContext": {
"anyOf": [
{
"$ref": "#/definitions/PluginShareContext"
},
{
"type": "null"
}
],
"description": "Remote sharing context associated with this plugin when available."
},
"source": {
"$ref": "#/definitions/PluginSource"
},
"version": {
"default": null,
"description": "Version advertised by the remote marketplace backend when available.",
"type": [
"string",
"null"
]
}
},
"required": [
"authPolicy",
"enabled",
"id",
"installPolicy",
"installed",
"name",
"source"
],
"type": "object"
}
},
"properties": {
"featuredPluginIds": {
"default": [],
"items": {
"type": "string"
},
"type": "array"
},
"marketplaceLoadErrors": {
"default": [],
"items": {
"$ref": "#/definitions/MarketplaceLoadErrorInfo"
},
"type": "array"
},
"marketplaces": {
"items": {
"$ref": "#/definitions/PluginMarketplaceEntry"
},
"type": "array"
}
},
"required": [
"marketplaces"
],
"title": "PluginListResponse",
"type": "object"
}