fix(a2a): serve agent-card discovery at the standard well-known path

[khaliqgant]

Split out of the Phase 2 federation work (#318) so it can ship on its own — it affects any A2A counterparty, not just that engagement.

Current production behaviour

Agent-card discovery is where A2A federation starts, and it does not work today on any deployment whose workspace is not named after the first label of its hostname. Verified against cast.agentrelay.com, whose workspace is actually named rw_7ccfea89:

GET /.well-known/agent-card.json                        -> 404 workspace_not_found
GET /.well-known/agent-card.json?workspace=rw_7ccfea89  -> 200
GET /rw_7ccfea89/.well-known/agent-card.json            -> 404 workspace_not_found
GET /.well-known/agent-card.json  (Authorization: Bearer …)  -> 200

Two defects, one root cause

extractWorkspaceHint resolved query → host label → path param, and the unauthenticated card handler had no other source.

1. The documented /:workspace/.well-known/agent-card.json route was dead on any authority with three or more labels — host inference always answered first, so the path parameter was never read. The Relay identifier profile requires multi-label, non-loopback authorities, so every conformant deployment sits exactly where that escape hatch cannot work.
2. A single-tenant self-host could not answer the bare standard URL at all — the one an A2A counterparty tries first.

POST /a2a/rpc is unaffected; it authenticates and takes the workspace from the token. That is what made this narrow and misleading: discovery 404s while everything authenticated succeeds, and the error text blames agent registration.

The fix

• An explicit path selector now beats host inference.
• The card handler falls back to the sole workspace when a deployment has exactly one.
• The fallback is skipped whenever a query or path selector was supplied, so a misspelled selector fails loudly instead of quietly resolving to another tenant.
• The candidate query is bounded to , so a multi-tenant deployment fails closed without scanning the workspace table.

Regression risk, and the test that covers it

This reorders live routing. The test that makes it safe to ship is "keeps a valid hosted workspace subdomain authoritative" — hosted multitenancy behaviour is unchanged.

Six tests total; the two subtle ones assert that the fallback never papers over a caller error.

Verification

• packages/engine full suite: 558 passed (558), 52 files — no regressions
• a2a.test.ts: 33/33

🤖 Generated with Claude Code

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 41c14fc7-bc26-40df-8889-8a2a3be7c3c9

📥 Commits

Reviewing files that changed from the base of the PR and between 5bd11af and 4349727.

📒 Files selected for processing (1)

• openapi.yaml

🚧 Files skipped from review as they are similar to previous changes (1)

• openapi.yaml

---

📝 Walkthrough

Walkthrough

Workspace agent-card discovery now prioritizes explicit path selectors and supports bare well-known URLs for single-workspace deployments. API documentation, route classification, integration tests, and changelogs describe the updated behavior.

Changes

Workspace agent-card discovery

Layer / File(s)	Summary
Workspace selector resolution packages/engine/src/routes/a2a.ts	Path workspace parameters take precedence over host inference. Bare well-known URLs fall back to the sole workspace only when the lookup returns one workspace.
Discovery validation and API documentation packages/engine/src/engine/__tests__/a2a.test.ts, README.md, openapi.yaml, packages/types/src/__tests__/sdk-openapi-sync.test.ts	Tests cover host and path selection, selector precedence, single-workspace fallback, and fail-closed 404 responses. README and OpenAPI document both routes and workspace resolution.
Release notes CHANGELOG.md, packages/engine/CHANGELOG.md	Changelogs classify the workspace agent-card routing fixes as unreleased patches.

Estimated code review effort: 2 (Simple) | ~10 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Client
  participant handleWorkspaceAgentCard
  participant extractWorkspaceHint
  participant WorkspaceLookup
  Client->>handleWorkspaceAgentCard: Request agent card
  handleWorkspaceAgentCard->>extractWorkspaceHint: Resolve path or host workspace
  handleWorkspaceAgentCard->>WorkspaceLookup: Query up to two workspaces
  WorkspaceLookup-->>handleWorkspaceAgentCard: Return workspace match or ambiguity
  handleWorkspaceAgentCard-->>Client: Return agent card or workspace_not_found

Loading

Suggested labels: size:L

Poem

A rabbit checked the path first,
Then checked the host when nothing stirred.
One workspace served the card with care,
Ambiguous choices stopped there.
Selectors now resolve just right!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: fixing A2A agent-card discovery at the standard well-known path.
Description check	✅ Passed	The description directly explains the A2A discovery defects, workspace resolution changes, regression coverage, and verification results.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/a2a-agent-card-discovery

---

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.}

