gate4agent

Universal Rust transport library for CLI AI agents. Spawn, stream, resume — for six different CLI agents through one unified API.

Not a harness. Not a sandbox. gate4agent is the thin wiring layer between your Rust app and the CLI agent's subprocess: spawn the binary, write the prompt, read structured events, resume by session id. That's it.

Supported CLI tools

Transport classes:

• Pipe: spawn the CLI directly, read NDJSON over stdout
• PTY: spawn inside a pseudo-terminal, scrape the screen with vt100 (for agents without structured output)
• DaemonHarness: pre-probe a running daemon via raw TCP, then spawn the client binary over pipe

Quick start

use gate4agent::{TransportSession, SpawnOptions, CliTool, AgentEvent};
use std::path::PathBuf;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    let opts = SpawnOptions {
        working_dir: PathBuf::from("."),
        prompt: "Say hello in 3 words".into(),
        resume_session_id: None,
        model: None,
        append_system_prompt: None,
        extra_args: vec![],
        env_vars: vec![],
    };

    let mut session = TransportSession::spawn(
        CliTool::ClaudeCode,
        &opts.working_dir.clone(),
        &opts.prompt.clone(),
        opts,
    )?;

    let rx = session.subscribe();
    while let Ok(event) = rx.recv() {
        match event {
            AgentEvent::Text { text, .. } => print!("{text}"),
            AgentEvent::SessionEnd { .. } => break,
            _ => {}
        }
    }
    Ok(())
}

Resume an existing session

let opts = SpawnOptions {
    resume_session_id: Some("abc-123-session".into()),
    ..opts
};

Each CLI handles resume in its own way — Codex swaps exec → exec resume <id>, Claude/Cursor use --resume <id>, OpenCode uses --session <ses_XXX>. gate4agent hides the difference behind SpawnOptions::resume_session_id.

DaemonHarness (OpenClaw)

OpenClaw requires a running daemon. gate4agent probes it via raw TCP (no HTTP client) before spawning the acpx client. If the daemon is down, TransportSession::spawn returns AgentError::DaemonNotRunning or DaemonProbeTimeout.

let session = TransportSession::spawn(CliTool::OpenClaw, &cwd, &prompt, opts)?;

Features

• Single API for 6 CLIs — TransportSession::spawn(tool, cwd, prompt, options)
• SessionEnd synthesis — Codex has no terminal event; gate4agent synthesizes SessionEnd { result: "exit_code=N", is_error: N != 0 } on child exit
• Raw TCP daemon probe — no reqwest, no HTTP client, std::net only
• Transport-neutral events — AgentEvent::{Text, ToolStart, ToolResult, Thinking, TurnComplete, SessionStart, SessionEnd}
• Cross-platform — Windows (ConPTY + cmd /C argv wrapping) and Unix (POSIX PTY + bare exec)
• Rate-limit detection — pattern-based session/daily/weekly limit detection per CLI
• Zero new dependencies — gate4agent 0.2.0 added 3 CLIs, a daemon transport, and a unified session API without pulling in any new crate

Architecture

gate4agent/
├── src/
│   ├── lib.rs           — Library root, re-exports
│   ├── types.rs         — AgentEvent, CliTool, SessionConfig
│   ├── error.rs         — AgentError (DaemonNotRunning, DaemonProbeTimeout, ...)
│   ├── transport/       — ★ TransportSession, SpawnOptions, pipe_runner, daemon_runner
│   ├── cli/             — Per-tool spawn builders + parsers (claude, codex, gemini, cursor, opencode, openclaw)
│   ├── ndjson/          — NDJSON parsers per CLI
│   ├── parser/          — VTE + screen parser for PTY mode
│   ├── pty/             — PTY session (PtyWrapper, PtySession)
│   ├── pipe/            — Low-level PipeProcess (used internally by pipe_runner)
│   ├── daemon/          — TCP liveness probe (std::net only)
│   └── detection/       — Rate limit detection

Prerequisites

At least one CLI agent must be installed on the host. gate4agent does not install them.

Versioning

• 0.1.x — original 3-CLI library (Claude, Codex, Gemini)
• 0.2.0 — breaking: 6 CLIs, TransportSession, AgentEvent renamed, PipeSession removed

See ROADMAP.md for what's next and DEBUGGING.md for known issues and mitigations.

Migration from 0.1.x to 0.2.0

1. Events: AgentEvent::Pipe* → neutral names. Rename all match arms:

   • PipeText → Text
   • PipeToolStart → ToolStart
   • PipeToolResult → ToolResult
   • PipeThinking → Thinking
   • PipeTurnComplete → TurnComplete
   • PipeSessionStart → SessionStart
   • PipeSessionEnd → SessionEnd

2. Entry point: PipeSession::spawn(config, prompt, options) → TransportSession::spawn(tool, cwd, prompt, SpawnOptions). PipeSession no longer exists.

3. SpawnOptions: replaces PipeProcessOptions / ClaudeOptions. Fields: working_dir, prompt, resume_session_id, model, append_system_prompt, extra_args, env_vars.

4. CliTool is now non-exhaustive in effect (3 new variants: Cursor, OpenCode, OpenClaw). Add arms or a _ => fallback.

5. AgentError: new variants DaemonNotRunning { host, port, detail } and DaemonProbeTimeout { host, port, timeout_ms } — handle them when calling OpenClaw.

Support the Project

If you find this tool useful, consider supporting development:

License

MIT