feat(examples): WhatsApp installment negotiation (multi-turn session.send + Asaas preview)

[dangazineu]

Adds a multi-turn buyer-vs-merchant agent demo at
examples/whatsapp-installment-negotiation/. The buyer asks for a
payment option that was not on the merchant's pre-authored menu
("what about 6x?"), the agent computes the variant in real time by
calling the Asaas installment MCP in preview mode, presents
R$800/month back, the buyer confirms, and the agent commits the
payment, issues the NF-e, and sends the WhatsApp confirmation.

The skeleton test runs end-to-end against the OSS MCP bridge with
MCP_DEMO=true on every server and @copilotkit/aimock standing in
for api.anthropic.com — no real credentials needed. A live.test.ts
file is included for the live-LLM smoke gate (gated on
CODESPAR_LIVE_SMOKE=1) and is required to pass locally before
pushing, per the codespar-core CLAUDE.md workflow rule. Live smoke
against api.anthropic.com (claude-sonnet-4-6) was run separately
and exercised the full four-turn flow.

Why this matters

A BSP flow-builder (Blip, Zenvia, Take) breaks when a buyer asks for
a payment option the merchant did not pre-author. "What about 6x?"
is not on the menu; the flow-builder has no branch for it. The agent
computes the variant from a real MCP tool call, not from prose
hardcoded in the prompt. The runtime drives three buyer messages
through three separate session.send() calls; narrative continuity
across those sends lives in the fixture authoring and the agent's
prompt, not in shared message state (see "Per-send fixture
semantics" below).

Three judgment points the agent navigates:

1. Which options to present first — Pix with discount vs. 12x as
   openers. Picking the wrong opener costs deals; no rule fires here.
2. How to answer a non-enumerated variant — call Asaas, get
   R$800/month back, present it. A script that anticipates only
   pre-enumerated installment counts misroutes silently.
3. When to stop exploring and close — after "confirma, pode
   fechar" the agent commits the payment and issues the NF-e instead
   of proposing another variant.

Per-send fixture semantics (read before reviewing the fixture)

The OSS chat loop resets the messages array on every
session.send() call. turnIndex (which aimock derives from the
number of assistant messages in the current LLM request) therefore
restarts at 0 on each new send rather than running continuously 0-4
across all three buyer turns. The five fixture entries are organised
per-send, and the two "after tool result" continuations sit at
turnIndex 1 within their own send with userMessage
discriminators so they do not collide. Substring matching on
userMessage is case-sensitive — the turn-3 match is Confirma,
not confirm.

The README's "How to extend the fixture for your own multi-turn
flow" subsection walks through the entry-per-completion mapping and
the turnIndex + hasToolResult match-key pattern.

Scaffold inherited from the natural-language NFS-e example

The boilerplate is verbatim from
examples/nfse-from-natural-language/:
three runtime modes in validate.sh (Docker default /
CODESPAR_BASE_URL / CODESPAR_RUNTIME_DIR), aimock lifecycle,
live.test.ts gated on CODESPAR_LIVE_SMOKE=1, the three
mockability layers boilerplate in the README, exact MCP pins as
devDeps, --demo flags in mcp-servers.json (source of truth for
demo mode).

What is new here:

• Three session.send() calls instead of one — the test drives
  the buyer's three messages explicitly.
• Five-entry aimock fixture instead of three — opener text →
  preview tool_use → preview reply text → close tool_uses × 3 →
  final confirmation text, organised per-send (see above).
• The Asaas MCP get_installments preview path — the agent
  calls get_installments(value: 4800, installments: 6) without an
  id to get a hypothetical schedule before committing. The
  response shape carries preview: true and status: "PREVIEW" per
  installment so the test (and the agent) can distinguish a preview
  from a real payment schedule.
• package-lock.json committed — npm ci in the
  validate-example-whatsapp-installment-negotiation CI job
  requires it, pinned against the published
  @codespar/mcp-asaas@0.2.0.

Files

File	Purpose
package.json	Exact pins: @codespar/mcp-asaas@0.2.0, @codespar/mcp-nuvem-fiscal@0.3.0, @codespar/mcp-z-api@0.2.1, @codespar/sdk@^0.9.0
package-lock.json	Lockfile against the published @codespar/mcp-asaas@0.2.0; required by npm ci in CI
mcp-servers.json	Three stdio servers — asaas, nuvem-fiscal, z-api, all with --demo
fixtures/aimock-fixtures.json	Five fixture entries organised per-send (turnIndex restarts at 0 each send, userMessage discriminators on the two turnIndex 1 continuations); turn 2's "R$800,00" text is hardcoded to match the Asaas demo handler's deterministic installmentValue: 800 for value: 4800 / installments: 6
skeleton.test.ts	Three-send() test asserting the Asaas preview, the create_payment with installments: 6, the NF-e issuance, and the WhatsApp confirmation
live.test.ts	Same flow against real Claude, gated on CODESPAR_LIVE_SMOKE=1, coarse assertions tolerant of LLM probabilism
scripts/validate.sh	Same three runtime modes as the NFS-e example, container name updated to codespar-example-installments-$$
scripts/validate-live.sh	Same modes minus aimock, requires ANTHROPIC_API_KEY
tsconfig.json / vitest.config.ts / .npmrc / .gitignore	Identical to the NFS-e example
.github/workflows/ci.yml	New validate-example-whatsapp-installment-negotiation job, same shape as the existing validate-example-nfse-from-natural-language job

Acceptance criteria

The skeleton.test.ts spec asserts:

1. Turn 1 — string message, no tool calls (opener is conversation only).
2. Turn 2 — exactly one asaas__get_installments call with
   input.value === 4800 and input.installments === 6, output carrying
   preview: true, installmentCount: 6, installmentValue: 800, and a
   six-entry installments array.
3. Turn 3 — exactly one asaas__create_payment call with
   billingType: "CREDIT_CARD", value: 4800, installments: 6, output
   carrying id matching /^pay_demo_/, installments: 6,
   installmentValue: 800.
4. Turn 3 — exactly one nuvem-fiscal__create_nfe call returning
   id matching /^nfe_demo_/ and status === "autorizada".
5. Turn 3 — at least one z-api__send_text call whose message
   matches /confirm/i.
6. Cross-turn — total iterations >= 3 across the three calls.
7. Cross-turn — every dispatched tool call records
   status === "success".

Out of scope

• Live test does not yet assert z-api__send_text presence. The
  skeleton test does, but the live test's coarse assertions skip
  this. Filed as a follow-up; not a blocker for merging this example.
• Installment-interest impact on NF-e taxable amount. Brazilian
  credit-card installments often carry juros parcelado that
  increases the NF-e taxable amount. The Asaas demo handler computes
  value / installments flat; the NF-e is issued for the original
  sticker price. Documented in the README as a known gap.
• A delete_payment cleanup path if the buyer backs out after the
  preview. The preview path now exists precisely to avoid creating
  payments tentatively, so the cleanup case is no longer needed. The
  demo never creates a payment until the buyer confirms.
• The Nuvem Fiscal pagamento echo for create_nfe. Not
  required for this example — the existing canned demo response is
  sufficient. Can land as a focused follow-on if a future demo needs
  to assert installment terms round-trip into the NF-e response.