feat(plugins): typed capability-gated Host data API (ADR 0043) (#1753)
* docs(plugins): draft Host data API proto (read + write DTOs) Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(plugins): ADR + spec + plan for the Host data API Plugins access kandev data via capability-gated Host gRPC RPCs returning hand-mapped DTOs, never the DB directly. ADR 0042. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(plugins): add Host data API RPCs and DTOs to plugin proto Extends the existing service Host (per ADR 0042) with read RPCs (ListTasks/GetTask, ListWorkspaces, ListWorkflows, ListWorkflowSteps, ListAgentProfiles, ListRepositories, ListSessions, ListSessionCodeStats) and declares the deferred phase-2 write RPCs (CreateTask, UpdateTask, CreateComment) so the contract is stable for later tasks. Regenerates plugin.pb.go/plugin_grpc.pb.go via `make -C apps/backend proto`. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> * feat(plugins): Host data API SDK accessors + session LOC aggregation Wave 1-2 of ADR 0042: pkg/pluginsdk gains typed reader accessors (host.Tasks(), host.Sessions().CodeStats(), host.Workflows(), ...) over the extended Host gRPC service, with proto<->native DTO conversions and an UnimplementedHostData seam for the kandev-side impl. internal/analytics gains the per-session LOC aggregation those readers surface. Backend handlers + capability gating land in the next wave. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(plugins): capability-gated Host data read handlers (ADR 0042) Implement pluginHost Tasks/Sessions/Workspaces/Workflows/AgentProfiles/ Repositories readers: each gated on api_read:<resource> (PermissionDenied otherwise), backed by the service layer via narrow injected interfaces, and hand-mapped to the pluginsdk DTOs. Sessions().CodeStats routes through the analytics aggregation; acp_session_id preserves the metadata->resume_token fallback. Wired through plugins.Service.SetDataSources + backendapp. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * test(plugins): wire test for Host data reads + docs (ADR 0042 accepted) End-to-end test over the real go-plugin transport: session data round-trips, per-resource api_read gating returns PermissionDenied over the wire, cursor pagination. Document the Host data API + SDK accessors in GRPC-CONTRACT.md, reconcile the spec to shipped code, mark ADR 0042 accepted. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * feat(plugins): full session history + snapshot profile name in data API Sessions().List now fetches tasks with includeArchived=true — an archived task's sessions are still real sessions, and CodeStats already made the same call at the SQL layer, so the two session reads were inconsistent (26 of 359 sessions visible on a real instance). Tasks().List keeps archived tasks excluded. Session gains agent_profile_name (proto field 10) sourced from the profile snapshot, so sessions of since-uninstalled agents keep a human label — the AgentProfiles registry only lists live agents. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(plugins): renumber Host data API ADR 0042 -> 0043 main merged its own ADR 0042 (project shell output); renumber this one to the next free slot and update all references. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * fix(plugins): address Host data API review (perf, pagination, filters, proto) - paginate before DTO conversion so per-session ACP lookups run <=limit times - fetch all source pages (no silent 1000/workspace truncation); accurate HasMore - stable id tiebreaker on paginated sorts - AND SessionFilter.TaskIDs with WorkspaceIDs; exclude config-mode sessions from CodeStats (shared dialect.ExcludeConfigModePredicate) so List/CodeStats match - Get returns codes.NotFound consistently in-process and over the wire - wrap bare-DTO RPC responses (GetTaskResponse etc.) for Buf response uniqueness Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * docs(plugins): mark Host data API plan tasks done --------- Co-authored-by: Kandev Agent <agent@kandev.dev> Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,154 @@
|
||||
---
|
||||
spec: docs/specs/plugins/spec.md
|
||||
adr: docs/decisions/0043-plugin-host-data-api.md
|
||||
created: 2026-07-17
|
||||
status: implemented
|
||||
---
|
||||
|
||||
# Implementation Plan: Plugin Host data API
|
||||
|
||||
## Overview
|
||||
|
||||
Give plugins a typed, capability-gated path to read (phase 1) 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.
|
||||
|
||||
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/`),
|
||||
do not redesign.
|
||||
|
||||
---
|
||||
|
||||
## Backend
|
||||
|
||||
### Proto contract (`apps/backend/proto/kandev/plugin/v1/plugin.proto`)
|
||||
Fold the read + (deferred) 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
|
||||
than a separate `service HostData`, unless a separate service is needed to keep
|
||||
the interceptor's per-RPC capability lookup clean. Regenerate stubs with
|
||||
`make -C apps/backend proto`. Read RPCs: `ListTasks`, `GetTask`, `ListWorkspaces`,
|
||||
`ListWorkflows`, `ListWorkflowSteps`, `ListAgentProfiles`, `ListRepositories`,
|
||||
`ListSessions`, `ListSessionCodeStats`. DTOs mirror
|
||||
`apps/backend/pkg/api/v1/{task,workflow,agent,workspace}.go` field-for-field with
|
||||
RFC3339 string timestamps and `optional` nullables.
|
||||
|
||||
### Per-session LOC aggregation (`internal/analytics/repository/sqlite/`)
|
||||
No existing method computes per-session committed + peak-pending LOC.
|
||||
`internal/analytics/repository/sqlite/stats.go` aggregates git stats at workspace
|
||||
and per-repository granularity only. Add a read-only aggregation returning, per
|
||||
session id: `SUM(insertions)` / `SUM(deletions)` from `task_session_commits`, and
|
||||
the peak pending-diff (`MAX` over each snapshot's `SUM(json_each(files).additions
|
||||
/ .deletions)`) from `task_session_git_snapshots`. This mirrors the SQL the
|
||||
agent-stats plugin runs today (`stats.go:sessionsQuery`). Use the `dialect`
|
||||
helpers for SQLite/Postgres portability; filter by session-id set / workspace and
|
||||
support pagination bounds. Expose it through the analytics (or task) service so
|
||||
the Host handler calls a service method, not the repository.
|
||||
|
||||
### Host data RPC implementation (`internal/plugins/`)
|
||||
Extend `pluginHost` (or add a sibling under `internal/plugins/`) to implement the
|
||||
new Host data interface methods. Each read handler:
|
||||
1. checks `manifest.CanRead("<resource>")` — reuse the existing per-plugin
|
||||
binding and `permissionDenied("api_read:<resource>")` helper shape;
|
||||
2. calls the relevant service method (`taskSvc` for tasks/workspaces/repositories/
|
||||
sessions, workflow service for workflows/steps, agent settings for profiles,
|
||||
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`.
|
||||
|
||||
---
|
||||
|
||||
## Frontend
|
||||
|
||||
None. This feature has no SPA surface; it is a plugin-facing gRPC contract.
|
||||
|
||||
---
|
||||
|
||||
## SDK (`apps/backend/pkg/pluginsdk/`)
|
||||
|
||||
Extend the Go-native Host surface authors and kandev share:
|
||||
- Add Go-native DTO structs (`Task`, `Session`, `SessionCodeStats`, `Workspace`,
|
||||
`Workflow`, `WorkflowStep`, `AgentProfile`, `Repository`, page types) mirroring
|
||||
the proto, with `toProto`/`fromProto` helpers alongside the existing ones in
|
||||
`types.go`.
|
||||
- Add data methods to the `Host` interface (or a `HostData` sub-interface exposed
|
||||
via `host.Tasks()`, `host.Sessions()`, ...), with `grpcHostClient` (plugin-side)
|
||||
and `grpcHostServer` (kandev-side) conversions in `host.go`.
|
||||
- Author-facing ergonomics: typed accessors returning Go-native structs, e.g.
|
||||
`host.Tasks().List(ctx, filter, page)`, `host.Sessions().List(...)`,
|
||||
`host.Sessions().CodeStats(...)`.
|
||||
|
||||
---
|
||||
|
||||
## Tests
|
||||
|
||||
- **DTO mapping (`internal/plugins/*_test.go`):** table-driven — internal model →
|
||||
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`.
|
||||
- **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).
|
||||
- **SDK conversions (`pkg/pluginsdk/*_test.go`):** proto↔native round-trip for the
|
||||
new DTOs.
|
||||
- **Integration:** a plugin (via the SDK Host client over the broker) calls
|
||||
`ListSessions` + `ListSessionCodeStats` and gets rows without DB access — extend
|
||||
the existing `internal/plugins/host_test.go` / integration harness.
|
||||
|
||||
---
|
||||
|
||||
## E2E Tests
|
||||
|
||||
None. No user-visible UI surface. The integration test above covers the plugin↔host
|
||||
path.
|
||||
|
||||
---
|
||||
|
||||
## Implementation Waves
|
||||
|
||||
```
|
||||
Wave 1 (parallel):
|
||||
- [x] [task-01-proto-contract](task-01-proto-contract.md)
|
||||
- [x] [task-02-session-loc-aggregation](task-02-session-loc-aggregation.md)
|
||||
|
||||
Wave 2:
|
||||
- [x] [task-03-sdk-data-accessors](task-03-sdk-data-accessors.md)
|
||||
|
||||
Wave 3:
|
||||
- [x] [task-04-host-data-impl](task-04-host-data-impl.md)
|
||||
|
||||
Wave 4 (parallel):
|
||||
- [x] [task-05-rewrite-agent-stats-plugin](task-05-rewrite-agent-stats-plugin.md)
|
||||
- [x] [task-06-tests](task-06-tests.md)
|
||||
- [x] [task-07-docs](task-07-docs.md)
|
||||
```
|
||||
|
||||
Rationale: task-01 (contract) and task-02 (aggregation) touch disjoint packages
|
||||
and can run in parallel. The SDK (task-03) needs generated stubs from task-01. The
|
||||
kandev impl (task-04) needs the stubs (task-01), the aggregation (task-02), and
|
||||
the Go-native interface/DTOs (task-03). Wave 4 tasks touch disjoint trees (a
|
||||
separate plugin repo, backend tests, public docs) and parallelize.
|
||||
|
||||
---
|
||||
|
||||
## Open Questions
|
||||
|
||||
- **Proto placement:** RPCs on the existing `service Host` vs a new
|
||||
`service HostData` served on the same broker connection. Recommendation: extend
|
||||
`service Host` to reuse the existing capability interceptor and single broker
|
||||
wiring; revisit only if the interceptor's per-RPC capability mapping gets
|
||||
unwieldy. Settle in task-01.
|
||||
- **Aggregation home:** `internal/analytics` (where git stats already live) vs a
|
||||
new method on the task repository's `git_snapshots.go`. Recommendation:
|
||||
analytics repository, consistent with `GetGitStats`/`GetRepositoryStats`.
|
||||
Settle in task-02.
|
||||
</content>
|
||||
@@ -0,0 +1,60 @@
|
||||
---
|
||||
id: "01-proto-contract"
|
||||
title: "Host data proto contract + regenerated stubs"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../../specs/plugins/spec.md"
|
||||
adr: "../../../decisions/0043-plugin-host-data-api.md"
|
||||
---
|
||||
|
||||
# Task 01: Host data proto contract + regenerated stubs
|
||||
|
||||
Fold the Host data RPCs and DTOs from `docs/plans/plugins/HOST-DATA-API.proto`
|
||||
into the frozen plugin proto and regenerate Go stubs. This is the contract every
|
||||
later task compiles against.
|
||||
|
||||
## Scope
|
||||
- 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`.
|
||||
- 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
|
||||
`service HostData`. Record the choice in a proto comment.
|
||||
- Verify DTO fields against the real shapes in
|
||||
`apps/backend/pkg/api/v1/{task,workflow,agent,workspace}.go`; keep RFC3339
|
||||
string timestamps and `optional` nullables per ADR 0043.
|
||||
|
||||
## Acceptance
|
||||
- `apps/backend/proto/kandev/plugin/v1/plugin.proto` contains the read + deferred
|
||||
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.
|
||||
|
||||
## Verification
|
||||
- `make -C apps/backend proto`
|
||||
- `cd apps/backend && go build ./...`
|
||||
|
||||
## Files likely touched
|
||||
- `apps/backend/proto/kandev/plugin/v1/plugin.proto`
|
||||
- `apps/backend/proto/kandev/plugin/v1/plugin.pb.go` (generated)
|
||||
- `apps/backend/proto/kandev/plugin/v1/plugin_grpc.pb.go` (generated)
|
||||
|
||||
## Inputs
|
||||
- Spec: "Host data API" section, capability table.
|
||||
- Draft: `docs/plans/plugins/HOST-DATA-API.proto`.
|
||||
- DTO shapes: `apps/backend/pkg/api/v1/{task,workflow,agent,workspace}.go`.
|
||||
- ADR 0043 (DTO discipline, conventions).
|
||||
|
||||
## Dependencies
|
||||
None.
|
||||
|
||||
## Output contract
|
||||
Summary of RPC placement decision, files changed (incl. regenerated stubs),
|
||||
`make proto` + build result, any DTO field deviations from the draft, and status
|
||||
update here + in `plan.md`.
|
||||
</content>
|
||||
@@ -0,0 +1,66 @@
|
||||
---
|
||||
id: "02-session-loc-aggregation"
|
||||
title: "Per-session LOC aggregation (committed + peak-pending)"
|
||||
status: done
|
||||
wave: 1
|
||||
depends_on: []
|
||||
plan: "plan.md"
|
||||
spec: "../../../specs/plugins/spec.md"
|
||||
adr: "../../../decisions/0043-plugin-host-data-api.md"
|
||||
---
|
||||
|
||||
# Task 02: Per-session LOC aggregation (committed + peak-pending)
|
||||
|
||||
Add the one net-new read-only query the Host data API needs: per-session code
|
||||
stats. No existing method computes this. `internal/analytics/repository/sqlite/
|
||||
stats.go` aggregates git stats at workspace and per-repository granularity only,
|
||||
and the peak-pending snapshot aggregation exists nowhere in-tree.
|
||||
|
||||
## Scope
|
||||
Add a repository method (recommended home: `internal/analytics/repository/sqlite/`,
|
||||
alongside `GetGitStats`/`GetRepositoryStats`) returning, per session id:
|
||||
- `lines_added_committed` = `SUM(insertions)` over `task_session_commits`.
|
||||
- `lines_deleted_committed` = `SUM(deletions)`.
|
||||
- `lines_added_peak_pending` = `MAX` over each snapshot's
|
||||
`SUM(json_extract(json_each(files).value,'$.additions'))` from
|
||||
`task_session_git_snapshots` (peak, not latest — the latest is usually a clean
|
||||
tree).
|
||||
- `lines_deleted_peak_pending` = the deletions equivalent.
|
||||
|
||||
Mirror the SQL in the agent-stats plugin
|
||||
(`/home/jcfs/.kandev/tasks/tokens-per-task-loc_9tk/kandev-plugin-agent-stats/server/stats.go`,
|
||||
`sessionsQuery`). Use `internal/db/dialect` helpers (`JSONExtract`, etc.) so the
|
||||
query is portable to Postgres. Support filtering by a session-id set and/or
|
||||
workspace, plus a limit/offset (or cursor bound) for pagination. Expose it via a
|
||||
service method so the Host handler (task-04) calls the service, not the repository.
|
||||
|
||||
## Acceptance
|
||||
- New repository + service method returns per-session committed sums and the
|
||||
peak-pending `MAX` semantics, filterable by session ids / workspace.
|
||||
- Peak-pending uses the peak snapshot, not the latest, and does not double-count
|
||||
committed work (matches `effectiveLines` intent in the source plugin).
|
||||
- Table-driven SQLite test with commits + multiple snapshots asserts both.
|
||||
|
||||
## Verification
|
||||
- `cd apps/backend && go test ./internal/analytics/...`
|
||||
|
||||
## Files likely touched
|
||||
- `apps/backend/internal/analytics/repository/sqlite/stats.go`
|
||||
- `apps/backend/internal/analytics/models/` (new `SessionCodeStats` model)
|
||||
- analytics service file exposing the method
|
||||
- `apps/backend/internal/analytics/repository/sqlite/*_test.go`
|
||||
|
||||
## Inputs
|
||||
- Source SQL: agent-stats `server/stats.go` `sessionsQuery` (committed sums +
|
||||
snapshot peak).
|
||||
- Patterns: `GetGitStats` / `buildRepositoryStatsQuery` in
|
||||
`internal/analytics/repository/sqlite/stats.go`; `dialect` helpers.
|
||||
- Spec: "Host data API" → `ListSessionCodeStats` row.
|
||||
|
||||
## Dependencies
|
||||
None. Independent of the proto task (pure Go/SQL).
|
||||
|
||||
## Output contract
|
||||
Summary, method signatures added, chosen home (analytics vs task repo), test
|
||||
result, portability notes (SQLite/Postgres), and status update here + in `plan.md`.
|
||||
</content>
|
||||
@@ -0,0 +1,65 @@
|
||||
---
|
||||
id: "03-sdk-data-accessors"
|
||||
title: "SDK Go-native data DTOs, Host interface, and author accessors"
|
||||
status: done
|
||||
wave: 2
|
||||
depends_on: ["01-proto-contract"]
|
||||
plan: "plan.md"
|
||||
spec: "../../../specs/plugins/spec.md"
|
||||
adr: "../../../decisions/0043-plugin-host-data-api.md"
|
||||
---
|
||||
|
||||
# Task 03: SDK Go-native data DTOs, Host interface, and author accessors
|
||||
|
||||
Extend `pkg/pluginsdk` so authors read kandev data through Go-native typed structs
|
||||
— proto types never leak past the package boundary, matching the existing
|
||||
state/secrets pattern in `host.go`/`types.go`.
|
||||
|
||||
## Scope
|
||||
- **Go-native DTOs** in `types.go` mirroring the proto: `Task`, `TaskRepository`,
|
||||
`Session`, `SessionCodeStats`, `Workspace`, `Workflow`, `WorkflowStep`,
|
||||
`AgentProfile`, `Repository`, plus `Page`/`PageInfo`/filter structs, each with
|
||||
`toProto`/`fromProto` helpers alongside the existing ones.
|
||||
- **Host interface extension** (`host.go`): add data read methods. Prefer grouping
|
||||
behind sub-accessors exposed from the `Host` interface — `host.Tasks()`,
|
||||
`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).
|
||||
- **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
|
||||
`GetState`/`ListState` conversion shape exactly.
|
||||
- Keep the existing `Host` state/secrets/emit methods intact.
|
||||
|
||||
## Acceptance
|
||||
- Author can call `host.Sessions().List(ctx, filter, page)` and
|
||||
`host.Sessions().CodeStats(ctx, filter, page)` (etc.) receiving Go-native
|
||||
structs; proto types are not exposed.
|
||||
- `grpcHostServer` satisfies the generated server interface for the new RPCs;
|
||||
`grpcHostClient` satisfies the extended `Host` interface.
|
||||
- Round-trip conversion unit tests pass.
|
||||
|
||||
## Verification
|
||||
- `cd apps/backend && go test ./pkg/pluginsdk/...`
|
||||
- `cd apps/backend && go build ./...`
|
||||
|
||||
## Files likely touched
|
||||
- `apps/backend/pkg/pluginsdk/types.go`
|
||||
- `apps/backend/pkg/pluginsdk/host.go`
|
||||
- `apps/backend/pkg/pluginsdk/*_test.go`
|
||||
|
||||
## Inputs
|
||||
- Generated stubs from task-01.
|
||||
- Existing pattern: `pkg/pluginsdk/host.go` (grpcHostClient/grpcHostServer),
|
||||
`types.go` (toProto/fromProto, `mapToStruct`/`structToMap`).
|
||||
- Spec: "Host data API" resource/capability table.
|
||||
|
||||
## Dependencies
|
||||
Task 01 (needs regenerated proto stubs).
|
||||
|
||||
## Output contract
|
||||
Summary, the accessor shape chosen (sub-accessors vs flat methods), files changed,
|
||||
test result, and status update here + in `plan.md`.
|
||||
</content>
|
||||
@@ -0,0 +1,77 @@
|
||||
---
|
||||
id: "04-host-data-impl"
|
||||
title: "kandev-side Host data RPC implementation + capability gating + wiring"
|
||||
status: done
|
||||
wave: 3
|
||||
depends_on: ["01-proto-contract", "02-session-loc-aggregation", "03-sdk-data-accessors"]
|
||||
plan: "plan.md"
|
||||
spec: "../../../specs/plugins/spec.md"
|
||||
adr: "../../../decisions/0043-plugin-host-data-api.md"
|
||||
---
|
||||
|
||||
# Task 04: kandev-side Host data RPC implementation
|
||||
|
||||
Implement the Go-native Host data interface (from task-03) inside
|
||||
`internal/plugins`, backed by the service layer, with per-resource capability
|
||||
gating, and wire the new service dependencies through `plugins.Service`.
|
||||
|
||||
## Scope
|
||||
- Implement each read method on `pluginHost` (or a sibling type in
|
||||
`internal/plugins/`) satisfying the extended `pluginsdk.Host` interface:
|
||||
1. **Gate:** check `manifest.CanRead("<resource>")`; on miss return
|
||||
`permissionDenied("api_read:<resource>")` (extend the existing helper —
|
||||
`status.Errorf(codes.PermissionDenied, "capability '%s' not declared", ...)`).
|
||||
2. **Service call:** tasks/workspaces/repositories/sessions → `taskSvc`
|
||||
methods (e.g. `ListTaskSessions`, workspace + repository listers); workflows/
|
||||
steps → workflow service (`ListStepsByWorkflow`, workflow lister); agent
|
||||
profiles → agent settings store; code stats → the task-02 aggregation
|
||||
service method. Never call a repository directly from the handler.
|
||||
3. **Map:** explicit internal model → Go-native DTO mapping (RFC3339 strings,
|
||||
optional/NULL handling). Session DTO must carry `acp_session_id` (from
|
||||
session metadata / `executors_running` fallback, as the source plugin did).
|
||||
- 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`.
|
||||
- **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
|
||||
broker connection (`runtime/manager.go` spawn path, `registerHostServer`).
|
||||
|
||||
## Acceptance
|
||||
- A plugin declaring `api_read:sessions` gets `ListSessions` +
|
||||
`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`.
|
||||
- `make -C apps/backend proto` not required here (done in task-01); package builds
|
||||
and tests pass.
|
||||
|
||||
## Verification
|
||||
- `cd apps/backend && go test ./internal/plugins/...`
|
||||
- `cd apps/backend && go build ./...`
|
||||
|
||||
## Files likely touched
|
||||
- `apps/backend/internal/plugins/host.go`
|
||||
- `apps/backend/internal/plugins/service.go` (deps, `NewService`, `Provide`,
|
||||
`hostForPlugin`)
|
||||
- possibly a new `apps/backend/internal/plugins/host_data.go`
|
||||
- `apps/backend/internal/plugins/host_test.go`
|
||||
|
||||
## Inputs
|
||||
- Extended `Host` interface + Go-native DTOs from task-03.
|
||||
- Aggregation service method from task-02.
|
||||
- Existing gating pattern: `internal/plugins/host.go` (`permissionDenied`,
|
||||
capability checks), `service.go` `hostForPlugin`, `manifest.CanRead`/`CanWrite`.
|
||||
- Service methods: `internal/task/service/service_sessions.go`,
|
||||
`internal/workflow/service/service.go`, `internal/agent/settings/store`.
|
||||
- Spec: "Host data API"; ADR 0043 (service-layer reads, DTO discipline, scoping).
|
||||
|
||||
## Dependencies
|
||||
Tasks 01, 02, 03.
|
||||
|
||||
## Output contract
|
||||
Summary, per-resource service method used for each RPC, capability-gating result,
|
||||
wiring changes, `acp_session_id` sourcing note, test result, and status update
|
||||
here + in `plan.md`.
|
||||
</content>
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
id: "05-rewrite-agent-stats-plugin"
|
||||
title: "Rewrite kandev-plugin-agent-stats to use the SDK data API"
|
||||
status: done
|
||||
wave: 4
|
||||
depends_on: ["03-sdk-data-accessors", "04-host-data-impl"]
|
||||
plan: "plan.md"
|
||||
spec: "../../../specs/plugins/spec.md"
|
||||
adr: "../../../decisions/0043-plugin-host-data-api.md"
|
||||
---
|
||||
|
||||
# Task 05: Rewrite kandev-plugin-agent-stats to use the SDK data API
|
||||
|
||||
The proof the carrot is sufficient: replace the agent-stats plugin's direct SQLite
|
||||
access with the Host data API. This is a **separate repository** at
|
||||
`/home/jcfs/.kandev/tasks/tokens-per-task-loc_9tk/kandev-plugin-agent-stats/` — do
|
||||
not vendor it into the kandev repo; reference it.
|
||||
|
||||
## Scope
|
||||
- Delete `readSessions` + `sessionsQuery` and the `modernc.org/sqlite` dependency
|
||||
from `server/stats.go`. Stop opening `~/.kandev/data/kandev.db`.
|
||||
- Fetch sessions via `host.Sessions().List(...)` and per-session LOC via
|
||||
`host.Sessions().CodeStats(...)`. Map the returned `Session` +
|
||||
`SessionCodeStats` into the existing `sessionRow` shape (agent display, model,
|
||||
`acp_session_id`, committed + peak-pending lines).
|
||||
- Keep `effectiveLines` semantics (max of committed and peak-pending) on the DTO
|
||||
fields; keep the tokscale join on `acp_session_id` unchanged (external tool,
|
||||
unaffected).
|
||||
- Declare `capabilities.api_read: ["sessions"]` in the plugin `manifest.yaml`.
|
||||
- Remove the `KANDEV_AGENT_STATS_DB` config path (no DB path needed); keep the
|
||||
tokscale override.
|
||||
|
||||
## Acceptance
|
||||
- The plugin no longer imports a SQLite driver or opens any kandev DB file.
|
||||
- Stats report still renders sessions + LOC + tokscale ratios using data obtained
|
||||
solely through the Host data API.
|
||||
- `manifest.yaml` declares `api_read: ["sessions"]`.
|
||||
|
||||
## Verification
|
||||
- In the plugin repo: `go build ./...` and its existing `go test ./...`.
|
||||
|
||||
## Files likely touched (separate repo)
|
||||
- `.../kandev-plugin-agent-stats/server/stats.go`
|
||||
- `.../kandev-plugin-agent-stats/server/plugin.go`
|
||||
- `.../kandev-plugin-agent-stats/manifest.yaml`
|
||||
- `.../kandev-plugin-agent-stats/go.mod` (drop sqlite dep)
|
||||
|
||||
## Inputs
|
||||
- SDK data accessors from task-03; live host impl from task-04.
|
||||
- Current plugin: `server/stats.go` (`sessionRow`, `aggregate`, `effectiveLines`),
|
||||
`server/plugin.go` (`loadConfig`, `collect`).
|
||||
|
||||
## Dependencies
|
||||
Tasks 03, 04.
|
||||
|
||||
## Output contract
|
||||
Summary, confirmation the SQLite import is gone, mapping notes (DTO →
|
||||
`sessionRow`), build/test result, and status update here + in `plan.md`.
|
||||
</content>
|
||||
@@ -0,0 +1,59 @@
|
||||
---
|
||||
id: "06-tests"
|
||||
title: "Capability-gating, DTO-mapping, and plugin-reads-sessions integration tests"
|
||||
status: done
|
||||
wave: 4
|
||||
depends_on: ["04-host-data-impl"]
|
||||
plan: "plan.md"
|
||||
spec: "../../../specs/plugins/spec.md"
|
||||
adr: "../../../decisions/0043-plugin-host-data-api.md"
|
||||
---
|
||||
|
||||
# Task 06: Host data API tests
|
||||
|
||||
Cover the spec scenarios for the Host data API at the host boundary. (Aggregation
|
||||
SQL and SDK round-trip conversions are unit-tested in tasks 02/03; this task owns
|
||||
the host RPC behavior and the end-to-end plugin path.)
|
||||
|
||||
## Scope
|
||||
- **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`.
|
||||
- **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`.
|
||||
- **Pagination:** `ListTasks` (or another list RPC) returns `has_more` + a
|
||||
`next_cursor` that yields the next page and terminates.
|
||||
- **Ephemeral exclusion:** `ListTasks` without `include_ephemeral` omits ephemeral
|
||||
tasks.
|
||||
- **Integration:** drive a Host client (SDK `grpcHostClient` over the broker, or
|
||||
the existing plugins test harness) to call `ListSessions` +
|
||||
`ListSessionCodeStats` against a seeded DB and assert rows come back without any
|
||||
file-level DB access — the concrete "plugin reads sessions via the API" scenario.
|
||||
|
||||
## Acceptance
|
||||
- Tests exist for each spec scenario listed above and pass.
|
||||
- No test opens the SQLite file to stand in for the plugin path — the plugin-facing
|
||||
assertion goes through the Host RPC surface.
|
||||
|
||||
## Verification
|
||||
- `cd apps/backend && go test ./internal/plugins/...`
|
||||
|
||||
## Files likely touched
|
||||
- `apps/backend/internal/plugins/host_test.go`
|
||||
- possibly `apps/backend/internal/plugins/host_data_test.go`
|
||||
|
||||
## Inputs
|
||||
- Host impl from task-04; existing test harness in
|
||||
`internal/plugins/host_test.go` / `service_test.go`.
|
||||
- Spec: "Host data API" scenarios.
|
||||
- Backend testing conventions in `apps/backend/CLAUDE.md` (synctest, goleak).
|
||||
|
||||
## Dependencies
|
||||
Task 04.
|
||||
|
||||
## Output contract
|
||||
Summary, list of scenarios covered, test result, coverage gaps if any, and status
|
||||
update here + in `plan.md`.
|
||||
</content>
|
||||
@@ -0,0 +1,133 @@
|
||||
---
|
||||
id: "07-docs"
|
||||
title: "Author docs: Host data API + manifest api_read/api_write resource list"
|
||||
status: done
|
||||
wave: 4
|
||||
depends_on: ["04-host-data-impl"]
|
||||
plan: "plan.md"
|
||||
spec: "../../../specs/plugins/spec.md"
|
||||
adr: "../../../decisions/0043-plugin-host-data-api.md"
|
||||
---
|
||||
|
||||
# Task 07: Author docs for the Host data API
|
||||
|
||||
Document the Host data API for plugin authors: which resources are readable, the
|
||||
`api_read`/`api_write` capability vocabulary, and the SDK accessor surface.
|
||||
|
||||
## Scope
|
||||
- **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`).
|
||||
- **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
|
||||
they return Go-native structs.
|
||||
- **Manifest reference:** wherever the manifest `capabilities` block is documented
|
||||
for authors, list the `api_read` / `api_write` resource vocabulary (`tasks`,
|
||||
`sessions`, `workspaces`, `workflows`, `agents`, `repositories`, `comments`) and
|
||||
what each unlocks, with the `api_read: ["sessions"]` example from the agent-stats
|
||||
plugin.
|
||||
- **Public docs:** if a user-facing plugin authoring page exists under
|
||||
`docs/public/**` at implementation time, add the resource list there too; there
|
||||
is none today, so the authoritative author docs are the plans references above.
|
||||
Do not invent a new public page in this task.
|
||||
|
||||
## 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.
|
||||
|
||||
## Verification
|
||||
- Markdown-only; no build. `cd apps && pnpm --filter @kandev/web lint` only if a
|
||||
`docs/public` page is touched (none expected).
|
||||
|
||||
## Files likely touched
|
||||
- `docs/plans/plugins/GRPC-CONTRACT.md`
|
||||
- `docs/plans/plugins/PLUGIN-API.md` (if the SDK/author surface is documented
|
||||
there)
|
||||
|
||||
## Inputs
|
||||
- Final RPC set + accessor names from tasks 01/03/04.
|
||||
- Spec: "Host data API"; ADR 0043.
|
||||
|
||||
## Dependencies
|
||||
Task 04 (behavior finalized).
|
||||
|
||||
## Output contract
|
||||
Summary, files changed, and status update here + in `plan.md`.
|
||||
|
||||
## Output
|
||||
|
||||
**Summary:** Documented the Host data API (ADR 0043) in the wire/SDK contract
|
||||
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
|
||||
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`,
|
||||
`WorkflowReader`, `AgentProfileReader`, `RepositoryReader`) with their real Go
|
||||
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.
|
||||
- `docs/specs/plugins/spec.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
|
||||
actual per-RPC inline checks (no shared unary interceptor exists in code);
|
||||
updated the readable-resources table's `ListAgentProfiles` row.
|
||||
- `docs/plans/plugins/host-data-api/plan.md` — marked task-07 done in the wave
|
||||
list.
|
||||
|
||||
**Code-vs-doc drift found and corrected (spec.md only; code is source of
|
||||
truth, left unchanged):**
|
||||
- The `ListAgentProfiles` capability is `api_read:agent_profiles` in code
|
||||
(`internal/plugins/host_data.go: resourceAgentProfiles = "agent_profiles"`,
|
||||
confirmed by `host_data_test.go`), not `api_read:agents` as the spec had it
|
||||
in the manifest example, the resource-vocabulary sentence, and the readable-
|
||||
resources table. Fixed all three.
|
||||
- The spec's manifest example listed `"projects"` as an `api_read` resource;
|
||||
there is no `ListProjects` RPC, resource constant, or reader anywhere in the
|
||||
proto or `internal/plugins/host_data.go`. Removed it from the example.
|
||||
- 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.
|
||||
- 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
|
||||
inline at the top of the handler (`host.go`, `host_data.go`). Reworded to
|
||||
describe the actual per-RPC check without implying a shared interceptor
|
||||
layer (this was pre-existing drift, unrelated to ADR 0043, caught while
|
||||
editing the same paragraph).
|
||||
- `GRPC-CONTRACT.md`'s pre-ADR text already read "api_read/api_write reserved
|
||||
for future" in §5 and the `service Host` proto snippet only listed the 6
|
||||
pre-ADR RPCs; both were stale relative to the shipped proto and are now
|
||||
updated in place.
|
||||
|
||||
**Not touched (out of scope / already correct):**
|
||||
- `docs/decisions/0043-plugin-host-data-api.md` — read for context per the
|
||||
task's Inputs; its `Status: proposed` front matter looks stale given the
|
||||
code is fully implemented, but the task's edit scope was spec.md, not the
|
||||
ADR, so it is left for whoever finalizes the ADR's status.
|
||||
- `docs/plans/plugins/PLUGIN-API.md` — this is the native frontend (JS) UI
|
||||
plugin contract; it has no backend Host/SDK content and the Host data API
|
||||
has no UI surface, so nothing there needed updating. The SDK reference went
|
||||
into `GRPC-CONTRACT.md` §4 per the task's "and/or" framing.
|
||||
- `docs/public/plugins*.md` — do not exist on this branch (confirmed); per the
|
||||
task instructions these live on `feature/kandev-plugin-system-docs` and are
|
||||
out of scope here.
|
||||
- `apps/backend/internal/plugins/manifest/manifest_test.go` has an unrelated
|
||||
test fixture using `api_read: ["tasks", "agents"]` as a manifest capability
|
||||
example — manifest capability values are freeform strings with no vocabulary
|
||||
validation at that layer (confirmed: no enum/allow-list check in
|
||||
`internal/plugins/manifest`), so this is a test fixture choice, not a
|
||||
functional bug; flagged here as a code-side echo of the same naming drift,
|
||||
left unchanged since it's code, not docs.
|
||||
</content>
|
||||
Reference in New Issue
Block a user