Deterministic quote tools service

PR #8032 adds the Dealops 2 server-side quote tool layer used by Slack agent, external API, and MCP callers without making model calls.

Author: @megnaanand24 PR: dealops#8032 Ticket: DEA-8393 Area: apps/server · Dealops 2 Files: 21 Diff: +4821 / -56 State: open Diff note: truncated

What it adds

A new createQuoteTools() service under apps/server/src/dealops2/quoteTools/ implementing the T0 tool contract.

Tools are deterministic orchestration only: authorize, load config, prepare / price / create.

Core behavior

previewQuote prices drafts and signs a 30-minute preview token only when ready; createQuote verifies that token against live config before writing.

Important design choice

Org context is built per call from the opportunity’s existing load(), not from a stored context table or pinned hash.

Review pressure

Focus on auth boundaries, idempotency / replacement semantics, preview-token binding, hidden-product filtering, and the deployed secret prerequisite.

Quote tools
Quote configuration
Org quote context
Preview token
Conversation quote run
Pricing quote service

1. Why this exists

Problem

Several non-UI entrypoints need the same quote operations: Slack agent, /external/v1, and MCP.

Without a shared layer, each entrypoint would need to duplicate config loading, per-user catalog filtering, preview validation, and create idempotency.

Fix

This PR introduces one deterministic tool service for Dealops 2 quoting.

It centralizes authorization, context construction, preview pricing, signed preview verification, inline quote creation, quote lookup, and catalog / discount-policy lookup.

Stacking context: this is based on #8009 and replaces #8027. The previously planned stored org-context table from #8025 is intentionally not used; approval-rule pieces from #8022 are cut from V1.

2. What changes

New service surface
quoteTools/service.tsImplements getQuoteContext, previewQuote, createQuote, search, quote read, product details, and discount policy.
quoteTools/auth.tsScope-based actor authorization for user and API-key callers.
quoteTools/previewToken.tsHMAC-SHA256 signed preview token with TTL and config / input hashes.
quoteTools/aliases.tsMaps real product / pricebook IDs to caller-safe aliases like P1 and PB2.
New org context builder

orgQuoteContext/service.ts builds context from the opportunity’s loaded QuoteConfiguration.

  • Renders catalog and discount policy over the admin view.
  • Filters to caller visibility through filterForUser.
  • Uses caller’s entitled pricebooks and default pricebook.
Conversation quote store

conversationQuotes/store.ts now supports quote-tool semantics.

  • reserve() reports whether it inserted a run.
  • findTurn() finds an existing run by turn / idempotency key.
  • oneOpportunity prevents one conversation from drifting across deals.
Docs and tests

Adds concept docs plus broad Mocha and e2e coverage for preview, create, token rejection, idempotency, replacement, visibility, and hidden products.

Tool Inputs that matter Output / side effect Guardrail
getQuoteContext opportunityId Quoting setup text, opportunity summary, questions for an empty draft. Builds from one opportunity load(); no stored hash.
previewQuote Opportunity, aliased draft, optional start date / pricebook alias. Labels assumptions, prices totals, signs token only if ready. Writes no quote; hidden products are unnamed and unpriced.
createQuote Opportunity, preview token, idempotency key, optional conversation / replace. Creates quote inline, completes quote run, emits quote.created. Rejects stale / forged / config-drifted previews.
getQuote Quote ID or conversation ID. Quote summary and app URL. Conversation visibility and quote access are rechecked.
Lookups opportunityId plus aliases / query. Product details, product search, discount policy. Context is rebuilt from live opportunity config and filtered for caller.

3. How it works

Preview token binding

Preview token signs the parts needed to prove “create exactly what was previewed.”

  • Org, user, opportunity.
  • Caller draft and contract start date.
  • pricingSpecId and dataSheetId.
  • Canonical engine input hash.
  • Applied promotions hash.
  • Priced result hash.
  • 30-minute expiry.
Create safety

createQuote verifies the token, reloads live configuration, prepares the draft again, and compares the signed hashes.

A
stale_preview
Forged, foreign, expired, or malformed token.
B
config_changed
Spec, datasheet, promotions, engine input, or priced result no longer match.
C
conflict
Idempotency key, replacement, or conversation opportunity guard blocks the write.
Authorization model
Layer Requirement Reason
User Active user in org; role scopes via assertScopes(resolveScopes(user)). Tools are entrypoint-agnostic; they do not rely on Slack-only staff admission.
API key Stored key scopes must also cover required scopes, plus act-as-user when applicable. Key actors can be narrower than their user.
Create All lookup scopes plus edit_pricing_flow. Preview can read / price; create mutates quoting state.
Visibility Conversation visible to creator, participants, staff/admin, or act-as-user key. Hidden conversations return NOT_FOUND, not leaked metadata.

4. What it doesn't change

Explicit non-goals

5. Risks / rollback / open questions

Deploy prerequisite

Required: set QUOTE_PREVIEW_TOKEN_SECRET on deployed servers.

Local and CI can use a per-process secret; deployed multi-replica environments need a shared secret or previews signed on one server may fail elsewhere.

Latency budget

createQuote is inline and measured through recordQuoteJob.

The e2e helper asserts under 30s; the turn timeout is 120s. Baseline timings are still pending in ticket A.

Default handling

Pipeline defaults for term and currency are shown as kind: "default" and source: "spec_default".

Open product decision: V1 could ask questions instead of defaulting; the PR calls that a small change.

Test caveat

The diff adds broad e2e coverage, but the PR description says the e2e suite was not run locally.

Server typecheck, ESLint on changed files, full Mocha, selected Jest, and OKF validation are reported clean.

Diff visibility note: the provided diff is truncated. This explainer is based on the PR description and visible diff sections, especially the new quote tools, org context service, preview token, auth, conversation quote store changes, and tests.