diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 0f189a40a..988e7baf7 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -129,6 +129,9 @@ The descriptor validates the following `harness.settings` fields: | `terminal_timeout` | positive number | `60` | Limits a Hermes terminal tool operation in seconds; it does not enable a TUI. | | `interfaces.api`, `interfaces.dashboard`, `interfaces.terminal` | object | None | Serve Hermes's API or shared dashboard/terminal TUI backend, with an exact `port` and optional `enabled`. Dashboard and terminal ports must match when both are enabled; API requires a distinct port; see [Hermes invocation paths](../../../docs/integrations/harness/hermes/hermes.mdx). | | `startup_timeout_seconds` | number, greater than 0 and at most 75 | `60` | Time from the start of the runtime for every enabled interface to pass its health check. | +| `auxiliary.title_generation.enabled` | boolean | Hermes native default; `false` with Relay | Native automatic session-title generation. An explicit value wins over the Relay default. | +| `auxiliary.background_review.enabled` | boolean | Hermes native default | Native automatic background memory and skill review after turns. Explicit native `/refine` remains available. | +| `tools.tool_search.enabled` | `auto`, `on`, `off`, or boolean | Hermes native default | Native tool search; `true` and `false` are aliases for `on` and `off`. `off` presents the selected tool schemas directly. | For example: @@ -147,6 +150,12 @@ harness = HarnessConfig( ) ``` +### Native Harness Controls + +The `auxiliary` and `tools` settings use Hermes's native `config.yaml` structure. The adapter writes only the fields you set, before any SDK agent or native interface starts, so all four execution paths read them. Omitting a field keeps the current behavior. For title generation, an explicit value always wins; when it is omitted, a Relay-enabled runtime keeps writing `false` and other runtimes keep Hermes's default. `harness.settings.tools` is Hermes's native tools section and is separate from NeMo Fabric's normalized top-level `tools.enabled` and `tools.blocked`. + +These controls reduce automatic background model calls. They do not stop context compaction calls and do not correlate concurrent sessions; refer to the [Hermes guide](../../../docs/integrations/harness/hermes/hermes.mdx#native-harness-controls). + ## Configuration Mapping and Ownership Managed native processes use the adapter's launcher to apply explicit instructions and behavioral settings before constructing agents. Explicit enabled tools, including an empty list, override native selection; a nonempty blocked list overrides native exclusions. Unspecified tool policies can differ between SDK and native paths. diff --git a/adapters/python/hermes/hermes.fabric-adapter.json b/adapters/python/hermes/hermes.fabric-adapter.json index 5071a5318..91b6a5477 100644 --- a/adapters/python/hermes/hermes.fabric-adapter.json +++ b/adapters/python/hermes/hermes.fabric-adapter.json @@ -149,6 +149,65 @@ }, "additionalProperties": false, "description": "Embedded SDK execution, enabled by default. Runtime management remains available when disabled." + }, + "auxiliary": { + "type": "object", + "properties": { + "title_generation": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether Hermes generates session titles automatically. When omitted, Relay-enabled runtimes disable it and other runtimes keep Hermes's default." + } + }, + "additionalProperties": false, + "description": "Hermes's native auxiliary.title_generation section." + }, + "background_review": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether Hermes starts automatic background memory and skill reviews after turns. Explicit native /refine remains available. When omitted, Hermes's default applies." + } + }, + "additionalProperties": false, + "description": "Hermes's native auxiliary.background_review section." + } + }, + "additionalProperties": false, + "description": "Native Hermes auxiliary-task controls written to config.yaml for every execution path. Only authored fields are written." + }, + "tools": { + "type": "object", + "properties": { + "tool_search": { + "type": "object", + "properties": { + "enabled": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "auto", + "on", + "off" + ] + } + ], + "description": "Hermes tool search: auto, on, or off; true and false are native aliases for on and off. off presents the selected tool schemas directly. When omitted, Hermes's default applies." + } + }, + "additionalProperties": false, + "description": "Hermes's native tools.tool_search section." + } + }, + "additionalProperties": false, + "description": "Native Hermes tools section written to config.yaml. Distinct from NeMo Fabric's normalized top-level tools.enabled and tools.blocked. Only authored fields are written." } }, "required": [], diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py index 9dda0920f..252322797 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -878,7 +878,6 @@ def _invoke_hermes_turn( conversation_history=conversation_history, task_id=task_id, sync_honcho=False, - dont_review=True, ) result = agent.run_conversation( user_message, diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py index 0441b5115..0ca379a33 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py @@ -125,6 +125,25 @@ def _interface_model(model_config: AgentModelConfig) -> dict[str, Any]: ) +def _native_auxiliary( + settings: dict[str, Any], *, relay_enabled: bool +) -> dict[str, Any]: + """Return the authored auxiliary-task switches for native config.yaml. + + An explicit title-generation value wins. When it is omitted, Relay-enabled + runtimes keep title generation off because Hermes makes an extra model call + for titles, which skews Relay telemetry. + """ + authored = settings.get("auxiliary", {}) + auxiliary: dict[str, Any] = {} + for task in ("title_generation", "background_review"): + if "enabled" in authored.get(task, {}): + auxiliary[task] = {"enabled": authored[task]["enabled"]} + if relay_enabled and "title_generation" not in auxiliary: + auxiliary["title_generation"] = {"enabled": False} + return auxiliary + + def build_hermes_config( agent_config: AgentConfig, *, @@ -168,9 +187,13 @@ def build_hermes_config( config["agent"]["cron_drain_timeout"] = GATEWAY_DRAIN_TIMEOUT_SECONDS config["agent"]["restart_drain_timeout"] = 0 - if relay_enabled: - # Hermes makes an extra model call for titles, which skews Relay telemetry. - config["auxiliary"] = {"title_generation": {"enabled": False}} + auxiliary = _native_auxiliary(settings, relay_enabled=relay_enabled) + if auxiliary: + config["auxiliary"] = auxiliary + tool_search = settings.get("tools", {}).get("tool_search", {}) + if "enabled" in tool_search: + # Hermes reads booleans as aliases for on/off, so pass values through. + config["tools"] = {"tool_search": {"enabled": tool_search["enabled"]}} skill_dirs = ( [str(path) for path in agent_config.skills.paths] diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index 4290d204d..ab765d823 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -127,6 +127,14 @@ The following settings are specific to the OpenClaw adapter: | `shutdown_timeout_seconds` | `5` | Graceful shutdown timeout. | | `connect_timeout_seconds` | `10` | Local HTTP connection timeout. | | `read_timeout_seconds` | None | Local HTTP response timeout. When unset, the invocation timeout bounds the response. | +| `agents.defaults.heartbeat.every` | OpenClaw native default | Recurring heartbeat interval with units, such as `30m`; `0m` disables the recurring cadence but not event-driven turns. | +| `agents.defaults.compaction.memoryFlush.enabled` | OpenClaw native default | Pre-compaction memory flush turn. Compaction itself still runs. | +| `tools.exec.notifyOnExit` | OpenClaw native default | System event and heartbeat when a backgrounded `exec` process exits. | +| `tools.toolSearch` | OpenClaw native default | Tool search for large tool catalogs. | +| `tools.codeMode` | OpenClaw native default | Code Mode, which can take precedence over tool search and exposes only `exec` and `wait`; do not combine it with blocking `exec`. | +| `plugins.entries.memory-core.config.dreaming.enabled` | OpenClaw native default | Scheduled dreaming in the `memory-core` plugin. | + +The `agents`, `tools`, and `plugins` settings use OpenClaw's native structure. The adapter merges only the fields you set into the generated `openclaw.json` for managed runtimes and prepared services, beside the generated `agents.defaults`, `tools.allow`, `tools.deny`, and adapter-owned plugin entries, without replacing generated keys. Omitting a field preserves the current behavior. `harness.settings.tools` is separate from the normalized top-level `tools.enabled` and `tools.blocked` selectors. Attached Gateways reject these settings. These controls do not stop context compaction or correlate concurrent sessions, and they do not add NeMo Relay support; refer to [Native Gateway Controls](../../../docs/integrations/harness/openclaw/openclaw.mdx#native-gateway-controls). OpenClaw's [derived-port mapping](https://docs.openclaw.ai/gateway/multiple-gateways#port-mapping-derived) uses `base_port + 2` for browser control and allocates browser CDP ports from `base_port + 11` through `base_port + 110`. Set `port_range` when the consumer reserves a port range before configuring NeMo Fabric; the adapter selects a base whose complete derived footprint fits inside that range. The adapter verifies only that `base_port` and `base_port + 2` are available before startup. OpenClaw allocates the CDP ports on demand instead of reserving the complete range, so the adapter cannot guarantee that those ports will still be available when OpenClaw needs them. Keep the configured range reserved for the lifetime of the runtime when using OpenClaw browser features. @@ -294,8 +302,9 @@ async with await fabric.attach_service(config, reference) as service: The attached configuration can contain request-level model sampling and a system instruction. Remove deployment-owned model endpoints, API-key references, tools, MCP servers, skills, the OpenClaw command, channel -configuration, port range, and startup or shutdown timeouts because NeMo Fabric -cannot verify or apply those fields to an existing Gateway. Connection and read +configuration, port range, startup or shutdown timeouts, and the native +`agents`, `tools`, and `plugins` harness settings because NeMo Fabric cannot +verify or apply those fields to an existing Gateway. Connection and read timeouts and `agent_id` remain valid client-side settings. Releasing an attachment closes only NeMo Fabric-owned clients and private connection material; it does not stop the Gateway. diff --git a/adapters/python/openclaw/openclaw.fabric-adapter.json b/adapters/python/openclaw/openclaw.fabric-adapter.json index f77440d86..6910c3c65 100644 --- a/adapters/python/openclaw/openclaw.fabric-adapter.json +++ b/adapters/python/openclaw/openclaw.fabric-adapter.json @@ -137,6 +137,106 @@ "type": "number", "exclusiveMinimum": 0, "description": "Timeout between response bytes from the local OpenClaw Gateway. When unset, the invocation timeout bounds the response." + }, + "agents": { + "type": "object", + "properties": { + "defaults": { + "type": "object", + "properties": { + "heartbeat": { + "type": "object", + "properties": { + "every": { + "type": "string", + "pattern": "^(?:[0-9]+(?:\\.[0-9]+)?(?:ms|s|m|h|d))+$", + "description": "Native recurring heartbeat interval, such as 30m or 1h30m. Units are required; 0m disables the recurring cadence but not event-driven turns." + } + }, + "additionalProperties": false + }, + "compaction": { + "type": "object", + "properties": { + "memoryFlush": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether OpenClaw runs its pre-compaction memory flush turn. This does not stop compaction itself." + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false, + "description": "Native OpenClaw agents.defaults controls for NeMo Fabric-owned Gateways. Only authored fields are written; attached Gateways reject them." + }, + "tools": { + "type": "object", + "properties": { + "exec": { + "type": "object", + "properties": { + "notifyOnExit": { + "type": "boolean", + "description": "Whether OpenClaw emits a system event and heartbeat when a backgrounded exec process exits." + } + }, + "additionalProperties": false + }, + "toolSearch": { + "type": "boolean", + "description": "Whether OpenClaw compacts large tool catalogs behind search tools." + }, + "codeMode": { + "type": "boolean", + "description": "Whether OpenClaw Code Mode is enabled. Code Mode can take precedence over tool search." + } + }, + "additionalProperties": false, + "description": "Native OpenClaw tools controls for NeMo Fabric-owned Gateways, merged with the allow and deny lists generated from NeMo Fabric's normalized top-level tools. Only authored fields are written; attached Gateways reject them." + }, + "plugins": { + "type": "object", + "properties": { + "entries": { + "type": "object", + "properties": { + "memory-core": { + "type": "object", + "properties": { + "config": { + "type": "object", + "properties": { + "dreaming": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether the memory-core plugin runs scheduled dreaming." + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false + } + }, + "additionalProperties": false, + "description": "Native OpenClaw plugin controls for NeMo Fabric-owned Gateways. Only authored fields are written; attached Gateways reject them." } }, "dependentSchemas": { diff --git a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py index c329af881..e9202e652 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -64,6 +64,8 @@ # OpenClaw's tools.effective notice for an MCP server whose last connection or # tool listing failed in the session. MCP_SERVER_DIAGNOSTIC_PREFIX = "mcp-server-diagnostic:" +# Harness settings written into the Gateway's native openclaw.json. +NATIVE_SETTING_SECTIONS = ("agents", "tools", "plugins") logger = logging.getLogger(__name__) @@ -130,6 +132,7 @@ def _validate_attach_config(config: contract.AgentConfig) -> None: "port_range", "startup_timeout_seconds", "shutdown_timeout_seconds", + *NATIVE_SETTING_SECTIONS, ): if name in settings: unsupported.append(f"harness.settings.{name}") @@ -532,6 +535,33 @@ def _unavailable_mcp_servers( return list(entries.values()) +def _merge_native_settings( + target: dict[str, Any], key: str, authored: Any, *, field: str +) -> None: + """Write authored native leaves without replacing generated configuration. + + The descriptor's closed schema keeps these sections apart from the keys the + adapter generates; a collision is refused rather than overwritten. + """ + existing = target.get(key) + if not isinstance(authored, dict) or ( + existing is not None and not isinstance(existing, dict) + ): + if key in target: + raise lifecycle.LifecycleError( + "openclaw_invalid_configuration", + "OpenClaw native setting conflicts with NeMo Fabric-generated configuration", + metadata={"field": field}, + ) + target[key] = authored + return + section = {} if existing is None else existing + for name, value in authored.items(): + _merge_native_settings(section, name, value, field=f"{field}.{name}") + if section: + target[key] = section + + def _openclaw_config( config: contract.AgentConfig, context: contract.RuntimeContext, @@ -647,6 +677,15 @@ def _openclaw_config( mcp = _mcp_config(config) if mcp: result["mcp"] = {"servers": mcp} + settings = config.harness.settings if config.harness else {} + for section in NATIVE_SETTING_SECTIONS: + if section in settings: + _merge_native_settings( + result, + section, + settings[section], + field=f"harness.settings.{section}", + ) provider: dict[str, Any] = {} if model.base_url is not None: provider.update( diff --git a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json index 5071a5318..91b6a5477 100644 --- a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json +++ b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json @@ -149,6 +149,65 @@ }, "additionalProperties": false, "description": "Embedded SDK execution, enabled by default. Runtime management remains available when disabled." + }, + "auxiliary": { + "type": "object", + "properties": { + "title_generation": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether Hermes generates session titles automatically. When omitted, Relay-enabled runtimes disable it and other runtimes keep Hermes's default." + } + }, + "additionalProperties": false, + "description": "Hermes's native auxiliary.title_generation section." + }, + "background_review": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether Hermes starts automatic background memory and skill reviews after turns. Explicit native /refine remains available. When omitted, Hermes's default applies." + } + }, + "additionalProperties": false, + "description": "Hermes's native auxiliary.background_review section." + } + }, + "additionalProperties": false, + "description": "Native Hermes auxiliary-task controls written to config.yaml for every execution path. Only authored fields are written." + }, + "tools": { + "type": "object", + "properties": { + "tool_search": { + "type": "object", + "properties": { + "enabled": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "auto", + "on", + "off" + ] + } + ], + "description": "Hermes tool search: auto, on, or off; true and false are native aliases for on and off. off presents the selected tool schemas directly. When omitted, Hermes's default applies." + } + }, + "additionalProperties": false, + "description": "Hermes's native tools.tool_search section." + } + }, + "additionalProperties": false, + "description": "Native Hermes tools section written to config.yaml. Distinct from NeMo Fabric's normalized top-level tools.enabled and tools.blocked. Only authored fields are written." } }, "required": [], diff --git a/docs/integrations/harness/hermes/hermes-sdk.mdx b/docs/integrations/harness/hermes/hermes-sdk.mdx index 64cbd964f..de8a8d7b9 100644 --- a/docs/integrations/harness/hermes/hermes-sdk.mdx +++ b/docs/integrations/harness/hermes/hermes-sdk.mdx @@ -69,6 +69,11 @@ The descriptor uses closed schemas, so unknown settings are rejected. | `save_trajectories` | `false` | Save native JSONL trajectories; separate from normalized telemetry. | | `max_tokens` | Hermes native default | Response-token limit used when the selected model has no explicit `max_tokens`. A model-level limit takes precedence; if both are omitted, Hermes uses its native default. | | `terminal_timeout` | `60` | Positive timeout in seconds for a Hermes terminal tool operation; this does not enable a TUI. | +| `auxiliary.title_generation.enabled` | Hermes native default; `false` with Relay | Automatic session-title generation. An explicit value wins over the Relay default. | +| `auxiliary.background_review.enabled` | Hermes native default | Automatic background memory and skill review after turns. | +| `tools.tool_search.enabled` | Hermes native default | Native tool search: `auto`, `on`, `off`, `true`, or `false`. Separate from the normalized top-level `tools` selectors. | + +The `auxiliary` and `tools` settings apply to all four paths; refer to [Native Harness Controls](./hermes.mdx#native-harness-controls). Use the [API](./hermes-api.mdx), [dashboard](./hermes-dashboard.mdx), or [terminal TUI](./hermes-tui.mdx) guide for native interface selection. diff --git a/docs/integrations/harness/hermes/hermes.mdx b/docs/integrations/harness/hermes/hermes.mdx index 628d1bc5c..cf184e340 100644 --- a/docs/integrations/harness/hermes/hermes.mdx +++ b/docs/integrations/harness/hermes/hermes.mdx @@ -118,6 +118,36 @@ Model credentials are supplied through child process environments, not public at - Explicit enabled tools, including an empty list, override native tool selection. A nonempty blocked list overrides native exclusions. - Unspecified native tool policies can differ from SDK defaults. Set explicit policies when comparing behavior across paths. +### Native Harness Controls + +The following optional `harness.settings` fields use Hermes's native `config.yaml` structure: + +```yaml +harness: + adapter_id: nvidia.fabric.hermes + settings: + auxiliary: + title_generation: + enabled: false + background_review: + enabled: false + tools: + tool_search: + enabled: "off" +``` + +| Setting | Values | Behavior | +| --- | --- | --- | +| `auxiliary.title_generation.enabled` | boolean | `false` turns off automatic session-title generation. | +| `auxiliary.background_review.enabled` | boolean | `false` turns off automatic background memory and skill reviews after turns. Explicit native `/refine` remains available. | +| `tools.tool_search.enabled` | `auto`, `on`, `off`, `true`, or `false` | `off` presents the selected tool schemas directly instead of behind tool search. `true` and `false` are native aliases for `on` and `off`. `auto` follows the installed Hermes release. | + +The adapter writes only the fields you set into `config.yaml` before the SDK agent or any native interface starts, so the SDK, API, dashboard, and terminal paths all read the same values. Omitting a field preserves the current behavior. The closed descriptor schema rejects unknown fields and invalid values, such as `tool_search.enabled: maybe`. + +- **Title generation and Relay:** An explicit `title_generation.enabled` value always wins. When it is omitted, a Relay-enabled runtime disables title generation, as before, and other runtimes use Hermes's default. +- **Tool selection:** `harness.settings.tools` is Hermes's native tools section. It is separate from NeMo Fabric's normalized top-level `tools.enabled` and `tools.blocked` selectors, which still choose the Hermes toolsets. +- **Scope:** These controls reduce automatic background model calls; they do not stop context compaction calls. They configure every conversation in the runtime the same way and do not correlate concurrent sessions, so a consumer that tracks only the latest model request must use one session at a time. + ### Shared Runtime Home The default Hermes home is `/.fabric/hermes/runtimes/`. With `runtime.keep_state`, the Hermes home is `/.fabric/state/nvidia.fabric.hermes/`, so runtimes of the agent share the session database, memory, skills, and logs. The SDK starts a new conversation for each runtime, and earlier sessions remain in the database. The adapter rewrites `config.yaml` at each start. diff --git a/docs/integrations/harness/openclaw/openclaw-sdk.mdx b/docs/integrations/harness/openclaw/openclaw-sdk.mdx index 4813000be..8f2b07484 100644 --- a/docs/integrations/harness/openclaw/openclaw-sdk.mdx +++ b/docs/integrations/harness/openclaw/openclaw-sdk.mdx @@ -75,8 +75,9 @@ Fabric-owned clients and private connection material without stopping the caller-owned Gateway. Attached Gateways must use HTTPS unless the URL contains a literal loopback IP address. For an attached service, omit deployment-owned model endpoints, API-key references, tools, MCP servers, skills, channel -configuration, and startup settings from `config` because NeMo Fabric cannot -apply them to an existing Gateway. +configuration, [native Gateway controls](./openclaw.mdx#native-gateway-controls), +and startup settings from `config` because NeMo Fabric cannot apply them to an +existing Gateway. ## Execution and Isolation @@ -87,7 +88,8 @@ does not use the OpenClaw configuration RPC. The generated configuration: - binds the Gateway to loopback; - enables the OpenAI-compatible Chat Completions endpoint; - uses a cryptographically generated one-time Gateway token; -- applies the normalized workspace, model, skills, and MCP servers; +- applies the normalized workspace, model, skills, and MCP servers, and any + authored native Gateway controls; - disables OpenClaw anonymous telemetry; and - uses a unique temporary state directory. diff --git a/docs/integrations/harness/openclaw/openclaw.mdx b/docs/integrations/harness/openclaw/openclaw.mdx index e6c5f6535..ba1202595 100644 --- a/docs/integrations/harness/openclaw/openclaw.mdx +++ b/docs/integrations/harness/openclaw/openclaw.mdx @@ -16,7 +16,7 @@ You can use OpenClaw through the NVIDIA NeMo Fabric adapter in four ways: ## Shared Configuration -All four paths execute through one OpenClaw Gateway and its native agent runtime. NeMo Fabric translates `FabricConfig` into one private `openclaw.json`, with a fresh state directory, configured model/endpoint/credential references, generation parameters, workspace, tool policy, MCP servers, and skill paths. +All four paths execute through one OpenClaw Gateway and its native agent runtime. NeMo Fabric translates `FabricConfig` into one private `openclaw.json`, with a fresh state directory, configured model/endpoint/credential references, generation parameters, workspace, tool policy, MCP servers, skill paths, and any authored [native Gateway controls](#native-gateway-controls). When a native interface is enabled, a small adapter-owned plugin adds the configured instruction through OpenClaw's public `before_prompt_build` hook for the selected agent. It preserves OpenClaw's native system prompt, including tool guidance. SDK requests then omit their separate instruction injection, so each client receives the Fabric instruction once. SDK-only and service configurations retain their existing system-message handling. @@ -132,6 +132,49 @@ For a [NeMo Fabric-owned service](./openclaw-sdk.mdx#use-a-shared-service), `har Every binding must target the configured `agent_id`. OpenClaw validates the nested channel settings. Channel traffic flows directly between the channel and OpenClaw; it does not pass through a NeMo Fabric runtime. +### Native Gateway Controls + +The following optional `harness.settings` fields use OpenClaw's native `openclaw.json` structure: + +```yaml +harness: + adapter_id: nvidia.fabric.openclaw + settings: + agents: + defaults: + heartbeat: + every: 0m + compaction: + memoryFlush: + enabled: false + tools: + exec: + notifyOnExit: false + toolSearch: false + codeMode: false + plugins: + entries: + memory-core: + config: + dreaming: + enabled: false +``` + +| Setting | Values | Behavior | +| --- | --- | --- | +| `agents.defaults.heartbeat.every` | Duration with units, such as `30m`, `1h30m`, or `500ms` | Recurring heartbeat interval. `0m` disables the recurring cadence; it does not stop event-driven turns. | +| `agents.defaults.compaction.memoryFlush.enabled` | boolean | `false` turns off the pre-compaction memory flush turn. Compaction itself still runs. | +| `tools.exec.notifyOnExit` | boolean | `false` stops the system event and heartbeat when a backgrounded `exec` process exits. | +| `tools.toolSearch` | boolean | `false` presents tool schemas directly instead of behind tool search. | +| `tools.codeMode` | boolean | Code Mode. When enabled, it can take precedence over tool search and exposes only `exec` and `wait`, so do not combine it with blocking `exec` through `tools.blocked`. | +| `plugins.entries.memory-core.config.dreaming.enabled` | boolean | `false` turns off scheduled dreaming in the `memory-core` plugin. | + +The adapter merges only the fields you set into the generated `openclaw.json` before the Gateway starts. It adds them beside the generated `agents.defaults`, the `tools.allow` and `tools.deny` lists, and any adapter-owned plugin entry without replacing generated keys. Omitting a field preserves the current behavior. The closed descriptor schema rejects unknown fields and invalid values. Heartbeat durations require units. OpenClaw treats an unparseable value such as `30 minutes` as no heartbeat, so the schema rejects it, and it also rejects bare numbers such as `30` to avoid ambiguity. + +- **Ownership:** Managed runtimes and NeMo Fabric-owned prepared services apply these controls, so they reach SDK invocations, every runtime connected to a prepared service, and the native API, dashboard, and terminal clients of a managed runtime. A caller-owned Gateway keeps its deployment-owned configuration: `attach_service()` rejects these fields with `openclaw_attach_configuration_unverifiable`. +- **Tool selection:** `harness.settings.tools` is OpenClaw's native tools section. It is separate from NeMo Fabric's normalized top-level `tools.enabled` and `tools.blocked` selectors, which still generate `tools.allow` and `tools.deny`. +- **Scope:** These controls reduce automatic background turns; they do not stop context compaction. They apply to every session on the Gateway and do not correlate concurrent sessions, so a consumer that tracks only the latest model request must use one session at a time. They do not add NeMo Relay support to the OpenClaw adapter. + ## Select Native Interfaces An absent interface is off. A present interface is enabled unless `enabled` is `false`: diff --git a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json index 5071a5318..91b6a5477 100644 --- a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json +++ b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json @@ -149,6 +149,65 @@ }, "additionalProperties": false, "description": "Embedded SDK execution, enabled by default. Runtime management remains available when disabled." + }, + "auxiliary": { + "type": "object", + "properties": { + "title_generation": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether Hermes generates session titles automatically. When omitted, Relay-enabled runtimes disable it and other runtimes keep Hermes's default." + } + }, + "additionalProperties": false, + "description": "Hermes's native auxiliary.title_generation section." + }, + "background_review": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "description": "Whether Hermes starts automatic background memory and skill reviews after turns. Explicit native /refine remains available. When omitted, Hermes's default applies." + } + }, + "additionalProperties": false, + "description": "Hermes's native auxiliary.background_review section." + } + }, + "additionalProperties": false, + "description": "Native Hermes auxiliary-task controls written to config.yaml for every execution path. Only authored fields are written." + }, + "tools": { + "type": "object", + "properties": { + "tool_search": { + "type": "object", + "properties": { + "enabled": { + "anyOf": [ + { + "type": "boolean" + }, + { + "type": "string", + "enum": [ + "auto", + "on", + "off" + ] + } + ], + "description": "Hermes tool search: auto, on, or off; true and false are native aliases for on and off. off presents the selected tool schemas directly. When omitted, Hermes's default applies." + } + }, + "additionalProperties": false, + "description": "Hermes's native tools.tool_search section." + } + }, + "additionalProperties": false, + "description": "Native Hermes tools section written to config.yaml. Distinct from NeMo Fabric's normalized top-level tools.enabled and tools.blocked. Only authored fields are written." } }, "required": [], diff --git a/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json b/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json index a3c67923e..3572016c9 100644 --- a/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json +++ b/sdk/python/nemo-fabric-adapter-catalog/src/nemo_fabric_adapter_catalog/catalog.json @@ -918,6 +918,35 @@ } ], "properties": { + "auxiliary": { + "additionalProperties": false, + "description": "Native Hermes auxiliary-task controls written to config.yaml for every execution path. Only authored fields are written.", + "properties": { + "background_review": { + "additionalProperties": false, + "description": "Hermes's native auxiliary.background_review section.", + "properties": { + "enabled": { + "description": "Whether Hermes starts automatic background memory and skill reviews after turns. Explicit native /refine remains available. When omitted, Hermes's default applies.", + "type": "boolean" + } + }, + "type": "object" + }, + "title_generation": { + "additionalProperties": false, + "description": "Hermes's native auxiliary.title_generation section.", + "properties": { + "enabled": { + "description": "Whether Hermes generates session titles automatically. When omitted, Relay-enabled runtimes disable it and other runtimes keep Hermes's default.", + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + }, "interfaces": { "additionalProperties": false, "description": "Native interfaces served by the runtime as child processes.", @@ -1057,6 +1086,36 @@ "description": "Maximum number of seconds for a Hermes terminal operation.", "exclusiveMinimum": 0, "type": "number" + }, + "tools": { + "additionalProperties": false, + "description": "Native Hermes tools section written to config.yaml. Distinct from NeMo Fabric's normalized top-level tools.enabled and tools.blocked. Only authored fields are written.", + "properties": { + "tool_search": { + "additionalProperties": false, + "description": "Hermes's native tools.tool_search section.", + "properties": { + "enabled": { + "anyOf": [ + { + "type": "boolean" + }, + { + "enum": [ + "auto", + "on", + "off" + ], + "type": "string" + } + ], + "description": "Hermes tool search: auto, on, or off; true and false are native aliases for on and off. off presents the selected tool schemas directly. When omitted, Hermes's default applies." + } + }, + "type": "object" + } + }, + "type": "object" } }, "required": [], @@ -1079,7 +1138,7 @@ "name": "nemo-fabric-adapters-hermes", "version": "0.7.0" }, - "sha256": "d4ffb1125719a5e7ddaf1f58eb45f4f7b10e877288abc2a2abcc848075192301", + "sha256": "0a3da72a5086e275e6f3e26639d58014e95eebdd08bd0cc17906167bda0c3b70", "source": "adapters/python/hermes/hermes.fabric-adapter.json" }, "nvidia.fabric.kilo": { @@ -2182,6 +2241,46 @@ "pattern": "^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$", "type": "string" }, + "agents": { + "additionalProperties": false, + "description": "Native OpenClaw agents.defaults controls for NeMo Fabric-owned Gateways. Only authored fields are written; attached Gateways reject them.", + "properties": { + "defaults": { + "additionalProperties": false, + "properties": { + "compaction": { + "additionalProperties": false, + "properties": { + "memoryFlush": { + "additionalProperties": false, + "properties": { + "enabled": { + "description": "Whether OpenClaw runs its pre-compaction memory flush turn. This does not stop compaction itself.", + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + }, + "heartbeat": { + "additionalProperties": false, + "properties": { + "every": { + "description": "Native recurring heartbeat interval, such as 30m or 1h30m. Units are required; 0m disables the recurring cadence but not event-driven turns.", + "pattern": "^(?:[0-9]+(?:\\.[0-9]+)?(?:ms|s|m|h|d))+$", + "type": "string" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "type": "object" + }, "channel_config": { "additionalProperties": false, "description": "OpenClaw-native channels and bindings for NeMo Fabric-owned services. Every binding must target the configured agent. Managed runtimes reject channel configuration.", @@ -2281,6 +2380,41 @@ "minLength": 1, "type": "string" }, + "plugins": { + "additionalProperties": false, + "description": "Native OpenClaw plugin controls for NeMo Fabric-owned Gateways. Only authored fields are written; attached Gateways reject them.", + "properties": { + "entries": { + "additionalProperties": false, + "properties": { + "memory-core": { + "additionalProperties": false, + "properties": { + "config": { + "additionalProperties": false, + "properties": { + "dreaming": { + "additionalProperties": false, + "properties": { + "enabled": { + "description": "Whether the memory-core plugin runs scheduled dreaming.", + "type": "boolean" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "type": "object" + } + }, + "type": "object" + }, "port_range": { "additionalProperties": false, "description": "Inclusive consumer-allocated port range. The adapter selects a Gateway base port whose complete derived footprint through base + 110 fits within the range. When omitted, the adapter selects an available local range.", @@ -2319,6 +2453,31 @@ "exclusiveMinimum": 0, "maximum": 75, "type": "number" + }, + "tools": { + "additionalProperties": false, + "description": "Native OpenClaw tools controls for NeMo Fabric-owned Gateways, merged with the allow and deny lists generated from NeMo Fabric's normalized top-level tools. Only authored fields are written; attached Gateways reject them.", + "properties": { + "codeMode": { + "description": "Whether OpenClaw Code Mode is enabled. Code Mode can take precedence over tool search.", + "type": "boolean" + }, + "exec": { + "additionalProperties": false, + "properties": { + "notifyOnExit": { + "description": "Whether OpenClaw emits a system event and heartbeat when a backgrounded exec process exits.", + "type": "boolean" + } + }, + "type": "object" + }, + "toolSearch": { + "description": "Whether OpenClaw compacts large tool catalogs behind search tools.", + "type": "boolean" + } + }, + "type": "object" } }, "type": "object" @@ -2329,7 +2488,7 @@ "name": "nemo-fabric-adapters-openclaw", "version": "0.7.0" }, - "sha256": "dbfb74e0d2a2ba4db50bdc0d93140c0de3abc07d90f6551b9dd1f28458b9cc59", + "sha256": "ec8b5ab61b51a542e571084ebed6e428ce5c1b67d5bcc5080357032ccafaabab", "source": "adapters/python/openclaw/openclaw.fabric-adapter.json" }, "nvidia.fabric.opencode": { diff --git a/tests/adapters/test_hermes_config_builder.py b/tests/adapters/test_hermes_config_builder.py index 540e6af9c..88c9a894a 100644 --- a/tests/adapters/test_hermes_config_builder.py +++ b/tests/adapters/test_hermes_config_builder.py @@ -125,3 +125,111 @@ def import_without_yaml(name: str, *args: object, **kwargs: object) -> object: ) assert json.loads(config_path.read_text(encoding="utf-8")) == config + + +def _native_controls_config(settings: dict[str, object]) -> AgentConfig: + return AgentConfig.from_mapping( + { + "harness": {"settings": settings}, + "models": {"default": {"provider": "nvidia", "model": "nvidia/test-model"}}, + "tools": {"enabled": ["file"], "blocked": ["terminal"]}, + } + ) + + +@pytest.mark.parametrize("relay_enabled", [False, True]) +@pytest.mark.parametrize( + "settings", + [ + {}, + {"auxiliary": {}, "tools": {}}, + {"auxiliary": {"title_generation": {}, "background_review": {}}}, + {"tools": {"tool_search": {}}}, + ], + ids=["absent", "empty-sections", "empty-tasks", "empty-tool-search"], +) +def test_omitted_native_controls_keep_the_existing_config( + settings: dict[str, object], relay_enabled: bool +): + config = configuration.build_hermes_config( + _native_controls_config(settings), + workspace=".", + relay_enabled=relay_enabled, + ) + + # The configuration NeMo Fabric wrote before native controls existed. + expected = { + "model": {"provider": "nvidia", "default": "nvidia/test-model"}, + "agent": {"disabled_toolsets": ["terminal"]}, + "terminal": {"backend": "local", "cwd": ".", "timeout": 60}, + "platform_toolsets": {"cli": ["file"]}, + } + if relay_enabled: + expected["auxiliary"] = {"title_generation": {"enabled": False}} + assert config == expected + + +@pytest.mark.parametrize("enabled", [True, False]) +def test_authored_auxiliary_controls_reach_native_config(enabled: bool): + config = configuration.build_hermes_config( + _native_controls_config( + { + "auxiliary": { + "title_generation": {"enabled": enabled}, + "background_review": {"enabled": enabled}, + } + } + ), + workspace=".", + ) + + assert config["auxiliary"] == { + "title_generation": {"enabled": enabled}, + "background_review": {"enabled": enabled}, + } + assert "tools" not in config + + +@pytest.mark.parametrize("value", [True, False, "auto", "on", "off"]) +def test_tool_search_value_passes_through_as_authored(value: object): + config = configuration.build_hermes_config( + _native_controls_config({"tools": {"tool_search": {"enabled": value}}}), + workspace=".", + ) + + assert config["tools"] == {"tool_search": {"enabled": value}} + # Normalized tool selection stays in its own native sections. + assert config["platform_toolsets"] == {"cli": ["file"]} + assert config["agent"]["disabled_toolsets"] == ["terminal"] + assert "auxiliary" not in config + + +@pytest.mark.parametrize( + ("title_generation", "relay_enabled", "expected"), + [ + pytest.param(True, True, {"enabled": True}, id="explicit-true-relay"), + pytest.param(False, True, {"enabled": False}, id="explicit-false-relay"), + pytest.param(True, False, {"enabled": True}, id="explicit-true-no-relay"), + pytest.param(False, False, {"enabled": False}, id="explicit-false-no-relay"), + pytest.param(None, True, {"enabled": False}, id="omitted-relay"), + pytest.param(None, False, None, id="omitted-no-relay"), + ], +) +def test_title_generation_precedence_over_relay( + title_generation: bool | None, + relay_enabled: bool, + expected: dict[str, bool] | None, +): + auxiliary: dict[str, object] = {"background_review": {"enabled": False}} + if title_generation is not None: + auxiliary["title_generation"] = {"enabled": title_generation} + + config = configuration.build_hermes_config( + _native_controls_config({"auxiliary": auxiliary}), + workspace=".", + relay_enabled=relay_enabled, + ) + + # The Relay default must not replace other authored auxiliary controls. + assert config["auxiliary"]["background_review"] == {"enabled": False} + assert config["auxiliary"].get("title_generation") == expected diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py index 36bc41397..45443a1c6 100644 --- a/tests/adapters/test_hermes_interfaces.py +++ b/tests/adapters/test_hermes_interfaces.py @@ -1326,3 +1326,133 @@ async def api_turn(): assert (await runtime.check("ready"))["outcome"] == "passed" finally: await runtime.stop() + + +def _native_controls(tool_search: object = "off") -> dict[str, object]: + return { + "auxiliary": { + "title_generation": {"enabled": False}, + "background_review": {"enabled": False}, + }, + "tools": {"tool_search": {"enabled": tool_search}}, + } + + +def _hermes_native_controls() -> dict[str, object]: + """Read the controls through Hermes's own loaders for the current home.""" + from hermes_cli.config import load_config + from tools.tool_search import load_config as load_tool_search_config + + auxiliary = load_config()["auxiliary"] + return { + "title_generation": auxiliary["title_generation"]["enabled"], + "background_review": auxiliary["background_review"]["enabled"], + "tool_search": load_tool_search_config().enabled, + } + + +@pytest.mark.parametrize( + ("settings", "expected"), + [ + pytest.param( + {}, + { + "title_generation": True, + "background_review": True, + "tool_search": "auto", + }, + id="omitted-keeps-hermes-defaults", + ), + *[ + pytest.param( + _native_controls(tool_search), + { + "title_generation": False, + "background_review": False, + "tool_search": expected, + }, + id=f"tool-search-{tool_search}", + ) + for tool_search, expected in ( + (True, "on"), + (False, "off"), + ("on", "on"), + ("off", "off"), + ("auto", "auto"), + ) + ], + ], +) +async def test_sdk_agent_reads_native_controls_at_initialization( + tmp_path, monkeypatch, settings, expected +): + import hermes_state + import run_agent + + observed: dict[str, object] = {} + + def construct(*_args: object, **_kwargs: object) -> MagicMock: + observed.update(_hermes_native_controls()) + return MagicMock() + + monkeypatch.setattr(run_agent, "AIAgent", MagicMock(side_effect=construct)) + monkeypatch.setattr(hermes_state, "SessionDB", MagicMock()) + runtime = adapter.HermesRuntime() + try: + await runtime.start(_payload(tmp_path, settings)) + assert os.environ["HERMES_HOME"] == str(runtime._hermes_home) + finally: + await runtime.stop() + + assert observed == expected + + +@pytest.mark.parametrize( + ("interface", "command"), + [("api", "gateway"), ("dashboard", "dashboard"), ("terminal", "serve")], +) +@pytest.mark.usefixtures("web_dist") +async def test_native_interfaces_read_native_controls_before_startup( + tmp_path, monkeypatch, interface, command +): + from nemo_fabric_adapters.hermes import terminal + + spawned: list[tuple[tuple[str, ...], str, dict[str, object]]] = [] + + async def spawn(*arguments: str, env: dict[str, str], **_options: object): + # A child process reads config.yaml from its HERMES_HOME at startup. + os.environ["HERMES_HOME"] = env["HERMES_HOME"] + spawned.append((arguments, env["HERMES_HOME"], _hermes_native_controls())) + return MagicMock(returncode=0) + + monkeypatch.setattr(interfaces.asyncio, "create_subprocess_exec", spawn) + monkeypatch.setattr(interfaces, "_wait_healthy", AsyncMock()) + monkeypatch.setattr(terminal, "tui_ready", AsyncMock(return_value=True)) + settings = { + **_native_controls(False), + "sdk": {"enabled": False}, + **_interface(interface, port=_free_port()), + } + runtime = adapter.HermesRuntime() + try: + await runtime.start(_payload(tmp_path, settings)) + home = str(runtime._hermes_home) + if interface == "terminal": + # The terminal renderer attaches to the backend that owns this home. + connection = runtime._hermes_home / "interfaces" / "tui.json" + attachment = await asyncio.to_thread( + terminal.attachment_environment, connection + ) + assert attachment["HERMES_HOME"] == home + finally: + await runtime.stop() + + [(arguments, child_home, observed)] = spawned + assert arguments[1:3] == ("-m", "nemo_fabric_adapters.hermes.native") + assert arguments[5] == command + assert child_home == home + assert observed == { + "title_generation": False, + "background_review": False, + "tool_search": "off", + } diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index bb68a3d24..89c523bb7 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -2903,3 +2903,324 @@ async def test_status_command_timeout_stops_children_holding_the_pipes(tmp_path) else: os.kill(child_pid, signal.SIGKILL) pytest.fail("the status command's child kept running") + + +def _native_controls() -> dict[str, object]: + return { + "agents": { + "defaults": { + "heartbeat": {"every": "0m"}, + "compaction": {"memoryFlush": {"enabled": False}}, + } + }, + "tools": { + "exec": {"notifyOnExit": False}, + "toolSearch": False, + "codeMode": False, + }, + "plugins": { + "entries": {"memory-core": {"config": {"dreaming": {"enabled": False}}}} + }, + } + + +GENERATED_AGENT_DEFAULTS = { + "workspace", + "skipBootstrap", + "model", + "models", + "contextInjection", +} + + +def _generated(config: AgentConfig, tmp_path: Path, **options: object): + return adapter._openclaw_config( + config, + _context(tmp_path), + base_dir=tmp_path, + port=20_000, + token_env="OPENCLAW_GATEWAY_TOKEN", + **options, + ) + + +def _assert_native_controls_merged(generated: dict[str, object]): + defaults = generated["agents"]["defaults"] + assert set(defaults) == GENERATED_AGENT_DEFAULTS | {"heartbeat", "compaction"} + assert defaults["heartbeat"] == {"every": "0m"} + assert defaults["compaction"] == {"memoryFlush": {"enabled": False}} + assert defaults["model"] == {"primary": "test/fabric-echo"} + assert defaults["contextInjection"] == "never" + assert generated["tools"] == { + "allow": ["browser", "web_search"], + "deny": ["exec"], + "exec": {"notifyOnExit": False}, + "toolSearch": False, + "codeMode": False, + } + assert generated["plugins"]["entries"]["memory-core"] == { + "config": {"dreaming": {"enabled": False}} + } + + +@pytest.mark.parametrize( + "settings", + [ + pytest.param({}, id="absent"), + pytest.param({"agents": {}, "tools": {}, "plugins": {}}, id="empty-sections"), + pytest.param( + { + "agents": {"defaults": {"heartbeat": {}, "compaction": {}}}, + "tools": {"exec": {}}, + "plugins": {"entries": {"memory-core": {"config": {}}}}, + }, + id="empty-leaves", + ), + ], +) +def test_openclaw_omitted_native_controls_keep_generated_config( + mock_openclaw: Path, tmp_path: Path, settings: dict[str, object] +): + baseline = _generated(_config(mock_openclaw), tmp_path) + config = _config(mock_openclaw) + config.harness.settings.update(settings) + + generated = _generated(config, tmp_path) + + assert generated == baseline + assert set(generated["agents"]["defaults"]) == GENERATED_AGENT_DEFAULTS + assert generated["tools"] == {"allow": ["browser", "web_search"], "deny": ["exec"]} + assert "plugins" not in generated + + +@pytest.mark.parametrize( + ("settings", "path", "value"), + [ + pytest.param( + {"agents": {"defaults": {"heartbeat": {"every": "1h30m"}}}}, + ("agents", "defaults", "heartbeat", "every"), + "1h30m", + id="heartbeat", + ), + pytest.param( + { + "agents": { + "defaults": {"compaction": {"memoryFlush": {"enabled": True}}} + } + }, + ("agents", "defaults", "compaction", "memoryFlush", "enabled"), + True, + id="memory-flush", + ), + pytest.param( + {"tools": {"exec": {"notifyOnExit": True}}}, + ("tools", "exec", "notifyOnExit"), + True, + id="notify-on-exit", + ), + pytest.param( + {"tools": {"toolSearch": True}}, + ("tools", "toolSearch"), + True, + id="tool-search", + ), + pytest.param( + {"tools": {"codeMode": True}}, + ("tools", "codeMode"), + True, + id="code-mode", + ), + pytest.param( + { + "plugins": { + "entries": { + "memory-core": {"config": {"dreaming": {"enabled": True}}} + } + } + }, + ("plugins", "entries", "memory-core", "config", "dreaming", "enabled"), + True, + id="dreaming", + ), + ], +) +def test_openclaw_writes_only_authored_native_controls( + mock_openclaw: Path, + tmp_path: Path, + settings: dict[str, object], + path: tuple[str, ...], + value: object, +): + # The generated configuration plus exactly the authored leaf. + expected = _generated(_config(mock_openclaw), tmp_path) + parent = expected + for key in path[:-1]: + parent = parent.setdefault(key, {}) + parent[path[-1]] = value + config = _config(mock_openclaw) + config.harness.settings.update(settings) + + assert _generated(config, tmp_path) == expected + + +@pytest.mark.parametrize("service_mode", [False, True]) +@pytest.mark.parametrize("shared_plugin", [False, True]) +def test_openclaw_native_controls_merge_with_generated_config( + mock_openclaw: Path, tmp_path: Path, service_mode: bool, shared_plugin: bool +): + config = _config(mock_openclaw) + config.harness.settings.update(_native_controls()) + if shared_plugin: + config.harness.settings["interfaces"] = {"terminal": {}} + + generated = _generated(config, tmp_path, service_mode=service_mode) + + _assert_native_controls_merged(generated) + if shared_plugin: + assert set(generated["plugins"]["entries"]) == { + "fabric-shared-config", + "memory-core", + } + assert generated["plugins"]["load"]["paths"] + else: + assert generated["plugins"] == { + "entries": {"memory-core": {"config": {"dreaming": {"enabled": False}}}} + } + + +@pytest.mark.parametrize( + ("settings", "field"), + [ + pytest.param( + {"tools": {"allow": ["exec"]}}, "harness.settings.tools.allow", id="tools" + ), + pytest.param( + {"agents": {"defaults": {"workspace": "/tmp"}}}, + "harness.settings.agents.defaults.workspace", + id="agent-defaults", + ), + ], +) +def test_openclaw_native_controls_never_replace_generated_keys( + mock_openclaw: Path, tmp_path: Path, settings: dict[str, object], field: str +): + # The descriptor rejects these keys; the writer also refuses to overwrite. + config = _config(mock_openclaw) + config.harness.settings.update(settings) + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + _generated(config, tmp_path) + + assert caught.value.code == "openclaw_invalid_configuration" + assert caught.value.metadata == {"field": field} + + +@pytest.mark.skipif( + sys.platform == "win32", reason="Runs the mock openclaw script directly" +) +@pytest.mark.parametrize( + "gateway", + [ + "managed", + pytest.param( + "interfaces", + marks=pytest.mark.skipif( + os.name != "posix", reason="The native terminal requires POSIX" + ), + ), + "prepared", + ], +) +async def test_owned_gateways_receive_native_controls_before_startup( + mock_openclaw: Path, tmp_path: Path, dashboard_port: int, gateway: str +): + capture = tmp_path / "config.json" + os.environ["FAKE_OPENCLAW_CAPTURE"] = str(capture) + os.environ["FAKE_OPENCLAW_REQUEST"] = str(tmp_path / "request.json") + config = _config(mock_openclaw) + config.harness.settings.update(_native_controls()) + payload: dict[str, object] = {} + if gateway == "interfaces": + config.harness.settings["interfaces"] = { + "dashboard": {"port": dashboard_port}, + "terminal": {}, + } + connection_path = tmp_path / "private" / "service-connection.json" + if gateway == "prepared": + payload["service"] = { + "operation": "prepare", + "connection_path": str(connection_path), + } + runtime = adapter.OpenClawRuntime() + await _start(runtime, tmp_path, config, **payload) + try: + # OpenClaw validates the generated file before the Gateway starts. + generated = json.loads(capture.read_text(encoding="utf-8")) + _assert_native_controls_merged(generated) + if gateway == "interfaces": + directory = _dashboard_token(tmp_path).parent + assert (directory / "terminal.running").exists() + assert json.loads((directory / "gateway.json").read_text())["http_url"] == ( + f"http://127.0.0.1:{dashboard_port}" + ) + assert generated["gateway"]["controlUi"]["enabled"] is True + assert "fabric-shared-config" in generated["plugins"]["entries"] + if gateway == "prepared": + session = adapter.OpenClawRuntime() + context = _context(tmp_path, "runtime-a") + await session.start( + { + "config": config, + "runtime_context": context.to_mapping(), + "base_dir": str(tmp_path), + "service": { + "operation": "connect", + "service_id": "service-1", + "connection_path": str(connection_path), + }, + } + ) + try: + result = await session.invoke( + AgentRunRequest(input="Use the prepared Gateway."), context + ) + finally: + await session.stop() + assert result.status == "succeeded" + finally: + await runtime.stop() + + +@pytest.mark.parametrize("section", ["agents", "tools", "plugins"]) +async def test_openclaw_attach_rejects_native_controls(tmp_path: Path, section: str): + os.environ["OPENCLAW_GATEWAY_TOKEN"] = "caller-owned-token" + config = AgentConfig.from_mapping( + { + "harness": {"settings": {section: _native_controls()[section]}}, + "models": {"default": {"provider": "test", "model": "fabric-echo"}}, + } + ) + runtime = adapter.OpenClawRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await _start( + runtime, + tmp_path, + config, + service={ + "operation": "attach", + "connection_path": str(tmp_path / "service-connection.json"), + "reference": { + "adapter_id": "nvidia.fabric.openclaw", + "service_type": "openclaw_gateway", + "connection": { + "gateway_url": "http://127.0.0.1:9", + "gateway_token_env": "OPENCLAW_GATEWAY_TOKEN", + }, + }, + }, + ) + + assert caught.value.code == "openclaw_attach_configuration_unverifiable" + assert caught.value.metadata == {"fields": [f"harness.settings.{section}"]} + assert not (tmp_path / "service-connection.json").exists() diff --git a/tests/adapters/test_openclaw_native.py b/tests/adapters/test_openclaw_native.py index ecb1a2343..b4cfd3579 100644 --- a/tests/adapters/test_openclaw_native.py +++ b/tests/adapters/test_openclaw_native.py @@ -608,3 +608,94 @@ async def test_native_selection_preserves_sdk_prompt_guidance( (tmp_path / "sdk-prompt-compatibility.json").write_text( json.dumps(prompts, indent=2) ) + + +async def test_native_controls_apply_to_pinned_gateway( + tmp_path, api_server, native_config, monkeypatch +): + """The pinned Gateway accepts and applies the native harness controls.""" + + mapping = native_config.to_mapping() + mapping["harness"]["settings"].update( + { + "agents": { + "defaults": { + "heartbeat": {"every": "0m"}, + "compaction": {"memoryFlush": {"enabled": False}}, + } + }, + "tools": { + "exec": {"notifyOnExit": False}, + "toolSearch": False, + "codeMode": False, + }, + "plugins": { + "entries": {"memory-core": {"config": {"dreaming": {"enabled": False}}}} + }, + } + ) + config = FabricConfig.from_mapping(mapping) + temp_root = tmp_path / "tmp" + temp_root.mkdir() + monkeypatch.setenv("TMPDIR", str(temp_root)) + + fabric = Fabric() + async with await fabric.start_runtime(config, base_dir=tmp_path) as runtime: + # Startup runs `openclaw config validate` on the generated file first. + (config_path,) = temp_root.glob("nemo-fabric-openclaw-*/openclaw.json") + generated = json.loads(config_path.read_text()) + defaults = generated["agents"]["defaults"] + assert defaults["heartbeat"] == {"every": "0m"} + assert defaults["compaction"]["memoryFlush"] == {"enabled": False} + assert generated["tools"]["exec"]["notifyOnExit"] is False + assert generated["tools"]["toolSearch"] is False + assert generated["tools"]["codeMode"] is False + assert set(generated["tools"]["deny"]) >= {"exec", "process"} + assert generated["plugins"]["entries"]["memory-core"] == { + "config": {"dreaming": {"enabled": False}} + } + + process = await asyncio.create_subprocess_exec( + native_config.harness.settings["openclaw_command"], + "plugins", + "list", + "--json", + env={ + **os.environ, + "OPENCLAW_CONFIG_PATH": str(config_path), + "OPENCLAW_STATE_DIR": str(config_path.parent / "state"), + "OPENCLAW_CONFIG_READONLY": "1", + }, + stdout=asyncio.subprocess.PIPE, + stderr=asyncio.subprocess.PIPE, + ) + try: + stdout, stderr = await asyncio.wait_for(process.communicate(), 60) + except BaseException: + # Stop a hung CLI and reap it so its pipes close before the error propagates. + if process.returncode is None: + process.kill() + await process.communicate() + raise + assert process.returncode == 0, stderr.decode() + memory_core = next( + plugin + for plugin in json.loads(stdout)["plugins"] + if plugin["id"] == "memory-core" + ) + # A config-only plugin entry must not disable the bundled plugin. + assert memory_core["enabled"] is True, memory_core + assert memory_core["status"] == "loaded", memory_core + + async with httpx.AsyncClient(trust_env=False, timeout=60) as client: + await client.post( + f"{api_server}/_scenario", + json={"response_text": "native controls turn complete"}, + ) + result = await runtime.invoke(input="List the tools you can call.") + assert result.status == "succeeded", result.to_mapping() + payloads = (await client.get(f"{api_server}/_requests")).json() + tools = {tool["function"]["name"] for tool in payloads[-1].get("tools", [])} + # Tool search and Code Mode are off, so the MCP tool is presented directly. + assert "fabricprobe__get_authorization_header" in tools, tools + assert not tools & {"tool_search", "tool_describe", "tool_call"}, tools diff --git a/tests/python/test_harness_settings_validation.py b/tests/python/test_harness_settings_validation.py index 8e694119a..317a0d7f4 100644 --- a/tests/python/test_harness_settings_validation.py +++ b/tests/python/test_harness_settings_validation.py @@ -163,6 +163,45 @@ }, id="openclaw", ), + *[ + pytest.param( + "nvidia.fabric.hermes", + { + "auxiliary": { + "title_generation": {"enabled": False}, + "background_review": {"enabled": True}, + }, + "tools": {"tool_search": {"enabled": value}}, + }, + id=f"hermes-native-controls-{value}", + ) + for value in (True, False, "auto", "on", "off") + ], + *[ + pytest.param( + "nvidia.fabric.openclaw", + { + "agents": { + "defaults": { + "heartbeat": {"every": every}, + "compaction": {"memoryFlush": {"enabled": False}}, + } + }, + "tools": { + "exec": {"notifyOnExit": False}, + "toolSearch": False, + "codeMode": True, + }, + "plugins": { + "entries": { + "memory-core": {"config": {"dreaming": {"enabled": False}}} + } + }, + }, + id=f"openclaw-native-controls-{every}", + ) + for every in ("0m", "30m", "1h30m", "500ms", "1.5h") + ], pytest.param( "nvidia.fabric.openhands", {"condenser": "none"}, @@ -539,6 +578,156 @@ def test_openclaw_rejects_relay(tmp_path: Path): "harness.settings.terminal_timeout", id="hermes-terminal-timeout", ), + pytest.param( + "nvidia.fabric.hermes", + {"tools": {"tool_search": {"enabled": "maybe"}}}, + "harness.settings.tools.tool_search.enabled", + id="hermes-tool-search-value", + ), + pytest.param( + "nvidia.fabric.hermes", + {"tools": {"tool_search": {"enabled": 1}}}, + "harness.settings.tools.tool_search.enabled", + id="hermes-tool-search-type", + ), + pytest.param( + "nvidia.fabric.hermes", + {"tools": {"tool_search": {"enabled": "On"}}}, + "harness.settings.tools.tool_search.enabled", + id="hermes-tool-search-case", + ), + pytest.param( + "nvidia.fabric.hermes", + {"tools": {"tool_search": {"threshold_pct": 5}}}, + "harness.settings.tools.tool_search.threshold_pct", + id="hermes-tool-search-unknown", + ), + pytest.param( + "nvidia.fabric.hermes", + {"tools": {"enabled": ["file"]}}, + "harness.settings.tools.enabled", + id="hermes-native-tools-not-normalized", + ), + pytest.param( + "nvidia.fabric.hermes", + {"auxiliary": {"title_generation": {"enabled": "false"}}}, + "harness.settings.auxiliary.title_generation.enabled", + id="hermes-title-generation-type", + ), + pytest.param( + "nvidia.fabric.hermes", + {"auxiliary": {"background_review": {"enabled": 0}}}, + "harness.settings.auxiliary.background_review.enabled", + id="hermes-background-review-type", + ), + pytest.param( + "nvidia.fabric.hermes", + {"auxiliary": {"title_generation": {"model": "fast"}}}, + "harness.settings.auxiliary.title_generation.model", + id="hermes-title-generation-unknown", + ), + pytest.param( + "nvidia.fabric.hermes", + {"auxiliary": {"compression": {"enabled": False}}}, + "harness.settings.auxiliary.compression", + id="hermes-auxiliary-unknown-task", + ), + pytest.param( + "nvidia.fabric.hermes", + {"memory": {"memory_enabled": False}}, + "harness.settings.memory", + id="hermes-memory-deferred", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"agents": {"defaults": {"heartbeat": {"every": "30 minutes"}}}}, + "harness.settings.agents.defaults.heartbeat.every", + id="openclaw-heartbeat-typo", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"agents": {"defaults": {"heartbeat": {"every": "30"}}}}, + "harness.settings.agents.defaults.heartbeat.every", + id="openclaw-heartbeat-unitless", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"agents": {"defaults": {"heartbeat": {"every": 30}}}}, + "harness.settings.agents.defaults.heartbeat.every", + id="openclaw-heartbeat-type", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"agents": {"defaults": {"heartbeat": {"target": "last"}}}}, + "harness.settings.agents.defaults.heartbeat.target", + id="openclaw-heartbeat-unknown", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"agents": {"defaults": {"workspace": "/tmp"}}}, + "harness.settings.agents.defaults.workspace", + id="openclaw-generated-agent-default", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"agents": {"list": []}}, + "harness.settings.agents.list", + id="openclaw-agents-unknown", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"agents": {"defaults": {"compaction": {"memoryFlush": {"enabled": 1}}}}}, + "harness.settings.agents.defaults.compaction.memoryFlush.enabled", + id="openclaw-memory-flush-type", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"tools": {"exec": {"notifyOnExit": "false"}}}, + "harness.settings.tools.exec.notifyOnExit", + id="openclaw-notify-on-exit-type", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"tools": {"toolSearch": {"enabled": False}}}, + "harness.settings.tools.toolSearch", + id="openclaw-tool-search-type", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"tools": {"codeMode": "auto"}}, + "harness.settings.tools.codeMode", + id="openclaw-code-mode-type", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"tools": {"allow": ["exec"]}}, + "harness.settings.tools.allow", + id="openclaw-native-tools-not-normalized", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"plugins": {"entries": {"memory-core": {"enabled": False}}}}, + "harness.settings.plugins.entries.memory-core.enabled", + id="openclaw-memory-core-unknown", + ), + pytest.param( + "nvidia.fabric.openclaw", + {"plugins": {"entries": {"other": {"enabled": True}}}}, + "harness.settings.plugins.entries.other", + id="openclaw-plugin-unknown", + ), + pytest.param( + "nvidia.fabric.openclaw", + { + "plugins": { + "entries": { + "memory-core": {"config": {"dreaming": {"enabled": "no"}}} + } + } + }, + "harness.settings.plugins.entries.memory-core.config.dreaming.enabled", + id="openclaw-dreaming-type", + ), pytest.param( "nvidia.fabric.openhands", {"condenser": "llm_summarizing"},