@elizaos/prompts 2.0.0-alpha.98 → 2.0.11-beta.7

package/README.md

@@ -1,63 +1,52 @@
 # @elizaos/prompts
 
-Shared prompt templates for elizaOS across TypeScript, Python, and Rust runtimes.
+Shared prompt templates and action specs for elizaOS.
 
 ## Overview
 
-This package provides a single source of truth for all prompt templates used by elizaOS agents. Prompts are stored as `.txt` files and generated into native formats for each language.
+This package is the single source of truth for prompt templates used by the runtime. Prompts are authored directly in `src/index.ts`.
 
 ## Structure
 
 ```
 packages/prompts/
-├── prompts/           # Source prompt templates (.txt files)
-│   ├── reply.txt
-│   ├── choose_option.txt
-│   ├── image_generation.txt
-│   └── ...
-├── scripts/           # Build scripts
-│   └── generate.js    # Generates native code from prompts
-├── dist/              # Generated output
-│   ├── typescript/    # TypeScript exports
-│   ├── python/        # Python module
-│   └── rust/          # Rust source
-└── package.json
+├── src/
+│   └── index.ts      # TypeScript prompt template exports
+├── specs/            # Merged action/provider specs (JSON) + generated plugins.generated.json
+└── scripts/          # Spec + docs generators
+    ├── generate-action-docs.js
+    ├── generate-plugin-action-spec.js
+    ├── prompt-compression.js
+    └── check-secrets.js
 ```
 
 ## Template Syntax
 
-All prompts use **Handlebars-style** template variables:
+Prompts use Handlebars-style variables:
 
-- `{{variableName}}` - Simple variable substitution
-- `{{#each items}}...{{/each}}` - Iteration over arrays
-- `{{#if condition}}...{{/if}}` - Conditional blocks
+- `{{variableName}}` - simple variable substitution
+- `{{#each items}}...{{/each}}` - iteration
+- `{{#if condition}}...{{/if}}` - conditional
 
-### Variable Naming Convention
+Use camelCase for variables (`{{agentName}}`, `{{providers}}`, `{{recentMessages}}`).
 
-Use camelCase for all template variables to ensure consistency across languages:
+## Plugin-local `prompts/*.json` (under `plugins/**`)
 
-- `{{agentName}}` - The agent's name
-- `{{providers}}` - Provider context
-- `{{recentMessages}}` - Recent conversation messages
+Some plugins keep **hand-edited** `actions.json` / `evaluators.json` / `providers.json` next to their source. Those files feed **per-plugin codegen** (for example `generated/specs/spec-helpers.ts` via each plugin’s own workflow). They are **not** inputs to `scripts/generate-plugin-action-spec.js`, which instead scans `plugins/**/*.ts` for `export const …: Action` blocks and writes `specs/actions/plugins.generated.json`.
 
 ## Building
 
 ```bash
-# Build all targets
-npm run build
-
-# Build specific target
-npm run build:typescript
-npm run build:python
-npm run build:rust
+# Generate plugin action spec + action docs
+bun run build
 ```
 
 ## Usage
 
-### TypeScript
+Runtime code imports the templates through `@elizaos/core`, which re-exports them and provides `composePrompt` to fill the `{{...}}` placeholders:
 
 ```typescript
-import { REPLY_TEMPLATE, CHOOSE_OPTION_TEMPLATE } from "@elizaos/prompts";
+import { REPLY_TEMPLATE, composePrompt } from "@elizaos/core";
 
 const prompt = composePrompt({
   state: { agentName: "Alice" },
@@ -65,78 +54,31 @@ const prompt = composePrompt({
 });
 ```
 
-### Python
-
-```python
-from elizaos.prompts import REPLY_TEMPLATE, CHOOSE_OPTION_TEMPLATE
-
-prompt = compose_prompt(state={'agentName': 'Alice'}, template=REPLY_TEMPLATE)
-```
-
-### Rust
-
-```rust
-use elizaos_prompts::{REPLY_TEMPLATE, CHOOSE_OPTION_TEMPLATE};
-
-let prompt = compose_prompt(&state, REPLY_TEMPLATE);
-```
+Import directly from `@elizaos/prompts` only inside this package's tooling and tests.
 
 ## Adding New Prompts
 
