Carlos Florêncio
78 lines
2.4 KiB
Markdown
78 lines
2.4 KiB
Markdown
---
|
|
id: "02-plugin-catalog-invocation"
|
|
title: "Plugin catalog and invocation"
|
|
status: done
|
|
wave: 2
|
|
depends_on: ["01-manifest-sdk-contract"]
|
|
plan: "plan.md"
|
|
spec: "../../specs/plugins/requirements/agent-tools.md"
|
|
adr: "../../decisions/2026-08-11-plugin-tools-through-kandev-mcp.md"
|
|
---
|
|
|
|
# Task 02: Plugin catalog and invocation
|
|
|
|
## Acceptance
|
|
|
|
- The plugin service produces sorted, active-only, generation/revision catalog
|
|
snapshots and rejects install/upgrade collisions without replacing the prior
|
|
installation.
|
|
- `InvokeAgentTool` revalidates current state, declaration, surface, input, and
|
|
result; enforces deadline/size bounds; calls the plugin once; and logs only
|
|
safe metadata.
|
|
- Every effective lifecycle change emits a nonblocking catalog-change signal;
|
|
equivalent changes do not advance the revision or emit duplicate work.
|
|
|
|
## Verification
|
|
|
|
```bash
|
|
cd apps/backend && go test -race ./internal/plugins/...
|
|
```
|
|
|
|
## Files likely touched
|
|
|
|
- `apps/backend/internal/plugins/agent_tools.go`
|
|
- `apps/backend/internal/plugins/agent_tools_test.go`
|
|
- `apps/backend/internal/plugins/invoke.go`
|
|
- `apps/backend/internal/plugins/service.go`
|
|
- `apps/backend/internal/plugins/service_test.go`
|
|
- `apps/backend/internal/plugins/types.go`
|
|
- `apps/backend/internal/plugins/provider.go`
|
|
|
|
## Dependencies
|
|
|
|
Task 01.
|
|
|
|
## Parallelism
|
|
|
|
Parallel-safe with Task 03 after Task 01. This task owns plugin service/catalog
|
|
files; Task 03 owns MCP server and agentctl files.
|
|
|
|
## Inputs
|
|
|
|
- Spec sections `Runtime Catalog`, `Permissions`, `Failure Modes`, and
|
|
`Persistence Guarantees`
|
|
- Existing `InvokeWebhook`, install transaction, status transition, runtime
|
|
supervision callback, and `notifyDeliverer` patterns
|
|
|
|
## Risks
|
|
|
|
- Runtime health callbacks must not block while catalog refresh reaches remote
|
|
agentctl instances.
|
|
- Tool calls are not retry-safe; no existing event-delivery retry helper may be
|
|
reused for invocation.
|
|
|
|
## Output contract
|
|
|
|
Report catalog ordering/revision rules, collision transaction behavior,
|
|
invocation bounds, safe logging fields, commands and results, and task/plan
|
|
status updates.
|
|
|
|
## Results
|
|
|
|
- Added the active-only catalog builder with stable generation/revision and
|
|
readable plugin-ID-derived exposed names, with bounded hash fallback for long
|
|
IDs.
|
|
- Added install collision checks, lifecycle refresh signaling, argument and
|
|
result schema validation, 30-second deadlines, and the 1 MiB result cap.
|
|
- Verification: `go test -race ./internal/plugins/...` passed.
|