Instruction file imported from trevorrussin/microstation-vba-project (.cursor/rules/wztc-agent-monitoring.mdc). Copyright stays with the author.

Driving/monitoring the WZTC chat agent from outside the panel

chat_driver.py normally takes input from WZTCChatPanel.frm inside MicroStation, but it is watching a plain file — you can drive and observe a full turn without touching the panel at all. Useful for testing a fix, running a sheet build unattended, or verifying a change actually stuck.

When monitoring: fix errors and off-track behavior (do not only report)

Standing engineer preference (2026-08-04): while watching a live agent turn, intervene and fix — do not wait for the engineer to ask, and do not stop at a status ping when you can clear the blockage yourself.

Fix immediately when you see:

• ERROR in chat-log.tsv (API/history/tool failures) — diagnose root cause, patch code or repair state (chat-history.json, SharedState, restart driver), then re-queue the engineer message if the turn died
• repeated TOOL_RESULT status=ERROR the agent is looping on or misinterpreting
• agent off the sheet-first / call-order path (e.g. freestyle corridor instead of assemble_corridor, heuristic place_order_table_* when sheet JSON exists, re-asking locked designer inputs, Downstream sta0 on Upstream's line, declaring complete without visual QA)
• MAX_TOOL_ITERATIONS / stale mid-turn with no progress — nudge via chat-input.tsv with a concrete continue instruction, or fix the underlying tool/prompt bug if that is why it burned iterations
• gate refusals (cross_validate_stations, corridor-topology, ALIGNMENT_NOT_READY) where the right recovery is known (assemble_corridor, adopt_alignment, clear+rebuild)

Still stay quiet on routine healthy progress. Tell the engineer briefly what you fixed and why; ask only when a real designer choice is required (speed/area_type/work-area edge picks) that you must not invent.

Sending a message (same as clicking Send in the panel)

Append one line to Bridge/chat-input.tsv, format <timestamp>\t<message> (matches WZTCChatPanel.btnSend_Click; see chat_driver.py's InputWatcher class). chat_driver.py polls this file every ~0.5s, so no restart needed:

2026-08-04 12:00:00.000000	Build sheet 619-311 using the standard wztc flow.

This is also how you answer an ASK_USER/ASK_USER_CHOICE prompt mid-turn — append the reply the same way; the same InputWatcher cursor serves both the top-level loop and any nested ask_user wait.

Before sending: confirm the agent is actually idle — tail Bridge/chat-log.tsv and check the last line is FINAL (or the session just started). Sending into a live turn queues behind it rather than interrupting, so it's not unsafe, but you won't get a response to that message until whatever's running finishes.

Watching progress

Bridge/chat-log.tsv is the full transcript: TOOL_CALL, TOOL_RESULT, THINKING, ASK_USER, ASK_USER_CHOICE, SCREENSHOT, and FINAL lines, each timestamped. The three lines that mean "the turn stopped and needs you" are:

• FINAL — turn complete (or hit MAX_TOOL_ITERATIONS without finishing — check the text, it says so explicitly rather than returning blank)
• ASK_USER / ASK_USER_CHOICE — blocked on a reply (engineer decision; do not invent designer inputs)
• a TOOL_RESULT with status=ERROR — fix or unblock per the monitoring rule above; only escalate if you cannot resolve it

Poll/tail that file (tail -f or equivalent) rather than guessing how long a turn will take — turns vary from seconds to several minutes depending on tool-call count.

Cost visibility

Bridge/chat-usage.tsv logs one line per API call: model, input, output, cacheWrite, cacheRead, costUsd, runningTotalUsd. Useful for confirming a caching fix actually holds (cacheRead should stay roughly stable across a turn, not repeatedly reset to a fresh full-price cacheWrite) or for a before/after cost comparison on a change.

After editing chat_driver.py/wztc_ops.py/etc.

Restart it yourself per the File Sync Protocol rule (hot-reload-sync.mdc) — python mcp-server/restart_chat_driver.py — then re-send via chat-input.tsv as above to verify the fix live rather than just reading the diff.