@salesforce/sfdx-agent-harness-openai 0.0.1 → 0.2.0

package/dist/skill-loader.d.ts

@@ -0,0 +1,76 @@
+import { type LogBus } from '@salesforce/agentic-common';
+/**
+ * One discovered skill: the absolute path to its `SKILL.md` and the description
+ * string the loader surfaces to the model in the `load_skill` tool catalog. The
+ * frontmatter `name` (or the skill folder basename, if the frontmatter is
+ * missing) is the key in the {@link SkillMap}; this struct holds the rest.
+ */
+export type SkillEntry = {
+    /** Absolute path to the resolved `SKILL.md` file. */
+    path: string;
+    /**
+     * Skill description from the YAML frontmatter `description:` field, trimmed.
+     * Empty string when the frontmatter omits `description:`. Surfaced verbatim
+     * in the `load_skill` tool description so the model can pick the right skill
+     * without reading the body.
+     */
+    description: string;
+};
+/**
+ * Discovered skill catalog: skill name → entry. The name is what the model
+ * passes back when it invokes `load_skill({ skill })`.
+ */
+export type SkillMap = Map<string, SkillEntry>;
+/**
+ * Resolve `config.skills` paths into a `Map<skillName, SkillEntry>`. Each entry
+ * in `skillPaths` may be:
+ *
+ * - A `SKILL.md` file path → one skill (named from frontmatter or parent folder
+ *   basename).
+ * - A folder containing `SKILL.md` → one skill.
+ * - A parent folder containing one or more skill subfolders, each with its own
+ *   `SKILL.md` → many skills. Subfolders without a `SKILL.md` are silently
+ *   skipped so consumers can drop arbitrary subdirectories into their skill
+ *   roots without breaking the loader.
+ *
+ * Each entry is resolved against `projectRoot` (via `path.resolve`) before it is
+ * `stat`ed, per the SDK `AgentConfig.skills` contract — relative entries resolve
+ * against the project root, absolute entries pass through unchanged. The
+ * resulting `SkillEntry.path` is therefore always absolute, which the
+ * `read_skill_file` sibling reader and the `<skill-location>` anchor both rely
+ * on.
+ *
+ * Mirrors `composeRulesAppend`'s contract for path validation: a configured
+ * entry that does not exist or that the harness cannot `stat` rejects
+ * `createAgent`, matching the rules-loader behavior so a typo in `config.skills`
+ * fails loud at registration time rather than silently dropping the skill at
+ * every turn.
+ *
+ * Skill name resolution: the frontmatter `name:` field wins; if it is missing or
+ * empty the parent-folder basename is used. When two configured paths resolve to
+ * the same name, **first writer wins** — the second entry is dropped.
+ *
+ * Frontmatter `description:` is captured verbatim (trimmed) and stored for the
+ * `load_skill` tool to surface in its description. When absent, the entry's
+ * `description` is the empty string.
+ *
+ * Frontmatter parsing is intentionally regex-based, not full YAML —
+ * `splitFrontmatterAndBody` from `@salesforce/agentic-common` already keeps the
+ * parser dependency-free, and the only fields this loader needs are `name` and
+ * `description`.
+ *
+ * A deliberate copy of the Claude harness's `skill-loader.ts`: a cross-harness
+ * import is lint-blocked by `harnessIsolationPack`, so the behavior is
+ * duplicated on purpose and drift-guarded by the shared
+ * `@salesforce/harness-conformance` `SKILL_LOADER_FIXTURES` table (the same
+ * posture as `rule-composer.ts` / `mcp-error-classifier.ts`).
+ */
+export declare function buildSkillMap(skillPaths: readonly string[] | undefined, projectRoot: string, logBus?: LogBus): Promise<SkillMap>;
+/**
+ * The unique set of skill directories in a {@link SkillMap} — each is the parent
+ * directory of a resolved `SKILL.md` (deduplicated, stable order). The
+ * `read_skill_file` tool scopes each read to one of these directories so a
+ * skill's relative reference (`references/...`, `assets/...`) resolves to a
+ * file inside its own skill folder and nothing else on disk is reachable.
+ */
+export declare function skillDirectories(skillMap: SkillMap): string[];