[devin-ai-integration]

Devin Review found 2 potential issues.

View 1 additional finding in Devin Review.

[devin-ai-integration]

🟡 Discovery endpoint behaviour changed without matching API documentation updates

The public agent-card discovery endpoint changed how it picks a workspace (new sole-workspace fallback added at packages/engine/src/routes/a2a.ts:244-253 and reordered selection at packages/engine/src/routes/a2a.ts:65-80) without the required matching updates to README.md and openapi.yaml, so the published API description no longer matches the server.
Impact: Integrators reading the docs cannot tell how discovery resolves a workspace, including the /:workspace/ path form and the ?workspace= selector.

Repository documentation rule and what is missing

AGENTS.md ("Docs Hygiene") mandates: "Update README.md and openapi.yaml together when API behavior changes." This PR changes observable behaviour of GET /.well-known/agent-card.json (a bare request on a single-workspace deployment now returns 200 instead of 404) and makes the /:workspace/.well-known/agent-card.json route functional for the first time on multi-label authorities. README.md:652 lists only the bare route, and openapi.yaml:4796-4810 documents no workspace query parameter, no path-scoped variant, and no 404 workspace_not_found response. Neither file is touched by this PR.

Prompt for agents

AGENTS.md requires README.md and openapi.yaml to be updated together whenever API behaviour changes. This PR changes the behaviour of GET /.well-known/agent-card.json (single-workspace deployments now answer the bare path; an explicit /:workspace/ path selector now takes precedence over host inference) but does not touch the docs. Update openapi.yaml's /.well-known/agent-card.json entry to document the optional ?workspace= query parameter, the /:workspace/.well-known/agent-card.json path variant, and the 404 workspace_not_found response, and add the path-scoped route to the A2A route list in README.md.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[devin-ai-integration]

🟨 Unauthenticated agent-card discovery can leak a workspace's agent roster when host selector is wrong

The unauthenticated discovery handler now falls back to the only workspace in the database whenever no query/path selector is present (packages/engine/src/routes/a2a.ts:244-253). This fallback also triggers when a host-label selector was supplied but did not resolve, so any request to any hostname on a deployment holding exactly one workspace returns that workspace's card, which enumerates every agent name in the workspace (getWorkspaceAgentCard). On the hosted gateway this makes an internal workspace's agent roster reachable without credentials at a time when the table holds a single workspace.

---

