kandev/docs/plans/plugin-agent-tools/task-01-manifest-sdk-contract.md

id, title, status, wave, depends_on, plan, spec, adr

id	title	status	wave	depends_on	plan	spec	adr
01-manifest-sdk-contract	Manifest and SDK contract	done	1		plan.md	../../specs/plugins/requirements/agent-tools.md	../../decisions/2026-08-11-plugin-tools-through-kandev-mcp.md

Task 01: Manifest and SDK contract

Acceptance

• The manifest and normalized runtime descriptor represent every field and limit in the spec, reject invalid schemas/surfaces/names, and derive bounded deterministic exposed names.
• The plugin protobuf and Go SDK support one context-respecting InvokeAgentTool RPC with fallback text, optional structured content, and is_error; the optional AgentToolPlugin interface leaves the base Plugin interface and existing implementations source-compatible.
• Protobuf stubs are regenerated, not edited manually, and focused manifest and SDK round-trip tests pass.

Verification

make -C apps/backend proto && cd apps/backend && go test -race ./internal/plugins/manifest ./internal/mcp/plugintools ./pkg/pluginsdk

Files likely touched

• apps/backend/internal/plugins/manifest/manifest.go
• apps/backend/internal/plugins/manifest/validate.go
• apps/backend/internal/plugins/manifest/manifest_test.go
• apps/backend/internal/mcp/plugintools/types.go
• apps/backend/internal/mcp/plugintools/types_test.go
• apps/backend/internal/mcp/toolschema/schema.go
• apps/backend/internal/mcp/toolschema/schema_test.go
• apps/backend/proto/kandev/plugin/v1/plugin.proto
• apps/backend/proto/kandev/plugin/v1/plugin.pb.go
• apps/backend/proto/kandev/plugin/v1/plugin_grpc.pb.go
• apps/backend/pkg/pluginsdk/plugin.go
• apps/backend/pkg/pluginsdk/types.go
• apps/backend/pkg/pluginsdk/serve.go
• apps/backend/pkg/pluginsdk/plugin_test.go
• apps/backend/pkg/pluginsdk/serve_test.go

Dependencies

None.

Parallelism

Sequential. This task establishes shared manifest, protobuf, generated, and SDK contracts consumed by every later task.

Inputs

• Spec sections What, Manifest Contract, and Plugin SDK Contract
• ADR decisions 1, 4, 8, and 9
• Existing manifest.Validate, protobuf service Plugin, pluginsdk optional interface/adapter patterns, and MCP JSON Schema validation behavior

Risks

• A protobuf field or SDK signature mistake becomes a public compatibility burden. Keep request context backend-authored and result content bounded.
• JSON Schema must have one interpretation at install and invocation time.

Output contract

Report RED tests, exact public fields and defaults, generated files, commands and results, compatibility notes, and task/plan status updates.

Results

• RED: TestParse_AgentToolDeclarationIsRetained failed because the existing manifest parser had no AgentTools field.
• Added manifest declarations and validation for names, surfaces, schemas, limits, and annotation consistency; added normalized readable provider-safe names and catalog snapshots under internal/mcp/plugintools.
• Added shared JSON Schema compilation under internal/mcp/toolschema.
• Added optional pluginsdk.AgentToolPlugin and gRPC request/response conversion. The base Plugin interface remains unchanged for compatibility.
• Added InvokeAgentTool to the plugin protobuf and regenerated stubs with make proto.
• Verification: make proto (pass); go test -race ./internal/plugins/manifest ./internal/mcp/toolschema ./internal/mcp/plugintools ./pkg/pluginsdk (pass); focused SDK round trip go test -race -run 'TestServe_EndToEnd/InvokeAgentTool' ./pkg/pluginsdk (pass).
• Remaining risk: backend catalog invocation and agentctl registry are not yet wired; task 02 begins that work.