From 2e6f2eb84a85e9a1c26fe5db027cead489369757 Mon Sep 17 00:00:00 2001 From: Henry Date: Mon, 31 Aug 2026 12:28:36 +0000 Subject: [PATCH] docs(plugins): sync WorkflowStep field docs with the shipped contract (#3183) Co-authored-by: nova28 <17953305+nova28@users.noreply.github.com> Co-authored-by: Carlos Florencio --- docs/plans/plugins/HOST-DATA-API.proto | 14 +++++++++++++- docs/specs/plugins/system-design/plugins-02.md | 8 +++++++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/plans/plugins/HOST-DATA-API.proto b/docs/plans/plugins/HOST-DATA-API.proto index a8c4690e65..020d78cf21 100644 --- a/docs/plans/plugins/HOST-DATA-API.proto +++ b/docs/plans/plugins/HOST-DATA-API.proto @@ -1,7 +1,16 @@ // kandev.plugin.v1 Host data API — folded into // apps/backend/proto/kandev/plugin/v1/plugin.proto and fully wired (reads and // writes both implemented). This file is the frozen design draft kept for -// reference alongside the ADRs. +// reference alongside the ADRs: a point-in-time SNAPSHOT that has NOT tracked +// the contract since it was written. For the live shape, read +// apps/backend/proto/kandev/plugin/v1/plugin.proto (wire contract) and +// apps/backend/pkg/pluginsdk/data_types.go (Go SDK mirror) directly — do not +// infer current fields from this file. Examples of known-diverged messages +// (not exhaustive — other messages in this file may also have drifted): +// `Task` (17 fields here vs 29 live), `WorkflowStep` (5 here vs 10 live — +// missing `color`, `is_start_step`, `wip_limit`, `agent_profile_id`, +// `on_enter_action_types`), and `Message` (absent here; the whole +// `ListMessages` read path from ADR 0047 postdates this draft). // // Extends the existing capability-gated Host service so plugins read AND write // kandev data through a typed, versioned contract instead of touching the @@ -133,6 +142,9 @@ message Workflow { message ListWorkflowsRequest { string workspace_id = 1; Page page = 2; } message ListWorkflowsResponse { repeated Workflow workflows = 1; PageInfo page_info = 2; } +// DIVERGED from the live contract — see canonical +// apps/backend/proto/kandev/plugin/v1/plugin.proto for fields 6-10 +// (color, is_start_step, wip_limit, agent_profile_id, on_enter_action_types). message WorkflowStep { string id = 1; string workflow_id = 2; diff --git a/docs/specs/plugins/system-design/plugins-02.md b/docs/specs/plugins/system-design/plugins-02.md index 6f5c9d95e5..2815d0798c 100644 --- a/docs/specs/plugins/system-design/plugins-02.md +++ b/docs/specs/plugins/system-design/plugins-02.md @@ -252,7 +252,7 @@ domain structs. See [ADR 0043](../../../decisions/0043-plugin-host-data-api.md) | `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) | +| `ListWorkflowSteps` | `api_read:workflows` | Steps for a workflow (`id`, `workflow_id`, `name`, `position`, `stage_type`, `color`, `is_start_step`, `wip_limit`, `agent_profile_id`, `on_enter_action_types`) | | `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) | @@ -267,6 +267,12 @@ aggregate the agent-stats plugin previously re-derived by hand from `task_session_commits` and `task_session_git_snapshots` — so plugins never touch those raw rows. +`on_enter_action_types` on a step lists the on-enter action *types* configured +for that step (e.g. `auto_start_agent`, `queue_run`), never the action +*config* — target task ids, payloads, and profile ids stay server-side. A type +appearing in this list means it is configured, not a guarantee of when or +whether it fires. Plugins must ignore action types they do not recognize. + **Conversation content (`api_read:messages`, ADR 0047).** `ListMessages` reads historical user/agent message content — the data a "summarize yesterday" plugin needs, which the `message.added` bus event alone (live-only,