Summary

Fixes a compatibility issue in web-search on the Perplexity chat-completions compatibility path (OpenRouter), where citations could be lost when responses provide URL citations under choices[*].message.annotations instead of top-level citations.

• Problem: runPerplexitySearch only read data.citations.
• Why it matters: users got grounded content but empty/missing citations in tool output when using OpenRouter.
• What changed:
  • Extended Perplexity response typing to include message.annotations.
  • Added extractPerplexityCitations(...):
    • Prefer top-level citations.
    • Fallback to choices[*].message.annotations[*].url_citation.url.
    • Trim + dedupe URLs.
  • Added regression test for annotations-only responses.
• What did NOT change (scope boundary):
  • No provider routing changes.
  • No request payload or endpoint changes.
  • No changes to Perplexity native Search API path.

Change Type (select all)

• Bug fix
• Feature
• Refactor
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #N/A
• Related #N/A

User-visible / Behavior Changes

web_search with Perplexity OpenRouter-compatible responses now returns citations when sources are provided via message.annotations (fallback path), instead of returning empty citations.

Security Impact (required)

• New permissions/capabilities? (No)
• Secrets/tokens handling changed? (No)
• New/changed network calls? (No)
• Command/tool execution surface changed? (No)
• Data access scope changed? (No)
• If any Yes, explain risk + mitigation: N/A

Repro + Verification

Environment

• OS: macOS (local dev)
• Runtime/container: local gateway + local tests
• Model/provider: Perplexity sonar/sonar-pro/sonar-pro-search via OpenRouter
• Integration/channel (if any): Gateway tool execution
• Relevant config (redacted): tools.web.search.provider=perplexity, OpenRouter key configured

Steps

1. Configure web_search with Perplexity/OpenRouter chat_completions path.
2. Run a search where response citations are only in choices[*].message.annotations.
3. Inspect tool result citations.

Expected

• citations should include URLs from annotations (deduplicated) when top-level citations are absent.

Actual

• Before fix: citations could be empty on the chat_completions compatibility path (OpenRouter).
• After fix: citations correctly populated from annotations fallback.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Runtime before (same query/provider/model)

{
  "query": "Iran latest situation today March 2026 nuclear talks military tensions sanctions",
  "provider": "perplexity",
  "model": "perplexity/sonar",
  "externalContent": {
    "untrusted": true,
    "source": "web_search",
    "provider": "perplexity",
    "wrapped": true
  },
  "content": "<omitted>",
  "citations": []
  }

Runtime after (same query/provider/model)

{
  "query": "Iran latest situation today March 2026 nuclear talks military tensions sanctions",
  "provider": "perplexity",
  "model": "perplexity/sonar",
  "externalContent": {
    "untrusted": true,
    "source": "web_search",
    "provider": "perplexity",
    "wrapped": true
  },
  "content": "<omitted>",
  "citations": [
    "https://timesofindia.indiatimes.com/videos/international/explosions-shake-tel-aviv-as-iran-launches-khorramshahr-fattah-missiles-in-new-barrage/videoshow/129306402.cms",
    "https://www.democracynow.org/2026/3/5/iran_state_defense",
    "https://www.foxnews.com/video/6390605040112",
    "https://www.euronews.com/video/2026/03/03/europe-today-iran-war-intensifies-as-trump-signals-prolonged-fight",
    "https://globalnews.ca/video/11712842/middle-east-analyst-on-u-s-military-action-in-iran"
  ]
}

Test evidence

• pnpm test src/agents/tools/web-tools.enabled-defaults.test.ts
• Result: 44 passed / 44 total
• Includes regression case:
  falls back to message annotations when top-level citations are missing

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios:
  • Unit/regression test for annotations-only response.
  • Manual runtime check with Perplexity/OpenRouter response showing non-empty citations.
• Edge cases checked:
  • Top-level citations still preferred when present.
  • Duplicate annotation URLs are deduplicated.
• What you did not verify:
  • Full cross-provider matrix beyond Perplexity/OpenRouter citation parsing path.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes)
• Config/env changes? (No)
• Migration needed? (No)
• If yes, exact upgrade steps: N/A

Failure Recovery (if this breaks)

• How to disable/revert this change quickly:
  • Revert this PR commit.
• Files/config to restore:
  • src/agents/tools/web-search.ts
  • src/agents/tools/web-tools.enabled-defaults.test.ts
• Known bad symptoms reviewers should watch for:
  • Missing citations in Perplexity/OpenRouter tool output.

Risks and Mitigations

List only real risks for this PR. Add/remove entries as needed. If none, write None.

• Risk:
  • Unexpected annotation shapes from upstream responses.
  • Mitigation:
    • Defensive optional parsing + fallback to existing top-level citations behavior.