kandev/docs/plans/workflow-transition-canvas/task-02-host-api.md

id, title, status, wave, depends_on, plan, requirements, acceptance_criteria, system_design

id	title	status	wave	depends_on	plan	requirements	acceptance_criteria	system_design
02-host-api	Expose scoped Host and canvas reads	done	2	01-transition-reads	plan.md	REQ-PLUGINS-WORKFLOW-HISTORY-001 REQ-PLUGINS-WORKFLOW-HISTORY-002	AC-PLUGINS-WORKFLOW-HISTORY-001.1 AC-PLUGINS-WORKFLOW-HISTORY-001.2 AC-PLUGINS-WORKFLOW-HISTORY-001.4 AC-PLUGINS-WORKFLOW-HISTORY-001.5 AC-PLUGINS-WORKFLOW-HISTORY-002.1 AC-PLUGINS-WORKFLOW-HISTORY-002.2 AC-PLUGINS-WORKFLOW-HISTORY-002.3	../../specs/plugins/system-design/workflow-transition-history.md

Task 02: Expose scoped Host and canvas reads

Summary

Add typed plugin Host reads and equivalent canvas browser routes for task trails and workflow route groups. Enforce grants and scope before a ledger query, then document the additive public contract.

In scope

• Extend the v1 proto, generated stubs, SDK interfaces and mappings, Plugin Host adapter, and browser JSON routing.
• Reuse api_read:tasks for a scoped task trail. Require both task and workflow read grants plus workspace canvas scope for route groups.
• Test forbidden task/workflow IDs, task-scope summary denial, pagination, missing steps, null endpoints, and omission of actor/session identifiers.
• Update the embedded canvas authoring API reference and public plugin/canvas reference pages.

Out of scope

• Canvas layout and publication, task writes, and new permission kinds.

Acceptance

1. gRPC/SDK and browser reads expose the same ordered facts and bounded groups, with no unscoped or unpublished identifier leaked through an error.
2. Effective grants and current canvas scope gate every browser request; task scope can read only its own trail and cannot read route groups.
3. The authoring bundle and public docs name the new routes, fields, limits, permission requirements, and workspace-promotion boundary.

Verification

make -C apps/backend proto
(cd apps/backend && go test ./internal/plugins ./pkg/pluginsdk ./internal/mcp/canvasskill)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs

Files likely touched

• apps/backend/proto/kandev/plugin/v1/plugin.proto and generated Go stubs
• apps/backend/pkg/pluginsdk/host.go and tests
• apps/backend/internal/plugins/host_data.go
• apps/backend/internal/plugins/webapp_protocol.go
• apps/backend/internal/plugins/webapp_protocol_data.go and tests
• apps/backend/internal/mcp/canvasskill/files/references/browser-api.md
• docs/public/plugins-authoring.md
• docs/public/canvases.md

Dependencies

Task 01's task-service read methods.

Risks

The Host gRPC API is additive-only in protocol v1. A browser route that checks only a resource grant but misses canvas scope could expose other tasks' moves.

Parallelism

sequential

Inputs

• Requirements
• System design
• ADR 0043

Results

Added task-history and workflow-group RPCs to protocol v1, generated stubs, the optional SDK Host extension, the real Host adapter, and scoped canvas browser routes. Browser tests cover task-scope refusal, missing grants, foreign workflows, and workflows beyond the first list page. The bundled browser reference and public canvas/plugin guides document both routes.

Passed after the final implementation edit:

make -C apps/backend proto
(cd apps/backend && go test ./internal/plugins ./pkg/pluginsdk ./internal/mcp/canvasskill)
node --test scripts/validate-public-docs.test.mjs
node scripts/validate-public-docs.mjs