Fix broad ref types in OpenAPI spec

[amikofalvy]

Summary

• Override drizzle-zod's permissive JSONB inference for ref fields with explicit ResolvedRefSchema in select and insert schemas for TriggerInvocation, ScheduledTriggerInvocation, DatasetRun, and EvaluationRun
• Updates OpenAPI snapshot so ref renders as $ref: ResolvedRef instead of anyOf: [string, number, boolean, null, object, array]

Context

Addresses review comment — drizzle-zod can't infer the TypeScript generic from jsonb().$type<ResolvedRef>(), so it falls back to a maximally permissive schema. The fix follows the same pattern already used by conversations, tasks, and contextCache.

Test plan

• pnpm --filter @inkeep/agents-api openapi:update-snapshot passes
• OpenAPI snapshot now shows $ref: "#/components/schemas/ResolvedRef" for both TriggerInvocation and ScheduledTriggerInvocation

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agents-api	Ready	Preview, Comment	Mar 16, 2026 7:30pm
agents-docs	Ready	Preview, Comment	Mar 16, 2026 7:30pm
agents-manage-ui	Ready	Preview, Comment	Mar 16, 2026 7:30pm

[changeset-bot]

⚠️ No Changeset found

Latest commit: 2c42721

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pullfrog]

Clean, focused fix. The .extend({ ref: ResolvedRefSchema }) / ref: () => ResolvedRefSchema overrides are consistent with the existing pattern used by conversations, tasks, and contextCache. The OpenAPI snapshot correctly narrows both TriggerInvocation and ScheduledTriggerInvocation ref fields. Update schemas inherit the override through .partial() as expected.

  ^{｜ View workflow run ｜ pullfrog.com ｜ 𝕏}

[claude]

PR Review Summary

(0) Total Issues | Risk: Low

✅ Clean Review

This PR correctly fixes drizzle-zod's inability to infer TypeScript generics from jsonb().$type<ResolvedRef>() by explicitly extending schemas with ResolvedRefSchema.

What the PR does well:

• Precisely targeted: Only fixes schemas that are actually exposed in OpenAPI (TriggerInvocation, ScheduledTriggerInvocation)
• Follows established patterns: Uses the same .extend({ ref: ResolvedRefSchema }) approach used elsewhere in the codebase
• Future-proofs insert schemas: Adds ref override to DatasetRunInsertSchema and EvaluationRunInsertSchema for consistency, even though their Select schemas aren't currently exposed in the API
• OpenAPI snapshot validates the fix: Changes from permissive anyOf: [string, number, boolean, null, object, array] to proper $ref: "#/components/schemas/ResolvedRef"

Verification notes:

• Confirmed DatasetRunSelectSchema and EvaluationRunSelectSchema do NOT need the ref override because their routes are commented out / not used in any API endpoint
• The fix is correctly scoped to only the schemas that appear in API responses

---

✅ APPROVE

Summary: Clean, well-targeted fix that addresses a drizzle-zod limitation for JSONB type inference. The PR correctly identifies which schemas need the override (those exposed in OpenAPI) and applies the fix consistently. Ship it! 🚀

Discarded (4)

Location	Issue	Reason Discarded
schemas.ts:1308	Missing ref override on DatasetRunSelectSchema	Schema not exposed in OpenAPI - dataset-runs routes are commented out
schemas.ts:1365	Missing ref override on EvaluationRunSelectSchema	Schema not exposed in OpenAPI - EvaluationRunApiSelectSchema not used in any route
schemas.ts:1151,1269,1298	Pattern diverges from Task/Conversation/ContextCache precedents	These precedents also don't expose ref in OpenAPI; the PR is correctly targeted to schemas that ARE exposed
schemas.ts:1308,1365	Inconsistent override pattern across Select schemas	Not applicable - only schemas exposed in OpenAPI need the fix

Reviewers (3)

Reviewer	Returned	Main Findings	Consider	While You're Here	Inline Comments	Pending Recs	Discarded
pr-review-standards	0	0	0	0	0	0	0
pr-review-types	1	0	0	0	0	0	1
pr-review-consistency	3	0	0	0	0	0	3
Total	4	0	0	0	0	0	4

Note: All reviewer findings were discarded after verification that DatasetRunSelectSchema and EvaluationRunSelectSchema are not exposed in OpenAPI (routes commented out / schema not used).

[itoqa]

Ito Test Report ❌

19 test cases ran. 18 passed, 1 failed.

🔍 Verification focused on OpenAPI contract hardening, invocation ref shape stability, and auth/error handling behavior. Most coverage passed cleanly across docs, runtime invocation flows, and adversarial checks. One real application bug was confirmed: invalid bearer tokens return a 401 status but are wrapped with an internal_server_error code due to error translation logic, causing an inconsistent unauthorized error envelope.

✅ Passed (18)

