@enactprotocol/shared 2.2.2 → 2.3.1

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";

package/src/types/manifest.ts

@@ -1,6 +1,6 @@
 /**
  * TypeScript types for Enact tool manifests
- * These types define the structure of SKILL.md (and legacy enact.yaml/enact.md) frontmatter
+ * These types define the structure of SKILL.md (and skill.yaml/legacy enact.yaml/enact.md) frontmatter
  */
 
 import type { JSONSchema7 } from "json-schema";
@@ -13,6 +13,8 @@ export interface EnvVariable {
   description: string;
   /** If true, stored in OS keyring; if false, stored in .env files */
   secret?: boolean;
+  /** If true, must be set before execution (no default fallback) */
+  required?: boolean;
   /** Default value if not set (only for non-secrets) */
   default?: string;
 }
@@ -50,6 +52,32 @@ export interface ToolAnnotations {
   openWorldHint?: boolean;
 }
 
+/**
+ * Lifecycle hooks for tool installation and management
+ */
+export interface ToolHooks {
+  /** Command(s) to run after the tool is installed/extracted (e.g., "npm install", "pip install -r requirements.txt") */
+  postinstall?: string | string[];
+  /** Build command(s) to run before execution (e.g., "pip install -r requirements.txt") */
+  build?: string | string[];
+}
+
+/**
+ * Script definition — either a simple command string or an expanded object
+ *
+ * Simple form: "python main.py {{url}}"
+ * Expanded form: { command: "python main.py {{url}}", description: "Scrape a URL" }
+ */
+export type ScriptDefinition =
+  | string
+  | {
+      command: string;
+      description?: string;
+      inputSchema?: JSONSchema7;
+      outputSchema?: JSONSchema7;
+      annotations?: ToolAnnotations;
+    };
+
 /**
  * Resource requirements for tool execution
  */
