feat(api-tox): v2.2.0 Phase 1.2 — cycle detection in tool chains

[dreamrec]

Summary

Second feature of the v2.2.0 reliability phase (1.1 was auto-rollback, shipped in #34 + Codex-followup #36; consolidation pre-work in #35). 1.2 pairs with 1.1 to cover the second high-impact reliability gap:

Failure mode	Caught by
"agent broke things"	1.1 auto-rollback (undo the batch)
"agent is stuck looping"	1.2 cycle detection (break the turn)

Per-turn ledger tracks (tool_name, args_hash) -> count. Before each dispatch, ledger.record(name, args) increments; when the count reaches the threshold (default 3), CycleDetected raises BEFORE invoking the tool. run_turn's BaseException catch fires on_error → EV_ERROR + EV_STATE: idle → red banner in the chat UI carrying the stuck tool's name + an args preview.

No version bump — Phase 1 ships as v2.2.0 only when the whole phase is in.

Design highlights

Decision	Rationale
Threshold = 3 (configurable)	2 dispatches allowed before the 3rd attempt blocks. One re-attempt covers transient blips (DeepSeek 5xx retry, momentary cook conflict) without papering over real loops.
Args hash via sorted-keys JSON	{"a":1,"b":2} and {"b":2,"a":1} collapse to the same key; nested dicts hash recursively; lists are order-sensitive (connect source/dest order matters).
Check BEFORE on_tool_call	A blocked call shouldn't leak EV_TOOL_CALL that the chat UI then has to retract a tick later. Cleaner UI state machine.
Per-turn lifetime	Built once at _loop start, discarded at turn end. Identical calls between turns aren't a cycle — that's the user re-asking.
Late-import CycleDetected in _loop	cycle_detector imports AgentError from agent. Top-level import in agent → circular. Late import inside _loop resolves it; Python's module cache makes cost = 1 dict lookup per turn after first call.
Subclass of AgentError	Same family as TurnBudgetExceeded. The existing run_turn catch-all (except BaseException) routes it through on_error automatically; no new event wiring needed.

Files

New (2):

• td_component/tdpilot_api_cycle_detector.py — ~210 lines, pure-Python. Exports CycleDetected exception, CycleLedger class, args_hash, env-var gate, factory builder.
• tests/test_tdpilot_api_cycle_detector.py — ~330 lines, 49 tests across 8 classes.

Modified (4):

• td_component/tdpilot_api_agent.py — new cycle_ledger_factory ctor kwarg; _loop builds one ledger per turn; inner per-batch loop checks ledger.record() BEFORE on_tool_call/dispatch; raises at threshold.
• td_component/tdpilot_api_runtime.py — new _build_cycle_ledger_factory method; honours TDPILOT_DISABLE_CYCLE_DETECTION=1; passes factory to Agent().
• td_component/build_tdpilot_api_tox.py — adds tdpilot_api_cycle_detector to _SOURCE_FILES. Post-refactor: consolidate paired .tox source-file lists #35 the freshness gate auto-imports this list, so no paired-list maintenance.
• CHANGELOG.md — new "Feature 1.2" entry under "Unreleased".

Binary update (2): td_component/tdpilot_API.tox (221,182 → 222,406 → now 222,406 + ~1.5KB cycle-detector textDAT) + .tox-api-source-hash.json.

Tests (49 new)

Class	Tests	What it pins
TestArgsHash	8	Order independence; None/{} normalisation; nested-dict ordering; list-order sensitivity; compact-separators invariant; defensive paths for non-JSON values.
TestCycleLedger	10	Threshold validation (rejects <2); increment correctness; per-key isolation; peek is idempotent; reset clears; __len__ semantics.
TestCycleDetectedException	3	Carries tool_name/count/args_summary; message formatting; isinstance(AgentError) so run_turn catches it.
TestEnvVarGate	3	Truthy / falsy / unset env-var classification.
TestBuildCycleLedgerFactory	3	Env-disable returns None; env-enabled returns callable producing fresh per-turn instances; custom threshold propagates.
TestUsagePattern	4	Canonical check-then-dispatch flow; 2 identical calls don't trigger; alternating calls eventually trigger (proves ledger spans the whole turn).
TestFormatArgsSummary	3	Empty/short/long args rendering.
TestAgentLoopCycleIntegration	3	End-to-end with mocked urlopen: 3 identical calls → raises on 3rd, dispatches only 2, fires on_error; disabled factory → 4 dispatches hit turn budget; distinct args → completes cleanly without triggering.

Test plan

• uv run pytest tests/ --ignore=tests/agent_evals -q — 1821 passed (1772 prior + 49 new).
• uv run --extra dev ruff format --check src tests scripts td_component — clean.
• uv run --extra dev ruff check src tests scripts td_component — clean.
• uv run python scripts/check_versions.py — in sync at v2.1.5.
• uv run python scripts/check_tox_freshness.py — dpsk4 .tox fresh (not touched).
• uv run python scripts/check_tox_api_freshness.py — API .tox fresh post-rebuild (hash 0f6a0f482630993d...).
• bash scripts/check_no_personal_paths.sh — clean.
• CI all-green on push.

Manual verification (post-merge, in TD)

1. Open tdpilot_API.tox in /project1.
2. Ask the agent something where it will likely loop (e.g. an ambiguous "what's wrong with my project" while the project has a misleading error state).
3. Expected: after 2 identical lookups, the 3rd attempt is blocked; chat shows a red banner reading "Cycle detected: td_get_errors ×3 with identical args (…)" and the turn ends with EV_STATE: idle.
4. Disable check: set TDPILOT_DISABLE_CYCLE_DETECTION=1, reload the COMP, repeat — agent should now loop until the turn budget exhausts.

Why mock-only and not live-TD verification

User's TD has TD_MCP_REQUIRE_AUTH=1 so my MCP client hits 401, blocking live verification through the dpsk4 MCP server. The 3 integration tests in TestAgentLoopCycleIntegration cover the agent loop's late-import + raise + on_error path with a real Agent instance + mocked urlopen — high-fidelity coverage. If anything slips, the standing Codex-followup pattern catches it post-merge.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 88532a9235

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Count only consecutive repeats before declaring a cycle

This ledger increments per (tool_name, args_hash) across the entire turn and never resets when a different call happens, so non-looping patterns like td_get_errors between unrelated mutation steps still trip at the 3rd check. In normal validate/fix/validate flows, the turn will be aborted even though the agent is progressing, which creates false-positive CycleDetected failures and prematurely ends useful runs.

Useful? React with 👍 / 👎.

[chatgpt-codex-connector]

Preserve protocol invariants when blocking a tool call

Raising CycleDetected here exits before a tool_result is appended for the current assistant tool_use, leaving conversation history with a dangling tool_use block. After this error, the next turn reuses that invalid transcript and can be rejected by the Anthropic/DeepSeek tool-use protocol (missing matching tool_result), so one cycle-detection event can poison subsequent requests until history is repaired.

Useful? React with 👍 / 👎.