Was this helpful? React with 👍 or 👎 to provide feedback.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@CHANGELOG.md`:
- Line 23: Shorten the release-note bullet in CHANGELOG.md at lines 23-23 to one
concise, impact-first statement covering standard agent-card discovery and
explicit workspace path selection. Also shorten packages/engine/CHANGELOG.md at
lines 14-14 to one concise bullet describing the workspace-selection contract;
remove failure mechanisms, private helper names, query details, and
implementation backstory from both entries.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2102354e-b708-48c5-8e18-649b38ac03fe

📥 Commits

Reviewing files that changed from the base of the PR and between eb7563f and 37be358.

📒 Files selected for processing (4)

• CHANGELOG.md
• packages/engine/CHANGELOG.md
• packages/engine/src/engine/__tests__/a2a.test.ts
• packages/engine/src/routes/a2a.ts

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 37be358d22

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Update README and OpenAPI with the discovery contract

This changes the public agent-card resolution contract by adding sole-workspace fallback and making the path selector authoritative, but README.md still lists only the root route and openapi.yaml documents neither selector nor fallback/error semantics. Consumers therefore cannot discover the supported /:workspace/ form or determine when the bare URL returns 404; update both sources alongside this behavior change.

AGENTS.md reference: AGENTS.md:L35-L35

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Treat an empty workspace query as explicit

When a deployment has exactly one workspace and a caller sends ?workspace=, the query value is an empty string, so both extraction and this truthiness guard treat the selector as absent and return the sole workspace's card. This silently replaces a malformed explicit selector despite the new fail-loud contract; test parameter presence separately from whether its value is nonempty so this request returns workspace_not_found.

Useful? React with 👍 / 👎.

[cubic-dev-ai]

1 issue found across 4 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="packages/engine/src/routes/a2a.ts">

<violation number="1" location="packages/engine/src/routes/a2a.ts:246">
P3: An empty `?workspace=` selector is treated as absent and returns the sole workspace card rather than failing closed. Check query-key presence in the fallback guard so supplied-but-empty selectors produce `workspace_not_found`.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: An empty ?workspace= selector is treated as absent and returns the sole workspace card rather than failing closed. Check query-key presence in the fallback guard so supplied-but-empty selectors produce workspace_not_found.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At packages/engine/src/routes/a2a.ts, line 246:

<comment>An empty `?workspace=` selector is treated as absent and returns the sole workspace card rather than failing closed. Check query-key presence in the fallback guard so supplied-but-empty selectors produce `workspace_not_found`.</comment>

<file context>
@@ -228,6 +235,23 @@ async function handleWorkspaceAgentCard(c: Context<AppEnv>) {
+    // closed without scanning the workspace table.
+    if (
+      !workspace
+      && !c.req.query('workspace')
+      && !c.req.param('workspace')
+    ) {
</file context>

Suggested change

	&& !c.req.query('workspace')
	&& !new URL(c.req.url).searchParams.has('workspace')

[khaliqgant]

Review addressed in ada0cff. Engine suite 559/559 across 52 files.

Devin — docs parity. Correct, and it is a repo rule I missed. openapi.yaml now documents the resolution order, the ?workspace= selector, the path-scoped route as its own path item, and the 404 workspace_not_found response on both forms. README.md lists the path-scoped route.

Devin — sole-workspace fallback firing after an unresolved host label. Keeping this, deliberately, and the reasoning is now in the code rather than implied.

The guard distinguishes two things that look alike. An explicit ?workspace= or /:workspace/ is caller intent, so a typo must 404 rather than resolve to another tenant. Host-label inference is not caller intent — it is the hosted workspace-per-subdomain convention, and on any authority with three or more labels it always yields a candidate. The Relay identifier profile requires multi-label authorities, so treating an inferred label as an explicit selector would mean the fallback never fires on precisely the deployments it exists for. That would reinstate the bug this PR fixes.

The row cap is the real boundary: with two or more workspaces the fallback declines rather than guessing, so there is no tenant boundary to cross. On a deployment holding exactly one workspace there is only one tenant, and the card is unauthenticated by design — that is what A2A discovery is.

Rather than leave that as an argument, it is now asserted both ways:

• serves the sole workspace even when an unresolved host label was inferred — new, states the single-tenant behaviour as intent
• fails closed on a bare multi-tenant deployment instead of selecting a workspace — pre-existing, and it is the same request shape (host label cast against workspaces named northwind/borealis), returning 404

CodeRabbit — changelog concision. Fair; both entries were carrying implementation backstory. Trimmed to one impact-first bullet each.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@openapi.yaml`:
- Line 4820: Update the workspace parameter description in the OpenAPI
specification to avoid saying it is required for every multi-tenant deployment;
state that it is required only when the workspace cannot otherwise be resolved,
while preserving support for valid hosted workspace subdomains.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: a652e509-6b31-494f-b3e7-295f68a6f0c8

📥 Commits

Reviewing files that changed from the base of the PR and between 37be358 and 5bd11af.

📒 Files selected for processing (7)

• CHANGELOG.md
• README.md
• openapi.yaml
• packages/engine/CHANGELOG.md
• packages/engine/src/engine/__tests__/a2a.test.ts
• packages/engine/src/routes/a2a.ts
• packages/types/src/__tests__/sdk-openapi-sync.test.ts

🚧 Files skipped from review as they are similar to previous changes (4)

• packages/engine/CHANGELOG.md
• CHANGELOG.md
• packages/engine/src/routes/a2a.ts
• packages/engine/src/engine/tests/a2a.test.ts

[khaliqgant]

CodeRabbit — workspace is not required on every multi-tenant deployment. Correct; the description was wrong. A valid workspace subdomain resolves on its own, as the integration test shows (northwind.cast.example/.well-known/agent-card.json → 200, no query parameter).

Fixed in 4349727. The endpoint description had the same ambiguity — "unless a selector identifies it" read as excluding the host label, which is one of the four resolution mechanisms listed a line above it. Both now say a valid workspace subdomain is sufficient on its own, while keeping the part that matters: an explicit query or path selector that does not resolve still 404s rather than falling back to another workspace.