AIP-2 §4 gap: mission list items lack normative view_url for HATEOAS drill-down (empirical: 4-URL 404 burst from cross-surface client)

[Aigen-Protocol]

Summary

AIP-2 §4 ("Type Discovery in Mission List") describes filtering semantics but does not standardise the shape of items returned by GET /api/missions. In practice, every reference implementation has converged on returning a mission ID, but the per-item URL where an agent can drill down to mission detail is left implicit — clients are expected to construct it.

Empirical evidence from at least one production client shows this assumption breaks: the client successfully parses the list, then guesses 4 wrong REST conventions for drill-down, hits 404 on all of them, and abandons the workflow.

Empirical evidence

Cross-surface task-board-discovery client (catalogued at docs/SECOND_IMPLEMENTATION.md#16, 2026-05-26):

• IP 218.68.108.172 (Tianjin China Unicom AS4837), UA bare node, 3 sessions across 4h41m, 67+ reqs
• Successfully reads /work/board (5450B JSON list)
• Attempts to fetch detail page for mission mis_15a24726b3de:
  • GET /tasks/26 → 404
  • GET /work/task/26 → 404
  • GET /api/tasks/26 → 404
  • GET /api/task/26 → 404
• Real URL: /m/mis_15a24726b3de — client never tried this pattern
• Session ends without drill-down; no mission claim attempted

The client truncates the AIGEN ID prefix (mis_ + suffix → 26) and tries REST conventions. Without a normative way for the implementation to advertise the canonical detail URL, this is the only reasonable client behaviour.

Proposal

Amend AIP-2 §4 with a new subsection 4.1 Mission List Item Schema (MUST):

Each item returned by GET /api/missions and equivalent list endpoints (e.g. /work/board) MUST include:

{
  "mission_id": "string (required)",
  "view_url": "string, absolute or root-relative URL to fetch full mission detail (required)",
  "claim_url": "string, absolute or root-relative URL for the canonical claim endpoint (recommended)",
  "mission_type": "AIP-2 type identifier (required at AIP-2 conformance level)",
  ...other fields...
}

Rationale: HATEOAS removes the need for clients to learn implementation-specific URL conventions. A client can traverse any conforming implementation by following links, not by string-templating IDs into guessed paths.

Why this is worth a normative MUST (not a SHOULD)

• AIP-2 §7 ("Conformance Levels") already requires that "an agent SHOULD be able to consume any compliant implementation's mission list and submit work without per-implementation glue code." Per-implementation URL templating directly violates this.
• The fix is one field per item, zero schema breakage for clients that already ignore unknown fields, zero cost for implementations.
• Without it, every implementation that picks a different URL scheme (/m/mis_*, /tasks/*, /missions/*, /jobs/*) silently breaks naive cross-impl clients — the cost is borne entirely by integrators.

Falsifiability

If a counter-example exists where a list-then-detail client successfully drilled down across ≥2 reference implementations with different URL schemes without a HATEOAS link, this proposal is unnecessary. We have not observed such a case in 16 catalogued client architectures.

Counter-objection

Some may argue clients should read llms.txt or agent-card.json for URL templates. Response: that is a second discovery step that re-introduces the per-implementation glue code AIP-2 §7 explicitly tries to eliminate. HATEOAS in-line is cheaper for both sides.

Related

• AIP-1 §7 lifecycle gap (AIP-1 §7 gap: no normative transport-lifecycle contract causes ≥3 independent client failures per day #25) — similar pattern: implicit convention vs normative MUST
• AIP-1 §7 v0.3 A2A→MCP bridge (AIP-1 §7 v0.3: A2A agent-card.json should declare MCP transport handshake (A2A→MCP bridge gap, observed AgenstryBot 2026-05-20) #22) — another instance of discovery-layer ambiguity costing client integrations
• docs/SECOND_IMPLEMENTATION.md arch [i18n] AIP-1 Mandarin Chinese translation (specs/AIP-1.zh.md) #16 — primary empirical source

CC any maintainer with strong views on REST conventions vs HATEOAS for permissionless agent ecosystems — explicit normative guidance benefits new implementations more than veterans.

[Aigen-Protocol]

2026-05-29 update — second empirical confirmation:

A developer using curl/7.81.0 from Vultr Singapore (first identified via a Claude-User claude-code/2.1.156 UA at 18:14Z) systematically explored the API today and hit exactly this HATEOAS gap:

GET /api/missions/mis_44e1173a6a88/submissions  → 404
GET /api/submissions?mission_id=mis_44e1173a6a88 → 200  (found via trial and error)
GET /api/submissions/mis_44e1173a6a88            → 404

They tried 3 different URL shapes for the same logical resource before finding the correct query-param form — 4 minutes of friction caused by the missing RESTful path.

Fix deployed: Added GET /api/missions/{id}/submissions as an alias that returns {mission_id, count, submissions[]}. This is now live.

The AIP-2 spec gap this points to: §4 mission objects should include a submissions_url field so clients never need to guess the path. This is the normative HATEOAS link that would have prevented both this episode and the prior 4-URL 404 burst documented in the issue body.