api refactor: unify provider/deployment adapter flow and remove startup reconciliation by ilackarms · Pull Request #302 · agentregistry-dev/agentregistry

ilackarms · 2026-03-06T20:55:32Z

Description

This PR completes the API/deployment refactor to make provider adapters the single platform boundary, simplify deployment lifecycle handling, and remove startup-time reconciliation behavior from core registry startup.

Motivation: reduce abstraction leaks, enforce a cleaner adapter contract, and make deployment behavior consistent across providers without adding parallel APIs.
What changed:
- Enforced strict providerId in core deployment APIs, while keeping CLI/MCP convenience behavior at the edge.
- Removed startup reconciliation config/wiring and related chart/daemon settings.
- Moved provider-specific deployment runtime reconciliation behavior into adapters.
- Introduced adapter result/state patch primitives for provider metadata/status updates without DB access from adapters.
- Fixed regressions around agent-resolved MCP deployment scoping, ARG_/HEADER_ runtime input recovery, and stale artifact handling during reconciliation.
- Reduced cross-layer coupling by removing client dependence on handler DTOs and service dependence on runtime translation DTOs.
- Updated tests and docs to match the new API/adapter behavior.

Change Type

/kind breaking_change
/kind cleanup
/kind design
/kind fix

Changelog

Refactored deployments/providers to use a unified adapter-driven flow: `providerId` is now required in core deployment APIs, startup reconciliation was removed, and adapter result/state patch handling now drives provider-specific deployment status/metadata updates.

- finish rename config -> env - call deployment adapters from within registry service - add extraroutes

…yments per server

Copilot

Pull request overview

This PR completes an API/deployment refactor to make provider adapters the primary platform boundary, require providerId in core deployment APIs, remove startup reconciliation, and shift provider-specific deployment behavior into adapters.

Changes:

Updated OpenAPI + generated UI SDK/types to require providerId for deployment requests and renamed deployments list response type.
Removed legacy runtime translation/reconciliation modules and startup reconciliation wiring/config across server, daemon, and Helm chart.
Introduced adapter-driven deployment action results and partial deployment state patching (DB + models), plus new local/kubernetes deployment adapters and supporting platform types/utils.

Reviewed changes