-1. Create a new `.txt` file in `prompts/` directory
-2. Name the file using snake_case (e.g., `my_new_action.txt`)
-3. Run `npm run build` to generate native code
-4. The prompt will be exported as `MY_NEW_ACTION_TEMPLATE` in all languages
-
-## Plugin Prompts
-
-Plugins can use the same prompt system! See [README-PLUGIN-PROMPTS.md](./README-PLUGIN-PROMPTS.md) for details on how to set up prompts in your plugin.
-
-The `scripts/generate-plugin-prompts.js` utility can be used by any plugin to generate TypeScript, Python, and Rust exports from `.txt` prompt templates.
+1. Add a `camelCaseTemplate` string export in `src/index.ts`.
+2. Add the paired `UPPER_SNAKE_CASE_TEMPLATE` export.
 
 ## Template Guidelines
 
-1. **Start with a task description** - Begin prompts with `# Task:` to clearly state the objective
-2. **Include providers placeholder** - Use `{{providers}}` where provider context should be injected
-3. **Use XML output format** - Standardize on XML response format for consistent parsing
-4. **Add clear instructions** - Include explicit instructions for the LLM
-5. **End with output format** - Always specify the expected output format
+1. **Start with a task description** — begin prompts with `# Task:` to state the objective.
+2. **Include providers placeholder** — use `{{providers}}` where provider context should be injected.
+3. **Use JSON output format** — standardize on JSON response format for consistent parsing.
+4. **Add clear instructions** — explicit instructions for the LLM.
+5. **End with output format** — always specify the expected output format.
 
-Example:
+## Security & Privacy
 
-```txt
-# Task: Generate dialog for the character {{agentName}}.
-
-{{providers}}
-
-# Instructions: Write the next message for {{agentName}}.
-
-Respond using XML format like this:
-<response>
-    <thought>Your thought here</thought>
-    <text>Your message here</text>
-</response>
-
-IMPORTANT: Your response must ONLY contain the <response></response> XML block above.
-```
-
-## Security & Privacy Guidance (SOC2-aligned)
-
-- **Do not embed real secrets** in prompt templates. Prompts are source-controlled and often distributed.
+- **Do not embed real secrets** in prompt templates. Prompts are source-controlled.
 - **Avoid including PII** (emails, phone numbers, addresses, IDs) in templates or examples.
-- Prefer placeholders (e.g., `{{apiKey}}`, `{{userEmail}}`) and ensure the runtime injects only the minimum needed.
+- Prefer placeholders (e.g., `{{apiKey}}`, `{{userEmail}}`) and inject only the minimum needed at runtime.
 
 ### Secret scan
 
-This package includes a conservative scanner that flags prompt templates containing strings that strongly resemble real credentials (or private key material).
-
-Run:
-
 ```bash
-npm run check:secrets
+bun run check:secrets
 ```
 
-It scans:
-
-- `packages/prompts/prompts/**/*.txt`
-- `plugins/**/prompts/**/*.txt`
+Scans `packages/prompts/src/**/*.ts`, plugin prompt TS modules (paths matching `prompts/**/*.ts`, `workflow-prompts/**/*.ts`, etc.), and a few explicit files — see `scripts/check-secrets.js`.

package/package.json

@@ -1,34 +1,37 @@
 {
   "name": "@elizaos/prompts",
   "private": false,
-  "version": "2.0.0-alpha.98",
+  "version": "2.0.11-beta.7",
   "description": "Shared prompt templates for elizaOS across TypeScript, Python, and Rust",
   "type": "module",
-  "main": "./dist/typescript/index.ts",
-  "types": "./dist/typescript/index.ts",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
   "exports": {
     ".": {
-      "types": "./dist/typescript/index.ts",
-      "import": "./dist/typescript/index.ts"
+      "types": "./src/index.ts",
+      "import": "./src/index.ts"
     },
-    "./python": "./dist/python/prompts.py",
-    "./rust": "./dist/rust/prompts.rs"
+    "./*.css": "./dist/*.css",
+    "./*": {
+      "types": "./dist/*.d.ts",
+      "import": "./dist/*.js",
+      "default": "./dist/*.js"
+    }
   },
   "scripts": {
-    "build": "node scripts/generate.js && node scripts/generate-plugin-action-spec.js && node scripts/generate-action-docs.js",
-    "build:typescript": "node scripts/generate.js --target typescript",
-    "build:python": "node scripts/generate.js --target python",
-    "build:rust": "node scripts/generate.js --target rust",
+    "build": "node scripts/generate-plugin-action-spec.js && bunx @biomejs/biome format --write specs/actions/plugins.generated.json && node scripts/generate-action-docs.js",
     "build:action-docs": "node scripts/generate-action-docs.js",
-    "build:plugin-action-spec": "node scripts/generate-plugin-action-spec.js",
+    "build:plugin-action-spec": "node scripts/generate-plugin-action-spec.js && bunx @biomejs/biome format --write specs/actions/plugins.generated.json",
     "check:secrets": "node scripts/check-secrets.js",
     "clean": "rm -rf dist",
     "lint": "bunx @biomejs/biome check --write .",
     "lint:check": "bunx @biomejs/biome check .",
-    "typecheck": "echo 'No TypeScript source files to check'"
+    "format:check": "bunx @biomejs/biome format .",
+    "typecheck": "echo 'No TypeScript source files to check'",
+    "test": "bun test ./test"
   },
   "files": [
-    "prompts/",
+    "src/",
     "dist/",
     "scripts/"
   ],
@@ -43,5 +46,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d8b08e678cc0ac9a64ff2cb22e1387aacfdcba6a"
+  "gitHead": "cdbc876f793d96073d7eb0d09715a031ce0cd32e"
 }

