hatchery_node/
lib.rs

1//! Native Gate4Agent node server and runtime.
2
3mod bundle_catalog;
4
5mod context_pack;
6
7mod harness_mcp_proxy;
8
9mod bundle_provider;
10
11mod git_worktree;
12pub mod plugins;
13pub mod provider_inventory;
14pub mod session_signals;
15
16mod host_directory_browser;
17
18mod environment_profiles;
19
20mod session_environment;
21
22mod worktree_service;
23
24pub(crate) use gate4agent_node_core::session_registry;
25
26mod standalone_workspace;
27
28#[cfg(windows)]
29mod workspace_file_windows;
30
31#[cfg(unix)]
32mod workspace_file_unix;
33
34#[cfg(feature = "dig2-station-probe")]
35mod dig2_station_lease;
36#[cfg(feature = "dig2-station-probe")]
37mod dig2_station_probe;
38pub mod kit;
39pub mod local_infra;
40pub mod node_control;
41#[cfg(feature = "wireguard")]
42pub(crate) use gate4agent_node_core::kit_wireguard;
43mod network_allowlist_catalog;
44pub(crate) use gate4agent_node_core::platform;
45pub mod enroll_client;
46pub mod uplink_journal;
47pub mod restream_session;
48pub mod uplink_calls;
49pub mod machine_env;
50pub use machine_env::collect as collect_machine_environment;
51pub mod restream_g4a_bridge;
52#[cfg(feature = "d2b")]
53pub mod browser_capture;
54pub mod grok_leader;
55pub mod m4a_accounts;
56pub mod m4a_adopt;
57pub mod m4a_wake;
58pub mod windows_process;
59pub mod m4a_attach;
60#[cfg(unix)]
61pub mod keystore_proxy;
62/// 0.2.15 name of [`keystore_proxy`]. Unix only, same as the proxy itself.
63#[cfg(unix)]
64pub mod m4a_signer_proxy {
65    pub use super::keystore_proxy::*;
66}
67pub mod door;
68#[cfg(feature = "local-server")]
69pub mod local_server;
70pub mod wake_pipeline;
71#[cfg(unix)]
72pub mod isolation;
73pub use kit::{force_link, linked_core_names};
74#[cfg(feature = "m4a")]
75pub use kit::start_mailbox;
76#[cfg(feature = "m4a")]
77pub use kit::MailboxHandle;
78#[cfg(feature = "wireguard")]
79pub use kit_wireguard::{
80    bring_up_node_wireguard, node_wg_from_env, NodeWgPeerConfig, NodeWgPeerError,
81    LINK_TAG as WIREGUARD_LINK_TAG, WG_ADDRESS_ENV, WG_INTERFACE_ENV, WG_KEEPALIVE_ENV,
82    WG_LISTEN_PORT_ENV, WG_PEER_ADDRESS_ENV, WG_PEER_ENDPOINT_ENV, WG_PEER_KEY_ENV,
83    WG_PRIVATE_KEY_ENV,
84};
85mod provider_runtime;
86mod server;
87pub(crate) use gate4agent_node_core::spawn_spec;
88
89#[cfg(feature = "fixture")]
90pub use bundle_catalog::protect_bundle_source_tree_fixture;
91pub use bundle_catalog::{
92    BundleCatalog, BundleCatalogError, NodeBundle, NodeBundleError, NodeBundleFile,
93    MAX_BUNDLE_CATALOG_ENTRIES, MAX_BUNDLE_FILES, MAX_BUNDLE_FILE_BYTES, MAX_BUNDLE_PATH_BYTES,
94    MAX_BUNDLE_TOTAL_BYTES,
95};
96pub use environment_profiles::{
97    NodeEnvironmentProfile, NodeEnvironmentProfileError, MAX_NODE_ENVIRONMENT_PROFILES,
98};
99pub use gate4agent_node_protocol::WorktreeServiceMode;
100pub use gate4agent_runtime_native::{
101    orca_home_roots, HistorySourceLayout, NativeHistoryConfig, NativeHistoryRoot,
102};
103pub use network_allowlist_catalog::{
104    claude_allowed_domains_from_permits, claude_bash_sandbox_network_os_supported,
105    claude_settings_network_overlay_args, claude_station_network_settings_json,
106    codex_network_access_config_overlay, load_network_allowlist_catalog_file,
107    parse_network_allowlist_catalog_text, permit_peer_to_allowed_domain,
108    provider_native_mapping_supported, resolve_network_allowlist_catalog,
109    resolve_provider_native_launch_overlay, NetworkAllowlistCatalog, NetworkAllowlistCatalogError,
110    NetworkAllowlistEntry, NetworkPermitProtocol, NetworkPermitSketch, ProviderNativeNetworkSketch,
111    CLAUDE_STATION_NETWORK_SETTINGS_FILE, MAX_NETWORK_ALLOWLIST_CATALOG_ENTRIES,
112    MAX_NETWORK_PERMITS_PER_ENTRY, NETWORK_ALLOWLIST_CATALOG_ENV,
113    NETWORK_ALLOWLIST_CATALOG_SCHEMA_VERSION,
114};
115#[cfg(feature = "fixture")]
116pub use server::SpawnManagedWorktreeV2FailureProbe;
117pub use server::node_wake::{NodeLetter, NodeWake};
118pub use server::{
119    default_node_endpoint, default_state_path, NodeServer, NodeServerConfig, NodeServerError,
120    NodeShutdownHandle, WorkspaceConfig,
121};
122pub use session_environment::{
123    NodeSecretReference, NodeSecretResolveError, NodeSecretResolver, NodeSecretValue,
124    NodeSecretValueError, NodeSessionEnvironmentMutation, NodeSessionFile,
125    NodeSessionMaterializationProfile, NodeSessionMaterializationProfileError,
126    NodeSessionPathBinding, NodeSessionPathClass, MAX_NODE_SECRET_REFERENCE_BYTES,
127    MAX_NODE_SECRET_VALUE_BYTES, MAX_SESSION_ENVIRONMENT_ENTRIES,
128    MAX_SESSION_MATERIALIZATION_FILES, MAX_SESSION_MATERIALIZATION_FILE_BYTES,
129    MAX_SESSION_MATERIALIZATION_RELATIVE_PATH_BYTES,
130};
131pub use spawn_spec::{
132    SpawnProfileRegistry, SpawnProfileRegistryError, DEFAULT_SPAWN_PROFILE_ID, MAX_SPAWN_PROFILES,
133};
134pub use worktree_service::ManagedWorktreeProfile;
135
136#[cfg(windows)]
137pub use server::DEFAULT_NODE_ENDPOINT;
138
139pub use gate4agent_node_protocol as protocol;
140
141#[cfg(test)]
142mod kit_manifest {
143    #[test]
144    fn default_features_are_the_full_kit() {
145        let manifest = include_str!("../Cargo.toml");
146        let features = manifest
147            .split("[features]")
148            .nth(1)
149            .expect("features section")
150            .split("\n[")
151            .next()
152            .expect("features body");
153        assert!(
154            features.contains("default = [\"kit\"]"),
155            "default build must include the kit"
156        );
157        let kit = feature_array(features, "kit");
158        for core in ["m4a", "d2b", "session-restore", "wireguard", "memory"] {
159            assert!(
160                kit.iter().any(|item| item == core),
161                "kit feature missing {core}: {kit:?}"
162            );
163        }
164        assert!(
165            !features.contains("bare = "),
166            "there is no light mode"
167        );
168        let m4a = feature_array(features, "m4a");
169        assert_eq!(m4a, ["dep:mail4agent"]);
170        let d2b = feature_array(features, "d2b");
171        // The browser stream (websocket + frame encoding) rides with dig2browser.
172        assert_eq!(d2b, ["dep:dig2browser", "dep:tokio-tungstenite", "dep:futures-util", "dep:image"]);
173        let wg = feature_array(features, "wireguard");
174        assert_eq!(wg, ["gate4agent-node-core/wireguard"]);
175        let code = manifest
176            .lines()
177            .map(|line| line.split('#').next().unwrap_or(""))
178            .collect::<Vec<_>>()
179            .join("\n");
180        assert!(
181            !code.contains("hatchery-tui") && !code.contains("hatchery_tui"),
182            "node must not depend on the hatchery TUI"
183        );
184        assert!(manifest.contains("dig2browser = { version = \"0.5.3\""));
185        assert!(manifest.contains("mail4agent = { version = \"0.4.17\""));
186        assert!(!manifest.contains("[patch.crates-io]"), "published state has no patch table");
187        assert!(!manifest.contains("../../../"), "no path dependency leaves the workspace");
188        assert!(manifest.contains("claude-session-restore = { version = \"0.1.3\""));
189        assert!(manifest.contains("codex-session-restore = { version = \"0.1.3\""));
190        assert!(manifest.contains("grok-session-restore"));
191        assert!(manifest.contains("kimi-session-restore"));
192    }
193
194    fn feature_array(features: &str, name: &str) -> Vec<String> {
195        let line_start = features
196            .find(&format!("{name} = "))
197            .unwrap_or_else(|| panic!("missing feature {name}"));
198        let rest = &features[line_start + name.len() + 3..];
199        if rest.starts_with("[]") {
200            return Vec::new();
201        }
202        assert!(rest.starts_with("["), "{name} must be an array");
203        let end = rest.find(']').unwrap_or_else(|| panic!("{name} array"));
204        rest[1..end]
205            .split(',')
206            .map(|item| item.trim().trim_matches('"').to_owned())
207            .filter(|item| !item.is_empty())
208            .collect()
209    }
210}
211
212
213#[cfg(test)]
214mod deploy_artifacts {
215    //! Static checks for the three kit deploy modes. No Docker build, no
216    //! QEMU boot, no network. Lives in `--lib` so the ordinary node test
217    //! cycle refuses missing or gutted deploy entry points.
218
219    #[test]
220    fn service_unit_is_mode1_kit_entry() {
221        let unit = include_str!("../deploy/node/gate4agent-node.service");
222        assert!(unit.contains("ExecStart=/usr/local/bin/gate4agent-node"));
223        assert!(unit.contains("gate4agent node (standard kit)"));
224        assert!(
225            !unit.contains("INSTALL_PROVIDER_CLIS"),
226            "mode 1 unit must not install provider CLIs"
227        );
228        assert!(
229            unit.contains("GATE4AGENT_WG_INTERFACE") || unit.contains("WireGuard"),
230            "unit must document optional WG env"
231        );
232    }
233
234    #[test]
235    fn dockerfile_and_build_script_are_mode2() {
236        let dockerfile = include_str!("../deploy/node/Dockerfile");
237        assert!(dockerfile.contains("cargo build --locked --release -p hatchery-node"));
238        assert!(dockerfile.contains("ENTRYPOINT [\"gate4agent-node\"]"));
239        assert!(!dockerfile.contains("COPY mail4agent"));
240        assert!(!dockerfile.contains("COPY gate4agent"), "crates.io only: no sibling checkouts");
241        assert!(
242            !dockerfile.contains("GATE4AGENT_NODE_TOKEN"),
243            "image must not bake a node token"
244        );
245        let build = include_str!("../deploy/node/docker-build.sh");
246        assert!(build.contains("docker build"));
247        assert!(build.contains("gate4agent-node:kit"));
248        assert!(!build.contains("copy_tree \"$WS/mail4agent\""));
249    }
250
251    #[test]
252    fn qemu_guest_script_is_mode3_underlay_only() {
253        let script = include_str!("../deploy/node/qemu-guest.sh");
254        assert!(script.contains("Mode 3"));
255        assert!(script.contains("QEMU_NET"));
256        assert!(script.contains("tap") && script.contains("user"));
257        assert!(
258            script.contains("Kernel WireGuard is not a QEMU network"),
259            "script must keep WG out of the QEMU NIC story"
260        );
261        assert!(script.contains("GATE4AGENT_WG_"));
262        assert!(script.contains("gate4agent-node"));
263        // Guest boot stays opt-in: this test only reads the script text.
264        assert!(
265            !script.contains("cargo test"),
266            "qemu guest script must not be wired into cargo test"
267        );
268    }
269
270    #[test]
271    fn deploy_readme_names_three_modes() {
272        let readme = include_str!("../deploy/node/README.md");
273        assert!(readme.contains("Mode 1 — service"));
274        assert!(readme.contains("Mode 2 — container"));
275        assert!(readme.contains("Mode 3 — QEMU guest"));
276        assert!(readme.contains("no light mode"));
277    }
278}
hatchery_node/lib.rs

hatchery_node/
lib.rs
