Pricebook Agent joins the CPQ Config Agent

A new specialist sub-agent for pricebook CRUD, plus orchestrator wiring that resolves the target pricebook before any product-create action plan.

Entity legend

1. Why this exists

2. The four-agent delegation model

Before this PR the orchestrator delegated to three specialists. Pricebook management had no owner — the orchestrator either lacked the capability or had to shoehorn it into the Product Catalog Agent's turn. Now it's its own surface with its own approval type (specType: "pricebooks").

3. The pricebook resolution flow

The most consequential orchestrator change is a new rule: before proposing any action_plan that creates products, resolve the target pricebook. The branch is deterministic on the count returned by listPricebooks.

4. Reference semantics — the delete guard

Pricebook deletion is the interesting part. Because pricebook writes are live-instant but product writes are drafts, a pricebook counts as referenced by the union of live and staged product rows. The comment block at the top of pricebookContext.ts is the canonical spec.

A product mid-move counts under both pricebooks until the move publishes. That's why liveProductCount and stagedOnlyProductCount are reported separately — the sub-agent's reason string tells the user exactly which lever to pull for each kind.

5. The five pricebook tools

6. Serialization: withResourceLock

Pricebook writes never touch the versioning manifest — they're plain relational rows. Reusing the existing withSpecLock would serialize them against unrelated draft saves for no reason.

7. Sub-agent runner consolidation

Three existing sub-agent files (productCatalogAgent.ts, approvalRuleAgent.ts, userManagementAgent.ts) all contained an identical ~50-line block: build the ReAct agent, invoke with limits, walk messages backwards to find the final AI text, log telemetry. The new file extracts it.

// subAgentRunner.ts — the whole file, in essence
export async function runSubAgent(params: {
  agent: string;                 // telemetry label
  tools: any[];
  systemPrompt: string;
  question: string;
  config: AgentRuntimeConfig;
  signal?: AbortSignal;
}): Promise<string> {
  const agent = createReactAgent({ llm: createSubAgentLLM(), tools, prompt: systemPrompt });
  const result = await agent.invoke(
    { messages: [new HumanMessage(question)] },
    { recursionLimit, signal, timeout },
  );
  const toolsUsed = extractToolCallNames(result.messages);
  const raw = extractFinalAiText(result.messages) || '{"error":"..."}';
  const augmented = augmentWithToolsUsed(raw, toolsUsed);
  logSubAgent({ agent, orgSlug, iterations, ... });
  return augmented;
}

The per-agent files now contain only their system prompt and tool set. approvalRuleAgent.ts drops from 70 lines of scaffolding to 17. extractFinalAiText moves to subAgentCommon.ts — the Gemini array-content flatten quirk documented once, applied everywhere.

8. Type-level single source of truth

The specType vocabulary for action_plan was previously repeated in three places: the TypeScript union, the main orchestrator prompt, and the active-plan prompt fragment. Adding "pricebooks" without a central constant would drift.

// types.ts
export const PLANNED_ACTION_SPEC_TYPES = [
  'catalogProducts', 'pricingSpec', 'workflowSpec',
  'datasheet', 'attributes', 'pricebooks',   // ← added
] as const;

export type PlannedActionSpecType = (typeof PLANNED_ACTION_SPEC_TYPES)[number];

Prompt strings now interpolate ${PLANNED_ACTION_SPEC_TYPES.join('|')}. Editing the array updates the TS union and both prompts.

9. What it doesn't change

10. Risks & open questions