feat: dependency management — external, cross-project, and platform-provisioned dependencies; new agent-service as default

[kaje94]

Adds dependency management to the platform: components can now declare what they need — a sibling component, another project's shared service, a third-party API, or platform-provisioned infrastructure — and the platform discovers, resolves, gates, provisions, and wires those needs automatically, end to end. The feature was proven in the previous-generation codebase (#63) and is brought into the rewrite here, restructured around OpenChoreo's own Workload taxonomy rather than ported verbatim.

It also completes the agent-service cutover: the new services/agents now serves architect, document-generation, and task-planner on the same wire contract the BFF already speaks, and ships as the compose default (the legacy service stays in-tree for rollback).

The feature in one flow

A component declares what it needs; the platform knows how to satisfy each kind; nothing deploys until every need is met — and nothing is ever wired by hand.

flowchart LR
    subgraph Design
        P[Prompt] --> A[Architect agent]
        A -- "MCP discovery:<br/>external resources, org endpoints,<br/>platform resource types" --> C[(Org catalogs)]
        A -- "web_search fallback" --> W((Web))
        A --> D["design.json<br/>dependencies[]"]
    end
    subgraph Resolve
        D --> G{Proceed-gate<br/>409 until resolved}
        G -- "external: spec + values → OpenBao" --> R1[Drawer]
        G -- "platform-resource: Provision → CNPG" --> R1
        G -- "org-service: catalog / access request" --> R1
    end
    subgraph Deliver
        G --> T["Typed task graph<br/>(config-collection, resource-provisioning gates)"]
        T --> DIS[Dispatch]
        DIS -- "platform-resolved comment" --> CA[Coding agent]
        CA -- "authors workload.yaml<br/>(declarative wiring)" --> DEP[Deploy]
        DEP -- "cascade releases held siblings" --> DIS
    end

Loading

The four dependency kinds

Kind	Satisfied by	Wired via
component	Sibling component in the project	WorkloadConnection (endpoints)
org-service	Another project's org-published component (project-prefixed catalog name)	WorkloadConnection, cross-namespace env injection
external	Third-party service; org-registered schema + per-project values (secrets → OpenBao via SM-API, never the DB)	OC Resource model → ResourceReleaseBinding → ExternalSecret → pod env
platform-resource	Platform-provisioned infra from a typed catalog (postgres-cnpg via CNPG operator, readyWhen-gated)	OC Resource model, binding pinned to controller-cut release

Two load-bearing decisions (ADR-0003/0004 in docs/decisions/):

• Read-time resolution — status/reason are computed on every read against live platform state and are structurally unrepresentable in design.json. No stale status, ever.
• Declarative wiring — dispatch posts a "Platform-resolved dependencies" comment on the task issue; the coding agent copies it verbatim into workload.yaml. The platform never patches a deployed Workload CR; git checkout reproduces the running system.

Architecture

flowchart TB
    subgraph console["console-legacy"]
        DR[DependencyDrawer + 5 panels]
        BB[Board CTAs → ?dep= deep-link]
        ST[External resources settings]
    end
    subgraph api["aep-api — internal/feature/dependencies/"]
        MCP["MCP server (authenticated,<br/>4 discovery tools, OC service identity)"]
        subgraph EP[endpoints/]
            CAT[Org endpoint catalog]
            ACC[Access requests<br/>single-owner state machine]
        end
        subgraph RES[resources/]
            REG[External registry + values]
            PROV[Two provisioners<br/>external / platform]
        end
    end
    subgraph agents["services/agents (NEW — compose default)"]
        AR[architect route + web_search]
        DG[document-generation route]
        TP["task-planner (plan/detail)<br/>guided by skills/task-breakdown"]
    end
    OC[(OpenChoreo<br/>Workload / Resource / Bindings)]
    BAO[(SM-API → OpenBao)]
    console --> api
    api -- "mcp {url, token} per call" --> agents
    agents -- "tools/call" --> MCP
    RES --> OC
    RES --> BAO
    EP --> OC

Loading

Task lifecycle is event-driven through internal/contracts (the Projector is the sole status writer): values.provisioned, provision.started, resource.ready, resource.provision_failed. SYSTEM rows (config-collection, resource-provisioning) gate component tasks via three depends_on_* JSONB columns; deploy events cascade-release held siblings — the whole chain runs hands-off (verified live: values save → gate deployed → CNPG Ready → watcher → cascade → dispatch, zero clicks).

Agent-service cutover

