chat-drive

Push text into the snappy-chat composer from any agent, anywhere. The text flows through the same OpenUI submit path the human types into: processMessage → /dispatch/chat → AG-UI stream → generative-UI cards rendered in the live React tree. Same store, same surface, same eyes.

This is the missing primitive for closed-loop snappy-chat dogfood: an agent can now type intent and watch real cards stream in, then audit by screenshot.

What it's for

• Dogfood loops. A subagent pushes a stress-test intent, screenshots the

result, grades the rendered card. The actor (push) and the auditor (read the screenshot) are necessarily distinct - the contract holds for free.

• Automated UX QA. Verify the welcome surface unmounts on first message,

user-pill alignment, dispatch-card variants, etc., end-to-end through the rendered DOM.

• Recursive subagent dispatch. A long-running agent can re-enter the chat

surface mid-task by pushing a follow-up intent. The chat is the agent's outbox.

When NOT to use it

• Anything that doesn't need the rendered UI. If you don't care about the

React tree, call the head-screen server's /dispatch/chat directly, or use the dispatch skill. Running through the chat surface adds streaming latency for no reason.

• As a synthesis transport. The bridge is a queue, not an RPC channel -

there's no callback when streaming finishes. Use /dispatch/chat directly when you need the response programmatically.

Steps

1. Verify the head-screen server is up. The bridge endpoints live on it.

   bash ~/projects/snappy-os/state/bin/head-screen/launch.sh   # idempotent

1. Verify snappy-chat is running and on screen so the polled push lands somewhere.

   pgrep -af "/Applications/SnappyChat.app/Contents/MacOS/SnappyChat"

If it's not, build + install:

   cd ~/projects/snappy-chat && bash scripts/build-app.sh --install

1. Push the intent.

   npx tsx -e "
   import { dispatchInChatUI } from './state/lib/chat-drive.ts';
   await dispatchInChatUI('what did the agents do today', { waitForFirstFrame: 12000 });
   "

The default waitForFirstFrame is 8000ms. Pass a larger value when the target backend is slow (Claude Code: 12-15s; openrouter/gemini: 6-10s).

1. Audit by screenshot. The bridge has no completion callback - actor ≠ auditor.

   npx tsx -e "
   import { captureScreen } from './state/lib/desktop.ts';
   const path = await captureScreen('/tmp/chat-drive-verify.png');
   console.log(path);
   "

Then Read the PNG. Welcome surface unmounted + user pill on the right + assistant card streaming = bridge working.

Library API

state/lib/chat-drive.ts exports three functions. Importable from any TS agent code; also runnable as a CLI smoke.

export async function dispatchInChatUI(
  text: string,
  opts?: { waitForFirstFrame?: number }   // default 8000ms
): Promise<void>;

export async function resetChatUI(
  opts?: { waitMs?: number }               // default 1500ms
): Promise<void>;

export async function chatDriveAvailable(): Promise<boolean>;

resetChatUI is for multi-scenario dogfood loops: clears the thread and brings the welcome surface back so the next dispatchInChatUI lands in a clean state. Same FIFO as text pushes (single ordering), distinct /chat-inject-control endpoint so wire shape is unambiguous.

CLI:

npx tsx state/lib/chat-drive.ts "say hello in three words"

HEAD_SCREEN_URL env var overrides the default http://127.0.0.1:3147.

Architecture (one paragraph)

dispatchInChatUI POSTs to the head-screen server's POST /chat-inject-push endpoint, which appends the text to a 50-slot in-memory FIFO with FIFO eviction on overflow. The snappy-chat React app mounts a polling effect that hits GET /chat-inject-pop every 500ms; on hit, it locates whichever OpenUI composer is currently visible (welcome OR thread variant) and writes through React's native value setter to trigger the textarea's onChange, then clicks the submit button. From there, the real processMessage path takes over - same code as a human typing.

For QA probes and dogfood agents, include "newThread": true in the push body. The app resets to a fresh chat before dispatching that item so probe traffic does not land in Robert's active thread. Omit it only when the intent is deliberately a follow-up in the current conversation.

Eval

Actor: dispatchInChatUI(text) - pushes onto the queue. Auditor: the audit harness re-reads the lib's exported function shape (present, async, two parameters); the user-facing audit is "is the rendered card correct" via screenshot, deliberately outside the lib.

Eval kind: shape. Mechanical: import the lib, assert dispatchInChatUI and chatDriveAvailable exist as functions, type-check passes. Logged as the skill's eval row in state/log/evals.ndjson.

Pitfalls

• The head-screen server must be alive. The bridge IS the head-screen

server. If /healthz doesn't answer, push will throw. chatDriveAvailable() is the cheap precheck.

• No completion callback. waitForFirstFrame is the only synchronization

knob. Tune it per backend, then screenshot.

• Restart drops queued pushes. The queue is in-memory by design - restart

= empty. If a dogfood loop relies on durability across restarts, you're using the wrong primitive.

• The bridge is loopback only. No external network exposure. The CORS

headers are wide so file:// origins (WKWebView) work; the listener is bound to 127.0.0.1.

Files

• state/lib/chat-drive.ts - the API (importable + CLI).
• state/bin/head-screen/server.ts - owns the queue endpoints

