bevy_agent_feedback_plugin/config.rs
1use bevy::prelude::Resource;
2use std::{net::SocketAddr, path::PathBuf, time::Duration};
3
4/// Runtime configuration for [`crate::AgentFeedbackPlugin`].
5///
6/// Defaults bind to localhost on port `15712`, write `agent-feedback.json`,
7/// keep captures in `agent-feedback-captures`, and refresh a heartbeat for protocol 0.5
8/// stale-session checks.
9#[derive(Clone, Debug, Resource)]
10pub struct AgentFeedbackConfig {
11 /// TCP address used by the local JSON-lines control socket.
12 ///
13 /// Use port `0` to let the operating system choose a free port. The chosen
14 /// address is written to [`protocol_file`](Self::protocol_file).
15 pub bind_addr: SocketAddr,
16
17 /// JSON file written at startup so Pi/Codex agents can discover the socket.
18 pub protocol_file: PathBuf,
19
20 /// Directory where `capture` commands write PNG screenshots.
21 pub capture_dir: PathBuf,
22
23 /// Maximum queued agent commands drained per frame.
24 pub max_pending_commands: usize,
25
26 /// Maximum accepted frame count for a single `wait` command.
27 pub max_wait_frames: u16,
28
29 /// Maximum accepted step count for compound actions such as `drag`.
30 pub max_action_steps: u16,
31
32 /// Freezes Bevy virtual time between explicit advancement commands.
33 ///
34 /// The default is `false`, which preserves Bevy's normal time behavior.
35 pub deterministic_time: bool,
36
37 /// Maximum number of deterministic deltas in one `advance_time` command.
38 ///
39 /// This cap is always treated as at least one by protocol discovery and
40 /// request validation. The default is `600`.
41 pub max_time_advance_steps: u16,
42
43 /// Maximum gameplay duration accepted by one `advance_time` command.
44 ///
45 /// The default is 10 seconds. Wire durations must also be finite, positive,
46 /// and nonzero after conversion to [`Duration`].
47 pub max_time_advance: Duration,
48
49 /// How often the plugin refreshes the session heartbeat file.
50 pub heartbeat_interval: Duration,
51
52 /// How old the heartbeat may be before clients reject the session as stale.
53 pub session_stale_after: Duration,
54
55 /// Maximum number of retained PNG captures.
56 ///
57 /// Older capture files created by this plugin are removed after this limit.
58 pub max_captures: usize,
59
60 /// Maximum time a socket client waits for the game to answer a command.
61 pub command_timeout: Duration,
62
63 /// Optional app exit after no accepted agent commands for this duration.
64 /// Values below 5 seconds are clamped up; `None` disables idle shutdown.
65 pub idle_shutdown_after: Option<Duration>,
66}
67
68impl Default for AgentFeedbackConfig {
69 fn default() -> Self {
70 Self {
71 bind_addr: SocketAddr::from(([127, 0, 0, 1], 15712)),
72 protocol_file: PathBuf::from("agent-feedback.json"),
73 capture_dir: PathBuf::from("agent-feedback-captures"),
74 max_pending_commands: 32,
75 max_wait_frames: 300,
76 max_action_steps: 120,
77 deterministic_time: false,
78 max_time_advance_steps: 600,
79 max_time_advance: Duration::from_secs(10),
80 heartbeat_interval: Duration::from_millis(250),
81 session_stale_after: Duration::from_secs(3),
82 max_captures: 32,
83 command_timeout: Duration::from_secs(10),
84 idle_shutdown_after: None,
85 }
86 }
87}