Skip to content

openapi: /v1/loop/* idea/task-graph family (5 routes, excl. request-apr-transfer) missing from spec #9309

Description

@JSONbored

⚠️ Definition of Done: this issue must be completed in full, in a single PR. Do not split this
work across multiple PRs, and do not defer any Deliverable below to a follow-up issue. A PR that
satisfies only some of the Deliverables, stubs a required test, or leaves a checkbox
partially-done does NOT resolve this issue and will be closed.

⚠️ Required pattern: mirror how GET /v1/repos/{owner}/{repo}/gate-config/effective is documented
in src/openapi/spec.ts — issue #6611 fixed the exact same class of gap for that route — applied
uniformly across all five routes below.

Context

src/api/routes.ts groups five idea/task-graph POST routes under /v1/loop/*, each backed by an
MCP tool with its own Zod output shape already defined in src/mcp/server.ts:

Route MCP tool Output shape
POST /v1/loop/evaluate-escalation loopover_evaluate_escalation evaluateEscalationOutputSchema
POST /v1/loop/results-payload loopover_build_results_payload buildResultsPayloadOutputSchema
POST /v1/loop/progress-snapshot loopover_build_progress_snapshot buildProgressSnapshotOutputSchema
POST /v1/loop/intake-idea loopover_intake_idea intakeIdeaOutputSchema
POST /v1/loop/plan-idea-claims loopover_plan_idea_claims planIdeaClaimsOutputSchema

None of the five appears in src/openapi/spec.ts — grep for /v1/loop/ in that file returns
nothing. Each route's own code comment in src/api/routes.ts explicitly documents it as "the REST
mirror of the loopover_* MCP tool," confirming these are meant to be a fully parallel surface, not
an internal-only shortcut.

Note: POST /v1/loop/request-apr-transfer (in the same file, same /v1/loop/* prefix) is
intentionally excluded from this issue — it's a customer-facing funds/transfer-initiation route
with its own dedicated anti-abuse hardening (see the #7742/#8000 comments above that route in
src/api/routes.ts) and should not be bundled with this batch of pure, source-free composer routes.

Requirements

  • In src/openapi/schemas.ts, define one z.object({...}) response schema per route (5 total,
    e.g. EvaluateEscalationResponseSchema, BuildResultsPayloadResponseSchema,
    BuildProgressSnapshotResponseSchema, IntakeIdeaResponseSchema, PlanIdeaClaimsResponseSchema),
    using each route's existing MCP outputSchema constant (table above) as the field-level source of
    truth. Also add request-body schemas mirroring each tool's corresponding inputSchema/shape
    constant in src/mcp/server.ts.
  • In src/openapi/spec.ts, registry.register all five response schemas as components, then add a
    registerPath entry for each of the five routes.
  • Schema is the contract — regenerate and commit. Run npm run ui:openapi after the edits and
    commit the regenerated apps/loopover-ui/public/openapi.json in this same PR. CI enforces this via
    npm run ui:openapi:check (part of npm run test:ci).

Deliverables

  • Five new response schemas (plus matching request-body schemas) added to
    src/openapi/schemas.ts, one per route in the table above.
  • All five routes registered as OpenAPI paths in src/openapi/spec.ts.
  • apps/loopover-ui/public/openapi.json regenerated via npm run ui:openapi and committed.
  • npm run ui:openapi:check passes in CI.

All five routes are required in this one PR — there is no follow-up issue. request-apr-transfer is
explicitly out of scope for this issue (see Context) — do not add it.

Test Coverage Requirements

99%+ Codecov patch target (codecov/patch, unsharded via npm run test:coverage) on any new schema
helper code. Add a regression test asserting all five paths appear in buildOpenApiSpec()'s output
with response schemas whose keys match each route's MCP tool output shape from the table above.

Expected Outcome

The /v1/loop/* idea/task-graph route family (excluding request-apr-transfer) is documented in
GET /openapi.json / apps/loopover-ui/public/openapi.json, matching what each route's MCP tool
already validates.

Links & Resources

Metadata

Metadata

Assignees

No one assigned

    Labels

    gittensor:bugGittensor-scored bug fix — scores a 0.05x multiplier.help wantedExtra attention is needed

    Projects

    No projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions