claude-integrationlisted

Low-level AI CLI spawn mechanics used by ralphctl's provider adapters — headless / interactive spawn, the file-based contract (`signals.json` + `sessionId` files), idle-stdout watchdog, exponential rate-limit backoff, and `--resume` for in-flight recovery. Use when modifying `src/integration/ai/providers/{claude,copilot,codex}/` or `src/integration/ai/providers/_engine/`, debugging stdin hangs / slow Claude startups, or wiring a new code path that spawns an AI CLI directly.
lukas-grigis/ralphctl · ★ 10 · AI & Automation · score 79

Install: claude install-skill lukas-grigis/ralphctl

# AI provider integration (Claude / Copilot / Codex) Covers what is **not** in `CLAUDE.md` or `.claude/docs/ARCHITECTURE.md`. For harness signals, exit codes, sequential task execution, and check-script gating — see `CLAUDE.md`. **Source of truth (v0.7.0):** - Provider adapters: `src/integration/ai/providers/{claude,copilot,codex}/` — one folder per tool, sibling- isolated. Each owns `headless.ts` and `interactive.ts` entries (Claude also has `parse-stream.ts` for stream-format handling). - Shared engine: `src/integration/ai/providers/_engine/` — `spawn.ts` (the `ProviderSpawn` port + default `node:child_process.spawn` impl), `run-headless-spawn.ts` (the headless wrapper that wires watchdog + signals file + sessionId file + rate-limit backoff), `rate-limit-backoff.ts` (exponential retry policy), `idle-watchdog.ts` (kills wedged children), `headless-ai-provider.ts` (the cross-tool port). - Signal contract: `src/integration/ai/contract/_engine/{validate-signals-file,render-sidecars,render-contract-section}.ts` with per-kind Zod schemas under `src/integration/ai/contract/_engine/signals/<kind>/schema.ts`. Each AI-spawning leaf composes `<leaf>.contract.ts` from these primitives; the AI writes `signals.json` via its Write tool, the harness Zod-validates post-spawn. - Composition: `src/application/bootstrap/provider-factory.ts` (`createAiProvider`) picks the concrete adapter from `settings.ai.provider`. ## Spawn modes There are two ports under `_engine/`: