@sales-bot-llm/sdk 0.2.0

package/docs/superpowers/plans/2026-05-11-w3-sales-tool-polish-plan.md

@@ -0,0 +1,476 @@
+# Workstream 3: SDK Sales-Tool Polish — Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development. Steps use checkbox (`- [ ]`) syntax.
+
+**Goal:** Surface the new backend sales-workflow tool events as first-class SDK citizens — typed name discriminators, a hook callback for consumers, and friendly widget UI pills. Additive only; no breaking changes.
+
+**Architecture:** Tiny additions to `src/core/types.ts` (literal union + type guard), `src/core/index.ts` (re-export), `src/react/use-sales-bot.tsx` and `src/vue/use-sales-bot.ts` (new optional `onSalesToolCall` callback), `src/widget/widget.ts` + `src/widget/styles.ts` (ephemeral status pill). One test file.
+
+**Tech Stack:** TypeScript SDK (tsup build), Vitest, vanilla DOM widget.
+
+**Design spec:** `/Users/artemzaitsev/projects/chaindoc/sales_bot/docs/superpowers/specs/2026-05-11-sales-workflow-dashboard-and-sdk-design.md` §6 + §3 rows 17-20.
+
+---
+
+## Hard constraints
+
+1. **Additive only — zero breaking changes.** Existing consumers continue to work without code changes.
+2. **No new dependencies.** No npm installs.
+3. **Existing tests stay green.**
+4. **Version bump to `0.2.0`** in `package.json` reflects non-breaking additions.
+5. **Wire types unchanged.** The new exports describe known tool *names*; they don't add new event types to `SalesBotEvent`.
+
+---
+
+## File map
+
+| File | Action | Responsibility |
+|---|---|---|
+| `src/core/types.ts` | **Modify** | Add `SALES_WORKFLOW_TOOL_NAMES`, `SalesWorkflowToolName`, `isSalesWorkflowTool`. |
+| `src/core/index.ts` | **Modify** | Already does `export * from './types'`, so the new exports flow through automatically. No edit needed if `*` re-export is in place. |
+| `src/react/use-sales-bot.tsx` | **Modify** | Add `onSalesToolCall?: (e: ToolCallStartedEvent) => void` to `UseSalesBotOptions`; subscribe to `tool_call_started`, narrow on `isSalesWorkflowTool`, fire callback. |
+| `src/vue/use-sales-bot.ts` | **Modify** | Same as the React hook. |
+| `src/widget/widget.ts` | **Modify** | When a `tool_call_started` event matches a sales tool name, render an ephemeral status pill above the next assistant message. Remove on `tool_call_finished` with matching id. |
+| `src/widget/styles.ts` | **Modify** | CSS for the status pill. |
+| `tests/sales-tool-discriminator.spec.ts` | **Create** | Vitest unit tests for `isSalesWorkflowTool` + the React hook callback firing on the right events. |
+| `package.json` | **Modify** | Bump version `0.1.0` → `0.2.0`. |
+
+---
+
+## Task 1: Baseline
+
+- [ ] **Step 1.1:** Confirm baseline:
+
+```bash
+pnpm install
+pnpm test --run 2>&1 | tail -8
+pnpm tsc --noEmit
+```
+
+Expected: existing tests pass; tsc clean.
+
+- [ ] **Step 1.2:** Note baseline test count. No commit.
+
+---
+
+## Task 2: Types + type guard + tests (RED → GREEN)
+
+**Files:**
+- Modify: `src/core/types.ts`
+- Create: `tests/sales-tool-discriminator.spec.ts`
+
+- [ ] **Step 2.1:** Write the failing test first.
+
+```typescript
+// tests/sales-tool-discriminator.spec.ts
+import { describe, it, expect } from 'vitest';
+import {
+  SALES_WORKFLOW_TOOL_NAMES,
+  isSalesWorkflowTool,
+  type SalesWorkflowToolName,
+} from '../src/core/types';
+
+describe('SALES_WORKFLOW_TOOL_NAMES', () => {
+  it('is a readonly tuple containing all five sales-workflow tool names', () => {
+    expect(SALES_WORKFLOW_TOOL_NAMES).toEqual([
+      'project_brief__set_field',
+      'project_brief__get_current',
+      'quotes__generate',
+      'quotes__send_as_pdf',
+      'quotes__send_as_proposal',
+    ]);
+  });
+});
+
+describe('isSalesWorkflowTool', () => {
+  it('returns true for each sales-workflow tool name', () => {
+    expect(isSalesWorkflowTool('project_brief__set_field')).toBe(true);
+    expect(isSalesWorkflowTool('project_brief__get_current')).toBe(true);
+    expect(isSalesWorkflowTool('quotes__generate')).toBe(true);
+    expect(isSalesWorkflowTool('quotes__send_as_pdf')).toBe(true);
+    expect(isSalesWorkflowTool('quotes__send_as_proposal')).toBe(true);
+  });
+
+  it('returns false for unrelated tool names', () => {
+    expect(isSalesWorkflowTool('chaindoc_media_upload')).toBe(false);
+    expect(isSalesWorkflowTool('llms_txt__search')).toBe(false);
+    expect(isSalesWorkflowTool('')).toBe(false);
+    expect(isSalesWorkflowTool('quotes__')).toBe(false);
+    expect(isSalesWorkflowTool('project_brief__unknown')).toBe(false);
+  });
+
+  it('narrows the type when used as a type guard', () => {
+    const name: string = 'quotes__generate';
+    if (isSalesWorkflowTool(name)) {
+      // Inside this branch, TypeScript narrows `name` to `SalesWorkflowToolName`.
+      const narrowed: SalesWorkflowToolName = name;
+      expect(narrowed).toBe('quotes__generate');
+    }
+  });
+});
+```
+
+- [ ] **Step 2.2:** Run the test — confirm it fails with "Cannot find module" or undefined-export.
+
+```bash
+pnpm test --run tests/sales-tool-discriminator.spec.ts 2>&1 | tail -10
+```
+
+Expected: red.
+
+- [ ] **Step 2.3:** Add to `src/core/types.ts` — append at the bottom of the file (after the existing exports):
+
+```typescript
+// ---------------------------------------------------------------------------
+// Sales-workflow tool name discriminators
+// ---------------------------------------------------------------------------
+//
+// The backend's SalesWorkflowDispatcher registers these tools with the LLM
+// alongside MCP tools. They surface to the SDK via standard `tool_call_started`
+// / `tool_call_finished` events with the names below. Consumers can narrow on
+// these names via `isSalesWorkflowTool` for typed handling.
+
+/** All sales-workflow tool names. Order is intentional (set_field/get_current
+ *  first, quotes after). */
+export const SALES_WORKFLOW_TOOL_NAMES = [
+  'project_brief__set_field',
+  'project_brief__get_current',
+  'quotes__generate',
+  'quotes__send_as_pdf',
+  'quotes__send_as_proposal',
+] as const;
+
+export type SalesWorkflowToolName = (typeof SALES_WORKFLOW_TOOL_NAMES)[number];
+
+/** Type guard for narrowing tool-call event names to SalesWorkflowToolName. */
+export function isSalesWorkflowTool(name: string): name is SalesWorkflowToolName {
+  return (SALES_WORKFLOW_TOOL_NAMES as readonly string[]).includes(name);
+}
+```
+
+- [ ] **Step 2.4:** Verify `src/core/index.ts` already does `export * from './types'`. If yes, no edit needed — the new exports flow through automatically. If it lists named re-exports instead, add the three names there.
+
+- [ ] **Step 2.5:** Run the test — confirm 8/8 pass:
+
+```bash
+pnpm test --run tests/sales-tool-discriminator.spec.ts 2>&1 | tail -10
+```
+
+Expected: green.
+
+- [ ] **Step 2.6:** `pnpm tsc --noEmit` — clean.
+
+- [ ] **Step 2.7:** Commit:
+
+```bash
+git add src/core/types.ts src/core/index.ts tests/sales-tool-discriminator.spec.ts
+git commit -m "$(cat <<'EOF'
+feat(core): SalesWorkflowToolName + isSalesWorkflowTool guard
+
+Adds typed discriminators for the five sales-workflow tool events
+the backend dispatches alongside MCP tools. Wire format is unchanged
+— these names already arrive through the existing `tool_call_started`
+/ `tool_call_finished` events. Consumers can now narrow on them with
+type safety:
+
+  client.on('tool_call_started', (e) => {
+    if (isSalesWorkflowTool(e.name)) {
+      // e.name is narrowed to SalesWorkflowToolName
+    }
+  });
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 3: React + Vue hook `onSalesToolCall` callback
+
+**Files:**
+- Modify: `src/react/use-sales-bot.tsx`
+- Modify: `src/vue/use-sales-bot.ts`
+
+- [ ] **Step 3.1:** React hook — read the existing `UseSalesBotOptions` definition, then extend it:
+
+In `src/react/use-sales-bot.tsx`, find:
+
+```typescript
+export interface UseSalesBotOptions extends SalesBotClientOptions {
+  /** Optional initial conversationId (e.g. restored from URL hash) */
+  conversationId?: string
+}
+```
+
+Add to this interface:
+
+```typescript
+/**
+ * Fires when a sales-workflow tool call starts (e.g. quotes__send_as_pdf).
+ * Convenience over manually filtering tool_call_started events via
+ * isSalesWorkflowTool. Pass-through; receives the same payload.
+ */
+onSalesToolCall?: (event: import('../core/types').ToolCallStartedEvent) => void
+```
+
+Inside the hook body, after the client is constructed and the event subscription block, wire up the callback. Find the existing `tool_call_started` handler (if any) or the `client.on(...)` subscription pattern. If the hook currently subscribes to events in a `useEffect`, add a sibling subscription:
+
+```typescript
+useEffect(() => {
+  if (!opts.onSalesToolCall) return;
+  const client = clientRef.current;
+  if (!client) return;
+  const handler = (e: import('../core/types').ToolCallStartedEvent) => {
+    // Lazy-load isSalesWorkflowTool from the same module to avoid widening
+    // the runtime cost when consumers don't use this callback.
+    const { isSalesWorkflowTool } = require('../core/types') as typeof import('../core/types');
+    if (isSalesWorkflowTool(e.name)) {
+      opts.onSalesToolCall!(e);
+    }
+  };
+  const off = client.on('tool_call_started', handler);
+  return () => { if (typeof off === 'function') off(); };
+}, [opts.onSalesToolCall]);
+```
+
+If the existing hook subscribes via `client.on(...)` returning an unsubscribe function, use that. If it uses async iteration over `client.events()` or similar, adapt this to match the existing subscription pattern. Read the actual file before writing the snippet — the comment above is the intent, not the literal final code.
+
+`import('../core/types').ToolCallStartedEvent` is used in-line (no top-level type import) to keep the existing imports list minimal — change to a top-of-file import if the file's style prefers that.
+
+- [ ] **Step 3.2:** Vue hook — same change in `src/vue/use-sales-bot.ts`. The Vue composable structure differs (uses Vue refs / watchers); follow the existing event-subscription pattern in that file.
+
+- [ ] **Step 3.3:** Type-check:
+
+```bash
+pnpm tsc --noEmit
+```
+
+Expected: clean.
+
+- [ ] **Step 3.4:** Run the existing test suite — confirm nothing regressed:
+
+```bash
+pnpm test --run 2>&1 | tail -8
+```
+
+Expected: all pass.
+
+- [ ] **Step 3.5:** Commit:
+
+```bash
+git add src/react/ src/vue/
+git commit -m "$(cat <<'EOF'
+feat(hooks): onSalesToolCall callback in React + Vue hooks
+
+Optional hook option that fires for sales-workflow tool calls
+(quotes__*, project_brief__*) only. Convenience over manually
+filtering tool_call_started events with isSalesWorkflowTool.
+Additive — existing consumers continue to work unchanged.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 4: Widget UI pills
+
+**Files:**
+- Modify: `src/widget/widget.ts`
+- Modify: `src/widget/styles.ts`
+
+- [ ] **Step 4.1:** Pill text mapping. In `src/widget/widget.ts`, near the top (after imports), add:
+
+```typescript
+import { isSalesWorkflowTool, type SalesWorkflowToolName } from '../core/types';
+
+const SALES_TOOL_PILL_TEXT: Record<SalesWorkflowToolName, string> = {
+  'project_brief__set_field': 'Saving project details…',
+  'project_brief__get_current': 'Checking project details…',
+  'quotes__generate': 'Generating quote…',
+  'quotes__send_as_pdf': 'Sending quote PDF…',
+  'quotes__send_as_proposal': 'Sending proposal for signing…',
+};
+```
+
+- [ ] **Step 4.2:** Find the existing `tool_call_started` / `tool_call_finished` handlers in the widget. They currently call `ensureThinking()` etc. Augment them so:
+
+- On `tool_call_started` with a sales tool name: also create a pill DOM element with the matching text, append to the current message-stream container, and track it by the event's `id`.
+- On `tool_call_finished` with a sales tool name (matching id): remove the pill. If `ok: false`, briefly (4 seconds) replace the pill text with "Error" before removing.
+
+Suggested implementation — adapt to match the existing widget file's idioms:
+
+```typescript
+// State at the module / instance scope (where other widget state lives):
+const salesPills = new Map<string, HTMLElement>();
+
+// Inside the tool_call_started handler:
+case 'tool_call_started': {
+  ensureThinking();
+  if (isSalesWorkflowTool(event.data.name)) {
+    const pill = document.createElement('div');
+    pill.className = 'sb-sales-pill';
+    pill.textContent = SALES_TOOL_PILL_TEXT[event.data.name as SalesWorkflowToolName];
+    // Append to whatever container the widget uses for the active message stream.
+    // If you keep a reference to the "current assistant message" container, append there;
+    // otherwise append to a known stream root.
+    streamContainer.appendChild(pill);
+    salesPills.set(event.data.id, pill);
+  }
+  break;
+}
+
+case 'tool_call_finished': {
+  const pill = salesPills.get(event.data.id);
+  if (pill) {
+    if (event.data.ok === false) {
+      pill.textContent = 'Error';
+      pill.classList.add('sb-sales-pill-error');
+      setTimeout(() => {
+        pill.remove();
+        salesPills.delete(event.data.id);
+      }, 4000);
+    } else {
+      pill.remove();
+      salesPills.delete(event.data.id);
+    }
+  }
+  // existing tool_call_finished handling continues:
+  // hideThinkingIfDone(); etc.
+  break;
+}
+```
+
+Read the current widget file before applying this; the `streamContainer` reference and the `ensureThinking()` / `hideThinkingIfDone()` helpers must come from the existing widget code.
+
+- [ ] **Step 4.3:** Append pill styles in `src/widget/styles.ts`. The widget styles are CSS-in-template-strings or similar; add a block:
+
+```css
+.sb-sales-pill {
+  display: inline-flex;
+  align-items: center;
+  margin: 4px 0;
+  padding: 4px 10px;
+  border-radius: 999px;
+  background: var(--sb-pill-bg, rgba(0, 0, 0, 0.05));
+  color: var(--sb-pill-fg, rgba(0, 0, 0, 0.7));
+  font-size: 12px;
+  line-height: 1.3;
+  animation: sb-sales-pill-pulse 1.8s ease-in-out infinite;
+}
+.sb-sales-pill-error {
+  background: var(--sb-pill-error-bg, rgba(255, 69, 58, 0.12));
+  color: var(--sb-pill-error-fg, rgba(155, 28, 28, 0.95));
+  animation: none;
+}
+@keyframes sb-sales-pill-pulse {
+  0%, 100% { opacity: 1; }
+  50%      { opacity: 0.55; }
+}
+```
+
+If `styles.ts` exports a single template string of CSS, append the rules into that string. If it exports a function that returns CSS, add inside the function body. Match the file's actual structure.
+
+- [ ] **Step 4.4:** Manually verify the widget compiles and renders (open `example/` against a local backend if available — optional). At minimum:
+
+```bash
+pnpm tsc --noEmit
+pnpm test --run 2>&1 | tail -8
+```
+
+Expected: clean + green.
+
+- [ ] **Step 4.5:** Commit:
+
+```bash
+git add src/widget/
+git commit -m "$(cat <<'EOF'
+feat(widget): ephemeral status pills for sales-workflow tool calls
+
+When the widget receives tool_call_started for project_brief__* or
+quotes__* events, it renders a small pulsing pill above the active
+assistant-message stream with friendly text ("Generating quote…",
+"Sending proposal for signing…", etc.). On tool_call_finished the
+pill is removed; on failure (ok=false) it briefly switches to an
+"Error" state for 4 seconds before vanishing.
+
+No-op for backends that don't dispatch these tool names — older
+SDK behavior is preserved.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Task 5: Version bump + final verification
+
+**Files:**
+- Modify: `package.json`
+
+- [ ] **Step 5.1:** Bump version in `package.json` from `0.1.0` to `0.2.0`:
+
+```bash
+# Edit package.json:
+#   "version": "0.1.0"  →  "version": "0.2.0"
+```
+
+- [ ] **Step 5.2:** Run the build to confirm the SDK still bundles cleanly:
+
+```bash
+pnpm build 2>&1 | tail -15
+```
+
+Expected: tsup outputs `dist/` files without errors. Size-limit checks (if present) should still pass.
+
+- [ ] **Step 5.3:** Final tests + tsc:
+
+```bash
+pnpm test --run 2>&1 | tail -8
+pnpm tsc --noEmit
+```
+
+Expected: all green.
+
+- [ ] **Step 5.4:** Commit:
+
+```bash
+git add package.json
+git commit -m "$(cat <<'EOF'
+chore: bump SDK version to 0.2.0
+
+Reflects additive sales-workflow polish:
+- typed SalesWorkflowToolName + isSalesWorkflowTool guard
+- onSalesToolCall callback on React + Vue hooks
+- widget status pills for the new tool events
+
+Non-breaking; existing consumers continue to work without changes.
+
+Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
+EOF
+)"
+```
+
+---
+
+## Out-of-scope follow-ups
+
+- Tool-call-specific entries on the `SalesBotEvent` discriminated union (current solution piggybacks on `tool_call_started`).
+- Operator-customizable pill text (operator sets the "Generating quote…" string per tenant).
+- Localization of pill text.
+
+---
+
+## Self-review notes
+
+Spec coverage:
+
+- §6.1 typed discriminators — Task 2.
+- §6.2 widget UI hints — Task 4.
+- §6.3 React/Vue hook callbacks — Task 3.
+- §6.5 version bump — Task 5.
+
+No placeholders. Each step's intent is spelled out with code blocks; the few places where the implementer must read the existing file before adapting (the widget pill insertion point, the hook subscription pattern) are explicitly flagged.