feat(kap-server): add plugin marketplace and capability REST routes - #2868
feat(kap-server): add plugin marketplace and capability REST routes#2868wbxl2000 wants to merge 34 commits into
Conversation
CapabilityEntry.install now resolves an optional note exposed through CapabilityInstallProgress.note (wire-visible). The webbridge entry returns 'user-skill-migrated' when it migrates a pre-existing standalone skill copy onto the plugin-managed one — clients can localize the migration instead of the skill silently disappearing from the user's directory.
Expose the App-scope plugin and capability services over the wire so
non-CLI hosts (desktop, web) can manage plugins and built-in
capabilities end to end:
- GET /api/v1/plugins, POST /api/v1/plugins {source},
POST /api/v1/plugins/{id}:{enable,disable,remove}
- GET /api/v1/plugins/marketplace — catalog (pluginMarketplaceUrl
server option / KIMI_CODE_PLUGIN_MARKETPLACE_URL env / production
default) merged on demand with live install state; updateAvailable
only on strict semver catalog > installed (no semver dependency)
- GET /api/v1/capabilities, GET /api/v1/capabilities/{id},
POST /api/v1/capabilities/{id}:install with client-polled progress
- New wire codes 40418 capability.not_found, 40419 plugin.not_found,
40923 capability.install_in_progress, 40924 capability.unsupported
Mutations flow through IPluginService, so they serialize with other
install paths and fire onDidReload (session skill catalogs and the
capability shelf-install hook converge).
|
commit: |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 23812879b4
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…ported test code - mapPluginError now translates the domain's validation.failed (40001) and fs.path_not_found (40409) instead of collapsing client-fixable input mistakes (relative source, nonexistent local path) into a 50001 internal error - the non-macOS capability install test expected 40923, which this branch assigns to capability.install_in_progress; the unsupported code is 40924 (macOS runners skip the case, which is why it only fails on Linux/Windows CI)
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: daf02e7b70
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…en the unsupported-test skip - The production CDN catalog carries sources relative to the catalog URL (./official/*.zip); clients handing them back to POST /plugins would hit the local-path normalizer's 40001. Resolve entry sources against the configured catalog URL so every returned source is directly installable. - The 40924 install-rejection test only skipped macOS, but kimi-cu is also supported on Windows x64 — running it there would start the real installer. Skip on every supported platform.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8adff36d75
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
… aliases Custom catalogs that the CLI already accepts can carry an entry's source under url or downloadUrl instead of source; the route's strict schema rejected the whole catalog with 50001. Normalize the aliases before validation (same precedence as the CLI parser) so those catalogs keep working through /api/v1/plugins/marketplace.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 145cddb966
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…nal spreads - KIMI_CODE_PLUGIN_MARKETPLACE_URL accepts a plain path or file:// catalog in the CLI loader; the route only fetched over HTTP, so local catalogs 50001'd for desktop/web hosts. Read local catalogs from disk and resolve their relative sources against the catalog's directory. - Replace the marketplace mapping's conditional spreads with direct possibly-undefined properties per the repo rule.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 1f9a5744a5
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…:// entry sources - The klient capabilities contract omitted install.note, so zod parsing stripped it and facade callers (node-sdk, TUI) never saw 'user-skill-migrated'. Add the field and pin it in the facade test fixture. - A marketplace entry source given as a file:// URL fell through to the relative-branch and came back as a garbage path; convert with fileURLToPath so the advertised source stays installable.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b4762f4c7d
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
- The capabilities list assertion treated every non-macOS host as unsupported, but kimi-cu is supported on Windows x64 — derive the expectation from the same platform predicate. - file:///abs/... is not a valid absolute file URL on Windows (no drive root); build the fixture with pathToFileURL from a temp path instead.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d964617856
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…ions - agent-core-v2 keeps explanatory docs in the top-of-file block only; the note contract already lives in the capability types header, so drop the two member-level doc blocks. - The plugins route test helper sets the optional fetch body directly instead of via a conditional spread.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6528c8a836
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The CLI loader expands ~/ against the home directory; the route read the path literally, so KIMI_CODE_PLUGIN_MARKETPLACE_URL=~/catalog.json 50001'd for desktop/web hosts while working in the CLI. Share one localCatalogPath helper (file:// conversion + tilde expansion) between the catalog read and the relative-source resolver.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 02328499f4
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
A catalog entry with source '~/...' fell through to the catalog-relative branch and came back as <catalog-dir>/~/... — unresolvable by POST /plugins. Expand ~ via the shared helper before the absolute/relative decision.
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 8ae05103f7
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
The hand-rolled strict x.y.z check rejected valid semver the CLI accepts (v-prefixed, prerelease tags), so updateAvailable diverged between CLI and wire clients. Take the semver package (already in the monorepo via the CLI) for the update check and the two source-derived version validators.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 12178e16df
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…erver as default - Custom catalog rows with an unsupported type (e.g. integration) were stripped by the schema and advertised as installable plugins; the CLI rejects the catalog outright. Model the same plugin/managed/guide vocabulary. - scripts/dev.mjs marks its repo-owned catalog with KIMI_CODE_PLUGIN_MARKETPLACE_FROM_DEV_SERVER=1 — honor the flag in the isDefault check so capability markers and the checkout fallback behave exactly like the CLI under the dev marketplace.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: b6b27d83dc
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…lugin id kimi-cu installs its wiring plugin as kimi-cu-win on Windows x64, so a catalog row keyed kimi-cu never matched the installed record there (no installed state, no updateAvailable). The row mapping now knows each capability's wiring plugin ids and joins through them.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: e9b3708dd8
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
An install source pointing at a directory/zip with a missing or invalid manifest throws plugin.load_failed — a client-fixable input error that fell through to 50001. Map it to validation.failed alongside the other input mistakes.
|
@codex review |
|
Codex Review: Didn't find any major issues. Keep it up! Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
|
@codex review |
|
Codex Review: Didn't find any major issues. Another round soon, please! Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
|
@codex review |
|
Codex Review: Didn't find any major issues. Can't wait for the next one! Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
sherif rejects multiple workspace versions of one dependency; the CLI pins @types/semver at ^7.7.0.
…cross hosts The kap-server marketplace route grew its own copy of the CLI's catalog loading/parsing logic (lenient aliases, blank-means-missing fields, source resolution, GitHub version derivation) — two implementations of a public, hand-writable format would drift on every catalog change. Move the read/parse/version machinery into the plugin domain as app/plugin/marketplace (pure functions, no DI): the CLI keeps a thin wrapper owning configured-source resolution and its checkout fallback, and the route keeps only the wire concerns (install-state merge, capabilityId markers, error envelopes). plugins.ts drops ~230 lines of duplicated machinery. One deliberate behavior fix rides along: tilde entry sources now expand against the home directory at parse time (the CLI previously passed them through literally, failing later at install validation).
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 838094136d
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…he file header The package convention keeps explanatory comments in the top-of-file block only; the moved parser carried several function/member-level JSDoc blocks from its CLI home. The header now carries the format contract, leniency rules, source/version resolution order, built-in masking semantics, and the fallback gating rule.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 4a61e72512
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
…ketplace module The header carries the rationale (update semantics, GitHub ref shapes, the releases/latest choice); the convention allows nothing beside statements.
|
@codex review |
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c89db9ee36
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
constant/app.ts is evaluated on every CLI invocation; re-exporting from the agent-core-v2 root would pull the whole engine module graph into startup. The package's wildcard subpath export lets both CLI files take only the pure marketplace module (node builtins + semver).
|
@codex review |
|
Codex Review: Didn't find any major issues. Can't wait for the next one! Reviewed commit: ℹ️ About Codex in GitHubCodex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
If Codex has suggestions, it will comment; otherwise it will react with 👍. When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback". |
Related Issue
Follow-up to #2407 — that PR landed the capability domain and the CLI/TUI integration, but the kap-server wire surface for plugins and capabilities never made it to main. This PR restores it.
Problem
Non-CLI hosts (the desktop app, the browser web UI) cannot manage plugins or built-in capabilities:
IPluginServiceandICapabilityServiceare App-scope services inside agent-core-v2, only reachable in-process. Desktop/web settings UIs need a wire API to list/install/enable/disable/remove plugins, browse the marketplace catalog, and drive capability (Kimi Computer Use / Kimi WebBridge) readiness detection and install with progress.What changed
GET /api/v1/plugins,POST /api/v1/plugins {source},POST /api/v1/plugins/{id}:{enable,disable,remove}GET /api/v1/plugins/marketplace— catalog fetched on demand (newpluginMarketplaceUrlserver option /KIMI_CODE_PLUGIN_MARKETPLACE_URLenv / production default) and merged server-side with live install state;updateAvailableonly on strict semver catalog > installed (no semver dependency)GET /api/v1/capabilities,GET /api/v1/capabilities/{id},POST /api/v1/capabilities/{id}:installwith client-polled progress40418 capability.not_found,40419 plugin.not_found,40923 capability.install_in_progress,40924 capability.unsupportedIPluginService/ICapabilityService, so they serialize with the CLI/TUI install paths and fireonDidReload— session skill catalogs and the capability shelf-install hook converge regardless of which client triggered the change.user-skill-migratedwhen the WebBridge install migrates a pre-existing standalone skill onto the plugin-managed copy), surfaced throughCapabilityInstallProgress.noteso clients can localize it.No changeset: per gen-changesets Core Rule 6, kap-server REST additions consumed by external hosts are not perceivable by CLI users.
Checklist
gen-changesetsskill, or this PR needs no changeset.gen-docsskill, or this PR needs no doc update.API surface
All under
/api/v1, standard{ code, msg, data }envelope; schemas live inpackages/kap-server/src/protocol/rest-plugin.ts/rest-capability.ts.Capabilities — built-in product capabilities (kimi-cu, kimi-webbridge)
dataGET /capabilities{ capabilities: CapabilityStatus[] }GET /capabilities/{id}CapabilityStatusPOST /capabilities/{id}:installCapabilityStatus(install running — pollGETfor progress; no WS events in v1)Plugins
dataGET /plugins{ plugins: PluginSummary[] }POST /plugins— body{ source }PluginSummary(upsert: local path, zip URL, or GitHub repo — CLI semantics)POST /plugins/{id}:enable/:disable/:remove{ ok: true }GET /plugins/marketplace{ entries: MarketplaceEntry[] }Server wiring
pluginMarketplaceUrlserver option →KIMI_CODE_PLUGIN_MARKETPLACE_URLenv → production default. Plain paths /file:///~read from disk;KIMI_CODE_PLUGIN_MARKETPLACE_FROM_DEV_SERVER=1counts as the default; a failed default read falls back to the source checkout'splugins/marketplace.json(CLI parity).40418 capability.not_found,40419 plugin.not_found,40923 capability.install_in_progress,40924 capability.unsupported; plugin input mistakes map to40001/40409(never 50001).Domain / contract additions
CapabilityInstallProgress.note(agent-core-v2 + klient contract) — install completions carry a localizable machine key.app/plugin/marketplace(agent-core-v2) — the single catalog client/parser, consumed by both the CLI and this route.