# Agent Thinking Block

This file defines the product intent and high-level behavior of the thinking block. It should stay short. Visual details, motion, layout rules, command shapes, and implementation logic belong in `reference/workspace.html`.

## Purpose

The thinking block is a temporary inline view of the agent's working state. It replaces a generic "thinking" placeholder with a structured sense of progress.

Its job is to help users understand:
- what the agent is working on now
- what the strongest active context is
- what is likely to happen next

It is not the final output, and it is not a raw chain-of-thought transcript.

## Core concept

The thinking block is a compact execution brief inside the conversation.

- A single ongoing activity shows what the agent is doing right now.
- A short thought queue shows a rolling working set: two active thoughts and one pending thought.
- The pending thought should visibly promote into the active set on the next update.
- The user observes the block. They do not interact with it.

## Design principles

- Show direction, not internal noise.
- Prefer structure over volume.
- Keep the block calm, restrained, and readable.
- Keep the block bounded. Preserve useful concepts, not every breadcrumb.
- Make progress feel continuous, not chaotic.
- Let the block leave cleanly once the response begins.

## High-level behavior

1. The block appears when agent execution starts.
2. One ongoing activity is always visible while the block is present.
3. The thought queue stays capped at two active thoughts and one pending thought.
4. Each thought update shifts the queue forward: the older active context falls away, the current active thought settles into context, and the pending thought promotes into the active set.
5. The block should stay small enough to scan quickly. Preserve only the most useful working context.
6. The block exits when the response begins, or when execution ends due to failure or cancellation.

## Activity model

The ongoing activity line should describe the most legible current action in plain language. In practice, the live implementation expresses a small set of recognizable activity families:

- absorbing a new signal or concept
- calling a tool or waiting on a tool
- folding a tool result back into the working set
- comparing candidate paths
- linking related signals
- converging on a stronger direction
- clearing stale context

## Content model

Each update in the block should express:
- the current ongoing activity in plain language
- up to three short thought labels in the queue
- which thoughts are active versus pending

Thought labels should be short and scannable. Use one plain-language label per visible thought, ideally around 5-8 words.

The visible queue uses three roles:
- active context
- active now
- pending, which is explicitly framed as next in line

The queue should be derived from the strongest recent thought labels, not from every intermediate step. Duplicate labels should collapse rather than reappear as noise.

## Lifecycle

### During execution

The block updates as the agent works. It should feel like one continuing process, not a series of disconnected scenes. The activity line may refresh between larger queue shifts so the user still sees motion during longer steps.

### Handoff

When the final response begins, the block resolves its current state, visually recedes, and exits. The response becomes the primary artifact in the conversation.

### Failure or cancel

The block should still exit cleanly. It should not remain as dead UI after work stops.

## Spec boundary

This document should only describe the product idea, the user-facing purpose, and the high-level logic.

Do not duplicate implementation detail here, including:
- exact visuals or styling values
- animation timings or easing
- DOM or canvas structure
- layout and collision rules
- command schemas or function signatures
- mapping heuristics, prompts, or algorithms
- renderer lifecycle details

Those details belong in `reference/workspace.html`.