Copilot reviewed 79 out of 80 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
ui/lib/api/types.gen.ts	Makes `providerId` required in `DeploymentRequest`; renames deployments list response type; doc tweaks.
ui/lib/api/sdk.gen.ts	Updates cancel deployment description in generated SDK.
ui/lib/api/index.ts	Re-exports updated generated types (e.g., `DeploymentsListResponse`).
ui/components/deploy-server-dialog.tsx	Supplies `providerId` in deploy request to satisfy new API requirement.
pkg/types/types.go	Removes legacy deployment target/service factory hooks; updates deployment adapter deploy signature to return `DeploymentActionResult`.
pkg/registry/database/database.go	Renames DB interface method to `UpdateDeploymentState` using `DeploymentStatePatch`.
pkg/models/provider.go	Adds `KubernetesProviderConfig` model for provider selection settings.
pkg/models/deployment.go	Adds `DeploymentActionResult` and `DeploymentStatePatch`; extends k8s metadata.
openapi.yaml	Requires `providerId` in deployment request schema; updates docs and response schema names.
internal/runtime/translation/registry/utils/registry_utils.go	Deleted legacy runtime translation utilities.
internal/runtime/translation/registry/internal_registry_translator.go	Deleted legacy registry-to-runtime translator.
internal/runtime/translation/kagent/kagent_translator.go	Deleted legacy k8s translator.
internal/runtime/translation/dockercompose/docker_compose_translator.go	Deleted legacy docker-compose translator.
internal/runtime/translation/api/translator.go	Deleted legacy runtime translator interface.
internal/runtime/translation/api/internal_runtime_api.go	Deleted legacy internal runtime API types.
internal/runtime/translation/api/dockercompose_types.go	Deleted legacy docker-compose type aliases.
internal/runtime/runtime_test.go	Deleted runtime validation tests (runtime package removed).
internal/runtime/runtime.go	Deleted runtime validator implementation (runtime package removed).
internal/runtime/agentregistry_runtime_unit_test.go	Deleted runtime translation unit tests.
internal/runtime/agentregistry_runtime_test.go	Deleted runtime docker integration test.
internal/runtime/agentregistry_runtime.go	Deleted legacy runtime reconciler implementation.
internal/registry/service/testing/fake_registry.go	Updates fake service interface: removes platform param, adds skill resolution hook.
internal/registry/service/service.go	Updates RegistryService interface: removes reconciler/platform params; adds `ResolveAgentManifestSkills`.
internal/registry/service/registry_service_discovered_id_test.go	Updates discovered deployment ID tests for new scoping inputs.
internal/registry/registry_app.go	Removes startup reconciliation; wires new local/k8s deployment adapters; switches to shared `apitypes.VersionBody`.
internal/registry/platforms/utils/deployment_adapter_utils_test.go	New tests for runtime input splitting and MCP/agent resolution helpers.
internal/registry/platforms/types/types.go	New shared platform types (desired state, local/k8s configs, agent gateway config).
internal/registry/platforms/types/agentgateway_types.go	Moves AgentGateway types into `platforms/types` package and refactors comments/formatting.
internal/registry/platforms/local/deployment_adapter_local_test.go	New tests for local undeploy cleanup when registry artifacts are missing.
internal/registry/platforms/local/deployment_adapter_local_platform_test.go	New tests for local platform config route port defaults.
internal/registry/platforms/local/deployment_adapter_local.go	New local deployment adapter implementing deploy/undeploy/cleanup behaviors.
internal/registry/platforms/kubernetes/deployment_adapter_kubernetes.go	New kubernetes deployment adapter implementing deploy/undeploy/discover/cleanup behaviors.
internal/registry/database/postgres_test.go	Updates/extends tests for `UpdateDeploymentState` patching behavior.
internal/registry/database/postgres.go	Requires provider ID on create; implements `UpdateDeploymentState` with partial patch semantics.
internal/registry/database/migrations/010_drop_platform_validity_constraints.sql	Drops DB-level platform validity constraints (adapter-driven validation).
internal/registry/config/config.go	Removes `ReconcileOnStartup` config; keeps runtime dir/verbose.
internal/registry/api/server.go	Switches version type to `apitypes.VersionBody`.
internal/registry/api/router/v0.go	Switches version type to `apitypes.VersionBody`.
internal/registry/api/router/router.go	Switches version type to `apitypes.VersionBody`.
internal/registry/api/handlers/v0/version.go	Aliases version body to centralized `apitypes` type.
internal/registry/api/handlers/v0/servers.go	Updates deployment-meta attachment call signature.
internal/registry/api/handlers/v0/providers.go	Updates platform filter doc string.
internal/registry/api/handlers/v0/embeddings.go	Moves embeddings request/response types to `apitypes`.
internal/registry/api/handlers/v0/edit.go	Updates deployment-meta attachment call signature.
internal/registry/api/handlers/v0/deployments_test.go	Updates deployment adapter signature and providerId validation expectations; removes platform arg passing.
internal/registry/api/handlers/v0/deployments.go	Requires `providerId`; removes platform-resolution param flow; updates cancel/logs unsupported error sentinel usage.
internal/registry/api/handlers/v0/deployment_meta_bridge_test.go	Updates tests for filtered deployment statuses and new attachment signature.
internal/registry/api/handlers/v0/deployment_meta_bridge.go	Filters inactive deployment statuses; recalculates deployment index internally in attachment helpers.
internal/registry/api/handlers/v0/deployment_adapters.go	Deleted legacy deployment adapters (moved to platforms/).
internal/registry/api/handlers/v0/agents.go	Updates deployment-meta attachment call signature.
internal/registry/api/cors_test.go	Switches version type to `apitypes.VersionBody`.
internal/registry/api/apitypes/types.go	New shared API DTOs used by handlers + internal client.
internal/mcp/registryserver/server.go	Updates deploy tool args structure; removes platform lookup for undeploy tool.
internal/mcp/registryserver/deployments_test.go	Updates fake undeploy signature (no platform arg).
internal/daemon/docker-compose.yml	Removes reconcile-on-startup env var.
internal/client/client_integration_test.go	Updates tests to align with providerId requirements and new request/response types.
internal/client/client.go	Defaults deploy provider ID to `local` at the client edge; switches to `apitypes` DTO aliases.
internal/cli/skill/publish_test.go	Minor test cleanup (removes nolint, aligns formatting).
internal/cli/mcp/run.go	Replaces legacy runtime reconciliation with local platform config + compose up/down workflow.
internal/cli/mcp/publish_test.go	Formatting alignment in table-driven test struct.
internal/cli/embeddings.go	Switches embeddings DTOs to internal client aliases.
internal/cli/agent/utils/registry_translator.go	Replaces legacy registry translation utils with platform utils translation flow.
internal/cli/agent/build.go	Makes `--image` optional (defaults derived from manifest/name).
go.mod	Adds `gopkg.in/evanphx/json-patch.v4` indirect dependency.
e2e/deploy_test.go	Updates deploy flows to pass/derive image refs consistently and adds k8s resource cleanup verification test.
charts/agentregistry/values.yaml	Removes reconcile-on-startup value.
charts/agentregistry/tests/configmap_test.yaml	Removes reconcile-on-startup configmap assertion.
charts/agentregistry/templates/configmap.yaml	Removes reconcile-on-startup env var from rendered configmap.
AGENTS.md	Removes development guidelines document.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-10T21:12:44Z

