# single-react-diagnosis-agent Specification

## Purpose
定义内部单体 Diagnosis ReactAgent 的极简输入、框架 ReAct/tool loop、Harness 模型与 Tool 边界、结构化 DiagnosisDraft、无证据停止、确定性预算和审计隔离要求。
## Requirements
### Requirement: Diagnosis execution SHALL use one framework ReactAgent
The internal diagnosis path SHALL create exactly one `diagnosis_agent` with the framework-provided ReAct/tool loop. It SHALL NOT create Planner, Executor, Verifier, Composer, SequentialAgent, SupervisorAgent, an outer business Graph, or a hand-written model/Tool loop. One use-case invocation SHALL call the Diagnosis Agent once and SHALL NOT wrap the Agent or any individual model call in Harness retry.

#### Scenario: Diagnosis needs Tool evidence
- **WHEN** the model emits one or more Tool actions before its final response
- **THEN** the same Diagnosis ReactAgent executes those actions through its framework loop and returns one final Draft without invoking another Agent

#### Scenario: Agent execution fails
- **WHEN** the single Diagnosis Agent invocation throws or returns invalid structured output
- **THEN** the internal use case fails closed without automatically invoking the Agent or model again
### Requirement: Diagnosis input SHALL contain only current Query and optional PreviousTurn
The internal use case SHALL accept a non-blank current Query and an optional frozen `PreviousTurn`, serialize them as the fixed `query` and `previous_turn` input fields, and SHALL NOT load or accept complete Session history, Redis memory, prior raw Tool results, or model-generated history summaries. The current Query SHALL retain its original text and SHALL NOT be rewritten or silently truncated.

#### Scenario: Follow-up diagnosis has a safe previous turn
- **WHEN** a caller supplies a `PreviousTurn`
- **THEN** the Agent receives exactly the frozen previous-turn fields plus the current Query and no complete conversation history

#### Scenario: Query exceeds configured context budget
- **WHEN** the current Query exceeds its UTF-8 byte limit
- **THEN** the use case rejects it before any model call instead of truncating or rewriting it
### Requirement: Every model round SHALL be controlled by RunContext
The Diagnosis Agent SHALL receive `RunContext` explicitly and SHALL use a model interceptor to call `DiagnosisHarnessCore.beforeModelCall` for every framework ReAct model round. Non-streaming model response Usage SHALL be recorded into the same Run budget when available. Cancellation, deadline, model-call exhaustion, or Token exhaustion SHALL prevent subsequent controlled work.

#### Scenario: ReAct performs two model rounds
- **WHEN** one model round requests a Tool and the next produces the Draft
- **THEN** the same Run budget records two model calls and no Harness retry attempt

#### Scenario: Model-call budget is exhausted
- **WHEN** the framework attempts a model round beyond the configured maximum
- **THEN** the call is rejected before reaching ChatModel and the Run records budget exhaustion
### Requirement: Evidence Tools SHALL execute through the Harness boundary
The Diagnosis Agent SHALL expose only the frozen `lookup_knowledge`, `query_logs`, and `query_mysql` definitions through native Tool Calling. Each Agent-facing Tool input SHALL be a typed Envelope containing optional `previous_observation` and required business `input`. A Tool interceptor SHALL validate and consume the previous observation, propagate the exact framework Tool Call ID, Run ID, Tool name, and unwrapped business JSON into the corresponding adapter and `ToolBoundary`, and SHALL enforce Run progress before execution. Successful observations SHALL use a bounded per-Tool whitelist projection; failed or control observations SHALL contain only stable safe semantics and SHALL NOT contain raw responses, internal exceptions, credentials, invocation lifecycle internals, counters, thresholds, or remaining budget.

#### Scenario: Framework requests first RAG evidence
- **WHEN** the model calls `lookup_knowledge` with framework ID `call-1`, no pending evaluation and a typed business input
- **THEN** the RAG adapter receives only the unwrapped business request, uses exactly `call-1`, and the canonical invocation is owned by the current Run

#### Scenario: Model continues after a non-empty result
- **WHEN** the last successful Tool result is pending semantic evaluation and the model requests another Tool
- **THEN** the Envelope must identify that exact prior Tool Call and contain `GAINED` or `NO_GAIN` before the new business Tool can execute

#### Scenario: Model omits required progress field
- **WHEN** a prior non-empty Tool observation is pending and the model requests another Tool without `previous_observation`
- **THEN** the business Tool does not execute and the Agent receives a bounded repair observation explaining the missing `previous_observation` field and expected prior Tool Call ID

#### Scenario: Tool execution fails
- **WHEN** a registered adapter returns an error result
- **THEN** the Agent receives `evidence_status=ERROR`, the framework Tool Call ID and a stable error code without automatic Tool retry or raw failure detail

