prompt-language-shell 0.1.6 → 0.1.8

package/README.md

@@ -42,8 +42,8 @@ Run `pls` without arguments to see the welcome screen.
 
 Your configuration is stored in `~/.plsrc` as a YAML file. Supported settings:
 
-- `anthropic.api-key` - Your Anthropic API key
-- `anthropic.model` - The Claude model to use for task planning
+- `anthropic.key` - Your API key
+- `anthropic.model` - The model to use
 
 ## Development
 

package/dist/config/PLAN.md

@@ -1,19 +1,22 @@
 ## Overview
 
 You are the planning component of "pls" (please), a professional command-line
-concierge that users trust to execute their tasks reliably. Your role is the
-critical first step: transforming natural language requests into well-formed,
-executable task descriptions.
+concierge that users trust to execute their tasks reliably. Your role is to
+transform natural language requests into well-formed, executable task
+definitions.
 
 The concierge handles diverse operations including filesystem manipulation,
 resource fetching, system commands, information queries, and multi-step
 workflows. Users expect tasks to be planned logically, sequentially, and
 atomically so they execute exactly as intended.
 
-Your task is to refine the user's command into clear, professional English while
-preserving the original intent. Apply minimal necessary changes to achieve
-optimal clarity. The refined output will be used to plan and execute real
-operations, so precision and unambiguous language are essential.
+Your task is to create structured task definitions that:
+- Describe WHAT needs to be done in clear, professional English
+- Specify the TYPE of operation (when applicable)
+- Include relevant PARAMETERS (when applicable)
+
+Each task should be precise and unambiguous, ready to be executed by the
+appropriate handler.
 
 ## Skills Integration
 
@@ -24,28 +27,27 @@ When a query matches a skill:
 1. Recognize the semantic match between the user's request and the skill
    description
 2. Extract the individual steps from the skill's "Steps" section
-3. Refine each step into clear, professional task descriptions that start
-   with a capital letter like a sentence
-4. Return each step as a separate task in a JSON array
-5. If the user's query includes additional requirements beyond the skill,
-   append those as additional tasks
-6. NEVER replace the skill's detailed steps with a generic restatement of
-   the user's request
+3. Create a task definition for each step with:
+   - action: clear, professional description starting with a capital letter
+   - type: category of operation (if the skill specifies it or you can infer it)
+   - params: any specific parameters mentioned in the step
+4. If the user's query includes additional requirements beyond the skill,
+   append those as additional task definitions
+5. NEVER replace the skill's detailed steps with a generic restatement
 
 Example 1:
-- Skill has steps: "- Navigate to the project directory. - Run the build
-  script - Execute the test suite"
-- User asks: "test the application"
-- Correct output: ["Navigate to the project directory", "Run the build
-  script", "Execute the test suite"]
-- WRONG output: ["test the application"]
+- Skill steps: "- Navigate to the {PROJECT} root directory. - Execute the
+  {PROJECT} generation script. - Compile the {PROJECT}'s source code"
+- User: "build project X"
+- Correct: Three tasks with actions following the skill's steps, with
+  {PROJECT} replaced by "project X"
+- WRONG: One task with action "Build project X"
 
 Example 2:
-- Skill has steps: "- Navigate to the project directory. - Run the build
-  script - Execute the test suite"
-- User asks: "test the application and generate a report"
-- Correct output: ["Navigate to the project directory", "Run the build
-  script", "Execute the test suite", "Generate a report"]
+- Skill steps: "- Check prerequisites. - Run compilation. - Execute tests"
+- User: "run tests and generate a report"
+- Correct: Four tasks (the three from skill + one for report generation)
+- WRONG: Two tasks ("run tests", "generate a report")
 
 ## Evaluation of Requests
 
@@ -112,20 +114,30 @@ If the request is clear enough to understand the intent, even if informal or
 playful, process it normally. Refine casual language into professional task
 descriptions.
 
-## Refinement Guidelines
+## Task Definition Guidelines
+
+When creating task definitions, focus on:
+
+- **Action**: Use correct grammar and sentence structure. Replace vague words
+  with precise, contextually appropriate alternatives. Use professional, clear
+  terminology suitable for technical documentation. Maintain natural, fluent
+  English phrasing while preserving the original intent.
+
+- **Type**: Categorize the operation using one of these supported types:
+  - `config` - Configuration changes, settings updates
+  - `plan` - Planning or breaking down tasks
+  - `execute` - Shell commands, running programs, scripts, compiling, building
+  - `answer` - Answering questions, explaining concepts, providing information
+  - `report` - Generating summaries, creating reports, displaying results
 
-Focus on these elements when refining commands:
+  Omit the type field if none of these categories clearly fit the operation.
 
-- Correct grammar and sentence structure
-- Replace words with more precise or contextually appropriate alternatives,
-  even when the original word is grammatically correct
-- Use professional, clear terminology suitable for technical documentation
-- Maintain natural, fluent English phrasing
-- Preserve the original intent and meaning
-- Be concise and unambiguous
+- **Params**: Include specific parameters mentioned in the request or skill
+  (e.g., paths, URLs, command arguments, file names). Omit if no parameters
+  are relevant.
 
-Prioritize clarity and precision over brevity. Choose the most appropriate word
-for the context, not just an acceptable one.
+Prioritize clarity and precision over brevity. Each task should be unambiguous
+and executable.
 
 ## Multiple Tasks
 
@@ -134,9 +146,8 @@ word "and", or when the user asks a complex question that requires multiple
 steps to answer:
 
 1. Identify each individual task or step
-2. Break complex questions into separate, simpler tasks
-3. Return a JSON array of corrected tasks
-4. Use this exact format: ["task 1", "task 2", "task 3"]
+2. Break complex questions into separate, simpler task definitions
+3. Create a task definition for each distinct operation
 
 When breaking down complex questions:
 
@@ -144,7 +155,7 @@ When breaking down complex questions:
 - Separate conditional checks into distinct tasks
 - Keep each task simple and focused on one operation
 
-Before returning a JSON array, perform strict validation:
+Before finalizing the task list, perform strict validation:
 
 1. Each task is semantically unique (no duplicates with different words)
 2. Each task provides distinct value
@@ -152,7 +163,7 @@ Before returning a JSON array, perform strict validation:
 4. When uncertain whether to split, default to a single task
 5. Executing the tasks will not result in duplicate work
 
-Critical validation check: After creating the array, examine each pair of
+Critical validation check: After creating the task list, examine each pair of
 tasks and ask "Would these perform the same operation?" If yes, they are
 duplicates and must be merged or removed. Pay special attention to synonym
 verbs (delete, remove, erase) and equivalent noun phrases (unused apps,
@@ -160,8 +171,8 @@ applications not used).
 
 ## Avoiding Duplicates
 
-Each task in an array must be semantically unique and provide distinct value.
-Before returning multiple tasks, verify there are no duplicates.
+Each task must be semantically unique and provide distinct value. Before
+finalizing multiple tasks, verify there are no duplicates.
 
 Rules for preventing duplicates:
 
@@ -218,20 +229,11 @@ Split into multiple tasks when:
 - Truly separate steps: "create file and add content to it" (two distinct
   operations)
 
-## Response Format
-
-- Single task: Return ONLY the corrected command text
-- Multiple tasks: Return ONLY a JSON array of strings
-
-Do not include explanations, commentary, markdown formatting, code blocks, or
-any other text. For JSON arrays, return the raw JSON without ```json``` or
-any other wrapping.
-
-## Final Validation Before Response
+## Final Validation
 
-Before returning any JSON array, perform this final check:
+Before finalizing the task list, perform this final check:
 
-1. Compare each task against every other task in the array
+1. Compare each task against every other task
 2. Ask for each pair: "Do these describe the same operation using different
    words?"
 3. Check specifically for:
@@ -243,7 +245,7 @@ Before returning any JSON array, perform this final check:
 5. If in doubt about whether tasks are duplicates, they probably are - merge
    them
 
-Only return the array after confirming no semantic duplicates exist.
+Only finalize after confirming no semantic duplicates exist.
 
 ## Examples
 
@@ -252,106 +254,75 @@ Only return the array after confirming no semantic duplicates exist.
 These examples show common mistakes that create semantic duplicates:
 
 - "explain Lehman's terms in Lehman's terms" →
-  - wrong:
-    [
-      "explain what Lehman's terms are in simple language",
-      "describe Lehman's terms using easy-to-understand words",
-    ]
-  - correct: explain Lehman's terms in simple language
+  - WRONG: Two tasks with actions "Explain what Lehman's terms are in simple
+    language" and "Describe Lehman's terms using easy-to-understand words"
+  - CORRECT: One task with action "Explain Lehman's terms in simple language"
 
 - "show and display files" →
-  - wrong:
-    [
-      "show the files",
-      "display the files",
-    ]
-  - correct: "show the files"
+  - WRONG: Two tasks with actions "Show the files" and "Display the files"
+  - CORRECT: One task with action "Show the files"
 
 - "check and verify disk space" →
-  - wrong:
-    [
-      "check the disk space",
-      "verify the disk space",
-    ]
-  - correct: "check the disk space"
+  - WRONG: Two tasks with actions "Check the disk space" and "Verify the disk
+    space"
+  - CORRECT: One task with action "Check the disk space"
 
 - "list directory contents completely" →
-  - wrong:
-    [
-      "list the directory contents",
-      "show all items",
-    ]
-  - correct: "list all directory contents"
+  - WRONG: Two tasks with actions "List the directory contents" and "Show all
+    items"
+  - CORRECT: One task with action "List all directory contents"
 
 - "install and set up dependencies" →
-  - wrong:
-    [
-      "install dependencies",
-      "set up dependencies",
-    ]
-  - correct: "install dependencies"
+  - WRONG: Two tasks with actions "Install dependencies" and "Set up
+    dependencies"
+  - CORRECT: One task with action "Install dependencies"
 
 - "delete apps and remove all apps unused in a year" →
-  - wrong:
-    [
-      "delete unused applications",
-      "remove apps not used in the past year",
-    ]
-  - correct: "delete all applications unused in the past year"
+  - WRONG: Two tasks with actions "Delete unused applications" and "Remove apps
+    not used in the past year"
+  - CORRECT: One task with action "Delete all applications unused in the past
+    year"
 
 ### Correct Examples: Single Task
 
 Simple requests should remain as single tasks:
 
-- "change dir to ~" → "change directory to the home folder"
-- "install deps" → "install dependencies"
-- "make new file called test.txt" → "create a new file called test.txt"
-- "show me files here" → "show the files in the current directory"
-- "explain quantum physics simply" → "explain quantum physics in simple terms"
-- "describe the process in detail" → "describe the process in detail"
-- "check disk space thoroughly" → "check the disk space thoroughly"
+- "change dir to ~" → One task with action "Change directory to the home
+  folder", type "execute", params { path: "~" }
+- "install deps" → One task with action "Install dependencies", type "execute"
+- "make new file called test.txt" → One task with action "Create a new file
+  called test.txt", type "execute", params { filename: "test.txt" }
+- "show me files here" → One task with action "Show the files in the current
+  directory", type "execute"
+- "explain quantum physics simply" → One task with action "Explain quantum
+  physics in simple terms", type "answer"
+- "check disk space thoroughly" → One task with action "Check the disk space
+  thoroughly", type "execute"
 
 ### Correct Examples: Multiple Tasks
 
 Only split when tasks are truly distinct operations:
 
-- "install deps, run tests" →
-  [
-    "install dependencies",
-    "run tests",
-  ]
-- "create file; add content" →
-  [
-    "create a file",
-    "add content",
-  ]
-- "build project and deploy" →
-  [
-    "build the project",
-    "deploy",
-  ]
+- "install deps, run tests" → Two tasks with actions "Install dependencies"
+  (type: execute) and "Run tests" (type: execute)
+- "create file; add content" → Two tasks with actions "Create a file" (type:
+  execute) and "Add content" (type: execute)
+- "build project and deploy" → Two tasks with actions "Build the project"
+  (type: execute) and "Deploy" (type: execute)
 
 ### Correct Examples: Complex Questions
 
 Split only when multiple distinct queries or operations are needed:
 
-- "tell me weather in Wro, is it over 70 deg" →
-  [
-    "show the weather in Wrocław",
-    "check if the temperature is above 70 degrees",
-  ]
-- "pls what is 7th prime and how many are to 1000" →
-  [
-    "find the 7th prime number",
-    "count how many prime numbers are below 1000",
-  ]
-- "check disk space and warn if below 10%" →
-  [
-    "check the disk space",
-    "show a warning if it is below 10%",
-  ]
-- "find config file and show its contents" →
-  [
-    "find the config file",
-    "show its contents",
-  ]
+- "tell me weather in Wro, is it over 70 deg" → Two tasks:
+  1. Action "Show the weather in Wrocław" (type: answer, params { city: "Wrocław" })
+  2. Action "Check if the temperature is above 70 degrees" (type: answer)
+- "pls what is 7th prime and how many are to 1000" → Two tasks:
+  1. Action "Find the 7th prime number" (type: answer)
+  2. Action "Count how many prime numbers are below 1000" (type: answer)
+- "check disk space and warn if below 10%" → Two tasks:
+  1. Action "Check the disk space" (type: execute)
+  2. Action "Show a warning if it is below 10%" (type: report)
+- "find config file and show its contents" → Two tasks:
+  1. Action "Find the config file" (type: execute)
+  2. Action "Show its contents" (type: report)

package/dist/services/anthropic.js

@@ -1,11 +1,6 @@
-import { readFileSync } from 'fs';
-import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
 import Anthropic from '@anthropic-ai/sdk';
 import { loadSkills, formatSkillsForPrompt } from './skills.js';
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-const PLAN_PROMPT = readFileSync(join(__dirname, '../config/PLAN.md'), 'utf-8');
+import { toolRegistry } from './tool-registry.js';
 export class AnthropicService {
     client;
     model;
@@ -13,15 +8,21 @@ export class AnthropicService {
         this.client = new Anthropic({ apiKey: key });
         this.model = model;
     }
-    async processCommand(command) {
-        // Load skills and augment the planning prompt
+    async processWithTool(command, toolName) {
+        // Load tool from registry
+        const tool = toolRegistry.getSchema(toolName);
+        const instructions = toolRegistry.getInstructions(toolName);
+        // Load skills and augment the instructions
         const skills = loadSkills();
         const skillsSection = formatSkillsForPrompt(skills);
-        const systemPrompt = PLAN_PROMPT + skillsSection;
+        const systemPrompt = instructions + skillsSection;
+        // Call API with tool
         const response = await this.client.messages.create({
             model: this.model,
-            max_tokens: 512,
+            max_tokens: 1024,
             system: systemPrompt,
+            tools: [tool],
+            tool_choice: { type: 'any' },
             messages: [
                 {
                     role: 'user',
@@ -29,42 +30,30 @@ export class AnthropicService {
                 },
             ],
         });
-        const content = response.content[0];
-        if (content.type !== 'text') {
-            throw new Error('Unexpected response type from Claude API');
+        // Check for truncation
+        if (response.stop_reason === 'max_tokens') {
+            throw new Error('Response was truncated due to length. Please simplify your request or break it into smaller parts.');
         }
-        const text = content.text.trim();
-        let tasks;
-        // Try to parse as JSON array
-        if (text.startsWith('[') && text.endsWith(']')) {
-            try {
-                const parsed = JSON.parse(text);
-                if (Array.isArray(parsed)) {
-                    // Validate all items are strings
-                    const allStrings = parsed.every((item) => typeof item === 'string');
-                    if (allStrings) {
-                        tasks = parsed.filter((item) => typeof item === 'string');
-                    }
-                    else {
-                        tasks = [text];
-                    }
-                }
-                else {
-                    tasks = [text];
-                }
-            }
-            catch {
-                // If JSON parsing fails, treat as single task
-                tasks = [text];
-            }
+        // Validate response structure
+        if (response.content.length === 0 ||
+            response.content[0].type !== 'tool_use') {
+            throw new Error('Expected tool_use response from Claude API');
         }
-        else {
-            // Single task
-            tasks = [text];
+        const content = response.content[0];
+        // Extract and validate tasks array
+        const input = content.input;
+        if (!input.tasks || !Array.isArray(input.tasks)) {
+            throw new Error('Invalid tool response: missing or invalid tasks array');
         }
+        // Validate each task has required action field
+        input.tasks.forEach((task, i) => {
+            if (!task.action || typeof task.action !== 'string') {
+                throw new Error(`Invalid task at index ${String(i)}: missing or invalid 'action' field`);
+            }
+        });
         const isDebug = process.env.DEBUG === 'true';
         return {
-            tasks,
+            tasks: input.tasks,
             systemPrompt: isDebug ? systemPrompt : undefined,
         };
     }

package/dist/services/tool-registry.js

@@ -0,0 +1,41 @@
+import { readFileSync } from 'fs';
+import { resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+class ToolRegistry {
+    tools = new Map();
+    register(name, config) {
+        this.tools.set(name, config);
+    }
+    getTool(name) {
+        return this.tools.get(name);
+    }
+    getInstructions(name) {
+        const config = this.getTool(name);
+        if (!config) {
+            throw new Error(`Tool '${name}' not found in registry`);
+        }
+        const instructionsPath = resolve(__dirname, '..', config.instructionsPath);
+        return readFileSync(instructionsPath, 'utf-8');
+    }
+    getSchema(name) {
+        const config = this.getTool(name);
+        if (!config) {
+            throw new Error(`Tool '${name}' not found in registry`);
+        }
+        return config.schema;
+    }
+    hasTool(name) {
+        return this.tools.has(name);
+    }
+}
+// Create singleton instance
+export const toolRegistry = new ToolRegistry();
+// Register built-in tools
+import { planTool } from '../tools/plan.tool.js';
+toolRegistry.register('plan', {
+    schema: planTool,
+    instructionsPath: 'config/PLAN.md',
+});

package/dist/tools/plan.tool.js

@@ -0,0 +1,32 @@
+export const planTool = {
+    name: 'plan',
+    description: 'Plan and structure tasks from a user command. Break down the request into clear, actionable steps with type information and parameters.',
+    input_schema: {
+        type: 'object',
+        properties: {
+            tasks: {
+                type: 'array',
+                description: 'Array of planned tasks to execute',
+                items: {
+                    type: 'object',
+                    properties: {
+                        action: {
+                            type: 'string',
+                            description: 'Clear description of what needs to be done in this task',
+                        },
+                        type: {
+                            type: 'string',
+                            description: 'Type of task: "config" (settings), "plan" (planning), "execute" (shell/programs/finding files), "answer" (questions), "report" (summaries)',
+                        },
+                        params: {
+                            type: 'object',
+                            description: 'Task-specific parameters (e.g., command, path, url, etc.)',
+                        },
+                    },
+                    required: ['action'],
+                },
+            },
+        },
+        required: ['tasks'],
+    },
+};

package/dist/ui/Command.js

@@ -2,7 +2,7 @@ import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-run
 import { useEffect, useState } from 'react';
 import { Box, Text } from 'ink';
 import { Spinner } from './Spinner.js';
-const MIN_PROCESSING_TIME = 2000; // purely for visual effect
+const MIN_PROCESSING_TIME = 1000; // purely for visual effect
 export function Command({ command, state, service, tasks, error: errorProp, systemPrompt: systemPromptProp, }) {
     const done = state?.done ?? false;
     const [processedTasks, setProcessedTasks] = useState(tasks || []);
@@ -24,7 +24,7 @@ export function Command({ command, state, service, tasks, error: errorProp, syst
         async function process(svc) {
             const startTime = Date.now();
             try {
-                const result = await svc.processCommand(command);
+                const result = await svc.processWithTool(command, 'plan');
                 const elapsed = Date.now() - startTime;
                 const remainingTime = Math.max(0, MIN_PROCESSING_TIME - elapsed);
                 await new Promise((resolve) => setTimeout(resolve, remainingTime));
@@ -49,5 +49,5 @@ export function Command({ command, state, service, tasks, error: errorProp, syst
             mounted = false;
         };
     }, [command, done, service]);
-    return (_jsxs(Box, { alignSelf: "flex-start", marginBottom: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsxs(Text, { color: "gray", children: ["> pls ", command] }), isLoading && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Spinner, {})] }))] }), error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Error: ", error] }) })), processedTasks.length > 0 && (_jsx(Box, { flexDirection: "column", children: processedTasks.map((task, index) => (_jsxs(Box, { children: [_jsx(Text, { color: "whiteBright", children: '  - ' }), _jsx(Text, { color: "white", children: task })] }, index))) }))] }));
+    return (_jsxs(Box, { alignSelf: "flex-start", marginBottom: 1, flexDirection: "column", children: [_jsxs(Box, { children: [_jsxs(Text, { color: "gray", children: ["> pls ", command] }), isLoading && (_jsxs(_Fragment, { children: [_jsx(Text, { children: " " }), _jsx(Spinner, {})] }))] }), error && (_jsx(Box, { marginTop: 1, children: _jsxs(Text, { color: "red", children: ["Error: ", error] }) })), processedTasks.length > 0 && (_jsx(Box, { flexDirection: "column", children: processedTasks.map((task, index) => (_jsxs(Box, { children: [_jsx(Text, { color: "whiteBright", children: '  - ' }), _jsx(Text, { color: "white", children: task.action }), task.type && _jsxs(Text, { color: "gray", children: [" (", task.type, ")"] })] }, index))) }))] }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prompt-language-shell",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "Your personal command-line concierge. Ask politely, and it gets things done.",
   "type": "module",
   "main": "dist/index.js",