internal/registry/api/handlers/v0/deployment_meta_bridge.go

+func isActiveDeploymentStatus(status string) bool {
+	switch strings.ToLower(strings.TrimSpace(status)) {
+	case "deploying", "deployed", "discovered":
+		return true
+	default:
+		return false
+	}


isActiveDeploymentStatus currently treats only deploying/deployed/discovered as active. Deployment statuses like "queued" are used elsewhere (e.g., cancel flow tests) and will be filtered out of server/agent deployment metadata, making queued deployments invisible in Meta.Deployments. Consider including "queued" (and any other in-flight statuses you support) in the active set, or deriving this from a shared status enum/constant list to avoid drift.

peterj · 2026-03-10T21:19:05Z

internal/cli/agent/utils/registry_translator.go

+			Packages:    serverSpec.Packages,
+			Remotes:     serverSpec.Remotes,
+		},
+		PreferRemote: preferRemote,


can we remove this preferremote?

i would leave this for anotehr follow up... the scope of this pr is also quite large

we need to sit and design the replacement

internal/cli/agent/build.go

peterj · 2026-03-10T21:25:16Z

internal/mcp/registryserver/server.go

+	ServerName   string            `json:"serverName" required:"true"`
+	Version      string            `json:"version" required:"true"`
+	Env          map[string]string `json:"env,omitempty"`
+	PreferRemote bool              `json:"preferRemote,omitempty"`


remove prefereremote

removing preferRemote is a significant change to the api / behavior of the registry today. i think it deserves its own design+pr (which i was planning on addressing after all the deployment stuff is done)

peterj · 2026-03-10T22:11:36Z

internal/registry/platforms/kubernetes/deployment_adapter_kubernetes_platform.go

