feat(agents): typed API client and shared infra (1/8)

[VaibhavAcharya]

Summary

Linear: https://linear.app/netlify/issue/EX-2195

Splits the agents CLI revamp (formerly one large PR) into a reviewable stack. This first PR is the foundation: the typed agents API and the shared types, constants, and utilities the rest of the command work builds on. No user-facing command behavior changes yet.

• The static model whitelist is gone. Models are fetched live from the AI gateway, so adding a model upstream no longer needs a CLI patch.
• API calls live in a typed module (api.ts) so each command file can focus on UX.
• Attachment upload handling (attachments.ts) with size and per-request limits, plus orphan cleanup on partial failure.

The existing create/list/show/stop commands keep working unchanged against the new infra; their behavior changes land in the next PR.

Stack (merge in order): base → existing commands → diff/open → pr/commit → sync/redeploy → publish/revert → rename/archive → follow-up.
Base branch: main.

---

For us to review and ship your PR efficiently, please perform the following steps:

• Open a bug/issue before writing your code 🧑‍💻. This ensures we can discuss the changes and get feedback from everyone that should be involved. If you`re fixing a typo or something that`s on fire 🔥 (e.g. incident related), you can skip this step.
• Read the contribution guidelines 📖. This ensures your code follows our style guide and
  passes our tests.
• Update or add tests (if any source code was changed or added) 🧪
• Update or add documentation (if features were changed or added) 📝
• Make sure the status checks below are successful ✅

[coderabbitai]

📝 Walkthrough

Summary by CodeRabbit

• New Features
  • Added agents API support for creating, listing, and managing agent runners
  • Implemented file attachment uploads for agents with validation and error recovery
  • Enabled agent runner operations including pull requests, commits, publishing, and git management

Walkthrough

This PR introduces a complete Netlify agents API client factory and attachment upload subsystem. It adds configuration constants for agent/session modes and filtering options with terminal state subsets and attachment limits, expands the TypeScript data model with new runner and session fields covering deployment state, contributors, usage metrics, and AI gateway integration. The API client implements HTTP plumbing with centralized error handling, pagination via Total/Link headers, and strongly-typed methods for listing/managing runners and sessions, retrieving diffs, triggering actions, and listing AI gateway providers with in-memory caching. Supporting utilities add validators for prompts, titles, agents, and models; formatters for dates, PR states, bytes, tokens, and diffs; dashboard URL building; MIME type detection; and HTTP header parsing. Attachment upload validates file counts and sizes, requests upload URLs, streams files via PUT with 60-second timeouts, and performs best-effort orphan cleanup on failure. Test infrastructure updates mock API to track originalUrl and support function-based route responses.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: introducing a typed API client and shared infrastructure for the agents CLI as the first part of an eight-part series.
Description check	✅ Passed	The description is well-related to the changeset, explaining the foundation work including the typed agents API module, shared types/constants/utilities, attachment handling, and the transition from static to live model fetching.
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.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/cli/pr8237-base

---

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

[github-actions]

📊 Benchmark results

Comparing with c9d1772

• Dependency count: 1,136 (no change)
• Package size: 379 MB ⬆️ 0.00% increase vs. c9d1772
• Number of ts-expect-error directives: 354 (no change)

[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 `@tests/integration/utils/mock-api.ts`:
- Around line 70-73: The handler currently returns before applying the
configured status when response is a function, so update the logic in the mock
API handler (the branch that checks typeof response === 'function') to call
res.status(status) before invoking response(req, res); ensure you still return
afterwards and preserve existing behavior for non-function responses; reference
the response variable and res.status(...) call in the function branch so
function-based dynamic responses receive the configured HTTP status.

🪄 Autofix (Beta)

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

Run ID: c4c8d79b-38a5-47a2-8f64-ac81a9961d99

📥 Commits

Reviewing files that changed from the base of the PR and between c9d1772 and 5549de6.

📒 Files selected for processing (6)

• src/commands/agents/api.ts
• src/commands/agents/attachments.ts
• src/commands/agents/constants.ts
• src/commands/agents/types.ts
• src/commands/agents/utils.ts
• tests/integration/utils/mock-api.ts

[VaibhavAcharya]

Link EX-2195

[khendrikse]

[nit] a smaller comment with less service specificity

Suggested change

	// TODO: Migrate to @netlify/api once these endpoints are public.
	// They are marked x-internal in bitballoon (#21736).
	// Method names mirror the bitballoon @operation_id to keep the future swap quick.
	// TODO: Migrate to @netlify/api once these endpoints are public.
	// Method names mirror the backend @operation_id to keep the future swap quick.