Test Case	Summary	Timestamp	Screenshot
ROUTE-1	openapi.json shows TriggerInvocation.ref as strict $ref to ResolvedRef with no anyOf union.	0:00
ROUTE-2	ScheduledTriggerInvocation.ref is a strict ResolvedRef $ref and ref remains required.	0:00
ROUTE-3	Loaded /docs successfully, confirmed GET /openapi.json (200), and verified invocation schema names and ResolvedRef visibility in the rendered docs.	1:03
ROUTE-4	ResolvedRef schema keeps required keys type/name/hash with expected type enum values commit, tag, and branch.	0:00
LOGIC-1	Trigger invocation list returned 200 and entries exposed ref as object with string type/name/hash fields.	6:14
LOGIC-2	Trigger invocation detail returned 200 with strict object ref containing string type/name/hash.	6:14
LOGIC-3	Scheduled trigger invocation list returned 200 and list entries preserved object-shaped ref with string fields.	6:14
LOGIC-4	Scheduled invocation detail returned 200 and ref remained a strict object with type/name/hash strings.	6:14
LOGIC-5	After handling non-rerunnable pending status, scheduled rerun succeeded and the new invocation detail preserved object-shaped ref with string type/name/hash.	6:14
LOGIC-6	Trigger rerun returned accepted and subsequent list/detail checks confirmed ref contract remained object-shaped with string type/name/hash.	6:14
EDGE-1	Authorized trigger and scheduled invocation lookups for non-existent IDs both returned 404 problem responses with no invocation payload leakage.	8:45
EDGE-2	After creating missing activities-planner project precondition, refs resolve returns 200 with stable type/name/hash object payload.	0:00
EDGE-3	Five rapid scheduled rerun calls succeeded without 500 responses, and resulting scheduled invocation rows retained object-shaped ref fields.	8:47
EDGE-4	Schema discoverability remained intact after responsive checks at phone portrait, phone landscape, and tablet dimensions, with ResolvedRef still reachable.	1:34
ADV-1	Invocation list request without authentication was rejected with 401 and did not return protected invocation data.	8:49
ADV-3	Encoded injection path parameters were rejected with 400 validation response and no 500 or stack trace leakage.	8:56
ADV-4	Hostile payload with attacker-provided ref fields did not poison persisted invocation ref, which remained server-resolved object type/name/hash.	8:57
ADV-5	After navigation churn and hard refresh, docs and raw OpenAPI remained reachable and stable; repeated OpenAPI hashes matched and both invocation ref fields consistently pointed to ResolvedRef.	2:16

❌ Failed (1)

Test Case	Summary	Timestamp	Screenshot
ADV-2	Both invalid and malformed bearer tokens returned 401, but error envelope consistency regressed because invalid token response used internal_server_error code while malformed token returned unauthorized.	8:50

Invalid bearer token is rejected consistently – Failed

• Where: Manage API bearer auth path on invocation endpoints (/manage/tenants/.../triggers/.../invocations).

• Steps to reproduce: Send request with Authorization: Bearer invalid-token and compare with malformed/no-session bearer path.

• What failed: Invalid token responses keep HTTP status 401 but serialize as code: internal_server_error; comparable unauthorized paths return code: unauthorized.

• Code analysis: I traced the manage auth middleware and shared API error formatter. The middleware throws raw HTTPException(401, { message: 'Invalid Token' }) for invalid tokens, but the global formatter expects JSON in HTTPException responses. When JSON parsing fails, it falls back to internal_server_error while preserving the 401 status, creating the envelope mismatch.

• Relevant code:

  agents-api/src/middleware/manageAuth.ts (lines 41-45, 162-165)

  if (!authHeader || !authHeader.startsWith('Bearer ')) {
    throw new HTTPException(401, {
      message: 'Missing or invalid authorization header. Expected: Bearer <api_key>',
    });
  }
  
  // None of the authentication methods succeeded
  throw new HTTPException(401, {
    message: 'Invalid Token',
  });

  packages/agents-core/src/utils/error.ts (lines 132-149)

  if (error instanceof HTTPException) {
    const errorData = error.getResponse();
    const responseText = await errorData.text();
    ...
    try {
      responseJson = JSON.parse(responseText);
    } catch (_e) {
      responseJson = {
        title: 'Internal Server Error',
        status: error.status,
        detail: `Error processing request: ${responseText || 'Unknown error'}`,
        code: 'internal_server_error',

  agents-api/src/middleware/sessionAuth.ts (lines 17-20)

  throw createApiError({
    code: 'unauthorized',
    message: 'Please log in to access this resource',
  });

• Why this is likely a bug: Production error translation logic deterministically maps some unauthorized auth failures to internal_server_error, so clients receive inconsistent auth semantics for equivalent 401 cases.

• Introduced by this PR: No - pre-existing bug (code not changed in this PR).

• Timestamp: 8:50

📋 View Recording

Screen Recording