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:
João Salavisa
2026-07-17 13:43:58 +01:00
committed by GitHub
parent 2bb11bacb1
commit 0df2bbac0a
44 changed files with 9250 additions and 110 deletions
+154
View File
@@ -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>