@enactprotocol/shared 2.2.4 → 2.3.4

package/src/resolver.ts

@@ -4,19 +4,21 @@
  * Resolution order:
  * 1. Direct file path (if provided path exists)
  * 2. Project tools (.enact/tools/{name}/)
- * 3. Global tools (via ~/.enact/tools.json → cache)
- * 4. Cache (~/.enact/cache/{name}/{version}/)
+ * 3. Global tools (via ~/.enact/tools.json → ~/.agent/skills/)
+ * 4. Skills directory (~/.agent/skills/{name}/)
  */
 
-import { existsSync, readdirSync } from "node:fs";
+import { existsSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import {
   type LoadManifestOptions,
   ManifestLoadError,
   findManifestFile,
   loadManifest,
+  loadManifestFromDir,
 } from "./manifest/loader";
-import { getCacheDir, getProjectEnactDir } from "./paths";
+import { manifestScriptsToActionsManifest } from "./manifest/scripts";
+import { getProjectEnactDir, getSkillsDir } from "./paths";
 import { getInstalledVersion, getToolCachePath, resolveAlias } from "./registry";
 import type { ToolLocation, ToolResolution } from "./types/manifest";
 
@@ -66,13 +68,70 @@ export interface ResolveOptions {
   skipCache?: boolean;
 }
 
+/**
+ * Result of parsing an action specifier
+ */
+export interface ParsedActionSpecifier {
+  /** The skill name (e.g., "owner/skill" from "owner/skill:action") */
+  skillName: string;
+  /** The action name (e.g., "action" from "owner/skill:action"), or undefined if not specified */
+  actionName?: string;
+}
+
+/**
+ * Parse an action specifier into skill name and action name
+ *
+ * Specifier formats (uses colon separator):
+ * - "owner/skill" - skill only, no action
+ * - "owner/skill:action" - skill with action
+ * - "./path" or "/path" - file path (no action parsing)
+ * - "./path:action" - file path with action
+ *
+ * Examples:
+ * - "mendable/firecrawl" → skill="mendable/firecrawl", action=undefined
+ * - "mendable/firecrawl:scrape" → skill="mendable/firecrawl", action="scrape"
+ * - "acme/tools/greeter:hello" → skill="acme/tools/greeter", action="hello"
+ * - "/tmp/skill" → skill="/tmp/skill", action=undefined (file path)
+ * - "./skill:hello" → skill="./skill", action="hello" (file path with action)
+ *
+ * @param specifier - The tool/action specifier string
+ * @returns Parsed skill name and optional action name
+ */
+export function parseActionSpecifier(specifier: string): ParsedActionSpecifier {
+  const normalized = specifier.replace(/\\/g, "/").trim();
+
+  // Check for colon separator (action specifier)
+  const colonIndex = normalized.lastIndexOf(":");
+
+  // No colon - just a skill name or file path
+  if (colonIndex === -1) {
+    return { skillName: normalized };
+  }
+
+  // Windows drive letter check (e.g., "C:/path")
+  // If colon is at index 1 and followed by /, it's a Windows path
+  if (colonIndex === 1 && normalized.length > 2 && normalized[2] === "/") {
+    return { skillName: normalized };
+  }
+
+  // Split on colon
+  const skillName = normalized.slice(0, colonIndex);
+  const actionName = normalized.slice(colonIndex + 1);
+
+  // Validate action name is non-empty
+  if (!actionName || actionName.length === 0) {
+    return { skillName: normalized };
+  }
+
+  return { skillName, actionName };
+}
+
 /**
  * Convert tool name to directory path
- * e.g., "acme/utils/greeter" -> "acme/utils/greeter"
+ * Strips the @ prefix for disk paths: "@org/my-skill" -> "org/my-skill"
  */
 export function toolNameToPath(name: string): string {
-  // Tool names are already path-like, just normalize
-  return name.replace(/\\/g, "/");
+  return name.replace(/^@/, "").replace(/\\/g, "/");
 }
 
 /**
@@ -92,6 +151,8 @@ export function getToolPath(toolsDir: string, toolName: string): string {
 /**
  * Try to load a tool from a specific directory
  *
+ * Supports two-file model (skill.yaml + SKILL.md) via loadManifestFromDir().
+ *
  * @param dir - Directory to check
  * @param location - The location type for metadata
  * @param options - Options for loading the manifest
@@ -106,22 +167,26 @@ function tryLoadFromDir(
     return null;
   }
 
-  const manifestPath = findManifestFile(dir);
-  if (!manifestPath) {
-    return null;
-  }
-
   try {
-    const loaded = loadManifest(manifestPath, options);
-    return {
+    const loaded = loadManifestFromDir(dir, options);
+
+    const resolution: ToolResolution = {
       manifest: loaded.manifest,
       sourceDir: dir,
       location,
-      manifestPath,
+      manifestPath: loaded.filePath,
       version: loaded.manifest.version,
     };
+
+    // Convert inline scripts to actionsManifest
+    const scriptsManifest = manifestScriptsToActionsManifest(loaded.manifest);
+    if (scriptsManifest) {
+      resolution.actionsManifest = scriptsManifest;
+    }
+
+    return resolution;
   } catch {
-    // Invalid manifest, skip
+    // No manifest or invalid manifest, skip
     return null;
   }
 }
@@ -153,13 +218,23 @@ export function resolveToolFromPath(filePath: string): ToolResolution {
     }
 
     const loaded = loadManifest(absolutePath, localOptions);
-    return {
+    const sourceDir = dirname(absolutePath);
+
+    const resolution: ToolResolution = {
       manifest: loaded.manifest,
-      sourceDir: dirname(absolutePath),
+      sourceDir,
       location: "file",
       manifestPath: absolutePath,
       version: loaded.manifest.version,
     };
+
+    // Convert inline scripts to actionsManifest
+    const scriptsManifest = manifestScriptsToActionsManifest(loaded.manifest);
+    if (scriptsManifest) {
+      resolution.actionsManifest = scriptsManifest;
+    }
+
+    return resolution;
   }
 
   // Treat as directory
@@ -171,10 +246,76 @@ export function resolveToolFromPath(filePath: string): ToolResolution {
   throw new ToolResolveError(`No manifest found at: ${absolutePath}`, filePath);
 }
 
+/**
+ * Resolve a specific action from a tool/skill
+ *
+ * @param resolution - Already resolved tool
+ * @param actionName - Name of the action to resolve
+ * @returns ToolResolution with action field populated
+ * @throws ToolResolveError if action not found
+ */
+export function resolveAction(resolution: ToolResolution, actionName: string): ToolResolution {
+  // Check if the skill has actions (from scripts or ACTIONS.yaml)
+  if (!resolution.actionsManifest) {
+    throw new ToolResolveError(
+      `Skill "${resolution.manifest.name}" does not define any scripts or actions. ` +
+        `Cannot resolve "${actionName}".`,
+      `${resolution.manifest.name}:${actionName}`
+    );
+  }
+
+  // Find the script/action (map lookup)
+  const action = resolution.actionsManifest.actions[actionName];
+  if (!action) {
+    const availableActions = Object.keys(resolution.actionsManifest.actions);
+    throw new ToolResolveError(
+      `Action "${actionName}" not found in skill "${resolution.manifest.name}". ` +
+        `Available actions: ${availableActions.join(", ")}`,
+      `${resolution.manifest.name}:${actionName}`
+    );
+  }
+
+  return {
+    ...resolution,
+    action,
+    actionName,
+  };
+}
+
+/**
+ * Resolve a tool with optional action specifier
+ *
+ * Supports formats:
+ * - "owner/skill" - resolves skill only
+ * - "owner/skill:action" - resolves skill and specific action
+ *
+ * @param specifier - Tool/action specifier (e.g., "mendable/firecrawl:scrape")
+ * @param options - Resolution options
+ * @returns ToolResolution with action populated if specified
+ * @throws ToolResolveError if not found
+ */
+export function resolveToolWithAction(
+  specifier: string,
+  options: ResolveOptions = {}
+): ToolResolution {
+  const { skillName, actionName } = parseActionSpecifier(specifier);
+
+  // Resolve the skill first
+  const resolution = resolveTool(skillName, options);
+
+  // If no action specified, return as-is
+  if (!actionName) {
+    return resolution;
+  }
+
+  // Resolve the action
+  return resolveAction(resolution, actionName);
+}
+
 /**
  * Resolve a tool by name, searching through standard locations
  *
- * @param toolName - Tool name (e.g., "acme/utils/greeter") or alias (e.g., "firebase")
+ * @param toolName - Tool name (e.g., "acme/greeter" or "@acme/greeter") or alias (e.g., "firebase")
  * @param options - Resolution options
  * @returns ToolResolution
  * @throws ToolResolveError if not found
@@ -209,48 +350,29 @@ export function resolveTool(toolName: string, options: ResolveOptions = {}): Too
     }
   }
 
-  // 2. Try global tools (via ~/.enact/tools.json → cache)
+  // 2. Try global tools (via ~/.enact/tools.json → ~/.agent/skills/)
   if (!options.skipUser) {
     const globalVersion = getInstalledVersion(normalizedName, "global");
     if (globalVersion) {
-      const cachePath = getToolCachePath(normalizedName, globalVersion);
-      searchedLocations.push(cachePath);
+      const skillPath = getToolCachePath(normalizedName, globalVersion);
+      searchedLocations.push(skillPath);
 
-      const result = tryLoadFromDir(cachePath, "user");
+      const result = tryLoadFromDir(skillPath, "user");
       if (result) {
         return result;
       }
     }
   }
 
-  // 3. Try cache (with optional version)
+  // 3. Try skills directory (~/.agent/skills/{name}/)
   if (!options.skipCache) {
-    const cacheDir = getCacheDir();
-    const toolCacheBase = getToolPath(cacheDir, normalizedName);
+    const skillsDir = getSkillsDir();
+    const skillDir = getToolPath(skillsDir, normalizedName);
+    searchedLocations.push(skillDir);
 
-    if (options.version) {
-      // Look for specific version
-      const versionDir = join(toolCacheBase, `v${options.version.replace(/^v/, "")}`);
-      searchedLocations.push(versionDir);
-
-      const result = tryLoadFromDir(versionDir, "cache");
-      if (result) {
-        return result;
-      }
-    } else {
-      // Look for latest cached version
-      if (existsSync(toolCacheBase)) {
-        const latestVersion = findLatestCachedVersion(toolCacheBase);
-        if (latestVersion) {
-          const versionDir = join(toolCacheBase, latestVersion);
-          searchedLocations.push(versionDir);
-
-          const result = tryLoadFromDir(versionDir, "cache");
-          if (result) {
-            return result;
-          }
-        }
-      }
+    const result = tryLoadFromDir(skillDir, "cache");
+    if (result) {
+      return result;
     }
   }
 
@@ -261,33 +383,6 @@ export function resolveTool(toolName: string, options: ResolveOptions = {}): Too
   );
 }
 
-/**
- * Find the latest cached version directory
- */
-function findLatestCachedVersion(toolCacheBase: string): string | null {
-  try {
-    const entries = readdirSync(toolCacheBase, { withFileTypes: true });
-    const versions = entries
-      .filter((e) => e.isDirectory() && e.name.startsWith("v"))
-      .map((e) => e.name)
-      .sort((a, b) => {
-        // Sort by semver (v1.0.0 format)
-        const aVer = a.slice(1).split(".").map(Number);
-        const bVer = b.slice(1).split(".").map(Number);
-        for (let i = 0; i < 3; i++) {
-          if ((aVer[i] ?? 0) !== (bVer[i] ?? 0)) {
-            return (bVer[i] ?? 0) - (aVer[i] ?? 0);
-          }
-        }
-        return 0;
-      });
-
-    return versions[0] ?? null;
-  } catch {
-    return null;
-  }
-}
-
 /**
  * Try to resolve a tool, returning null instead of throwing
  *
@@ -483,7 +578,7 @@ export function getToolSearchPaths(toolName: string, options: ResolveOptions = {
 
   // Cache
   if (!options.skipCache) {
-    const cacheDir = getCacheDir();
+    const cacheDir = getSkillsDir();
     paths.push(join(cacheDir, toolNameToPath(normalizedName)));
   }
 

package/src/types/actions.ts

@@ -0,0 +1,223 @@
+/**
+ * TypeScript types for Agent Actions (ACTIONS.yaml)
+ *
+ * Agent Actions extends the Agent Skills specification with structured execution semantics,
+ * enabling skills to define executable actions with typed inputs, validated outputs,
+ * and secure credential handling.
+ *
+ * @see RFC-001-AGENT-ACTIONS.md
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import type { ToolAnnotations } from "./manifest";
+
+/**
+ * Environment variable declaration in ACTIONS.yaml
+ */
+export interface ActionEnvVar {
+  /** Human-readable description of what this variable is for */
+  description?: string;
+  /** If true, value should be stored securely and masked in logs */
+  secret?: boolean;
+  /** If true, execution fails if not set */
+  required?: boolean;
+  /** Default value if not provided */
+  default?: string;
+}
+
+/**
+ * Environment variables map for actions
+ */
+export type ActionEnvVars = Record<string, ActionEnvVar>;
+
+/**
+ * A single executable action within a skill
+ *
+ * Each action maps directly to an MCP tool with:
+ * - (key) → tool name (action name is the map key, not a field)
+ * - description → tool description
+ * - inputSchema → tool parameters
+ * - outputSchema → expected response shape
+ * - annotations → behavioral hints
+ */
+export interface Action {
+  /** Human-readable description of what this action does */
+  description: string;
+
+  /**
+   * Execution command
+   *
+   * Can be string form (simple commands without templates) or array form
+   * (required when using {{}} templates).
+   *
+   * Template syntax: {{param}} - each template is replaced with the literal
+   * value as a single argument, regardless of content.
+   *
+   * @example
+   * // String form (no templates)
+   * command: "python main.py --version"
+   *
+   * // Array form (with templates)
+   * command: ["python", "main.py", "scrape", "{{url}}"]
+   */
+  command: string | string[];
+
+  /**
+   * JSON Schema defining expected input parameters
+   *
+   * Uses standard JSON Schema conventions:
+   * - Required fields listed in 'required' array must be provided
+   * - Optional fields with 'default' use the default value if not provided
+   * - Optional fields without 'default' cause the argument to be omitted entirely
+   *
+   * If omitted, defaults to { type: 'object', properties: {} } (no parameters)
+   */
+  inputSchema?: JSONSchema7;
+
+  /**
+   * JSON Schema defining expected output structure
+   *
+   * If provided, clients must validate results against this schema.
+   * Results that don't conform are treated as errors.
+   */
+  outputSchema?: JSONSchema7;
+
+  /**
+   * Behavioral hints for AI models and clients
+   *
+   * Open-ended object for attaching metadata to actions.
+   * Clients may use these for UI presentation, filtering, or custom behavior.
+   */
+  annotations?: ToolAnnotations;
+}
+
+/**
+ * Complete ACTIONS.yaml manifest structure
+ *
+ * Defines how to execute actions for a skill, including environment
+ * variables, build steps, and the map of executable actions.
+ *
+ * @example
+ * ```yaml
+ * actions:
+ *   scrape:
+ *     description: Scrape a URL
+ *     command: ["python", "main.py", "{{url}}"]
+ *     inputSchema:
+ *       type: object
+ *       required: [url]
+ *       properties:
+ *         url: { type: string }
+ * ```
+ */
+export interface ActionsManifest {
+  /**
+   * Environment variables and secrets required by all actions
+   *
+   * Key benefit: Unlike traditional skills where you discover missing
+   * credentials at runtime, ACTIONS.yaml declares requirements upfront.
+   */
+  env?: ActionEnvVars;
+
+  /**
+   * Map of action names to action definitions
+   *
+   * Each action becomes an MCP tool that can be executed directly.
+   * The key is the action name (e.g., "scrape", "crawl").
+   *
+   * @example
+   * actions:
+   *   scrape:
+   *     description: Scrape a URL
+   *     command: ["python", "main.py", "{{url}}"]
+   *   list-formats:
+   *     description: List supported formats
+   *     command: ffmpeg -formats
+   */
+  actions: Record<string, Action>;
+
+  /**
+   * Build commands to run before execution
+   *
+   * For projects that require setup (e.g., pip install, npm install).
+   * Build runs once per environment setup, not per action invocation.
+   * Build failures prevent action execution.
+   *
+   * @example
+   * build:
+   *   - pip install -r requirements.txt
+   *   - npm install
+   *   - npm run build
+   */
+  build?: string | string[];
+}
+
+/**
+ * Result of parsing an ACTIONS.yaml file
+ */
+export interface ParsedActionsManifest {
+  /** The parsed actions manifest */
+  actions: ActionsManifest;
+  /** The file path the manifest was loaded from */
+  filePath: string;
+}
+
+/**
+ * Validation error specific to actions
+ */
+export interface ActionValidationError {
+  /** Path to the field with the error (e.g., "actions[0].command") */
+  path: string;
+  /** Error message */
+  message: string;
+  /** Error code for programmatic handling */
+  code: ActionValidationErrorCode;
+}
+
+/**
+ * Error codes for action validation
+ */
+export type ActionValidationErrorCode =
+  | "MISSING_REQUIRED_FIELD"
+  | "INVALID_COMMAND_FORMAT"
+  | "STRING_COMMAND_WITH_TEMPLATE"
+  | "DUPLICATE_ACTION_NAME"
+  | "INVALID_INPUT_SCHEMA"
+  | "INVALID_OUTPUT_SCHEMA"
+  | "EMPTY_ACTIONS_ARRAY";
+
+/**
+ * Result of validating an actions manifest
+ */
+export interface ActionValidationResult {
+  /** Whether the manifest is valid */
+  valid: boolean;
+  /** Validation errors (if any) */
+  errors?: ActionValidationError[];
+}
+
+/**
+ * Actions manifest file names (in order of preference)
+ */
+export const ACTIONS_FILES = ["ACTIONS.yaml", "ACTIONS.yml"] as const;
+export type ActionsFileName = (typeof ACTIONS_FILES)[number];
+
+/**
+ * Default inputSchema when not provided
+ *
+ * Actions without inputSchema default to accepting no parameters.
+ */
+export const DEFAULT_INPUT_SCHEMA: JSONSchema7 = {
+  type: "object",
+  properties: {},
+} as const;
+
+/**
+ * Get the effective inputSchema for an action
+ *
+ * Returns the action's inputSchema if provided, otherwise returns
+ * the default empty schema.
+ */
+export function getEffectiveInputSchema(action: Action): JSONSchema7 {
+  return action.inputSchema ?? DEFAULT_INPUT_SCHEMA;
+}

package/src/types/index.ts

@@ -13,6 +13,7 @@ export type {
   Author,
   ToolAnnotations,
   ResourceRequirements,
+  ToolHooks,
   ToolExample,
   // Validation types
   ValidationResult,
@@ -28,3 +29,13 @@ export {
   MANIFEST_FILES,
   PACKAGE_MANIFEST_FILE,
 } from "./manifest";
+
+// Actions types (internal — used by scripts bridge and execution pipeline)
+export type {
+  ActionEnvVar,
+  ActionEnvVars,
+  Action,
+  ActionsManifest,
+} from "./actions";
+
+export { DEFAULT_INPUT_SCHEMA, getEffectiveInputSchema } from "./actions";