@oxygen-agent/cli 1.591.1 → 1.615.0

package/dist/skills.js

@@ -2,7 +2,7 @@ import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { dirname, join, resolve } from "node:path";
-import { OxygenError, toFailure } from "@oxygen/shared";
+import { OxygenError, inferCapabilityRoute, serializeCapabilityRoute, toFailure, } from "@oxygen/shared";
 import { defaultApiUrl, loadCredentials, normalizeApiUrl } from "./credentials.js";
 import { requestOxygen } from "./http-client.js";
 import { isRecord, readOption } from "./util.js";
@@ -86,6 +86,85 @@ export async function listAgentSkills(options, runtime = {}) {
         install_command_args: recommendedSkillsInstallArgs(apiUrl),
     };
 }
+export async function searchAgentSkills(query, options, runtime = {}) {
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
+    const index = await inspectSkillIndex(source.index_url, runtime.fetch);
+    if (!index.reachable) {
+        throw new OxygenError("skills_index_unreachable", "Oxygen skill index is not reachable.", {
+            details: { index_url: source.index_url, error: index.error },
+            exitCode: 1,
+        });
+    }
+    const normalized = query.trim();
+    const tokens = tokenizeSkillQuery(normalized);
+    const route = inferCapabilityRoute(normalized);
+    const requestedLimit = Number.parseInt(readOption(options.limit) ?? "5", 10);
+    const limit = Number.isFinite(requestedLimit) ? Math.min(10, Math.max(1, requestedLimit)) : 5;
+    const matches = index.skills
+        .map((skill) => ({
+        skill,
+        score: scoreSkill(skill, tokens, route?.card.skills ?? []),
+        matching_documents: matchingSkillDocuments(skill, tokens),
+    }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.skill.name.localeCompare(b.skill.name));
+    return {
+        query: normalized,
+        route: serializeCapabilityRoute(route),
+        total_matches: matches.length,
+        returned: Math.min(limit, matches.length),
+        skills: matches.slice(0, limit).map(({ skill, score, matching_documents }) => ({
+            name: skill.name,
+            title: skill.title,
+            description: skill.description,
+            dependencies: skill.dependencies,
+            capability_ids: skill.capability_ids,
+            endpoint_sections: skill.endpoint_sections,
+            score,
+            matching_documents: matching_documents.slice(0, 5),
+        })),
+        hydrate: "oxygen skills get <exact-skill-name> --json",
+    };
+}
+export async function getAgentSkill(skillName, options, runtime = {}) {
+    const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
+    const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
+    const index = await inspectSkillIndex(source.index_url, runtime.fetch);
+    if (!index.reachable) {
+        throw new OxygenError("skills_index_unreachable", "Oxygen skill index is not reachable.", {
+            details: { index_url: source.index_url, error: index.error },
+            exitCode: 1,
+        });
+    }
+    const normalized = skillName.trim();
+    const skill = index.skills.find((entry) => entry.name === normalized);
+    if (!skill) {
+        throw new OxygenError("skill_not_found", `Unknown Oxygen skill: ${normalized}`, {
+            details: { available_names: index.skill_names },
+            exitCode: 2,
+        });
+    }
+    if (!skill.entrypoint) {
+        throw new OxygenError("skill_entrypoint_missing", `Oxygen skill ${normalized} has no entrypoint.`, {
+            exitCode: 1,
+        });
+    }
+    const fetchImpl = runtime.fetch ?? fetch;
+    const response = await fetchImpl(skill.entrypoint, { headers: { Accept: "text/markdown" } });
+    if (!response.ok) {
+        throw new OxygenError("skill_entrypoint_unreachable", `Unable to hydrate Oxygen skill ${normalized}.`, {
+            details: { status: response.status },
+            exitCode: 1,
+        });
+    }
+    const content = await response.text();
+    return {
+        ...skill,
+        content,
+        install: `oxygen skills install --skill ${skill.name} --json`,
+    };
+}
 export async function doctorAgentSkills(options, runtime = {}) {
     const apiUrl = normalizeApiUrl(readOption(options.apiUrl) ?? defaultApiUrl());
     const source = await resolveSkillsInstallSource({ apiUrl, ...runtime });
@@ -547,6 +626,18 @@ function parseSkillIndex(value) {
                     .filter((dep) => typeof dep === "string" && dep.trim().length > 0)
                     .map((dep) => dep.trim())
                 : [],
+            capability_ids: readSkillIndexStrings(entry.capability_ids),
+            endpoint_sections: readSkillIndexStrings(entry.endpoint_sections),
+            documents: Array.isArray(entry.documents)
+                ? entry.documents
+                    .map(parseSkillIndexDocument)
+                    .filter((document) => document !== null)
+                : [],
+            files: Array.isArray(entry.files)
+                ? entry.files
+                    .filter((file) => typeof file === "string" && file.trim().length > 0)
+                    .map((file) => file.trim())
+                : [],
         };
     })
         .filter((entry) => entry !== null);
@@ -556,6 +647,114 @@ function parseSkillIndex(value) {
         skills,
     };
 }
+function parseSkillIndexDocument(value) {
+    if (!isRecord(value) || typeof value.path !== "string" || !value.path.trim())
+        return null;
+    const readStrings = (candidate) => Array.isArray(candidate)
+        ? candidate
+            .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+            .map((entry) => entry.trim())
+        : [];
+    return {
+        path: value.path.trim(),
+        kind: typeof value.kind === "string" ? value.kind : null,
+        title: typeof value.title === "string" ? value.title : null,
+        tags: readStrings(value.tags),
+        providers: readStrings(value.providers),
+        url: typeof value.url === "string" ? value.url : null,
+    };
+}
+function readSkillIndexStrings(candidate) {
+    return Array.isArray(candidate)
+        ? candidate
+            .filter((entry) => typeof entry === "string" && entry.trim().length > 0)
+            .map((entry) => entry.trim())
+        : [];
+}
+const SKILL_SEARCH_STOP_WORDS = new Set([
+    "a", "an", "and", "for", "from", "how", "i", "in", "is", "of", "on",
+    "or", "please", "the", "to", "want", "with",
+]);
+function tokenizeSkillQuery(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 0 && !SKILL_SEARCH_STOP_WORDS.has(token));
+}
+function skillSearchText(skill) {
+    return [
+        skill.name,
+        skill.title ?? "",
+        skill.description ?? "",
+        ...skill.capability_ids,
+        ...skill.endpoint_sections,
+        ...skill.documents.flatMap((document) => [
+            document.path,
+            document.title ?? "",
+            document.kind ?? "",
+            ...document.tags,
+            ...document.providers,
+        ]),
+    ].join(" ").toLowerCase();
+}
+function scoreSkill(skill, tokens, recommendedSkills) {
+    if (tokens.length === 0)
+        return 0;
+    const name = skill.name.toLowerCase();
+    const title = skill.title?.toLowerCase() ?? "";
+    const description = skill.description?.toLowerCase() ?? "";
+    const allText = skillSearchText(skill);
+    let score = 0;
+    let matched = 0;
+    for (const token of tokens) {
+        let tokenMatched = false;
+        if (name.includes(token)) {
+            score += 10;
+            tokenMatched = true;
+        }
+        if (title.includes(token)) {
+            score += 6;
+            tokenMatched = true;
+        }
+        if (description.includes(token)) {
+            score += 3;
+            tokenMatched = true;
+        }
+        if (allText.includes(token)) {
+            score += 1;
+            tokenMatched = true;
+        }
+        if (tokenMatched)
+            matched += 1;
+    }
+    if (matched > 0)
+        score += Math.round((matched / tokens.length) * 20);
+    const routeIndex = recommendedSkills.indexOf(skill.name);
+    if (routeIndex >= 0)
+        score += 400 - (routeIndex * 20);
+    return score;
+}
+function matchingSkillDocuments(skill, tokens) {
+    if (tokens.length === 0)
+        return [];
+    return skill.documents
+        .map((document) => ({
+        document,
+        score: tokens.reduce((total, token) => {
+            const text = [
+                document.path,
+                document.title ?? "",
+                document.kind ?? "",
+                ...document.tags,
+                ...document.providers,
+            ].join(" ").toLowerCase();
+            return total + (text.includes(token) ? 1 : 0);
+        }, 0),
+    }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.document.path.localeCompare(b.document.path))
+        .map((entry) => entry.document);
+}
 function inspectSkillsInstaller() {
     const invocation = resolveCmdShimInvocation("npx", ["--version"], process.platform, process.env);
     const result = spawnSync(invocation.executable, invocation.args, {

package/node_modules/@oxygen/shared/dist/capability-discovery.d.ts

@@ -0,0 +1,36 @@
+import { type RecipePrimitive } from "./recipes.js";
+export type CapabilityLayer = "Control" | "Knowledge" | "Data" | "Action" | "External";
+export type CapabilityPosture = "read_only" | "workspace_write" | "paid_read" | "external_write" | "mixed";
+export type CapabilityRouteCard = {
+    id: string;
+    layer: CapabilityLayer;
+    primitive: RecipePrimitive | null;
+    owns: string;
+    notFor: string;
+    execution: string;
+    posture: CapabilityPosture;
+    gatewayTools: readonly string[];
+    gatewayCommands: readonly string[];
+    skills: readonly string[];
+    endpointSections: readonly string[];
+    intentTerms: readonly string[];
+    negativeTerms?: readonly string[];
+};
+export type PrimitiveRouteCard = CapabilityRouteCard & {
+    primitive: RecipePrimitive;
+};
+export type CapabilityRouteMatch = {
+    card: CapabilityRouteCard;
+    recommendedTools: string[];
+    recommendedCommands: string[];
+};
+export type PrimitiveRouteMatch = CapabilityRouteMatch & {
+    card: PrimitiveRouteCard;
+};
+export declare const OXYGEN_CAPABILITY_ROUTES: readonly CapabilityRouteCard[];
+export declare const OXYGEN_PRIMITIVE_ROUTES: readonly PrimitiveRouteCard[];
+export declare function getCapabilityRoute(id: string): CapabilityRouteCard | null;
+export declare function getCapabilityRouteMatch(id: string): CapabilityRouteMatch | null;
+export declare function inferCapabilityRoute(query: string): CapabilityRouteMatch | null;
+export declare function inferPrimitiveRoute(query: string): PrimitiveRouteMatch | null;
+export declare function serializeCapabilityRoute(route: CapabilityRouteMatch | null): Record<string, unknown> | null;