Carlos Florêncio
89 lines
3.5 KiB
Markdown
89 lines
3.5 KiB
Markdown
---
|
|
id: "04-runtime-propagation-backend-dispatch"
|
|
title: "Runtime propagation and backend dispatch"
|
|
status: done
|
|
wave: 3
|
|
depends_on: ["02-plugin-catalog-invocation", "03-agentctl-dynamic-registry"]
|
|
plan: "plan.md"
|
|
spec: "../../specs/plugins/requirements/agent-tools.md"
|
|
adr: "../../decisions/2026-08-11-plugin-tools-through-kandev-mcp.md"
|
|
---
|
|
|
|
# Task 04: Runtime propagation and backend dispatch
|
|
|
|
## Acceptance
|
|
|
|
- Launch and resume profiles include the current catalog, while Configuration
|
|
and External surfaces expose no plugin tools.
|
|
- A scoped backend MCP action verifies the bound task/session pair and current
|
|
plugin declaration before one plugin RPC, and maps valid text/structured/error
|
|
results back to agentctl.
|
|
- A serialized backendapp refresher pushes each effective snapshot to every
|
|
active execution, continues after individual failures, and leaves later
|
|
launch/resume or refresh able to repair stale runtime state.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
cd apps/backend && go test -race ./internal/mcp/handlers ./internal/mcp/scope ./internal/orchestrator/executor ./internal/agent/runtime/lifecycle ./internal/backendapp
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/backend/pkg/websocket/actions.go`
|
|
- `apps/backend/internal/mcp/handlers/handlers.go`
|
|
- `apps/backend/internal/mcp/handlers/plugin_tools.go`
|
|
- `apps/backend/internal/mcp/handlers/plugin_tools_test.go`
|
|
- `apps/backend/internal/orchestrator/executor/executor.go`
|
|
- `apps/backend/internal/orchestrator/executor/executor_execute.go`
|
|
- `apps/backend/internal/orchestrator/executor/executor_mcp_mode_test.go`
|
|
- `apps/backend/internal/agent/runtime/lifecycle/manager_launch.go`
|
|
- `apps/backend/internal/agent/runtime/lifecycle/manager_mcp_plugin_tools_test.go`
|
|
- `apps/backend/internal/backendapp/plugin_tool_refresher.go`
|
|
- `apps/backend/internal/backendapp/plugin_tool_refresher_test.go`
|
|
- `apps/backend/internal/backendapp/main.go`
|
|
|
|
## Dependencies
|
|
|
|
Tasks 02 and 03.
|
|
|
|
## Parallelism
|
|
|
|
Sequential. This task joins shared plugin, MCP, orchestrator, lifecycle, and
|
|
backendapp contracts.
|
|
|
|
## Inputs
|
|
|
|
- Spec `Permissions`, `Failure Modes`, and hot-refresh scenarios
|
|
- Root/backend auth scoping guidance for in-session MCP
|
|
- Existing provider live refresher, `resolveTaskSessionMCPProfile`, lifecycle
|
|
`SetMcpProvidersForSession`, and MCP dispatcher patterns
|
|
|
|
## Risks
|
|
|
|
- A handler that trusts agent-supplied task/session IDs creates a cross-user
|
|
authorization defect. Use only server-bound identity and authorize first.
|
|
- Out-of-order or blocking catalog propagation can restore stale tools or stall
|
|
plugin supervision.
|
|
|
|
## Output contract
|
|
|
|
Report the exact identity/authorization chain, refresh serialization and failure
|
|
behavior, launch/resume wiring, commands and results, and task/plan status
|
|
updates.
|
|
|
|
## Results
|
|
|
|
- Added `mcp.list_plugin_tools` and `mcp.invoke_plugin_tool` actions with task /
|
|
session binding checks, surface filtering, and service dispatch.
|
|
- Wired the plugin service into backend MCP handler registration and preserved
|
|
existing identity scoping.
|
|
- Added the agentctl plugin-tool control endpoint, lifecycle fan-out, and a
|
|
coalescing backendapp refresher wired to plugin lifecycle notifications.
|
|
- Agentctl retains the complete revisioned catalog and applies surface filters
|
|
while rebuilding the active MCP profile, so live surface changes do not lose
|
|
declarations.
|
|
- Verification: `go test -race ./internal/mcp/handlers ./internal/mcp/scope
|
|
./internal/orchestrator/executor ./internal/agent/runtime/lifecycle
|
|
./internal/backendapp` passed.
|