From 4dbc76b7564552fc80eb73c11fafdc16d9dbf622 Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 6 Nov 2026 18:33:36 -0700 Subject: [PATCH 1/2] feat(fabric)!: accept a skill folder or a folder of skills in skills.paths Pin Fabric ec77dcc0, the head of NVIDIA/NeMo-Fabric#615, so OpenClaw and Hermes resolve each skills.paths entry as one skill (it contains SKILL.md) or a folder of skills (each folder directly inside it that contains SKILL.md). A folder without skills adds none; a missing path or a duplicate skill name stops the agent from starting. The interfaces live case mounts a folder of skills and a separate skill for each agent, and Skills on a Mounted Volume shows both forms mixed. Signed-off-by: Carlos Villela --- Cargo.lock | 2 +- crates/fabric-provider/Cargo.toml | 2 +- .../nemoclaw-build/src/run_ci/live_docker.rs | 9 ++- .../docker-openclaw-hermes-interfaces.yaml | 36 +++++++++++- .../kubernetes-gateway-driver-mismatch.yaml | 2 +- .../openshift-external-two-providers.yaml | 4 +- ...cker-openclaw-hermes-interfaces.tftest.hcl | 29 ++++++++++ .../nemoclaw-e2e/tests/e2e/hcl/volume/main.tf | 40 ++++++++++---- ...penshift-external-two-providers.tftest.hcl | 12 ++-- crates/nemoclaw-fabric/Cargo.toml | 2 +- crates/nemoclaw-sdk/Cargo.toml | 2 +- docs/agents-inference/agents.md | 55 +++++++++++++++++-- docs/agents-inference/interfaces.md | 2 +- docs/build-deploy/state.md | 24 ++++---- image/fabric/Dockerfile | 4 +- image/fabric/catalog.json | 5 +- .../contributing/integration-tests.md | 2 +- internal-docs/contributing/live-tests.md | 5 +- internal-docs/design/fabric-management.md | 2 +- 19 files changed, 184 insertions(+), 55 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index f370f43696a..86cb3152752 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2968,7 +2968,7 @@ checksum = "743fb55ba31b18fb1ecef6bdc9aa2743314978ac084044301a7eee33fb99a20d" [[package]] name = "nemo-fabric-core" version = "0.7.0" -source = "git+https://github.com/NVIDIA/NeMo-Fabric?rev=934ab7eca1ec9ac86a22fd24913f2e9d68637c4a#934ab7eca1ec9ac86a22fd24913f2e9d68637c4a" +source = "git+https://github.com/NVIDIA/NeMo-Fabric?rev=ec77dcc0132bb02198f7aac736671bd0effa87eb#ec77dcc0132bb02198f7aac736671bd0effa87eb" dependencies = [ "chrono", "getrandom 0.4.3", diff --git a/crates/fabric-provider/Cargo.toml b/crates/fabric-provider/Cargo.toml index a2a339e1c72..67b809dc790 100644 --- a/crates/fabric-provider/Cargo.toml +++ b/crates/fabric-provider/Cargo.toml @@ -20,7 +20,7 @@ nemoclaw-fabric = { path = "../nemoclaw-fabric" } nemoclaw-openshell = { path = "../nemoclaw-openshell" } nemoclaw-tofu = { path = "../nemoclaw-tofu" } openshell-provider = { path = "../openshell-provider", default-features = false, features = ["kubernetes"] } -nemo-fabric-core = { git = "https://github.com/NVIDIA/NeMo-Fabric", rev = "934ab7eca1ec9ac86a22fd24913f2e9d68637c4a" } +nemo-fabric-core = { git = "https://github.com/NVIDIA/NeMo-Fabric", rev = "ec77dcc0132bb02198f7aac736671bd0effa87eb" } async-trait.workspace = true regex.workspace = true rustls.workspace = true diff --git a/crates/nemoclaw-build/src/run_ci/live_docker.rs b/crates/nemoclaw-build/src/run_ci/live_docker.rs index a60b5e28fbe..94006b3e82e 100644 --- a/crates/nemoclaw-build/src/run_ci/live_docker.rs +++ b/crates/nemoclaw-build/src/run_ci/live_docker.rs @@ -398,8 +398,9 @@ fn dummy_case( const INTERFACES_CASE: &str = "docker-openclaw-hermes-interfaces"; /// The interface case bound to one run's UID, gateway endpoint, subnet, stub -/// model address and port, which its model provider and a grant name, and -/// OpenClaw and Hermes images. +/// model address and port, which its model provider and a grant name, +/// OpenClaw and Hermes images, and skills volumes named for the UID, so runs +/// never share one. fn interfaces_case( template: &str, uid: &str, @@ -424,6 +425,10 @@ fn interfaces_case( ("172.30.123.0/24", subnet), (&format!("nc-fabric@sha256:{zero}"), openclaw), (&format!("nc-fabric-hermes@sha256:{zero}"), hermes), + ( + "source: hcl-interfaces-", + &format!("source: hcl-interfaces-{uid}-"), + ), ], )?) } diff --git a/crates/nemoclaw-e2e/cases/docker-openclaw-hermes-interfaces.yaml b/crates/nemoclaw-e2e/cases/docker-openclaw-hermes-interfaces.yaml index 3b1324eba9e..13ca52bd3c0 100644 --- a/crates/nemoclaw-e2e/cases/docker-openclaw-hermes-interfaces.yaml +++ b/crates/nemoclaw-e2e/cases/docker-openclaw-hermes-interfaces.yaml @@ -6,9 +6,11 @@ # same reply and refuses any request without the run's key. Apply reports # each interface; a person reaches it with the pinned OpenShell CLI's forward # and the token apply names. cargo ci live-docker gives each run a fresh -# identity, gateway port and subnet, stub address, and agent images. Only -# claw grants python3 the stub's /health, which the managed inference grant -# leaves out. +# identity, gateway port and subnet, stub address, volume names, and agent +# images. Only claw grants python3 the stub's /health, which the managed +# inference grant leaves out. Each agent's skills.paths lists a folder of +# skills on one volume and a skill on its own read-only volume; Hermes's +# folder is empty. apiVersion: nemoclaw.nvidia.com/v1alpha1 kind: NemoClawConfig metadata: @@ -53,8 +55,22 @@ spec: access: read-only binaries: - path: /usr/local/bin/python3 + driverConfig: + docker: + mounts: + - type: volume + source: hcl-interfaces-claw-skills + target: /sandbox/skills + read_only: false + - type: volume + source: hcl-interfaces-claw-review-skill + target: /sandbox/review-skill + read_only: true harness: kind: nvidia.fabric.openclaw + config: + skills: + paths: [/sandbox/skills, /sandbox/review-skill] settings: interfaces: dashboard: @@ -72,8 +88,22 @@ spec: ref: nc-fabric-hermes@sha256:0000000000000000000000000000000000000000000000000000000000000000 network: tier: isolated + driverConfig: + docker: + mounts: + - type: volume + source: hcl-interfaces-hermes-skills + target: /sandbox/skills + read_only: false + - type: volume + source: hcl-interfaces-hermes-notes-skill + target: /sandbox/notes-skill + read_only: true harness: kind: nvidia.fabric.hermes + config: + skills: + paths: [/sandbox/skills, /sandbox/notes-skill] settings: interfaces: api: diff --git a/crates/nemoclaw-e2e/cases/kubernetes-gateway-driver-mismatch.yaml b/crates/nemoclaw-e2e/cases/kubernetes-gateway-driver-mismatch.yaml index be82af1c3d5..8d500cbee12 100644 --- a/crates/nemoclaw-e2e/cases/kubernetes-gateway-driver-mismatch.yaml +++ b/crates/nemoclaw-e2e/cases/kubernetes-gateway-driver-mismatch.yaml @@ -24,7 +24,7 @@ spec: assistant: image: metadata: {env: NEMOCLAW_AGENT_IMAGE_METADATA} - ref: fixture/agent@sha256:1d19a142c96ae1c19b60b7636e5af877f54a3138c11d6d6e23ef8b3ac849143e + ref: fixture/agent@sha256:48a128f23afd35fee801a8314c4bea657d335f1ef31f48fd28670f32ae9d6c56 network: tier: isolated harness: diff --git a/crates/nemoclaw-e2e/cases/openshift-external-two-providers.yaml b/crates/nemoclaw-e2e/cases/openshift-external-two-providers.yaml index 6f679a5bd82..8be4b8c1341 100644 --- a/crates/nemoclaw-e2e/cases/openshift-external-two-providers.yaml +++ b/crates/nemoclaw-e2e/cases/openshift-external-two-providers.yaml @@ -49,7 +49,7 @@ spec: assistant: image: metadata: {env: NEMOCLAW_AGENT_IMAGE_METADATA} - ref: fixture/agent@sha256:1d19a142c96ae1c19b60b7636e5af877f54a3138c11d6d6e23ef8b3ac849143e + ref: fixture/agent@sha256:48a128f23afd35fee801a8314c4bea657d335f1ef31f48fd28670f32ae9d6c56 network: tier: isolated harness: @@ -60,7 +60,7 @@ spec: researcher: image: metadata: {env: NEMOCLAW_AGENT_IMAGE_METADATA} - ref: fixture/agent@sha256:1d19a142c96ae1c19b60b7636e5af877f54a3138c11d6d6e23ef8b3ac849143e + ref: fixture/agent@sha256:48a128f23afd35fee801a8314c4bea657d335f1ef31f48fd28670f32ae9d6c56 network: tier: isolated harness: diff --git a/crates/nemoclaw-e2e/tests/e2e/hcl/tests/docker-openclaw-hermes-interfaces.tftest.hcl b/crates/nemoclaw-e2e/tests/e2e/hcl/tests/docker-openclaw-hermes-interfaces.tftest.hcl index ea1e4ebb8de..4d3ba777ede 100644 --- a/crates/nemoclaw-e2e/tests/e2e/hcl/tests/docker-openclaw-hermes-interfaces.tftest.hcl +++ b/crates/nemoclaw-e2e/tests/e2e/hcl/tests/docker-openclaw-hermes-interfaces.tftest.hcl @@ -16,6 +16,35 @@ # the stub at a path only the document grants, and OpenShell refuses its # connection to the managed gateway, which no grant names. Destroy keeps only # the gateway's storage. cargo ci live-docker runs it. +# +# Each agent starts with two skills.paths entries, each on its own volume: a +# folder of skills and a folder that is one skill. OpenClaw's folder holds +# two skills and a file that isn't one; Hermes's is empty. + +# The skills volumes, which a platform provides before apply. The agent images +# run agents as 10001:10001 (image/fabric/Dockerfile). +run "volume" { + module { + source = "./volume" + } + + variables { + owner = "10001:10001" + files = { + "claw:/sandbox/skills" = { + "summarize/SKILL.md" = "---\nname: summarize\ndescription: Summarize the workspace.\n---\n\nSummarize the workspace.\n" + "translate/SKILL.md" = "---\nname: translate\ndescription: Translate the reply.\n---\n\nTranslate the reply.\n" + "README.md" = "Skills shared by the deployment's agents.\n" + } + "claw:/sandbox/review-skill" = { + "SKILL.md" = "---\nname: review\ndescription: Review the change.\n---\n\nReview the change.\n" + } + "hermes:/sandbox/notes-skill" = { + "SKILL.md" = "---\nname: notes\ndescription: Keep notes.\n---\n\nKeep notes.\n" + } + } + } +} run "model" { module { diff --git a/crates/nemoclaw-e2e/tests/e2e/hcl/volume/main.tf b/crates/nemoclaw-e2e/tests/e2e/hcl/volume/main.tf index 51ae3ba521b..2dda299cd1a 100644 --- a/crates/nemoclaw-e2e/tests/e2e/hcl/volume/main.tf +++ b/crates/nemoclaw-e2e/tests/e2e/hcl/volume/main.tf @@ -4,8 +4,9 @@ # The named volumes a Docker case's sandboxes mount, provisioned with the # bundled Docker provider before the case's first apply, as # docs/build-deploy/state.md asks of a platform: each volume carries -# OpenShell's default approval labels for the deployment's workspace, and the -# sandbox's identity owns its root. NemoClaw's destroy leaves the volumes; +# OpenShell's default approval labels for the deployment's workspace, holds +# the files the case names for it, and belongs to the sandbox's identity. +# NemoClaw's destroy leaves the volumes; # tofu test removes them when the case ends. terraform { @@ -28,15 +29,25 @@ variable "owner" { type = string } +variable "files" { + description = "Files to write in a volume before its sandbox starts: by \"SANDBOX:TARGET\", the sandbox's name and the volume's mount target, then by path in the volume." + type = map(map(string)) + default = {} +} + locals { document = yamldecode(file(var.context.config)) # OpenShell admits a volume for the workspace that its label names, which # NemoClaw derives from the deployment's UID. workspace = "nc-${substr(sha256(local.document.metadata.uid), 0, 16)}" - # Each mounted volume and the image of the sandbox that mounts it. + # Each mounted volume, the image of the sandbox that mounts it, and the + # files to write in it. volumes = merge([ - for sandbox in values(local.document.spec.sandboxes) : { - for mount in try(sandbox.driverConfig.docker.mounts, []) : mount.source => sandbox.image.ref + for name, sandbox in local.document.spec.sandboxes : { + for mount in try(sandbox.driverConfig.docker.mounts, []) : mount.source => { + image = sandbox.image.ref + files = lookup(var.files, "${name}:${mount.target}", {}) + } if mount.type == "volume" } ]...) @@ -69,13 +80,20 @@ resource "docker_volume" "mounted" { } # A new volume's root belongs to root. The sandbox's own image, run once as -# root without a network, hands it to the sandbox's identity. +# root without a network, writes the volume's files and hands it to the +# sandbox's identity. Each file's content arrives in its own environment +# variable, so the script quotes only paths. resource "docker_container" "owner" { - for_each = local.volumes - name = "${each.key}-owner" - image = each.value - user = "0:0" - entrypoint = ["chown", var.owner, "/volume"] + for_each = local.volumes + name = "${each.key}-owner" + image = each.value.image + user = "0:0" + entrypoint = length(each.value.files) == 0 ? ["chown", var.owner, "/volume"] : ["sh", "-c", join("\n", concat( + ["set -e"], + [for index, path in keys(each.value.files) : "mkdir -p \"$(dirname '/volume/${path}')\" && printf '%s' \"$NEMOCLAW_VOLUME_FILE_${index}\" > '/volume/${path}'"], + ["chown -R ${var.owner} /volume"], + ))] + env = [for index, path in keys(each.value.files) : "NEMOCLAW_VOLUME_FILE_${index}=${each.value.files[path]}"] network_mode = "none" must_run = false attach = true diff --git a/crates/nemoclaw-e2e/tests/integration/hcl/tests/openshift-external-two-providers.tftest.hcl b/crates/nemoclaw-e2e/tests/integration/hcl/tests/openshift-external-two-providers.tftest.hcl index a1fa04dde85..72e0b5db210 100644 --- a/crates/nemoclaw-e2e/tests/integration/hcl/tests/openshift-external-two-providers.tftest.hcl +++ b/crates/nemoclaw-e2e/tests/integration/hcl/tests/openshift-external-two-providers.tftest.hcl @@ -45,13 +45,13 @@ run "verify" { assert { condition = alltrue([ for binding in [ - openshell_inference.inference_hosted-22877e5d3b30075fab1951c5, - openshell_inference.inference_nvidia-0eeb59e6e69664e5ca31bc21, - openshell_inference.inference_nvidia-b086c7471e688c318b5fc93e, + openshell_inference.inference_hosted-9d2dfc001bdd6f546a5d19fd, + openshell_inference.inference_nvidia-361ce3344fad2b9d0b2ba866, + openshell_inference.inference_nvidia-f7d603dfd605989d81132c5d, ] : module.observed.registrations[binding.registration].credentials == { (binding.sandbox_env) = "env:${binding.server.credential_env}" } && contains(values(module.observed.registrations[binding.registration].config), binding.server.endpoint) - ]) && openshell_inference.inference_hosted-22877e5d3b30075fab1951c5.api == "anthropic-messages" + ]) && openshell_inference.inference_hosted-9d2dfc001bdd6f546a5d19fd.api == "anthropic-messages" error_message = "A registration's API, base URL, or credential differs from its provider." } @@ -59,7 +59,7 @@ run "verify" { # the Hermes sandbox names only its own NVIDIA binding. assert { condition = ( - contains(module.observed.agents.assistant.providers, openshell_inference.inference_hosted-22877e5d3b30075fab1951c5.registration) + contains(module.observed.agents.assistant.providers, openshell_inference.inference_hosted-9d2dfc001bdd6f546a5d19fd.registration) && length(module.observed.agents.assistant.providers) == 2 && length(module.observed.agents.researcher.providers) == 1 && length(setintersection(module.observed.agents.assistant.providers, module.observed.agents.researcher.providers)) == 0 @@ -72,7 +72,7 @@ run "verify" { condition = ( module.observed.agents.assistant.start.configuration == jsondecode(terraform_data.agent_assistant.input) && module.observed.agents.researcher.start.configuration == jsondecode(terraform_data.agent_researcher.input) - && module.observed.agents.assistant.start.configuration.models.smart.api_key_env == openshell_inference.inference_hosted-22877e5d3b30075fab1951c5.sandbox_env + && module.observed.agents.assistant.start.configuration.models.smart.api_key_env == openshell_inference.inference_hosted-9d2dfc001bdd6f546a5d19fd.sandbox_env && module.observed.agents.assistant.start.configuration.models.default == module.observed.agents.assistant.start.configuration.models.smart && module.observed.http.requests == [] ) diff --git a/crates/nemoclaw-fabric/Cargo.toml b/crates/nemoclaw-fabric/Cargo.toml index 0ef18838893..a845c71f383 100644 --- a/crates/nemoclaw-fabric/Cargo.toml +++ b/crates/nemoclaw-fabric/Cargo.toml @@ -20,7 +20,7 @@ nemoclaw-docker = { path = "../nemoclaw-docker", optional = true } nemoclaw-openshell = { path = "../nemoclaw-openshell" } nemoclaw-tofu = { path = "../nemoclaw-tofu" } jsonschema.workspace = true -nemo-fabric-core = { git = "https://github.com/NVIDIA/NeMo-Fabric", rev = "934ab7eca1ec9ac86a22fd24913f2e9d68637c4a" } +nemo-fabric-core = { git = "https://github.com/NVIDIA/NeMo-Fabric", rev = "ec77dcc0132bb02198f7aac736671bd0effa87eb" } serde.workspace = true serde_json.workspace = true sha2.workspace = true diff --git a/crates/nemoclaw-sdk/Cargo.toml b/crates/nemoclaw-sdk/Cargo.toml index 4da001f0b89..a4a8e655b4b 100644 --- a/crates/nemoclaw-sdk/Cargo.toml +++ b/crates/nemoclaw-sdk/Cargo.toml @@ -40,7 +40,7 @@ nemoclaw-fabric = { path = "../nemoclaw-fabric", default-features = false } # Only the endpoint policy and retained identity types, without the engine client. nemoclaw-docker = { path = "../nemoclaw-docker", default-features = false } nemoclaw-runtime = { path = "../nemoclaw-runtime", default-features = false } -nemo-fabric-core = { git = "https://github.com/NVIDIA/NeMo-Fabric", rev = "934ab7eca1ec9ac86a22fd24913f2e9d68637c4a" } +nemo-fabric-core = { git = "https://github.com/NVIDIA/NeMo-Fabric", rev = "ec77dcc0132bb02198f7aac736671bd0effa87eb" } futures-util.workspace = true jsonschema.workspace = true reqwest.workspace = true diff --git a/docs/agents-inference/agents.md b/docs/agents-inference/agents.md index 18cb239bfe3..4833cccf598 100644 --- a/docs/agents-inference/agents.md +++ b/docs/agents-inference/agents.md @@ -55,7 +55,7 @@ Check `result.status` as well as the outer `status`: the outer one only reports ### Run One Headless OpenClaw Request Headless operation follows the same public Fabric invocation boundary. -The [pinned OpenClaw adapter](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/openclaw/README.md) takes a text prompt and sends it to the native OpenClaw agent selected by `harness.settings.agent_id`, which defaults to `default`. +The [pinned OpenClaw adapter](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/openclaw/README.md) takes a text prompt and sends it to the native OpenClaw agent selected by `harness.settings.agent_id`, which defaults to `default`. A request can incur inference charges and affect retained conversation history. With the [pinned OpenClaw example](../get-started/first-deployment.md) applied, use its sandbox key `assistant`, agent name `main`, and state directory. From the v1 worktree root on the client host, read the runtime ID and send a request: @@ -157,9 +157,31 @@ NemoClaw does not wrap its refresh contract, and manual sandbox attachments affe ## Skills on a Mounted Volume Fabric reads skills from the paths in `fabric_agent`'s `skills` block. +For OpenClaw and Hermes, each path is a skill or a folder of skills: + +- A folder that contains `SKILL.md` is one skill. +- Otherwise, each folder directly inside it that contains `SKILL.md` is a skill; Fabric ignores the folder's other files and folders. +- A folder that holds no skills, such as a new, empty volume, adds none. + +The agent doesn't start when a path doesn't exist or two skills have the same name; Fabric's error names the path or both skills' folders. +For other harnesses, the [pinned Fabric adapters](https://github.com/NVIDIA/NeMo-Fabric/tree/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters) say what a path must hold. + To give an agent skills that outlive its sandbox, mount a volume into the sandbox through OpenShell's driver configuration and point `skills` at the mount. The gateway must allow driver configuration: for a managed gateway, set `allow_driver_config: true` in the driver's table of `spec.gateway.config` when you create the deployment (see [mounted volumes](../build-deploy/state.md#keep-agent-files-on-mounted-volumes)); for an external gateway, its administrator enables OpenShell's `allow_driver_config`. -In YAML, set the sandbox's `driverConfig` and list the mount in the harness configuration's `skills`: + +Mix the two forms to share a folder of skills between agents and give one agent a skill of its own, with its own mount settings. +In this example, the `team-skills` volume holds a folder per skill, and the `review-skill` volume holds one skill at its root: + +```text +team-skills review-skill +├── summarize/ └── SKILL.md +│ └── SKILL.md +└── translate/ + └── SKILL.md +``` + +Both agents mount `team-skills` read-only; only the OpenClaw agent mounts `review-skill`, and it can write there. +In YAML, set each sandbox's `driverConfig` and list its mounts in the harness configuration's `skills`: ```yaml sandboxes: @@ -168,15 +190,35 @@ sandboxes: docker: mounts: - type: volume - source: assistant-skills + source: team-skills target: /sandbox/skills + read_only: true + - type: volume + source: review-skill + target: /sandbox/review-skill + read_only: false harness: kind: nvidia.fabric.openclaw + config: + skills: + paths: [/sandbox/skills, /sandbox/review-skill] + researcher: + driverConfig: + docker: + mounts: + - type: volume + source: team-skills + target: /sandbox/skills + read_only: true + harness: + kind: nvidia.fabric.hermes config: skills: paths: [/sandbox/skills] ``` +The `assistant` agent loads `summarize`, `translate`, and the skill in `review-skill`; `researcher` loads `summarize` and `translate`. + In HCL, use `openshell_sandbox`'s [`driver_config`](../references/provider.md#openshell-resources-and-data-sources) and `fabric_agent`'s `skills` block: ```hcl @@ -184,7 +226,10 @@ resource "openshell_sandbox" "assistant" { # ... driver_config = jsonencode({ docker = { - mounts = [{ type = "volume", source = "assistant-skills", target = "/sandbox/skills" }] + mounts = [ + { type = "volume", source = "team-skills", target = "/sandbox/skills", read_only = true }, + { type = "volume", source = "review-skill", target = "/sandbox/review-skill", read_only = false }, + ] } }) } @@ -192,7 +237,7 @@ resource "openshell_sandbox" "assistant" { resource "fabric_agent" "assistant" { # ... skills { - paths = ["/sandbox/skills"] + paths = ["/sandbox/skills", "/sandbox/review-skill"] } } ``` diff --git a/docs/agents-inference/interfaces.md b/docs/agents-inference/interfaces.md index 6fcd5c747a8..e60f232fd17 100644 --- a/docs/agents-inference/interfaces.md +++ b/docs/agents-inference/interfaces.md @@ -97,7 +97,7 @@ Apply prints this command for each interface that an agent's configuration enabl OpenClaw's Control UI and Hermes's API server and dashboard are served by the agent's Fabric runtime inside its sandbox, on loopback ports that you choose. Fabric's adapters start them, generate their tokens, and stop them with the runtime; NemoClaw checks the settings while planning and tells you how to reach each interface after apply. -The [Fabric OpenClaw adapter](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/openclaw/README.md#serve-the-control-ui) and [Fabric Hermes adapter](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/hermes/README.md#serve-the-api-server-and-dashboard) document each interface's behavior. +The [Fabric OpenClaw adapter](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/openclaw/README.md#serve-the-control-ui) and [Fabric Hermes adapter](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/hermes/README.md#serve-the-api-server-and-dashboard) document each interface's behavior. ### Enable an Interface diff --git a/docs/build-deploy/state.md b/docs/build-deploy/state.md index b494014ac7d..ae7c2f1b52f 100644 --- a/docs/build-deploy/state.md +++ b/docs/build-deploy/state.md @@ -50,7 +50,7 @@ Native settings can select other locations; inspect the selected harness configu | OO Agents (`nooa`) and BenchAgent (`nooa-bench`) | Working files use the configured workspace; persistence beyond those files belongs to the selected native target, with no common backup path defined by these adapters | | Remote agent | Conversation history is held by the live Fabric adapter and discarded when it stops; server-side data remains under the remote service's control and is not backed up by collecting sandbox files | -NemoClaw sets the workspace and artifact locations in the agent's Fabric configuration; the [pinned Fabric adapters](https://github.com/NVIDIA/NeMo-Fabric/tree/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python) define the rest. +NemoClaw sets the workspace and artifact locations in the agent's Fabric configuration; the [pinned Fabric adapters](https://github.com/NVIDIA/NeMo-Fabric/tree/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python) define the rest. When the image's adapter accepts Fabric's `runtime.keep_state`, NemoClaw sets it, so Fabric gives every runtime of the agent the same state folder instead of one per runtime; among the bundled images, only Hermes's adapter does. With `/sandbox/artifacts` on a [mounted volume](#keep-agent-files-on-mounted-volumes), that state survives sandbox replacement. Only one runtime can use the folder at a time. To discard the state, delete the folder or the volume. @@ -125,17 +125,17 @@ Paths describe the pinned Fabric adapters linked above, not a common history imp | Harness | Additional mount and retained files | Conversation after runtime replacement | |---|---|---| -| [OpenClaw](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py) | Workspace files only; the adapter overrides native state/config paths with its private temporary directory and removes it on stop | Mounting the workspace does not preserve the adapter's temporary native history | -| [Hermes](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py) | `/sandbox/artifacts` retains the native home under `.fabric/state/nvidia.fabric.hermes/`, with the session database, memory, and skills, plus Relay traces when enabled | A new runtime starts a new session in the same database; the API server still finds earlier sessions, but the agent doesn't resume them | -| [Claude Code](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/claude/src/nemo_fabric_adapters/claude/adapter.py) | `/sandbox/artifacts` retains generated MCP configuration and skill plugins under `.fabric/claude`; this is not an inventory of the native client's home | The adapter starts a new native client; no saved-conversation reattachment procedure is provided | -| [Codex](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/codex/README.md#authentication) | `/sandbox/artifacts` retains `.fabric/codex`, including `custom-provider-home` for non-OpenAI providers; cached native login uses `CODEX_HOME` (default `/sandbox/.codex`), which needs its own mount if retained | The adapter starts a new thread; OpenAI API-key login instead uses a temporary home outside artifacts and removes it on stop, even if `CODEX_HOME` was supplied | -| [LangChain Deep Agents](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/deepagents/src/nemo_fabric_adapters/deepagents/adapter.py) | `/sandbox/artifacts` retains the SQLite checkpoints under `.fabric/deepagents/runtimes` | Each runtime creates a new LangGraph thread ID; the saved SQLite file alone does not resume the old thread | -| [Pi](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/typescript/pi/src/pi-sdk.ts) | Workspace files; the adapter uses an in-memory session manager | No conversation file to retain; stopping the runtime loses its conversation | -| [OpenCode](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/typescript/opencode/README.md) | Workspace files, and each invocation's reported diff under `opencode/` in the artifact directory | No conversation file to retain; stopping the runtime removes its session | -| [mini-SWE-agent](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/mini-swe-agent/src/nemo_fabric_adapters/mini_swe_agent/adapter.py) | Workspace files; the adapter keeps the conversation in the live runtime | No conversation file to retain; stopping the runtime loses its conversation | -| [OO Agents (`nooa`)](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/nooa/src/nemo_fabric_adapters/nooa/adapter.py) | Workspace files; additional storage depends on the selected native target | The adapter defines no common persistent conversation path or restore procedure | -| [BenchAgent (`nooa-bench`)](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/nooa/src/nemo_fabric_adapters/nooa/bench_adapter.py) | Workspace files; additional storage depends on the selected native target | The adapter defines no common persistent conversation path or restore procedure | -| [Remote agent](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/adapters/python/remote-agent/src/nemo_fabric_adapters/remote_agent/adapter.py) | Workspace files and any requested local artifacts; remote service data stays with that service | Local adapter history is in memory; a local volume does not back up the remote service | +| [OpenClaw](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/openclaw/src/nemo_fabric_adapters/openclaw/adapter.py) | Workspace files only; the adapter overrides native state/config paths with its private temporary directory and removes it on stop | Mounting the workspace does not preserve the adapter's temporary native history | +| [Hermes](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py) | `/sandbox/artifacts` retains the native home under `.fabric/state/nvidia.fabric.hermes/`, with the session database, memory, and skills, plus Relay traces when enabled | A new runtime starts a new session in the same database; the API server still finds earlier sessions, but the agent doesn't resume them | +| [Claude Code](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/claude/src/nemo_fabric_adapters/claude/adapter.py) | `/sandbox/artifacts` retains generated MCP configuration and skill plugins under `.fabric/claude`; this is not an inventory of the native client's home | The adapter starts a new native client; no saved-conversation reattachment procedure is provided | +| [Codex](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/codex/README.md#authentication) | `/sandbox/artifacts` retains `.fabric/codex`, including `custom-provider-home` for non-OpenAI providers; cached native login uses `CODEX_HOME` (default `/sandbox/.codex`), which needs its own mount if retained | The adapter starts a new thread; OpenAI API-key login instead uses a temporary home outside artifacts and removes it on stop, even if `CODEX_HOME` was supplied | +| [LangChain Deep Agents](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/deepagents/src/nemo_fabric_adapters/deepagents/adapter.py) | `/sandbox/artifacts` retains the SQLite checkpoints under `.fabric/deepagents/runtimes` | Each runtime creates a new LangGraph thread ID; the saved SQLite file alone does not resume the old thread | +| [Pi](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/typescript/pi/src/pi-sdk.ts) | Workspace files; the adapter uses an in-memory session manager | No conversation file to retain; stopping the runtime loses its conversation | +| [OpenCode](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/typescript/opencode/README.md) | Workspace files, and each invocation's reported diff under `opencode/` in the artifact directory | No conversation file to retain; stopping the runtime removes its session | +| [mini-SWE-agent](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/mini-swe-agent/src/nemo_fabric_adapters/mini_swe_agent/adapter.py) | Workspace files; the adapter keeps the conversation in the live runtime | No conversation file to retain; stopping the runtime loses its conversation | +| [OO Agents (`nooa`)](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/nooa/src/nemo_fabric_adapters/nooa/adapter.py) | Workspace files; additional storage depends on the selected native target | The adapter defines no common persistent conversation path or restore procedure | +| [BenchAgent (`nooa-bench`)](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/nooa/src/nemo_fabric_adapters/nooa/bench_adapter.py) | Workspace files; additional storage depends on the selected native target | The adapter defines no common persistent conversation path or restore procedure | +| [Remote agent](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/adapters/python/remote-agent/src/nemo_fabric_adapters/remote_agent/adapter.py) | Workspace files and any requested local artifacts; remote service data stays with that service | Local adapter history is in memory; a local volume does not back up the remote service | Mounting the whole home or a temporary directory does not establish conversation resume. Homes can contain login tokens and generated authentication configuration, while adapter cleanup can still delete files on a mounted temporary directory. diff --git a/image/fabric/Dockerfile b/image/fabric/Dockerfile index 28484e3d7f7..4e348fb654c 100644 --- a/image/fabric/Dockerfile +++ b/image/fabric/Dockerfile @@ -8,8 +8,8 @@ ARG RUST_IMAGE=rust:1.99.1-slim-trixie@sha256:aab42391a986424e22d6a3ec14f37bc6dd ARG UV_IMAGE=ghcr.io/astral-sh/uv:0.13.7@sha256:96f40d3904aad8d0bd010539001d36c8e2188b981e1334471a90c4a1d93bb490 # The Fabric source every harness installs; the reference dummy's descriptor # follows the adapter contract at the same revision. -ARG FABRIC_REVISION=934ab7eca1ec9ac86a22fd24913f2e9d68637c4a -ARG FABRIC_SHA256=33c4e855e3b72464546b5cb77cc83644f7401956976d34dc7f11cd4235203ff6 +ARG FABRIC_REVISION=ec77dcc0132bb02198f7aac736671bd0effa87eb +ARG FABRIC_SHA256=275395222fc37ea391a1ad21e06bb65484aa5e0d3b5667fc08d0243d0f05c7d7 # OpenClaw release 2026.9.34, the only version the pinned Fabric's OpenClaw # adapter supports; move it with the Fabric revision, not on its own. ARG OPENCLAW_IMAGE=ghcr.io/openclaw/openclaw@sha256:70e88573161a9248cfe992c069f638085ac066278e03f11a46bcbd115f38e3fc diff --git a/image/fabric/catalog.json b/image/fabric/catalog.json index 3613ab3b813..a3bc7c91d74 100644 --- a/image/fabric/catalog.json +++ b/image/fabric/catalog.json @@ -562,7 +562,6 @@ "type": "object" }, "max_tokens": { - "default": 512, "description": "Maximum number of tokens in each Hermes model response.", "minimum": 1, "type": "integer" @@ -2193,8 +2192,8 @@ ] } ], - "fabric_revision": "934ab7eca1ec9ac86a22fd24913f2e9d68637c4a", + "fabric_revision": "ec77dcc0132bb02198f7aac736671bd0effa87eb", "schema_version": 2, - "source_sha256": "33c4e855e3b72464546b5cb77cc83644f7401956976d34dc7f11cd4235203ff6", + "source_sha256": "275395222fc37ea391a1ad21e06bb65484aa5e0d3b5667fc08d0243d0f05c7d7", "targets": [] } diff --git a/internal-docs/contributing/integration-tests.md b/internal-docs/contributing/integration-tests.md index c11e06371d6..0874956b26a 100644 --- a/internal-docs/contributing/integration-tests.md +++ b/internal-docs/contributing/integration-tests.md @@ -374,7 +374,7 @@ The SDK's [compatibility tests](../../crates/nemoclaw-sdk/tests/fabric_compatibi ### Inference API Fixtures -Native adapter protocol and configuration tests belong to [Fabric](https://github.com/NVIDIA/NeMo-Fabric/tree/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/tests), alongside the implementation. +Native adapter protocol and configuration tests belong to [Fabric](https://github.com/NVIDIA/NeMo-Fabric/tree/ec77dcc0132bb02198f7aac736671bd0effa87eb/tests), alongside the implementation. The [image source checks](testing.md#image-source-checks) cover NemoClaw packaging separately. diff --git a/internal-docs/contributing/live-tests.md b/internal-docs/contributing/live-tests.md index f807d0114e4..8eefc23abd7 100644 --- a/internal-docs/contributing/live-tests.md +++ b/internal-docs/contributing/live-tests.md @@ -223,7 +223,10 @@ The `docker-openclaw-hermes-interfaces` [HCL E2E scenario](#hcl-e2e-scenarios) d `cargo ci live-docker` runs it: it installs the pinned OpenShell CLI by checksum, binds the case to a fresh UID, gateway port and subnet, stub address, and the run's OpenClaw and Hermes images, and passes a fresh model key as `NEMOCLAW_TEST_INTERFACES_MODEL_KEY` and `TF_VAR_model_key`. Before apply, the `tests/e2e/hcl/model` module runs a stub model with the bundled Docker provider: the pinned `nginx-unprivileged` image that the development issuer runs, on the host network at the port the case's `model` provider names. It lists one model and answers every chat completion with the same reply, streamed when the request asks, and refuses any request without that key. -Apply must report each interface's port, sign-in, and token file. +The `tests/e2e/hcl/volume` module also creates each sandbox's two skills volumes, named for the run's UID, and writes their skills, owned by the agent image's user. +Each agent's `skills.paths` lists a folder of skills on one volume and a folder that is one skill on a read-only volume, as [Skills on a Mounted Volume](../../docs/agents-inference/agents.md#skills-on-a-mounted-volume) describes; OpenClaw's folder holds two skills and a file that isn't one, and Hermes's folder is empty. +Apply must start both agents with them, and report each interface's port, sign-in, and token file. +Whether the agent uses a skill is not checked live; Fabric's tests check what each harness loads. The `tests/e2e/hcl/interface` module then runs `hcl_live::interface` once per request: it reads the reported token with `openshell sandbox exec`, forwards the port with `openshell forward service`, and sends one request with the token as a Bearer credential. OpenClaw's Control UI page must load and its configuration endpoint must accept the token; Hermes's API server must list its models and answer a chat completion with the stub's reply, which also shows that NemoClaw sent the configured key; Hermes's dashboard page must load with its session token. Reports hold status codes; tokens and response bodies stay in the run's private `work` directory. diff --git a/internal-docs/design/fabric-management.md b/internal-docs/design/fabric-management.md index 28c49fbb049..592802b3795 100644 --- a/internal-docs/design/fabric-management.md +++ b/internal-docs/design/fabric-management.md @@ -41,7 +41,7 @@ Success exits 0; failure and unsupported operations exit 1. Requests are limited to 512 KiB and responses to 4 MiB. Diagnostics carry only Fabric's fixed stages and codes, never its messages. A timeout, malformed response, or disconnection leaves the outcome unconfirmed; callers do not replay starts or invocations. -Fabric's [runtime server documentation](https://github.com/NVIDIA/NeMo-Fabric/blob/934ab7eca1ec9ac86a22fd24913f2e9d68637c4a/sdk/python/nemo-fabric-runtime/src/nemo_fabric/runtime_server/README.md) defines the commands. +Fabric's [runtime server documentation](https://github.com/NVIDIA/NeMo-Fabric/blob/ec77dcc0132bb02198f7aac736671bd0effa87eb/sdk/python/nemo-fabric-runtime/src/nemo_fabric/runtime_server/README.md) defines the commands. Fabric can start another runtime in a sandbox after a stop. After a start whose effects Fabric reports as uncertain, another start returns `runtime_exists`, which the provider reports with guidance to replace the sandbox. From 6f1c4b78414188e47444a98b97be02958d4a812b Mon Sep 17 00:00:00 2001 From: Carlos Villela Date: Fri, 6 Nov 2026 18:38:27 -0700 Subject: [PATCH 2/2] docs(skills): state the pinned Fabric's skills.paths rule in verify-fabric-boundary Signed-off-by: Carlos Villela --- .agents/skills/verify-fabric-boundary/SKILL.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.agents/skills/verify-fabric-boundary/SKILL.md b/.agents/skills/verify-fabric-boundary/SKILL.md index 5cd1b8c4c30..8d6ac5748d3 100644 --- a/.agents/skills/verify-fabric-boundary/SKILL.md +++ b/.agents/skills/verify-fabric-boundary/SKILL.md @@ -84,7 +84,7 @@ Run [Write the YAML](../verify-yaml-deployment/SKILL.md#write-the-yaml), all fiv Add what the checks need to the base YAML, then save it: 1. **Volumes.** Mount `$WORKSPACE_VOLUME` at `/sandbox/workspace` and `$ARTIFACTS_VOLUME` at `/sandbox/artifacts`, with `read_only: false` on both mounts; OpenShell defaults them to read-only. Follow [caller-owned volumes](../../../docs/build-deploy/state.md) for admission and filesystem access. -2. **Skills.** Keep the supplied skill under `/sandbox/workspace/skills/capability-probe`. Check the selected adapter's path validation before setting `harness.config.skills.paths`: OpenClaw at Fabric `e5b5ebf2b81cc3c6325301ea419ebf2453dab12e` requires individual skill directories containing `SKILL.md`, so use `[/sandbox/workspace/skills/capability-probe]`, not the parent directory. Record this per-item configuration separately from native discovery; do not claim directory scanning or automatic discovery of generated skills from it. +2. **Skills.** Keep the supplied skill under `/sandbox/workspace/skills/capability-probe`. Check the selected adapter's path validation before setting `harness.config.skills.paths`: at the Fabric pin in `image/fabric/Dockerfile`, OpenClaw and Hermes accept a folder that contains `SKILL.md` or a folder of such folders, as [Skills on a Mounted Volume](../../../docs/agents-inference/agents.md#skills-on-a-mounted-volume) describes. Use `[/sandbox/workspace/skills/capability-probe]`, the supplied skill's own folder, so the path names only that skill. Record this per-item configuration separately from native discovery; do not claim directory scanning or automatic discovery of generated skills from it. 3. **Capabilities.** Choose the run-scoped extension names first: run step 2 of [mounted-extensions](features/mounted-extensions.md), and note the generated plugin's ID, `fb-plugin-$UID8`, as step 4 of [plugins](features/plugins.md) derives it. Resolve the bundled plugin's safe trigger, observable effect, and startup registration capture through [plugin bindings](features/plugins.md#driving-it-with-fabric-agent-ctl-and-the-openshell-cli) before apply; Hermes has a [pinned binding recipe](references/hermes-bundled-plugin.md). Then enable each capability the feature files check: the native TUI and, where in scope, the Web UI; a harmless bundled plugin; the mounted native tool and plugin locations under `/sandbox/workspace/extensions`, with any per-item enablement; and a tool allow-list from which Config change can remove only the shell-launch tool.