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.