package/scripts/check-secrets.js

@@ -1,15 +1,4 @@
 #!/usr/bin/env node
-/**
- * Secret/credential scanner for prompt templates.
- *
- * This is intentionally conservative: it only fails on patterns that strongly
- * resemble real credentials (or private key material) to avoid false positives.
- *
- * Scans:
- * - all .txt files under packages/prompts/prompts/
- * - all .txt files under plugin prompt folders (if plugins/ exists)
- */
-
 import fs from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -20,47 +9,102 @@ const __dirname = path.dirname(__filename);
 const PROMPTS_PKG_DIR = path.resolve(__dirname, "..");
 const REPO_ROOT = path.resolve(PROMPTS_PKG_DIR, "..", "..");
 
-const PROMPTS_DIR = path.join(PROMPTS_PKG_DIR, "prompts");
-const PLUGINS_DIR = path.join(REPO_ROOT, "plugins");
+const PROMPT_SCAN_TS_ROOTS = [
+  "packages/prompts/src",
+  "packages/core/src",
+  "plugins",
+];
+
+const PROMPT_SCAN_FILES = [
+  "packages/core/src/prompts.ts",
+  "packages/core/src/services/message.ts",
+  "plugins/plugin-music/src/actions/music-player-action-docs.ts",
+];
+
+const PROMPT_SCAN_FILE_PATTERNS = [
+  /(^|\/)prompts?\.ts$/,
+  /(^|\/)prompts\/[^/]+\.ts$/,
+  /(^|\/)workflow-prompts\/[^/]+\.ts$/,
+  /(^|\/)templates?\.ts$/,
+];
+
+const TEST_SOURCE_PATH_PATTERN =
+  /(^|\/)(__tests__|tests?|e2e)(\/|$)|\.(test|spec)\.tsx?$/;
+
+const SKIP_DIR_NAMES = new Set([
+  ".git",
+  ".turbo",
+  ".next",
+  "build",
+  "coverage",
+  "dist",
+  "node_modules",
+  "generated",
+]);
 
 /**
- * @param {string} dir
+ * @param {string} root
+ * @param {(absPath: string, relPath: string) => boolean} predicate
  * @returns {Promise<string[]>}
  */
