From e3eb9bde0a35cdfe5453ea257a19596848fe5bc3 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 04:45:49 -0700 Subject: [PATCH 01/54] fix: stop agents where group signals are denied OpenShell's sandbox denies signals to a process group with EPERM. The OpenClaw adapter let that error escape its stop and left the Gateway running until the sandbox went away, and the ACP runner left the agent process running the same way. Both now signal the child itself when the group signal is denied. The Python adapters share `common.utils.signal_process_group` for this. Not covered here: the Codex adapter's SIGKILL of its app server, which has the same pattern. Signed-off-by: Carlos Villela --- .../src/nemo_fabric_adapters/common/utils.py | 17 +++++++++ .../nemo_fabric_adapters/openclaw/adapter.py | 17 +++------ adapters/typescript/common/src/acp-runner.ts | 10 ++++- .../common/test/acp-runner.test.mjs | 37 +++++++++++++++++-- .../strands/test/strands-acp.test.mjs | 7 ++-- tests/adapters/test_openclaw.py | 25 +++++++++++++ 6 files changed, 94 insertions(+), 19 deletions(-) diff --git a/adapters/python/common/src/nemo_fabric_adapters/common/utils.py b/adapters/python/common/src/nemo_fabric_adapters/common/utils.py index 9878b63e5..c45b6c10f 100644 --- a/adapters/python/common/src/nemo_fabric_adapters/common/utils.py +++ b/adapters/python/common/src/nemo_fabric_adapters/common/utils.py @@ -9,6 +9,7 @@ import json import os import re +import signal import sys import uuid from contextlib import nullcontext @@ -790,3 +791,19 @@ def write_relay_configs( def relay_model_name(payload: dict[str, Any]) -> str: return selected_model_config(payload).get("model") or "unknown" + + +def signal_process_group(pid: int, signum: signal.Signals) -> None: + """Signal a child's process group, or only the child where that's denied. + + OpenShell's sandbox denies signals to a process group with EPERM. + """ + try: + os.killpg(pid, signum) + except ProcessLookupError: + pass + except PermissionError: + try: + os.kill(pid, signum) + except ProcessLookupError: + pass 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 7c616642b..7e082eead 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -1583,10 +1583,7 @@ def _forward_gateway_signal(self, signum: int) -> None: process = self._process if process is None or process.returncode is not None: return - try: - os.killpg(process.pid, signum) - except ProcessLookupError: - pass + common_utils.signal_process_group(process.pid, signum) async def _wait_started(self, port: int, token: str, timeout: float) -> None: deadline = asyncio.get_running_loop().time() + timeout @@ -1735,10 +1732,7 @@ async def stop(self) -> None: if os.name == "nt": process.terminate() else: - try: - os.killpg(process.pid, signal.SIGTERM) - except ProcessLookupError: - pass + common_utils.signal_process_group(process.pid, signal.SIGTERM) try: await asyncio.wait_for( process.wait(), timeout=self._shutdown_timeout @@ -1749,10 +1743,9 @@ async def stop(self) -> None: if os.name == "nt": process.kill() else: - try: - os.killpg(process.pid, signal.SIGKILL) - except ProcessLookupError: - pass + common_utils.signal_process_group( + process.pid, signal.SIGKILL + ) try: await process.wait() except asyncio.CancelledError as error: diff --git a/adapters/typescript/common/src/acp-runner.ts b/adapters/typescript/common/src/acp-runner.ts index d2dd97a2d..fdfac458c 100644 --- a/adapters/typescript/common/src/acp-runner.ts +++ b/adapters/typescript/common/src/acp-runner.ts @@ -141,7 +141,15 @@ async function terminateProcessTree(child: ChildProcessWithoutNullStreams, timeo try { process.kill(-pid, signal); } catch (error) { - if ((error as NodeJS.ErrnoException).code !== "ESRCH") throw error; + const code = (error as NodeJS.ErrnoException).code; + if (code === "ESRCH") return; + // OpenShell's sandbox denies signals to a process group; signal the agent itself. + if (code !== "EPERM") throw error; + try { + process.kill(pid, signal); + } catch (fallbackError) { + if ((fallbackError as NodeJS.ErrnoException).code !== "ESRCH") throw fallbackError; + } } }; // Each agent has its own process group, including tool and MCP children. diff --git a/adapters/typescript/common/test/acp-runner.test.mjs b/adapters/typescript/common/test/acp-runner.test.mjs index db8da8019..8474c14ed 100644 --- a/adapters/typescript/common/test/acp-runner.test.mjs +++ b/adapters/typescript/common/test/acp-runner.test.mjs @@ -213,10 +213,11 @@ test("retries process-group termination after a failed stop", { skip: process.pl }); const pids = JSON.parse(await readFile(marker, "utf8")); const originalKill = process.kill.bind(process); - let failTermination = true; + // Deny the first stop's group signal and its fallback to the agent itself. + let deniedTerminations = 2; const kill = t.mock.method(process, "kill", (pid, signal) => { - if (pid === -pids.parent && signal === "SIGTERM" && failTermination) { - failTermination = false; + if (Math.abs(pid) === pids.parent && signal === "SIGTERM" && deniedTerminations > 0) { + deniedTerminations -= 1; throw Object.assign(new Error("termination denied"), { code: "EPERM" }); } return originalKill(pid, signal); @@ -252,3 +253,33 @@ test("retries process-group termination after a failed stop", { skip: process.pl } if (cleanupError !== undefined) throw cleanupError; }); + +test("stops the agent where process-group signals are denied", { skip: process.platform === "win32" }, async (t) => { + const directory = await mkdtemp(join(tmpdir(), "fabric-acp-denied-")); + const marker = join(directory, "pids.json"); + const session = await startAcpSession({ + command: process.execPath, + args: [fixture], + cwd: process.cwd(), + env: { ...process.env, TEST_DESCENDANT_MARKER: marker }, + shutdownTimeoutMs: 1_000, + }); + const pids = JSON.parse(await readFile(marker, "utf8")); + const originalKill = process.kill.bind(process); + // OpenShell's sandbox denies every signal to a process group. + const kill = t.mock.method(process, "kill", (pid, signal) => { + if (pid < 0) throw Object.assign(new Error("group signals denied"), { code: "EPERM" }); + return originalKill(pid, signal); + }); + try { + await session.stop(); + await waitForProcessToStop(pids.parent); + } finally { + kill.mock.restore(); + for (const pid of [pids.parent, pids.child]) { + try { originalKill(pid, "SIGKILL"); } catch (error) { + if (error.code !== "ESRCH") throw error; + } + } + } +}); diff --git a/adapters/typescript/strands/test/strands-acp.test.mjs b/adapters/typescript/strands/test/strands-acp.test.mjs index dbdc1f051..36d6d9f80 100644 --- a/adapters/typescript/strands/test/strands-acp.test.mjs +++ b/adapters/typescript/strands/test/strands-acp.test.mjs @@ -212,10 +212,11 @@ test("retains a timed-out runtime session until process cleanup succeeds", { ski const { pid: parent } = JSON.parse(await readFile(input.runtimeContext.environment.env.TEST_STRANDS_STATE, "utf8")); const { pid: child } = JSON.parse(await readFile(descendantState, "utf8")); const originalKill = process.kill.bind(process); - let failTermination = true; + // Deny the first stop's group signal and its fallback to the agent itself. + let deniedTerminations = 2; const kill = t.mock.method(process, "kill", (pid, signal) => { - if (pid === -parent && signal === "SIGTERM" && failTermination) { - failTermination = false; + if (Math.abs(pid) === parent && signal === "SIGTERM" && deniedTerminations > 0) { + deniedTerminations -= 1; throw Object.assign(new Error("termination denied"), { code: "EPERM" }); } return originalKill(pid, signal); diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index ffb1d7c67..f6f344fce 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -1323,6 +1323,31 @@ async def test_openclaw_stop_continues_after_cleanup_failures( assert runtime._temp_dir is None +@pytest.mark.skipif(os.name == "nt", reason="Requires POSIX process groups") +async def test_openclaw_stop_ends_the_gateway_where_group_signals_are_denied( + mock_openclaw: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + os.environ["FAKE_OPENCLAW_CAPTURE"] = str(tmp_path / "config.json") + runtime = adapter.OpenClawRuntime() + await runtime.start( + { + "config": _config(mock_openclaw), + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + gateway = runtime._process + + # OpenShell's sandbox denies signals to a process group with EPERM. + def deny_group_signals(_pgid: int, _signum: int) -> None: + raise PermissionError(1, "Operation not permitted") + + monkeypatch.setattr(os, "killpg", deny_group_signals) + await runtime.stop() + + assert gateway.returncode is not None + + @pytest.mark.parametrize("phase", ["client", "process", "logs"]) async def test_openclaw_stop_completes_cleanup_before_propagating_cancellation( monkeypatch: pytest.MonkeyPatch, phase: str From 7bb12a1cbb7d43b5c229ee19e9278bf621391254 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 04:47:10 -0700 Subject: [PATCH 02/54] fix: bound OpenClaw's whole start by one deadline On busy hosts, such as CI runners starting three agents at once on four vCPUs, the Gateway took close to 40 s to become ready. Each startup step had its own 30 s timeout, so start failed at random and could also run past NeMo Fabric's 90 s start limit. `startup_timeout_seconds` now bounds all of start, from checking the `openclaw` command to the Gateway becoming ready, with a 60 s default. The descriptor caps it at 75 s so start stays within Fabric's limit. OpenClaw 2026.9.34 also starts a background lookup of catalog.openclaw.ai once the Gateway is ready. The adapter already turns off update checks and telemetry, and now sets `models.catalogRefresh.enabled` to false too. Signed-off-by: Carlos Villela --- adapters/python/openclaw/README.md | 2 +- .../openclaw/openclaw.fabric-adapter.json | 5 ++-- .../nemo_fabric_adapters/openclaw/adapter.py | 19 +++++++++----- docs/integrations/harness/openclaw.mdx | 2 +- .../nemo_fabric_adapter_catalog/catalog.json | 7 ++--- tests/_utils/mock_openclaw.py | 3 +++ tests/adapters/test_openclaw.py | 26 +++++++++++++++++++ 7 files changed, 51 insertions(+), 13 deletions(-) diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index ebdb1f2a3..a8447ddde 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -107,7 +107,7 @@ The following settings are specific to the OpenClaw adapter: | `agent_id` | `default` | OpenClaw agent for NeMo Fabric-originated invocations. | | `channel_config` | None | OpenClaw-native `channels` and `bindings` for a prepared service. Every binding must target `agent_id`. Managed runtimes reject this setting. | | `port_range` | Random available range | Inclusive consumer-allocated range with `start` and `end` fields; it must span at least 111 ports. | -| `startup_timeout_seconds` | `30` | Gateway startup timeout. | +| `startup_timeout_seconds` | `60` | One deadline for all of start, from checking the `openclaw` command to the Gateway becoming ready; at most 75 seconds. | | `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. | diff --git a/adapters/python/openclaw/openclaw.fabric-adapter.json b/adapters/python/openclaw/openclaw.fabric-adapter.json index 862c01b2d..5d00b0240 100644 --- a/adapters/python/openclaw/openclaw.fabric-adapter.json +++ b/adapters/python/openclaw/openclaw.fabric-adapter.json @@ -67,8 +67,9 @@ "startup_timeout_seconds": { "type": "number", "exclusiveMinimum": 0, - "default": 30, - "description": "Maximum time to wait for the OpenClaw Gateway to become ready." + "maximum": 75, + "default": 60, + "description": "One deadline for all of start, from checking the OpenClaw command to the Gateway becoming ready, within NeMo Fabric's 90-second start limit." }, "shutdown_timeout_seconds": { "type": "number", 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 7e082eead..3b5034248 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -38,7 +38,7 @@ from nemo_fabric_adapters.openclaw import _windows_job -DEFAULT_STARTUP_TIMEOUT_SECONDS = 30.0 +DEFAULT_STARTUP_TIMEOUT_SECONDS = 60.0 # Fabric gives the adapter host 10 s to stop, including this wait. DEFAULT_SHUTDOWN_TIMEOUT_SECONDS = 5.0 DEFAULT_CONNECT_TIMEOUT_SECONDS = 10.0 @@ -511,6 +511,7 @@ def _openclaw_config( }, "telemetry": {"enabled": False}, "update": {"checkOnStart": False}, + "models": {"catalogRefresh": {"enabled": False}}, "discovery": {"mdns": {"mode": "off"}}, } agent_id = _agent_id(config.harness.settings if config.harness else {}) @@ -556,7 +557,7 @@ def _openclaw_config( "id": model.api_key_env, } if provider: - result["models"] = {"providers": {model.provider: provider}} + result["models"]["providers"] = {model.provider: provider} channel_config = _channel_config( config.harness.settings if config.harness else {}, agent_id=agent_id ) @@ -1084,8 +1085,14 @@ async def start(self, payload: dict[str, Any]) -> dict[str, Any] | None: startup_timeout = _positive_setting( settings, "startup_timeout_seconds", DEFAULT_STARTUP_TIMEOUT_SECONDS ) + # One deadline covers every startup step, so start ends within it. + startup_deadline = asyncio.get_running_loop().time() + startup_timeout + + def startup_remaining() -> float: + return max(startup_deadline - asyncio.get_running_loop().time(), 0.0) + version_output = await _command_output( - command, "--version", env=child_env, timeout=startup_timeout + command, "--version", env=child_env, timeout=startup_remaining() ) version = _validate_openclaw_version(version_output) from nemo_fabric_adapters.common.provenance import record_version @@ -1139,7 +1146,7 @@ async def start(self, payload: dict[str, Any]) -> dict[str, Any] | None: "validate", "--json", env=child_env, - timeout=startup_timeout, + timeout=startup_remaining(), ) if os.name == "nt": try: @@ -1152,7 +1159,7 @@ async def start(self, payload: dict[str, Any]) -> dict[str, Any] | None: gateway_command = _gateway_command( command, port=port, - prefix=await _parent_death_prefix(timeout=startup_timeout), + prefix=await _parent_death_prefix(timeout=startup_remaining()), ) self._process = await asyncio.create_subprocess_exec( *gateway_command, @@ -1179,7 +1186,7 @@ async def start(self, payload: dict[str, Any]) -> dict[str, Any] | None: ), ] self._install_signal_handlers() - await self._wait_started(port, token, startup_timeout) + await self._wait_started(port, token, startup_remaining()) self._client = httpx.AsyncClient( headers={"authorization": f"Bearer {token}"}, http2=True, diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index e33020a46..05add4484 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -71,7 +71,7 @@ harness = HarnessConfig( adapter_id="nvidia.fabric.openclaw", settings={ "openclaw_command": "/opt/openclaw/bin/openclaw", - "startup_timeout_seconds": 30, + "startup_timeout_seconds": 60, }, ) ``` 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 2d6fc6b90..29b4508fe 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 @@ -2091,9 +2091,10 @@ "type": "number" }, "startup_timeout_seconds": { - "default": 30, - "description": "Maximum time to wait for the OpenClaw Gateway to become ready.", + "default": 60, + "description": "One deadline for all of start, from checking the OpenClaw command to the Gateway becoming ready, within NeMo Fabric's 90-second start limit.", "exclusiveMinimum": 0, + "maximum": 75, "type": "number" } }, @@ -2105,7 +2106,7 @@ "name": "nemo-fabric-adapters-openclaw", "version": "0.7.0" }, - "sha256": "bc95c4dfeee7638a490df68073543d8632b1eb7d9957c4874d72dd8522e99c56", + "sha256": "27af873589f481bd85f2e8e5fd32826879d5d1ba1dbdd1ff0c1e1d1298bb5be0", "source": "adapters/python/openclaw/openclaw.fabric-adapter.json" }, "nvidia.fabric.opencode": { diff --git a/tests/_utils/mock_openclaw.py b/tests/_utils/mock_openclaw.py index 7316d9d45..1c8fdeb29 100755 --- a/tests/_utils/mock_openclaw.py +++ b/tests/_utils/mock_openclaw.py @@ -8,10 +8,13 @@ import os import signal import sys +import time from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer args = sys.argv[1:] +if args[:1] != ["gateway"] and (delay := os.environ.get("FAKE_OPENCLAW_COMMAND_DELAY")): + time.sleep(float(delay)) if args == ["--version"]: print("OpenClaw 2026.9.34 (fabric test)") raise SystemExit(0) diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index f6f344fce..427cd0cd0 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -481,6 +481,8 @@ async def test_openclaw_runtime_generates_config_invokes_and_cleans_up( assert generated["mcp"]["servers"]["local"]["command"] == "python" assert generated["mcp"]["servers"]["remote"]["transport"] == ("streamable-http") assert "auth" not in generated["mcp"]["servers"]["remote"] + # The sandbox would deny OpenClaw's model catalog lookup anyway. + assert generated["models"]["catalogRefresh"] == {"enabled": False} assert not state_root.exists() @@ -1323,6 +1325,30 @@ async def test_openclaw_stop_continues_after_cleanup_failures( assert runtime._temp_dir is None +async def test_openclaw_startup_timeout_bounds_all_of_start( + mock_openclaw: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + # Each command finishes within the timeout, but the two together don't. + monkeypatch.setenv("FAKE_OPENCLAW_COMMAND_DELAY", "0.6") + monkeypatch.setenv("FAKE_OPENCLAW_CAPTURE", str(tmp_path / "config.json")) + config = _config(mock_openclaw) + assert config.harness is not None + config.harness.settings["startup_timeout_seconds"] = 1 + runtime = adapter.OpenClawRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + { + "config": config, + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + + assert caught.value.code == "openclaw_command_timeout" + assert runtime._process is None + + @pytest.mark.skipif(os.name == "nt", reason="Requires POSIX process groups") async def test_openclaw_stop_ends_the_gateway_where_group_signals_are_denied( mock_openclaw: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch From f638e4422e72a475f2a7611c2aacd5dcb1512918 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 04:50:17 -0700 Subject: [PATCH 03/54] feat: serve OpenClaw's Control UI from managed runtimes OpenClaw's Control UI is its browser dashboard and chat. With `harness.settings.interfaces.dashboard.port`, a managed runtime runs the Gateway on that exact loopback port with the Control UI on, accepting the loopback origins for it. After the Gateway starts, the adapter writes the per-start sign-in token to `/.fabric/openclaw/runtimes//interfaces/dashboard.token` with mode 0600, and `stop` removes it. Prepared and attached services reject interfaces. The descriptor's schema validates the settings, including that a dashboard port can't be combined with `port_range`; the adapter doesn't repeat those checks. The atomic owner-only file write that the service connection file already used moves to `common.local_interfaces` so the token file can share it. Left for later: extra browser origins beyond loopback, and checking on Linux that the Gateway itself owns the port. Signed-off-by: Carlos Villela --- .../common/local_interfaces.py | 35 +++++ adapters/python/openclaw/README.md | 1 + .../openclaw/openclaw.fabric-adapter.json | 29 ++++ .../nemo_fabric_adapters/openclaw/adapter.py | 92 ++++++++--- docs/integrations/harness/openclaw.mdx | 37 +++++ .../nemo_fabric_adapter_catalog/catalog.json | 41 ++++- tests/adapters/test_openclaw.py | 148 ++++++++++++++++++ 7 files changed, 359 insertions(+), 24 deletions(-) create mode 100644 adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py diff --git a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py new file mode 100644 index 000000000..a8e30575d --- /dev/null +++ b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py @@ -0,0 +1,35 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Helpers for native interfaces that an adapter serves on loopback.""" + +from __future__ import annotations + +import os +import tempfile +from pathlib import Path + + +def write_private_file(path: Path, payload: str) -> None: + """Atomically write an owner-only file in an owner-only directory.""" + path.parent.mkdir(parents=True, exist_ok=True, mode=0o700) + os.chmod(path.parent, 0o700) + descriptor, temporary_name = tempfile.mkstemp( + dir=path.parent, + prefix=f".{path.name}.", + ) + try: + if hasattr(os, "fchmod"): + os.fchmod(descriptor, 0o600) + with os.fdopen(descriptor, "w", encoding="utf-8") as stream: + descriptor = -1 + stream.write(payload) + os.replace(temporary_name, path) + except BaseException: + if descriptor >= 0: + os.close(descriptor) + try: + os.unlink(temporary_name) + except FileNotFoundError: + pass + raise diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index a8447ddde..b7df6522c 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -107,6 +107,7 @@ The following settings are specific to the OpenClaw adapter: | `agent_id` | `default` | OpenClaw agent for NeMo Fabric-originated invocations. | | `channel_config` | None | OpenClaw-native `channels` and `bindings` for a prepared service. Every binding must target `agent_id`. Managed runtimes reject this setting. | | `port_range` | Random available range | Inclusive consumer-allocated range with `start` and `end` fields; it must span at least 111 ports. | +| `interfaces.dashboard` | None | Serve the Control UI on a managed runtime, with an exact `port` and optional `enabled`; see [Serve the Control UI](../../../docs/integrations/harness/openclaw.mdx#serve-the-control-ui). | | `startup_timeout_seconds` | `60` | One deadline for all of start, from checking the `openclaw` command to the Gateway becoming ready; at most 75 seconds. | | `shutdown_timeout_seconds` | `5` | Graceful shutdown timeout. | | `connect_timeout_seconds` | `10` | Local HTTP connection timeout. | diff --git a/adapters/python/openclaw/openclaw.fabric-adapter.json b/adapters/python/openclaw/openclaw.fabric-adapter.json index 5d00b0240..cfc9419f4 100644 --- a/adapters/python/openclaw/openclaw.fabric-adapter.json +++ b/adapters/python/openclaw/openclaw.fabric-adapter.json @@ -64,6 +64,32 @@ "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." }, + "interfaces": { + "type": "object", + "properties": { + "dashboard": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve the Control UI. A present dashboard is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65425, + "description": "Exact loopback Gateway base port, which serves the Control UI. Start fails if it or port + 2 is in use, and OpenClaw reserves ports through port + 110. Can't be combined with port_range." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "OpenClaw's Control UI. After the Gateway starts, the adapter writes its sign-in token to /.fabric/openclaw/runtimes//interfaces/dashboard.token." + } + }, + "additionalProperties": false, + "description": "Native interfaces served by a managed runtime. Services reject interfaces." + }, "startup_timeout_seconds": { "type": "number", "exclusiveMinimum": 0, @@ -89,6 +115,9 @@ "description": "Timeout between response bytes from the local OpenClaw Gateway. When unset, the invocation timeout bounds the response." } }, + "dependentSchemas": { + "port_range": {"properties": {"interfaces": {"properties": {"dashboard": false}}}} + }, "additionalProperties": false }, "model_schema": { 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 3b5034248..908652262 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -7,6 +7,7 @@ from __future__ import annotations import asyncio +import contextlib import copy import ipaddress import json @@ -33,6 +34,7 @@ from nemo_fabric_adapter_contract import models as contract from nemo_fabric_adapters.common import instructions as common_instructions from nemo_fabric_adapters.common import lifecycle +from nemo_fabric_adapters.common import local_interfaces from nemo_fabric_adapters.common import openai_chat from nemo_fabric_adapters.common import utils as common_utils from nemo_fabric_adapters.openclaw import _windows_job @@ -160,6 +162,31 @@ def _positive_setting(settings: dict[str, Any], name: str, default: float) -> fl return float(value) +def _dashboard_port(settings: dict[str, Any]) -> int | None: + """Return the Control UI's port when the settings enable it. + + The descriptor's schema has already checked the settings. + """ + dashboard = settings.get("interfaces", {}).get("dashboard") + if dashboard is None or not dashboard.get("enabled", True): + return None + return dashboard["port"] + + +def _dashboard_token_path(context: contract.RuntimeContext, base_dir: Path) -> Path: + root = context.artifacts.root + artifact_root = (base_dir / str(root)).resolve() if root else base_dir / "artifacts" + return ( + artifact_root + / ".fabric" + / "openclaw" + / "runtimes" + / context.runtime_id + / "interfaces" + / "dashboard.token" + ) + + def _agent_id(settings: dict[str, Any]) -> str: value = settings.get("agent_id", "default") if not isinstance(value, str) or not value.strip(): @@ -461,6 +488,7 @@ def _openclaw_config( port: int, token_env: str, service_mode: bool = False, + dashboard: bool = False, ) -> dict[str, Any]: model = _selected_model(config) model_id = _model_id(model) @@ -493,7 +521,15 @@ def _openclaw_config( "mode": "token", "token": {"source": "env", "provider": "default", "id": token_env}, }, - "controlUi": {"enabled": False}, + "controlUi": { + "enabled": True, + "allowedOrigins": [ + f"http://127.0.0.1:{port}", + f"http://localhost:{port}", + ], + } + if dashboard + else {"enabled": False}, "http": {"endpoints": {"chatCompletions": {"enabled": True}}}, }, "agents": { @@ -782,8 +818,6 @@ def _write_service_connection( token: str, agent_id: str, ) -> None: - path.parent.mkdir(parents=True, exist_ok=True, mode=0o700) - os.chmod(path.parent, 0o700) payload = ( json.dumps( { @@ -794,25 +828,7 @@ def _write_service_connection( ) + "\n" ) - descriptor, temporary_name = tempfile.mkstemp( - dir=path.parent, - prefix=f".{path.name}.", - ) - try: - if hasattr(os, "fchmod"): - os.fchmod(descriptor, 0o600) - with os.fdopen(descriptor, "w", encoding="utf-8") as stream: - descriptor = -1 - stream.write(payload) - os.replace(temporary_name, path) - except BaseException: - if descriptor >= 0: - os.close(descriptor) - try: - os.unlink(temporary_name) - except FileNotFoundError: - pass - raise + local_interfaces.write_private_file(path, payload) def _read_service_connection(path: Path) -> tuple[str, str, str]: @@ -857,6 +873,7 @@ def __init__(self) -> None: self._temp_dir: tempfile.TemporaryDirectory[str] | None = None self._port: int | None = None self._token: str | None = None + self._dashboard_token_path: Path | None = None self._gateway_url: str | None = None self._agent_id = "default" self._shutdown_timeout = DEFAULT_SHUTDOWN_TIMEOUT_SECONDS @@ -1050,6 +1067,13 @@ async def start(self, payload: dict[str, Any]) -> dict[str, Any] | None: "openclaw_invalid_service_context", "OpenClaw service context must be an object", ) + if service is not None and "interfaces" in settings: + raise lifecycle.LifecycleError( + "openclaw_interfaces_require_managed_runtime", + "OpenClaw interfaces require a managed runtime", + metadata={"field": "harness.settings.interfaces"}, + ) + dashboard_port = _dashboard_port(settings) self._service_host = service is not None and service.get("operation") in { "prepare", "attach", @@ -1106,7 +1130,20 @@ def startup_remaining() -> float: kind="component", ) - port = _select_port(settings) + if dashboard_port is None: + port = _select_port(settings) + else: + port = dashboard_port + for candidate in (port, port + 2): + if not _port_available(candidate): + raise lifecycle.LifecycleError( + "openclaw_interface_port_unavailable", + f"OpenClaw dashboard port {candidate} is already in use", + metadata={ + "field": "harness.settings.interfaces.dashboard.port", + "port": candidate, + }, + ) # Generate a one-time use token for the OpenClaw gateway token = secrets.token_urlsafe(48) @@ -1123,6 +1160,7 @@ def startup_remaining() -> float: port=port, token_env=token_env, service_mode=service is not None and service.get("operation") == "prepare", + dashboard=dashboard_port is not None, ) config_path.write_text(json.dumps(generated, indent=2) + "\n", encoding="utf-8") config_path.chmod(0o600) @@ -1187,6 +1225,10 @@ def startup_remaining() -> float: ] self._install_signal_handlers() await self._wait_started(port, token, startup_remaining()) + if dashboard_port is not None: + token_path = _dashboard_token_path(context, base_dir) + local_interfaces.write_private_file(token_path, token) + self._dashboard_token_path = token_path self._client = httpx.AsyncClient( headers={"authorization": f"Bearer {token}"}, http2=True, @@ -1708,6 +1750,10 @@ async def invoke( async def stop(self) -> None: cancellation: asyncio.CancelledError | None = None self._stopping = True + token_path, self._dashboard_token_path = self._dashboard_token_path, None + if token_path is not None: + with contextlib.suppress(OSError): + token_path.unlink(missing_ok=True) try: self._restore_signal_handlers() except Exception: diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index 05add4484..ce21a3f11 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -115,6 +115,43 @@ By default, the adapter chooses an available local port range. Set `port_range` to an inclusive consumer-allocated range with `start` and `end` fields. The range must span at least 111 ports. 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`. 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 or service when using OpenClaw browser features. +## Serve the Control UI + +OpenClaw's Control UI is its browser dashboard and chat. A managed runtime +serves it when `harness.settings.interfaces.dashboard` is present: + +```python +from nemo_fabric import HarnessConfig + +harness = HarnessConfig( + adapter_id="nvidia.fabric.openclaw", + settings={"interfaces": {"dashboard": {"port": 18789}}}, +) +``` + +- The Gateway listens on `127.0.0.1` at the dashboard `port`, which serves the + Control UI. `start` fails with `openclaw_interface_port_unavailable` if + `port` or `port + 2` is in use. OpenClaw also uses `port + 10` for its + browser relay and allocates browser CDP ports from `port + 11` through + `port + 110`, so reserve the whole range from `port` through `port + 110`. + `port` can't be combined with `port_range`; set `enabled` to `false` to keep + a configured dashboard off. +- After the Gateway starts, the adapter writes the sign-in token, generated at + each start, to + `/.fabric/openclaw/runtimes//interfaces/dashboard.token` + with mode `0600`. `stop` removes it; if the adapter host is killed, the file + can remain. +- Open `http://127.0.0.1:/#token=` through a forward to that + port to sign in. The Control UI removes the token from the address bar. + OpenClaw 2026.9.34 accepts any loopback origin, such as a forward to a + different local port; the token is still required. +- Processes that run as the runtime's user, including the agent's own tools, + can read the token and reach the port. +- The adapter regenerates OpenClaw's configuration at each start and marks it + read-only, so changes made through the Control UI don't survive a restart. +- Prepared and attached services reject `interfaces` with + `openclaw_interfaces_require_managed_runtime`. + ## Use a Shared Service Call `prepare_service()` to map the normalized `FabricConfig` to 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 29b4508fe..ba0937b1e 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 @@ -2001,6 +2001,17 @@ "settings_schema": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, + "dependentSchemas": { + "port_range": { + "properties": { + "interfaces": { + "properties": { + "dashboard": false + } + } + } + } + }, "properties": { "agent_id": { "default": "default", @@ -2053,6 +2064,34 @@ "exclusiveMinimum": 0, "type": "number" }, + "interfaces": { + "additionalProperties": false, + "description": "Native interfaces served by a managed runtime. Services reject interfaces.", + "properties": { + "dashboard": { + "additionalProperties": false, + "description": "OpenClaw's Control UI. After the Gateway starts, the adapter writes its sign-in token to /.fabric/openclaw/runtimes//interfaces/dashboard.token.", + "properties": { + "enabled": { + "default": true, + "description": "Serve the Control UI. A present dashboard is on unless this is false.", + "type": "boolean" + }, + "port": { + "description": "Exact loopback Gateway base port, which serves the Control UI. Start fails if it or port + 2 is in use, and OpenClaw reserves ports through port + 110. Can't be combined with port_range.", + "maximum": 65425, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "port" + ], + "type": "object" + } + }, + "type": "object" + }, "openclaw_command": { "description": "OpenClaw executable name or path. Relative paths containing a directory are resolved from the NeMo Fabric base directory.", "minLength": 1, @@ -2106,7 +2145,7 @@ "name": "nemo-fabric-adapters-openclaw", "version": "0.7.0" }, - "sha256": "27af873589f481bd85f2e8e5fd32826879d5d1ba1dbdd1ff0c1e1d1298bb5be0", + "sha256": "5a90fc71ffd726f09d952162d0fa49e5fcc153a2398c37467815ffafd1ecfd93", "source": "adapters/python/openclaw/openclaw.fabric-adapter.json" }, "nvidia.fabric.opencode": { diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index 427cd0cd0..1a48e6ce2 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -11,6 +11,7 @@ import os import shutil import signal +import socket import subprocess import sys import time @@ -98,11 +99,30 @@ def _config(command: Path, *, with_skills: bool = False) -> AgentConfig: ) +def _dashboard_config(command: Path, dashboard: dict[str, object]) -> AgentConfig: + config = _config(command) + assert config.harness is not None + config.harness.settings["interfaces"] = {"dashboard": dashboard} + return config + + +def _dashboard_token(base_dir: Path) -> Path: + return ( + base_dir + / "artifacts/.fabric/openclaw/runtimes/openclaw-runtime/interfaces/dashboard.token" + ) + + @pytest.fixture(name="mock_openclaw") def mock_openclaw_fixture(repo_root: Path) -> Path: return repo_root / "tests/_utils/mock_openclaw.py" +@pytest.fixture(name="dashboard_port") +def dashboard_port_fixture() -> int: + return adapter._select_port({}) + + def test_openclaw_port_availability_checks_one_port( monkeypatch: pytest.MonkeyPatch, ): @@ -183,6 +203,46 @@ def test_openclaw_rejects_invalid_port_range(settings: dict[str, object]): assert caught.value.metadata == {"field": "harness.settings.port_range"} +@pytest.mark.parametrize( + "settings", + [ + pytest.param({"interfaces": {"terminal": {}}}, id="unsupported-interface"), + pytest.param( + {"interfaces": {"dashboard": {"port": 20_000, "token": "x"}}}, + id="unknown-field", + ), + pytest.param({"interfaces": {"dashboard": {}}}, id="missing-port"), + pytest.param({"interfaces": {"dashboard": {"port": 65_426}}}, id="port-too-high"), + pytest.param( + { + "interfaces": {"dashboard": {"port": 20_000}}, + "port_range": {"start": 20_000, "end": 20_200}, + }, + id="port-range-with-dashboard", + ), + pytest.param({"startup_timeout_seconds": 76}, id="startup-timeout-too-long"), + ], +) +def test_openclaw_plan_rejects_invalid_settings( + tmp_path: Path, settings: dict[str, object] +): + config = FabricConfig.from_mapping( + { + "metadata": {"name": "openclaw-interfaces"}, + "harness": { + "adapter_id": "nvidia.fabric.openclaw", + "resolution": "preinstalled", + "settings": settings, + }, + "models": {"default": {"provider": "test", "model": "fabric-echo"}}, + "environment": {"provider": "local", "workspace": "."}, + } + ) + + with pytest.raises(FabricConfigError): + Fabric().plan(config, base_dir=tmp_path) + + @pytest.mark.parametrize("raw", ["2026.9.34 extra", "2026.9.34\nuntrusted suffix"]) async def test_gateway_records_the_same_version_it_validates(monkeypatch, raw): from nemo_fabric_adapters.common import provenance @@ -481,6 +541,8 @@ async def test_openclaw_runtime_generates_config_invokes_and_cleans_up( assert generated["mcp"]["servers"]["local"]["command"] == "python" assert generated["mcp"]["servers"]["remote"]["transport"] == ("streamable-http") assert "auth" not in generated["mcp"]["servers"]["remote"] + assert generated["gateway"]["controlUi"] == {"enabled": False} + assert not (tmp_path / "artifacts").exists() # The sandbox would deny OpenClaw's model catalog lookup anyway. assert generated["models"]["catalogRefresh"] == {"enabled": False} assert not state_root.exists() @@ -1325,6 +1387,92 @@ async def test_openclaw_stop_continues_after_cleanup_failures( assert runtime._temp_dir is None +@pytest.mark.skipif(sys.platform == "win32", reason="Requires POSIX file permissions") +async def test_openclaw_dashboard_serves_control_ui_with_a_token_file( + mock_openclaw: Path, tmp_path: Path, dashboard_port: int +): + capture = tmp_path / "config.json" + os.environ["FAKE_OPENCLAW_CAPTURE"] = str(capture) + token_path = _dashboard_token(tmp_path) + runtime = adapter.OpenClawRuntime() + + await runtime.start( + { + "config": _dashboard_config(mock_openclaw, {"port": dashboard_port}), + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + try: + gateway_token = runtime._token + stored_token = token_path.read_text(encoding="utf-8") + token_mode = token_path.stat().st_mode & 0o777 + directory_mode = token_path.parent.stat().st_mode & 0o777 + finally: + await runtime.stop() + + generated = json.loads(capture.read_text(encoding="utf-8")) + assert generated["gateway"]["port"] == dashboard_port + assert generated["gateway"]["controlUi"] == { + "enabled": True, + "allowedOrigins": [ + f"http://127.0.0.1:{dashboard_port}", + f"http://localhost:{dashboard_port}", + ], + } + assert stored_token == gateway_token + assert token_mode == 0o600 + assert directory_mode == 0o700 + assert not token_path.exists() + + +@pytest.mark.parametrize("offset", [0, 2]) +async def test_openclaw_dashboard_port_in_use_fails_start( + mock_openclaw: Path, tmp_path: Path, dashboard_port: int, offset: int +): + runtime = adapter.OpenClawRuntime() + + with socket.create_server(("127.0.0.1", dashboard_port + offset)): + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + { + "config": _dashboard_config( + mock_openclaw, {"port": dashboard_port} + ), + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + + assert caught.value.code == "openclaw_interface_port_unavailable" + assert caught.value.metadata == { + "field": "harness.settings.interfaces.dashboard.port", + "port": dashboard_port + offset, + } + assert runtime._process is None + assert not (tmp_path / "artifacts").exists() + + +@pytest.mark.parametrize("operation", ["prepare", "attach", "connect"]) +async def test_openclaw_services_reject_interfaces( + mock_openclaw: Path, tmp_path: Path, operation: str +): + runtime = adapter.OpenClawRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + { + "config": _dashboard_config(mock_openclaw, {"port": 20_000}), + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + "service": {"operation": operation}, + } + ) + + assert caught.value.code == "openclaw_interfaces_require_managed_runtime" + assert runtime._process is None + + async def test_openclaw_startup_timeout_bounds_all_of_start( mock_openclaw: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch ): From 7ed10cea02bbf1d8504b3ea56cffb4268094157c Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 04:56:09 -0700 Subject: [PATCH 04/54] feat: serve Hermes's API server and dashboard from a runtime With `harness.settings.interfaces.api` or `.dashboard`, a runtime starts Hermes's gateway, with only its API server, or its dashboard, as child processes on exact loopback ports, alongside the embedded agent and on the same Hermes home. Start waits for each child's health check within `startup_timeout_seconds` (60 s by default, at most 75 s). Then the adapter writes the API server's per-start bearer token to `/.fabric/hermes/runtimes//interfaces/api.token` with mode 0600. `stop` removes the token and stops each child's process group, signalling the child itself where group signals are denied. With interfaces on, `config.yaml` names the model's endpoint as Hermes's `custom` provider, with the key as a reference to `api_key_env`, so the children call the configured endpoint. The gateway drains in-flight runs for 3 s so it exits within the stop grace. The API server needs `aiohttp`, so `install-hermes-agent` installs it from Hermes's `messaging` extra without the platform SDKs. The descriptor's schema validates the settings; the adapter doesn't repeat those checks. OpenClaw's loopback port check moves to `common.local_interfaces` so both adapters use it. The two descriptor copies and the catalog are mechanical. Left for later: checking on Linux that each child itself owns its port. Signed-off-by: Carlos Villela --- .../common/local_interfaces.py | 14 + adapters/python/hermes/README.md | 2 + .../python/hermes/hermes.fabric-adapter.json | 52 ++++ .../nemo_fabric_adapters/hermes/adapter.py | 24 ++ .../hermes/configuration.py | 36 +++ .../nemo_fabric_adapters/hermes/interfaces.py | 225 ++++++++++++++ .../nemo_fabric_adapters/openclaw/adapter.py | 16 +- .../hermes/hermes.fabric-adapter.json | 52 ++++ docs/integrations/harness/hermes.mdx | 47 +++ .../hermes/hermes.fabric-adapter.json | 52 ++++ justfile | 8 +- .../nemo_fabric_adapter_catalog/catalog.json | 58 +++- tests/_utils/mock_api_server.py | 16 +- tests/adapters/test_hermes_interfaces.py | 288 ++++++++++++++++++ 14 files changed, 873 insertions(+), 17 deletions(-) create mode 100644 adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py create mode 100644 tests/adapters/test_hermes_interfaces.py diff --git a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py index a8e30575d..70eaf5e3a 100644 --- a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py +++ b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py @@ -6,10 +6,24 @@ from __future__ import annotations import os +import socket import tempfile from pathlib import Path +def port_available(port: int) -> bool: + """Return whether one loopback TCP port is available.""" + sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) + try: + sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + sock.bind(("127.0.0.1", port)) + return True + except (OSError, OverflowError): + return False + finally: + sock.close() + + def write_private_file(path: Path, payload: str) -> None: """Atomically write an owner-only file in an owner-only directory.""" path.parent.mkdir(parents=True, exist_ok=True, mode=0o700) diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 2ee52da7a..828da6982 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -86,6 +86,8 @@ The descriptor validates the following `harness.settings` fields: | `save_trajectories` | boolean | `false` | Enables Hermes-native JSONL conversation trajectory saving. This is separate from normalized NeMo Fabric telemetry. | | `max_tokens` | positive integer | `512` | Limits the number of tokens in each Hermes model response. | | `terminal_timeout` | positive number | `60` | Limits a Hermes terminal operation in seconds. | +| `interfaces.api`, `interfaces.dashboard` | object | None | Serve Hermes's API server or dashboard from a runtime, each with an exact `port` and optional `enabled`; see [Serve the API Server and Dashboard](../../../docs/integrations/harness/hermes.mdx#serve-the-api-server-and-dashboard). | +| `startup_timeout_seconds` | number, at most 75 | `60` | Time for every enabled interface to pass its health check. | For example: diff --git a/adapters/python/hermes/hermes.fabric-adapter.json b/adapters/python/hermes/hermes.fabric-adapter.json index 84af8a6e8..bee24bf18 100644 --- a/adapters/python/hermes/hermes.fabric-adapter.json +++ b/adapters/python/hermes/hermes.fabric-adapter.json @@ -55,6 +55,58 @@ "exclusiveMinimum": 0, "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation." + }, + "interfaces": { + "type": "object", + "properties": { + "api": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the API server. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + }, + "dashboard": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the dashboard. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST." + } + }, + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes." + }, + "startup_timeout_seconds": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 75, + "default": 60, + "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "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 c43a5088d..bc12cf9d9 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -32,6 +32,7 @@ from nemo_fabric_adapters.common import instructions as common_instructions from nemo_fabric_adapters.common import lifecycle from nemo_fabric_adapters.hermes import configuration +from nemo_fabric_adapters.hermes import interfaces from nemo_fabric_adapters.hermes import telemetry # Default agent loop budget when FabricConfig.runtime.max_turns is unset. @@ -70,6 +71,7 @@ def __init__(self) -> None: self._relay_plugin_config: dict[str, Any] | None = None self._relay_plugin_config_path: Path | None = None self._active_invoke_task: asyncio.Task[tuple[dict[str, Any], str]] | None = None + self._interfaces = interfaces.InterfaceChildren() async def start(self, payload: dict[str, Any]) -> None: if self._started: @@ -102,6 +104,7 @@ async def start(self, payload: dict[str, Any]) -> None: telemetry.validate_hermes_relay_compatibility() self._agent_config = agent_config self._settings = configuration._settings(agent_config) + interface_ports = interfaces.interface_ports(self._settings) model_config = configuration._selected_model(agent_config) self._model_config = model_config self._runtime_id = runtime_context.runtime_id @@ -145,6 +148,7 @@ async def start(self, payload: dict[str, Any]) -> None: # Workspace belongs to the per-runtime context, not AgentConfig. workspace=str(runtime_context.environment.workspace or "."), relay_enabled=relay_enabled, + interfaces=interface_ports, ) api_key_env = configuration._api_key_env(model_config) api_key = os.environ.get(api_key_env) @@ -222,6 +226,22 @@ async def start(self, payload: dict[str, Any]) -> None: session_db=self._session_db, ) ) + if interface_ports: + environment = dict(os.environ) + provider_key_env = configuration.PROVIDER_DEFAULT_API_KEY_ENV.get( + str(model_config.provider or "").lower() + ) + if provider_key_env: + # Hermes's own processes read a provider's key from its + # default variable, not from api_key_env. + environment[provider_key_env] = api_key + await self._interfaces.start( + interface_ports, + hermes_home=self._hermes_home, + token_path=self._hermes_home / "interfaces" / "api.token", + timeout=interfaces.startup_timeout(self._settings), + environment=environment, + ) self._agent_config = agent_config self._started = True except BaseException: @@ -596,6 +616,10 @@ async def stop(self) -> None: self._stopping = True active_invoke_task = self._active_invoke_task errors: list[BaseException] = [] + try: + await self._interfaces.stop() + except BaseException as error: + errors.append(error) if active_invoke_task is not None: try: await asyncio.shield(active_invoke_task) 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 39a0244c8..3ab44e97d 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py @@ -6,6 +6,7 @@ from __future__ import annotations import os +from collections.abc import Collection from pathlib import Path from typing import Any @@ -15,6 +16,7 @@ from nemo_fabric_adapter_contract.models import McpOAuth2Config from nemo_fabric_adapter_contract.models import McpServiceAccountConfig import nemo_fabric_adapters.common.utils as common_utils +from nemo_fabric_adapters.hermes.interfaces import GATEWAY_DRAIN_TIMEOUT_SECONDS PROVIDER_DEFAULT_API_KEY_ENV = { @@ -74,11 +76,37 @@ def disabled_toolsets(config: AgentConfig) -> list[str]: return config.tools.blocked if config.tools is not None else [] +def _interface_model(model_config: AgentModelConfig) -> dict[str, Any]: + """Return the model section Hermes's own processes read from config.yaml. + + Fabric's embedded agent receives the endpoint and key as arguments; the + gateway and dashboard read them from config.yaml, where Hermes's ``openai`` + provider ignores ``base_url``. The key stays in the environment. + """ + + provider = str(model_config.provider or "").lower() + if model_config.base_url and provider in {"openai", "custom"}: + return { + "provider": "custom", + "default": model_config.model, + "base_url": model_config.base_url, + "api_key": f"${{{_api_key_env(model_config)}}}", + } + return common_utils.without_none( + { + "provider": model_config.provider, + "default": model_config.model, + "base_url": model_config.base_url, + } + ) + + def build_hermes_config( agent_config: AgentConfig, *, workspace: str, relay_enabled: bool = False, + interfaces: Collection[str] = (), ) -> dict[str, Any]: settings = _settings(agent_config) model_config = _selected_model(agent_config) @@ -110,6 +138,12 @@ def build_hermes_config( ), } + if interfaces: + config["model"] = _interface_model(model_config) + if "api" in interfaces: + 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}} @@ -145,12 +179,14 @@ def write_hermes_config( *, workspace: str, relay_enabled: bool = False, + interfaces: Collection[str] = (), ) -> tuple[Path, dict[str, Any]]: hermes_home.mkdir(parents=True, exist_ok=True) config = build_hermes_config( agent_config, workspace=workspace, relay_enabled=relay_enabled, + interfaces=interfaces, ) config_path = hermes_home / "config.yaml" config_path.write_text(common_utils.dump_yaml(config), encoding="utf-8") diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py new file mode 100644 index 000000000..923c21435 --- /dev/null +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py @@ -0,0 +1,225 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Serve Hermes's API server and dashboard as children of a managed runtime.""" + +from __future__ import annotations + +import asyncio +import http.client +import os +import secrets +import signal +import sys +from dataclasses import dataclass +from pathlib import Path +from typing import Any + +from nemo_fabric_adapters.common import lifecycle +from nemo_fabric_adapters.common import local_interfaces +from nemo_fabric_adapters.common import utils as common_utils + +HEALTH_PATHS = {"api": "/health", "dashboard": "/api/status"} +DEFAULT_STARTUP_TIMEOUT_SECONDS = 60.0 +# Fabric gives the adapter host 10 s to stop, including this wait. +STOP_GRACE_SECONDS = 5.0 +# Hermes's gateway waits this long for in-flight API runs and cron jobs on +# SIGTERM, so it exits within STOP_GRACE_SECONDS. +GATEWAY_DRAIN_TIMEOUT_SECONDS = 3 + + +def interface_ports(settings: dict[str, Any]) -> dict[str, int]: + """Return the enabled interfaces' loopback ports, keyed by interface name. + + The descriptor's schema has already checked the settings. + """ + return { + name: interface["port"] + for name, interface in settings.get("interfaces", {}).items() + if interface.get("enabled", True) + } + + +def startup_timeout(settings: dict[str, Any]) -> float: + """Return the deadline for every enabled interface to pass its health check.""" + return float( + settings.get("startup_timeout_seconds", DEFAULT_STARTUP_TIMEOUT_SECONDS) + ) + + +@dataclass +class _Child: + name: str + port: int + process: asyncio.subprocess.Process + + +class InterfaceChildren: + """Start, track and stop one runtime's interface processes.""" + + def __init__(self) -> None: + self._children: list[_Child] = [] + self._token_path: Path | None = None + + async def start( + self, + ports: dict[str, int], + *, + hermes_home: Path, + token_path: Path, + timeout: float, + environment: dict[str, str], + ) -> None: + """Start the enabled interfaces and write the API token once all pass health.""" + for name, port in ports.items(): + if not local_interfaces.port_available(port): + raise lifecycle.LifecycleError( + "hermes_interface_port_unavailable", + f"Hermes {name} port {port} is already in use", + metadata={ + "field": f"harness.settings.interfaces.{name}.port", + "port": port, + }, + ) + web_dist = _web_dist() if "dashboard" in ports else None + token = secrets.token_urlsafe(32) + log_dir = hermes_home / "logs" + log_dir.mkdir(parents=True, exist_ok=True) + deadline = asyncio.get_running_loop().time() + timeout + try: + for name, port in ports.items(): + arguments, child_environment = _child_command( + name, port, token=token, web_dist=web_dist, environment=environment + ) + with open(log_dir / f"fabric-interface-{name}.log", "ab") as log: + process = await asyncio.create_subprocess_exec( + sys.executable, + "-m", + "hermes_cli.main", + *arguments, + env=child_environment, + stdin=asyncio.subprocess.DEVNULL, + stdout=log, + stderr=asyncio.subprocess.STDOUT, + start_new_session=True, + ) + self._children.append(_Child(name, port, process)) + for child in self._children: + await _wait_healthy(child, deadline) + if "api" in ports: + local_interfaces.write_private_file(token_path, token) + self._token_path = token_path + except BaseException: + await self.stop() + raise + + async def stop(self) -> None: + """Remove the API token, then stop every interface process group.""" + token_path, self._token_path = self._token_path, None + if token_path is not None: + token_path.unlink(missing_ok=True) + children, self._children = self._children, [] + running = [child for child in children if child.process.returncode is None] + for child in running: + common_utils.signal_process_group(child.process.pid, signal.SIGTERM) + if running: + waits = [asyncio.ensure_future(child.process.wait()) for child in running] + _, pending = await asyncio.wait(waits, timeout=STOP_GRACE_SECONDS) + for child in running: + common_utils.signal_process_group(child.process.pid, signal.SIGKILL) + if pending: + await asyncio.wait(pending) + + +def _web_dist() -> Path: + configured = os.environ.get("HERMES_WEB_DIST") + if configured: + dist = Path(configured) + else: + import hermes_cli + + dist = Path(hermes_cli.__file__).parent / "web_dist" + if not (dist / "index.html").is_file(): + raise lifecycle.LifecycleError( + "hermes_dashboard_frontend_missing", + f"Hermes's dashboard needs a built frontend at {dist}; set " + "HERMES_WEB_DIST to one", + metadata={"field": "harness.settings.interfaces.dashboard"}, + ) + return dist + + +async def _wait_healthy(child: _Child, deadline: float) -> None: + loop = asyncio.get_running_loop() + while loop.time() < deadline: + if child.process.returncode is not None: + raise lifecycle.LifecycleError( + "hermes_interface_start_failed", + f"Hermes {child.name} exited before passing its health check", + metadata={"interface": child.name}, + ) + if await _http_status(child.port, HEALTH_PATHS[child.name]) == 200: + return + await asyncio.sleep(0.1) + raise lifecycle.LifecycleError( + "hermes_interface_start_timeout", + f"Hermes {child.name} didn't pass its health check before the startup timeout", + retryable=True, + metadata={"interface": child.name}, + ) + + +def _child_command( + name: str, + port: int, + *, + token: str, + web_dist: Path | None, + environment: dict[str, str], +) -> tuple[list[str], dict[str, str]]: + """Return one interface's Hermes CLI arguments and environment.""" + child_environment = { + key: value + for key, value in environment.items() + if not key.startswith("API_SERVER_") + } + if name == "api": + child_environment.update( + API_SERVER_KEY=token, + API_SERVER_HOST="127.0.0.1", + API_SERVER_PORT=str(port), + ) + return ["gateway", "run"], child_environment + child_environment["HERMES_WEB_DIST"] = str(web_dist) + # --isolated keeps one dashboard per runtime instead of attaching to another + # runtime's dashboard on this host. + return [ + "dashboard", + "--host", + "127.0.0.1", + "--port", + str(port), + "--no-open", + "--skip-build", + "--isolated", + ], child_environment + + +async def _http_status(port: int, path: str) -> int | None: + """Return a loopback GET's status, or None when nothing answers. + + ``http.client`` neither follows redirects nor uses a proxy, which can't + reach this process's loopback anyway. + """ + + def get() -> int | None: + connection = http.client.HTTPConnection("127.0.0.1", port, timeout=1.0) + try: + connection.request("GET", path) + return connection.getresponse().status + except (OSError, http.client.HTTPException): + return None + finally: + connection.close() + + return await asyncio.to_thread(get) 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 908652262..8691260e7 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -35,6 +35,9 @@ from nemo_fabric_adapters.common import instructions as common_instructions from nemo_fabric_adapters.common import lifecycle from nemo_fabric_adapters.common import local_interfaces +from nemo_fabric_adapters.common.local_interfaces import ( + port_available as _port_available, +) from nemo_fabric_adapters.common import openai_chat from nemo_fabric_adapters.common import utils as common_utils from nemo_fabric_adapters.openclaw import _windows_job @@ -360,19 +363,6 @@ def _resolve_command(settings: dict[str, Any], base_dir: Path) -> Path: return candidate.resolve() -def _port_available(port: int) -> bool: - """Return whether one loopback TCP port is available.""" - sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) - try: - sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) - sock.bind(("127.0.0.1", port)) - return True - except (OSError, OverflowError): - return False - finally: - sock.close() - - def _select_port(settings: dict[str, Any]) -> int: """Select a base port with available Gateway and browser control ports. 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 84af8a6e8..bee24bf18 100644 --- a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json +++ b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json @@ -55,6 +55,58 @@ "exclusiveMinimum": 0, "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation." + }, + "interfaces": { + "type": "object", + "properties": { + "api": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the API server. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + }, + "dashboard": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the dashboard. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST." + } + }, + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes." + }, + "startup_timeout_seconds": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 75, + "default": 60, + "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "required": [], diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index e0eef5556..ab3e2506e 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -108,6 +108,53 @@ attempt is blocked, skipped, fails, or aborts without a rewrite. For the complete configuration and lifecycle reference, refer to the [Hermes Agent adapter guide](https://github.com/NVIDIA/NeMo-Fabric/tree/main/adapters/python/hermes). +## Serve the API Server and Dashboard + +A runtime can serve Hermes's API server and dashboard as child processes +alongside its embedded agent: + +```python +from nemo_fabric import HarnessConfig + +harness = HarnessConfig( + adapter_id="nvidia.fabric.hermes", + settings={"interfaces": {"api": {"port": 8642}, "dashboard": {"port": 9119}}}, +) +``` + +- The adapter starts `python -m hermes_cli.main gateway run`, with only the API + server enabled, and `python -m hermes_cli.main dashboard --skip-build + --isolated`, on the adapter's interpreter and the runtime's Hermes home, each + on `127.0.0.1` at its port. Each must pass its health check, `GET /health` or + `GET /api/status`, within `startup_timeout_seconds` (60 by default, at most + 75). `start` fails if a port is in use or a child exits first; a failed + start stops the children it started and leaves no token. Set `enabled` to + `false` to keep a configured interface off. +- Once every enabled interface passes, the adapter writes the API server's + bearer token, generated at each start, to + `/.fabric/hermes/runtimes//interfaces/api.token` + with mode `0600`. Send it as `Authorization: Bearer `. Only the + gateway child receives it. Processes that run as the runtime's user, + including the agent's own tools, can read it. +- The dashboard has no sign-in. On loopback, Hermes embeds its session token in + the page, so anyone who can reach the port can use the dashboard and its + browser chat, which runs the agent. The adapter turns off none of its pages. + Browser chat needs Hermes's built terminal UI bundle. +- With interfaces enabled, the adapter writes an `openai` or `custom` model + that has a `base_url` to `config.yaml` as Hermes's `custom` provider, with + its key as a reference to `api_key_env`, so the API server and browser chat + use the configured endpoint and key. +- `stop` removes the token, sends SIGTERM to each child's process group, and + SIGKILL to what remains after 5 seconds. The gateway drains in-flight API + runs and cron jobs for 3 seconds. After start, a child that exits doesn't fail + the runtime check, and NeMo Fabric doesn't restart it. +- The embedded agent, the gateway, the dashboard and browser chat share the + Hermes home, and Hermes coordinates their writes. The dashboard's gateway + actions, such as restart, start Hermes processes outside the runtime. +- The API server needs `aiohttp`, from Hermes's `messaging` extra. The dashboard + needs a built frontend at `HERMES_WEB_DIST` or Hermes's own + `hermes_cli/web_dist`; the adapter never builds it. + ## Runtime Health `Fabric.check()` supports `live`, `active`, and `ready`. The adapter checks native agent and database ownership, the initialized invocation interface, and a fresh `get_activity_summary()` diagnostic response. diff --git a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json index 84af8a6e8..bee24bf18 100644 --- a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json +++ b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json @@ -55,6 +55,58 @@ "exclusiveMinimum": 0, "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation." + }, + "interfaces": { + "type": "object", + "properties": { + "api": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the API server. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + }, + "dashboard": { + "type": "object", + "properties": { + "enabled": { + "type": "boolean", + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false." + }, + "port": { + "type": "integer", + "minimum": 1, + "maximum": 65535, + "description": "Exact loopback port for the dashboard. Start fails if it is in use." + } + }, + "required": ["port"], + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST." + } + }, + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes." + }, + "startup_timeout_seconds": { + "type": "number", + "exclusiveMinimum": 0, + "maximum": 75, + "default": 60, + "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "required": [], diff --git a/justfile b/justfile index c68730115..e6643c46c 100644 --- a/justfile +++ b/justfile @@ -439,8 +439,12 @@ install-hermes-agent: uv venv --python 3.14 --clear "$REPO_ROOT/.venv-hermes" fi # Use the release lockfile, including upstream's security dependency overrides. + # From the messaging extra, install only aiohttp, which Hermes's API server needs. UV_PROJECT_ENVIRONMENT="$REPO_ROOT/.venv-hermes" uv sync \ - --project "$hermes_checkout" --frozen --no-default-groups --extra mcp \ + --project "$hermes_checkout" --frozen --no-default-groups --extra mcp --extra messaging \ + --no-install-package discord-py --no-install-package python-telegram-bot \ + --no-install-package slack-bolt --no-install-package slack-sdk \ + --no-install-package qrcode --no-install-package brotlicffi \ --config-settings-package hermes-agent:editable_mode=compat uv pip install --python "$REPO_ROOT/.venv-hermes/bin/python" \ --editable "$REPO_ROOT/sdk/python/nemo-fabric-evidence" \ @@ -453,7 +457,7 @@ install-hermes-agent: pytest pytest-asyncio pyyaml test-hermes: install-hermes-agent - .venv-hermes/bin/python -m pytest tests/adapters/test_hermes_adapter.py tests/adapters/test_hermes_config_builder.py tests/adapters/test_hermes_streaming.py tests/adapters/test_hermes_health.py tests/e2e/test_hermes_e2e.py tests/e2e/test_hermes_checks.py -q + .venv-hermes/bin/python -m pytest tests/adapters/test_hermes_adapter.py tests/adapters/test_hermes_config_builder.py tests/adapters/test_hermes_interfaces.py tests/adapters/test_hermes_streaming.py tests/adapters/test_hermes_health.py tests/e2e/test_hermes_e2e.py tests/e2e/test_hermes_checks.py -q # Build the TypeScript contract and adapter packages using their locked dependencies. build-typescript: install-typescript 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 ba0937b1e..7d07e98d8 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 @@ -843,6 +843,55 @@ "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { + "interfaces": { + "additionalProperties": false, + "description": "Native interfaces served by the runtime as child processes.", + "properties": { + "api": { + "additionalProperties": false, + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token.", + "properties": { + "enabled": { + "default": true, + "description": "Serve Hermes's OpenAI-compatible API server. A present api interface is on unless this is false.", + "type": "boolean" + }, + "port": { + "description": "Exact loopback port for the API server. Start fails if it is in use.", + "maximum": 65535, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "port" + ], + "type": "object" + }, + "dashboard": { + "additionalProperties": false, + "description": "Hermes's dashboard, which has no sign-in when bound to loopback. It needs a built frontend at HERMES_WEB_DIST.", + "properties": { + "enabled": { + "default": true, + "description": "Serve Hermes's dashboard and browser chat. A present dashboard is on unless this is false.", + "type": "boolean" + }, + "port": { + "description": "Exact loopback port for the dashboard. Start fails if it is in use.", + "maximum": 65535, + "minimum": 1, + "type": "integer" + } + }, + "required": [ + "port" + ], + "type": "object" + } + }, + "type": "object" + }, "max_tokens": { "default": 512, "description": "Maximum number of tokens in each Hermes model response.", @@ -890,6 +939,13 @@ "description": "Whether Hermes saves its native conversation trajectories as JSONL.", "type": "boolean" }, + "startup_timeout_seconds": { + "default": 60, + "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit.", + "exclusiveMinimum": 0, + "maximum": 75, + "type": "number" + }, "terminal_timeout": { "default": 60, "description": "Maximum number of seconds for a Hermes terminal operation.", @@ -917,7 +973,7 @@ "name": "nemo-fabric-adapters-hermes", "version": "0.7.0" }, - "sha256": "6539b80cd3dbc76f2db58640bb957dcbe5f9e45421a2d7f9a45785325f354f38", + "sha256": "8ed091b3214e34c21757fd0e2fbd24d843006ebb596490f4924a81207a896099", "source": "adapters/python/hermes/hermes.fabric-adapter.json" }, "nvidia.fabric.kilo": { diff --git a/tests/_utils/mock_api_server.py b/tests/_utils/mock_api_server.py index 020f2a341..6e06ebc36 100644 --- a/tests/_utils/mock_api_server.py +++ b/tests/_utils/mock_api_server.py @@ -1,6 +1,7 @@ # SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. # SPDX-License-Identifier: Apache-2.0 +import asyncio import json import threading import time @@ -18,7 +19,8 @@ def mock_api_server(port: int) -> Iterator[str]: Context manager for a mock API server. Use the /_requests endpoint to inspect captured chat-completion payloads after a test action. - Use the /_scenario endpoint to configure a status code or ordered tool calls for subsequent requests. + Use the /_scenario endpoint to configure a status code, a response delay, or ordered tool calls for subsequent requests. + Use the /_chat_authorization_headers endpoint to inspect the Authorization header of each chat-completion request. Use the /_reset endpoint to clear all retained request and scenario state. Args: @@ -33,6 +35,8 @@ def mock_api_server(port: int) -> Iterator[str]: def reset_state() -> None: app.state.requests = [] app.state.status_code = 200 + app.state.delay_seconds = 0.0 + app.state.chat_authorization_headers = [] app.state.tool_calls = [] app.state.tool_call_index = 0 app.state.mcp_authorization_headers = [] @@ -69,6 +73,7 @@ async def scenario(request: Request) -> dict[str, object]: payload = await request.json() app.state.status_code = int(payload.get("status_code", 200)) + app.state.delay_seconds = float(payload.get("delay_seconds", 0.0)) tool_call = payload.get("tool_call") app.state.tool_calls = payload.get("tool_calls") or ( [tool_call] if tool_call is not None else [] @@ -97,6 +102,10 @@ def reset() -> dict[str, str]: reset_state() return {"status": "ok"} + @app.get("/_chat_authorization_headers") + def chat_authorization_headers() -> list[str | None]: + return list(app.state.chat_authorization_headers) + @app.get("/_mcp_authorization_headers") def mcp_authorization_headers() -> list[str | None]: return list(app.state.mcp_authorization_headers) @@ -149,6 +158,11 @@ async def mcp(request: Request): async def chat_completions(request: Request): payload = await request.json() app.state.requests.append(payload) + app.state.chat_authorization_headers.append( + request.headers.get("authorization") + ) + if app.state.delay_seconds: + await asyncio.sleep(app.state.delay_seconds) if app.state.status_code != 200: return JSONResponse( status_code=app.state.status_code, diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py new file mode 100644 index 000000000..f99a17236 --- /dev/null +++ b/tests/adapters/test_hermes_interfaces.py @@ -0,0 +1,288 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Tests for Hermes's API server and dashboard served by a managed runtime.""" + +from __future__ import annotations + +import asyncio +import importlib.util +import os +import socket +import sys +import time +from pathlib import Path + +import pytest +import requests +from nemo_fabric import Fabric +from nemo_fabric import FabricConfig +from nemo_fabric.errors import FabricConfigError +from nemo_fabric_adapter_contract.models import AgentConfig +from nemo_fabric_adapter_contract.models import RuntimeContext + +pytestmark = pytest.mark.usefixtures("requires_hermes_agent") + +if importlib.util.find_spec("run_agent") is not None: + from nemo_fabric_adapters.hermes import adapter + from nemo_fabric_adapters.hermes import configuration + from nemo_fabric_adapters.hermes import interfaces + +MODEL_KEY = "fabric-test-model-key" + + +def _free_port() -> int: + with socket.create_server(("127.0.0.1", 0)) as server: + return server.getsockname()[1] + + +def _agent_config( + settings: dict[str, object], *, base_url: str | None = None +) -> AgentConfig: + model: dict[str, object] = { + "provider": "openai", + "model": "fabric-echo", + "api_key_env": "FABRIC_TEST_MODEL_KEY", + } + if base_url is not None: + model["base_url"] = base_url + return AgentConfig.from_mapping( + {"harness": {"settings": settings}, "models": {"default": model}} + ) + + +def _payload( + tmp_path: Path, settings: dict[str, object], *, base_url: str | None = None +) -> dict[str, object]: + os.environ["FABRIC_TEST_MODEL_KEY"] = MODEL_KEY + context = RuntimeContext.from_mapping( + { + "runtime_id": "runtime-interfaces", + "invocation_id": "invocation-1", + "request_id": "request-1", + "environment": { + "environment_id": "environment-1", + "provider": "test", + "control_location": "in_env_control", + "ownership": "caller_owned", + "workspace": str(tmp_path), + }, + "artifacts": {}, + } + ) + return { + "base_dir": str(tmp_path), + "runtime_context": context.to_mapping(), + "config": _agent_config(settings, base_url=base_url), + } + + +def _token_path(tmp_path: Path) -> Path: + return ( + tmp_path + / "artifacts/.fabric/hermes/runtimes/runtime-interfaces/interfaces/api.token" + ) + + +@pytest.fixture(name="web_dist") +def web_dist_fixture(tmp_path: Path) -> Path: + dist = tmp_path / "web_dist" + dist.mkdir() + (dist / "index.html").write_text( + "fabric-test-dashboard", + encoding="utf-8", + ) + os.environ["HERMES_WEB_DIST"] = str(dist) + return dist + + +def _interface(name: str, **fields: object) -> dict[str, object]: + return {"interfaces": {name: fields}} + + +# Settings that the descriptor's schema rejects during planning. +INVALID_SETTINGS = [ + pytest.param(_interface("terminal"), id="unsupported"), + pytest.param(_interface("api", port=8642, key="x"), id="unknown-field"), + pytest.param(_interface("api"), id="missing-port"), + pytest.param(_interface("dashboard", port=65_536), id="port-too-high"), + pytest.param({"startup_timeout_seconds": 75.5}, id="timeout-too-long"), +] + + +@pytest.mark.parametrize("settings", INVALID_SETTINGS) +def test_hermes_plan_rejects_invalid_settings( + tmp_path: Path, settings: dict[str, object] +): + config = FabricConfig.from_mapping( + { + "metadata": {"name": "hermes-interfaces"}, + "harness": { + "adapter_id": "nvidia.fabric.hermes", + "resolution": "preinstalled", + "settings": settings, + }, + "models": {"default": {"provider": "nvidia", "model": "test-model"}}, + "environment": {"provider": "local", "workspace": "."}, + } + ) + + with pytest.raises(FabricConfigError): + Fabric().plan(config, base_dir=tmp_path) + + +def test_hermes_interfaces_read_the_model_endpoint_and_key_from_config(): + config = configuration.build_hermes_config( + _agent_config({}, base_url="http://127.0.0.1:9/v1"), + workspace=".", + interfaces={"api": 8642}, + ) + + assert config["model"] == { + "provider": "custom", + "default": "fabric-echo", + "base_url": "http://127.0.0.1:9/v1", + "api_key": "${FABRIC_TEST_MODEL_KEY}", + } + assert config["agent"]["cron_drain_timeout"] == 3 + assert config["agent"]["restart_drain_timeout"] == 0 + + +@pytest.mark.skipif(sys.platform != "linux", reason="Reads Linux procfs") +async def test_hermes_serves_api_and_dashboard_with_the_configured_model( + tmp_path: Path, api_server: str, web_dist: Path +): + api_port, dashboard_port = _free_port(), _free_port() + runtime = adapter.HermesRuntime() + await runtime.start( + _payload( + tmp_path, + { + "interfaces": { + "api": {"port": api_port}, + "dashboard": {"port": dashboard_port}, + } + }, + base_url=f"{api_server}/v1", + ) + ) + token_path = _token_path(tmp_path) + try: + token = token_path.read_text(encoding="utf-8") + token_mode = token_path.stat().st_mode & 0o777 + api = f"http://127.0.0.1:{api_port}" + unauthorized = await asyncio.to_thread( + requests.get, f"{api}/v1/models", timeout=10 + ) + reply = await asyncio.to_thread( + requests.post, + f"{api}/v1/chat/completions", + headers={"Authorization": f"Bearer {token}"}, + json={ + "model": "hermes-agent", + "messages": [{"role": "user", "content": "ping"}], + }, + timeout=60, + ) + dashboard = await asyncio.to_thread( + requests.get, f"http://127.0.0.1:{dashboard_port}/", timeout=10 + ) + dashboard_environment = next( + Path(f"/proc/{child.process.pid}/environ").read_bytes() + for child in runtime._interfaces._children + if child.name == "dashboard" + ) + finally: + await runtime.stop() + model_keys = requests.get(f"{api_server}/_chat_authorization_headers", timeout=5) + + assert token_mode == 0o600 + assert unauthorized.status_code == 401 + assert reply.status_code == 200, reply.text + assert "latest=ping" in reply.json()["choices"][0]["message"]["content"] + assert model_keys.json() + assert set(model_keys.json()) == {f"Bearer {MODEL_KEY}"} + assert "fabric-test-dashboard" in dashboard.text + # On loopback, Hermes embeds its session token: the dashboard has no sign-in. + assert "window.__HERMES_SESSION_TOKEN__" in dashboard.text + assert b"API_SERVER_KEY=" not in dashboard_environment + assert not token_path.exists() + + +async def test_hermes_stop_cuts_off_an_in_flight_api_request( + tmp_path: Path, api_server: str +): + requests.post(f"{api_server}/_scenario", json={"delay_seconds": 60}, timeout=5) + api_port = _free_port() + runtime = adapter.HermesRuntime() + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"api": {"port": api_port}}}, + base_url=f"{api_server}/v1", + ) + ) + token = _token_path(tmp_path).read_text(encoding="utf-8") + in_flight = asyncio.create_task( + asyncio.to_thread( + requests.post, + f"http://127.0.0.1:{api_port}/v1/chat/completions", + headers={"Authorization": f"Bearer {token}"}, + json={ + "model": "hermes-agent", + "messages": [{"role": "user", "content": "slow"}], + }, + timeout=90, + ) + ) + while not requests.get(f"{api_server}/_requests", timeout=5).json(): + await asyncio.sleep(0.1) + + started = time.monotonic() + await runtime.stop() + elapsed = time.monotonic() - started + in_flight.cancel() + + assert elapsed < 8 + assert not _token_path(tmp_path).exists() + + +async def test_hermes_interface_port_in_use_fails_start( + tmp_path: Path, api_server: str +): + runtime = adapter.HermesRuntime() + with socket.create_server(("127.0.0.1", 0)) as server: + port = server.getsockname()[1] + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"api": {"port": port}}}, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_interface_port_unavailable" + assert caught.value.metadata == { + "field": "harness.settings.interfaces.api.port", + "port": port, + } + assert not _token_path(tmp_path).exists() + + +async def test_hermes_dashboard_without_a_built_frontend_fails_start( + tmp_path: Path, api_server: str +): + os.environ["HERMES_WEB_DIST"] = str(tmp_path / "missing") + runtime = adapter.HermesRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"dashboard": {"port": _free_port()}}}, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_dashboard_frontend_missing" From 3a5abc21f6722b2ff3770f7eb3aea5d308b469b4 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 05:14:47 -0700 Subject: [PATCH 05/54] feat: keep an agent's state in one folder across its runtimes Each runtime of an agent gets a new runtime ID, and adapters keep native state in a folder named after it, so a restarted or replaced runtime starts with empty state even when the artifact root survives. `runtime.keep_state` asks core for one folder per agent instead: `/.fabric/state//`. Core passes it to the adapter as `RuntimeContext.state_dir`, holds a lock on it while the runtime runs so a second runtime fails with `StateInUse`, and never deletes it. The operating system releases the lock when the host process exits, so a crash leaves no stale lock. Planning rejects the setting for adapters that don't accept `runtime.keep_state`, and rejects an agent name that isn't one folder name, so `metadata.name` can't escape the artifact root. The adapter contract, schemas, generated TypeScript and Rust reference, CLI presets and scaffold template, the adapter docs and the build-adapter skill describe the new field. Left out: no bundled adapter accepts the setting yet; Hermes opts in in a later change. The Python SDK gets no typed `keep_state` field: the config mapping already carries `runtime.keep_state` through to core, which parses and validates it. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapter_contract/models.py | 1 + .../schemas/adapter-descriptor.schema.json | 5 + .../schemas/runtime-context.schema.json | 7 + .../src/generated/adapter-descriptor.ts | 1 + .../src/generated/runtime-context.ts | 6 + crates/fabric-cli/src/presets.rs | 1 + crates/fabric-cli/templates/rust/main.rs.tmpl | 1 + crates/fabric-core/src/config.rs | 26 ++++ crates/fabric-core/src/error.rs | 8 ++ crates/fabric-core/src/runtime.rs | 136 ++++++++++++++++++ .../tutorials/adapter-descriptor.md | 5 + docs/adapter-contract/tutorials/execution.md | 1 + .../config/enum-adapterconfigfield.mdx | 7 + .../config/struct-runtimeconfig.mdx | 6 +- .../error/enum-fabricerror.mdx | 14 +- .../runtime/struct-runtimecontext.mdx | 6 +- docs/sdk/python.mdx | 11 ++ .../adapter-descriptor.schema.json | 5 + .../adapter-invocation.schema.json | 7 + .../openai-stream-invocation.schema.json | 7 + .../runtime-context.schema.json | 7 + schemas/sdk/agent.schema.json | 4 + schemas/sdk/run-plan.schema.json | 9 ++ skills/nemo-fabric-build-adapter/SKILL.md | 3 + 24 files changed, 281 insertions(+), 3 deletions(-) diff --git a/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py b/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py index d3c1103cf..899b4c5fa 100644 --- a/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py +++ b/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py @@ -647,6 +647,7 @@ class RuntimeContext(ContractModel): artifacts: ArtifactManifest telemetry: RuntimeTelemetryContext | None = _optional() deadline_millis: int | None = _optional() + state_dir: str | Path | None = _optional() def _validate(self) -> None: _nonblank(self.runtime_id, "runtime_id") diff --git a/adapter-contract/typescript/schemas/adapter-descriptor.schema.json b/adapter-contract/typescript/schemas/adapter-descriptor.schema.json index 637dfbf2a..b62f59d20 100644 --- a/adapter-contract/typescript/schemas/adapter-descriptor.schema.json +++ b/adapter-contract/typescript/schemas/adapter-descriptor.schema.json @@ -38,6 +38,11 @@ "description": "Per-invocation harness turn limit.", "type": "string" }, + { + "const": "runtime.keep_state", + "description": "Agent-named state folder kept across runtimes.", + "type": "string" + }, { "const": "tools.enabled", "description": "Adapter-native tool names to expose.", diff --git a/adapter-contract/typescript/schemas/runtime-context.schema.json b/adapter-contract/typescript/schemas/runtime-context.schema.json index 62bc7927c..4c1cbb51d 100644 --- a/adapter-contract/typescript/schemas/runtime-context.schema.json +++ b/adapter-contract/typescript/schemas/runtime-context.schema.json @@ -214,6 +214,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/adapter-contract/typescript/src/generated/adapter-descriptor.ts b/adapter-contract/typescript/src/generated/adapter-descriptor.ts index 4884855be..dbd941e07 100644 --- a/adapter-contract/typescript/src/generated/adapter-descriptor.ts +++ b/adapter-contract/typescript/src/generated/adapter-descriptor.ts @@ -43,6 +43,7 @@ export type AdapterConfigField = | "models.max_tokens" | "instructions.system" | "runtime.max_turns" + | "runtime.keep_state" | "tools.enabled" | "tools.definitions" | "tools.blocked" diff --git a/adapter-contract/typescript/src/generated/runtime-context.ts b/adapter-contract/typescript/src/generated/runtime-context.ts index 19310d068..f8c563a94 100644 --- a/adapter-contract/typescript/src/generated/runtime-context.ts +++ b/adapter-contract/typescript/src/generated/runtime-context.ts @@ -29,6 +29,12 @@ export interface RuntimeContext { * Runtime handle id. */ runtime_id: string; + /** + * Absolute folder for the adapter's native state, present when + * `runtime.keep_state` is set. Every runtime of the agent gets the same + * folder, and Fabric lets only one running runtime use it at a time. + */ + state_dir?: string | null; /** * Runtime telemetry context generated for this invocation. */ diff --git a/crates/fabric-cli/src/presets.rs b/crates/fabric-cli/src/presets.rs index e39fca5df..fbe0ff8c4 100644 --- a/crates/fabric-cli/src/presets.rs +++ b/crates/fabric-cli/src/presets.rs @@ -287,6 +287,7 @@ fn config( artifacts: None, timeout_seconds: None, max_turns: None, + keep_state: false, extensions: BTreeMap::new(), }, environment: Some(EnvironmentConfig { diff --git a/crates/fabric-cli/templates/rust/main.rs.tmpl b/crates/fabric-cli/templates/rust/main.rs.tmpl index 4055d76af..bb6c81dfe 100644 --- a/crates/fabric-cli/templates/rust/main.rs.tmpl +++ b/crates/fabric-cli/templates/rust/main.rs.tmpl @@ -38,6 +38,7 @@ fn build_config() -> FabricConfig { artifacts: None, timeout_seconds: {{TIMEOUT_SECONDS}}, max_turns: {{MAX_TURNS}}, + keep_state: false, extensions: BTreeMap::new(), }, environment: Some(EnvironmentConfig { diff --git a/crates/fabric-core/src/config.rs b/crates/fabric-core/src/config.rs index 72cc01947..b3ff649ee 100644 --- a/crates/fabric-core/src/config.rs +++ b/crates/fabric-core/src/config.rs @@ -873,6 +873,9 @@ pub enum AdapterConfigField { /// Per-invocation harness turn limit. #[serde(rename = "runtime.max_turns")] MaxTurns, + /// Agent-named state folder kept across runtimes. + #[serde(rename = "runtime.keep_state")] + KeepState, /// Adapter-native tool names to expose. #[serde(rename = "tools.enabled")] EnabledTools, @@ -1063,6 +1066,11 @@ pub struct RuntimeConfig { #[serde(default, skip_serializing_if = "Option::is_none")] #[schemars(range(min = 1, max = u32::MAX))] pub max_turns: Option, + /// Keep the adapter's native state in a folder named after the agent, so + /// every runtime of the agent uses the same folder. Requires an artifact + /// directory and an adapter that accepts `runtime.keep_state`. + #[serde(default, skip_serializing_if = "std::ops::Not::not")] + pub keep_state: bool, /// Additive normalized runtime fields. #[serde(default, flatten)] pub extensions: BTreeMap, @@ -1927,6 +1935,12 @@ pub(crate) fn validate_config(config: &FabricConfig) -> Result<()> { if config.runtime.max_turns == Some(0) { return invalid_config("runtime.max_turns", "must be greater than zero"); } + if config.runtime.keep_state && !is_one_folder_name(&config.metadata.name) { + return invalid_config( + "metadata.name", + "must be usable as one folder name when runtime.keep_state is set: not empty, `.` or `..`, and without `/` or `\\`", + ); + } if let Some(timeout) = config.runtime.timeout_seconds && (!timeout.is_finite() || timeout <= 0.0 @@ -2388,6 +2402,11 @@ fn validate_names(field: &str, names: &[String]) -> Result<()> { Ok(()) } +/// Whether a name can be one path component on every platform Fabric runs on. +fn is_one_folder_name(name: &str) -> bool { + !name.trim().is_empty() && name != "." && name != ".." && !name.contains(['/', '\\']) +} + fn invalid_config(field: impl Into, reason: impl Into) -> Result { Err(FabricError::InvalidConfig { field: field.into(), @@ -2811,6 +2830,13 @@ pub(crate) fn adapter_config_compatibility_issues( )); } } + if config.runtime.keep_state && !accepts(AdapterConfigField::KeepState) { + issues.push(incompatible( + "runtime.keep_state".to_string(), + "the adapter does not declare that it keeps its state in an agent-named folder" + .to_string(), + )); + } if config.runtime.max_turns.is_some() && !accepts(AdapterConfigField::MaxTurns) { issues.push(incompatible( "runtime.max_turns".to_string(), diff --git a/crates/fabric-core/src/error.rs b/crates/fabric-core/src/error.rs index 056c0c034..856123b73 100644 --- a/crates/fabric-core/src/error.rs +++ b/crates/fabric-core/src/error.rs @@ -255,6 +255,14 @@ pub enum FabricError { /// Service handle id. service_id: String, }, + /// Another runtime holds the agent's kept state folder. + #[error( + "agent state folder {path} is in use by another runtime; stop that runtime before starting another" + )] + StateInUse { + /// The agent's state folder. + path: PathBuf, + }, /// A service cannot be released while runtimes still use it. #[error("service `{service_id}` has active runtimes: {runtime_ids:?}")] ServiceInUse { diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index d7041c9ed..4c3749639 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -476,6 +476,11 @@ pub struct RuntimeContext { /// Present on every invocation, shortly before Fabric's own invocation timeout. #[serde(default, skip_serializing_if = "Option::is_none")] pub deadline_millis: Option, + /// Absolute folder for the adapter's native state, present when + /// `runtime.keep_state` is set. Every runtime of the agent gets the same + /// folder, and Fabric lets only one running runtime use it at a time. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub state_dir: Option, } /// Runtime telemetry config passed to adapters. @@ -892,6 +897,8 @@ struct LocalAdapterHost { relay_config: Option, // Adapter startup values stay in memory, never in a serialized handle or plan. environment_env: BTreeMap, + // Held while the host runs; dropping the host releases the agent's state folder. + _state_lock: Option, } struct LocalServiceRecord { @@ -2650,6 +2657,7 @@ fn spawn_local_host( relay_config: Option, environment_env: BTreeMap, ) -> Result { + let state_lock = lock_agent_state(plan, &artifacts)?; let runtime_dir = local_host_directory(&runtime.runtime_id); std::fs::create_dir_all(&runtime_dir).map_err(|source| FabricError::Write { path: runtime_dir.clone(), @@ -2779,6 +2787,7 @@ fn spawn_local_host( artifacts, relay_config, environment_env, + _state_lock: state_lock, }) } @@ -3479,9 +3488,66 @@ fn adapter_runtime_context( artifacts: artifacts.clone(), telemetry: runtime_telemetry_context(plan, relay_config), deadline_millis: None, + state_dir: agent_state_dir(plan, artifacts)?, }) } +/// The folder that keeps an agent's native state across its runtimes when +/// `runtime.keep_state` is set: `/.fabric/state//`. +/// The adapter ID keeps another harness from reading the state if the agent's +/// adapter changes. +fn agent_state_dir(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result> { + if !plan.config.runtime.keep_state { + return Ok(None); + } + let Some(root) = artifacts.root.as_ref() else { + return Err(FabricError::InvalidConfig { + field: "runtime.keep_state".to_string(), + reason: "requires an artifact directory, from runtime.artifacts or the environment" + .to_string(), + }); + }; + let adapter = adapter_id(plan).unwrap_or_else(|| harness(plan)); + absolute_path( + root.join(".fabric") + .join("state") + .join(adapter) + .join(&plan.agent_name), + ) + .map(Some) +} + +/// Takes the agent's state folder for one runtime. The lock lasts while the +/// returned file is open, and the operating system releases it when this +/// process exits, so a crashed runtime leaves no stale lock behind. +fn lock_agent_state(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result> { + let Some(state_dir) = agent_state_dir(plan, artifacts)? else { + return Ok(None); + }; + std::fs::create_dir_all(&state_dir).map_err(|source| FabricError::Write { + path: state_dir.clone(), + source, + })?; + let lock_path = state_dir.join(".fabric-state.lock"); + let file = File::options() + .create(true) + .write(true) + .truncate(false) + .open(&lock_path) + .map_err(|source| FabricError::Write { + path: lock_path.clone(), + source, + })?; + match file.try_lock() { + Ok(()) => Ok(Some(file)), + Err(std::fs::TryLockError::WouldBlock) => Err(FabricError::StateInUse { path: state_dir }), + Err(std::fs::TryLockError::Error(source)) => Err(FabricError::Write { + path: lock_path, + source, + }), + } +} + fn resolve_named_environment(plan: &RunPlan, env: &mut BTreeMap) -> Result<()> { for name in plan .environment_plan @@ -4453,6 +4519,7 @@ for line in sys.stdin: "normalized_env": os.environ.get("FABRIC_NORMALIZED_ENV"), "context_env": invocation["runtime_context"]["environment"].get("env", {}), "deadline_millis": invocation["runtime_context"].get("deadline_millis"), + "state_dir": invocation["runtime_context"].get("state_dir"), } if MODE in {"adapter_reported_failure", "blank_error_code"}: result = { @@ -4819,6 +4886,74 @@ for line in sys.stdin: let _ = fs::remove_dir_all(root); } + fn local_host_plan_keeping_state() -> (PathBuf, RunPlan) { + let (root, plan) = local_host_plan("success"); + let descriptor_path = root.join("adapters/local-host/local-host.fabric-adapter.json"); + let mut descriptor: Value = serde_json::from_str( + &fs::read_to_string(&descriptor_path).expect("read adapter descriptor"), + ) + .expect("parse adapter descriptor"); + descriptor["config"] = serde_json::json!({"accepts": ["runtime.keep_state"]}); + fs::write(&descriptor_path, descriptor.to_string()).expect("write adapter descriptor"); + let mut config = plan.config; + config.metadata.name = "assistant".to_string(); + config.runtime.keep_state = true; + let plan = resolve_run_plan_from_config(config, ResolveContext::new(&root)) + .expect("resolve keep_state plan"); + (root, plan) + } + + #[test] + fn keep_state_gives_an_agents_runtimes_one_state_folder_one_at_a_time() { + let (root, plan) = local_host_plan_keeping_state(); + let state_dir = |runtime: &RuntimeHandle| { + invoke_runtime(&plan, runtime, RunRequest::text("state")) + .expect("invocation") + .output["state_dir"] + .clone() + }; + + let first = start_runtime(&plan).expect("start first runtime"); + let error = start_runtime(&plan).expect_err("a second runtime must not share the folder"); + assert!(matches!(error, FabricError::StateInUse { .. }), "{error}"); + let first_dir = state_dir(&first); + stop_runtime(&plan, &first).expect("stop first runtime"); + let second = start_runtime(&plan).expect("start once the first runtime stopped"); + let second_dir = state_dir(&second); + stop_runtime(&plan, &second).expect("stop second runtime"); + + let expected = root.join("artifacts/.fabric/state/acme.fabric.local-host/assistant"); + assert_ne!(first.runtime_id, second.runtime_id); + assert_eq!(second_dir, first_dir); + let first_dir = first_dir.as_str().expect("state_dir in runtime context"); + assert!(Path::new(first_dir).is_absolute(), "{first_dir}"); + assert_eq!(Path::new(first_dir), expected); + assert!(expected.is_dir()); + let _ = fs::remove_dir_all(root); + } + + #[test] + fn keep_state_planning_rejects_unaccepting_adapters_and_unsafe_agent_names() { + let (root, accepting) = local_host_plan_keeping_state(); + let (plain_root, plain) = local_host_plan("success"); + let mut not_accepted = plain.config; + not_accepted.runtime.keep_state = true; + let mut cases = vec![(&plain_root, not_accepted, "runtime.keep_state")]; + for name in ["..", "a/b", "a\\b"] { + let mut config = accepting.config.clone(); + config.metadata.name = name.to_string(); + cases.push((&root, config, "metadata.name")); + } + + for (base_dir, config, field) in cases { + let error = resolve_run_plan_from_config(config, ResolveContext::new(base_dir)) + .expect_err(field); + assert!(error.to_string().contains(field), "{field}: {error}"); + } + let _ = fs::remove_dir_all(root); + let _ = fs::remove_dir_all(plain_root); + } + fn local_host_plan_with_env_name(name: &str) -> (PathBuf, RunPlan) { let (root, plan) = local_host_plan("success"); let mut config = plan.config; @@ -4846,6 +4981,7 @@ for line in sys.stdin: result.output["context_env"]["FABRIC_NORMALIZED_ENV"], serde_json::json!("visible") ); + assert_eq!(result.output["state_dir"], Value::Null); let persisted_invocation: Value = serde_json::from_str( &fs::read_to_string( result.metadata["fabric_invocation"] diff --git a/docs/adapter-contract/tutorials/adapter-descriptor.md b/docs/adapter-contract/tutorials/adapter-descriptor.md index b32a3d154..27d98f9f5 100644 --- a/docs/adapter-contract/tutorials/adapter-descriptor.md +++ b/docs/adapter-contract/tutorials/adapter-descriptor.md @@ -102,6 +102,11 @@ schema enum for the exact accepted values. Planning rejects configured normalized behavior outside the declared surface. NeMo Fabric does not silently remove unsupported fields. +Accept `runtime.keep_state` only when the adapter keeps all of its native +state in `RuntimeContext.state_dir` when that field is present. Every runtime +of the agent then receives the same folder, so a later runtime finds the +earlier runtime's sessions, memory, and other harness files. + When an adapter accepts `instructions.system`, declare the exact supported modes in `config.system_instruction_modes`. `replace` discards the harness default system instruction. `append` preserves the harness default and adds the diff --git a/docs/adapter-contract/tutorials/execution.md b/docs/adapter-contract/tutorials/execution.md index 367575b19..8bcc786fc 100644 --- a/docs/adapter-contract/tutorials/execution.md +++ b/docs/adapter-contract/tutorials/execution.md @@ -131,6 +131,7 @@ value: | `artifacts` | Lists artifacts visible when the operation begins. | | `telemetry` | Supplies invocation telemetry context, including generated Relay configuration when enabled. | | `deadline_millis` | Gives the Unix time in milliseconds by which an invocation should return. NeMo Fabric's own invocation timeout fires shortly after and kills the host with its descendant processes; the gap is shorter for very short timeouts. Keep cleanup after the deadline brief, or the invocation fails with `host_timeout` instead of returning the adapter's result. | +| `state_dir` | Present when the config sets `runtime.keep_state` and the adapter accepts it. Gives an absolute folder, `/.fabric/state//`, that every runtime of the agent receives. Keep the harness's native state there instead of in a per-runtime folder. NeMo Fabric creates the folder, fails `start` while another runtime holds it, and never deletes it. | Use the canonical [`runtime-context.schema.json`](https://github.com/NVIDIA/NeMo-Fabric/blob/main/schemas/adapter-contract/runtime-context.schema.json) diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx index dcf56eaf5..39cdfb55b 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx @@ -18,6 +18,7 @@ pub enum AdapterConfigField { ModelMaxTokens, SystemInstructions, MaxTurns, + KeepState, EnabledTools, ToolDefinitions, BlockedTools, @@ -75,6 +76,12 @@ Portable system instructions. Per-invocation harness turn limit. +### `KeepState` + +
+ +Agent-named state folder kept across runtimes. + ### `EnabledTools`
diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx index ad38ed633..2658123ab 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx @@ -9,7 +9,7 @@ SPDX-License-Identifier: Apache-2.0 */} Generated from `cargo doc --no-deps -p nemo-fabric-core`. -
String,\n    pub output_schema: String,\n    pub artifacts: Option<PathBuf>,\n    pub timeout_seconds: Option<f64>,\n    pub max_turns: Option<u32>,\n    pub extensions: BTreeMap<String, Value>,\n}"}} />
+
String,\n    pub output_schema: String,\n    pub artifacts: Option<PathBuf>,\n    pub timeout_seconds: Option<f64>,\n    pub max_turns: Option<u32>,\n    pub keep_state: bool,\n    pub extensions: BTreeMap<String, Value>,\n}"}} />
Invocation runtime contract. @@ -35,6 +35,10 @@ Maximum duration of one invocation in seconds. Maximum number of harness turns within one invocation. +### `keep_state: bool` + +Keep the adapter's native state in a folder named after the agent, so every runtime of the agent uses the same folder. Requires an artifact directory and an adapter that accepts `runtime.keep_state`. + ### `extensions: BTreeMap` Additive normalized runtime fields. diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx index 18ad7379a..b3500721a 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx @@ -9,7 +9,7 @@ SPDX-License-Identifier: Apache-2.0 */} Generated from `cargo doc --no-deps -p nemo-fabric-core`. -
PathBuf,\n        source: Error,\n    },\n    PathNotFound(PathBuf),\n    UnknownAdapter {\n        adapter_id: String,\n        available: Vec<String>,\n    },\n    UnknownAdapterTarget {\n        target_id: String,\n        available: Vec<String>,\n    },\n    AmbiguousDescriptor {\n        descriptor_kind: &'static str,\n        id: String,\n        paths: Vec<PathBuf>,\n    },\n    AdapterDescriptorMismatch {\n        path: PathBuf,\n        field: &'static str,\n        expected: String,\n        actual: String,\n    },\n    AdapterDescriptorUnsupported {\n        adapter_id: String,\n        field: &'static str,\n        value: String,\n    },\n    InvalidAdapterDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidAdapterTargetDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidHarnessSettings {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        settings_path: String,\n        reason: String,\n    },\n    InvalidWorkflow {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        workflow_path: String,\n        reason: String,\n    },\n    InvalidToolDefinition {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        definition_path: String,\n        reason: String,\n    },\n    InvalidAdapterExtension {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        extension_path: String,\n        reason: String,\n    },\n    InvalidConfig {\n        field: String,\n        reason: String,\n    },\n    AdapterCompatibility {\n        adapter_id: String,\n        field: String,\n        reason: String,\n    },\n    UnknownSchema {\n        schema: String,\n        available: Vec<String>,\n    },\n    UnsupportedRuntimeAdapter {\n        harness: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedRuntimeCapability {\n        adapter_id: String,\n        capability: &'static str,\n    },\n    InvalidOpenAiStreamTransport {\n        field: &'static str,\n        reason: &'static str,\n    },\n    AdapterLifecycleOperation {\n        operation: &'static str,\n        runtime_id: String,\n        code: String,\n        message: String,\n        diagnostics: String,\n    },\n    RuntimeHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        runtime_id: String,\n    },\n    ServiceHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        service_id: String,\n    },\n    ServiceInUse {\n        service_id: String,\n        runtime_ids: Vec<String>,\n    },\n    ServiceNotActive {\n        service_id: String,\n    },\n    UnsupportedEnvironmentProvider {\n        provider: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedEnvironmentRelease {\n        provider: String,\n    },\n    EnvironmentProviderOperation {\n        provider: String,\n        operation: String,\n        code: String,\n        message: String,\n    },\n    EnvironmentInUse {\n        environment_id: String,\n        runtime_id: String,\n    },\n    EnvironmentReleaseInProgress {\n        environment_id: String,\n    },\n    EnvironmentHandleRequired {\n        provider: String,\n    },\n    EnvironmentHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        environment_id: String,\n    },\n    ResourceObservationUnavailable {\n        runtime_id: String,\n        reason: String,\n    },\n    ResourceObservationUnsupported {\n        runtime_id: String,\n        reason: String,\n    },\n    InvalidProcessSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    InvalidPythonSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    PythonInterpreterUnavailable {\n        path: PathBuf,\n        origin: String,\n        reason: String,\n    },\n    ProcessRunner {\n        command: String,\n        source: Error,\n    },\n    SerializeJson(Error),\n    Read {\n        path: PathBuf,\n        source: Error,\n    },\n    Write {\n        path: PathBuf,\n        source: Error,\n    },\n    ParseJson {\n        path: PathBuf,\n        source: Error,\n    },\n}"}} />
+
PathBuf,\n        source: Error,\n    },\n    PathNotFound(PathBuf),\n    UnknownAdapter {\n        adapter_id: String,\n        available: Vec<String>,\n    },\n    UnknownAdapterTarget {\n        target_id: String,\n        available: Vec<String>,\n    },\n    AmbiguousDescriptor {\n        descriptor_kind: &'static str,\n        id: String,\n        paths: Vec<PathBuf>,\n    },\n    AdapterDescriptorMismatch {\n        path: PathBuf,\n        field: &'static str,\n        expected: String,\n        actual: String,\n    },\n    AdapterDescriptorUnsupported {\n        adapter_id: String,\n        field: &'static str,\n        value: String,\n    },\n    InvalidAdapterDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidAdapterTargetDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidHarnessSettings {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        settings_path: String,\n        reason: String,\n    },\n    InvalidWorkflow {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        workflow_path: String,\n        reason: String,\n    },\n    InvalidToolDefinition {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        definition_path: String,\n        reason: String,\n    },\n    InvalidAdapterExtension {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        extension_path: String,\n        reason: String,\n    },\n    InvalidConfig {\n        field: String,\n        reason: String,\n    },\n    AdapterCompatibility {\n        adapter_id: String,\n        field: String,\n        reason: String,\n    },\n    UnknownSchema {\n        schema: String,\n        available: Vec<String>,\n    },\n    UnsupportedRuntimeAdapter {\n        harness: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedRuntimeCapability {\n        adapter_id: String,\n        capability: &'static str,\n    },\n    InvalidOpenAiStreamTransport {\n        field: &'static str,\n        reason: &'static str,\n    },\n    AdapterLifecycleOperation {\n        operation: &'static str,\n        runtime_id: String,\n        code: String,\n        message: String,\n        diagnostics: String,\n    },\n    RuntimeHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        runtime_id: String,\n    },\n    ServiceHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        service_id: String,\n    },\n    StateInUse {\n        path: PathBuf,\n    },\n    ServiceInUse {\n        service_id: String,\n        runtime_ids: Vec<String>,\n    },\n    ServiceNotActive {\n        service_id: String,\n    },\n    UnsupportedEnvironmentProvider {\n        provider: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedEnvironmentRelease {\n        provider: String,\n    },\n    EnvironmentProviderOperation {\n        provider: String,\n        operation: String,\n        code: String,\n        message: String,\n    },\n    EnvironmentInUse {\n        environment_id: String,\n        runtime_id: String,\n    },\n    EnvironmentReleaseInProgress {\n        environment_id: String,\n    },\n    EnvironmentHandleRequired {\n        provider: String,\n    },\n    EnvironmentHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        environment_id: String,\n    },\n    ResourceObservationUnavailable {\n        runtime_id: String,\n        reason: String,\n    },\n    ResourceObservationUnsupported {\n        runtime_id: String,\n        reason: String,\n    },\n    InvalidProcessSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    InvalidPythonSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    PythonInterpreterUnavailable {\n        path: PathBuf,\n        origin: String,\n        reason: String,\n    },\n    ProcessRunner {\n        command: String,\n        source: Error,\n    },\n    SerializeJson(Error),\n    Read {\n        path: PathBuf,\n        source: Error,\n    },\n    Write {\n        path: PathBuf,\n        source: Error,\n    },\n    ParseJson {\n        path: PathBuf,\n        source: Error,\n    },\n}"}} />
Errors raised by NeMo Fabric config loading and validation. @@ -453,6 +453,18 @@ Actual value. Service handle id. +### `StateInUse` + +
+ +Another runtime holds the agent's kept state folder. + +#### Fields + +##### `path: PathBuf` + +The agent's state folder. + ### `ServiceInUse`
diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx index 625527702..a4e24f344 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx @@ -9,7 +9,7 @@ SPDX-License-Identifier: Apache-2.0 */} Generated from `cargo doc --no-deps -p nemo-fabric-core`. -
String,\n    pub invocation_id: String,\n    pub request_id: String,\n    pub environment: EnvironmentHandle,\n    pub artifacts: ArtifactManifest,\n    pub telemetry: Option<RuntimeTelemetryContext>,\n    pub deadline_millis: Option<u64>,\n}"}} />
+
String,\n    pub invocation_id: String,\n    pub request_id: String,\n    pub environment: EnvironmentHandle,\n    pub artifacts: ArtifactManifest,\n    pub telemetry: Option<RuntimeTelemetryContext>,\n    pub deadline_millis: Option<u64>,\n    pub state_dir: Option<PathBuf>,\n}"}} />
Context generated for one invocation of a started runtime. @@ -43,6 +43,10 @@ Runtime telemetry context generated for this invocation. Unix time in milliseconds by which the adapter should return its result. Present on every invocation, shortly before Fabric's own invocation timeout. +### `state_dir: Option` + +Absolute folder for the adapter's native state, present when `runtime.keep_state` is set. Every runtime of the agent gets the same folder, and Fabric lets only one running runtime use it at a time. + ## Trait Implementations ### `impl Clone for RuntimeContext` diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index f93512c2b..dc1c85932 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -858,6 +858,17 @@ on one live thread, Deep Agents invokes one compiled graph and checkpointer, Hermes Agent reuses one agent and session database, and Claude keeps one connected SDK client. Harness-native identifiers remain adapter-internal. +### Keep Agent State Across Runtimes + +By default, each runtime keeps its native state in its own folder, so a new +runtime starts empty. Set `"keep_state": true` in the config's `runtime` +mapping to give every runtime of the agent one folder instead: +`/.fabric/state//`. The config needs an +artifact directory, and `metadata.name` must be usable as one folder name. +Only one runtime can use the folder at a time: `start_runtime(...)` fails while +another runtime of the agent runs. Planning fails for an adapter that doesn't +declare `runtime.keep_state`. + ## Runtime Resource Snapshots `Runtime.resource_snapshot()` returns a timestamped `RuntimeResourceSnapshot` diff --git a/schemas/adapter-contract/adapter-descriptor.schema.json b/schemas/adapter-contract/adapter-descriptor.schema.json index 637dfbf2a..b62f59d20 100644 --- a/schemas/adapter-contract/adapter-descriptor.schema.json +++ b/schemas/adapter-contract/adapter-descriptor.schema.json @@ -38,6 +38,11 @@ "description": "Per-invocation harness turn limit.", "type": "string" }, + { + "const": "runtime.keep_state", + "description": "Agent-named state folder kept across runtimes.", + "type": "string" + }, { "const": "tools.enabled", "description": "Adapter-native tool names to expose.", diff --git a/schemas/adapter-contract/adapter-invocation.schema.json b/schemas/adapter-contract/adapter-invocation.schema.json index f86a452b8..183c92248 100644 --- a/schemas/adapter-contract/adapter-invocation.schema.json +++ b/schemas/adapter-contract/adapter-invocation.schema.json @@ -210,6 +210,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/schemas/adapter-contract/openai-stream-invocation.schema.json b/schemas/adapter-contract/openai-stream-invocation.schema.json index 364e2f3ff..17d0efc1a 100644 --- a/schemas/adapter-contract/openai-stream-invocation.schema.json +++ b/schemas/adapter-contract/openai-stream-invocation.schema.json @@ -300,6 +300,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/schemas/adapter-contract/runtime-context.schema.json b/schemas/adapter-contract/runtime-context.schema.json index 62bc7927c..4c1cbb51d 100644 --- a/schemas/adapter-contract/runtime-context.schema.json +++ b/schemas/adapter-contract/runtime-context.schema.json @@ -214,6 +214,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/schemas/sdk/agent.schema.json b/schemas/sdk/agent.schema.json index 63bbcf0d6..f69595c6a 100644 --- a/schemas/sdk/agent.schema.json +++ b/schemas/sdk/agent.schema.json @@ -1495,6 +1495,10 @@ "description": "Input schema label.", "type": "string" }, + "keep_state": { + "description": "Keep the adapter's native state in a folder named after the agent, so\nevery runtime of the agent uses the same folder. Requires an artifact\ndirectory and an adapter that accepts `runtime.keep_state`.", + "type": "boolean" + }, "max_turns": { "description": "Maximum number of harness turns within one invocation.", "format": "uint32", diff --git a/schemas/sdk/run-plan.schema.json b/schemas/sdk/run-plan.schema.json index a15e3e678..ad240c67e 100644 --- a/schemas/sdk/run-plan.schema.json +++ b/schemas/sdk/run-plan.schema.json @@ -38,6 +38,11 @@ "description": "Per-invocation harness turn limit.", "type": "string" }, + { + "const": "runtime.keep_state", + "description": "Agent-named state folder kept across runtimes.", + "type": "string" + }, { "const": "tools.enabled", "description": "Adapter-native tool names to expose.", @@ -2964,6 +2969,10 @@ "description": "Input schema label.", "type": "string" }, + "keep_state": { + "description": "Keep the adapter's native state in a folder named after the agent, so\nevery runtime of the agent uses the same folder. Requires an artifact\ndirectory and an adapter that accepts `runtime.keep_state`.", + "type": "boolean" + }, "max_turns": { "description": "Maximum number of harness turns within one invocation.", "format": "uint32", diff --git a/skills/nemo-fabric-build-adapter/SKILL.md b/skills/nemo-fabric-build-adapter/SKILL.md index 9dfc2389c..e195634f5 100644 --- a/skills/nemo-fabric-build-adapter/SKILL.md +++ b/skills/nemo-fabric-build-adapter/SKILL.md @@ -122,6 +122,9 @@ adapter boundary: the task environment. - Read identity, environment, artifacts, telemetry, and the invocation deadline (`deadline_millis`) from `RuntimeContext`, not from workflow settings. +- If the adapter declares `runtime.keep_state`, keep all native state in + `RuntimeContext.state_dir` when it is present. Every runtime of the agent + receives the same folder. Reject unsupported values with stable, safe error codes. Do not log complete configs, environment values, headers, credentials, or arbitrary user input. From fd471cf2226c4bf8f8e1e8f72158d5cb489d8a76 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 05:14:47 -0700 Subject: [PATCH 06/54] feat: keep an agent's state in one folder across its runtimes Each runtime of an agent gets a new runtime ID, and adapters keep native state in a folder named after it, so a restarted or replaced runtime starts with empty state even when the artifact root survives. `runtime.keep_state` asks core for one folder per agent instead: `/.fabric/state//`. Core passes it to the adapter as `RuntimeContext.state_dir`, holds a lock on it while the runtime runs so a second runtime fails with `StateInUse`, and never deletes it. The operating system releases the lock when the host process exits, so a crash leaves no stale lock. Planning rejects the setting for adapters that don't accept `runtime.keep_state`, and rejects an agent name that isn't one folder name, so `metadata.name` can't escape the artifact root. The adapter contract, schemas, generated TypeScript and Rust reference, CLI presets and scaffold template, the adapter docs and the build-adapter skill describe the new field. Left out: no bundled adapter accepts the setting yet; Hermes opts in in a later change. The Python SDK gets no typed `keep_state` field: the config mapping already carries `runtime.keep_state` through to core, which parses and validates it. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapter_contract/models.py | 1 + .../schemas/adapter-descriptor.schema.json | 5 + .../schemas/runtime-context.schema.json | 7 + .../src/generated/adapter-descriptor.ts | 1 + .../src/generated/runtime-context.ts | 6 + crates/fabric-cli/src/presets.rs | 1 + crates/fabric-cli/templates/rust/main.rs.tmpl | 1 + crates/fabric-core/src/config.rs | 26 ++++ crates/fabric-core/src/error.rs | 8 ++ crates/fabric-core/src/runtime.rs | 136 ++++++++++++++++++ .../tutorials/adapter-descriptor.md | 5 + docs/adapter-contract/tutorials/execution.md | 1 + .../config/enum-adapterconfigfield.mdx | 7 + .../config/struct-runtimeconfig.mdx | 6 +- .../error/enum-fabricerror.mdx | 14 +- .../runtime/struct-runtimecontext.mdx | 6 +- docs/sdk/python.mdx | 11 ++ .../adapter-descriptor.schema.json | 5 + .../adapter-invocation.schema.json | 7 + .../openai-stream-invocation.schema.json | 7 + .../runtime-context.schema.json | 7 + schemas/sdk/agent.schema.json | 4 + schemas/sdk/run-plan.schema.json | 9 ++ skills/nemo-fabric-build-adapter/SKILL.md | 3 + 24 files changed, 281 insertions(+), 3 deletions(-) diff --git a/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py b/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py index d3c1103cf..899b4c5fa 100644 --- a/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py +++ b/adapter-contract/python/src/nemo_fabric_adapter_contract/models.py @@ -647,6 +647,7 @@ class RuntimeContext(ContractModel): artifacts: ArtifactManifest telemetry: RuntimeTelemetryContext | None = _optional() deadline_millis: int | None = _optional() + state_dir: str | Path | None = _optional() def _validate(self) -> None: _nonblank(self.runtime_id, "runtime_id") diff --git a/adapter-contract/typescript/schemas/adapter-descriptor.schema.json b/adapter-contract/typescript/schemas/adapter-descriptor.schema.json index 637dfbf2a..b62f59d20 100644 --- a/adapter-contract/typescript/schemas/adapter-descriptor.schema.json +++ b/adapter-contract/typescript/schemas/adapter-descriptor.schema.json @@ -38,6 +38,11 @@ "description": "Per-invocation harness turn limit.", "type": "string" }, + { + "const": "runtime.keep_state", + "description": "Agent-named state folder kept across runtimes.", + "type": "string" + }, { "const": "tools.enabled", "description": "Adapter-native tool names to expose.", diff --git a/adapter-contract/typescript/schemas/runtime-context.schema.json b/adapter-contract/typescript/schemas/runtime-context.schema.json index 62bc7927c..4c1cbb51d 100644 --- a/adapter-contract/typescript/schemas/runtime-context.schema.json +++ b/adapter-contract/typescript/schemas/runtime-context.schema.json @@ -214,6 +214,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/adapter-contract/typescript/src/generated/adapter-descriptor.ts b/adapter-contract/typescript/src/generated/adapter-descriptor.ts index 4884855be..dbd941e07 100644 --- a/adapter-contract/typescript/src/generated/adapter-descriptor.ts +++ b/adapter-contract/typescript/src/generated/adapter-descriptor.ts @@ -43,6 +43,7 @@ export type AdapterConfigField = | "models.max_tokens" | "instructions.system" | "runtime.max_turns" + | "runtime.keep_state" | "tools.enabled" | "tools.definitions" | "tools.blocked" diff --git a/adapter-contract/typescript/src/generated/runtime-context.ts b/adapter-contract/typescript/src/generated/runtime-context.ts index 19310d068..f8c563a94 100644 --- a/adapter-contract/typescript/src/generated/runtime-context.ts +++ b/adapter-contract/typescript/src/generated/runtime-context.ts @@ -29,6 +29,12 @@ export interface RuntimeContext { * Runtime handle id. */ runtime_id: string; + /** + * Absolute folder for the adapter's native state, present when + * `runtime.keep_state` is set. Every runtime of the agent gets the same + * folder, and Fabric lets only one running runtime use it at a time. + */ + state_dir?: string | null; /** * Runtime telemetry context generated for this invocation. */ diff --git a/crates/fabric-cli/src/presets.rs b/crates/fabric-cli/src/presets.rs index e39fca5df..fbe0ff8c4 100644 --- a/crates/fabric-cli/src/presets.rs +++ b/crates/fabric-cli/src/presets.rs @@ -287,6 +287,7 @@ fn config( artifacts: None, timeout_seconds: None, max_turns: None, + keep_state: false, extensions: BTreeMap::new(), }, environment: Some(EnvironmentConfig { diff --git a/crates/fabric-cli/templates/rust/main.rs.tmpl b/crates/fabric-cli/templates/rust/main.rs.tmpl index 4055d76af..bb6c81dfe 100644 --- a/crates/fabric-cli/templates/rust/main.rs.tmpl +++ b/crates/fabric-cli/templates/rust/main.rs.tmpl @@ -38,6 +38,7 @@ fn build_config() -> FabricConfig { artifacts: None, timeout_seconds: {{TIMEOUT_SECONDS}}, max_turns: {{MAX_TURNS}}, + keep_state: false, extensions: BTreeMap::new(), }, environment: Some(EnvironmentConfig { diff --git a/crates/fabric-core/src/config.rs b/crates/fabric-core/src/config.rs index 72cc01947..b3ff649ee 100644 --- a/crates/fabric-core/src/config.rs +++ b/crates/fabric-core/src/config.rs @@ -873,6 +873,9 @@ pub enum AdapterConfigField { /// Per-invocation harness turn limit. #[serde(rename = "runtime.max_turns")] MaxTurns, + /// Agent-named state folder kept across runtimes. + #[serde(rename = "runtime.keep_state")] + KeepState, /// Adapter-native tool names to expose. #[serde(rename = "tools.enabled")] EnabledTools, @@ -1063,6 +1066,11 @@ pub struct RuntimeConfig { #[serde(default, skip_serializing_if = "Option::is_none")] #[schemars(range(min = 1, max = u32::MAX))] pub max_turns: Option, + /// Keep the adapter's native state in a folder named after the agent, so + /// every runtime of the agent uses the same folder. Requires an artifact + /// directory and an adapter that accepts `runtime.keep_state`. + #[serde(default, skip_serializing_if = "std::ops::Not::not")] + pub keep_state: bool, /// Additive normalized runtime fields. #[serde(default, flatten)] pub extensions: BTreeMap, @@ -1927,6 +1935,12 @@ pub(crate) fn validate_config(config: &FabricConfig) -> Result<()> { if config.runtime.max_turns == Some(0) { return invalid_config("runtime.max_turns", "must be greater than zero"); } + if config.runtime.keep_state && !is_one_folder_name(&config.metadata.name) { + return invalid_config( + "metadata.name", + "must be usable as one folder name when runtime.keep_state is set: not empty, `.` or `..`, and without `/` or `\\`", + ); + } if let Some(timeout) = config.runtime.timeout_seconds && (!timeout.is_finite() || timeout <= 0.0 @@ -2388,6 +2402,11 @@ fn validate_names(field: &str, names: &[String]) -> Result<()> { Ok(()) } +/// Whether a name can be one path component on every platform Fabric runs on. +fn is_one_folder_name(name: &str) -> bool { + !name.trim().is_empty() && name != "." && name != ".." && !name.contains(['/', '\\']) +} + fn invalid_config(field: impl Into, reason: impl Into) -> Result { Err(FabricError::InvalidConfig { field: field.into(), @@ -2811,6 +2830,13 @@ pub(crate) fn adapter_config_compatibility_issues( )); } } + if config.runtime.keep_state && !accepts(AdapterConfigField::KeepState) { + issues.push(incompatible( + "runtime.keep_state".to_string(), + "the adapter does not declare that it keeps its state in an agent-named folder" + .to_string(), + )); + } if config.runtime.max_turns.is_some() && !accepts(AdapterConfigField::MaxTurns) { issues.push(incompatible( "runtime.max_turns".to_string(), diff --git a/crates/fabric-core/src/error.rs b/crates/fabric-core/src/error.rs index 056c0c034..856123b73 100644 --- a/crates/fabric-core/src/error.rs +++ b/crates/fabric-core/src/error.rs @@ -255,6 +255,14 @@ pub enum FabricError { /// Service handle id. service_id: String, }, + /// Another runtime holds the agent's kept state folder. + #[error( + "agent state folder {path} is in use by another runtime; stop that runtime before starting another" + )] + StateInUse { + /// The agent's state folder. + path: PathBuf, + }, /// A service cannot be released while runtimes still use it. #[error("service `{service_id}` has active runtimes: {runtime_ids:?}")] ServiceInUse { diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index d7041c9ed..4c3749639 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -476,6 +476,11 @@ pub struct RuntimeContext { /// Present on every invocation, shortly before Fabric's own invocation timeout. #[serde(default, skip_serializing_if = "Option::is_none")] pub deadline_millis: Option, + /// Absolute folder for the adapter's native state, present when + /// `runtime.keep_state` is set. Every runtime of the agent gets the same + /// folder, and Fabric lets only one running runtime use it at a time. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub state_dir: Option, } /// Runtime telemetry config passed to adapters. @@ -892,6 +897,8 @@ struct LocalAdapterHost { relay_config: Option, // Adapter startup values stay in memory, never in a serialized handle or plan. environment_env: BTreeMap, + // Held while the host runs; dropping the host releases the agent's state folder. + _state_lock: Option, } struct LocalServiceRecord { @@ -2650,6 +2657,7 @@ fn spawn_local_host( relay_config: Option, environment_env: BTreeMap, ) -> Result { + let state_lock = lock_agent_state(plan, &artifacts)?; let runtime_dir = local_host_directory(&runtime.runtime_id); std::fs::create_dir_all(&runtime_dir).map_err(|source| FabricError::Write { path: runtime_dir.clone(), @@ -2779,6 +2787,7 @@ fn spawn_local_host( artifacts, relay_config, environment_env, + _state_lock: state_lock, }) } @@ -3479,9 +3488,66 @@ fn adapter_runtime_context( artifacts: artifacts.clone(), telemetry: runtime_telemetry_context(plan, relay_config), deadline_millis: None, + state_dir: agent_state_dir(plan, artifacts)?, }) } +/// The folder that keeps an agent's native state across its runtimes when +/// `runtime.keep_state` is set: `/.fabric/state//`. +/// The adapter ID keeps another harness from reading the state if the agent's +/// adapter changes. +fn agent_state_dir(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result> { + if !plan.config.runtime.keep_state { + return Ok(None); + } + let Some(root) = artifacts.root.as_ref() else { + return Err(FabricError::InvalidConfig { + field: "runtime.keep_state".to_string(), + reason: "requires an artifact directory, from runtime.artifacts or the environment" + .to_string(), + }); + }; + let adapter = adapter_id(plan).unwrap_or_else(|| harness(plan)); + absolute_path( + root.join(".fabric") + .join("state") + .join(adapter) + .join(&plan.agent_name), + ) + .map(Some) +} + +/// Takes the agent's state folder for one runtime. The lock lasts while the +/// returned file is open, and the operating system releases it when this +/// process exits, so a crashed runtime leaves no stale lock behind. +fn lock_agent_state(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result> { + let Some(state_dir) = agent_state_dir(plan, artifacts)? else { + return Ok(None); + }; + std::fs::create_dir_all(&state_dir).map_err(|source| FabricError::Write { + path: state_dir.clone(), + source, + })?; + let lock_path = state_dir.join(".fabric-state.lock"); + let file = File::options() + .create(true) + .write(true) + .truncate(false) + .open(&lock_path) + .map_err(|source| FabricError::Write { + path: lock_path.clone(), + source, + })?; + match file.try_lock() { + Ok(()) => Ok(Some(file)), + Err(std::fs::TryLockError::WouldBlock) => Err(FabricError::StateInUse { path: state_dir }), + Err(std::fs::TryLockError::Error(source)) => Err(FabricError::Write { + path: lock_path, + source, + }), + } +} + fn resolve_named_environment(plan: &RunPlan, env: &mut BTreeMap) -> Result<()> { for name in plan .environment_plan @@ -4453,6 +4519,7 @@ for line in sys.stdin: "normalized_env": os.environ.get("FABRIC_NORMALIZED_ENV"), "context_env": invocation["runtime_context"]["environment"].get("env", {}), "deadline_millis": invocation["runtime_context"].get("deadline_millis"), + "state_dir": invocation["runtime_context"].get("state_dir"), } if MODE in {"adapter_reported_failure", "blank_error_code"}: result = { @@ -4819,6 +4886,74 @@ for line in sys.stdin: let _ = fs::remove_dir_all(root); } + fn local_host_plan_keeping_state() -> (PathBuf, RunPlan) { + let (root, plan) = local_host_plan("success"); + let descriptor_path = root.join("adapters/local-host/local-host.fabric-adapter.json"); + let mut descriptor: Value = serde_json::from_str( + &fs::read_to_string(&descriptor_path).expect("read adapter descriptor"), + ) + .expect("parse adapter descriptor"); + descriptor["config"] = serde_json::json!({"accepts": ["runtime.keep_state"]}); + fs::write(&descriptor_path, descriptor.to_string()).expect("write adapter descriptor"); + let mut config = plan.config; + config.metadata.name = "assistant".to_string(); + config.runtime.keep_state = true; + let plan = resolve_run_plan_from_config(config, ResolveContext::new(&root)) + .expect("resolve keep_state plan"); + (root, plan) + } + + #[test] + fn keep_state_gives_an_agents_runtimes_one_state_folder_one_at_a_time() { + let (root, plan) = local_host_plan_keeping_state(); + let state_dir = |runtime: &RuntimeHandle| { + invoke_runtime(&plan, runtime, RunRequest::text("state")) + .expect("invocation") + .output["state_dir"] + .clone() + }; + + let first = start_runtime(&plan).expect("start first runtime"); + let error = start_runtime(&plan).expect_err("a second runtime must not share the folder"); + assert!(matches!(error, FabricError::StateInUse { .. }), "{error}"); + let first_dir = state_dir(&first); + stop_runtime(&plan, &first).expect("stop first runtime"); + let second = start_runtime(&plan).expect("start once the first runtime stopped"); + let second_dir = state_dir(&second); + stop_runtime(&plan, &second).expect("stop second runtime"); + + let expected = root.join("artifacts/.fabric/state/acme.fabric.local-host/assistant"); + assert_ne!(first.runtime_id, second.runtime_id); + assert_eq!(second_dir, first_dir); + let first_dir = first_dir.as_str().expect("state_dir in runtime context"); + assert!(Path::new(first_dir).is_absolute(), "{first_dir}"); + assert_eq!(Path::new(first_dir), expected); + assert!(expected.is_dir()); + let _ = fs::remove_dir_all(root); + } + + #[test] + fn keep_state_planning_rejects_unaccepting_adapters_and_unsafe_agent_names() { + let (root, accepting) = local_host_plan_keeping_state(); + let (plain_root, plain) = local_host_plan("success"); + let mut not_accepted = plain.config; + not_accepted.runtime.keep_state = true; + let mut cases = vec![(&plain_root, not_accepted, "runtime.keep_state")]; + for name in ["..", "a/b", "a\\b"] { + let mut config = accepting.config.clone(); + config.metadata.name = name.to_string(); + cases.push((&root, config, "metadata.name")); + } + + for (base_dir, config, field) in cases { + let error = resolve_run_plan_from_config(config, ResolveContext::new(base_dir)) + .expect_err(field); + assert!(error.to_string().contains(field), "{field}: {error}"); + } + let _ = fs::remove_dir_all(root); + let _ = fs::remove_dir_all(plain_root); + } + fn local_host_plan_with_env_name(name: &str) -> (PathBuf, RunPlan) { let (root, plan) = local_host_plan("success"); let mut config = plan.config; @@ -4846,6 +4981,7 @@ for line in sys.stdin: result.output["context_env"]["FABRIC_NORMALIZED_ENV"], serde_json::json!("visible") ); + assert_eq!(result.output["state_dir"], Value::Null); let persisted_invocation: Value = serde_json::from_str( &fs::read_to_string( result.metadata["fabric_invocation"] diff --git a/docs/adapter-contract/tutorials/adapter-descriptor.md b/docs/adapter-contract/tutorials/adapter-descriptor.md index b32a3d154..27d98f9f5 100644 --- a/docs/adapter-contract/tutorials/adapter-descriptor.md +++ b/docs/adapter-contract/tutorials/adapter-descriptor.md @@ -102,6 +102,11 @@ schema enum for the exact accepted values. Planning rejects configured normalized behavior outside the declared surface. NeMo Fabric does not silently remove unsupported fields. +Accept `runtime.keep_state` only when the adapter keeps all of its native +state in `RuntimeContext.state_dir` when that field is present. Every runtime +of the agent then receives the same folder, so a later runtime finds the +earlier runtime's sessions, memory, and other harness files. + When an adapter accepts `instructions.system`, declare the exact supported modes in `config.system_instruction_modes`. `replace` discards the harness default system instruction. `append` preserves the harness default and adds the diff --git a/docs/adapter-contract/tutorials/execution.md b/docs/adapter-contract/tutorials/execution.md index 367575b19..8bcc786fc 100644 --- a/docs/adapter-contract/tutorials/execution.md +++ b/docs/adapter-contract/tutorials/execution.md @@ -131,6 +131,7 @@ value: | `artifacts` | Lists artifacts visible when the operation begins. | | `telemetry` | Supplies invocation telemetry context, including generated Relay configuration when enabled. | | `deadline_millis` | Gives the Unix time in milliseconds by which an invocation should return. NeMo Fabric's own invocation timeout fires shortly after and kills the host with its descendant processes; the gap is shorter for very short timeouts. Keep cleanup after the deadline brief, or the invocation fails with `host_timeout` instead of returning the adapter's result. | +| `state_dir` | Present when the config sets `runtime.keep_state` and the adapter accepts it. Gives an absolute folder, `/.fabric/state//`, that every runtime of the agent receives. Keep the harness's native state there instead of in a per-runtime folder. NeMo Fabric creates the folder, fails `start` while another runtime holds it, and never deletes it. | Use the canonical [`runtime-context.schema.json`](https://github.com/NVIDIA/NeMo-Fabric/blob/main/schemas/adapter-contract/runtime-context.schema.json) diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx index dcf56eaf5..39cdfb55b 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/enum-adapterconfigfield.mdx @@ -18,6 +18,7 @@ pub enum AdapterConfigField { ModelMaxTokens, SystemInstructions, MaxTurns, + KeepState, EnabledTools, ToolDefinitions, BlockedTools, @@ -75,6 +76,12 @@ Portable system instructions. Per-invocation harness turn limit. +### `KeepState` + +
+ +Agent-named state folder kept across runtimes. + ### `EnabledTools`
diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx index ad38ed633..2658123ab 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/config/struct-runtimeconfig.mdx @@ -9,7 +9,7 @@ SPDX-License-Identifier: Apache-2.0 */} Generated from `cargo doc --no-deps -p nemo-fabric-core`. -
String,\n    pub output_schema: String,\n    pub artifacts: Option<PathBuf>,\n    pub timeout_seconds: Option<f64>,\n    pub max_turns: Option<u32>,\n    pub extensions: BTreeMap<String, Value>,\n}"}} />
+
String,\n    pub output_schema: String,\n    pub artifacts: Option<PathBuf>,\n    pub timeout_seconds: Option<f64>,\n    pub max_turns: Option<u32>,\n    pub keep_state: bool,\n    pub extensions: BTreeMap<String, Value>,\n}"}} />
Invocation runtime contract. @@ -35,6 +35,10 @@ Maximum duration of one invocation in seconds. Maximum number of harness turns within one invocation. +### `keep_state: bool` + +Keep the adapter's native state in a folder named after the agent, so every runtime of the agent uses the same folder. Requires an artifact directory and an adapter that accepts `runtime.keep_state`. + ### `extensions: BTreeMap` Additive normalized runtime fields. diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx index 18ad7379a..b3500721a 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/error/enum-fabricerror.mdx @@ -9,7 +9,7 @@ SPDX-License-Identifier: Apache-2.0 */} Generated from `cargo doc --no-deps -p nemo-fabric-core`. -
PathBuf,\n        source: Error,\n    },\n    PathNotFound(PathBuf),\n    UnknownAdapter {\n        adapter_id: String,\n        available: Vec<String>,\n    },\n    UnknownAdapterTarget {\n        target_id: String,\n        available: Vec<String>,\n    },\n    AmbiguousDescriptor {\n        descriptor_kind: &'static str,\n        id: String,\n        paths: Vec<PathBuf>,\n    },\n    AdapterDescriptorMismatch {\n        path: PathBuf,\n        field: &'static str,\n        expected: String,\n        actual: String,\n    },\n    AdapterDescriptorUnsupported {\n        adapter_id: String,\n        field: &'static str,\n        value: String,\n    },\n    InvalidAdapterDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidAdapterTargetDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidHarnessSettings {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        settings_path: String,\n        reason: String,\n    },\n    InvalidWorkflow {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        workflow_path: String,\n        reason: String,\n    },\n    InvalidToolDefinition {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        definition_path: String,\n        reason: String,\n    },\n    InvalidAdapterExtension {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        extension_path: String,\n        reason: String,\n    },\n    InvalidConfig {\n        field: String,\n        reason: String,\n    },\n    AdapterCompatibility {\n        adapter_id: String,\n        field: String,\n        reason: String,\n    },\n    UnknownSchema {\n        schema: String,\n        available: Vec<String>,\n    },\n    UnsupportedRuntimeAdapter {\n        harness: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedRuntimeCapability {\n        adapter_id: String,\n        capability: &'static str,\n    },\n    InvalidOpenAiStreamTransport {\n        field: &'static str,\n        reason: &'static str,\n    },\n    AdapterLifecycleOperation {\n        operation: &'static str,\n        runtime_id: String,\n        code: String,\n        message: String,\n        diagnostics: String,\n    },\n    RuntimeHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        runtime_id: String,\n    },\n    ServiceHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        service_id: String,\n    },\n    ServiceInUse {\n        service_id: String,\n        runtime_ids: Vec<String>,\n    },\n    ServiceNotActive {\n        service_id: String,\n    },\n    UnsupportedEnvironmentProvider {\n        provider: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedEnvironmentRelease {\n        provider: String,\n    },\n    EnvironmentProviderOperation {\n        provider: String,\n        operation: String,\n        code: String,\n        message: String,\n    },\n    EnvironmentInUse {\n        environment_id: String,\n        runtime_id: String,\n    },\n    EnvironmentReleaseInProgress {\n        environment_id: String,\n    },\n    EnvironmentHandleRequired {\n        provider: String,\n    },\n    EnvironmentHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        environment_id: String,\n    },\n    ResourceObservationUnavailable {\n        runtime_id: String,\n        reason: String,\n    },\n    ResourceObservationUnsupported {\n        runtime_id: String,\n        reason: String,\n    },\n    InvalidProcessSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    InvalidPythonSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    PythonInterpreterUnavailable {\n        path: PathBuf,\n        origin: String,\n        reason: String,\n    },\n    ProcessRunner {\n        command: String,\n        source: Error,\n    },\n    SerializeJson(Error),\n    Read {\n        path: PathBuf,\n        source: Error,\n    },\n    Write {\n        path: PathBuf,\n        source: Error,\n    },\n    ParseJson {\n        path: PathBuf,\n        source: Error,\n    },\n}"}} />
+
PathBuf,\n        source: Error,\n    },\n    PathNotFound(PathBuf),\n    UnknownAdapter {\n        adapter_id: String,\n        available: Vec<String>,\n    },\n    UnknownAdapterTarget {\n        target_id: String,\n        available: Vec<String>,\n    },\n    AmbiguousDescriptor {\n        descriptor_kind: &'static str,\n        id: String,\n        paths: Vec<PathBuf>,\n    },\n    AdapterDescriptorMismatch {\n        path: PathBuf,\n        field: &'static str,\n        expected: String,\n        actual: String,\n    },\n    AdapterDescriptorUnsupported {\n        adapter_id: String,\n        field: &'static str,\n        value: String,\n    },\n    InvalidAdapterDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidAdapterTargetDescriptor {\n        path: PathBuf,\n        message: String,\n    },\n    InvalidHarnessSettings {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        settings_path: String,\n        reason: String,\n    },\n    InvalidWorkflow {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        workflow_path: String,\n        reason: String,\n    },\n    InvalidToolDefinition {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        definition_path: String,\n        reason: String,\n    },\n    InvalidAdapterExtension {\n        adapter_id: String,\n        descriptor_source: DescriptorSource,\n        descriptor_path: PathBuf,\n        extension_path: String,\n        reason: String,\n    },\n    InvalidConfig {\n        field: String,\n        reason: String,\n    },\n    AdapterCompatibility {\n        adapter_id: String,\n        field: String,\n        reason: String,\n    },\n    UnknownSchema {\n        schema: String,\n        available: Vec<String>,\n    },\n    UnsupportedRuntimeAdapter {\n        harness: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedRuntimeCapability {\n        adapter_id: String,\n        capability: &'static str,\n    },\n    InvalidOpenAiStreamTransport {\n        field: &'static str,\n        reason: &'static str,\n    },\n    AdapterLifecycleOperation {\n        operation: &'static str,\n        runtime_id: String,\n        code: String,\n        message: String,\n        diagnostics: String,\n    },\n    RuntimeHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        runtime_id: String,\n    },\n    ServiceHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        service_id: String,\n    },\n    StateInUse {\n        path: PathBuf,\n    },\n    ServiceInUse {\n        service_id: String,\n        runtime_ids: Vec<String>,\n    },\n    ServiceNotActive {\n        service_id: String,\n    },\n    UnsupportedEnvironmentProvider {\n        provider: String,\n        adapter_kind: AdapterKind,\n    },\n    UnsupportedEnvironmentRelease {\n        provider: String,\n    },\n    EnvironmentProviderOperation {\n        provider: String,\n        operation: String,\n        code: String,\n        message: String,\n    },\n    EnvironmentInUse {\n        environment_id: String,\n        runtime_id: String,\n    },\n    EnvironmentReleaseInProgress {\n        environment_id: String,\n    },\n    EnvironmentHandleRequired {\n        provider: String,\n    },\n    EnvironmentHandleMismatch {\n        field: &'static str,\n        expected: String,\n        actual: String,\n        environment_id: String,\n    },\n    ResourceObservationUnavailable {\n        runtime_id: String,\n        reason: String,\n    },\n    ResourceObservationUnsupported {\n        runtime_id: String,\n        reason: String,\n    },\n    InvalidProcessSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    InvalidPythonSettings {\n        path: PathBuf,\n        source: Error,\n    },\n    PythonInterpreterUnavailable {\n        path: PathBuf,\n        origin: String,\n        reason: String,\n    },\n    ProcessRunner {\n        command: String,\n        source: Error,\n    },\n    SerializeJson(Error),\n    Read {\n        path: PathBuf,\n        source: Error,\n    },\n    Write {\n        path: PathBuf,\n        source: Error,\n    },\n    ParseJson {\n        path: PathBuf,\n        source: Error,\n    },\n}"}} />
Errors raised by NeMo Fabric config loading and validation. @@ -453,6 +453,18 @@ Actual value. Service handle id. +### `StateInUse` + +
+ +Another runtime holds the agent's kept state folder. + +#### Fields + +##### `path: PathBuf` + +The agent's state folder. + ### `ServiceInUse`
diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx index 625527702..a4e24f344 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/runtime/struct-runtimecontext.mdx @@ -9,7 +9,7 @@ SPDX-License-Identifier: Apache-2.0 */} Generated from `cargo doc --no-deps -p nemo-fabric-core`. -
String,\n    pub invocation_id: String,\n    pub request_id: String,\n    pub environment: EnvironmentHandle,\n    pub artifacts: ArtifactManifest,\n    pub telemetry: Option<RuntimeTelemetryContext>,\n    pub deadline_millis: Option<u64>,\n}"}} />
+
String,\n    pub invocation_id: String,\n    pub request_id: String,\n    pub environment: EnvironmentHandle,\n    pub artifacts: ArtifactManifest,\n    pub telemetry: Option<RuntimeTelemetryContext>,\n    pub deadline_millis: Option<u64>,\n    pub state_dir: Option<PathBuf>,\n}"}} />
Context generated for one invocation of a started runtime. @@ -43,6 +43,10 @@ Runtime telemetry context generated for this invocation. Unix time in milliseconds by which the adapter should return its result. Present on every invocation, shortly before Fabric's own invocation timeout. +### `state_dir: Option` + +Absolute folder for the adapter's native state, present when `runtime.keep_state` is set. Every runtime of the agent gets the same folder, and Fabric lets only one running runtime use it at a time. + ## Trait Implementations ### `impl Clone for RuntimeContext` diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index f93512c2b..dc1c85932 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -858,6 +858,17 @@ on one live thread, Deep Agents invokes one compiled graph and checkpointer, Hermes Agent reuses one agent and session database, and Claude keeps one connected SDK client. Harness-native identifiers remain adapter-internal. +### Keep Agent State Across Runtimes + +By default, each runtime keeps its native state in its own folder, so a new +runtime starts empty. Set `"keep_state": true` in the config's `runtime` +mapping to give every runtime of the agent one folder instead: +`/.fabric/state//`. The config needs an +artifact directory, and `metadata.name` must be usable as one folder name. +Only one runtime can use the folder at a time: `start_runtime(...)` fails while +another runtime of the agent runs. Planning fails for an adapter that doesn't +declare `runtime.keep_state`. + ## Runtime Resource Snapshots `Runtime.resource_snapshot()` returns a timestamped `RuntimeResourceSnapshot` diff --git a/schemas/adapter-contract/adapter-descriptor.schema.json b/schemas/adapter-contract/adapter-descriptor.schema.json index 637dfbf2a..b62f59d20 100644 --- a/schemas/adapter-contract/adapter-descriptor.schema.json +++ b/schemas/adapter-contract/adapter-descriptor.schema.json @@ -38,6 +38,11 @@ "description": "Per-invocation harness turn limit.", "type": "string" }, + { + "const": "runtime.keep_state", + "description": "Agent-named state folder kept across runtimes.", + "type": "string" + }, { "const": "tools.enabled", "description": "Adapter-native tool names to expose.", diff --git a/schemas/adapter-contract/adapter-invocation.schema.json b/schemas/adapter-contract/adapter-invocation.schema.json index f86a452b8..183c92248 100644 --- a/schemas/adapter-contract/adapter-invocation.schema.json +++ b/schemas/adapter-contract/adapter-invocation.schema.json @@ -210,6 +210,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/schemas/adapter-contract/openai-stream-invocation.schema.json b/schemas/adapter-contract/openai-stream-invocation.schema.json index 364e2f3ff..17d0efc1a 100644 --- a/schemas/adapter-contract/openai-stream-invocation.schema.json +++ b/schemas/adapter-contract/openai-stream-invocation.schema.json @@ -300,6 +300,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/schemas/adapter-contract/runtime-context.schema.json b/schemas/adapter-contract/runtime-context.schema.json index 62bc7927c..4c1cbb51d 100644 --- a/schemas/adapter-contract/runtime-context.schema.json +++ b/schemas/adapter-contract/runtime-context.schema.json @@ -214,6 +214,13 @@ "description": "Runtime handle id.", "type": "string" }, + "state_dir": { + "description": "Absolute folder for the adapter's native state, present when\n`runtime.keep_state` is set. Every runtime of the agent gets the same\nfolder, and Fabric lets only one running runtime use it at a time.", + "type": [ + "string", + "null" + ] + }, "telemetry": { "anyOf": [ { diff --git a/schemas/sdk/agent.schema.json b/schemas/sdk/agent.schema.json index 63bbcf0d6..f69595c6a 100644 --- a/schemas/sdk/agent.schema.json +++ b/schemas/sdk/agent.schema.json @@ -1495,6 +1495,10 @@ "description": "Input schema label.", "type": "string" }, + "keep_state": { + "description": "Keep the adapter's native state in a folder named after the agent, so\nevery runtime of the agent uses the same folder. Requires an artifact\ndirectory and an adapter that accepts `runtime.keep_state`.", + "type": "boolean" + }, "max_turns": { "description": "Maximum number of harness turns within one invocation.", "format": "uint32", diff --git a/schemas/sdk/run-plan.schema.json b/schemas/sdk/run-plan.schema.json index a15e3e678..ad240c67e 100644 --- a/schemas/sdk/run-plan.schema.json +++ b/schemas/sdk/run-plan.schema.json @@ -38,6 +38,11 @@ "description": "Per-invocation harness turn limit.", "type": "string" }, + { + "const": "runtime.keep_state", + "description": "Agent-named state folder kept across runtimes.", + "type": "string" + }, { "const": "tools.enabled", "description": "Adapter-native tool names to expose.", @@ -2964,6 +2969,10 @@ "description": "Input schema label.", "type": "string" }, + "keep_state": { + "description": "Keep the adapter's native state in a folder named after the agent, so\nevery runtime of the agent uses the same folder. Requires an artifact\ndirectory and an adapter that accepts `runtime.keep_state`.", + "type": "boolean" + }, "max_turns": { "description": "Maximum number of harness turns within one invocation.", "format": "uint32", diff --git a/skills/nemo-fabric-build-adapter/SKILL.md b/skills/nemo-fabric-build-adapter/SKILL.md index 9dfc2389c..e195634f5 100644 --- a/skills/nemo-fabric-build-adapter/SKILL.md +++ b/skills/nemo-fabric-build-adapter/SKILL.md @@ -122,6 +122,9 @@ adapter boundary: the task environment. - Read identity, environment, artifacts, telemetry, and the invocation deadline (`deadline_millis`) from `RuntimeContext`, not from workflow settings. +- If the adapter declares `runtime.keep_state`, keep all native state in + `RuntimeContext.state_dir` when it is present. Every runtime of the agent + receives the same folder. Reject unsupported values with stable, safe error codes. Do not log complete configs, environment values, headers, credentials, or arbitrary user input. From 35658a6a00bef5f929800519eb82c5a47ae3eaa7 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 05:18:01 -0700 Subject: [PATCH 07/54] feat: keep Hermes's home in the agent's state folder The Hermes adapter now accepts `runtime.keep_state`. When the runtime context has a state folder, the adapter uses it as the Hermes home, so every runtime of the agent uses the same session database, memory, skills and logs; otherwise the home stays `/.fabric/hermes/runtimes/`. Each runtime still starts a new session, and earlier sessions stay in the database. The API server's token moves with the home, to `interfaces/api.token`. The two descriptor copies and the catalog are mechanical. Signed-off-by: Carlos Villela --- .../python/hermes/hermes.fabric-adapter.json | 3 ++- .../nemo_fabric_adapters/hermes/adapter.py | 22 ++++++++++++++----- .../hermes/hermes.fabric-adapter.json | 3 ++- docs/integrations/harness/hermes.mdx | 13 ++++++++--- docs/sdk/python.mdx | 2 +- .../hermes/hermes.fabric-adapter.json | 3 ++- .../nemo_fabric_adapter_catalog/catalog.json | 5 +++-- tests/adapters/test_hermes_adapter.py | 19 ++++++++++++++++ 8 files changed, 55 insertions(+), 15 deletions(-) diff --git a/adapters/python/hermes/hermes.fabric-adapter.json b/adapters/python/hermes/hermes.fabric-adapter.json index bee24bf18..d0891ad47 100644 --- a/adapters/python/hermes/hermes.fabric-adapter.json +++ b/adapters/python/hermes/hermes.fabric-adapter.json @@ -76,7 +76,7 @@ }, "required": ["port"], "additionalProperties": false, - "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: /.fabric/hermes/runtimes/, or the agent's state folder with runtime.keep_state." }, "dashboard": { "type": "object", @@ -131,6 +131,7 @@ "models.max_tokens", "instructions.system", "runtime.max_turns", + "runtime.keep_state", "tools.enabled", "tools.blocked", "mcp", 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 bc12cf9d9..265630bf6 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -108,12 +108,8 @@ async def start(self, payload: dict[str, Any]) -> None: model_config = configuration._selected_model(agent_config) self._model_config = model_config self._runtime_id = runtime_context.runtime_id - self._hermes_home = ( - _artifact_root(runtime_context, common_utils.base_dir(payload)) - / ".fabric" - / "hermes" - / "runtimes" - / runtime_context.runtime_id + self._hermes_home = _hermes_home( + runtime_context, common_utils.base_dir(payload) ) self._hermes_home.mkdir(parents=True, exist_ok=True) os.environ["HOME"] = str(self._hermes_home) @@ -691,6 +687,20 @@ async def stop(self) -> None: ) from errors[0] +def _hermes_home(runtime_context: RuntimeContext, base_dir: str) -> Path: + """Return the agent's state folder when Fabric keeps state across runtimes, + otherwise this runtime's own folder.""" + if runtime_context.state_dir: + return Path(runtime_context.state_dir) + return ( + _artifact_root(runtime_context, base_dir) + / ".fabric" + / "hermes" + / "runtimes" + / runtime_context.runtime_id + ) + + def _artifact_root(runtime_context: RuntimeContext, base_dir: str) -> Path: root = runtime_context.artifacts.root if root: 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 bee24bf18..d0891ad47 100644 --- a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json +++ b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json @@ -76,7 +76,7 @@ }, "required": ["port"], "additionalProperties": false, - "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: /.fabric/hermes/runtimes/, or the agent's state folder with runtime.keep_state." }, "dashboard": { "type": "object", @@ -131,6 +131,7 @@ "models.max_tokens", "instructions.system", "runtime.max_turns", + "runtime.keep_state", "tools.enabled", "tools.blocked", "mcp", diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index ab3e2506e..8ea169cd1 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -94,6 +94,14 @@ Use `runtime.max_turns` to set the Hermes agent-loop budget. The adapter maps that normalized field to `AIAgent.max_iterations`; `max_iterations` is not a Hermes harness setting. +By default, the Hermes home is +`/.fabric/hermes/runtimes/`, so runtimes don't share +config or the session database. With `runtime.keep_state`, it is the agent's +state folder, `/.fabric/state/nvidia.fabric.hermes/`: +every runtime of the agent then uses the same session database, memory, skills +and logs. Each runtime starts a new session, and earlier sessions stay in the +database. The adapter rewrites `config.yaml` at each start. + ## Understand the Runtime Lifecycle Each NeMo Fabric runtime creates one Hermes Agent `AIAgent` and one `SessionDB`. @@ -131,9 +139,8 @@ harness = HarnessConfig( start stops the children it started and leaves no token. Set `enabled` to `false` to keep a configured interface off. - Once every enabled interface passes, the adapter writes the API server's - bearer token, generated at each start, to - `/.fabric/hermes/runtimes//interfaces/api.token` - with mode `0600`. Send it as `Authorization: Bearer `. Only the + bearer token, generated at each start, to `interfaces/api.token` in the + Hermes home with mode `0600`. Send it as `Authorization: Bearer `. Only the gateway child receives it. Processes that run as the runtime's user, including the agent's own tools, can read it. - The dashboard has no sign-in. On loopback, Hermes embeds its session token in diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index dc1c85932..ed7823dd8 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -867,7 +867,7 @@ mapping to give every runtime of the agent one folder instead: artifact directory, and `metadata.name` must be usable as one folder name. Only one runtime can use the folder at a time: `start_runtime(...)` fails while another runtime of the agent runs. Planning fails for an adapter that doesn't -declare `runtime.keep_state`. +declare `runtime.keep_state`; Hermes Agent's adapter declares it. ## Runtime Resource Snapshots diff --git a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json index bee24bf18..d0891ad47 100644 --- a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json +++ b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json @@ -76,7 +76,7 @@ }, "required": ["port"], "additionalProperties": false, - "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token." + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: /.fabric/hermes/runtimes/, or the agent's state folder with runtime.keep_state." }, "dashboard": { "type": "object", @@ -131,6 +131,7 @@ "models.max_tokens", "instructions.system", "runtime.max_turns", + "runtime.keep_state", "tools.enabled", "tools.blocked", "mcp", 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 7d07e98d8..8c3a7c6d0 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 @@ -812,6 +812,7 @@ "models.max_tokens", "instructions.system", "runtime.max_turns", + "runtime.keep_state", "tools.enabled", "tools.blocked", "mcp", @@ -849,7 +850,7 @@ "properties": { "api": { "additionalProperties": false, - "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to /.fabric/hermes/runtimes//interfaces/api.token.", + "description": "Hermes's API server, run by a gateway child. After every enabled interface starts, the adapter writes its bearer token to interfaces/api.token in the Hermes home: /.fabric/hermes/runtimes/, or the agent's state folder with runtime.keep_state.", "properties": { "enabled": { "default": true, @@ -973,7 +974,7 @@ "name": "nemo-fabric-adapters-hermes", "version": "0.7.0" }, - "sha256": "8ed091b3214e34c21757fd0e2fbd24d843006ebb596490f4924a81207a896099", + "sha256": "25e791ea0eaa1fc38120afb1dfe874e7627a0316e44f10bc4c979d4890d4e9a0", "source": "adapters/python/hermes/hermes.fabric-adapter.json" }, "nvidia.fabric.kilo": { diff --git a/tests/adapters/test_hermes_adapter.py b/tests/adapters/test_hermes_adapter.py index 964de3c56..8ebeb4b47 100644 --- a/tests/adapters/test_hermes_adapter.py +++ b/tests/adapters/test_hermes_adapter.py @@ -181,6 +181,7 @@ def test_descriptor_uses_the_typed_agent_config_contract(): "models.max_tokens", "instructions.system", "runtime.max_turns", + "runtime.keep_state", "tools.enabled", "tools.blocked", "mcp", @@ -1222,6 +1223,24 @@ def stop_after_environment_setup(*_args, **_kwargs): await adapter.HermesRuntime().start(payload) +@pytest.mark.parametrize("kept", [False, True]) +def test_hermes_home_is_the_agents_state_folder_when_fabric_keeps_state( + tmp_path: Path, kept: bool +): + state_dir = tmp_path / "artifacts/.fabric/state/nvidia.fabric.hermes/assistant" + context = _runtime_context(artifact_root="artifacts").to_mapping() + if kept: + context["state_dir"] = str(state_dir) + + home = adapter._hermes_home(RuntimeContext.from_mapping(context), str(tmp_path)) + + assert home == ( + state_dir + if kept + else tmp_path / "artifacts/.fabric/hermes/runtimes/runtime-1" + ) + + def test_artifact_root_resolves_relative_to_base_dir(tmp_path: Path): assert ( adapter._artifact_root( From dde1815c7bbec98f247246d48e89a44ba6bf6547 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 12:55:45 -0700 Subject: [PATCH 08/54] test: skip the OpenClaw tests that run the mock script where CI can't Signed-off-by: Carlos Villela --- tests/adapters/test_openclaw.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index 1a48e6ce2..5d9f0afb0 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -1426,6 +1426,7 @@ async def test_openclaw_dashboard_serves_control_ui_with_a_token_file( assert not token_path.exists() +@pytest.mark.skipif(sys.platform == "win32", reason="Runs the mock openclaw script directly") @pytest.mark.parametrize("offset", [0, 2]) async def test_openclaw_dashboard_port_in_use_fails_start( mock_openclaw: Path, tmp_path: Path, dashboard_port: int, offset: int @@ -1473,6 +1474,7 @@ async def test_openclaw_services_reject_interfaces( assert runtime._process is None +@pytest.mark.skipif(sys.platform == "win32", reason="Runs the mock openclaw script directly") async def test_openclaw_startup_timeout_bounds_all_of_start( mock_openclaw: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch ): @@ -1497,7 +1499,10 @@ async def test_openclaw_startup_timeout_bounds_all_of_start( assert runtime._process is None -@pytest.mark.skipif(os.name == "nt", reason="Requires POSIX process groups") +@pytest.mark.skipif( + sys.platform in {"darwin", "win32"}, + reason="Starts the mock Gateway, which CI runs only on Linux", +) async def test_openclaw_stop_ends_the_gateway_where_group_signals_are_denied( mock_openclaw: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch ): From 9bfb8e30243f9554fd4c1e91973c5ed4e5791288 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:02:26 -0700 Subject: [PATCH 09/54] fix: let a service share an agent's kept state with one runtime With runtime.keep_state, the service host and the runtime connected to it both took the agent's state lock, so the first connected runtime failed with StateInUse. The service host now holds the lock for its connected runtimes, and a second connected runtime fails with StateInUse while the first runs. An independent runtime still fails while the service holds the lock. The state path also checks RunPlan.agent_name, because a deserialized plan can carry a name such as ../../x that planning never saw. Planning now rejects keep_state without runtime.artifacts or environment.artifacts instead of failing at start. Signed-off-by: Carlos Villela --- crates/fabric-core/src/config.rs | 13 +++- crates/fabric-core/src/runtime.rs | 68 ++++++++++++++++++-- docs/adapter-contract/tutorials/execution.md | 2 +- docs/sdk/python.mdx | 5 +- 4 files changed, 79 insertions(+), 9 deletions(-) diff --git a/crates/fabric-core/src/config.rs b/crates/fabric-core/src/config.rs index b3ff649ee..fbb4788ee 100644 --- a/crates/fabric-core/src/config.rs +++ b/crates/fabric-core/src/config.rs @@ -2403,7 +2403,7 @@ fn validate_names(field: &str, names: &[String]) -> Result<()> { } /// Whether a name can be one path component on every platform Fabric runs on. -fn is_one_folder_name(name: &str) -> bool { +pub(crate) fn is_one_folder_name(name: &str) -> bool { !name.trim().is_empty() && name != "." && name != ".." && !name.contains(['/', '\\']) } @@ -2654,6 +2654,17 @@ fn resolve_selected_descriptors( )?; let resolution = resolve_resolution(&config, descriptor)?; let environment_plan = resolve_environment_plan(&config, &base_dir); + if config.runtime.keep_state + && config.runtime.artifacts.is_none() + && environment_plan + .as_ref() + .is_none_or(|environment| environment.artifacts.is_none()) + { + return invalid_config( + "runtime.keep_state", + "requires an artifact directory, from runtime.artifacts or environment.artifacts", + ); + } validate_control_location(descriptor, environment_plan.as_ref())?; let capability_plan = resolve_capability_plan(&config, &base_dir, adapter_descriptor.as_ref()); if enforce_compatibility { diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index 4c3749639..d07db8bef 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -25,10 +25,10 @@ use crate::agent_execution::{ }; use crate::config::{ AdapterKind, AgentConfig, CapabilityPlan, CapabilityTarget, ControlLocation, - EnvironmentOwnership, RunPlan, TelemetryPlan, validate_adapter_config_compatibility, - validate_agent_config_extensions, validate_agent_run_request_extensions, - validate_agent_run_result_extensions, validate_config, validate_harness_settings, - validate_tool_definitions, validate_workflow, + EnvironmentOwnership, RunPlan, TelemetryPlan, is_one_folder_name, + validate_adapter_config_compatibility, validate_agent_config_extensions, + validate_agent_run_request_extensions, validate_agent_run_result_extensions, validate_config, + validate_harness_settings, validate_tool_definitions, validate_workflow, }; use crate::environment::resolve_environment_provider; use crate::error::{FabricError, Result}; @@ -898,6 +898,7 @@ struct LocalAdapterHost { // Adapter startup values stay in memory, never in a serialized handle or plan. environment_env: BTreeMap, // Held while the host runs; dropping the host releases the agent's state folder. + // A service host holds it for the runtimes connected to the service. _state_lock: Option, } @@ -1040,6 +1041,13 @@ pub fn start_runtime_with_service( service_id: service.service_id.clone(), }); } + // The service host holds the agent's state lock for its connected + // runtimes, so only one of them may run at a time. + if !record.active_runtime_ids.is_empty() + && let Some(path) = agent_state_dir(plan, &record.host.artifacts)? + { + return Err(FabricError::StateInUse { path }); + } let mut current_env = record.host.environment_env.clone(); resolve_named_environment(plan, &mut current_env)?; validate_named_environment(plan, &record.host.environment_env, ¤t_env)?; @@ -2657,7 +2665,12 @@ fn spawn_local_host( relay_config: Option, environment_env: BTreeMap, ) -> Result { - let state_lock = lock_agent_state(plan, &artifacts)?; + // A runtime connected to a service uses the lock its service host holds. + let state_lock = if runtime.service_id.is_none() { + lock_agent_state(plan, &artifacts)? + } else { + None + }; let runtime_dir = local_host_directory(&runtime.runtime_id); std::fs::create_dir_all(&runtime_dir).map_err(|source| FabricError::Write { path: runtime_dir.clone(), @@ -3507,6 +3520,13 @@ fn agent_state_dir(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result (PathBuf, RunPlan) { let (root, plan) = local_host_plan("success"); let mut config = plan.config; diff --git a/docs/adapter-contract/tutorials/execution.md b/docs/adapter-contract/tutorials/execution.md index 8bcc786fc..2170649ab 100644 --- a/docs/adapter-contract/tutorials/execution.md +++ b/docs/adapter-contract/tutorials/execution.md @@ -131,7 +131,7 @@ value: | `artifacts` | Lists artifacts visible when the operation begins. | | `telemetry` | Supplies invocation telemetry context, including generated Relay configuration when enabled. | | `deadline_millis` | Gives the Unix time in milliseconds by which an invocation should return. NeMo Fabric's own invocation timeout fires shortly after and kills the host with its descendant processes; the gap is shorter for very short timeouts. Keep cleanup after the deadline brief, or the invocation fails with `host_timeout` instead of returning the adapter's result. | -| `state_dir` | Present when the config sets `runtime.keep_state` and the adapter accepts it. Gives an absolute folder, `/.fabric/state//`, that every runtime of the agent receives. Keep the harness's native state there instead of in a per-runtime folder. NeMo Fabric creates the folder, fails `start` while another runtime holds it, and never deletes it. | +| `state_dir` | Present when the config sets `runtime.keep_state` and the adapter accepts it. Gives an absolute folder, `/.fabric/state//`, that every runtime of the agent receives. Keep the harness's native state there instead of in a per-runtime folder. A service and the one runtime connected to it at a time receive the same folder. NeMo Fabric creates the folder, fails `start` while another runtime holds it, and never deletes it. | Use the canonical [`runtime-context.schema.json`](https://github.com/NVIDIA/NeMo-Fabric/blob/main/schemas/adapter-contract/runtime-context.schema.json) diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index dc1c85932..b229c5dd1 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -866,8 +866,9 @@ mapping to give every runtime of the agent one folder instead: `/.fabric/state//`. The config needs an artifact directory, and `metadata.name` must be usable as one folder name. Only one runtime can use the folder at a time: `start_runtime(...)` fails while -another runtime of the agent runs. Planning fails for an adapter that doesn't -declare `runtime.keep_state`. +another runtime of the agent runs. A service and one runtime connected to it +share the folder. Planning fails without an artifact directory, or for an +adapter that doesn't declare `runtime.keep_state`. ## Runtime Resource Snapshots From 20118ba53a15c82843b2d98edd334f08297b491a Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:03:41 -0700 Subject: [PATCH 10/54] fix: probe loopback ports exclusively on Windows On Windows, SO_REUSEADDR lets a bind succeed on a port that another socket holds, so port_available could report a busy port as free and Hermes and OpenClaw would skip their port-in-use errors. Use SO_EXCLUSIVEADDRUSE where the platform has it. Signed-off-by: Carlos Villela --- .../src/nemo_fabric_adapters/common/local_interfaces.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py index 70eaf5e3a..69d581faa 100644 --- a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py +++ b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py @@ -15,7 +15,11 @@ def port_available(port: int) -> bool: """Return whether one loopback TCP port is available.""" sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM) try: - sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) + if hasattr(socket, "SO_EXCLUSIVEADDRUSE"): + # On Windows, SO_REUSEADDR lets a bind succeed on a port in use. + sock.setsockopt(socket.SOL_SOCKET, socket.SO_EXCLUSIVEADDRUSE, 1) + else: + sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1) sock.bind(("127.0.0.1", port)) return True except (OSError, OverflowError): From 005aa7ebeb204e1efd650cd245abecda664308cb Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:03:41 -0700 Subject: [PATCH 11/54] fix: keep Hermes interface start and stop within their limits - startup_timeout_seconds now counts from the start of the runtime's start, not from the launch of the interface children, so Hermes's own setup can't push start past NeMo Fabric's 90-second limit. - stop sends SIGKILL to the children even when it's cancelled while it waits for them, so a child that ignores SIGTERM can't keep its port. - The docs say that the gateway also starts other Hermes platforms that its inherited environment configures, such as Telegram. - Tests cover a start that times out after launching a child, a disabled interface, and a cancelled stop. The in-flight request test bounds its wait, and the mock model server reads its scenario before the configured delay. Signed-off-by: Carlos Villela --- adapters/python/hermes/README.md | 2 +- .../python/hermes/hermes.fabric-adapter.json | 2 +- .../nemo_fabric_adapters/hermes/adapter.py | 9 +- .../nemo_fabric_adapters/hermes/interfaces.py | 26 ++-- .../hermes/hermes.fabric-adapter.json | 2 +- docs/integrations/harness/hermes.mdx | 14 ++- .../hermes/hermes.fabric-adapter.json | 2 +- .../nemo_fabric_adapter_catalog/catalog.json | 4 +- tests/_utils/mock_api_server.py | 11 +- tests/adapters/test_hermes_interfaces.py | 116 +++++++++++++++++- 10 files changed, 161 insertions(+), 27 deletions(-) diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 828da6982..d02e72400 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -87,7 +87,7 @@ The descriptor validates the following `harness.settings` fields: | `max_tokens` | positive integer | `512` | Limits the number of tokens in each Hermes model response. | | `terminal_timeout` | positive number | `60` | Limits a Hermes terminal operation in seconds. | | `interfaces.api`, `interfaces.dashboard` | object | None | Serve Hermes's API server or dashboard from a runtime, each with an exact `port` and optional `enabled`; see [Serve the API Server and Dashboard](../../../docs/integrations/harness/hermes.mdx#serve-the-api-server-and-dashboard). | -| `startup_timeout_seconds` | number, at most 75 | `60` | Time for every enabled interface to pass its health check. | +| `startup_timeout_seconds` | number, at most 75 | `60` | Time from the start of the runtime for every enabled interface to pass its health check. | For example: diff --git a/adapters/python/hermes/hermes.fabric-adapter.json b/adapters/python/hermes/hermes.fabric-adapter.json index bee24bf18..b47657f0e 100644 --- a/adapters/python/hermes/hermes.fabric-adapter.json +++ b/adapters/python/hermes/hermes.fabric-adapter.json @@ -106,7 +106,7 @@ "exclusiveMinimum": 0, "maximum": 75, "default": 60, - "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "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 bc12cf9d9..b95f0058e 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -81,6 +81,9 @@ async def start(self, payload: dict[str, Any]) -> None: ) self._stopping = False + # startup_timeout_seconds bounds all of start, so Fabric's start limit + # can't expire first. + started_at = asyncio.get_running_loop().time() try: agent_config = payload.get("config") if not isinstance(agent_config, AgentConfig): @@ -239,7 +242,11 @@ async def start(self, payload: dict[str, Any]) -> None: interface_ports, hermes_home=self._hermes_home, token_path=self._hermes_home / "interfaces" / "api.token", - timeout=interfaces.startup_timeout(self._settings), + timeout=max( + interfaces.startup_timeout(self._settings) + - (asyncio.get_running_loop().time() - started_at), + 0.0, + ), environment=environment, ) self._agent_config = agent_config diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py index 923c21435..96658a5a7 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py @@ -118,17 +118,25 @@ async def stop(self) -> None: token_path, self._token_path = self._token_path, None if token_path is not None: token_path.unlink(missing_ok=True) - children, self._children = self._children, [] - running = [child for child in children if child.process.returncode is None] - for child in running: - common_utils.signal_process_group(child.process.pid, signal.SIGTERM) - if running: - waits = [asyncio.ensure_future(child.process.wait()) for child in running] - _, pending = await asyncio.wait(waits, timeout=STOP_GRACE_SECONDS) + running = [ + child for child in self._children if child.process.returncode is None + ] + pending: set[asyncio.Future[int]] = set() + try: + for child in running: + common_utils.signal_process_group(child.process.pid, signal.SIGTERM) + if running: + waits = [ + asyncio.ensure_future(child.process.wait()) for child in running + ] + _, pending = await asyncio.wait(waits, timeout=STOP_GRACE_SECONDS) + finally: + # Runs even when stop is cancelled, so no child outlives the runtime. for child in running: common_utils.signal_process_group(child.process.pid, signal.SIGKILL) - if pending: - await asyncio.wait(pending) + self._children = [] + if pending: + await asyncio.wait(pending) def _web_dist() -> Path: 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 bee24bf18..b47657f0e 100644 --- a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json +++ b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json @@ -106,7 +106,7 @@ "exclusiveMinimum": 0, "maximum": 75, "default": 60, - "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "required": [], diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index ab3e2506e..6b377efe5 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -122,14 +122,18 @@ harness = HarnessConfig( ) ``` -- The adapter starts `python -m hermes_cli.main gateway run`, with only the API - server enabled, and `python -m hermes_cli.main dashboard --skip-build - --isolated`, on the adapter's interpreter and the runtime's Hermes home, each - on `127.0.0.1` at its port. Each must pass its health check, `GET /health` or +- The adapter starts `python -m hermes_cli.main gateway run` for the API server + and `python -m hermes_cli.main dashboard --skip-build --isolated`, on the + adapter's interpreter and the runtime's Hermes home, each on `127.0.0.1` at + its port. Each must pass its health check, `GET /health` or `GET /api/status`, within `startup_timeout_seconds` (60 by default, at most - 75). `start` fails if a port is in use or a child exits first; a failed + 75) of the runtime's start. `start` fails if a port is in use or a child exits first; a failed start stops the children it started and leaves no token. Set `enabled` to `false` to keep a configured interface off. +- The children inherit the adapter host's environment without its + `API_SERVER_*` variables. The gateway also starts any other Hermes platform + that this environment configures, such as Telegram with `TELEGRAM_BOT_TOKEN` + or webhooks with `WEBHOOK_ENABLED`. - Once every enabled interface passes, the adapter writes the API server's bearer token, generated at each start, to `/.fabric/hermes/runtimes//interfaces/api.token` diff --git a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json index bee24bf18..b47657f0e 100644 --- a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json +++ b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json @@ -106,7 +106,7 @@ "exclusiveMinimum": 0, "maximum": 75, "default": 60, - "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit." } }, "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 7d07e98d8..ec6afab21 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 @@ -941,7 +941,7 @@ }, "startup_timeout_seconds": { "default": 60, - "description": "Time for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit.", + "description": "Time from the start of the runtime for every enabled interface to pass its health check, within NeMo Fabric's 90-second start limit.", "exclusiveMinimum": 0, "maximum": 75, "type": "number" @@ -973,7 +973,7 @@ "name": "nemo-fabric-adapters-hermes", "version": "0.7.0" }, - "sha256": "8ed091b3214e34c21757fd0e2fbd24d843006ebb596490f4924a81207a896099", + "sha256": "d69ab9ae7ccc76f30f70f94a924fd2796bcdffcc05560b1ac2c89dc49bf77ab2", "source": "adapters/python/hermes/hermes.fabric-adapter.json" }, "nvidia.fabric.kilo": { diff --git a/tests/_utils/mock_api_server.py b/tests/_utils/mock_api_server.py index 6e06ebc36..65dbb82ea 100644 --- a/tests/_utils/mock_api_server.py +++ b/tests/_utils/mock_api_server.py @@ -161,20 +161,23 @@ async def chat_completions(request: Request): app.state.chat_authorization_headers.append( request.headers.get("authorization") ) + # Read the scenario before the delay, so a later /_scenario or /_reset + # doesn't change this response. + status_code = app.state.status_code + tool_call = next_tool_call(payload) if status_code == 200 else None if app.state.delay_seconds: await asyncio.sleep(app.state.delay_seconds) - if app.state.status_code != 200: + if status_code != 200: return JSONResponse( - status_code=app.state.status_code, + status_code=status_code, content={ "error": { - "message": f"configured status {app.state.status_code}", + "message": f"configured status {status_code}", "type": "api_error", } }, ) - tool_call = next_tool_call(payload) if tool_call is not None: if payload.get("stream") is True: return StreamingResponse( diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py index f99a17236..244949333 100644 --- a/tests/adapters/test_hermes_interfaces.py +++ b/tests/adapters/test_hermes_interfaces.py @@ -235,8 +235,17 @@ async def test_hermes_stop_cuts_off_an_in_flight_api_request( timeout=90, ) ) - while not requests.get(f"{api_server}/_requests", timeout=5).json(): - await asyncio.sleep(0.1) + try: + deadline = time.monotonic() + 30 + while not requests.get(f"{api_server}/_requests", timeout=5).json(): + assert time.monotonic() < deadline, ( + "the API request never reached the model" + ) + await asyncio.sleep(0.1) + except BaseException: + await runtime.stop() + in_flight.cancel() + raise started = time.monotonic() await runtime.stop() @@ -270,6 +279,109 @@ async def test_hermes_interface_port_in_use_fails_start( assert not _token_path(tmp_path).exists() +def test_hermes_disabled_interface_is_not_started(): + settings = { + "interfaces": { + "api": {"port": 8642, "enabled": False}, + "dashboard": {"port": 9119}, + } + } + + assert interfaces.interface_ports(settings) == {"dashboard": 9119} + + +async def test_hermes_interface_startup_timeout_counts_from_the_start_of_start( + tmp_path: Path, api_server: str, monkeypatch: pytest.MonkeyPatch +): + write_hermes_config = configuration.write_hermes_config + timeouts: list[float] = [] + + def slow_write_hermes_config(*args, **kwargs): + time.sleep(0.5) + return write_hermes_config(*args, **kwargs) + + async def record_start(self, ports, *, timeout, **kwargs): + timeouts.append(timeout) + + monkeypatch.setattr(configuration, "write_hermes_config", slow_write_hermes_config) + monkeypatch.setattr(interfaces.InterfaceChildren, "start", record_start) + runtime = adapter.HermesRuntime() + await runtime.start( + _payload( + tmp_path, + {"startup_timeout_seconds": 5, "interfaces": {"api": {"port": 8642}}}, + base_url=f"{api_server}/v1", + ) + ) + await runtime.stop() + + assert len(timeouts) == 1 + assert timeouts[0] <= 4.5 + + +async def test_hermes_interface_start_timeout_stops_the_started_child( + tmp_path: Path, api_server: str, monkeypatch: pytest.MonkeyPatch +): + create_subprocess_exec = asyncio.create_subprocess_exec + processes: list[asyncio.subprocess.Process] = [] + + async def record_process(*args, **kwargs): + process = await create_subprocess_exec(*args, **kwargs) + processes.append(process) + return process + + monkeypatch.setattr(interfaces.asyncio, "create_subprocess_exec", record_process) + runtime = adapter.HermesRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + { + "startup_timeout_seconds": 0.001, + "interfaces": {"api": {"port": _free_port()}}, + }, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_interface_start_timeout" + assert len(processes) == 1 + assert processes[0].returncode is not None + assert not runtime._interfaces._children + assert not _token_path(tmp_path).exists() + + +@pytest.mark.skipif(sys.platform == "win32", reason="Uses POSIX process groups") +async def test_hermes_cancelled_interface_stop_still_kills_a_child_that_ignores_sigterm(): + process = await asyncio.create_subprocess_exec( + sys.executable, + "-c", + "import signal, time\n" + "signal.signal(signal.SIGTERM, signal.SIG_IGN)\n" + "print('ready', flush=True)\n" + "time.sleep(60)\n", + stdout=asyncio.subprocess.PIPE, + start_new_session=True, + ) + try: + assert await process.stdout.readline() == b"ready\n" + children = interfaces.InterfaceChildren() + children._children.append(interfaces._Child("api", 0, process)) + + stopping = asyncio.create_task(children.stop()) + await asyncio.sleep(0.5) + stopping.cancel() + with pytest.raises(asyncio.CancelledError): + await stopping + + assert await asyncio.wait_for(process.wait(), timeout=2) is not None + finally: + if process.returncode is None: + process.kill() + await process.wait() + + async def test_hermes_dashboard_without_a_built_frontend_fails_start( tmp_path: Path, api_server: str ): From d2a63a62a67769f014528e59494be3ec9c5da7b5 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:05:15 -0700 Subject: [PATCH 12/54] fix: remove a stale Hermes API token from a kept home at start With runtime.keep_state, every runtime of an agent uses the same Hermes home. A runtime that ended without stop left interfaces/api.token there, and a later start that failed before writing a new token kept it. Start now removes that token first. The Hermes README also describes the kept home: runtimes then share the session database, and each still starts a new session. Signed-off-by: Carlos Villela --- adapters/python/hermes/README.md | 12 ++++++---- .../nemo_fabric_adapters/hermes/adapter.py | 6 ++++- docs/integrations/harness/hermes.mdx | 3 ++- tests/adapters/test_hermes_interfaces.py | 22 +++++++++++++++++++ 4 files changed, 37 insertions(+), 6 deletions(-) diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 828da6982..b3ea8938e 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -110,10 +110,14 @@ Use `runtime.max_turns` to set the Hermes agent-loop budget. The adapter maps that normalized field to `AIAgent.max_iterations`; `max_iterations` is not a Hermes harness setting. -The adapter derives Hermes state from the NeMo Fabric artifact root and creates -a child under `runtimes/`, so invocations in one NeMo Fabric runtime -share state without sharing config or the session database with another -runtime. +By default, the adapter derives Hermes state from the NeMo Fabric artifact root +and creates a child under `runtimes/`, so invocations in one NeMo +Fabric runtime share state without sharing config or the session database with +another runtime. With `runtime.keep_state`, the Hermes home is the agent's +state folder, `/.fabric/state/nvidia.fabric.hermes/`, +so every runtime of the agent uses the same session database, memory, skills +and logs. Each runtime still starts a new session, and earlier sessions stay in +the database. ## Execution Model 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 265630bf6..25eb302c3 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -112,6 +112,10 @@ async def start(self, payload: dict[str, Any]) -> None: runtime_context, common_utils.base_dir(payload) ) self._hermes_home.mkdir(parents=True, exist_ok=True) + # A runtime that ended without stop can leave its API token in a + # kept Hermes home, for a server that no longer runs. + token_path = self._hermes_home / "interfaces" / "api.token" + token_path.unlink(missing_ok=True) os.environ["HOME"] = str(self._hermes_home) os.environ["HERMES_HOME"] = str(self._hermes_home) os.environ.setdefault("HERMES_YOLO_MODE", "1") @@ -234,7 +238,7 @@ async def start(self, payload: dict[str, Any]) -> None: await self._interfaces.start( interface_ports, hermes_home=self._hermes_home, - token_path=self._hermes_home / "interfaces" / "api.token", + token_path=token_path, timeout=interfaces.startup_timeout(self._settings), environment=environment, ) diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index 8ea169cd1..2ac429fab 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -100,7 +100,8 @@ config or the session database. With `runtime.keep_state`, it is the agent's state folder, `/.fabric/state/nvidia.fabric.hermes/`: every runtime of the agent then uses the same session database, memory, skills and logs. Each runtime starts a new session, and earlier sessions stay in the -database. The adapter rewrites `config.yaml` at each start. +database. At each start, the adapter rewrites `config.yaml` and removes an +API token that an earlier runtime left in the Hermes home. ## Understand the Runtime Lifecycle diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py index f99a17236..e232d0d39 100644 --- a/tests/adapters/test_hermes_interfaces.py +++ b/tests/adapters/test_hermes_interfaces.py @@ -270,6 +270,28 @@ async def test_hermes_interface_port_in_use_fails_start( assert not _token_path(tmp_path).exists() +async def test_hermes_failed_interface_start_removes_a_token_left_in_kept_state( + tmp_path: Path, api_server: str +): + state_dir = tmp_path / "artifacts/.fabric/state/nvidia.fabric.hermes/assistant" + stale_token = state_dir / "interfaces" / "api.token" + stale_token.parent.mkdir(parents=True) + stale_token.write_text("token-from-a-crashed-runtime", encoding="utf-8") + runtime = adapter.HermesRuntime() + with socket.create_server(("127.0.0.1", 0)) as server: + payload = _payload( + tmp_path, + {"interfaces": {"api": {"port": server.getsockname()[1]}}}, + base_url=f"{api_server}/v1", + ) + payload["runtime_context"]["state_dir"] = str(state_dir) + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start(payload) + + assert caught.value.code == "hermes_interface_port_unavailable" + assert not stale_token.exists() + + async def test_hermes_dashboard_without_a_built_frontend_fails_start( tmp_path: Path, api_server: str ): From 075f8c4455b7631a12ff0ea2e736d28cc554fa11 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:05:22 -0700 Subject: [PATCH 13/54] docs: correct OpenClaw's dashboard port and token file claims OpenClaw allocates browser CDP ports through port + 110 on demand; it doesn't reserve them. The dashboard port description now says to keep that range free. The token file is owner-only only on POSIX hosts. On Windows, chmod sets only the read-only flag, so the file inherits the artifact root's permissions. The guide now says so. Signed-off-by: Carlos Villela --- .../src/nemo_fabric_adapters/common/local_interfaces.py | 6 +++++- adapters/python/openclaw/openclaw.fabric-adapter.json | 2 +- docs/integrations/harness/openclaw.mdx | 3 ++- .../src/nemo_fabric_adapter_catalog/catalog.json | 4 ++-- 4 files changed, 10 insertions(+), 5 deletions(-) diff --git a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py index a8e30575d..51f3c1bd6 100644 --- a/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py +++ b/adapters/python/common/src/nemo_fabric_adapters/common/local_interfaces.py @@ -11,7 +11,11 @@ def write_private_file(path: Path, payload: str) -> None: - """Atomically write an owner-only file in an owner-only directory.""" + """Atomically write an owner-only file in an owner-only directory. + + On Windows, chmod sets only the read-only flag, so the file inherits the + directory's permissions. + """ path.parent.mkdir(parents=True, exist_ok=True, mode=0o700) os.chmod(path.parent, 0o700) descriptor, temporary_name = tempfile.mkstemp( diff --git a/adapters/python/openclaw/openclaw.fabric-adapter.json b/adapters/python/openclaw/openclaw.fabric-adapter.json index cfc9419f4..602cda7b5 100644 --- a/adapters/python/openclaw/openclaw.fabric-adapter.json +++ b/adapters/python/openclaw/openclaw.fabric-adapter.json @@ -79,7 +79,7 @@ "type": "integer", "minimum": 1, "maximum": 65425, - "description": "Exact loopback Gateway base port, which serves the Control UI. Start fails if it or port + 2 is in use, and OpenClaw reserves ports through port + 110. Can't be combined with port_range." + "description": "Exact loopback Gateway base port, which serves the Control UI. Start fails if it or port + 2 is in use. OpenClaw allocates browser ports through port + 110 on demand, so keep that range free. Can't be combined with port_range." } }, "required": ["port"], diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index ce21a3f11..8ec365a8e 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -139,7 +139,8 @@ harness = HarnessConfig( - After the Gateway starts, the adapter writes the sign-in token, generated at each start, to `/.fabric/openclaw/runtimes//interfaces/dashboard.token` - with mode `0600`. `stop` removes it; if the adapter host is killed, the file + with mode `0600` on POSIX hosts; on Windows, the file inherits the artifact + root's permissions. `stop` removes it; if the adapter host is killed, the file can remain. - Open `http://127.0.0.1:/#token=` through a forward to that port to sign in. The Control UI removes the token from the address bar. 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 ba0937b1e..fe59187af 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 @@ -2078,7 +2078,7 @@ "type": "boolean" }, "port": { - "description": "Exact loopback Gateway base port, which serves the Control UI. Start fails if it or port + 2 is in use, and OpenClaw reserves ports through port + 110. Can't be combined with port_range.", + "description": "Exact loopback Gateway base port, which serves the Control UI. Start fails if it or port + 2 is in use. OpenClaw allocates browser ports through port + 110 on demand, so keep that range free. Can't be combined with port_range.", "maximum": 65425, "minimum": 1, "type": "integer" @@ -2145,7 +2145,7 @@ "name": "nemo-fabric-adapters-openclaw", "version": "0.7.0" }, - "sha256": "5a90fc71ffd726f09d952162d0fa49e5fcc153a2398c37467815ffafd1ecfd93", + "sha256": "f2420e753b7efff19d6c56a8ff00f428f07f2f0761d77f49a031e90aa7f3a057", "source": "adapters/python/openclaw/openclaw.fabric-adapter.json" }, "nvidia.fabric.opencode": { From e9d33365001e652fe96eba5640bb747017235188 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:05:23 -0700 Subject: [PATCH 14/54] test: cover a disabled OpenClaw dashboard and token cleanup after failed starts A dashboard with enabled false serves no Control UI and writes no token. A start that fails after writing the token removes it, and a start that times out with a dashboard configured leaves no artifacts. Signed-off-by: Carlos Villela --- tests/adapters/test_openclaw.py | 76 ++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 2 deletions(-) diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index 5d9f0afb0..21e19f123 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -1426,6 +1426,74 @@ async def test_openclaw_dashboard_serves_control_ui_with_a_token_file( assert not token_path.exists() +@pytest.mark.skipif( + sys.platform in {"darwin", "win32"}, + reason="Starts the mock Gateway, which CI runs only on Linux", +) +async def test_openclaw_dashboard_disabled_serves_no_control_ui( + mock_openclaw: Path, tmp_path: Path, dashboard_port: int +): + capture = tmp_path / "config.json" + os.environ["FAKE_OPENCLAW_CAPTURE"] = str(capture) + runtime = adapter.OpenClawRuntime() + + await runtime.start( + { + "config": _dashboard_config( + mock_openclaw, {"port": dashboard_port, "enabled": False} + ), + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + try: + gateway_port = runtime._port + token_exists = _dashboard_token(tmp_path).exists() + finally: + await runtime.stop() + + generated = json.loads(capture.read_text(encoding="utf-8")) + assert generated["gateway"]["controlUi"] == {"enabled": False} + assert gateway_port != dashboard_port + assert not token_exists + + +@pytest.mark.skipif( + sys.platform in {"darwin", "win32"}, + reason="Starts the mock Gateway, which CI runs only on Linux", +) +async def test_openclaw_dashboard_removes_the_token_when_start_fails_after_writing_it( + mock_openclaw: Path, + tmp_path: Path, + dashboard_port: int, + monkeypatch: pytest.MonkeyPatch, +): + os.environ["FAKE_OPENCLAW_CAPTURE"] = str(tmp_path / "config.json") + token_path = _dashboard_token(tmp_path) + token_written: list[bool] = [] + + # Start reads the HTTP read timeout only after it writes the token. + def fail_after_token_write(_settings): + token_written.append(token_path.exists()) + raise RuntimeError("start failed after writing the token") + + monkeypatch.setattr(adapter, "_read_timeout", fail_after_token_write) + runtime = adapter.OpenClawRuntime() + + with pytest.raises(RuntimeError, match="after writing the token"): + await runtime.start( + { + "config": _dashboard_config(mock_openclaw, {"port": dashboard_port}), + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + + assert token_written == [True] + assert not token_path.exists() + assert runtime._process is None + + @pytest.mark.skipif(sys.platform == "win32", reason="Runs the mock openclaw script directly") @pytest.mark.parametrize("offset", [0, 2]) async def test_openclaw_dashboard_port_in_use_fails_start( @@ -1476,12 +1544,15 @@ async def test_openclaw_services_reject_interfaces( @pytest.mark.skipif(sys.platform == "win32", reason="Runs the mock openclaw script directly") async def test_openclaw_startup_timeout_bounds_all_of_start( - mock_openclaw: Path, tmp_path: Path, monkeypatch: pytest.MonkeyPatch + mock_openclaw: Path, + tmp_path: Path, + dashboard_port: int, + monkeypatch: pytest.MonkeyPatch, ): # Each command finishes within the timeout, but the two together don't. monkeypatch.setenv("FAKE_OPENCLAW_COMMAND_DELAY", "0.6") monkeypatch.setenv("FAKE_OPENCLAW_CAPTURE", str(tmp_path / "config.json")) - config = _config(mock_openclaw) + config = _dashboard_config(mock_openclaw, {"port": dashboard_port}) assert config.harness is not None config.harness.settings["startup_timeout_seconds"] = 1 runtime = adapter.OpenClawRuntime() @@ -1497,6 +1568,7 @@ async def test_openclaw_startup_timeout_bounds_all_of_start( assert caught.value.code == "openclaw_command_timeout" assert runtime._process is None + assert not (tmp_path / "artifacts").exists() @pytest.mark.skipif( From 427a3e3a92dd96ec6804e59c41e08a2082fc3579 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:02:24 -0700 Subject: [PATCH 15/54] fix: don't signal a child's PID after it exits Where group signals are denied, stop falls back to signaling the child's own PID. Once the child is reaped, that PID can belong to another process. The ACP runner now skips the fallback after the agent exits, and OpenClaw rechecks the Gateway's return code before it escalates to SIGKILL. The tests now cover an agent that ignores SIGTERM, a Gateway that needs SIGKILL, and signal forwarding, each where group signals are denied. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapters/openclaw/adapter.py | 14 +-- adapters/typescript/common/src/acp-runner.ts | 2 + .../common/test/acp-runner.test.mjs | 60 ++++++------ tests/adapters/test_openclaw.py | 97 ++++++++++++++++++- 4 files changed, 139 insertions(+), 34 deletions(-) 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 908652262..044325cb2 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -1793,12 +1793,14 @@ async def stop(self) -> None: except (TimeoutError, asyncio.CancelledError) as error: if isinstance(error, asyncio.CancelledError): cancellation = cancellation or error - if os.name == "nt": - process.kill() - else: - common_utils.signal_process_group( - process.pid, signal.SIGKILL - ) + # A reaped Gateway's PID can belong to another process. + if process.returncode is None: + if os.name == "nt": + process.kill() + else: + common_utils.signal_process_group( + process.pid, signal.SIGKILL + ) try: await process.wait() except asyncio.CancelledError as error: diff --git a/adapters/typescript/common/src/acp-runner.ts b/adapters/typescript/common/src/acp-runner.ts index fdfac458c..067bbe298 100644 --- a/adapters/typescript/common/src/acp-runner.ts +++ b/adapters/typescript/common/src/acp-runner.ts @@ -145,6 +145,8 @@ async function terminateProcessTree(child: ChildProcessWithoutNullStreams, timeo if (code === "ESRCH") return; // OpenShell's sandbox denies signals to a process group; signal the agent itself. if (code !== "EPERM") throw error; + // Node reaps an exited agent, so its PID can belong to another process. + if (child.exitCode !== null || child.signalCode !== null) return; try { process.kill(pid, signal); } catch (fallbackError) { diff --git a/adapters/typescript/common/test/acp-runner.test.mjs b/adapters/typescript/common/test/acp-runner.test.mjs index 8474c14ed..e772e6270 100644 --- a/adapters/typescript/common/test/acp-runner.test.mjs +++ b/adapters/typescript/common/test/acp-runner.test.mjs @@ -254,32 +254,38 @@ test("retries process-group termination after a failed stop", { skip: process.pl if (cleanupError !== undefined) throw cleanupError; }); -test("stops the agent where process-group signals are denied", { skip: process.platform === "win32" }, async (t) => { - const directory = await mkdtemp(join(tmpdir(), "fabric-acp-denied-")); - const marker = join(directory, "pids.json"); - const session = await startAcpSession({ - command: process.execPath, - args: [fixture], - cwd: process.cwd(), - env: { ...process.env, TEST_DESCENDANT_MARKER: marker }, - shutdownTimeoutMs: 1_000, - }); - const pids = JSON.parse(await readFile(marker, "utf8")); - const originalKill = process.kill.bind(process); - // OpenShell's sandbox denies every signal to a process group. - const kill = t.mock.method(process, "kill", (pid, signal) => { - if (pid < 0) throw Object.assign(new Error("group signals denied"), { code: "EPERM" }); - return originalKill(pid, signal); - }); - try { - await session.stop(); - await waitForProcessToStop(pids.parent); - } finally { - kill.mock.restore(); - for (const pid of [pids.parent, pids.child]) { - try { originalKill(pid, "SIGKILL"); } catch (error) { - if (error.code !== "ESRCH") throw error; +for (const ignoresSigterm of [false, true]) { + test(`stops an agent that ${ignoresSigterm ? "ignores" : "exits on"} SIGTERM where process-group signals are denied`, { skip: process.platform === "win32" }, async (t) => { + const directory = await mkdtemp(join(tmpdir(), "fabric-acp-denied-")); + const marker = join(directory, "pids.json"); + const session = await startAcpSession({ + command: process.execPath, + args: [fixture], + cwd: process.cwd(), + env: { ...process.env, TEST_DESCENDANT_MARKER: marker, TEST_IGNORE_SIGTERM: ignoresSigterm ? "1" : "0" }, + shutdownTimeoutMs: 1_000, + }); + const pids = JSON.parse(await readFile(marker, "utf8")); + const originalKill = process.kill.bind(process); + const agentSignals = []; + // OpenShell's sandbox denies every signal to a process group. + const kill = t.mock.method(process, "kill", (pid, signal) => { + if (pid < 0) throw Object.assign(new Error("group signals denied"), { code: "EPERM" }); + if (pid === pids.parent && signal !== 0) agentSignals.push(signal); + return originalKill(pid, signal); + }); + try { + await session.stop(); + await waitForProcessToStop(pids.parent); + // Once the agent exits, its PID can belong to another process. + assert.deepEqual(agentSignals, ignoresSigterm ? ["SIGTERM", "SIGKILL"] : ["SIGTERM"]); + } finally { + kill.mock.restore(); + for (const pid of [pids.parent, pids.child]) { + try { originalKill(pid, "SIGKILL"); } catch (error) { + if (error.code !== "ESRCH") throw error; + } } } - } -}); + }); +} diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index 21e19f123..c88e19ad7 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -1594,9 +1594,75 @@ def deny_group_signals(_pgid: int, _signum: int) -> None: raise PermissionError(1, "Operation not permitted") monkeypatch.setattr(os, "killpg", deny_group_signals) + try: + await runtime.stop() + + assert gateway.returncode is not None + finally: + if gateway.returncode is None: + gateway.kill() + await gateway.wait() + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX process groups") +async def test_openclaw_stop_kills_a_gateway_that_ignores_sigterm_where_group_signals_are_denied( + monkeypatch: pytest.MonkeyPatch, +): + runtime = adapter.OpenClawRuntime() + runtime._shutdown_timeout = 0.01 + mock_process = MagicMock(spec=asyncio.subprocess.Process) + mock_process.pid = 1234 + mock_process.returncode = None + wait_calls = 0 + + async def wait_for_process(): + nonlocal wait_calls + wait_calls += 1 + if wait_calls == 1: + await asyncio.Event().wait() + + mock_process.wait = AsyncMock(side_effect=wait_for_process) + runtime._process = mock_process + signals: list[tuple[int, int]] = [] + + def deny_group_signals(_pgid: int, _signum: int) -> None: + raise PermissionError(1, "Operation not permitted") + + monkeypatch.setattr(adapter.os, "killpg", deny_group_signals) + monkeypatch.setattr( + adapter.os, "kill", lambda pid, signum: signals.append((pid, signum)) + ) + await runtime.stop() - assert gateway.returncode is not None + assert signals == [(1234, signal.SIGTERM), (1234, signal.SIGKILL)] + + +@pytest.mark.skipif(os.name == "nt", reason="POSIX process groups") +async def test_openclaw_stop_does_not_kill_a_gateway_that_exited_during_cancellation( + monkeypatch: pytest.MonkeyPatch, +): + runtime = adapter.OpenClawRuntime() + mock_process = MagicMock(spec=asyncio.subprocess.Process) + mock_process.pid = 1234 + mock_process.returncode = None + + async def exit_then_cancel(): + mock_process.returncode = 0 + raise asyncio.CancelledError + + mock_process.wait = AsyncMock(side_effect=exit_then_cancel) + runtime._process = mock_process + signals: list[tuple[int, int]] = [] + monkeypatch.setattr( + adapter.os, "killpg", lambda pid, signum: signals.append((pid, signum)) + ) + + with pytest.raises(asyncio.CancelledError): + await runtime.stop() + + # Once the Gateway is reaped, its PID can belong to another process. + assert signals == [(1234, signal.SIGTERM)] @pytest.mark.parametrize("phase", ["client", "process", "logs"]) @@ -1849,6 +1915,35 @@ def test_openclaw_signal_handler_forwards_to_gateway_process_group( assert forwarded == [(1234, signal.SIGTERM)] +@pytest.mark.skipif(os.name == "nt", reason="POSIX signal forwarding") +def test_openclaw_signal_handler_forwards_to_gateway_where_group_signals_are_denied( + monkeypatch: pytest.MonkeyPatch, +): + runtime = adapter.OpenClawRuntime() + mock_process = MagicMock(spec=asyncio.subprocess.Process) + mock_process.pid = 1234 + mock_process.returncode = None + runtime._process = mock_process + forwarded: list[tuple[int, int]] = [] + + def deny_group_signals(_pgid: int, _signum: int) -> None: + raise PermissionError(1, "Operation not permitted") + + monkeypatch.setattr(adapter.os, "killpg", deny_group_signals) + monkeypatch.setattr( + adapter.os, "kill", lambda pid, signum: forwarded.append((pid, signum)) + ) + + runtime._install_signal_handlers() + try: + with pytest.raises(SystemExit): + runtime._signal_handler(signal.SIGTERM, None) + finally: + runtime._restore_signal_handlers() + + assert forwarded == [(1234, signal.SIGTERM)] + + def test_windows_job_assigns_process_and_enables_kill_on_close( monkeypatch: pytest.MonkeyPatch, ): From 532424e143e6d9c85fb96ade01ce9c7b0ee94223 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:03:19 -0700 Subject: [PATCH 16/54] fix: end OpenClaw's readiness check at the startup deadline The readiness loop checked the deadline only between requests, and each /startupz request could wait up to 1 second per phase. A request that began just before the deadline could run past it. Each request is now bounded by the time left. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapters/openclaw/adapter.py | 8 +++++-- tests/adapters/test_openclaw.py | 23 +++++++++++++++++++ 2 files changed, 29 insertions(+), 2 deletions(-) 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 044325cb2..09ad5d4f4 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -1649,10 +1649,14 @@ async def _wait_started(self, port: int, token: str, timeout: float) -> None: metadata={"detail": detail[-2000:]}, ) try: - response = await client.get(f"http://127.0.0.1:{port}/startupz") + # A request can't outlast the startup deadline. + response = await asyncio.wait_for( + client.get(f"http://127.0.0.1:{port}/startupz"), + timeout=deadline - asyncio.get_running_loop().time(), + ) if response.status_code == 200: return - except httpx.RequestError: + except (httpx.RequestError, TimeoutError): pass await asyncio.sleep(0.05) raise lifecycle.LifecycleError( diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index c88e19ad7..cdb6617f3 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -1665,6 +1665,29 @@ async def exit_then_cancel(): assert signals == [(1234, signal.SIGTERM)] +async def test_openclaw_startup_deadline_bounds_a_pending_readiness_request(): + async def never_respond(reader, _writer): + await reader.read() + + server = await asyncio.start_server(never_respond, "127.0.0.1", 0) + port = server.sockets[0].getsockname()[1] + runtime = adapter.OpenClawRuntime() + mock_process = MagicMock(spec=asyncio.subprocess.Process) + mock_process.returncode = None + runtime._process = mock_process + loop = asyncio.get_running_loop() + started = loop.time() + try: + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime._wait_started(port, "token", 0.2) + finally: + server.close() + + assert caught.value.code == "openclaw_gateway_start_timeout" + # Each readiness request otherwise waits up to 1 second for a response. + assert loop.time() - started < 0.8 + + @pytest.mark.parametrize("phase", ["client", "process", "logs"]) async def test_openclaw_stop_completes_cleanup_before_propagating_cancellation( monkeypatch: pytest.MonkeyPatch, phase: str From 4a6009ae18e954bbabf4eb576491390876859d12 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:03:19 -0700 Subject: [PATCH 17/54] docs: describe OpenClaw's startup deadline The guide's example sets startup_timeout_seconds without saying what it covers or that the descriptor caps it at 75 seconds. Signed-off-by: Carlos Villela --- docs/integrations/harness/openclaw.mdx | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index 8ec365a8e..4821372fb 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -81,6 +81,11 @@ contains a directory is resolved from the NeMo Fabric base directory. The adapte uses the resolved executable for its version check, configuration validation, and Gateway startup. +`startup_timeout_seconds` sets one deadline for all of start, from checking the +`openclaw` command to the Gateway becoming ready. It defaults to 60 seconds and +can be at most 75 seconds, which keeps start within NeMo Fabric's 90-second +start limit. + The adapter supports only OpenClaw's default `openclaw` agent runtime. The adapter accepts normalized model provider, model, base URL, temperature, From e9ffe44f9d5d5395c285ef206f5de7db6896ad01 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:02:26 -0700 Subject: [PATCH 18/54] fix: let a service share an agent's kept state with one runtime With runtime.keep_state, the service host and the runtime connected to it both took the agent's state lock, so the first connected runtime failed with StateInUse. The service host now holds the lock for its connected runtimes, and a second connected runtime fails with StateInUse while the first runs. An independent runtime still fails while the service holds the lock. The state path also checks RunPlan.agent_name, because a deserialized plan can carry a name such as ../../x that planning never saw. Planning now rejects keep_state without runtime.artifacts or environment.artifacts instead of failing at start. Signed-off-by: Carlos Villela --- crates/fabric-core/src/config.rs | 13 +++- crates/fabric-core/src/runtime.rs | 68 ++++++++++++++++++-- docs/adapter-contract/tutorials/execution.md | 2 +- docs/sdk/python.mdx | 6 +- 4 files changed, 80 insertions(+), 9 deletions(-) diff --git a/crates/fabric-core/src/config.rs b/crates/fabric-core/src/config.rs index b3ff649ee..fbb4788ee 100644 --- a/crates/fabric-core/src/config.rs +++ b/crates/fabric-core/src/config.rs @@ -2403,7 +2403,7 @@ fn validate_names(field: &str, names: &[String]) -> Result<()> { } /// Whether a name can be one path component on every platform Fabric runs on. -fn is_one_folder_name(name: &str) -> bool { +pub(crate) fn is_one_folder_name(name: &str) -> bool { !name.trim().is_empty() && name != "." && name != ".." && !name.contains(['/', '\\']) } @@ -2654,6 +2654,17 @@ fn resolve_selected_descriptors( )?; let resolution = resolve_resolution(&config, descriptor)?; let environment_plan = resolve_environment_plan(&config, &base_dir); + if config.runtime.keep_state + && config.runtime.artifacts.is_none() + && environment_plan + .as_ref() + .is_none_or(|environment| environment.artifacts.is_none()) + { + return invalid_config( + "runtime.keep_state", + "requires an artifact directory, from runtime.artifacts or environment.artifacts", + ); + } validate_control_location(descriptor, environment_plan.as_ref())?; let capability_plan = resolve_capability_plan(&config, &base_dir, adapter_descriptor.as_ref()); if enforce_compatibility { diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index 4c3749639..d07db8bef 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -25,10 +25,10 @@ use crate::agent_execution::{ }; use crate::config::{ AdapterKind, AgentConfig, CapabilityPlan, CapabilityTarget, ControlLocation, - EnvironmentOwnership, RunPlan, TelemetryPlan, validate_adapter_config_compatibility, - validate_agent_config_extensions, validate_agent_run_request_extensions, - validate_agent_run_result_extensions, validate_config, validate_harness_settings, - validate_tool_definitions, validate_workflow, + EnvironmentOwnership, RunPlan, TelemetryPlan, is_one_folder_name, + validate_adapter_config_compatibility, validate_agent_config_extensions, + validate_agent_run_request_extensions, validate_agent_run_result_extensions, validate_config, + validate_harness_settings, validate_tool_definitions, validate_workflow, }; use crate::environment::resolve_environment_provider; use crate::error::{FabricError, Result}; @@ -898,6 +898,7 @@ struct LocalAdapterHost { // Adapter startup values stay in memory, never in a serialized handle or plan. environment_env: BTreeMap, // Held while the host runs; dropping the host releases the agent's state folder. + // A service host holds it for the runtimes connected to the service. _state_lock: Option, } @@ -1040,6 +1041,13 @@ pub fn start_runtime_with_service( service_id: service.service_id.clone(), }); } + // The service host holds the agent's state lock for its connected + // runtimes, so only one of them may run at a time. + if !record.active_runtime_ids.is_empty() + && let Some(path) = agent_state_dir(plan, &record.host.artifacts)? + { + return Err(FabricError::StateInUse { path }); + } let mut current_env = record.host.environment_env.clone(); resolve_named_environment(plan, &mut current_env)?; validate_named_environment(plan, &record.host.environment_env, ¤t_env)?; @@ -2657,7 +2665,12 @@ fn spawn_local_host( relay_config: Option, environment_env: BTreeMap, ) -> Result { - let state_lock = lock_agent_state(plan, &artifacts)?; + // A runtime connected to a service uses the lock its service host holds. + let state_lock = if runtime.service_id.is_none() { + lock_agent_state(plan, &artifacts)? + } else { + None + }; let runtime_dir = local_host_directory(&runtime.runtime_id); std::fs::create_dir_all(&runtime_dir).map_err(|source| FabricError::Write { path: runtime_dir.clone(), @@ -3507,6 +3520,13 @@ fn agent_state_dir(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result (PathBuf, RunPlan) { let (root, plan) = local_host_plan("success"); let mut config = plan.config; diff --git a/docs/adapter-contract/tutorials/execution.md b/docs/adapter-contract/tutorials/execution.md index 8bcc786fc..2170649ab 100644 --- a/docs/adapter-contract/tutorials/execution.md +++ b/docs/adapter-contract/tutorials/execution.md @@ -131,7 +131,7 @@ value: | `artifacts` | Lists artifacts visible when the operation begins. | | `telemetry` | Supplies invocation telemetry context, including generated Relay configuration when enabled. | | `deadline_millis` | Gives the Unix time in milliseconds by which an invocation should return. NeMo Fabric's own invocation timeout fires shortly after and kills the host with its descendant processes; the gap is shorter for very short timeouts. Keep cleanup after the deadline brief, or the invocation fails with `host_timeout` instead of returning the adapter's result. | -| `state_dir` | Present when the config sets `runtime.keep_state` and the adapter accepts it. Gives an absolute folder, `/.fabric/state//`, that every runtime of the agent receives. Keep the harness's native state there instead of in a per-runtime folder. NeMo Fabric creates the folder, fails `start` while another runtime holds it, and never deletes it. | +| `state_dir` | Present when the config sets `runtime.keep_state` and the adapter accepts it. Gives an absolute folder, `/.fabric/state//`, that every runtime of the agent receives. Keep the harness's native state there instead of in a per-runtime folder. A service and the one runtime connected to it at a time receive the same folder. NeMo Fabric creates the folder, fails `start` while another runtime holds it, and never deletes it. | Use the canonical [`runtime-context.schema.json`](https://github.com/NVIDIA/NeMo-Fabric/blob/main/schemas/adapter-contract/runtime-context.schema.json) diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index ed7823dd8..2299931a4 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -866,8 +866,10 @@ mapping to give every runtime of the agent one folder instead: `/.fabric/state//`. The config needs an artifact directory, and `metadata.name` must be usable as one folder name. Only one runtime can use the folder at a time: `start_runtime(...)` fails while -another runtime of the agent runs. Planning fails for an adapter that doesn't -declare `runtime.keep_state`; Hermes Agent's adapter declares it. +another runtime of the agent runs. A service and one runtime connected to it +share the folder. Planning fails without an artifact directory, or for an +adapter that doesn't declare `runtime.keep_state`; Hermes Agent's adapter +declares it. ## Runtime Resource Snapshots From 138554015a48201caec1e0dcfca4d683389b853b Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:59:25 -0700 Subject: [PATCH 19/54] fix: forget a service's connected runtime even when its stop fails A failed stop still releases the runtime's host, but the service kept the runtime's ID, so every later connection failed with StateInUse and release_service with ServiceInUse. The docs also say the service holds the kept state folder until it is released. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 30 +++++++++++++++++++++++++----- docs/sdk/python.mdx | 3 ++- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index d07db8bef..3e8c22ce2 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -1403,11 +1403,13 @@ pub fn stop_runtime(plan: &RunPlan, runtime: &RuntimeHandle) -> Result Result (PathBuf, RunPlan) { - let (root, plan) = local_host_plan("success"); + local_host_plan_keeping_state_in("success") + } + + fn local_host_plan_keeping_state_in(mode: &str) -> (PathBuf, RunPlan) { + let (root, plan) = local_host_plan(mode); let descriptor_path = root.join("adapters/local-host/local-host.fabric-adapter.json"); let mut descriptor: Value = serde_json::from_str( &fs::read_to_string(&descriptor_path).expect("read adapter descriptor"), @@ -5012,6 +5018,20 @@ for line in sys.stdin: let _ = fs::remove_dir_all(root); } + #[test] + fn keep_state_lets_a_runtime_connect_after_another_failed_to_stop() { + let (root, plan) = local_host_plan_keeping_state_in("stop_failure"); + let service = prepare_service(&plan).expect("prepare service"); + + let first = start_runtime_with_service(&plan, &service).expect("first connected runtime"); + stop_runtime(&plan, &first).expect_err("the adapter fails its stop"); + let second = start_runtime_with_service(&plan, &service) + .expect("connect once the first runtime's host is gone"); + let _ = stop_runtime(&plan, &second); + let _ = release_service(&plan, &service); + let _ = fs::remove_dir_all(root); + } + fn local_host_plan_with_env_name(name: &str) -> (PathBuf, RunPlan) { let (root, plan) = local_host_plan("success"); let mut config = plan.config; diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index b229c5dd1..07eaa8b0b 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -867,7 +867,8 @@ mapping to give every runtime of the agent one folder instead: artifact directory, and `metadata.name` must be usable as one folder name. Only one runtime can use the folder at a time: `start_runtime(...)` fails while another runtime of the agent runs. A service and one runtime connected to it -share the folder. Planning fails without an artifact directory, or for an +share the folder; the service holds it until `release_service(...)`, even with +no runtime connected. Planning fails without an artifact directory, or for an adapter that doesn't declare `runtime.keep_state`. ## Runtime Resource Snapshots From f231a6a24977531f23010e75fd46a6402ff4dff7 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 1 Nov 2026 17:59:25 -0700 Subject: [PATCH 20/54] fix: forget a service's connected runtime even when its stop fails A failed stop still releases the runtime's host, but the service kept the runtime's ID, so every later connection failed with StateInUse and release_service with ServiceInUse. The docs also say the service holds the kept state folder until it is released. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 30 +++++++++++++++++++++++++----- docs/sdk/python.mdx | 3 ++- 2 files changed, 27 insertions(+), 6 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index d07db8bef..3e8c22ce2 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -1403,11 +1403,13 @@ pub fn stop_runtime(plan: &RunPlan, runtime: &RuntimeHandle) -> Result Result (PathBuf, RunPlan) { - let (root, plan) = local_host_plan("success"); + local_host_plan_keeping_state_in("success") + } + + fn local_host_plan_keeping_state_in(mode: &str) -> (PathBuf, RunPlan) { + let (root, plan) = local_host_plan(mode); let descriptor_path = root.join("adapters/local-host/local-host.fabric-adapter.json"); let mut descriptor: Value = serde_json::from_str( &fs::read_to_string(&descriptor_path).expect("read adapter descriptor"), @@ -5012,6 +5018,20 @@ for line in sys.stdin: let _ = fs::remove_dir_all(root); } + #[test] + fn keep_state_lets_a_runtime_connect_after_another_failed_to_stop() { + let (root, plan) = local_host_plan_keeping_state_in("stop_failure"); + let service = prepare_service(&plan).expect("prepare service"); + + let first = start_runtime_with_service(&plan, &service).expect("first connected runtime"); + stop_runtime(&plan, &first).expect_err("the adapter fails its stop"); + let second = start_runtime_with_service(&plan, &service) + .expect("connect once the first runtime's host is gone"); + let _ = stop_runtime(&plan, &second); + let _ = release_service(&plan, &service); + let _ = fs::remove_dir_all(root); + } + fn local_host_plan_with_env_name(name: &str) -> (PathBuf, RunPlan) { let (root, plan) = local_host_plan("success"); let mut config = plan.config; diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index 2299931a4..95cd10143 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -867,7 +867,8 @@ mapping to give every runtime of the agent one folder instead: artifact directory, and `metadata.name` must be usable as one folder name. Only one runtime can use the folder at a time: `start_runtime(...)` fails while another runtime of the agent runs. A service and one runtime connected to it -share the folder. Planning fails without an artifact directory, or for an +share the folder; the service holds it until `release_service(...)`, even with +no runtime connected. Planning fails without an artifact directory, or for an adapter that doesn't declare `runtime.keep_state`; Hermes Agent's adapter declares it. From b675e51b5ab3244ac4a4ca401866b3a63f6124b5 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Tue, 3 Nov 2026 02:11:33 -0700 Subject: [PATCH 21/54] fix: keep agent state out of workspace patches and its lock beside it A workspace patch collected untracked files under the kept state folder when the artifact directory sat inside a Git workspace, and that folder can hold conversations and credentials. The patch now leaves out /.fabric/state. The state lock moves beside the folder, as ..lock, so an adapter that replaces the folder can't drop it. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 65 ++++++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 6 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index 3e8c22ce2..d07a91247 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -3550,7 +3550,11 @@ fn lock_agent_state(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result = manifest + .root + .iter() + .map(|root| root.join(".fabric").join("state")) + .collect(); + patch.push_str(&untracked_workspace_patch(workspace, &kept_state)?); if patch.trim().is_empty() { return Ok(()); } @@ -4075,16 +4086,29 @@ fn collect_workspace_artifacts( Ok(()) } -fn untracked_workspace_patch(workspace: &Path) -> Result { - let Ok(untracked) = Command::new("git") +fn untracked_workspace_patch(workspace: &Path, excluded: &[PathBuf]) -> Result { + let mut command = Command::new("git"); + command .arg("-C") .arg(workspace) .arg("ls-files") .arg("--others") .arg("--exclude-standard") .arg("-z") - .output() - else { + .arg("--") + .arg("."); + let workspace_root = workspace + .canonicalize() + .unwrap_or_else(|_| workspace.to_path_buf()); + for path in excluded { + let path = path.canonicalize().unwrap_or_else(|_| path.clone()); + if let Ok(relative) = path.strip_prefix(&workspace_root) { + let mut pathspec = std::ffi::OsString::from(":(exclude)"); + pathspec.push(relative); + command.arg(pathspec); + } + } + let Ok(untracked) = command.output() else { return Ok(String::new()); }; if !untracked.status.success() || untracked.stdout.is_empty() { @@ -4955,6 +4979,35 @@ for line in sys.stdin: assert!(Path::new(first_dir).is_absolute(), "{first_dir}"); assert_eq!(Path::new(first_dir), expected); assert!(expected.is_dir()); + // The lock sits beside the folder, so an adapter that replaces the + // folder can't drop it. + assert!(!expected.join(".fabric-state.lock").exists()); + assert!(expected.with_file_name(".assistant.lock").is_file()); + let _ = fs::remove_dir_all(root); + } + + #[test] + fn workspace_patch_leaves_out_kept_agent_state() { + let root = std::env::temp_dir().join(new_id("fabric-workspace-patch-test")); + let state = root.join("artifacts/.fabric/state/acme.agent/assistant"); + fs::create_dir_all(&state).expect("create state folder"); + assert!( + Command::new("git") + .arg("init") + .arg("-q") + .arg(&root) + .status() + .expect("run git init") + .success() + ); + fs::write(root.join("notes.txt"), "note\n").expect("write workspace file"); + fs::write(state.join("state.db"), "private\n").expect("write state file"); + + let patch = untracked_workspace_patch(&root, &[root.join("artifacts/.fabric/state")]) + .expect("untracked patch"); + + assert!(patch.contains("notes.txt"), "{patch}"); + assert!(!patch.contains("state.db"), "{patch}"); let _ = fs::remove_dir_all(root); } From ee5dc9dbf33686e5a8b2e83cc6a13ab304d0cf35 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Tue, 3 Nov 2026 02:11:33 -0700 Subject: [PATCH 22/54] fix: keep agent state out of workspace patches and its lock beside it A workspace patch collected untracked files under the kept state folder when the artifact directory sat inside a Git workspace, and that folder can hold conversations and credentials. The patch now leaves out /.fabric/state. The state lock moves beside the folder, as ..lock, so an adapter that replaces the folder can't drop it. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 65 ++++++++++++++++++++++++++++--- 1 file changed, 59 insertions(+), 6 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index 3e8c22ce2..d07a91247 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -3550,7 +3550,11 @@ fn lock_agent_state(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result = manifest + .root + .iter() + .map(|root| root.join(".fabric").join("state")) + .collect(); + patch.push_str(&untracked_workspace_patch(workspace, &kept_state)?); if patch.trim().is_empty() { return Ok(()); } @@ -4075,16 +4086,29 @@ fn collect_workspace_artifacts( Ok(()) } -fn untracked_workspace_patch(workspace: &Path) -> Result { - let Ok(untracked) = Command::new("git") +fn untracked_workspace_patch(workspace: &Path, excluded: &[PathBuf]) -> Result { + let mut command = Command::new("git"); + command .arg("-C") .arg(workspace) .arg("ls-files") .arg("--others") .arg("--exclude-standard") .arg("-z") - .output() - else { + .arg("--") + .arg("."); + let workspace_root = workspace + .canonicalize() + .unwrap_or_else(|_| workspace.to_path_buf()); + for path in excluded { + let path = path.canonicalize().unwrap_or_else(|_| path.clone()); + if let Ok(relative) = path.strip_prefix(&workspace_root) { + let mut pathspec = std::ffi::OsString::from(":(exclude)"); + pathspec.push(relative); + command.arg(pathspec); + } + } + let Ok(untracked) = command.output() else { return Ok(String::new()); }; if !untracked.status.success() || untracked.stdout.is_empty() { @@ -4955,6 +4979,35 @@ for line in sys.stdin: assert!(Path::new(first_dir).is_absolute(), "{first_dir}"); assert_eq!(Path::new(first_dir), expected); assert!(expected.is_dir()); + // The lock sits beside the folder, so an adapter that replaces the + // folder can't drop it. + assert!(!expected.join(".fabric-state.lock").exists()); + assert!(expected.with_file_name(".assistant.lock").is_file()); + let _ = fs::remove_dir_all(root); + } + + #[test] + fn workspace_patch_leaves_out_kept_agent_state() { + let root = std::env::temp_dir().join(new_id("fabric-workspace-patch-test")); + let state = root.join("artifacts/.fabric/state/acme.agent/assistant"); + fs::create_dir_all(&state).expect("create state folder"); + assert!( + Command::new("git") + .arg("init") + .arg("-q") + .arg(&root) + .status() + .expect("run git init") + .success() + ); + fs::write(root.join("notes.txt"), "note\n").expect("write workspace file"); + fs::write(state.join("state.db"), "private\n").expect("write state file"); + + let patch = untracked_workspace_patch(&root, &[root.join("artifacts/.fabric/state")]) + .expect("untracked patch"); + + assert!(patch.contains("notes.txt"), "{patch}"); + assert!(!patch.contains("state.db"), "{patch}"); let _ = fs::remove_dir_all(root); } From f48e7935a97787d374b6568e23ebcd8eb1f51788 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Tue, 3 Nov 2026 02:12:59 -0700 Subject: [PATCH 23/54] fix: refuse Hermes interfaces on Windows before any child starts The children run in their own sessions and stop by process group, which Windows doesn't have; start failed there with an unclear error after launching a child. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapters/hermes/interfaces.py | 8 ++++++++ docs/integrations/harness/hermes.mdx | 4 +++- tests/adapters/test_hermes_interfaces.py | 20 +++++++++++++++++++ 3 files changed, 31 insertions(+), 1 deletion(-) diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py index 96658a5a7..89a717752 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py @@ -20,6 +20,8 @@ from nemo_fabric_adapters.common import utils as common_utils HEALTH_PATHS = {"api": "/health", "dashboard": "/api/status"} +# Children run in their own sessions and stop by process group. +POSIX = os.name != "nt" DEFAULT_STARTUP_TIMEOUT_SECONDS = 60.0 # Fabric gives the adapter host 10 s to stop, including this wait. STOP_GRACE_SECONDS = 5.0 @@ -71,6 +73,12 @@ async def start( environment: dict[str, str], ) -> None: """Start the enabled interfaces and write the API token once all pass health.""" + if not POSIX: + raise lifecycle.LifecycleError( + "hermes_interfaces_unsupported_platform", + "Hermes interfaces require a POSIX host", + metadata={"field": "harness.settings.interfaces"}, + ) for name, port in ports.items(): if not local_interfaces.port_available(port): raise lifecycle.LifecycleError( diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index 6b377efe5..4c9b45e43 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -157,7 +157,9 @@ harness = HarnessConfig( actions, such as restart, start Hermes processes outside the runtime. - The API server needs `aiohttp`, from Hermes's `messaging` extra. The dashboard needs a built frontend at `HERMES_WEB_DIST` or Hermes's own - `hermes_cli/web_dist`; the adapter never builds it. + `hermes_cli/web_dist`; the adapter never builds it. Interfaces need a POSIX + host: on Windows, `start` fails with `hermes_interfaces_unsupported_platform` + before any child starts. ## Runtime Health diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py index 244949333..496fce992 100644 --- a/tests/adapters/test_hermes_interfaces.py +++ b/tests/adapters/test_hermes_interfaces.py @@ -256,6 +256,26 @@ async def test_hermes_stop_cuts_off_an_in_flight_api_request( assert not _token_path(tmp_path).exists() +async def test_hermes_interfaces_fail_start_on_windows_before_any_child_starts( + tmp_path: Path, api_server: str, monkeypatch: pytest.MonkeyPatch +): + monkeypatch.setattr(interfaces, "POSIX", False) + runtime = adapter.HermesRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + _payload( + tmp_path, + {"interfaces": {"api": {"port": _free_port()}}}, + base_url=f"{api_server}/v1", + ) + ) + + assert caught.value.code == "hermes_interfaces_unsupported_platform" + assert runtime._interfaces._children == [] + assert not _token_path(tmp_path).exists() + + async def test_hermes_interface_port_in_use_fails_start( tmp_path: Path, api_server: str ): From ef3ce6cd7dae50429351be4d24091fd59548cc14 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Thu, 5 Nov 2026 10:08:02 -0700 Subject: [PATCH 24/54] test: release the service before removing the failed-stop test root The keep-state failed-stop test ignored the failing release, which left the service record and its state lock registered after the test deleted its root. Assert the first release fails, then retry it and check the record is gone. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index d07a91247..ae1a10f13 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -5080,8 +5080,13 @@ for line in sys.stdin: stop_runtime(&plan, &first).expect_err("the adapter fails its stop"); let second = start_runtime_with_service(&plan, &service) .expect("connect once the first runtime's host is gone"); - let _ = stop_runtime(&plan, &second); - let _ = release_service(&plan, &service); + stop_runtime(&plan, &second).expect_err("the adapter fails its stop"); + assert!(matches!( + release_service(&plan, &service), + Err(FabricError::AdapterLifecycleOperation { .. }) + )); + release_service(&plan, &service).expect("retry release service"); + assert!(!local_services().contains_key(&service.service_id)); let _ = fs::remove_dir_all(root); } From 838f0bc0ed3bc99eb342be6641e53ea1a0ab1b7e Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Thu, 5 Nov 2026 10:08:08 -0700 Subject: [PATCH 25/54] fix: retry removing the OpenClaw dashboard token after a failed stop stop() suppressed OSError when unlinking the dashboard token and cleared the path, so a later stop() could not retry. Log the failure, keep the path, and continue Gateway cleanup. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapters/openclaw/adapter.py | 14 +++++-- tests/adapters/test_openclaw.py | 41 +++++++++++++++++++ 2 files changed, 52 insertions(+), 3 deletions(-) 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 44f32f814..f120ddf64 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -7,7 +7,6 @@ from __future__ import annotations import asyncio -import contextlib import copy import ipaddress import json @@ -1754,10 +1753,19 @@ async def invoke( async def stop(self) -> None: cancellation: asyncio.CancelledError | None = None self._stopping = True - token_path, self._dashboard_token_path = self._dashboard_token_path, None + token_path = self._dashboard_token_path if token_path is not None: - with contextlib.suppress(OSError): + try: token_path.unlink(missing_ok=True) + except OSError: + # Keep the path so a later stop can retry. + logger.error( + "OpenClaw could not remove its dashboard token at %s", + token_path, + exc_info=True, + ) + else: + self._dashboard_token_path = None try: self._restore_signal_handlers() except Exception: diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index 3b13a814c..c7be809cb 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -1494,6 +1494,47 @@ def fail_after_token_write(_settings): assert runtime._process is None +@pytest.mark.skipif( + sys.platform in {"darwin", "win32"}, + reason="Starts the mock Gateway, which CI runs only on Linux", +) +async def test_openclaw_dashboard_stop_retries_a_token_it_could_not_remove( + mock_openclaw: Path, + tmp_path: Path, + dashboard_port: int, + monkeypatch: pytest.MonkeyPatch, + caplog: pytest.LogCaptureFixture, +): + os.environ["FAKE_OPENCLAW_CAPTURE"] = str(tmp_path / "config.json") + token_path = _dashboard_token(tmp_path) + runtime = adapter.OpenClawRuntime() + await runtime.start( + { + "config": _dashboard_config(mock_openclaw, {"port": dashboard_port}), + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + unlink = Path.unlink + + def fail_token_unlink(path: Path, missing_ok: bool = False) -> None: + if path == token_path: + raise PermissionError("token is locked") + unlink(path, missing_ok=missing_ok) + + with monkeypatch.context() as patch: + patch.setattr(Path, "unlink", fail_token_unlink) + await runtime.stop() + + assert runtime._process is None + assert token_path.exists() + assert "could not remove its dashboard token" in caplog.text + + await runtime.stop() + + assert not token_path.exists() + + @pytest.mark.skipif(sys.platform == "win32", reason="Runs the mock openclaw script directly") @pytest.mark.parametrize("offset", [0, 2]) async def test_openclaw_dashboard_port_in_use_fails_start( From d9f57a6109ae189ec7eb476a669401fde0364265 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Thu, 5 Nov 2026 10:09:37 -0700 Subject: [PATCH 26/54] fix: keep tracked agent state out of workspace patches Only the untracked-file query left out the kept state folder, so tracked or intent-to-add files under it still reached workspace.patch through git diff. Apply the same exclude pathspecs to the tracked diff. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 96 ++++++++++++++++++++++--------- 1 file changed, 68 insertions(+), 28 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index ae1a10f13..2117acf41 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -4024,22 +4024,6 @@ fn collect_workspace_artifacts( if status_text.trim().is_empty() { return Ok(()); } - let mut patch = String::new(); - let Ok(diff) = Command::new("git") - .arg("-C") - .arg(workspace) - .arg("diff") - .arg("--binary") - .arg("--") - .arg(".") - .output() - else { - return Ok(()); - }; - if !diff.status.success() { - return Ok(()); - } - patch.push_str(&String::from_utf8_lossy(&diff.stdout)); // Kept agent state can hold conversations and credentials; leave it out // when the artifact directory sits inside the workspace. let kept_state: Vec = manifest @@ -4047,6 +4031,9 @@ fn collect_workspace_artifacts( .iter() .map(|root| root.join(".fabric").join("state")) .collect(); + let Some(mut patch) = tracked_workspace_patch(workspace, &kept_state) else { + return Ok(()); + }; patch.push_str(&untracked_workspace_patch(workspace, &kept_state)?); if patch.trim().is_empty() { return Ok(()); @@ -4086,6 +4073,40 @@ fn collect_workspace_artifacts( Ok(()) } +fn tracked_workspace_patch(workspace: &Path, excluded: &[PathBuf]) -> Option { + let diff = Command::new("git") + .arg("-C") + .arg(workspace) + .arg("diff") + .arg("--binary") + .arg("--") + .arg(".") + .args(excluded_pathspecs(workspace, excluded)) + .output() + .ok()?; + if !diff.status.success() { + return None; + } + Some(String::from_utf8_lossy(&diff.stdout).into_owned()) +} + +/// Git pathspecs that leave out each excluded path inside the workspace. +fn excluded_pathspecs(workspace: &Path, excluded: &[PathBuf]) -> Vec { + let workspace_root = workspace + .canonicalize() + .unwrap_or_else(|_| workspace.to_path_buf()); + excluded + .iter() + .filter_map(|path| { + let path = path.canonicalize().unwrap_or_else(|_| path.clone()); + let relative = path.strip_prefix(&workspace_root).ok()?; + let mut pathspec = std::ffi::OsString::from(":(exclude)"); + pathspec.push(relative); + Some(pathspec) + }) + .collect() +} + fn untracked_workspace_patch(workspace: &Path, excluded: &[PathBuf]) -> Result { let mut command = Command::new("git"); command @@ -4096,18 +4117,8 @@ fn untracked_workspace_patch(workspace: &Path, excluded: &[PathBuf]) -> Result Date: Thu, 5 Nov 2026 10:10:12 -0700 Subject: [PATCH 27/54] test: check Hermes's Windows refusal never spawns an interface Signed-off-by: Carlos Villela --- tests/adapters/test_hermes_interfaces.py | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py index 496fce992..8faaddc59 100644 --- a/tests/adapters/test_hermes_interfaces.py +++ b/tests/adapters/test_hermes_interfaces.py @@ -12,6 +12,7 @@ import sys import time from pathlib import Path +from unittest.mock import AsyncMock import pytest import requests @@ -260,6 +261,10 @@ async def test_hermes_interfaces_fail_start_on_windows_before_any_child_starts( tmp_path: Path, api_server: str, monkeypatch: pytest.MonkeyPatch ): monkeypatch.setattr(interfaces, "POSIX", False) + # start() stops whatever it started when it fails, so check the spawn + # itself rather than the children left afterwards. + spawn = AsyncMock() + monkeypatch.setattr(interfaces.asyncio, "create_subprocess_exec", spawn) runtime = adapter.HermesRuntime() with pytest.raises(adapter.lifecycle.LifecycleError) as caught: @@ -272,7 +277,7 @@ async def test_hermes_interfaces_fail_start_on_windows_before_any_child_starts( ) assert caught.value.code == "hermes_interfaces_unsupported_platform" - assert runtime._interfaces._children == [] + spawn.assert_not_called() assert not _token_path(tmp_path).exists() From 9e867d84776cc35f202b5b7e3bd080c66e127af6 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Thu, 5 Nov 2026 10:11:13 -0700 Subject: [PATCH 28/54] fix: refuse Hermes interfaces on Windows before MCP discovery Signed-off-by: Carlos Villela --- .../src/nemo_fabric_adapters/hermes/adapter.py | 4 ++++ .../nemo_fabric_adapters/hermes/interfaces.py | 17 +++++++++++------ tests/adapters/test_hermes_interfaces.py | 6 ++++++ 3 files changed, 21 insertions(+), 6 deletions(-) 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 b95f0058e..b0507d5a5 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -108,6 +108,10 @@ async def start(self, payload: dict[str, Any]) -> None: self._agent_config = agent_config self._settings = configuration._settings(agent_config) interface_ports = interfaces.interface_ports(self._settings) + if interface_ports: + # Refuse before Hermes's setup, whose MCP discovery can take + # minutes and outlast the caller's start deadline. + interfaces.require_supported_platform() model_config = configuration._selected_model(agent_config) self._model_config = model_config self._runtime_id = runtime_context.runtime_id diff --git a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py index 89a717752..c554d3036 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/interfaces.py @@ -49,6 +49,16 @@ def startup_timeout(settings: dict[str, Any]) -> float: ) +def require_supported_platform() -> None: + """Refuse interfaces on a host without POSIX process groups.""" + if not POSIX: + raise lifecycle.LifecycleError( + "hermes_interfaces_unsupported_platform", + "Hermes interfaces require a POSIX host", + metadata={"field": "harness.settings.interfaces"}, + ) + + @dataclass class _Child: name: str @@ -73,12 +83,7 @@ async def start( environment: dict[str, str], ) -> None: """Start the enabled interfaces and write the API token once all pass health.""" - if not POSIX: - raise lifecycle.LifecycleError( - "hermes_interfaces_unsupported_platform", - "Hermes interfaces require a POSIX host", - metadata={"field": "harness.settings.interfaces"}, - ) + require_supported_platform() for name, port in ports.items(): if not local_interfaces.port_available(port): raise lifecycle.LifecycleError( diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py index 8faaddc59..408d8b159 100644 --- a/tests/adapters/test_hermes_interfaces.py +++ b/tests/adapters/test_hermes_interfaces.py @@ -13,6 +13,7 @@ import time from pathlib import Path from unittest.mock import AsyncMock +from unittest.mock import MagicMock import pytest import requests @@ -265,6 +266,10 @@ async def test_hermes_interfaces_fail_start_on_windows_before_any_child_starts( # itself rather than the children left afterwards. spawn = AsyncMock() monkeypatch.setattr(interfaces.asyncio, "create_subprocess_exec", spawn) + # Refusing before Hermes's setup keeps MCP discovery, which can take + # minutes, from outlasting a caller's start deadline. + write_config = MagicMock(wraps=configuration.write_hermes_config) + monkeypatch.setattr(configuration, "write_hermes_config", write_config) runtime = adapter.HermesRuntime() with pytest.raises(adapter.lifecycle.LifecycleError) as caught: @@ -278,6 +283,7 @@ async def test_hermes_interfaces_fail_start_on_windows_before_any_child_starts( assert caught.value.code == "hermes_interfaces_unsupported_platform" spawn.assert_not_called() + write_config.assert_not_called() assert not _token_path(tmp_path).exists() From fb91e9292ff97746226deef89529b3b3c795409e Mon Sep 17 00:00:00 2001 From: Julie Yaunches Date: Fri, 6 Nov 2026 12:01:15 -0500 Subject: [PATCH 29/54] test: verify native supplied-skill loading in Hermes and OpenClaw Signed-off-by: Julie Yaunches --- .github/workflows/ci_python.yml | 11 ++++ tests/_utils/openclaw_skills.mjs | 37 ++++++++++++ tests/e2e/test_hermes_e2e.py | 21 ++++++- tests/e2e/test_openclaw_skills.py | 99 +++++++++++++++++++++++++++++++ 4 files changed, 165 insertions(+), 3 deletions(-) create mode 100644 tests/_utils/openclaw_skills.mjs create mode 100644 tests/e2e/test_openclaw_skills.py diff --git a/.github/workflows/ci_python.yml b/.github/workflows/ci_python.yml index 72a0ec20c..b7ef8c7bc 100644 --- a/.github/workflows/ci_python.yml +++ b/.github/workflows/ci_python.yml @@ -122,6 +122,17 @@ jobs: set -euo pipefail just --set no_uv true test-python + - name: Test skill loading with pinned native OpenClaw + if: matrix.platform == 'linux-amd64' && matrix.python-version == '3.12' + run: | + set -euo pipefail + openclaw_root="$RUNNER_TEMP/fabric-openclaw-skills" + npm exec --yes --package=npm@11.16.0 -- npm install --global \ + --prefix "$openclaw_root" --no-audit --no-fund \ + --allow-scripts=openclaw openclaw@2026.9.34 + export OPENCLAW_TEST_PACKAGE="$openclaw_root/lib/node_modules/openclaw" + uv run --no-sync pytest tests/e2e/test_openclaw_skills.py -q + - name: Test Kiro health with the pinned native CLI if: matrix.platform == 'linux-amd64' && matrix.python-version == '3.12' env: diff --git a/tests/_utils/openclaw_skills.mjs b/tests/_utils/openclaw_skills.mjs new file mode 100644 index 000000000..94c7ad1ad --- /dev/null +++ b/tests/_utils/openclaw_skills.mjs @@ -0,0 +1,37 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import assert from "node:assert/strict"; +import { readFileSync, readdirSync } from "node:fs"; +import { join } from "node:path"; +import { pathToFileURL } from "node:url"; + +// The pinned release exposes its native loader through a hashed bundle facade. +// Do not replace discovery or file reading with a test implementation. +const dist = join(process.argv[2], "dist"); +const loaders = []; +for (const file of readdirSync(dist).filter((name) => + /^workspace-skill-loader-.*\.mjs$/.test(name), +)) { + const module = await import(pathToFileURL(join(dist, file)).href); + if (typeof module.loadWorkspaceSkills === "function") { + loaders.push(module.loadWorkspaceSkills); + } +} +assert.equal( + loaders.length, + 1, + "the pinned package must expose one native workspace loader", +); +const config = JSON.parse(readFileSync(process.argv[3], "utf8")); +const entries = loaders[0](config.agents.defaults.workspace, { config }); +process.stdout.write( + JSON.stringify( + entries.map(({ skill }) => ({ + name: skill.name, + source: skill.source, + path: skill.filePath, + contentHash: skill.contentHash, + })), + ), +); diff --git a/tests/e2e/test_hermes_e2e.py b/tests/e2e/test_hermes_e2e.py index 20472ff62..332db7f5f 100644 --- a/tests/e2e/test_hermes_e2e.py +++ b/tests/e2e/test_hermes_e2e.py @@ -15,7 +15,7 @@ import pytest import requests import yaml -from _utils.utils import assert_atof_model, assert_atof_skill_selection +from _utils.utils import assert_atof_model, assert_atof_skill_selection, atof_records from examples.code_review_agent import ( hermes_config, @@ -104,8 +104,7 @@ async def test_hermes_persistent_host_with_relay( ] assert ( sum( - record["name"] == "hermes.session" - and record.get("scope_category") == "end" + record["name"] == "hermes.session" and record.get("scope_category") == "end" for record in atof_records ) == 2 @@ -300,6 +299,22 @@ async def test_skill_selection( assert result["status"] == "succeeded", result.to_mapping() assert_atof_skill_selection(result["output"], skill) + skill_results = [ + json.loads(record["data"]) + for record in atof_records(result["output"]) + if record["kind"] == "scope" + and record["category"] == "tool" + and record["name"] == "skill_view" + and record["scope_category"] == "end" + ] + if skill is None: + assert skill_results == [] + else: + assert len(skill_results) == 1, skill_results + loaded = skill_results[0] + assert loaded["success"] is True, loaded + skill_dir = {"default": default_skill, "alternate": alternate_skill}[skill] + assert loaded["content"] == (skill_dir / "SKILL.md").read_text(), loaded @pytest.mark.usefixtures("mock_nvidia_api_key", "nemo_relay") diff --git a/tests/e2e/test_openclaw_skills.py b/tests/e2e/test_openclaw_skills.py new file mode 100644 index 000000000..91aeef545 --- /dev/null +++ b/tests/e2e/test_openclaw_skills.py @@ -0,0 +1,99 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Fabric configuration through the installed native loader, without inference. + +OPENCLAW_TEST_PACKAGE selects the pinned package installed by the native CI step. +The loader hashes the bytes it reads; this does not prove model use or mounts. +""" + +import hashlib +import json +import os +from pathlib import Path +import subprocess + +import pytest +from nemo_fabric_adapter_contract.models import AgentConfig, RuntimeContext +from nemo_fabric_adapters.openclaw import adapter + + +@pytest.fixture(name="openclaw_package") +def openclaw_package_fixture() -> Path: + configured = os.environ.get("OPENCLAW_TEST_PACKAGE") + if configured is None: + pytest.skip("OPENCLAW_TEST_PACKAGE must name the installed native package") + package = Path(configured).resolve() + manifest = json.loads((package / "package.json").read_text()) + assert manifest["version"] in adapter.SUPPORTED_OPENCLAW_VERSIONS + return package + + +@pytest.mark.parametrize("skill", ["default", "alternate", None]) +def test_configured_skill_is_loaded_by_native_openclaw( + tmp_path: Path, + openclaw_package: Path, + default_skill: Path, + alternate_skill: Path, + skill: str | None, +): + sources = {"default": default_skill, "alternate": alternate_skill} + workspace = tmp_path / "workspace" + workspace.mkdir() + config = AgentConfig.from_mapping( + { + "models": {"default": {"provider": "test", "model": "unused"}}, + "skills": {"paths": [sources[skill]] if skill else []}, + } + ) + context = RuntimeContext.from_mapping( + { + "runtime_id": "skill-loading", + "invocation_id": "skill-loading", + "request_id": "skill-loading", + "environment": { + "environment_id": "skill-loading", + "provider": "local", + "control_location": "in_env_control", + "workspace": str(workspace), + "env": {}, + "ownership": "caller_owned", + }, + "artifacts": {}, + } + ) + native = adapter._openclaw_config( + config, context, base_dir=tmp_path, port=18789, token_env="UNUSED_TEST_TOKEN" + ) + config_path = tmp_path / "openclaw.json" + config_path.write_text(json.dumps(native)) + home = tmp_path / "home" + home.mkdir() + probe = Path(__file__).parents[1] / "_utils" / "openclaw_skills.mjs" + result = subprocess.run( + ["node", str(probe), str(openclaw_package), str(config_path)], + cwd=workspace, + env={ + "PATH": os.environ["PATH"], + "HOME": str(home), + "OPENCLAW_HOME": str(home), + "OPENCLAW_STATE_DIR": str(home / ".openclaw"), + }, + capture_output=True, + text=True, + timeout=30, + ) + assert result.returncode == 0, result.stderr + loaded = [entry for entry in json.loads(result.stdout) if entry["name"] in sources] + if skill is None: + assert loaded == [] + else: + source = (sources[skill] / "SKILL.md").resolve() + assert loaded == [ + { + "name": skill, + "source": "openclaw-extra", + "path": str(source), + "contentHash": hashlib.sha256(source.read_bytes()).hexdigest(), + } + ] From 612da0fde4a39518cf878edf73a1b6d9b1eb9a9c Mon Sep 17 00:00:00 2001 From: Julie Yaunches Date: Fri, 6 Nov 2026 12:12:38 -0500 Subject: [PATCH 30/54] test: document native skill loading assertions Signed-off-by: Julie Yaunches --- tests/e2e/test_hermes_e2e.py | 2 ++ tests/e2e/test_openclaw_skills.py | 2 ++ 2 files changed, 4 insertions(+) diff --git a/tests/e2e/test_hermes_e2e.py b/tests/e2e/test_hermes_e2e.py index 332db7f5f..18d01b4b8 100644 --- a/tests/e2e/test_hermes_e2e.py +++ b/tests/e2e/test_hermes_e2e.py @@ -73,6 +73,7 @@ async def test_hermes_persistent_host_with_relay( code_review_agent_dir: Path, api_server: str, ): + """Verify reused Hermes sessions retain Relay artifacts across invocations.""" os.environ["ADAPTER_PYTHON"] = sys.executable config = with_relay(hermes_config()) config.models["default"].base_url = f"{api_server}/v1" @@ -265,6 +266,7 @@ async def test_skill_selection( default_skill: Path, alternate_skill: Path, ): + """Verify Hermes returns the full supplied skill through a successful tool call.""" os.environ["ADAPTER_PYTHON"] = sys.executable config = with_relay(hermes_config()) config.models["default"].model = "fabric-echo" diff --git a/tests/e2e/test_openclaw_skills.py b/tests/e2e/test_openclaw_skills.py index 91aeef545..13031861a 100644 --- a/tests/e2e/test_openclaw_skills.py +++ b/tests/e2e/test_openclaw_skills.py @@ -20,6 +20,7 @@ @pytest.fixture(name="openclaw_package") def openclaw_package_fixture() -> Path: + """Require a supported native package when the dedicated CI step enables it.""" configured = os.environ.get("OPENCLAW_TEST_PACKAGE") if configured is None: pytest.skip("OPENCLAW_TEST_PACKAGE must name the installed native package") @@ -37,6 +38,7 @@ def test_configured_skill_is_loaded_by_native_openclaw( alternate_skill: Path, skill: str | None, ): + """Check native selection, source path, and content hash for supplied skills.""" sources = {"default": default_skill, "alternate": alternate_skill} workspace = tmp_path / "workspace" workspace.mkdir() From 71b50396fbb108fd5391a6e505be1406f74ff813 Mon Sep 17 00:00:00 2001 From: Julie Yaunches Date: Fri, 6 Nov 2026 12:20:45 -0500 Subject: [PATCH 31/54] test: check native Hermes discovery after skill removal Signed-off-by: Julie Yaunches --- tests/e2e/test_hermes_e2e.py | 36 +++++++++++++++++++----------------- 1 file changed, 19 insertions(+), 17 deletions(-) diff --git a/tests/e2e/test_hermes_e2e.py b/tests/e2e/test_hermes_e2e.py index 18d01b4b8..08d334306 100644 --- a/tests/e2e/test_hermes_e2e.py +++ b/tests/e2e/test_hermes_e2e.py @@ -280,18 +280,18 @@ async def test_skill_selection( if skill == "alternate": config.add_skill_path(alternate_skill) - if skill is not None: - scenario_response = requests.post( - f"{api_server}/_scenario", - json={ - "tool_call": { - "name": "skill_view", - "arguments": {"name": skill}, - } - }, - timeout=5, - ) - scenario_response.raise_for_status() + tool_name = "skill_view" if skill is not None else "skills_list" + scenario_response = requests.post( + f"{api_server}/_scenario", + json={ + "tool_call": { + "name": tool_name, + "arguments": {"name": skill} if skill is not None else {}, + } + }, + timeout=5, + ) + scenario_response.raise_for_status() result = await Fabric().run( config, @@ -306,15 +306,17 @@ async def test_skill_selection( for record in atof_records(result["output"]) if record["kind"] == "scope" and record["category"] == "tool" - and record["name"] == "skill_view" + and record["name"] == tool_name and record["scope_category"] == "end" ] + assert len(skill_results) == 1, skill_results + loaded = skill_results[0] + assert loaded["success"] is True, loaded if skill is None: - assert skill_results == [] + assert not {"default", "alternate"}.intersection( + entry["name"] for entry in loaded["skills"] + ), loaded else: - assert len(skill_results) == 1, skill_results - loaded = skill_results[0] - assert loaded["success"] is True, loaded skill_dir = {"default": default_skill, "alternate": alternate_skill}[skill] assert loaded["content"] == (skill_dir / "SKILL.md").read_text(), loaded From 72fabd49b6b404fcca265c6c92ece4df2f6fc46e Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 6 Nov 2026 16:37:57 -0700 Subject: [PATCH 32/54] feat: resolve skill folders in the adapter contract A skills.paths entry that contains SKILL.md is one skill; otherwise each folder directly inside it that contains SKILL.md is a skill. An entry without skills loads nothing, and a missing entry or two skills with the same name fail. nemo_fabric_adapter_contract.skills.resolve_skills applies the rule in the task environment, and the contract schema describes it. Signed-off-by: Carlos Villela --- adapter-contract/python/README.md | 13 ++ .../nemo_fabric_adapter_contract/skills.py | 136 +++++++++++++++++ .../schemas/agent-config.schema.json | 2 +- .../typescript/src/generated/agent-config.ts | 5 +- crates/fabric-core/src/agent_config.rs | 5 +- .../tutorials/normalized-configuration.md | 14 +- .../agent-config/struct-agentskillconfig.mdx | 2 +- .../adapter-contract/agent-config.schema.json | 2 +- schemas/sdk/run-plan.schema.json | 2 +- skills/nemo-fabric-build-adapter/SKILL.md | 6 +- tests/adapter_contract/test_skills.py | 142 ++++++++++++++++++ 11 files changed, 321 insertions(+), 8 deletions(-) create mode 100644 adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py create mode 100644 tests/adapter_contract/test_skills.py diff --git a/adapter-contract/python/README.md b/adapter-contract/python/README.md index 05f1f9734..d1c3b74b1 100644 --- a/adapter-contract/python/README.md +++ b/adapter-contract/python/README.md @@ -28,6 +28,19 @@ Import `AgentConfig` from the contract models module: from nemo_fabric_adapter_contract.models import AgentConfig ``` +Resolve `skills.paths` in the task environment with the contract's skills +helper. Each entry is a skill folder or a folder of skills: + +```python +from nemo_fabric_adapter_contract.skills import SkillPathError, resolve_skills + +skills = resolve_skills(config.skills.paths if config.skills else [], base_dir) +``` + +The helper returns each skill's name and resolved folder. It raises +`SkillPathError` when an entry does not exist or is not a folder, or when two +skills share a name. + An adapter descriptor opts into the southbound configuration with `config.input=agent_config`. Python adapters using the optional common lifecycle host pass `AgentConfig.from_mapping` as the `config_loader`. diff --git a/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py b/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py new file mode 100644 index 000000000..fedac058d --- /dev/null +++ b/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py @@ -0,0 +1,136 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Resolve ``skills.paths`` entries in the task environment. + +Each entry names one skill or a folder of skills: + +1. An entry that contains ``SKILL.md`` is one skill. +2. Otherwise each folder directly inside the entry that contains ``SKILL.md`` + is a skill. Other files and folders are ignored. +3. An entry that exists but holds no skills loads nothing. +4. An entry that does not exist, or is not a folder, fails. +5. Two skills with the same name fail. + +A skill's name is the ``name`` field of its ``SKILL.md`` front matter, or its +folder name when the front matter has none. +""" + +from __future__ import annotations + +import os +import re +from collections.abc import Iterable +from dataclasses import dataclass +from pathlib import Path +from typing import Literal + +SKILL_FILE = "SKILL.md" + +SkillPathFailure = Literal["not_found", "invalid", "duplicate"] + +_NAME = re.compile(r"name:\s*(.*?)\s*") + + +@dataclass(frozen=True) +class Skill: + """One skill found through ``skills.paths``.""" + + name: str + """Name from the skill's front matter, or its folder name.""" + path: Path + """Resolved folder that contains the skill's ``SKILL.md``.""" + field: str + """The ``skills.paths`` entry that supplied the skill, such as ``skills.paths[0]``.""" + + +class SkillPathError(ValueError): + """A ``skills.paths`` entry that cannot be loaded.""" + + def __init__( + self, + reason: SkillPathFailure, + message: str, + *, + field: str, + paths: tuple[Path, ...], + ) -> None: + super().__init__(message) + self.reason: SkillPathFailure = reason + self.field = field + self.paths = paths + + +def resolve_skills( + paths: Iterable[str | os.PathLike[str]], base_dir: str | os.PathLike[str] +) -> list[Skill]: + """Return the skills named by ``paths``, resolving relative entries against ``base_dir``. + + Raises: + SkillPathError: If an entry does not exist or is not a folder, or two + skills share a name. + """ + + skills: list[Skill] = [] + by_name: dict[str, Skill] = {} + for index, value in enumerate(paths): + field = f"skills.paths[{index}]" + configured = Path(base_dir) / value + try: + entry = configured.resolve(strict=True) + except (OSError, RuntimeError): + raise SkillPathError( + "not_found", + f"NeMo Fabric skill path {field} does not exist: {configured}", + field=field, + paths=(configured,), + ) from None + if not entry.is_dir(): + raise SkillPathError( + "invalid", + f"NeMo Fabric skill path {field} is not a folder: {configured}", + field=field, + paths=(configured,), + ) + for directory in _skill_directories(entry): + skill = Skill(name=_skill_name(directory), path=directory, field=field) + existing = by_name.get(skill.name) + if existing is None: + by_name[skill.name] = skill + skills.append(skill) + elif existing.path != skill.path: + raise SkillPathError( + "duplicate", + f"NeMo Fabric skill {skill.name!r} is configured twice: " + f"{existing.path} ({existing.field}) and {skill.path} ({field})", + field=field, + paths=(existing.path, skill.path), + ) + return skills + + +def _skill_directories(entry: Path) -> list[Path]: + if (entry / SKILL_FILE).is_file(): + return [entry] + return [ + child.resolve() + for child in sorted(entry.iterdir(), key=lambda child: child.name) + if child.is_dir() and (child / SKILL_FILE).is_file() + ] + + +def _skill_name(directory: Path) -> str: + text = (directory / SKILL_FILE).read_text(encoding="utf-8-sig", errors="replace") + front_matter = text.splitlines() + if front_matter[:1] == ["---"]: + for line in front_matter[1:]: + if line.strip() == "---": + break + match = _NAME.fullmatch(line) + if match: + name = match.group(1) + if len(name) >= 2 and name[0] == name[-1] and name[0] in "\"'": + name = name[1:-1] + if name: + return name + return directory.name diff --git a/adapter-contract/typescript/schemas/agent-config.schema.json b/adapter-contract/typescript/schemas/agent-config.schema.json index 193ea1206..179b820fa 100644 --- a/adapter-contract/typescript/schemas/agent-config.schema.json +++ b/adapter-contract/typescript/schemas/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. A missing entry, or two skills with the same name, fails.", "items": { "type": "string" }, diff --git a/adapter-contract/typescript/src/generated/agent-config.ts b/adapter-contract/typescript/src/generated/agent-config.ts index eb77eec56..8a7d30618 100644 --- a/adapter-contract/typescript/src/generated/agent-config.ts +++ b/adapter-contract/typescript/src/generated/agent-config.ts @@ -286,7 +286,10 @@ export interface AgentSkillConfig { */ extensions?: JsonObject; /** - * Skill paths resolved for the task environment. + * Skill paths resolved for the task environment. An entry that contains + * `SKILL.md` is one skill; otherwise each folder directly inside it that + * contains `SKILL.md` is a skill. An entry that holds no skills loads + * nothing. A missing entry, or two skills with the same name, fails. */ paths?: string[]; } diff --git a/crates/fabric-core/src/agent_config.rs b/crates/fabric-core/src/agent_config.rs index 9e86515bf..542873f06 100644 --- a/crates/fabric-core/src/agent_config.rs +++ b/crates/fabric-core/src/agent_config.rs @@ -140,7 +140,10 @@ pub struct AgentRuntimeConfig { #[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize, JsonSchema)] #[serde(deny_unknown_fields)] pub struct AgentSkillConfig { - /// Skill paths resolved for the task environment. + /// Skill paths resolved for the task environment. An entry that contains + /// `SKILL.md` is one skill; otherwise each folder directly inside it that + /// contains `SKILL.md` is a skill. An entry that holds no skills loads + /// nothing. A missing entry, or two skills with the same name, fails. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub paths: Vec, /// Adapter-owned skill fields. diff --git a/docs/adapter-contract/tutorials/normalized-configuration.md b/docs/adapter-contract/tutorials/normalized-configuration.md index 833a23cd2..1d61073dd 100644 --- a/docs/adapter-contract/tutorials/normalized-configuration.md +++ b/docs/adapter-contract/tutorials/normalized-configuration.md @@ -55,7 +55,7 @@ needs and applies it. | `models` | Named model roles with provider, model, credential-variable name, endpoint, temperature, and provider settings. | | `instructions` | Portable target instructions. | | `runtime` | Target-applied behavior, such as a turn limit. | -| `skills` | Skill paths resolved for the execution environment. | +| `skills` | Skill paths resolved for the execution environment. Each entry is a skill or a folder of skills. | | `mcp` | Named Model Context Protocol (MCP) servers, authentication metadata, headers, and effective per-server tool policy. | | `tools` | Named tool or tool-group definitions plus effective enabled and blocked policy. | | `workflow` | A registered custom-agent entry point and immutable construction settings. | @@ -66,6 +66,18 @@ Use the canonical for exact fields and constraints. Python adapters can use the matching dependency-free dataclasses from `nemo_fabric_adapter_contract.models`. +Resolve `skills.paths` during `start` in the task environment, where mounted +skill folders exist. An entry that contains `SKILL.md` is one skill. Otherwise +each folder directly inside the entry that contains `SKILL.md` is a skill, and +other files and folders are ignored. An entry that exists but holds no skills +loads nothing. Fail start when an entry does not exist, when an entry is not a +folder, or when two skills share a name, and name the entry or both skill +folders. A skill's name is the `name` field of its `SKILL.md` front matter, or +its folder name. Python adapters can call +`nemo_fabric_adapter_contract.skills.resolve_skills(paths, base_dir)`, which +applies these rules, returns each skill's name and folder, and raises +`SkillPathError` with the failing `skills.paths[N]` field. + ## To Map the Normalized Configuration Work through each step in order, verifying your progress at each checkpoint. diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx index 9f6fee792..cc0facd2e 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx @@ -18,7 +18,7 @@ Skill paths made available to an adapter target. ### `paths: Vec` -Skill paths resolved for the task environment. +Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. A missing entry, or two skills with the same name, fails. ### `extensions: BTreeMap` diff --git a/schemas/adapter-contract/agent-config.schema.json b/schemas/adapter-contract/agent-config.schema.json index 193ea1206..179b820fa 100644 --- a/schemas/adapter-contract/agent-config.schema.json +++ b/schemas/adapter-contract/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. A missing entry, or two skills with the same name, fails.", "items": { "type": "string" }, diff --git a/schemas/sdk/run-plan.schema.json b/schemas/sdk/run-plan.schema.json index ad240c67e..293323ebd 100644 --- a/schemas/sdk/run-plan.schema.json +++ b/schemas/sdk/run-plan.schema.json @@ -769,7 +769,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. A missing entry, or two skills with the same name, fails.", "items": { "type": "string" }, diff --git a/skills/nemo-fabric-build-adapter/SKILL.md b/skills/nemo-fabric-build-adapter/SKILL.md index e195634f5..de06c68c2 100644 --- a/skills/nemo-fabric-build-adapter/SKILL.md +++ b/skills/nemo-fabric-build-adapter/SKILL.md @@ -117,7 +117,11 @@ adapter boundary: planning; `replace` discards the harness default, while `append` preserves it and adds the configured content after it. - Convert MCP servers, tool definitions, tool policy, and skills into native - target constructs. + target constructs. Treat each `skills.paths` entry as one skill when it + contains `SKILL.md`, otherwise as a folder whose direct subfolders that + contain `SKILL.md` are skills; load nothing from an entry without skills, and + fail start on a missing entry or two skills with the same name. Python + adapters can use `nemo_fabric_adapter_contract.skills.resolve_skills`. - Resolve workflow entry points and construction settings during `start` in the task environment. - Read identity, environment, artifacts, telemetry, and the invocation diff --git a/tests/adapter_contract/test_skills.py b/tests/adapter_contract/test_skills.py new file mode 100644 index 000000000..69acf175b --- /dev/null +++ b/tests/adapter_contract/test_skills.py @@ -0,0 +1,142 @@ +# SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +# SPDX-License-Identifier: Apache-2.0 + +"""Resolve skills.paths entries that name a skill or a folder of skills.""" + +from __future__ import annotations + +from pathlib import Path + +import pytest + +from nemo_fabric_adapter_contract.skills import Skill, SkillPathError, resolve_skills + + +def _skill(directory: Path, name: str | None = None) -> Path: + directory.mkdir(parents=True) + frontmatter = f"---\nname: {name}\ndescription: Test skill.\n---\n" if name else "" + (directory / "SKILL.md").write_text( + f"{frontmatter}# Test skill\n", encoding="utf-8" + ) + return directory + + +def test_entry_with_skill_md_is_one_skill(tmp_path: Path): + review = _skill(tmp_path / "review", "code-review") + + assert resolve_skills([review], tmp_path) == [ + Skill(name="code-review", path=review.resolve(), field="skills.paths[0]") + ] + + +def test_skill_name_falls_back_to_its_directory(tmp_path: Path): + review = _skill(tmp_path / "review") + + assert [skill.name for skill in resolve_skills([review], tmp_path)] == ["review"] + + +def test_quoted_frontmatter_name_is_unquoted(tmp_path: Path): + review = tmp_path / "review" + review.mkdir() + (review / "SKILL.md").write_text( + '---\r\nname: "code-review"\r\n---\r\n', encoding="utf-8" + ) + + assert [skill.name for skill in resolve_skills([review], tmp_path)] == [ + "code-review" + ] + + +def test_folder_loads_skills_directly_inside_it(tmp_path: Path): + shared = tmp_path / "shared" + one = _skill(shared / "one", "one") + two = _skill(shared / "two", "two") + (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") + (shared / "docs").mkdir() + (shared / "docs" / "README.md").write_text("Not a skill.\n", encoding="utf-8") + _skill(shared / "group" / "nested", "nested") + + assert resolve_skills([shared], tmp_path) == [ + Skill(name="one", path=one.resolve(), field="skills.paths[0]"), + Skill(name="two", path=two.resolve(), field="skills.paths[0]"), + ] + + +def test_folder_and_separate_skill_mix(tmp_path: Path): + shared = tmp_path / "shared" + _skill(shared / "one", "one") + _skill(shared / "two", "two") + separate = _skill(tmp_path / "mounted" / "three", "three") + + skills = resolve_skills([shared, separate], tmp_path) + + assert [(skill.name, skill.field) for skill in skills] == [ + ("one", "skills.paths[0]"), + ("two", "skills.paths[0]"), + ("three", "skills.paths[1]"), + ] + + +def test_existing_entry_without_skills_loads_nothing(tmp_path: Path): + empty = tmp_path / "empty" + empty.mkdir() + + assert resolve_skills([empty], tmp_path) == [] + + +def test_relative_entry_resolves_against_base_dir(tmp_path: Path): + review = _skill(tmp_path / "skills" / "review", "review") + + assert resolve_skills(["skills/review"], tmp_path) == [ + Skill(name="review", path=review.resolve(), field="skills.paths[0]") + ] + + +def test_missing_entry_fails_naming_it(tmp_path: Path): + review = _skill(tmp_path / "review", "review") + missing = tmp_path / "missing" + + with pytest.raises(SkillPathError) as caught: + resolve_skills([review, missing], tmp_path) + + assert caught.value.reason == "not_found" + assert caught.value.field == "skills.paths[1]" + assert caught.value.paths == (missing,) + assert "skills.paths[1]" in str(caught.value) + assert str(missing) in str(caught.value) + + +def test_file_entry_fails(tmp_path: Path): + entry = tmp_path / "SKILL.md" + entry.write_text("# Not a folder\n", encoding="utf-8") + + with pytest.raises(SkillPathError) as caught: + resolve_skills([entry], tmp_path) + + assert caught.value.reason == "invalid" + assert caught.value.field == "skills.paths[0]" + assert str(entry) in str(caught.value) + + +def test_duplicate_skill_names_fail_naming_both_paths(tmp_path: Path): + shared = tmp_path / "shared" + first = _skill(shared / "review", "review") + second = _skill(tmp_path / "mounted" / "review-copy", "review") + + with pytest.raises(SkillPathError) as caught: + resolve_skills([shared, second], tmp_path) + + assert caught.value.reason == "duplicate" + assert caught.value.field == "skills.paths[1]" + assert caught.value.paths == (first.resolve(), second.resolve()) + assert str(first.resolve()) in str(caught.value) + assert str(second.resolve()) in str(caught.value) + + +def test_same_skill_listed_twice_loads_once(tmp_path: Path): + shared = tmp_path / "shared" + review = _skill(shared / "review", "review") + + assert resolve_skills([shared, review], tmp_path) == [ + Skill(name="review", path=review.resolve(), field="skills.paths[0]") + ] From ec77dcc0132bb02198f7aac736671bd0effa87eb Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 6 Nov 2026 16:37:57 -0700 Subject: [PATCH 33/54] feat: accept a folder of skills in OpenClaw and Hermes Both adapters resolve skills.paths with the contract helper. OpenClaw passes each skill folder to skills.load.extraDirs and Hermes passes each to skills.external_dirs, so neither searches deeper than the rule allows. A missing entry fails with _skill_not_found; a non-folder entry or a duplicate skill name fails with _skill_invalid, naming both skill folders. Signed-off-by: Carlos Villela --- adapters/python/hermes/README.md | 17 ++- .../nemo_fabric_adapters/hermes/adapter.py | 1 + .../hermes/configuration.py | 26 +++- adapters/python/openclaw/README.md | 11 ++ .../nemo_fabric_adapters/openclaw/adapter.py | 30 ++-- docs/integrations/harness/hermes.mdx | 2 + docs/integrations/harness/openclaw.mdx | 11 ++ tests/adapters/test_hermes_adapter.py | 31 ++++- tests/adapters/test_hermes_config_builder.py | 3 +- tests/adapters/test_hermes_interfaces.py | 1 + tests/adapters/test_openclaw.py | 19 ++- tests/e2e/test_hermes_config_mapping.py | 12 +- tests/e2e/test_hermes_e2e.py | 105 ++++++++++++++ tests/e2e/test_openclaw_skills.py | 129 ++++++++++++++---- 14 files changed, 335 insertions(+), 63 deletions(-) diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 3428d18a1..3a0c2fb61 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -63,7 +63,8 @@ The adapter receives a normalized payload from NeMo Fabric and materializes a na - replacement `instructions.system` and `runtime.max_turns`; - workspace and explicit environment variables through `environment`; - invocation timeout through `runtime.timeout_seconds`; -- NeMo Fabric skills as external skill directories for Hermes Agent; +- NeMo Fabric skills as Hermes Agent `skills.external_dirs`, one folder per + skill (refer to [Skills](#skills)); - NeMo Fabric MCP servers as Hermes Agent MCP server config; - `tools.enabled` and `tools.blocked` as Hermes-native toolset selection and blocking policy; @@ -72,6 +73,20 @@ The adapter receives a normalized payload from NeMo Fabric and materializes a na Tool selectors are Hermes toolset names because that is the native policy surface Hermes exposes. +### Skills + +Each `skills.paths` entry is a skill or a folder of skills. An entry that +contains `SKILL.md` is one skill. Otherwise each folder directly inside the +entry that contains `SKILL.md` is a skill, and other files and folders are +ignored. Mix the two forms to combine a shared folder of skills with a skill +mounted on its own. An entry that exists but holds no skills, such as a new, +empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an +entry does not exist and with `hermes_skill_invalid` when an entry is not a +folder or two skills share a name; the error names the entry or both skill +folders. The adapter passes each skill folder to Hermes Agent's +`skills.external_dirs`, so Hermes does not search the rest of a configured +folder. + During run-plan resolution, NeMo Fabric Core validates the `models..top_p` (from 0 through 1) and positive `models..max_tokens` fields against the Hermes descriptor before 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 d893a008b..cf4911e16 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -154,6 +154,7 @@ async def start(self, payload: dict[str, Any]) -> None: self._hermes_home, # Workspace belongs to the per-runtime context, not AgentConfig. workspace=str(runtime_context.environment.workspace or "."), + base_dir=common_utils.base_dir(payload), relay_enabled=relay_enabled, interfaces=interface_ports, ) 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..2e5da1c9a 100644 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/configuration.py @@ -15,6 +15,8 @@ from nemo_fabric_adapter_contract.models import AgentModelConfig from nemo_fabric_adapter_contract.models import McpOAuth2Config from nemo_fabric_adapter_contract.models import McpServiceAccountConfig +from nemo_fabric_adapter_contract import skills as contract_skills +from nemo_fabric_adapters.common import lifecycle import nemo_fabric_adapters.common.utils as common_utils from nemo_fabric_adapters.hermes.interfaces import GATEWAY_DRAIN_TIMEOUT_SECONDS @@ -129,6 +131,7 @@ def build_hermes_config( agent_config: AgentConfig, *, workspace: str, + base_dir: str | Path, relay_enabled: bool = False, interfaces: Collection[str] = (), ) -> dict[str, Any]: @@ -172,11 +175,7 @@ def build_hermes_config( # Hermes makes an extra model call for titles, which skews Relay telemetry. config["auxiliary"] = {"title_generation": {"enabled": False}} - skill_dirs = ( - [str(path) for path in agent_config.skills.paths] - if agent_config.skills is not None - else [] - ) + skill_dirs = _skill_dirs(agent_config, base_dir) if skill_dirs: config["skills"] = {"external_dirs": skill_dirs} @@ -197,11 +196,27 @@ def build_hermes_config( return config +def _skill_dirs(agent_config: AgentConfig, base_dir: str | Path) -> list[str]: + try: + skills = contract_skills.resolve_skills( + agent_config.skills.paths if agent_config.skills else [], base_dir + ) + except contract_skills.SkillPathError as error: + code = "not_found" if error.reason == "not_found" else "invalid" + raise lifecycle.LifecycleError( + f"hermes_skill_{code}", str(error), metadata={"field": error.field} + ) from None + # Hermes walks each external directory for SKILL.md files, including nested + # folders, so pass each skill's own folder rather than the configured entry. + return [str(skill.path) for skill in skills] + + def write_hermes_config( agent_config: AgentConfig, hermes_home: Path, *, workspace: str, + base_dir: str | Path, relay_enabled: bool = False, interfaces: Collection[str] = (), ) -> tuple[Path, dict[str, Any]]: @@ -209,6 +224,7 @@ def write_hermes_config( config = build_hermes_config( agent_config, workspace=workspace, + base_dir=base_dir, relay_enabled=relay_enabled, interfaces=interfaces, ) diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index b7df6522c..de2242ebe 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -73,6 +73,17 @@ list maps to a wildcard `tools.deny` policy, and `tools.blocked` maps to isolated temporary OpenClaw state directory. The Gateway is stopped and its temporary configuration is removed when the NeMo Fabric runtime stops. +Each `skills.paths` entry is a skill or a folder of skills. An entry that +contains `SKILL.md` is one skill. Otherwise each folder directly inside the +entry that contains `SKILL.md` is a skill, and other files and folders are +ignored. Mix the two forms to combine a shared folder of skills with a skill +mounted on its own. An entry that exists but holds no skills, such as a new, +empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an +entry does not exist and with `openclaw_skill_invalid` when an entry is not a +folder or two skills share a name; the error names the entry or both skill +folders. The adapter passes each skill folder to OpenClaw's +`skills.load.extraDirs`. + For custom OpenAI-compatible providers, set `models..base_url`; the adapter generates an OpenClaw custom provider using the `openai-completions` API adapter. Set `api_key_env` when that provider requires 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 f120ddf64..ac90efa85 100644 --- a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py +++ b/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py @@ -31,6 +31,7 @@ import httpx from nemo_fabric_adapter_contract import models as contract +from nemo_fabric_adapter_contract import skills as contract_skills from nemo_fabric_adapters.common import instructions as common_instructions from nemo_fabric_adapters.common import lifecycle from nemo_fabric_adapters.common import local_interfaces @@ -309,24 +310,17 @@ def _channel_secret_env_names(value: Any) -> set[str]: def _resolve_skill_paths(config: contract.AgentConfig, base_dir: Path) -> list[str]: - paths: list[str] = [] - for index, path in enumerate(config.skills.paths if config.skills else []): - try: - directory = (base_dir / path).resolve(strict=True) - except (OSError, RuntimeError): - raise lifecycle.LifecycleError( - "openclaw_skill_not_found", - "A configured NeMo Fabric skill path does not exist", - metadata={"field": f"skills.paths[{index}]"}, - ) from None - if not directory.is_dir() or not (directory / "SKILL.md").is_file(): - raise lifecycle.LifecycleError( - "openclaw_skill_invalid", - "NeMo Fabric skill paths must be directories containing a SKILL.md file", - metadata={"field": f"skills.paths[{index}]"}, - ) - paths.append(str(directory)) - return paths + try: + skills = contract_skills.resolve_skills( + config.skills.paths if config.skills else [], base_dir + ) + except contract_skills.SkillPathError as error: + code = "not_found" if error.reason == "not_found" else "invalid" + raise lifecycle.LifecycleError( + f"openclaw_skill_{code}", str(error), metadata={"field": error.field} + ) from None + # OpenClaw loads an extra directory that contains SKILL.md as one skill. + return [str(skill.path) for skill in skills] def _resolve_command(settings: dict[str, Any], base_dir: Path) -> Path: diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index 98e5aaecc..d2a065771 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -74,6 +74,8 @@ Replace the endpoint and model, and provide `MODEL_API_KEY` in the adapter envir The adapter supports `instructions.system.mode: replace` and rejects `append`. Tool selectors are Hermes toolset names. `models..top_p` must be between 0 and 1, and `max_tokens` must be positive. A model-level token limit takes precedence over `harness.settings.max_tokens`. If both are omitted, the adapter passes `None` to preserve Hermes' native response token limit behavior for embedded and native interface agents. Use `runtime.max_turns`, not a `max_iterations` harness setting, to control the agent loop. +Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. + ### Hermes Settings The descriptor uses closed schemas, so unknown settings are rejected. diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index 4821372fb..663397c2a 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -94,6 +94,17 @@ MCP configuration. Normalized MCP authentication is not supported. For a custom OpenAI-compatible endpoint, set the model's `base_url` and, when needed, `api_key_env`. +Each `skills.paths` entry is a skill or a folder of skills. An entry that +contains `SKILL.md` is one skill. Otherwise each folder directly inside the +entry that contains `SKILL.md` is a skill, and other files and folders are +ignored. Mix the two forms to combine a shared folder of skills with a skill +mounted on its own. An entry that exists but holds no skills, such as a new, +empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an +entry does not exist and with `openclaw_skill_invalid` when an entry is not a +folder or two skills share a name; the error names the entry or both skill +folders. The adapter passes each skill folder to OpenClaw's +`skills.load.extraDirs`. + For an endpoint that supports `stream_options.include_usage`, set `models..settings.supports_usage_in_streaming` to `true`. This maps to OpenClaw's native `compat.supportsUsageInStreaming` and requires `base_url`. diff --git a/tests/adapters/test_hermes_adapter.py b/tests/adapters/test_hermes_adapter.py index 55629bd78..a5495453a 100644 --- a/tests/adapters/test_hermes_adapter.py +++ b/tests/adapters/test_hermes_adapter.py @@ -538,8 +538,11 @@ async def test_runtime_rechecks_ambient_relay_config_before_each_turn( mock_finalize.assert_not_called() -def test_build_hermes_config_maps_fabric_config_to_hermes_config(): +def test_build_hermes_config_maps_fabric_config_to_hermes_config(tmp_path: Path): os.environ["MCP_URL"] = "http://localhost:9000/mcp" + review = tmp_path / "skills" / "review" + review.mkdir(parents=True) + (review / "SKILL.md").write_text("# Review\n", encoding="utf-8") agent_config = _agent_config( { "harness": { @@ -576,6 +579,7 @@ def test_build_hermes_config_maps_fabric_config_to_hermes_config(): config = configuration.build_hermes_config( agent_config, workspace="/workspace/repo", + base_dir=tmp_path, ) assert config == { @@ -593,7 +597,7 @@ def test_build_hermes_config_maps_fabric_config_to_hermes_config(): "cwd": "/workspace/repo", "timeout": 90, }, - "skills": {"external_dirs": ["skills/review"]}, + "skills": {"external_dirs": [str(review.resolve())]}, "mcp_servers": { "github": { "enabled": True, @@ -621,7 +625,9 @@ def test_build_hermes_config_omits_max_turns_when_fabric_limit_unset(): } ) - config = configuration.build_hermes_config(agent_config, workspace=".") + config = configuration.build_hermes_config( + agent_config, workspace=".", base_dir="." + ) assert "max_turns" not in config["agent"] @@ -637,7 +643,9 @@ def test_build_hermes_config_omits_max_turns_when_fabric_limit_null(): } ) - config = configuration.build_hermes_config(agent_config, workspace=".") + config = configuration.build_hermes_config( + agent_config, workspace=".", base_dir="." + ) assert "max_turns" not in config["agent"] @@ -708,10 +716,13 @@ def test_hermes_config_variation_matrix_surfaces_supported_capabilities( } ) payload["config"] = agent_config.to_mapping() + (tmp_path / "skills" / "review").mkdir(parents=True) + (tmp_path / "skills" / "review" / "SKILL.md").write_text("# Review\n") config = configuration.build_hermes_config( agent_config, workspace=str(tmp_path / "workspace"), + base_dir=tmp_path, ) plugin_config = common_utils.load_relay_plugin_config(payload) observability = plugin_config["components"][0]["config"] @@ -721,7 +732,9 @@ def test_hermes_config_variation_matrix_surfaces_supported_capabilities( "default": "nvidia/review-model", } assert config["terminal"]["cwd"] == str(tmp_path / "workspace") - assert config["skills"]["external_dirs"] == [str(tmp_path / "skills" / "review")] + assert config["skills"]["external_dirs"] == [ + str((tmp_path / "skills" / "review").resolve()) + ] assert config["mcp_servers"] == { "github": { "enabled": True, @@ -774,6 +787,7 @@ def test_build_hermes_config_maps_stdio_mcp_args_and_env_from_agent_config( config = configuration.build_hermes_config( agent_config, workspace=str(tmp_path / "workspace"), + base_dir=tmp_path, ) assert config["mcp_servers"] == { @@ -1101,9 +1115,11 @@ def test_build_hermes_config_disables_session_title_generation_only_for_relay(): } ) - ordinary_config = configuration.build_hermes_config(agent_config, workspace=".") + ordinary_config = configuration.build_hermes_config( + agent_config, workspace=".", base_dir="." + ) relay_config = configuration.build_hermes_config( - agent_config, workspace=".", relay_enabled=True + agent_config, workspace=".", base_dir=".", relay_enabled=True ) assert "auxiliary" not in ordinary_config @@ -1122,6 +1138,7 @@ def test_write_hermes_config_writes_file(tmp_path: Path): agent_config, tmp_path / "hermes-home", workspace=".", + base_dir=tmp_path, ) assert config_path == tmp_path / "hermes-home" / "config.yaml" diff --git a/tests/adapters/test_hermes_config_builder.py b/tests/adapters/test_hermes_config_builder.py index 540e6af9c..955463e4f 100644 --- a/tests/adapters/test_hermes_config_builder.py +++ b/tests/adapters/test_hermes_config_builder.py @@ -90,7 +90,7 @@ def test_build_hermes_config_omits_unset_values_without_hermes_agent(): } ) - config = configuration.build_hermes_config(config, workspace=".") + config = configuration.build_hermes_config(config, workspace=".", base_dir=".") assert config["model"] == { "provider": "nvidia", @@ -122,6 +122,7 @@ def import_without_yaml(name: str, *args: object, **kwargs: object) -> object: agent_config, tmp_path / "hermes-home", workspace=".", + base_dir=tmp_path, ) assert json.loads(config_path.read_text(encoding="utf-8")) == config diff --git a/tests/adapters/test_hermes_interfaces.py b/tests/adapters/test_hermes_interfaces.py index ac918f040..e07d83e2a 100644 --- a/tests/adapters/test_hermes_interfaces.py +++ b/tests/adapters/test_hermes_interfaces.py @@ -139,6 +139,7 @@ def test_hermes_interfaces_read_the_model_endpoint_and_key_from_config(): config = configuration.build_hermes_config( _agent_config({}, base_url="http://127.0.0.1:9/v1"), workspace=".", + base_dir=".", interfaces={"api": 8642}, ) diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index c7be809cb..802b53b24 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -553,7 +553,6 @@ async def test_openclaw_runtime_generates_config_invokes_and_cleans_up( [ ("missing", "openclaw_skill_not_found"), ("file", "openclaw_skill_invalid"), - ("missing_manifest", "openclaw_skill_invalid"), ], ) def test_openclaw_rejects_invalid_skill_paths( @@ -565,8 +564,6 @@ def test_openclaw_rejects_invalid_skill_paths( skill_path = tmp_path / "skills" if invalid_path == "file": skill_path.write_text("not a directory", encoding="utf-8") - elif invalid_path == "missing_manifest": - skill_path.mkdir() with pytest.raises(adapter.lifecycle.LifecycleError) as caught: adapter._openclaw_config( @@ -581,6 +578,22 @@ def test_openclaw_rejects_invalid_skill_paths( assert caught.value.metadata == {"field": "skills.paths[0]"} +def test_openclaw_loads_no_skills_from_an_empty_skill_folder( + mock_openclaw: Path, tmp_path: Path +): + (tmp_path / "skills").mkdir() + + generated = adapter._openclaw_config( + _config(mock_openclaw, with_skills=True), + _context(tmp_path), + base_dir=tmp_path, + port=20_000, + token_env="OPENCLAW_GATEWAY_TOKEN", + ) + + assert "skills" not in generated + + def test_openclaw_preserves_context_injection_without_system_instruction( mock_openclaw: Path, tmp_path: Path ): diff --git a/tests/e2e/test_hermes_config_mapping.py b/tests/e2e/test_hermes_config_mapping.py index 98693d2aa..91346639d 100644 --- a/tests/e2e/test_hermes_config_mapping.py +++ b/tests/e2e/test_hermes_config_mapping.py @@ -20,10 +20,14 @@ def test_hermes_config_mapping(tmp_path: Path): hermes_home = tmp_path / "home" + skill = tmp_path / "skills" / "code-review" + skill.mkdir(parents=True) + (skill / "SKILL.md").write_text("# Code review\n", encoding="utf-8") config_path, config = configuration.write_hermes_config( - agent_config(), + agent_config(skill), hermes_home, workspace=str(tmp_path / "workspace"), + base_dir=tmp_path, relay_enabled=True, ) @@ -40,7 +44,7 @@ def test_hermes_config_mapping(tmp_path: Path): assert config["terminal"]["backend"] == "local" assert Path(config["terminal"]["cwd"]) == tmp_path / "workspace" assert config["terminal"]["timeout"] == 30 - assert config["skills"]["external_dirs"] == ["/tmp/fabric-skills/code-review"] + assert config["skills"]["external_dirs"] == [str(skill.resolve())] assert config["mcp_servers"]["github"] == { "enabled": True, "url": "https://mcp.github.example/mcp", @@ -50,7 +54,7 @@ def test_hermes_config_mapping(tmp_path: Path): assert config["plugins"]["enabled"] == ["observability/nemo_relay"] -def agent_config() -> AgentConfig: +def agent_config(skill: Path) -> AgentConfig: return AgentConfig.from_mapping( { "harness": {"settings": {"terminal_timeout": 30}}, @@ -63,7 +67,7 @@ def agent_config() -> AgentConfig: } }, "tools": {"enabled": []}, - "skills": {"paths": ["/tmp/fabric-skills/code-review"]}, + "skills": {"paths": [str(skill)]}, "mcp": { "servers": { "github": { diff --git a/tests/e2e/test_hermes_e2e.py b/tests/e2e/test_hermes_e2e.py index 08d334306..3d9c754e1 100644 --- a/tests/e2e/test_hermes_e2e.py +++ b/tests/e2e/test_hermes_e2e.py @@ -23,6 +23,7 @@ ) from nemo_fabric import ( Fabric, + FabricRuntimeError, RelayAtofConfig, RelayAtofFileSinkConfig, RelayObservabilityConfig, @@ -321,6 +322,110 @@ async def test_skill_selection( assert loaded["content"] == (skill_dir / "SKILL.md").read_text(), loaded +def _write_skill(directory: Path, name: str) -> Path: + directory.mkdir(parents=True) + (directory / "SKILL.md").write_text( + f"---\nname: {name}\ndescription: Use the {name} test skill.\n---\n\n" + f"Reply with `{name} loaded`.\n", + encoding="utf-8", + ) + return directory + + +def _skill_folder_config(api_server: str, *paths: Path): + os.environ["ADAPTER_PYTHON"] = sys.executable + config = with_relay(hermes_config()) + config.models["default"].model = "fabric-echo" + config.models["default"].base_url = f"{api_server}/v1" + config.tools.enabled = None + for path in paths: + config.add_skill_path(path) + return config + + +@pytest.mark.usefixtures("mock_nvidia_api_key", "nemo_relay") +@pytest.mark.parametrize("layout", ["folder", "folder_and_skill", "empty"]) +async def test_skill_folders( + code_review_agent_dir: Path, + api_server: str, + tmp_path: Path, + layout: str, +): + """Verify Hermes lists each skill directly inside a folder, plus separate skills.""" + shared = tmp_path / "shared" + shared.mkdir() + expected: set[str] = set() + if layout != "empty": + _write_skill(shared / "one", "fabric-one") + _write_skill(shared / "two", "fabric-two") + (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") + _write_skill(shared / "group" / "nested", "fabric-nested") + expected = {"fabric-one", "fabric-two"} + paths = [shared] + if layout == "folder_and_skill": + paths.append(_write_skill(tmp_path / "mounted" / "three", "fabric-three")) + expected.add("fabric-three") + config = _skill_folder_config(api_server, *paths) + requests.post( + f"{api_server}/_scenario", + json={"tool_call": {"name": "skills_list", "arguments": {}}}, + timeout=5, + ).raise_for_status() + + result = await Fabric().run( + config, base_dir=code_review_agent_dir, input="List your skills." + ) + + assert result["status"] == "succeeded", result.to_mapping() + listed = [ + json.loads(record["data"]) + for record in atof_records(result["output"]) + if record["kind"] == "scope" + and record["category"] == "tool" + and record["name"] == "skills_list" + and record["scope_category"] == "end" + ] + assert len(listed) == 1, listed + assert listed[0]["success"] is True, listed[0] + assert { + entry["name"] + for entry in listed[0]["skills"] + if entry["name"].startswith("fabric-") + } == expected + + +@pytest.mark.usefixtures("mock_nvidia_api_key", "nemo_relay") +async def test_missing_skill_path_fails_start( + code_review_agent_dir: Path, api_server: str, tmp_path: Path +): + """Verify Hermes refuses a configured skill entry that does not exist.""" + missing = tmp_path / "missing" + config = _skill_folder_config(api_server, missing) + + with pytest.raises(FabricRuntimeError) as caught: + await Fabric().run(config, base_dir=code_review_agent_dir, input="Hi.") + + assert caught.value.code == "hermes_skill_not_found" + assert str(missing) in str(caught.value) + + +@pytest.mark.usefixtures("mock_nvidia_api_key", "nemo_relay") +async def test_duplicate_skill_names_fail_start( + code_review_agent_dir: Path, api_server: str, tmp_path: Path +): + """Verify Hermes refuses two configured skills that share a name.""" + first = _write_skill(tmp_path / "shared" / "review", "fabric-review") + second = _write_skill(tmp_path / "mounted" / "review", "fabric-review") + config = _skill_folder_config(api_server, tmp_path / "shared", second) + + with pytest.raises(FabricRuntimeError) as caught: + await Fabric().run(config, base_dir=code_review_agent_dir, input="Hi.") + + assert caught.value.code == "hermes_skill_invalid" + assert str(first.resolve()) in str(caught.value) + assert str(second.resolve()) in str(caught.value) + + @pytest.mark.usefixtures("mock_nvidia_api_key", "nemo_relay") @pytest.mark.parametrize("model", ["m1", "m2"]) async def test_model_selection( diff --git a/tests/e2e/test_openclaw_skills.py b/tests/e2e/test_openclaw_skills.py index 13031861a..7c3eac01b 100644 --- a/tests/e2e/test_openclaw_skills.py +++ b/tests/e2e/test_openclaw_skills.py @@ -30,22 +30,23 @@ def openclaw_package_fixture() -> Path: return package -@pytest.mark.parametrize("skill", ["default", "alternate", None]) -def test_configured_skill_is_loaded_by_native_openclaw( - tmp_path: Path, - openclaw_package: Path, - default_skill: Path, - alternate_skill: Path, - skill: str | None, -): - """Check native selection, source path, and content hash for supplied skills.""" - sources = {"default": default_skill, "alternate": alternate_skill} +def _skill(directory: Path, name: str) -> Path: + directory.mkdir(parents=True) + (directory / "SKILL.md").write_text( + f"---\nname: {name}\ndescription: Use the {name} test skill.\n---\n\n" + f"Reply with `{name} loaded`.\n", + encoding="utf-8", + ) + return directory + + +def _native_config(tmp_path: Path, paths: list[Path]) -> dict: workspace = tmp_path / "workspace" - workspace.mkdir() + workspace.mkdir(exist_ok=True) config = AgentConfig.from_mapping( { "models": {"default": {"provider": "test", "model": "unused"}}, - "skills": {"paths": [sources[skill]] if skill else []}, + "skills": {"paths": paths}, } ) context = RuntimeContext.from_mapping( @@ -64,9 +65,15 @@ def test_configured_skill_is_loaded_by_native_openclaw( "artifacts": {}, } ) - native = adapter._openclaw_config( + return adapter._openclaw_config( config, context, base_dir=tmp_path, port=18789, token_env="UNUSED_TEST_TOKEN" ) + + +def _load_natively( + tmp_path: Path, openclaw_package: Path, paths: list[Path] +) -> list[dict]: + native = _native_config(tmp_path, paths) config_path = tmp_path / "openclaw.json" config_path.write_text(json.dumps(native)) home = tmp_path / "home" @@ -74,7 +81,7 @@ def test_configured_skill_is_loaded_by_native_openclaw( probe = Path(__file__).parents[1] / "_utils" / "openclaw_skills.mjs" result = subprocess.run( ["node", str(probe), str(openclaw_package), str(config_path)], - cwd=workspace, + cwd=tmp_path / "workspace", env={ "PATH": os.environ["PATH"], "HOME": str(home), @@ -86,16 +93,90 @@ def test_configured_skill_is_loaded_by_native_openclaw( timeout=30, ) assert result.returncode == 0, result.stderr - loaded = [entry for entry in json.loads(result.stdout) if entry["name"] in sources] + return json.loads(result.stdout) + + +def _loaded(skill_dir: Path, name: str) -> dict: + source = (skill_dir / "SKILL.md").resolve() + return { + "name": name, + "source": "openclaw-extra", + "path": str(source), + "contentHash": hashlib.sha256(source.read_bytes()).hexdigest(), + } + + +@pytest.mark.parametrize("skill", ["default", "alternate", None]) +def test_configured_skill_is_loaded_by_native_openclaw( + tmp_path: Path, + openclaw_package: Path, + default_skill: Path, + alternate_skill: Path, + skill: str | None, +): + """Check native selection, source path, and content hash for supplied skills.""" + sources = {"default": default_skill, "alternate": alternate_skill} + entries = _load_natively( + tmp_path, openclaw_package, [sources[skill]] if skill else [] + ) + loaded = [entry for entry in entries if entry["name"] in sources] if skill is None: assert loaded == [] else: - source = (sources[skill] / "SKILL.md").resolve() - assert loaded == [ - { - "name": skill, - "source": "openclaw-extra", - "path": str(source), - "contentHash": hashlib.sha256(source.read_bytes()).hexdigest(), - } - ] + assert loaded == [_loaded(sources[skill], skill)] + + +@pytest.mark.parametrize("layout", ["folder", "folder_and_skill", "empty"]) +def test_skill_folders_are_loaded_by_native_openclaw( + tmp_path: Path, openclaw_package: Path, layout: str +): + """Load each skill directly inside a folder, mixed with a separate skill.""" + shared = tmp_path / "shared" + shared.mkdir() + expected: list[dict] = [] + if layout != "empty": + one = _skill(shared / "one", "fabric-one") + two = _skill(shared / "two", "fabric-two") + (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") + _skill(shared / "group" / "nested", "fabric-nested") + expected = [_loaded(one, "fabric-one"), _loaded(two, "fabric-two")] + paths = [shared] + if layout == "folder_and_skill": + separate = _skill(tmp_path / "mounted" / "three", "fabric-three") + paths.append(separate) + expected.append(_loaded(separate, "fabric-three")) + + entries = _load_natively(tmp_path, openclaw_package, paths) + + loaded = [entry for entry in entries if entry["name"].startswith("fabric-")] + assert sorted(loaded, key=lambda entry: entry["name"]) == sorted( + expected, key=lambda entry: entry["name"] + ) + + +def test_missing_skill_path_fails_naming_it(tmp_path: Path): + """Refuse a configured entry that is absent from the task environment.""" + shared = tmp_path / "shared" + shared.mkdir() + missing = tmp_path / "missing" + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + _native_config(tmp_path, [shared, missing]) + + assert caught.value.code == "openclaw_skill_not_found" + assert caught.value.metadata["field"] == "skills.paths[1]" + assert str(missing) in caught.value.message + + +def test_duplicate_skill_names_fail_naming_both_paths(tmp_path: Path): + """Refuse two configured skills that share a name.""" + first = _skill(tmp_path / "shared" / "review", "fabric-review") + second = _skill(tmp_path / "mounted" / "review", "fabric-review") + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + _native_config(tmp_path, [tmp_path / "shared", second]) + + assert caught.value.code == "openclaw_skill_invalid" + assert caught.value.metadata["field"] == "skills.paths[1]" + assert str(first.resolve()) in caught.value.message + assert str(second.resolve()) in caught.value.message From 23f9553b3a73ac5071b13c776c0757c1171e4a74 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 6 Nov 2026 20:06:15 -0700 Subject: [PATCH 34/54] fix: ignore unreadable folders and read skill names like YAML A folder inside a skills.paths entry that cannot be read, such as a new volume's lost+found, is not a skill; on Python 3.11 to 3.13 it crashed start with an unhandled PermissionError. An entry or SKILL.md that cannot be read now fails with SkillPathError naming it. Skill names now ignore a YAML comment after the name and need the closing front matter line, as Hermes Agent and OpenClaw read them. The same skill folder reached through two spellings, such as another case on a case-insensitive file system, loads once. Signed-off-by: Carlos Villela --- adapter-contract/python/README.md | 2 +- .../nemo_fabric_adapter_contract/skills.py | 128 +++++++++++++----- adapters/python/hermes/README.md | 2 +- adapters/python/openclaw/README.md | 2 +- .../tutorials/normalized-configuration.md | 2 +- docs/integrations/harness/hermes.mdx | 2 +- docs/integrations/harness/openclaw.mdx | 2 +- tests/adapter_contract/test_skills.py | 123 +++++++++++++++++ 8 files changed, 223 insertions(+), 40 deletions(-) diff --git a/adapter-contract/python/README.md b/adapter-contract/python/README.md index d1c3b74b1..2558160c7 100644 --- a/adapter-contract/python/README.md +++ b/adapter-contract/python/README.md @@ -38,7 +38,7 @@ skills = resolve_skills(config.skills.paths if config.skills else [], base_dir) ``` The helper returns each skill's name and resolved folder. It raises -`SkillPathError` when an entry does not exist or is not a folder, or when two +`SkillPathError` when an entry does not exist or is not a readable folder, or when two skills share a name. An adapter descriptor opts into the southbound configuration with diff --git a/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py b/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py index fedac058d..a09888633 100644 --- a/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py +++ b/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py @@ -29,7 +29,8 @@ SkillPathFailure = Literal["not_found", "invalid", "duplicate"] -_NAME = re.compile(r"name:\s*(.*?)\s*") +_NAME = re.compile(r"name:(?:[ \t]+(.*?))?[ \t]*") +_COMMENT = re.compile(r"[ \t]+#") @dataclass(frozen=True) @@ -66,13 +67,18 @@ def resolve_skills( ) -> list[Skill]: """Return the skills named by ``paths``, resolving relative entries against ``base_dir``. + A folder inside an entry that cannot be read is not a skill. The same + folder reached through several entries loads once. + Raises: - SkillPathError: If an entry does not exist or is not a folder, or two - skills share a name. + SkillPathError: If an entry does not exist, is not a folder, or cannot + be read, if a skill's ``SKILL.md`` cannot be read, or if two skills + share a name. """ skills: list[Skill] = [] by_name: dict[str, Skill] = {} + folders: set[tuple[int, int]] = set() for index, value in enumerate(paths): field = f"skills.paths[{index}]" configured = Path(base_dir) / value @@ -92,13 +98,16 @@ def resolve_skills( field=field, paths=(configured,), ) - for directory in _skill_directories(entry): - skill = Skill(name=_skill_name(directory), path=directory, field=field) + for directory in _skill_directories(entry, field, configured): + folder = _folder_identity(directory) + if folder in folders: + continue + folders.add(folder) + skill = Skill( + name=_skill_name(directory, field), path=directory, field=field + ) existing = by_name.get(skill.name) - if existing is None: - by_name[skill.name] = skill - skills.append(skill) - elif existing.path != skill.path: + if existing is not None: raise SkillPathError( "duplicate", f"NeMo Fabric skill {skill.name!r} is configured twice: " @@ -106,31 +115,82 @@ def resolve_skills( field=field, paths=(existing.path, skill.path), ) + by_name[skill.name] = skill + skills.append(skill) return skills -def _skill_directories(entry: Path) -> list[Path]: - if (entry / SKILL_FILE).is_file(): - return [entry] - return [ - child.resolve() - for child in sorted(entry.iterdir(), key=lambda child: child.name) - if child.is_dir() and (child / SKILL_FILE).is_file() - ] - - -def _skill_name(directory: Path) -> str: - text = (directory / SKILL_FILE).read_text(encoding="utf-8-sig", errors="replace") - front_matter = text.splitlines() - if front_matter[:1] == ["---"]: - for line in front_matter[1:]: - if line.strip() == "---": - break - match = _NAME.fullmatch(line) - if match: - name = match.group(1) - if len(name) >= 2 and name[0] == name[-1] and name[0] in "\"'": - name = name[1:-1] - if name: - return name - return directory.name +def _skill_directories(entry: Path, field: str, configured: Path) -> list[Path]: + try: + if (entry / SKILL_FILE).is_file(): + return [entry] + children = sorted(entry.iterdir(), key=lambda child: child.name) + except OSError: + raise SkillPathError( + "invalid", + f"NeMo Fabric skill path {field} cannot be read: {configured}", + field=field, + paths=(configured,), + ) from None + return [child.resolve() for child in children if _is_skill(child)] + + +def _is_skill(child: Path) -> bool: + # A folder that cannot be read, such as a volume's lost+found, is not a skill. + try: + return child.is_dir() and (child / SKILL_FILE).is_file() + except OSError: + return False + + +def _folder_identity(directory: Path) -> tuple[int, int]: + # Compare folders by identity so that spellings resolve() keeps apart, such + # as a different case on a case-insensitive file system, still match. + stat = directory.stat() + return stat.st_dev, stat.st_ino + + +def _skill_name(directory: Path, field: str) -> str: + skill_file = directory / SKILL_FILE + try: + with skill_file.open(encoding="utf-8-sig", errors="replace") as lines: + name = _front_matter_name(lines) + except OSError: + raise SkillPathError( + "invalid", + f"NeMo Fabric skill path {field} has a {SKILL_FILE} that cannot be " + f"read: {skill_file}", + field=field, + paths=(skill_file,), + ) from None + return name or directory.name + + +def _front_matter_name(lines: Iterable[str]) -> str | None: + """Return the ``name`` scalar of a ``---`` front matter block, if any.""" + + lines = iter(lines) + if next(lines, "").rstrip() != "---": + return None + name: str | None = None + for line in lines: + line = line.rstrip() + if line == "---": + return name + match = _NAME.fullmatch(line) + if match and not name: + name = _scalar(match.group(1) or "") + # Without its closing line the block is not front matter. + return None + + +def _scalar(value: str) -> str: + if value[:1] in ("'", '"'): + end = value.find(value[0], 1) + rest = value[end + 1 :].strip() if end > 0 else "" + if end > 0 and (not rest or rest.startswith("#")): + return value[1:end] + return value + if value.startswith("#"): + return "" + return _COMMENT.split(value, maxsplit=1)[0] diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 3a0c2fb61..1ab594975 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -82,7 +82,7 @@ ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a -folder or two skills share a name; the error names the entry or both skill +readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index de2242ebe..288d6fe59 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -80,7 +80,7 @@ ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an entry does not exist and with `openclaw_skill_invalid` when an entry is not a -folder or two skills share a name; the error names the entry or both skill +readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to OpenClaw's `skills.load.extraDirs`. diff --git a/docs/adapter-contract/tutorials/normalized-configuration.md b/docs/adapter-contract/tutorials/normalized-configuration.md index 1d61073dd..31a512ee5 100644 --- a/docs/adapter-contract/tutorials/normalized-configuration.md +++ b/docs/adapter-contract/tutorials/normalized-configuration.md @@ -71,7 +71,7 @@ skill folders exist. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. An entry that exists but holds no skills loads nothing. Fail start when an entry does not exist, when an entry is not a -folder, or when two skills share a name, and name the entry or both skill +readable folder, or when two skills share a name, and name the entry or both skill folders. A skill's name is the `name` field of its `SKILL.md` front matter, or its folder name. Python adapters can call `nemo_fabric_adapter_contract.skills.resolve_skills(paths, base_dir)`, which diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index d2a065771..260e252c1 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -74,7 +74,7 @@ Replace the endpoint and model, and provide `MODEL_API_KEY` in the adapter envir The adapter supports `instructions.system.mode: replace` and rejects `append`. Tool selectors are Hermes toolset names. `models..top_p` must be between 0 and 1, and `max_tokens` must be positive. A model-level token limit takes precedence over `harness.settings.max_tokens`. If both are omitted, the adapter passes `None` to preserve Hermes' native response token limit behavior for embedded and native interface agents. Use `runtime.max_turns`, not a `max_iterations` harness setting, to control the agent loop. -Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. +Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. ### Hermes Settings diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index 663397c2a..a305a26ad 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -101,7 +101,7 @@ ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an entry does not exist and with `openclaw_skill_invalid` when an entry is not a -folder or two skills share a name; the error names the entry or both skill +readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to OpenClaw's `skills.load.extraDirs`. diff --git a/tests/adapter_contract/test_skills.py b/tests/adapter_contract/test_skills.py index 69acf175b..d39c5a9d6 100644 --- a/tests/adapter_contract/test_skills.py +++ b/tests/adapter_contract/test_skills.py @@ -5,6 +5,8 @@ from __future__ import annotations +from collections.abc import Callable, Iterator +import os from pathlib import Path import pytest @@ -140,3 +142,124 @@ def test_same_skill_listed_twice_loads_once(tmp_path: Path): assert resolve_skills([shared, review], tmp_path) == [ Skill(name="review", path=review.resolve(), field="skills.paths[0]") ] + + +_POSIX_PERMISSIONS = pytest.mark.skipif( + not hasattr(os, "geteuid") or os.geteuid() == 0, + reason="needs POSIX permissions enforced for a non-root user", +) + + +@pytest.fixture(name="lock") +def lock_fixture() -> Iterator[Callable[[Path], Path]]: + """Remove all permissions from a path and restore them after the test.""" + locked: list[Path] = [] + + def lock(path: Path) -> Path: + path.chmod(0) + locked.append(path) + return path + + yield lock + for path in reversed(locked): + path.chmod(0o700) + + +@_POSIX_PERMISSIONS +def test_unreadable_folder_inside_entry_is_ignored( + tmp_path: Path, lock: Callable[[Path], Path] +): + shared = tmp_path / "shared" + one = _skill(shared / "one", "one") + (shared / "lost+found").mkdir() + lock(shared / "lost+found") + + assert resolve_skills([shared], tmp_path) == [ + Skill(name="one", path=one.resolve(), field="skills.paths[0]") + ] + + +@_POSIX_PERMISSIONS +def test_unreadable_entry_fails_naming_it(tmp_path: Path, lock: Callable[[Path], Path]): + review = _skill(tmp_path / "review", "review") + entry = tmp_path / "locked" + entry.mkdir() + lock(entry) + + with pytest.raises(SkillPathError) as caught: + resolve_skills([review, entry], tmp_path) + + assert caught.value.reason == "invalid" + assert caught.value.field == "skills.paths[1]" + assert caught.value.paths == (entry,) + assert "skills.paths[1]" in str(caught.value) + assert str(entry) in str(caught.value) + + +@_POSIX_PERMISSIONS +def test_unreadable_skill_file_fails_naming_it( + tmp_path: Path, lock: Callable[[Path], Path] +): + shared = tmp_path / "shared" + review = _skill(shared / "review", "review") + lock(review / "SKILL.md") + + with pytest.raises(SkillPathError) as caught: + resolve_skills([shared], tmp_path) + + assert caught.value.reason == "invalid" + assert caught.value.field == "skills.paths[0]" + assert caught.value.paths == (review.resolve() / "SKILL.md",) + assert str(review.resolve() / "SKILL.md") in str(caught.value) + + +@pytest.mark.parametrize( + ("text", "name"), + [ + ("---\nname: code-review # main skill\n---\n", "code-review"), + ("---\nname: 'code-review' # quoted\n---\n", "code-review"), + ("---\nname: code#review\n---\n", "code#review"), + ("--- \nname: code-review\n---\n", "code-review"), + ("---\nname:\n---\n", "review"), + ("---\ndescription: Front matter without an end.\nname: code-review\n", "review"), + ("# Review\n\nname: code-review\n", "review"), + ], +) +def test_skill_name_follows_front_matter(tmp_path: Path, text: str, name: str): + review = tmp_path / "review" + review.mkdir() + (review / "SKILL.md").write_text(text, encoding="utf-8") + + assert [skill.name for skill in resolve_skills([review], tmp_path)] == [name] + + +def test_skill_md_folder_does_not_make_a_skill(tmp_path: Path): + shared = tmp_path / "shared" + (shared / "SKILL.md").mkdir(parents=True) + one = _skill(shared / "one", "one") + + assert resolve_skills([shared], tmp_path) == [ + Skill(name="one", path=one.resolve(), field="skills.paths[0]") + ] + + +@pytest.mark.parametrize("spelling", ["review/", "./review", "other/../review", "link"]) +def test_same_skill_spelled_differently_loads_once(tmp_path: Path, spelling: str): + review = _skill(tmp_path / "review", "review") + (tmp_path / "other").mkdir() + if spelling == "link": + (tmp_path / "link").symlink_to(review, target_is_directory=True) + + assert resolve_skills(["review", spelling], tmp_path) == [ + Skill(name="review", path=review.resolve(), field="skills.paths[0]") + ] + + +def test_same_skill_in_another_case_loads_once(tmp_path: Path): + review = _skill(tmp_path / "Review") + if not (tmp_path / "review").exists(): + pytest.skip("needs a case-insensitive file system") + + assert resolve_skills(["Review", "review"], tmp_path) == [ + Skill(name="Review", path=review.resolve(), field="skills.paths[0]") + ] From c7851d6a5513f51967389beb8d409c84d8e42ae8 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 6 Nov 2026 20:07:02 -0700 Subject: [PATCH 35/54] docs: say that a skills.paths entry that is not a folder fails The contract field description named only a missing entry and duplicate names; resolve_skills also fails an entry that is not a folder. Regenerate the schema snapshots, TypeScript declarations, and Rust reference. Signed-off-by: Carlos Villela --- adapter-contract/typescript/schemas/agent-config.schema.json | 2 +- adapter-contract/typescript/src/generated/agent-config.ts | 3 ++- crates/fabric-core/src/agent_config.rs | 3 ++- .../nemo-fabric-core/agent-config/struct-agentskillconfig.mdx | 2 +- schemas/adapter-contract/agent-config.schema.json | 2 +- schemas/sdk/run-plan.schema.json | 2 +- 6 files changed, 8 insertions(+), 6 deletions(-) diff --git a/adapter-contract/typescript/schemas/agent-config.schema.json b/adapter-contract/typescript/schemas/agent-config.schema.json index 179b820fa..e8965d4cb 100644 --- a/adapter-contract/typescript/schemas/agent-config.schema.json +++ b/adapter-contract/typescript/schemas/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. A missing entry, or two skills with the same name, fails.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing or is not a folder, or two skills\nwith the same name, fails.", "items": { "type": "string" }, diff --git a/adapter-contract/typescript/src/generated/agent-config.ts b/adapter-contract/typescript/src/generated/agent-config.ts index 8a7d30618..d3c999976 100644 --- a/adapter-contract/typescript/src/generated/agent-config.ts +++ b/adapter-contract/typescript/src/generated/agent-config.ts @@ -289,7 +289,8 @@ export interface AgentSkillConfig { * Skill paths resolved for the task environment. An entry that contains * `SKILL.md` is one skill; otherwise each folder directly inside it that * contains `SKILL.md` is a skill. An entry that holds no skills loads - * nothing. A missing entry, or two skills with the same name, fails. + * nothing. An entry that is missing or is not a folder, or two skills + * with the same name, fails. */ paths?: string[]; } diff --git a/crates/fabric-core/src/agent_config.rs b/crates/fabric-core/src/agent_config.rs index 542873f06..f7e59a4c7 100644 --- a/crates/fabric-core/src/agent_config.rs +++ b/crates/fabric-core/src/agent_config.rs @@ -143,7 +143,8 @@ pub struct AgentSkillConfig { /// Skill paths resolved for the task environment. An entry that contains /// `SKILL.md` is one skill; otherwise each folder directly inside it that /// contains `SKILL.md` is a skill. An entry that holds no skills loads - /// nothing. A missing entry, or two skills with the same name, fails. + /// nothing. An entry that is missing or is not a folder, or two skills + /// with the same name, fails. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub paths: Vec, /// Adapter-owned skill fields. diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx index cc0facd2e..33b4b6751 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx @@ -18,7 +18,7 @@ Skill paths made available to an adapter target. ### `paths: Vec` -Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. A missing entry, or two skills with the same name, fails. +Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. An entry that is missing or is not a folder, or two skills with the same name, fails. ### `extensions: BTreeMap` diff --git a/schemas/adapter-contract/agent-config.schema.json b/schemas/adapter-contract/agent-config.schema.json index 179b820fa..e8965d4cb 100644 --- a/schemas/adapter-contract/agent-config.schema.json +++ b/schemas/adapter-contract/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. A missing entry, or two skills with the same name, fails.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing or is not a folder, or two skills\nwith the same name, fails.", "items": { "type": "string" }, diff --git a/schemas/sdk/run-plan.schema.json b/schemas/sdk/run-plan.schema.json index 293323ebd..5517f5ef2 100644 --- a/schemas/sdk/run-plan.schema.json +++ b/schemas/sdk/run-plan.schema.json @@ -769,7 +769,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. A missing entry, or two skills with the same name, fails.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing or is not a folder, or two skills\nwith the same name, fails.", "items": { "type": "string" }, From 14071d8d43093eb4c98887e18a712c88ddeb7f5f Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 6 Nov 2026 20:07:44 -0700 Subject: [PATCH 36/54] test: read and write skill test files as UTF-8 Signed-off-by: Carlos Villela --- tests/adapter_contract/test_skills.py | 5 ++++- tests/adapters/test_hermes_adapter.py | 4 +++- tests/e2e/test_hermes_e2e.py | 4 +++- tests/e2e/test_openclaw_skills.py | 4 ++-- 4 files changed, 12 insertions(+), 5 deletions(-) diff --git a/tests/adapter_contract/test_skills.py b/tests/adapter_contract/test_skills.py index d39c5a9d6..1d911338a 100644 --- a/tests/adapter_contract/test_skills.py +++ b/tests/adapter_contract/test_skills.py @@ -221,7 +221,10 @@ def test_unreadable_skill_file_fails_naming_it( ("---\nname: code#review\n---\n", "code#review"), ("--- \nname: code-review\n---\n", "code-review"), ("---\nname:\n---\n", "review"), - ("---\ndescription: Front matter without an end.\nname: code-review\n", "review"), + ( + "---\ndescription: Front matter without an end.\nname: code-review\n", + "review", + ), ("# Review\n\nname: code-review\n", "review"), ], ) diff --git a/tests/adapters/test_hermes_adapter.py b/tests/adapters/test_hermes_adapter.py index a5495453a..d03d73da5 100644 --- a/tests/adapters/test_hermes_adapter.py +++ b/tests/adapters/test_hermes_adapter.py @@ -717,7 +717,9 @@ def test_hermes_config_variation_matrix_surfaces_supported_capabilities( ) payload["config"] = agent_config.to_mapping() (tmp_path / "skills" / "review").mkdir(parents=True) - (tmp_path / "skills" / "review" / "SKILL.md").write_text("# Review\n") + (tmp_path / "skills" / "review" / "SKILL.md").write_text( + "# Review\n", encoding="utf-8" + ) config = configuration.build_hermes_config( agent_config, diff --git a/tests/e2e/test_hermes_e2e.py b/tests/e2e/test_hermes_e2e.py index 3d9c754e1..7e50170e5 100644 --- a/tests/e2e/test_hermes_e2e.py +++ b/tests/e2e/test_hermes_e2e.py @@ -319,7 +319,9 @@ async def test_skill_selection( ), loaded else: skill_dir = {"default": default_skill, "alternate": alternate_skill}[skill] - assert loaded["content"] == (skill_dir / "SKILL.md").read_text(), loaded + assert loaded["content"] == (skill_dir / "SKILL.md").read_text( + encoding="utf-8" + ), loaded def _write_skill(directory: Path, name: str) -> Path: diff --git a/tests/e2e/test_openclaw_skills.py b/tests/e2e/test_openclaw_skills.py index 7c3eac01b..8768f5dbd 100644 --- a/tests/e2e/test_openclaw_skills.py +++ b/tests/e2e/test_openclaw_skills.py @@ -25,7 +25,7 @@ def openclaw_package_fixture() -> Path: if configured is None: pytest.skip("OPENCLAW_TEST_PACKAGE must name the installed native package") package = Path(configured).resolve() - manifest = json.loads((package / "package.json").read_text()) + manifest = json.loads((package / "package.json").read_text(encoding="utf-8")) assert manifest["version"] in adapter.SUPPORTED_OPENCLAW_VERSIONS return package @@ -75,7 +75,7 @@ def _load_natively( ) -> list[dict]: native = _native_config(tmp_path, paths) config_path = tmp_path / "openclaw.json" - config_path.write_text(json.dumps(native)) + config_path.write_text(json.dumps(native), encoding="utf-8") home = tmp_path / "home" home.mkdir() probe = Path(__file__).parents[1] / "_utils" / "openclaw_skills.mjs" From b06bd9c5d31e74e3ae15450f8fd46876083f9157 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 05:30:56 -0700 Subject: [PATCH 37/54] feat: resolve skill folders in the TypeScript adapter contract nemo-fabric-adapter-contract/skills exports resolveSkills, which applies the same skills.paths rule as the Python contract's resolve_skills: an entry with SKILL.md is one skill, otherwise each folder directly inside it with SKILL.md is a skill; a missing, non-folder, or unreadable entry, an unreadable SKILL.md, or two resolved skills with one name fail with SkillPathError. The module uses Node.js file system APIs, so it is a separate entry point and the package root stays free of them. The tests mirror the Python contract's cases; @types/node is a new development dependency, pinned to the Node.js 20 floor. Signed-off-by: Carlos Villela --- adapter-contract/typescript/README.md | 19 ++ adapter-contract/typescript/package-lock.json | 18 ++ adapter-contract/typescript/package.json | 8 +- .../typescript/scripts/check-package.mjs | 10 +- adapter-contract/typescript/src/skills.ts | 266 +++++++++++++++++ .../typescript/test/skills.test.mjs | 278 ++++++++++++++++++ tests/adapter_contract/test_skills.py | 1 + 7 files changed, 598 insertions(+), 2 deletions(-) create mode 100644 adapter-contract/typescript/src/skills.ts create mode 100644 adapter-contract/typescript/test/skills.test.mjs diff --git a/adapter-contract/typescript/README.md b/adapter-contract/typescript/README.md index 59a73768a..b57e3620e 100644 --- a/adapter-contract/typescript/README.md +++ b/adapter-contract/typescript/README.md @@ -60,6 +60,25 @@ Use the maintained for the implementation sequence and the bundled schemas for runtime validation. +## Skill Paths + +The `nemo-fabric-adapter-contract/skills` entry point resolves `skills.paths` +in the task environment with Node.js file system APIs. Each entry is a skill +folder or a folder of skills: + +```typescript +import { resolveSkills, SkillPathError } from "nemo-fabric-adapter-contract/skills"; + +const skills = await resolveSkills(config.skills?.paths ?? [], baseDir); +``` + +The helper returns each skill's name, resolved folder, and `skills.paths[N]` +field. It rejects with `SkillPathError` when an entry does not exist or is not +a readable folder, when a skill's `SKILL.md` cannot be read, or when two skills +share a name. It applies the same rules as the Python contract's +`nemo_fabric_adapter_contract.skills.resolve_skills`; refer to the +[normalized configuration tutorial](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/adapter-contract/tutorials/normalized-configuration.md). + ## Invocation Types The package root also exports the same request and result models as the Python diff --git a/adapter-contract/typescript/package-lock.json b/adapter-contract/typescript/package-lock.json index 6b8242c27..69f6e1f08 100644 --- a/adapter-contract/typescript/package-lock.json +++ b/adapter-contract/typescript/package-lock.json @@ -9,6 +9,7 @@ "version": "0.7.0", "license": "Apache-2.0", "devDependencies": { + "@types/node": "20.19.43", "json-schema-to-typescript": "15.0.4", "typescript": "5.6.3" }, @@ -55,6 +56,16 @@ "dev": true, "license": "MIT" }, + "node_modules/@types/node": { + "version": "20.19.43", + "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz", + "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==", + "dev": true, + "license": "MIT", + "dependencies": { + "undici-types": "~6.21.0" + } + }, "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", @@ -226,6 +237,13 @@ "engines": { "node": ">=14.17" } + }, + "node_modules/undici-types": { + "version": "6.21.0", + "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", + "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", + "dev": true, + "license": "MIT" } } } diff --git a/adapter-contract/typescript/package.json b/adapter-contract/typescript/package.json index b934f8a66..c07f659bb 100644 --- a/adapter-contract/typescript/package.json +++ b/adapter-contract/typescript/package.json @@ -11,6 +11,10 @@ "types": "./dist/index.d.ts", "import": "./dist/index.js" }, + "./skills": { + "types": "./dist/skills.d.ts", + "import": "./dist/skills.js" + }, "./schemas/*": "./schemas/*.schema.json", "./package.json": "./package.json" }, @@ -26,9 +30,10 @@ "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json", "test:generator": "node --test test/*.test.mjs", "test:types": "tsc -p test/tsconfig.json --noEmit", + "test:skills": "npm run build && node --test test/skills.test.mjs", "test:dependencies": "node scripts/check-dependencies.mjs && npm ls --all && npm audit --audit-level=high", "pack:check": "npm run build && node scripts/check-package.mjs", - "test": "npm run generate:check && npm run test:generator && npm run test:types && npm run test:dependencies && npm run pack:check", + "test": "npm run generate:check && npm run test:generator && npm run test:types && npm run test:skills && npm run test:dependencies && npm run pack:check", "prepack": "npm run generate:check && npm run build" }, "publishConfig": { @@ -48,6 +53,7 @@ "node": ">=20.18.3" }, "devDependencies": { + "@types/node": "20.19.43", "json-schema-to-typescript": "15.0.4", "typescript": "5.6.3" } diff --git a/adapter-contract/typescript/scripts/check-package.mjs b/adapter-contract/typescript/scripts/check-package.mjs index bda0fa56e..878b51fa6 100644 --- a/adapter-contract/typescript/scripts/check-package.mjs +++ b/adapter-contract/typescript/scripts/check-package.mjs @@ -54,6 +54,8 @@ try { "dist/index.js", "dist/json.d.ts", "dist/json.js", + "dist/skills.d.ts", + "dist/skills.js", "dist/version.d.ts", "dist/version.js", "package.json", @@ -134,6 +136,8 @@ import agentConfigSchema from "nemo-fabric-adapter-contract/schemas/agent-config import type { AdapterDescriptor } from "nemo-fabric-adapter-contract"; import type { AdapterTargetDescriptor } from "nemo-fabric-adapter-contract"; import type { AgentRunResult } from "nemo-fabric-adapter-contract"; +import { resolveSkills, SkillPathError } from "nemo-fabric-adapter-contract/skills"; +import type { Skill } from "nemo-fabric-adapter-contract/skills"; const descriptor: AdapterDescriptor = { adapter_id: "example", @@ -147,6 +151,8 @@ const target: AdapterTargetDescriptor = { spec: { entrypoint: { kind: "factory", ref: "example.agent" } }, type: "workflow", }; +const skills: Skill[] = []; +void skills; const result: AgentRunResult = { output: ["ok", null], status: "succeeded", @@ -155,7 +161,9 @@ if ( descriptor.contract_version !== ADAPTER_CONTRACT_VERSION || target.adapter_id !== descriptor.adapter_id || result.status !== "succeeded" || - agentConfigSchema.title !== "AgentConfig" + agentConfigSchema.title !== "AgentConfig" || + (await resolveSkills([], "/")).length !== 0 || + new SkillPathError("invalid", "example", { field: "skills.paths[0]", paths: [] }).reason !== "invalid" ) { throw new Error("Unexpected adapter contract values"); } diff --git a/adapter-contract/typescript/src/skills.ts b/adapter-contract/typescript/src/skills.ts new file mode 100644 index 000000000..2ea983d5a --- /dev/null +++ b/adapter-contract/typescript/src/skills.ts @@ -0,0 +1,266 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +/** + * Resolve `skills.paths` entries in the task environment. + * + * Each entry names one skill or a folder of skills: + * + * 1. An entry that contains `SKILL.md` is one skill. + * 2. Otherwise each folder directly inside the entry that contains `SKILL.md` + * is a skill. Other files and folders, including folders that cannot be + * read, are ignored. + * 3. An entry that exists but holds no skills loads nothing. + * 4. An entry that does not exist, is not a folder, or cannot be read fails. + * 5. Two skills with the same name fail. The same folder reached through + * several entries loads once. + * + * A skill's name is the `name` field of its `SKILL.md` front matter, or its + * folder name when the front matter has none. + * + * This module uses Node.js file system APIs; import it from + * `nemo-fabric-adapter-contract/skills`. + * + * @module + */ + +import type { FileHandle } from "node:fs/promises"; +import { open, readdir, realpath, stat } from "node:fs/promises"; +import { basename, isAbsolute, join, sep } from "node:path"; + +/** File that marks a folder as a skill. */ +export const SKILL_FILE = "SKILL.md"; + +/** Why a `skills.paths` entry cannot be loaded. */ +export type SkillPathFailure = "not_found" | "invalid" | "duplicate"; + +/** One skill found through `skills.paths`. */ +export interface Skill { + /** Name from the skill's front matter, or its folder name. */ + readonly name: string; + /** Resolved folder that contains the skill's `SKILL.md`. */ + readonly path: string; + /** The `skills.paths` entry that supplied the skill, such as `skills.paths[0]`. */ + readonly field: string; +} + +/** A `skills.paths` entry that cannot be loaded. */ +export class SkillPathError extends Error { + override readonly name = "SkillPathError"; + readonly reason: SkillPathFailure; + readonly field: string; + readonly paths: readonly string[]; + + constructor( + reason: SkillPathFailure, + message: string, + options: { field: string; paths: readonly string[] }, + ) { + super(message); + this.reason = reason; + this.field = options.field; + this.paths = options.paths; + } +} + +const NAME = /^name:(?:[ \t]+(.*?))?[ \t]*$/; +const COMMENT = /[ \t]+#/; + +/** + * Return the skills named by `paths`, resolving relative entries against + * `baseDir`. + * + * @throws {SkillPathError} If an entry does not exist, is not a folder, or + * cannot be read, if a skill's `SKILL.md` cannot be read, or if two skills + * share a name. + */ +export async function resolveSkills( + paths: Iterable, + baseDir: string, +): Promise { + const skills: Skill[] = []; + const byName = new Map(); + const folders = new Set(); + let index = 0; + for (const value of paths) { + const field = `skills.paths[${index}]`; + index += 1; + // Do not normalize ".." here: realpath follows symbolic links before "..". + const configured = isAbsolute(value) ? value : `${baseDir}${sep}${value}`; + let entry: string; + try { + entry = await realpath(configured); + } catch { + throw new SkillPathError( + "not_found", + `NeMo Fabric skill path ${field} does not exist: ${configured}`, + { field, paths: [configured] }, + ); + } + if (!(await isDirectory(entry))) { + throw new SkillPathError( + "invalid", + `NeMo Fabric skill path ${field} is not a folder: ${configured}`, + { field, paths: [configured] }, + ); + } + for (const directory of await skillDirectories(entry, field, configured)) { + const folder = await folderIdentity(directory); + if (folders.has(folder)) { + continue; + } + folders.add(folder); + const skill: Skill = { + name: await skillName(directory, field), + path: directory, + field, + }; + const existing = byName.get(skill.name); + if (existing !== undefined) { + throw new SkillPathError( + "duplicate", + `NeMo Fabric skill '${skill.name}' is configured twice: ` + + `${existing.path} (${existing.field}) and ${skill.path} (${field})`, + { field, paths: [existing.path, skill.path] }, + ); + } + byName.set(skill.name, skill); + skills.push(skill); + } + } + return skills; +} + +async function skillDirectories( + entry: string, + field: string, + configured: string, +): Promise { + let children: string[]; + try { + if (await isFile(join(entry, SKILL_FILE))) { + return [entry]; + } + children = (await readdir(entry)).sort(compareNames); + } catch { + throw new SkillPathError( + "invalid", + `NeMo Fabric skill path ${field} cannot be read: ${configured}`, + { field, paths: [configured] }, + ); + } + const directories: string[] = []; + for (const child of children) { + const path = join(entry, child); + // A folder that cannot be read, such as a volume's lost+found, is not a skill. + try { + if ((await isDirectory(path)) && (await isFile(join(path, SKILL_FILE)))) { + directories.push(await realpath(path)); + } + } catch { + continue; + } + } + return directories; +} + +function compareNames(left: string, right: string): number { + return left < right ? -1 : left > right ? 1 : 0; +} + +const MISSING = new Set(["ENOENT", "ENOTDIR", "ELOOP"]); + +async function isDirectory(path: string): Promise { + try { + return (await stat(path)).isDirectory(); + } catch (error) { + if (MISSING.has(errorCode(error))) { + return false; + } + throw error; + } +} + +async function isFile(path: string): Promise { + try { + return (await stat(path)).isFile(); + } catch (error) { + if (MISSING.has(errorCode(error))) { + return false; + } + throw error; + } +} + +function errorCode(error: unknown): string { + return typeof error === "object" && error !== null && "code" in error + ? String(error.code) + : ""; +} + +async function folderIdentity(directory: string): Promise { + // Compare folders by identity so that spellings realpath keeps apart, such + // as a different case on a case-insensitive file system, still match. + const info = await stat(directory, { bigint: true }); + return `${info.dev}:${info.ino}`; +} + +async function skillName(directory: string, field: string): Promise { + const skillFile = join(directory, SKILL_FILE); + let handle: FileHandle | undefined; + let name: string | undefined; + try { + handle = await open(skillFile, "r"); + name = await frontMatterName(handle); + } catch { + throw new SkillPathError( + "invalid", + `NeMo Fabric skill path ${field} has a ${SKILL_FILE} that cannot be read: ${skillFile}`, + { field, paths: [skillFile] }, + ); + } finally { + await handle?.close(); + } + return name || basename(directory); +} + +/** Return the `name` scalar of a `---` front matter block, if any. */ +async function frontMatterName(handle: FileHandle): Promise { + let first = true; + let name: string | undefined; + for await (let line of handle.readLines({ encoding: "utf8", autoClose: false })) { + line = line.trimEnd(); + if (first) { + first = false; + if (line.replace(/^\uFEFF/, "") !== "---") { + return undefined; + } + continue; + } + if (line === "---") { + return name; + } + const match = NAME.exec(line); + if (match !== null && !name) { + name = scalar(match[1] ?? ""); + } + } + // Without its closing line the block is not front matter. + return undefined; +} + +function scalar(value: string): string { + const quote = value[0]; + if (quote === "'" || quote === '"') { + const end = value.indexOf(quote, 1); + const rest = end > 0 ? value.slice(end + 1).trim() : ""; + if (end > 0 && (rest === "" || rest.startsWith("#"))) { + return value.slice(1, end); + } + return value; + } + if (value.startsWith("#")) { + return ""; + } + return value.split(COMMENT, 1)[0] ?? ""; +} diff --git a/adapter-contract/typescript/test/skills.test.mjs b/adapter-contract/typescript/test/skills.test.mjs new file mode 100644 index 000000000..1b138e4b4 --- /dev/null +++ b/adapter-contract/typescript/test/skills.test.mjs @@ -0,0 +1,278 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +// Resolve skills.paths entries that name a skill or a folder of skills. These +// cases mirror tests/adapter_contract/test_skills.py for the Python contract. + +import assert from "node:assert/strict"; +import { chmod, mkdir, mkdtemp, realpath, rm, symlink, writeFile } from "node:fs/promises"; +import { existsSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; + +import { resolveSkills, SkillPathError } from "../dist/skills.js"; + +const posixPermissions = + typeof process.geteuid === "function" && process.geteuid() !== 0 + ? {} + : { skip: "needs POSIX permissions enforced for a non-root user" }; + +async function temporary(t) { + const root = await realpath(await mkdtemp(join(tmpdir(), "fabric-skills-"))); + const locked = []; + t.after(async () => { + for (const path of locked.reverse()) { + await chmod(path, 0o700); + } + await rm(root, { recursive: true, force: true }); + }); + return { + root, + async lock(path) { + await chmod(path, 0); + locked.push(path); + return path; + }, + }; +} + +async function skill(directory, name) { + await mkdir(directory, { recursive: true }); + const frontMatter = name ? `---\nname: ${name}\ndescription: Test skill.\n---\n` : ""; + await writeFile(join(directory, "SKILL.md"), `${frontMatter}# Test skill\n`, "utf8"); + return directory; +} + +async function rejection(promise) { + try { + await promise; + } catch (error) { + assert.ok(error instanceof SkillPathError, String(error)); + return error; + } + assert.fail("expected a SkillPathError"); +} + +test("an entry with SKILL.md is one skill", async (t) => { + const { root } = await temporary(t); + const review = await skill(join(root, "review"), "code-review"); + + assert.deepEqual(await resolveSkills([review], root), [ + { name: "code-review", path: review, field: "skills.paths[0]" }, + ]); +}); + +test("a skill's name falls back to its folder", async (t) => { + const { root } = await temporary(t); + const review = await skill(join(root, "review")); + + assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), ["review"]); +}); + +test("a quoted front matter name is unquoted", async (t) => { + const { root } = await temporary(t); + const review = join(root, "review"); + await mkdir(review); + await writeFile(join(review, "SKILL.md"), '---\r\nname: "code-review"\r\n---\r\n', "utf8"); + + assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), ["code-review"]); +}); + +test("a folder loads the skills directly inside it", async (t) => { + const { root } = await temporary(t); + const shared = join(root, "shared"); + const one = await skill(join(shared, "one"), "one"); + const two = await skill(join(shared, "two"), "two"); + await writeFile(join(shared, "notes.md"), "Not a skill.\n", "utf8"); + await mkdir(join(shared, "docs")); + await writeFile(join(shared, "docs", "README.md"), "Not a skill.\n", "utf8"); + await skill(join(shared, "group", "nested"), "nested"); + + assert.deepEqual(await resolveSkills([shared], root), [ + { name: "one", path: one, field: "skills.paths[0]" }, + { name: "two", path: two, field: "skills.paths[0]" }, + ]); +}); + +test("a folder and a separate skill mix", async (t) => { + const { root } = await temporary(t); + const shared = join(root, "shared"); + await skill(join(shared, "one"), "one"); + await skill(join(shared, "two"), "two"); + const separate = await skill(join(root, "mounted", "three"), "three"); + + const skills = await resolveSkills([shared, separate], root); + + assert.deepEqual(skills.map((s) => [s.name, s.field]), [ + ["one", "skills.paths[0]"], + ["two", "skills.paths[0]"], + ["three", "skills.paths[1]"], + ]); +}); + +test("an existing entry without skills loads nothing", async (t) => { + const { root } = await temporary(t); + await mkdir(join(root, "empty")); + + assert.deepEqual(await resolveSkills([join(root, "empty")], root), []); +}); + +test("a relative entry resolves against the base folder", async (t) => { + const { root } = await temporary(t); + const review = await skill(join(root, "skills", "review"), "review"); + + assert.deepEqual(await resolveSkills(["skills/review"], root), [ + { name: "review", path: review, field: "skills.paths[0]" }, + ]); +}); + +test("a missing entry fails naming it", async (t) => { + const { root } = await temporary(t); + const review = await skill(join(root, "review"), "review"); + const missing = join(root, "missing"); + + const error = await rejection(resolveSkills([review, missing], root)); + + assert.equal(error.reason, "not_found"); + assert.equal(error.field, "skills.paths[1]"); + assert.deepEqual(error.paths, [missing]); + assert.match(error.message, /skills\.paths\[1\]/); + assert.ok(error.message.includes(missing), error.message); +}); + +test("a file entry fails", async (t) => { + const { root } = await temporary(t); + const entry = join(root, "SKILL.md"); + await writeFile(entry, "# Not a folder\n", "utf8"); + + const error = await rejection(resolveSkills([entry], root)); + + assert.equal(error.reason, "invalid"); + assert.equal(error.field, "skills.paths[0]"); + assert.ok(error.message.includes(entry), error.message); +}); + +test("duplicate skill names fail naming both folders", async (t) => { + const { root } = await temporary(t); + const shared = join(root, "shared"); + const first = await skill(join(shared, "review"), "review"); + const second = await skill(join(root, "mounted", "review-copy"), "review"); + + const error = await rejection(resolveSkills([shared, second], root)); + + assert.equal(error.reason, "duplicate"); + assert.equal(error.field, "skills.paths[1]"); + assert.deepEqual(error.paths, [first, second]); + assert.ok(error.message.includes(first) && error.message.includes(second), error.message); +}); + +test("the same skill listed twice loads once", async (t) => { + const { root } = await temporary(t); + const shared = join(root, "shared"); + const review = await skill(join(shared, "review"), "review"); + + assert.deepEqual(await resolveSkills([shared, review], root), [ + { name: "review", path: review, field: "skills.paths[0]" }, + ]); +}); + +test("an unreadable folder inside an entry is ignored", posixPermissions, async (t) => { + const { root, lock } = await temporary(t); + const shared = join(root, "shared"); + const one = await skill(join(shared, "one"), "one"); + await mkdir(join(shared, "lost+found")); + await lock(join(shared, "lost+found")); + + assert.deepEqual(await resolveSkills([shared], root), [ + { name: "one", path: one, field: "skills.paths[0]" }, + ]); +}); + +test("an unreadable entry fails naming it", posixPermissions, async (t) => { + const { root, lock } = await temporary(t); + const review = await skill(join(root, "review"), "review"); + const entry = join(root, "locked"); + await mkdir(entry); + await lock(entry); + + const error = await rejection(resolveSkills([review, entry], root)); + + assert.equal(error.reason, "invalid"); + assert.equal(error.field, "skills.paths[1]"); + assert.deepEqual(error.paths, [entry]); + assert.ok(error.message.includes(entry), error.message); +}); + +test("an unreadable SKILL.md fails naming it", posixPermissions, async (t) => { + const { root, lock } = await temporary(t); + const shared = join(root, "shared"); + const review = await skill(join(shared, "review"), "review"); + await lock(join(review, "SKILL.md")); + + const error = await rejection(resolveSkills([shared], root)); + + assert.equal(error.reason, "invalid"); + assert.equal(error.field, "skills.paths[0]"); + assert.deepEqual(error.paths, [join(review, "SKILL.md")]); + assert.ok(error.message.includes(join(review, "SKILL.md")), error.message); +}); + +for (const [text, name] of [ + ["---\nname: code-review # main skill\n---\n", "code-review"], + ["---\nname: 'code-review' # quoted\n---\n", "code-review"], + ["---\nname: code#review\n---\n", "code#review"], + ["--- \nname: code-review\n---\n", "code-review"], + ["\uFEFF---\nname: code-review\n---\n", "code-review"], + ["---\nname:\n---\n", "review"], + ["---\ndescription: Front matter without an end.\nname: code-review\n", "review"], + ["# Review\n\nname: code-review\n", "review"], +]) { + test(`a skill's name follows its front matter: ${JSON.stringify(text)}`, async (t) => { + const { root } = await temporary(t); + const review = join(root, "review"); + await mkdir(review); + await writeFile(join(review, "SKILL.md"), text, "utf8"); + + assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), [name]); + }); +} + +test("a SKILL.md folder does not make a skill", async (t) => { + const { root } = await temporary(t); + const shared = join(root, "shared"); + await mkdir(join(shared, "SKILL.md"), { recursive: true }); + const one = await skill(join(shared, "one"), "one"); + + assert.deepEqual(await resolveSkills([shared], root), [ + { name: "one", path: one, field: "skills.paths[0]" }, + ]); +}); + +for (const spelling of ["review/", "./review", "other/../review", "link"]) { + test(`the same skill spelled ${spelling} loads once`, async (t) => { + const { root } = await temporary(t); + const review = await skill(join(root, "review"), "review"); + await mkdir(join(root, "other")); + if (spelling === "link") { + await symlink(review, join(root, "link"), "dir"); + } + + assert.deepEqual(await resolveSkills(["review", spelling], root), [ + { name: "review", path: review, field: "skills.paths[0]" }, + ]); + }); +} + +test("the same skill in another case loads once", async (t) => { + const { root } = await temporary(t); + const review = await skill(join(root, "Review")); + if (!existsSync(join(root, "review"))) { + t.skip("needs a case-insensitive file system"); + return; + } + + assert.deepEqual(await resolveSkills(["Review", "review"], root), [ + { name: "Review", path: review, field: "skills.paths[0]" }, + ]); +}); diff --git a/tests/adapter_contract/test_skills.py b/tests/adapter_contract/test_skills.py index 1d911338a..8f2ba184e 100644 --- a/tests/adapter_contract/test_skills.py +++ b/tests/adapter_contract/test_skills.py @@ -220,6 +220,7 @@ def test_unreadable_skill_file_fails_naming_it( ("---\nname: 'code-review' # quoted\n---\n", "code-review"), ("---\nname: code#review\n---\n", "code#review"), ("--- \nname: code-review\n---\n", "code-review"), + ("\ufeff---\nname: code-review\n---\n", "code-review"), ("---\nname:\n---\n", "review"), ( "---\ndescription: Front matter without an end.\nname: code-review\n", From 7370baf6ecfa28eb971e60c2ea200c89c7721b44 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 05:30:57 -0700 Subject: [PATCH 38/54] docs: say which adapters load skill folders and how harnesses differ The skills.paths contract text now names the adapters that follow the folder rule (OpenClaw and Hermes Agent) and says an unreadable entry fails. A new Load Skills from Folders page states the rule and a table of known harness differences: Hermes Agent loads skills nested inside a skill folder, looks skills up by name, folder name, and path, requires exactly SKILL.md, and cuts names to 64 characters; NeMo Fabric's duplicate check sees only the skills it resolves, loads hidden folders, and does not expand ~ or ${VAR}. Signed-off-by: Carlos Villela --- ATTRIBUTIONS-Node.md | 31 +++++++++++++++ .../schemas/agent-config.schema.json | 2 +- .../typescript/src/generated/agent-config.ts | 6 ++- adapters/python/hermes/README.md | 4 +- adapters/python/openclaw/README.md | 4 +- crates/fabric-core/src/agent_config.rs | 6 ++- .../tutorials/normalized-configuration.md | 11 ++++-- docs/index.yml | 2 + docs/integrations/harness/hermes.mdx | 2 +- docs/integrations/harness/openclaw.mdx | 3 +- docs/integrations/harness/skills.mdx | 39 +++++++++++++++++++ .../agent-config/struct-agentskillconfig.mdx | 2 +- .../adapter-contract/agent-config.schema.json | 2 +- schemas/sdk/run-plan.schema.json | 2 +- skills/nemo-fabric-build-adapter/SKILL.md | 11 +++++- 15 files changed, 110 insertions(+), 17 deletions(-) create mode 100644 docs/integrations/harness/skills.mdx diff --git a/ATTRIBUTIONS-Node.md b/ATTRIBUTIONS-Node.md index e9bbf1fe6..c78e749ce 100644 --- a/ATTRIBUTIONS-Node.md +++ b/ATTRIBUTIONS-Node.md @@ -24608,6 +24608,37 @@ MIT License SOFTWARE ``` +## @types/node - 20.19.43 + +**Repository URL**: https://github.com/DefinitelyTyped/DefinitelyTyped +**License Type(s)**: MIT + +### License: https://spdx.org/licenses/MIT.html + +``` +MIT License + + Copyright (c) Microsoft Corporation. + + Permission is hereby granted, free of charge, to any person obtaining a copy + of this software and associated documentation files (the "Software"), to deal + in the Software without restriction, including without limitation the rights + to use, copy, modify, merge, publish, distribute, sublicense, and/or sell + copies of the Software, and to permit persons to whom the Software is + furnished to do so, subject to the following conditions: + + The above copyright notice and this permission notice shall be included in all + copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR + IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, + FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE + AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER + LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, + OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE + SOFTWARE +``` + ## @types/node - 22.19.19 **Repository URL**: https://github.com/DefinitelyTyped/DefinitelyTyped diff --git a/adapter-contract/typescript/schemas/agent-config.schema.json b/adapter-contract/typescript/schemas/agent-config.schema.json index e8965d4cb..bd14d3b13 100644 --- a/adapter-contract/typescript/schemas/agent-config.schema.json +++ b/adapter-contract/typescript/schemas/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing or is not a folder, or two skills\nwith the same name, fails.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", "items": { "type": "string" }, diff --git a/adapter-contract/typescript/src/generated/agent-config.ts b/adapter-contract/typescript/src/generated/agent-config.ts index d3c999976..cf6848298 100644 --- a/adapter-contract/typescript/src/generated/agent-config.ts +++ b/adapter-contract/typescript/src/generated/agent-config.ts @@ -289,8 +289,10 @@ export interface AgentSkillConfig { * Skill paths resolved for the task environment. An entry that contains * `SKILL.md` is one skill; otherwise each folder directly inside it that * contains `SKILL.md` is a skill. An entry that holds no skills loads - * nothing. An entry that is missing or is not a folder, or two skills - * with the same name, fails. + * nothing. An entry that is missing, is not a folder, or cannot be read, + * or two resolved skills with the same name, fails. The OpenClaw and + * Hermes Agent adapters follow this rule; other adapters require each + * entry to contain `SKILL.md`. */ paths?: string[]; } diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 1ab594975..97068f734 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -85,7 +85,9 @@ entry does not exist and with `hermes_skill_invalid` when an entry is not a readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured -folder. +folder. Hermes Agent still loads skills nested inside a skill folder; refer to +[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx) for +this and other differences in how Hermes Agent loads skills. During run-plan resolution, NeMo Fabric Core validates the `models..top_p` (from 0 through 1) and positive diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index 288d6fe59..5a08e29da 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -82,7 +82,9 @@ empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an entry does not exist and with `openclaw_skill_invalid` when an entry is not a readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to OpenClaw's -`skills.load.extraDirs`. +`skills.load.extraDirs`. Refer to +[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx) for +how harnesses differ when they load skills. For custom OpenAI-compatible providers, set `models..base_url`; the adapter generates an OpenClaw custom provider using the diff --git a/crates/fabric-core/src/agent_config.rs b/crates/fabric-core/src/agent_config.rs index f7e59a4c7..f7cd72f61 100644 --- a/crates/fabric-core/src/agent_config.rs +++ b/crates/fabric-core/src/agent_config.rs @@ -143,8 +143,10 @@ pub struct AgentSkillConfig { /// Skill paths resolved for the task environment. An entry that contains /// `SKILL.md` is one skill; otherwise each folder directly inside it that /// contains `SKILL.md` is a skill. An entry that holds no skills loads - /// nothing. An entry that is missing or is not a folder, or two skills - /// with the same name, fails. + /// nothing. An entry that is missing, is not a folder, or cannot be read, + /// or two resolved skills with the same name, fails. The OpenClaw and + /// Hermes Agent adapters follow this rule; other adapters require each + /// entry to contain `SKILL.md`. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub paths: Vec, /// Adapter-owned skill fields. diff --git a/docs/adapter-contract/tutorials/normalized-configuration.md b/docs/adapter-contract/tutorials/normalized-configuration.md index 31a512ee5..91138d2af 100644 --- a/docs/adapter-contract/tutorials/normalized-configuration.md +++ b/docs/adapter-contract/tutorials/normalized-configuration.md @@ -74,9 +74,14 @@ loads nothing. Fail start when an entry does not exist, when an entry is not a readable folder, or when two skills share a name, and name the entry or both skill folders. A skill's name is the `name` field of its `SKILL.md` front matter, or its folder name. Python adapters can call -`nemo_fabric_adapter_contract.skills.resolve_skills(paths, base_dir)`, which -applies these rules, returns each skill's name and folder, and raises -`SkillPathError` with the failing `skills.paths[N]` field. +`nemo_fabric_adapter_contract.skills.resolve_skills(paths, base_dir)`, and +TypeScript adapters can call `resolveSkills(paths, baseDir)` from +`nemo-fabric-adapter-contract/skills`. Both apply these rules, return each +skill's name and folder, and raise `SkillPathError` with the failing +`skills.paths[N]` field. Pass each resolved skill folder to the harness's +native skill loader, and document how the harness differs from the rule, as +[Load Skills from Folders](../../integrations/harness/skills.mdx) does for +Hermes Agent and OpenClaw. ## To Map the Normalized Configuration diff --git a/docs/index.yml b/docs/index.yml index 97c5d7d05..c65029f07 100644 --- a/docs/index.yml +++ b/docs/index.yml @@ -66,6 +66,8 @@ navigation: contents: - page: Overview path: ./integrations/harness/overview.mdx + - page: Skill Folders + path: ./integrations/harness/skills.mdx - page: Claude Code path: ./integrations/harness/claude.mdx - page: Codex diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index 260e252c1..a88055118 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -74,7 +74,7 @@ Replace the endpoint and model, and provide `MODEL_API_KEY` in the adapter envir The adapter supports `instructions.system.mode: replace` and rejects `append`. Tool selectors are Hermes toolset names. `models..top_p` must be between 0 and 1, and `max_tokens` must be positive. A model-level token limit takes precedence over `harness.settings.max_tokens`. If both are omitted, the adapter passes `None` to preserve Hermes' native response token limit behavior for embedded and native interface agents. Use `runtime.max_turns`, not a `max_iterations` harness setting, to control the agent loop. -Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. +Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. Hermes Agent still loads skills nested inside a skill folder; refer to [Load Skills from Folders](./skills.mdx) for this and other differences in how Hermes Agent loads skills. ### Hermes Settings diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index a305a26ad..840685691 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -103,7 +103,8 @@ empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an entry does not exist and with `openclaw_skill_invalid` when an entry is not a readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to OpenClaw's -`skills.load.extraDirs`. +`skills.load.extraDirs`. Refer to [Load Skills from Folders](./skills.mdx) +for how harnesses differ when they load skills. For an endpoint that supports `stream_options.include_usage`, set `models..settings.supports_usage_in_streaming` to `true`. This maps to diff --git a/docs/integrations/harness/skills.mdx b/docs/integrations/harness/skills.mdx new file mode 100644 index 000000000..e1f1fc97f --- /dev/null +++ b/docs/integrations/harness/skills.mdx @@ -0,0 +1,39 @@ +--- +title: "Load Skills from Folders" +description: "Point NVIDIA NeMo Fabric skill paths at a skill or a folder of skills, and see how harnesses differ when they load them." +--- +{/* SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +SPDX-License-Identifier: Apache-2.0 */} + +NVIDIA NeMo Fabric resolves each `skills.paths` entry in the task environment when the adapter starts. An entry names one skill or a folder of skills. + +## How NeMo Fabric Resolves an Entry + +The following rules apply to each entry: + +- An entry that contains `SKILL.md` is one skill. +- Otherwise, each folder directly inside the entry that contains `SKILL.md` is a skill. Other files and folders, including folders that cannot be read, are ignored. +- An entry that exists but holds no skills, such as a new, empty volume, loads nothing. +- Start fails when an entry does not exist, is not a folder, or cannot be read, and when two resolved skills share a name. The error names the entry or both skill folders. +- The same folder listed through several entries loads once. +- A skill's name is the `name` field of its `SKILL.md` front matter, or its folder name when the front matter has none. + +Relative entries resolve against the agent's base directory. NeMo Fabric does not expand `~` or environment variables such as `${VAR}`. + +The OpenClaw and Hermes Agent adapters follow these rules. They pass each resolved skill folder to the harness's native skill loader. Other adapters that accept `skills.paths` still require each entry to contain `SKILL.md`; refer to each adapter's guide. + +## Harness Differences + +NeMo Fabric decides which folders are skills, but the harness loads them. The harness can find more skills inside those folders or name them differently. The following table lists the known differences: + +| Situation | What Happens | +| --- | --- | +| A skill folder contains other skill folders | Hermes Agent also loads the nested skills. It searches every folder below a skill except `references`, `templates`, `assets`, and `scripts`. OpenClaw loads only the skill folder. | +| Two skills share a name | NeMo Fabric's duplicate check covers only the skills it resolves from `skills.paths`. It does not see nested skills that Hermes Agent loads or skills that a harness loads from its own folders. | +| A skill's name matches another skill's folder name | Hermes Agent looks a skill up by its name, its folder name, and its path. The skill is ambiguous, and Hermes Agent does not load it. OpenClaw loads both skills. | +| A skill's file is `skill.md` or uses another case | On a case-insensitive file system, NeMo Fabric accepts the folder as a skill. Hermes Agent requires exactly `SKILL.md` and does not load the skill. | +| A skill's name is longer than 64 characters | Hermes Agent cuts the name to 64 characters, so two names that share their first 64 characters collide. | +| A folder of skills contains a hidden folder, such as `.archive` | NeMo Fabric loads a hidden folder that contains `SKILL.md` as a skill. Hermes Agent's own scans skip folders such as `.archive`, `.git`, and `.hub`. | +| A Hermes Agent configuration used relative paths, `~`, or `${VAR}` | Relative entries resolve against the agent's base directory, not the Hermes home folder. NeMo Fabric does not expand `~` or `${VAR}`, which Hermes Agent's own `skills.external_dirs` setting does. | + +To avoid these differences, keep one skill per folder, do not nest skill folders, give each skill a name that differs from every skill folder name, and name the file `SKILL.md`. diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx index 33b4b6751..8958066ab 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx @@ -18,7 +18,7 @@ Skill paths made available to an adapter target. ### `paths: Vec` -Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. An entry that is missing or is not a folder, or two skills with the same name, fails. +Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. An entry that is missing, is not a folder, or cannot be read, or two resolved skills with the same name, fails. The OpenClaw and Hermes Agent adapters follow this rule; other adapters require each entry to contain `SKILL.md`. ### `extensions: BTreeMap` diff --git a/schemas/adapter-contract/agent-config.schema.json b/schemas/adapter-contract/agent-config.schema.json index e8965d4cb..bd14d3b13 100644 --- a/schemas/adapter-contract/agent-config.schema.json +++ b/schemas/adapter-contract/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing or is not a folder, or two skills\nwith the same name, fails.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", "items": { "type": "string" }, diff --git a/schemas/sdk/run-plan.schema.json b/schemas/sdk/run-plan.schema.json index 5517f5ef2..a2b3f88fb 100644 --- a/schemas/sdk/run-plan.schema.json +++ b/schemas/sdk/run-plan.schema.json @@ -769,7 +769,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing or is not a folder, or two skills\nwith the same name, fails.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", "items": { "type": "string" }, diff --git a/skills/nemo-fabric-build-adapter/SKILL.md b/skills/nemo-fabric-build-adapter/SKILL.md index de06c68c2..0ba5ebcd1 100644 --- a/skills/nemo-fabric-build-adapter/SKILL.md +++ b/skills/nemo-fabric-build-adapter/SKILL.md @@ -120,8 +120,15 @@ adapter boundary: target constructs. Treat each `skills.paths` entry as one skill when it contains `SKILL.md`, otherwise as a folder whose direct subfolders that contain `SKILL.md` are skills; load nothing from an entry without skills, and - fail start on a missing entry or two skills with the same name. Python - adapters can use `nemo_fabric_adapter_contract.skills.resolve_skills`. + fail start on a missing, non-folder, or unreadable entry or on two resolved + skills with the same name. Python adapters can use + `nemo_fabric_adapter_contract.skills.resolve_skills`, and TypeScript adapters + can use `resolveSkills` from `nemo-fabric-adapter-contract/skills`. Pass each + resolved skill folder to the harness's native skill loader. Of the adapters + that ship with NeMo Fabric, the OpenClaw and Hermes Agent adapters follow this + rule; the others still require each entry to contain `SKILL.md`. Refer to + [Load Skills from Folders](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/integrations/harness/skills.mdx) + for how harnesses can differ from the rule. - Resolve workflow entry points and construction settings during `start` in the task environment. - Read identity, environment, artifacts, telemetry, and the invocation From 1a6d4dd936dec1f7f59907843ad6ce577349f34f Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 05:37:56 -0700 Subject: [PATCH 39/54] fix: keep an agent's kept state private and inside its state folder - agent_state_dir checks the adapter ID the way it checks the agent name, so a local descriptor whose ID is "../x", "/x" or "CON" cannot place the state folder or its lock outside /.fabric/state. - On Unix, the state folder is owner-only (0700), including a folder that an earlier runtime created; kept state can hold conversations and credentials. - is_one_folder_name now also refuses names that cannot be folders on Windows, which NeMo Fabric supports as a host (Windows x86_64 in the install guide): <>:"|?* and control characters, a trailing space or ".", and device names such as CON, NUL.txt or COM1. The rule applies on every platform, so a config means the same on each. - The workspace patch leaves out kept state with a literal pathspec. A glob such as "artifacts[1]/.fabric/state" still left out the real folder, but also a workspace file at "artifacts1/.fabric/state". Signed-off-by: Carlos Villela --- crates/fabric-core/src/config.rs | 42 +++++- crates/fabric-core/src/runtime.rs | 224 ++++++++++++++++++++++++------ 2 files changed, 218 insertions(+), 48 deletions(-) diff --git a/crates/fabric-core/src/config.rs b/crates/fabric-core/src/config.rs index fbb4788ee..58720d713 100644 --- a/crates/fabric-core/src/config.rs +++ b/crates/fabric-core/src/config.rs @@ -1938,7 +1938,7 @@ pub(crate) fn validate_config(config: &FabricConfig) -> Result<()> { if config.runtime.keep_state && !is_one_folder_name(&config.metadata.name) { return invalid_config( "metadata.name", - "must be usable as one folder name when runtime.keep_state is set: not empty, `.` or `..`, and without `/` or `\\`", + "must be usable as one folder name on Linux, macOS, and Windows when runtime.keep_state is set: not empty, `.` or `..`, without `/`, `\\`, `<>:\"|?*` or control characters, not ending in a space or `.`, and not a Windows device name such as `CON` or `NUL`", ); } if let Some(timeout) = config.runtime.timeout_seconds @@ -2402,9 +2402,45 @@ fn validate_names(field: &str, names: &[String]) -> Result<()> { Ok(()) } -/// Whether a name can be one path component on every platform Fabric runs on. +/// Whether a name can be one path component on every platform Fabric runs on, +/// including Windows: not empty, `.` or `..`, without a path separator, +/// `<>:"|?*` or a control character, not ending in a space or `.`, and not a +/// Windows device name such as `CON` or `NUL.txt`. pub(crate) fn is_one_folder_name(name: &str) -> bool { - !name.trim().is_empty() && name != "." && name != ".." && !name.contains(['/', '\\']) + !name.trim().is_empty() + && name != "." + && name != ".." + && !name.chars().any(|character| { + matches!( + character, + '/' | '\\' | '<' | '>' | ':' | '"' | '|' | '?' | '*' + ) || character.is_control() + }) + && !name.ends_with([' ', '.']) + && !is_windows_device_name(name) +} + +/// Windows reserves these names, with or without an extension, in any folder. +fn is_windows_device_name(name: &str) -> bool { + let stem = name.split('.').next().unwrap_or(name).trim_end_matches(' '); + let upper = stem.to_ascii_uppercase(); + if matches!( + upper.as_str(), + "CON" | "PRN" | "AUX" | "NUL" | "CONIN$" | "CONOUT$" + ) { + return true; + } + let Some(number) = upper + .strip_prefix("COM") + .or_else(|| upper.strip_prefix("LPT")) + else { + return false; + }; + let mut characters = number.chars(); + matches!( + (characters.next(), characters.next()), + (Some('0'..='9' | '\u{b9}' | '\u{b2}' | '\u{b3}'), None) + ) } fn invalid_config(field: impl Into, reason: impl Into) -> Result { diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index 2117acf41..115af520d 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -3529,7 +3529,14 @@ fn agent_state_dir(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result Result Vecb", + "a\"b", + "a\u{1}b", + "name.", + "name ", + "CON", + "nul", + "Aux.txt", + "COM1", + "lpt9", + "COM\u{b9}", + ] { let mut config = accepting.config.clone(); config.metadata.name = name.to_string(); cases.push((&root, config, "metadata.name")); @@ -5090,6 +5162,68 @@ for line in sys.stdin: let _ = fs::remove_dir_all(root); } + #[test] + fn one_folder_name_accepts_names_that_are_folders_on_every_platform() { + for name in [ + "assistant", + "my agent", + "a.b", + ".hidden", + "CONSOLE", + "COM10", + "nul-agent", + ] { + assert!(is_one_folder_name(name), "{name}"); + } + } + + #[test] + fn keep_state_rejects_an_adapter_id_that_leaves_the_state_folder() { + for adapter_id in ["../../outside", "/outside", "a/b", "CON"] { + let (root, mut plan) = local_host_plan_keeping_state(); + plan.adapter_descriptor + .as_mut() + .expect("adapter descriptor") + .descriptor + .adapter_id = adapter_id.to_string(); + + let error = start_runtime(&plan).expect_err(adapter_id); + assert!( + matches!(&error, FabricError::InvalidConfig { field, .. } if field == "adapter_id"), + "{adapter_id}: {error}" + ); + assert!(!root.join("artifacts/outside").exists(), "{adapter_id}"); + assert!(!Path::new("/outside").exists(), "{adapter_id}"); + let _ = fs::remove_dir_all(root); + } + } + + #[cfg(unix)] + #[test] + fn keep_state_creates_the_state_folder_for_its_owner_only() { + use std::os::unix::fs::PermissionsExt; + + let (root, plan) = local_host_plan_keeping_state(); + let state_dir = root.join("artifacts/.fabric/state/acme.fabric.local-host/assistant"); + let mode = |path: &Path| { + fs::metadata(path) + .expect("state folder") + .permissions() + .mode() + & 0o777 + }; + + let first = start_runtime(&plan).expect("start runtime"); + assert_eq!(mode(&state_dir), 0o700); + stop_runtime(&plan, &first).expect("stop runtime"); + + fs::set_permissions(&state_dir, fs::Permissions::from_mode(0o755)).expect("widen"); + let second = start_runtime(&plan).expect("start runtime again"); + assert_eq!(mode(&state_dir), 0o700, "an existing folder is narrowed"); + stop_runtime(&plan, &second).expect("stop runtime again"); + let _ = fs::remove_dir_all(root); + } + #[test] fn keep_state_lets_a_service_and_one_connected_runtime_use_the_state_folder() { let (root, plan) = local_host_plan_keeping_state(); From a0375301815ae952e7454ecc3de528217d5d65a2 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 05:37:56 -0700 Subject: [PATCH 40/54] docs: name the public SDK methods for kept state Refer to Fabric.start_runtime(...) and Service.release() rather than the native bindings, and state the folder-name rules and owner-only permissions for kept state. Signed-off-by: Carlos Villela --- docs/sdk/python.mdx | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index bdf47c766..c2646581b 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -864,10 +864,13 @@ By default, each runtime keeps its native state in its own folder, so a new runtime starts empty. Set `"keep_state": true` in the config's `runtime` mapping to give every runtime of the agent one folder instead: `/.fabric/state//`. The config needs an -artifact directory, and `metadata.name` must be usable as one folder name. -Only one runtime can use the folder at a time: `start_runtime(...)` fails while -another runtime of the agent runs. A service and one runtime connected to it -share the folder; the service holds it until `release_service(...)`, even with +artifact directory, and `metadata.name` and the adapter ID must each be usable +as one folder name on Linux, macOS, and Windows: no `/`, `\`, `<>:"|?*`, or +control characters, no trailing space or `.`, and not a Windows device name such +as `CON` or `NUL`. On Linux and macOS, only the folder's owner can read it. +Only one runtime can use the folder at a time: `Fabric.start_runtime(...)` fails +while another runtime of the agent runs. A service and one runtime connected to +it share the folder; the service holds it until `Service.release()`, even with no runtime connected. Planning fails without an artifact directory, or for an adapter that doesn't declare `runtime.keep_state`. From 7f362e098f18270a4d6238ccc31b9602fb9c959d Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 05:50:34 -0700 Subject: [PATCH 41/54] test: run the TypeScript skills tests after the build test:generator runs every test/*.test.mjs before dist/ exists, so the skills tests, which import the build, failed on a clean checkout. Move them to test/skills/, which test:skills runs after building. Signed-off-by: Carlos Villela --- adapter-contract/typescript/package.json | 2 +- .../test/{skills.test.mjs => skills/resolve-skills.test.mjs} | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) rename adapter-contract/typescript/test/{skills.test.mjs => skills/resolve-skills.test.mjs} (98%) diff --git a/adapter-contract/typescript/package.json b/adapter-contract/typescript/package.json index c07f659bb..49159f035 100644 --- a/adapter-contract/typescript/package.json +++ b/adapter-contract/typescript/package.json @@ -30,7 +30,7 @@ "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json", "test:generator": "node --test test/*.test.mjs", "test:types": "tsc -p test/tsconfig.json --noEmit", - "test:skills": "npm run build && node --test test/skills.test.mjs", + "test:skills": "npm run build && node --test test/skills/resolve-skills.test.mjs", "test:dependencies": "node scripts/check-dependencies.mjs && npm ls --all && npm audit --audit-level=high", "pack:check": "npm run build && node scripts/check-package.mjs", "test": "npm run generate:check && npm run test:generator && npm run test:types && npm run test:skills && npm run test:dependencies && npm run pack:check", diff --git a/adapter-contract/typescript/test/skills.test.mjs b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs similarity index 98% rename from adapter-contract/typescript/test/skills.test.mjs rename to adapter-contract/typescript/test/skills/resolve-skills.test.mjs index 1b138e4b4..db2369cee 100644 --- a/adapter-contract/typescript/test/skills.test.mjs +++ b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs @@ -2,6 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 // Resolve skills.paths entries that name a skill or a folder of skills. These +// run against the build in dist/, so test:skills builds first. // cases mirror tests/adapter_contract/test_skills.py for the Python contract. import assert from "node:assert/strict"; @@ -11,7 +12,7 @@ import { tmpdir } from "node:os"; import { join } from "node:path"; import test from "node:test"; -import { resolveSkills, SkillPathError } from "../dist/skills.js"; +import { resolveSkills, SkillPathError } from "../../dist/skills.js"; const posixPermissions = typeof process.geteuid === "function" && process.geteuid() !== 0 From d92b8804d215745c893f794e2cf41cdd549fbc9c Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 06:25:32 -0700 Subject: [PATCH 42/54] feat: resolve skill folders in the TypeScript adapter host resolveSkillFolders applies the contract's skills.paths rule through resolveSkills and reports each failure as a LifecycleError with the adapter's own code for not_found, invalid, or duplicate, and the failing skills.paths[N] field. Signed-off-by: Carlos Villela --- adapters/typescript/common/README.md | 4 ++ adapters/typescript/common/src/index.ts | 1 + adapters/typescript/common/src/skills.ts | 39 +++++++++++++ .../typescript/common/test/skills.test.mjs | 55 +++++++++++++++++++ adapters/typescript/scripts/check-package.mjs | 2 + 5 files changed, 101 insertions(+) create mode 100644 adapters/typescript/common/src/skills.ts create mode 100644 adapters/typescript/common/test/skills.test.mjs diff --git a/adapters/typescript/common/README.md b/adapters/typescript/common/README.md index 4ef0b9638..82a254fcf 100644 --- a/adapters/typescript/common/README.md +++ b/adapters/typescript/common/README.md @@ -66,6 +66,10 @@ dependency graph. The private TypeScript workspace uses a local `nemo-fabric-adapter-contract` file link so source builds test the checked-out contract. Published package manifests use the registry version instead. +## Skill Paths + +`resolveSkillFolders(paths, baseDir, codes)` resolves `skills.paths` with the adapter contract's `resolveSkills` and returns each skill's folder. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. Failures become a `LifecycleError` with the adapter's code for `not_found`, `invalid`, or `duplicate` and the failing `skills.paths[N]` field in its metadata. + ## Model Endpoint Policy `insecureHttpModelHosts(settings, errorCode)` validates and normalizes the explicit `insecure_http_model_hosts` setting. `modelEndpointAllowed(url, hosts, allowPrivateHttp)` applies the shared HTTPS, loopback HTTP, and exact HTTP host policy used by OpenCode, Qwen, and Kilo. The optional private IPv4 argument preserves Kilo's existing opt-in. These utilities do not apply to MCP endpoints. diff --git a/adapters/typescript/common/src/index.ts b/adapters/typescript/common/src/index.ts index 286643d13..ae19ad65d 100644 --- a/adapters/typescript/common/src/index.ts +++ b/adapters/typescript/common/src/index.ts @@ -29,6 +29,7 @@ export { type AcpSessionReadinessNotification, } from "./acp-runner.js"; export { unobservedHealth } from "./health.js"; +export { resolveSkillFolders, type SkillPathErrorCodes } from "./skills.js"; export type { SoftwareSelection } from "./provenance.js"; diff --git a/adapters/typescript/common/src/skills.ts b/adapters/typescript/common/src/skills.ts new file mode 100644 index 000000000..11715e0ad --- /dev/null +++ b/adapters/typescript/common/src/skills.ts @@ -0,0 +1,39 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +// Resolve skills.paths with the adapter contract's rule and report failures as +// lifecycle errors with each adapter's own error codes. + +import { resolveSkills, SkillPathError } from "nemo-fabric-adapter-contract/skills"; +import type { SkillPathFailure } from "nemo-fabric-adapter-contract/skills"; + +import { LifecycleError } from "./lifecycle.js"; + +/** Lifecycle error code that an adapter reports for each `skills.paths` failure. */ +export type SkillPathErrorCodes = Readonly>; + +/** + * Return the folder of each skill that `paths` names, resolving relative + * entries against `baseDir`. An entry that contains `SKILL.md` is one skill; + * otherwise each folder directly inside it that contains `SKILL.md` is. + * + * @throws {LifecycleError} With the code from `codes` and the failing + * `skills.paths[N]` field when an entry is missing, is not a readable folder, + * or two skills share a name. + */ +export async function resolveSkillFolders( + paths: readonly string[], + baseDir: string, + codes: SkillPathErrorCodes, +): Promise { + try { + return (await resolveSkills(paths, baseDir)).map((skill) => skill.path); + } catch (error) { + if (error instanceof SkillPathError) { + throw new LifecycleError(codes[error.reason], error.message, { + metadata: { field: error.field }, + }); + } + throw error; + } +} diff --git a/adapters/typescript/common/test/skills.test.mjs b/adapters/typescript/common/test/skills.test.mjs new file mode 100644 index 000000000..9895dc79a --- /dev/null +++ b/adapters/typescript/common/test/skills.test.mjs @@ -0,0 +1,55 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import assert from "node:assert/strict"; +import { mkdir, mkdtemp, realpath, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; +import test from "node:test"; + +import { LifecycleError, resolveSkillFolders } from "../dist/index.js"; + +const codes = { not_found: "x_skill_not_found", invalid: "x_skill_invalid", duplicate: "x_skill_duplicate" }; + +async function skill(directory, name) { + await mkdir(directory, { recursive: true }); + await writeFile(join(directory, "SKILL.md"), `---\nname: ${name}\n---\n`, "utf8"); + return directory; +} + +test("resolves a skill and each skill inside a folder of skills", async (t) => { + const root = await realpath(await mkdtemp(join(tmpdir(), "fabric-common-skills-"))); + t.after(() => rm(root, { recursive: true, force: true })); + const one = await skill(join(root, "shared", "one"), "one"); + const two = await skill(join(root, "shared", "two"), "two"); + const three = await skill(join(root, "three"), "three"); + + assert.deepEqual(await resolveSkillFolders(["shared", three], root, codes), [one, two, three]); +}); + +for (const [reason, layout] of [ + ["not_found", async () => ["missing"]], + ["invalid", async (root) => { + await writeFile(join(root, "file"), "not a folder\n", "utf8"); + return ["file"]; + }], + ["duplicate", async (root) => { + await skill(join(root, "a", "review"), "review"); + await skill(join(root, "b", "review"), "review"); + return ["a", "b"]; + }], +]) { + test(`reports ${reason} with the adapter's code and the failing field`, async (t) => { + const root = await realpath(await mkdtemp(join(tmpdir(), "fabric-common-skills-"))); + t.after(() => rm(root, { recursive: true, force: true })); + const paths = await layout(root); + + await assert.rejects(resolveSkillFolders(paths, root, codes), (error) => { + assert.ok(error instanceof LifecycleError); + assert.equal(error.code, codes[reason]); + assert.deepEqual(error.metadata, { field: `skills.paths[${paths.length - 1}]` }); + assert.match(error.message, /skills\.paths\[\d\]/); + return true; + }); + }); +} diff --git a/adapters/typescript/scripts/check-package.mjs b/adapters/typescript/scripts/check-package.mjs index 04dbabea5..21d75325c 100644 --- a/adapters/typescript/scripts/check-package.mjs +++ b/adapters/typescript/scripts/check-package.mjs @@ -35,6 +35,8 @@ const expectedByPackage = { "dist/lifecycle.js", "dist/model-endpoint.d.ts", "dist/model-endpoint.js", + "dist/skills.d.ts", + "dist/skills.js", "package.json", ], "nemo-fabric-adapters-cline": [ From cc8bbf976ad6b8c68c1999156e6994165300fb09 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 06:25:32 -0700 Subject: [PATCH 43/54] feat: accept a folder of skills in the OpenHands, Codex, Claude, and NOOA adapters Each adapter resolves skills.paths with the contract's resolve_skills and passes each resolved skill folder to its native loader: OpenHands loads each SKILL.md, Codex registers each folder as a skill root, Claude Code stages each folder in its runtime plugin, and NOOA targets load each folder. Error codes stay as they were (openhands_skill_invalid or openhands_skill_duplicate, codex_invalid_configuration, claude_invalid_configuration); NOOA now fails start with nooa_skill_not_found or nooa_skill_invalid instead of later in a target. An entry without SKILL.md is now a folder of skills, so a folder that holds none loads nothing instead of failing. Codex no longer requires unique folder names, since each skill is its own root; Claude Code still does, because its plugin keeps skills under their folder names. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapters/claude/adapter.py | 19 +++--- .../src/nemo_fabric_adapters/codex/adapter.py | 35 +++-------- .../src/nemo_fabric_adapters/nooa/adapter.py | 26 +++++--- .../nemo_fabric_adapters/openhands/adapter.py | 30 ++++----- tests/adapters/test_claude_adapter.py | 42 ++++++++++++- tests/adapters/test_codex_adapter.py | 44 ++++++++++++- tests/adapters/test_nooa_adapter.py | 27 ++++++++ tests/adapters/test_openhands.py | 61 +++++++++++++++++++ 8 files changed, 223 insertions(+), 61 deletions(-) diff --git a/adapters/python/claude/src/nemo_fabric_adapters/claude/adapter.py b/adapters/python/claude/src/nemo_fabric_adapters/claude/adapter.py index 3761b59ec..a198fc10b 100644 --- a/adapters/python/claude/src/nemo_fabric_adapters/claude/adapter.py +++ b/adapters/python/claude/src/nemo_fabric_adapters/claude/adapter.py @@ -36,6 +36,7 @@ from claude_agent_sdk._errors import MessageParseError from claude_agent_sdk._internal.transport.subprocess_cli import SubprocessCLITransport from claude_agent_sdk.types import EffortLevel +from nemo_fabric_adapter_contract import skills as contract_skills from nemo_fabric_adapter_contract.codec import ContractValidationError from nemo_fabric_adapter_contract.models import AgentConfig from nemo_fabric_adapter_contract.models import AgentModelConfig @@ -432,8 +433,13 @@ def _cleanup_mcp_config(config_path: Path | None) -> None: def _native_skill_paths(config: AgentConfig, base_dir: str) -> list[Path]: - values = config.skills.paths if config.skills is not None else [] - return [_resolve_path(base_dir, value) for value in values] + try: + skills = contract_skills.resolve_skills( + config.skills.paths if config.skills is not None else [], base_dir + ) + except contract_skills.SkillPathError as error: + raise AdapterConfigError("claude_invalid_configuration", str(error)) from None + return [skill.path for skill in skills] def _stage_skill_plugin( @@ -446,16 +452,13 @@ def _stage_skill_plugin( skills: list[tuple[str, Path]] = [] names: set[str] = set() for skill_path in skill_paths: - if not skill_path.is_dir() or not (skill_path / "SKILL.md").is_file(): - raise AdapterConfigError( - "claude_invalid_configuration", - f"NeMo Fabric skill path must be a directory containing SKILL.md: {skill_path}", - ) + # The plugin keeps each skill under its folder name, so two skills + # from different folders with the same folder name cannot both load. name = skill_path.name if name in names: raise AdapterConfigError( "claude_invalid_configuration", - f"NeMo Fabric skill names must be unique: {name}", + f"NeMo Fabric skill folder names must be unique: {name}", ) names.add(name) skills.append((name, skill_path)) diff --git a/adapters/python/codex/src/nemo_fabric_adapters/codex/adapter.py b/adapters/python/codex/src/nemo_fabric_adapters/codex/adapter.py index 90bdaddaa..c3795078d 100644 --- a/adapters/python/codex/src/nemo_fabric_adapters/codex/adapter.py +++ b/adapters/python/codex/src/nemo_fabric_adapters/codex/adapter.py @@ -43,6 +43,7 @@ ) from openai_codex.types import Personality, ReasoningEffort, TurnStatus +from nemo_fabric_adapter_contract import skills as contract_skills from nemo_fabric_adapter_contract.codec import ContractValidationError from nemo_fabric_adapter_contract.models import AgentConfig from nemo_fabric_adapter_contract.models import AgentModelConfig @@ -294,32 +295,14 @@ def _mcp_oauth_callback_url(config: AgentConfig) -> str | None: def _native_skill_paths(config: AgentConfig, base_dir: str) -> list[Path]: - values = config.skills.paths if config.skills else [] - - paths: list[Path] = [] - names: set[str] = set() - config_root = Path(base_dir) - for value in values: - skill_path = Path(value) - if not skill_path.is_absolute(): - skill_path = config_root / skill_path - skill_path = skill_path.resolve() - skill_file = skill_path / "SKILL.md" - if not skill_path.is_dir() or not skill_file.is_file(): - raise AdapterConfigError( - "codex_invalid_configuration", - "NeMo Fabric skill path must be a directory containing SKILL.md: " - f"{skill_path}", - ) - name = skill_path.name - if not name or name in names: - raise AdapterConfigError( - "codex_invalid_configuration", - f"NeMo Fabric skill names must be unique: {name}", - ) - names.add(name) - paths.append(skill_path) - return paths + try: + skills = contract_skills.resolve_skills( + config.skills.paths if config.skills else [], base_dir + ) + except contract_skills.SkillPathError as error: + raise AdapterConfigError("codex_invalid_configuration", str(error)) from None + # Each skill folder becomes its own Codex skill root. + return [skill.path for skill in skills] async def _register_skill_roots(codex: AsyncCodex, skill_paths: list[Path]) -> None: diff --git a/adapters/python/nooa/src/nemo_fabric_adapters/nooa/adapter.py b/adapters/python/nooa/src/nemo_fabric_adapters/nooa/adapter.py index e7c6e235d..d92aa6494 100644 --- a/adapters/python/nooa/src/nemo_fabric_adapters/nooa/adapter.py +++ b/adapters/python/nooa/src/nemo_fabric_adapters/nooa/adapter.py @@ -17,6 +17,7 @@ from types import MappingProxyType from typing import Any +from nemo_fabric_adapter_contract import skills as contract_skills from nemo_fabric_adapter_contract.models import AgentConfig from nemo_fabric_adapter_contract.models import AgentRunError from nemo_fabric_adapter_contract.models import AgentRunRequest @@ -125,16 +126,21 @@ def _path(value: Any, *, default: Path | None = None) -> Path | None: def _resolved_skill_paths(config: AgentConfig, base_dir: Path) -> tuple[Path, ...]: - values = config.skills.paths if config.skills is not None else [] - paths: list[Path] = [] - seen: set[Path] = set() - for value in values: - path = Path(value) - resolved = path if path.is_absolute() else base_dir / path - if resolved not in seen: - paths.append(resolved) - seen.add(resolved) - return tuple(paths) + try: + skills = contract_skills.resolve_skills( + config.skills.paths if config.skills is not None else [], base_dir + ) + except contract_skills.SkillPathError as error: + code = ( + "nooa_skill_not_found" + if error.reason == "not_found" + else "nooa_skill_invalid" + ) + raise lifecycle.LifecycleError( + code, str(error), metadata={"field": error.field} + ) from None + # Targets load each skill from its own folder. + return tuple(skill.path for skill in skills) def _mcp_registry(agent: Any) -> Any: diff --git a/adapters/python/openhands/src/nemo_fabric_adapters/openhands/adapter.py b/adapters/python/openhands/src/nemo_fabric_adapters/openhands/adapter.py index 490059343..245ad3b87 100644 --- a/adapters/python/openhands/src/nemo_fabric_adapters/openhands/adapter.py +++ b/adapters/python/openhands/src/nemo_fabric_adapters/openhands/adapter.py @@ -16,6 +16,7 @@ from typing import NamedTuple from nemo_fabric_adapter_contract import models as contract +from nemo_fabric_adapter_contract import skills as contract_skills from nemo_fabric_adapters.common import instructions as common_instructions from nemo_fabric_adapters.common import lifecycle from nemo_fabric_adapters.common import utils as common_utils @@ -167,20 +168,21 @@ def _workspace(context: contract.RuntimeContext, base_dir: str) -> Path: def _skill_paths(config: contract.AgentConfig, base_dir: str) -> list[Path]: - paths: list[Path] = [] - for value in config.skills.paths if config.skills is not None else []: - path = Path(value) - if not path.is_absolute(): - path = Path(base_dir) / path - path = path.resolve() - if not path.is_dir() or not (path / "SKILL.md").is_file(): - raise lifecycle.LifecycleError( - "openhands_skill_invalid", - "An OpenHands skill path must be a directory containing " - f"SKILL.md: {path}", - ) - paths.append(path) - return paths + try: + skills = contract_skills.resolve_skills( + config.skills.paths if config.skills is not None else [], base_dir + ) + except contract_skills.SkillPathError as error: + code = ( + "openhands_skill_duplicate" + if error.reason == "duplicate" + else "openhands_skill_invalid" + ) + raise lifecycle.LifecycleError( + code, str(error), metadata={"field": error.field} + ) from None + # OpenHands loads each skill from its own SKILL.md. + return [skill.path for skill in skills] def _skills( diff --git a/tests/adapters/test_claude_adapter.py b/tests/adapters/test_claude_adapter.py index ab57e5adb..316e573b1 100644 --- a/tests/adapters/test_claude_adapter.py +++ b/tests/adapters/test_claude_adapter.py @@ -884,11 +884,19 @@ def test_build_options_maps_blocked_tools_to_disallowed_tools(claude_payload): assert options.disallowed_tools == ["Bash", "WebFetch"] -def test_build_options_rejects_skill_path_without_skill_manifest(claude_payload): +def test_build_options_loads_nothing_from_a_folder_without_skills(claude_payload): skill_path = Path(claude_payload["config"]["skills"]["paths"][0]) (skill_path / "SKILL.md").unlink() - with pytest.raises(adapter.AdapterConfigError, match=r"SKILL\.md"): + assert build_options(claude_payload).skills is None + + +def test_build_options_rejects_a_missing_skill_path(claude_payload, tmp_path): + claude_payload["config"]["skills"]["paths"] = [str(tmp_path / "missing")] + + with pytest.raises( + adapter.AdapterConfigError, match=r"skills\.paths\[0\] does not exist" + ): build_options(claude_payload) @@ -2421,3 +2429,33 @@ def test_claude_relay_reports_invalid_or_unsupported_http_model_hosts( assert caught.value.code == "claude_relay_invalid_http_model_hosts" assert isinstance(caught.value.__cause__, adapter.RelayHttpModelError) write_configs.assert_not_called() + + +def test_build_options_stages_each_skill_in_a_skill_folder(claude_payload, tmp_path): + shared = tmp_path / "shared" + for name in ("lint", "security"): + (shared / name).mkdir(parents=True) + (shared / name / "SKILL.md").write_text(f"# {name}\n", encoding="utf-8") + (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") + claude_payload["config"]["skills"]["paths"].append(str(shared)) + + options = build_options(claude_payload) + + staged = Path(options.plugins[0]["path"]) / "skills" + assert sorted(path.name for path in staged.iterdir()) == [ + "lint", + "review", + "security", + ] + assert (staged / "lint" / "SKILL.md").read_text(encoding="utf-8") == "# lint\n" + + +def test_build_options_stages_no_plugin_for_an_empty_skill_folder( + claude_payload, tmp_path +): + (tmp_path / "empty").mkdir() + claude_payload["config"]["skills"]["paths"] = [str(tmp_path / "empty")] + + options = build_options(claude_payload) + + assert options.skills is None diff --git a/tests/adapters/test_codex_adapter.py b/tests/adapters/test_codex_adapter.py index 1128414ce..9272c3605 100644 --- a/tests/adapters/test_codex_adapter.py +++ b/tests/adapters/test_codex_adapter.py @@ -1151,7 +1151,8 @@ def test_sdk_rejects_invalid_native_skill_path(codex_payload, mock_codex, tmp_pa error = runtime_start_error(codex_payload) assert error.code == "codex_invalid_configuration" - assert "directory containing SKILL.md" in error.message + assert "skills.paths[0] does not exist" in error.message + assert str(missing) in error.message mock_codex.assert_not_called() @@ -2579,3 +2580,44 @@ def test_codex_relay_reports_invalid_or_unsupported_http_model_hosts( assert caught.value.code == "codex_relay_invalid_http_model_hosts" assert isinstance(caught.value.__cause__, adapter.RelayHttpModelError) write_configs.assert_not_called() + + +def test_sdk_registers_each_skill_in_a_skill_folder( + codex_payload, mock_codex, tmp_path +): + shared = tmp_path / "shared" + for name in ("review", "test"): + (shared / name).mkdir(parents=True) + (shared / name / "SKILL.md").write_text( + f"---\nname: {name}\ndescription: Test skill.\n---\n", encoding="utf-8" + ) + (shared / "notes").mkdir() + separate = tmp_path / "mounted" / "lint" + separate.mkdir(parents=True) + (separate / "SKILL.md").write_text("# Lint\n", encoding="utf-8") + codex_payload["config"]["skills"] = {"paths": ["shared", str(separate)]} + + invoke_once(codex_payload) + + mock_codex.instances[0]._client.request.assert_awaited_once_with( + "skills/extraRoots/set", + { + "extraRoots": [ + str((shared / "review").resolve()), + str((shared / "test").resolve()), + str(separate.resolve()), + ] + }, + response_model=adapter.SkillsExtraRootsSetResponse, + ) + + +def test_sdk_registers_no_skill_roots_for_an_empty_skill_folder( + codex_payload, mock_codex, tmp_path +): + (tmp_path / "empty").mkdir() + codex_payload["config"]["skills"] = {"paths": ["empty"]} + + invoke_once(codex_payload) + + mock_codex.instances[0]._client.request.assert_not_awaited() diff --git a/tests/adapters/test_nooa_adapter.py b/tests/adapters/test_nooa_adapter.py index f441f3fa6..315428998 100644 --- a/tests/adapters/test_nooa_adapter.py +++ b/tests/adapters/test_nooa_adapter.py @@ -1971,3 +1971,30 @@ async def test_incompatible_relay_fails_before_target_execution( assert result.called is False assert result.report.error == "Relay setup failed (RuntimeError)" call.assert_not_awaited() + + +def test_skill_folder_resolves_each_skill_directly_inside_it(tmp_path: Path): + shared = tmp_path / "shared" + for name in ("code-review", "security-review"): + (shared / name).mkdir(parents=True) + (shared / name / "SKILL.md").write_text( + f"---\nname: {name}\n---\n", encoding="utf-8" + ) + (shared / "notes").mkdir() + config = AgentConfig.from_mapping({"skills": {"paths": ["shared"]}}) + + assert adapter._resolved_skill_paths(config, tmp_path) == ( + (shared / "code-review").resolve(), + (shared / "security-review").resolve(), + ) + + +def test_missing_skill_path_fails_naming_it(tmp_path: Path): + config = AgentConfig.from_mapping({"skills": {"paths": ["missing"]}}) + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + adapter._resolved_skill_paths(config, tmp_path) + + assert caught.value.code == "nooa_skill_not_found" + assert caught.value.metadata == {"field": "skills.paths[0]"} + assert str(tmp_path / "missing") in caught.value.message diff --git a/tests/adapters/test_openhands.py b/tests/adapters/test_openhands.py index a45eceab3..715f7f791 100644 --- a/tests/adapters/test_openhands.py +++ b/tests/adapters/test_openhands.py @@ -1094,3 +1094,64 @@ def test_usage_retains_only_complete_cost_when_token_coverage_is_partial( assert result.total_tokens is None else: assert result is None + + +def _skill_folder(root: Path, *names: str) -> Path: + for name in names: + (root / name).mkdir(parents=True) + (root / name / "SKILL.md").write_text( + f"---\nname: {name}\ndescription: Test skill.\n---\n", encoding="utf-8" + ) + root.mkdir(parents=True, exist_ok=True) + return root + + +def test_skill_folder_loads_each_skill_directly_inside_it(tmp_path: Path): + shared = _skill_folder(tmp_path / "shared", "lint", "review") + (shared / "notes").mkdir() + skill_type = MagicMock() + skill_type.load.side_effect = lambda path, **_kwargs: SimpleNamespace( + name=path.parent.name + ) + config = AgentConfig.from_mapping({"skills": {"paths": ["shared"]}}) + + skills = adapter._skills(SimpleNamespace(Skill=skill_type), config, str(tmp_path)) + + assert [skill.name for skill in skills] == ["lint", "review"] + assert [call.args[0] for call in skill_type.load.call_args_list] == [ + (shared / "lint" / "SKILL.md").resolve(), + (shared / "review" / "SKILL.md").resolve(), + ] + + +def test_empty_skill_folder_loads_no_skills(tmp_path: Path): + (tmp_path / "empty").mkdir() + skill_type = MagicMock() + config = AgentConfig.from_mapping({"skills": {"paths": ["empty"]}}) + + assert ( + adapter._skills(SimpleNamespace(Skill=skill_type), config, str(tmp_path)) == [] + ) + skill_type.load.assert_not_called() + + +@pytest.mark.parametrize( + ("layout", "code"), + [ + ("missing", "openhands_skill_invalid"), + ("duplicate", "openhands_skill_duplicate"), + ], +) +def test_skill_paths_fail_naming_the_entry(tmp_path: Path, layout: str, code: str): + paths = ["missing"] + if layout == "duplicate": + _skill_folder(tmp_path / "one", "review") + _skill_folder(tmp_path / "two", "review") + paths = ["one", "two"] + config = AgentConfig.from_mapping({"skills": {"paths": paths}}) + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + adapter._skills(SimpleNamespace(Skill=MagicMock()), config, str(tmp_path)) + + assert caught.value.code == code + assert caught.value.metadata == {"field": f"skills.paths[{len(paths) - 1}]"} From e6e66a04708fd494c60aeaf8ed87140f13ac8ce5 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 06:25:33 -0700 Subject: [PATCH 44/54] feat: accept a folder of skills in the TypeScript adapters Pi, Kilo Code, Qwen Code, OpenCode, Cline, and Factory Droid resolve skills.paths with resolveSkillFolders and pass each resolved skill folder to their native loader. Existing error codes stay (pi_skill_not_found, pi_skill_invalid, kilo_skill_invalid, qwen_skill_not_found, qwen_skill_duplicate, opencode_skill_not_found, opencode_skill_invalid, opencode_skill_name_duplicate, cline_skill_invalid, droid_skill_invalid). Cline and Droid still refuse two skills with one folder name, which their staging layouts keep, and OpenCode still refuses extra discoverable skills inside a skill folder. An entry without SKILL.md is now a folder of skills, so a folder that holds none loads nothing instead of failing; Qwen loads the same folder listed twice once instead of failing with qwen_skill_duplicate. Signed-off-by: Carlos Villela --- adapters/typescript/cline/src/cline-sdk.ts | 24 +++------ .../typescript/cline/test/cline-sdk.test.mjs | 32 ++++++++++++ adapters/typescript/droid/src/droid-sdk.ts | 23 +++------ .../typescript/droid/test/droid-sdk.test.mjs | 29 +++++++++++ adapters/typescript/kilo/src/kilo-sdk.ts | 18 +++---- .../typescript/kilo/test/kilo-sdk.test.mjs | 26 +++++++++- .../typescript/opencode/src/opencode-sdk.ts | 45 ++++++----------- .../opencode/test/opencode-sdk.test.mjs | 50 +++++++++++++++++++ adapters/typescript/pi/src/pi-sdk.ts | 40 +++------------ adapters/typescript/pi/test/pi-sdk.test.mjs | 31 ++++++++++++ adapters/typescript/qwen/src/configuration.ts | 28 ++++------- .../qwen/test/configuration.test.mjs | 24 ++++++++- 12 files changed, 241 insertions(+), 129 deletions(-) diff --git a/adapters/typescript/cline/src/cline-sdk.ts b/adapters/typescript/cline/src/cline-sdk.ts index fbf468412..88cd5116f 100644 --- a/adapters/typescript/cline/src/cline-sdk.ts +++ b/adapters/typescript/cline/src/cline-sdk.ts @@ -14,7 +14,7 @@ import type { AgentUsage, JsonObject, } from "nemo-fabric-adapter-contract"; -import { LifecycleError, unobservedHealth, type AdapterStartInput } from "nemo-fabric-adapters-common"; +import { LifecycleError, resolveSkillFolders, unobservedHealth, type AdapterStartInput } from "nemo-fabric-adapters-common"; import type { ClinePromptOutcome, ClineSessionFactory, ClineSessionHandle } from "./runtime.js"; import { RawUsageCollector } from "./raw-usage.js"; @@ -267,9 +267,13 @@ interface RuntimeFiles { } async function prepareRuntimeFiles(input: AdapterStartInput): Promise { + const skillPaths = await resolveSkillFolders(input.config.skills?.paths ?? [], input.baseDir, { + not_found: "cline_skill_invalid", + invalid: "cline_skill_invalid", + duplicate: "cline_skill_invalid", + }); const root = await mkdtemp(join(tmpdir(), "nemo-fabric-cline-")); const dataDir = join(root, "data"); - const skillPaths = input.config.skills?.paths ?? []; const mcpServers = input.config.mcp?.servers ?? {}; if (skillPaths.length === 0 && Object.keys(mcpServers).length === 0) { return { root, dataDir, skillCount: 0, mcpServerCount: 0 }; @@ -293,20 +297,8 @@ async function prepareRuntimeFiles(input: AdapterStartInput): Promise(); - for (const configured of skillPaths) { - let source: string; - try { - source = await realpath(resolve(input.baseDir, configured)); - if (!(await stat(source)).isDirectory() || !(await stat(join(source, "SKILL.md"))).isFile()) { - throw new Error("invalid skill directory"); - } - } catch { - throw new LifecycleError( - "cline_skill_invalid", - "Cline skill paths must be directories containing a SKILL.md file", - { metadata: { path: configured } }, - ); - } + for (const source of skillPaths) { + // The plugin keeps each skill under its folder name. const name = basename(source); if (names.has(name)) { throw new LifecycleError("cline_skill_collision", "Two configured Cline skills use the same directory name", { diff --git a/adapters/typescript/cline/test/cline-sdk.test.mjs b/adapters/typescript/cline/test/cline-sdk.test.mjs index d6368cc0a..46409682e 100644 --- a/adapters/typescript/cline/test/cline-sdk.test.mjs +++ b/adapters/typescript/cline/test/cline-sdk.test.mjs @@ -509,3 +509,35 @@ test("rejects unsupported MCP authentication and tool filters", async () => { (error) => error.code === "cline_mcp_blocklist_unsupported", ); }); + +test("stages each skill directly inside a configured skill folder in the Cline plugin", async () => { + const root = await mkdtemp(join(tmpdir(), "fabric-cline-skill-folder-")); + try { + for (const name of ["lint", "review-code"]) { + await mkdir(join(root, "skills", name), { recursive: true }); + await writeFile(join(root, "skills", name, "SKILL.md"), `---\nname: ${name}\ndescription: Test.\n---\n`, "utf8"); + } + await mkdir(join(root, "skills", "notes")); + const sdk = fakeSdk(); + const baseModule = await sdk.loader(); + sdk.loader = async () => ({ + ...baseModule, + async loadAgentPluginPackages(value) { + sdk.calls.plugins.push(value); + return { skills: [{}, {}], mcpServers: [], diagnostics: [] }; + }, + }); + const configured = input({ skills: { paths: ["skills"] } }); + configured.baseDir = root; + + const handle = await new ClineSdkSessionFactory(sdk.loader).create(configured); + + const pluginRoot = sdk.calls.start[0].config.agentPluginPaths[0]; + for (const name of ["lint", "review-code"]) { + await access(join(pluginRoot, "skills", name, "SKILL.md")); + } + await handle.stop(); + } finally { + await rm(root, { recursive: true, force: true }); + } +}); diff --git a/adapters/typescript/droid/src/droid-sdk.ts b/adapters/typescript/droid/src/droid-sdk.ts index 9d411e402..f9b5e03ba 100644 --- a/adapters/typescript/droid/src/droid-sdk.ts +++ b/adapters/typescript/droid/src/droid-sdk.ts @@ -17,6 +17,7 @@ import type { import { unobservedHealth, LifecycleError, + resolveSkillFolders, type AdapterStartInput, } from "nemo-fabric-adapters-common"; @@ -402,7 +403,11 @@ async function prepareRuntimeProfile( if (input.config.skills?.extensions !== undefined) { throw new LifecycleError("droid_skill_extensions_unsupported", "Droid does not support skill extensions"); } - const configured = input.config.skills?.paths ?? []; + const configured = await resolveSkillFolders(input.config.skills?.paths ?? [], input.baseDir, { + not_found: "droid_skill_invalid", + invalid: "droid_skill_invalid", + duplicate: "droid_skill_invalid", + }); const sourceHome = settingsHome(input, parentEnvironment); const settingsEnvironment = await customModelSettingsEnvironment(input, model, sourceHome, parentEnvironment); if (configured.length === 0 && !hasMcpServers) return { entrypoints: [], settingsEnvironment }; @@ -433,20 +438,8 @@ async function prepareRuntimeProfile( if (configured.length > 0) await mkdir(skillsRoot, { recursive: true }); const names = new Set(); const entrypoints: string[] = []; - for (const configuredPath of configured) { - let source: string; - try { - source = await realpath(resolve(input.baseDir, configuredPath)); - if (!(await stat(source)).isDirectory() || !(await stat(join(source, "SKILL.md"))).isFile()) { - throw new Error("invalid skill directory"); - } - } catch { - throw new LifecycleError( - "droid_skill_invalid", - "Droid skill paths must be directories containing a SKILL.md file", - { metadata: { path: configuredPath } }, - ); - } + for (const source of configured) { + // Droid's home keeps each skill under its folder name. const name = basename(source); if (name.length === 0 || names.has(name)) { throw new LifecycleError("droid_skill_collision", "Configured Droid skills must use distinct directory names", { diff --git a/adapters/typescript/droid/test/droid-sdk.test.mjs b/adapters/typescript/droid/test/droid-sdk.test.mjs index 0a7d060c3..452bc6a35 100644 --- a/adapters/typescript/droid/test/droid-sdk.test.mjs +++ b/adapters/typescript/droid/test/droid-sdk.test.mjs @@ -547,3 +547,32 @@ test("native health failures remain unknown and never close a session", async () assert.equal((await handle.prompt("one")).status, "completed"); await handle.stop(); }); + +test("stages each skill directly inside a configured skill folder in the Droid home", async (t) => { + const root = await mkdtemp(join(tmpdir(), "fabric-droid-skill-folder-")); + t.after(() => rm(root, { recursive: true, force: true })); + for (const name of ["lint", "review-code"]) { + await mkdir(join(root, "shared", name), { recursive: true }); + await writeFile(join(root, "shared", name, "SKILL.md"), `---\nname: ${name}\ndescription: Test.\n---\n`); + } + await mkdir(join(root, "shared", "notes")); + const sdk = fakeSdk({ + skillReport: (created) => ({ + skills: ["lint", "review-code"].map((name) => ({ + name, + filePath: join(created.env.HOME, ".agents", "skills", name, "SKILL.md"), + enabled: true, + })), + }), + }); + + const handle = await new DroidSdkSessionFactory(sdk.loader).create(input({ + tools: undefined, + skills: { paths: [join(root, "shared")] }, + })); + const created = sdk.calls.create[0]; + for (const name of ["lint", "review-code"]) { + assert.equal((await stat(join(created.env.HOME, ".agents", "skills", name, "SKILL.md"))).isFile(), true); + } + await handle.stop(); +}); diff --git a/adapters/typescript/kilo/src/kilo-sdk.ts b/adapters/typescript/kilo/src/kilo-sdk.ts index dc287bbcb..eaee0e125 100644 --- a/adapters/typescript/kilo/src/kilo-sdk.ts +++ b/adapters/typescript/kilo/src/kilo-sdk.ts @@ -16,7 +16,7 @@ import type { AgentUsage, } from "nemo-fabric-adapter-contract"; import type { AdapterStartInput } from "nemo-fabric-adapters-common"; -import { unobservedHealth, LifecycleError } from "nemo-fabric-adapters-common"; +import { unobservedHealth, LifecycleError, resolveSkillFolders } from "nemo-fabric-adapters-common"; import { KiloPromptError } from "./runtime.js"; import { KiloUsageEvents } from "./usage-events.js"; @@ -94,19 +94,13 @@ async function workspacePath(input: AdapterStartInput): Promise { } } -async function skillPaths(input: AdapterStartInput): Promise { - const paths: string[] = []; - for (const entry of input.config.skills?.paths ?? []) { +/** Resolve skills.paths to the skill folders that Kilo Code loads through its skills.paths setting. */ +export async function skillPaths(input: Pick): Promise { + const configured = input.config.skills?.paths ?? []; + for (const entry of configured) { if (typeof entry !== "string") throw new LifecycleError("kilo_invalid_skill", "Kilo Code skill paths must be strings"); - try { - const directory = await realpath(resolve(input.baseDir, entry)); - if (!(await stat(directory)).isDirectory() || !(await stat(join(directory, "SKILL.md"))).isFile()) throw new Error("invalid"); - paths.push(directory); - } catch { - throw new LifecycleError("kilo_skill_invalid", "NeMo Fabric skill paths must be directories that contain SKILL.md"); - } } - return paths; + return resolveSkillFolders(configured, input.baseDir, {not_found: "kilo_skill_invalid", invalid: "kilo_skill_invalid", duplicate: "kilo_skill_invalid"}); } /** Map normalized tool policy to non-interactive Kilo permissions, with blocked tools taking precedence. */ diff --git a/adapters/typescript/kilo/test/kilo-sdk.test.mjs b/adapters/typescript/kilo/test/kilo-sdk.test.mjs index 141743f2a..32240a5a8 100644 --- a/adapters/typescript/kilo/test/kilo-sdk.test.mjs +++ b/adapters/typescript/kilo/test/kilo-sdk.test.mjs @@ -4,7 +4,7 @@ import assert from "node:assert/strict"; import {EventEmitter} from "node:events"; import test from "node:test"; -import {mkdtemp, mkdir, rm, writeFile} from "node:fs/promises"; +import {mkdtemp, mkdir, realpath, rm, writeFile} from "node:fs/promises"; import {createServer} from "node:http"; import {tmpdir} from "node:os"; import {join} from "node:path"; @@ -14,7 +14,7 @@ import {setImmediate as nextTurn} from "node:timers/promises"; import {createKiloClient} from "@kilocode/sdk/v2"; import undiciTimers from "undici/lib/util/timers.js"; -import {classifySpawnError, closeChild, extractPromptOutcome, kiloFetch, KiloSdkSessionFactory, startKiloServer} from "../dist/kilo-sdk.js"; +import {classifySpawnError, closeChild, extractPromptOutcome, kiloFetch, KiloSdkSessionFactory, skillPaths, startKiloServer} from "../dist/kilo-sdk.js"; test("extracts Kilo Code terminal text without treating final-message counters as invocation usage", () => { assert.deepEqual(extractPromptOutcome({ @@ -369,3 +369,25 @@ for (const phase of ["headers", "body"]) { }); } } + +test("projects each skill directly inside a configured skill folder", async () => { + const root = await realpath(await mkdtemp(join(tmpdir(), "kilo-skill-folder-"))); + try { + for (const name of ["lint", "review"]) { + await mkdir(join(root, "skills", name), {recursive: true}); + await writeFile(join(root, "skills", name, "SKILL.md"), `# ${name}\n`, "utf8"); + } + await mkdir(join(root, "skills", "notes")); + + assert.deepEqual( + await skillPaths({baseDir: root, config: {skills: {paths: ["skills"]}}}), + [join(root, "skills", "lint"), join(root, "skills", "review")], + ); + await assert.rejects( + skillPaths({baseDir: root, config: {skills: {paths: ["missing"]}}}), + (error) => error.code === "kilo_skill_invalid" && error.metadata.field === "skills.paths[0]", + ); + } finally { + await rm(root, {recursive: true, force: true}); + } +}); diff --git a/adapters/typescript/opencode/src/opencode-sdk.ts b/adapters/typescript/opencode/src/opencode-sdk.ts index 2366706cf..0ae3be98a 100644 --- a/adapters/typescript/opencode/src/opencode-sdk.ts +++ b/adapters/typescript/opencode/src/opencode-sdk.ts @@ -7,9 +7,9 @@ import type { AdapterCheckResult, CheckLevel, AgentUsage } from "nemo-fabric-adapter-contract"; import type { AdapterStartInput } from "nemo-fabric-adapters-common"; -import { LifecycleError } from "nemo-fabric-adapters-common"; +import { LifecycleError, resolveSkillFolders } from "nemo-fabric-adapters-common"; import { randomUUID } from "node:crypto"; -import { cp, mkdtemp, readdir, realpath, rm, stat } from "node:fs/promises"; +import { cp, mkdtemp, readdir, realpath, rm } from "node:fs/promises"; import { tmpdir } from "node:os"; import { isAbsolute, join, relative, resolve, sep } from "node:path"; @@ -184,7 +184,17 @@ async function rejectAdditionalDiscoverableSkills(directory: string, root = dire } async function prepareRuntimeSkills(baseDir: string, configured: string[]): Promise { - if (configured.length === 0) { + for (const entry of configured) { + if (typeof entry !== "string") { + throw new LifecycleError("opencode_invalid_skill", "OpenCode skill paths must be strings"); + } + } + const sources = await resolveSkillFolders(configured, baseDir, { + not_found: "opencode_skill_not_found", + invalid: "opencode_skill_invalid", + duplicate: "opencode_skill_name_duplicate", + }); + if (sources.length === 0) { return { skills: [] }; } // OpenCode reports canonical skill paths. Canonicalize the temporary root as @@ -193,34 +203,7 @@ async function prepareRuntimeSkills(baseDir: string, configured: string[]): Prom const root = await realpath(await mkdtemp(join(tmpdir(), "nemo-fabric-opencode-skills-"))); const skills: OpenCodeSkill[] = []; try { - for (const [index, entry] of configured.entries()) { - if (typeof entry !== "string") { - throw new LifecycleError("opencode_invalid_skill", "OpenCode skill paths must be strings"); - } - let source: string; - try { - source = await realpath(resolve(baseDir, entry)); - } catch { - throw new LifecycleError("opencode_skill_not_found", "A configured NeMo Fabric skill path does not exist"); - } - try { - if (!(await stat(source)).isDirectory()) { - throw new Error("not a directory"); - } - } catch { - throw new LifecycleError("opencode_skill_invalid", "NeMo Fabric skill paths must be directories"); - } - try { - const sourceLocation = await realpath(join(source, "SKILL.md")); - if (!(await stat(sourceLocation)).isFile()) { - throw new Error("not a file"); - } - } catch { - throw new LifecycleError( - "opencode_skill_invalid", - "NeMo Fabric skill directories must contain a SKILL.md file", - ); - } + for (const [index, source] of sources.entries()) { const directory = join(root, String(index)); try { await cp(source, directory, { recursive: true, dereference: true, errorOnExist: true }); diff --git a/adapters/typescript/opencode/test/opencode-sdk.test.mjs b/adapters/typescript/opencode/test/opencode-sdk.test.mjs index d7f5e05e2..b45467e12 100644 --- a/adapters/typescript/opencode/test/opencode-sdk.test.mjs +++ b/adapters/typescript/opencode/test/opencode-sdk.test.mjs @@ -2106,3 +2106,53 @@ test("leaves later root observations unknown when an opaque plugin can resume ea assert.deepEqual(second.usage.extensions["nvidia.fabric.opencode.usage_evidence.v1"].observed, {}); } finally { await fixture.handle.stop(); } }); + +test("stages each skill directly inside a configured skill folder for OpenCode", async () => { + const baseDir = await mkdtemp(join(tmpdir(), "fabric-opencode-skill-folder-")); + try { + for (const name of ["lint", "review"]) { + await mkdir(join(baseDir, "skills", name), { recursive: true }); + await writeFile(join(baseDir, "skills", name, "SKILL.md"), `---\nname: ${name}\n---\nUse ${name}.\n`, "utf8"); + } + await writeFile(join(baseDir, "skills", "notes.txt"), "Not a skill.\n", "utf8"); + let staged; + const factory = new OpenCodeSdkSessionFactory(async () => ({ + OpenCode: { + async create(options) { + staged = JSON.parse(options.config.content).skills; + return { + skill: { + async list() { + return { + data: await Promise.all(staged.map(async (directory, index) => ({ + name: ["lint", "review"][index], + path: await realpath(join(directory, "SKILL.md")), + }))), + }; + }, + }, + sessions: { + async create() { return { id: "session-skill-folder" }; }, + async remove() {}, + }, + async close() {}, + }; + }, + }, + })); + const input = startInput(); + input.baseDir = baseDir; + input.config.skills = { paths: ["skills"] }; + + const handle = await factory.create(input); + + assert.equal(staged.length, 2); + assert.deepEqual( + await Promise.all(staged.map((directory) => readFile(join(directory, "SKILL.md"), "utf8"))), + ["---\nname: lint\n---\nUse lint.\n", "---\nname: review\n---\nUse review.\n"], + ); + await handle.stop(); + } finally { + await rm(baseDir, { recursive: true, force: true }); + } +}); diff --git a/adapters/typescript/pi/src/pi-sdk.ts b/adapters/typescript/pi/src/pi-sdk.ts index 31c874d04..234065ca3 100644 --- a/adapters/typescript/pi/src/pi-sdk.ts +++ b/adapters/typescript/pi/src/pi-sdk.ts @@ -21,7 +21,7 @@ import type { } from "@earendil-works/pi-coding-agent"; import { createJiti } from "jiti/static"; import type { AdapterCheckResult, CheckLevel, CheckSource, AgentConfig, AgentModelConfig, AgentToolDefinition, JsonObject } from "nemo-fabric-adapter-contract"; -import { LifecycleError, unobservedHealth, type AdapterStartInput } from "nemo-fabric-adapters-common"; +import { LifecycleError, resolveSkillFolders, unobservedHealth, type AdapterStartInput } from "nemo-fabric-adapters-common"; import { PiRelayFactory, @@ -808,37 +808,13 @@ async function resolveExtensionPaths(workspace: string, configured: string[]): P return resolved; } -async function resolveSkillPaths(baseDir: string, configured: string[]): Promise { - const resolved: string[] = []; - for (const entry of configured) { - let candidate: string; - try { - candidate = await realpath(resolve(baseDir, entry)); - } catch { - throw new LifecycleError("pi_skill_not_found", "A configured NeMo Fabric skill path does not exist"); - } - let info; - try { - info = await stat(candidate); - } catch { - throw new LifecycleError("pi_skill_not_found", "A configured NeMo Fabric skill path does not exist"); - } - if (!info.isDirectory()) { - throw new LifecycleError("pi_skill_invalid", "NeMo Fabric skill paths must be directories"); - } - try { - if (!(await stat(join(candidate, "SKILL.md"))).isFile()) { - throw new Error("not a file"); - } - } catch { - throw new LifecycleError( - "pi_skill_invalid", - "NeMo Fabric skill directories must contain a SKILL.md file", - ); - } - resolved.push(candidate); - } - return resolved; +/** Resolve skills.paths to skill folders; Pi loads a folder with SKILL.md as one skill. */ +export async function resolveSkillPaths(baseDir: string, configured: string[]): Promise { + return resolveSkillFolders(configured, baseDir, { + not_found: "pi_skill_not_found", + invalid: "pi_skill_invalid", + duplicate: "pi_skill_invalid", + }); } function credentialValue(input: AdapterStartInput, name: string): string | undefined { diff --git a/adapters/typescript/pi/test/pi-sdk.test.mjs b/adapters/typescript/pi/test/pi-sdk.test.mjs index e74bef829..7f381c452 100644 --- a/adapters/typescript/pi/test/pi-sdk.test.mjs +++ b/adapters/typescript/pi/test/pi-sdk.test.mjs @@ -13,6 +13,7 @@ import { modelAwareCompactionReserveTokens, PiSdkSessionFactory, resolveCustomTools, + resolveSkillPaths, selectPiMcpServers, withCustomBaseUrl, } from "../dist/pi-sdk.js"; @@ -1506,3 +1507,33 @@ test("accepts a well-formed extensions.cost", async () => { await rm(workspace, { recursive: true, force: true }); } }); + +async function skillFolder(root, ...names) { + for (const name of names) { + await mkdir(join(root, name), { recursive: true }); + await writeFile(join(root, name, "SKILL.md"), `---\nname: ${name}\ndescription: Test skill.\n---\n`, "utf8"); + } + await mkdir(root, { recursive: true }); + return root; +} + +test("resolves each skill directly inside a configured skill folder", async (t) => { + const root = await realpath(await mkdtemp(join(tmpdir(), "fabric-pi-skill-folder-"))); + t.after(() => rm(root, { recursive: true, force: true })); + const shared = await skillFolder(join(root, "shared"), "lint", "review"); + await mkdir(join(shared, "notes")); + const separate = await skillFolder(join(root, "mounted"), "test"); + + assert.deepEqual(await resolveSkillPaths(root, ["shared", join(separate, "test")]), [ + join(shared, "lint"), + join(shared, "review"), + join(separate, "test"), + ]); + await mkdir(join(root, "empty")); + assert.deepEqual(await resolveSkillPaths(root, ["empty"]), []); + await assert.rejects(resolveSkillPaths(root, ["missing"]), (error) => { + assert.equal(error.code, "pi_skill_not_found"); + assert.deepEqual(error.metadata, { field: "skills.paths[0]" }); + return true; + }); +}); diff --git a/adapters/typescript/qwen/src/configuration.ts b/adapters/typescript/qwen/src/configuration.ts index b738c3328..9dd84a52c 100644 --- a/adapters/typescript/qwen/src/configuration.ts +++ b/adapters/typescript/qwen/src/configuration.ts @@ -2,9 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 import type { AgentConfig, AgentMcpServerConfig, AgentModelConfig } from "nemo-fabric-adapter-contract"; -import { LifecycleError, insecureHttpModelHosts, modelEndpointAllowed } from "nemo-fabric-adapters-common"; -import { realpath, stat } from "node:fs/promises"; -import { join, resolve } from "node:path"; +import { LifecycleError, insecureHttpModelHosts, modelEndpointAllowed, resolveSkillFolders } from "nemo-fabric-adapters-common"; export interface QwenModel { id: string; @@ -202,26 +200,18 @@ export async function selectSkillPaths(config: AgentConfig, baseDir: string): Pr if (config.skills?.extensions !== undefined) { throw new LifecycleError("qwen_unsupported_skills", "Qwen does not support skill extensions"); } - const paths: string[] = []; - const seen = new Set(); - for (const entry of config.skills?.paths ?? []) { + const configured = config.skills?.paths ?? []; + for (const entry of configured) { if (typeof entry !== "string" || entry.trim().length === 0) { throw new LifecycleError("qwen_invalid_skill", "Qwen skill paths must be non-empty strings"); } - let directory: string; - try { - directory = await realpath(resolve(baseDir, entry)); - if (!(await stat(directory)).isDirectory() || !(await stat(join(directory, "SKILL.md"))).isFile()) { - throw new Error("not a skill directory"); - } - } catch { - throw new LifecycleError("qwen_skill_not_found", "A configured Qwen skill directory or SKILL.md is missing"); - } - if (seen.has(directory)) throw new LifecycleError("qwen_skill_duplicate", "Qwen skill paths must be unique"); - seen.add(directory); - paths.push(directory); } - return paths; + // Qwen loads each skill from its own folder. + return resolveSkillFolders(configured, baseDir, { + not_found: "qwen_skill_not_found", + invalid: "qwen_skill_not_found", + duplicate: "qwen_skill_duplicate", + }); } export function rejectUnclaimedConfig(config: AgentConfig): void { diff --git a/adapters/typescript/qwen/test/configuration.test.mjs b/adapters/typescript/qwen/test/configuration.test.mjs index 0a3fdc888..db78fa346 100644 --- a/adapters/typescript/qwen/test/configuration.test.mjs +++ b/adapters/typescript/qwen/test/configuration.test.mjs @@ -2,10 +2,12 @@ // SPDX-License-Identifier: Apache-2.0 import assert from "node:assert/strict"; -import { readFile } from "node:fs/promises"; +import { mkdir, mkdtemp, readFile, realpath, rm, writeFile } from "node:fs/promises"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; import test from "node:test"; -import { selectModel, selectSystemPrompt, selectPermissionMode, selectBlockedTools, selectMcpServers, rejectUnclaimedConfig } from "../dist/configuration.js"; +import { selectModel, selectSystemPrompt, selectPermissionMode, selectBlockedTools, selectMcpServers, rejectUnclaimedConfig, selectSkillPaths } from "../dist/configuration.js"; const descriptor = JSON.parse(await readFile(new URL("../qwen.fabric-adapter.json", import.meta.url))); const model = { provider: "openai", model: "test-model", api_key_env: "TEST_KEY", base_url: "http://127.0.0.1:1234/v1" }; @@ -94,3 +96,21 @@ test("HTTP host settings compose with Qwen permissions without relaxing MCP trus config.mcp = { servers: { gateway: { transport: "streamable-http", url: "http://gateway/mcp" } } }; assert.throws(() => selectMcpServers(config, {}, {}), (error) => error.code === "qwen_mcp_invalid_server"); }); + +test("selects each skill directly inside a configured skill folder, once", async (t) => { + const root = await realpath(await mkdtemp(join(tmpdir(), "qwen-skill-folder-"))); + t.after(() => rm(root, { recursive: true, force: true })); + for (const name of ["lint", "review"]) { + await mkdir(join(root, "skills", name), { recursive: true }); + await writeFile(join(root, "skills", name, "SKILL.md"), `# ${name}\n`, "utf8"); + } + + assert.deepEqual( + await selectSkillPaths({ skills: { paths: ["skills", "skills/review"] } }, root), + [join(root, "skills", "lint"), join(root, "skills", "review")], + ); + await assert.rejects( + selectSkillPaths({ skills: { paths: ["missing"] } }, root), + (error) => error.code === "qwen_skill_not_found" && error.metadata.field === "skills.paths[0]", + ); +}); From 53ca0314fd9fab29dfadd82bd61695bffab1e6a7 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sat, 7 Nov 2026 06:25:33 -0700 Subject: [PATCH 45/54] docs: list the adapters that accept a folder of skills The skills.paths contract text, Load Skills from Folders, the build-adapter skill, and each adapter's README and guide now say that the adapters shipped with NeMo Fabric follow the folder rule, except Deep Agents. Deep Agents skill sources are folders of skills read through its backend, which can be virtual, so that adapter passes entries unchanged. The harness differences table adds the folder-name limit of the Claude Code, Cline, and Factory Droid staging layouts and OpenCode's refusal of extra discoverable files inside a skill folder. Signed-off-by: Carlos Villela --- .../typescript/schemas/agent-config.schema.json | 2 +- adapter-contract/typescript/src/generated/agent-config.ts | 6 +++--- adapters/python/claude/README.md | 6 ++++-- adapters/python/codex/README.md | 7 ++++--- adapters/python/deepagents/README.md | 5 +++++ adapters/python/nooa/README.md | 3 ++- adapters/python/openhands/README.md | 4 ++-- adapters/typescript/cline/README.md | 4 +++- adapters/typescript/droid/README.md | 7 +++++-- adapters/typescript/kilo/README.md | 5 +++-- adapters/typescript/opencode/README.md | 6 ++++-- adapters/typescript/qwen/README.md | 4 ++-- crates/fabric-core/src/agent_config.rs | 6 +++--- docs/integrations/harness/cline.mdx | 6 ++++-- docs/integrations/harness/codex.mdx | 6 +++--- docs/integrations/harness/deepagents.mdx | 5 +++++ docs/integrations/harness/droid.mdx | 7 ++++--- docs/integrations/harness/kilo.mdx | 5 +++-- docs/integrations/harness/opencode.mdx | 6 ++++-- docs/integrations/harness/openhands.mdx | 4 ++-- docs/integrations/harness/pi.mdx | 4 +++- docs/integrations/harness/qwen.mdx | 4 ++-- docs/integrations/harness/skills.mdx | 4 +++- .../agent-config/struct-agentskillconfig.mdx | 2 +- schemas/adapter-contract/agent-config.schema.json | 2 +- schemas/sdk/run-plan.schema.json | 2 +- skills/nemo-fabric-build-adapter/SKILL.md | 6 +++--- 27 files changed, 80 insertions(+), 48 deletions(-) diff --git a/adapter-contract/typescript/schemas/agent-config.schema.json b/adapter-contract/typescript/schemas/agent-config.schema.json index bd14d3b13..89af5e7e2 100644 --- a/adapter-contract/typescript/schemas/agent-config.schema.json +++ b/adapter-contract/typescript/schemas/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The adapters that\nship with NeMo Fabric follow this rule, except Deep Agents, which passes\neach entry to Deep Agents as a skill source.", "items": { "type": "string" }, diff --git a/adapter-contract/typescript/src/generated/agent-config.ts b/adapter-contract/typescript/src/generated/agent-config.ts index cf6848298..c012b9773 100644 --- a/adapter-contract/typescript/src/generated/agent-config.ts +++ b/adapter-contract/typescript/src/generated/agent-config.ts @@ -290,9 +290,9 @@ export interface AgentSkillConfig { * `SKILL.md` is one skill; otherwise each folder directly inside it that * contains `SKILL.md` is a skill. An entry that holds no skills loads * nothing. An entry that is missing, is not a folder, or cannot be read, - * or two resolved skills with the same name, fails. The OpenClaw and - * Hermes Agent adapters follow this rule; other adapters require each - * entry to contain `SKILL.md`. + * or two resolved skills with the same name, fails. The adapters that + * ship with NeMo Fabric follow this rule, except Deep Agents, which passes + * each entry to Deep Agents as a skill source. */ paths?: string[]; } diff --git a/adapters/python/claude/README.md b/adapters/python/claude/README.md index 4aa6eab95..4ae736b71 100644 --- a/adapters/python/claude/README.md +++ b/adapters/python/claude/README.md @@ -101,8 +101,10 @@ Configure portable capabilities through the normalized `FabricConfig` fields: - `mcp` configures stdio, HTTP, streamable HTTP, or SSE servers. For stdio, set `url` to the executable and pass each command-line argument as a separate `args` element. -- `skills.paths` names skill directories that contain `SKILL.md`. The adapter - stages these directories as a local Claude plugin for the runtime. +- `skills.paths` names skill folders or folders of skills; refer to + [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). The adapter stages each skill folder in a local Claude + plugin for the runtime, under its folder name, so two skills with the same + folder name fail start. Only Claude-specific controls belong in `harness.settings`: diff --git a/adapters/python/codex/README.md b/adapters/python/codex/README.md index 1d48409dc..736229289 100644 --- a/adapters/python/codex/README.md +++ b/adapters/python/codex/README.md @@ -110,9 +110,10 @@ Use normalized `FabricConfig` fields for portable configuration: - `mcp` maps stdio, HTTP, and streamable HTTP servers into the Codex thread's `mcp_servers` configuration. For stdio, set `url` to the executable and pass each command-line argument as a separate `args` element. -- `skills.paths` names skill directories that contain `SKILL.md`. The adapter - registers each directory as a process-scoped Codex skill root so Codex can - select matching skills through its normal discovery behavior. +- `skills.paths` names skill folders or folders of skills; refer to + [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). The adapter registers each skill folder as a + process-scoped Codex skill root so Codex can select matching skills through + its normal discovery behavior. - `telemetry` enables native OpenTelemetry or NeMo Relay observability. Invocation deadlines return the normalized error code `timeout`, including when the deadline expires during MCP authentication; a Codex SDK request that times out earlier returns `codex_timed_out`. The adapter interrupts the active turn and closes the SDK before returning either outcome. With a timeout under 10 seconds, NeMo Fabric's own timeout can stop the adapter host before the interrupt finishes, which fails the invocation with a core `host_timeout` error instead. diff --git a/adapters/python/deepagents/README.md b/adapters/python/deepagents/README.md index 3427b47cf..9fd466e32 100644 --- a/adapters/python/deepagents/README.md +++ b/adapters/python/deepagents/README.md @@ -103,6 +103,11 @@ NeMo Fabric maps the following into the harness: confines filesystem tools to the workspace: absolute paths and `..` cannot escape `root_dir`. - Routed `skills` (`native.skill_paths`) become the Deep Agents `skills` sources. + A Deep Agents source is a folder of skills read through the Deep Agents + backend, which can be virtual, so this adapter passes each entry unchanged + instead of resolving it as a skill folder or a folder of skills as the other + adapters do; refer to + [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). - Configured MCP servers are loaded as Deep Agents tools via `langchain-mcp-adapters`. A misconfigured server (non-mapping, empty target, unsupported transport) is a normalized configuration failure, not a silent drop. diff --git a/adapters/python/nooa/README.md b/adapters/python/nooa/README.md index 5eee7418f..5231346de 100644 --- a/adapters/python/nooa/README.md +++ b/adapters/python/nooa/README.md @@ -15,7 +15,8 @@ lifecycle contract. Choose the integration that matches the agent interface: The shared `nvidia.fabric.nooa` adapter owns the common NOOA queue dispatcher. It also maps normalized skill paths and whole MCP servers into compatible -registered targets. +registered targets. Each skill path is a skill folder or a folder of skills; +refer to [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). The dedicated `nvidia.fabric.nooa.bench-agent` adapter maps the benchmark-native `BenchAgent` task contract directly into a NeMo Fabric invocation. Its [observed token usage](docs/bench-agent.md#observed-token-usage) preserves the diff --git a/adapters/python/openhands/README.md b/adapters/python/openhands/README.md index 28c513907..93f6dd5c7 100644 --- a/adapters/python/openhands/README.md +++ b/adapters/python/openhands/README.md @@ -75,8 +75,8 @@ config = FabricConfig( ``` Relative skill and workspace paths resolve from the configuration base -directory. Each skill path must be a directory containing `SKILL.md`. The -adapter disables ambient OpenHands user, public, project, and memory loading; +directory. Each skill path is a skill folder or a folder of skills; refer to +[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). The adapter disables ambient OpenHands user, public, project, and memory loading; only explicitly configured NeMo Fabric skills are loaded. For `provider="nvidia"`, the adapter adds LiteLLM's `nvidia_nim/` dispatch diff --git a/adapters/typescript/cline/README.md b/adapters/typescript/cline/README.md index 261816485..3d64c24da 100644 --- a/adapters/typescript/cline/README.md +++ b/adapters/typescript/cline/README.md @@ -70,7 +70,9 @@ config.add_skill_path("./skills/code-review") For a source build, use `adapters/typescript/cline/cline.fabric-adapter.json`. Relative skill paths -resolve from the `base_dir` passed to `plan()`, `doctor()`, or `run()`. +resolve from the `base_dir` passed to `plan()`, `doctor()`, or `run()`. Each +skill path is a skill folder or a folder of skills; refer to +[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). The initial adapter supports a configured model, an API-key environment reference, an optional model base URL, replacement system instructions, Cline diff --git a/adapters/typescript/droid/README.md b/adapters/typescript/droid/README.md index 994c3c0d0..38d3d529a 100644 --- a/adapters/typescript/droid/README.md +++ b/adapters/typescript/droid/README.md @@ -82,8 +82,11 @@ Each NeMo Fabric runtime owns one SDK session. Ordered invocations call history. `stop()` closes the session and its CLI subprocess. Independent runtimes create separate sessions. -Configured skill directories are copied into a runtime-scoped temporary home -using Droid's compatible personal `.agents/skills` layout. The adapter verifies +Each configured skill path is a skill folder or a folder of skills; refer to +[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). Each skill folder is copied into a +runtime-scoped temporary home using Droid's compatible personal +`.agents/skills` layout, under its folder name, so two skills with the same +folder name fail start. The adapter verifies them with `listSkills()` and removes the temporary home during shutdown. This keeps Fabric-provided skills isolated without modifying the workspace. The isolated profile preserves Factory `settings.json` and diff --git a/adapters/typescript/kilo/README.md b/adapters/typescript/kilo/README.md index 473d01971..2066b8bae 100644 --- a/adapters/typescript/kilo/README.md +++ b/adapters/typescript/kilo/README.md @@ -35,8 +35,9 @@ The adapter supports the following normalized configuration: step limit. - **Tools:** Maps native Kilo Code tool names in `tools.enabled` and `tools.blocked`. Tool definitions are unsupported. -- **Skills:** Each `skills.paths` entry must be a directory containing - `SKILL.md`. Startup verifies that Kilo Code loaded every configured skill. +- **Skills:** Each `skills.paths` entry is a skill folder or a folder of + skills; refer to [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). Startup verifies that Kilo + Code loaded every resolved skill. - **MCP:** Supports stdio, streamable HTTP, and SSE server configurations. Startup requires every configured server to report `connected`. diff --git a/adapters/typescript/opencode/README.md b/adapters/typescript/opencode/README.md index aab95d087..543907d63 100644 --- a/adapters/typescript/opencode/README.md +++ b/adapters/typescript/opencode/README.md @@ -52,8 +52,10 @@ The adapter supports the following configuration: - **Models:** Selects the `default` role, or the only configured role. `api_key_env` may use any portable environment-variable name. - **Instructions:** Supports `instructions.system` with `mode: replace`. -- **Skills:** Each `skills.paths` entry must be a directory containing `SKILL.md`. - Startup verifies that only those `SKILL.md` files load and that names are unique. +- **Skills:** Each `skills.paths` entry is a skill folder or a folder of skills; + refer to [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). Startup verifies that only those + `SKILL.md` files load and that names are unique, so a skill folder that + contains another skill fails start. - **MCP:** Supports `stdio` and `streamable-http`. Startup fails if a configured server cannot connect. diff --git a/adapters/typescript/qwen/README.md b/adapters/typescript/qwen/README.md index cd471ef51..727503a94 100644 --- a/adapters/typescript/qwen/README.md +++ b/adapters/typescript/qwen/README.md @@ -43,8 +43,8 @@ The adapter supports the following normalized configuration: `mode: append`. - **Tools:** Maps Qwen-native tool names from `tools.blocked`. Tool definitions and `tools.enabled` are unsupported. -- **Skills:** Each `skills.paths` entry must be a directory containing - `SKILL.md`. +- **Skills:** Each `skills.paths` entry is a skill folder or a folder of + skills; refer to [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx). - **MCP:** Supports stdio and streamable HTTP servers, including per-server allowed and blocked tool filters. - **Harness settings:** Maps `permission_mode` to Qwen Code's `default`, `plan`, diff --git a/crates/fabric-core/src/agent_config.rs b/crates/fabric-core/src/agent_config.rs index f7cd72f61..eb893de31 100644 --- a/crates/fabric-core/src/agent_config.rs +++ b/crates/fabric-core/src/agent_config.rs @@ -144,9 +144,9 @@ pub struct AgentSkillConfig { /// `SKILL.md` is one skill; otherwise each folder directly inside it that /// contains `SKILL.md` is a skill. An entry that holds no skills loads /// nothing. An entry that is missing, is not a folder, or cannot be read, - /// or two resolved skills with the same name, fails. The OpenClaw and - /// Hermes Agent adapters follow this rule; other adapters require each - /// entry to contain `SKILL.md`. + /// or two resolved skills with the same name, fails. The adapters that + /// ship with NeMo Fabric follow this rule, except Deep Agents, which passes + /// each entry to Deep Agents as a skill source. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub paths: Vec, /// Adapter-owned skill fields. diff --git a/docs/integrations/harness/cline.mdx b/docs/integrations/harness/cline.mdx index 8aca38a83..b379399b5 100644 --- a/docs/integrations/harness/cline.mdx +++ b/docs/integrations/harness/cline.mdx @@ -118,8 +118,10 @@ absolute paths in user input. ## Configure MCP Servers and Skills Normalized skill paths are staged into a runtime-scoped Agent Plugins v1 -package and loaded through Cline's native skill discovery. Each path must name -a directory containing `SKILL.md`. +package and loaded through Cline's native skill discovery. Each path is a skill +folder or a folder of skills; refer to [Load Skills from Folders](./skills.mdx). The +package keeps each skill under its folder name, so two skills with the same +folder name fail start. Normalized MCP servers use the same runtime-scoped native plugin. The adapter supports unauthenticated stdio, SSE, and streamable HTTP servers. diff --git a/docs/integrations/harness/codex.mdx b/docs/integrations/harness/codex.mdx index c74dfbca3..17068360c 100644 --- a/docs/integrations/harness/codex.mdx +++ b/docs/integrations/harness/codex.mdx @@ -117,9 +117,9 @@ config.add_mcp_server( ``` The adapter maps stdio, HTTP, and streamable HTTP servers into the Codex -thread's `mcp_servers` configuration. It resolves each skill directory, verifies -that it contains `SKILL.md`, and registers it as a process-scoped Codex skill -root. Codex uses its normal skill discovery behavior. Invalid skill directories +thread's `mcp_servers` configuration. It resolves each skill path to skill +folders, as [Load Skills from Folders](./skills.mdx) describes, and registers +each skill folder as a process-scoped Codex skill root. Codex uses its normal skill discovery behavior. Invalid skill directories and MCP transports fail before the SDK runtime starts. For `Fabric.start_runtime(...)`, the model provider, MCP configuration, and diff --git a/docs/integrations/harness/deepagents.mdx b/docs/integrations/harness/deepagents.mdx index 412c7194f..ba61d8595 100644 --- a/docs/integrations/harness/deepagents.mdx +++ b/docs/integrations/harness/deepagents.mdx @@ -103,6 +103,11 @@ MCP-reported tool errors (`ToolException`) and argument validation failures retu Use normalized `FabricConfig` fields to configure the model, workspace, skills, MCP servers, replacement system instructions, blocked tools, and telemetry. +Each `skills.paths` entry becomes a Deep Agents skill source: a folder of +skills that Deep Agents reads through its backend. Unlike the other adapters, +this adapter does not resolve entries as described in +[Load Skills from Folders](./skills.mdx), because a backend path can be +virtual and need not exist in the task environment. The adapter rejects `append` system instructions. Use `harness.settings.deepagents` to configure the JSON-serializable Deep Agents-native `interrupt_on` and `subagents` options: diff --git a/docs/integrations/harness/droid.mdx b/docs/integrations/harness/droid.mdx index 30b99a61b..d83a5f1ea 100644 --- a/docs/integrations/harness/droid.mdx +++ b/docs/integrations/harness/droid.mdx @@ -126,9 +126,10 @@ server's explicit `env`; unrelated variables from the adapter host are removed. ## Configure Skills -The adapter supports normalized `skills.paths`. It validates each configured -directory and its `SKILL.md`, copies the skill into a runtime-scoped temporary -home using Droid's compatible personal `.agents/skills` layout, and verifies +The adapter supports normalized `skills.paths`; each entry is a skill folder +or a folder of skills, as [Load Skills from Folders](./skills.mdx) describes. +It copies each skill folder, under its folder name, into a runtime-scoped +temporary home using Droid's compatible personal `.agents/skills` layout, and verifies discovery through the SDK. Runtime shutdown removes the temporary files. Project skills already placed in Droid's documented discovery locations remain Droid-owned ambient configuration. diff --git a/docs/integrations/harness/kilo.mdx b/docs/integrations/harness/kilo.mdx index e9132183c..64d76c209 100644 --- a/docs/integrations/harness/kilo.mdx +++ b/docs/integrations/harness/kilo.mdx @@ -78,8 +78,9 @@ The adapter supports the following normalized configuration: step limit. - **Tools:** Maps native Kilo Code tool names in `tools.enabled` and `tools.blocked`. Tool definitions are unsupported. -- **Skills:** Each `skills.paths` entry must be a directory containing - `SKILL.md`. Startup verifies that Kilo Code loaded every configured skill. +- **Skills:** Each `skills.paths` entry is a skill folder or a folder of + skills; refer to [Load Skills from Folders](./skills.mdx). Startup verifies that Kilo + Code loaded every resolved skill. - **MCP:** Supports stdio, streamable HTTP, and SSE server configurations. Startup requires every configured server to report `connected`. diff --git a/docs/integrations/harness/opencode.mdx b/docs/integrations/harness/opencode.mdx index e854a41c8..1eb10f97e 100644 --- a/docs/integrations/harness/opencode.mdx +++ b/docs/integrations/harness/opencode.mdx @@ -83,8 +83,10 @@ The adapter supports the following configuration: - **Instructions:** Supports `instructions.system` with `mode: replace`. A replacement instruction replaces OpenCode's base prompt. OpenCode may still append runtime context. -- **Skills:** Each `skills.paths` entry must be a directory containing `SKILL.md`. - Startup verifies that only those `SKILL.md` files load and that names are unique. +- **Skills:** Each `skills.paths` entry is a skill folder or a folder of skills; + refer to [Load Skills from Folders](./skills.mdx). Startup verifies that only those + `SKILL.md` files load and that names are unique, so a skill folder that + contains another skill fails start. - **MCP:** Supports `stdio` and `streamable-http`. Startup fails if a configured server cannot connect. diff --git a/docs/integrations/harness/openhands.mdx b/docs/integrations/harness/openhands.mdx index 7ebdb2e36..b76c8a3a7 100644 --- a/docs/integrations/harness/openhands.mdx +++ b/docs/integrations/harness/openhands.mdx @@ -69,8 +69,8 @@ prefix while preserving the served model ID, including its `nvidia/` namespace. This also supports self-hosted NIM endpoints through `base_url`. An existing `nvidia_nim/` prefix is retained once. -Skill paths resolve from the configuration base directory and must contain a -`SKILL.md` file. The adapter disables ambient OpenHands user, public, project, +Skill paths resolve from the configuration base directory. Each is a skill +folder or a folder of skills; refer to [Load Skills from Folders](./skills.mdx). The adapter disables ambient OpenHands user, public, project, and memory loading, so only explicitly configured NeMo Fabric skills load. The adapter configures the OpenHands SDK standard summarizing condenser, diff --git a/docs/integrations/harness/pi.mdx b/docs/integrations/harness/pi.mdx index dfa602a1e..968402568 100644 --- a/docs/integrations/harness/pi.mdx +++ b/docs/integrations/harness/pi.mdx @@ -199,7 +199,9 @@ config.harness.settings["extensions"] = ["extensions/review.ts"] ``` The adapter loads only the skill and extension paths in the configuration. It -does not load ambient Pi resources from the user profile or workspace. +does not load ambient Pi resources from the user profile or workspace. Each +skill path is a skill folder or a folder of skills; refer to +[Load Skills from Folders](./skills.mdx). ## Configure MCP Servers diff --git a/docs/integrations/harness/qwen.mdx b/docs/integrations/harness/qwen.mdx index b8e6f55f9..a50e49b34 100644 --- a/docs/integrations/harness/qwen.mdx +++ b/docs/integrations/harness/qwen.mdx @@ -79,8 +79,8 @@ The adapter supports the following normalized configuration: `mode: append`. - **Tools:** Maps Qwen-native tool names from `tools.blocked`. Tool definitions and `tools.enabled` are unsupported. -- **Skills:** Each `skills.paths` entry must be a directory containing - `SKILL.md`. +- **Skills:** Each `skills.paths` entry is a skill folder or a folder of + skills; refer to [Load Skills from Folders](./skills.mdx). - **MCP:** Supports stdio and streamable HTTP servers, including per-server allowed and blocked tool filters. - **Harness settings:** Maps `permission_mode` to Qwen Code's `default`, `plan`, diff --git a/docs/integrations/harness/skills.mdx b/docs/integrations/harness/skills.mdx index e1f1fc97f..41579964c 100644 --- a/docs/integrations/harness/skills.mdx +++ b/docs/integrations/harness/skills.mdx @@ -20,7 +20,7 @@ The following rules apply to each entry: Relative entries resolve against the agent's base directory. NeMo Fabric does not expand `~` or environment variables such as `${VAR}`. -The OpenClaw and Hermes Agent adapters follow these rules. They pass each resolved skill folder to the harness's native skill loader. Other adapters that accept `skills.paths` still require each entry to contain `SKILL.md`; refer to each adapter's guide. +The adapters that ship with NeMo Fabric follow these rules and pass each resolved skill folder to the harness's native skill loader. The exception is the [Deep Agents adapter](./deepagents.mdx), which passes each entry to Deep Agents as a skill source, a folder of skills read through the Deep Agents backend. ## Harness Differences @@ -34,6 +34,8 @@ NeMo Fabric decides which folders are skills, but the harness loads them. The ha | A skill's file is `skill.md` or uses another case | On a case-insensitive file system, NeMo Fabric accepts the folder as a skill. Hermes Agent requires exactly `SKILL.md` and does not load the skill. | | A skill's name is longer than 64 characters | Hermes Agent cuts the name to 64 characters, so two names that share their first 64 characters collide. | | A folder of skills contains a hidden folder, such as `.archive` | NeMo Fabric loads a hidden folder that contains `SKILL.md` as a skill. Hermes Agent's own scans skip folders such as `.archive`, `.git`, and `.hub`. | +| Two skills in different folders share a folder name | The Claude Code, Cline, and Factory Droid adapters copy each skill into one folder under its folder name, so start fails. | +| A skill folder contains another skill, or a Markdown file other than `SKILL.md` at its top level | The OpenCode adapter fails start, because OpenCode would load the extra file as a skill. | | A Hermes Agent configuration used relative paths, `~`, or `${VAR}` | Relative entries resolve against the agent's base directory, not the Hermes home folder. NeMo Fabric does not expand `~` or `${VAR}`, which Hermes Agent's own `skills.external_dirs` setting does. | To avoid these differences, keep one skill per folder, do not nest skill folders, give each skill a name that differs from every skill folder name, and name the file `SKILL.md`. diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx index 8958066ab..473e4f2d3 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx @@ -18,7 +18,7 @@ Skill paths made available to an adapter target. ### `paths: Vec` -Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. An entry that is missing, is not a folder, or cannot be read, or two resolved skills with the same name, fails. The OpenClaw and Hermes Agent adapters follow this rule; other adapters require each entry to contain `SKILL.md`. +Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. An entry that is missing, is not a folder, or cannot be read, or two resolved skills with the same name, fails. The adapters that ship with NeMo Fabric follow this rule, except Deep Agents, which passes each entry to Deep Agents as a skill source. ### `extensions: BTreeMap` diff --git a/schemas/adapter-contract/agent-config.schema.json b/schemas/adapter-contract/agent-config.schema.json index bd14d3b13..89af5e7e2 100644 --- a/schemas/adapter-contract/agent-config.schema.json +++ b/schemas/adapter-contract/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The adapters that\nship with NeMo Fabric follow this rule, except Deep Agents, which passes\neach entry to Deep Agents as a skill source.", "items": { "type": "string" }, diff --git a/schemas/sdk/run-plan.schema.json b/schemas/sdk/run-plan.schema.json index a2b3f88fb..ff9234d2f 100644 --- a/schemas/sdk/run-plan.schema.json +++ b/schemas/sdk/run-plan.schema.json @@ -769,7 +769,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The adapters that\nship with NeMo Fabric follow this rule, except Deep Agents, which passes\neach entry to Deep Agents as a skill source.", "items": { "type": "string" }, diff --git a/skills/nemo-fabric-build-adapter/SKILL.md b/skills/nemo-fabric-build-adapter/SKILL.md index 0ba5ebcd1..93a6d693b 100644 --- a/skills/nemo-fabric-build-adapter/SKILL.md +++ b/skills/nemo-fabric-build-adapter/SKILL.md @@ -124,9 +124,9 @@ adapter boundary: skills with the same name. Python adapters can use `nemo_fabric_adapter_contract.skills.resolve_skills`, and TypeScript adapters can use `resolveSkills` from `nemo-fabric-adapter-contract/skills`. Pass each - resolved skill folder to the harness's native skill loader. Of the adapters - that ship with NeMo Fabric, the OpenClaw and Hermes Agent adapters follow this - rule; the others still require each entry to contain `SKILL.md`. Refer to + resolved skill folder to the harness's native skill loader. The adapters that + ship with NeMo Fabric follow this rule, except Deep Agents, whose skill + sources are backend paths. Refer to [Load Skills from Folders](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/integrations/harness/skills.mdx) for how harnesses can differ from the rule. - Resolve workflow entry points and construction settings during `start` in From 0809e5f7d0713c4c738fcb13cdd7e43f8bc8a1df Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:11:51 -0700 Subject: [PATCH 46/54] fix: keep an agent's state locked while its adapter host runs The state lock was a file lock held only by the process that started the runtime. If that process exited or crashed while the adapter host was still running, for example while the host was stopping its harness after stdin closed, the lock was released and a replacement runtime could start on the same state. On Unix the adapter host now inherits the lock, so the state stays locked until both have exited. Taking the lock waits up to 250 ms before failing with StateInUse, because a process that forks while another runtime holds the lock, such as one starting another host, keeps it until it execs. Windows keeps the lock in the starting process only. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 116 +++++++++++++++++++++++++++--- 1 file changed, 107 insertions(+), 9 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index 115af520d..1f71c223d 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -2698,6 +2698,24 @@ fn spawn_local_host( .stdin(Stdio::piped()) .stdout(Stdio::piped()) .stderr(Stdio::from(stderr)); + // The host inherits the state lock, so the state stays locked until the + // host exits too, even when this process exits or crashes first. + #[cfg(unix)] + if let Some(lock) = &state_lock { + use std::os::fd::AsRawFd; + use std::os::unix::process::CommandExt; + let fd = lock.as_raw_fd(); + // SAFETY: the closure runs between fork and exec and only calls + // fcntl, which is async-signal-safe. + unsafe { + command.pre_exec(move || { + if libc::fcntl(fd, libc::F_SETFD, 0) == -1 { + return Err(std::io::Error::last_os_error()); + } + Ok(()) + }); + } + } if let Some(root) = artifacts.root.as_ref() { command.env("FABRIC_ARTIFACTS", root); } @@ -3547,8 +3565,9 @@ fn agent_state_dir(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result Result> { let Some(state_dir) = agent_state_dir(plan, artifacts)? else { return Ok(None); @@ -3583,16 +3602,31 @@ fn lock_agent_state(plan: &RunPlan, artifacts: &ArtifactManifest) -> Result Ok(Some(file)), - Err(std::fs::TryLockError::WouldBlock) => Err(FabricError::StateInUse { path: state_dir }), - Err(std::fs::TryLockError::Error(source)) => Err(FabricError::Write { - path: lock_path, - source, - }), + // A process that forks while another runtime holds the lock, such as one + // starting another host, keeps the lock until it execs, so wait briefly + // before deciding that the state is in use. + let deadline = Instant::now() + STATE_LOCK_WAIT; + loop { + match file.try_lock() { + Ok(()) => return Ok(Some(file)), + Err(std::fs::TryLockError::WouldBlock) if Instant::now() < deadline => { + thread::sleep(Duration::from_millis(10)); + } + Err(std::fs::TryLockError::WouldBlock) => { + return Err(FabricError::StateInUse { path: state_dir }); + } + Err(std::fs::TryLockError::Error(source)) => { + return Err(FabricError::Write { + path: lock_path, + source, + }); + } + } } } +const STATE_LOCK_WAIT: Duration = Duration::from_millis(250); + fn resolve_named_environment(plan: &RunPlan, env: &mut BTreeMap) -> Result<()> { for name in plan .environment_plan @@ -4678,6 +4712,15 @@ for line in sys.stdin: sys.exit(18) response("stop") break +else: + if MODE == "linger_after_exit": + # Outlive the process that started this host, as a host still + # stopping its harness after that process crashed would. + root = os.path.dirname(os.environ["FABRIC_FAKE_HOST_STOP_MARKER"]) + with open(os.path.join(root, "host.pid.tmp"), "w", encoding="utf-8") as stream: + stream.write(str(os.getpid())) + os.replace(os.path.join(root, "host.pid.tmp"), os.path.join(root, "host.pid")) + time.sleep(30) "#, ) .expect("write fake host"); @@ -5224,6 +5267,61 @@ for line in sys.stdin: let _ = fs::remove_dir_all(root); } + #[cfg(unix)] + #[test] + fn keep_state_stays_locked_while_a_host_outlives_the_process_that_started_it() { + const APP_PLAN: &str = "FABRIC_KEEP_STATE_TEST_APP_PLAN"; + if let Ok(path) = std::env::var(APP_PLAN) { + // The app: start a runtime, then exit without stopping it. + let plan: RunPlan = + serde_json::from_str(&fs::read_to_string(path).expect("read plan")).expect("plan"); + start_runtime(&plan).expect("start runtime in the app"); + std::process::exit(0); + } + let (root, plan) = local_host_plan_keeping_state_in("linger_after_exit"); + let plan_path = root.join("plan.json"); + fs::write(&plan_path, serde_json::to_string(&plan).expect("plan JSON")) + .expect("write plan"); + let app = Command::new(std::env::current_exe().expect("test binary")) + .args([ + "runtime::tests::keep_state_stays_locked_while_a_host_outlives_the_process_that_started_it", + "--exact", + "--nocapture", + ]) + .env(APP_PLAN, &plan_path) + .status() + .expect("run the app"); + assert!(app.success(), "{app}"); + let pid_path = root.join("host.pid"); + let deadline = Instant::now() + Duration::from_secs(10); + while !pid_path.exists() && Instant::now() < deadline { + thread::sleep(Duration::from_millis(20)); + } + let host: libc::pid_t = fs::read_to_string(&pid_path) + .expect("the host outlives the app") + .trim() + .parse() + .expect("host pid"); + + let second = start_runtime(&plan); + // SAFETY: kill has no memory-safety preconditions. + unsafe { libc::kill(host, libc::SIGKILL) }; + let error = second.expect_err("the surviving host still uses the state"); + assert!(matches!(error, FabricError::StateInUse { .. }), "{error}"); + let deadline = Instant::now() + Duration::from_secs(5); + let runtime = loop { + match start_runtime(&plan) { + Ok(runtime) => break runtime, + Err(FabricError::StateInUse { .. }) if Instant::now() < deadline => { + thread::sleep(Duration::from_millis(20)); + } + Err(error) => panic!("start after the host exited: {error}"), + } + }; + stop_runtime(&plan, &runtime).expect("stop runtime"); + let _ = fs::remove_dir_all(root); + } + #[test] fn keep_state_lets_a_service_and_one_connected_runtime_use_the_state_folder() { let (root, plan) = local_host_plan_keeping_state(); From 313dfa8644c749e70f7b275ec94c67d78455027a Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:14:31 -0700 Subject: [PATCH 47/54] fix: compare skill folders by path when the file system has no inode The resolver keyed folders by (device, inode) so that two spellings of one folder load once. A file system that reports inode 0, such as some network, FUSE, or Windows volumes, gave every folder the same key, so all skills after the first were skipped without an error. Use (device, inode) only for a non-zero inode and the resolved path otherwise, in both contracts. The OpenClaw and Hermes docs now say that an unreadable entry fails only when the resolver has to list it: an entry with a readable SKILL.md is one skill and is not listed. Signed-off-by: Carlos Villela --- .../nemo_fabric_adapter_contract/skills.py | 9 ++++--- adapter-contract/typescript/src/skills.ts | 5 ++-- .../test/skills/resolve-skills.test.mjs | 27 ++++++++++++++++++- adapters/python/hermes/README.md | 4 +-- adapters/python/openclaw/README.md | 4 +-- docs/integrations/harness/hermes.mdx | 2 +- docs/integrations/harness/openclaw.mdx | 4 +-- tests/adapter_contract/test_skills.py | 21 +++++++++++++++ 8 files changed, 62 insertions(+), 14 deletions(-) diff --git a/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py b/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py index a09888633..2c01ffc46 100644 --- a/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py +++ b/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py @@ -78,7 +78,7 @@ def resolve_skills( skills: list[Skill] = [] by_name: dict[str, Skill] = {} - folders: set[tuple[int, int]] = set() + folders: set[tuple[int, int] | Path] = set() for index, value in enumerate(paths): field = f"skills.paths[{index}]" configured = Path(base_dir) / value @@ -143,11 +143,12 @@ def _is_skill(child: Path) -> bool: return False -def _folder_identity(directory: Path) -> tuple[int, int]: +def _folder_identity(directory: Path) -> tuple[int, int] | Path: # Compare folders by identity so that spellings resolve() keeps apart, such - # as a different case on a case-insensitive file system, still match. + # as a different case on a case-insensitive file system, still match. An + # inode of 0 identifies nothing, so fall back to the resolved path. stat = directory.stat() - return stat.st_dev, stat.st_ino + return (stat.st_dev, stat.st_ino) if stat.st_ino else directory def _skill_name(directory: Path, field: str) -> str: diff --git a/adapter-contract/typescript/src/skills.ts b/adapter-contract/typescript/src/skills.ts index 2ea983d5a..a7424538e 100644 --- a/adapter-contract/typescript/src/skills.ts +++ b/adapter-contract/typescript/src/skills.ts @@ -200,9 +200,10 @@ function errorCode(error: unknown): string { async function folderIdentity(directory: string): Promise { // Compare folders by identity so that spellings realpath keeps apart, such - // as a different case on a case-insensitive file system, still match. + // as a different case on a case-insensitive file system, still match. An + // inode of 0 identifies nothing, so fall back to the resolved path. const info = await stat(directory, { bigint: true }); - return `${info.dev}:${info.ino}`; + return info.ino === 0n ? `path:${directory}` : `inode:${info.dev}:${info.ino}`; } async function skillName(directory: string, field: string): Promise { diff --git a/adapter-contract/typescript/test/skills/resolve-skills.test.mjs b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs index db2369cee..309348a77 100644 --- a/adapter-contract/typescript/test/skills/resolve-skills.test.mjs +++ b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs @@ -7,7 +7,8 @@ import assert from "node:assert/strict"; import { chmod, mkdir, mkdtemp, realpath, rm, symlink, writeFile } from "node:fs/promises"; -import { existsSync } from "node:fs"; +import fs, { existsSync } from "node:fs"; +import { syncBuiltinESMExports } from "node:module"; import { tmpdir } from "node:os"; import { join } from "node:path"; import test from "node:test"; @@ -277,3 +278,27 @@ test("the same skill in another case loads once", async (t) => { { name: "Review", path: review, field: "skills.paths[0]" }, ]); }); + +test("folders without inode numbers compare by path", async (t) => { + const { root } = await temporary(t); + const shared = join(root, "shared"); + const one = await skill(join(shared, "one"), "one"); + const two = await skill(join(shared, "two"), "two"); + // Some file systems report inode 0 for every folder. + const stat = fs.promises.stat; + fs.promises.stat = async (path, options) => { + const info = await stat(path, options); + info.ino = typeof info.ino === "bigint" ? 0n : 0; + return info; + }; + syncBuiltinESMExports(); + t.after(() => { + fs.promises.stat = stat; + syncBuiltinESMExports(); + }); + + assert.deepEqual(await resolveSkills([shared, one], root), [ + { name: "one", path: one, field: "skills.paths[0]" }, + { name: "two", path: two, field: "skills.paths[0]" }, + ]); +}); diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 97068f734..046890935 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -81,8 +81,8 @@ entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an -entry does not exist and with `hermes_skill_invalid` when an entry is not a -readable folder or two skills share a name; the error names the entry or both skill +entry does not exist and with `hermes_skill_invalid` when an entry is not a folder, when an entry +without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. Hermes Agent still loads skills nested inside a skill folder; refer to diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index 5a08e29da..9d315097d 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -79,8 +79,8 @@ entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an -entry does not exist and with `openclaw_skill_invalid` when an entry is not a -readable folder or two skills share a name; the error names the entry or both skill +entry does not exist and with `openclaw_skill_invalid` when an entry is not a folder, when an entry +without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to OpenClaw's `skills.load.extraDirs`. Refer to [Load Skills from Folders](../../../docs/integrations/harness/skills.mdx) for diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index a88055118..7d511a92f 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -74,7 +74,7 @@ Replace the endpoint and model, and provide `MODEL_API_KEY` in the adapter envir The adapter supports `instructions.system.mode: replace` and rejects `append`. Tool selectors are Hermes toolset names. `models..top_p` must be between 0 and 1, and `max_tokens` must be positive. A model-level token limit takes precedence over `harness.settings.max_tokens`. If both are omitted, the adapter passes `None` to preserve Hermes' native response token limit behavior for embedded and native interface agents. Use `runtime.max_turns`, not a `max_iterations` harness setting, to control the agent loop. -Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a readable folder or two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. Hermes Agent still loads skills nested inside a skill folder; refer to [Load Skills from Folders](./skills.mdx) for this and other differences in how Hermes Agent loads skills. +Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a folder, when an entry without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. Hermes Agent still loads skills nested inside a skill folder; refer to [Load Skills from Folders](./skills.mdx) for this and other differences in how Hermes Agent loads skills. ### Hermes Settings diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index 840685691..6f8706712 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -100,8 +100,8 @@ entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an -entry does not exist and with `openclaw_skill_invalid` when an entry is not a -readable folder or two skills share a name; the error names the entry or both skill +entry does not exist and with `openclaw_skill_invalid` when an entry is not a folder, when an entry +without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to OpenClaw's `skills.load.extraDirs`. Refer to [Load Skills from Folders](./skills.mdx) for how harnesses differ when they load skills. diff --git a/tests/adapter_contract/test_skills.py b/tests/adapter_contract/test_skills.py index 8f2ba184e..ff3392557 100644 --- a/tests/adapter_contract/test_skills.py +++ b/tests/adapter_contract/test_skills.py @@ -267,3 +267,24 @@ def test_same_skill_in_another_case_loads_once(tmp_path: Path): assert resolve_skills(["Review", "review"], tmp_path) == [ Skill(name="Review", path=review.resolve(), field="skills.paths[0]") ] + + +def test_folders_without_inode_numbers_compare_by_path( + tmp_path: Path, monkeypatch: pytest.MonkeyPatch +): + shared = tmp_path / "shared" + one = _skill(shared / "one", "one") + two = _skill(shared / "two", "two") + stat = Path.stat + + def without_inode(path: Path, *args, **kwargs) -> os.stat_result: + # Some file systems report inode 0 for every folder. + result = stat(path, *args, **kwargs) + return os.stat_result((result.st_mode, 0, *tuple(result)[2:])) + + monkeypatch.setattr(Path, "stat", without_inode) + + assert resolve_skills([shared, one], tmp_path) == [ + Skill(name="one", path=one.resolve(), field="skills.paths[0]"), + Skill(name="two", path=two.resolve(), field="skills.paths[0]"), + ] From 13b87243c7428d4dbac74c3f5da2ced6c758642d Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:24:05 -0700 Subject: [PATCH 48/54] test: share the OpenClaw dashboard tests' start payload Start each dashboard test through one helper, and keep the startup-timeout test where it was, so the diff shows only the lines that changed. Signed-off-by: Carlos Villela --- tests/adapters/test_openclaw.py | 146 ++++++++++++++++---------------- 1 file changed, 74 insertions(+), 72 deletions(-) diff --git a/tests/adapters/test_openclaw.py b/tests/adapters/test_openclaw.py index c7be809cb..97fa75a69 100644 --- a/tests/adapters/test_openclaw.py +++ b/tests/adapters/test_openclaw.py @@ -113,6 +113,22 @@ def _dashboard_token(base_dir: Path) -> Path: ) +async def _start( + runtime: adapter.OpenClawRuntime, + tmp_path: Path, + config: AgentConfig, + **payload: object, +) -> None: + await runtime.start( + { + "config": config, + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + **payload, + } + ) + + @pytest.fixture(name="mock_openclaw") def mock_openclaw_fixture(repo_root: Path) -> Path: return repo_root / "tests/_utils/mock_openclaw.py" @@ -212,7 +228,9 @@ def test_openclaw_rejects_invalid_port_range(settings: dict[str, object]): id="unknown-field", ), pytest.param({"interfaces": {"dashboard": {}}}, id="missing-port"), - pytest.param({"interfaces": {"dashboard": {"port": 65_426}}}, id="port-too-high"), + pytest.param( + {"interfaces": {"dashboard": {"port": 65_426}}}, id="port-too-high" + ), pytest.param( { "interfaces": {"dashboard": {"port": 20_000}}, @@ -1396,12 +1414,8 @@ async def test_openclaw_dashboard_serves_control_ui_with_a_token_file( token_path = _dashboard_token(tmp_path) runtime = adapter.OpenClawRuntime() - await runtime.start( - { - "config": _dashboard_config(mock_openclaw, {"port": dashboard_port}), - "runtime_context": _context(tmp_path).to_mapping(), - "base_dir": str(tmp_path), - } + await _start( + runtime, tmp_path, _dashboard_config(mock_openclaw, {"port": dashboard_port}) ) try: gateway_token = runtime._token @@ -1437,14 +1451,10 @@ async def test_openclaw_dashboard_disabled_serves_no_control_ui( os.environ["FAKE_OPENCLAW_CAPTURE"] = str(capture) runtime = adapter.OpenClawRuntime() - await runtime.start( - { - "config": _dashboard_config( - mock_openclaw, {"port": dashboard_port, "enabled": False} - ), - "runtime_context": _context(tmp_path).to_mapping(), - "base_dir": str(tmp_path), - } + await _start( + runtime, + tmp_path, + _dashboard_config(mock_openclaw, {"port": dashboard_port, "enabled": False}), ) try: gateway_port = runtime._port @@ -1481,12 +1491,10 @@ def fail_after_token_write(_settings): runtime = adapter.OpenClawRuntime() with pytest.raises(RuntimeError, match="after writing the token"): - await runtime.start( - { - "config": _dashboard_config(mock_openclaw, {"port": dashboard_port}), - "runtime_context": _context(tmp_path).to_mapping(), - "base_dir": str(tmp_path), - } + await _start( + runtime, + tmp_path, + _dashboard_config(mock_openclaw, {"port": dashboard_port}), ) assert token_written == [True] @@ -1508,12 +1516,8 @@ async def test_openclaw_dashboard_stop_retries_a_token_it_could_not_remove( os.environ["FAKE_OPENCLAW_CAPTURE"] = str(tmp_path / "config.json") token_path = _dashboard_token(tmp_path) runtime = adapter.OpenClawRuntime() - await runtime.start( - { - "config": _dashboard_config(mock_openclaw, {"port": dashboard_port}), - "runtime_context": _context(tmp_path).to_mapping(), - "base_dir": str(tmp_path), - } + await _start( + runtime, tmp_path, _dashboard_config(mock_openclaw, {"port": dashboard_port}) ) unlink = Path.unlink @@ -1535,7 +1539,9 @@ def fail_token_unlink(path: Path, missing_ok: bool = False) -> None: assert not token_path.exists() -@pytest.mark.skipif(sys.platform == "win32", reason="Runs the mock openclaw script directly") +@pytest.mark.skipif( + sys.platform == "win32", reason="Runs the mock openclaw script directly" +) @pytest.mark.parametrize("offset", [0, 2]) async def test_openclaw_dashboard_port_in_use_fails_start( mock_openclaw: Path, tmp_path: Path, dashboard_port: int, offset: int @@ -1544,14 +1550,10 @@ async def test_openclaw_dashboard_port_in_use_fails_start( with socket.create_server(("127.0.0.1", dashboard_port + offset)): with pytest.raises(adapter.lifecycle.LifecycleError) as caught: - await runtime.start( - { - "config": _dashboard_config( - mock_openclaw, {"port": dashboard_port} - ), - "runtime_context": _context(tmp_path).to_mapping(), - "base_dir": str(tmp_path), - } + await _start( + runtime, + tmp_path, + _dashboard_config(mock_openclaw, {"port": dashboard_port}), ) assert caught.value.code == "openclaw_interface_port_unavailable" @@ -1570,48 +1572,17 @@ async def test_openclaw_services_reject_interfaces( runtime = adapter.OpenClawRuntime() with pytest.raises(adapter.lifecycle.LifecycleError) as caught: - await runtime.start( - { - "config": _dashboard_config(mock_openclaw, {"port": 20_000}), - "runtime_context": _context(tmp_path).to_mapping(), - "base_dir": str(tmp_path), - "service": {"operation": operation}, - } + await _start( + runtime, + tmp_path, + _dashboard_config(mock_openclaw, {"port": 20_000}), + service={"operation": operation}, ) assert caught.value.code == "openclaw_interfaces_require_managed_runtime" assert runtime._process is None -@pytest.mark.skipif(sys.platform == "win32", reason="Runs the mock openclaw script directly") -async def test_openclaw_startup_timeout_bounds_all_of_start( - mock_openclaw: Path, - tmp_path: Path, - dashboard_port: int, - monkeypatch: pytest.MonkeyPatch, -): - # Each command finishes within the timeout, but the two together don't. - monkeypatch.setenv("FAKE_OPENCLAW_COMMAND_DELAY", "0.6") - monkeypatch.setenv("FAKE_OPENCLAW_CAPTURE", str(tmp_path / "config.json")) - config = _dashboard_config(mock_openclaw, {"port": dashboard_port}) - assert config.harness is not None - config.harness.settings["startup_timeout_seconds"] = 1 - runtime = adapter.OpenClawRuntime() - - with pytest.raises(adapter.lifecycle.LifecycleError) as caught: - await runtime.start( - { - "config": config, - "runtime_context": _context(tmp_path).to_mapping(), - "base_dir": str(tmp_path), - } - ) - - assert caught.value.code == "openclaw_command_timeout" - assert runtime._process is None - assert not (tmp_path / "artifacts").exists() - - @pytest.mark.skipif( sys.platform in {"darwin", "win32"}, reason="Starts the mock Gateway, which CI runs only on Linux", @@ -1790,6 +1761,37 @@ def signal_group(pid: int, signum: int) -> None: assert pid_signals == ([(1234, signal.SIGTERM)] if group_signals_denied else []) +@pytest.mark.skipif( + sys.platform == "win32", reason="Runs the mock openclaw script directly" +) +async def test_openclaw_startup_timeout_bounds_all_of_start( + mock_openclaw: Path, + tmp_path: Path, + dashboard_port: int, + monkeypatch: pytest.MonkeyPatch, +): + # Each command finishes within the timeout, but the two together don't. + monkeypatch.setenv("FAKE_OPENCLAW_COMMAND_DELAY", "0.6") + monkeypatch.setenv("FAKE_OPENCLAW_CAPTURE", str(tmp_path / "config.json")) + config = _dashboard_config(mock_openclaw, {"port": dashboard_port}) + assert config.harness is not None + config.harness.settings["startup_timeout_seconds"] = 1 + runtime = adapter.OpenClawRuntime() + + with pytest.raises(adapter.lifecycle.LifecycleError) as caught: + await runtime.start( + { + "config": config, + "runtime_context": _context(tmp_path).to_mapping(), + "base_dir": str(tmp_path), + } + ) + + assert caught.value.code == "openclaw_command_timeout" + assert runtime._process is None + assert not (tmp_path / "artifacts").exists() + + async def test_openclaw_startup_deadline_bounds_a_pending_readiness_request(): async def never_respond(reader, _writer): await reader.read() From d18336475b32f889fbca131a07697ea23edac5cd Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:26:18 -0700 Subject: [PATCH 49/54] test: combine the kept-state path tests One test covers the tracked and untracked workspace patches with an artifacts[1] folder, which also covers a plain folder name, and one covers an agent name or adapter ID that would leave the state folder. Signed-off-by: Carlos Villela --- crates/fabric-core/src/runtime.rs | 153 +++++++++--------------------- 1 file changed, 47 insertions(+), 106 deletions(-) diff --git a/crates/fabric-core/src/runtime.rs b/crates/fabric-core/src/runtime.rs index 1f71c223d..02385ba89 100644 --- a/crates/fabric-core/src/runtime.rs +++ b/crates/fabric-core/src/runtime.rs @@ -5061,87 +5061,37 @@ else: let _ = fs::remove_dir_all(root); } - // A bracket in the artifact folder's name must not act as a pathspec pattern. - const ARTIFACT_FOLDERS: [&str; 2] = ["artifacts", "artifacts[1]"]; - #[test] - fn workspace_patch_leaves_out_kept_agent_state() { - for artifacts in ARTIFACT_FOLDERS { + fn workspace_patches_leave_out_kept_agent_state_by_literal_path() { + for tracked in [false, true] { let root = std::env::temp_dir().join(new_id("fabric-workspace-patch-test")); - let state = root - .join(artifacts) - .join(".fabric/state/acme.agent/assistant"); + // A bracket in the folder name must not act as a pathspec pattern, + // which would also leave out "artifacts1/.fabric/state". + let kept = root.join("artifacts[1]/.fabric/state"); + let state = kept.join("acme.agent/assistant"); fs::create_dir_all(&state).expect("create state folder"); - assert!( - Command::new("git") - .arg("init") - .arg("-q") - .arg(&root) - .status() - .expect("run git init") - .success() - ); - fs::write(root.join("notes.txt"), "note\n").expect("write workspace file"); fs::write(state.join("state.db"), "private\n").expect("write state file"); - // Under glob matching, "artifacts[1]" would also match "artifacts1". - let lookalike = root.join("artifacts1/.fabric/state"); - fs::create_dir_all(lookalike.parent().expect("parent")) - .expect("create lookalike folder"); - fs::write(&lookalike, "workspace\n").expect("write lookalike"); - - let patch = - untracked_workspace_patch(&root, &[root.join(artifacts).join(".fabric/state")]) - .expect("untracked patch"); - - assert!(patch.contains("notes.txt"), "{artifacts}: {patch}"); - assert!( - patch.contains("artifacts1/.fabric/state"), - "{artifacts}: {patch}" - ); - assert!(!patch.contains("state.db"), "{artifacts}: {patch}"); - let _ = fs::remove_dir_all(root); - } - } - - #[test] - fn workspace_patch_leaves_out_tracked_kept_agent_state() { - for artifacts in ARTIFACT_FOLDERS { - let root = std::env::temp_dir().join(new_id("fabric-workspace-patch-test")); - let state = root - .join(artifacts) - .join(".fabric/state/acme.agent/assistant"); - fs::create_dir_all(&state).expect("create state folder"); + fs::create_dir_all(root.join("artifacts1/.fabric")).expect("create lookalike folder"); + fs::write(root.join("artifacts1/.fabric/state"), "workspace\n") + .expect("write lookalike"); + fs::write(root.join("notes.txt"), "note\n").expect("write workspace file"); let git = |args: &[&str]| { - assert!( - Command::new("git") - .arg("-C") - .arg(&root) - .args(args) - .status() - .expect("run git") - .success() - ); + let status = Command::new("git").arg("-C").arg(&root).args(args).status(); + assert!(status.expect("run git").success()); }; git(&["init", "-q"]); - fs::write(root.join("notes.txt"), "note\n").expect("write workspace file"); - fs::write(state.join("state.db"), "private\n").expect("write state file"); - // Under glob matching, "artifacts[1]" would also match "artifacts1". - let lookalike = root.join("artifacts1/.fabric/state"); - fs::create_dir_all(lookalike.parent().expect("parent")) - .expect("create lookalike folder"); - fs::write(&lookalike, "workspace\n").expect("write lookalike"); - git(&["add", "--intent-to-add", "--", "."]); - - let patch = - tracked_workspace_patch(&root, &[root.join(artifacts).join(".fabric/state")]) - .expect("tracked patch"); - - assert!(patch.contains("notes.txt"), "{artifacts}: {patch}"); - assert!( - patch.contains("artifacts1/.fabric/state"), - "{artifacts}: {patch}" - ); - assert!(!patch.contains("state.db"), "{artifacts}: {patch}"); + + let patch = if tracked { + git(&["add", "--intent-to-add", "--", "."]); + tracked_workspace_patch(&root, std::slice::from_ref(&kept)).expect("tracked patch") + } else { + untracked_workspace_patch(&root, std::slice::from_ref(&kept)) + .expect("untracked patch") + }; + + assert!(patch.contains("notes.txt"), "{patch}"); + assert!(patch.contains("artifacts1/.fabric/state"), "{patch}"); + assert!(!patch.contains("state.db"), "{patch}"); let _ = fs::remove_dir_all(root); } } @@ -5192,17 +5142,30 @@ else: } #[test] - fn keep_state_rejects_a_run_plan_whose_agent_name_leaves_the_state_folder() { - let (root, mut plan) = local_host_plan_keeping_state(); - plan.agent_name = "../../outside".to_string(); + fn keep_state_rejects_a_run_plan_whose_names_leave_the_state_folder() { + for (field, value) in [ + ("agent_name", "../../outside"), + ("adapter_id", "../../outside"), + ("adapter_id", "/outside"), + ("adapter_id", "CON"), + ] { + let (root, mut plan) = local_host_plan_keeping_state(); + if field == "agent_name" { + plan.agent_name = value.to_string(); + } else if let Some(adapter) = plan.adapter_descriptor.as_mut() { + adapter.descriptor.adapter_id = value.to_string(); + } - let error = start_runtime(&plan).expect_err("an agent name with .. must not start"); - assert!( - matches!(&error, FabricError::InvalidConfig { field, .. } if field == "agent_name"), - "{error}" - ); - assert!(!root.join("artifacts/.fabric/outside").exists()); - let _ = fs::remove_dir_all(root); + let error = start_runtime(&plan).expect_err(value); + assert!( + matches!(&error, FabricError::InvalidConfig { field: name, .. } if name == field), + "{field} {value}: {error}" + ); + assert!(!root.join("artifacts/.fabric/outside").exists(), "{value}"); + assert!(!root.join("artifacts/outside").exists(), "{value}"); + assert!(!Path::new("/outside").exists(), "{value}"); + let _ = fs::remove_dir_all(root); + } } #[test] @@ -5214,33 +5177,11 @@ else: ".hidden", "CONSOLE", "COM10", - "nul-agent", ] { assert!(is_one_folder_name(name), "{name}"); } } - #[test] - fn keep_state_rejects_an_adapter_id_that_leaves_the_state_folder() { - for adapter_id in ["../../outside", "/outside", "a/b", "CON"] { - let (root, mut plan) = local_host_plan_keeping_state(); - plan.adapter_descriptor - .as_mut() - .expect("adapter descriptor") - .descriptor - .adapter_id = adapter_id.to_string(); - - let error = start_runtime(&plan).expect_err(adapter_id); - assert!( - matches!(&error, FabricError::InvalidConfig { field, .. } if field == "adapter_id"), - "{adapter_id}: {error}" - ); - assert!(!root.join("artifacts/outside").exists(), "{adapter_id}"); - assert!(!Path::new("/outside").exists(), "{adapter_id}"); - let _ = fs::remove_dir_all(root); - } - } - #[cfg(unix)] #[test] fn keep_state_creates_the_state_folder_for_its_owner_only() { From 44e78c622e9c6570f0f0250fa54f9a235534b817 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:26:56 -0700 Subject: [PATCH 50/54] docs: point the Hermes README at the guide for kept state Signed-off-by: Carlos Villela --- adapters/python/hermes/README.md | 13 +++++-------- 1 file changed, 5 insertions(+), 8 deletions(-) diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 3428d18a1..788d272ec 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -111,14 +111,11 @@ Use `runtime.max_turns` to set the Hermes agent-loop budget. The adapter maps that normalized field to `AIAgent.max_iterations`; `max_iterations` is not a Hermes harness setting. -By default, the adapter derives Hermes state from the NeMo Fabric artifact root -and creates a child under `runtimes/`, so invocations in one NeMo -Fabric runtime share state without sharing config or the session database with -another runtime. With `runtime.keep_state`, the Hermes home is the agent's -state folder, `/.fabric/state/nvidia.fabric.hermes/`, -so every runtime of the agent uses the same session database, memory, skills -and logs. Each runtime still starts a new session, and earlier sessions stay in -the database. +The adapter derives Hermes state from the NeMo Fabric artifact root and creates +a child under `runtimes/`, so invocations in one NeMo Fabric runtime +share state without sharing config or the session database with another +runtime. With `runtime.keep_state`, the Hermes home is the agent's state folder +instead; see the [Hermes Agent guide](../../../docs/integrations/harness/hermes.mdx). ## Execution Model From 316fbdfbd7ac9eb63ffd52023ab4464f2d23e938 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:34:11 -0700 Subject: [PATCH 51/54] refactor: trim the skill-folder change to what OpenClaw and Hermes need - Move the TypeScript resolver to the follow-up that switches the TypeScript adapters to it; no TypeScript adapter uses it here. - State the rule once, in Load Skills from Folders, and link to it from the contract text, the tutorial, the build-adapter skill, and the OpenClaw and Hermes guides and READMEs. - Parametrize the resolver tests, and keep one native OpenClaw and one Hermes folder test; the unit tests cover the missing and empty cases. - Revert an unrelated reflow and docstrings on existing Hermes tests. Signed-off-by: Carlos Villela --- ATTRIBUTIONS-Node.md | 31 -- adapter-contract/python/README.md | 4 +- adapter-contract/typescript/README.md | 19 -- adapter-contract/typescript/package-lock.json | 18 -- adapter-contract/typescript/package.json | 8 +- .../schemas/agent-config.schema.json | 2 +- .../typescript/scripts/check-package.mjs | 10 +- .../typescript/src/generated/agent-config.ts | 8 +- adapter-contract/typescript/src/skills.ts | 267 --------------- .../test/skills/resolve-skills.test.mjs | 304 ------------------ adapters/python/hermes/README.md | 23 +- adapters/python/openclaw/README.md | 17 +- crates/fabric-core/src/agent_config.rs | 8 +- .../tutorials/normalized-configuration.md | 21 +- docs/integrations/harness/hermes.mdx | 2 +- docs/integrations/harness/openclaw.mdx | 16 +- docs/integrations/harness/skills.mdx | 6 +- .../agent-config/struct-agentskillconfig.mdx | 2 +- .../adapter-contract/agent-config.schema.json | 2 +- schemas/sdk/run-plan.schema.json | 2 +- skills/nemo-fabric-build-adapter/SKILL.md | 16 +- tests/adapter_contract/test_skills.py | 231 +++++-------- tests/e2e/test_hermes_e2e.py | 33 +- tests/e2e/test_openclaw_skills.py | 47 +-- 24 files changed, 142 insertions(+), 955 deletions(-) delete mode 100644 adapter-contract/typescript/src/skills.ts delete mode 100644 adapter-contract/typescript/test/skills/resolve-skills.test.mjs diff --git a/ATTRIBUTIONS-Node.md b/ATTRIBUTIONS-Node.md index c78e749ce..e9bbf1fe6 100644 --- a/ATTRIBUTIONS-Node.md +++ b/ATTRIBUTIONS-Node.md @@ -24608,37 +24608,6 @@ MIT License SOFTWARE ``` -## @types/node - 20.19.43 - -**Repository URL**: https://github.com/DefinitelyTyped/DefinitelyTyped -**License Type(s)**: MIT - -### License: https://spdx.org/licenses/MIT.html - -``` -MIT License - - Copyright (c) Microsoft Corporation. - - Permission is hereby granted, free of charge, to any person obtaining a copy - of this software and associated documentation files (the "Software"), to deal - in the Software without restriction, including without limitation the rights - to use, copy, modify, merge, publish, distribute, sublicense, and/or sell - copies of the Software, and to permit persons to whom the Software is - furnished to do so, subject to the following conditions: - - The above copyright notice and this permission notice shall be included in all - copies or substantial portions of the Software. - - THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR - IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, - FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE - AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER - LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, - OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE - SOFTWARE -``` - ## @types/node - 22.19.19 **Repository URL**: https://github.com/DefinitelyTyped/DefinitelyTyped diff --git a/adapter-contract/python/README.md b/adapter-contract/python/README.md index 2558160c7..0888af11e 100644 --- a/adapter-contract/python/README.md +++ b/adapter-contract/python/README.md @@ -38,8 +38,8 @@ skills = resolve_skills(config.skills.paths if config.skills else [], base_dir) ``` The helper returns each skill's name and resolved folder. It raises -`SkillPathError` when an entry does not exist or is not a readable folder, or when two -skills share a name. +`SkillPathError` with the failing `skills.paths[N]` field when an entry cannot +be loaded or two skills share a name. An adapter descriptor opts into the southbound configuration with `config.input=agent_config`. Python adapters using the optional common diff --git a/adapter-contract/typescript/README.md b/adapter-contract/typescript/README.md index b57e3620e..59a73768a 100644 --- a/adapter-contract/typescript/README.md +++ b/adapter-contract/typescript/README.md @@ -60,25 +60,6 @@ Use the maintained for the implementation sequence and the bundled schemas for runtime validation. -## Skill Paths - -The `nemo-fabric-adapter-contract/skills` entry point resolves `skills.paths` -in the task environment with Node.js file system APIs. Each entry is a skill -folder or a folder of skills: - -```typescript -import { resolveSkills, SkillPathError } from "nemo-fabric-adapter-contract/skills"; - -const skills = await resolveSkills(config.skills?.paths ?? [], baseDir); -``` - -The helper returns each skill's name, resolved folder, and `skills.paths[N]` -field. It rejects with `SkillPathError` when an entry does not exist or is not -a readable folder, when a skill's `SKILL.md` cannot be read, or when two skills -share a name. It applies the same rules as the Python contract's -`nemo_fabric_adapter_contract.skills.resolve_skills`; refer to the -[normalized configuration tutorial](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/adapter-contract/tutorials/normalized-configuration.md). - ## Invocation Types The package root also exports the same request and result models as the Python diff --git a/adapter-contract/typescript/package-lock.json b/adapter-contract/typescript/package-lock.json index 69f6e1f08..6b8242c27 100644 --- a/adapter-contract/typescript/package-lock.json +++ b/adapter-contract/typescript/package-lock.json @@ -9,7 +9,6 @@ "version": "0.7.0", "license": "Apache-2.0", "devDependencies": { - "@types/node": "20.19.43", "json-schema-to-typescript": "15.0.4", "typescript": "5.6.3" }, @@ -56,16 +55,6 @@ "dev": true, "license": "MIT" }, - "node_modules/@types/node": { - "version": "20.19.43", - "resolved": "https://registry.npmjs.org/@types/node/-/node-20.19.43.tgz", - "integrity": "sha512-6oYBAi5ikg4Pl+kGsoYtawUMBT2zZMCvPNF7pVLnHZfd1zf38DRiWn/gT01RYCdUqkv7Fhr+C9ot4/tb+2sVvA==", - "dev": true, - "license": "MIT", - "dependencies": { - "undici-types": "~6.21.0" - } - }, "node_modules/argparse": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/argparse/-/argparse-2.0.1.tgz", @@ -237,13 +226,6 @@ "engines": { "node": ">=14.17" } - }, - "node_modules/undici-types": { - "version": "6.21.0", - "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-6.21.0.tgz", - "integrity": "sha512-iwDZqg0QAGrg9Rav5H4n0M64c3mkR59cJ6wQp+7C4nI0gsmExaedaYLNO44eT4AtBBwjbTiGPMlt2Md0T9H9JQ==", - "dev": true, - "license": "MIT" } } } diff --git a/adapter-contract/typescript/package.json b/adapter-contract/typescript/package.json index 49159f035..b934f8a66 100644 --- a/adapter-contract/typescript/package.json +++ b/adapter-contract/typescript/package.json @@ -11,10 +11,6 @@ "types": "./dist/index.d.ts", "import": "./dist/index.js" }, - "./skills": { - "types": "./dist/skills.d.ts", - "import": "./dist/skills.js" - }, "./schemas/*": "./schemas/*.schema.json", "./package.json": "./package.json" }, @@ -30,10 +26,9 @@ "build": "node scripts/clean.mjs && tsc -p tsconfig.build.json", "test:generator": "node --test test/*.test.mjs", "test:types": "tsc -p test/tsconfig.json --noEmit", - "test:skills": "npm run build && node --test test/skills/resolve-skills.test.mjs", "test:dependencies": "node scripts/check-dependencies.mjs && npm ls --all && npm audit --audit-level=high", "pack:check": "npm run build && node scripts/check-package.mjs", - "test": "npm run generate:check && npm run test:generator && npm run test:types && npm run test:skills && npm run test:dependencies && npm run pack:check", + "test": "npm run generate:check && npm run test:generator && npm run test:types && npm run test:dependencies && npm run pack:check", "prepack": "npm run generate:check && npm run build" }, "publishConfig": { @@ -53,7 +48,6 @@ "node": ">=20.18.3" }, "devDependencies": { - "@types/node": "20.19.43", "json-schema-to-typescript": "15.0.4", "typescript": "5.6.3" } diff --git a/adapter-contract/typescript/schemas/agent-config.schema.json b/adapter-contract/typescript/schemas/agent-config.schema.json index bd14d3b13..578a59d4a 100644 --- a/adapter-contract/typescript/schemas/agent-config.schema.json +++ b/adapter-contract/typescript/schemas/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. The OpenClaw and Hermes Agent adapters\nfollow this rule; other adapters require each entry to contain\n`SKILL.md`.", "items": { "type": "string" }, diff --git a/adapter-contract/typescript/scripts/check-package.mjs b/adapter-contract/typescript/scripts/check-package.mjs index 878b51fa6..bda0fa56e 100644 --- a/adapter-contract/typescript/scripts/check-package.mjs +++ b/adapter-contract/typescript/scripts/check-package.mjs @@ -54,8 +54,6 @@ try { "dist/index.js", "dist/json.d.ts", "dist/json.js", - "dist/skills.d.ts", - "dist/skills.js", "dist/version.d.ts", "dist/version.js", "package.json", @@ -136,8 +134,6 @@ import agentConfigSchema from "nemo-fabric-adapter-contract/schemas/agent-config import type { AdapterDescriptor } from "nemo-fabric-adapter-contract"; import type { AdapterTargetDescriptor } from "nemo-fabric-adapter-contract"; import type { AgentRunResult } from "nemo-fabric-adapter-contract"; -import { resolveSkills, SkillPathError } from "nemo-fabric-adapter-contract/skills"; -import type { Skill } from "nemo-fabric-adapter-contract/skills"; const descriptor: AdapterDescriptor = { adapter_id: "example", @@ -151,8 +147,6 @@ const target: AdapterTargetDescriptor = { spec: { entrypoint: { kind: "factory", ref: "example.agent" } }, type: "workflow", }; -const skills: Skill[] = []; -void skills; const result: AgentRunResult = { output: ["ok", null], status: "succeeded", @@ -161,9 +155,7 @@ if ( descriptor.contract_version !== ADAPTER_CONTRACT_VERSION || target.adapter_id !== descriptor.adapter_id || result.status !== "succeeded" || - agentConfigSchema.title !== "AgentConfig" || - (await resolveSkills([], "/")).length !== 0 || - new SkillPathError("invalid", "example", { field: "skills.paths[0]", paths: [] }).reason !== "invalid" + agentConfigSchema.title !== "AgentConfig" ) { throw new Error("Unexpected adapter contract values"); } diff --git a/adapter-contract/typescript/src/generated/agent-config.ts b/adapter-contract/typescript/src/generated/agent-config.ts index cf6848298..b53a36389 100644 --- a/adapter-contract/typescript/src/generated/agent-config.ts +++ b/adapter-contract/typescript/src/generated/agent-config.ts @@ -288,11 +288,9 @@ export interface AgentSkillConfig { /** * Skill paths resolved for the task environment. An entry that contains * `SKILL.md` is one skill; otherwise each folder directly inside it that - * contains `SKILL.md` is a skill. An entry that holds no skills loads - * nothing. An entry that is missing, is not a folder, or cannot be read, - * or two resolved skills with the same name, fails. The OpenClaw and - * Hermes Agent adapters follow this rule; other adapters require each - * entry to contain `SKILL.md`. + * contains `SKILL.md` is a skill. The OpenClaw and Hermes Agent adapters + * follow this rule; other adapters require each entry to contain + * `SKILL.md`. */ paths?: string[]; } diff --git a/adapter-contract/typescript/src/skills.ts b/adapter-contract/typescript/src/skills.ts deleted file mode 100644 index a7424538e..000000000 --- a/adapter-contract/typescript/src/skills.ts +++ /dev/null @@ -1,267 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -/** - * Resolve `skills.paths` entries in the task environment. - * - * Each entry names one skill or a folder of skills: - * - * 1. An entry that contains `SKILL.md` is one skill. - * 2. Otherwise each folder directly inside the entry that contains `SKILL.md` - * is a skill. Other files and folders, including folders that cannot be - * read, are ignored. - * 3. An entry that exists but holds no skills loads nothing. - * 4. An entry that does not exist, is not a folder, or cannot be read fails. - * 5. Two skills with the same name fail. The same folder reached through - * several entries loads once. - * - * A skill's name is the `name` field of its `SKILL.md` front matter, or its - * folder name when the front matter has none. - * - * This module uses Node.js file system APIs; import it from - * `nemo-fabric-adapter-contract/skills`. - * - * @module - */ - -import type { FileHandle } from "node:fs/promises"; -import { open, readdir, realpath, stat } from "node:fs/promises"; -import { basename, isAbsolute, join, sep } from "node:path"; - -/** File that marks a folder as a skill. */ -export const SKILL_FILE = "SKILL.md"; - -/** Why a `skills.paths` entry cannot be loaded. */ -export type SkillPathFailure = "not_found" | "invalid" | "duplicate"; - -/** One skill found through `skills.paths`. */ -export interface Skill { - /** Name from the skill's front matter, or its folder name. */ - readonly name: string; - /** Resolved folder that contains the skill's `SKILL.md`. */ - readonly path: string; - /** The `skills.paths` entry that supplied the skill, such as `skills.paths[0]`. */ - readonly field: string; -} - -/** A `skills.paths` entry that cannot be loaded. */ -export class SkillPathError extends Error { - override readonly name = "SkillPathError"; - readonly reason: SkillPathFailure; - readonly field: string; - readonly paths: readonly string[]; - - constructor( - reason: SkillPathFailure, - message: string, - options: { field: string; paths: readonly string[] }, - ) { - super(message); - this.reason = reason; - this.field = options.field; - this.paths = options.paths; - } -} - -const NAME = /^name:(?:[ \t]+(.*?))?[ \t]*$/; -const COMMENT = /[ \t]+#/; - -/** - * Return the skills named by `paths`, resolving relative entries against - * `baseDir`. - * - * @throws {SkillPathError} If an entry does not exist, is not a folder, or - * cannot be read, if a skill's `SKILL.md` cannot be read, or if two skills - * share a name. - */ -export async function resolveSkills( - paths: Iterable, - baseDir: string, -): Promise { - const skills: Skill[] = []; - const byName = new Map(); - const folders = new Set(); - let index = 0; - for (const value of paths) { - const field = `skills.paths[${index}]`; - index += 1; - // Do not normalize ".." here: realpath follows symbolic links before "..". - const configured = isAbsolute(value) ? value : `${baseDir}${sep}${value}`; - let entry: string; - try { - entry = await realpath(configured); - } catch { - throw new SkillPathError( - "not_found", - `NeMo Fabric skill path ${field} does not exist: ${configured}`, - { field, paths: [configured] }, - ); - } - if (!(await isDirectory(entry))) { - throw new SkillPathError( - "invalid", - `NeMo Fabric skill path ${field} is not a folder: ${configured}`, - { field, paths: [configured] }, - ); - } - for (const directory of await skillDirectories(entry, field, configured)) { - const folder = await folderIdentity(directory); - if (folders.has(folder)) { - continue; - } - folders.add(folder); - const skill: Skill = { - name: await skillName(directory, field), - path: directory, - field, - }; - const existing = byName.get(skill.name); - if (existing !== undefined) { - throw new SkillPathError( - "duplicate", - `NeMo Fabric skill '${skill.name}' is configured twice: ` + - `${existing.path} (${existing.field}) and ${skill.path} (${field})`, - { field, paths: [existing.path, skill.path] }, - ); - } - byName.set(skill.name, skill); - skills.push(skill); - } - } - return skills; -} - -async function skillDirectories( - entry: string, - field: string, - configured: string, -): Promise { - let children: string[]; - try { - if (await isFile(join(entry, SKILL_FILE))) { - return [entry]; - } - children = (await readdir(entry)).sort(compareNames); - } catch { - throw new SkillPathError( - "invalid", - `NeMo Fabric skill path ${field} cannot be read: ${configured}`, - { field, paths: [configured] }, - ); - } - const directories: string[] = []; - for (const child of children) { - const path = join(entry, child); - // A folder that cannot be read, such as a volume's lost+found, is not a skill. - try { - if ((await isDirectory(path)) && (await isFile(join(path, SKILL_FILE)))) { - directories.push(await realpath(path)); - } - } catch { - continue; - } - } - return directories; -} - -function compareNames(left: string, right: string): number { - return left < right ? -1 : left > right ? 1 : 0; -} - -const MISSING = new Set(["ENOENT", "ENOTDIR", "ELOOP"]); - -async function isDirectory(path: string): Promise { - try { - return (await stat(path)).isDirectory(); - } catch (error) { - if (MISSING.has(errorCode(error))) { - return false; - } - throw error; - } -} - -async function isFile(path: string): Promise { - try { - return (await stat(path)).isFile(); - } catch (error) { - if (MISSING.has(errorCode(error))) { - return false; - } - throw error; - } -} - -function errorCode(error: unknown): string { - return typeof error === "object" && error !== null && "code" in error - ? String(error.code) - : ""; -} - -async function folderIdentity(directory: string): Promise { - // Compare folders by identity so that spellings realpath keeps apart, such - // as a different case on a case-insensitive file system, still match. An - // inode of 0 identifies nothing, so fall back to the resolved path. - const info = await stat(directory, { bigint: true }); - return info.ino === 0n ? `path:${directory}` : `inode:${info.dev}:${info.ino}`; -} - -async function skillName(directory: string, field: string): Promise { - const skillFile = join(directory, SKILL_FILE); - let handle: FileHandle | undefined; - let name: string | undefined; - try { - handle = await open(skillFile, "r"); - name = await frontMatterName(handle); - } catch { - throw new SkillPathError( - "invalid", - `NeMo Fabric skill path ${field} has a ${SKILL_FILE} that cannot be read: ${skillFile}`, - { field, paths: [skillFile] }, - ); - } finally { - await handle?.close(); - } - return name || basename(directory); -} - -/** Return the `name` scalar of a `---` front matter block, if any. */ -async function frontMatterName(handle: FileHandle): Promise { - let first = true; - let name: string | undefined; - for await (let line of handle.readLines({ encoding: "utf8", autoClose: false })) { - line = line.trimEnd(); - if (first) { - first = false; - if (line.replace(/^\uFEFF/, "") !== "---") { - return undefined; - } - continue; - } - if (line === "---") { - return name; - } - const match = NAME.exec(line); - if (match !== null && !name) { - name = scalar(match[1] ?? ""); - } - } - // Without its closing line the block is not front matter. - return undefined; -} - -function scalar(value: string): string { - const quote = value[0]; - if (quote === "'" || quote === '"') { - const end = value.indexOf(quote, 1); - const rest = end > 0 ? value.slice(end + 1).trim() : ""; - if (end > 0 && (rest === "" || rest.startsWith("#"))) { - return value.slice(1, end); - } - return value; - } - if (value.startsWith("#")) { - return ""; - } - return value.split(COMMENT, 1)[0] ?? ""; -} diff --git a/adapter-contract/typescript/test/skills/resolve-skills.test.mjs b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs deleted file mode 100644 index 309348a77..000000000 --- a/adapter-contract/typescript/test/skills/resolve-skills.test.mjs +++ /dev/null @@ -1,304 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -// Resolve skills.paths entries that name a skill or a folder of skills. These -// run against the build in dist/, so test:skills builds first. -// cases mirror tests/adapter_contract/test_skills.py for the Python contract. - -import assert from "node:assert/strict"; -import { chmod, mkdir, mkdtemp, realpath, rm, symlink, writeFile } from "node:fs/promises"; -import fs, { existsSync } from "node:fs"; -import { syncBuiltinESMExports } from "node:module"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; -import test from "node:test"; - -import { resolveSkills, SkillPathError } from "../../dist/skills.js"; - -const posixPermissions = - typeof process.geteuid === "function" && process.geteuid() !== 0 - ? {} - : { skip: "needs POSIX permissions enforced for a non-root user" }; - -async function temporary(t) { - const root = await realpath(await mkdtemp(join(tmpdir(), "fabric-skills-"))); - const locked = []; - t.after(async () => { - for (const path of locked.reverse()) { - await chmod(path, 0o700); - } - await rm(root, { recursive: true, force: true }); - }); - return { - root, - async lock(path) { - await chmod(path, 0); - locked.push(path); - return path; - }, - }; -} - -async function skill(directory, name) { - await mkdir(directory, { recursive: true }); - const frontMatter = name ? `---\nname: ${name}\ndescription: Test skill.\n---\n` : ""; - await writeFile(join(directory, "SKILL.md"), `${frontMatter}# Test skill\n`, "utf8"); - return directory; -} - -async function rejection(promise) { - try { - await promise; - } catch (error) { - assert.ok(error instanceof SkillPathError, String(error)); - return error; - } - assert.fail("expected a SkillPathError"); -} - -test("an entry with SKILL.md is one skill", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "review"), "code-review"); - - assert.deepEqual(await resolveSkills([review], root), [ - { name: "code-review", path: review, field: "skills.paths[0]" }, - ]); -}); - -test("a skill's name falls back to its folder", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "review")); - - assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), ["review"]); -}); - -test("a quoted front matter name is unquoted", async (t) => { - const { root } = await temporary(t); - const review = join(root, "review"); - await mkdir(review); - await writeFile(join(review, "SKILL.md"), '---\r\nname: "code-review"\r\n---\r\n', "utf8"); - - assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), ["code-review"]); -}); - -test("a folder loads the skills directly inside it", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - const one = await skill(join(shared, "one"), "one"); - const two = await skill(join(shared, "two"), "two"); - await writeFile(join(shared, "notes.md"), "Not a skill.\n", "utf8"); - await mkdir(join(shared, "docs")); - await writeFile(join(shared, "docs", "README.md"), "Not a skill.\n", "utf8"); - await skill(join(shared, "group", "nested"), "nested"); - - assert.deepEqual(await resolveSkills([shared], root), [ - { name: "one", path: one, field: "skills.paths[0]" }, - { name: "two", path: two, field: "skills.paths[0]" }, - ]); -}); - -test("a folder and a separate skill mix", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - await skill(join(shared, "one"), "one"); - await skill(join(shared, "two"), "two"); - const separate = await skill(join(root, "mounted", "three"), "three"); - - const skills = await resolveSkills([shared, separate], root); - - assert.deepEqual(skills.map((s) => [s.name, s.field]), [ - ["one", "skills.paths[0]"], - ["two", "skills.paths[0]"], - ["three", "skills.paths[1]"], - ]); -}); - -test("an existing entry without skills loads nothing", async (t) => { - const { root } = await temporary(t); - await mkdir(join(root, "empty")); - - assert.deepEqual(await resolveSkills([join(root, "empty")], root), []); -}); - -test("a relative entry resolves against the base folder", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "skills", "review"), "review"); - - assert.deepEqual(await resolveSkills(["skills/review"], root), [ - { name: "review", path: review, field: "skills.paths[0]" }, - ]); -}); - -test("a missing entry fails naming it", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "review"), "review"); - const missing = join(root, "missing"); - - const error = await rejection(resolveSkills([review, missing], root)); - - assert.equal(error.reason, "not_found"); - assert.equal(error.field, "skills.paths[1]"); - assert.deepEqual(error.paths, [missing]); - assert.match(error.message, /skills\.paths\[1\]/); - assert.ok(error.message.includes(missing), error.message); -}); - -test("a file entry fails", async (t) => { - const { root } = await temporary(t); - const entry = join(root, "SKILL.md"); - await writeFile(entry, "# Not a folder\n", "utf8"); - - const error = await rejection(resolveSkills([entry], root)); - - assert.equal(error.reason, "invalid"); - assert.equal(error.field, "skills.paths[0]"); - assert.ok(error.message.includes(entry), error.message); -}); - -test("duplicate skill names fail naming both folders", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - const first = await skill(join(shared, "review"), "review"); - const second = await skill(join(root, "mounted", "review-copy"), "review"); - - const error = await rejection(resolveSkills([shared, second], root)); - - assert.equal(error.reason, "duplicate"); - assert.equal(error.field, "skills.paths[1]"); - assert.deepEqual(error.paths, [first, second]); - assert.ok(error.message.includes(first) && error.message.includes(second), error.message); -}); - -test("the same skill listed twice loads once", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - const review = await skill(join(shared, "review"), "review"); - - assert.deepEqual(await resolveSkills([shared, review], root), [ - { name: "review", path: review, field: "skills.paths[0]" }, - ]); -}); - -test("an unreadable folder inside an entry is ignored", posixPermissions, async (t) => { - const { root, lock } = await temporary(t); - const shared = join(root, "shared"); - const one = await skill(join(shared, "one"), "one"); - await mkdir(join(shared, "lost+found")); - await lock(join(shared, "lost+found")); - - assert.deepEqual(await resolveSkills([shared], root), [ - { name: "one", path: one, field: "skills.paths[0]" }, - ]); -}); - -test("an unreadable entry fails naming it", posixPermissions, async (t) => { - const { root, lock } = await temporary(t); - const review = await skill(join(root, "review"), "review"); - const entry = join(root, "locked"); - await mkdir(entry); - await lock(entry); - - const error = await rejection(resolveSkills([review, entry], root)); - - assert.equal(error.reason, "invalid"); - assert.equal(error.field, "skills.paths[1]"); - assert.deepEqual(error.paths, [entry]); - assert.ok(error.message.includes(entry), error.message); -}); - -test("an unreadable SKILL.md fails naming it", posixPermissions, async (t) => { - const { root, lock } = await temporary(t); - const shared = join(root, "shared"); - const review = await skill(join(shared, "review"), "review"); - await lock(join(review, "SKILL.md")); - - const error = await rejection(resolveSkills([shared], root)); - - assert.equal(error.reason, "invalid"); - assert.equal(error.field, "skills.paths[0]"); - assert.deepEqual(error.paths, [join(review, "SKILL.md")]); - assert.ok(error.message.includes(join(review, "SKILL.md")), error.message); -}); - -for (const [text, name] of [ - ["---\nname: code-review # main skill\n---\n", "code-review"], - ["---\nname: 'code-review' # quoted\n---\n", "code-review"], - ["---\nname: code#review\n---\n", "code#review"], - ["--- \nname: code-review\n---\n", "code-review"], - ["\uFEFF---\nname: code-review\n---\n", "code-review"], - ["---\nname:\n---\n", "review"], - ["---\ndescription: Front matter without an end.\nname: code-review\n", "review"], - ["# Review\n\nname: code-review\n", "review"], -]) { - test(`a skill's name follows its front matter: ${JSON.stringify(text)}`, async (t) => { - const { root } = await temporary(t); - const review = join(root, "review"); - await mkdir(review); - await writeFile(join(review, "SKILL.md"), text, "utf8"); - - assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), [name]); - }); -} - -test("a SKILL.md folder does not make a skill", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - await mkdir(join(shared, "SKILL.md"), { recursive: true }); - const one = await skill(join(shared, "one"), "one"); - - assert.deepEqual(await resolveSkills([shared], root), [ - { name: "one", path: one, field: "skills.paths[0]" }, - ]); -}); - -for (const spelling of ["review/", "./review", "other/../review", "link"]) { - test(`the same skill spelled ${spelling} loads once`, async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "review"), "review"); - await mkdir(join(root, "other")); - if (spelling === "link") { - await symlink(review, join(root, "link"), "dir"); - } - - assert.deepEqual(await resolveSkills(["review", spelling], root), [ - { name: "review", path: review, field: "skills.paths[0]" }, - ]); - }); -} - -test("the same skill in another case loads once", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "Review")); - if (!existsSync(join(root, "review"))) { - t.skip("needs a case-insensitive file system"); - return; - } - - assert.deepEqual(await resolveSkills(["Review", "review"], root), [ - { name: "Review", path: review, field: "skills.paths[0]" }, - ]); -}); - -test("folders without inode numbers compare by path", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - const one = await skill(join(shared, "one"), "one"); - const two = await skill(join(shared, "two"), "two"); - // Some file systems report inode 0 for every folder. - const stat = fs.promises.stat; - fs.promises.stat = async (path, options) => { - const info = await stat(path, options); - info.ino = typeof info.ino === "bigint" ? 0n : 0; - return info; - }; - syncBuiltinESMExports(); - t.after(() => { - fs.promises.stat = stat; - syncBuiltinESMExports(); - }); - - assert.deepEqual(await resolveSkills([shared, one], root), [ - { name: "one", path: one, field: "skills.paths[0]" }, - { name: "two", path: two, field: "skills.paths[0]" }, - ]); -}); diff --git a/adapters/python/hermes/README.md b/adapters/python/hermes/README.md index 7830bdde1..912b74fb9 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -63,8 +63,7 @@ The adapter receives a normalized payload from NeMo Fabric and materializes a na - replacement `instructions.system` and `runtime.max_turns`; - workspace and explicit environment variables through `environment`; - invocation timeout through `runtime.timeout_seconds`; -- NeMo Fabric skills as Hermes Agent `skills.external_dirs`, one folder per - skill (refer to [Skills](#skills)); +- NeMo Fabric skills as external skill directories for Hermes Agent; - NeMo Fabric MCP servers as Hermes Agent MCP server config; - `tools.enabled` and `tools.blocked` as Hermes-native toolset selection and blocking policy; @@ -73,21 +72,11 @@ The adapter receives a normalized payload from NeMo Fabric and materializes a na Tool selectors are Hermes toolset names because that is the native policy surface Hermes exposes. -### Skills - -Each `skills.paths` entry is a skill or a folder of skills. An entry that -contains `SKILL.md` is one skill. Otherwise each folder directly inside the -entry that contains `SKILL.md` is a skill, and other files and folders are -ignored. Mix the two forms to combine a shared folder of skills with a skill -mounted on its own. An entry that exists but holds no skills, such as a new, -empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an -entry does not exist and with `hermes_skill_invalid` when an entry is not a folder, when an entry -without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill -folders. The adapter passes each skill folder to Hermes Agent's -`skills.external_dirs`, so Hermes does not search the rest of a configured -folder. Hermes Agent still loads skills nested inside a skill folder; refer to -[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx) for -this and other differences in how Hermes Agent loads skills. +Each `skills.paths` entry is a skill or a folder of skills, as +[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx) +describes. Start fails with `hermes_skill_not_found` for a missing entry and +`hermes_skill_invalid` for the other failures. The adapter passes each skill +folder to Hermes Agent's `skills.external_dirs`. During run-plan resolution, NeMo Fabric Core validates the `models..top_p` (from 0 through 1) and positive diff --git a/adapters/python/openclaw/README.md b/adapters/python/openclaw/README.md index 9d315097d..1753e57cb 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -73,18 +73,11 @@ list maps to a wildcard `tools.deny` policy, and `tools.blocked` maps to isolated temporary OpenClaw state directory. The Gateway is stopped and its temporary configuration is removed when the NeMo Fabric runtime stops. -Each `skills.paths` entry is a skill or a folder of skills. An entry that -contains `SKILL.md` is one skill. Otherwise each folder directly inside the -entry that contains `SKILL.md` is a skill, and other files and folders are -ignored. Mix the two forms to combine a shared folder of skills with a skill -mounted on its own. An entry that exists but holds no skills, such as a new, -empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an -entry does not exist and with `openclaw_skill_invalid` when an entry is not a folder, when an entry -without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill -folders. The adapter passes each skill folder to OpenClaw's -`skills.load.extraDirs`. Refer to -[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx) for -how harnesses differ when they load skills. +Each `skills.paths` entry is a skill or a folder of skills, as +[Load Skills from Folders](../../../docs/integrations/harness/skills.mdx) +describes. Start fails with `openclaw_skill_not_found` for a missing entry and +`openclaw_skill_invalid` for the other failures. The adapter passes each skill +folder to OpenClaw's `skills.load.extraDirs`. For custom OpenAI-compatible providers, set `models..base_url`; the adapter generates an OpenClaw custom provider using the diff --git a/crates/fabric-core/src/agent_config.rs b/crates/fabric-core/src/agent_config.rs index f7cd72f61..042c83015 100644 --- a/crates/fabric-core/src/agent_config.rs +++ b/crates/fabric-core/src/agent_config.rs @@ -142,11 +142,9 @@ pub struct AgentRuntimeConfig { pub struct AgentSkillConfig { /// Skill paths resolved for the task environment. An entry that contains /// `SKILL.md` is one skill; otherwise each folder directly inside it that - /// contains `SKILL.md` is a skill. An entry that holds no skills loads - /// nothing. An entry that is missing, is not a folder, or cannot be read, - /// or two resolved skills with the same name, fails. The OpenClaw and - /// Hermes Agent adapters follow this rule; other adapters require each - /// entry to contain `SKILL.md`. + /// contains `SKILL.md` is a skill. The OpenClaw and Hermes Agent adapters + /// follow this rule; other adapters require each entry to contain + /// `SKILL.md`. #[serde(default, skip_serializing_if = "Vec::is_empty")] pub paths: Vec, /// Adapter-owned skill fields. diff --git a/docs/adapter-contract/tutorials/normalized-configuration.md b/docs/adapter-contract/tutorials/normalized-configuration.md index 91138d2af..ff9b89088 100644 --- a/docs/adapter-contract/tutorials/normalized-configuration.md +++ b/docs/adapter-contract/tutorials/normalized-configuration.md @@ -67,21 +67,12 @@ for exact fields and constraints. Python adapters can use the matching dependency-free dataclasses from `nemo_fabric_adapter_contract.models`. Resolve `skills.paths` during `start` in the task environment, where mounted -skill folders exist. An entry that contains `SKILL.md` is one skill. Otherwise -each folder directly inside the entry that contains `SKILL.md` is a skill, and -other files and folders are ignored. An entry that exists but holds no skills -loads nothing. Fail start when an entry does not exist, when an entry is not a -readable folder, or when two skills share a name, and name the entry or both skill -folders. A skill's name is the `name` field of its `SKILL.md` front matter, or -its folder name. Python adapters can call -`nemo_fabric_adapter_contract.skills.resolve_skills(paths, base_dir)`, and -TypeScript adapters can call `resolveSkills(paths, baseDir)` from -`nemo-fabric-adapter-contract/skills`. Both apply these rules, return each -skill's name and folder, and raise `SkillPathError` with the failing -`skills.paths[N]` field. Pass each resolved skill folder to the harness's -native skill loader, and document how the harness differs from the rule, as -[Load Skills from Folders](../../integrations/harness/skills.mdx) does for -Hermes Agent and OpenClaw. +skill folders exist. Python adapters can call +`nemo_fabric_adapter_contract.skills.resolve_skills(paths, base_dir)`, which +applies the rule in [Load Skills from Folders](../../integrations/harness/skills.mdx), +returns each skill's name and folder, and raises `SkillPathError` with the +failing `skills.paths[N]` field. Pass each resolved skill folder to the +harness's native skill loader. ## To Map the Normalized Configuration diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index 7d511a92f..9fe4206be 100644 --- a/docs/integrations/harness/hermes.mdx +++ b/docs/integrations/harness/hermes.mdx @@ -74,7 +74,7 @@ Replace the endpoint and model, and provide `MODEL_API_KEY` in the adapter envir The adapter supports `instructions.system.mode: replace` and rejects `append`. Tool selectors are Hermes toolset names. `models..top_p` must be between 0 and 1, and `max_tokens` must be positive. A model-level token limit takes precedence over `harness.settings.max_tokens`. If both are omitted, the adapter passes `None` to preserve Hermes' native response token limit behavior for embedded and native interface agents. Use `runtime.max_turns`, not a `max_iterations` harness setting, to control the agent loop. -Each `skills.paths` entry is a skill or a folder of skills. An entry that contains `SKILL.md` is one skill. Otherwise each folder directly inside the entry that contains `SKILL.md` is a skill, and other files and folders are ignored. Mix the two forms to combine a shared folder of skills with a skill mounted on its own. An entry that exists but holds no skills, such as a new, empty volume, loads nothing. Start fails with `hermes_skill_not_found` when an entry does not exist and with `hermes_skill_invalid` when an entry is not a folder, when an entry without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill folders. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`, so Hermes does not search the rest of a configured folder. Hermes Agent still loads skills nested inside a skill folder; refer to [Load Skills from Folders](./skills.mdx) for this and other differences in how Hermes Agent loads skills. +Each `skills.paths` entry is a skill or a folder of skills, as [Load Skills from Folders](./skills.mdx) describes. Start fails with `hermes_skill_not_found` for a missing entry and `hermes_skill_invalid` for the other failures. The adapter passes each skill folder to Hermes Agent's `skills.external_dirs`. ### Hermes Settings diff --git a/docs/integrations/harness/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index 6f8706712..b57005a22 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -94,17 +94,11 @@ MCP configuration. Normalized MCP authentication is not supported. For a custom OpenAI-compatible endpoint, set the model's `base_url` and, when needed, `api_key_env`. -Each `skills.paths` entry is a skill or a folder of skills. An entry that -contains `SKILL.md` is one skill. Otherwise each folder directly inside the -entry that contains `SKILL.md` is a skill, and other files and folders are -ignored. Mix the two forms to combine a shared folder of skills with a skill -mounted on its own. An entry that exists but holds no skills, such as a new, -empty volume, loads nothing. Start fails with `openclaw_skill_not_found` when an -entry does not exist and with `openclaw_skill_invalid` when an entry is not a folder, when an entry -without `SKILL.md` cannot be listed, or when two skills share a name; the error names the entry or both skill -folders. The adapter passes each skill folder to OpenClaw's -`skills.load.extraDirs`. Refer to [Load Skills from Folders](./skills.mdx) -for how harnesses differ when they load skills. +Each `skills.paths` entry is a skill or a folder of skills, as +[Load Skills from Folders](./skills.mdx) describes. Start fails with +`openclaw_skill_not_found` for a missing entry and `openclaw_skill_invalid` for +the other failures. The adapter passes each skill folder to OpenClaw's +`skills.load.extraDirs`. For an endpoint that supports `stream_options.include_usage`, set `models..settings.supports_usage_in_streaming` to `true`. This maps to diff --git a/docs/integrations/harness/skills.mdx b/docs/integrations/harness/skills.mdx index e1f1fc97f..d6eb5b6e4 100644 --- a/docs/integrations/harness/skills.mdx +++ b/docs/integrations/harness/skills.mdx @@ -14,7 +14,7 @@ The following rules apply to each entry: - An entry that contains `SKILL.md` is one skill. - Otherwise, each folder directly inside the entry that contains `SKILL.md` is a skill. Other files and folders, including folders that cannot be read, are ignored. - An entry that exists but holds no skills, such as a new, empty volume, loads nothing. -- Start fails when an entry does not exist, is not a folder, or cannot be read, and when two resolved skills share a name. The error names the entry or both skill folders. +- Start fails when an entry does not exist or is not a folder, when an entry without `SKILL.md` cannot be listed, when a skill's `SKILL.md` cannot be read, or when two resolved skills share a name. The error names the entry or both skill folders. - The same folder listed through several entries loads once. - A skill's name is the `name` field of its `SKILL.md` front matter, or its folder name when the front matter has none. @@ -24,7 +24,7 @@ The OpenClaw and Hermes Agent adapters follow these rules. They pass each resolv ## Harness Differences -NeMo Fabric decides which folders are skills, but the harness loads them. The harness can find more skills inside those folders or name them differently. The following table lists the known differences: +NeMo Fabric decides which folders are skills, but the harness loads them, and it can find more skills or name them differently: | Situation | What Happens | | --- | --- | @@ -34,6 +34,6 @@ NeMo Fabric decides which folders are skills, but the harness loads them. The ha | A skill's file is `skill.md` or uses another case | On a case-insensitive file system, NeMo Fabric accepts the folder as a skill. Hermes Agent requires exactly `SKILL.md` and does not load the skill. | | A skill's name is longer than 64 characters | Hermes Agent cuts the name to 64 characters, so two names that share their first 64 characters collide. | | A folder of skills contains a hidden folder, such as `.archive` | NeMo Fabric loads a hidden folder that contains `SKILL.md` as a skill. Hermes Agent's own scans skip folders such as `.archive`, `.git`, and `.hub`. | -| A Hermes Agent configuration used relative paths, `~`, or `${VAR}` | Relative entries resolve against the agent's base directory, not the Hermes home folder. NeMo Fabric does not expand `~` or `${VAR}`, which Hermes Agent's own `skills.external_dirs` setting does. | +| A Hermes Agent configuration used relative paths, `~`, or `${VAR}` | Hermes Agent's own `skills.external_dirs` resolves relative paths against the Hermes home and expands `~` and `${VAR}`; NeMo Fabric does neither. | To avoid these differences, keep one skill per folder, do not nest skill folders, give each skill a name that differs from every skill folder name, and name the file `SKILL.md`. diff --git a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx index 8958066ab..0933e255a 100644 --- a/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx +++ b/docs/reference/api/rust-library-reference/nemo-fabric-core/agent-config/struct-agentskillconfig.mdx @@ -18,7 +18,7 @@ Skill paths made available to an adapter target. ### `paths: Vec` -Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. An entry that holds no skills loads nothing. An entry that is missing, is not a folder, or cannot be read, or two resolved skills with the same name, fails. The OpenClaw and Hermes Agent adapters follow this rule; other adapters require each entry to contain `SKILL.md`. +Skill paths resolved for the task environment. An entry that contains `SKILL.md` is one skill; otherwise each folder directly inside it that contains `SKILL.md` is a skill. The OpenClaw and Hermes Agent adapters follow this rule; other adapters require each entry to contain `SKILL.md`. ### `extensions: BTreeMap` diff --git a/schemas/adapter-contract/agent-config.schema.json b/schemas/adapter-contract/agent-config.schema.json index bd14d3b13..578a59d4a 100644 --- a/schemas/adapter-contract/agent-config.schema.json +++ b/schemas/adapter-contract/agent-config.schema.json @@ -269,7 +269,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. The OpenClaw and Hermes Agent adapters\nfollow this rule; other adapters require each entry to contain\n`SKILL.md`.", "items": { "type": "string" }, diff --git a/schemas/sdk/run-plan.schema.json b/schemas/sdk/run-plan.schema.json index a2b3f88fb..054afe758 100644 --- a/schemas/sdk/run-plan.schema.json +++ b/schemas/sdk/run-plan.schema.json @@ -769,7 +769,7 @@ "type": "object" }, "paths": { - "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. An entry that holds no skills loads\nnothing. An entry that is missing, is not a folder, or cannot be read,\nor two resolved skills with the same name, fails. The OpenClaw and\nHermes Agent adapters follow this rule; other adapters require each\nentry to contain `SKILL.md`.", + "description": "Skill paths resolved for the task environment. An entry that contains\n`SKILL.md` is one skill; otherwise each folder directly inside it that\ncontains `SKILL.md` is a skill. The OpenClaw and Hermes Agent adapters\nfollow this rule; other adapters require each entry to contain\n`SKILL.md`.", "items": { "type": "string" }, diff --git a/skills/nemo-fabric-build-adapter/SKILL.md b/skills/nemo-fabric-build-adapter/SKILL.md index 0ba5ebcd1..772f11635 100644 --- a/skills/nemo-fabric-build-adapter/SKILL.md +++ b/skills/nemo-fabric-build-adapter/SKILL.md @@ -117,18 +117,12 @@ adapter boundary: planning; `replace` discards the harness default, while `append` preserves it and adds the configured content after it. - Convert MCP servers, tool definitions, tool policy, and skills into native - target constructs. Treat each `skills.paths` entry as one skill when it - contains `SKILL.md`, otherwise as a folder whose direct subfolders that - contain `SKILL.md` are skills; load nothing from an entry without skills, and - fail start on a missing, non-folder, or unreadable entry or on two resolved - skills with the same name. Python adapters can use - `nemo_fabric_adapter_contract.skills.resolve_skills`, and TypeScript adapters - can use `resolveSkills` from `nemo-fabric-adapter-contract/skills`. Pass each - resolved skill folder to the harness's native skill loader. Of the adapters - that ship with NeMo Fabric, the OpenClaw and Hermes Agent adapters follow this - rule; the others still require each entry to contain `SKILL.md`. Refer to + target constructs. Each `skills.paths` entry is a skill or a folder of + skills, as [Load Skills from Folders](https://github.com/NVIDIA/NeMo-Fabric/blob/main/docs/integrations/harness/skills.mdx) - for how harnesses can differ from the rule. + describes; Python adapters can resolve them with + `nemo_fabric_adapter_contract.skills.resolve_skills` and pass each skill + folder to the harness's native skill loader. - Resolve workflow entry points and construction settings during `start` in the task environment. - Read identity, environment, artifacts, telemetry, and the invocation diff --git a/tests/adapter_contract/test_skills.py b/tests/adapter_contract/test_skills.py index ff3392557..6d4938dcb 100644 --- a/tests/adapter_contract/test_skills.py +++ b/tests/adapter_contract/test_skills.py @@ -23,124 +23,20 @@ def _skill(directory: Path, name: str | None = None) -> Path: return directory -def test_entry_with_skill_md_is_one_skill(tmp_path: Path): - review = _skill(tmp_path / "review", "code-review") - - assert resolve_skills([review], tmp_path) == [ - Skill(name="code-review", path=review.resolve(), field="skills.paths[0]") - ] - - -def test_skill_name_falls_back_to_its_directory(tmp_path: Path): - review = _skill(tmp_path / "review") - - assert [skill.name for skill in resolve_skills([review], tmp_path)] == ["review"] - - -def test_quoted_frontmatter_name_is_unquoted(tmp_path: Path): - review = tmp_path / "review" - review.mkdir() - (review / "SKILL.md").write_text( - '---\r\nname: "code-review"\r\n---\r\n', encoding="utf-8" - ) - - assert [skill.name for skill in resolve_skills([review], tmp_path)] == [ - "code-review" - ] - - -def test_folder_loads_skills_directly_inside_it(tmp_path: Path): +def test_entries_name_skills_or_folders_of_skills(tmp_path: Path): shared = tmp_path / "shared" one = _skill(shared / "one", "one") two = _skill(shared / "two", "two") (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") - (shared / "docs").mkdir() - (shared / "docs" / "README.md").write_text("Not a skill.\n", encoding="utf-8") + (shared / "SKILL.md").mkdir() _skill(shared / "group" / "nested", "nested") + three = _skill(tmp_path / "mounted" / "three", "three") + (tmp_path / "empty").mkdir() - assert resolve_skills([shared], tmp_path) == [ + assert resolve_skills([shared, "mounted/three", "empty"], tmp_path) == [ Skill(name="one", path=one.resolve(), field="skills.paths[0]"), Skill(name="two", path=two.resolve(), field="skills.paths[0]"), - ] - - -def test_folder_and_separate_skill_mix(tmp_path: Path): - shared = tmp_path / "shared" - _skill(shared / "one", "one") - _skill(shared / "two", "two") - separate = _skill(tmp_path / "mounted" / "three", "three") - - skills = resolve_skills([shared, separate], tmp_path) - - assert [(skill.name, skill.field) for skill in skills] == [ - ("one", "skills.paths[0]"), - ("two", "skills.paths[0]"), - ("three", "skills.paths[1]"), - ] - - -def test_existing_entry_without_skills_loads_nothing(tmp_path: Path): - empty = tmp_path / "empty" - empty.mkdir() - - assert resolve_skills([empty], tmp_path) == [] - - -def test_relative_entry_resolves_against_base_dir(tmp_path: Path): - review = _skill(tmp_path / "skills" / "review", "review") - - assert resolve_skills(["skills/review"], tmp_path) == [ - Skill(name="review", path=review.resolve(), field="skills.paths[0]") - ] - - -def test_missing_entry_fails_naming_it(tmp_path: Path): - review = _skill(tmp_path / "review", "review") - missing = tmp_path / "missing" - - with pytest.raises(SkillPathError) as caught: - resolve_skills([review, missing], tmp_path) - - assert caught.value.reason == "not_found" - assert caught.value.field == "skills.paths[1]" - assert caught.value.paths == (missing,) - assert "skills.paths[1]" in str(caught.value) - assert str(missing) in str(caught.value) - - -def test_file_entry_fails(tmp_path: Path): - entry = tmp_path / "SKILL.md" - entry.write_text("# Not a folder\n", encoding="utf-8") - - with pytest.raises(SkillPathError) as caught: - resolve_skills([entry], tmp_path) - - assert caught.value.reason == "invalid" - assert caught.value.field == "skills.paths[0]" - assert str(entry) in str(caught.value) - - -def test_duplicate_skill_names_fail_naming_both_paths(tmp_path: Path): - shared = tmp_path / "shared" - first = _skill(shared / "review", "review") - second = _skill(tmp_path / "mounted" / "review-copy", "review") - - with pytest.raises(SkillPathError) as caught: - resolve_skills([shared, second], tmp_path) - - assert caught.value.reason == "duplicate" - assert caught.value.field == "skills.paths[1]" - assert caught.value.paths == (first.resolve(), second.resolve()) - assert str(first.resolve()) in str(caught.value) - assert str(second.resolve()) in str(caught.value) - - -def test_same_skill_listed_twice_loads_once(tmp_path: Path): - shared = tmp_path / "shared" - review = _skill(shared / "review", "review") - - assert resolve_skills([shared, review], tmp_path) == [ - Skill(name="review", path=review.resolve(), field="skills.paths[0]") + Skill(name="three", path=three.resolve(), field="skills.paths[1]"), ] @@ -165,57 +61,86 @@ def lock(path: Path) -> Path: path.chmod(0o700) -@_POSIX_PERMISSIONS -def test_unreadable_folder_inside_entry_is_ignored( - tmp_path: Path, lock: Callable[[Path], Path] -): - shared = tmp_path / "shared" - one = _skill(shared / "one", "one") - (shared / "lost+found").mkdir() - lock(shared / "lost+found") +def _missing( + root: Path, _lock: Callable[[Path], Path] +) -> tuple[list[Path], tuple[Path, ...]]: + return [_skill(root / "review"), root / "missing"], (root / "missing",) - assert resolve_skills([shared], tmp_path) == [ - Skill(name="one", path=one.resolve(), field="skills.paths[0]") - ] +def _file( + root: Path, _lock: Callable[[Path], Path] +) -> tuple[list[Path], tuple[Path, ...]]: + (root / "SKILL.md").write_text("# Not a folder\n", encoding="utf-8") + return [_skill(root / "review"), root / "SKILL.md"], (root / "SKILL.md",) -@_POSIX_PERMISSIONS -def test_unreadable_entry_fails_naming_it(tmp_path: Path, lock: Callable[[Path], Path]): - review = _skill(tmp_path / "review", "review") - entry = tmp_path / "locked" - entry.mkdir() - lock(entry) + +def _duplicate( + root: Path, _lock: Callable[[Path], Path] +) -> tuple[list[Path], tuple[Path, ...]]: + first = _skill(root / "shared" / "review", "review") + second = _skill(root / "mounted" / "review-copy", "review") + return [root / "shared", second], (first.resolve(), second.resolve()) + + +def _unreadable_entry( + root: Path, lock: Callable[[Path], Path] +) -> tuple[list[Path], tuple[Path, ...]]: + (root / "locked").mkdir() + return [_skill(root / "review"), lock(root / "locked")], (root / "locked",) + + +def _unreadable_skill_file( + root: Path, lock: Callable[[Path], Path] +) -> tuple[list[Path], tuple[Path, ...]]: + _skill(root / "review") + review = _skill(root / "shared" / "other") + lock(review / "SKILL.md") + return [root / "review", root / "shared"], (review.resolve() / "SKILL.md",) + + +@pytest.mark.parametrize( + ("layout", "reason"), + [ + (_missing, "not_found"), + (_file, "invalid"), + (_duplicate, "duplicate"), + pytest.param(_unreadable_entry, "invalid", marks=_POSIX_PERMISSIONS), + pytest.param(_unreadable_skill_file, "invalid", marks=_POSIX_PERMISSIONS), + ], +) +def test_failures_name_the_entry_and_paths( + tmp_path: Path, lock: Callable[[Path], Path], layout, reason: str +): + entries, paths = layout(tmp_path, lock) with pytest.raises(SkillPathError) as caught: - resolve_skills([review, entry], tmp_path) + resolve_skills(entries, tmp_path) - assert caught.value.reason == "invalid" + assert caught.value.reason == reason assert caught.value.field == "skills.paths[1]" - assert caught.value.paths == (entry,) + assert caught.value.paths == paths assert "skills.paths[1]" in str(caught.value) - assert str(entry) in str(caught.value) + assert all(str(path) in str(caught.value) for path in paths) @_POSIX_PERMISSIONS -def test_unreadable_skill_file_fails_naming_it( +def test_unreadable_folder_inside_entry_is_ignored( tmp_path: Path, lock: Callable[[Path], Path] ): shared = tmp_path / "shared" - review = _skill(shared / "review", "review") - lock(review / "SKILL.md") - - with pytest.raises(SkillPathError) as caught: - resolve_skills([shared], tmp_path) + one = _skill(shared / "one", "one") + (shared / "lost+found").mkdir() + lock(shared / "lost+found") - assert caught.value.reason == "invalid" - assert caught.value.field == "skills.paths[0]" - assert caught.value.paths == (review.resolve() / "SKILL.md",) - assert str(review.resolve() / "SKILL.md") in str(caught.value) + assert resolve_skills([shared], tmp_path) == [ + Skill(name="one", path=one.resolve(), field="skills.paths[0]") + ] @pytest.mark.parametrize( ("text", "name"), [ + ('---\r\nname: "code-review"\r\n---\r\n', "code-review"), ("---\nname: code-review # main skill\n---\n", "code-review"), ("---\nname: 'code-review' # quoted\n---\n", "code-review"), ("---\nname: code#review\n---\n", "code#review"), @@ -237,24 +162,16 @@ def test_skill_name_follows_front_matter(tmp_path: Path, text: str, name: str): assert [skill.name for skill in resolve_skills([review], tmp_path)] == [name] -def test_skill_md_folder_does_not_make_a_skill(tmp_path: Path): - shared = tmp_path / "shared" - (shared / "SKILL.md").mkdir(parents=True) - one = _skill(shared / "one", "one") - - assert resolve_skills([shared], tmp_path) == [ - Skill(name="one", path=one.resolve(), field="skills.paths[0]") - ] - - -@pytest.mark.parametrize("spelling", ["review/", "./review", "other/../review", "link"]) -def test_same_skill_spelled_differently_loads_once(tmp_path: Path, spelling: str): - review = _skill(tmp_path / "review", "review") +@pytest.mark.parametrize( + "spelling", + ["shared", "shared/review/", "./shared/review", "other/../shared/review", "link"], +) +def test_same_skill_reached_twice_loads_once(tmp_path: Path, spelling: str): + review = _skill(tmp_path / "shared" / "review", "review") (tmp_path / "other").mkdir() - if spelling == "link": - (tmp_path / "link").symlink_to(review, target_is_directory=True) + (tmp_path / "link").symlink_to(review, target_is_directory=True) - assert resolve_skills(["review", spelling], tmp_path) == [ + assert resolve_skills(["shared/review", spelling], tmp_path) == [ Skill(name="review", path=review.resolve(), field="skills.paths[0]") ] diff --git a/tests/e2e/test_hermes_e2e.py b/tests/e2e/test_hermes_e2e.py index 7e50170e5..a48d7d1df 100644 --- a/tests/e2e/test_hermes_e2e.py +++ b/tests/e2e/test_hermes_e2e.py @@ -74,7 +74,6 @@ async def test_hermes_persistent_host_with_relay( code_review_agent_dir: Path, api_server: str, ): - """Verify reused Hermes sessions retain Relay artifacts across invocations.""" os.environ["ADAPTER_PYTHON"] = sys.executable config = with_relay(hermes_config()) config.models["default"].base_url = f"{api_server}/v1" @@ -106,7 +105,8 @@ async def test_hermes_persistent_host_with_relay( ] assert ( sum( - record["name"] == "hermes.session" and record.get("scope_category") == "end" + record["name"] == "hermes.session" + and record.get("scope_category") == "end" for record in atof_records ) == 2 @@ -267,7 +267,6 @@ async def test_skill_selection( default_skill: Path, alternate_skill: Path, ): - """Verify Hermes returns the full supplied skill through a successful tool call.""" os.environ["ADAPTER_PYTHON"] = sys.executable config = with_relay(hermes_config()) config.models["default"].model = "fabric-echo" @@ -346,28 +345,16 @@ def _skill_folder_config(api_server: str, *paths: Path): @pytest.mark.usefixtures("mock_nvidia_api_key", "nemo_relay") -@pytest.mark.parametrize("layout", ["folder", "folder_and_skill", "empty"]) async def test_skill_folders( - code_review_agent_dir: Path, - api_server: str, - tmp_path: Path, - layout: str, + code_review_agent_dir: Path, api_server: str, tmp_path: Path ): - """Verify Hermes lists each skill directly inside a folder, plus separate skills.""" + """Verify Hermes lists each skill directly inside a folder, plus a separate skill.""" shared = tmp_path / "shared" - shared.mkdir() - expected: set[str] = set() - if layout != "empty": - _write_skill(shared / "one", "fabric-one") - _write_skill(shared / "two", "fabric-two") - (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") - _write_skill(shared / "group" / "nested", "fabric-nested") - expected = {"fabric-one", "fabric-two"} - paths = [shared] - if layout == "folder_and_skill": - paths.append(_write_skill(tmp_path / "mounted" / "three", "fabric-three")) - expected.add("fabric-three") - config = _skill_folder_config(api_server, *paths) + _write_skill(shared / "one", "fabric-one") + _write_skill(shared / "two", "fabric-two") + (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") + separate = _write_skill(tmp_path / "mounted" / "three", "fabric-three") + config = _skill_folder_config(api_server, shared, separate) requests.post( f"{api_server}/_scenario", json={"tool_call": {"name": "skills_list", "arguments": {}}}, @@ -393,7 +380,7 @@ async def test_skill_folders( entry["name"] for entry in listed[0]["skills"] if entry["name"].startswith("fabric-") - } == expected + } == {"fabric-one", "fabric-two", "fabric-three"} @pytest.mark.usefixtures("mock_nvidia_api_key", "nemo_relay") diff --git a/tests/e2e/test_openclaw_skills.py b/tests/e2e/test_openclaw_skills.py index 8768f5dbd..3f73ccf71 100644 --- a/tests/e2e/test_openclaw_skills.py +++ b/tests/e2e/test_openclaw_skills.py @@ -126,46 +126,25 @@ def test_configured_skill_is_loaded_by_native_openclaw( assert loaded == [_loaded(sources[skill], skill)] -@pytest.mark.parametrize("layout", ["folder", "folder_and_skill", "empty"]) def test_skill_folders_are_loaded_by_native_openclaw( - tmp_path: Path, openclaw_package: Path, layout: str + tmp_path: Path, openclaw_package: Path ): """Load each skill directly inside a folder, mixed with a separate skill.""" shared = tmp_path / "shared" - shared.mkdir() - expected: list[dict] = [] - if layout != "empty": - one = _skill(shared / "one", "fabric-one") - two = _skill(shared / "two", "fabric-two") - (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") - _skill(shared / "group" / "nested", "fabric-nested") - expected = [_loaded(one, "fabric-one"), _loaded(two, "fabric-two")] - paths = [shared] - if layout == "folder_and_skill": - separate = _skill(tmp_path / "mounted" / "three", "fabric-three") - paths.append(separate) - expected.append(_loaded(separate, "fabric-three")) - - entries = _load_natively(tmp_path, openclaw_package, paths) + one = _skill(shared / "one", "fabric-one") + two = _skill(shared / "two", "fabric-two") + (shared / "notes.md").write_text("Not a skill.\n", encoding="utf-8") + _skill(shared / "group" / "nested", "fabric-nested") + separate = _skill(tmp_path / "mounted" / "three", "fabric-three") - loaded = [entry for entry in entries if entry["name"].startswith("fabric-")] - assert sorted(loaded, key=lambda entry: entry["name"]) == sorted( - expected, key=lambda entry: entry["name"] - ) - - -def test_missing_skill_path_fails_naming_it(tmp_path: Path): - """Refuse a configured entry that is absent from the task environment.""" - shared = tmp_path / "shared" - shared.mkdir() - missing = tmp_path / "missing" + entries = _load_natively(tmp_path, openclaw_package, [shared, separate]) - with pytest.raises(adapter.lifecycle.LifecycleError) as caught: - _native_config(tmp_path, [shared, missing]) - - assert caught.value.code == "openclaw_skill_not_found" - assert caught.value.metadata["field"] == "skills.paths[1]" - assert str(missing) in caught.value.message + loaded = [entry for entry in entries if entry["name"].startswith("fabric-")] + assert sorted(loaded, key=lambda entry: entry["name"]) == [ + _loaded(one, "fabric-one"), + _loaded(separate, "fabric-three"), + _loaded(two, "fabric-two"), + ] def test_duplicate_skill_names_fail_naming_both_paths(tmp_path: Path): From 312f5d010085f53c1cd63898aeb8c57ba94b4e56 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:37:08 -0700 Subject: [PATCH 52/54] test: drop adapter tests that repeat the resolver's empty-folder case The contract's resolver tests and the Claude adapter's folder-without-skills test cover an entry that holds no skills. Signed-off-by: Carlos Villela --- adapters/typescript/pi/test/pi-sdk.test.mjs | 7 ------- tests/adapters/test_claude_adapter.py | 11 ----------- tests/adapters/test_codex_adapter.py | 11 ----------- tests/adapters/test_openhands.py | 11 ----------- 4 files changed, 40 deletions(-) diff --git a/adapters/typescript/pi/test/pi-sdk.test.mjs b/adapters/typescript/pi/test/pi-sdk.test.mjs index 7f381c452..c2534025d 100644 --- a/adapters/typescript/pi/test/pi-sdk.test.mjs +++ b/adapters/typescript/pi/test/pi-sdk.test.mjs @@ -1529,11 +1529,4 @@ test("resolves each skill directly inside a configured skill folder", async (t) join(shared, "review"), join(separate, "test"), ]); - await mkdir(join(root, "empty")); - assert.deepEqual(await resolveSkillPaths(root, ["empty"]), []); - await assert.rejects(resolveSkillPaths(root, ["missing"]), (error) => { - assert.equal(error.code, "pi_skill_not_found"); - assert.deepEqual(error.metadata, { field: "skills.paths[0]" }); - return true; - }); }); diff --git a/tests/adapters/test_claude_adapter.py b/tests/adapters/test_claude_adapter.py index 316e573b1..7a5ac2079 100644 --- a/tests/adapters/test_claude_adapter.py +++ b/tests/adapters/test_claude_adapter.py @@ -2448,14 +2448,3 @@ def test_build_options_stages_each_skill_in_a_skill_folder(claude_payload, tmp_p "security", ] assert (staged / "lint" / "SKILL.md").read_text(encoding="utf-8") == "# lint\n" - - -def test_build_options_stages_no_plugin_for_an_empty_skill_folder( - claude_payload, tmp_path -): - (tmp_path / "empty").mkdir() - claude_payload["config"]["skills"]["paths"] = [str(tmp_path / "empty")] - - options = build_options(claude_payload) - - assert options.skills is None diff --git a/tests/adapters/test_codex_adapter.py b/tests/adapters/test_codex_adapter.py index 9272c3605..1dd79c14a 100644 --- a/tests/adapters/test_codex_adapter.py +++ b/tests/adapters/test_codex_adapter.py @@ -2610,14 +2610,3 @@ def test_sdk_registers_each_skill_in_a_skill_folder( }, response_model=adapter.SkillsExtraRootsSetResponse, ) - - -def test_sdk_registers_no_skill_roots_for_an_empty_skill_folder( - codex_payload, mock_codex, tmp_path -): - (tmp_path / "empty").mkdir() - codex_payload["config"]["skills"] = {"paths": ["empty"]} - - invoke_once(codex_payload) - - mock_codex.instances[0]._client.request.assert_not_awaited() diff --git a/tests/adapters/test_openhands.py b/tests/adapters/test_openhands.py index 715f7f791..0f4625166 100644 --- a/tests/adapters/test_openhands.py +++ b/tests/adapters/test_openhands.py @@ -1124,17 +1124,6 @@ def test_skill_folder_loads_each_skill_directly_inside_it(tmp_path: Path): ] -def test_empty_skill_folder_loads_no_skills(tmp_path: Path): - (tmp_path / "empty").mkdir() - skill_type = MagicMock() - config = AgentConfig.from_mapping({"skills": {"paths": ["empty"]}}) - - assert ( - adapter._skills(SimpleNamespace(Skill=skill_type), config, str(tmp_path)) == [] - ) - skill_type.load.assert_not_called() - - @pytest.mark.parametrize( ("layout", "code"), [ From a2fdccaba3a62a0f1b6b1a781ff9cc9ee7fa9157 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 00:40:16 -0700 Subject: [PATCH 53/54] test: share fixtures across the TypeScript skill resolver tests Signed-off-by: Carlos Villela --- .../test/skills/resolve-skills.test.mjs | 206 +++++------------- 1 file changed, 49 insertions(+), 157 deletions(-) diff --git a/adapter-contract/typescript/test/skills/resolve-skills.test.mjs b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs index 309348a77..b4bcf2928 100644 --- a/adapter-contract/typescript/test/skills/resolve-skills.test.mjs +++ b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs @@ -56,128 +56,61 @@ async function rejection(promise) { assert.fail("expected a SkillPathError"); } -test("an entry with SKILL.md is one skill", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "review"), "code-review"); - - assert.deepEqual(await resolveSkills([review], root), [ - { name: "code-review", path: review, field: "skills.paths[0]" }, - ]); -}); - -test("a skill's name falls back to its folder", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "review")); - - assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), ["review"]); -}); - -test("a quoted front matter name is unquoted", async (t) => { - const { root } = await temporary(t); - const review = join(root, "review"); - await mkdir(review); - await writeFile(join(review, "SKILL.md"), '---\r\nname: "code-review"\r\n---\r\n', "utf8"); - - assert.deepEqual((await resolveSkills([review], root)).map((s) => s.name), ["code-review"]); -}); - -test("a folder loads the skills directly inside it", async (t) => { +test("entries name skills or folders of skills", async (t) => { const { root } = await temporary(t); const shared = join(root, "shared"); const one = await skill(join(shared, "one"), "one"); const two = await skill(join(shared, "two"), "two"); await writeFile(join(shared, "notes.md"), "Not a skill.\n", "utf8"); - await mkdir(join(shared, "docs")); - await writeFile(join(shared, "docs", "README.md"), "Not a skill.\n", "utf8"); + await mkdir(join(shared, "SKILL.md")); await skill(join(shared, "group", "nested"), "nested"); + const three = await skill(join(root, "mounted", "three"), "three"); + await mkdir(join(root, "empty")); - assert.deepEqual(await resolveSkills([shared], root), [ + assert.deepEqual(await resolveSkills([shared, "mounted/three", "empty"], root), [ { name: "one", path: one, field: "skills.paths[0]" }, { name: "two", path: two, field: "skills.paths[0]" }, + { name: "three", path: three, field: "skills.paths[1]" }, ]); }); -test("a folder and a separate skill mix", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - await skill(join(shared, "one"), "one"); - await skill(join(shared, "two"), "two"); - const separate = await skill(join(root, "mounted", "three"), "three"); - - const skills = await resolveSkills([shared, separate], root); - - assert.deepEqual(skills.map((s) => [s.name, s.field]), [ - ["one", "skills.paths[0]"], - ["two", "skills.paths[0]"], - ["three", "skills.paths[1]"], - ]); -}); - -test("an existing entry without skills loads nothing", async (t) => { - const { root } = await temporary(t); - await mkdir(join(root, "empty")); - - assert.deepEqual(await resolveSkills([join(root, "empty")], root), []); -}); - -test("a relative entry resolves against the base folder", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "skills", "review"), "review"); - - assert.deepEqual(await resolveSkills(["skills/review"], root), [ - { name: "review", path: review, field: "skills.paths[0]" }, - ]); -}); - -test("a missing entry fails naming it", async (t) => { - const { root } = await temporary(t); - const review = await skill(join(root, "review"), "review"); - const missing = join(root, "missing"); - - const error = await rejection(resolveSkills([review, missing], root)); - - assert.equal(error.reason, "not_found"); - assert.equal(error.field, "skills.paths[1]"); - assert.deepEqual(error.paths, [missing]); - assert.match(error.message, /skills\.paths\[1\]/); - assert.ok(error.message.includes(missing), error.message); -}); - -test("a file entry fails", async (t) => { - const { root } = await temporary(t); - const entry = join(root, "SKILL.md"); - await writeFile(entry, "# Not a folder\n", "utf8"); - - const error = await rejection(resolveSkills([entry], root)); - - assert.equal(error.reason, "invalid"); - assert.equal(error.field, "skills.paths[0]"); - assert.ok(error.message.includes(entry), error.message); -}); - -test("duplicate skill names fail naming both folders", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - const first = await skill(join(shared, "review"), "review"); - const second = await skill(join(root, "mounted", "review-copy"), "review"); - - const error = await rejection(resolveSkills([shared, second], root)); - - assert.equal(error.reason, "duplicate"); - assert.equal(error.field, "skills.paths[1]"); - assert.deepEqual(error.paths, [first, second]); - assert.ok(error.message.includes(first) && error.message.includes(second), error.message); -}); - -test("the same skill listed twice loads once", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - const review = await skill(join(shared, "review"), "review"); - - assert.deepEqual(await resolveSkills([shared, review], root), [ - { name: "review", path: review, field: "skills.paths[0]" }, - ]); -}); +const failures = [ + ["not_found", {}, async (root) => [[await skill(join(root, "review")), join(root, "missing")], [join(root, "missing")]]], + ["invalid", {}, async (root) => { + await writeFile(join(root, "SKILL.md"), "# Not a folder\n", "utf8"); + return [[await skill(join(root, "review")), join(root, "SKILL.md")], [join(root, "SKILL.md")]]; + }], + ["duplicate", {}, async (root) => { + const first = await skill(join(root, "shared", "review"), "review"); + const second = await skill(join(root, "mounted", "review-copy"), "review"); + return [[join(root, "shared"), second], [first, second]]; + }], + ["invalid", posixPermissions, async (root, lock) => { + await mkdir(join(root, "locked")); + return [[await skill(join(root, "review")), await lock(join(root, "locked"))], [join(root, "locked")]]; + }], + ["invalid", posixPermissions, async (root, lock) => { + await skill(join(root, "review")); + const other = await skill(join(root, "shared", "other")); + await lock(join(other, "SKILL.md")); + return [[join(root, "review"), join(root, "shared")], [join(other, "SKILL.md")]]; + }], +]; + +for (const [index, [reason, options, layout]] of failures.entries()) { + test(`failure ${index} reports ${reason}, naming the entry and paths`, options, async (t) => { + const { root, lock } = await temporary(t); + const [entries, paths] = await layout(root, lock); + + const error = await rejection(resolveSkills(entries, root)); + + assert.equal(error.reason, reason); + assert.equal(error.field, "skills.paths[1]"); + assert.deepEqual(error.paths, paths); + assert.match(error.message, /skills\.paths\[1\]/); + assert.ok(paths.every((path) => error.message.includes(path)), error.message); + }); +} test("an unreadable folder inside an entry is ignored", posixPermissions, async (t) => { const { root, lock } = await temporary(t); @@ -191,36 +124,8 @@ test("an unreadable folder inside an entry is ignored", posixPermissions, async ]); }); -test("an unreadable entry fails naming it", posixPermissions, async (t) => { - const { root, lock } = await temporary(t); - const review = await skill(join(root, "review"), "review"); - const entry = join(root, "locked"); - await mkdir(entry); - await lock(entry); - - const error = await rejection(resolveSkills([review, entry], root)); - - assert.equal(error.reason, "invalid"); - assert.equal(error.field, "skills.paths[1]"); - assert.deepEqual(error.paths, [entry]); - assert.ok(error.message.includes(entry), error.message); -}); - -test("an unreadable SKILL.md fails naming it", posixPermissions, async (t) => { - const { root, lock } = await temporary(t); - const shared = join(root, "shared"); - const review = await skill(join(shared, "review"), "review"); - await lock(join(review, "SKILL.md")); - - const error = await rejection(resolveSkills([shared], root)); - - assert.equal(error.reason, "invalid"); - assert.equal(error.field, "skills.paths[0]"); - assert.deepEqual(error.paths, [join(review, "SKILL.md")]); - assert.ok(error.message.includes(join(review, "SKILL.md")), error.message); -}); - for (const [text, name] of [ + ['---\r\nname: "code-review"\r\n---\r\n', "code-review"], ["---\nname: code-review # main skill\n---\n", "code-review"], ["---\nname: 'code-review' # quoted\n---\n", "code-review"], ["---\nname: code#review\n---\n", "code#review"], @@ -240,27 +145,14 @@ for (const [text, name] of [ }); } -test("a SKILL.md folder does not make a skill", async (t) => { - const { root } = await temporary(t); - const shared = join(root, "shared"); - await mkdir(join(shared, "SKILL.md"), { recursive: true }); - const one = await skill(join(shared, "one"), "one"); - - assert.deepEqual(await resolveSkills([shared], root), [ - { name: "one", path: one, field: "skills.paths[0]" }, - ]); -}); - -for (const spelling of ["review/", "./review", "other/../review", "link"]) { - test(`the same skill spelled ${spelling} loads once`, async (t) => { +for (const spelling of ["shared", "shared/review/", "./shared/review", "other/../shared/review", "link"]) { + test(`the same skill reached as ${spelling} loads once`, async (t) => { const { root } = await temporary(t); - const review = await skill(join(root, "review"), "review"); + const review = await skill(join(root, "shared", "review"), "review"); await mkdir(join(root, "other")); - if (spelling === "link") { - await symlink(review, join(root, "link"), "dir"); - } + await symlink(review, join(root, "link"), "dir"); - assert.deepEqual(await resolveSkills(["review", spelling], root), [ + assert.deepEqual(await resolveSkills(["shared/review", spelling], root), [ { name: "review", path: review, field: "skills.paths[0]" }, ]); }); From e89d6c7c81da2bf07b937b352f8f670b0e6523a8 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Sun, 8 Nov 2026 15:29:40 -0700 Subject: [PATCH 54/54] docs: say how long the kept-state lock lasts On Linux and macOS the adapter host inherits the state lock, so the folder stays locked until the app and the host have exited. If the host is killed while a native process it started in its own session keeps running, the folder is unlocked while that process runs. Adapters must not leave detached children holding inherited descriptors, which would keep the state locked after the host exits. Signed-off-by: Carlos Villela --- docs/adapter-contract/tutorials/adapter-descriptor.md | 6 +++++- docs/sdk/python.mdx | 6 +++++- 2 files changed, 10 insertions(+), 2 deletions(-) diff --git a/docs/adapter-contract/tutorials/adapter-descriptor.md b/docs/adapter-contract/tutorials/adapter-descriptor.md index 27d98f9f5..c2c1b5c31 100644 --- a/docs/adapter-contract/tutorials/adapter-descriptor.md +++ b/docs/adapter-contract/tutorials/adapter-descriptor.md @@ -105,7 +105,11 @@ NeMo Fabric does not silently remove unsupported fields. Accept `runtime.keep_state` only when the adapter keeps all of its native state in `RuntimeContext.state_dir` when that field is present. Every runtime of the agent then receives the same folder, so a later runtime finds the -earlier runtime's sessions, memory, and other harness files. +earlier runtime's sessions, memory, and other harness files. On Linux and +macOS, the adapter host inherits the folder's lock. Don't leave detached +children that keep inherited file descriptors open: such a child keeps the +agent's state locked after the host exits, and later runtimes of the agent +fail to start. When an adapter accepts `instructions.system`, declare the exact supported modes in `config.system_instruction_modes`. `replace` discards the harness diff --git a/docs/sdk/python.mdx b/docs/sdk/python.mdx index c2646581b..3cf12deef 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -871,7 +871,11 @@ as `CON` or `NUL`. On Linux and macOS, only the folder's owner can read it. Only one runtime can use the folder at a time: `Fabric.start_runtime(...)` fails while another runtime of the agent runs. A service and one runtime connected to it share the folder; the service holds it until `Service.release()`, even with -no runtime connected. Planning fails without an artifact directory, or for an +no runtime connected. On Linux and macOS, the adapter host also holds the +folder, so it stays locked until both the process that started the runtime and +the host have exited. If the host itself is killed while a native process it +started in its own session keeps running, the folder is unlocked while that +process runs. Planning fails without an artifact directory, or for an adapter that doesn't declare `runtime.keep_state`. ## Runtime Resource Snapshots