(POST /chat-inject-push, POST /chat-inject-control, GET /chat-inject-pop).

• ~/projects/snappy-chat/web/src/App.tsx - the React polling effect and

composer-injection helper that drains the queue.

chat-drive - loader

Per-turn rules for chat-drive. Push text via queue to the live React chat. Full reference: state/skills/chat-drive/SKILL.md. Lib: state/lib/chat-drive.ts. Server: state/bin/head-screen/server.ts. Consumer: ~/projects/snappy-chat/web/src/App.tsx (poll 1000ms).

Critical Rules

1. Actor (push) ≠ auditor (screenshot). dispatchInChatUI() queues text. Lib never reports "did card render" - audit via captureScreen + Read. No callback when streaming finishes.
2. waitForFirstFrame is ONLY sync knob. Default 8000ms. Tune per backend: Claude Code 12-15s, openrouter/gemini 6-10s, plus 1000ms React poll lag. After push, screenshot to audit.
3. Head-screen server MUST be alive. Pre-flight: chatDriveAvailable() or bash state/bin/head-screen/launch.sh (idempotent). Verify: /healthz answers.
4. snappy-chat must be running and visible. Push → in-memory 30-slot FIFO. No React polling = silent eviction. Confirm: pgrep -af "/Applications/SnappyChat.app".
5. Queue is in-memory only, 30s TTL per item, server-restart-safe = wiped. Never durability-dependent. Drain before testing: curl -XPOST /chat-inject-flush returns flushed count.
6. React polls every 1000ms (App.tsx:337). Each push incurs up to 1000ms before composer sees it. Factor into waitForFirstFrame budget.
7. tsx never hot-reloads server.ts. After any server.ts edit, restart the server process. Verify running code: pgrep -af server.ts + git log match.
8. Don't push faster than dispatcher streams. Wait for RUN_FINISHED before next text push. Control actions (open-cowork, stop, theme:*, view-*) must stay live while a stream is running; the React poller calls /chat-inject-pop?busy=1 during active streams so controls pop but text stays queued server-side until RUN_FINISHED. Use resetChatUI() (NOT peekaboo) between scenarios.
9. resetChatUI() does NOT flush. It sends control items for nav reset (welcome). Pre-flush with /chat-inject-flush if stale pushes queued.
10. Activate app before screenshotting. SnappyChat on secondary Space = wallpaper screenshot. Run osascript -e 'tell application "Snappy Chat" to activate' first (1-2s wait).
11. React pre-fetches queue items. App polls /chat-inject-pop before dispatch. Use endpoint /chat-inject-flush, never manual curl drain (competes with React).
12. Queue inspection is non-consuming. GET /chat-inject?agentId=ui returns {items, depth, controlDepth, textDepth} without shifting the queue. Never use GET /chat-inject-pop for inspection; pop consumes and can steal React's next item.
13. Concurrent claude -p / claude --continue compete for queue. Symptom: your pushes hit queued:N, then pop returns empty, no matching intent_chars in dispatch-chat.ndjson. Mitigation: serialize QA or use direct /dispatch/chat POST (isolated SSE stream, independent thread).
14. Server crashes wipe in-memory queue. Failure mode (2026-04-30+): FATAL evalLeaderboardRegex undefined from server.ts. Verify uptime: ps -p $(pgrep -f server.ts | head -1) -o etime. If elapsed time reset between push and audit, queue is gone. Check log: tail state/log/head-screen.log | grep FATAL.
15. Force fresh crypto.randomUUID() for each request messageId. Reusing any id (including OpenUI's optimistic user-message id) causes the assistant message to collide in the store reducer and produces a duplicate-render bug. This is in App.tsx:processMessage - do not remove the crypto.randomUUID() call.
16. Audit with window-targeted screenshot. After dispatch, capture: peekaboo screenshot --app "Snappy Chat" --window-index 1 --output /tmp/after-dispatch.png. App name has a space. Window index 1 is the real chat window (index 0 is the helper).

Commands

| ui dashboard | state/skills/chat-drive/resources/ui.openui |

Self-Test

An agent reading this should correctly:

1. [ ] Pre-flight chatDriveAvailable() before push?
2. [ ] Tune waitForFirstFrame for backend + 1000ms React poll lag?
3. [ ] Audit by screenshot Read, NOT lib return values?
4. [ ] Keep both snappy-chat and head-screen alive?
5. [ ] Use resetChatUI() (not peekaboo) between scenarios?
6. [ ] Restart server after any server.ts edit (tsx no hot-reload)?
7. [ ] Serialize pushes; wait for RUN_FINISHED before next?
8. [ ] Drain with /chat-inject-flush before QA tests?
9. [ ] Know React pre-fetches (no callback on dispatch complete)?
10. [ ] Activate app via osascript before screenshot on secondary Space?
11. [ ] Know resetChatUI() does NOT flush (pre-flush if stale items queued)?
12. [ ] Check pgrep claude.*-p for competing queue consumers?

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case, you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table row, or code example.
• Only LOGGED is allowed when: the fix needs >10 lines or spans multiple files.
• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] chat-drive: <what was missing or fixed> [FIXED|LOGGED] action_kind=<kind>" >> state/log/loader-feedback.log

Do not skip this. Every agent run must leave the system better than it found it.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/chat-drive/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.