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/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/python/README.md b/adapter-contract/python/README.md index 05f1f9734..0888af11e 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` 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 lifecycle host pass `AgentConfig.from_mapping` as the `config_loader`. 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/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..2c01ffc46 --- /dev/null +++ b/adapter-contract/python/src/nemo_fabric_adapter_contract/skills.py @@ -0,0 +1,197 @@ +# 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:(?:[ \t]+(.*?))?[ \t]*") +_COMMENT = re.compile(r"[ \t]+#") + + +@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``. + + 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, 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] | Path] = set() + 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, 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 not None: + 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), + ) + by_name[skill.name] = skill + skills.append(skill) + return skills + + +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] | Path: + # Compare folders by identity so that spellings resolve() 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. + stat = directory.stat() + return (stat.st_dev, stat.st_ino) if stat.st_ino else directory + + +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/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..49159f035 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/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: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/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/agent-config.schema.json b/adapter-contract/typescript/schemas/agent-config.schema.json index 193ea1206..c850cfe58 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. The adapters that ship with NeMo Fabric\nfollow this rule, except Deep Agents, which passes each entry to Deep\nAgents as a skill source.", "items": { "type": "string" }, 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/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/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/agent-config.ts b/adapter-contract/typescript/src/generated/agent-config.ts index eb77eec56..179072280 100644 --- a/adapter-contract/typescript/src/generated/agent-config.ts +++ b/adapter-contract/typescript/src/generated/agent-config.ts @@ -286,7 +286,11 @@ 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. 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/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/adapter-contract/typescript/src/skills.ts b/adapter-contract/typescript/src/skills.ts new file mode 100644 index 000000000..a7424538e --- /dev/null +++ b/adapter-contract/typescript/src/skills.ts @@ -0,0 +1,267 @@ +// 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 new file mode 100644 index 000000000..b4bcf2928 --- /dev/null +++ b/adapter-contract/typescript/test/skills/resolve-skills.test.mjs @@ -0,0 +1,196 @@ +// 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("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, "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, "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]" }, + ]); +}); + +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); + 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]" }, + ]); +}); + +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"], + ["--- \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]); + }); +} + +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, "shared", "review"), "review"); + await mkdir(join(root, "other")); + await symlink(review, join(root, "link"), "dir"); + + assert.deepEqual(await resolveSkills(["shared/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/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/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/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/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/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/hermes/README.md b/adapters/python/hermes/README.md index 45bcbda43..912b74fb9 100644 --- a/adapters/python/hermes/README.md +++ b/adapters/python/hermes/README.md @@ -72,6 +72,12 @@ 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. +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 `models..max_tokens` fields against the Hermes descriptor before @@ -114,7 +120,8 @@ 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. +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 diff --git a/adapters/python/hermes/hermes.fabric-adapter.json b/adapters/python/hermes/hermes.fabric-adapter.json index 0ceeda9e3..3c7231c7f 100644 --- a/adapters/python/hermes/hermes.fabric-adapter.json +++ b/adapters/python/hermes/hermes.fabric-adapter.json @@ -75,7 +75,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", @@ -130,6 +130,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 3fa9935f1..cf4911e16 100755 --- a/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py +++ b/adapters/python/hermes/src/nemo_fabric_adapters/hermes/adapter.py @@ -115,14 +115,14 @@ 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) + # 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") @@ -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, ) @@ -242,7 +243,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=max( interfaces.startup_timeout(self._settings) - (asyncio.get_running_loop().time() - started_at), @@ -700,6 +701,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/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/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/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/openclaw/README.md b/adapters/python/openclaw/README.md index a8447ddde..1753e57cb 100644 --- a/adapters/python/openclaw/README.md +++ b/adapters/python/openclaw/README.md @@ -73,6 +73,12 @@ 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, 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 `openai-completions` API adapter. Set `api_key_env` when that provider requires @@ -107,6 +113,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..602cda7b5 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. OpenClaw allocates browser ports through port + 110 on demand, so keep that range free. 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 fa450672f..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,8 +31,10 @@ 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 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(): @@ -283,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: @@ -461,6 +481,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 +514,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 +811,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 +821,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 +866,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 +1060,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 +1123,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 +1153,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 +1218,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, @@ -1712,6 +1747,19 @@ async def invoke( async def stop(self) -> None: cancellation: asyncio.CancelledError | None = None self._stopping = True + token_path = self._dashboard_token_path + if token_path is not None: + 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/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/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/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/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/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/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/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/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/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/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/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..c2534025d 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,26 @@ 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"), + ]); +}); 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/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]", + ); +}); 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": [ 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 0ceeda9e3..3c7231c7f 100644 --- a/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json +++ b/crates/fabric-cli/assets/adapters/hermes/hermes.fabric-adapter.json @@ -75,7 +75,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", @@ -130,6 +130,7 @@ "models.max_tokens", "instructions.system", "runtime.max_turns", + "runtime.keep_state", "tools.enabled", "tools.blocked", "mcp", 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/agent_config.rs b/crates/fabric-core/src/agent_config.rs index 9e86515bf..5e1f3d155 100644 --- a/crates/fabric-core/src/agent_config.rs +++ b/crates/fabric-core/src/agent_config.rs @@ -140,7 +140,11 @@ 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. 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/crates/fabric-core/src/config.rs b/crates/fabric-core/src/config.rs index 72cc01947..58720d713 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 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 && (!timeout.is_finite() || timeout <= 0.0 @@ -2388,6 +2402,47 @@ fn validate_names(field: &str, names: &[String]) -> Result<()> { Ok(()) } +/// 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.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 { Err(FabricError::InvalidConfig { field: field.into(), @@ -2635,6 +2690,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 { @@ -2811,6 +2877,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..02385ba89 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}; @@ -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,9 @@ 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. + // A service host holds it for the runtimes connected to the service. + _state_lock: Option, } struct LocalServiceRecord { @@ -1033,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)?; @@ -1388,11 +1403,13 @@ pub fn stop_runtime(plan: &RunPlan, runtime: &RuntimeHandle) -> Result Result, environment_env: BTreeMap, ) -> Result { + // 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(), @@ -2675,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); } @@ -2779,6 +2820,7 @@ fn spawn_local_host( artifacts, relay_config, environment_env, + _state_lock: state_lock, }) } @@ -3479,9 +3521,112 @@ 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(), + }); + }; + // A deserialized plan can carry any agent name, so check it again here. + if !is_one_folder_name(&plan.agent_name) { + return Err(FabricError::InvalidConfig { + field: "agent_name".to_string(), + reason: "must be one folder name when runtime.keep_state is set".to_string(), + }); + } + // A local descriptor can declare any adapter ID, so check it the same way. + let adapter = adapter_id(plan).unwrap_or_else(|| harness(plan)); + if !is_one_folder_name(&adapter) { + return Err(FabricError::InvalidConfig { + field: "adapter_id".to_string(), + reason: "must be one folder name when runtime.keep_state is set".to_string(), + }); + } + 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 here or, on Unix, in the adapter host that inherits +/// it, and the operating system releases it when both have exited, 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, + })?; + // Kept state can hold conversations and credentials: only its owner may + // read it, including a folder that an earlier runtime created. + #[cfg(unix)] + { + use std::os::unix::fs::PermissionsExt; + std::fs::set_permissions(&state_dir, std::fs::Permissions::from_mode(0o700)).map_err( + |source| FabricError::Write { + path: state_dir.clone(), + source, + }, + )?; + } + // The lock sits beside the folder, which the adapter owns and may replace. + let mut lock_name = std::ffi::OsString::from("."); + lock_name.push(state_dir.file_name().unwrap_or_default()); + lock_name.push(".lock"); + let lock_path = state_dir.with_file_name(lock_name); + let file = File::options() + .create(true) + .write(true) + .truncate(false) + .open(&lock_path) + .map_err(|source| FabricError::Write { + path: lock_path.clone(), + 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 @@ -3932,23 +4077,17 @@ 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 { + // Kept agent state can hold conversations and credentials; leave it out + // when the artifact directory sits inside the workspace. + let kept_state: Vec = manifest + .root + .iter() + .map(|root| root.join(".fabric").join("state")) + .collect(); + let Some(mut patch) = tracked_workspace_patch(workspace, &kept_state) else { return Ok(()); }; - if !diff.status.success() { - return Ok(()); - } - patch.push_str(&String::from_utf8_lossy(&diff.stdout)); - patch.push_str(&untracked_workspace_patch(workspace)?); + patch.push_str(&untracked_workspace_patch(workspace, &kept_state)?); if patch.trim().is_empty() { return Ok(()); } @@ -3987,16 +4126,55 @@ fn collect_workspace_artifacts( Ok(()) } -fn untracked_workspace_patch(workspace: &Path) -> Result { - let Ok(untracked) = Command::new("git") +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()?; + // Match the path literally: a folder name such as "artifacts[1]" + // would otherwise be a pattern that also leaves out other paths. + let mut pathspec = std::ffi::OsString::from(":(exclude,literal)"); + pathspec.push(relative); + Some(pathspec) + }) + .collect() +} + +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(".") + .args(excluded_pathspecs(workspace, excluded)); + let Ok(untracked) = command.output() else { return Ok(String::new()); }; if !untracked.status.success() || untracked.stdout.is_empty() { @@ -4453,6 +4631,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 = { @@ -4533,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"); @@ -4819,6 +5007,302 @@ for line in sys.stdin: let _ = fs::remove_dir_all(root); } + fn local_host_plan_keeping_state() -> (PathBuf, RunPlan) { + 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"), + ) + .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()); + // 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_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")); + // 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"); + fs::write(state.join("state.db"), "private\n").expect("write state file"); + 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]| { + let status = Command::new("git").arg("-C").arg(&root).args(args).status(); + assert!(status.expect("run git").success()); + }; + git(&["init", "-q"]); + + 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); + } + } + + #[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")]; + let mut without_artifacts = accepting.config.clone(); + without_artifacts.runtime.artifacts = None; + cases.push((&root, without_artifacts, "runtime.keep_state")); + for name in [ + "..", + "a/b", + "a\\b", + "a:b", + "a*b", + "a?b", + "a|b", + "ab", + "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")); + } + + 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); + } + + #[test] + 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(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] + fn one_folder_name_accepts_names_that_are_folders_on_every_platform() { + for name in [ + "assistant", + "my agent", + "a.b", + ".hidden", + "CONSOLE", + "COM10", + ] { + assert!(is_one_folder_name(name), "{name}"); + } + } + + #[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); + } + + #[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(); + let service = prepare_service(&plan).expect("prepare service"); + + let first = start_runtime_with_service(&plan, &service).expect("first connected runtime"); + let error = start_runtime_with_service(&plan, &service) + .expect_err("a second connected runtime must not share the folder"); + assert!(matches!(error, FabricError::StateInUse { .. }), "{error}"); + let error = start_runtime(&plan).expect_err("an independent runtime must not share it"); + assert!(matches!(error, FabricError::StateInUse { .. }), "{error}"); + stop_runtime(&plan, &first).expect("stop first runtime"); + let second = start_runtime_with_service(&plan, &service) + .expect("connect once the first runtime stopped"); + stop_runtime(&plan, &second).expect("stop second runtime"); + release_service(&plan, &service).expect("release service"); + let independent = start_runtime(&plan).expect("start once the service is released"); + stop_runtime(&plan, &independent).expect("stop independent runtime"); + 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"); + 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); + } + 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 +5330,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..c2c1b5c31 100644 --- a/docs/adapter-contract/tutorials/adapter-descriptor.md +++ b/docs/adapter-contract/tutorials/adapter-descriptor.md @@ -102,6 +102,15 @@ 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. 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 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..2170649ab 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. 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/adapter-contract/tutorials/normalized-configuration.md b/docs/adapter-contract/tutorials/normalized-configuration.md index 833a23cd2..6dc7f8413 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,16 @@ 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. 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`. Each 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 Work through each step in order, verifying your progress at each checkpoint. 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/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/hermes-interfaces.mdx b/docs/integrations/harness/hermes-interfaces.mdx index 1fe7c0bfc..84200547b 100644 --- a/docs/integrations/harness/hermes-interfaces.mdx +++ b/docs/integrations/harness/hermes-interfaces.mdx @@ -72,12 +72,14 @@ An absent interface is off. A present interface is on unless `enabled` is `false ### API Access -The API server binds to `127.0.0.1` at its configured port. After every enabled interface passes readiness, the adapter writes a per-start bearer token with mode `0600` to: +The API server binds to `127.0.0.1` at its configured port. After every enabled interface passes readiness, the adapter writes a per-start bearer token with mode `0600` to `interfaces/api.token` in the Hermes home. By default, that is: ```text /.fabric/hermes/runtimes//interfaces/api.token ``` +With `runtime.keep_state`, the Hermes home is the agent's state folder, `/.fabric/state/nvidia.fabric.hermes/`. + Clients calling the native API must read the generated token file and include `Authorization: Bearer ` in each HTTP request. Only the API gateway child receives it in its environment. Processes running as the runtime's user, including agent tools, can read the token file. ### Dashboard Access @@ -88,7 +90,7 @@ Open the configured loopback port in a browser. The dashboard has no sign-in: He Ordered SDK invocations reuse the embedded agent's conversation. Native clients use Hermes's native session mechanisms and receive native responses; these do not pass through `Runtime.invoke()` or become NeMo Fabric `RunResult` objects. -The runtime's Hermes home is stored under `/.fabric/hermes/runtimes/`. Sharing that home gives access to persisted resources, but does not select a shared live conversation or establish cross-runtime resume. +The runtime's Hermes home is stored under `/.fabric/hermes/runtimes/`, or in the agent's state folder with `runtime.keep_state`. Sharing that home gives access to persisted resources, but does not select a shared live conversation or establish cross-runtime resume. ## 4. What NeMo Fabric Manages diff --git a/docs/integrations/harness/hermes.mdx b/docs/integrations/harness/hermes.mdx index db5f28e11..9fe4206be 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, 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 The descriptor uses closed schemas, so unknown settings are rejected. @@ -88,9 +90,18 @@ The descriptor uses closed schemas, so unknown settings are rejected. Native interface settings are documented in the [Hermes native interfaces guide](./hermes-interfaces.mdx#enable-native-interfaces). +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. 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 -Each runtime creates one embedded Hermes `AIAgent` and one `SessionDB`. Ordered SDK invocations reuse these objects and their conversation history until stop closes them. The Hermes home is stored under `/.fabric/hermes/runtimes/`; retaining files does not by itself establish cross-runtime conversation resume. +Each runtime creates one embedded Hermes `AIAgent` and one `SessionDB`. Ordered SDK invocations reuse these objects and their conversation history until stop closes them. The Hermes home is stored under `/.fabric/hermes/runtimes/`, or in the agent's state folder with `runtime.keep_state`; retaining files does not by itself establish cross-runtime conversation resume. SDK invocations return normalized NeMo Fabric `RunResult` objects. The adapter finalizes the Hermes Relay session and flushes subscribers before returning, so available ATOF/ATIF artifacts are complete at that invocation boundary. Native interface responses follow a different path, described in [What NeMo Fabric Normalizes](./hermes-interfaces.mdx#what-nemo-fabric-normalizes). 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/openclaw.mdx b/docs/integrations/harness/openclaw.mdx index 5f5589eed..b57005a22 100644 --- a/docs/integrations/harness/openclaw.mdx +++ b/docs/integrations/harness/openclaw.mdx @@ -94,6 +94,12 @@ 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, 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 OpenClaw's native `compat.supportsUsageInStreaming` and requires `base_url`. @@ -120,6 +126,44 @@ 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` 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. + 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/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 new file mode 100644 index 000000000..5bafe224c --- /dev/null +++ b/docs/integrations/harness/skills.mdx @@ -0,0 +1,41 @@ +--- +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 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. + +Relative entries resolve against the agent's base directory. NeMo Fabric does not expand `~` or environment variables such as `${VAR}`. + +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 + +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 | +| --- | --- | +| 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`. | +| 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}` | 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 9f6fee792..f1f8ca673 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. 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/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 259d53568..77166eb11 100644 --- a/docs/sdk/python.mdx +++ b/docs/sdk/python.mdx @@ -858,6 +858,27 @@ 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` 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. 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`; Hermes Agent's adapter +declares it. + ## Runtime Resource Snapshots `Runtime.resource_snapshot()` returns a timestamped `RuntimeResourceSnapshot` diff --git a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json index 0ceeda9e3..3c7231c7f 100644 --- a/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json +++ b/examples/harbor/swebench/adapters/hermes/hermes.fabric-adapter.json @@ -75,7 +75,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", @@ -130,6 +130,7 @@ "models.max_tokens", "instructions.system", "runtime.max_turns", + "runtime.keep_state", "tools.enabled", "tools.blocked", "mcp", 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/agent-config.schema.json b/schemas/adapter-contract/agent-config.schema.json index 193ea1206..c850cfe58 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. The adapters that ship with NeMo Fabric\nfollow this rule, except Deep Agents, which passes each entry to Deep\nAgents as a skill source.", "items": { "type": "string" }, 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..bb52069f7 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.", @@ -764,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. The adapters that ship with NeMo Fabric\nfollow this rule, except Deep Agents, which passes each entry to Deep\nAgents as a skill source.", "items": { "type": "string" }, @@ -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/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 a9c22f672..b8a669fff 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, @@ -972,7 +973,7 @@ "name": "nemo-fabric-adapters-hermes", "version": "0.7.0" }, - "sha256": "3370179a56673b6261c38653c42f049970eae696f9e88464c1757e8dc15348f0", + "sha256": "855ca764a2be962faa8ec02bca736d328e4db9142003b365d2dfa69a8bbfbdc3", "source": "adapters/python/hermes/hermes.fabric-adapter.json" }, "nvidia.fabric.kilo": { @@ -2056,6 +2057,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", @@ -2108,6 +2120,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. 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" + } + }, + "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, @@ -2161,7 +2201,7 @@ "name": "nemo-fabric-adapters-openclaw", "version": "0.7.0" }, - "sha256": "27af873589f481bd85f2e8e5fd32826879d5d1ba1dbdd1ff0c1e1d1298bb5be0", + "sha256": "f2420e753b7efff19d6c56a8ff00f428f07f2f0761d77f49a031e90aa7f3a057", "source": "adapters/python/openclaw/openclaw.fabric-adapter.json" }, "nvidia.fabric.opencode": { diff --git a/skills/nemo-fabric-build-adapter/SKILL.md b/skills/nemo-fabric-build-adapter/SKILL.md index 9dfc2389c..cee9fa826 100644 --- a/skills/nemo-fabric-build-adapter/SKILL.md +++ b/skills/nemo-fabric-build-adapter/SKILL.md @@ -117,11 +117,20 @@ 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. 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) + describes; Python adapters can resolve them with + `nemo_fabric_adapter_contract.skills.resolve_skills`, and TypeScript adapters + with `resolveSkills` from `nemo-fabric-adapter-contract/skills`. 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 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. 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/adapter_contract/test_skills.py b/tests/adapter_contract/test_skills.py new file mode 100644 index 000000000..6d4938dcb --- /dev/null +++ b/tests/adapter_contract/test_skills.py @@ -0,0 +1,207 @@ +# 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 collections.abc import Callable, Iterator +import os +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_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 / "SKILL.md").mkdir() + _skill(shared / "group" / "nested", "nested") + three = _skill(tmp_path / "mounted" / "three", "three") + (tmp_path / "empty").mkdir() + + 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]"), + Skill(name="three", path=three.resolve(), field="skills.paths[1]"), + ] + + +_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) + + +def _missing( + root: Path, _lock: Callable[[Path], Path] +) -> tuple[list[Path], tuple[Path, ...]]: + return [_skill(root / "review"), root / "missing"], (root / "missing",) + + +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",) + + +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(entries, tmp_path) + + assert caught.value.reason == reason + assert caught.value.field == "skills.paths[1]" + assert caught.value.paths == paths + assert "skills.paths[1]" in str(caught.value) + assert all(str(path) in str(caught.value) for path in paths) + + +@_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]") + ] + + +@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"), + ("--- \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"), + ], +) +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] + + +@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() + (tmp_path / "link").symlink_to(review, target_is_directory=True) + + assert resolve_skills(["shared/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]") + ] + + +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]"), + ] diff --git a/tests/adapters/test_claude_adapter.py b/tests/adapters/test_claude_adapter.py index ab57e5adb..7a5ac2079 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,22 @@ 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" diff --git a/tests/adapters/test_codex_adapter.py b/tests/adapters/test_codex_adapter.py index 1128414ce..1dd79c14a 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,33 @@ 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, + ) diff --git a/tests/adapters/test_hermes_adapter.py b/tests/adapters/test_hermes_adapter.py index 237e0f495..d03d73da5 100644 --- a/tests/adapters/test_hermes_adapter.py +++ b/tests/adapters/test_hermes_adapter.py @@ -203,6 +203,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", @@ -537,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": { @@ -575,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 == { @@ -592,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, @@ -620,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"] @@ -636,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"] @@ -707,10 +716,15 @@ 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", encoding="utf-8" + ) 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"] @@ -720,7 +734,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, @@ -773,6 +789,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"] == { @@ -1100,9 +1117,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 @@ -1121,6 +1140,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" @@ -1244,6 +1264,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( 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 67be36680..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}, ) @@ -483,6 +484,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() + + def test_hermes_disabled_interface_is_not_started(): settings = { "interfaces": { 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_openclaw.py b/tests/adapters/test_openclaw.py index 9aebfc320..1a25164aa 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,46 @@ 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" + ) + + +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" +@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 +219,48 @@ 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 +559,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() @@ -491,7 +571,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( @@ -503,8 +582,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( @@ -519,6 +596,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 ): @@ -1325,6 +1418,184 @@ 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 _start( + runtime, tmp_path, _dashboard_config(mock_openclaw, {"port": dashboard_port}) + ) + 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.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 _start( + runtime, + tmp_path, + _dashboard_config(mock_openclaw, {"port": dashboard_port, "enabled": False}), + ) + 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 _start( + runtime, + tmp_path, + _dashboard_config(mock_openclaw, {"port": dashboard_port}), + ) + + assert token_written == [True] + assert not token_path.exists() + 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 _start( + runtime, tmp_path, _dashboard_config(mock_openclaw, {"port": dashboard_port}) + ) + 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( + 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 _start( + runtime, + tmp_path, + _dashboard_config(mock_openclaw, {"port": dashboard_port}), + ) + + 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 _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 in {"darwin", "win32"}, reason="Starts the mock Gateway, which CI runs only on Linux", @@ -1507,12 +1778,15 @@ def signal_group(pid: int, signum: int) -> None: 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() @@ -1528,6 +1802,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() async def test_openclaw_startup_deadline_bounds_a_pending_readiness_request(): diff --git a/tests/adapters/test_openhands.py b/tests/adapters/test_openhands.py index a45eceab3..0f4625166 100644 --- a/tests/adapters/test_openhands.py +++ b/tests/adapters/test_openhands.py @@ -1094,3 +1094,53 @@ 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(), + ] + + +@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}]"} 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 20472ff62..a48d7d1df 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, @@ -23,6 +23,7 @@ ) from nemo_fabric import ( Fabric, + FabricRuntimeError, RelayAtofConfig, RelayAtofFileSinkConfig, RelayObservabilityConfig, @@ -279,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, @@ -300,6 +301,118 @@ 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"] == 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 not {"default", "alternate"}.intersection( + entry["name"] for entry in loaded["skills"] + ), loaded + else: + skill_dir = {"default": default_skill, "alternate": alternate_skill}[skill] + assert loaded["content"] == (skill_dir / "SKILL.md").read_text( + encoding="utf-8" + ), 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") +async def test_skill_folders( + code_review_agent_dir: Path, api_server: str, tmp_path: Path +): + """Verify Hermes lists each skill directly inside a folder, plus a separate skill.""" + shared = tmp_path / "shared" + _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": {}}}, + 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-") + } == {"fabric-one", "fabric-two", "fabric-three"} + + +@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") diff --git a/tests/e2e/test_openclaw_skills.py b/tests/e2e/test_openclaw_skills.py new file mode 100644 index 000000000..3f73ccf71 --- /dev/null +++ b/tests/e2e/test_openclaw_skills.py @@ -0,0 +1,161 @@ +# 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: + """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") + package = Path(configured).resolve() + manifest = json.loads((package / "package.json").read_text(encoding="utf-8")) + assert manifest["version"] in adapter.SUPPORTED_OPENCLAW_VERSIONS + return package + + +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(exist_ok=True) + config = AgentConfig.from_mapping( + { + "models": {"default": {"provider": "test", "model": "unused"}}, + "skills": {"paths": paths}, + } + ) + 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": {}, + } + ) + 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), encoding="utf-8") + 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=tmp_path / "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 + 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: + assert loaded == [_loaded(sources[skill], skill)] + + +def test_skill_folders_are_loaded_by_native_openclaw( + tmp_path: Path, openclaw_package: Path +): + """Load each skill directly inside a folder, mixed with a separate skill.""" + shared = tmp_path / "shared" + 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") + + entries = _load_natively(tmp_path, openclaw_package, [shared, separate]) + + 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): + """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