#### Scenario: Unknown Tool is requested
- **WHEN** a model requests a Tool outside the three registered definitions
- **THEN** the Harness does not authorize or emulate it and does not create a canonical evidence record
### Requirement: Diagnosis output SHALL be a bounded DiagnosisDraft
The Agent SHALL receive the generated schema for `DiagnosisDraft` and SHALL return JSON that the internal use case strictly parses into the frozen record. The use case SHALL enforce configured UTF-8 limits for query, previous turn, total input and Draft output and account accepted input/output bytes against the Run capacity. It SHALL reject blank, fenced, prefixed, malformed, oversized or schema-incompatible output without repair or retry.

#### Scenario: Supported Draft is returned
- **WHEN** the Agent returns valid JSON containing Conclusion, Analysis items, Action Plan, Recommendations and Limitations
- **THEN** the use case returns a `DiagnosisDraft` whose Analysis Tool Call IDs are the exact strings emitted by the Agent

#### Scenario: Model returns prose around JSON
- **WHEN** the final response contains a Markdown fence or explanatory prefix around an otherwise valid object
- **THEN** strict parsing fails and the Diagnosis Agent is not invoked a second time
### Requirement: Insufficient evidence SHALL terminate without a fabricated conclusion
The single Chinese Prompt SHALL require every normal Analysis item to cite current-Run evidence Tool Call IDs and SHALL restrict `NO_EVIDENCE` to scoped `NEGATIVE_OBSERVATION`. The Agent SHALL NOT be required to find a root cause. If current evidence cannot support a diagnosis, no required context exists for a bounded Tool call, or available results are correct but do not advance any diagnosis hypothesis, the Agent SHALL stop with `conclusion=null`, describe actual scope and missing information in `limitations`, and SHALL NOT infer that the problem does not exist, fabricate a root cause, or make equivalent Tool calls merely to show activity.

#### Scenario: Tool finds no evidence
- **WHEN** completed Tool observations have no diagnostic information gain
- **THEN** the final Draft has no confirmed Conclusion, records bounded checked scope and missing information, and does not make an equivalent retry

#### Scenario: No bounded Tool query is possible
- **WHEN** the Query lacks required enterprise, time, service or error context
- **THEN** the Agent may perform zero Tool calls and returns a no-conclusion Draft whose `limitations.missing_info` identifies the required context

#### Scenario: Harness requires stop
- **WHEN** the Agent receives `STOP_REQUIRED`
- **THEN** it emits a bounded final Draft without another Tool call
### Requirement: Stage-four execution SHALL remain internal and auditable
The new use case SHALL be callable only as an internal Java/test entry in this stage and SHALL NOT be wired into public Chat or AIOps controllers. It SHALL propagate the same sessionId/runId through RunnableConfig metadata, allow the existing AgentStep Hook to be injected, retain ToolBoundary canonical invocation audit, and leave final Run success/persistence ownership to later Guard/application stages.

#### Scenario: Internal audited execution completes
- **WHEN** an injected audit Hook observes a model round and a Tool executes
- **THEN** both observe the same RunContext sessionId/runId and the public Chat call path remains unchanged

#### Scenario: Stage four is archived
- **WHEN** focused Agent tests pass and the change is archived
- **THEN** `ChatController`, public SSE behavior and the old multi-Agent implementation remain available for stages 5, 6A and 6B
### Requirement: Diagnosis execution SHALL preserve controlled stop outcomes
The internal Agent use case SHALL distinguish a valid Draft, controlled information saturation, and budget termination from an unclassified Agent failure. It SHALL return a bounded internal execution result containing optional Draft, ProgressSnapshot and stop reason, and SHALL NOT convert a recognized controlled stop into `DiagnosisAgentOutputException`.

#### Scenario: Model ignores STOP_REQUIRED
- **WHEN** the framework surfaces the typed collection-stopped signal after the final completion opportunity
- **THEN** the Agent use case returns no Draft with the controlled stop reason and the current ProgressSnapshot

#### Scenario: Unclassified framework failure
- **WHEN** Agent execution throws an exception unrelated to controlled stop, cancellation, or budget termination
- **THEN** execution still fails closed and no safe progress is fabricated

#### Scenario: Invalid final Draft after verified checks
- **WHEN** the final model text is empty or violates the strict DiagnosisDraft contract after the current Run has completed READY canonical Tool checks
- **THEN** the invalid text is discarded, the output failure carries only the bounded ProgressSnapshot and safe failure metadata, and no model repair or loose JSON extraction occurs

#### Scenario: Invalid final Draft without verified checks
- **WHEN** the final model text violates the strict DiagnosisDraft contract before any publishable ProgressSnapshot exists
- **THEN** execution remains failed and MUST NOT fabricate missing context, observed facts or a no-conclusion Draft