[PDT42]

• Lazy exposure of compile logic via lib/api.js, symmetric to https://github.com/cap-js/mcp/blob/main/lib/api.js
• Dropped support for @Core.Links
• Dropped support for @agent.card, as it was not considered in any other place that needs to resolve the AGENTS.md to use

[PDT42]

Why do we need this?

[Akatuoro]

@schiwekM are you using this? We now typically get the actual url via req.headers["x-forwarded-proto"]

[schiwekM]

We use it because if the CAP service is behind a proxy the wrong URL was advertised before and then Joule made wrong requests. If the url gets replaced by a relative path property that would be ideal and would avoid these workarounds.

[Akatuoro]

Does Joule support relative URLs?

According to A2A:
"For HTTP-based transports, must be a valid absolute HTTPS URL in production"
https://a2a-protocol.org/latest/specification/#446-agentinterface

[Akatuoro]

We noticed the following situation (approuter / dwc approuter):

client --> approuter --> srv (agent)

The agent card will contain the srv url, but the client can only access the approuter. Here we still need a way for the agent to customize the host.

[Akatuoro]

> cds.compile.to.a2a(cds.model, { service: 'CatalogService' })
{
  name: 'CatalogService',
  description: 'Agent for CatalogService',
  url: 'https://HOST/a2a/catalog',
  version: '1.0.0',
  protocolVersion: '0.3.0',
  supportedInterfaces: [
    {
      url: 'https://HOST/a2a/catalog',
      protocolBinding: 'JSONRPC',
      protocolVersion: '0.3.0'
    }
  ],

Host is still unresolved when calling cds.compile.to.a2a. This is how we fill it in at the endpoint:

agents/lib/index.js

Lines 166 to 168 in 95bce97

	router.get("/.well-known/agent-card.json", (req, res) => {
	const proto = req.headers["x-forwarded-proto"]?.split(",")[0].trim() || req.protocol
	const url = proxyUrl || `${proto}://${req.get("host")}${req.baseUrl}`

Just noting it. @PDT42 do you know if ORD will fill urls in themselves?

[hyperspace-pr-bot]

🔍 PR Review — feat: ord plugin compat

🔴 Action required (1 open, 4 total)

Category	Finding	File
⚙️ Correctness	Adapter path override is omitted from the base card	lib/index.js:106
⚙️ Correctness	Feature cards still compile the base service definition	lib/index.js:164
⚙️ Correctness	Skills are skipped when AGENTS.md has no frontmatter	protocol/agent-card.js:124
⚙️ Correctness	Compile target cannot resolve the service's AGENTS.md	lib/compile.js:40

🟡 Suggestions (1 open, 4 total)

Category	Finding	File
⚙️ Correctness	Empty Example lines suppress the fallback example	protocol/agent-card.js:58
⚙️ Correctness	Changelog omits SKILL.md as an agent-card source	CHANGELOG.md:12
⚙️ Correctness	Changelog claims the compile function is exported	CHANGELOG.md:17
⚙️ Correctness	Changelog names the wrong Core annotation	CHANGELOG.md:13

🟢 Nitpicks (2 open, 4 total)

Category	Finding	File
✏️ Style	Agent-card JSDoc contains a grammatical typo	protocol/agent-card.js:137
✏️ Style	Helper name misidentifies a directory as a file	protocol/agent-card.js:121
⚙️ Correctness	`serviceUrl` documentation contradicts relative default	protocol/agent-card.js:146
✏️ Style	Misleading `compileCallActionSkill` name	protocol/agent-card.js:51

---

You're seeing this review as part of a pilot for our new /review+ experience. To help us continuously improve, check the feedback boxes on the comments below or share your thoughts in our Community channel.

---

PR Bot Information

Version: 1.33.19

• Correlation ID: 7ff0bd10-d3b9-11f1-94c2-f535e223d455
• LLM: gpt-5.6-sol
• File Content Strategy: Full file content
• Event Trigger: issue_comment.created
• Experiment Variant: treatment