feat(chat): stabilize tool definitions and make Actions advisory

Merged
WE
10h ago
+2836-975

Description

Keep tool definitions stable across agent steps and make Action selection advisory. Web and mobile preserve the selected Action across messages. The model may use another available tool or answer without tools.

Agents register tool definitions and named phases once. Each step selects execution permissions without mutating the registered definitions. The runtime enforces those permissions before tool execution and verifies the saved configuration when restoring a run. Provider restrictions can still affect the definitions sent on the wire.

Action preferences appear in the trailing request reminder, outside recorded history. Clients send the persistent selection with each request. API clients must replace forced_tool_id with preferred_tool_id; non-null legacy values and preferences combined with Deep Research are rejected. When inline project context replaces retrieval, only a configured and allowed Search preference is omitted for that request. Excluded preferences still fail validation.

Slack uses completed-search evidence before replacing an answer with an empty-search notice. Eval inputs share validation, and retrieval benchmarks fail cases without completed retrieval. These changes include the former #17306; this PR now delivers the tool contract and its product behavior together.

How Has This Been Tested?

  • Nine integration cases passed through the frontend/API with isolated PostgreSQL, Redis, search, file storage, and Celery workers. They cover preferences, allowlists, parallel calls, XML recovery, uploaded inline project files, and excluded Search preferences. The inline-file regression reproduces the original BAD_REQUEST before the fix.
  • The project-file test uses the existing upload manager and connector-seeding helper. Search availability is established before upload, independent of indexing. The revised success case also passed by itself.
  • Final combined PR 4 passed 1,689 runtime/chat/API/eval/Slack/benchmark tests. Persistent-selection validation passed 36 web tests and 106 mobile tests, with full client type checks and lint.
  • Three Deep Research API integration cases, 15 LiteLLM HTTP-contract tests, and 56 real-storage answer/run-store/restoration tests passed during tool-contract development.
  • The live Anthropic replay test passed, including evidence reuse, compaction, and restoration. Tool selection is deterministic in that test; live preference compliance rates were not measured.
  • Normal commit hooks passed. Additional enterprise document-set integration coverage is blocked locally by a missing license; the MCP OAuth suite needs Nginx, which is not installed locally.

Docs

  • Customer-facing change: I updated documentation/ (text and screenshots).

Updated chat API and image-generation guidance, eval documentation, runtime documentation, and feature-map contracts. No existing screenshot depicts the changed preference wording.

Additional Options

  • [Optional] Please cherry-pick this PR to the latest release version.

Summary by CodeRabbit

  • New Features

    • Actions can be marked as preferred for a chat. The assistant may use the selected Action when helpful, but can also answer without it or choose another available Action.
    • Search preferences are reflected in chat and Slack responses when Search is available and permitted; they do not guarantee a search.
    • Preferred Actions remain selected across messages in a chat. Deep Research and Action preferences cannot be active together.
    • Evaluation inputs can specify preferred Actions, including per-turn preferences.

  • Bug Fixes

    • Resuming a saved agent run now checks that its tool configuration is unchanged and preserves saved execution permissions.
    • Final-answer requests retain prior tool evidence while preventing further tool execution.