---
id: WF-PFM-LLM-014
title: Refine a query or directory through Jazz AI
trigger: Change a query or directory through scoped Jazz AI assistance.
product_area: platform
module: llm
revision: 1
status: draft
design_intent: proposed
implementation_evidence: partially-observed
inference:
  - IOP-PFM-LLM-002
source_sha:
  react-console: baf6dae382d6f41dce976c7f848667ccc37e076f
  services-platform: ad3f6a6582843008ed0f5a17b131878d15829af1
implements:
  - CAP-PFM-LLM-020
  - CAP-PFM-LLM-019
moves:
  - STATE-PFM-LLM-008
crosses:
  - SVC-PFM-LLM-console-agent
  - SVC-PFM-LLM-llm
idempotency: >-
  Scope creation reuses matching identity, but applying descriptions and writing exchanges are not atomic or
  replay protected.
concurrency: >-
  The page blocks local concurrent sends but applies work before posting history. Other page changes and
  failed history writes have no shared transaction.
hops:
  - 'n': 1
    actor_or_service: Query workspace or record directory
    action: Register the current page scope and find or create its conversation with earlier messages.
    anchor: 'react-console:components/queries/query-workspace.tsx:openRefine'
    seam: sync
    on_failure: Show an error when scoped conversation opening fails.
    left_inconsistent: No assistance view opens successfully.
    observer: 'Visible work state, chat history and outcome toast.'
    provenance: observed
    source: 'react-console:components/agent/agent-provider.tsx:useAgentScope'
  - 'n': 2
    actor_or_service: Jazz AI chat
    action: Pass the description to the registered work handler.
    anchor: 'react-console:components/console/agent-chat.tsx:AgentChat'
    seam: sync
    on_failure: Restore text and show an error for a thrown handler.
    left_inconsistent: Further effects depend on where the handler failed.
    observer: 'Visible work state, chat history and outcome toast.'
    provenance: observed
    source: 'react-console:components/console/agent-chat.tsx:AgentChat'
  - 'n': 3
    actor_or_service: Query workspace and Queries generation (Describe With AI)
    action: >-
      For live queries, start and poll metered generation; demonstration queries and directories interpret
      locally.
    anchor: 'react-console:lib/queries/client.ts:interpret'
    seam: sync
    on_failure: Return a refusal or generation failure as the reply without changing work.
    left_inconsistent: The model attempt may incur cost despite no applied change.
    observer: 'Visible work state, chat history and outcome toast.'
    provenance: observed
    source: 'react-console:lib/queries/platform/client-live.ts:liveInterpret'
  - 'n': 4
    actor_or_service: Query workspace
    action: >-
      Apply generated criteria while preserving record type, context and prior column order, and retain undo
      state.
    anchor: 'react-console:components/queries/query-workspace.tsx:refine'
    seam: sync
    on_failure: A generation without a usable query does not enter this step.
    left_inconsistent: Applied work remains unsaved.
    observer: 'Visible work state, chat history and outcome toast.'
    provenance: observed
    source: 'react-console:components/queries/query-workspace.tsx:refine'
  - 'n': 5
    actor_or_service: Jazz AI chat and console conversation route
    action: Append the description and result after applying any screen change.
    anchor: 'react-console:lib/agent/client.ts:appendTurns'
    seam: sync
    on_failure: Show the write error and restore the submitted text.
    left_inconsistent: The screen can retain a change absent from conversation history; resending can apply another change.
    observer: 'Visible work state, chat history and outcome toast.'
    provenance: observed
    source: 'react-console:components/console/agent-chat.tsx:AgentChat'
  - 'n': 6
    actor_or_service: Jazz AI chat and query workspace
    action: Restore the prior work state before appending an undo note.
    anchor: 'react-console:components/console/agent-chat.tsx:AgentChat'
    seam: sync
    on_failure: Report note-write failure after the state has already reverted.
    left_inconsistent: History can still describe an applied change that was undone.
    observer: 'Visible work state, chat history and outcome toast.'
    provenance: observed
    source: 'react-console:components/queries/query-workspace.tsx:refine'
branches:
  - Detached scoped history links back to its work instead of invoking a refinement handler.
waits:
  - >-
    Console polling starts at one and a half seconds and grows to five, with a ninety-second deadline checked
    between awaited calls.
evidence:
  - >-
    react-console at baf6dae: components/console/agent-chat.tsx; components/agent/agent-provider.tsx;
    components/queries/query-workspace.tsx; components/record-explorer/use-explorer-assistant.ts;
    lib/queries/client.ts; lib/queries/platform/client-live.ts; lib/api/generate-query.ts;
    lib/agent/client.ts.
  - 'services-platform at ad3f6a6: modules/llm/catalog/llm-operations.ts (the operation Describe With AI runs).'
controls: [TC-AI-001, TC-AI-002, TC-AI-003, TC-AI-004, TC-AI-005, TC-AI-006, TC-AI-007, TC-AVL-001, TC-AVL-004, TC-AVL-005, TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-006, TC-CRY-001, TC-CRY-002, TC-CRY-003, TC-CRY-004, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-DAT-006, TC-IAM-001, TC-IAM-002, TC-IAM-004, TC-IAM-005, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-MON-001, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-004, TC-PI-005, TC-PRV-001, TC-PRV-002, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-VEN-001, TC-VEN-002, TC-VEN-003]
---

# Refine a query or directory through Jazz AI

## What It Does

The page supplies its own send and undo handlers. Live query refinement consumes metered generation; directories and demonstration mode use local interpretation.

## The Flow

```mermaid
flowchart TD
  H1["Register the current page scope and find or create its conversation with earlier messages."]
  H2["Pass the description to the registered work handler."]
  H1 --> H2
  H3["For live queries, start and poll metered generation; demonstration queries and directories interpret locally."]
  H2 --> H3
  H4["Apply generated criteria while preserving record type, context and prior column order, and retain undo state."]
  H3 --> H4
  H5["Append the description and result after applying any screen change."]
  H4 --> H5
  H6["Restore the prior work state before appending an undo note."]
  H5 --> H6
```

Find scoped history, interpret the description, apply an unsaved change with undo, then append the conversation exchange. Undo restores work before adding its note.

## When Something Fails

Appending history after a change can fail, leaving the screen and history disagreeing. Refusal leaves the work unchanged, even if the model attempt was charged.

## Open Design Questions

Decide request linkage and consistency between applied work and durable conversation history as part of the wider Jazz AI boundary.