Quote agent V1 turn orchestrator, behind a flag
This PR adds a Dealops 2 server-side tool-calling turn for standard quote conversations, but routes no org to it until the PostHog flag is enabled.
A new conversationAgent/orchestrator.ts path for Dealops 2 quote turns.
The model runs one tool-calling loop over quoteTools, then code appends exact preview, candidate, and quote-created details.
Conversation SSE progress is now structured as step, label, and status.
Slack keys gain quote-tool read scopes and old installs can be upgraded.
isQuoteAgentOrchestratorEnabled is off for every org.
Standard quote conversations can route to the orchestrator; AI quote mode stays on the old graph.
Approval safety is in code, not prompt faith.
Review create/confirm gates, alias mapping, checkpoint compatibility, and Slack scope migration.
1. Why this exists
- The existing quote conversation graph is multi-step and prompt-driven.
- Separate interpret/reply prompts do not fit a single agent loop.
- Progress events existed, but the stream contract needed clearer typed labels.
- One turn runs as a model plus tools loop on the
quoteToolslayer. - Quote safety constraints run inside tool implementations.
- The model writes prose; code owns exact approval-sensitive artifacts.
DEA-8394. The orchestrator is present, tested with scripted models, and disabled everywhere until the feature flag and operational prerequisites are ready.
2. What changes
streamConversationTurn chooses old graph vs. orchestrator based on the saved conversation state and requested agent.
The ceiling is a runaway guard, not a lookup cap. Repeated read-only lookups are cached per turn and per opportunity.
createQuote and confirmOpportunity enforce prior display, rep authorship, and unchanged preview requirements.
Mocha covers orchestration, aliases, form answers, replay, legacy mapping, create gates, context reload, and org isolation.
MAX_TOOL_CALLS = 15, per-turn cache support, and bad-argument errors returned to the model.quote.created for inline quote creation.3. How it works
runsOnOrchestrator keeps an existing orchestrator conversation on v2.
Old-graph checkpoints stay on the old graph.
On opportunity confirmation, getQuoteContext loads quoting setup, terms, and alias map once.
Reloads for a new opportunity or config_changed.
The model sees aliases and calls tools such as searchProducts, updateDraft, previewQuote, and createQuote.
Code appends exact facts, emits events, saves the reply, and persists state for replay and later approval.
| Rule | Enforced where | Reviewer takeaway |
|---|---|---|
| Create only after explicit go-ahead | createQuote tool logic |
The latest message must be a plain approval, not a question, condition, pause, decline, or same-message edit. |
| Create only the preview the rep saw | Saved lastPreview, preview token identity, re-preview checks |
Unseen previews, changed catalogs, changed pricebooks, and open questions block creation. |
| Confirm only shown opportunities | confirmOpportunity tool logic |
A Salesforce ID alone cannot confirm unless that candidate was presented in a prior saved reply. |
| Model sees aliases, not real IDs | Context snapshot and draft state | P3 / PB1 stay stable for the conversation; quoteTools owns real ID mapping. |
| Prices come only from preview | previewQuote and exact code append |
The model does not author prices; code presents priced output and totals. |
- Conversation graph interprets, resolves, assesses, quotes, and responds across distinct nodes.
- Quote creation is job-oriented for the old flow.
- Progress was string-like and less descriptive for clients.
- One orchestrator turn performs tool calls until the model replies.
- Ready quote creation can happen inline and emits
quote.created. - Progress labels describe steps like
resolve,preview, andcreate.
Tool set exposed to the agent
findOpportunity
confirmOpportunity
withdrawOpportunity
searchProducts
getProductDetails
getDiscountPolicy
updateDraft
previewQuote
createQuote
4. Testing added
- Loop ceiling, tool cache, and invalid arguments.
- Context loaded once and reloaded after
config_changed. - Confirm rules, create rules, fallback reply, replay, thread trimming.
- Alias mapping in state, tools, and form answers.
- New
quoteAgentTurnchain-builder step. - Real quote tools, search, confirmation checks, pricing, and DB writes.
- Scripted model only; no real-model run yet.
- New e2e suite not run locally because seed guard rejects the Neon dev DB.
- Conversation agent, quoteTools, and Slack conversation suites pass.
pnpm run typecheckon server passes.- ESLint on changed files reports zero errors.
5. What it doesn't change
- It does not enable the orchestrator for any org; the rollout flag is off everywhere.
- It does not route AI quote mode to the orchestrator; that Codex finding was fixed.
- It does not migrate old-graph conversations into live orchestrator execution; old-graph conversations stay on the old graph.
- It does not make the model the source of truth for prices, Salesforce IDs, quote links, or approval state.
- It does not add a Prisma migration or new persisted table; state is checkpointed through the conversation agent mechanism.
- It does not replace #8033’s eval need; the copied
draftChanges.tsshape still needs real-model eval coverage next.
6. Risks / rollback / open questions
- PostHog flag still needs to be added. The code path depends on
isQuoteAgentOrchestratorEnabled, but rollout config is not complete. - Reconnect Slack once per installation before enabling. Existing Slack keys keep old scopes; quote tools require
opportunity:read,product:read, andpricebook:read. - CI is the first run for the new e2e suite. Treat failures as likely integration feedback, not proof the unit path is untested.
- No real-model run yet. Safety gates are coded, but prompt/tool behavior still needs evals and real model observation.
- Diff was truncated in the prompt. This explainer is based on the PR description, file list, and visible diff sections, not every changed line.
Keep the feature flag off or disable it for affected orgs. Since existing old-graph conversations stay on the old graph and the orchestrator is opt-in for new standard-quote conversations, rollback is primarily routing control rather than schema rollback.