prompt-language-shell 0.9.2 → 0.9.6

package/dist/skills/schedule.md

@@ -14,6 +14,15 @@ behavior must adapt accordingly:
 - **Skills present**: Match user requests ONLY against listed skills
 - **Empty or missing**: Create "ignore" tasks for ALL action verbs
 
+**CRITICAL - Available Skills Section Takes Precedence**:
+
+Information provided in the "Available Skills" section is AUTHORITATIVE
+and OVERRIDES any default behavior in these instructions. When a skill's
+description specifies required parameters, error handling, or specific
+behaviors, those requirements MUST be followed exactly. Skill-specific
+rules always take precedence over general examples or default patterns
+in this document.
+
 All examples in these instructions (e.g., "build", "deploy", "process")
 are for illustration only. They do NOT represent actual available
 skills unless they appear in the "Available Skills" section of the
@@ -268,6 +277,152 @@ User request with multiple config expressions
 - This applies to ALL placeholders in task actions, including those
   from skill references
 
+## Runtime Parameter Placeholders
+
+Skills may include runtime parameters in their Execution section using
+angle bracket syntax. These parameters MUST be resolved by the LLM
+during scheduling - they represent values extracted from the user's
+command, NOT from stored configuration.
+
+**Parameter Format:**
+
+- `<PARAM>` - Required parameter, extract from user command
+- `<PARAM=default>` - Parameter with default, use default if not specified
+- `<PARAM?>` - Optional parameter, omit entirely if not mentioned
+
+**Distinction from Config Placeholders:**
+
+- `{x.y.z}` - Config placeholder, resolved by system at execution from
+  ~/.plsrc
+- `{x.VARIANT.z}` - Variant config, LLM matches variant at schedule time,
+  system resolves from ~/.plsrc at execution
+- `<PARAM>` - Runtime parameter, resolved entirely by LLM at schedule time
+  from user command
+
+**Resolution Rules:**
+
+1. **Full resolution required**: All `<PARAM>` placeholders MUST be
+   resolved to concrete values before creating tasks. No angle-bracket
+   syntax should remain in task actions or params.
+
+2. **Space normalization**: When optional params are omitted, collapse
+   adjacent spaces to single space (e.g., `cmd <OPT?> file` → `cmd file`)
+
+3. **Complete descriptions**: Task actions must be human-readable with
+   all parameters filled in:
+   - CORRECT: "Process /data/report.csv in batch mode with JSON output"
+   - WRONG: "Process <SOURCE> in <MODE> mode"
+
+**Parameter Classification:**
+
+Runtime parameters fall into two categories:
+
+1. **Key parameters** - Essential to the operation, define WHAT to operate on
+   - Input files, paths, URLs, target names, identifiers
+   - The primary subject of the command
+   - Cannot be guessed or listed as options
+   - Examples: `<SOURCE>`, `<FILE>`, `<URL>`, `<TARGET>`
+
+2. **Modifier parameters** - Configure HOW the operation runs
+   - Have a finite set of valid options
+   - Affect behavior but not the primary subject
+   - Examples: `<MODE>`, `<QUALITY>`, `<FORMAT>`, `<VERBOSITY>`
+
+**Resolution Outcomes:**
+
+When processing runtime parameters, exactly ONE of these outcomes applies.
+**CRITICAL: Evaluate in this EXACT order - key param check MUST happen first:**
+
+1. **Key param missing** → Create IGNORE task (CHECK THIS FIRST!)
+   - **PREREQUISITE CHECK**: Before considering ANY other outcome, verify
+     ALL key parameters (input files, paths, URLs, targets) are present
+   - A key parameter is not specified → ALWAYS create IGNORE task
+   - **NEVER create a DEFINE task when key params are missing**, even if
+     modifier params could be listed as options
+   - NEVER offer options for key parameters - they cannot be guessed
+   - Use type `ignore` with descriptive action
+   - Action format: "Missing [param]: specify [what's needed]"
+   - Examples:
+     - "Missing input: specify which file to process"
+     - "Missing target: specify which server to deploy to"
+     - "Missing URL: specify which page to fetch"
+
+2. **All resolved** → Create normal execute/group task
+   - All key parameters are present AND extracted successfully
+   - All modifier parameters are extracted or defaulted
+   - Task action contains fully resolved description
+
+3. **Modifier param unclear (ALL key params present)** → Create DEFINE task
+   - **PREREQUISITE**: ALL key parameters MUST be present in user's command
+   - Only a modifier parameter is unclear but has finite options
+   - **NEVER use DEFINE when ANY key param is missing** - use IGNORE instead
+   - Use type `define` with params.skill and params.options
+   - MUST have more than one option (if only one option exists, use it
+     directly without refinement)
+   - Example: mode (batch/stream/interactive), format (json/xml/csv)
+   - Each option is an object: { name: string, command: string }
+     - name: readable display text for user selection
+     - command: user's natural language command with ALL params resolved
+   - Note: command is NOT the shell command - shell commands are generated
+     by EXECUTE in the next step
+
+**Examples:**
+
+Skill execution line:
+- `process <SOURCE> --mode <MODE> --format <FORMAT=json> <VERBOSE?>`
+
+Key param missing case (CHECK FIRST):
+- User: "process in batch mode"
+- Problem: SOURCE path not specified (key param, cannot be guessed)
+- Task: type `ignore`, action: "Missing source: specify which file to process"
+
+Key param missing with modifier specified:
+- User: "export in JSON format"
+- Problem: SOURCE file not specified (key param, cannot be guessed)
+- Task: type `ignore`, action: "Missing source: specify which data to export"
+- Note: Even though format IS specified, key param is missing → IGNORE, not
+  DEFINE. Key param check takes absolute precedence over DEFINE.
+
+Success case (all resolved):
+- User: "process /data/report.csv in batch mode"
+- Resolution:
+  - `<SOURCE>` → `/data/report.csv` (extracted)
+  - `<MODE>` → `batch` (extracted from "batch mode")
+  - `<FORMAT=json>` → `json` (default used)
+  - `<VERBOSE?>` → omitted (optional, not mentioned)
+- Task action: "Process /data/report.csv in batch mode with JSON format"
+
+Define case (modifier unclear, ALL key params present):
+- User: "process /data/report.csv"
+- Key params: SOURCE is present (/data/report.csv) ✓
+- Problem: MODE not specified but can be listed (3 options available)
+- Task: type `define`, params:
+  - skill: "Process Data"
+  - options:
+    - { name: "Process in batch mode",
+        command: "process /data/report.csv in batch mode" }
+    - { name: "Process in stream mode",
+        command: "process /data/report.csv in stream mode" }
+    - { name: "Process interactively",
+        command: "process /data/report.csv interactively" }
+- User selects "Process in batch mode"
+- SCHEDULE receives: "process /data/report.csv in batch mode"
+- EXECUTE then generates the appropriate shell command
+
+**Critical Rules:**
+- **KEY PARAM CHECK IS MANDATORY AND FIRST**: Before creating ANY task type,
+  verify ALL key parameters are present. This check takes absolute precedence.
+- IGNORE when ANY key param is missing (input, file, URL, target, etc.)
+- Key params cannot be guessed - always require IGNORE with clear error
+- **DEFINE is ONLY valid when ALL key params are present** - if any key param
+  is missing, DEFINE is NOT an option, regardless of modifier params
+- DEFINE tasks MUST have multiple options (2+); single option = use directly
+- NEVER leave `<PARAM>` unresolved in task output
+- NEVER use placeholder values like `<UNKNOWN>` or `<MISSING>`
+- option.command is user's natural language request, NOT shell command
+- Each option.command must include ALL user parameters (original + selected)
+- option.command must preserve exact paths, filenames, URLs (case-sensitive)
+
 ## Grouping Strategy
 
 Group subtasks under logical parent tasks based on:

package/dist/tools/execute.tool.js

@@ -34,10 +34,6 @@ export const executeTool = {
                             type: 'number',
                             description: 'Optional timeout in milliseconds. Defaults to 30000 (30 seconds).',
                         },
-                        critical: {
-                            type: 'boolean',
-                            description: 'Whether failure should stop execution of subsequent commands. Defaults to true.',
-                        },
                     },
                     required: ['description', 'command'],
                 },

package/dist/tools/schedule.tool.js

@@ -31,7 +31,7 @@ export const scheduleTool = {
                     },
                     params: {
                         type: 'object',
-                        description: 'Parameters for leaf tasks (e.g., command, path)',
+                        description: 'Parameters for leaf tasks. For "define" type: { skill: string, options: Array<{ name: string, command: string }> }. "name" is display text, "command" is full resolved command.',
                     },
                     config: {
                         type: 'array',

package/dist/types/schemas.js

@@ -56,7 +56,6 @@ export const ExecuteCommandSchema = z.object({
     command: z.string().min(1),
     workdir: z.string().optional(),
     timeout: z.number().int().positive().optional(),
-    critical: z.boolean().optional(),
 });
 /**
  * Zod schema for Capability type.

package/package.json

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

package/dist/execution/hooks.js

@@ -1,291 +0,0 @@
-import { useCallback, useEffect, useRef, useState, } from 'react';
-import { ComponentStatus, } from '../types/components.js';
-import { FeedbackType } from '../types/types.js';
-import { createFeedback, createMessage } from '../services/components.js';
-import { formatErrorMessage, getExecutionErrorMessage, } from '../services/messages.js';
-import { ExecutionStatus } from '../services/shell.js';
-import { ensureMinimumTime } from '../services/timing.js';
-import { handleTaskCompletion, handleTaskFailure } from './handlers.js';
-import { processTasks } from './processing.js';
-import { executeTask } from './runner.js';
-import { ExecuteActionType } from './types.js';
-import { getCurrentTaskIndex } from './utils.js';
-const ELAPSED_UPDATE_INTERVAL = 1000;
-/**
- * Track elapsed time from a start timestamp.
- * Returns 0 when not active or no start time.
- */
-export function useElapsedTimer(startTime, isActive) {
-    const [elapsed, setElapsed] = useState(0);
-    useEffect(() => {
-        if (!startTime || !isActive)
-            return;
-        const interval = setInterval(() => {
-            setElapsed(Date.now() - startTime);
-        }, ELAPSED_UPDATE_INTERVAL);
-        return () => {
-            clearInterval(interval);
-        };
-    }, [startTime, isActive]);
-    return elapsed;
-}
-/**
- * Manage live output and timing for the currently executing task.
- * Groups related state for tracking a running task's output.
- */
-export function useLiveTaskOutput() {
-    const [output, setOutput] = useState({
-        stdout: '',
-        stderr: '',
-        error: '',
-    });
-    const [startTime, setStartTime] = useState(null);
-    const start = useCallback(() => {
-        setOutput({ stdout: '', stderr: '', error: '' });
-        setStartTime(Date.now());
-    }, []);
-    const stop = useCallback(() => {
-        setStartTime(null);
-    }, []);
-    return {
-        output,
-        startTime,
-        setOutput,
-        start,
-        stop,
-    };
-}
-/**
- * Handle execution cancellation with a ref-based flag.
- * The ref is needed because callbacks check the current cancellation state.
- */
-export function useCancellation() {
-    const cancelledRef = useRef(false);
-    const cancel = useCallback(() => {
-        cancelledRef.current = true;
-    }, []);
-    const reset = useCallback(() => {
-        cancelledRef.current = false;
-    }, []);
-    return {
-        cancelledRef,
-        cancel,
-        reset,
-    };
-}
-const MINIMUM_PROCESSING_TIME = 400;
-/**
- * Helper to create ExecuteState with defaults
- */
-function createExecuteState(overrides = {}) {
-    return {
-        message: '',
-        summary: '',
-        tasks: [],
-        completionMessage: null,
-        error: null,
-        ...overrides,
-    };
-}
-/**
- * Process input tasks through AI to generate executable commands.
- * Handles the initial phase of task execution.
- */
-export function useTaskProcessor(config) {
-    const { inputTasks, service, isActive, hasProcessed, tasksCount, dispatch, requestHandlers, lifecycleHandlers, workflowHandlers, } = config;
-    useEffect(() => {
-        if (!isActive || tasksCount > 0 || hasProcessed) {
-            return;
-        }
-        let mounted = true;
-        async function process(svc) {
-            const startTime = Date.now();
-            try {
-                const result = await processTasks(inputTasks, svc);
-                await ensureMinimumTime(startTime, MINIMUM_PROCESSING_TIME);
-                if (!mounted)
-                    return;
-                // Add debug components to timeline if present
-                if (result.debug?.length) {
-                    workflowHandlers.addToTimeline(...result.debug);
-                }
-                if (result.commands.length === 0) {
-                    if (result.error) {
-                        const errorMessage = getExecutionErrorMessage(result.error);
-                        workflowHandlers.addToTimeline(createMessage({ text: errorMessage }, ComponentStatus.Done));
-                        requestHandlers.onCompleted(createExecuteState({ message: result.message }));
-                        lifecycleHandlers.completeActive();
-                        return;
-                    }
-                    dispatch({
-                        type: ExecuteActionType.ProcessingComplete,
-                        payload: { message: result.message },
-                    });
-                    requestHandlers.onCompleted(createExecuteState({ message: result.message }));
-                    lifecycleHandlers.completeActive();
-                    return;
-                }
-                // Create task infos from commands
-                const taskInfos = result.commands.map((cmd, index) => ({
-                    label: inputTasks[index]?.action ?? cmd.description,
-                    command: cmd,
-                    status: ExecutionStatus.Pending,
-                    elapsed: 0,
-                }));
-                dispatch({
-                    type: ExecuteActionType.CommandsReady,
-                    payload: {
-                        message: result.message,
-                        summary: result.summary,
-                        tasks: taskInfos,
-                    },
-                });
-                requestHandlers.onCompleted(createExecuteState({
-                    message: result.message,
-                    summary: result.summary,
-                    tasks: taskInfos,
-                }));
-            }
-            catch (err) {
-                await ensureMinimumTime(startTime, MINIMUM_PROCESSING_TIME);
-                if (mounted) {
-                    const errorMessage = formatErrorMessage(err);
-                    dispatch({
-                        type: ExecuteActionType.ProcessingError,
-                        payload: { error: errorMessage },
-                    });
-                    requestHandlers.onCompleted(createExecuteState({ error: errorMessage }));
-                    requestHandlers.onError(errorMessage);
-                }
-            }
-        }
-        void process(service);
-        return () => {
-            mounted = false;
-        };
-    }, [
-        inputTasks,
-        isActive,
-        service,
-        requestHandlers,
-        lifecycleHandlers,
-        workflowHandlers,
-        tasksCount,
-        hasProcessed,
-        dispatch,
-    ]);
-}
-/**
- * Execute tasks sequentially, managing state and handling completion/errors.
- */
-export function useTaskExecutor(config) {
-    const { isActive, tasks, message, summary, error, workdir, setWorkdir, cancelledRef, liveOutput, dispatch, requestHandlers, lifecycleHandlers, workflowHandlers, } = config;
-    const currentTaskIndex = getCurrentTaskIndex(tasks);
-    useEffect(() => {
-        if (!isActive ||
-            tasks.length === 0 ||
-            currentTaskIndex >= tasks.length ||
-            error) {
-            return;
-        }
-        const currentTask = tasks[currentTaskIndex];
-        if (currentTask.status !== ExecutionStatus.Pending) {
-            return;
-        }
-        cancelledRef.current = false;
-        // Mark task as started (running)
-        dispatch({
-            type: ExecuteActionType.TaskStarted,
-            payload: { index: currentTaskIndex },
-        });
-        // Reset live state for new task
-        liveOutput.start();
-        // Merge workdir into command
-        const command = workdir
-            ? { ...currentTask.command, workdir }
-            : currentTask.command;
-        void executeTask(command, currentTaskIndex, {
-            onOutputChange: (output) => {
-                if (!cancelledRef.current) {
-                    liveOutput.setOutput(output);
-                }
-            },
-            onComplete: (elapsed, output) => {
-                if (cancelledRef.current)
-                    return;
-                liveOutput.stop();
-                // Track working directory
-                if (output.workdir) {
-                    setWorkdir(output.workdir);
-                }
-                const tasksWithOutput = tasks.map((task, i) => i === currentTaskIndex
-                    ? {
-                        ...task,
-                        stdout: output.stdout,
-                        stderr: output.stderr,
-                        error: output.error,
-                    }
-                    : task);
-                const result = handleTaskCompletion(currentTaskIndex, elapsed, {
-                    tasks: tasksWithOutput,
-                    message,
-                    summary,
-                });
-                dispatch(result.action);
-                requestHandlers.onCompleted(result.finalState);
-                if (result.shouldComplete) {
-                    lifecycleHandlers.completeActive();
-                }
-            },
-            onError: (errorMsg, elapsed, output) => {
-                if (cancelledRef.current)
-                    return;
-                liveOutput.stop();
-                // Track working directory
-                if (output.workdir) {
-                    setWorkdir(output.workdir);
-                }
-                const tasksWithOutput = tasks.map((task, i) => i === currentTaskIndex
-                    ? {
-                        ...task,
-                        stdout: output.stdout,
-                        stderr: output.stderr,
-                        error: output.error,
-                    }
-                    : task);
-                const result = handleTaskFailure(currentTaskIndex, errorMsg, elapsed, {
-                    tasks: tasksWithOutput,
-                    message,
-                    summary,
-                });
-                dispatch(result.action);
-                requestHandlers.onCompleted(result.finalState);
-                if (result.action.type === ExecuteActionType.TaskErrorCritical) {
-                    const criticalErrorMessage = getExecutionErrorMessage(errorMsg);
-                    workflowHandlers.addToQueue(createFeedback({
-                        type: FeedbackType.Failed,
-                        message: criticalErrorMessage,
-                    }));
-                }
-                if (result.shouldComplete) {
-                    lifecycleHandlers.completeActive();
-                }
-            },
-        });
-    }, [
-        isActive,
-        tasks,
-        currentTaskIndex,
-        message,
-        summary,
-        error,
-        workdir,
-        setWorkdir,
-        cancelledRef,
-        liveOutput,
-        dispatch,
-        requestHandlers,
-        lifecycleHandlers,
-        workflowHandlers,
-    ]);
-}

package/dist/ui/Confirm.js

@@ -1,62 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useState } from 'react';
-import { Box, Text } from 'ink';
-import { ComponentStatus, } from '../types/components.js';
-import { Colors, getTextColor, Palette } from '../services/colors.js';
-import { useInput } from '../services/keyboard.js';
-import { UserQuery } from './UserQuery.js';
-export const ConfirmView = ({ message, state, status }) => {
-    const isActive = status === ComponentStatus.Active;
-    const { selectedIndex } = state;
-    const options = [
-        { label: 'yes', value: 'yes', color: Palette.BrightGreen },
-        { label: 'no', value: 'no', color: Colors.Status.Error },
-    ];
-    // Timeline rendering (Done status)
-    if (status === ComponentStatus.Done) {
-        return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginBottom: 1, marginLeft: 1, children: _jsx(Text, { color: undefined, children: message }) }), _jsxs(UserQuery, { children: ["> ", options[selectedIndex].label] })] }));
-    }
-    // Active/Pending rendering
-    return (_jsxs(Box, { flexDirection: "column", children: [_jsx(Box, { marginBottom: 1, marginLeft: 1, children: _jsx(Text, { color: getTextColor(isActive), children: message }) }), _jsxs(Box, { marginLeft: 1, children: [_jsx(Text, { color: Colors.Action.Select, children: ">" }), _jsx(Text, { children: " " }), _jsx(Box, { children: options.map((option, index) => {
-                            const isSelected = index === selectedIndex;
-                            return (_jsx(Box, { marginRight: 2, children: _jsx(Text, { color: isSelected ? option.color : undefined, dimColor: !isSelected, children: option.label }) }, option.value));
-                        }) })] })] }));
-};
-/**
- * Confirm controller: Manages yes/no selection
- */
-export function Confirm({ message, status, requestHandlers, onConfirmed, onCancelled, }) {
-    const isActive = status === ComponentStatus.Active;
-    const [selectedIndex, setSelectedIndex] = useState(0); // 0 = Yes, 1 = No
-    useInput((input, key) => {
-        if (!isActive)
-            return;
-        if (key.escape) {
-            // Escape: highlight "No" and cancel
-            const finalState = { selectedIndex: 1, confirmed: false };
-            requestHandlers.onCompleted(finalState);
-            onCancelled();
-        }
-        else if (key.tab) {
-            // Toggle between Yes (0) and No (1)
-            setSelectedIndex((prev) => (prev === 0 ? 1 : 0));
-        }
-        else if (key.return) {
-            // Confirm selection
-            const finalState = {
-                selectedIndex,
-                confirmed: true,
-            };
-            requestHandlers.onCompleted(finalState);
-            if (selectedIndex === 0) {
-                onConfirmed();
-            }
-            else {
-                onCancelled();
-            }
-        }
-    }, { isActive });
-    // Controller always renders View, passing current state
-    const state = { selectedIndex, confirmed: false };
-    return _jsx(ConfirmView, { message: message, state: state, status: status });
-}

package/dist/ui/Debug.js

@@ -1,7 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box, Text } from 'ink';
-const CONTENT_WIDTH = 80;
-const HORIZONTAL_PADDING = 2;
-export const Debug = ({ title, content, color }) => {
-    return (_jsxs(Box, { flexDirection: "column", paddingX: HORIZONTAL_PADDING, paddingY: 1, borderStyle: "single", borderColor: color, width: CONTENT_WIDTH, children: [_jsx(Text, { color: color, wrap: "wrap", children: title }), _jsx(Text, { color: color, wrap: "wrap", children: content })] }));
-};

package/dist/ui/Feedback.js

@@ -1,19 +0,0 @@
-import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
-import { Box, Text } from 'ink';
-import { ComponentStatus } from '../types/components.js';
-import { FeedbackType } from '../types/types.js';
-import { getFeedbackColor } from '../services/colors.js';
-function getSymbol(type) {
-    return {
-        [FeedbackType.Info]: 'ℹ',
-        [FeedbackType.Warning]: '⚠',
-        [FeedbackType.Succeeded]: '✓',
-        [FeedbackType.Aborted]: '⊘',
-        [FeedbackType.Failed]: '✗',
-    }[type];
-}
-export function Feedback({ type, message }) {
-    const color = getFeedbackColor(type, ComponentStatus.Done);
-    const symbol = getSymbol(type);
-    return (_jsx(Box, { marginLeft: 1, children: _jsxs(Text, { color: color, children: [symbol, " ", message] }) }));
-}

package/dist/ui/Refinement.js

@@ -1,23 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box } from 'ink';
-import { ComponentStatus } from '../types/components.js';
-import { useInput } from '../services/keyboard.js';
-import { Message } from './Message.js';
-import { Spinner } from './Spinner.js';
-export const RefinementView = ({ text, status }) => {
-    const isActive = status === ComponentStatus.Active;
-    return (_jsxs(Box, { gap: 1, children: [_jsx(Message, { text: text, status: status }), isActive && _jsx(Spinner, {})] }));
-};
-/**
- * Refinement controller: Handles abort input
- */
-export const Refinement = ({ text, status, onAborted }) => {
-    const isActive = status === ComponentStatus.Active;
-    useInput((_, key) => {
-        if (key.escape && isActive) {
-            onAborted('plan refinement');
-            return;
-        }
-    }, { isActive });
-    return _jsx(RefinementView, { text: text, status: status });
-};