feat(plugins): expand task fields for integrations
This commit is contained in:
@@ -9,13 +9,13 @@ status: implemented
|
||||
|
||||
## Overview
|
||||
|
||||
Give plugins a typed, capability-gated path to read (phase 1) kandev domain data
|
||||
Give plugins a typed, capability-gated path to read and write kandev domain data
|
||||
over the existing `kandev.plugin.v1` Host gRPC channel, replacing direct SQLite
|
||||
access. Land the contract first (proto + regen) and the one net-new aggregation
|
||||
(per-session LOC), then the SDK's Go-native accessors, then kandev's server-side
|
||||
implementation, and finally the proof (rewrite the agent-stats plugin) plus tests
|
||||
and docs. Write RPCs (`CreateTask`/`UpdateTask`/`CreateComment`) are specified in
|
||||
the proto but deferred; handlers return `Unimplemented` this phase.
|
||||
and docs. The implemented write surface is `CreateTask`, `UpdateTask`, and
|
||||
`SendMessage`; workflow transitions use `MoveTask`.
|
||||
|
||||
The draft contract at `docs/plans/plugins/HOST-DATA-API.proto` is largely settled
|
||||
— refine field-level details against the real DTOs (`apps/backend/pkg/api/v1/`),
|
||||
@@ -26,7 +26,7 @@ do not redesign.
|
||||
## Backend
|
||||
|
||||
### Proto contract (`apps/backend/proto/kandev/plugin/v1/plugin.proto`)
|
||||
Fold the read + (deferred) write RPCs and DTOs from
|
||||
Fold the read and write RPCs and DTOs from
|
||||
`docs/plans/plugins/HOST-DATA-API.proto` into the frozen plugin proto. Decide
|
||||
placement: add the RPCs to the existing `service Host` (simplest — reuses the
|
||||
single Host broker connection and the existing capability interceptor) rather
|
||||
@@ -60,8 +60,9 @@ new Host data interface methods. Each read handler:
|
||||
the new aggregation for code stats) — never a repository directly;
|
||||
3. maps internal models → the Go-native DTOs with explicit code.
|
||||
Wire the new service dependencies into `plugins.Service` /
|
||||
`plugins.NewService` / `Provide`, and thread them into `hostForPlugin`. Write
|
||||
handlers return `codes.Unimplemented`.
|
||||
`plugins.NewService` / `Provide`, and thread them into `hostForPlugin`. The
|
||||
implemented writes route through the task service and orchestrator delivery
|
||||
path.
|
||||
|
||||
---
|
||||
|
||||
@@ -93,8 +94,8 @@ Extend the Go-native Host surface authors and kandev share:
|
||||
DTO for each resource, including nullable/optional and timestamp formatting.
|
||||
- **Capability gating (`internal/plugins/host_test.go`):** each read RPC returns
|
||||
`PermissionDenied` with `capability 'api_read:<resource>' not declared` when the
|
||||
manifest omits the resource, and succeeds when it declares it. Write RPC returns
|
||||
`Unimplemented`.
|
||||
manifest omits the resource, and succeeds when it declares it. Write RPCs
|
||||
enforce their `api_write` capabilities and return their task/message results.
|
||||
- **Per-session LOC aggregation (`internal/analytics/repository/sqlite/*_test.go`):**
|
||||
real SQLite fixture with commits + snapshots; assert committed sums and the
|
||||
peak-pending `MAX` semantics (peak, not latest; not double-counted).
|
||||
|
||||
@@ -19,8 +19,7 @@ later task compiles against.
|
||||
- Read RPCs: `ListTasks`, `GetTask`, `ListWorkspaces`, `ListWorkflows`,
|
||||
`ListWorkflowSteps`, `ListAgentProfiles`, `ListRepositories`, `ListSessions`,
|
||||
`ListSessionCodeStats`.
|
||||
- Deferred write RPCs (declared in proto, not implemented later this phase):
|
||||
`CreateTask`, `UpdateTask`, `CreateComment`.
|
||||
- Implemented write RPCs: `CreateTask`, `UpdateTask`, and `SendMessage`.
|
||||
- DTOs + `Page`/`PageInfo`/filter messages from the draft.
|
||||
- Decide placement: add RPCs to the existing `service Host` (recommended — reuses
|
||||
the single broker connection and the capability interceptor) rather than a new
|
||||
@@ -30,7 +29,7 @@ later task compiles against.
|
||||
string timestamps and `optional` nullables per ADR 0043.
|
||||
|
||||
## Acceptance
|
||||
- `apps/backend/proto/kandev/plugin/v1/plugin.proto` contains the read + deferred
|
||||
- `apps/backend/proto/kandev/plugin/v1/plugin.proto` contains the read + write
|
||||
write RPCs and DTOs; existing `Host`/`Plugin` RPCs are unchanged.
|
||||
- `make -C apps/backend proto` regenerates `plugin.pb.go` / `plugin_grpc.pb.go`
|
||||
with no manual edits, and the tree builds.
|
||||
|
||||
@@ -25,8 +25,9 @@ state/secrets pattern in `host.go`/`types.go`.
|
||||
`host.Sessions()`, `host.Workspaces()`, `host.Workflows()`,
|
||||
`host.AgentProfiles()`, `host.Repositories()` — each returning a small typed
|
||||
accessor (e.g. `TasksAPI.List(ctx, filter, page)`, `TasksAPI.Get(ctx, id)`,
|
||||
`SessionsAPI.List(...)`, `SessionsAPI.CodeStats(...)`). Keep write methods off
|
||||
the surface this phase (deferred).
|
||||
`SessionsAPI.List(...)`, `SessionsAPI.CodeStats(...)`). The task and message
|
||||
accessors also expose the implemented write methods, including
|
||||
`Tasks().Create`, `Tasks().Update`, `Tasks().Move`, and `Messages().Send`.
|
||||
- **Client + server conversions**: `grpcHostClient` (plugin side) calls the
|
||||
generated data RPCs and converts responses to Go-native; `grpcHostServer`
|
||||
(kandev side) dispatches to the Go-native interface. Follow the existing
|
||||
|
||||
@@ -32,7 +32,8 @@ gating, and wire the new service dependencies through `plugins.Service`.
|
||||
- Apply the v1 scoping rule: global reads, filters narrow results, ephemeral
|
||||
tasks excluded unless requested. Leave a single scoping hook per ADR 0043(a).
|
||||
- Implement opaque-cursor pagination (server-defined cursor encoding + max cap).
|
||||
- Write RPC handlers return `codes.Unimplemented`.
|
||||
- Implemented task and message writes route through the task service and
|
||||
orchestrator delivery path.
|
||||
- **Wiring:** add the new service deps to `plugins.Service`, `plugins.NewService`,
|
||||
and `Provide`; thread them into `hostForPlugin` so each spawned `pluginHost`
|
||||
can serve data RPCs. Confirm the new RPCs are served over the existing Host
|
||||
@@ -43,7 +44,7 @@ gating, and wire the new service dependencies through `plugins.Service`.
|
||||
`ListSessionCodeStats` results via the Host channel; one without it gets
|
||||
`PermissionDenied` naming `api_read:sessions`.
|
||||
- All read RPCs map internal models to DTOs with no proto/domain-struct leakage;
|
||||
write RPCs return `Unimplemented`.
|
||||
write RPCs enforce capabilities and return their task/message results.
|
||||
- `make -C apps/backend proto` not required here (done in task-01); package builds
|
||||
and tests pass.
|
||||
|
||||
|
||||
@@ -19,7 +19,7 @@ the host RPC behavior and the end-to-end plugin path.)
|
||||
- **Capability gating (`internal/plugins/host_test.go`):** for each read RPC,
|
||||
assert `PermissionDenied` with `capability 'api_read:<resource>' not declared`
|
||||
when the manifest omits the resource, and success when it declares it. Assert
|
||||
write RPCs return `Unimplemented`.
|
||||
write RPCs enforce their capabilities and return their task/message results.
|
||||
- **DTO mapping:** table-driven internal-model → DTO assertions per resource,
|
||||
covering optional/NULL fields and RFC3339 timestamp formatting; assert the
|
||||
Session DTO carries `acp_session_id`.
|
||||
|
||||
@@ -18,7 +18,8 @@ Document the Host data API for plugin authors: which resources are readable, the
|
||||
- **Wire reference (`docs/plans/plugins/GRPC-CONTRACT.md`):** add the Host data
|
||||
RPCs to the `service Host` block (§3) and note capability gating uses
|
||||
`api_read:<resource>` / `api_write:<resource>` (§5), replacing the "reserved"
|
||||
language. Note write RPCs are deferred (`Unimplemented`).
|
||||
language. Document the implemented task and message writes, including the
|
||||
`UpdateTask` field mask and `MoveTask` workflow-transition path.
|
||||
- **SDK reference (`docs/plans/plugins/GRPC-CONTRACT.md` §4 and/or
|
||||
`PLUGIN-API.md`):** document the author accessors (`host.Tasks().List(...)`,
|
||||
`host.Sessions().List(...)`, `host.Sessions().CodeStats(...)`, etc.) and that
|
||||
@@ -36,9 +37,9 @@ Document the Host data API for plugin authors: which resources are readable, the
|
||||
## Acceptance
|
||||
- `GRPC-CONTRACT.md` lists the Host data RPCs and the per-resource capability
|
||||
gating; the "reserved / not implemented" wording for `api_read`/`api_write` is
|
||||
removed or scoped to the deferred write RPCs.
|
||||
- The manifest capability vocabulary is documented with the readable-resource
|
||||
list and an example.
|
||||
removed or scoped to capabilities that are not yet implemented.
|
||||
- The manifest capability vocabulary is documented with the readable and
|
||||
writable-resource list and an example.
|
||||
|
||||
## Verification
|
||||
- Markdown-only; no build. `cd apps && pnpm --filter @kandev/web lint` only if a
|
||||
@@ -65,9 +66,9 @@ Summary, files changed, and status update here + in `plan.md`.
|
||||
reference and reconciled the spec section against the shipped code.
|
||||
|
||||
**Files changed:**
|
||||
- `docs/plans/plugins/GRPC-CONTRACT.md` — added the 9 read RPCs + 3 deferred
|
||||
write RPCs to the `service Host` block (§3); added a new "§3a. Host data API
|
||||
(ADR 0043)" subsection covering the resource/capability table, deferred
|
||||
- `docs/plans/plugins/GRPC-CONTRACT.md` — added the Host data read and
|
||||
implemented write RPCs to the `service Host` block (§3); added a new "§3a.
|
||||
Host data API (ADR 0043)" subsection covering the resource/capability table,
|
||||
writes, service-layer/DTO conventions, pagination/timestamp/nullable/scoping
|
||||
conventions; added the `Host` interface's 6 data accessors plus the 6 reader
|
||||
interfaces (`TaskReader`, `SessionReader`, `WorkspaceReader`,
|
||||
@@ -75,7 +76,7 @@ reference and reconciled the spec section against the shipped code.
|
||||
signatures, and an authoring example (manifest snippet + `Sessions().CodeStats`
|
||||
call) to §4; rewrote the §5 "Capability gating" bullet to remove the stale
|
||||
"api_read/api_write reserved" wording and describe the real per-RPC gating
|
||||
plus the write RPCs' current `Unimplemented` behavior.
|
||||
plus the write RPCs' current behavior.
|
||||
- `docs/specs/plugins/requirements/plugins.md` — fixed capability-vocabulary drift against code
|
||||
(see below) and added a "Declaring data access" note under the manifest
|
||||
capabilities section; reworded the interceptor description to match the
|
||||
@@ -97,8 +98,8 @@ truth, left unchanged):**
|
||||
- The spec described `api_read`/`api_write` as "reserved for future Host RPCs"
|
||||
in the manifest example comments and said the capability-gating interceptor
|
||||
covers "state, secrets; api_read/api_write reserved" — both predate this
|
||||
ADR shipping; `api_read` is live now (write RPCs remain deferred/
|
||||
`Unimplemented`). Reworded both.
|
||||
ADR shipping; `api_read` and the implemented write capabilities are live now.
|
||||
Reworded both.
|
||||
- The spec attributed capability gating to "a unary server interceptor on
|
||||
Host"; there is no `grpc.UnaryServerInterceptor` in `internal/plugins` or
|
||||
`pkg/pluginsdk` — each Host/Host-data method checks its own capability
|
||||
|
||||
Reference in New Issue
Block a user