STATE_OVERVIEW_REMOVAL_DESIGN.md4.7 KBView on GitHub # Remove the agent state-overview (score / notification) subsystem — DONE
Split out of `conversations/AGENTS_INTO_FILES_DESIGN.md` (Phases 3–5) and executed as one commit.
## The critical distinction (why this was subtle)
`statusOverview` names **two unrelated things**:
1. **Agent state overview (concept #1) — REMOVED.** A per-`(agent, conversation)` **score / notification**
widget: `AgentState.statusOverview: { type: 'score' } | { type: 'notification' } | null`, backed by
the `agent_conversation_states` table (`synthesized_output`, `awake`, `reasoning`) and the
`aop_agents.state_overview_config` column, written by `updateAgentStateOverviewTool`. Surfaced as
`conversationData.data.agents[]`, rendered by `ScoreCircle`/notification pills, dynamic `ags_*`
canvas columns, the AgentRow badge, the timeline agent-state cards, and the debugger tab.
2. **Conversation status-overview text field (concept #2) — KEPT, untouched.** A plain-text summary
field `conversation.statusOverview: string | null` backed by `crm_conversations.status_overview`,
written by the dashboard tool / CRM updater / external-CRM sync and read by export, SSE, statistics,
the overview card, CRM columns, kanban, etc. (~40 server + ~15 client refs). Completely separate;
only shares the name.
A first parallel pass conflated the two and stripped both; it was reverted, and the removal redone
scoped strictly to concept #1 (keyed on `AgentState`/`data.agents`/`ags_`/`agent-state`/
`stateOverviewConfig`/`agentConversationStates`/`synthesizedOutput` — never `statusOverview`/
`status_overview`/`CEDAR_OVERVIEW_FIELDS`).
## What was removed
- [x] **Server tool/schema:** deleted `mastra/tools/agent-state/updateAgentStateOverviewTool.ts` and
`services/aop/agent-state-schemas.ts`; removed their registrations in `automation-agent.ts` /
`on-event-execution-agent.ts`; removed the `<state_overview_config>` instruction block in
`automations.ts`; removed `stateOverviewConfig` from the aop-agents route + service +
`runSubagentTool` + `playbook-execution-triggers` + `playbook-doc-hooks` (and the now-dead
`findSubagentByAgentId`); deleted the `listStatesForConversation` procedure.
- [x] **Server hydration:** removed the `agent_conversation_states` subquery + `agents[]` assembly +
`agents?` field in `services/crm/conversations.ts`. **Kept** `conversation.statusOverview`
(`row.status_overview`).
- [x] **Server schema:** removed the `agentConversationStates` table + relations, the
`aop_agents.state_overview_config` column, and the `StateOverviewConfig`/`SynthesizedOutput`
types from `db/aop-schema.ts` + `db/schema.ts` re-exports. **Kept** `CEDAR_OVERVIEW_FIELDS`'s
`statusOverview` and `ConversationFieldDefinitions.statusOverview` (concept #2).
- [x] **Client types:** removed `AgentState` interface + `HydratedConversation.agents` from
`crm/types/index.ts`.
- [x] **Client render/columns:** removed `agentStateColumns` (`use-canvas-configuration`), the
`ags_*`/`agent-state` cases (`ConversationItem`, `crmSlice` union, `filter-sort-helpers`,
`utils/index` colors, `FilterSortConfigurationRow` popover), the `agents` mapping in
`use-canvas-conversations` + `use-conversations-sidebar-conversations`, the AgentRow badge, the
timeline agent-state rendering (`ConversationBodyContent`, `PastEventsTimeline`, `SlackTimeline`,
`TimelineTab.test`), and the `stateOverviewConfig`/`OverviewPreview`/`NotificationPill`/template
`outputType` config in `AgentsEditor`.
- [x] **Deleted files:** `AgentStateCellRenderer.tsx`, `AgentStateColumnPopover.tsx`,
`debugger/components/AgentStateDebuggerTab.tsx`.
- [x] **DB migration authored** (`db/migrations/drop_agent_state_overview.sql`) — idempotent
`DROP TABLE agent_conversation_states` + `ALTER TABLE aop_agents DROP COLUMN state_overview_config`.
**Not auto-applied** (destructive DDL on shared staging; leaving the orphaned table/column is
harmless since no code references them). Apply manually per the hand-authored-migration convention.
- [x] **Kept (concept #2):** `ScoreCircle` / `ScoreNode` (generic score primitives still used by chat
markdown, agent demo pages, and doc inline scores) and the entire `conversation.statusOverview`
text-field stack.
## Verification
- Concept-#1 symbol sweep across `apps/mail` + `apps/server/src`: zero refs.
- `apps/mail` tsc: no new errors vs the pre-removal baseline (client + server, since the mail project
also typechecks `../server`).
- Server tests `aop-agents-router.test.ts` + `automations-service.test.ts`: 25 passing.
- Frontend rendering (CRM table/kanban/canvas/agenda/overview) is runtime-only — verify in the app.