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.
• Rejects every other Perplexity identifier locally with HTTP 400 before provider fetch.
• 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.
• Preserves HTTP-200 Agent execution and protocol failures as internal server errors rather than legacy caller 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. The streaming command awaits terminal completion and exits nonzero on failure.
• 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.

Adversarial-review follow-up

Resolved on the current head:

• Unsupported perplexity:xhigh, perplexity:wide-research, and typo identifiers return 400 without calling either Perplexity endpoint.
• An HTTP-200 Agent response with status: "failed" returns 500 while the existing non-2xx provider mappings remain intact.
• The streaming example awaits runner.done() and sets a nonzero process exit code on failure.

Not implemented without live evidence:

• Token-limited stream termination. Non-streaming token exhaustion already maps to finish_reason: "length", but the public Perplexity documentation does not identify the exact incomplete terminal SSE discriminator. The stream parser will not guess that contract.

Verification

Passed on the current branch:

• pnpm install --frozen-lockfile — passed.
• pnpm --filter baseai test:node — 6 files, 91/91 tests, no type errors.
• pnpm --filter baseai test:edge — 5 files, 88/88 tests, no type errors.
• pnpm --filter baseai exec vitest --config vitest.node.config.js --run src/dev/routes/v1/pipes/run.perplexity.test.ts — 21/21 route-level cases.
• pnpm --filter baseai exec vitest --config vitest.edge.config.js --run src/dev/routes/v1/pipes/run.perplexity.test.ts — 21/21 route-level cases.
• pnpm --filter @baseai/core exec vitest --config vitest.node.config.js --run src/pipes/pipes.streaming.test.ts — 1/1.
• pnpm --filter @baseai/core exec vitest --config vitest.edge.config.js --run src/pipes/pipes.streaming.test.ts — 1/1.
• pnpm --filter baseai build — passed.
• pnpm --filter @baseai/core build — passed.
• pnpm --filter example-nodejs check — workspace-linked build, type-check, and CLI check passed.
• pnpm --filter baseai.dev build — production docs build passed with existing warnings.
• pnpm changeset status --since=main — validates minor bumps for baseai and @baseai/core.
• git diff --check — passed.
• Scoped Prettier checks for every follow-up file — passed.
• Shared legacy stream parser comparison against main — no diff.
• Credential and proprietary-scope pattern scan — no findings.

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

The pull request currently has no GitHub check runs attached.

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 is available in the protected environment, and no billable-call authorization or call ceiling has been supplied for this follow-up. No live request was made.

Before moving this PR out of draft:

1. Capture one non-streaming perplexity:fast response with citations.
2. Capture one normal streaming perplexity:fast event sequence.
3. Capture one deliberately token-limited streaming event sequence.
4. Sanitize and commit the live contract evidence, or record an explicit maintainer waiver.
5. Implement token-limit stream handling from the observed terminal discriminator and rerun the commands above.

This PR intentionally remains a draft and is not ready to merge until the live contract and token-limit acceptance items are completed or explicitly waived.