feat(shared/a2a): graph entry partial state sanity (#73)

[hagyutae]

Summary

LangGraph 그래프가 응답을 끝내지 못한 상태에서 (cancel / 외부 proxy timeout 등) 다음 turn 시작 시 messages tail 의 dangling 잔재를 marker 로 정리. shared/a2a 의 핸들러 layer 에 적용 — 모든 에이전트가 즉시 보호받음.

3 dangling 패턴

#39 검증 thread 의 messages 채널 디코드에서 발견:

패턴	위험	Marker
A user-user adjacency	LLM 이 첫 user 의도 합치거나 무시 — felt "꼬임"	SystemMessage("[직전 turn 응답 중단됨, 함께 종합해 답하라]")
B trailing ToolMessage	닫는 AIMessage 부재 → LLM context 형태 깨짐	AIMessage("[직전 turn 응답이 도구 결과 후 중단됨]")
C trailing AIMessage(tool_calls) without matching ToolMessage	Anthropic API 의 tool_use ↔ tool_result hard 요구사항 — 위반 시 LLM 호출 자체 실패	unanswered tool_call 별 ToolMessage("[tool call interrupted before completion]", tool_call_id=...)

C 가 가장 critical (API 차원 hard-fail), A/B 는 LLM tolerable 하지만 의미 명확화.

설계 — tail-only / append-only / handler layer

shared/src/dev_team_shared/a2a/server/graph_handlers/sanity.py 신설:

• detect_tail_markers(msgs) -> list[AnyMessage] — 순수 함수, tail 검사. dangling 패턴별 marker 반환 (또는 []).
• apply_tail_sanity(graph, config) -> int — graph state 의 latest checkpoint 에 marker append. 추가 개수 반환 (0 = 깨끗).

Tail-only: 매 turn 시작 시 호출되므로 mid-history 까지 dangling 이 누적될 수 없음. middle 검사 / 복잡한 RemoveMessage 불필요.

Append-only: add_messages reducer 의 자연 동작과 충돌 없음. marker 가 새 user 입력 앞에 위치 → LLM context 정상화.

Handler layer: graph 노드가 아니라 핸들러에서 graph 호출 직전 적용 — 모든 에이전트 (Primary / Librarian / 향후 Architect / Engineer / QA) 가 무료로 받음. graph 코드 수정 0.

통합 지점

• send_streaming.py — stream_artifact_events 호출 직전
• send_message.py — graph.ainvoke 직전

검증

단위 + 통합 (14 테스트)

shared/tests/test_a2a_graph_sanity.py:

• detect_tail_markers (8) — 3 패턴 + 정상 tail / 빈 history / 단일 user / clean AI
• apply_tail_sanity InMemorySaver 통합 (6) — no-state / clean state / 각 패턴 / idempotent

회귀 (기존 테스트)

• shared 69 통과 (sanity 14 + 기존 55)
• primary 23 통과
• librarian 20 통과

실 stack 부팅

• docker compose --profile agents up -d primary librarian — 정상 부팅
• Primary lifespan: primary tools wired: doc_store=on, issue_tracker=on, wiki=on, librarian=on, total=23
• 양쪽 /healthz 200

비-스코프

• Mid-history dangling 정리 — tail-only 정책으로 sufficient (turn 마다 sanity 가 호출돼 누적될 수 없음). 만약 본 PR land 전 누적된 mid-history 잔재가 있다면 다음 turn 시작 시 tail 부분만 정리됨 — 이전 잔재는 LLM 이 persona 가이드 기반 처리.
• LangGraph pre_model_hook (매 LLM 호출 직전 sanity) — handler layer 적용으로 충분. ReAct 루프 안 dangling 이 발견되면 추후 추가 가능.

Closes #73

🤖 Generated with Claude Code

[hagyutae]

#75 재설계 (PR 1~4 머지) 로 환경이 크게 달라져 본 PR 의 변경 base 가 stale. 최신 main 형상에서 #73 의 sanity 노드를 다시 작성 예정. 본 PR 의 의도는 #73 body (갱신됨) 에 반영.