@enactprotocol/shared 2.2.4 → 2.3.1

package/src/execution/command.ts

@@ -5,14 +5,14 @@
  *
  * ## Parameter Recognition
  *
- * Only `${...}` patterns that match parameters defined in the tool's inputSchema
- * are substituted. Other `${...}` patterns (like bash variables, arrays, etc.)
- * are passed through unchanged to the shell.
+ * Only `${...}` patterns that match known parameter names are substituted.
+ * Other `${...}` patterns (like bash variables, arrays, etc.) are passed
+ * through unchanged to the shell.
  *
  * This allows natural use of shell syntax:
- * - `${name}` - Substituted if "name" is in inputSchema
- * - `${MY_VAR}` - Passed through to bash (not in inputSchema)
- * - `${array[$i]}` - Passed through to bash (not in inputSchema)
+ * - `${name}` - Substituted if "name" is a known parameter
+ * - `${MY_VAR}` - Passed through to bash (not a known parameter)
+ * - `${array[$i]}` - Passed through to bash (not a known parameter)
  *
  * ## Quoting Behavior
  *
@@ -50,9 +50,9 @@ const PARAM_PATTERN = /\$\{([^}:]+)(?::([^}]+))?\}/g;
  */
 export interface ParseCommandOptions {
   /**
-   * Set of known parameter names from the inputSchema.
+   * Set of known parameter names.
    * Only ${...} patterns matching these names will be treated as parameters.
-   * If not provided, ALL ${...} patterns are treated as parameters (legacy behavior).
+   * If not provided, ALL ${...} patterns are treated as parameters.
    */
   knownParameters?: Set<string>;
 }

package/src/execution/index.ts

@@ -73,5 +73,22 @@ export {
   getParamInfo,
 } from "./validation.js";
 
+// Action command interpolation ({{param}} templates)
+export {
+  parseActionCommand,
+  parseActionArgument,
+  interpolateActionCommand,
+  prepareActionCommand,
+  getMissingRequiredParams,
+  getActionCommandParams,
+  hasActionTemplates,
+  type ActionCommandToken,
+  type ActionCommandLiteralToken,
+  type ActionCommandParamToken,
+  type ParsedArgument,
+  type ParsedActionCommand,
+  type ActionInterpolationOptions,
+} from "./action-command.js";
+
 // NOTE: Dagger provider moved to @enactprotocol/execution package
 // This keeps @enactprotocol/shared browser-safe (no Dagger SDK dependency)

package/src/execution/types.ts

@@ -3,6 +3,7 @@
  * Provides interfaces for tool execution, container management, and results
  */
 
+import type { Action, ActionsManifest } from "../types/actions";
 import type { ToolManifest } from "../types/manifest";
 
 // ============================================================================
@@ -302,6 +303,16 @@ export interface ExecutionProvider {
     options?: ExecutionOptions
   ): Promise<ExecutionResult>;
 
+  /** Execute an action from ACTIONS.yaml */
+  executeAction(
+    manifest: ToolManifest,
+    actionsManifest: ActionsManifest,
+    actionName: string,
+    action: Action,
+    input: ExecutionInput,
+    options?: ExecutionOptions
+  ): Promise<ExecutionResult>;
+
   /** Shutdown the provider */
   shutdown(): Promise<void>;
 }
@@ -342,9 +353,9 @@ export interface InterpolationOptions {
   /** Callback for warnings (e.g., potential double-quoting) */
   onWarning?: (warning: CommandWarning) => void;
   /**
-   * Set of known parameter names from the inputSchema.
+   * Set of known parameter names.
    * Only ${...} patterns matching these names will be substituted.
-   * If not provided, ALL ${...} patterns are treated as parameters (legacy behavior).
+   * If not provided, ALL ${...} patterns are treated as parameters.
    */
   knownParameters?: Set<string>;
 }

package/src/index.ts

