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.
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.
previewQuote prices drafts and signs a 30-minute preview token only when ready; createQuote verifies that token against live config before writing.
Org context is built per call from the opportunity’s existing load(), not from a stored context table or pinned hash.
Focus on auth boundaries, idempotency / replacement semantics, preview-token binding, hidden-product filtering, and the deployed secret prerequisite.
1. Why this exists
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.
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.
2. What changes
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.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.
conversationQuotes/store.ts now supports quote-tool semantics.
reserve()reports whether it inserted a run.findTurn()finds an existing run by turn / idempotency key.oneOpportunityprevents one conversation from drifting across deals.
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
edit_pricing_flow for quote creation.
Preview token signs the parts needed to prove “create exactly what was previewed.”
- Org, user, opportunity.
- Caller draft and contract start date.
pricingSpecIdanddataSheetId.- Canonical engine input hash.
- Applied promotions hash.
- Priced result hash.
- 30-minute expiry.
createQuote verifies the token, reloads live configuration, prepares the draft again, and compares the signed hashes.
stale_previewForged, foreign, expired, or malformed token.
config_changedSpec, datasheet, promotions, engine input, or priced result no longer match.
conflictIdempotency key, replacement, or conversation opportunity guard blocks the write.
| 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
- No model calls are added in this layer.
- No new Prisma migration or stored org-context table is introduced.
- No context hash, refresh endpoint, org content hash, or context pinning remains in V1.
- No approval-rules tool surface is included; those pieces were removed from V1.
- No BullMQ job is used for quote creation;
PricingQuoteService.createPricingQuoteruns inline. - The existing standard quote pipeline still supplies default contract term and currency when omitted.
- Slack agent admission stays at the Slack entrypoint; this service does not add a staff-only gate.
- No client-side UI is changed in this PR.
5. Risks / rollback / open questions
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.
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.
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.
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.