prompt-language-shell 0.9.6 → 0.9.8

package/README.md

@@ -31,7 +31,7 @@ Here's what I can help with:
   - Configure - manage and configure system settings
   - Answer - respond to questions and provide information
   - Execute - run shell commands and process operations
-  ```
+```
 
 Skills are custom workflows you can define to teach `pls` about your specific
 projects and commands. Once defined, you can use them naturally:
@@ -87,16 +87,47 @@ commands your environment requires.
 
 ## Configuration
 
-Your configuration is stored in `~/.plsrc` as a YAML file. Supported settings:
+Your configuration is stored in `~/.plsrc` as a YAML file:
+
+```yaml
+# Mandatory
+anthropic:
+  key: sk-ant-...
+  model: claude-...
+
+# Optional
+settings:
+  memory: 1024 # Child process memory limit (MB)
+  debug: none # none | info | verbose
+
+# Custom
+project:
+  path: ~/projects/app
+```
+
+Skills can define their own configuration properties via a `Config` section. When
+a skill requires config values that don't exist, `pls` prompts you to provide
+them before execution. See [Skills](#skills) for details.
+
+## Reference
+
+### Debug Mode
+Press `Shift+Tab` during execution to cycle through debug levels
+(none → info → verbose).
+Logs are saved to `~/.pls/logs/` when debug is `info` or `verbose`.
 
-- `anthropic.key` - Your API key
-- `anthropic.model` - The model to use
+### Data Locations
+```
+~/.plsrc              # Configuration
+~/.pls/skills/        # Custom skills
+~/.pls/logs/          # Debug logs
+```
 
 ## Skills
 
 Skills let you teach `pls` about your project-specific workflows. Create
-markdown files in `~/.pls/skills/` to define custom operations that `pls` can
-understand and execute.
+markdown files in `~/.pls/skills/` to define custom operations that
+`pls` can understand and execute.
 
 For complete documentation, see [docs/SKILLS.md](./docs/SKILLS.md).
 

package/dist/components/controllers/Execute.js

@@ -139,9 +139,9 @@ export function Execute({ tasks: inputTasks, status, service, upcoming, label, r
                     lifecycleHandlers.completeActive();
                     return;
                 }
-                // Create task data from commands
-                const tasks = result.commands.map((cmd, index) => ({
-                    label: inputTasks[index]?.action ?? cmd.description,
+                // Create task data from commands - use descriptions from execute response
+                const tasks = result.commands.map((cmd) => ({
+                    label: cmd.description,
                     command: cmd,
                     status: ExecutionStatus.Pending,
                     elapsed: 0,

package/dist/components/views/Output.js

@@ -4,15 +4,21 @@ import { Palette } from '../../services/colors.js';
 import { ExecutionStatus } from '../../services/shell.js';
 const MAX_LINES = 8;
 const MAX_WIDTH = 75;
-const SHORT_OUTPUT_THRESHOLD = 4;
 const MINIMAL_INFO_THRESHOLD = 2;
 /**
- * Get the last N lines from text, filtering out empty/whitespace-only lines
+ * Get the last N lines from text, filtering out empty/whitespace-only lines.
+ * Handles carriage returns used in progress output by keeping only the
+ * content after the last \r in each line.
  */
 export function getLastLines(text, maxLines = MAX_LINES) {
     const lines = text
         .trim()
         .split(/\r?\n/)
+        .map((line) => {
+        // Handle carriage returns: keep only content after the last \r
+        const lastCR = line.lastIndexOf('\r');
+        return lastCR >= 0 ? line.slice(lastCR + 1) : line;
+    })
         .filter((line) => line.trim().length > 0);
     return lines.length <= maxLines ? lines : lines.slice(-maxLines);
 }
@@ -29,9 +35,6 @@ export function computeDisplayConfig(stdout, stderr, status, isFinished) {
     const stderrLines = hasStderr ? getLastLines(stderr) : [];
     // Show stdout if no stderr, or if stderr is minimal (provides context)
     const showStdout = hasStdout && (!hasStderr || stderrLines.length <= MINIMAL_INFO_THRESHOLD);
-    // Use word wrapping for short outputs to show more detail
-    const totalLines = stdoutLines.length + stderrLines.length;
-    const wrapMode = totalLines <= SHORT_OUTPUT_THRESHOLD ? 'wrap' : 'truncate-end';
     // Darker colors for finished tasks
     const baseColor = isFinished ? Palette.DarkGray : Palette.Gray;
     const stderrColor = status === ExecutionStatus.Failed ? Palette.Yellow : baseColor;
@@ -39,7 +42,6 @@ export function computeDisplayConfig(stdout, stderr, status, isFinished) {
         stdoutLines,
         stderrLines,
         showStdout,
-        wrapMode,
         stdoutColor: baseColor,
         stderrColor,
     };
@@ -48,7 +50,7 @@ export function Output({ stdout, stderr, status, isFinished }) {
     const config = computeDisplayConfig(stdout, stderr, status, isFinished ?? false);
     if (!config)
         return null;
-    const { stdoutLines, stderrLines, showStdout, wrapMode, stdoutColor, stderrColor, } = config;
+    const { stdoutLines, stderrLines, showStdout, stdoutColor, stderrColor } = config;
     return (_jsxs(Box, { marginTop: 1, marginLeft: 5, flexDirection: "column", width: MAX_WIDTH, children: [showStdout &&
-                stdoutLines.map((line, index) => (_jsx(Text, { color: stdoutColor, wrap: wrapMode, children: line }, `out-${index}`))), stderrLines.map((line, index) => (_jsx(Text, { color: stderrColor, wrap: wrapMode, children: line }, `err-${index}`)))] }));
+                stdoutLines.map((line, index) => (_jsx(Text, { color: stdoutColor, wrap: "wrap", children: line }, `out-${index}`))), stderrLines.map((line, index) => (_jsx(Text, { color: stderrColor, wrap: "wrap", children: line }, `err-${index}`)))] }));
 }

package/dist/configuration/io.js

@@ -104,3 +104,13 @@ export function loadDebugSetting(fs = defaultFileSystem) {
         return DebugLevel.None;
     }
 }
+const DEFAULT_MEMORY_LIMIT = 1024;
+export function loadMemorySetting(fs = defaultFileSystem) {
+    try {
+        const config = loadConfig(fs);
+        return config.settings?.memory ?? DEFAULT_MEMORY_LIMIT;
+    }
+    catch {
+        return DEFAULT_MEMORY_LIMIT;
+    }
+}

package/dist/configuration/schema.js

@@ -38,6 +38,12 @@ const coreConfigSchema = {
         default: DebugLevel.None,
         description: 'Debug mode',
     },
+    'settings.memory': {
+        type: ConfigDefinitionType.Number,
+        required: false,
+        default: 1024,
+        description: 'Child process memory limit (MB)',
+    },
 };
 /**
  * Get complete configuration schema

package/dist/configuration/validation.js

@@ -37,6 +37,11 @@ export function validateConfig(parsed) {
                 validatedConfig.settings.debug = settings.debug;
             }
         }
+        if ('memory' in settings) {
+            if (typeof settings.memory === 'number' && settings.memory > 0) {
+                validatedConfig.settings.memory = settings.memory;
+            }
+        }
     }
     return validatedConfig;
 }

package/dist/execution/processing.js

@@ -1,3 +1,5 @@
+import { stringify } from 'yaml';
+import { loadMemorySetting } from '../configuration/io.js';
 import { loadUserConfig } from '../services/loader.js';
 import { replacePlaceholders } from '../services/resolver.js';
 import { validatePlaceholderResolution } from './validation.js';
@@ -10,6 +12,36 @@ export function fixEscapedQuotes(command) {
     // Replace ="value" with =\"value\"
     return command.replace(/="([^"]*)"/g, '=\\"$1\\"');
 }
+/**
+ * Format a task as YAML with action line and metadata block
+ */
+export function formatTaskAsYaml(action, metadata, indent = '') {
+    const normalizedAction = action.charAt(0).toLowerCase() + action.slice(1);
+    if (!metadata || Object.keys(metadata).length === 0) {
+        return normalizedAction;
+    }
+    const metadataYaml = stringify({ metadata })
+        .trim()
+        .split('\n')
+        .map((line) => `${indent}${line}`)
+        .join('\n');
+    return `${normalizedAction}\n\n${metadataYaml}`;
+}
+/**
+ * Build task descriptions for the LLM
+ * Single task: use as-is; multiple tasks: add header and bullet prefix
+ */
+function buildTaskDescriptions(resolvedTasks) {
+    if (resolvedTasks.length === 1) {
+        const { action, params } = resolvedTasks[0];
+        return formatTaskAsYaml(action, params);
+    }
+    const header = `complete these ${resolvedTasks.length} tasks:`;
+    const bulletedTasks = resolvedTasks
+        .map(({ action, params }) => `- ${formatTaskAsYaml(action, params, '  ')}`)
+        .join('\n\n');
+    return `${header}\n\n${bulletedTasks}`;
+}
 /**
  * Processes tasks through the AI service to generate executable commands.
  * Resolves placeholders in task descriptions and validates the results.
@@ -17,27 +49,26 @@ export function fixEscapedQuotes(command) {
 export async function processTasks(tasks, service) {
     // Load user config for placeholder resolution
     const userConfig = loadUserConfig();
-    // Format tasks for the execute tool and resolve placeholders
-    const taskList = tasks
-        .map((task) => {
-        const resolvedAction = replacePlaceholders(task.action, userConfig);
-        const params = task.params
-            ? ` (params: ${JSON.stringify(task.params)})`
-            : '';
-        return `- ${resolvedAction}${params}`;
-    })
-        .join('\n');
-    // Build message with confirmed schedule header
-    const taskDescriptions = `Confirmed schedule (${tasks.length} tasks):\n${taskList}`;
+    const memoryLimitMB = loadMemorySetting();
+    // Resolve placeholders in task actions
+    const resolvedTasks = tasks.map((task) => ({
+        action: replacePlaceholders(task.action, userConfig),
+        params: task.params,
+    }));
+    const taskDescriptions = buildTaskDescriptions(resolvedTasks);
     // Call execute tool to get commands
     const result = await service.processWithTool(taskDescriptions, 'execute');
-    // Resolve placeholders in command strings
+    // Resolve placeholders in command strings and inject memory limit
     const resolvedCommands = (result.commands || []).map((cmd) => {
         // Fix escaped quotes lost in JSON parsing
         const fixed = fixEscapedQuotes(cmd.command);
         const resolved = replacePlaceholders(fixed, userConfig);
         validatePlaceholderResolution(resolved);
-        return { ...cmd, command: resolved };
+        return {
+            ...cmd,
+            command: resolved,
+            memoryLimit: memoryLimitMB,
+        };
     });
     return {
         message: result.message,

package/dist/execution/runner.js

@@ -70,7 +70,7 @@ export async function executeTask(command, index, callbacks) {
             return { status: ExecutionStatus.Success, elapsed, output };
         }
         else {
-            const errorMsg = result.errors || result.error || 'Command failed';
+            const errorMsg = result.error || result.errors || 'Command failed';
             error = errorMsg;
             const output = createOutput();
             callbacks.onUpdate(output);

package/dist/index.js

@@ -5,7 +5,9 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { render } from 'ink';
 import { DebugLevel } from './configuration/types.js';
+import { preventPerformanceBufferOverflow } from './services/performance.js';
 import { Main } from './Main.js';
+preventPerformanceBufferOverflow();
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 // Get package info

package/dist/services/filesystem.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'fs';
+import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'fs';
 import { dirname } from 'path';
 /**
  * Real filesystem implementation using Node's fs module
@@ -13,6 +13,9 @@ export class RealFileSystem {
     writeFile(path, data) {
         writeFileSync(path, data, 'utf-8');
     }
+    appendFile(path, data) {
+        appendFileSync(path, data, 'utf-8');
+    }
     readDirectory(path) {
         return readdirSync(path);
     }
@@ -51,6 +54,15 @@ export class MemoryFileSystem {
         }
         this.files.set(path, data);
     }
+    appendFile(path, data) {
+        // Auto-create parent directories (consistent with writeFile)
+        const dir = dirname(path);
+        if (dir !== '.' && dir !== path) {
+            this.createDirectory(dir, { recursive: true });
+        }
+        const existing = this.files.get(path) ?? '';
+        this.files.set(path, existing + data);
+    }
     readDirectory(path) {
         if (!this.directories.has(path)) {
             throw new Error(`ENOENT: no such file or directory, scandir '${path}'`);

package/dist/services/logger.js

@@ -1,7 +1,10 @@
+import { homedir, platform } from 'os';
+import { dirname, join } from 'path';
 import { DebugLevel } from '../configuration/types.js';
 import { loadDebugSetting } from '../configuration/io.js';
 import { Palette } from './colors.js';
 import { createDebug } from './components.js';
+import { defaultFileSystem } from './filesystem.js';
 /**
  * Enum controlling what content is shown in debug prompt output
  * - LLM: Exact prompt as sent to LLM (no display formatting)
@@ -23,6 +26,112 @@ let currentDebugLevel = DebugLevel.None;
  * Accumulated warnings to be displayed in the timeline
  */
 const warnings = [];
+/**
+ * Content width for debug display (matches Debug component)
+ * Box width 80 - 2 borders - 4 padding = 74 chars
+ */
+const DISPLAY_CONTENT_WIDTH = 74;
+/**
+ * File logging configuration
+ */
+const LOGS_DIR = join(homedir(), '.pls', 'logs');
+/**
+ * Whether running on Windows (affects filename separators)
+ */
+const IS_WINDOWS = platform() === 'win32';
+/**
+ * Maximum number of letter suffixes (a-z) for unique filenames
+ */
+const MAX_LETTER_SUFFIXES = 26;
+/**
+ * Pad a number with leading zeros to the specified width
+ */
+const pad = (n, width = 2) => String(n).padStart(width, '0');
+/**
+ * Current session's log file path (null until first log entry)
+ */
+let currentLogFile = null;
+/**
+ * Filesystem instance for file operations (injectable for testing)
+ */
+let fileSystem = defaultFileSystem;
+/**
+ * Set the filesystem instance (used for testing)
+ */
+export function setFileSystem(fs) {
+    fileSystem = fs;
+}
+/**
+ * Reset the session log file (used for testing)
+ */
+export function resetSessionLog() {
+    currentLogFile = null;
+}
+/**
+ * Generate a timestamped log file path using local time
+ * Format: ~/.pls/logs/YYYY-MM-DD/HH:MM:SS.log.md (HH-MM-SS on Windows)
+ */
+function getLogFilePath() {
+    const now = new Date();
+    const date = `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+    const separator = IS_WINDOWS ? '-' : ':';
+    const time = `${pad(now.getHours())}${separator}${pad(now.getMinutes())}${separator}${pad(now.getSeconds())}`;
+    return join(LOGS_DIR, date, `${time}.log.md`);
+}
+/**
+ * Generate a unique log file path by adding suffix if file exists
+ */
+function getUniqueLogFilePath(basePath) {
+    if (!fileSystem.exists(basePath)) {
+        return basePath;
+    }
+    const dir = dirname(basePath);
+    const ext = '.log.md';
+    const name = basePath.slice(dir.length + 1, -ext.length);
+    for (let i = 0; i < MAX_LETTER_SUFFIXES; i++) {
+        const suffix = String.fromCharCode(97 + i); // a-z
+        const candidate = join(dir, `${name}-${suffix}${ext}`);
+        if (!fileSystem.exists(candidate)) {
+            return candidate;
+        }
+    }
+    // Fallback: use milliseconds for uniqueness (avoids overwriting)
+    return join(dir, `${name}-${pad(new Date().getMilliseconds(), 3)}${ext}`);
+}
+/**
+ * Initialize the session log file if not already created
+ */
+function initializeSessionLog() {
+    if (currentLogFile)
+        return true;
+    try {
+        const basePath = getLogFilePath();
+        const logDir = dirname(basePath);
+        if (!fileSystem.exists(logDir)) {
+            fileSystem.createDirectory(logDir, { recursive: true });
+        }
+        const logPath = getUniqueLogFilePath(basePath);
+        fileSystem.writeFile(logPath, '');
+        currentLogFile = logPath;
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Append content to the current session's log file
+ */
+function appendToLog(content) {
+    if (!initializeSessionLog() || !currentLogFile)
+        return;
+    try {
+        fileSystem.appendFile(currentLogFile, content);
+    }
+    catch {
+        // Silently fail - logging should not crash the app
+    }
+}
 /**
  * Initialize the logger with the current debug level from config
  */
@@ -61,11 +170,6 @@ export function getWarnings() {
     warnings.length = 0;
     return result;
 }
-/**
- * Content width for debug display (matches Debug component)
- * Box width 80 - 2 borders - 4 padding = 74 chars
- */
-const DISPLAY_CONTENT_WIDTH = 74;
 /**
  * Join sections with separators matching display width
  */
@@ -142,28 +246,28 @@ function formatSkillsForDisplay(formattedSkills) {
  * - Summary: Returns header + skill summaries (Name, Steps, Execution)
  */
 export function formatPromptContent(toolName, command, baseInstructions, formattedSkills, mode, definitions) {
-    const header = ['', `Tool: ${toolName}`, `Command: ${command}`];
     switch (mode) {
-        case PromptDisplay.LLM:
+        case PromptDisplay.LLM: {
+            const header = ['', `**Tool:** ${toolName}`];
             return [...header, '', baseInstructions + formattedSkills].join('\n');
+        }
         case PromptDisplay.Skills: {
-            // Layout: header -> separator -> skills with visual separators
-            const headerString = header.join('\n');
+            const header = `\nTool: ${toolName}\nCommand: ${command}`;
             const skillsDisplay = formatSkillsForDisplay(formattedSkills);
-            return joinWithSeparators([headerString, skillsDisplay]);
+            return joinWithSeparators([header, skillsDisplay]);
         }
         case PromptDisplay.Summary: {
-            const headerString = header.join('\n');
+            const header = `\nTool: ${toolName}\nCommand: ${command}`;
             const summary = definitions
                 ? formatSkillsSummary(definitions)
                 : '(no skills)';
-            return joinWithSeparators([headerString, summary]);
+            return joinWithSeparators([header, summary]);
         }
     }
 }
 /**
  * Create debug component for system prompts sent to the LLM
- * Only creates at Verbose level
+ * Creates UI component at Verbose level, writes to file at Info or Verbose
  *
  * @param toolName - Name of the tool being invoked
  * @param command - User command being processed
@@ -172,6 +276,13 @@ export function formatPromptContent(toolName, command, baseInstructions, formatt
  * @param definitions - Parsed skill definitions for summary display
  */
 export function logPrompt(toolName, command, baseInstructions, formattedSkills, definitions = []) {
+    // Write to file at Info or Verbose level (full LLM format)
+    if (currentDebugLevel !== DebugLevel.None) {
+        const userPrompt = `# User Command\n\n\`\`\`\n${command}\n\`\`\`\n\n`;
+        const fileContent = formatPromptContent(toolName, command, baseInstructions, formattedSkills, PromptDisplay.LLM);
+        appendToLog(userPrompt + '# System Prompt\n' + fileContent + '\n\n');
+    }
+    // Create UI component only at Verbose level
     if (currentDebugLevel !== DebugLevel.Verbose) {
         return null;
     }
@@ -185,18 +296,27 @@ export function logPrompt(toolName, command, baseInstructions, formattedSkills,
 }
 /**
  * Create debug component for LLM responses received
- * Only creates at Verbose level
+ * Creates UI component at Verbose level, writes to file at Info or Verbose
  */
 export function logResponse(toolName, response, durationMs) {
+    const jsonContent = JSON.stringify(response, null, 2);
+    // Write to file at Info or Verbose level (markdown format)
+    if (currentDebugLevel !== DebugLevel.None) {
+        const fileContent = [
+            '',
+            `**Tool:** ${toolName}`,
+            '',
+            '```json',
+            jsonContent,
+            '```',
+        ].join('\n');
+        appendToLog('# LLM Response\n' + fileContent + '\n\n');
+    }
+    // Create UI component only at Verbose level
     if (currentDebugLevel !== DebugLevel.Verbose) {
         return null;
     }
-    const content = [
-        '',
-        `Tool: ${toolName}`,
-        '',
-        JSON.stringify(response, null, 2),
-    ].join('\n');
+    const content = ['', `Tool: ${toolName}`, '', jsonContent].join('\n');
     const title = `LLM RESPONSE (${String(durationMs)} ms)`;
     return createDebug({ title, content, color: Palette.LightGray });
 }

package/dist/services/messages.js

@@ -148,11 +148,14 @@ export function formatErrorMessage(error) {
     return rawMessage;
 }
 /**
- * Returns an execution error message with varied phrasing.
- * Error details are shown in the task output, so this is just a summary.
- * Randomly selects from variations to sound natural.
+ * Returns an execution error message.
+ * If a specific error is provided, returns it directly.
+ * Otherwise, returns a generic failure message with varied phrasing.
  */
-export function getExecutionErrorMessage(_error) {
+export function getExecutionErrorMessage(error) {
+    if (error) {
+        return error;
+    }
     const messages = [
         'The execution failed.',
         'Execution has failed.',

package/dist/services/monitor.js

@@ -0,0 +1,288 @@
+import { execFile, execSync } from 'child_process';
+import { existsSync, readFileSync } from 'fs';
+import { platform } from 'os';
+import { promisify } from 'util';
+// Memory monitoring constants
+const MEMORY_CHECK_INTERVAL = 1000;
+const DEFAULT_PAGE_SIZE = 4096;
+export const SIGKILL_GRACE_PERIOD = 3000;
+/**
+ * Get system page size in bytes.
+ * Computed lazily on first call, then cached at module level.
+ */
+let cachedPageSize;
+function getPageSize() {
+    if (cachedPageSize !== undefined) {
+        return cachedPageSize;
+    }
+    if (platform() === 'linux') {
+        try {
+            const output = execSync('getconf PAGESIZE', {
+                encoding: 'utf-8',
+                timeout: 1000,
+            }).trim();
+            const size = parseInt(output, 10);
+            if (!isNaN(size) && size > 0) {
+                cachedPageSize = size;
+                return cachedPageSize;
+            }
+        }
+        catch {
+            // Fall through to default
+        }
+    }
+    cachedPageSize = DEFAULT_PAGE_SIZE;
+    return cachedPageSize;
+}
+/**
+ * Gracefully terminate a child process with SIGTERM, escalating to SIGKILL
+ * after a grace period if the process doesn't terminate.
+ * Returns the kill timeout ID for cleanup.
+ */
+export function killGracefully(child, gracePeriod = SIGKILL_GRACE_PERIOD) {
+    child.kill('SIGTERM');
+    return setTimeout(() => {
+        try {
+            child.kill('SIGKILL');
+        }
+        catch {
+            // Process already terminated
+        }
+    }, gracePeriod);
+}
+const execFileAsync = promisify(execFile);
+/**
+ * Run a command asynchronously and return stdout.
+ * Returns undefined on error or timeout.
+ */
+async function runCommandAsync(command, args, timeout = 1000) {
+    try {
+        const { stdout } = await execFileAsync(command, args, { timeout });
+        return stdout.trim();
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get memory usage of a process in bytes.
+ * Returns undefined if the process doesn't exist or memory can't be read.
+ * On macOS, uses async subprocess; on Linux, reads from /proc (fast).
+ */
+async function getProcessMemoryBytes(pid) {
+    try {
+        if (platform() === 'linux') {
+            // Linux: Read from /proc/[pid]/statm (memory in pages)
+            // This is fast and effectively non-blocking for procfs
+            const statmPath = `/proc/${pid}/statm`;
+            if (!existsSync(statmPath))
+                return undefined;
+            const statm = readFileSync(statmPath, 'utf-8');
+            const rssPages = parseInt(statm.split(' ')[1], 10);
+            return rssPages * getPageSize();
+        }
+        else {
+            // macOS/BSD: Use ps command asynchronously
+            const output = await runCommandAsync('ps', [
+                '-o',
+                'rss=',
+                '-p',
+                `${pid}`,
+            ]);
+            if (!output)
+                return undefined;
+            const rssKB = parseInt(output, 10);
+            if (isNaN(rssKB))
+                return undefined;
+            return rssKB * 1024;
+        }
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Get child PIDs of a single process.
+ */
+async function getChildPids(pid) {
+    try {
+        let output;
+        if (platform() === 'linux') {
+            output = await runCommandAsync('ps', ['-o', 'pid=', '--ppid', `${pid}`]);
+        }
+        else {
+            output = await runCommandAsync('pgrep', ['-P', `${pid}`]);
+        }
+        if (!output)
+            return [];
+        return output
+            .split('\n')
+            .map((p) => parseInt(p.trim(), 10))
+            .filter((p) => !isNaN(p) && p > 0);
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Get all descendant PIDs of a process.
+ * Uses iterative BFS with parallel child lookups at each level.
+ */
+async function getAllDescendantPids(pid) {
+    const visited = new Set();
+    const pids = [];
+    let currentLevel = [pid];
+    while (currentLevel.length > 0) {
+        // Add unvisited PIDs from current level
+        const unvisited = currentLevel.filter((p) => !visited.has(p));
+        for (const p of unvisited)
+            visited.add(p);
+        pids.push(...unvisited);
+        // Fetch children of all current level PIDs in parallel
+        const childArrays = await Promise.all(unvisited.map(getChildPids));
+        currentLevel = childArrays.flat();
+    }
+    return pids;
+}
+/**
+ * Get total memory usage of a process tree.
+ * Sums memory of the process and all its descendants.
+ */
+async function getProcessTreeMemoryBytes(pid) {
+    try {
+        const allPids = await getAllDescendantPids(pid);
+        let totalBytes = 0;
+        for (const p of allPids) {
+            const mem = await getProcessMemoryBytes(p);
+            if (mem)
+                totalBytes += mem;
+        }
+        return totalBytes > 0 ? totalBytes : undefined;
+    }
+    catch {
+        return getProcessMemoryBytes(pid);
+    }
+}
+/** Monitor lifecycle state */
+var MonitorState;
+(function (MonitorState) {
+    MonitorState["Idle"] = "idle";
+    MonitorState["Running"] = "running";
+    MonitorState["Stopped"] = "stopped";
+    MonitorState["Killed"] = "killed";
+})(MonitorState || (MonitorState = {}));
+/**
+ * Monitors a child process memory and kills it when the limit is exceeded.
+ * Uses async self-scheduling to avoid blocking the event loop.
+ * By default monitors only the root process; set includeDescendants for tree.
+ */
+export class MemoryMonitor {
+    nextCheckId;
+    killTimeoutId;
+    child;
+    memoryLimit;
+    limitBytes;
+    onExceeded;
+    state = MonitorState.Idle;
+    getMemoryFn;
+    constructor(child, memoryLimitMB, onExceeded, getMemoryFn) {
+        this.child = child;
+        this.memoryLimit = memoryLimitMB;
+        this.limitBytes = memoryLimitMB * 1024 * 1024;
+        this.onExceeded = onExceeded;
+        // Always monitor full process tree by default
+        this.getMemoryFn = getMemoryFn ?? getProcessTreeMemoryBytes;
+    }
+    /**
+     * Start monitoring the child process memory.
+     * Uses async self-scheduling loop instead of setInterval for non-blocking.
+     */
+    start() {
+        if (!this.child.pid)
+            return;
+        this.state = MonitorState.Running;
+        this.scheduleNextCheck();
+    }
+    /**
+     * Schedule the next memory check after the configured interval.
+     */
+    scheduleNextCheck() {
+        if (this.state !== MonitorState.Running)
+            return;
+        this.nextCheckId = setTimeout(() => {
+            void this.checkMemory();
+        }, MEMORY_CHECK_INTERVAL);
+    }
+    /**
+     * Perform async memory check and schedule next one.
+     */
+    async checkMemory() {
+        if (this.state !== MonitorState.Running || !this.child.pid)
+            return;
+        let memoryBytes;
+        try {
+            memoryBytes = await this.getMemoryFn(this.child.pid);
+        }
+        catch {
+            // Memory reading failed, schedule next check and continue
+            this.scheduleNextCheck();
+            return;
+        }
+        // Re-check after async operation - state may have changed
+        if (this.state !== MonitorState.Running)
+            return; // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+        if (memoryBytes !== undefined && memoryBytes >= this.limitBytes) {
+            this.terminateProcess(memoryBytes);
+        }
+        else {
+            this.scheduleNextCheck();
+        }
+    }
+    /**
+     * Stop monitoring and cancel any pending timeouts.
+     */
+    stop() {
+        if (this.state !== MonitorState.Killed) {
+            this.state = MonitorState.Stopped;
+        }
+        if (this.nextCheckId) {
+            clearTimeout(this.nextCheckId);
+            this.nextCheckId = undefined;
+        }
+        if (this.killTimeoutId) {
+            clearTimeout(this.killTimeoutId);
+            this.killTimeoutId = undefined;
+        }
+    }
+    /**
+     * Terminate the child process due to memory limit exceeded.
+     */
+    terminateProcess(currentMemoryBytes) {
+        if (this.state === MonitorState.Killed)
+            return;
+        this.state = MonitorState.Killed;
+        // Clear only the next check timeout, keep killTimeoutId for cleanup
+        if (this.nextCheckId) {
+            clearTimeout(this.nextCheckId);
+            this.nextCheckId = undefined;
+        }
+        // Kill first, then notify - ensures termination even if callback throws
+        this.killTimeoutId = killGracefully(this.child);
+        const info = {
+            used: Math.ceil(currentMemoryBytes / 1024 / 1024),
+            limit: this.memoryLimit,
+        };
+        try {
+            this.onExceeded?.(info);
+        }
+        catch {
+            // Ignore callback errors - kill already initiated
+        }
+    }
+    /**
+     * Check if the process was killed due to memory limit.
+     */
+    wasKilledByMemoryLimit() {
+        return this.state === MonitorState.Killed;
+    }
+}

package/dist/services/performance.js

@@ -0,0 +1,14 @@
+import { performance } from 'perf_hooks';
+/**
+ * Prevent perf_hooks memory leak warning during long-running operations.
+ * React and Ink create performance measurements internally that accumulate
+ * in the global buffer. This clears them immediately and periodically.
+ */
+export function preventPerformanceBufferOverflow(intervalMs = 60000) {
+    performance.clearMarks();
+    performance.clearMeasures();
+    setInterval(() => {
+        performance.clearMarks();
+        performance.clearMeasures();
+    }, intervalMs).unref();
+}

package/dist/services/refinement.js

@@ -1,5 +1,5 @@
 import { ComponentStatus, } from '../types/components.js';
-import { TaskType } from '../types/types.js';
+import { formatTaskAsYaml } from '../execution/processing.js';
 import { createCommand, createRefinement } from './components.js';
 import { formatErrorMessage, getRefiningMessage } from './messages.js';
 import { routeTasksWithConfirm } from './router.js';
@@ -22,18 +22,15 @@ export async function handleRefinement(selectedTasks, service, originalCommand,
     });
     workflowHandlers.addToQueue(refinementDef);
     try {
-        // Build refined command from selected tasks
+        // Build refined command with action line followed by YAML metadata
         const refinedCommand = selectedTasks
             .map((task) => {
+            // Replace commas with dashes for cleaner LLM prompt formatting
             const action = task.action.replace(/,/g, ' -');
-            const type = task.type;
-            // For execute/group tasks, use generic hint - let LLM decide based on skill
-            if (type === TaskType.Execute || type === TaskType.Group) {
-                return `${action} (shell execution)`;
-            }
-            return `${action} (type: ${type})`;
+            const metadata = { ...task.params, type: task.type };
+            return formatTaskAsYaml(action, metadata);
         })
-            .join(', ');
+            .join('\n\n');
         // Call LLM to refine plan with selected tasks
         const refinedResult = await service.processWithTool(refinedCommand, 'schedule');
         // Complete the Refinement component with success state

package/dist/services/shell.js

@@ -1,4 +1,5 @@
 import { spawn } from 'child_process';
+import { killGracefully, MemoryMonitor, } from './monitor.js';
 export var ExecutionStatus;
 (function (ExecutionStatus) {
     ExecutionStatus["Pending"] = "pending";
@@ -60,12 +61,12 @@ export class DummyExecutor {
     }
 }
 // Marker for extracting pwd from command output
-const PWD_MARKER = '__PWD_MARKER_7x9k2m__';
-const MAX_OUTPUT_LINES = 128;
+export const PWD_MARKER = '__PWD_MARKER_7x9k2m__';
+export const MAX_OUTPUT_LINES = 128;
 /**
  * Limit output to last MAX_OUTPUT_LINES lines.
  */
-function limitLines(output) {
+export function limitLines(output) {
     const lines = output.split('\n');
     return lines.slice(-MAX_OUTPUT_LINES).join('\n');
 }
@@ -73,7 +74,7 @@ function limitLines(output) {
  * Parse stdout to extract workdir and clean output.
  * Returns the cleaned output and the extracted workdir.
  */
-function parseWorkdir(rawOutput) {
+export function parseWorkdir(rawOutput) {
     const markerIndex = rawOutput.lastIndexOf(PWD_MARKER);
     if (markerIndex === -1) {
         return { output: rawOutput };
@@ -88,7 +89,7 @@ function parseWorkdir(rawOutput) {
  * Manages streaming output while filtering out the PWD marker.
  * Buffers output to avoid emitting partial markers to the callback.
  */
-class OutputStreamer {
+export class OutputStreamer {
     chunks = [];
     emittedLength = 0;
     callback;
@@ -183,18 +184,22 @@ export class RealExecutor {
                 return;
             }
             // Handle timeout if specified
-            const SIGKILL_GRACE_PERIOD = 3000;
             let timeoutId;
             let killTimeoutId;
             if (cmd.timeout && cmd.timeout > 0) {
                 timeoutId = setTimeout(() => {
-                    child.kill('SIGTERM');
-                    // Escalate to SIGKILL if process doesn't terminate
-                    killTimeoutId = setTimeout(() => {
-                        child.kill('SIGKILL');
-                    }, SIGKILL_GRACE_PERIOD);
+                    killTimeoutId = killGracefully(child);
                 }, cmd.timeout);
             }
+            // Handle memory limit monitoring
+            let memoryMonitor;
+            let memoryInfo;
+            if (cmd.memoryLimit) {
+                memoryMonitor = new MemoryMonitor(child, cmd.memoryLimit, (info) => {
+                    memoryInfo = info;
+                });
+                memoryMonitor.start();
+            }
             // Use OutputStreamer for buffered stdout streaming
             const stdoutStreamer = new OutputStreamer(this.outputCallback);
             child.stdout.on('data', (data) => {
@@ -217,6 +222,7 @@ export class RealExecutor {
                     clearTimeout(timeoutId);
                 if (killTimeoutId)
                     clearTimeout(killTimeoutId);
+                memoryMonitor?.stop();
                 const commandResult = {
                     description: cmd.description,
                     command: cmd.command,
@@ -228,20 +234,32 @@ export class RealExecutor {
                 onProgress?.(ExecutionStatus.Failed);
                 resolve(commandResult);
             });
-            child.on('close', (code) => {
+            child.on('exit', (code) => {
                 if (timeoutId)
                     clearTimeout(timeoutId);
                 if (killTimeoutId)
                     clearTimeout(killTimeoutId);
-                const success = code === 0;
+                memoryMonitor?.stop();
                 const { output, workdir } = parseWorkdir(stdoutStreamer.getAccumulated());
+                // Check if terminated due to memory limit
+                const killedByMemoryLimit = memoryMonitor?.wasKilledByMemoryLimit();
+                const success = code === 0 && !killedByMemoryLimit;
+                let errorMessage;
+                if (killedByMemoryLimit && memoryInfo) {
+                    errorMessage =
+                        `Process exceeded ${memoryInfo.limit} MB memory limit, ` +
+                            `${memoryInfo.used} MB was used.`;
+                }
+                else if (!success) {
+                    errorMessage = `Exit code: ${code}`;
+                }
                 const commandResult = {
                     description: cmd.description,
                     command: cmd.command,
                     output,
                     errors: limitLines(stderr.join('')),
                     result: success ? ExecutionResult.Success : ExecutionResult.Error,
-                    error: success ? undefined : `Exit code: ${code}`,
+                    error: errorMessage,
                     workdir,
                 };
                 onProgress?.(success ? ExecutionStatus.Success : ExecutionStatus.Failed);

package/dist/skills/execute.md

@@ -100,14 +100,28 @@ position.
 
 ### How to Generate Commands from Skills
 
+**CRITICAL - ONE TASK = ONE COMMAND**: Each input task maps to exactly
+ONE command in your response. The task's action tells you WHICH specific
+step from the skill to use. Do NOT expand an entire skill workflow for
+a single task - only generate the command for that specific step.
+
 1. **Identify skill tasks**: Check if tasks have params.skill
 2. **Find the skill**: Look up the skill in "Available Skills" section
    below (REQUIRED - must exist)
-3. **Match tasks to Execution**: Each task action came from a Steps line;
-   use the corresponding Execution line for the command
-4. **Substitute parameters**: Replace {PARAM} placeholders with actual
+3. **Match task action to skill step**: The task action describes which
+   step from the skill's Steps section this task represents. Find the
+   matching step by semantic meaning (e.g., "Export results" matches
+   "Export the results to {FORMAT}", NOT all three steps of the skill)
+4. **Use corresponding Execution line**: Once you identify which step
+   the task represents, use ONLY that step's corresponding Execution line
+5. **Substitute parameters**: Replace {PARAM} placeholders with actual
    values from task params
 
+**IMPORTANT**: If the schedule contains separate tasks for different
+steps of the same skill (e.g., one task for fetching data, another for
+exporting), each task produces its own single command. Do NOT combine
+them or add steps that weren't scheduled.
+
 ### Example Skill
 
 ```markdown
@@ -151,6 +165,28 @@ steps 1 and 3 (with step 2 skipped), use Execution lines 1 and 3
 which Execution line to use - always match by original position, never
 by sequential task index.
 
+### Expanding Skill References in Execution Lines
+
+Execution lines may contain **skill references** in the format
+`[ Skill Name ]`. These are references to other skills that must be
+expanded to actual commands before execution.
+
+**Format**: `[ Skill Name ]` with spaces inside the brackets
+
+**How to expand**:
+1. When an Execution line contains `[ Skill Name ]`, look up that skill
+   in the "Available Skills" section
+2. Get the referenced skill's Execution command
+3. Replace the `[ Skill Name ]` reference with the actual command
+
+**IMPORTANT**: Skill references are the ONLY exception to the verbatim
+execution rule below. You MUST expand them - never output `[ ... ]`
+syntax in the final command.
+
+**Note**: Use the `skill:` field from task metadata to find the skill
+definition. If that skill's Execution line contains `[ Other Skill ]`,
+look up "Other Skill" and replace the reference with its command.
+
 **CRITICAL - VERBATIM EXECUTION**: Run shell commands EXACTLY as written in
 the ### Execution section. Do NOT:
 - Modify the command string in any way
@@ -371,6 +407,41 @@ commands:
     command: "df -h"
 ```
 
+### Example 8: Partial skill execution (specific steps only)
+
+When the schedule breaks a multi-step skill into separate tasks, each
+task produces exactly ONE command for its specific step:
+
+Skill "Prepare Report" has 3 steps:
+- Steps: Fetch source data | Transform data | Export results
+- Execution: curl {url} | python3 process.py | cat output.csv
+
+Tasks (schedule requested only steps 1 and 3, skipping transform):
+- { action: "Fetch source data", params: { skill: "Prepare Report" } }
+- { action: "Export results", params: { skill: "Prepare Report" } }
+
+Response (2 tasks = 2 commands, NOT 3):
+```
+message: "Prepare report:"
+summary: "Report prepared"
+commands:
+  - description: "Fetch source data"
+    command: "curl {url}"
+  - description: "Export results"
+    command: "cat output.csv"
+```
+
+**WRONG** response (adding unscheduled transform step):
+```
+commands:
+  - description: "Fetch source data"
+    command: "curl {url}"
+  - description: "Transform data"       ← NOT IN SCHEDULE - DO NOT ADD
+    command: "python3 process.py"
+  - description: "Export results"
+    command: "cat output.csv"
+```
+
 ## Handling Complex Operations
 
 For complex multi-step operations:
@@ -420,6 +491,10 @@ Example:
 - **CRITICAL: Assume what commands to run when skill is missing**
 - **CRITICAL: Replace unknown placeholders with `<UNKNOWN>` - this breaks
   shell syntax**
+- **CRITICAL: Add steps that weren't in the scheduled tasks** - if the
+  schedule has 2 tasks, you MUST return exactly 2 commands
+- **CRITICAL: Expand entire skill workflows** when only specific steps
+  were scheduled - match task actions to individual skill steps
 
 **DO:**
 - Match commands precisely to task descriptions
@@ -434,6 +509,10 @@ Example:
   commands**
 - Always use skill's Execution section when params.skill is present
 - Replace all {PARAM} placeholders with values from task params
+- **CRITICAL: Count input tasks and ensure output has same count** -
+  N tasks in = N commands out, no exceptions
+- **CRITICAL: Match each task action to its specific skill step** -
+  use only that step's Execution line for the command
 
 ## Final Validation
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prompt-language-shell",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Your personal command-line concierge. Ask politely, and it gets things done.",
   "type": "module",
   "main": "dist/index.js",
@@ -17,9 +17,10 @@
     "dev": "npm run build && tsc --watch",
     "prepare": "husky",
     "prepublishOnly": "npm run check",
-    "test": "vitest run --exclude 'tests/tools/schedule/*.test.tsx'",
-    "test:watch": "vitest --exclude 'tests/tools/schedule/*.test.tsx'",
+    "test": "vitest run --exclude 'tests/tools/schedule/*.test.tsx' --exclude 'tests/shell/*.test.ts'",
+    "test:watch": "vitest --exclude 'tests/tools/schedule/*.test.tsx' --exclude 'tests/shell/*.test.ts'",
     "test:llm": "vitest run tests/tools/schedule/*.test.tsx",
+    "test:shell": "vitest run tests/shell/*.test.ts",
     "format": "prettier --write '**/*.{ts,tsx}'",
     "format:check": "prettier --check '**/*.{ts,tsx}'",
     "lint": "eslint .",