@oxygen-agent/cli 1.591.1 → 1.615.0

package/README.md

@@ -34,4 +34,4 @@ oxygen update
 
 For product documentation, visit https://oxygen-agent.com/docs. For support, visit https://oxygen-agent.com.
 
-Version: 1.591.1
+Version: 1.615.0

package/dist/command-manifest.d.ts

@@ -17,6 +17,7 @@ export type CommandManifestEntry = {
     flags: CommandManifestFlag[];
     spends_credits: boolean;
     mutates: boolean;
+    preview_by_default: boolean;
     json_supported: boolean;
     hidden: boolean;
 };
@@ -27,4 +28,21 @@ export type CommandManifest = {
     exit_codes: Record<string, string>;
     commands: CommandManifestEntry[];
 };
+export type CommandSearchResult = {
+    query: string;
+    total_matches: number;
+    returned: number;
+    route: Record<string, unknown> | null;
+    commands: Array<Pick<CommandManifestEntry, "name" | "group" | "description" | "spends_credits" | "mutates" | "json_supported" | "hidden"> & {
+        score: number;
+    }>;
+    hydrate: string;
+};
 export declare function buildCommandManifest(program: Command, binaryName: string): CommandManifest;
+/** Bounded natural-language projection over the complete local manifest. */
+export declare function searchCommandManifest(manifest: CommandManifest, query: string, requestedLimit?: number): CommandSearchResult;
+/** Exact second hop after search; avoids serializing the full command grammar. */
+export declare function getCommandManifestEntry(manifest: CommandManifest, exactName: string): (CommandManifestEntry & {
+    invoke: string;
+}) | null;
+export declare function suggestCommandNames(manifest: CommandManifest, query: string, limit?: number): string[];

package/dist/command-manifest.js

@@ -1,4 +1,10 @@
-import { CLI_EXIT_CODE_TABLE, OXYGEN_VERSION } from "@oxygen/shared";
+import { CLI_EXIT_CODE_TABLE, OXYGEN_VERSION, inferCapabilityRoute, serializeCapabilityRoute, } from "@oxygen/shared";
+const DEFAULT_COMMAND_SEARCH_LIMIT = 10;
+const MAX_COMMAND_SEARCH_LIMIT = 25;
+const COMMAND_SEARCH_STOP_WORDS = new Set([
+    "a", "an", "and", "for", "from", "get", "i", "in", "into", "is", "me",
+    "of", "on", "or", "please", "show", "the", "to", "want", "with",
+]);
 // Leaf verbs (or their hyphen-prefix) that name a state mutation, external
 // write, or paid side effect. `mutates` is derived from this set (see
 // toManifestEntry). It is hand-curated and cross-checked against the real leaf
@@ -47,14 +53,108 @@ export function buildCommandManifest(program, binaryName) {
         commands,
     };
 }