-async function listPromptTxtFiles(dir) {
+export async function walkFiles(root, predicate) {
   /** @type {string[]} */
   const out = [];
 
   /** @param {string} current */
   async function walk(current) {
-    const entries = await fs.readdir(current, { withFileTypes: true });
+    /** @type {Awaited<ReturnType<typeof fs.readdir>>} */
+    let entries;
+    try {
+      entries = await fs.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
     for (const entry of entries) {
       const full = path.join(current, entry.name);
       if (entry.isDirectory()) {
+        if (SKIP_DIR_NAMES.has(entry.name)) continue;
         await walk(full);
         continue;
       }
-      if (entry.isFile() && entry.name.endsWith(".txt")) {
-        out.push(full);
-      }
+      if (!entry.isFile()) continue;
+      const rel = path.relative(REPO_ROOT, full);
+      if (predicate(full, rel)) out.push(full);
     }
   }
 
-  try {
-    await walk(dir);
-  } catch (_e) {
-    // Directory might not exist (e.g., plugins/ in minimal checkouts).
-  }
-
+  await walk(root);
   return out;
 }
 
+/**
+ * @returns {Promise<string[]>}
+ */
+export async function listPromptTsFiles() {
+  /** @type {Set<string>} */
+  const set = new Set();
+  for (const file of PROMPT_SCAN_FILES) {
+    set.add(path.join(REPO_ROOT, file));
+  }
+  for (const root of PROMPT_SCAN_TS_ROOTS) {
+    const absRoot = path.join(REPO_ROOT, root);
+    const files = await walkFiles(absRoot, (_abs, rel) => {
+      if (!rel.endsWith(".ts") && !rel.endsWith(".tsx")) return false;
+      if (TEST_SOURCE_PATH_PATTERN.test(rel)) return false;
+      if (/(^|\/)generated\//.test(rel)) return false;
+      return PROMPT_SCAN_FILE_PATTERNS.some((p) => p.test(rel));
+    });
+    for (const f of files) set.add(f);
+  }
+  return [...set].sort();
+}
+
 /**
  * @param {string} filePath
  * @param {string} content
  * @returns {{errors: string[], warnings: string[]}}
  */
-function scanContent(filePath, content) {
+export function scanContent(filePath, content) {
   /** @type {string[]} */
   const errors = [];
   /** @type {string[]} */
@@ -115,38 +159,28 @@ function scanContent(filePath, content) {
 
   for (let i = 0; i < lines.length; i++) {
     const line = lines[i];
+    let hasError = false;
+    /** @type {string[]} */
+    const lineWarnings = [];
     for (const rule of rules) {
       if (rule.re.test(line)) {
         const msg = `${filePath}:${i + 1}  ${rule.name}: ${line.trim()}`;
-        if (rule.severity === "error") errors.push(msg);
-        else warnings.push(msg);
+        if (rule.severity === "error") {
+          errors.push(msg);
+          hasError = true;
+        } else {
+          lineWarnings.push(msg);
+        }
       }
     }
+    if (!hasError) warnings.push(...lineWarnings);
   }
 
   return { errors, warnings };
 }
 
 async function main() {
-  const promptFiles = await listPromptTxtFiles(PROMPTS_DIR);
-
-  /** @type {string[]} */
-  let pluginPromptFiles = [];
-  try {
-    const pluginEntries = await fs.readdir(PLUGINS_DIR, {
-      withFileTypes: true,
-    });
-    for (const entry of pluginEntries) {
-      if (!entry.isDirectory()) continue;
-      const candidate = path.join(PLUGINS_DIR, entry.name, "prompts");
-      const files = await listPromptTxtFiles(candidate);
-      pluginPromptFiles = pluginPromptFiles.concat(files);
-    }
-  } catch {
-    // plugins directory missing; ok.
-  }
-
-  const allFiles = [...promptFiles, ...pluginPromptFiles].sort();
+  const allFiles = await listPromptTsFiles();
 
   /** @type {string[]} */
   const errors = [];
@@ -154,34 +188,36 @@ async function main() {
   const warnings = [];
 
   for (const file of allFiles) {
-    const content = await fs.readFile(file, "utf-8");
+    let content;
+    try {
+      content = await fs.readFile(file, "utf-8");
+    } catch {
+      continue;
+    }
     const result = scanContent(file, content);
     errors.push(...result.errors);
     warnings.push(...result.warnings);
   }
 
   if (warnings.length > 0) {
-    // eslint-disable-next-line no-console
     console.warn("\nPrompt secret scan warnings (review recommended):\n");
     for (const w of warnings) {
-      // eslint-disable-next-line no-console
       console.warn(`- ${w}`);
     }
   }
 
   if (errors.length > 0) {
-    // eslint-disable-next-line no-console
     console.error("\nPrompt secret scan errors (must fix):\n");
     for (const e of errors) {
-      // eslint-disable-next-line no-console
       console.error(`- ${e}`);
     }
     process.exit(1);
   }
 }
 
-main().catch((err) => {
-  // eslint-disable-next-line no-console
-  console.error(err);
-  process.exit(2);
-});
+if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(2);
+  });
+}

package/scripts/file-utils.js

@@ -0,0 +1,13 @@
+import fs from "node:fs";
+
+export function readText(filePath) {
+  return fs.readFileSync(filePath, "utf-8");
+}
+
+export function readJson(filePath) {
+  return JSON.parse(readText(filePath));
+}
+
+export function ensureDirectory(dir) {
+  fs.mkdirSync(dir, { recursive: true });
+}