+	return servers, nil
+}
+
+func kubernetesTranslatePlatformConfig(ctx context.Context, desired *platformtypes.DesiredState) (*platformtypes.KubernetesPlatformConfig, error) {


any reason all these functions are prefixed with "kubernetes" -- they are in the kubernetes package already

personally i prefer this for searches; makes it easier when trying to find the right file. is this a strong ask?

peterj · 2026-03-10T22:12:07Z

internal/registry/platforms/kubernetes/deployment_adapter_kubernetes_platform.go

+	return servers, nil
+}
+
+func kubernetesTranslatePlatformConfig(ctx context.Context, desired *platformtypes.DesiredState) (*platformtypes.KubernetesPlatformConfig, error) {


also, the file naming looks odd -- why not just name the file "platform.go" without the "deployment_adapter_"

same as above wrt easier for searches

peterj · 2026-03-10T23:41:55Z

internal/registry/platforms/local/deployment_adapter_local.go

+}
+
+func (a *localDeploymentAdapter) Discover(_ context.Context, _ string) ([]*models.Deployment, error) {
+	return []*models.Deployment{}, nil


if this is something we'll implement, let's add a TODO here, so we don't forget.

i don't think we will implement this; it is needed just to implement the interface

internal/registry/registry_app.go

peterj · 2026-03-10T23:53:08Z

AGENTS.md

@@ -1,450 +0,0 @@
-# AGENTS.md - Development Guidelines
-
-This document provides guidelines for both AI coding assistants (Claude, Copilot, Cursor, etc.) and human developers working on the AgentRegistry codebase.


why was this deleted?

whoops, unintended, restoring

not sure why it still shows as deleted but it is re-added in my pr 266df2e

peterj

add a couple of comments, I'll try to test it in the morning

ilackarms added 30 commits February 27, 2026 14:14

api refactor:

641b5dc

- finish rename config -> env - call deployment adapters from within registry service - add extraroutes

Merge branch 'main' into api-refactor-7.2

438ccae

Merge branch 'main' into api-refactor-7.2

94f3c86

test fixes

56224b1

fix lint

34c0db1

pr feedback

e410b5c

go mod tidy

b39a0e9

clean up client methods and add test

02abcb7

fix deployment response, fix deployment id

35831d6

Merge branch 'main' into api-refactor-7.2

ef446cc

pr feedback

0f821a7

go mod tidy

843e0e2

lint

84b2c06

migrate to using deployment id as primary key, support multiple deplo…

be20cfb

…yments per server

separate kube specific code from registry service

5ea85af

fix multiple deployments for local runtime

56c26b3

pr feedback

224bcca

pr feedback

932f523

Merge branch 'main' into api-refactor-7.2

c4baeb6

fix bad merge

d44f209

lint

cb190f0

fix e2e test

1a54c35

fix unit test

34a131f

ensure agent-resolved mcp servers are part of runtime desired state

bafb6ce

Merge branch 'main' into api-refactor-7.2

80be73d

separate kube specific code from registry service

4ef8d54

extract all platform specific code to adapters

dbcf668

complete adapter decoupling and enforce provider-driven deployments

91cafa0

fix deployment name suffix

481073f

Merge branch 'fix-kubernetes-delete-bug' into api-refactor-8

3f70e69

ilackarms added 4 commits March 10, 2026 13:50

lint

49e48ed

propagate cmd ctx, remove unused db method

a913c00

e2e test fix

78d4265

flag not required

feb5989

ilackarms marked this pull request as ready for review March 10, 2026 21:08

Copilot AI review requested due to automatic review settings March 10, 2026 21:08

Copilot started reviewing on behalf of ilackarms March 10, 2026 21:09 View session

lint

d52efa2

Copilot AI reviewed Mar 10, 2026

View reviewed changes

peterj reviewed Mar 10, 2026

View reviewed changes

internal/cli/agent/build.go Show resolved Hide resolved

peterj reviewed Mar 10, 2026

View reviewed changes

catalog metadata includes all deployments

792bc77

peterj reviewed Mar 10, 2026

View reviewed changes

internal/registry/registry_app.go Outdated Show resolved Hide resolved

peterj reviewed Mar 10, 2026

View reviewed changes

ilackarms added 3 commits March 10, 2026 19:59

readd agents.md

266df2e

remove stale

444783a

respect supported resource types

298a99e

peterj approved these changes Mar 11, 2026

View reviewed changes

ilackarms added 2 commits March 11, 2026 12:21

add unit test

840fea3

Merge branch 'main' into api-refactor-8

f38938e

timflannagan approved these changes Mar 11, 2026

View reviewed changes

peterj added this pull request to the merge queue Mar 11, 2026

Merged via the queue into main with commit d272053 Mar 11, 2026
8 of 9 checks passed

peterj deleted the api-refactor-8 branch March 11, 2026 17:06

		@@ -1,450 +0,0 @@
		# AGENTS.md - Development Guidelines

		This document provides guidelines for both AI coding assistants (Claude, Copilot, Cursor, etc.) and human developers working on the AgentRegistry codebase.

Conversation

ilackarms commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Change Type

Changelog

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

peterj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

ilackarms commented Mar 6, 2026 •

edited

Loading