+/** Bounded natural-language projection over the complete local manifest. */
+export function searchCommandManifest(manifest, query, requestedLimit = DEFAULT_COMMAND_SEARCH_LIMIT) {
+    const normalized = query.trim();
+    const tokens = tokenizeCommandQuery(normalized);
+    const route = inferCapabilityRoute(normalized);
+    const limit = Math.min(MAX_COMMAND_SEARCH_LIMIT, Math.max(1, Math.floor(requestedLimit)));
+    const matches = tokens.length === 0
+        ? []
+        : manifest.commands
+            .map((command) => ({ command, score: scoreCommand(command, tokens, route) }))
+            .filter((entry) => entry.score > 0)
+            .sort((a, b) => b.score - a.score || a.command.name.localeCompare(b.command.name));
+    return {
+        query: normalized,
+        total_matches: matches.length,
+        returned: Math.min(limit, matches.length),
+        route: serializeCapabilityRoute(route),
+        commands: matches.slice(0, limit).map(({ command, score }) => ({
+            name: command.name,
+            group: command.group,
+            description: command.description,
+            spends_credits: command.spends_credits,
+            mutates: command.mutates,
+            json_supported: command.json_supported,
+            hidden: command.hidden,
+            score,
+        })),
+        hydrate: `${manifest.binary} commands get <exact-command> --json`,
+    };
+}
+/** Exact second hop after search; avoids serializing the full command grammar. */
+export function getCommandManifestEntry(manifest, exactName) {
+    const normalized = exactName.trim().replace(/\s+/g, " ");
+    const command = manifest.commands.find((entry) => entry.name === normalized);
+    return command ? { ...command, invoke: `${manifest.binary} ${command.name}` } : null;
+}
+export function suggestCommandNames(manifest, query, limit = 3) {
+    const tokens = tokenizeCommandQuery(query);
+    return manifest.commands
+        .map((command) => ({ command, score: scoreCommand(command, tokens, null) }))
+        .filter((entry) => entry.score > 0)
+        .sort((a, b) => b.score - a.score || a.command.name.localeCompare(b.command.name))
+        .slice(0, Math.max(1, limit))
+        .map((entry) => entry.command.name);
+}
+function tokenizeCommandQuery(query) {
+    return query
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((token) => token.length > 0 && !COMMAND_SEARCH_STOP_WORDS.has(token));
+}
+function scoreCommand(command, tokens, route) {
+    const name = command.name.toLowerCase();
+    const description = command.description.toLowerCase();
+    const searchableDetails = [
+        ...command.arguments.map((argument) => `${argument.name} ${argument.description}`),
+        ...command.flags.map((flag) => `${flag.flags} ${flag.description}`),
+    ].join(" ").toLowerCase();
+    let score = 0;
+    let matched = 0;
+    for (const token of tokens) {
+        let tokenMatched = false;
+        if (name.includes(token)) {
+            score += 8;
+            tokenMatched = true;
+        }
+        if (description.includes(token)) {
+            score += 3;
+            tokenMatched = true;
+        }
+        if (searchableDetails.includes(token)) {
+            score += 1;
+            tokenMatched = true;
+        }
+        if (tokenMatched)
+            matched += 1;
+    }
+    const routeIndex = route?.recommendedCommands.findIndex((recommended) => name === recommended || name.startsWith(`${recommended} `)) ?? -1;
+    const routeGroups = new Set([
+        ...(route?.card.endpointSections ?? []),
+        ...(route?.card.gatewayCommands ?? []).map((recommended) => recommended.split(" ")[0] ?? ""),
+        ...(route?.recommendedCommands ?? []).map((recommended) => recommended.split(" ")[0] ?? ""),
+    ]);
+    if (route && routeIndex < 0 && !routeGroups.has(command.group))
+        return 0;
+    if (routeIndex < 0 && matched < Math.ceil(tokens.length / 2))
+        return 0;
+    if (tokens.length > 0 && matched > 0)
+        score += Math.round((matched / tokens.length) * 20);
+    if (routeIndex >= 0)
+        score += 500 - (routeIndex * 25);
+    return score;
+}
 function collectCommand(command, ancestors, out) {
     const path = [...ancestors, command.name()];
     const children = command.commands;
-    // Group commands (e.g. `oxygen tables`) exist to hold subcommands; only leaf
-    // commands are invocable work, so only leaves become manifest entries.
-    if (children.length === 0) {
+    // Most group commands only hold children. A small number (notably the
+    // backwards-compatible `commands` index) also have their own action, so
+    // preserve them as invocable entries while still walking their children.
+    const hasAction = Boolean(command._actionHandler);
+    if (children.length === 0 || hasAction) {
         out.push(toManifestEntry(command, path));
-        return;
     }
     for (const child of children) {
         collectCommand(child, path, out);
@@ -92,6 +192,7 @@ function toManifestEntry(command, path) {
             (path[0] === "copilot" &&
                 (leafVerb === "send" || leafVerb === "approve")),
         mutates: MUTATING_VERBS.has(leafVerb) || MUTATING_VERBS.has(verbPrefix),
+        preview_by_default: flagStrings.some((flags) => flags.includes("--live")),
         json_supported: flagStrings.some((flags) => flags.includes("--json")),
         hidden: isHiddenCommand(command),
     };

package/dist/help.js

@@ -136,7 +136,8 @@ export function applyOxygenHelp(program, binaryName) {
         // OXYGEN_API_KEY never runs it — without this step nothing on any
         // first-touch surface names the skill that teaches the GTM loops.
         `  2. ${binaryName} skills install --json      load the skills that teach the GTM loops (automatic after login)`,
-        `  3. ${binaryName} commands --json            full machine-readable command grammar (this CLI's self-index)`,
+        `  3. ${binaryName} context resolve --json     load workspace context before operating primitives`,
+        `  4. ${binaryName} capabilities search "<goal>" --json   route the goal, then hydrate one exact command`,
         `  Recurring monitors: use a shareable Blueprint; start with ${binaryName} blueprints list --json.`,
         "",
         "Conventions:",