fix(integrations): stop reporting projectless tool discovery as an error

[kojiwakayama]

Found by a DX dogfood walk of https://veryfront.com/docs/code/getting-started/quickstart against published CLI 0.1.1228.

Symptom

In a scaffold that declares no integrations at all, with a valid stored login token (veryfront whoami → logged in), every agent request emitted an error-level line in the dev server log:

07:07:48  VERYFRONT  ✖ Failed to fetch remote integration tool definitions
                       error="Integration tools API returned 400 Bad Request"

A new developer gets a red failure line, once per run, for a feature they never configured.

Root cause

The integration tools endpoint is project scoped. veryfront dev in an unlinked project puts the veryfront login session credential into VERYFRONT_API_TOKEN (cli/shared/runtime-auth.ts) but has no project to put into VERYFRONT_PROJECT_SLUG. That credential carries no project claim, so the API cannot resolve a project and rejects the request:

$ curl -sX POST https://api.veryfront.com/integrations/tools/list -H "Authorization: Bearer <login token>"
{"title":"Validation Failed","status":400,"detail":"slug: Required", ...}

discoverRemoteIntegrationToolCatalog logged every such failure at logger.error, so the expected state of an unlinked project was reported as an application error.

The request itself is not removed. A credential with no project slug is a supported configuration elsewhere in this module (see does not inherit host project scope for an explicit projectless credential, and buildAgentStreamEnv which sets VERYFRONT_API_TOKEN from a proxy token while VERYFRONT_PROJECT_SLUG is conditional) — a project-scoped token resolves its own project server-side, so the framework cannot know in advance that the call is unusable. What it can do is classify the answer.

Fix

fetchToolList now throws a typed IntegrationToolListResponseError carrying the HTTP status, and discovery classifies it:

• 400 and the runtime resolved no project slug → logger.debug, "Skipped remote integration tools: no project scope for this runtime".
• everything else, including a 400 for a runtime that did send a project slug → unchanged logger.error.

The returned { status: "unavailable", reason: "request_failed" } is unchanged, so no caller behaviour changes.

Regression test

src/integrations/remote-tools.test.ts — Deno BDD, colocated with the module. This is reproducible entirely in-process: mock fetch, env-driven token/slug resolution, and log records captured via __subscribeLogRecordEmitter. No browser and no credentials, so it runs in the pre-push gate; veryfront-e2e would have needed a real dev server and a real 400 from the live API to assert on a log line.

Three cases:

Test	Asserts
reports a projectless integration tools rejection below error level	env token, no slug, 400 → exactly one debug record, no error record
still reports integration tool discovery failures for a project-scoped runtime	env token with slug, 400 → still error
still reports integration tool discovery server failures at error level	env token, no slug, 500 → still error

Confirmed failing before the fix for the right reason — the first case produced the exact record from the finding:

- { level: "error", message: "Failed to fetch remote integration tool definitions",
-   context: { error: "Integration tools API returned 400 Bad Request" } }
+ []

End-to-end verification

Driving the worktree's getRemoteIntegrationToolDiscovery() against the live API with the stored login token and no project slug:

• before (git stash of the source change): ✖ Failed to fetch remote integration tool definitions error="Integration tools API returned 400 Bad Request"
• after: silent at the default level; with VERYFRONT_DEBUG=1, · Skipped remote integration tools: no project scope for this runtime

Full pre-push suite passed.

Summary by CodeRabbit

• Bug Fixes
  • Improved remote tool catalog discovery when no project scope is available.
  • Expected unavailable-tool responses are handled gracefully without surfacing unnecessary errors.
  • Other client and server failures continue to be reported at the appropriate severity.
  • Project-specific tool discovery requests now use the correct project context.

[coderabbitai]

Warning

Review limit reached

@kojiwakayama, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 9 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4e9e1395-5757-4ccd-9bba-4a84d3bccb9a

📥 Commits

Reviewing files that changed from the base of the PR and between d721efc and 02ba8b7.

📒 Files selected for processing (2)

• docs/api-reference/veryfront/integrations.md
• src/integrations/remote-tools.ts

📝 Walkthrough

Walkthrough

Remote tool discovery now passes project scope into catalog requests, preserves tool-list response statuses, and handles projectless HTTP 400 responses as unavailable at debug level. Tests verify logging for projectless, project-scoped, and server failures.

Changes

Remote tool discovery

Layer / File(s)	Summary
Typed catalog failures and project propagation src/integrations/remote-tools.ts	Catalog failures now use IntegrationToolListResponseError with the HTTP status. Discovery accepts the resolved project slug and passes it to catalog requests.
Conditional discovery logging and coverage src/integrations/remote-tools.ts, src/integrations/remote-tools.test.ts	Projectless HTTP 400 responses log at debug level. Project-scoped 400 responses and 500 responses remain errors. Tests capture and verify these records.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• veryfront/veryfront-code#3331: Related remote MCP tool-list discovery and transport handling.
• veryfront/veryfront-code#3515: Related remote tool discovery APIs and caching behavior.

Suggested reviewers: kwakayama

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: reducing error reporting for projectless tool discovery.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/dx-20260811-0742-1

---

_{Comment @coderabbitai help to get the list of available commands.}

[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 `@src/integrations/remote-tools.ts`:
- Around line 64-72: Replace the IntegrationToolListResponseError class with a
defineError-based VeryfrontError registry entry that preserves the status
payload and API error message. Update the integration failure handling near the
existing status check to first require instanceof VeryfrontError and the
expected error slug, then inspect status.

🪄 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: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 2ed03e20-f548-4781-9186-0799065ad037

📥 Commits

Reviewing files that changed from the base of the PR and between fe5d5b8 and d721efc.

📒 Files selected for processing (2)

• src/integrations/remote-tools.test.ts
• src/integrations/remote-tools.ts