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
@@ -26,11 +26,20 @@ reliably from database metadata alone. They become eligible for host-sensitive
actions only after local-origin discovery or an explicit provider import/update
records the host.
For plugin providers, authority alone is still insufficient: two self-managed
instances can share one host while using different context roots. Persist an opaque,
credential-free `provider_scope` alongside the provider's immutable repository ID.
When both are present, the authoritative identity is workspace + provider + scope +
repository ID; owner/name/clone URL are mutable routing and display data. Scoped
imports never adopt an unscoped legacy row, and managed clone paths hash the complete
scope and immutable ID. Before reusing an existing scoped checkout, Kandev verifies
that its exact credential-free origin matches the requested clone URL.
## Consequences
Self-managed provider repositories are unambiguous across workspaces and host
changes, and frontend selection can use the same identity contract as backend
authorization. Repository persistence and API contracts gain one field, and
Self-managed provider repositories are unambiguous across workspaces, hosts, and
context roots, and frontend selection can use the same identity contract as backend
authorization. Repository persistence and API contracts gain origin/scope fields, and
legacy provider rows with unknown hosts require refresh or re-import before
GitLab-specific linking and creation actions are available.
@@ -43,3 +52,5 @@ GitLab-specific linking and creation actions are available.
existing repository as belonging to a different GitLab instance.
- Keep host only in frontend state. Rejected because backend association and
execution boundaries must enforce the same identity independently.
- Treat authority plus owner/name as sufficient. Rejected because Data Center
context roots can collide and repository slugs can be renamed.
@@ -0,0 +1,70 @@
# ADR-2026-07-31-authenticated-plugin-actions: Authenticated Plugin Actions
**Status:** accepted
**Date:** 2026-07-31
**Area:** backend, frontend, protocol, security
## Context
The frontend plugin host currently maps plugin fetches toward `/api/plugins/:id/...`,
while the host plugin endpoint is an externally callable webhook proxy. Reusing that
public callback surface for browser commands would bypass normal user authentication,
resource authorization, request limits, and cancellation controls.
Repository-provider plugins need browser-triggered connection, browse, review, and
watch operations without turning each provider into a first-party HTTP route.
## Decision
The manifest declares plugin action keys, each with canonical field `scope` set to
`workspace`, `task`, or `repository`, plus a bounded body size. Kandev continues to
read the prerelease `resource_scope` spelling for package compatibility, but new
manifests and serialized records use `scope`. Kandev exposes one authenticated
route: `POST /api/plugins/:id/actions/:key`. It rejects inactive plugins and undeclared
actions; normal Kandev authentication and server-side authorization verify every
referenced resource before the host dispatches `Plugin.HandleAction`.
The host derives task/workspace relationships itself, forwards verified actor and
resource context separately from untrusted action JSON, applies a hard timeout and
cancellation, caps request/response bodies, and permits only a small response-header
allowlist. The frontend contract is `host.api.invokeAction(...)`; plugin code must not
use public webhook paths for authenticated browser work. Resource selectors use the
documented camelCase JSON envelope (`workspaceId`, `taskId`, `repositoryId`). Callers
may pass an `AbortSignal`; registry/provider teardown propagates it through the browser
request and backend context.
`PluginActionResponse.status` is an optional HTTP status projection. Zero keeps the
legacy `200 OK`; otherwise the host accepts statuses from 200 through 599. This lets
provider-neutral adapters preserve safe domain outcomes such as invalid input,
authentication expiry, conflicts, and rate limits without turning them into transport
failures. `Retry-After` joins the response-header allowlist for throttling responses.
Invalid statuses fail closed as `502`, while plugin transport/runtime failures remain
`503` and do not expose internal error text.
The Go SDK defines stable typed action categories (`ActionErrorCode`) and shared HTTP
projection (`ActionErrorHTTPStatus`). Plugins preserve causes with
`CategorizeActionError`/`CategorizeActionErrorWithRetry` and map only typed provider or
domain failures. Message-substring classification is outside the contract because it
changes under wrapping/localization and can misreport authorization, conflict, or
retry behavior.
`/api/plugins/:id/webhooks/:key` remains public only for provider callbacks/events.
OAuth callbacks use signed, expiring, single-use state and PKCE.
## Consequences
Future plugins gain one reusable browser-to-plugin RPC seam without Kandev learning
provider endpoints or payloads. Plugin authors declare each action up front and must
design against explicit resource scope and bounded input/output. The host gains a
security-critical authorization boundary, but no provider-specific handler branch.
Callers can distinguish retryable and user-correctable domain outcomes while the host
continues to redact unexpected implementation failures.
## Alternatives Considered
- Reuse public webhook proxy for browser calls: rejected because callback endpoints do
not establish user identity or authorize Kandev resources.
- Add provider-specific REST routes in the host: rejected because every connector
would pull provider payloads and authentication into core.
- Let frontend bundles call plugin processes directly: rejected because managed plugin
transport is not a browser-accessible authorization boundary.
@@ -0,0 +1,81 @@
# ADR-2026-07-31-plugin-repository-provider-extensions: Plugin Repository Provider Extensions
**Status:** accepted
**Date:** 2026-07-31
**Area:** frontend, backend, protocol
## Context
Kandev task creation, Link menus, and review panels contain provider-specific GitHub/
GitLab assumptions. A connector plugin must contribute repository discovery, pull-
request actions, and native review UI without adding a Bitbucket branch or leaving
mobile as a compressed desktop-only escape hatch.
## Decision
The frontend plugin registry gains revocable, manifest-owned registrations for:
- `registerRepositoryProvider(...)` with repository listing, URL matching, branch
listing, and credential-free `inspectURL` descriptors whose clone URL is HTTPS;
- `registerTaskAction(...)` for children of the existing **Link** submenu, with
visibility and an async handler receiving read-only current
workspace/task/repository context;
- `registerReviewProvider(...)` with normalized task-item summaries, external-store
`getSnapshot`/`subscribe`/cancellable `refresh`, and a plugin-owned `ReviewPanel`.
The frontend author boundary is the independently consumable, runtime-free
`@kandev/plugin-sdk` package. It exposes named provider/review/UI contracts and a
typed `host.context` read service. Private Zustand `AppState` access remains only as
legacy runtime compatibility and is not part of the public SDK; official and new
plugins must request provider-neutral context additions instead of copying host store
shapes.
Registration icon fields accept either a backwards-compatible curated host icon
name or a plugin-owned component rendered through the supplied host React runtime.
Provider brand glyphs belong to the provider plugin, so adding another code host
does not require a brand import or lookup-table edit in Kandev production code.
Repository URL ownership is established by cancellable, workspace-scoped structured
inspection. `matchesURL` is optional and only narrows candidates; `inspectURL` returns
`null` when the configured provider does not own the URL. The host rejects multiple
successful inspectors as ambiguous rather than selecting registration order. This is
required for overlapping self-hosted URL shapes.
Providers have unique active ownership, are removed on plugin disable/unload, and
abort their in-flight work. Activation is transactional: a failed or timed-out
`initialize` revokes partial registrations and fences late callbacks from restoring
them. The host adapts GitHub, GitLab, and Azure implementations to the same contracts.
It accepts a complete plugin-inspected provider descriptor, including an exact
credential-free HTTPS clone URL, rather than parsing plugin provider URLs.
Task link actions render in existing desktop and visible mobile menus. A generic
top-level `action` placement is deliberately deferred until Kandev has a host-owned
workflow contract for command eligibility, result handling, and review navigation;
accepting registrations with no consumer would be a false public API. Review panels use
provider-neutral IDs and params `{ providerId, reviewKey }`; legacy GitHub/GitLab
layout names remain aliases. The host's native desktop and mobile review surfaces own
navigation and placement, while the plugin owns provider data and rendering.
Task-link surfaces remain host-owned through `openTaskLinkDialog`; `openModal` remains
available for plugin-owned workflows but is not a substitute for native task actions.
Native review surfaces expose provider-neutral selection when
multiple built-in or plugin reviews exist instead of silently choosing the first.
Selections are revalidated by provider and review key after unload/reload, so a stale
same-ID provider instance cannot keep an obsolete item selected.
## Consequences
Repository providers and review actions become extensible without host provider
knowledge. Registry lifecycle and normalized item contracts are more deliberate, and
existing built-ins require adapter work. Plugin review components must tolerate host
selection, persistence, task switching, close, and mobile presentation changes.
Released frontend plugins compile against a semver contract instead of the host
application's private module graph.
## Alternatives Considered
- Hard-code Bitbucket alongside GitHub/GitLab: rejected because every new provider
would enlarge host provider unions and duplicate routing logic.
- Give plugins only a standalone route: rejected because it omits native Link and
review flows users already rely on.
- Register React hooks for reviews: rejected because plugin load/unload can violate
hook ordering; an external-store source is lifecycle-safe.
@@ -0,0 +1,71 @@
# ADR-2026-07-31-provider-neutral-git-credential-broker: Provider-Neutral Git Credential Broker
**Status:** accepted
**Date:** 2026-07-31
**Area:** backend, protocol, security
## Context
GitHub has lease mechanics in a GitHub-specific broker, while other paths inject raw
credentials into executor wiring. A repository-provider plugin needs clone, fetch, and
push credentials without persisting tokens in URLs, task state, environment variables,
logs, or process arguments. Self-managed repository URLs must retain exact host, path,
and context path.
## Decision
Kandev extracts generic lease issuance, redemption, authorization, expiry, and
revocation into `internal/gitcredentials/`. A composite resolver preserves current
GitHub behavior through an adapter and adds an optional plugin `ResolveGitCredential`
RPC. The plugin receives host-verified plugin/provider/workspace/task/session/
repository/exact-host/path scope and returns a generic short-lived credential shape;
provider-specific username/token formatting remains plugin-owned.
Credential-capable plugins also implement `GetGitCredentialBinding` for the same exact
scope. It returns an opaque non-secret connection generation. Kandev stores that value
when issuing a lease and compares it before and after each secret redemption; an empty,
unsupported, rotated, or disconnected binding revokes the lease. The host never
resolves a secret merely to inspect its generation.
Executors receive opaque short-lived helper leases. Redeeming a lease re-resolves
against the live provider, so OAuth refresh does not require a task restart. Leases are
scoped to exact workspace, task, session, repository, host, and path; they revoke on
teardown, plugin disable/error/uninstall, credential-generation change, and connection
reset. Disabling, failing, or uninstalling a plugin immediately revokes every lease for
each provider it declared; later redemption does not wait for expiry. Host matching is
normalized, while repository paths remain case-sensitive and exact. The helper carries
the requested path without appending or removing `.git`. Remote executor transport uses
HTTPS.
Host-local initial repository materialization uses the same verified scope before it
creates a checkout. The orchestrator and workspace-source materializer must carry the
canonical task ID, active session ID, and persisted repository ID explicitly into the
clone credential request; the cloner must not reconstruct them from provider data or
accept browser-selected identifiers. A plugin-provider clone without that complete
scope fails closed. GitHub's legacy workspace credential adapter remains compatible,
but generic plugin providers never receive a weaker initial-clone request than later
fetch/push lease redemption.
`RepositoryCloneURL` remains authoritative and is never reconstructed from provider
fragments.
Before creating a worktree from an existing plugin-provider checkout, the orchestrator
performs a strict origin refresh through that same exact scope. It then marks the
in-memory launch as already refreshed; local and worktree preparers consume local and
`origin/*` refs without issuing a second unauthenticated fetch or pull. A failed scoped
refresh fails the launch closed.
## Consequences
New repository providers can participate in Git operations without host credential
branches or secret leakage. The host must carry stricter lease scope and lifecycle
checks, and plugins must resolve credentials promptly while handling rotation. GitLab
is not migrated as part of this decision.
## Alternatives Considered
- Put provider tokens in clone URLs or executor environment variables: rejected
because both spread durable or observable secrets.
- Add a Bitbucket broker beside GitHub's: rejected because it repeats a cross-provider
security boundary.
- Reconstruct clone URLs from provider fields: rejected because Data Center context
paths and configured origins would be lost or silently changed.
@@ -0,0 +1,54 @@
# ADR-2026-08-01-bitbucket-initial-release-remains-unsigned: Bitbucket Initial Release Remains Unsigned
**Status:** accepted
**Date:** 2026-08-01
**Area:** infra, workflow, security
## Context
Kandev currently verifies every plugin package's generated internal
`checksums.txt`, but it does not verify `checksums.txt.sig`; installed packages
are therefore reported as unsigned. The Bitbucket implementation plan had made
a signed release a publication gate even though no host trust policy, verifier,
approved key, or key-rotation process exists. Producing a signature that the
host cannot authenticate would add ceremony without adding enforceable trust.
## Decision
The initial official `kandev-plugin-bitbucket` release may use the current
unsigned marketplace contract. Its package must contain the generated internal
`checksums.txt`, its public GitHub Release may include the standard advisory
release-level checksum asset, and its source remains public and subject to the
official catalog's maintainer review. Kandev will report the installed package
as unsigned, and neither repository may claim that the release is signed or
that its publisher provenance is cryptographically verified.
Signing is not a Bitbucket release gate. Enforceable plugin signing remains
future host-wide work and requires a superseding decision covering signature
verification, trusted-key or identity distribution, rotation and revocation,
and fail-closed policy before official plugins can rely on it.
## Consequences
- Bitbucket follows the trust posture already implemented for other plugins
instead of inventing an integration-specific signing ceremony.
- Package checksums detect extraction corruption and unexpected file changes,
but they do not authenticate who produced an archive. Trust still rests on
the public source and release repository, curated catalog review, and the
operator's explicit install/update action.
- The signing decision no longer blocks Bitbucket publication; host
compatibility, live provider behavior, packaged-host, and credential-broker
evidence remain independent release gates.
- A future signing rollout must deliberately supersede this decision and may
require republishing or reattesting the plugin.
## Alternatives Considered
- **Block Bitbucket until signing exists.** Rejected because no shipped verifier
or trust-root policy exists, while the marketplace explicitly supports
unsigned packages.
- **Generate an ad hoc Ed25519 signature for Bitbucket.** Rejected because the
host could not authenticate it and no approved distribution, rotation, or
revocation process exists.
- **Require Sigstore provenance for this plugin alone.** Rejected as a useful
future direction that first needs a host-wide verification and policy design.
@@ -33,6 +33,15 @@ timer:
- stale generations cannot publish lifecycle completion or registrations over a newer
load.
Repository and review provider callbacks use the same authority. The registry does not
only request cooperative cancellation: it races every callback against the owning
generation's abort signal, refuses to start already-aborted work, and rejects late
results with `AbortError` even when third-party code ignores its signal. Subscription
cleanup is likewise owner-tracked and idempotent. Unloaded code therefore cannot
publish stale repositories, review snapshots, or callback results into a newer UI.
Synchronous coarse callbacks such as repository `matchesURL` are also fault-isolated:
a throw is treated as no match in every host call site, never as a task-dialog crash.
Desktop dockview and the phone task layout consume the same lifecycle authority. If a
removed plugin panel is focused on a phone, the mobile session state changes to `chat`.
Mobile-enabled registrations are exposed through one touch-sized **Panels** bottom-nav
@@ -65,6 +74,10 @@ uninstall failures instead of warnings, so an operator may need to retry after a
database problem; this is preferable to reporting success while retaining private
data.
Provider work becomes result-fenced as well as cancellation-aware. This adds a small
host wrapper around callbacks, but makes unload safety independent of third-party abort
discipline.
## Alternatives Considered
- **Keep a longer revocation timeout.** Rejected because no finite duration proves that
@@ -0,0 +1,55 @@
# ADR-2026-08-05-plugin-native-integration-settings: Plugins Contribute Native Integration Settings
**Status:** accepted
**Date:** 2026-08-05
**Area:** frontend, protocol
## Context
An integration plugin can register an arbitrary plugin settings route, but that route
appears under Settings > Plugins and does not participate in Kandev's native
Settings > Integrations index, workspace navigation, or workspace-scoped URL model.
Official integrations such as Bitbucket should use the same discovery and settings
structure as built-in integrations without adding provider-specific rendering branches
to the host.
## Decision
The frontend plugin registry adds
`registerIntegrationSettings({ id, label, description, icon?, Component })`.
`Component` receives `{ workspaceId?: string }`; the host renders it in the existing
settings shell at both `/settings/integrations/{id}` and
`/settings/workspace/{workspaceId}/integrations/{id}`, and adds the contribution to
the native integrations index and workspace settings navigation. The host wraps the
component's plugin-owned cards and controls in the shared `SettingsSection`, using the
registered label, description, and resolved icon, and uses the label in settings
topbar chrome.
Integration IDs are URL-safe slugs. First-party integration IDs remain reserved, one
active plugin owns each contributed ID, collisions fail without replacing the current
owner, and unload revokes the contribution. Labels, descriptions, icons, and rendering
stay plugin-owned; the host contains no provider-specific settings branch. Curated
brand icons remain a host-owned string-to-component map, including `bitbucket`.
Operational plugin routes remain separate. An integration's queue, review, or browse
workbench may live at its normal plugin route, while credentials, connection health,
and watch configuration use the native integration settings contribution.
## Consequences
Official and third-party integrations can feel first-party in Settings while retaining
independent release ownership. Plugins must choose a stable non-reserved slug and make
their settings component work with either an explicit workspace or the legacy global
route; it returns the section body rather than duplicating the host heading. The host
owns navigation, responsive settings chrome, error containment, and
lifecycle; the plugin owns all provider-specific fields and behavior.
## Alternatives Considered
- Keep integration configuration under Settings > Plugins: rejected because it makes
an installed integration use a different information architecture from built-ins.
- Let plugins register arbitrary `/settings/integrations/...` routes: rejected because
route registration alone cannot safely contribute index metadata, workspace
navigation, ownership, or collision handling.
- Add a Bitbucket-specific settings page to the host: rejected because future provider
plugins would repeat the same core coupling.
@@ -0,0 +1,161 @@
# ADR-2026-08-06-plugin-code-host-dashboard-parity: Code-Host Plugins Reuse Native Dashboard Primitives
**Status:** accepted
**Date:** 2026-08-06
**Area:** frontend, protocol
## Context
GitHub and GitLab dashboards share one interaction model, but their list and toolbar
components remained provider-coupled. The first Bitbucket plugin therefore reproduced
their appearance with plugin CSS while inventing a second dashboard review action and
an intermediate launch dialog. Visual similarity did not preserve the native task and
review workflow.
## Decision
Kandev owns provider-neutral code-host dashboard primitives under
`apps/web/components/integrations/` and exposes them through `host.ui`. GitHub, GitLab,
and compatible plugins render their result list, row, toolbar, scope controls, task
preset menu, linked-task indicator, and semantic change-request icons through those
same host components. Plugins select icon semantics such as open, merged, or closed;
they do not copy SVG paths from first-party providers.
Task presets use the same provider-neutral semantic icon keys as first-party presets.
The host resolves those keys to its Tabler components, so **Review**, **Address
feedback**, and **Fix CI** render the exact eye, message, and tool glyphs everywhere.
Plugins do not pass custom icon components or rely on a generic fallback when a native
semantic equivalent exists. Provider brand glyphs are different: the plugin owns that
component and Kandev reuses it across native surfaces.
Kandev also owns common task change-request linking anatomy. Code-host plugins invoke
the host task-link dialog contract with provider copy and a submit callback; they do not
rebuild the input, validation, loading state, footer, toast, close behavior, or responsive
surface inside an arbitrary plugin modal. A Link-submenu child names the target only
(for example, **Bitbucket Pull Request**) because the parent already supplies the verb.
The singleton plugin modal host mounts inside `AppShell`'s theme, tooltip, and toast
provider tree so host-owned workflows retain the same runtime contexts as first-party
dialogs.
Runtime React components remain in the Kandev host repository and are delivered by
the versioned `host.ui` contract. They do not move to a separate shared frontend
repository: host-owned React, Radix contexts, theme behavior, and release compatibility
must remain atomic. A future published SDK package may provide TypeScript contracts
and pure build-time helpers once multiple plugin repositories need them, but it must
not duplicate runtime UI implementations.
A code-host dashboard row is an inert result container. Its title opens the provider,
its metadata describes the change request, and its sole creation control is the compact
**Task** preset dropdown. Selecting a preset opens the host's real
`TaskCreateDialog` directly; provider linking runs after successful task creation.
Dashboard rows do not add a **Review** action or a provider-owned intermediate launch
modal. Review begins from linked task context through the existing review-provider
registry on desktop and mobile.
When the selected repository already exists in the workspace, the dialog keeps its
normal REST create transport. For a first-use plugin repository, the plugin may inject
the dialog's provider-neutral `createTask` transport and forward only native task
fields through an authenticated plugin action. The plugin server resolves the pull
request and trusted repository descriptor from its connection before calling Host
`Tasks.Create`; browser input never grants repository-provider authority. A per-dialog
launch identifier makes transport retries idempotent without limiting one pull request
to one task.
Kandev also owns task-scoped change-request status presentation. A review-provider
summary may include normalized status/check data; the host review registry preserves it,
refreshes it through the existing provider lifecycle, and automatically mounts the same
shared control in both first-party locations: the task topbar and the status row above
the chat composer (including passthrough sessions). The host owns the exact trigger,
delayed desktop hover popover, native mobile drawer, accessibility, touch geometry, and
responsive behavior. Providers do not register a visual status slot. They supply data,
refresh it around every 90 seconds, and retain provider API ownership.
The shared status body is the provider-neutral presentation extracted from GitHub's CI
popover. Its common header, grouped checks, review/comment summaries, links, loading,
empty, and error states render identically for built-ins and plugins. Provider-only
controls such as automation or merge actions are optional callbacks/capabilities inside
that anatomy, not alternate markup. Opening Review routes through the registered review
provider on desktop or the current mobile session.
Kandev likewise owns the common change-request detail presentation exposed through
`host.ui.ChangeRequestDetail`. GitHub and compatible review providers map their native
payloads into one normalized detail model and pass supported action callbacks. The host
owns header, branch/state metadata, description, reviews, checks, threaded comments,
action placement, loading/error states, scroll ownership, and responsive behavior.
Providers retain queries, authorization, mutation semantics, capability detection, and
normalization. A plugin may still own a review-panel adapter, but not a parallel visual
design for those common surfaces.
Every successful PR-from-task creation and watch-created task records the same durable
task-to-change-request association exposed by manual linking. Watch-owned links remain
authoritative in watch state and are unioned with manual link state when serving task
review/status and workspace association queries; implementations do not copy them into
a second store merely for presentation. Durable association, suppression, reservation,
and watch keys use provider ID, provider connection scope, immutable repository ID, and
change-request number. Repository paths, display keys, and clone URLs are mutable lookup
attributes and never durable identity. A changed connection epoch pauses an existing
watch before provider access; resuming explicitly rebinds it and discards its old cursor.
Task-scoped refresh also performs bounded branch-based discovery, equivalent to
GitHub's external-PR detection. It derives repository and checkout branch only from the
host-verified task, exact-matches an open provider change request's source branch, and
stores the result idempotently. Browser-supplied repository or branch values never
authorize automatic linking, and discovery failure does not hide an existing link.
The native task dialog's branch picker follows the same provider-neutral trust boundary.
For a persisted plugin-owned repository, the host resolves the active manifest owner and
invokes its declared workspace-scoped `repositories.branches` action with a descriptor
derived only from the stored repository row. The action returns normalized branch names;
the browser cannot substitute provider identity, host, namespace, clone URL, or repository
ID. GitHub remains on its first-party service path, while future code-host plugins reuse
this action instead of adding another host-native provider branch.
Provider adapters continue to own API queries, normalization, authorization, task-link
storage, provider data, and capability handling. Shared host components own presentation
and interaction geometry; they accept normalized data and callbacks and contain no
GitHub, GitLab, or Bitbucket API logic.
Repository discovery is a provider-neutral, server-searchable paged contract. The host
passes optional `query`, opaque `cursor`, and requested `limit` fields; providers return
either the legacy repository array or `{ repositories, nextCursor }`. The host follows
pages, rejects repeated cursors, and always binds returned provider identities to the
manifest owner. Registered plugin-owned provider icons are used in native repository
controls rather than a generic branch glyph. These rules keep large installations usable without adding
provider-specific search or pagination branches to Kandev. Provider cursors are bound to
the original query, state, provider connection scope, and immutable repository identity;
using one after any of those inputs changes fails before a provider request.
Task indicator and CI refreshes are summary operations. They fetch only normalized
change-request metadata, reviews, checks, and an inexpensive accurate unresolved-comment
count when the provider exposes one. Files, diffs, commits, and comment bodies load lazily
when Review opens. Both summary and detail responses remain bounded, with explicit
truncation instead of exceeding the authenticated plugin action response limit.
Pipeline/build status is read from the pull request's source (head) commit. The
destination commit describes the merge target and cannot represent the CI result for
the proposed change.
## Consequences
Code-host plugins require a host release containing these additive `host.ui` exports.
Dashboard fixes now apply uniformly to first-party and plugin providers, including
themes, touch targets, dropdown behavior, loading/error states, and row density.
Provider adapters remain independently releasable, while common review/status visuals
enter the versioned host contract. New semantic icon or presentation needs require an
additive host contract release rather than a plugin-local visual approximation. Plugin
repositories avoid a second runtime UI dependency and its version-skew/release-
coordination cost. Task-link, status, and detail fixes land once in the host and remain
consistent for first-party and plugin providers, without moving provider polling,
credentials, or API payloads into Kandev.
## Alternatives Considered
- Keep copying GitHub/GitLab markup and CSS into each plugin. Rejected because the
first live implementation already drifted in behavior despite similar styling.
- Export GitHub's `PRList` directly. Rejected because its status hooks, payloads, and
task associations are GitHub-specific rather than a reusable plugin contract.
- Permit each provider to choose its own dashboard actions. Rejected for first-party-
parity code hosts because it makes task creation and review placement inconsistent.
- Put shared React components in a dedicated repository/package. Rejected because it
would split host UI contexts and versioning; only pure types/helpers may be published
later if repeated plugin-authoring demand justifies them.
@@ -1,7 +1,7 @@
# ADR-2026-08-10-no-em-dash-public-copy: Keep Em Dashes Out of Public Copy
**Status:** accepted
**Date:** 2026-08-10
**Status:** accepted
**Date:** 2026-08-10
**Area:** frontend, infra
## Context
@@ -0,0 +1,69 @@
# ADR-2026-08-10-plugin-change-request-mutations: Route Native Change-Request Mutations Through Providers
**Status:** accepted
**Date:** 2026-08-10
**Area:** frontend, protocol
## Context
Repository-provider plugins can list repositories and expose review data, but Kandev's
native **Create PR** workflow still delegates the complete operation to `agentctl`,
whose provider-specific creation code supports only built-in hosts. Registered review
providers likewise have no native unlink mutation or workspace association source, so
plugin links cannot drive the same task-row indicators and unlink controls as built-in
change requests.
## Decision
`RepositoryProviderRegistration` gains an optional provider-neutral change-request
creation callback. Kandev keeps the native create dialog and performs the ordinary Git
push first through the existing executor path. Only after that push succeeds does the
host call the active repository provider with the current workspace, task, session,
persisted repository, title, description, destination branch, and supported options.
Plugin callbacks must cross the authenticated action boundary. The callback forwards
the session only as a selector: Kandev verifies that it belongs to the task, resolves
the selected repository's exact worktree branch server-side, and adds that branch to
`VerifiedActionContext`. Plugin servers use this verified head branch and repository;
browser body fields never select the source branch.
Normalized open reviews from registered providers also participate in the native VCS
action state, so an already-linked plugin change request suppresses the primary
**Create PR** action exactly like a built-in pull request.
For a task-scoped action, the browser may include optional `repositoryId` and
`sessionId` selectors. Kandev accepts the repository only when it is attached to the
verified task and accepts the session only when it belongs to that task. When both
selectors are present, the repository must have a worktree in that session and Kandev
supplies its non-empty branch as `headBranch`; omitting selectors preserves existing
task-only action behavior.
`ReviewProviderRegistration` gains optional unlink and workspace-association external-
store methods. Kandev renders unlink controls and task-row/card change-request glyphs
from those normalized callbacks and snapshots. Providers own association queries and
mutations; the host owns placement, accessibility, responsive behavior, pending/error
feedback, lifecycle cancellation, and semantic icons.
An explicit unlink must remain detached: provider implementations suppress automatic
source-branch relinking for that task/review pair until the user explicitly links it
again, and watch-owned associations relinquish ownership without deleting the task.
Built-in providers retain their current adapters. `agentctl` receives no Bitbucket or
plugin dispatch branch. Callback work and association subscriptions are revoked with
their owning plugin, matching the existing repository/review provider lifecycle.
## Consequences
Future code-host plugins can participate in native create, unlink, and task-indicator
workflows without provider-specific host branches. Creation now has a deliberate
two-stage failure model: a successful push followed by a failed remote create reopens
the native dialog in retry state and does not push again unnecessarily. Provider
implementations must truthfully declare option support and make create retries safe.
Normal Kandev tasks need not copy session worktree branches into task-repository
metadata merely to authorize a plugin create operation.
## Alternatives Considered
- Add Bitbucket creation to `agentctl`: rejected because it moves plugin API/auth logic
into the host and repeats for every future provider.
- Register a plugin-owned **Create PR** button or modal: rejected because it duplicates
Kandev's native Git eligibility, dialog, feedback, and mobile behavior.
- Infer plugin links by refreshing every task's full review detail: rejected because a
task list would create an unbounded provider-request fan-out; one workspace
association snapshot is the reusable bounded contract.
@@ -0,0 +1,43 @@
# ADR-2026-08-12-plugin-localization-contract: Host-Scoped Plugin Localization
**Status:** accepted
**Date:** 2026-08-12
**Area:** frontend, protocol
## Context
Native UI plugins render inside Kandev but ship independently, so their copy cannot live in the
application's built-in catalogs. Giving plugins direct access to the shared i18next instance would
let one plugin collide with or remove another plugin's messages, and hardcoded English prevents
locale changes and pseudo-locale QA.
## Decision
The runtime-free `@kandev/plugin-sdk` contract exposes
`registry.registerTranslations(catalogs)` plus a plugin-scoped `host.i18n` API. Every catalog must
include English, may target only Kandev-supported locales, and uses bounded flat message keys. The
host mounts catalogs under a namespace derived from the verified plugin ID, supplies imperative
`t()` and reactive `useTranslation()` access, and removes resources on disable, reload, failed load,
or uninstall.
Plugin React surfaces use `host.i18n.useTranslation()` so locale changes rerender without reload.
Imperative callbacks use `host.i18n.t()` at execution time. Registration metadata that must remain
live uses accessor properties backed by `host.i18n.t()`; the registry preserves those accessors and
invalidates its subscribers when locale changes. Provider data, user content, identifiers, and
machine-readable discriminants are never translated or used as translated control-flow tokens.
## Consequences
Official and third-party plugins can follow Kandev locale and pseudo-locale behavior without
bundling i18next or importing private application modules. Catalogs remain isolated and lifecycle
safe, while English remains a guaranteed fallback. Plugin authors must maintain their own catalogs,
and human-locale parity remains advisory just like Kandev's built-in catalogs.
## Alternatives Considered
- Put official plugin copy in Kandev's built-in catalogs. Rejected because plugin releases would
remain coupled to host releases and community plugins could not participate.
- Expose the shared i18next instance. Rejected because namespace ownership and cleanup would be
unenforceable.
- Let each plugin bundle its own localization runtime. Rejected because locale selection, fallback,
pseudo-locale QA, and lifecycle behavior would diverge across plugins.
+8
View File
@@ -64,6 +64,10 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 2026-07-23-post-commit-hook-aware-verification | [Post-Commit Hook-Aware Verification](2026-07-23-post-commit-hook-aware-verification.md) | superseded by 2026-07-26 | workflow | 2026-07-23 |
| 2026-07-23-workspace-source-root-move-boundary | [Workspace Source Root Move Boundary](2026-07-23-workspace-source-root-move-boundary.md) | accepted | backend | 2026-07-23 |
| 2026-07-24-operator-owned-agent-launcher-settings | [Operator-Owned Agent Launcher Settings](2026-07-24-operator-owned-agent-launcher-settings.md) | accepted | backend, frontend, protocol | 2026-07-24 |
| 2026-08-05-plugin-native-integration-settings | [Plugins Contribute Native Integration Settings](2026-08-05-plugin-native-integration-settings.md) | accepted | frontend, protocol | 2026-08-05 |
| 2026-08-06-plugin-code-host-dashboard-parity | [Code-Host Plugins Reuse Native Dashboard Primitives](2026-08-06-plugin-code-host-dashboard-parity.md) | accepted | frontend, protocol | 2026-08-06 |
| 2026-08-10-plugin-change-request-mutations | [Route Native Change-Request Mutations Through Providers](2026-08-10-plugin-change-request-mutations.md) | accepted | frontend, protocol | 2026-08-10 |
| 2026-08-12-plugin-localization-contract | [Host-Scoped Plugin Localization](2026-08-12-plugin-localization-contract.md) | accepted | frontend, protocol | 2026-08-12 |
| 2026-07-18-turn-configuration-snapshots | [Attribute runtime configuration to turns](2026-07-18-turn-configuration-snapshots.md) | accepted | backend, frontend | 2026-07-18 |
| 2026-07-22-gpg-signed-release-tags | [GPG-signed release tags](2026-07-22-gpg-signed-release-tags.md) | accepted | infra, workflow | 2026-07-22 |
| 2026-07-19-reject-mcp-actions-on-raw-websocket | [Reject MCP Actions on the Raw WebSocket](2026-07-19-reject-mcp-actions-on-raw-websocket.md) | accepted | backend, protocol | 2026-07-19 |
@@ -93,6 +97,10 @@ Read individual ADRs for full context. Create new ones via `/record decision` or
| 2026-07-30-session-owned-mcp-observability | [Keep MCP Attachment Evidence Session Owned](2026-07-30-session-owned-mcp-observability.md) | accepted | backend, frontend, protocol, security | 2026-07-30 |
| 2026-07-30-file-backed-diagnostic-bundles | [File-backed diagnostic bundles](2026-07-30-file-backed-diagnostic-bundles.md) | accepted | backend, frontend, infra, protocol, workflow | 2026-07-30 |
| 2026-07-30-runtime-task-state-before-running-event | [Publish Task State Before Running Session State](2026-07-30-runtime-task-state-before-running-event.md) | accepted | backend, frontend, protocol, workflow | 2026-07-30 |
| 2026-07-31-authenticated-plugin-actions | [Authenticated Plugin Actions](2026-07-31-authenticated-plugin-actions.md) | accepted | backend, frontend, protocol, security | 2026-07-31 |
| 2026-07-31-plugin-repository-provider-extensions | [Plugin Repository Provider Extensions](2026-07-31-plugin-repository-provider-extensions.md) | accepted | frontend, backend, protocol | 2026-07-31 |
| 2026-07-31-provider-neutral-git-credential-broker | [Provider-Neutral Git Credential Broker](2026-07-31-provider-neutral-git-credential-broker.md) | accepted | backend, protocol, security | 2026-07-31 |
| 2026-08-01-bitbucket-initial-release-remains-unsigned | [Bitbucket Initial Release Remains Unsigned](2026-08-01-bitbucket-initial-release-remains-unsigned.md) | accepted | infra, workflow, security | 2026-08-01 |
| 2026-07-31-npm-nightly-release-channel | [Publish deterministic npm-only nightlies](2026-07-31-npm-nightly-release-channel.md) | accepted (amended 2026-08-03) | workflow, backend, frontend, cli | 2026-07-31 |
| 2026-07-31-isolate-manual-pr-review-content | [Isolate Manual PR Review Content](2026-07-31-isolate-manual-pr-review-content.md) | accepted | infra, workflow, security | 2026-07-31 |
| 2026-07-31-agent-generated-task-titles | [Bind Agent Title Generation to Pending Tasks](2026-07-31-agent-generated-task-titles.md) | accepted | backend, frontend, protocol | 2026-07-31 |
+208
View File
@@ -0,0 +1,208 @@
---
spec: docs/specs/bitbucket-plugin/spec.md
created: 2026-07-31
status: in_progress
---
# Implementation Plan: Bitbucket Connector Plugin
## Overview
Release generic host seams before plugin behavior: authenticated actions, plugin
registry contracts, dynamic composer sources, richer task ownership, and a provider-
neutral credential broker. Build Cloud/Data Center adapters and plugin workflows only
after those seams land, then prove native task, review, composer, desktop, mobile, and
credential behavior through cross-repository acceptance.
The host remains provider-neutral. `kdlbs/kandev-plugin-bitbucket` owns Bitbucket
payloads, auth, product probes, watches, and UI. The required native hooks remain
**Link → Bitbucket Pull Request**, host-rendered review/status surfaces supplied by
plugin adapters, and composer `#` source search with submit-time authorization.
## Host contracts
- Add additive plugin RPC/SDK/manifest shapes and authenticated action dispatch.
- Add revocable repository-provider, task-action, and review-provider frontend
registrations; migrate built-ins through the same registry.
- Register/unregister dynamic backend composer reference sources and reauthorize every
reference at submission.
- Extend plugin-owned task lifecycle and provider-neutral descriptor validation.
- Replace GitHub-only broker mechanics with composite short-lived credential leases.
## Plugin repository
- Bootstrap `kdlbs/kandev-plugin-bitbucket` from official template in its attached
Kandev workspace; do not nest a clone under this repository.
- Implement separate Cloud and Data Center adapters, workspace-scoped encrypted auth,
health, capabilities, task/link/Git/watch workflows, and native registrations.
- Publish only after source/package, host/plugin desktop/mobile, and container broker
acceptance pass; marketplace mutation is last.
## Tests
- Host protocol/action tests cover declaration, normal authentication, resource
authorization, body caps, timeout/cancellation, response headers, and SDK
compatibility.
- Registry/task/review tests cover ownership collisions, unload cancellation, complete
provider descriptors, Link-group actions, layout aliases, desktop/mobile review
selection, and plugin teardown.
- Composer tests cover dynamic source lifecycle, canonical identity, workspace
isolation, search and submission authorization, disabled plugins, and generic
presentation.
- Credential tests cover exact scope, expiry/revocation, refreshed resolution,
leakage, custom host/path, and local/remote executor helper use.
- Plugin tests cover Cloud/DC fixture mapping, auth rotation/PKCE, capability probes,
health/retry, watch concurrency/recovery, ownership-safe deletion, and responsive UI.
- Plugin page parity tests compare `/bitbucket` with the first-party `/github`
list-first structure: scope bar, compact toolbar, bordered rows, focused review URL,
and native mobile list/detail navigation.
## E2E tests
- Install/enable fixture package; call a declared authenticated action without exposing
a webhook as a browser RPC.
- Select a plugin provider in native task creation, import/inspect a PR, invoke
**Link → Bitbucket Pull Request**, then open the plugin native review panel on
desktop and mobile.
- Select a `#` Bitbucket pull request and prove submitted metadata is authorized.
- Verify watch-created task, unload/reload cleanup, secret-free failure UI, and real
HTTPS clone/push in the containers project.
## Implementation waves and task files
Wave 0 (parallel-safe, docs/external repository only):
- [x] [task 01 — design package](task-01-design-package.md)
- [x] [task 02 — plugin repository bootstrap](task-02-plugin-repository-bootstrap.md)
Wave 1 (parallel-safe after task 01):
- [x] [task 03 — protocol, manifest, authenticated actions](task-03-protocol-manifest-actions.md)
- [x] [task 04 — frontend plugin registry contracts](task-04-frontend-plugin-registry.md)
Wave 2 (parallel-safe after contract foundations):
- [x] [task 05 — dynamic composer reference sources](task-05-dynamic-composer-reference-sources.md)
- [x] [task 06 — plugin-owned task lifecycle](task-06-plugin-owned-task-lifecycle.md)
- [x] [task 07 — provider-neutral git credential broker](task-07-provider-neutral-git-credentials.md)
- [x] [task 08 — native repository provider task creation](task-08-native-repository-provider.md)
- [x] [task 09 — native Link and review surfaces](task-09-native-link-review-surfaces.md)
Wave 3 (plugin repository after declared dependencies):
- [x] [task 10 — Cloud/DC domain and authentication](task-10-cloud-dc-domain-auth.md)
- [x] [task 11 — task, Git, linking, and watch workflows](task-11-plugin-workflows-watches.md)
- [x] [task 12 — plugin UI and native registrations](task-12-plugin-ui-native-registrations.md)
Wave 3b (corrective UI pass after live evaluation):
- [x] [task 12b — GitHub-parity Bitbucket page](task-12b-github-parity-page.md)
Wave 3c (exact shared interaction parity after user evaluation):
- [x] [task 12c — exact shared code-host UI parity](task-12c-exact-code-host-ui-parity.md)
Wave 3d (native task-link parity after manual evaluation):
- [x] [task 12d — host-native task-link dialog parity](task-12d-host-native-task-link-parity.md)
Wave 3e (corrective host-owned task status after manual evaluation):
- [x] [task 12e — registry-backed shared task status](task-12e-shared-task-status.md)
Wave 3f (corrective host-owned review presentation; parallel with 12e):
- [x] [task 12f — shared change-request detail](task-12f-shared-review-detail.md)
Wave 3g (after 12e and 12f):
- [x] [task 12g — Bitbucket adapters and live parity acceptance](task-12g-bitbucket-status-detail-adapters.md)
Wave 3h (corrective native workflow pass after final manual evaluation):
- [x] [task 12h — native create, unlink, task indicators, and saved queries](task-12h-native-create-unlink-indicators-saved-queries.md)
Wave 3i (corrective sidebar hover parity after manual evaluation):
- [x] [task 12i — shared task-indicator hover summary](task-12i-shared-task-indicator-hover-summary.md)
Wave 4:
- [ ] [task 13 — contract E2E, release, and marketplace](task-13-contract-e2e-release-marketplace.md)
## Current status
Tasks 01–12i are implemented. Task 13 remains the
release/marketplace gate.
Live Cloud evaluation showed that task 12's permanent
desktop queue/review split diverged from the first-party `/github` page despite being
functionally complete; task 12b replaced it with the approved list-first parity model
and passed the live Cloud-connected desktop/mobile suite. User evaluation then found
that its equal **Task**/**Review** buttons and intermediate launch modal still diverged
from GitHub/GitLab interaction behavior. Task 12c replaced copied presentation and
plugin-specific launch/review placement with shared host primitives and native task
creation. Its first pass passed the complete host suite (1,010 files / 7,712 tests) and
seven live Cloud desktop/mobile checks. Manual testing then found that scope pills did
not commit their filter into the visible query and plugin-drawn SVGs did not match the
host's semantic icons. The corrected evaluation package commits scope selections
into the visible query, uses host-owned semantic Tabler icons, and passes eight live
Cloud desktop/mobile checks. It also registers the exact **Bitbucket Pull Request**
submenu label and invokes the shared host task-link dialog. Live evaluation caught the
modal host outside the host toast-provider tree; the corrected topology now mounts
plugin modals inside `AppShell`, and a production-topology regression test protects the
real form. Empty validation, authenticated Cloud linking, close-on-success, toast,
desktop geometry, and mobile no-overflow behavior pass against the disposable account.
Version 0.1.7 also proves exact preset glyphs, persisted-provider branch selection,
manual linking, exact-branch auto-link recovery, restart-safe watch associations, native
desktop/mobile Review, and live CI polling. The CI marker was changed
`SUCCESSFUL -> INPROGRESS -> SUCCESSFUL`; each 90-second poll updated the shared host
glyph and the remote fixture was restored.
Manual evaluation then established that the topbar body and Review panel were still
plugin-owned approximations and that no Bitbucket CI chip existed above the composer.
Tasks 12e–12g replaced those approximations with registry-backed, host-owned surfaces
used by GitHub itself. Package 0.1.10 passed desktop/touch live acceptance: the shared
topbar/composer anatomy, shared review detail, manual linking, exact-branch auto-link,
and a real `SUCCESSFUL -> INPROGRESS -> FAILED -> SUCCESSFUL` pipeline cycle all passed;
the fixture was restored.
Task 12h closed the final manual-evaluation gaps. Package 0.1.12 proved native Create PR
through the registered provider after a real Git push, shared unlink with reload-safe
detachment, workspace-hydrated sidebar indicators, and saved-query persistence and
restoration. The native Create PR control remains Kandev's existing Changes-panel
control; no duplicate plugin-specific create button was added.
Task 12i removed the association indicator's count-only tooltip. Registered providers
now reuse GitHub's host-owned structured pull-request summary and load task detail only
when the desktop indicator opens; the existing mobile Status/Review surfaces remain the
touch path. A manual follow-up also moved task-indicator color derivation into the shared
provider-neutral status palette, so normalized pipeline/review state changes the glyph
without provider CSS tokens. Unit, packaged-plugin desktop E2E, mobile contract E2E,
typecheck, and lint pass. The public authoring reference now includes a code-host hook
surface map and focused captures of the shared dashboard, repository picker, Link flow,
task status, CI, Review, and composer reference search.
The packaged generic host contract passes on desktop and
mobile. The actual package passes its unconfigured action, disable/re-enable, desktop,
and mobile lifecycle checks; its canonical composer reference now rehydrates the
repository/PR identity and performs live submit-time authorization. Plugin unit, race,
build, and five-platform archive checks pass. Cloud acceptance is complete for the
available disposable target. Task 13 remains in progress until a disposable Data Center
target and a container-reachable HTTPS credential-broker URL are available, the host
changes ship
in a release that can be named by `min_kandev_version`, and the remaining live gates
pass. The initial plugin release intentionally follows the current checksum-verified,
unsigned marketplace contract under
[ADR-2026-08-01-bitbucket-initial-release-remains-unsigned](../../decisions/2026-08-01-bitbucket-initial-release-remains-unsigned.md);
no signature or cryptographic publisher-provenance claim is made. No plugin tag,
release, or marketplace entry is created before the other gates pass.
## Risks
- Full parity is complete only when every capability-matrix row passes; alpha sideloads
may be partial but must be marked partial.
- BYO OAuth registration and Data Center network/version variation require clear
failure states, fixture coverage, and a release-time compatibility matrix.
- Generic host seams must pass a second-provider test: Bitbucket types, URL parsing,
and auth rules in host code are a design failure.
- Cross-repository release ordering is strict: host contract release precedes plugin
compatibility gate, package release, and marketplace entry.
- Same-version development copies keep the plugin bundle URL stable. Live evaluation
must use a fresh document or hard reload after UI-only asset replacement; released
plugin updates change the manifest version and therefore the bundle URL.
@@ -0,0 +1,56 @@
---
id: "01-design-package"
title: "Design package and task files"
status: completed
wave: 0
depends_on: []
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 01: Design package and task files
## Intent
Materialize approved Bitbucket connector behavior, generic host boundaries, ADRs, and
dependency-scoped implementation packets without touching production code.
## Dependencies
None.
## Owned paths
- `docs/specs/bitbucket-plugin/spec.md`
- `docs/specs/INDEX.md`
- `docs/specs/plugins/spec.md`
- `docs/decisions/2026-07-31-authenticated-plugin-actions.md`
- `docs/decisions/2026-07-31-plugin-repository-provider-extensions.md`
- `docs/decisions/2026-07-31-provider-neutral-git-credential-broker.md`
- `docs/decisions/INDEX.md`
- `docs/plans/bitbucket-plugin/`
- `docs/plans/plugins/GRPC-CONTRACT.md`
- `docs/plans/plugins/PLUGIN-API.md`
- `docs/plans/plugins/HOST-DATA-API.proto`
## Acceptance
1. Spec preserves Cloud+DC, API token/PAT+OAuth, full supported-capability parity,
plugin-first boundaries, native Link/review hooks, and composer submission
reauthorization.
2. Three ADRs and frozen contracts define generic reusable seams without Bitbucket API
payloads in the host.
3. `task-01` through `task-13` declare dependencies, owned paths, acceptance, exact
checks, and risks; indexes and relative links resolve.
## Verification
```sh
git diff --check
rg -n 'Link → Bitbucket Pull Request|submit-time|reauthoriz|Cloud|Data Center' docs/specs/bitbucket-plugin docs/plans/bitbucket-plugin
```
## Risks
Frozen contract drift can make later host/plugin tasks incompatible. Reconcile every
contract amendment with the approved parent plan before implementation starts.
@@ -0,0 +1,49 @@
---
id: "02-plugin-repository-bootstrap"
title: "Dedicated plugin repository bootstrap"
status: completed
wave: 0
depends_on: []
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 02: Dedicated plugin repository bootstrap
## Intent
Create public `kdlbs/kandev-plugin-bitbucket` from official plugin template and attach
that repository to its Kandev task. Establish package/CI skeleton only; make no
unsupported product claims.
## Owned paths
- Attached `kdlbs/kandev-plugin-bitbucket` worktree only.
- Template-owned manifest, package, CI, backend, and UI skeleton files in that
repository.
## Dependencies
None.
## Acceptance
1. Repository is public, template-derived, and attached to the task rather than
cloned inside this host worktree.
2. Skeleton identifies `kandev-plugin-bitbucket`, ships no OAuth secret, and contains
no claimed minimum host version before generic seams release.
3. CI/package layout can build the release archive expected by task 13.
## Verification
```sh
make test
make vet
make build
make package
```
## Risks
Template drift can invalidate guessed commands or archive layout. Use the template's
current documented targets; do not add product behavior in this bootstrap task.
@@ -0,0 +1,65 @@
---
id: "03-protocol-manifest-actions"
title: "Plugin protocol, manifest ownership, and authenticated actions"
status: completed
wave: 1
depends_on: ["01-design-package"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 03: Plugin protocol, manifest ownership, and authenticated actions
## Intent
Add every additive RPC, SDK, manifest, and authenticated-action shape required by later
task, reference, credential, and repository-provider work. No later task edits proto
or generated stubs.
## Owned paths
- `apps/backend/proto/kandev/plugin/v1/plugin.proto`
- Generated `apps/backend/proto/kandev/plugin/v1/plugin.pb.go`
- Generated `apps/backend/proto/kandev/plugin/v1/plugin_grpc.pb.go`
- `apps/backend/pkg/pluginsdk/plugin.go`
- `apps/backend/pkg/pluginsdk/serve.go`
- `apps/backend/pkg/pluginsdk/data_types.go`
- `apps/backend/pkg/pluginsdk/host.go`
- `apps/backend/internal/plugins/manifest/manifest.go`
- `apps/backend/internal/plugins/manifest/validate.go`
- `apps/backend/internal/plugins/handlers.go`
- `apps/backend/internal/backendapp/helpers.go`
- `apps/backend/internal/backendapp/plugins_test.go`
- `apps/backend/internal/webapp/payload.go`
- `apps/backend/internal/plugins/runtime/testdata/fixtureplugin/main.go`
- Focused sibling tests under `apps/backend/pkg/pluginsdk/` and
`apps/backend/internal/plugins/{manifest/,handlers_test.go}`.
## Dependencies
Task 01.
## Acceptance
1. Protocol exposes optional action, reference search/authorization, credential
resolution, executor-profile read, and rich plugin-owned task lifecycle shapes;
old plugins receive clear unsupported responses.
2. Manifest validates declared actions, repository-provider ownership, and reference
source ownership/collisions before dispatch.
3. Active UI-plugin boot payload projects manifest `repository_providers` as optional
JSON `repositoryProviderIds`, preserving an explicitly present empty declaration.
4. Authenticated action handler rejects undeclared/unauthorized resources, bounds
bodies, passes verified context apart from payload, honors cancellation/timeout, and
allows only safe response headers.
## Verification
```sh
cd apps/backend && go test ./pkg/pluginsdk/... ./internal/plugins/... ./internal/plugins/manifest/...
make -C apps/backend lint
```
## Risks
Generated protobuf changes are shared contract files. Keep additions wire-compatible;
never hand-edit generated files or expose Bitbucket-specific fields.
@@ -0,0 +1,65 @@
---
id: "04-frontend-plugin-registry"
title: "Frontend plugin registry contracts"
status: completed
wave: 1
depends_on: ["01-design-package"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 04: Frontend plugin registry contracts
## Intent
Add generic revocable action, repository-provider, task-action, review-provider,
integration-settings, Drawer, and responsive contracts to the frontend plugin host.
Do not rewrite task-create or review screens in this task.
## Owned paths
- `apps/web/lib/plugins/types.ts`
- `apps/web/lib/plugins/registry.ts`
- `apps/web/lib/plugins/host-api.ts`
- `apps/web/lib/plugins/host.ts`
- `apps/web/lib/plugins/active-plugin.ts`
- `apps/web/src/boot-payload.ts`
- `apps/web/lib/plugins/registry.test.ts`
- `apps/web/lib/plugins/host-api.test.ts`
- `apps/web/lib/plugins/host.test.ts`
- `apps/web/lib/plugins/active-plugin.test.ts`
- `apps/web/src/boot-payload.test.ts`
- Built-in registration adapters directly required by those registry files.
- Native settings integration index, route resolver, workspace navigation, icons, and tests.
## Dependencies
Task 01.
## Acceptance
1. `host.api.invokeAction(...)` targets declared authenticated actions; repository,
task-action, and review registrations are owner-scoped and revoke on disable.
2. Duplicate provider ownership fails deterministically and unload aborts in-flight
work; review items use external-store sources rather than plugin React hooks.
3. `ActivePlugin.repositoryProviderIds?: string[]` parses JSON
`repositoryProviderIds`; loader records present manifest declarations before
`initialize`, uses them as repository/review provider ownership allowlist, and
preserves absent-field compatibility for older payloads.
4. Host exports Drawer family and supported responsive breakpoint behavior needed for
native mobile plugin UI.
5. `registerIntegrationSettings({ id, label, description, icon?, Component })`
contributes lifecycle-safe native global/workspace settings pages, index cards, and
workspace navigation without provider-specific host rendering.
## Verification
```sh
cd apps/web && pnpm test -- lib/plugins/registry.test.ts lib/plugins/host-api.test.ts lib/plugins/host.test.ts lib/plugins/active-plugin.test.ts src/boot-payload.test.ts
cd apps/web && pnpm run typecheck
```
## Risks
Registry contracts become public plugin API. Avoid closed provider unions and avoid
making a Bitbucket registration special.
@@ -0,0 +1,59 @@
---
id: "05-dynamic-composer-reference-sources"
title: "Dynamic composer reference sources"
status: completed
wave: 2
depends_on: ["01-design-package", "03-protocol-manifest-actions"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 05: Dynamic composer reference sources
## Intent
Bridge active manifest-declared plugin reference sources into the existing backend
mentions registry, preserving host canonicalization and live authorization at search
and submission.
## Owned paths
- `apps/backend/internal/mentions/service.go`
- `apps/backend/internal/mentions/types.go`
- `apps/backend/internal/mentions/service_test.go`
- `apps/backend/internal/backendapp/mentions.go`
- `apps/backend/internal/backendapp/mentions_test.go`
- `apps/backend/internal/plugins/mentions.go`
- Focused plugin bridge tests under `apps/backend/internal/plugins/`.
- `apps/web/hooks/use-entity-reference-search.test.ts`
- `apps/web/components/task/chat/use-entity-reference-composer.test.ts`
- `apps/web/components/task/chat/entity-reference-menu.test.tsx`
## Dependencies
Tasks 01 and 03.
## Acceptance
1. Plugins dynamically register/unregister only manifest-owned `(source, provider,
kind)` descriptors; source collisions, disabled plugins, timeouts, and cancellation
have deterministic behavior.
2. Host, not plugin, constructs canonical references. Search and message submission
call live plugin authorization with verified workspace and `search`/`submission`
purpose.
3. Generic composer UI renders plugin pull-request groups/icons/chips without a
Bitbucket frontend branch.
## Verification
```sh
cd apps/backend && go test ./internal/mentions ./internal/backendapp ./internal/plugins
cd apps/web && pnpm test -- hooks/use-entity-reference-search.test.ts components/task/chat/use-entity-reference-composer.test.ts components/task/chat/entity-reference-menu.test.tsx
cd apps/web && pnpm run typecheck
```
## Risks
Search results are untrusted presentation data. Submission reauthorization is required
to prevent stale, tampered, cross-workspace, or disabled-plugin references entering
message metadata.
@@ -0,0 +1,56 @@
---
id: "06-plugin-owned-task-lifecycle"
title: "Rich plugin-owned task lifecycle"
status: completed
wave: 2
depends_on: ["01-design-package", "03-protocol-manifest-actions"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 06: Rich plugin-owned task lifecycle
## Intent
Let plugins create/read plugin-owned tasks with complete remote descriptors, launch
profiles, namespaced metadata, and ownership-safe preview/cascade deletion.
## Owned paths
- `apps/backend/internal/plugins/host_write.go`
- `apps/backend/internal/plugins/host_data.go`
- `apps/backend/internal/plugins/host_write_test.go`
- `apps/backend/internal/plugins/host_data_test.go`
- `apps/backend/internal/plugins/host_data_wire_test.go`
- `apps/backend/internal/backendapp/services.go`
- `apps/backend/internal/backendapp/adapters_plugin_starter.go`
- `apps/backend/internal/task/service/service_requests.go`
- `apps/backend/internal/task/service/service_tasks.go`
- `apps/backend/internal/task/service/remote_repository_test.go`
## Dependencies
Tasks 01 and 03.
## Acceptance
1. Create/read shapes support existing repository ID or complete arbitrary-provider
remote descriptor, workflow/step, plan, agent/executor profile, prompt/plan mode,
and namespaced metadata.
2. Host writes reserved `metadata.source = plugin:<id>`, rejects reserved-key
overwrite, exposes executor-profile reads behind `api_read:executor_profiles`, and
preserves exact credential-free Data Center clone URLs.
3. Preview/delete only cascades trees whose source matches caller plugin; adopted or
user-owned tasks survive.
## Verification
```sh
cd apps/backend && go test ./internal/plugins ./internal/task/service ./internal/backendapp ./pkg/pluginsdk
make -C apps/backend lint
```
## Risks
Task provenance is destructive-action authorization. Missing or mismatched ownership
must fail closed; do not use plugin state links as authority to delete user tasks.
@@ -0,0 +1,71 @@
---
id: "07-provider-neutral-git-credentials"
title: "Provider-neutral Git credential broker"
status: completed
wave: 2
depends_on: ["01-design-package", "03-protocol-manifest-actions"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 07: Provider-neutral Git credential broker
## Intent
Extract generic broker lease mechanics, retain GitHub via adapter, and route plugin
credential resolution through scoped opaque helper leases for clone/fetch/push.
## Owned paths
- `apps/backend/internal/gitcredentials/`
- `apps/backend/internal/github/credential_broker.go`
- `apps/backend/internal/repoclone/clone.go`
- `apps/backend/internal/repoclone/protocol.go`
- `apps/backend/internal/orchestrator/executor/executor.go`
- `apps/backend/internal/orchestrator/executor/executor_credentials.go`
- `apps/backend/internal/orchestrator/executor/executor_execute.go`
- `apps/backend/internal/agent/runtime/lifecycle/remote_github_env.go`
- `apps/backend/internal/agent/runtime/lifecycle/broker_reachability.go`
- `apps/backend/internal/backendapp/orchestrator.go`
- Focused `internal/gitcredentials`, clone, executor, and lifecycle tests.
## Dependencies
Tasks 01 and 03.
## Acceptance
1. Composite resolver supports arbitrary manifest-declared provider IDs and optional
plugin credential RPCs while retaining current GitHub behavior unchanged.
2. Leases bind exact workspace/task/session/repository/host/path, expire/revoke on all
required lifecycle changes, re-resolve after OAuth refresh, and use HTTPS for remote
executor broker transport.
3. Clone/fetch/push preserve `RepositoryCloneURL` precedence and leave no credential in
URLs, task state, logs, environment, command arguments, or executor payloads.
4. Initial host clone requests carry exact task, active-session, and persisted-repository
scope through the orchestrator and workspace-source materializer. Plugin providers
reject missing scope; GitHub legacy behavior remains unchanged.
5. Pre-worktree refresh for plugin providers uses the same exact scope, is strict, and
suppresses every later unauthenticated fetch/pull while consuming refreshed refs.
## Verification
```sh
cd apps/backend && go test ./internal/gitcredentials ./internal/github ./internal/repoclone ./internal/orchestrator/executor ./internal/agent/runtime/lifecycle
cd apps/backend && go test ./internal/backendapp ./internal/orchestrator/executor ./internal/repoclone
make -C apps/backend lint
```
## Risks
Credential leakage and scope confusion are security failures. Treat host/path mismatch,
disabled plugin, expired lease, and unsupported resolver as deny-by-default.
## Completed verification (2026-08-06)
- Focused clone, worktree, executor, lifecycle, and backend-app suites passed, including
strict exact-scope refresh and no-network-after-refresh regressions.
- `make -C apps/backend lint` passed (with only the known stale external-worktree filter
warning).
- A live Bitbucket Cloud task prepared in 16 ms with only `git checkout`, performed no
second unauthenticated fetch, launched Codex, and reached `WAITING_FOR_INPUT` with `OK`.
@@ -0,0 +1,60 @@
---
id: "08-native-repository-provider"
title: "Native repository provider in task creation"
status: completed
wave: 2
depends_on: ["01-design-package", "04-frontend-plugin-registry"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 08: Native repository provider in task creation
## Intent
Move native remote repository selection, branch listing, and pull-request inspection
through repository-provider registry adapters without new host Bitbucket parsing.
## Owned paths
- `apps/web/hooks/domains/integrations/use-remote-repositories.ts`
- `apps/web/hooks/domains/integrations/use-remote-repositories.test.tsx`
- `apps/web/hooks/domains/github/use-branches-by-url.ts`
- `apps/web/hooks/domains/github/use-branches-by-url.test.ts`
- `apps/web/hooks/domains/github/use-pr-info-by-url.ts`
- `apps/web/hooks/domains/github/use-pr-info-by-url.test.ts`
- `apps/web/components/task-create-dialog-types.ts`
- `apps/web/components/task-create-dialog-state.ts`
- `apps/web/components/task-create-dialog-state.test.ts`
- `apps/web/components/task-create-dialog-helpers.ts`
- `apps/web/components/task-create-dialog-helpers.test.ts`
- `apps/web/components/task-create-dialog-remote-repo-provider-tabs.tsx`
- `apps/web/components/task-create-dialog-remote-repo-provider-tabs.test.tsx`
- `apps/web/components/task-create-dialog-remote-repo-identity.ts`
- `apps/web/components/task-create-dialog-remote-repo-identity.test.ts`
## Dependencies
Tasks 01 and 04.
## Acceptance
1. Registry adapters drive built-in and plugin repository discovery, branch selection,
and URL inspection; unknown self-managed URLs no longer default to GitLab.
2. Provider-neutral state uses `remoteUrl` while preserving `githubUrl` caller
compatibility during migration.
3. Plugin-inspected URLs produce a complete descriptor for backend validation, including
Cloud/DC custom host and exact clone URL behavior.
## Verification
```sh
cd apps/web && pnpm test -- hooks/domains/integrations/use-remote-repositories.test.tsx hooks/domains/github/use-branches-by-url.test.ts hooks/domains/github/use-pr-info-by-url.test.ts components/task-create-dialog-helpers.test.ts components/task-create-dialog-remote-repo-provider-tabs.test.tsx components/task-create-dialog-remote-repo-identity.test.ts
cd apps/web && pnpm run typecheck
cd apps && pnpm --filter @kandev/web lint
```
## Risks
Provider hint alone is untrusted. Preserve legacy callers while ensuring a plugin
provider descriptor—not a host Bitbucket parser—crosses the backend boundary.
@@ -0,0 +1,66 @@
---
id: "09-native-link-review-surfaces"
title: "Native Link and review surfaces"
status: completed
wave: 2
depends_on: ["01-design-package", "04-frontend-plugin-registry"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 09: Native Link and review surfaces
## Intent
Dispatch Link actions and review rendering through plugin registry providers while
keeping GitHub/GitLab compatibility and desktop/mobile feature parity.
## Owned paths
- `apps/web/components/kanban-card-menu-items.tsx`
- `apps/web/components/kanban-card-menu-items.test.tsx`
- `apps/web/components/task/task-switcher-context-menu.tsx`
- `apps/web/components/task/task-session-sidebar-link-actions.ts`
- `apps/web/components/task/review-panel-provider.ts`
- `apps/web/components/task/review-panel-provider.test.ts`
- `apps/web/components/task/review-detail-panel.tsx`
- `apps/web/components/task/dockview-panel-content.tsx`
- `apps/web/components/task/dockview-shared.tsx`
- `apps/web/components/task/dockview-session-tabs.ts`
- `apps/web/components/task/dockview-session-tabs.test.ts`
- `apps/web/lib/state/dockview-panel-actions.ts`
- `apps/web/lib/state/dockview-panel-actions.test.ts`
- `apps/web/lib/state/dockview-store.ts`
- `apps/web/lib/state/dockview-store.test.ts`
- `apps/web/components/task/dockview-add-panel-items.tsx`
- `apps/web/components/task/task-center-panel.tsx`
- `apps/web/components/task/mobile/session-mobile-layout.tsx`
- `apps/web/components/task/mobile/session-mobile-layout.test.tsx`
## Dependencies
Tasks 01 and 04.
## Acceptance
1. `registerTaskAction` renders Link-group actions—including **Link → Bitbucket Pull
Request**—in existing desktop and visible mobile menus, closes before invocation,
and passes read-only current context.
2. Registered reviews use normalized items and external-store refresh in selectors,
dock/detail panels, task center, auto-open/close, task switching, and mobile
navigation; plugin `ReviewPanel` renders in those native locations.
3. Provider-neutral panel IDs/params preserve saved-layout aliases `pr-detail`,
`mr-detail`, `prKey`, and `mrKey`; unload removes plugin UI safely.
## Verification
```sh
cd apps/web && pnpm test -- components/kanban-card-menu-items.test.tsx components/task/review-panel-provider.test.ts components/task/dockview-session-tabs.test.ts lib/state/dockview-panel-actions.test.ts lib/state/dockview-store.test.ts components/task/mobile/session-mobile-layout.test.tsx
cd apps/web && pnpm run typecheck
cd apps && pnpm --filter @kandev/web lint
```
## Risks
Link/menu placement and mobile discoverability are product contracts. Do not replace
native panels with a standalone route or remove legacy layout restoration.
@@ -0,0 +1,53 @@
---
id: "10-cloud-dc-domain-auth"
title: "Cloud/Data Center domain and authentication"
status: completed
wave: 3
depends_on: ["01-design-package", "02-plugin-repository-bootstrap", "03-protocol-manifest-actions"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 10: Cloud/Data Center domain, HTTP clients, and authentication
## Intent
Implement the plugin-owned common Bitbucket domain and separate Cloud/Data Center
adapters with secure workspace-scoped connection/auth lifecycle.
## Owned paths
- Attached `kdlbs/kandev-plugin-bitbucket` worktree: domain models, Cloud adapter, Data
Center adapter, HTTP clients, encrypted secret/state store, OAuth/token flows, health
probe, redaction, and their fixture tests.
## Dependencies
Tasks 01, 02, and 03.
## Acceptance
1. Cloud uses `https://api.bitbucket.org/2.0` cursor pagination and API-token/OAuth
authentication; Data Center normalizes configured API/clone bases and supports
`start`/`limit`, PAT/HTTP access token, and OAuth when application link permits.
2. Adapters map into one domain with explicit capabilities; UI/business code has no
scattered Cloud/DC checks. Unsupported Data Center versions/capabilities are
visible, not implied supported.
3. Secrets use workspace/generation encryption, PKCE/signed one-time OAuth state,
rotation singleflight, redaction, HTTPS/redirect/timeout/response-cap policy, and
~90-second health polling with jitter/backoff.
## Verification
```sh
make test
make fmt-check
make vet
make build
```
## Risks
Data Center context paths, private networks, proxies, and supported releases vary.
Never store URL credentials or ship OAuth client secrets; test capability probes and
origin-locked redirect behavior with fixtures.
@@ -0,0 +1,75 @@
---
id: "11-plugin-workflows-watches"
title: "Plugin task, Git, linking, and watch workflows"
status: completed
wave: 3
depends_on: ["03-protocol-manifest-actions", "05-dynamic-composer-reference-sources", "06-plugin-owned-task-lifecycle", "07-provider-neutral-git-credentials", "10-cloud-dc-domain-auth"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 11: Plugin task, Git, linking, and watch workflows
## Intent
Use released host seams to implement Bitbucket plugin actions/RPC handlers for task
launching, scoped Git credentials, PR linking/creation, and durable watches.
## Owned paths
- Attached `kdlbs/kandev-plugin-bitbucket` worktree: action/RPC handlers, task and
Git workflow services, link storage, credential resolver, health poll integration,
watch persistence/poller/recovery, events, and focused tests.
## Dependencies
Tasks 03, 05, 06, 07, and 10.
## Acceptance
1. Authenticated actions launch tasks from PRs, link/unlink tasks, create PRs from
task branches, and resolve Git credentials without secrets crossing host boundaries.
2. Plugin `pull_request` search and authorization use the live Cloud/DC adapter for
both composer search and message submission; they do not bypass host canonicalization.
3. Watches persist definition/cursor/dedupe/reservation/link/recovery state, use keyed
mutex plus durable `creating` reservation, reconcile crashes, and emit
`plugin.kandev-plugin-bitbucket.*` events.
4. Reset/delete previews cascade and removes only plugin/watch-owned task trees;
manually linked and adopted tasks survive.
5. The Cloud/Data Center provider wrapper preserves restart-safe PR paging; a
watch-created task is returned by both task-scoped PR and workspace-association
queries after restart.
6. Creating a PR from a verified task persists its association immediately. A remote
create success followed by local association failure returns a bounded partial
result rather than a retryable error that could duplicate the remote PR.
7. Review status adapters query the PR source/head commit.
8. Task-scoped refresh performs bounded, exact source-branch PR discovery from the
host-verified repository checkout and persists the result idempotently; discovery
errors do not suppress existing associations.
## Verification
```sh
make test
make vet
make build
```
## Risks
Concurrent polls and crash timing can duplicate tasks. Credential refresh and ownership
checks must fail closed; avoid adding Bitbucket logic to host `agentctl` PR automation.
## Completion
- Live Cloud acceptance proved manual linking through the host-native dialog and durable
association recovery after host/plugin restarts.
- A disposable linked task was explicitly unlinked, then task-scoped refresh rediscovered
the open pull request by its exact host-verified `kandev-live-test` checkout branch and
persisted the association again (`0 -> discovered key -> 1`).
- The live watch created exactly one owned task and a subsequent run skipped the same pull
request. Cloud paging now respects Bitbucket's 50-item maximum.
- Review status reads the source commit: the live `KANDEV-LIVE-ACCEPTANCE` marker resolved
target `c1c53106bebf`, not the destination commit.
- Final plugin checks passed: 37 UI tests, `go test ./...`, `go test -race ./internal/...`,
`go vet ./...`, host build, five-platform package build, and checksum verification.
@@ -0,0 +1,53 @@
---
id: "12-plugin-ui-native-registrations"
title: "Plugin UI and native registrations"
status: completed
wave: 3
depends_on: ["04-frontend-plugin-registry", "05-dynamic-composer-reference-sources", "08-native-repository-provider", "09-native-link-review-surfaces", "10-cloud-dc-domain-auth"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 12: Plugin UI and native registrations
## Intent
Build plugin-owned settings, queue, review, and mobile UI; register it with native
repository, task-action, review-provider, and reference-source contracts.
## Owned paths
- Attached `kdlbs/kandev-plugin-bitbucket` worktree: TypeScript UI bundle, route/nav,
connection/settings components, queue/review panels, native registration module,
responsive styles, view-model/component tests, and plugin Playwright tests.
## Dependencies
Tasks 04, 05, 08, 09, and 10.
## Acceptance
1. Native **Settings > Integrations > Bitbucket** provides connection/authentication,
health, and saved-watch configuration; `/bitbucket` provides browse/search, queue
filters, review details, status presentation, and task launch/link/unlink/create-PR
through authenticated plugin actions.
2. Plugin registers provider `bitbucket`, Link actions, native review panel, and
`bitbucket`/`pull_request` composer source; its review component works in host
desktop and mobile surfaces.
3. Mobile uses focused list/detail route state, one scroll owner, `100dvh`, safe areas,
>=44px controls, and Drawers for filters/actions rather than compressed panes.
## Verification
```sh
pnpm lint
pnpm typecheck
pnpm test
pnpm e2e
```
## Risks
Capability flags must remove or explain unavailable Cloud/DC controls. Do not duplicate
host UI or add a Bitbucket-specific frontend branch; plugin unload must tolerate
remounting and remove its registrations.
@@ -0,0 +1,101 @@
---
id: "12b-github-parity-page"
title: "Rebuild Bitbucket page with GitHub list parity"
status: completed
wave: 3b
depends_on: ["12-plugin-ui-native-registrations"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 12b: Rebuild Bitbucket page with GitHub list parity
## Intent
Replace the live-evaluation desktop split workbench with the first-party `/github`
page's list-first hierarchy while retaining plugin-owned review depth, watches, Cloud
and Data Center capability handling, and native mobile parity.
## Confirmed cause
`ui/src/bundle.ts` renders `.bb-desktop-panes`, permanently allocating a narrow queue
and an empty review pane. `apps/web/app/github/github-page-client.tsx` instead composes
`PresetsScopeBar`, `ListToolbar`, one padded full-width `PRList`, and an optional
pagination footer. Source, installed, and served plugin asset hashes matched during
reproduction, so stale files did not cause the reported layout.
## Owned paths
- Attached `kdlbs/kandev-plugin-bitbucket` worktree:
- `ui/src/bundle.ts`
- `ui/src/view-models.ts`
- `ui/plugin.css`
- `ui/bundle.js`
- `ui/test/registrations.test.ts`
- `ui/test/view-models.test.ts`
- `ui/e2e/desktop-packaged-plugin.spec.ts`
- `ui/e2e/mobile-packaged-plugin.spec.ts`
## Implementation
1. Add tested review-query URL helpers so `/bitbucket?review=<canonical-key>` is a
reloadable focused-detail state and Back returns to `/bitbucket`.
2. Replace `.bb-desktop-panes` with a full-height list layout matching GitHub's order:
desktop scope pills, compact title/count + repository/query + refresh/watch toolbar,
then one padded, bordered, divided result list.
3. Match GitHub row density and anatomy: provider-colored PR state icon, linked title,
repository/number and readable author metadata, restrained status, compact Task and
Review affordances. Hide provider-opaque account identifiers from display.
4. Reuse `ReviewDetailPanel` as focused page content and native task ReviewPanel; do
not duplicate review action logic.
5. Keep phone composition one-dimensional: compact list toolbar, filter Drawer,
direct focused detail, 44px controls, safe-area padding, and one scroll owner.
## Mobile design contract
- Desktop outcome: scan full-width results and launch a task, open Bitbucket, or open
focused review without a permanent detail pane.
- Mobile entry: `/bitbucket`; closest exemplar is `/github` list/filter hierarchy plus
`apps/web/components/kanban-with-preview.tsx` direct detail navigation.
- Hierarchy: topbar → compact toolbar → PR list → focused review. Primary row action is
Review; filters/actions are temporary Drawers.
- Scroll: list or focused review owns vertical scroll, never both; viewport-bound
content uses `100dvh`, overscroll containment, and bottom safe-area clearance.
- Shared query/filter/review state and view-model helpers serve both compositions.
## RED tests
- `ui/test/view-models.test.ts`: review URL encoding/decoding and opaque-author display.
- `ui/test/registrations.test.ts`: GitHub-parity markers exist and permanent split-pane
markers do not.
- Desktop Playwright: full-width list exists, no review pane exists initially, Review
changes URL and focuses detail, Back restores list.
- Mobile Playwright: same URL/back outcome, filter/action Drawers remain contained,
touch targets remain at least 44px, and document has no horizontal overflow.
## Verification
```sh
npm test
npm run typecheck
npm run lint
npm run e2e
test -z "$(gofmt -l .)"
git diff --check
```
Completed verification: 27 Vitest checks plus typecheck/build passed; seven packaged
desktop/mobile Playwright scenarios passed against the live Cloud-connected instance.
Fresh desktop and mobile documents rendered without browser console errors.
Then copy only `ui/bundle.js` and `ui/plugin.css` into the running disposable plugin
installation, hard-reload a fresh document, and capture `/github` and `/bitbucket` at
identical desktop/mobile viewport sizes. Do not replace the live plugin server binary.
## Risks
- Bitbucket queue actions currently expose a bounded result set without total/cursor;
match GitHub's list hierarchy but do not fabricate pagination totals.
- Review query keys must remain encoded and must not become a host-specific route.
- Cloud can return canonical opaque account IDs; presentation must omit those rather
than exposing unreadable identifiers or changing authorization identity semantics.
@@ -0,0 +1,139 @@
---
id: "12c-exact-code-host-ui-parity"
title: "Use exact shared GitHub/GitLab dashboard and task flow"
status: completed
wave: 3c
depends_on: ["12b-github-parity-page"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
---
# Task 12c: Use exact shared GitHub/GitLab dashboard and task flow
## Intent
Replace visual approximation and plugin-invented actions with the actual host-rendered
GitHub/GitLab dashboard contract. Preserve Bitbucket API/domain ownership and native
task review-provider depth.
## Confirmed mismatch
GitHub `PRList` and GitLab `MRList` render inert rows whose title opens the provider
and whose sole action is a compact **Task** preset dropdown. Preset selection opens
`TaskCreateDialog` directly. Bitbucket rendered equal **Task** and **Review** buttons,
then added an intermediate preset modal before server-side task creation. Served and
source hashes matched, so stale assets did not cause the mismatch.
Manual follow-up found two remaining parity regressions: Bitbucket scope pills changed
an out-of-band state parameter without committing the matching visible query, while
GitHub commits every preset filter into its query field; and Bitbucket used hand-drawn
SVG paths instead of GitHub/GitLab's host Tabler glyphs.
A second manual follow-up found that the Task preset rows still all used the generic
checklist fallback, because the plugin could not select the host's exact eye, message,
and tool preset icons. It also found no task-topbar CI status/popover contribution, so
linked Bitbucket pipelines were visible only inside the full review panel.
## Owned paths
- Host:
- `apps/web/components/integrations/**`
- `apps/web/components/github/my-github/{pr-list,list-toolbar}.tsx`
- `apps/web/components/gitlab/my-gitlab/{mr-list,list-toolbar,start-task-menu}.tsx`
- `apps/web/lib/plugins/{host-api,types}.ts` and focused tests
- plugin authoring/API docs and this feature's spec/plan/ADR
- `kdlbs/kandev-plugin-bitbucket`:
- `ui/**`
- `internal/{domain,cloud,datacenter,plugin}/**`
- `manifest.yaml`
## Implementation
1. Extract provider-neutral `ChangeRequestList`/row, task preset menu, and list
toolbar under `components/integrations`; refactor GitHub and GitLab to consume them
before exposing them with `IntegrationScopeBar` and `TaskRowIndicator` on `host.ui`.
2. Add human display-author and creation-time fields without replacing provider-
canonical authorization identity. Add a provider-free association action that
paginates workspace tasks and reads task-scoped Bitbucket link state.
3. Render Bitbucket results with the shared host components. Remove the row Review
action, dashboard Watch action, and `/bitbucket?review=...` dashboard flow; retain
`ReviewDetailPanel` only for the registered native task ReviewPanel. Watches remain
in native integration settings.
4. Use GitHub/GitLab's **Review**, **Address feedback**, and **Fix CI** task presets.
Selecting one mounts `host.ui.TaskCreateDialog` immediately with matched repository,
source branch, task title, and prompt; successful creation links the PR and routes
to the task.
5. Render linked tasks through the same host `TaskRowIndicator`; keep provider title
external and row container inert.
6. Export host-owned semantic integration icons, use them for Bitbucket scope and row
states, and keep runtime UI in the host repository rather than a shared UI repo.
7. Make Bitbucket's visible committed query the source of truth for scope state:
selecting Open/All/Merged/Declined writes and commits the normalized state token;
committing a query drives the same state sent to Cloud/Data Center.
8. Add semantic preset icon names to the shared menu and make GitHub and plugins resolve
them through one host mapping; Bitbucket sends eye/message/tool for the three native
presets.
9. Add the provider-neutral host `IntegrationChangeRequestStatus` control and
`openTaskReview` callback. Register Bitbucket in `chat-top-bar`, refresh linked PR
statuses on open and around every 90 seconds, and use the same desktop hover/mobile
drawer interaction as GitHub.
## Mobile design contract
- Entry and hierarchy match `/github` and `/gitlab`: topbar, temporary filter Sheet,
compact list toolbar, full-width change-request list.
- Row title opens Bitbucket. **Task** is the only row action; its host DropdownMenu
receives Kandev's phone bottom-surface treatment and 44px trigger/items.
- Task creation uses the same native responsive `TaskCreateDialog`; review uses the
host's task Review surface. No extra plugin Drawer or mobile dashboard detail route.
- Document has one vertical scroll owner and no horizontal overflow; shared host
components own responsive geometry, while plugin state/query logic remains shared.
## TDD and verification
1. RED host tests for missing `host.ui` exports and shared row/task-menu behavior.
2. RED plugin unit/E2E tests asserting one **Task** dropdown, no **Review** button,
direct native task dialog, linked-task refresh, and matching desktop/mobile flow.
3. RED Cloud/Data Center/workflow tests for display metadata and association paging.
4. Run focused host component/plugin API tests, GitHub/GitLab regressions, plugin unit
and race tests, typecheck/lint/build, packaged desktop/mobile E2E, then live Cloud.
5. Compare fresh `/github`, `/gitlab`, and `/bitbucket` desktop/mobile screenshots;
require source, installed, and served asset hashes to match with zero console errors.
## Risks
- New `host.ui` exports require a named host release before plugin publication.
- Task linking happens after host task creation; failures must not claim association
success and must preserve navigation to the successfully created task.
- Provider display names are presentation-only; canonical account IDs remain the
authorization identity and never get silently substituted.
- Shared primitives must stay provider-neutral; importing Bitbucket types or API logic
into the host fails this task.
## Completion
- GitHub, GitLab, and Bitbucket now consume the same host-owned change-request list,
toolbar, task menu, and linked-task indicator primitives.
- The live Cloud package presents one **Task** menu, opens `TaskCreateDialog` directly,
keeps review in the linked task, and has no dashboard Review or Watch action.
- Verification passed: 1,010 host test files / 7,712 tests, focused host typecheck/lint/
production build, 29 plugin UI tests, plugin Go race/vet/package checks, and eight
live Cloud desktop/mobile Playwright checks.
- The manual follow-up is complete: preset clicks commit `state:*` into the visible
query, committed queries drive provider requests, and Bitbucket consumes the same
host-owned semantic Tabler icons as GitHub/GitLab.
- Final browser acceptance verified the exact host preset glyph classes: `IconEye`,
`IconMessageDots`, and `IconTool`. The native task dialog loaded both live Bitbucket
branches through the persisted provider bridge with HTTP 200 instead of a GitHub
fallback/500.
- The host-native task-link dialog issued `pullrequests.link` successfully and all three
disposable manual, auto-discovered, and watch-created tasks remained associated after
restart.
- The task-topbar pipeline control passed desktop and native-touch acceptance. Opening it
refreshed live status, desktop hover rendered the pipeline popover/link, mobile used a
bounded no-overflow drawer with 44px controls, and both opened native Review. A live
90-second polling cycle tracked `SUCCESSFUL -> INPROGRESS -> SUCCESSFUL`, changing the
host glyph `check -> clock -> check`; the fixture was restored to `SUCCESSFUL`.
- Final focused host verification passed 154 tests, web typecheck, backend lint/build,
plugin 37 UI tests, Go unit/race/vet/build, and five-platform package checksums.
@@ -0,0 +1,63 @@
---
id: "12d-host-native-task-link-parity"
title: "Use the host-native task change-request link dialog"
status: completed
wave: 3d
depends_on: ["12c-exact-code-host-ui-parity"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
---
# Task 12d: Use the host-native task change-request link dialog
## Confirmed root cause
`TaskActionRegistration.run()` supplied verified task context but no native linking
surface. The Bitbucket plugin therefore used `host.openModal()` and hand-built a form
whose width, description placement, footer, validation, success handling, mobile
presentation, and icon differed from `TaskGitHubPRDialog`. Existing tests asserted only
action invocation and modal presence. The real plugin also registered “Link Bitbucket
Pull Request” even though the fixture and built-in submenu items name only their target.
## Implementation
1. Extract GitHub's one-input link form into a provider-neutral host component with
native inline errors, Cancel/Save footer, submitting state, toast, and close behavior.
2. Add an additive `host.openTaskLinkDialog()` contract that mounts that exact component
in host-owned dialog geometry; refactor GitHub to consume the shared form first.
3. Propagate registered plugin icon names into both task-card and task-switcher Link
menus instead of substituting a generic link glyph.
4. Register Bitbucket as **Bitbucket Pull Request**, submit its parsed reference through
the authenticated `pullrequests.link` action, and remove its copied link form.
5. Update the in-tree fixture and desktop/mobile E2E to prove native anatomy, validation,
action invocation, close-on-success, toast, icon, and menu copy.
## Mobile contract
- Entry remains the visible task actions menu and its existing **Link** submenu.
- Nearest exemplar is `TaskGitHubPRDialog`; Bitbucket uses the same dialog instead of a
plugin-only bottom drawer so behavior and focus return remain identical.
- One dialog owns scrolling; input and footer actions remain touch reachable without
document horizontal overflow.
## Validation
```bash
cd apps && pnpm --filter @kandev/web exec vitest run \
components/integrations/task-change-request-link-form.test.tsx \
components/task/task-github-pr-dialog.test.tsx \
components/plugins/plugin-modal-host.test.tsx \
components/kanban-card-menu-items.test.tsx \
lib/plugins/host-api.test.ts
cd ../kdlbs-kandev-plugin-bitbucket && npm test
cd ../kandev-2/apps/web && pnpm e2e:run e2e/tests/plugins/bitbucket-plugin-contract.spec.ts
```
## Acceptance
- Both Link menus show a Bitbucket brand icon and **Bitbucket Pull Request**.
- GitHub and Bitbucket render the same form anatomy and interaction states.
- Invalid input stays open with inline error; success links once, closes, and toasts.
- Desktop and mobile E2E complete the same user outcome with no overflow.
- Full current-worktree review records any unrelated blockers before merge readiness.
@@ -0,0 +1,67 @@
---
id: "12e-shared-task-status"
title: "Render registered provider status in exact host task chrome"
status: completed
wave: 3e
depends_on: ["12d-host-native-task-link-parity"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
---
# Task 12e: Render registered provider status in exact host task chrome
## Intent
Make status presentation impossible for a code-host plugin to visually fork. Extend the
existing review-provider data contract and have Kandev mount the exact shared topbar and
composer CI surfaces for registered providers.
## Owned paths
- `apps/web/lib/plugins/{types,registry,host-api}.ts` and focused tests
- `apps/web/components/task/review-panel-provider.ts` and tests
- `apps/web/components/integrations/change-request-status-*.tsx` and tests
- `apps/web/components/github/{pr-topbar-button,pr-status-chip,pr-ci-popover}.tsx`
- `apps/web/components/task/{task-top-bar,passthrough-toolbar}.tsx`
- `apps/web/components/task/chat/chat-input-area.tsx`
- plugin API/authoring docs
## Implementation
1. Add an optional normalized `taskStatus` to `ReviewItemSummary`, preserving it through
registry validation without accepting provider-specific payloads.
2. Extract the GitHub topbar trigger, composer chip, and common CI popover/drawer body
into provider-neutral host components. Adapt GitHub to those components first.
3. Build one registry-backed status adapter from `useNormalizedTaskReviews`; refresh via
the provider's existing deduplicated lifecycle and background interval.
4. Mount it beside `PRTopbarButton`, beside `PRStatusChip`, and in passthrough status.
Avoid a new plugin visual slot or second provider poller.
5. Keep optional GitHub-only automation/merge callbacks in the shared anatomy without
requiring them from Bitbucket.
## TDD and acceptance
1. RED registry tests prove normalized status is currently discarded.
2. RED task-topbar, chat-status, and passthrough tests require registered-provider
topbar and composer entries, exact shared popover content, refresh routing, and unload.
3. GREEN implementation keeps all existing GitHub status tests unchanged or adapts only
their provider-neutral import names.
4. Run focused Vitest, web typecheck/lint, and desktop/mobile E2E assertions.
## Mobile contract
Touch uses the same bounded drawer as GitHub, one internal scroll owner, and controls at
least 44px tall. Desktop and mobile expose the same checks and open-Review capability.
## Risks
- Provider snapshots must remain stable for `useSyncExternalStore`.
- Background refresh must deduplicate topbar/composer consumers and abort on unload.
- Built-in GitHub behavior, automation, and multi-PR aggregation cannot regress.
## Completed verification (2026-08-06)
- Nine focused host suites passed (70 tests), plus web typecheck and lint.
- Desktop topbar and composer both rendered the shared `pr-topbar-popover-inner` anatomy.
- Touch emulation rendered the shared bounded CI drawer with no horizontal overflow.
@@ -0,0 +1,64 @@
---
id: "12f-shared-review-detail"
title: "Extract the GitHub change-request detail as a host UI contract"
status: completed
wave: 3f
depends_on: ["12d-host-native-task-link-parity"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
---
# Task 12f: Extract the GitHub change-request detail as a host UI contract
## Intent
Use one host-owned review layout for GitHub and compatible plugin providers. Providers
map data and actions; they do not recreate headers, tabs, sections, buttons, or mobile
geometry.
## Owned paths
- `apps/web/components/integrations/change-request-detail.tsx` and tests
- `apps/web/components/github/pr-detail-panel.tsx` and focused regression tests
- `apps/web/lib/plugins/{types,host-api}.ts` and focused tests
- plugin API/authoring docs
## Implementation
1. Define a provider-neutral detail model for identity/state, author/timestamps,
branches/stats, description, review summaries, checks, threaded comments, and sync
time, plus capability-gated action descriptors/callbacks.
2. Extract the pure presentation from GitHub `PRDetailContent` into
`ChangeRequestDetail`; retain GitHub fetching, auth, feedback caching, and mutations
in a GitHub adapter.
3. Expose the component and its additive model through versioned `host.ui`.
4. Preserve GitHub's header, collapsible Description/Reviews/Checks/Comments sections,
action placement, loading/error treatment, and one-scroll-owner responsive layout.
## TDD and acceptance
1. RED component/API tests require the missing host component, model, action dispatch,
and responsive semantics.
2. GREEN GitHub adapter tests prove existing data and supported actions map without a
visual regression.
3. Run focused Vitest, web typecheck/lint, and existing GitHub review E2E coverage.
## Mobile contract
The component fills the native mobile Review location, owns no route or drawer, retains
one vertical scroll owner, prevents horizontal overflow, and keeps action targets at
least 44px.
## Risks
- Extraction must not weaken GitHub's auth-dependent approve/merge behavior.
- Provider-neutral types cannot encode GitHub or Bitbucket REST payloads.
- Unsupported actions must be absent, not disabled forever or replaced with new layout.
## Completed verification (2026-08-06)
- GitHub and registered providers now render the same host `ChangeRequestDetail` component.
- Focused component/adapter tests, web typecheck, and lint passed.
- Live desktop and touch runs rendered Description, Reviews, CI Checks, and Comments with
one scroll owner and no horizontal overflow.
@@ -0,0 +1,74 @@
---
id: "12g-bitbucket-status-detail-adapters"
title: "Adapt Bitbucket to shared task status and review detail"
status: completed
wave: 3g
depends_on: ["12e-shared-task-status", "12f-shared-review-detail"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
decision: "../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md"
---
# Task 12g: Adapt Bitbucket to shared task status and review detail
## Intent
Remove the plugin-owned status slot and bespoke tabbed Review panel. Feed Bitbucket
Cloud/Data Center data and supported actions into the exact host surfaces from tasks
12e and 12f, then prove live pipeline/link/review behavior.
## Owned paths
- `kdlbs/kandev-plugin-bitbucket/ui/src/{bundle,task-review-status,view-models}.ts`
- `kdlbs/kandev-plugin-bitbucket/ui/{plugin.css,test/**,e2e/**}`
- Bitbucket adapter/domain fixtures needed for normalized detail/status fields
- packaged plugin bundle and manifest version
## Implementation
1. Hydrate review-provider snapshots with head-commit build statuses and normalized
shared `taskStatus`; remove the `chat-top-bar` visual registration and its poller.
2. Map Bitbucket identity/state, author/timestamps, branches/stats, description,
participants/reviews, checks, threads, and supported mutations into
`host.ui.ChangeRequestDetail`.
3. Remove custom Review tabs/actions/CSS. Declare approve/unapprove/merge/decline,
comment/reply, refresh, and external links only when Cloud/Data Center capabilities
and viewer state permit them.
4. Preserve durable manual, auto-discovered, created, and watch-owned PR association as
the single source for review/status queries.
5. Rebuild/package a fresh version and restart the evaluation instance with exact served
asset hashes.
## TDD and acceptance
1. RED plugin tests require status in the registry snapshot, no visual slot, and exact
normalized detail/action mapping; cover links objects without string coercion.
2. RED desktop/mobile E2E requires topbar popover, composer CI chip, shared Review
sections, action dispatch, provider links, no custom tabs, and no overflow.
3. Live Cloud acceptance changes the source-commit pipeline
`SUCCESSFUL -> INPROGRESS -> FAILED -> SUCCESSFUL`, verifies both status surfaces
update, opens Review from each, and restores the fixture.
4. Verify manual linking and exact-branch auto-link survive restart and feed both status
surfaces. Data Center remains fixture-covered until a disposable target exists.
5. Run plugin unit/race/vet/build/package checks plus focused host E2E.
## Risks
- Bitbucket Cloud and Data Center expose different build/review detail shapes; normalize
capabilities without pretending unsupported operations exist.
- Live acceptance must restore the disposable pipeline state even after a failed test.
- Same-version bundle caching requires a version bump and fresh document.
## Completed verification (2026-08-06)
- Plugin UI tests passed (43), all Go packages passed, `go vet ./...` passed, and the
host-only `0.1.10` package verified and installed active in the evaluation instance.
- Live Cloud commit status completed the required
`SUCCESSFUL -> INPROGRESS -> FAILED -> SUCCESSFUL` cycle; both shared status surfaces
reflected each state and the fixture was restored.
- Manual Link dialog submission persisted one association. Exact-branch auto-link was
proved by unlinking the disposable task, observing zero associations, loading the task,
and observing the matching PR association recreated.
- Cloud review detail exposed real PR data/actions through the shared host component;
Cloud and Data Center timestamp fixtures cover provider normalization, while a live
Data Center target remains intentionally out of scope for this acceptance run.
@@ -0,0 +1,86 @@
---
id: "12h-native-create-unlink-indicators-saved-queries"
title: "Close native create, unlink, task-indicator, and saved-query gaps"
status: completed
wave: 3h
depends_on: ["12g-bitbucket-status-detail-adapters"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
decision: "../../decisions/2026-08-10-plugin-change-request-mutations.md"
---
# Task 12h: Close Native Create, Unlink, Task-Indicator, and Saved-Query Gaps
## Intent
Fix four live-evaluation gaps without adding Bitbucket-specific host branches: route
native create through a registered provider after Git push, expose shared unlink,
hydrate native task indicators from one workspace association snapshot, and persist
dashboard saved queries with GitHub/GitLab interaction parity.
## Owned paths
- `apps/web/lib/plugins/{types,registry,registry-normalization}.ts` and focused tests
- `apps/backend/internal/plugins/handlers.go` and authenticated-action tests
- `apps/web/hooks/use-git-operations.ts`, `apps/web/components/vcs/**`, and focused tests
- `apps/web/components/integrations/**`, task/sidebar/Kanban list placements, and tests
- `docs/{decisions,specs,plans,public}/**` plugin contract documentation
- Attached `kdlbs/kandev-plugin-bitbucket/{ui,internal,manifest.yaml}` implementation/tests
## Implementation
1. Extend repository-provider registration with lifecycle-cancelled native change-
request creation and declared option support. Resolve only the persisted repository
attached to the active task/repo scope; push through `worktree.push`, then call the
provider. Keep built-in `worktree.create_pr` behavior unchanged.
Extend task-scoped authenticated actions with an optional repository selector that
the host accepts only when it is attached to the verified task.
2. Extend review-provider registration with lifecycle-cancelled unlink and a normalized
workspace association external store. Add host-owned unlink controls and semantic
task indicators in desktop/mobile shared surfaces.
3. Register Bitbucket create/unlink/association callbacks. Server create selects the
host-verified repository ID, records the returned association, and remains safe after
a successful push. Link/create/unlink refresh both review and association snapshots.
4. Add `capabilities.user_state`, persist bounded workspace saved-query records through
`host.storage`, and reuse host scope/dialog primitives for save/select/delete on
desktop and mobile.
5. Update public plugin API docs, rebuild the plugin bundle/package, and cover complete
behavior in host fixture and packaged plugin E2E.
## TDD and acceptance
1. RED host tests pin provider resolution, push-before-create ordering, post-push retry,
lifecycle abort, option visibility, association dedupe, unlink, and no-plugin parity.
2. RED plugin tests pin authenticated create payloads, repository selection, link/unlink
refresh, association snapshots, storage validation, named save/select/delete, and
workspace isolation.
3. Desktop/mobile E2E proves conditional native Create PR, resulting association,
sidebar/Kanban glyph, shared unlink, multi-link preservation, saved-query reload and
delete, and unload cleanup.
4. Run focused frontend unit/type/lint checks, plugin UI/Go/race/build/package checks,
and `git diff --check` in both repositories.
## Risks
- Push succeeds before remote creation; retry must not duplicate a pull request or hide
the partial-success state.
- Multi-repository tasks require exact repo-scope-to-persisted-repository resolution.
- Association hydration must stay workspace-bounded and shared across many task rows;
per-task provider polling is not acceptable.
- `host.storage` is permission-gated; upgrade failure must remain visible and must not
corrupt in-memory saved-query state.
## Completion evidence
- Native **Create PR** pushed the verified session checkout, dispatched
`pullrequests.create` through the registered Bitbucket provider, received HTTP 201,
and linked the returned pull request without adding Bitbucket logic to agentctl.
- Shared desktop status hover exposed unlink; unlink removed topbar/composer status and
sidebar indicator immediately and remained detached after a full reload.
- Workspace association hydration rendered linked pull-request indicators across the
sidebar from one provider snapshot.
- A changed dashboard query enabled **Save current query**; the shared host dialog saved
it, reload retained it, and selecting it restored the exact query.
- Host focused frontend tests (100), typecheck, ESLint, backend plugin/SDK tests, Go
lint, plugin UI tests (44), plugin Go race tests, vet, package verification, and public
docs validation all passed.
@@ -0,0 +1,85 @@
---
id: "12i-shared-task-indicator-hover-summary"
title: "Reuse the native pull-request summary from registered task indicators"
status: completed
wave: 3i
depends_on: ["12h-native-create-unlink-indicators-saved-queries"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 12i: Reuse the Native Pull-Request Summary from Registered Task Indicators
## Root cause
`PRTaskIcon` renders GitHub's structured status summary, while
`RegisteredChangeRequestTaskIcon` independently renders only the association count as
tooltip text. The registered-provider path never subscribes to or lazily refreshes the
provider's existing task review snapshot, so it cannot supply title/review/CI detail.
## Mobile design contract
- Desktop task switcher/Kanban/rich-list icons disclose the shared structured summary on
mouse hover and keyboard focus.
- The nearest mobile exemplar is the existing registered topbar/composer status drawer
and mobile Review navigation. Those touch paths already expose the same normalized
review data and remain the mobile entry point; the sidebar hover affordance is not
mounted as a phone-only interaction.
- Shared provider state and summary derivation remain viewport-neutral. No new scroll
owner, safe-area surface, or touch-only control is introduced.
## Owned paths
- `apps/web/components/{github,integrations}/**` shared task-summary presentation,
registered task icon, and focused tests
- `apps/web/e2e/tests/plugins/**` desktop hover contract and existing mobile parity path
- `docs/{specs,plans,public}/**` provider contract documentation
## TDD and implementation
1. RED: prove a registered linked task's hover/focus tooltip lacks the PR number, title,
review, and CI rows even when its provider publishes `ReviewItemSummary.taskStatus`.
2. Extract/reuse the exact GitHub task-summary renderer as host-owned, provider-neutral
presentation. Map normalized registered review status into that renderer.
3. Subscribe to task review snapshots without refreshing every task row. Refresh only
when the icon opens, using the existing deduplicated provider refresh lease.
4. Preserve association-only initial rendering, registry unload cleanup, keyboard
focus/Escape behavior, and semantic status color/count.
5. Prove the real packaged Bitbucket provider in the isolated seed; retain the existing
mobile status/Review E2E as the touch path.
## Acceptance
- Bitbucket's linked-task icon opens the same structured summary anatomy as GitHub.
- The first workspace association refresh remains one bounded request across task rows;
task detail is not fetched until hover/focus or another active review surface needs it.
- Multiple linked PRs render separate summary entries; missing detail degrades to the
existing accessible linked-count label while loading.
- Provider unload removes the icon and cancels in-flight work.
- Focused frontend tests, typecheck/lint, rendered desktop verification, existing mobile
parity coverage, and `git diff --check` pass.
## Risks
- Mount-time use of the general review hook would reintroduce N-per-task provider calls;
use subscriptions plus open-time refresh instead.
- A hover tooltip has no touch equivalent; the existing mobile Status/Review path must
remain discoverable and tested.
## Completion evidence
- Focused Vitest: 4 files / 16 tests passed.
- Web typecheck and full ESLint passed.
- Packaged Bitbucket plugin E2E proved association discovery stays detail-lazy until
hover, then renders PR #42, title, Approved review, and Passed CI through the shared
host summary.
- Mobile plugin contract E2E passed on `mobile-chrome`, preserving the touch Review path.
- The isolated seed rendered the correctly embedded production bundle and the same
structured summary; `apps/web/.pr-assets/bitbucket-sidebar-pr-summary.png` records it.
- Follow-up manual acceptance found the registered glyph remained hard-coded muted.
Focused regression coverage now proves normalized provider detail drives the same
host-owned semantic status colors as first-party pull requests; the muted association-
only fallback remains until lazy detail arrives.
- The packaged-provider desktop E2E now asserts the resolved semantic color, and the
public plugin-authoring reference maps every code-host hook to its host-owned result
with eight focused screenshots from an isolated packaged-plugin run.
@@ -0,0 +1,116 @@
---
id: "13-contract-e2e-release-marketplace"
title: "Cross-repository contract E2E, release, and marketplace"
status: in_progress
wave: 4
depends_on: ["03-protocol-manifest-actions", "04-frontend-plugin-registry", "05-dynamic-composer-reference-sources", "06-plugin-owned-task-lifecycle", "07-provider-neutral-git-credentials", "08-native-repository-provider", "09-native-link-review-surfaces", "10-cloud-dc-domain-auth", "11-plugin-workflows-watches", "12-plugin-ui-native-registrations", "12b-github-parity-page", "12c-exact-code-host-ui-parity", "12d-host-native-task-link-parity", "12h-native-create-unlink-indicators-saved-queries"]
plan: "plan.md"
spec: "../../specs/bitbucket-plugin/spec.md"
---
# Task 13: Cross-repository contract E2E, release, and marketplace
## Intent
Prove packaged host/plugin integration and publish only after every required capability
and security contract passes. Marketplace registry is final mutation.
## Owned paths
- `apps/backend/cmd/plugin-fixture/`
- `apps/backend/internal/plugins/runtime/testdata/fixtureplugin/main.go`
- `apps/web/e2e/tests/plugins/bitbucket-plugin-contract.spec.ts`
- `apps/web/e2e/tests/plugins/mobile-bitbucket-plugin-contract.spec.ts`
- `plugin-registry/plugins.yaml`
- `docs/public/plugins-authoring.md`
- `docs/public/plugins-manifest.md`
- `docs/public/plugins-marketplace.md`
- `docs/public/integrations.md`
- Attached `kdlbs/kandev-plugin-bitbucket` release/package/docs paths.
## Dependencies
Tasks 03 through 12, integrated.
## Acceptance
1. Desktop/mobile E2E covers install/enable, authenticated connection action,
repository picker, PR import, **Link → Bitbucket Pull Request**, plugin native
review, composer `#` selection/submission, watch-created task, unload/reload, and
secret-free errors.
2. Containers E2E proves real HTTPS clone/push through helper leases for host and
remote executor paths. Packaged plugin installs against released minimum host
version.
3. A public plugin release with the mandatory internal checksums and no false signing
or provenance claim precedes the final `plugin-registry/plugins.yaml` entry; public
docs accurately describe setup, security, compatibility, and live `api_write`
behavior.
## Verification
```sh
make -C apps/backend test
make -C apps/backend lint
cd apps && pnpm --filter @kandev/web lint
cd apps/web && pnpm run typecheck
cd apps/web && pnpm e2e --grep "Bitbucket plugin contract"
cd apps/web && pnpm e2e --grep "mobile Bitbucket plugin contract"
cd apps/web && KANDEV_E2E_CONTAINERS=1 pnpm e2e --project=containers --grep "Bitbucket plugin contract"
node --test plugin-registry/build-index.test.mjs
```
## Risks
Marketplace publication before host release/package/container evidence breaks minimum-
version compatibility guarantees. Treat every capability-matrix row and all secret
leakage checks as release gates.
## Progress and remaining gates
- The packaged fixture passes the desktop and native-mobile host contract, including
authenticated action dispatch, repository selection, native Link and review
surfaces, `#` search with submit-time rejection, plugin-owned task provenance, and
disable/re-enable cleanup. The layout-owned desktop review tab now adopts the
registered provider's review title; the exact packaged Bitbucket contract passes
against a freshly built host bundle.
- Mobile review selection now persists provider-neutral review IDs. Exact selections
from built-in topbar actions and plugin/built-in review choosers share one path; a
two-MR GitLab regression E2E proves the selected review is not replaced by the
provider's primary item.
- Plugin unit/race/vet/build checks and host/all-platform package checksum verification
pass. The real package installs active on an isolated current development host;
unconfigured `connection.get`, repository, and pull-request actions return safe empty
states; disable/re-enable revokes and restores its route; and its desktop/mobile
workbench, mobile drawer target, and overflow checks pass.
- The real plugin accepts the host's canonical `id`/`key` composer reference, derives
repository and pull-request identity, rejects mismatched identities, and still
live-fetches the PR before authorizing submission. A configured Cloud/Data Center
cross-repository run still requires disposable provider credentials and fixtures.
- The plugin repository now provides an opt-in, fail-fast `make e2e-live` runner for
one configured product at a time. It installs the real package, saves the token
connection through the authenticated host action, exercises health/repositories/
branches/PR/review reads, optionally performs explicitly authorized comment,
approve/unapprove, and decline mutations, then disconnects in cleanup. Its live
Playwright config disables traces, screenshots, and video. Cloud API-token and OAuth
authorization-code/PKCE acceptance passed on 2026-08-05 against the disposable
`kdbls-kandev/kandev-plugin-live-test` repository. OAuth callback replay was rejected,
and the credential remained healthy across plugin disable/re-enable. Data Center
remains pending a disposable target.
- The current Cloud package additionally passed host-native manual linking, exact-branch
auto-link recovery, idempotent watch creation, persisted-provider branch selection,
desktop/mobile native Review, and task-topbar CI status. Live 90-second polling tracked
an actual build-status transition from successful to in-progress and back, and the
disposable marker was restored to successful.
- Public docs and the marketplace index baseline validate.
- Container credential specs are present for Docker and SSH, but this workspace lacks
`KANDEV_E2E_CREDENTIAL_BROKER_PUBLIC_BASE_URL`; both tests therefore skip rather than
claiming real HTTPS clone/push evidence.
- The release workflow's independent packaged-plugin runner still fails closed without
`KANDEV_PLUGIN_E2E_URL`. The manifest intentionally omits `min_kandev_version` until
these host contracts ship in a named release and the same package passes against
that released host.
- Signing is intentionally deferred by
[ADR-2026-08-01-bitbucket-initial-release-remains-unsigned](../../decisions/2026-08-01-bitbucket-initial-release-remains-unsigned.md).
The initial package uses mandatory internal checksums, remains visibly unsigned,
and makes no cryptographic publisher-provenance claim. Signing is no longer a Task
13 blocker; the unreleased host version and external live-test gates still are.
@@ -45,7 +45,7 @@ spec: ../../specs/ui/message-queue-merge.md
- Plan sections: `Frontend`.
- Patterns to mirror: `removeEntry` in `use-queue.ts`, the Edit/Remove ghost
buttons in `queued-ghost-message.tsx`, `handleRemove`/`handleSave` in
`queued-ghost-list.tsx`, and the existing `queued-ghost-list.test.tsx` /
`queued-ghost-list.tsx`, and the existing `queued-ghost-list.test.tsx` /
`queued-ghost-message.test.tsx` harnesses.
- Verify `IconArrowMerge` exists in the installed `@tabler/icons-react`
(^3.36.1) before importing; otherwise use `IconArrowsJoin` or the closest
+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.
Binary file not shown.

After

Width:  |  Height:  |  Size: 117 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 120 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 154 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 19 KiB

+229 -45
View File
@@ -6,24 +6,45 @@
"audiences": ["user", "operator"],
"stability": "stable",
"docs": ["index", "use-kandev", "cli", "desktop-app", "run-as-a-service"],
"sources": ["apps/cli/bin/native-shim.js", "apps/backend/internal/launcher/launcher.go", "apps/desktop/src-tauri/src/lib.rs"],
"tests": ["apps/cli/bin/native-shim.test.mjs", "apps/desktop/e2e/desktop-launch-smoke.test.mjs"]
"sources": [
"apps/cli/bin/native-shim.js",
"apps/backend/internal/launcher/launcher.go",
"apps/desktop/src-tauri/src/lib.rs"
],
"tests": [
"apps/cli/bin/native-shim.test.mjs",
"apps/desktop/e2e/desktop-launch-smoke.test.mjs"
]
},
{
"id": "backend-configuration",
"audiences": ["operator", "contributor"],
"stability": "stable",
"docs": ["configuration", "operations", "cli"],
"sources": ["apps/backend/internal/common/config/config.go", "apps/backend/internal/agentctl/server/config/config.go", "apps/backend/internal/profiles/profiles.go"],
"tests": ["apps/backend/internal/common/config/config_test.go", "apps/backend/internal/agentctl/server/config/config_test.go", "apps/backend/internal/profiles/profiles_test.go"]
"sources": [
"apps/backend/internal/common/config/config.go",
"apps/backend/internal/agentctl/server/config/config.go",
"apps/backend/internal/profiles/profiles.go"
],
"tests": [
"apps/backend/internal/common/config/config_test.go",
"apps/backend/internal/agentctl/server/config/config_test.go",
"apps/backend/internal/profiles/profiles_test.go"
]
},
{
"id": "workspaces-and-repositories",
"audiences": ["user"],
"stability": "stable",
"docs": ["use-kandev", "tasks-and-workflows", "configuration"],
"sources": ["apps/backend/internal/task/handlers/workspace_handlers.go", "apps/web/components/app-sidebar/app-sidebar-workspace-picker.tsx"],
"tests": ["apps/backend/internal/task/handlers/workspace_handlers_test.go", "apps/web/components/app-sidebar/app-sidebar-workspace-picker.test.tsx"],
"sources": [
"apps/backend/internal/task/handlers/workspace_handlers.go",
"apps/web/components/app-sidebar/app-sidebar-workspace-picker.tsx"
],
"tests": [
"apps/backend/internal/task/handlers/workspace_handlers_test.go",
"apps/web/components/app-sidebar/app-sidebar-workspace-picker.test.tsx"
],
"settingsRoutes": ["/settings/workspace", "/settings/workspaces"],
"mcpTools": ["list_repositories_kandev", "list_workspaces_kandev"]
},
@@ -31,9 +52,20 @@
"id": "tasks-and-workflows",
"audiences": ["user"],
"stability": "stable",
"docs": ["tasks-and-workflows", "workflow-tips", "workflow-import-export", "workflow-sync"],
"sources": ["apps/backend/internal/orchestrator/workflow_store.go", "apps/web/components/kanban-with-preview.tsx"],
"tests": ["apps/backend/internal/orchestrator/workflow_store_test.go", "apps/web/components/kanban-with-preview.test.ts"],
"docs": [
"tasks-and-workflows",
"workflow-tips",
"workflow-import-export",
"workflow-sync"
],
"sources": [
"apps/backend/internal/orchestrator/workflow_store.go",
"apps/web/components/kanban-with-preview.tsx"
],
"tests": [
"apps/backend/internal/orchestrator/workflow_store_test.go",
"apps/web/components/kanban-with-preview.test.ts"
],
"mcpTools": [
"create_workflow_kandev",
"create_workflow_step_kandev",
@@ -92,9 +124,22 @@
"id": "sessions-and-coordination",
"audiences": ["user"],
"stability": "stable",
"docs": ["sessions-and-review", "coordination", "automation-and-mcp", "agent-communication"],
"sources": ["apps/backend/internal/mcp/handlers/spawn_session.go", "apps/backend/internal/mcp/handlers/parent_question.go", "apps/web/components/task/dockview-session-tabs.ts"],
"tests": ["apps/backend/internal/mcp/handlers/spawn_session_test.go", "apps/backend/internal/mcp/handlers/parent_question_test.go", "apps/web/components/task/dockview-session-tabs.test.ts"],
"docs": [
"sessions-and-review",
"coordination",
"automation-and-mcp",
"agent-communication"
],
"sources": [
"apps/backend/internal/mcp/handlers/spawn_session.go",
"apps/backend/internal/mcp/handlers/parent_question.go",
"apps/web/components/task/dockview-session-tabs.ts"
],
"tests": [
"apps/backend/internal/mcp/handlers/spawn_session_test.go",
"apps/backend/internal/mcp/handlers/parent_question_test.go",
"apps/web/components/task/dockview-session-tabs.test.ts"
],
"mcpTools": [
"ask_parent_question_kandev",
"ask_user_question_kandev",
@@ -209,8 +254,14 @@
"audiences": ["user", "operator"],
"stability": "stable",
"docs": ["executors", "remote-cloud-environment", "docker", "k8s"],
"sources": ["apps/backend/internal/agent/executor/executor.go", "apps/web/app/settings/executors/page.tsx"],
"tests": ["apps/web/e2e/tests/docker/docker-launch.spec.ts", "apps/web/e2e/tests/ssh/executor-crud.spec.ts"],
"sources": [
"apps/backend/internal/agent/executor/executor.go",
"apps/web/app/settings/executors/page.tsx"
],
"tests": [
"apps/web/e2e/tests/docker/docker-launch.spec.ts",
"apps/web/e2e/tests/ssh/executor-crud.spec.ts"
],
"settingsRoutes": ["/settings/executor/new", "/settings/executors"],
"mcpTools": [
"create_executor_profile_kandev",
@@ -225,8 +276,26 @@
"audiences": ["user", "operator"],
"stability": "stable",
"docs": ["integrations", "configuration"],
"sources": ["apps/web/components/app-sidebar/sections/integrations-section.tsx", "apps/backend/internal/integrations/workspacescope/workspacescope.go", "apps/backend/internal/azuredevops/service.go", "apps/web/app/azure-devops/azure-devops-page-client.tsx", "apps/backend/internal/github/app_registration_lifecycle_service.go", "apps/backend/internal/github/app_registration_import.go", "apps/web/lib/api/domains/github-auth-api.ts", "apps/backend/internal/mcp/server/server.go"],
"tests": ["apps/web/components/app-sidebar/sections/integrations-section.test.tsx", "apps/backend/internal/integrations/workspacescope/workspacescope_test.go", "apps/backend/internal/azuredevops/service_test.go", "apps/web/e2e/tests/integrations/azure-devops.spec.ts", "apps/backend/internal/github/controller_app_registration_test.go", "apps/backend/internal/github/app_registration_import_test.go", "apps/web/e2e/tests/settings/github-app-registration.spec.ts", "apps/backend/internal/mcp/server/handlers_test.go"],
"sources": [
"apps/web/components/app-sidebar/sections/integrations-section.tsx",
"apps/backend/internal/integrations/workspacescope/workspacescope.go",
"apps/backend/internal/azuredevops/service.go",
"apps/web/app/azure-devops/azure-devops-page-client.tsx",
"apps/backend/internal/github/app_registration_lifecycle_service.go",
"apps/backend/internal/github/app_registration_import.go",
"apps/web/lib/api/domains/github-auth-api.ts",
"apps/backend/internal/mcp/server/server.go"
],
"tests": [
"apps/web/components/app-sidebar/sections/integrations-section.test.tsx",
"apps/backend/internal/integrations/workspacescope/workspacescope_test.go",
"apps/backend/internal/azuredevops/service_test.go",
"apps/web/e2e/tests/integrations/azure-devops.spec.ts",
"apps/backend/internal/github/controller_app_registration_test.go",
"apps/backend/internal/github/app_registration_import_test.go",
"apps/web/e2e/tests/settings/github-app-registration.spec.ts",
"apps/backend/internal/mcp/server/handlers_test.go"
],
"settingsRoutes": [
"/settings/integrations",
"/settings/integrations/azure-devops",
@@ -248,8 +317,14 @@
"audiences": ["user", "operator"],
"stability": "stable",
"docs": ["automation-and-mcp", "integrations", "workflow-tips"],
"sources": ["apps/backend/internal/automation/service.go", "apps/backend/internal/mcp/server/server.go"],
"tests": ["apps/backend/internal/automation/service_test.go", "apps/backend/internal/mcp/server/server_test.go"],
"sources": [
"apps/backend/internal/automation/service.go",
"apps/backend/internal/mcp/server/server.go"
],
"tests": [
"apps/backend/internal/automation/service_test.go",
"apps/backend/internal/mcp/server/server_test.go"
],
"settingsRoutes": ["/settings/automations", "/settings/external-mcp"],
"mcpTools": ["get_mcp_config_kandev", "update_mcp_config_kandev"]
},
@@ -257,9 +332,25 @@
"id": "personal-settings-and-secrets",
"audiences": ["user"],
"stability": "stable",
"docs": ["security", "configuration", "developer-tools", "operations", "sessions-and-review"],
"sources": ["apps/web/src/settings-routes.tsx", "apps/web/components/settings/settings-index.tsx", "apps/web/components/settings/general-settings.tsx", "apps/web/components/settings/layouts/layout-settings.tsx"],
"tests": ["apps/web/src/settings-routes.test.ts", "apps/web/components/settings/settings-index.test.tsx", "apps/web/components/settings/terminal-settings.test.ts", "apps/web/lib/layout/layout-profiles.test.ts"],
"docs": [
"security",
"configuration",
"developer-tools",
"operations",
"sessions-and-review"
],
"sources": [
"apps/web/src/settings-routes.tsx",
"apps/web/components/settings/settings-index.tsx",
"apps/web/components/settings/general-settings.tsx",
"apps/web/components/settings/layouts/layout-settings.tsx"
],
"tests": [
"apps/web/src/settings-routes.test.ts",
"apps/web/components/settings/settings-index.test.tsx",
"apps/web/components/settings/terminal-settings.test.ts",
"apps/web/lib/layout/layout-profiles.test.ts"
],
"settingsRoutes": [
"/settings",
"/settings/preferences",
@@ -286,18 +377,44 @@
"id": "security-and-trust",
"audiences": ["user", "operator"],
"stability": "stable",
"docs": ["security", "configuration", "executors", "automation-and-mcp", "operations"],
"sources": ["apps/backend/internal/backendapp/middleware.go", "apps/backend/internal/gateway/websocket/origin.go", "apps/backend/internal/secrets/crypto.go"],
"tests": ["apps/backend/internal/backendapp/middleware_test.go", "apps/backend/internal/gateway/websocket/origin_test.go"]
"docs": [
"security",
"configuration",
"executors",
"automation-and-mcp",
"operations"
],
"sources": [
"apps/backend/internal/backendapp/middleware.go",
"apps/backend/internal/gateway/websocket/origin.go",
"apps/backend/internal/secrets/crypto.go"
],
"tests": [
"apps/backend/internal/backendapp/middleware_test.go",
"apps/backend/internal/gateway/websocket/origin_test.go"
]
},
{
"id": "authentication-and-access",
"audiences": ["user", "operator"],
"stability": "beta",
"docs": ["authentication"],
"sources": ["apps/backend/internal/auth/httpmw/middleware.go", "apps/backend/internal/auth/service.go", "apps/backend/internal/auth/httpapi/handlers.go", "apps/web/components/app-sidebar/current-user-chip.tsx"],
"tests": ["apps/backend/internal/auth/httpapi/handlers_test.go", "apps/backend/internal/auth/httpmw/middleware_test.go", "apps/web/lib/state/slices/auth/auth-slice.test.ts"],
"settingsRoutes": ["/settings/system/users", "/settings/account/security", "/settings/account/tokens"]
"sources": [
"apps/backend/internal/auth/httpmw/middleware.go",
"apps/backend/internal/auth/service.go",
"apps/backend/internal/auth/httpapi/handlers.go",
"apps/web/components/app-sidebar/current-user-chip.tsx"
],
"tests": [
"apps/backend/internal/auth/httpapi/handlers_test.go",
"apps/backend/internal/auth/httpmw/middleware_test.go",
"apps/web/lib/state/slices/auth/auth-slice.test.ts"
],
"settingsRoutes": [
"/settings/system/users",
"/settings/account/security",
"/settings/account/tokens"
]
},
{
"id": "system-health-and-maintenance",
@@ -343,7 +460,13 @@
"id": "deployment-and-platforms",
"audiences": ["operator"],
"stability": "stable",
"docs": ["docker", "k8s", "run-as-a-service", "windows-support", "operations"],
"docs": [
"docker",
"k8s",
"run-as-a-service",
"windows-support",
"operations"
],
"sources": ["Dockerfile", "apps/backend/internal/launcher/service.go"],
"tests": ["apps/web/e2e/tests/docker/docker-launch.spec.ts"]
},
@@ -352,52 +475,113 @@
"audiences": ["user", "operator"],
"stability": "experimental",
"docs": ["coordination", "feature-status", "office-provider-routing"],
"sources": ["apps/backend/internal/office/routes.go", "apps/web/src/office-routes.tsx"],
"tests": ["apps/backend/internal/office/onboarding/service_test.go", "apps/web/src/office-routes.test.ts"]
"sources": [
"apps/backend/internal/office/routes.go",
"apps/web/src/office-routes.tsx"
],
"tests": [
"apps/backend/internal/office/onboarding/service_test.go",
"apps/web/src/office-routes.test.ts"
]
},
{
"id": "plugin-system",
"audiences": ["operator", "contributor"],
"stability": "experimental",
"docs": ["plugins", "plugins-authoring", "plugins-manifest"],
"sources": ["apps/backend/internal/plugins/handlers.go", "apps/backend/pkg/pluginsdk/host.go", "apps/web/lib/plugins/host-api.ts"],
"tests": ["apps/backend/internal/plugins/service_test.go", "apps/backend/internal/plugins/manifest/manifest_test.go", "apps/web/lib/plugins/host-api.test.ts"]
"sources": [
"apps/backend/internal/plugins/handlers.go",
"apps/backend/pkg/pluginsdk/host.go",
"apps/web/lib/plugins/host-api.ts"
],
"tests": [
"apps/backend/internal/plugins/service_test.go",
"apps/backend/internal/plugins/manifest/manifest_test.go",
"apps/web/lib/plugins/host-api.test.ts"
]
},
{
"id": "plugin-marketplace",
"audiences": ["operator", "contributor"],
"stability": "experimental",
"docs": ["plugins-marketplace"],
"sources": ["apps/backend/internal/plugins/marketplace/catalog.go", "apps/backend/internal/plugins/marketplace/sourcestore.go", "apps/web/lib/api/domains/marketplace-api.ts"],
"tests": ["apps/backend/internal/plugins/marketplace/catalog_test.go", "apps/backend/internal/plugins/marketplace/sourcestore_test.go", "apps/web/hooks/domains/plugins/use-marketplace.test.ts"]
"sources": [
"apps/backend/internal/plugins/marketplace/catalog.go",
"apps/backend/internal/plugins/marketplace/sourcestore.go",
"apps/web/lib/api/domains/marketplace-api.ts"
],
"tests": [
"apps/backend/internal/plugins/marketplace/catalog_test.go",
"apps/backend/internal/plugins/marketplace/sourcestore_test.go",
"apps/web/hooks/domains/plugins/use-marketplace.test.ts"
]
},
{
"id": "websocket-protocol",
"audiences": ["contributor", "integrator"],
"stability": "stable",
"docs": ["websocket-api", "architecture", "extending-kandev"],
"sources": ["apps/backend/pkg/websocket/actions.go", "apps/backend/pkg/websocket/handler.go"],
"tests": ["apps/backend/pkg/websocket/handler_test.go", "apps/backend/pkg/websocket/handler_race_test.go"]
"sources": [
"apps/backend/pkg/websocket/actions.go",
"apps/backend/pkg/websocket/handler.go"
],
"tests": [
"apps/backend/pkg/websocket/handler_test.go",
"apps/backend/pkg/websocket/handler_race_test.go"
]
},
{
"id": "contributor-workflow",
"audiences": ["contributor"],
"stability": "stable",
"docs": ["contributing", "architecture", "backend-development", "web-development", "testing", "remote-cloud-environment", "extending-kandev", "release-process"],
"docs": [
"contributing",
"architecture",
"backend-development",
"web-development",
"testing",
"remote-cloud-environment",
"extending-kandev",
"release-process"
],
"sources": ["CONTRIBUTING.md", "Makefile"],
"tests": ["scripts/lint-harness-files.test.py", ".github/scripts/lint-action-pinning_test.py"]
"tests": [
"scripts/lint-harness-files.test.py",
".github/scripts/lint-action-pinning_test.py"
]
}
],
"exclusions": {
"settingsRoutes": [
{ "route": "/settings/changelog", "reason": "Redirect to System updates." },
{ "route": "/settings/general/changes-panel", "reason": "Legacy redirect to Appearance." },
{ "route": "/settings/general/chat-input", "reason": "Legacy redirect to Keyboard Shortcuts." },
{ "route": "/settings/general/resource-metrics", "reason": "Legacy redirect to Appearance." },
{ "route": "/settings/general/shell", "reason": "Legacy redirect to Terminal." },
{ "route": "/settings/plugins", "reason": "Experimental feature intentionally omitted until its public contract stabilizes." },
{
"route": "/settings/changelog",
"reason": "Redirect to System updates."
},
{
"route": "/settings/general/changes-panel",
"reason": "Legacy redirect to Appearance."
},
{
"route": "/settings/general/chat-input",
"reason": "Legacy redirect to Keyboard Shortcuts."
},
{
"route": "/settings/general/resource-metrics",
"reason": "Legacy redirect to Appearance."
},
{
"route": "/settings/general/shell",
"reason": "Legacy redirect to Terminal."
},
{
"route": "/settings/plugins",
"reason": "Experimental feature intentionally omitted until its public contract stabilizes."
},
{ "route": "/settings/system", "reason": "Redirect to System status." },
{ "route": "/settings/system/message-queue", "reason": "Legacy redirect to General Message Queue." }
{
"route": "/settings/system/message-queue",
"reason": "Legacy redirect to General Message Queue."
}
],
"mcpTools": []
}
+100
View File
@@ -390,6 +390,106 @@ A successful create returns the MR URL and asynchronously records it against the
</details>
## Bitbucket
> [!EXPERIMENTAL]
> Bitbucket uses Kandev's experimental plugin platform. Package signatures are
> not enforced yet, so the official plugin follows the same unsigned install
> path as current plugins; signature enforcement is deferred.
Bitbucket support is provided by the separately installed **Bitbucket** plugin.
Install a package built for the running Kandev host from **Settings > Plugins**,
then open its **Bitbucket** entry in the Integrations section. The connection is
workspace-specific: configure each Kandev workspace that should discover
repositories, launch tasks, link pull requests, or use Bitbucket review and
watch workflows.
### Connect Bitbucket Cloud
Choose **Bitbucket Cloud**, enter the Bitbucket workspace slug or ID, then pick
one of these authentication methods:
| Method | Required values | Use when |
|---|---|---|
| API token | Atlassian account email and API token | A workspace-scoped, non-interactive connection is sufficient. |
| OAuth 2.0 | OAuth client ID and secret, then complete the browser flow | Access should be granted interactively and refreshed by Bitbucket. |
For a [scoped Cloud API token](https://support.atlassian.com/bitbucket-cloud/docs/using-api-tokens/), grant `read:user:bitbucket`,
`read:repository:bitbucket`, `write:repository:bitbucket`,
`read:pullrequest:bitbucket`, and `write:pullrequest:bitbucket`. The write
grants are needed for Git push, pull-request creation/review mutations, and
other enabled write actions; omit them only if those operations should fail
closed. For OAuth, enable Account read plus Repository and Pull request
read/write permissions on the consumer; the plugin requests those scopes in
the authorization flow.
For OAuth, copy the read-only callback URL that the plugin shows into the
Bitbucket OAuth consumer. It is derived from the current Kandev origin; changing
that origin requires updating the consumer redirect URI before reconnecting.
Select **Check connection** and wait for the health card to report
**Connected** before browsing repositories.
### Connect Bitbucket Data Center
Choose **Bitbucket Data Center**, enter the full HTTPS base URL (including any
context path such as `/bitbucket`), and select the narrowest credential that
matches your server:
| Method | Required values |
|---|---|
| Personal access token | Bitbucket username and PAT. |
| Project access token | Project token. |
| Repository access token | Repository token. |
| OAuth 2.0 | Bitbucket username, OAuth client ID and secret, then browser authorization. |
The Data Center OAuth incoming application link must allow `REPO_READ` and
`REPO_WRITE`. PATs and project/repository tokens likewise need read access for
discovery/review and write access for push, pull-request, and review mutations.
Data Center deployments differ in their enabled REST and OAuth capabilities.
The plugin reports unavailable operations from the connected server rather than
assuming Cloud behavior. Use a trusted HTTPS URL; test-only insecure endpoints
are not accepted by the normal connection flow.
### What the plugin adds
With a healthy connection, the plugin contributes Bitbucket repository discovery
to **New Task**, credential-free remote inspection/branch lookup, task link and
launch actions, a provider-neutral review panel, pull-request create/update and
review actions where the server grants them, and workspace pull-request watches.
Watches persist their cursor and reservations so a restart can reconcile a
partially created task; they still depend on the configured provider identity
and its current access.
Task Git credentials are brokered per verified Bitbucket provider/workspace/
task/repository scope. The plugin returns credentials transiently; Kandev does
not persist them in task metadata or remote URLs. Rotating credentials,
disconnecting the workspace, disabling the plugin, or uninstalling it revokes
the provider's leases so an already-issued helper fails closed. Configure
executor SSH credentials separately for SSH remotes.
### Security and limitations
The plugin stores only credential-free connection settings in plugin state and
keeps tokens, refresh tokens, and OAuth client secrets in Kandev's encrypted
plugin secret vault. Existing secrets are never displayed; leave a secret empty
only when the UI says it will retain the saved value. **Disconnect Bitbucket**
removes that workspace's Bitbucket connection and stored plugin credentials.
Install plugins only from sources you trust. A plugin backend runs as a Kandev
subprocess and its native UI runs in the Kandev origin, so capabilities are
permission gates, not an operating-system or browser sandbox. Limit Bitbucket
tokens to the repositories and write operations the workspace needs, and review
the plugin's requested `api_read`, `api_write`, `state`, and `secrets`
capabilities before installation.
The plugin does not turn a Bitbucket API credential into unrestricted executor
access. A task can show a Bitbucket pull request while its selected executor
cannot push; use the task's generated HTTPS credential path or separately
configured SSH credentials. Dynamic `#` references and review actions are
reauthorized against the active connection at use time, so a removed grant or
disconnected connection is denied rather than using cached authority.
## Azure DevOps
<details>
File diff suppressed because it is too large Load Diff
+82 -58
View File
@@ -47,12 +47,12 @@ min_kandev_version: "0.78.0" # optional
capabilities:
events: ["task.created", "task.state_changed", "agent.completed"]
api_read: ["tasks", "agent_profiles"] # gates the Host data-reader RPCs
api_write: ["tasks"] # gates Tasks().Create/Update
api_write: ["tasks", "messages"] # gates Host task and message writes
state: true
secrets: true
agent_invoke: true # gates Host.InvokeUtilityAgent
auth: true # gates external (OIDC/SAML) login, see ADR 0050
user_state: true # gates host.storage (per-user browser storage)
agent_invoke: true # gates Host.InvokeUtilityAgent
auth: true # gates external (OIDC/SAML) login; see ADR 0050
user_state: true # gates host.storage (per-user browser storage)
webhooks:
- key: "slack-events"
@@ -61,6 +61,19 @@ webhooks:
access: public # public (default) or authenticated
max_body_bytes: 4194304 # public maximum 4 MiB; authenticated maximum 16 MiB
actions: # authenticated browser-to-plugin calls
- key: "connection.save"
scope: "workspace" # workspace | task | repository
max_body_bytes: 65536 # 1 through 1048576
repository_providers: ["acme"] # optional provider ids owned while active
reference_sources: # optional dynamic composer sources
- source: "acme-pull-requests"
provider: "acme"
kind: "pull_request"
display_name: "Acme pull requests"
kind_label: "Pull request"
auth_providers: # login buttons (needs capabilities.auth)
- id: "google"
display_name: "Google"
@@ -126,53 +139,59 @@ ui: # optional native frontend plugin
<details>
<summary>Complete field reference and validation rules</summary>
| Field | Required | Type | Notes |
|---|---|---|---|
| `id` | yes | string | Must match `^[a-z0-9][a-z0-9._-]*$` (lowercase alphanumeric, dots, underscores, hyphens; must start with a lowercase alphanumeric). Directory name under `~/.kandev/plugins/`. |
| `api_version` | yes | int | Must be exactly `1`. Any other value is rejected. |
| `version` | yes | string | Free-form; used as the version directory name (`~/.kandev/plugins/<id>/<version>/`). |
| `display_name` | no | string | Shown in Settings > Plugins. |
| `description` | no | string | Shown in Settings > Plugins. |
| `author` | no | string | Free-form. |
| `categories` | no | string[] | Each entry must be one of `connector`, `automation`, `tools`, `analytics`. Unknown values are rejected. |
| `icon` | no | string | Package-relative path (e.g. `icon.svg`) to an image the package ships, rendered on the [marketplace](plugins-marketplace.md) card and in plugin lists. The registry index-build resolves it to an absolute `icon_url`; for an installed plugin it is served from the extracted package. Omit it and the card falls back to a letter tile. |
| `repo_url` | no | string | Absolute `http(s)` URL to the plugin's source repository. Rendered as a "Repo" link in Settings > Plugins (both the installed list and the plugin detail). Any other scheme (e.g. `javascript:`) is rejected at registration. Distinct from the marketplace card's `repo_url`, which the registry derives from `plugins.yaml`; declare this in the manifest so sideloaded and directly-installed plugins also carry the link. |
| `runtime.type` | conditionally | string | `"binary"` is the only supported value. Setting it (vs. leaving it empty) makes the manifest **runtime-managed**: see "Managed vs. legacy" below. |
| `runtime.executables` | required when `runtime.type: binary` | map\<string,string\> | Key is `<goos>-<goarch>` (e.g. `linux-amd64`, `darwin-arm64`, `windows-amd64`); value is a clean, package-relative path under `server/` (no leading `/`, no `..` segments). At least one entry required; the running host's key must be present at install time. Windows values end in `.exe`. |
| `min_kandev_version` | no | string | Lowest Kandev version this plugin supports. Enforced at **install time**: installing onto an older Kandev fails with `requires kandev >= <version>, running <version>` and nothing is registered. Already-installed plugins are never re-checked at load or start. A Kandev built from source reports the version `dev` and skips the check entirely, so local development is unaffected. Compare as dotted numeric segments (`0.78.0`); a `v` prefix does not parse as a number and falls back to a string comparison. |
| `capabilities.events` | no | string[] | Bus subjects (or wildcard patterns) this plugin subscribes to. See "Event subscription vocabulary" below. |
| `capabilities.api_read` | no | string[] | Gates the Host data API's read-only accessors. Each entry is a resource name: `tasks`, `sessions`, `messages`, `workspaces`, `workflows`, `agent_profiles`, `repositories`. Calling the matching `Host` accessor (e.g. `Tasks()`) without its resource declared returns gRPC `PermissionDenied`. See "Host data API resource vocabulary" below. |
| `capabilities.api_write` | no | string[] | Gates Host data writes. Current resources are `tasks` (`Tasks().Create/Update`) and `messages` (`Messages().Send`); reads and writes are gated independently. |
| `capabilities.state` | no | bool | Gates `Host.GetState`/`SetState`/`DeleteState`/`ListState`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
| `capabilities.secrets` | no | bool | Gates `Host.RevealSecret`/`GetSecret`/`SetSecret`/`DeleteSecret`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
| `capabilities.agent_invoke` | no | bool | Gates `Host.InvokeUtilityAgent`; a one-shot completion run by the utility agent selected for this plugin. Declare a `utility_agent` config property with `type: string` and `format: utility-agent`; Settings > Plugins renders the picker. The selected utility agent resolves its own enabled ACP profile. Calling without this capability returns gRPC `PermissionDenied`; calling without a valid profile-backed selection returns gRPC `FailedPrecondition`. See ADR 0048. |
| `capabilities.auth` | no | bool | Lets the plugin log a visitor in against an external IdP (OIDC/SAML). Its webhook validates the token, then asserts the identity to Kandev via the `X-Kandev-Auth-Login` response header (`{provider, subject, email, display_name}`); Kandev mints the session and sets the cookie; the plugin never sees the token. Requires authentication enabled; new users are provisioned as members, and Kandev never creates an admin nor auto-links to an existing admin account. **You MUST only assert an email the IdP verified as owned by the subject; a spoofed email claim is account takeover.** Highest-privilege capability; grant only to trusted plugins. See ADR 0050. |
| `capabilities.user_state` | no | bool | Gates `host.storage` (`get`/`set`/`delete`/`list`/`subscribe`), the authenticated per-user browser storage surface at `/api/plugins/{id}/user-state/...`. Unlike `capabilities.state` (the gRPC `Host.SetState` family, written by the plugin's own backend), this is reachable directly from the plugin's frontend bundle with no Go backend required; every read/write is scoped to the calling user. Calling the route without this capability returns `403`. See [Authoring a plugin](plugins-authoring.md) and the per-user-plugin-storage decision record. |
| `webhooks[].key` | yes | string | Must be unique within the manifest. Used in the relay path `POST /api/plugins/{id}/webhooks/{key}`. |
| `webhooks[].description` | no | string | Free-form. |
| `webhooks[].method` | no | string | **Informational only**: kandev does not validate or enforce the inbound HTTP method against this value. |
| `webhooks[].access` | no | string | `public` (default) allows anonymous callers; `authenticated` requires a Kandev identity. Cookie-authenticated browser calls remain subject to Kandev's same-origin policy. |
| `webhooks[].max_body_bytes` | no | int | Request-body limit for this key. Defaults to 4 MiB. Public webhooks cannot exceed 4 MiB; authenticated webhooks can request up to 16 MiB. Plugins using this field should declare the first supporting `min_kandev_version`. |
| `auth_providers[]` | no | object[] | Login buttons this plugin contributes to the pre-auth login screen (needs `capabilities.auth`). Each is `{ id, display_name, initiate }`, where `initiate` names one of the plugin's `webhooks[].key` values: the button navigates to that webhook, which 302-redirects to the IdP. Surfaced anonymously in the boot payload as `auth.ssoProviders`. |
| `config_schema` | no | object | JSON-Schema-like object driving the settings form at **Settings > Plugins > `<plugin>`** (`GET /api/plugins/{id}/config` and `PATCH /api/plugins/{id}`). See "Config schema validation and secret fields" below. |
| `agent_tools` | no | object[] | Task-aware MCP tools implemented by the managed plugin's optional `AgentToolPlugin` SDK interface. Each declaration has a local `name`, `description`, `surfaces`, required `input_schema`, optional `output_schema`, and optional MCP annotation hints. At most 16 tools are allowed. |
| `agent_tools[].name` | yes* | string | Plugin-local name matching `^[a-z0-9][a-z0-9_]{0,31}$`. Kandev derives the global MCP name; authors cannot choose it. |
| `agent_tools[].surfaces` | yes* | string[] | One or both of `kanban-task` and `office-task`. Plugin tools are not exposed to `configuration` or `external` MCP surfaces. |
| `agent_tools[].input_schema` | yes* | object | Compiled object-root JSON Schema, at most 64 KiB serialized. Kandev rejects unknown top-level arguments before invoking the plugin. |
| `agent_tools[].output_schema` | no | object | Optional compiled object-root JSON Schema applied to structured plugin results. |
| `agent_tools[].annotations` | no | object | MCP hints: `read_only_hint`, `destructive_hint`, `idempotent_hint`, and `open_world_hint`. Omitted values use conservative host defaults. |
| `ui.bundle` | no | string | Root-relative path (must start with `/`, e.g. `/ui/bundle.js`) to the plugin's native UI ES module, served at `GET /api/plugins/{id}/bundle`. |
| `ui.styles` | no | string[] | Root-relative CSS paths (each must start with `/`), served at `GET /api/plugins/{id}/ui/*` and injected as `<link>` tags on load. |
| `ui.pages` | no | object[] | Optional declarative metadata accepted by the manifest model. The current frontend does not render these entries; a native bundle registers its supported routes/nav/slots at runtime, so most plugins omit `ui.pages`. |
| `ui.pages[].key` | yes* | string | Stable identifier for the page (*required when a page entry is present). |
| `ui.pages[].title` | yes* | string | Display title. |
| `ui.pages[].path` | yes* | string | Route path for the page. |
| `ui.pages[].surface` | yes* | string | Metadata enum (`settings` · `task-panel` · `main-nav`) validated by the manifest parser. It is not a current frontend mount; use the registry hooks in the authoring guide. |
| `ui.keybindings` | no | object[] | Declares plugin keybindings bound at runtime via `registerKeybinding`. Requires `ui.bundle`. |
| `ui.keybindings[].id` | yes* | string | Stable, plugin-local slug (*required when a keybinding entry is present). Must match `^[a-z0-9][a-z0-9-]*$` and be unique within this plugin's own `ui.keybindings` list, not globally; the effective shortcut is namespaced `plugin:{pluginId}:{id}`. |
| `ui.keybindings[].default` | yes* | string | Default combo string. `+`-separated tokens: zero or more modifiers from `mod`, `ctrl`, `cmd`, `meta`, `alt`, `option`, `shift` (`mod` = ⌘ on macOS, Ctrl elsewhere) plus exactly one non-modifier key. `shift` may not combine with a digit or symbol key; the browser reports the shifted glyph for those keys, so the combo could never match. |
| `ui.keybindings[].description` | yes* | string | Non-empty, human-readable label shown in **Settings > Keyboard Shortcuts**. |
| `ui.keybindings[].allow_in_editor` | no | boolean | Lets this binding fire while an `input`, `textarea` or contenteditable holds focus. Defaults to `false`, so a plugin cannot shadow ordinary typing. Only accepted on a combo carrying a `ctrl`/`cmd`/`mod`/`alt` modifier; `shift` alone does not count, since `shift+a` is just a capital A. Kandev re-applies that requirement to the *effective* combo, so a user override that drops the modifier reverts this binding to the default skip-while-typing behaviour rather than intercepting ordinary keystrokes. Declare it only when the binding exists to act on the focused field (dictation into the composer is the canonical case). |
| Field | Required | Type | Notes |
| ---------------------------------- | ------------------------------------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | yes | string | Must match `^[a-z0-9][a-z0-9._-]*$` (lowercase alphanumeric, dots, underscores, hyphens; must start with a lowercase alphanumeric). Directory name under `~/.kandev/plugins/`. |
| `api_version` | yes | int | Must be exactly `1`. Any other value is rejected. |
| `version` | yes | string | Free-form; used as the version directory name (`~/.kandev/plugins/<id>/<version>/`). |
| `display_name` | no | string | Shown in Settings > Plugins. |
| `description` | no | string | Shown in Settings > Plugins. |
| `author` | no | string | Free-form. |
| `categories` | no | string[] | Each entry must be one of `connector`, `automation`, `tools`, `analytics`. Unknown values are rejected. |
| `icon` | no | string | Package-relative path (e.g. `icon.svg`) to an image the package ships, rendered on the [marketplace](plugins-marketplace.md) card and in plugin lists. The registry index-build resolves it to an absolute `icon_url`; for an installed plugin it is served from the extracted package. Omit it and the card falls back to a letter tile. |
| `repo_url` | no | string | Absolute `http(s)` URL to the plugin's source repository. Rendered as a "Repo" link in Settings > Plugins (both the installed list and the plugin detail). Any other scheme (e.g. `javascript:`) is rejected at registration. Distinct from the marketplace card's `repo_url`, which the registry derives from `plugins.yaml`; declare this in the manifest so sideloaded and directly-installed plugins also carry the link. |
| `runtime.type` | conditionally | string | `"binary"` is the only supported value. Setting it (vs. leaving it empty) makes the manifest **runtime-managed**; see "Managed vs. legacy" below. |
| `runtime.executables` | required when `runtime.type: binary` | map\<string,string\> | Key is `<goos>-<goarch>` (e.g. `linux-amd64`, `darwin-arm64`, `windows-amd64`); value is a clean, package-relative path under `server/` (no leading `/`, no `..` segments). At least one entry required; the running host's key must be present at install time. Windows values end in `.exe`. |
| `min_kandev_version` | no | string | Lowest released Kandev version this plugin supports. Enforced at **install time**: installing onto an older release fails with `requires kandev >= <version>, running <version>` and nothing is registered. Already-installed plugins are never re-checked at load or start. Release values use up to three dotted numeric segments (`0.78.0`) and may have a leading `v`; malformed minimums are rejected. Non-release development and git-describe builds skip the compatibility gate. |
| `capabilities.events` | no | string[] | Bus subjects (or wildcard patterns) this plugin subscribes to. See "Event subscription vocabulary" below. |
| `capabilities.api_read` | no | string[] | Gates the Host data API's read-only accessors. Each entry is a resource name: `tasks`, `sessions`, `messages`, `workspaces`, `workflows`, `agent_profiles`, `executor_profiles`, `repositories`. Calling the matching `Host` accessor (e.g. `Tasks()`) without its resource declared returns gRPC `PermissionDenied`. See "Host data API resource vocabulary" below. |
| `capabilities.api_write` | no | string[] | Gates Host writes independently of `api_read`. `tasks` permits `Host.Tasks().Create` and `.Update`; `messages` permits `Host.Messages().Send`. Undeclared writes return gRPC `PermissionDenied`. |
| `capabilities.state` | no | bool | Gates `Host.GetState`/`SetState`/`DeleteState`/`ListState`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
| `capabilities.secrets` | no | bool | Gates `Host.RevealSecret`/`GetSecret`/`SetSecret`/`DeleteSecret`. Calling any of them without this set to `true` returns gRPC `PermissionDenied`. |
| `capabilities.agent_invoke` | no | bool | Gates `Host.InvokeUtilityAgent`: a one-shot completion run by the utility agent selected for this plugin. Declare a `utility_agent` config property with `type: string` and `format: utility-agent`; Settings > Plugins renders the picker. The selected utility agent resolves its own enabled ACP profile. Calling without this capability returns gRPC `PermissionDenied`; calling without a valid profile-backed selection returns gRPC `FailedPrecondition`. See ADR 0048. |
| `capabilities.auth` | no | bool | Lets the plugin log a visitor in against an external IdP (OIDC/SAML). Its webhook validates the token, then asserts the identity to Kandev via the `X-Kandev-Auth-Login` response header (`{provider, subject, email, display_name}`); Kandev mints the session and sets the cookie, so the plugin never sees the token. Requires authentication enabled; new users are provisioned as members, and Kandev never creates an admin nor auto-links to an existing admin account. **You MUST only assert an email the IdP verified as owned by the subject; a spoofed email claim is account takeover.** Highest-privilege capability; grant only to trusted plugins. See ADR 0050. |
| `capabilities.user_state` | no | bool | Gates `host.storage` (`get`/`set`/`delete`/`list`/`subscribe`), the authenticated per-user browser storage surface at `/api/plugins/{id}/user-state/...`. Unlike `capabilities.state` (the gRPC `Host.SetState` family, written by the plugin's own backend), this is reachable directly from the plugin's frontend bundle with no Go backend required; every read/write is scoped to the calling user. Calling the route without this capability returns `403`. See [Authoring a plugin](plugins-authoring.md) and the per-user-plugin-storage decision record. |
| `webhooks[].key` | yes | string | Must be unique within the manifest. Used in the relay path `POST /api/plugins/{id}/webhooks/{key}`. |
| `webhooks[].description` | no | string | Free-form. |
| `webhooks[].method` | no | string | **Informational only**: kandev does not validate or enforce the inbound HTTP method against this value. |
| `webhooks[].access` | no | string | `public` (default) allows anonymous callers; `authenticated` requires a Kandev identity. Cookie-authenticated browser calls remain subject to Kandev's same-origin policy. |
| `webhooks[].max_body_bytes` | no | int | Request-body limit for this key. Defaults to 4 MiB. Public webhooks cannot exceed 4 MiB; authenticated webhooks can request up to 16 MiB. Plugins using this field should declare the first supporting `min_kandev_version`. |
| `actions[]` | no | object[] | Authenticated, manifest-declared browser actions. They are distinct from public webhooks: the host validates the action key, limits the JSON body, authorizes the declared resource, and passes only a verified context to the plugin. |
| `actions[].key` | yes\* | string | Unique non-empty action key, used at `POST /api/plugins/{id}/actions/{key}`. |
| `actions[].scope` | yes\* | `workspace` \| `task` \| `repository` | Resource selector the host authorizes. A task-scoped invocation may additionally name one repository attached to that verified task. Use the canonical field name `scope`; `resource_scope` is only a legacy read-compatibility spelling and must not be authored. |
| `actions[].max_body_bytes` | yes\* | int | Maximum size of the decoded untrusted `body`, from 1 through 1,048,576 bytes. The whole HTTP envelope has a slightly larger hard cap. |
| `repository_providers` | no | string[] | Provider IDs this plugin owns while active. An active provider can register native repository discovery/URL inspection and may supply transient Git credentials. Duplicate ownership is rejected. |
| `reference_sources[]` | no | object[] | Dynamic composer-reference source. Each entry declares `source`, `provider`, `kind`, `display_name`, and `kind_label`; `order` is optional. Candidate identity is not trusted: Kandev reauthorizes the canonical reference when it is submitted. |
| `auth_providers[]` | no | object[] | Login buttons this plugin contributes to the pre-auth login screen (needs `capabilities.auth`). Each is `{ id, display_name, initiate }`, where `initiate` names one of the plugin's `webhooks[].key` values; the button navigates to that webhook, which 302-redirects to the IdP. Surfaced anonymously in the boot payload as `auth.ssoProviders`. |
| `config_schema` | no | object | JSON-Schema-like object driving the settings form at **Settings > Plugins > `<plugin>`** (`GET /api/plugins/{id}/config` and `PATCH /api/plugins/{id}`). See "Config schema validation and secret fields" below. |
| `agent_tools` | no | object[] | Task-aware MCP tools implemented by the managed plugin's optional `AgentToolPlugin` SDK interface. Each declaration has a local `name`, `description`, `surfaces`, required `input_schema`, optional `output_schema`, and optional MCP annotation hints. At most 16 tools are allowed. |
| `agent_tools[].name` | yes\* | string | Plugin-local name matching `^[a-z0-9][a-z0-9_]{0,31}$`. Kandev derives the global MCP name; authors cannot choose it. |
| `agent_tools[].surfaces` | yes\* | string[] | One or both of `kanban-task` and `office-task`. Plugin tools are not exposed to `configuration` or `external` MCP surfaces. |
| `agent_tools[].input_schema` | yes\* | object | Compiled object-root JSON Schema, at most 64 KiB serialized. Kandev rejects unknown top-level arguments before invoking the plugin. |
| `agent_tools[].output_schema` | no | object | Optional compiled object-root JSON Schema applied to structured plugin results. |
| `agent_tools[].annotations` | no | object | MCP hints: `read_only_hint`, `destructive_hint`, `idempotent_hint`, and `open_world_hint`. Omitted values use conservative host defaults. |
| `ui.bundle` | no | string | Root-relative path (must start with `/`, e.g. `/ui/bundle.js`) to the plugin's native UI ES module, served at `GET /api/plugins/{id}/bundle`. |
| `ui.styles` | no | string[] | Root-relative CSS paths (each must start with `/`), served at `GET /api/plugins/{id}/ui/*` and injected as `<link>` tags on load. |
| `ui.pages` | no | object[] | Optional declarative metadata accepted by the manifest model. The current frontend does not render these entries; a native bundle registers its supported routes/nav/slots at runtime, so most plugins omit `ui.pages`. |
| `ui.pages[].key` | yes\* | string | Stable identifier for the page (\*required when a page entry is present). |
| `ui.pages[].title` | yes\* | string | Display title. |
| `ui.pages[].path` | yes\* | string | Route path for the page. |
| `ui.pages[].surface` | yes\* | string | Metadata enum (`settings` · `task-panel` · `main-nav`) validated by the manifest parser. It is not a current frontend mount; use the registry hooks in the authoring guide. |
| `ui.keybindings` | no | object[] | Declares plugin keybindings bound at runtime via `registerKeybinding`. Requires `ui.bundle`. |
| `ui.keybindings[].id` | yes\* | string | Stable, plugin-local slug (_required when a keybinding entry is present). Must match `^[a-z0-9][a-z0-9-]_$`and be unique within this plugin's own`ui.keybindings`list, not globally; the effective shortcut is namespaced`plugin:{pluginId}:{id}`. |
| `ui.keybindings[].default` | yes\* | string | Default combo string. `+`-separated tokens: zero or more modifiers from `mod`, `ctrl`, `cmd`, `meta`, `alt`, `option`, `shift` (`mod` = ⌘ on macOS, Ctrl elsewhere) plus exactly one non-modifier key. `shift` may not combine with a digit or symbol key; the browser reports the shifted glyph for those keys, so the combo could never match. |
| `ui.keybindings[].description` | yes\* | string | Non-empty, human-readable label shown in **Settings > Keyboard Shortcuts**. |
| `ui.keybindings[].allow_in_editor` | no | boolean | Lets this binding fire while an `input`, `textarea` or contenteditable holds focus. Defaults to `false`, so a plugin cannot shadow ordinary typing. Only accepted on a combo carrying a `ctrl`/`cmd`/`mod`/`alt` modifier; `shift` alone does not count. Kandev re-applies that requirement to the effective combo, so a user override that drops the modifier reverts to skip-while-typing behavior. |
`ui.pages` is declarative manifest metadata only and is not currently rendered
by the frontend. A native bundle's runtime nav items, icons, routes, named
@@ -202,15 +221,20 @@ recognizes its shape.
`capabilities.api_read` gates the read-only Host data accessors (ADR 0043,
ADR 0047): each entry must be one of `tasks`, `sessions`, `messages`,
`workspaces`, `workflows`, `agent_profiles`, `repositories`. Declaring a
`workspaces`, `workflows`, `agent_profiles`, `executor_profiles`, `repositories`. Declaring a
resource grants the matching `Host` accessor (`Tasks()`, `Sessions()`,
`Messages()`, `Workspaces()`, `Workflows()`, `AgentProfiles()`,
`Repositories()`, see [Authoring a plugin](plugins-authoring.md)); calling an
`Repositories()`), or the optional `pluginsdk.ExecutorProfiles(host)` extension;
see [Authoring a plugin](plugins-authoring.md). Calling an
accessor for an undeclared resource returns gRPC `PermissionDenied`.
`capabilities.api_write` gates the current Host data writes: `tasks` gates
`Tasks().Create`/`Update`, and `messages` gates `Messages().Send`. A plugin may
declare a read resource without its write capability, or vice versa. Calling a
write without the matching declaration returns gRPC `PermissionDenied`.
`capabilities.api_write` currently accepts `tasks` and `messages`. `tasks`
enables `Host.Tasks().Create` and `.Update`; `messages` enables
`Host.Messages().Send`. The host applies the same first-party task service and
message-delivery path as its own UI/API, emits the normal events, stamps created
rows/messages as `plugin:<id>`, and does not let a plugin supply that provenance.
A plugin may declare a read resource without its write capability, or vice
versa. Calling a write without the matching declaration returns gRPC
`PermissionDenied`.
`messages` reads historical **conversation content** (`Messages().List`):
one user/agent message per row (`id`, `session_id`, `task_id`, `turn_id`,
@@ -307,7 +331,7 @@ just the subject itself (`task.created`).
| Linear | `linear.new_issue` |
| Sentry | `sentry.new_issue` |
| Office (autonomous agents) | `office.agent.created`, `office.agent.updated`, `office.agent.status_changed`, `office.skill.created`, `office.skill.updated`, `office.project.created`, `office.project.updated`, `office.approval.created`, `office.approval.resolved`, `office.comment.created`, `office.cost.recorded`, `office.run.queued`, `office.run.processed`, `office.run.event_appended` (per-run), `office.routine.triggered`, `office.inbox.item`, `office.task.status_changed`, `office.task.updated`, `office.task.decision_recorded`, `office.task.review_requested`, `office.provider.health_changed`, `office.route_attempt.appended`, `office.routing.settings_updated` |
| Cross-plugin | `plugin.<plugin_id>.<name>`; published by `Host.EmitEvent`; subscribe with `plugin.<other-plugin-id>.*` to react to another plugin's events. |
| Cross-plugin | `plugin.<plugin_id>.<name>`: published by `Host.EmitEvent`; subscribe with `plugin.<other-plugin-id>.*` to react to another plugin's events. |
> Event list current as of 2026-07-16; regenerate from
> `apps/backend/internal/events/types.go` if this page drifts from the code.
+10 -8
View File
@@ -16,8 +16,9 @@ For building a plugin, see [Authoring a plugin](plugins-authoring.md). For the
manifest schema, see [Plugin manifest reference](plugins-manifest.md).
Plugins are an operator-level, instance-wide capability, there is no
per-user plugin access. They ship in the base product with no feature flag to
turn on: **Settings > Plugins** is always available in the sidebar. Because
per-user plugin access. Installing a plugin requires an administrator when
authentication is enabled. They ship in the base product with no feature flag
to turn on: **Settings > Plugins** is always available in the sidebar. Because
loaded plugin code runs with backend privileges, install only plugins you
trust, see [Security posture](#security-posture).
@@ -255,12 +256,13 @@ recorded and are cleared after successful recovery.
it declared in its manifest: `state` gates the state RPCs, `secrets` gates
the plugin-owned secret RPCs, and each read-only data accessor (tasks,
sessions, workspaces, workflows, agent profiles, repositories) is gated
individually via `api_read:<resource>` and `api_write:<resource>` for the
implemented task/message Host writes. An undeclared capability returns gRPC
`PermissionDenied` with a message naming the missing capability, checked by
a server interceptor before the handler runs. `GetConfig` and `EmitEvent`
are the only ungated RPCs: a plugin can always read its own config
(secrets included) and emit events.
individually via `api_read:<resource>`. Task create/update and message send
are independently gated by `api_write:tasks` and `api_write:messages` and
use Kandev's first-party service paths. An undeclared capability returns
gRPC `PermissionDenied` with a message naming the missing capability,
checked before the handler runs. `GetConfig` and `EmitEvent` are the only
ungated RPCs: a plugin can always read its own config (secrets included)
and emit events.
- **Native UI plugins run in-origin with full app-store access.** This is an
accepted tradeoff, not an oversight: a plugin bundle shares the kandev
React instance and Zustand store so it can build UI indistinguishable from
Binary file not shown.

After

Width:  |  Height:  |  Size: 13 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 26 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 12 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 14 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 9.4 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 22 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 55 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 15 KiB

+1
View File
@@ -127,6 +127,7 @@ Per-workspace credentials and triage triggers for external services.
| Spec | Status |
|---|---|
| [azure-devops-integration](azure-devops-integration/spec.md) | shipped |
| [bitbucket-plugin](bitbucket-plugin/spec.md) | approved |
| [slack](integrations/slack.md) | archived — moved to `kandev-plugin-slack` |
| [external-mcp](integrations/external-mcp.md) | draft |
| [mcp-tool-argument-validation](integrations/mcp-tool-argument-validation.md) | shipped |
+370
View File
@@ -0,0 +1,370 @@
---
status: approved
created: 2026-07-31
owner: kandev
---
# Bitbucket Connector Plugin
## Why
Teams using Bitbucket Cloud or Bitbucket Data Center need repository, pull-request,
and task workflows without putting Bitbucket API knowledge or credentials into the
Kandev host. The connector must feel native where users already create, link, review,
and reference work, while remaining independently releasable as an official plugin.
## What
- Kandev ships the official `kandev-plugin-bitbucket` from its dedicated public
repository. Its manifest pins `min_kandev_version` to the first released host
version containing the required generic contracts; it never guesses an unreleased
version.
- The initial release follows Kandev's current unsigned marketplace trust contract:
the generated internal `checksums.txt` is mandatory, the host reports the package
as unsigned, and neither repository claims cryptographically verified publisher
provenance. Signing is future host-wide work rather than a Bitbucket release gate,
as recorded in
[ADR-2026-08-01-bitbucket-initial-release-remains-unsigned](../../decisions/2026-08-01-bitbucket-initial-release-remains-unsigned.md).
- The plugin supports Bitbucket Cloud and Bitbucket Data Center through separate
adapters behind one Bitbucket domain. Cloud and Data Center have full capability
parity wherever their APIs provide an equivalent operation. Capability flags hide
unavailable controls or explain version-specific limits; the UI never presents a
non-working equivalent.
- A workspace connects with Cloud API token or OAuth 2.0, and with Data Center
personal/HTTP access token or OAuth 2.0 when its administrator configured an
incoming OAuth application link. Cloud app passwords are not accepted. OAuth client
registrations are bring-your-own per workspace; no client secret ships in the public
plugin.
- The plugin owns Bitbucket REST payloads, OAuth and token rules, product/version
probes, pagination, rate-limit handling, health polling, secret refresh, connector
screens, watches, normalized review/status data, and provider actions. The host owns
reusable authenticated action, repository-provider, task-action, review-provider,
reference-source, task ownership, credential-broker, and code-host presentation
contracts. GitHub, GitLab, and compatible plugins use the same host-rendered task
status and review-detail anatomy rather than provider-owned approximations.
- Users browse/search repositories, select branches, inspect pull-request URLs, launch
tasks from pull requests, link/unlink existing tasks, and create pull requests from
a task checkout branch. Remote descriptors preserve the exact credential-free clone
URL, including Data Center context paths.
- Native **Create PR** remains conditional on a task checkout containing commits and
having no linked change request. For a registered provider, Kandev keeps the shared
dialog, pushes the verified checkout branch through its normal Git path, and then
invokes the provider's authenticated create callback. Unsupported provider options,
such as draft creation, are hidden rather than silently ignored. This boundary is
recorded in
[ADR-2026-08-10-plugin-change-request-mutations](../../decisions/2026-08-10-plugin-change-request-mutations.md).
- Plugin task actions appear in native task surfaces. Inside the existing **Link**
submenu, the required entry is named **Bitbucket Pull Request**; it never repeats the
parent verb as “Link Bitbucket Pull Request.” Selecting it opens the same host-owned
task change-request dialog used by GitHub: title and explanatory description, one
labeled input, inline validation, Cancel and Save footer actions, disabled/submitting
state, success toast, and close-on-success. Provider code owns reference parsing and
the authenticated link mutation, not modal anatomy. Desktop and mobile expose the same
capability and host-native dialog behavior.
- Bitbucket pull requests appear through the native review-provider registry in desktop
selectors, dock/detail panels, task center, and mobile review navigation. The plugin
maps Bitbucket detail, checks, reviews, comments, and capabilities into the host's
provider-neutral change-request model and renders the same host-owned detail component
as GitHub. The plugin supplies callbacks for supported mutations; the host owns header,
sections, action placement, loading/error anatomy, scrolling, and responsive behavior.
Unsupported Cloud/Data Center capabilities are omitted or explained without changing
the shared layout.
- Linked Bitbucket pull requests expose host-owned unlink controls in shared desktop
popovers/review anatomy and touch-sized mobile surfaces. Unlink removes only the
selected task association, refreshes review/status data, and immediately removes the
corresponding task indicator without deleting the remote pull request. An explicit
unlink suppresses source-branch auto-link for that task/pull-request pair until a
manual relink and detaches watch ownership without deleting the task.
- Composer `#` search consumes the plugin's dynamically registered
`bitbucket`/`pull_request` reference source. Kandev constructs canonical reference
identity, and every selected reference is reauthorized by the live plugin at message
submission so stale, tampered, cross-workspace, or disabled-plugin selections fail
closed.
- **Settings > Integrations > Bitbucket** provides connection/authentication, health,
and saved-watch management through the plugin's native integration-settings
contribution. The `/bitbucket` page uses the same host-owned dashboard primitives
as `/github` and `/gitlab`: compact scope controls, result title/count, repository
and query filters, refresh, and one full-width bordered pull-request
list. Rows use the same inert-container, external-title, metadata, linked-task, and
sole **Task** preset-menu anatomy. Preset selection opens the native
`TaskCreateDialog` directly; no Bitbucket launch intermediary or row-level Review
action exists. Dashboard scope selection commits its normalized filter into the
visible query field, matching GitHub/GitLab; manually committed query changes and
the active scope always drive the same provider request. Scope and pull-request
state glyphs use host-owned semantic integration icons rather than plugin-drawn
copies. Review remains in normal linked-task desktop/mobile review surfaces.
The preset menu uses the exact first-party glyphs: eye for **Review**, message for
**Address feedback**, and tool for **Fix CI**.
Committed custom queries and repository filters can be named, saved, selected, and
deleted with the same scope-bar workflow as GitHub/GitLab. Saved queries are
per-user, per-workspace plugin state through `host.storage`; saving commits and stores
the visible query draft even when the user has not pressed Enter first.
Existing workspace repositories use the dialog's normal REST create path. First-use
Bitbucket repositories use the dialog's optional create transport through the
authenticated `tasks.launch` action; the server resolves the repository descriptor
from the connected pull request and uses a per-dialog launch ID for retry-only
deduplication. Browser payloads cannot nominate a trusted repository descriptor, and
separate Task-menu launches may create separate tasks for the same pull request.
After a Bitbucket repository is persisted, the dialog's native branch picker routes
through the plugin's workspace-scoped `repositories.branches` action. The host derives
its descriptor from that repository row, so the picker has Cloud/Data Center branches
without a GitHub fallback, local-clone dependency, or browser-selected authority.
This boundary is recorded in
[ADR-2026-08-06-plugin-code-host-dashboard-parity](../../decisions/2026-08-06-plugin-code-host-dashboard-parity.md).
Watch creation and management remain in **Settings > Integrations > Bitbucket**;
the dashboard does not add a provider-specific Watch button absent from GitHub/GitLab.
- Watches use authenticated polling, not Bitbucket event webhooks. OAuth callback is
the only required public webhook in v1. A watch writes a durable `creating`
reservation before task creation, stamps plugin/watch/external-PR ownership, and
reconciles unfinished reservations after restart. Reset/delete previews its cascade
and deletes only tasks owned by this plugin/watch; manually linked or adopted tasks
remain.
- Manual links, pull requests created from a task, and watch-created tasks all expose
one durable task-to-pull-request association to the dashboard, native Review
provider, and task-topbar status control. Restart recovery preserves watch-owned
associations without duplicating them into manual-link state.
- Task refresh detects an externally created open pull request by exact source-branch
match against each host-verified Bitbucket checkout and persists that association
idempotently. The browser cannot nominate the repository or branch, and a transient
discovery failure never removes or hides existing links.
- A linked Bitbucket pull request contributes normalized status through its registered
review-provider snapshot. Kandev automatically renders that status in both places used
by GitHub: the compact task-topbar pull-request control and the CI chip above the chat
composer (including passthrough sessions). Both use the exact shared trigger and
popover/drawer body, not a plugin slot or provider-owned lookalike. Desktop hover uses
the same delay; touch/mobile uses the same bounded, internally scrollable drawer.
Opening either surface refreshes immediately, the provider polls in the background
around every 90 seconds, and clicking through opens the registered Bitbucket Review
surface. Cloud Pipelines and Data Center build statuses are normalized from the pull
request's source/head commit, never its destination commit.
- The review provider exposes one bounded workspace association snapshot. Kandev uses
it to render its semantic pull-request glyph beside linked tasks in task switcher,
Kanban, and rich task-list rows, without issuing one provider request per task. On
mouse hover or keyboard focus, that glyph opens the same host-owned structured
pull-request summary used by GitHub (number, title, review, CI, and available state),
resolving detail lazily through the registered review-provider snapshot. A plain
count-only tooltip is not parity. Touch/mobile continues through the native task
status and Review surfaces; no required information or action is hover-only.
- Clone, fetch, and push resolve through the provider-neutral short-lived credential
broker. Secrets never appear in clone URLs, task metadata/state, environment
variables, command arguments, logs, or executor payloads.
Initial host-side materialization carries the same host-derived workspace, task,
active-session, repository, exact-host, and exact-path scope to the plugin; an
incomplete scope is rejected instead of falling back to a workspace-only secret.
Existing managed checkouts are refreshed through that exact scope before worktree
creation; local and worktree execution then use refreshed refs without a second
network operation.
## Capability matrix
| Capability | Cloud | Data Center |
| --------------------------------------------------------------------------------- | ----------------------- | ------------------------------------------------------- |
| API token/PAT connection and health | Required | Required |
| OAuth 2.0 connect and refresh | Required | Required when an incoming OAuth application link exists |
| Repository/project browse and search | Required | Required |
| Native repository picker, branch selection, and PR URL inspection | Required | Required |
| Scoped clone/fetch/push credential broker | Required | Required |
| Launch task, link/unlink, and create PR from task | Required | Required |
| Native desktop/mobile review panel | Required | Required |
| Composer `#` pull-request search and submitted context | Required | Required |
| Queue, files/diff, commits, comments/threads, reviewers, approvals, merge/decline | Required | Required where server API supports thread semantics |
| Status presentation | Pipelines | Commit/build status |
| Watches with deduplicated task creation | Required | Required |
| Bitbucket Issues | Not supported; use Jira | Not supported; use Jira |
## Connection, permissions, and secrets
Connection state is `unconfigured`, `checking`, `connected`, `auth_required`, or
`unavailable`. Workspace-scoped encrypted plugin secrets hold token/PAT credentials,
OAuth registrations, grants, and rotating refresh tokens. State stores only non-secret
connection metadata and an atomically rotated credential generation. Refresh is
singleflight per workspace/generation/connection epoch. Disconnect or connection
replacement removes completed refresh data and fences an exchange already in flight;
that stale result cannot be returned, cached, or persisted. Logs and returned errors
redact headers, query parameters, and secret values.
The host authenticates browser actions through normal Kandev session middleware and
authorizes every claimed workspace, task, and repository before dispatch. It derives
task-to-workspace relationships server-side. Plugins receive verified actor/resource
context separately from bounded untrusted JSON. The connector can create or cascade-
delete only task trees stamped `metadata.source = "plugin:kandev-plugin-bitbucket"`;
pre-existing task links remain plugin state rather than host-owned task provenance.
Data Center accepts private-network installations intentionally. Production connections
require HTTPS, reject URL credentials, retain redirect origin, and enforce connect/read
timeouts and response-size limits. HTTP is development-only behind an explicit setting.
## API and host contracts
The required generic seams are defined by
[authenticated plugin actions](../../decisions/2026-07-31-authenticated-plugin-actions.md),
[repository-provider extensions](../../decisions/2026-07-31-plugin-repository-provider-extensions.md),
and [provider-neutral git credential brokerage](../../decisions/2026-07-31-provider-neutral-git-credential-broker.md).
Their frozen protocol/UI references are
[`GRPC-CONTRACT.md`](../../plans/plugins/GRPC-CONTRACT.md),
[`HOST-DATA-API.proto`](../../plans/plugins/HOST-DATA-API.proto), and
[`PLUGIN-API.md`](../../plans/plugins/PLUGIN-API.md).
The plugin declares actions including `connection.get`, `connection.save`,
`oauth.start`, `repositories.list`, `pullrequests.get`, and `watches.update`; each
has a resource scope and bounded body. It declares ownership of provider ID
`bitbucket` and the `bitbucket`/`pull_request` reference source. The browser calls
declared actions only through the authenticated host action route; public plugin
webhooks remain reserved for provider callbacks.
## Failure modes
- A disabled, unavailable, or timed-out action plugin returns a bounded actionable
error; it does not expose the public webhook route as a browser fallback.
- A failed connection, expired credential, or refresh denial transitions visibly to
`auth_required` or `unavailable`; existing non-secret connection metadata stays
intact. Health probes run around every 90 seconds with jitter/backoff.
- Cloud rate limits and Data Center transient failures use adapter-owned bounded retry/
backoff. Unsupported product/version capabilities show an unsupported explanation.
- An invalid or incomplete provider descriptor, host/path mismatch, stale broker
lease, disabled provider, or submission reauthorization denial fails closed.
- Watch create/recovery failures preserve durable reservations and surface the last
error. A reset/delete never removes a task whose plugin provenance does not match.
## Persistence guarantees
Plugin state persists connection metadata, capability probe result, watches, cursors,
dedupe keys, reservations, links, and recovery/error state through the Host state API.
Durable pull-request identity is provider ID plus provider connection scope plus
immutable repository ID plus pull-request number; repository namespace/path and display
keys are never dedupe authority. Provider cursors are bound to that immutable identity
and their normalized query. Connection replacement pauses a bound watch before any
provider request; explicit resume rebinds it and clears stale pagination state.
Encrypted secrets persist separately. Credential broker leases are short-lived and
non-durable; they are re-resolved from the live plugin and revoked on task/session/
workspace teardown, plugin disable, connection reset, or credential-generation change.
The plugin exposes that generation only as an opaque, non-secret credential binding;
the host checks it before and after each lease redemption and fails closed when absent
or changed. Plugin disable, error, or uninstall also immediately revokes every lease
for its declared provider; exact repository path matching remains case-sensitive.
## Scenarios
- **GIVEN** the independently released Bitbucket UI bundle, **WHEN** it compiles or
launches native task creation, **THEN** it consumes `@kandev/plugin-sdk` and typed
`host.context` reads without copied host interfaces or private Zustand slice parsing.
- **GIVEN** Bitbucket is active and a user pastes a URL owned by GitHub, GitLab, or
another self-hosted provider, **WHEN** Kandev probes registered repository providers,
**THEN** Bitbucket's workspace-scoped structured inspector returns no match and does
not steal the URL by hostname/path heuristics or registration order.
- **GIVEN** a connected Cloud or Data Center workspace, **WHEN** a user selects a
Bitbucket repository in native task creation, **THEN** Kandev persists the complete
plugin-inspected descriptor and exact credential-free clone URL without host-side
Bitbucket URL parsing.
- **GIVEN** two Data Center connections share one authority but use different context
roots, **WHEN** either imports the same project/repository slug, **THEN** Kandev keeps
distinct rows and managed clones using the plugin's connection scope and immutable
repository ID; it never adopts the other root or a legacy unscoped row.
- **GIVEN** a persisted Bitbucket repository is materialized for a task session,
**WHEN** Kandev requests the initial HTTPS clone credential, **THEN** the plugin
receives the host-derived workspace, task, session, repository, exact-host, and
exact-path scope, and missing or mismatched scope fails before Git runs.
- **GIVEN** that managed checkout already exists and pull-before-worktree is enabled,
**WHEN** a task session launches, **THEN** Kandev refreshes origin through the same
exact plugin credential scope and performs no unauthenticated follow-up fetch or pull.
- **GIVEN** an eligible task, **WHEN** a user opens a desktop task context/dropdown or
visible mobile task action menu, **THEN** **Link → Bitbucket Pull Request** is
represented by a **Bitbucket Pull Request** child item and invokes the plugin with
verified current context.
- **GIVEN** that item is selected, **WHEN** the user enters an invalid or valid Bitbucket
pull-request reference, **THEN** the host renders GitHub-parity dialog geometry and
footer behavior, keeps validation errors inline, and on success closes the dialog and
shows a success toast after the authenticated task-scoped link completes.
- **GIVEN** a Bitbucket pull request linked to a task, **WHEN** the user opens review
on desktop or mobile, **THEN** the native review surface selects a normalized
Bitbucket item and mounts the host-owned change-request detail anatomy used by GitHub,
with Bitbucket data and only the actions its adapter declares.
- **GIVEN** the plugin is disabled after a review panel, task action, or repository
provider was registered, **WHEN** Kandev refreshes the plugin registry, **THEN**
those registrations disappear, in-flight work is aborted, review selections close
safely, and no host Bitbucket fallback remains.
- **GIVEN** the plugin is active, **WHEN** a user opens the native integrations index
or a workspace settings tree, **THEN** Bitbucket appears with its plugin-owned brand icon and
native settings page, receives the selected workspace ID, and disappears from both
surfaces when the plugin unloads.
- **GIVEN** a connected Bitbucket workspace, **WHEN** the user opens `/bitbucket`,
**THEN** the page uses the same list-first hierarchy, density, toolbar geometry,
row anatomy, and restrained loading/error/empty treatment as `/github` and
`/gitlab`; the host renders shared primitives rather than plugin-cloned markup.
- **GIVEN** more than one provider page of repositories or pull requests, **WHEN** the
user searches the repository filter or changes result pages, **THEN** the dashboard
consumes opaque cursors, exposes every repository, and keeps a deterministic
provider-neutral queue order without truncating before pagination.
- **GIVEN** a pull request in that list, **WHEN** the user opens its **Task** menu,
**THEN** the same compact preset menu as GitHub/GitLab appears and the chosen preset
opens Kandev's native task dialog directly with repository, source branch, title,
and prompt prefilled; the three preset rows use the exact native eye, message, and
tool glyphs.
- **GIVEN** a Bitbucket task is created or already linked, **WHEN** the user returns to
the dashboard or opens task Review, **THEN** the row exposes the native linked-task
indicator and review opens through the registered task review provider; there is no
dashboard Review button or intermediate launch dialog on desktop or mobile.
- **GIVEN** a linked Bitbucket pull request has normalized task status, **WHEN** its
task-list indicator renders or its lazy desktop refresh completes, **THEN** the glyph
uses the same failure, pending, review-wait, passing, merged, and muted color hierarchy
as first-party code hosts without accepting provider CSS or Bitbucket-specific tones.
- **GIVEN** a committed custom query or repository filter differs from a built-in
preset, **WHEN** the user saves and names it, **THEN** it appears in the shared saved
menu, survives reload for that user/workspace, restores the displayed query and
repository filter when selected, and can be deleted.
- **GIVEN** a pull request repository is not yet persisted in the workspace, **WHEN**
the native task dialog submits or retries, **THEN** the authenticated plugin action
creates from the server-resolved source repository exactly once for that dialog
launch; opening the Task menu again may create another linked task.
- **GIVEN** that Bitbucket repository is persisted, **WHEN** the native task dialog
loads its branch picker, **THEN** Kandev invokes the active Bitbucket plugin with the
stored provider descriptor and renders its branches without a GitHub request, a 500,
or a local-clone fallback.
- **GIVEN** a `#` Bitbucket pull-request result was selected, **WHEN** the message is
submitted after the plugin was disabled, moved workspaces, or access changed,
**THEN** submission reauthorization rejects it and no unapproved reference metadata
reaches the queued message.
- **GIVEN** a watch finds the same pull request concurrently or restarts during task
creation, **WHEN** recovery runs, **THEN** the durable reservation and plugin-owned
task metadata result in at most one created task; reset/delete previews and removes
only that owned tree, and the recovered task remains associated with the pull request
in dashboard, Review, and status queries.
- **GIVEN** a task creates a Bitbucket pull request successfully, **WHEN** the result is
returned or the task is reopened, **THEN** the new pull request is already associated
with that task; a later association-state failure is reported without inviting a
retry that could create a duplicate remote pull request.
- **GIVEN** an eligible Bitbucket task has commits and no linked pull request, **WHEN**
the user submits native **Create PR**, **THEN** Kandev pushes the selected checkout
branch, verifies the selected session/repository worktree and passes its server-derived
head branch to the active provider, associates the created pull request, and reports a
post-push create failure as retryable without trusting a browser source branch or
adding Bitbucket logic to `agentctl`.
- **GIVEN** one or more Bitbucket pull requests are linked to a task, **WHEN** association
data loads or one link is removed, **THEN** the native task-row/card glyph count and
shared unlink controls update reactively on desktop and mobile while other links
remain intact.
- **GIVEN** an agent or user creates an open Bitbucket pull request externally from a
task's checkout branch, **WHEN** that task refreshes, **THEN** the plugin discovers
the exact source-branch match from host-verified repository data and links it without
a manual URL paste.
- **GIVEN** a linked pull request has source-commit pipeline/build statuses, **WHEN**
the task topbar control or composer CI chip is opened on desktop or mobile, **THEN**
the exact shared GitHub-grade status surface shows those checks, refreshes on open,
and can open the registered Bitbucket Review panel without a provider-specific route.
## Out of scope
- Bitbucket Issues, Cloud app passwords, and a generic host Bitbucket API client.
- Bitbucket-specific changes in `agentctl` pull-request automation or a new
provider-specific WebSocket contract.
- External Bitbucket webhooks for watches; authenticated polling is v1 behavior.
- Pretending Cloud Pipelines and Data Center build statuses have identical APIs.
- A Bitbucket-specific signing verifier or trust-root policy. The initial release uses
the current checksum-verified, explicitly unsigned plugin contract.
- Marketplace publication before required host contracts are released, package,
desktop/mobile, and container credential-flow acceptance passes.
## Implementation plan
[Bitbucket plugin implementation plan](../../plans/bitbucket-plugin/plan.md)
+20 -1
View File
@@ -1,13 +1,14 @@
---
status: building
created: 2026-07-27
updated: 2026-08-02
updated: 2026-08-12
owner: jcfs
---
# Internationalization (i18n)
## Why
Kandev's i18n foundation lets migrated web surfaces externalize copy, switch
locale, and format dates and numbers per language, but English is still the only
human language shipped. Adding Simplified Chinese makes the existing localized
@@ -15,11 +16,16 @@ surface usable by Chinese-speaking users while preserving English as the source
language and the pseudo-locale as the migration QA oracle.
## What
- The web UI SHALL render all user-facing text through a translation layer
(i18next `t("ns:key")` / react-i18next `<Trans>`), not from inline literals. "User-facing text"
covers visible copy, `placeholder`, `aria-label`/`aria-description`, `title`,
`alt`, toast/`sonner` messages, form-validation messages, empty-state and
error copy, and confirm/dialog text.
- Native UI plugins SHALL register plugin-owned catalogs through the public plugin SDK. Kandev
SHALL isolate them by verified plugin identity, require English fallback copy, expose the active
locale through imperative and reactive scoped translation APIs, and remove their resources with
the plugin lifecycle. Plugin catalogs SHALL NOT mutate built-in or sibling-plugin namespaces.
- English SHALL remain the source locale. The shipped human locales SHALL be
`en`, `pt-pt`, and `zh-cn`; copy lives in per-namespace JSON catalogs keyed by
stable ids. The `pseudo` catalog is generated from `en`, never hand-edited.
@@ -92,6 +98,7 @@ merge. Sequence:
currently in `SCREENS`) and the shared-task artifacts.
## Data model
i18n adds no server-side persistent entities. It introduces:
- **Message catalogs** — checked-in JSON under
@@ -117,6 +124,7 @@ There is no SQLite or user-settings persistence for locale. The cookie is the
single persisted source of truth and is hydrated into the store at boot.
## API surface
No new HTTP/WS contract is required to add a locale. Two integration points:
- **Go shell** (`apps/backend/internal/webapp/shell.go`): reads the
@@ -134,8 +142,12 @@ Frontend module contract (new):
- `apps/web/lib/i18n/formats.ts` — locale-aware `formatDate`, `formatRelative`
(replacing `timeAgo`), `formatNumber`, `formatBytes` wrappers over `Intl` /
`date-fns` with the active locale.
- `@kandev/plugin-sdk` — `PluginRegistry.registerTranslations()` plus scoped
`PluginHostApi.i18n.t()` and `useTranslation()` access. See
[ADR-2026-08-12-plugin-localization-contract](../../decisions/2026-08-12-plugin-localization-contract.md).
## Scenarios
- **GIVEN** a fresh install with no locale cookie, **WHEN** the UI loads,
**THEN** `<html lang>` is `en`, all text renders from the `en` catalog, and the
language switcher shows English selected.
@@ -176,6 +188,9 @@ Frontend module contract (new):
falls back to its English default without throwing.
- **GIVEN** a plural key (`x_one` / `x_other`) rendered with a `count`, **WHEN**
count is 1 vs many, **THEN** i18next selects the matching form.
- **GIVEN** two active plugins with the same message key, **WHEN** either translates that key and
the locale changes, **THEN** each receives only its own message and reactive plugin surfaces
rerender. **WHEN** one plugin is disabled, **THEN** only its catalog is removed.
- **GIVEN** a production build, **WHEN** the language switcher renders, **THEN**
English, Português (Portugal), and 简体中文 are offered and the pseudo-locale
is not.
@@ -188,6 +203,7 @@ Frontend module contract (new):
the advisory path must not mask the gating one.
## Failure modes
- **Missing translation for the active locale** → i18next falls back to `en`,
and an entirely unknown key renders as the key itself; the UI never blanks or
throws. The `i18n:check` CI gate is what keeps unknown keys out.
@@ -203,6 +219,7 @@ Frontend module contract (new):
English `defaultProps`; no runtime dependency on the app i18n instance.
## Persistence guarantees
- The locale preference survives a kandev restart through the
`kandev_locale` cookie.
- Message catalogs are source-controlled build inputs; nothing i18n-related is
@@ -211,6 +228,7 @@ Frontend module contract (new):
switching locale is a pure client re-render.
## Out of scope
- Shipping human languages other than English, European Portuguese, and
Simplified Chinese.
- Translating the CLI launcher, logs, or ACP/agent output, and the ~1,100
@@ -229,6 +247,7 @@ Frontend module contract (new):
- A translation-management platform / vendor sync (Crowdin, Lokalise, etc.).
## Resolved decisions
- **Locale storage**: a dedicated `kandev_locale` cookie is the source of truth
(so the Go shell sets `<html lang>` on first paint with no flash); it is
hydrated into user-settings/store for the switcher UI. With no cookie set the
+203 -46
View File
@@ -53,7 +53,8 @@ surfaces. The core stays small; the ecosystem grows independently.
runtime"). This is the one in-process surface; the backend stays out-of-process
(but is now kandev-managed, not operator-managed).
- A plugin manifest declares identity, runtime executables (per OS/arch), capabilities,
declared webhooks, config schema, and optional UI bundle.
declared webhooks and authenticated actions, repository-provider and reference-source
ownership, config schema, and optional UI bundle.
- Plugins SHALL receive events, expose proxied external webhook
endpoints, and read/write a plugin-scoped KV state — all over gRPC.
- Plugins are distributed as a signed-or-unsigned release **tarball** and installed
@@ -69,6 +70,21 @@ surfaces. The core stays small; the ecosystem grows independently.
on crash or health-check failure. Operators no longer run or manage plugin processes
themselves. The remote/self-hosted tier (`base_url` registration of an
operator-run process kandev never spawns) is removed; see "Out of scope".
- Plugin repository providers, task actions, and review panels register through
revocable generic frontend contracts. A provider plugin can participate in native
task creation, Link menus, desktop/mobile review surfaces, and composer `#` search
without a host-specific provider branch.
- The independently consumable, runtime-free `@kandev/plugin-sdk` package is the
frontend author contract. Official plugins use its typed `host.context` reads and
named UI/provider contracts instead of importing or copying private Kandev store,
React, Zustand, or `@/` application types.
- First-party-parity code-host dashboards use host-owned provider-neutral list,
toolbar, scope, task-menu, and linked-task primitives exposed through `host.ui`.
Plugins provide normalized data and callbacks; task presets open the native
`TaskCreateDialog`, while review remains owned by the task review-provider surface.
- Native UI plugins register bounded, plugin-owned translation catalogs and consume them through a
host-scoped imperative/reactive localization API. Locale changes follow Kandev without bundling a
second i18n runtime, and disable/reload/uninstall removes only that plugin's resources.
## Data model
@@ -118,6 +134,21 @@ capabilities:
# "Frontend plugin runtime" and ADR
# 2026-08-01-per-user-plugin-storage
actions:
- key: "connection.save"
scope: workspace # workspace | task | repository
max_body_bytes: 65536
repository_providers: ["example-repository-provider"]
reference_sources:
- source: "example_change_requests"
provider: "example-repository-provider"
kind: "change_request"
display_name: "Example change requests"
kind_label: "Change request"
order: 100
webhooks:
- key: "slack-events"
description: "Slack Events API webhook"
@@ -159,7 +190,7 @@ fields. Existing records without these fields load as null.
`capabilities.api_read` / `capabilities.api_write` gate the **Host data API** Host
RPCs (both reads and writes live now) — the vocabulary is a list of
resource names: `tasks`, `sessions`, `messages`, `workspaces`, `workflows`,
`agent_profiles`, `repositories` for `api_read`, plus `tasks` (CreateTask/
`agent_profiles`, `executor_profiles`, `repositories` for `api_read`, plus `tasks` (CreateTask/
UpdateTask) and `messages` (SendMessage) for `api_write`. See "Host data API".
**Declaring data access.** Listing a resource under `api_read` grants the
@@ -174,6 +205,21 @@ not declared`. Writes work the same way under `api_write` (message
independently on the same resource — a plugin may declare `api_read:tasks`
without `api_write:tasks`, or vice versa (see "Host data API writes").
`actions` declare the only browser-invocable plugin operations. Each key is unique per
plugin, has one resource scope (`workspace`, `task`, or `repository`), and supplies a
bounded request-body maximum. `repository_providers` declares stable IDs the plugin may
register in the frontend repository-provider registry; one enabled plugin owns one
provider ID. A provider that supports the native task branch picker declares the
workspace-scoped `repositories.branches` action. Kandev invokes it server-to-server with
the persisted repository identity and accepts only a bounded normalized branch list;
browser input cannot select the provider or repository for that invocation.
`reference_sources` declares plugin-owned composer sources. Source names
are unique, a descriptor cannot claim another provider, and all entries are removed when
the plugin disables. See ADRs
[2026-07-31-authenticated-plugin-actions](../../decisions/2026-07-31-authenticated-plugin-actions.md)
and
[2026-07-31-plugin-repository-provider-extensions](../../decisions/2026-07-31-plugin-repository-provider-extensions.md).
**External login (`auth`).** An `auth`-capable plugin can log a visitor in
against an external IdP (OIDC/SAML): its webhook (the callback / SAML ACS)
validates the token, then asserts the identity to kandev via the reserved
@@ -192,8 +238,9 @@ See [ADR 0050](../../decisions/0050-plugin-external-auth-capability.md).
There is no manifest-paste registration step. A plugin is installed from a URL or an
uploaded tarball:
1. Operator calls `POST /api/plugins/install` with JSON `{"url": "..."}` (kandev
downloads the tarball) or a multipart `package` field (direct upload).
1. An administrator calls `POST /api/plugins/install` with JSON `{"url": "..."}`
(kandev downloads the tarball) or a multipart `package` field (direct upload).
Auth-disabled single-user instances retain their synthetic administrator.
2. Kandev verifies `checksums.txt` covers every other file in the tarball and every
hash matches (integrity gate, always enforced).
3. If `checksums.txt.sig` is present, kandev verifies the ed25519 signature; if
@@ -235,6 +282,10 @@ CREATE TABLE plugin_state (
### Plugin management API (operator -> kandev, HTTP)
Install is administrator-only when authentication is enabled. Auth-disabled
single-user instances retain the synthetic administrator used by other system
settings.
```
POST /api/plugins/install # Install a plugin: JSON {"url": "..."} or multipart `package`
POST /api/plugins/sync # Reconcile the registry with the plugins directory on disk
@@ -249,6 +300,7 @@ POST /api/plugins/{id}/enable
POST /api/plugins/{id}/disable
GET /api/plugins/{id}/bundle # Frontend bundle, served from the extracted package dir
GET /api/plugins/{id}/ui/* # Frontend bundle assets, served from the extracted package dir
POST /api/plugins/{id}/actions/{key} # Authenticated declared browser action
```
`POST /api/plugins/sync` is documented in full under "Filesystem sideloading & sync"
@@ -263,6 +315,31 @@ Enable/disable/uninstall act on the supervised subprocess: disable stops it (sta
config preserved); enable respawns it; uninstall stops it and deletes its package,
record, and state.
### Authenticated plugin actions (browser -> kandev -> plugin)
`POST /api/plugins/{id}/actions/{key}` is the only browser action route. Kandev first
applies ordinary HTTP authentication, then rejects inactive plugins or undeclared keys
and authorizes every referenced workspace, task, or repository. It derives a task's
workspace relation server-side, passes verified actor/resource context separately from
bounded untrusted JSON, invokes `Plugin.HandleAction` with a hard timeout and
cancellation, and relays only an allowlisted response-header set. Provider callback
routes under `/webhooks/` stay public and must not serve authenticated browser actions.
Task-scoped actions require a verified task and may optionally select one persisted
repository attached to that task; Kandev rejects unattached repository IDs and passes
the accepted repository separately in `VerifiedActionContext`.
The manifest's canonical action field is `scope`; `resource_scope` remains a read-only
compatibility alias for packages produced during the prerelease contract rollout.
### Dynamic composer reference sources (plugin -> kandev)
An active manifest `reference_sources` descriptor registers a plugin bridge in
`internal/mentions`. Kandev calls `Plugin.SearchEntityReferences` with verified
workspace, plain query, and bounded limit; plugin candidates are untrusted. The host
injects descriptor identity and constructs canonical references. Kandev calls
`Plugin.AuthorizeEntityReference` at search and again at message submission with
purpose `search` or `submission`. A disabled plugin, invalid result, stale selection,
or denial fails closed; no stale reference metadata enters the message queue.
### Event delivery (kandev -> plugin, gRPC `DeliverEvent`)
Kandev calls the plugin's `Plugin.DeliverEvent` RPC (unary) with an `Event` message:
@@ -280,6 +357,7 @@ message Event {
Expected response: `EventAck{}`. A non-nil gRPC error or a timeout counts as failure.
Delivery semantics (unchanged from earlier design, now carried over gRPC):
- **At-least-once.** Plugins must be idempotent (dedup by `event_id`).
- **Timeout:** 10 seconds. Up to 3 retries with exponential backoff (5s, 15s, 45s).
- **Sequential per plugin** — no concurrent delivery to the same plugin. Plugins
@@ -292,14 +370,14 @@ Event types: any subject kandev publishes on its internal event bus
below is a non-exhaustive sample across feature areas — the plugin system is not tied to
any one of them.
| Category | Events |
|----------|--------|
| Tasks | `task.created`, `task.updated`, `task.state_changed`, `task.deleted`, `task.moved` |
| Sessions | `task_session.state_changed`, `turn.started`, `turn.completed` |
| Agents | `agent.started`, `agent.completed`, `agent.failed`, `agent.stopped` |
| Category | Events |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Tasks | `task.created`, `task.updated`, `task.state_changed`, `task.deleted`, `task.moved` |
| Sessions | `task_session.state_changed`, `turn.started`, `turn.completed` |
| Agents | `agent.started`, `agent.completed`, `agent.failed`, `agent.stopped` |
| Other feature areas (examples) | Any additional subjects emitted by feature areas such as office/agents (e.g. `office.comment.created`, `office.approval.created`) — plugins may subscribe to these, but the plugin system does not depend on them |
| GitHub | `github.pr_state_changed`, `github.pr_feedback`, `github.new_issue` |
| Plugin | `plugin.<plugin_id>.<name>` (cross-plugin events) |
| GitHub | `github.pr_state_changed`, `github.pr_feedback`, `github.new_issue` |
| Plugin | `plugin.<plugin_id>.<name>` (cross-plugin events) |
Wildcard subscriptions: `task.*`, `agent.*`, `<feature>.*` (any subject prefix).
@@ -427,17 +505,18 @@ domain structs. See [ADR 0043](../../decisions/0043-plugin-host-data-api.md) and
**Readable resources (v1).** Each is gated by an `api_read:<resource>` capability:
| RPC | Capability | Returns |
|---|---|---|
| `ListTasks` / `GetTask` | `api_read:tasks` | Tasks (id, workspace, workflow, title, description, state, priority, timestamps, parent, identifier, repositories, metadata) |
| `ListWorkspaces` | `api_read:workspaces` | Workspaces (id, name, owner, defaults, timestamps) |
| `ListWorkflows` | `api_read:workflows` | Workflows for a workspace |
| `ListWorkflowSteps` | `api_read:workflows` | Steps for a workflow (id, name, position, stage type) |
| `ListAgentProfiles` | `api_read:agent_profiles` | Agent profiles (id, agent id, display name, model, mode) |
| `ListRepositories` | `api_read:repositories` | Repositories for a workspace (id, name, default branch) |
| `ListSessions` | `api_read:sessions` | Session identity + agent context (id, task, agent profile, resolved display name + model, `acp_session_id`, state, timestamps) |
| `ListSessionCodeStats` | `api_read:sessions` | **Computed** per-session code metrics: committed lines added/deleted, peak pending-diff lines added/deleted |
| `ListMessages` | `api_read:messages` | Historical conversation content (id, session, task, turn, `author_type` (user/agent), `content`, `type`, `created_at`), filterable by session ids, task ids, a `created_at` range (`since`/`until`), and types. See "Conversation content" below. |
| RPC | Capability | Returns |
| ----------------------- | ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ListTasks` / `GetTask` | `api_read:tasks` | Tasks (id, workspace, workflow, title, description, state, priority, timestamps, parent, identifier, repositories, metadata) |
| `ListWorkspaces` | `api_read:workspaces` | Workspaces (id, name, owner, defaults, timestamps) |
| `ListWorkflows` | `api_read:workflows` | Workflows for a workspace |
| `ListWorkflowSteps` | `api_read:workflows` | Steps for a workflow (id, name, position, stage type) |
| `ListAgentProfiles` | `api_read:agent_profiles` | Agent profiles (id, agent id, display name, model, mode) |
| `ListExecutorProfiles` | `api_read:executor_profiles` | Executor profiles (id, display name, executor type) |
| `ListRepositories` | `api_read:repositories` | Repositories for a workspace (id, name, default branch) |
| `ListSessions` | `api_read:sessions` | Session identity + agent context (id, task, agent profile, resolved display name + model, `acp_session_id`, state, timestamps) |
| `ListSessionCodeStats` | `api_read:sessions` | **Computed** per-session code metrics: committed lines added/deleted, peak pending-diff lines added/deleted |
| `ListMessages` | `api_read:messages` | Historical conversation content (id, session, task, turn, `author_type` (user/agent), `content`, `type`, `created_at`), filterable by session ids, task ids, a `created_at` range (`since`/`until`), and types. See "Conversation content" below. |
`acp_session_id` on a session is the external usage-attribution join key (e.g.
`tokscale`): kandev exposes the session identity and code stats but stays out of
@@ -478,7 +557,7 @@ missing task returns gRPC `NotFound`.
`Host.Messages().Send` (capability `api_write:messages`) delivers a prompt to a
task session through the orchestrator's real delivery path — the same one
`message_task` uses — so the message reaches the agent and drives a turn (it is
*not* an office comment). It resolves the target session (an explicit
_not_ an office comment). It resolves the target session (an explicit
`session_id`, verified to belong to the task, or the task's primary session),
records a user message stamped with the plugin source, and dispatches by session
state: a running session queues the prompt (`status: queued`); an idle/completed
@@ -533,7 +612,7 @@ refreshes the list) reconciles the registry with whatever is actually on disk:
registered and the others are reported as skipped, not registered.
2. **Dropped tarballs.** Every `*.tar.gz` file sitting directly in the plugins
directory is run through the same verified install pipeline `POST
/api/plugins/install` uses (checksum verification, manifest validation, platform
/api/plugins/install` uses (checksum verification, manifest validation, platform
executable check, extraction, spawn, activate). On success the tarball file is
deleted. On a validation failure the file is left in place (not retried
automatically) and the failure is reported.
@@ -572,17 +651,28 @@ Mattermost-webapp model), not iframes. The full contract lives in
involved in serving these assets — the plugin subprocess only needs to be running
to serve gRPC calls, not the UI bundle.
- **Boot payload:** the SPA boot payload carries
`plugins: [{ id, name, bundleUrl, styleUrls }]` for every **active** plugin that
declares a bundle (gated on the `plugins` feature flag).
`plugins: [{ id, name, bundleUrl, styleUrls, repositoryProviderIds? }]` for every
**active** plugin that declares a bundle (gated on the `plugins` feature flag).
`repositoryProviderIds` is the JSON projection of manifest
`repository_providers`; before `initialize`, the loader supplies it to the registry
as the plugin's provider/review ownership allowlist. Omission keeps older payloads
compatible but grants no invented manifest declaration.
- **Loading:** on boot (and on runtime enable), the frontend host dynamically
`import()`s each `bundleUrl`. The bundle calls
`window.registerKandevPlugin(id, { initialize(registry, host), destroy? })`.
`host` shares the kandev React instance, the app store, a plugin-scoped
`api.fetch`, a curated `@kandev/ui` subset, and the theme — so a plugin can build
a page indistinguishable from first-party UI (e.g. a native `/jira` page).
Activation is transactional: failure or timeout revokes every partial registration,
aborts owned work, and fences callbacks that arrive after the attempt ended.
- **Registry surface:** `registerRoute(path, C)`, `registerNavItem(item)`,
`registerSettingsRoute(path, C)`, `registerComponent(slot, C)` (including
`app-status-bar-left` and `app-status-bar-right`), `registerWsHandler(action, fn)`.
`registerSettingsRoute(path, C)`,
`registerIntegrationSettings({ id, label, description, icon?, Component })`,
`registerComponent(slot, C)` (including `app-status-bar-left` and
`app-status-bar-right`), and `registerWsHandler(action, fn)`. Integration-settings
contributions appear in the native global integrations index, workspace settings
navigation, and global/workspace settings routes. IDs are URL-safe, unique among
active plugins, and cannot shadow host integrations; unload revokes the contribution.
Status-slot components receive the exact `AppStatusBarSlotProps` contract in
`PLUGIN-API.md`: current path/context plus placement and presentation. The host
renders one responsive presentation at once — 24 px bar on tablet/desktop or
@@ -602,16 +692,45 @@ Mattermost-webapp model), not iframes. The full contract lives in
it globally, skipping editable targets the same way core app shortcuts do. User
overrides are namespaced `plugin:{pluginId}:{id}` so they survive independently
per plugin.
- **Modals:** `host.openModal({ title?, content, size?, dismissible? })` imperatively
opens a modal rendered by the host's `<PluginModalHost/>` (mounted once at the app
root, isolated behind its own error boundary) and returns `{ close() }` to close
- **Modals and drawers:** `host.openModal({ title?, description?, content, size?, dismissible?, presentation? })` imperatively
opens a modal rendered by the host's `<PluginModalHost/>` (mounted once inside the
authenticated `AppShell` theme/tooltip/toast provider tree and isolated behind its
own error boundary) and returns `{ close() }` to close
that instance. `content` reuses the slot-component contract (rendered with the
host React instance). Independent of keybindings — any plugin code path may call
it, including a keybinding handler.
host React instance). `presentation: "drawer"` renders the contribution in a
safe-area-aware host drawer for phone actions; omitted/`dialog` keeps desktop modal
presentation. Independent of keybindings — any plugin code path may call it.
- **Task change-request links:** `host.openTaskLinkDialog(...)` renders the same
one-field dialog anatomy, inline validation, Cancel/Save footer, submitting state,
success toast, and close behavior as Kandev's GitHub task-link flow. Code-host
plugins supply provider copy and an authenticated
`onSubmit(reference, signal)` callback; closing, unmounting, or revoking the plugin
aborts that signal and suppresses late feedback;
they do not build this workflow inside `openModal`. Link submenu children name only
the target because the parent already supplies the verb.
- **Provider registrations:** `registry.registerRepositoryProvider(...)` contributes
repository listing, optional coarse URL matching, structured URL inspection, and
branch listing. `matchesURL` is only a synchronous performance hint; workspace-scoped
`inspectURL` is authoritative, returns `null` when the configured provider does not
own the URL, and must produce exactly one winner across active providers. `inspectURL` returns
a complete credential-free provider/repository/pull-request descriptor with an HTTPS
clone URL. The host
persists that descriptor rather than parsing plugin URLs. Once persisted, native task
branch requests are routed to the active manifest owner through its declared
workspace-scoped `repositories.branches` action using only that stored descriptor.
`registerTaskAction(...)`
contributes children of the native **Link** submenu with visibility and a read-only
task/workspace/repository context. Unsupported top-level action placements are
rejected at compile/registration time rather than accepted without a consumer.
`registerReviewProvider(...)` supplies
normalized review summaries, an external-store task-item source, and a plugin
`ReviewPanel` rendered in native desktop/mobile review surfaces. All are
manifest-owned, lifecycle-revocable registrations; duplicate active provider
ownership is rejected.
- **Task panels:** `registerTaskPanel({ id, title, icon?, Component, mobileEnabled? })`
adds a row to the task workspace's "+" (add panel) menu; selecting it opens a
dockview panel rendering `Component` with `{ panelId, taskId, sessionId,
presentation }`. Every plugin panel shares one generic `"plugin-panel"` dockview
presentation }`. Every plugin panel shares one generic `"plugin-panel"` dockview
component (identity in `params.pluginId`/`params.panelKey`), so a saved layout
round-trips even when the owning plugin is later uninstalled — the layout manager
drops an unresolvable reference instead of throwing, and `Settings > Layouts`
@@ -628,12 +747,12 @@ Mattermost-webapp model), not iframes. The full contract lives in
the layout. Decision:
ADR-2026-08-04-plugin-contribution-lifecycle-authority.
- **Kanban card contributions:** `registerTaskMenuAction({ id, label, icon?,
group: "edit", visible?, run })` adds an item to the kanban card's `Edit`
group: "edit", visible?, run })` adds an item to the kanban card's `Edit`
submenu (the flat `Edit` item becomes `Edit > Edit task` once any plugin
registers one); `run(context)` receives `{ workspaceId, taskId, taskTitle,
workflowStepId, presentation }`, and a rejected `run` is caught and logged
workflowStepId, presentation }`, and a rejected `run` is caught and logged
without blocking the menu from closing. `registerComponent("task-card-indicators",
C)` renders `C` beside the PR status icon on every kanban card, receiving
C)` renders `C` beside the PR status icon on every kanban card, receiving
`{ taskId, workspaceId, workflowStepId }` as `slotProps`.
`registerComponent("task-card-tags", C)` renders `C` in its own row on every
kanban card (below the badges row), receiving the same
@@ -661,13 +780,13 @@ error --successful Enable/health recovery--> active
error --Disable--> disabled
```
| State | Meaning |
|---|---|
| `registered` | Package extracted and record written; go-plugin spawn/handshake pending or in flight |
| `active` | Handshake succeeded and health (`Ping`) passes; events delivered, webhooks proxied |
| `error` | 3 consecutive `Ping` failures (30s interval, injectable), or the subprocess crashed and restart attempts (backoff, max 5) are exhausted. Events buffered (ring buffer, 100 events, 5-minute TTL). Webhooks return 503 |
| `disabled` | Operator explicitly disabled. Subprocess stopped. No events, no webhooks. State and config preserved |
| `uninstalled` | Subprocess stopped, package/record/state deleted (no grace period in v1) |
| State | Meaning |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registered` | Package extracted and record written; go-plugin spawn/handshake pending or in flight |
| `active` | Handshake succeeded and health (`Ping`) passes; events delivered, webhooks proxied |
| `error` | 3 consecutive `Ping` failures (30s interval, injectable), or the subprocess crashed and restart attempts (backoff, max 5) are exhausted. Events buffered (ring buffer, 100 events, 5-minute TTL). Webhooks return 503 |
| `disabled` | Operator explicitly disabled. Subprocess stopped. No events, no webhooks. State and config preserved |
| `uninstalled` | Subprocess stopped, package/record/state deleted (no grace period in v1) |
Health monitoring: kandev's go-plugin client calls `Ping()` on the plugin every 30
seconds (injectable). 3 consecutive failures -> `error` + inbox item + restart attempt
@@ -737,6 +856,13 @@ complete.
- **External webhook hits a disabled/error plugin**: kandev returns 503.
- **Undeclared capability access attempt on a Host RPC**: gRPC `PermissionDenied` with
a message naming the missing capability.
- **Undeclared, unauthorized, oversized, or timed-out browser action**: Kandev rejects
it before/at bounded plugin dispatch; it never falls back to public webhook routing.
- **Disabled/unloaded repository or review provider**: registrations and in-flight work
are revoked; provider credential leases are invalidated immediately, and host
selectors/panels remove stale plugin items safely, including after same-ID reload.
- **Reference source denied during message submission**: Kandev rejects the selected
reference rather than queuing stale or cross-workspace metadata.
- **Checksum mismatch or unresolvable host-platform executable at install time**:
install is rejected before any code runs.
- **Frontend bundle import or initialization remains in flight**: open and saved
@@ -901,6 +1027,37 @@ complete.
a failed delivery leaves no durable user message and a retry can't duplicate
the prompt.
- **GIVEN** an active plugin declares `connection.save` with workspace scope,
**WHEN** a signed-in user invokes `host.api.invokeAction("connection.save", ...)`,
**THEN** Kandev authenticates the caller, authorizes the workspace, bounds the
payload, and passes verified context separately to `Plugin.HandleAction`; the public
webhook endpoint is not invoked.
- **GIVEN** a provider operation owns an `AbortSignal`, **WHEN** its registration is
replaced, unloaded, or its request is superseded, **THEN** `invokeAction` propagates
cancellation to the authenticated HTTP request and backend action context.
- **GIVEN** a manifest-owned repository and review provider, **WHEN** it registers
native task-link actions and a review panel, **THEN** Kandev renders those contributions
in applicable desktop and mobile task/review surfaces and removes them, including
in-flight work, when the plugin disables.
- **GIVEN** a registered review provider publishes normalized task status, **WHEN** a
linked task renders on desktop or mobile, **THEN** Kandev automatically mounts the
same topbar control, composer CI chip, hover popover/mobile drawer, review summary,
comment summary, and checks anatomy used by GitHub, refreshes through the provider
lifecycle, and requires no provider-owned visual slot or second poller.
- **GIVEN** a compatible code-host review provider, **WHEN** its panel renders normalized
detail through `host.ui.ChangeRequestDetail`, **THEN** GitHub and the provider share
the same header, collapsible sections, add-to-context controls, scroll ownership,
loading/error treatment, and desktop/mobile geometry; only data, capabilities, and
callbacks remain provider-owned.
- **GIVEN** a plugin-owned `#` reference source returns a pull-request candidate,
**WHEN** the user submits the selected reference, **THEN** Kandev authorizes it
again against the live plugin and rejects a disabled, stale, tampered, or
cross-workspace candidate before queueing message metadata.
- **GIVEN** a saved or open plugin task panel and a plugin reload whose import or
`initialize()` takes longer than 500 milliseconds, **WHEN** registration eventually
succeeds with the same panel identity, **THEN** the panel remains in the layout and
@@ -953,10 +1110,10 @@ complete.
in the kandev origin with full app-store access. Isolating plugin JS in a worker,
realm, or comparable sandbox is future work; v1 relies on only loading active,
operator-installed plugins served same-origin.
- **In-process backend plugins.** Plugin *backends* remain out-of-process — no Go
- **In-process backend plugins.** Plugin _backends_ remain out-of-process — no Go
plugin loading via `plugin.Open`, no WASM, no shared-memory communication. (This is
distinct from the frontend bundle, which does load into the SPA.)
- **Plugin marketplace or registry.** Out of scope *for this spec*: this spec covers
- **Plugin marketplace or registry.** Out of scope _for this spec_: this spec covers
install-by-URL/upload as a manual, single-plugin action. The discoverable, curated
catalog (central registry, one-click install, star ranking, third-party sources) is
a sibling feature specified in [marketplace.md](marketplace.md) and built on top of
+4 -4
View File
@@ -45,9 +45,10 @@ Decision: [ADR-2026-08-11-composer-access-authenticated-webhooks](../../decision
authenticated webhook with a limit of at least 10 MiB.
- The Voice plugin's OpenAI key belongs to its existing plugin settings and secret storage. Kandev
relays the request but does not own, expose, or select that key.
- Plugin localization is a separately scoped prerequisite. This package adds no host i18n API. The
later Voice plugin task must decide how plugin-owned catalogs follow Kandev's locale before core
Voice Mode is removed.
- Plugin-owned copy uses the scoped catalog and reactive locale API established by
[ADR-2026-08-12-plugin-localization-contract](../../decisions/2026-08-12-plugin-localization-contract.md).
The later Voice plugin registers its English fallback and supported-locale catalogs before any
composer contribution.
- Disabling, uninstalling, or reloading a plugin aborts its in-flight webhook requests, unregisters
its composer actions, and leaves native drafts intact.
- The current core Voice Mode stays present until a separately delivered Voice plugin proves parity
@@ -200,7 +201,6 @@ current external-call behavior. Request cancellation propagates through the exis
- General authenticated REST routing, response streaming, bidirectional browser sockets, or changing
the default limit for existing public webhooks.
- Sandboxing mutually malicious native UI plugin bundles.
- Plugin localization; it is a separate prerequisite for the later Voice plugin extraction.
## Implementation Plan