@@ -76,7 +104,7 @@ export interface ToolExample {
 
 /**
  * Complete tool manifest structure
- * This represents the YAML frontmatter in SKILL.md (or legacy enact.md/enact.yaml)
+ * This represents the YAML frontmatter in SKILL.md (or skill.yaml/legacy enact.md/enact.yaml)
  */
 export interface ToolManifest {
   // ==================== Required Fields ====================
@@ -115,9 +143,6 @@ export interface ToolManifest {
 
   // ==================== Schema Fields ====================
 
-  /** JSON Schema defining input parameters */
-  inputSchema?: JSONSchema7;
-
   /** JSON Schema defining output structure */
   outputSchema?: JSONSchema7;
 
@@ -134,6 +159,28 @@ export interface ToolManifest {
   /** Resource limits and requirements */
   resources?: ResourceRequirements;
 
+  // ==================== Lifecycle Hooks ====================
+
+  /** Lifecycle hooks (e.g., postinstall build step) */
+  hooks?: ToolHooks;
+
+  // ==================== Scripts ====================
+
+  /**
+   * Inline executable scripts (each becomes an MCP tool via colon syntax)
+   *
+   * Scripts replace the need for a separate ACTIONS.yaml file.
+   * Each script maps a name to a command with {{param}} template syntax.
+   *
+   * @example
+   * scripts:
+   *   scrape: python scripts/scrape.py {{url}}
+   *   crawl:
+   *     command: python scripts/crawl.py {{url}} {{depth}}
+   *     description: Crawl a website to specified depth
+   */
+  scripts?: Record<string, ScriptDefinition>;
+
   // ==================== Agent Skills Spec Fields ====================
 
   /** Environment requirements (intended product, system packages, network access, etc.) */
@@ -252,14 +299,28 @@ export interface ToolResolution {
   manifestPath: string;
   /** Tool version (if available) */
   version?: string | undefined;
+  /** The resolved script (if a script was specified via colon syntax) */
+  action?: import("./actions").Action | undefined;
+  /** The requested script name (if specified via colon syntax) */
+  actionName?: string | undefined;
+  /** The scripts manifest (converted from inline scripts) */
+  actionsManifest?: import("./actions").ActionsManifest | undefined;
 }
 
 /**
  * Supported manifest file names
  * SKILL.md is the primary format (aligned with Anthropic Agent Skills)
+ * skill.yaml/yml is the package manifest
  * enact.md/yaml/yml are supported for backwards compatibility
  */
-export const MANIFEST_FILES = ["SKILL.md", "enact.md", "enact.yaml", "enact.yml"] as const;
+export const MANIFEST_FILES = [
+  "SKILL.md",
+  "skill.yaml",
+  "skill.yml",
+  "enact.md",
+  "enact.yaml",
+  "enact.yml",
+] as const;
 export type ManifestFileName = (typeof MANIFEST_FILES)[number];
 
 /**

package/tests/action-command.test.ts

@@ -0,0 +1,249 @@
+/**
+ * Tests for the action command interpolation module.
+ *
+ * Covers {{param}} template parsing, interpolation, omission of optionals,
+ * and the prepareActionCommand entry point.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  getActionCommandParams,
+  getMissingRequiredParams,
+  hasActionTemplates,
+  interpolateActionCommand,
+  parseActionArgument,
+  parseActionCommand,
+  prepareActionCommand,
+} from "../src/execution/action-command";
+
+describe("hasActionTemplates", () => {
+  test("returns true for string with {{param}}", () => {
+    expect(hasActionTemplates("hello {{name}}")).toBe(true);
+  });
+
+  test("returns false for plain string", () => {
+    expect(hasActionTemplates("echo hello")).toBe(false);
+  });
+
+  test("returns false for ${param} syntax", () => {
+    expect(hasActionTemplates("echo ${name}")).toBe(false);
+  });
+
+  test("returns true for standalone {{param}}", () => {
+    expect(hasActionTemplates("{{url}}")).toBe(true);
+  });
+});
+
+describe("parseActionArgument", () => {
+  test("parses a literal argument", () => {
+    const result = parseActionArgument("echo");
+    expect(result.tokens).toHaveLength(1);
+    expect(result.tokens[0]?.type).toBe("literal");
+    expect(result.tokens[0]?.type === "literal" && result.tokens[0].value).toBe("echo");
+    expect(result.parameters).toHaveLength(0);
+  });
+
+  test("parses a standalone parameter", () => {
+    const result = parseActionArgument("{{url}}");
+    expect(result.tokens).toHaveLength(1);
+    expect(result.tokens[0]?.type).toBe("parameter");
+    expect(result.tokens[0]?.type === "parameter" && result.tokens[0].name).toBe("url");
+    expect(result.parameters).toEqual(["url"]);
+  });
+
+  test("parses mixed literal and parameter", () => {
+    const result = parseActionArgument("--name={{name}}");
+    expect(result.tokens).toHaveLength(2);
+    expect(result.tokens[0]?.type).toBe("literal");
+    expect(result.tokens[1]?.type).toBe("parameter");
+    expect(result.parameters).toEqual(["name"]);
+  });
+
+  test("parses multiple parameters in one argument", () => {
+    const result = parseActionArgument("{{host}}:{{port}}");
+    expect(result.tokens).toHaveLength(3);
+    expect(result.parameters).toEqual(["host", "port"]);
+  });
+
+  test("trims whitespace in parameter names", () => {
+    const result = parseActionArgument("{{ name }}");
+    expect(result.parameters).toEqual(["name"]);
+  });
+});
+
+describe("parseActionCommand", () => {
+  test("parses command with no templates", () => {
+    const result = parseActionCommand(["echo", "hello", "world"]);
+    expect(result.allParameters).toHaveLength(0);
+    expect(result.arguments).toHaveLength(3);
+  });
+
+  test("parses command with templates", () => {
+    const result = parseActionCommand(["python", "main.py", "{{url}}"]);
+    expect(result.allParameters).toEqual(["url"]);
+  });
+
+  test("deduplicates parameter names", () => {
+    const result = parseActionCommand(["echo", "{{name}}", "{{name}}"]);
+    expect(result.allParameters).toEqual(["name"]);
+  });
+
+  test("collects all unique parameters", () => {
+    const result = parseActionCommand(["cmd", "{{a}}", "{{b}}", "{{c}}"]);
+    expect(result.allParameters).toEqual(["a", "b", "c"]);
+  });
+});
+
+describe("interpolateActionCommand", () => {
+  test("replaces parameter with value", () => {
+    const result = interpolateActionCommand(["echo", "{{name}}"], { name: "Alice" });
+    expect(result).toEqual(["echo", "Alice"]);
+  });
+
+  test("preserves literal arguments", () => {
+    const result = interpolateActionCommand(["python", "main.py", "--verbose"], {});
+    expect(result).toEqual(["python", "main.py", "--verbose"]);
+  });
+
+  test("handles mixed literal and parameter", () => {
+    const result = interpolateActionCommand(["--output={{format}}"], { format: "json" });
+    expect(result).toEqual(["--output=json"]);
+  });
+
+  test("converts number to string", () => {
+    const result = interpolateActionCommand(["echo", "{{count}}"], { count: 42 });
+    expect(result).toEqual(["echo", "42"]);
+  });
+
+  test("converts boolean to string", () => {
+    const result = interpolateActionCommand(["echo", "{{flag}}"], { flag: true });
+    expect(result).toEqual(["echo", "true"]);
+  });
+
+  test("converts object to JSON string", () => {
+    const result = interpolateActionCommand(["echo", "{{data}}"], { data: { key: "value" } });
+    expect(result).toEqual(["echo", '{"key":"value"}']);
+  });
+
+  test("omits argument for optional param with no value", () => {
+    const schema = {
+      type: "object" as const,
+      properties: {
+        name: { type: "string" as const },
+        verbose: { type: "boolean" as const },
+      },
+      required: ["name"],
+    };
+
+    const result = interpolateActionCommand(
+      ["echo", "{{name}}", "{{verbose}}"],
+      { name: "Alice" },
+      { inputSchema: schema }
+    );
+    // "verbose" is optional with no value → omitted
+    expect(result).toEqual(["echo", "Alice"]);
+  });
+
+  test("uses default value for optional param", () => {
+    const schema = {
+      type: "object" as const,
+      properties: {
+        format: { type: "string" as const, default: "text" },
+      },
+    };
+
+    const result = interpolateActionCommand(["echo", "{{format}}"], {}, { inputSchema: schema });
+    expect(result).toEqual(["echo", "text"]);
+  });
+
+  test("does not split values with spaces into multiple args", () => {
+    const result = interpolateActionCommand(["echo", "{{msg}}"], {
+      msg: "hello world with spaces",
+    });
+    // Must remain a single argument — security property
+    expect(result).toEqual(["echo", "hello world with spaces"]);
+  });
+});
+
+describe("getMissingRequiredParams", () => {
+  test("returns empty when all required params provided", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["name"],
+      properties: { name: { type: "string" as const } },
+    };
+    const missing = getMissingRequiredParams(["echo", "{{name}}"], { name: "hi" }, schema);
+    expect(missing).toHaveLength(0);
+  });
+
+  test("returns missing required param names", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["name", "age"],
+      properties: {
+        name: { type: "string" as const },
+        age: { type: "number" as const },
+      },
+    };
+    const missing = getMissingRequiredParams(
+      ["echo", "{{name}}", "{{age}}"],
+      { name: "Alice" },
+      schema
+    );
+    expect(missing).toEqual(["age"]);
+  });
+
+  test("does not report optional params as missing", () => {
+    const schema = {
+      type: "object" as const,
+      required: [],
+      properties: { verbose: { type: "boolean" as const } },
+    };
+    const missing = getMissingRequiredParams(["echo", "{{verbose}}"], {}, schema);
+    expect(missing).toHaveLength(0);
+  });
+});
+
+describe("getActionCommandParams", () => {
+  test("returns all parameter names from command", () => {
+    expect(getActionCommandParams(["cmd", "{{a}}", "{{b}}"])).toEqual(["a", "b"]);
+  });
+
+  test("returns empty for command without templates", () => {
+    expect(getActionCommandParams(["echo", "hello"])).toEqual([]);
+  });
+});
+
+describe("prepareActionCommand", () => {
+  test("interpolates and returns command array", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["url"],
+      properties: { url: { type: "string" as const } },
+    };
+    const result = prepareActionCommand(
+      ["python", "main.py", "{{url}}"],
+      { url: "https://example.com" },
+      schema
+    );
+    expect(result).toEqual(["python", "main.py", "https://example.com"]);
+  });
+
+  test("throws when required parameters are missing", () => {
+    const schema = {
+      type: "object" as const,
+      required: ["url"],
+      properties: { url: { type: "string" as const } },
+    };
+    expect(() => prepareActionCommand(["python", "main.py", "{{url}}"], {}, schema)).toThrow(
+      "Missing required parameters: url"
+    );
+  });
+
+  test("works without schema (all params treated conservatively)", () => {
+    // Without schema, all params are treated as required
+    expect(() => prepareActionCommand(["echo", "{{name}}"], {})).toThrow(
+      "Missing required parameters: name"
+    );
+  });
+});