package/dist/skill-loader.js

@@ -0,0 +1,180 @@
+/*
+ * Copyright 2026, Salesforce, Inc. All rights reserved.
+ * See LICENSE.txt for license terms.
+ */
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { getErrorMessage, splitFrontmatterAndBody } from '@salesforce/agentic-common';
+const SKILL_FILE_NAME = 'SKILL.md';
+const FRONTMATTER_NAME_RE = /^name:\s*(.+?)\s*$/m;
+const FRONTMATTER_DESCRIPTION_RE = /^description:\s*(.+?)\s*$/m;
+/**
+ * Resolve `config.skills` paths into a `Map<skillName, SkillEntry>`. Each entry
+ * in `skillPaths` may be:
+ *
+ * - A `SKILL.md` file path → one skill (named from frontmatter or parent folder
+ *   basename).
+ * - A folder containing `SKILL.md` → one skill.
+ * - A parent folder containing one or more skill subfolders, each with its own
+ *   `SKILL.md` → many skills. Subfolders without a `SKILL.md` are silently
+ *   skipped so consumers can drop arbitrary subdirectories into their skill
+ *   roots without breaking the loader.
+ *
+ * Each entry is resolved against `projectRoot` (via `path.resolve`) before it is
+ * `stat`ed, per the SDK `AgentConfig.skills` contract — relative entries resolve
+ * against the project root, absolute entries pass through unchanged. The
+ * resulting `SkillEntry.path` is therefore always absolute, which the
+ * `read_skill_file` sibling reader and the `<skill-location>` anchor both rely
+ * on.
+ *
+ * Mirrors `composeRulesAppend`'s contract for path validation: a configured
+ * entry that does not exist or that the harness cannot `stat` rejects
+ * `createAgent`, matching the rules-loader behavior so a typo in `config.skills`
+ * fails loud at registration time rather than silently dropping the skill at
+ * every turn.
+ *
+ * Skill name resolution: the frontmatter `name:` field wins; if it is missing or
+ * empty the parent-folder basename is used. When two configured paths resolve to
+ * the same name, **first writer wins** — the second entry is dropped.
+ *
+ * Frontmatter `description:` is captured verbatim (trimmed) and stored for the
+ * `load_skill` tool to surface in its description. When absent, the entry's
+ * `description` is the empty string.
+ *
+ * Frontmatter parsing is intentionally regex-based, not full YAML —
+ * `splitFrontmatterAndBody` from `@salesforce/agentic-common` already keeps the
+ * parser dependency-free, and the only fields this loader needs are `name` and
+ * `description`.
+ *
+ * A deliberate copy of the Claude harness's `skill-loader.ts`: a cross-harness
+ * import is lint-blocked by `harnessIsolationPack`, so the behavior is
+ * duplicated on purpose and drift-guarded by the shared
+ * `@salesforce/harness-conformance` `SKILL_LOADER_FIXTURES` table (the same
+ * posture as `rule-composer.ts` / `mcp-error-classifier.ts`).
+ */
+export async function buildSkillMap(skillPaths, projectRoot, logBus) {
+    const map = new Map();
+    if (!skillPaths || skillPaths.length === 0)
+        return map;
+    for (const entry of skillPaths) {
+        // Resolve relative entries against the project root per the SDK
+        // `AgentConfig.skills` contract; an absolute entry is returned unchanged.
+        // This is what makes `SkillEntry.path` (and therefore the sibling-file
+        // reader + the `<skill-location>` anchor) absolute, as their contracts
+        // require — without it a relative entry would resolve against the host
+        // process cwd, which is not the project root.
+        const resolved = path.resolve(projectRoot, entry);
+        let stats;
+        try {
+            stats = await fs.stat(resolved);
+        }
+        catch (err) {
+            throw new Error(`Failed to load skills from "${entry}": ${getErrorMessage(err)}`, { cause: err });
+        }
+        if (stats.isFile()) {
+            if (path.basename(resolved) !== SKILL_FILE_NAME)
+                continue;
+            await ingestSkillFile(resolved, map, logBus);
+            continue;
+        }
+        if (!stats.isDirectory())
+            continue;
+        // Single-skill folder containing SKILL.md?
+        const candidate = path.join(resolved, SKILL_FILE_NAME);
+        if (await isFile(candidate)) {
+            await ingestSkillFile(candidate, map, logBus);
+            continue;
+        }
+        // Parent folder: enumerate immediate subdirectories.
+        let children;
+        try {
+            children = await fs.readdir(resolved, { withFileTypes: true });
+        }
+        catch (err) {
+            throw new Error(`Failed to load skills from "${entry}": ${getErrorMessage(err)}`, { cause: err });
+        }
+        for (const child of children) {
+            if (!child.isDirectory())
+                continue;
+            const childSkillMd = path.join(resolved, child.name, SKILL_FILE_NAME);
+            if (!(await isFile(childSkillMd)))
+                continue;
+            await ingestSkillFile(childSkillMd, map, logBus);
+        }
+    }
+    return map;
+}
+/**
+ * The unique set of skill directories in a {@link SkillMap} — each is the parent
+ * directory of a resolved `SKILL.md` (deduplicated, stable order). The
+ * `read_skill_file` tool scopes each read to one of these directories so a
+ * skill's relative reference (`references/...`, `assets/...`) resolves to a
+ * file inside its own skill folder and nothing else on disk is reachable.
+ */
+export function skillDirectories(skillMap) {
+    const dirs = new Set();
+    for (const entry of skillMap.values()) {
+        dirs.add(path.dirname(entry.path));
+    }
+    return [...dirs];
+}
+async function ingestSkillFile(skillMdPath, map, logBus) {
+    let raw;
+    try {
+        raw = await fs.readFile(skillMdPath, 'utf8');
+    }
+    catch (err) {
+        throw new Error(`Failed to read skill file "${skillMdPath}": ${getErrorMessage(err)}`, { cause: err });
+    }
+    const { frontmatter } = splitFrontmatterAndBody(raw);
+    const fm = frontmatter ?? '';
+    const name = readField(fm, FRONTMATTER_NAME_RE) ?? path.basename(path.dirname(skillMdPath));
+    const description = readField(fm, FRONTMATTER_DESCRIPTION_RE) ?? '';
+    if (!name)
+        return;
+    if (map.has(name)) {
+        // First-writer-wins by design (consumers can layer skill folders), but
+        // warn so the silent shadow doesn't burn debugging time.
+        const winner = map.get(name);
+        logBus?.warn(`Skill name "${name}" already loaded; ignoring duplicate at "${skillMdPath}".`, {
+            skillName: name,
+            keptPath: winner.path,
+            ignoredPath: skillMdPath,
+        });
+        return;
+    }
+    map.set(name, { path: skillMdPath, description });
+}
+function readField(frontmatter, re) {
+    const match = re.exec(frontmatter);
+    if (!match?.[1])
+        return undefined;
+    const trimmed = match[1].trim();
+    if (trimmed.length === 0)
+        return undefined;
+    // Strip a single matched pair of YAML scalar quotes (`"..."` or `'...'`).
+    // YAML allows quoting frontmatter scalars to escape colons, leading
+    // whitespace, etc. A regex-based reader (kept for the no-YAML-runtime
+    // stance) would otherwise capture the quotes verbatim — the resulting
+    // `name:` key would include them and the model's `load_skill({ skill })`
+    // call would miss the catalog entry. Keeps the cross-harness contract on the
+    // same observable shape as Mastra's full YAML parser.
+    if (trimmed.length >= 2) {
+        const first = trimmed.charAt(0);
+        const last = trimmed.charAt(trimmed.length - 1);
+        if ((first === '"' || first === "'") && first === last) {
+            return trimmed.slice(1, -1);
+        }
+    }
+    return trimmed;
+}
+async function isFile(p) {
+    try {
+        const s = await fs.stat(p);
+        return s.isFile();
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=skill-loader.js.map

package/dist/skill-loader.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-loader.js","sourceRoot":"","sources":["../src/skill-loader.ts"],"names":[],"mappings":"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"}