Skip to main content

Module oneshot

defect_cli

Module oneshot 

Source
Expand description

Single-turn unattended mode —— defect --message <prompt>.

Purpose: in CI / scripts, “run one prompt, produce a result, exit by success/failure”. On equal footing with the interactive REPL and the ACP server; the three only share the AgentCore kernel:

  • Does not reuse the REPL’s crate::repl rendering (that stack carries ANSI / line editing, bound to the repl feature’s crossterm/owo-colors). This module ships its own minimal, ANSI-free event projection, so under --no-default-features --features oneshot it builds a slim CI binary with no TUI dependencies.
  • Connects in-process directly to AgentCore (like the REPL), bypassing the wire —— CI runs its own agent and does not need ACP’s cross-process generality.

§Output contract: stdout = agent content, stderr = framework logs

All agent content (assistant body / thinking / tool calls) goes to stdout as a single stream in event order; framework-level diagnostics (denial warnings, turn errors, unreached goals) go through tracing —— and tracing is uniformly written to stderr by defect_obs::init_tracing. So 2>/dev/null cleanly filters out framework noise while preserving the agent’s complete work record; the two streams no longer share a cursor or run together.

§Exit codes (CI’s lifeline for judging success/failure)

Priority high to low: TurnError(1) > Refusal(3) > MaxTokens(2) > MaxTurnRequests(7) > Cancelled(5) > unattended denial (denied, 4) > goal unreached (6) > EndTurn(0). MaxTokens (a single response truncated by the output limit) and MaxTurnRequests (the per-turn call budget exhausted) are distinct conditions and carry distinct codes. See ExitOutcome.

§Non-interactive permissions

The caller (bin/cli.rs) is responsible for wrapping the session’s policy in defect_agent::policy::NonInteractivePolicy, so that Ask degrades to Deny and it does not hang waiting for input in a TTY-less environment. This module listens for PolicyDecision::Deny in the event stream: once one occurs, it logs a warning via tracing (→ stderr) and sets the denied flag, so even if the turn ends normally with EndTurn it exits with a non-zero code —— fail loud, letting CI know “an operation was denied, this result is not trustworthy”.

Functions§

run
Runs a single-turn prompt and returns the process exit code.