Headless agent invocation: run a prompt non-interactively and capture the reply

[getappz]

Summary

agentflare can launch agents interactively (agentflare run / agentflare agents launch → run_launch_env, src/agent_launch.rs), but that path uses Stdio::inherit() — there is no way to run an agent headlessly with a prompt and capture its reply. Add a headless invocation to the core.

General capability (cron, CI, scripting, orchestrators all want it) → belongs in agentflare, the core. First consumers: outbound-triggered flows and the inbound channels work (getappz/flared#1), which must turn a message into an agent reply.

What exists

• run_launch_env(registry, agent, model, mode, args, env, via_mise) in src/agent_launch.rs — finds the agent binary, maps --model/--mode, launches with inherited stdio, std::process::exits on non-zero. Interactive only.

Proposed

A sibling entrypoint that runs the agent in its non-interactive / print mode, captures stdout as the reply (Stdio::piped() + .output()), returns Result<String, …> (no process exit), enforces a timeout (kill child + tree on expiry), and truncates to a max-output cap. Reuse the existing registry / binary discovery / model+mode mapping / mise env — don't duplicate.

Per-agent headless invocation (add to the registry, next to the model/mode maps)

The print-mode form is per-CLI and small:

Agent	Headless form
Codex	codex exec [args] <prompt>
Gemini	gemini -p <prompt>
OpenCode	opencode run <prompt>
Claude Code	claude -p <prompt> (optionally --output-format json for structured capture)

The runner is uniform: Command → tokio timeout → capture stdout → truncate → {success, output}. ~10 lines of shared logic + a per-agent flag map. Build it in-house — it's tiny; don't pull a dependency for this.

Structured alternative (note for later, not v1)

The Agent Client Protocol (ACP) — https://agentclientprotocol.com — is the emerging cross-editor standard for driving an agent programmatically (streaming output, tool calls, permission prompts) over JSON-RPC. Several agent CLIs speak it. Worth considering as a structured successor to stdout-scraping once the simple path is proven; there's a Rust crate for the protocol. Out of scope for v1.

Out of scope

• Streaming/token-by-token output (batch capture is enough first).
• Any channel/transport concern (that's flared).

Exposure

• Library fn (in-process consumers) and, if cheap, a CLI form (agentflare run --print/--headless).

[getappz]

Shipped in #155 (merged). agentflare run <agent> --print "<prompt>" [--timeout N] — headless invocation for claude -p, codex exec, gemini -p, opencode run, capturing stdout and returning a non-zero exit on failure.

Two issues found in post-merge review, both fixed before merge:

• The timeout only killed the direct child process. If the underlying agent CLI spawned a subprocess that inherited the piped stdout, that descendant could keep the pipe open and hang the reader thread forever — defeating the timeout entirely. Fixed by putting the child in its own process group and killing the whole group/tree on timeout (kill -s KILL -- -<pid> on Unix, taskkill /T /F on Windows).
  • That fix itself briefly broke Linux CI on the first push: kill -KILL -<pid> (signal and negative pid as two separate --prefixed args) gets misparsed by the kill binary on Ubuntu runners once -KILL is consumed as the signal option, so the group was never actually signaled. Switched to the portable -s SIGNAME -- form, which fixed it — verified green across ubuntu/macos/windows CI before merging.
• --print silently ignored --model/--mode/--env/trailing args instead of honoring or rejecting them — now it errors clearly naming which flags aren't supported together with --print, rather than quietly running with different behavior than interactive run.

Closing out.