services/agents now serves the full BFF wire surface — cutover was literally the compose build-context flip, kept as the default per live E2E:

• POST /internal/v1/agents/architect — the design core under the legacy SSE contract, MCP-catalogs-first discovery with an Anthropic web_search fallback for externals not found locally.
• POST /internal/v1/agents/document-generation/{skillId} + /internal/v1/dsl/render — all 8 doc-gen skills ported byte-identical; DSL rendering reuses the shared @aep/excalidraw-dsl package.
• POST /internal/v1/agents/task-planner/{plan,detail} — renamed from "tech lead" (it plans, it doesn't manage); judgment lives in the new repo-root skills/task-breakdown/SKILL.md (leading words: topological order, gate, brief; authored TDD-style with a RED baseline), pushed by callers exactly like other skills; shape stays in the schema/scaffolding. A Go test guards byte-identity between the repo-root skill and the aep-api embed.

services/agents-legacy is untouched and stays in-tree for rollback until post-merge cleanup.

Verification — live E2E on a fresh k3d stack

Every scenario was driven through the real console in a browser (agent-browser) against a fresh local cluster — first on the legacy agent service, then re-run after the cutover:

Scenario	Proof
Third-party API (weather service + SPA)	Live OpenWeatherMap data; API key present in pod env, 0 occurrences in HTML/bundle
Registry reuse + credential rotation	Architect reused registered resource by exact name; key rotation re-pinned vault→binding→Secret (pod restart caveat noted)
Cross-project shared service	Consumer discovered provider via catalog, called it cross-namespace using only the injected env var
Org settings / registry management	Consumers listed, in-use delete blocked
Storefront demo (all four kinds in one project)	One POST: catalog price × live FX rate → row in platform-provisioned Postgres (verified by direct psql); repeated end-to-end on the new agent service

The E2E runs caught and fixed real defects the test pyramid could not: an MCP identity bug that silently emptied every discovery catalog in production paths, a reconcile hang on idempotent re-saves, an OC authz binding skipped by helm-recovery, and two Thunder 1.1.1 bootstrap breaks. Both agent services independently hallucinated the identical wrong FX API path — systematic model-prior evidence for defaulting needsSpec: true on unregistered externals (follow-up).

Docs

CONTEXT.md (ubiquitous language: dependency kinds, resolution, gate, discovery, task-planner — "connection" is banned vocabulary), docs/glossary.md, ADR-0003/0004, services/aep-api/design/dependencies.md, services/agents/design/task-planner-contract-parity.md.

⚠️ Open questions for reviewers

1. Agent→BFF authentication is deliberately NOT settled. The current mechanism (aep-api mints short-TTL MCP tokens per call, caller-supplied {url, token}) works but is not confirmed as the chosen model — needs a team decision before we harden it (mid-run refresh, service identity posture). Please treat it as provisional. For local development only, a flag-gated POST /internal/v1/mcp/playground-token endpoint (PLAYGROUND_TOKEN_ENABLED, default false, set only by docker-compose; never mounted otherwise, helm pins it false) lets the playground auto-mint a fresh token per turn — verified live against the four dependency discovery/breakdown checks. It deliberately does not prejudge the production model.
2. @sachiniSam — this replaces the provisional connections[] in ComponentDesign with the unified dependencies[] (status/reason excluded from the schema by design). One divergence to decide together: the Go codec marks base scalars (exposure sharpest) omitempty while the TS schemas require them — either relax TS or commit aep-api to always populating them.
3. New-console parity is tracked in New console parity: dependency-management UI (drawer, board CTAs, settings, diagram) #84 (the console changes land in console-legacy per the current wiring).

Notable follow-ups

• needsSpec default-true for unregistered externals (prevents hallucinated API paths)
• Secret rotation needs an automatic rollout (env-from-secret doesn't hot-reload)
• Failed builds have no self-service rebuild path (retry re-runs the whole coding agent)
• RetryTask backend guard for SYSTEM tasks; AutoMigrate-before-RunAll ordering (phase9's component_tasks section is currently shadowed by boot-time AutoMigrate — documented in-code)
• New service: per-org Anthropic key resolver at boot; usage counts not plumbed into architect route logs

🤖 Generated with Claude Code

https://claude.ai/code/session_01HaM9hGtqua4ZC2bKD2d2Fq

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 30575424-7905-47d8-8c1f-aec23bc9c99a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• ✅ Review completed - (🔄 Check again to review again)

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch aep-rewrite-kaj

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}