feat(perplexity): add Agent API presets and deprecate legacy Sonar models

[andrewmadson-pplx]

Summary

Adds Perplexity Agent API support to the public BaseAI OSS local runtime while preserving the existing Sonar Chat Completions path during the migration window.

Sonar Chat Completions is now Agent API. Migrate by September 27, 2026. View the Migration Guide.

What changed

• Adds four Agent API aliases: perplexity:fast, perplexity:low, perplexity:medium, and perplexity:high.
• Routes those aliases to POST https://api.perplexity.ai/v1/agent with the matching preset.
• Keeps all five existing Sonar model IDs on the legacy /chat/completions transport; existing Pipes are not migrated automatically.
• Adds a provider-local Agent SSE parser and leaves the shared legacy stream parser unchanged from main.
• Normalizes non-streaming and streaming Agent responses into BaseAI's existing contracts, including the upstream executing model, optional usage, and non-streaming citation metadata.
• Preserves upstream HTTP status categories for 400/422, 401, 403, 404, 429, and 5xx responses; transport failures remain generic internal errors.
• Rejects unsupported Agent inputs before the network request and documents the current limitations.
• Returns tool-free Core streams immediately after request creation instead of waiting for stream completion.
• Adds workspace-linked runnable Node examples for non-streaming and streaming Agent requests.
• Updates the provider catalog, migration guidance, changelogs, and changeset. Agent preset pricing is labeled dynamic rather than assigned a static token price.

The initial adapter supports system, user, and assistant text; non-streaming responses; streaming answer text; preset search; and non-streaming citation metadata. It does not yet support custom tools, tool-result replay, background runs, file outputs, explicit Agent model selection, image content, or streamed citation metadata.

OSS-only scope

This PR is intentionally limited to BaseAI's public open-source local runtime, public types, tests, examples, and documentation.

• It does not change, validate, or propose fixes for Langbase-hosted execution or any other proprietary system.
• It does not include hosted provider routing, proprietary infrastructure, deployment, rollout, or hosted-workflow migration work.
• It does not claim that the new aliases are available in any hosted Langbase product.

This PR changes only the public BaseAI local runtime; Langbase-hosted execution and rollout are outside its scope.

Migration notes

The provider documentation includes a before/after Pipe example, environment-key guidance, local commands, preset-selection guidance, supported and unsupported behavior, the Agent API quickstart, and the Sonar migration guide.

BaseAI's required max_tokens, temperature, and top_p values are forwarded to Agent API (max_tokens becomes max_output_tokens) and therefore override the chosen preset's tuned defaults. Migrating users should review those values.

Verification

Passed on this branch:

• pnpm install --frozen-lockfile
• BaseAI Node suite: 87/87 tests
• BaseAI edge suite: 84/84 tests
• Route-level Perplexity integration suite: 17 cases across /v1/pipes/run -> callLLM -> callPerplexity -> fetch, included in both BaseAI suites
• Core delayed-stream regression: 1/1 in Node and 1/1 in edge
• baseai build
• @baseai/core build
• workspace-linked Node example build, type-check, and CLI check
• BaseAI docs production build
• changeset validation
• scoped Prettier check
• diff whitespace check
• credential-pattern scan
• comparison confirming the shared legacy stream parser has no diff from main

The full Core suite still has four stale pipe.generateText/pipe.streamText failures. The same four failures reproduce on main. 仓库-wide type-check and lint commands also retain their existing main failures; the new targeted checks and builds pass.

Fixtures and live validation

The golden response and SSE fixtures are sanitized, documentation-derived contract examples assembled from the current public Agent API schema and migration documentation. They are not captured live responses.

No Perplexity credential was available in the protected environment, so no live or billable request was made. A credentialed live smoke test and captured fixture verification remain pending. This PR intentionally remains a draft and is not ready to merge until that acceptance item is completed or explicitly waived.