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.

Author: @megnaanand24 PR: #8035 Linear: DEA-8394 Stack: based on #8032, includes #8019 until landing Files: 51 Diff: +5991 / -76, truncated in prompt Status: open, flagged off

What it adds

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.

What it changes

Conversation SSE progress is now structured as step, label, and status.

Slack keys gain quote-tool read scopes and old installs can be upgraded.

Rollout posture

isQuoteAgentOrchestratorEnabled is off for every org.

Standard quote conversations can route to the orchestrator; AI quote mode stays on the old graph.

Review focus

Approval safety is in code, not prompt faith.

Review create/confirm gates, alias mapping, checkpoint compatibility, and Slack scope migration.

Orchestrator
quoteTools
Progress stream
Saved agent state
Slack integration
Old graph

1. Why this exists

Current shape
  • 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.
Target shape
  • One turn runs as a model plus tools loop on the quoteTools layer.
  • Quote safety constraints run inside tool implementations.
  • The model writes prose; code owns exact approval-sensitive artifacts.
This is explicitly the first part of 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

Server surface
new turn path

streamConversationTurn chooses old graph vs. orchestrator based on the saved conversation state and requested agent.

Agent loop
15 tools max

The ceiling is a runaway guard, not a lookup cap. Repeated read-only lookups are cached per turn and per opportunity.

Safety rules
code-gated

createQuote and confirmOpportunity enforce prior display, rep authorship, and unchanged preview requirements.

Tests
25 unit paths

Mocha covers orchestration, aliases, form answers, replay, legacy mapping, create gates, context reload, and org isolation.

conversationAgent/orchestrator.ts
Owns load, replay, state read/write, routing protections, exact preview/candidate append, fallback replies, and orchestrator streaming.
conversationAgent/orchestrator/agent.ts
Runs the LangChain tool-calling loop with MAX_TOOL_CALLS = 15, per-turn cache support, and bad-argument errors returned to the model.
conversationAgent/orchestrator/agentTools.ts
Defines the tool boundary and enforces confirm/create safety rules against saved state and the latest rep message.
conversationAgent/orchestrator/state.ts
Stores the orchestrator’s schema-versioned state separately from the old graph, including aliases, draft, preview, current quote, and candidate history.
conversationAgent/progress.ts + contracts.ts
Adds typed progress events and accepts quote.created for inline quote creation.
slackConversation/* + externalApiScopes.ts
Adds progress placeholder updates and expands Slack API-key scopes to include opportunity, product, and pricebook reads.

3. How it works

1. Route

runsOnOrchestrator keeps an existing orchestrator conversation on v2.

Old-graph checkpoints stay on the old graph.

2. Snapshot

On opportunity confirmation, getQuoteContext loads quoting setup, terms, and alias map once.

Reloads for a new opportunity or config_changed.

3. Act

The model sees aliases and calls tools such as searchProducts, updateDraft, previewQuote, and createQuote.

4. Save

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.
Before
  • 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.
After in flagged path
  • 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, and create.

Tool set exposed to the agent

findOpportunity confirmOpportunity withdrawOpportunity searchProducts getProductDetails getDiscountPolicy updateDraft previewQuote createQuote

4. Testing added

Mocha unit coverage
  • 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.
E2E harness
  • New quoteAgentTurn chain-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.
Regression suites
  • Conversation agent, quoteTools, and Slack conversation suites pass.
  • pnpm run typecheck on server passes.
  • ESLint on changed files reports zero errors.

5. What it doesn't change

6. Risks / rollback / open questions

Before rollout
Rollback shape

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.