feat(plugins): add source-control extension contracts (#2117)

This commit is contained in:
José Almeida
2026-08-13 08:29:29 +01:00
committed by GitHub
parent 064b852884
commit f218880ecb
530 changed files with 39054 additions and 7518 deletions
+137 -14
View File
@@ -28,6 +28,7 @@ var Handshake = plugin.HandshakeConfig{
```
Env kandev injects into the subprocess:
- `KANDEV_PLUGIN_DATA_DIR` — per-plugin writable dir (`~/.kandev/plugins/<id>/data`).
## 3. Proto (`apps/backend/proto/kandev/plugin/v1/plugin.proto`)
@@ -41,6 +42,14 @@ import "google/protobuf/struct.proto";
service Plugin {
rpc DeliverEvent(Event) returns (EventAck);
rpc HandleWebhook(WebhookRequest) returns (WebhookResponse);
// Browser calls pass through host-authenticated declared actions only.
rpc HandleAction(PluginActionRequest) returns (PluginActionResponse);
// Manifest-owned dynamic composer reference source operations.
rpc SearchEntityReferences(SearchEntityReferencesRequest) returns (SearchEntityReferencesResponse);
rpc AuthorizeEntityReference(AuthorizeEntityReferenceRequest) returns (AuthorizeEntityReferenceResponse);
// Optional provider-neutral credential resolver for declared repository providers.
rpc ResolveGitCredential(ResolveGitCredentialRequest) returns (ResolveGitCredentialResponse);
rpc GetGitCredentialBinding(GitCredentialBindingRequest) returns (GitCredentialBindingResponse);
}
// Implemented by KANDEV (served back over the go-plugin broker).
@@ -81,6 +90,7 @@ service Host {
rpc ListWorkflows(ListWorkflowsRequest) returns (ListWorkflowsResponse);
rpc ListWorkflowSteps(ListWorkflowStepsRequest) returns (ListWorkflowStepsResponse);
rpc ListAgentProfiles(ListAgentProfilesRequest) returns (ListAgentProfilesResponse);
rpc ListExecutorProfiles(ListExecutorProfilesRequest) returns (ListExecutorProfilesResponse);
rpc ListRepositories(ListRepositoriesRequest) returns (ListRepositoriesResponse);
rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse);
rpc ListSessionCodeStats(ListSessionCodeStatsRequest) returns (ListSessionCodeStatsResponse);
@@ -93,6 +103,8 @@ service Host {
rpc CreateTask(CreateTaskRequest) returns (Task);
rpc UpdateTask(UpdateTaskRequest) returns (Task);
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
rpc PreviewPluginOwnedTaskTree(PreviewPluginOwnedTaskTreeRequest) returns (PreviewPluginOwnedTaskTreeResponse);
rpc DeletePluginOwnedTaskTree(DeletePluginOwnedTaskTreeRequest) returns (DeletePluginOwnedTaskTreeResponse);
}
message Event {
@@ -114,6 +126,39 @@ message WebhookRequest {
}
message WebhookResponse { int32 status = 1; map<string, string> headers = 2; bytes body = 3; }
// The host derives resources and actor after normal HTTP auth/authorization. Body is
// untrusted JSON bounded by the manifest declaration; plugins must not infer authority
// from it. Response headers are filtered by the host allowlist.
message PluginActionRequest {
string action_key = 1;
VerifiedActionContext context = 2;
bytes body = 3;
}
message VerifiedActionContext {
string actor_id = 1;
string workspace_id = 2;
string task_id = 3;
string repository_id = 4;
string session_id = 5;
string head_branch = 6;
}
// status=0 preserves legacy 200. Otherwise the host accepts 200..599 and
// projects the status after filtering headers and enforcing the body limit.
message PluginActionResponse { bytes body = 1; map<string, string> headers = 2; int32 status = 3; }
message SearchEntityReferencesRequest { string source = 1; string workspace_id = 2; string query = 3; int32 limit = 4; }
message SearchEntityReferencesResponse { repeated EntityReferenceCandidate candidates = 1; }
message EntityReferenceCandidate { string provider_local_id = 1; string title = 2; string url = 3; google.protobuf.Struct attributes = 4; }
message AuthorizeEntityReferenceRequest { string source = 1; string workspace_id = 2; string purpose = 3; google.protobuf.Struct reference = 4; }
message AuthorizeEntityReferenceResponse { bool allowed = 1; string reason = 2; }
// Scope is host-verified. The credential value is transient; it must never be written
// into a host URL, task state, command argument, log, or executor environment.
message ResolveGitCredentialRequest { string provider_id = 1; string workspace_id = 2; string task_id = 3; string session_id = 4; string repository_id = 5; string host = 6; string path = 7; }
message ResolveGitCredentialResponse { string username = 1; string secret = 2; string expires_at = 3; }
message GitCredentialBindingRequest { string provider_id = 1; string workspace_id = 2; string task_id = 3; string session_id = 4; string repository_id = 5; string host = 6; string path = 7; }
message GitCredentialBindingResponse { string binding = 1; }
message GetStateRequest { string scope = 1; string scope_id = 2; string key = 3; }
message GetStateResponse { bool found = 1; google.protobuf.Struct value = 2; }
message SetStateRequest { string scope = 1; string scope_id = 2; string key = 3; google.protobuf.Struct value = 4; }
@@ -145,6 +190,15 @@ Notes: scope ∈ instance|workspace|task|agent (empty scope_id for instance —
matches the state store). The plugin never passes its own id; the Host service
instance is bound to the plugin's record at spawn time.
`DeletePluginOwnedTaskTree` is partial-progress aware. A successful response
carries every deleted task ID. If deletion stops after removing descendants,
the non-OK status includes a `DeletePluginOwnedTaskTreeProgress` detail with
those IDs. The Go SDK preserves them in the returned `([]string, error)` so a
plugin can reconcile completed deletions before retrying idempotent cleanup;
callers must not discard progress merely because the error is non-nil. An absent root
is a successful no-op, so a retry after a completed or externally removed tree remains
safe.
### 3a. Host data API (ADR 0043)
Read/write RPCs let plugins read and write kandev's own domain data —
@@ -162,16 +216,17 @@ capability gating, and cross-cutting conventions. See ADR 0043
**Readable resources.** Each read RPC requires `api_read:<resource>` in the
plugin's manifest:
| RPC | Capability | Resource |
|---|---|---|
| `ListTasks` / `GetTask` | `api_read:tasks` | tasks |
| `ListWorkspaces` | `api_read:workspaces` | workspaces |
| `ListWorkflows` | `api_read:workflows` | workflows |
| `ListWorkflowSteps` | `api_read:workflows` | workflows |
| `ListAgentProfiles` | `api_read:agent_profiles` | agent_profiles |
| `ListRepositories` | `api_read:repositories` | repositories |
| `ListSessions` | `api_read:sessions` | sessions |
| `ListSessionCodeStats` | `api_read:sessions` | sessions |
| RPC | Capability | Resource |
| ----------------------- | ---------------------------- | ----------------- |
| `ListTasks` / `GetTask` | `api_read:tasks` | tasks |
| `ListWorkspaces` | `api_read:workspaces` | workspaces |
| `ListWorkflows` | `api_read:workflows` | workflows |
| `ListWorkflowSteps` | `api_read:workflows` | workflows |
| `ListAgentProfiles` | `api_read:agent_profiles` | agent_profiles |
| `ListExecutorProfiles` | `api_read:executor_profiles` | executor_profiles |
| `ListRepositories` | `api_read:repositories` | repositories |
| `ListSessions` | `api_read:sessions` | sessions |
| `ListSessionCodeStats` | `api_read:sessions` | sessions |
An undeclared capability returns gRPC `PermissionDenied` with message
`capability 'api_read:tasks' not declared` (substituting the actual resource) —
@@ -281,6 +336,11 @@ type Host interface { // injected before
AgentProfiles() AgentProfileReader
Repositories() RepositoryReader
}
// Optional Host extension, discovered without breaking existing Host implementations.
type ExecutorProfileHost interface {
ExecutorProfiles() ExecutorProfileReader
}
func ExecutorProfiles(host Host) (ExecutorProfileReader, bool)
func Serve(p Plugin, opts ...Option) // blocks; wires go-plugin server + broker
// Optional embeddable no-op base: sdk.UnimplementedPlugin
// Optional embeddable no-op base for Host data accessors (every method
@@ -288,6 +348,47 @@ func Serve(p Plugin, opts ...Option) // blocks; wires go-plugin server + bro
// kandev side, not by plugin authors.
```
### Provider extensions (additive)
`Plugin` remains source-compatible. `Serve` detects optional handler interfaces and
returns `Unimplemented` only when a plugin has not opted into the corresponding
manifest declaration:
```go
type ActionHandler interface {
HandleAction(context.Context, *PluginActionRequest) (*PluginActionResponse, error)
}
type EntityReferenceHandler interface {
SearchEntityReferences(context.Context, *SearchEntityReferencesRequest) (*SearchEntityReferencesResponse, error)
AuthorizeEntityReference(context.Context, *AuthorizeEntityReferenceRequest) (*AuthorizeEntityReferenceResponse, error)
}
type GitCredentialResolver interface {
ResolveGitCredential(context.Context, *ResolveGitCredentialRequest) (*ResolveGitCredentialResponse, error)
}
type GitCredentialBinder interface {
GetGitCredentialBinding(context.Context, *GitCredentialBindingRequest) (*GitCredentialBindingResponse, error)
}
```
`HandleAction` receives host-verified actor/resource context and bounded untrusted body
separately. For task actions, an optional session selector is verified against the task;
when paired with a verified repository selector, `head_branch` is resolved from that
session's exact repository worktree. Browser body JSON cannot select or override it.
`SearchEntityReferences` candidates are untrusted: the host injects
descriptor identity and constructs canonical reference fields. `AuthorizeEntityReference`
runs for search and submission. `ResolveGitCredential` receives an exact host-verified
scope for both initial host materialization and helper-lease redemption, and returns
only a transient credential consumed by the host Git process. Initial materialization
and strict pre-worktree refresh carry the same task/session/repository scope; after a
successful refresh the worktree layer uses local refs and performs no second network operation.
Credential requests must include workspace, task, active session, repository, exact host, and exact path;
an incomplete plugin-provider scope fails closed.
`GetGitCredentialBinding` receives the same scope and returns an opaque, non-secret
generation checked before and after redemption; missing or changed bindings fail closed.
Disabling, failing, or uninstalling a plugin immediately revokes leases for all
manifest-declared provider IDs. Repository host and path matching are exact and
case-sensitive. The broker does not add, remove, or equate a trailing `.git`.
SDK types mirror proto but use `map[string]any` for Struct fields. The SDK owns
all go-plugin/grpc plumbing (handshake, broker for Host, conversions).
@@ -325,6 +426,10 @@ type AgentProfileReader interface {
List(ctx context.Context, page Page) ([]AgentProfile, *PageInfo, error)
}
type ExecutorProfileReader interface {
List(ctx context.Context, page Page) ([]ExecutorProfile, *PageInfo, error)
}
type RepositoryReader interface {
List(ctx context.Context, workspaceID string, page Page) ([]Repository, *PageInfo, error)
}
@@ -336,6 +441,16 @@ structs in `pluginsdk` (field-for-field mirrors of the proto messages, PascalCas
Go names for the proto's snake_case fields, `*string` for `optional string`) —
authors never see the generated `pluginv1.*` types.
`Repository` additionally carries credential-free provider origin identity:
`source_type`, `provider_id`, `provider_repository_id`, `provider_host`, `provider_scope`,
`owner_or_project`, `provider_name`, and `remote_url`. The Host never exposes a
local checkout path, scripts, or credentials through this DTO.
`provider_scope` is opaque and credential-free. For provider-backed repositories,
the strong identity is workspace + provider + scope + immutable provider repository
ID. Host/name/owner fields remain routing and display metadata; scoped descriptors do
not adopt legacy unscoped rows.
**Authoring example** — a plugin declaring `api_read: ["sessions"]` and reading
computed per-session code stats instead of opening the kandev database:
@@ -378,8 +493,8 @@ the API, never the DB.
converts the HTTP request to WebhookRequest and relays the WebhookResponse.
- **Health**: go-plugin client `Ping()` every 30s (injectable), 3 consecutive
failures → status `error` (+ restart attempt with backoff), recovery → `active`
+ delivery flush. Crash (process exit) → immediate restart with backoff
(max 5 attempts, then `error`).
- delivery flush. Crash (process exit) → immediate restart with backoff
(max 5 attempts, then `error`).
- **Capability gating**: each Host RPC checks the plugin's manifest capabilities
before doing any work — `state` for `GetState`/`SetState`/`DeleteState`/
`ListState`, `secrets` for `RevealSecret`, `api_read:<resource>` for each Host
@@ -410,7 +525,7 @@ runtime:
linux-amd64: server/plugin-linux-amd64
darwin-arm64: server/plugin-darwin-arm64
# ... any subset
min_kandev_version: "0.78.0" # optional
min_kandev_version: "0.78.0" # optional
```
Install pipeline: `POST /api/plugins/install` with JSON `{"url": "..."}` OR
@@ -427,5 +542,13 @@ multipart field `package` → verify checksums.txt covers all files & hashes mat
kandev **from the extracted package dir** (no reverse proxy, no upstream).
- Management page: "Register plugin" (manifest paste) is replaced by "Install
plugin" (URL input + file upload). No credentials are ever displayed.
- Boot payload `plugins: [{id,name,bundleUrl,styleUrls}]` unchanged.
- Boot payload `plugins: [{id,name,bundleUrl,styleUrls,repositoryProviderIds?}]`.
`repositoryProviderIds` is JSON camelCase copied from manifest
`repository_providers`; frontend loader records it before bundle initialization so
provider/review registration can enforce declared ownership. Omission remains
compatible with older payloads. Failed or timed-out initialization rolls back partial
registrations and fences late callbacks from the expired activation attempt.
```
```
+64 -1
View File
@@ -29,6 +29,7 @@ service HostData {
rpc ListWorkflows(ListWorkflowsRequest) returns (ListWorkflowsResponse);
rpc ListWorkflowSteps(ListWorkflowStepsRequest) returns (ListWorkflowStepsResponse);
rpc ListAgentProfiles(ListAgentProfilesRequest) returns (ListAgentProfilesResponse);
rpc ListExecutorProfiles(ListExecutorProfilesRequest) returns (ListExecutorProfilesResponse);
rpc ListRepositories(ListRepositoriesRequest) returns (ListRepositoriesResponse);
// Sessions + code stats — capability api_read:sessions. Driven by a real
@@ -41,10 +42,15 @@ service HostData {
// Writes — capability api_write:<resource>. Route through service methods so
// the corresponding task.* events fire; this is the whole reason not to let
// plugins write the DB.
// plugins write the DB.
// `ListExecutorProfiles` requires `api_read:executor_profiles`; preview/delete
// capability is implicit in plugin-owned task provenance and is never conferred by
// a task link stored in plugin state.
rpc CreateTask(CreateTaskRequest) returns (CreateTaskResponse);
rpc UpdateTask(UpdateTaskRequest) returns (UpdateTaskResponse);
rpc SendMessage(SendMessageRequest) returns (SendMessageResponse);
rpc PreviewPluginOwnedTaskTree(PreviewPluginOwnedTaskTreeRequest) returns (PreviewPluginOwnedTaskTreeResponse);
rpc DeletePluginOwnedTaskTree(DeletePluginOwnedTaskTreeRequest) returns (DeletePluginOwnedTaskTreeResponse);
}
// ── Common ──────────────────────────────────────────────────────────────────
@@ -86,6 +92,7 @@ message TaskRepository {
string repository_id = 2;
string base_branch = 3;
int32 position = 4;
string checkout_branch = 5;
}
message TaskFilter {
@@ -148,11 +155,31 @@ message AgentProfile {
message ListAgentProfilesRequest { Page page = 1; }
message ListAgentProfilesResponse { repeated AgentProfile profiles = 1; PageInfo page_info = 2; }
message ExecutorProfile {
string id = 1;
string display_name = 2;
string executor_type = 3;
}
message ListExecutorProfilesRequest { Page page = 1; }
message ListExecutorProfilesResponse { repeated ExecutorProfile profiles = 1; PageInfo page_info = 2; }
message Repository {
string id = 1;
string workspace_id = 2;
string name = 3; // owner/repo slug when known, else name
optional string default_branch = 4;
// Credential-free provider origin identity. Never expose local paths,
// scripts, or credentials through this Host DTO.
string source_type = 5;
string provider_id = 6;
string provider_repository_id = 7;
string provider_host = 8;
string owner_or_project = 9;
string provider_name = 10;
string remote_url = 11;
// Opaque provider-defined connection scope. Together with the immutable
// provider_repository_id, this is the durable upstream identity.
string provider_scope = 12;
}
message ListRepositoriesRequest { string workspace_id = 1; Page page = 2; }
message ListRepositoriesResponse { repeated Repository repositories = 1; PageInfo page_info = 2; }
@@ -204,6 +231,35 @@ message CreateTaskRequest {
optional string parent_id = 6;
bool start_agent = 7;
// kandev stamps source = "plugin:<id>" server-side; not settable here.
repeated PluginTaskRepository repositories = 8;
optional PluginTaskLaunchOptions launch = 9;
google.protobuf.Struct metadata = 10; // plugin namespace only; host reserves source.
}
message PluginTaskRepository {
string repository_id = 1; // existing Kandev repository, or empty with remote below
optional RemoteRepositoryDescriptor remote = 2;
optional string base_branch = 3;
optional string checkout_branch = 4;
optional int64 pull_request_number = 5;
}
message RemoteRepositoryDescriptor {
string provider_id = 1;
string provider_host = 2;
string owner_or_project = 3;
string provider_repository_id = 4;
string name = 5;
string clone_url = 6; // exact credential-free URL; host never reconstructs it
optional string default_branch = 7;
optional string base_branch = 8;
optional string head_branch = 9;
optional int64 pull_request_number = 10;
string provider_scope = 11; // credential-free configured provider instance
}
message PluginTaskLaunchOptions {
optional string agent_profile_id = 1;
optional string executor_profile_id = 2;
optional string prompt = 3;
optional string plan_mode = 4;
}
message CreateTaskResponse { Task task = 1; }
message UpdateTaskRequest {
@@ -228,3 +284,10 @@ message SendMessageResponse {
string session_id = 1; // the session the message was delivered to
string status = 2; // "queued" | "sent" | "started"
}
// Deletion is owner-scoped. Host compares metadata.source with calling plugin ID; links
// in plugin state are not deletion authority. Preview always precedes destructive UI.
message PreviewPluginOwnedTaskTreeRequest { string root_task_id = 1; }
message PreviewPluginOwnedTaskTreeResponse { repeated Task tasks = 1; }
message DeletePluginOwnedTaskTreeRequest { string root_task_id = 1; }
message DeletePluginOwnedTaskTreeResponse { repeated string deleted_task_ids = 1; }
+487 -32
View File
@@ -6,7 +6,11 @@ diverge without updating this file.
## Loading model
1. Backend boot payload gains `plugins: ActivePlugin[]` where
`ActivePlugin = { id: string; name: string; bundleUrl: string; styleUrls?: string[] }`.
`ActivePlugin = { id: string; name: string; bundleUrl: string; styleUrls?: string[];
repositoryProviderIds?: string[] }`. `repositoryProviderIds` is JSON
`repositoryProviderIds`, copied from manifest `repository_providers`. It is optional
only for additive compatibility with older boot payloads; a present empty list means
the plugin declared no repository providers.
`bundleUrl` = `/api/plugins/{id}/bundle` — kandev serves this **directly from the
extracted package directory** on local disk
(`~/.kandev/plugins/<id>/<version>/ui/...`, per manifest `ui.bundle`). There is no
@@ -14,7 +18,14 @@ diverge without updating this file.
be running to serve the UI bundle, since installation already extracted the file.
2. On SPA boot, the **plugin host** (`apps/web/lib/plugins/host.ts`) iterates
`bootPayload.plugins`, injects any `styleUrls` as `<link>`, and dynamically
`import(/* @vite-ignore */ bundleUrl)` each bundle as a native ES module.
`import(/* @vite-ignore */ bundleUrl)` each bundle as a native ES module. Before a
bundle can initialize, the loader supplies its `repositoryProviderIds` to the
registry (for example `setDeclaredRepositoryProviderIds(pluginId, ids)`). The scoped
registry then rejects `registerRepositoryProvider` or `registerReviewProvider` IDs
outside that declared set. An omitted field preserves older-host compatibility;
it does not invent provider ownership. Provider IDs are canonical lowercase
identifiers: the manifest validator and frontend registry reject uppercase or
otherwise non-canonical variants instead of creating case-dependent ownership.
3. Each bundle, when evaluated, calls the global:
```ts
window.registerKandevPlugin(pluginId, {
@@ -28,6 +39,12 @@ diverge without updating this file.
initialization finishes. Slow or failed reloads do not by themselves revoke
open or saved task panels. On explicit plugin disable/uninstall the host calls
`destroy?.()`, removes the plugin's registrations, and closes its panels.
Each initialization attempt is transactional: failure or timeout unregisters
its partial contributions, aborts plugin-owned work, and fences callbacks from
the expired generation. The same generation owns host-created subscriptions,
modal and task-link handles, toasts, and review surfaces; the loader closes or
unsubscribes them before calling `destroy` exactly once. Requests and callbacks
from an expired generation cannot mutate the replacement generation.
## Global entry point
@@ -35,6 +52,12 @@ diverge without updating this file.
host before any bundle loads. Bundles are authored with React as an **external**;
they must use `host.React` (NOT bundle their own React) to share the host instance.
The independently consumable frontend type contract is the runtime-free
`@kandev/plugin-sdk` package in `apps/packages/plugin-sdk`. Official plugins import
these types instead of re-declaring this document or importing `apps/web` internals.
The host has a compile-time assignability test, and the real Bitbucket package is a
required exact-head compatibility consumer.
## `host: PluginHostApi`
```ts
@@ -42,22 +65,58 @@ interface PluginHostApi {
pluginId: string;
React: typeof import("react"); // host React instance (shared)
jsx: typeof React.createElement; // convenience alias (h)
store: {
// kandev app store (zustand StoreApi)
getState(): AppState;
setState(partial): void;
subscribe(listener): () => void;
context: {
// Versioned provider-neutral reads; never exposes private AppState slices.
getActiveWorkspaceId(): string | undefined;
subscribeActiveWorkspace(listener): () => void;
getTaskCreationContext(workspaceId: string): TaskCreationContext | null;
subscribeTaskCreationContext(workspaceId: string, listener): () => void;
resolveRepositoryId(identity: RepositoryIdentityInput): string | undefined;
};
// Compatibility only for older bundles. Deliberately absent from
// @kandev/plugin-sdk; new/official plugins must use host.context.
store: Pick<StoreApi<AppState>, "getState" | "setState" | "subscribe">;
api: {
// fetch scoped to this plugin's backend via kandev proxy:
// GET/POST {method} /api/plugins/{id}/... ; returns parsed JSON
// Low-level request scoped to this plugin's host path. It MUST NOT target a
// public webhook path or be used for authenticated provider commands.
fetch(path: string, init?: RequestInit): Promise<Response>;
// Authenticated action declared in this plugin's manifest. The host verifies the
// indicated resource and passes it to the plugin separately from body JSON. This
// is the only browser-to-plugin command path; never call a public webhook route.
invokeAction<TResponse>(
key: string,
input?: {
workspaceId?: string;
taskId?: string;
sessionId?: string;
repositoryId?: string;
body?: unknown;
},
options?: { signal?: AbortSignal },
): Promise<TResponse>;
// Backend API origin ("" when SPA and API share an origin) — for reaching
// first-party kandev REST endpoints without re-deriving the split-origin
// dev/desktop base URL from window internals.
baseUrl: string;
};
ui: Record<string, unknown>; // curated @kandev/ui components + app UI (see below)
ui: PluginUIApi; // named curated host components; no open Record index
// Plugin-scoped locale and translation API. Components use the reactive
// hook; registry getters may use the imperative translator.
i18n: {
readonly locale: string;
t(
key: string,
options?: {
defaultValue?: string;
count?: number;
values?: Readonly<Record<string, string | number>>;
},
): string;
useTranslation(): {
readonly locale: string;
t: PluginHostApi["i18n"]["t"];
};
};
// The resolved light/dark theme, read live on every access. `host` is built
// once per plugin load, so copying this into a variable that outlives a
// render freezes it; read it during render, and pair it with onThemeChange
@@ -73,9 +132,17 @@ interface PluginHostApi {
// (e.g. /t/{taskId}) without a full reload.
navigate(href: string, options?: { replace?: boolean }): void;
// Imperatively opens a modal window rendered by the host's <PluginModalHost/>
// (mounted once at the app root, isolated behind its own error boundary).
// (mounted once at the app root with its own tooltip provider and isolated
// behind its own error boundary).
// Independent of keybindings — any plugin code path may call it.
openModal(options: PluginModalOptions): PluginModalHandle;
// Opens Kandev's native one-field task change-request linking workflow.
// Provider code supplies copy, parsing, and mutation only; the host owns
// validation placement, submitting state, footer, toast, and close behavior.
openTaskLinkDialog(options: PluginTaskLinkDialogOptions): PluginModalHandle;
// Opens a registered provider review in the native desktop dock panel or
// current mobile session review. Plugins do not reach into host layout stores.
openTaskReview(options: PluginTaskReviewOptions): void;
// Sonner's imperative toast. The host mounts the single <Toaster/>, so
// there is nothing to render and nothing to wire — and because it is
// imperative rather than a component, it works from inside a plugin modal
@@ -97,6 +164,8 @@ interface PluginStorageEntry {
}
interface PluginStorageSetOptions {
// Abort the request when the owning surface or plugin generation ends.
signal?: AbortSignal;
// Optimistic-concurrency guard: the updatedAt the caller last read. The
// write is rejected (the returned promise rejects with a
// PluginStorageConflictError) if the stored row was modified after this
@@ -132,6 +201,7 @@ interface PluginStorageApi {
scope: PluginStorageScope,
scopeId: string,
key: string,
options?: { signal?: AbortSignal },
): Promise<PluginStorageEntry | undefined>;
set(
scope: PluginStorageScope,
@@ -144,12 +214,13 @@ interface PluginStorageApi {
scope: PluginStorageScope,
scopeId: string,
key: string,
options?: Pick<PluginStorageSetOptions, "writerId">,
options?: Pick<PluginStorageSetOptions, "writerId" | "signal">,
): Promise<void>;
// Every entry under (scope, scopeId), ordered by key. Not paginated.
list(
scope: PluginStorageScope,
scopeId: string,
options?: { signal?: AbortSignal },
): Promise<PluginStorageEntry[]>;
// Subscribes to live updates for this plugin's own storage made from
// another tab, device, or surface — e.g. the kanban Edit modal and the
@@ -187,16 +258,56 @@ interface PluginUserStateChange {
interface PluginModalOptions {
title?: string; // rendered in a DialogHeader/DialogTitle; omit for no header title
description?: string; // rendered below the title in the host-owned header
content: React.ComponentType<{ slotProps?: unknown }>; // reuses the slot-component contract
size?: "sm" | "md" | "lg" | "xl"; // maps to the host's Dialog width classes; default "md"
dismissible?: boolean; // overlay click / Escape close the modal; default true
presentation?: "dialog" | "drawer"; // default dialog; use drawer for native phone actions
}
interface PluginModalHandle {
close(): void; // closes this modal instance; no-op if already closed
}
interface PluginTaskLinkDialogOptions {
title: string;
description: string;
inputLabel: string;
placeholder?: string;
emptyError: string;
failureMessage: string;
successMessage: string;
inputTestId?: string;
errorTestId?: string;
submitTestId?: string;
// The host aborts this signal when the user cancels or closes the dialog.
onSubmit(reference: string, signal: AbortSignal): Promise<void>;
}
interface PluginTaskReviewOptions {
providerId: string;
reviewKey: string;
title?: string;
presentation: "desktop" | "mobile";
sessionId?: string;
}
```
For `host.api.invokeAction`, workspace-scoped actions accept only `workspaceId`;
repository-scoped actions accept `workspaceId` plus `repositoryId`; task-scoped
actions require `taskId`, may include a matching `workspaceId`, and may include
`repositoryId` only when that persisted repository is attached to the verified task.
A task action may also include `sessionId`; the host verifies it belongs to that task.
When both session and repository selectors are present, the host resolves the exact
non-empty worktree branch and exposes it only in the backend verified action context.
Resource selectors never become part of the untrusted action body.
An action handler may return an HTTP status from 200 through 599; zero preserves the
legacy 200 response. The host forwards only safe response headers (`Content-Type`,
`Cache-Control`, `ETag`, and `Retry-After`). Invalid statuses become 502, while
transport/runtime errors become 503 without exposing internal error text. Plugins
should use explicit statuses only for safe domain outcomes that callers can act on.
`host.ui` contents: shadcn primitives (Accordion*, Alert*, Badge, Button,
Card*, Checkbox, Collapsible*, Dialog*, DropdownMenu*, Empty*, Input, Kbd,
KbdGroup, Label, Pagination*, Popover*, Progress, ScrollArea, Select*,
@@ -206,16 +317,110 @@ Tooltip*, including `TooltipProvider`), the recharts wrappers (`ChartContainer`,
`ChartStyle`), plus first-party app UI: `PageTopbar` (the kandev title bar, for
routes that opt out of the default chrome and own their layout),
`TaskCreateDialog` (kandev's real create-task modal, prefilled via
`initialValues`), `Combobox` (the app's Command+Popover picker), and
`RichTextEditor`/`RichTextReadOnly` (narrow wrappers over the Plan panel's
tiptap markdown editor — see below). The authoritative list is
`initialValues`), `Combobox` (the app's Command+Popover picker), and the
provider-neutral code-host dashboard set: `ChangeRequestList`,
`ChangeRequestRow`, `ChangeRequestDetail`, `IntegrationListToolbar`, `IntegrationScopeBar`,
`IntegrationSaveQueryDialog`, `IntegrationRepositoryFilter`, `IntegrationCursorPagination`,
`IntegrationStartTaskMenu`, `IntegrationIcon`, `IntegrationChangeRequestStatus`, and
`TaskRowIndicator`. The authoritative list is
`apps/web/lib/plugins/host-api.ts` (`PLUGIN_UI`).
In create mode, `TaskCreateDialog` accepts this optional transport seam:
```ts
createTask?: (
payload: Parameters<typeof createTask>[0],
) => Promise<CreateTaskResponse>;
```
When omitted, the dialog uses the normal `/api/v1/tasks` REST client. A trusted
plugin wrapper may provide it to send the unchanged native payload through
`Host Tasks.Create`; the same callback handles both the initial submission and
the one allowed fresh-branch re-consent retry. Edit and session modes ignore it.
The browser callback must not manufacture a repository-provider descriptor. It sends
only native task choices plus an idempotency identifier to an authenticated plugin
action; the plugin resolves repository identity from its live provider connection.
Scope idempotency to one open dialog so retry does not create duplicates while a later
intentional launch for the same change request still can.
Code-host plugins use that dashboard set as one contract. The plugin supplies
normalized change-request data, filter state, task presets, and callbacks; the
host owns row density, external-title behavior, responsive task menus,
linked-task navigation, and loading/error/empty treatment. A row's sole workflow CTA
is the shared **Task** preset menu, whose selection opens `TaskCreateDialog`
directly. Review belongs to the registered task review-provider surface, not a
parallel dashboard button or plugin-specific launch modal. `IntegrationIcon` maps
semantic names (`pull-request`, `pull-request-closed`, `merged`, `filter`) to the same
host Tabler glyphs used by first-party code-host pages; plugins do not copy their SVG
paths. Runtime components stay in the Kandev host and are versioned with `host.ui`.
A task preset may provide a semantic `iconName`; the host maps `eye`, `message`, and
`tool` to the exact first-party **Review**, **Address feedback**, and **Fix CI** icons.
`ReviewItemSummary.taskStatus` is the normal code-host status integration. Once a
registered review provider publishes it, Kandev automatically mounts the exact shared
topbar button, composer CI chip, desktop hover popover, and mobile drawer. Each rendered
linked-task row acquires one deduplicated provider refresh so its indicator color is live
before hover; hover/focus can refresh again, while active topbar/composer status refreshes
every 90 seconds. Plugins must not register
a visual slot or a second poller for these surfaces. Linked-task indicators also derive
the same semantic color hierarchy from normalized state, review, and pipeline fields;
providers do not send CSS classes or provider-specific color tokens. While the initial
task detail request is pending, the indicator remains muted; publishing the snapshot
updates both its summary and color. `IntegrationChangeRequestStatus` remains exposed for non-review-
provider composition only.
`ChangeRequestDetail` is the exact provider-neutral detail component consumed by
Kandev's GitHub panel. A review provider supplies its normalized model and advertised
callbacks; Kandev owns header, branches, state/review badges, description, review/check/
comment sections, add-to-context controls, scrolling, loading/error states, and native
mobile sizing. Code-host plugins must use it instead of recreating the review page.
A future SDK package may contain types or pure helpers, but not duplicate React/Radix
runtime components.
The curated surface also includes `RichTextEditor`/`RichTextReadOnly`, narrow
wrappers over the Plan panel's tiptap markdown editor (see below).
Plugins must use these host instances — bundling copies of anything
Radix/portal/context-based would split React context across instances and
break refs/`asChild`. Pure-React libs (e.g. `@tabler/icons-react`) bundle
fine.
### Persisted repository branch action
A manifest-owned repository provider that participates in Kandev's native task branch
picker declares this standardized action:
```yaml
actions:
- key: "repositories.branches"
scope: "workspace"
max_body_bytes: 16384
```
This action is invoked by the host backend, not the browser callback. Kandev resolves the
active plugin that owns the repository's persisted provider ID and supplies a verified
workspace context plus this snake-case body:
```json
{
"repository": {
"provider_id": "example-provider",
"provider_host": "https://code.example.com",
"provider_scope": "https://code.example.com/context-a",
"provider_repository_id": "owner/repository",
"owner_or_project": "owner",
"name": "repository",
"clone_url": "https://code.example.com/owner/repository.git",
"default_branch": "main"
}
}
```
Every field comes from the persisted workspace repository. The plugin returns
`{"branches":[{"name":"main","commit":"optional","is_default":true}]}`. Kandev
enforces the manifest request cap, a 15-second timeout, a 1 MiB response cap, at most
10,000 branches, non-empty names, and name deduplication. Missing ownership, an inactive
plugin, an undeclared/wrong-scope action, or malformed output fails closed. Providers
must not require browser-supplied repository authority on this path.
The host wraps plugin routes, slots, and `openModal` content in a
`TooltipProvider`, so a plain `Tooltip` works anywhere without one.
`TooltipProvider` is exported for plugins that want their own
@@ -261,6 +466,8 @@ interface PluginUtilsApi {
// The host's clsx + tailwind-merge combiner, so class merging matches the
// components it styles.
cn(...inputs: unknown[]): string;
// Non-security UUID with a fallback for supported insecure HTTP origins.
generateUUID(): string;
// Locale-aware relative time ("3 hours ago", "in 2 days", "yesterday") via
// Intl.RelativeTimeFormat in the user's active locale; "" for unparseable
// input. Prefer it over a hand-rolled ladder, which is English-only by
@@ -269,7 +476,7 @@ interface PluginUtilsApi {
}
```
Both are functions, so they sit beside `navigate`/`openModal` rather than in
These are functions, so they sit beside `navigate`/`openModal` rather than in
`ui`, which is a component map.
### `host.ui.RichTextEditor` / `host.ui.RichTextReadOnly`
@@ -349,17 +556,19 @@ own write).
```ts
// icon: curated icon name (apps/web/lib/plugins/icons.ts — "ticket", "chart",
// "robot", "database", ...); unknown/missing names render a puzzle glyph in
// the sidebar.
// "robot", "database", ...) or a plugin-owned component rendered with host
// React. Unknown/missing names render a puzzle glyph in the sidebar.
// section: "main" (default) renders as a top-level sidebar entry;
// "integrations" renders inside the sidebar's Integrations section alongside
// the first-party integration links (GitHub, Jira, ...). Hosts predating a
// section value simply don't render items targeting it (additive change).
type PluginIcon = string | React.ComponentType<{ className?: string }>;
interface NavItem {
id: string;
label: string;
path: string;
icon?: string;
icon?: PluginIcon;
section?: "main" | "settings" | "integrations";
}
@@ -368,7 +577,7 @@ interface NavItem {
interface PluginPageChrome {
title?: string; // default: nav-item label for the same path, else plugin name
subtitle?: string; // muted text next to the title
icon?: string; // curated icon name; default: matching nav item's icon
icon?: PluginIcon; // default: matching nav item's icon
backHref?: string; // back-link target (host default "/")
backLabel?: string; // back-link label (host default "Kandev")
actions?: React.ComponentType; // rendered on the right side of the topbar
@@ -381,6 +590,13 @@ interface PluginRouteOptions {
}
interface PluginRegistry {
// Installs flat locale catalogs under this plugin's isolated namespace.
// English is required as the fallback. Registration is atomic; unload
// removes all catalog bundles and locale changes invalidate host consumers.
registerTranslations(
catalogs: Readonly<Record<string, Readonly<Record<string, string>>>>,
): void;
// Top-level SPA route, e.g. "/jira". Component rendered by the SPA route resolver
// when window.location path === path (exact match; trailing segments via ":param" not
// required for v1 — exact + startsWith("/plugins/{id}") allowed). The host wraps the
@@ -402,9 +618,16 @@ interface PluginRegistry {
// The settings shell already provides its own topbar chrome — no options here.
registerSettingsRoute(path: string, Component: React.ComponentType): void;
// Native Settings > Integrations contribution. The host adds index/navigation
// entries and wraps this component in the shared settings section.
registerIntegrationSettings(
registration: IntegrationSettingsRegistration,
): void;
// Named slot injection. Host renders all components registered for a slot via
// <PluginSlot name="..." slotProps={...}/>. Initial slots: "task-sidebar",
// "settings-nav", "chat-input-actions", "chat-top-bar",
// "settings-nav", "chat-input-actions", "task-create-input-actions",
// "new-session-input-actions", "chat-top-bar",
// "main-top-bar", "app-status-bar-left", "app-status-bar-right",
// "plugin-settings", "task-card-indicators", and "task-card-tags".
// "task-card-indicators" renders a small icon/badge beside the PR status
@@ -417,9 +640,10 @@ interface PluginRegistry {
// same `{ taskId: string, workspaceId: string | null, workflowStepId: string | null }`
// shape as `slotProps` (`workspaceId` is null with no active workspace, and
// `workflowStepId` is null when the task has no workflow step assigned).
// "chat-input-actions" renders icon buttons in the chat composer toolbar
// (beside the model picker, mic, and send) and forwards
// `{ taskId, taskTitle, activeSessionId, sessionIds }` as `slotProps`.
// "chat-input-actions", "task-create-input-actions", and
// "new-session-input-actions" render composer actions for task/Quick Chat,
// task creation, and new-session creation. Each forwards the typed
// `PluginComposerSlotProps`, including native insert/focus/submit capabilities.
// "chat-top-bar" renders status in the session top bar (beside the
// document/editor/debug controls) and forwards
// `{ taskId, taskTitle, workspaceId, activeSessionId, sessionIds }`. Both
@@ -475,10 +699,21 @@ interface PluginRegistry {
// the manifest validator and the frontend parser reject it.
registerKeybinding(id: string, handler: (event: KeyboardEvent) => void): void;
// Contributes a panel to the task workspace "+" (add panel) menu (dockview
// desktop) and, when mobileEnabled, the phone bottom nav. Panel identity
// lives in the dockview params (pluginId/panelKey); the panel id is
// `plugin:{pluginId}:{panelKey}`. See "Task panels" below.
// Requires manifest ownership of provider.id. One active plugin owns one provider;
// unload revokes it and aborts in-flight provider work. inspectURL returns a complete
// credential-free HTTPS descriptor—host does not parse plugin provider URLs.
registerRepositoryProvider(provider: RepositoryProviderRegistration): void;
// Native task-menu contribution. placement "link" renders in Link menus on desktop
// and visible mobile action surfaces; host closes the menu before handler invocation.
registerTaskAction(action: TaskActionRegistration): void;
// Native desktop/mobile review integration. Use external-store callbacks, never a
// plugin hook, so enable/disable does not alter host hook ordering.
registerReviewProvider(provider: ReviewProviderRegistration): void;
// Contributes a panel to the task workspace "+" menu and, when enabled,
// the phone Panels picker.
registerTaskPanel(registration: TaskPanelRegistration): void;
// Contributes an item to the kanban card's Edit submenu (group "edit") or
@@ -492,6 +727,212 @@ interface PluginRegistry {
registerTaskFilter(registration: TaskFilterRegistration): void;
}
interface IntegrationSettingsRegistration {
id: string;
label: string;
description: string;
icon?: PluginIcon;
Component: React.ComponentType<{ workspaceId?: string }>;
}
// Integration settings render at /settings/integrations/{id} and
// /settings/workspace/{workspaceId}/integrations/{id}. IDs are URL-safe, cannot
// shadow first-party integrations, and have one active owner; unload revokes them.
interface RepositoryProviderRegistration {
id: string;
label: string;
icon?: PluginIcon;
listRepositories(context: {
workspaceId: string;
/** Optional server-side search text. */
query?: string;
/** Opaque cursor returned by this provider for the same query. */
cursor?: string;
/** Requested page size; a provider may return fewer items. */
limit?: number;
signal: AbortSignal;
}): Promise<RepositoryInspection[] | RepositoryProviderPage>;
// Optional synchronous performance hint. It never establishes ownership.
matchesURL?(url: string): boolean;
listBranches(context: {
workspaceId: string;
repository: RepositoryInspection;
signal: AbortSignal;
}): Promise<RepositoryProviderBranch[]>;
inspectURL(context: {
workspaceId: string;
url: string;
signal: AbortSignal;
}): Promise<RepositoryInspection | null>;
supportsDraft?: boolean; // default true; false hides the native draft option
// Kandev pushes the verified checkout branch before invoking this callback.
createChangeRequest?(context: {
workspaceId: string;
taskId: string;
sessionId: string; // session whose checkout Kandev pushed
repositoryId: string;
repository: PluginHostRepository; // persisted host repository, not browser authority
title: string;
body: string;
baseBranch?: string;
draft: boolean;
signal: AbortSignal;
}): Promise<RepositoryChangeRequestCreateResult>;
}
interface RepositoryProviderPage {
repositories: RepositoryInspection[];
nextCursor?: string;
}
// The host binds every returned RepositoryInspection.providerId to the
// registration's manifest-owned id; result data cannot spoof another namespace.
// Legacy arrays remain valid. The host follows page cursors and rejects a cursor
// repeated by a broken provider instead of looping forever.
interface PluginHostRepository {
id: string;
workspace_id: string;
name: string;
provider: string;
source_type?: string;
provider_repo_id?: string;
provider_host?: string;
provider_scope?: string;
provider_owner?: string;
provider_name?: string;
remote_url?: string;
default_branch?: string;
}
interface RepositoryProviderBranch {
name: string;
}
interface RepositoryChangeRequestCreateResult {
url: string;
provider?: string;
output?: string;
// False means remote creation succeeded but task association did not.
linked?: boolean;
// Safe detail shown with recovery guidance. Never retry remote creation.
associationError?: string;
}
interface RepositoryInspection {
providerId: string;
providerHost: string;
// Opaque, credential-free connection identity. Required when one authority
// can host multiple independent provider roots.
providerScope?: string;
ownerOrProject: string;
repositoryId: string;
repositoryName: string;
cloneUrl: string;
defaultBranch?: string;
baseBranch?: string;
headBranch?: string;
pullRequest?: { number: number; title: string };
}
interface TaskActionRegistration {
id: string;
label: string;
icon?: PluginIcon;
placement: "link";
group?: string;
visible?(context: PluginTaskActionContext): boolean;
singleTaskOnly?: boolean;
run(context: PluginTaskActionContext): Promise<void>;
}
interface PluginTaskActionContext {
workspaceId: string;
taskId: string;
repositories: readonly PluginHostRepository[];
pathname: string;
presentation: "desktop" | "mobile";
}
interface ReviewProviderRegistration {
id: string;
label: string;
icon?: PluginIcon;
changeRequestNoun: string;
order: number;
getSnapshot(taskId: string): readonly ReviewItemSummary[];
subscribe(taskId: string, listener: () => void): () => void;
refresh(taskId: string, signal: AbortSignal): Promise<void>;
// Implement all three association callbacks together. The host performs one
// workspace-bounded association refresh and renders native task-list/card
// indicators. Each rendered linked task leases refresh(taskId), deduplicated
// with topbar/panel consumers; hover/focus may refresh it again.
getAssociationSnapshot?(
workspaceId: string,
): readonly ReviewTaskAssociation[];
subscribeAssociations?(workspaceId: string, listener: () => void): () => void;
refreshAssociations?(workspaceId: string, signal: AbortSignal): Promise<void>;
// Removes only this task link; it never deletes the remote change request.
unlink?(context: {
workspaceId: string;
taskId: string;
reviewKey: string;
signal: AbortSignal;
}): Promise<void>;
ReviewPanel: React.ComponentType<PluginReviewPanelProps>;
Selector?: React.ComponentType;
EmptyState?: React.ComponentType;
}
interface ReviewTaskAssociation {
providerId: string;
taskId: string;
reviewKey: string;
connectionScope: string;
repositoryId: string;
changeRequestNumber: string | number;
}
interface ReviewItemSummary {
providerId: string;
reviewKey: string;
title: string;
url: string;
connectionScope: string;
repositoryId: string;
changeRequestNumber: string | number;
// open/opened/draft participates in native Create PR eligibility.
state: string;
statusBadge?: { label: string; tone?: string };
taskStatus?: ReviewTaskStatus;
}
type ReviewTaskPipelineState = "success" | "failure" | "pending" | "neutral";
interface ReviewTaskStatus {
number: number | string;
state: "open" | "merged" | "closed" | "draft";
pipelineState: ReviewTaskPipelineState;
checks: readonly {
id: string;
label: string;
state: ReviewTaskPipelineState;
detail?: string;
url?: string;
}[];
review?: {
state: "approved" | "changes_requested" | "pending";
approved: number;
required?: number;
requested?: number;
};
unresolvedComments?: number;
loading?: boolean;
error?: string;
updatedAt?: number;
}
interface PluginReviewPanelProps {
panelId: string;
presentation: "desktop" | "mobile";
workspaceId: string;
taskId: string;
sessionId?: string;
reviewKey: string;
connectionScope: string;
repositoryId: string;
changeRequestNumber: string | number;
}
type PluginPresentation = "desktop" | "mobile";
type PluginComposerSurface =
@@ -530,7 +971,7 @@ interface PluginTaskPanelProps {
interface TaskPanelRegistration {
id: string; // plugin-local panel id (unique within the plugin, not globally)
title: string; // add-panel-menu row label and dockview tab title
icon?: string; // curated icon name (apps/web/lib/plugins/icons.ts)
icon?: PluginIcon;
Component: React.ComponentType<PluginTaskPanelProps>; // wrapped in a PluginErrorBoundary
mobileEnabled?: boolean; // include in the phone's grouped Panels picker. Default: false.
}
@@ -575,6 +1016,11 @@ interface TaskFilterRegistration {
}
```
The host treats `matchesURL` only as a coarse candidate filter. It runs every
remaining provider's cancellable, workspace-scoped `inspectURL`; `null` means the
configured provider does not own the URL. One structured result wins, more than one
is an ambiguity error, and registration order never decides ownership.
### App-status-bar slots
`app-status-bar-left` and `app-status-bar-right` are live named component slots.
@@ -597,7 +1043,8 @@ interface AppStatusBarSlotProps {
`placement` matches registration slot. `presentation` identifies the mounted host;
the host mounts only one presentation at once. `density` is `full` on desktop and
phone drawer, `compact` on tablet. `pathname` and active IDs are current-context
hints, not entity payloads; read complete records from `host.store`.
hints, not entity payloads. Use a typed `host.context` read or host-verified action;
do not inspect private store slices from a released plugin.
Before customization, registration order is render order within each default side.
Users can Cmd-drag on macOS or Ctrl-drag elsewhere with a mouse to move any item
@@ -709,6 +1156,13 @@ and `getTaskMenuActions(group?)`. `unregisterWsHandler(pluginId, action, handler
removes exactly one WS handler (used by `host.storage.subscribe`'s returned
unsubscribe) without disturbing the plugin's other registrations.
Before `initialize`, the loader records `ActivePlugin.repositoryProviderIds` for the
plugin ID. A present declaration is an allowlist for provider/review registration; an
absent declaration is tolerated only for older payload compatibility. Disable/unload
removes this declaration with the plugin's registrations. Failed/timed-out activation
performs the same cleanup and an attempt token prevents late async registrations from
reappearing.
Plugin top-level routes render inside `PluginPageFrame`
(`apps/web/components/plugins/plugin-page.tsx`): a `PageTopbar` title bar above
a scrollable content area, resolved from `options.topbar` with derived
@@ -768,8 +1222,9 @@ Plugin JS runs in the kandev origin with store access — this is the accepted
tradeoff of option C. v1 mitigations: only **active, operator-installed** plugins
load; bundles are served by kandev from the extracted package directory (same-origin,
no third-party CDN, no upstream network hop); host wraps `initialize` in try/catch so
a broken plugin can't crash boot; registrations namespaced + bulk-revocable per
plugin. No credentials are ever displayed to the operator — installing a plugin (via
a broken plugin can't crash boot; failed/timed-out activation is rolled back; and
registrations are namespaced + bulk-revocable per plugin. No credentials are ever
displayed to the operator — installing a plugin (via
URL or upload) has nothing to copy or reveal, unlike the old register flow's one-time
API key/webhook secret. Sandboxing plugin JS (worker/realms) is explicit future work.