@@ -25,6 +25,7 @@ export {
   getEnactHome,
   getProjectEnactDir,
   getToolsDir,
+  getSkillsDir,
   getCacheDir,
   getConfigPath,
   getGlobalEnvPath,
@@ -60,6 +61,7 @@ export {
   type TrustConfig,
   type CacheConfig,
   type ExecutionConfig,
+  type ExecutionBackend,
   type RegistryConfig,
 } from "./config";
 
@@ -80,10 +82,21 @@ export type {
   ToolLocation,
   ToolResolution,
   ManifestFileName,
+  ScriptDefinition,
 } from "./types/manifest";
 
 export { MANIFEST_FILES, PACKAGE_MANIFEST_FILE } from "./types/manifest";
 
+// Actions types (internal — used by scripts bridge and execution pipeline)
+export type {
+  ActionEnvVar,
+  ActionEnvVars,
+  Action,
+  ActionsManifest,
+} from "./types/actions";
+
+export { DEFAULT_INPUT_SCHEMA, getEffectiveInputSchema } from "./types/actions";
+
 // Manifest parsing, validation, and loading
 export {
   // Parser
@@ -110,6 +123,12 @@ export {
   tryLoadManifest,
   tryLoadManifestFromDir,
   type LoadedManifest,
+  // Manifest with scripts
+  loadManifestWithActions,
+  type LoadedManifestWithActions,
+  // Scripts (inline scripts → Action bridge)
+  scriptToAction,
+  manifestScriptsToActionsManifest,
 } from "./manifest";
 
 // Tool resolver
@@ -118,6 +137,9 @@ export {
   resolveTool,
   resolveToolAuto,
   resolveToolFromPath,
+  resolveToolWithAction,
+  resolveAction,
+  parseActionSpecifier,
   tryResolveTool,
   tryResolveToolDetailed,
   normalizeToolName,
@@ -126,6 +148,7 @@ export {
   getToolSearchPaths,
   type ResolveOptions,
   type TryResolveResult,
+  type ParsedActionSpecifier,
 } from "./resolver";
 
 // Local tool registry (tools.json management)
@@ -281,4 +304,18 @@ export {
   applyDefaults,
   getRequiredParams,
   getParamInfo,
+  // Action command ({{param}} templates)
+  parseActionCommand,
+  parseActionArgument,
+  interpolateActionCommand,
+  prepareActionCommand,
+  getMissingRequiredParams,
+  getActionCommandParams,
+  hasActionTemplates,
+  type ActionCommandToken,
+  type ActionCommandLiteralToken,
+  type ActionCommandParamToken,
+  type ParsedArgument,
+  type ParsedActionCommand,
+  type ActionInterpolationOptions,
 } from "./execution";

package/src/manifest/actions-loader.ts

@@ -0,0 +1,49 @@
+/**
+ * Manifest loader with scripts support
+ *
+ * Loads SKILL.md manifests and converts inline scripts to ActionsManifest
+ * objects for the execution pipeline.
+ */
+
+import type { ActionsManifest } from "../types/actions";
+import { type LoadManifestOptions, type LoadedManifest, loadManifestFromDir } from "./loader";
+import { manifestScriptsToActionsManifest } from "./scripts";
+
+/**
+ * Result of loading a manifest with its scripts
+ */
+export interface LoadedManifestWithActions extends LoadedManifest {
+  /** The scripts manifest (converted from inline scripts) */
+  actionsManifest?: ActionsManifest;
+}
+
+/**
+ * Load a SKILL.md manifest and convert inline scripts to an ActionsManifest
+ *
+ * This is the primary function for loading a complete skill with scripts.
+ * It loads the SKILL.md for documentation and metadata, then converts any
+ * inline `scripts` field into an ActionsManifest for the execution pipeline.
+ *
+ * @param dir - Directory containing SKILL.md
+ * @param options - Options for loading and validation
+ * @returns LoadedManifestWithActions containing manifest and optional scripts
+ * @throws ManifestLoadError if SKILL.md loading fails
+ */
+export function loadManifestWithActions(
+  dir: string,
+  options: LoadManifestOptions = {}
+): LoadedManifestWithActions {
+  // Load the primary manifest (SKILL.md)
+  const loaded = loadManifestFromDir(dir, options);
+
+  // Convert inline scripts to ActionsManifest
+  const scriptsManifest = manifestScriptsToActionsManifest(loaded.manifest);
+  if (scriptsManifest) {
+    return {
+      ...loaded,
+      actionsManifest: scriptsManifest,
+    };
+  }
+
+  return loaded;
+}

package/src/manifest/index.ts

@@ -37,3 +37,15 @@ export {
   type LoadedManifest,
   type LoadManifestOptions,
 } from "./loader";
+
+// Manifest with scripts
+export {
+  loadManifestWithActions,
+  type LoadedManifestWithActions,
+} from "./actions-loader";
+
+// Scripts (inline scripts → Action bridge)
+export {
+  scriptToAction,
+  manifestScriptsToActionsManifest,
+} from "./scripts";

package/src/manifest/loader.ts

@@ -6,9 +6,10 @@
 
 import { existsSync, readFileSync } from "node:fs";
 import { basename, join } from "node:path";
+import yaml from "js-yaml";
 import type { ParsedManifest, ToolManifest, ValidationResult } from "../types/manifest";
 import { MANIFEST_FILES } from "../types/manifest";
-import { ManifestParseError, parseManifestAuto } from "./parser";
+import { ManifestParseError, extractFrontmatter, parseManifestAuto } from "./parser";
 import { type ValidateManifestOptions, validateManifest } from "./validator";
 
 /**
@@ -51,7 +52,7 @@ export interface LoadManifestOptions extends ValidateManifestOptions {
 /**
  * Load a manifest from a file path
  *
- * @param filePath - Path to the manifest file (SKILL.md, enact.md, enact.yaml, or enact.yml)
+ * @param filePath - Path to the manifest file (SKILL.md, skill.yaml, skill.yml, enact.md, enact.yaml, or enact.yml)
  * @param options - Options for loading and validation
  * @returns LoadedManifest with validated manifest and metadata
  * @throws ManifestLoadError if file doesn't exist, parse fails, or validation fails
@@ -116,10 +117,36 @@ export function loadManifest(filePath: string, options: LoadManifestOptions = {}
   return result;
 }
 
+/**
+ * Load SKILL.md for its body content and frontmatter fields.
+ * Does NOT validate as a full ToolManifest — used only to extract
+ * agent-facing documentation in two-file mode (skill.yaml + SKILL.md).
+ */
+function loadSkillDoc(
+  filePath: string
+): { body: string; frontmatter: Record<string, unknown> } | null {
+  try {
+    const content = readFileSync(filePath, "utf-8");
+    const extracted = extractFrontmatter(content);
+    if (!extracted) return null;
+    const frontmatter = extracted.frontmatter
+      ? ((yaml.load(extracted.frontmatter) as Record<string, unknown>) ?? {})
+      : {};
+    return { body: extracted.body, frontmatter };
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Find and load a manifest from a directory
  *
- * Searches for SKILL.md, enact.md, enact.yaml, or enact.yml in the given directory
+ * Supports two modes:
+ * 1. **Two-file model**: If both `skill.yaml` and `SKILL.md` exist, `skill.yaml` is
+ *    the package manifest and `SKILL.md` provides agent-facing documentation (body → `doc`).
+ *    Also supports legacy `enact.yaml` in place of `skill.yaml`.
+ * 2. **Single-file fallback**: Searches for SKILL.md, skill.yaml, skill.yml, enact.md, enact.yaml, or enact.yml
+ *    and uses the first match as the complete manifest.
  *
  * @param dir - Directory to search for manifest
  * @param options - Options for loading and validation
@@ -130,7 +157,53 @@ export function loadManifestFromDir(
   dir: string,
   options: LoadManifestOptions = {}
 ): LoadedManifest {
-  // Try each manifest filename in order of preference
+  const skillMdPath = join(dir, "SKILL.md");
+  const hasSkillMd = existsSync(skillMdPath);
+
+  // Find config file (skill.yaml, skill.yml, or legacy enact.yaml/enact.yml)
+  let enactConfigPath: string | null = null;
+  for (const f of ["skill.yaml", "skill.yml", "enact.yaml", "enact.yml"]) {
+    const p = join(dir, f);
+    if (existsSync(p)) {
+      enactConfigPath = p;
+      break;
+    }
+  }
+
+  // Two-file model: skill.yaml + SKILL.md
+  if (enactConfigPath && hasSkillMd) {
+    const loaded = loadManifest(enactConfigPath, options);
+    const skillDoc = loadSkillDoc(skillMdPath);
+
+    if (skillDoc) {
+      // Merge SKILL.md body into manifest.doc and LoadedManifest.body
+      loaded.manifest = { ...loaded.manifest };
+      if (skillDoc.body) {
+        if (!loaded.manifest.doc) {
+          loaded.manifest.doc = skillDoc.body;
+        }
+        loaded.body = skillDoc.body;
+      }
+      // Use SKILL.md frontmatter as fallbacks for shared fields
+      const fm = skillDoc.frontmatter;
+      if (!loaded.manifest.description && typeof fm.description === "string") {
+        loaded.manifest.description = fm.description;
+      }
+      if (!loaded.manifest.license && typeof fm.license === "string") {
+        loaded.manifest.license = fm.license;
+      }
+      if (!loaded.manifest.compatibility && typeof fm.compatibility === "string") {
+        loaded.manifest.compatibility = fm.compatibility;
+      }
+      if (!loaded.manifest.metadata && fm.metadata && typeof fm.metadata === "object") {
+        loaded.manifest.metadata = fm.metadata as Record<string, string>;
+      }
+    }
+
+    return loaded;
+  }
+
+  // Single-file fallback (existing behavior)
   for (const filename of MANIFEST_FILES) {
     const filePath = join(dir, filename);
     if (existsSync(filePath)) {

package/src/manifest/parser.ts

@@ -3,6 +3,7 @@
  *
  * Handles parsing of:
  * - SKILL.md files (YAML frontmatter + Markdown body) - primary format
+ * - skill.yaml/yml files (pure YAML) - package manifest
  * - enact.yaml/yml files (pure YAML) - legacy format
  * - enact.md files (YAML frontmatter + Markdown body) - legacy format
  */

package/src/manifest/scripts.ts

@@ -0,0 +1,116 @@
+/**
+ * Script-to-Action bridge
+ *
+ * Converts inline `scripts` from ToolManifest into Action/ActionsManifest
+ * objects so the existing execution pipeline works unchanged.
+ */
+
+import type { JSONSchema7 } from "json-schema";
+import { getActionCommandParams } from "../execution/action-command";
+import type { Action, ActionEnvVars, ActionsManifest } from "../types/actions";
+import type { ScriptDefinition, ToolManifest } from "../types/manifest";
+
+/**
+ * Convert a script command string to array form
+ *
+ * Splits on whitespace while preserving {{param}} tokens as single elements.
+ */
+function scriptCommandToArray(command: string): string[] {
+  return command.split(/\s+/).filter((s) => s.length > 0);
+}
+
+/**
+ * Auto-infer an inputSchema from {{param}} patterns in a command array
+ *
+ * Every parameter found becomes a required string property.
+ */
+function inferInputSchema(commandArray: string[]): JSONSchema7 {
+  const params = getActionCommandParams(commandArray);
+
+  if (params.length === 0) {
+    return { type: "object", properties: {} };
+  }
+
+  const properties: Record<string, JSONSchema7> = {};
+  for (const param of params) {
+    properties[param] = { type: "string" };
+  }
+
+  return {
+    type: "object",
+    required: params,
+    properties,
+  };
+}
+
+/**
+ * Convert a single script entry to an Action object
+ */
+export function scriptToAction(name: string, script: ScriptDefinition): Action {
+  if (typeof script === "string") {
+    const commandArray = scriptCommandToArray(script);
+    return {
+      description: name,
+      command: commandArray,
+      inputSchema: inferInputSchema(commandArray),
+    };
+  }
+
+  // Expanded form
+  const commandArray = scriptCommandToArray(script.command);
+  return {
+    description: script.description ?? name,
+    command: commandArray,
+    inputSchema: script.inputSchema ?? inferInputSchema(commandArray),
+    ...(script.outputSchema && { outputSchema: script.outputSchema }),
+    ...(script.annotations && { annotations: script.annotations }),
+  };
+}
+
+/**
+ * Convert manifest env (EnvVariables) to action env (ActionEnvVars)
+ */
+function convertEnv(env: ToolManifest["env"]): ActionEnvVars | undefined {
+  if (!env || Object.keys(env).length === 0) return undefined;
+
+  const actionEnv: ActionEnvVars = {};
+  for (const [key, value] of Object.entries(env)) {
+    const envVar: ActionEnvVars[string] = {
+      description: value.description,
+    };
+    if (value.secret !== undefined) {
+      envVar.secret = value.secret;
+    }
+    if (value.default !== undefined) {
+      envVar.default = value.default;
+    }
+    actionEnv[key] = envVar;
+  }
+  return actionEnv;
+}
+
+/**
+ * Convert all inline scripts from a manifest to an ActionsManifest
+ *
+ * Returns null if the manifest has no scripts.
+ */
+export function manifestScriptsToActionsManifest(manifest: ToolManifest): ActionsManifest | null {
+  if (!manifest.scripts || Object.keys(manifest.scripts).length === 0) {
+    return null;
+  }
+
+  const actions: Record<string, Action> = {};
+  for (const [name, script] of Object.entries(manifest.scripts)) {
+    actions[name] = scriptToAction(name, script);
+  }
+
+  const result: ActionsManifest = { actions };
+  const env = convertEnv(manifest.env);
+  if (env) {
+    result.env = env;
+  }
+  if (manifest.hooks?.build) {
+    result.build = manifest.hooks.build;
+  }
+  return result;
+}

package/src/manifest/validator.ts

@@ -20,6 +20,7 @@ import type {
 const EnvVariableSchema = z.object({
   description: z.string().min(1, "Description is required"),
   secret: z.boolean().optional(),
+  required: z.boolean().optional(),
   default: z.string().optional(),
 });
 
@@ -83,15 +84,16 @@ const SEMVER_REGEX =
   /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-((?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*)(?:\.(?:0|[1-9]\d*|\d*[a-zA-Z-][0-9a-zA-Z-]*))*))?(?:\+([0-9a-zA-Z-]+(?:\.[0-9a-zA-Z-]+)*))?$/;
 
 /**
- * Tool name regex - hierarchical path format (required for publishing)
+ * Tool name regex - @scope/name format (required for publishing)
+ * Exactly 2 segments with optional @ prefix: "org/tool" or "@org/tool"
  */
-const TOOL_NAME_REGEX = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)+$/;
+const TOOL_NAME_REGEX = /^@?[a-z0-9_-]+\/[a-z0-9_-]+$/;
 
 /**
  * Tool name regex - simple format (allowed for local tools)
- * Allows both hierarchical (org/tool) and simple (my-tool) names
+ * Allows simple names ("my-tool") or scope/name ("org/tool", "@org/tool")
  */
-const TOOL_NAME_REGEX_LOCAL = /^[a-z0-9_-]+(?:\/[a-z0-9_-]+)*$/;
+const TOOL_NAME_REGEX_LOCAL = /^@?[a-z0-9_-]+(?:\/[a-z0-9_-]+)?$/;
 
 /**
  * Go duration regex (used for timeout)
@@ -105,7 +107,7 @@ function createToolManifestSchema(allowSimpleNames: boolean) {
   const nameRegex = allowSimpleNames ? TOOL_NAME_REGEX_LOCAL : TOOL_NAME_REGEX;
   const nameMessage = allowSimpleNames
     ? "Tool name must contain only lowercase letters, numbers, hyphens, and underscores"
-    : "Tool name must be hierarchical path format (e.g., 'org/tool' or 'org/category/tool')";
+    : "Tool name must be scope/name format (e.g., 'org/tool' or '@org/tool')";
 
   return z
     .object({
@@ -133,7 +135,6 @@ function createToolManifestSchema(allowSimpleNames: boolean) {
       tags: z.array(z.string()).optional(),
 
       // Schema fields
-      inputSchema: JsonSchemaSchema.optional(),
       outputSchema: JsonSchemaSchema.optional(),
 
       // Environment variables
@@ -223,14 +224,6 @@ function generateWarnings(manifest: ToolManifest): ValidationWarning[] {
     });
   }
 
-  if (!manifest.inputSchema && manifest.command) {
-    warnings.push({
-      path: "inputSchema",
-      message: "Input schema is recommended for tools with parameters",
-      code: "MISSING_RECOMMENDED",
-    });
-  }
-
   if (!manifest.outputSchema) {
     warnings.push({
       path: "outputSchema",
@@ -249,6 +242,14 @@ function generateWarnings(manifest: ToolManifest): ValidationWarning[] {
           code: "SECRET_WITH_DEFAULT",
         });
       }
+      if (value.required && value.default !== undefined) {
+        warnings.push({
+          path: `env.${key}`,
+          message:
+            "Required variables with a default value are always satisfied — 'required' has no effect",
+          code: "REQUIRED_WITH_DEFAULT",
+        });
+      }
     }
   }
 

package/src/mcp-registry.ts

@@ -132,12 +132,12 @@ export function getMcpToolVersion(toolName: string): string | null {
 }
 
 /**
- * Get the cache path for an MCP tool
+ * Get the install path for an MCP tool
+ * Skills are stored at ~/.agent/skills/{name}/ (flat, no version subdirectory)
  */
-function getMcpToolCachePath(toolName: string, version: string): string {
-  const cacheDir = getCacheDir();
-  const normalizedVersion = version.startsWith("v") ? version.slice(1) : version;
-  return join(cacheDir, toolName, `v${normalizedVersion}`);
+function getMcpToolCachePath(toolName: string, _version: string): string {
+  const skillsDir = getCacheDir();
+  return join(skillsDir, toolName);
 }
 
 /**

package/src/paths.ts

@@ -74,11 +74,21 @@ export function getToolsDir(scope: ToolScope, startDir?: string): string | null
 }
 
 /**
- * Get the cache directory (~/.enact/cache/)
- * @returns Absolute path to ~/.enact/cache/
+ * Get the skills directory (~/.agent/skills/)
+ * This is the standard Agent Skills location for installed skills.
+ * @returns Absolute path to ~/.agent/skills/
+ */
+export function getSkillsDir(): string {
+  return join(homedir(), ".agent", "skills");
+}
+
+/**
+ * Get the cache directory (~/.agent/skills/)
+ * @deprecated Use getSkillsDir() instead
+ * @returns Absolute path to ~/.agent/skills/
  */
 export function getCacheDir(): string {
-  return join(getEnactHome(), "cache");
+  return getSkillsDir();
 }
 
 /**

package/src/registry.ts

@@ -165,12 +165,12 @@ export function getInstalledVersion(
 }
 
 /**
- * Get the cache path for an installed tool
+ * Get the install path for a skill
+ * Skills are stored at ~/.agent/skills/{name}/ (flat, no version subdirectory)
  */
-export function getToolCachePath(toolName: string, version: string): string {
-  const cacheDir = getCacheDir();
-  const normalizedVersion = version.startsWith("v") ? version.slice(1) : version;
-  return join(cacheDir, toolName, `v${normalizedVersion}`);
+export function getToolCachePath(toolName: string, _version: string): string {
+  const skillsDir = getCacheDir();
+  return join(skillsDir, toolName);
 }
 
 /**