toolpack-sdk 2.0.0-alpha.1 → 2.1.0

package/README.md

@@ -1,6 +1,6 @@
 # Toolpack SDK
 
-A unified TypeScript/Node.js SDK for building AI-powered applications with multiple providers, 97 built-in tools, a workflow engine, and a flexible mode system — all through a single API.
+A unified TypeScript/Node.js SDK for building AI-powered applications with multiple providers, 100+ built-in tools, a workflow engine, and a flexible mode system — all through a single API.
 
 [![npm version](https://img.shields.io/npm/v/toolpack-sdk.svg)](https://www.npmjs.com/package/toolpack-sdk)
 [![License: Apache 2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
@@ -14,27 +14,29 @@ A unified TypeScript/Node.js SDK for building AI-powered applications with multi
 - **Type-Safe** — Comprehensive TypeScript types throughout
 - **Multimodal** — Text and image inputs (vision) across all providers
 - **Embeddings** — Vector generation for RAG applications (OpenAI, Gemini, Ollama)
-- **Workflow Engine** — AI-driven planning and step-by-step task execution with progress events
+- **Workflow Engine** — AI-driven planning with plan-direct execution and parallel tool orchestration
 - **Mode System** — Built-in Agent and Chat modes, plus `createMode()` for custom modes with tool filtering
 - **HITL Confirmation** — Human-in-the-loop approval for high-risk operations with configurable bypass rules
 - **Custom Providers** — Bring your own provider by implementing the `ProviderAdapter` interface
-- **97 Built-in Tools** across 12 categories:
+- **101 Built-in Tools** across 14 categories (including 4 skill-tools and 2 mcp-tools):
 - **MCP Tool Server Integration** — dynamically bridge external Model Context Protocol servers into Toolpack as first-class tools via `createMcpToolProject()` and `disconnectMcpToolProject()`.
 
 | Category | Tools | Description |
 |----------|-------|-------------|
 | **`fs-tools`** | 18 | File system operations — read, write, search, tree, glob, batch read/write, etc. |
 | **`coding-tools`** | 12 | Code analysis — AST parsing, go to definition, find references, rename symbols, extract function |
-| **`git-tools`** | 9 | Version control — status, diff, log, blame, branch, commit, checkout |
+| **`git-tools`** | 10 | Version control — status, diff, log, blame, branch, commit, checkout, clone |
 | **`db-tools`** | 7 | Database operations — query, schema, tables, count, insert, update, delete (SQLite, PostgreSQL, MySQL) |
 | **`exec-tools`** | 6 | Command execution — run, run shell, background processes, kill, read output |
 | **`http-tools`** | 5 | HTTP requests — GET, POST, PUT, DELETE, download |
 | **`web-tools`** | 9 | Web interaction — fetch, search (Tavily/Brave/DuckDuckGo), scrape, extract links, map, metadata, sitemap, feed, screenshot |
 | **`system-tools`** | 5 | System info — env vars, cwd, disk usage, system info, set env |
 | **`github-tools`** | 9 | GitHub operations — PR reviews, review threads, file diffs, issue comments, GraphQL, repo contents |
+| **`slack-tools`** | 6 | Slack messaging — post messages, ephemeral messages, channel history, thread replies, reactions |
 | **`diff-tools`** | 3 | Patch operations — create, apply, and preview diffs |
 | **`cloud-tools`** | 3 | Deployments — deploy, status, list (via Netlify) |
 | **`k8s-tools`** | 11 | Kubernetes cluster inspection and management via kubectl |
+| **`skill-tools`** | 4 | Skill management — skill.create, skill.read, skill.update, skill.list |
 | **`mcp-tools`** | 2 | MCP integration — createMcpToolProject, disconnectMcpToolProject |
 
 ## Quick Start
@@ -61,7 +63,7 @@ const sdk = await Toolpack.init({
     anthropic: {},   // Reads ANTHROPIC_API_KEY from env
   },
   defaultProvider: 'openai',
-  tools: true,         // Load all 97 built-in tools
+  tools: true,         // Load all 100+ built-in tools
   defaultMode: 'agent', // Agent mode with workflow engine
 });
 
@@ -79,7 +81,7 @@ for await (const chunk of sdk.stream({
 
 // Switch providers on the fly
 const anthropicResponse = await sdk.generate({
-  model: 'claude-sonnet-4-20250514',
+  model: 'your-model',
   messages: [{ role: 'user', content: 'Hello from Anthropic!' }],
 }, 'anthropic');
 ```
@@ -105,7 +107,7 @@ const sdk = await Toolpack.init({
 });
 
 const podsResponse = await sdk.generate({
-  model: 'gpt-4o',
+  model: 'your-model',
   messages: [
     {
       role: 'user',
@@ -116,7 +118,7 @@ const podsResponse = await sdk.generate({
 console.log(podsResponse.content);
 
 const applyResponse = await sdk.generate({
-  model: 'gpt-4o',
+  model: 'your-model',
   messages: [
     {
       role: 'user',
@@ -279,8 +281,8 @@ Modes control AI behavior by setting a system prompt, filtering available tools,
 
 | Mode | Tools | Workflow | Description |
 |------|-------|----------|-------------|
-| **Agent** | All tools | Planning + step execution + dynamic steps | Full autonomous access — read, write, execute, browse |
-| **Coding** | All tools | Concise planning + step execution | Optimized for coding tasks — minimal text, file operations |
+| **Agent** | All tools | Plan-direct execution | Full autonomous access — read, write, execute, browse |
+| **Coding** | All tools | Plan-direct execution | Optimized for coding tasks — minimal text, file operations |
 | **Chat** | Web/HTTP only | Direct execution (no planning) | Conversational assistant with web access |
 
 ### Custom Modes
@@ -301,7 +303,6 @@ const reviewMode = createMode({
   },
   workflow: {
     planning: { enabled: true },
-    steps: { enabled: true, retryOnFailure: true },
     progress: { enabled: true },
   },
 });
@@ -341,19 +342,17 @@ sdk.cycleMode(); // Cycles through all registered modes
 | `blockedTools` | string[] | `[]` | Specific tools to block. Overrides allowed |
 | `blockAllTools` | boolean | `false` | If `true`, disables all tools (pure conversation) |
 | `baseContext` | object/false | `undefined` | Controls working directory and tool category injection |
-| `workflow` | WorkflowConfig | `undefined` | Planning, step execution, and progress configuration |
+| `workflow` | WorkflowConfig | `undefined` | Planning, execution mode, and progress configuration |
 
 ## Workflow Engine
 
-The workflow engine enables AI agents to plan and execute complex tasks step-by-step, with progress tracking, retries, and dynamic step additions.
+The workflow engine enables AI agents to plan and execute complex tasks with parallel tool orchestration.
 
 ### How It Works
 
-1. **Planning** — The AI generates a structured step-by-step plan from the user's request
-2. **Execution** — Each step is executed sequentially with tool access
-3. **Dynamic Steps** — New steps can be added during execution based on results
-4. **Retries** — Failed steps are retried automatically (configurable)
-5. **Progress** — Events are emitted at each stage for UI integration
+1. **Planning** — The AI generates a structured plan from the user's request
+2. **Execution** — The plan is injected as context and executed in a single call with parallel tool orchestration
+3. **Progress** — Events are emitted at each stage for UI integration
 
 ### Using the Workflow
 
@@ -364,7 +363,7 @@ const sdk = await Toolpack.init({
   defaultMode: 'agent', // Agent mode has workflow enabled
 });
 
-// Complex tasks are automatically planned and executed step-by-step
+// Complex tasks are automatically planned (plan-direct) with parallel tool execution
 const result = await sdk.generate('Build me a REST API with user authentication');
 
 // Or stream the response
@@ -386,35 +385,18 @@ const executor = sdk.getWorkflowExecutor();
 // Progress updates (ideal for status bars / shimmer text)
 executor.on('workflow:progress', (progress) => {
   // progress.status: 'planning' | 'awaiting_approval' | 'executing' | 'completed' | 'failed'
-  // progress.currentStep, progress.totalSteps, progress.percentage
-  // progress.currentStepDescription — includes retry info if retrying
-  console.log(`[${progress.percentage}%] Step ${progress.currentStep}/${progress.totalSteps}: ${progress.currentStepDescription}`);
+  // progress.percentage, progress.currentStepDescription
+  console.log(`[${progress.percentage}%] ${progress.currentStepDescription}`);
 });
 
-// Step lifecycle
-executor.on('workflow:step_start', (step, plan) => {
-  console.log(`Starting: ${step.description}`);
-});
-
-executor.on('workflow:step_complete', (step, plan) => {
-  console.log(`Completed: ${step.description}`);
-});
-
-executor.on('workflow:step_failed', (step, error, plan) => {
-  console.log(`Failed: ${step.description} — ${error.message}`);
-});
-
-executor.on('workflow:step_retry', (step, attempt, plan) => {
-  console.log(`Retrying: ${step.description} (attempt ${attempt})`);
-});
-
-executor.on('workflow:step_added', (step, plan) => {
-  console.log(`Dynamic step added: ${step.description}`);
+// Plan created
+executor.on('workflow:plan_created', (plan) => {
+  console.log('Plan:', plan.steps.map(s => s.description));
 });
 
 // Workflow completion
 executor.on('workflow:completed', (plan, result) => {
-  console.log(`Done! ${result.metrics.stepsCompleted} steps in ${result.metrics.totalDuration}ms`);
+  console.log(`Done in ${result.metrics.totalDuration}ms`);
 });
 
 executor.on('workflow:failed', (plan, error) => {
@@ -433,22 +415,10 @@ interface WorkflowConfig {
     maxSteps?: number;          // Max steps in a plan (default: 20)
   };
 
-  steps?: {
-    enabled: boolean;           // Enable step-by-step execution
-    retryOnFailure?: boolean;   // Retry failed steps (default: true)
-    maxRetries?: number;        // Max retries per step (default: 3)
-    allowDynamicSteps?: boolean; // Allow adding steps during execution
-    maxTotalSteps?: number;     // Max total steps including dynamic (default: 50)
-  };
-
   progress?: {
     enabled: boolean;           // Emit progress events (default: true)
     reportPercentage?: boolean; // Include completion percentage
   };
-
-  onFailure?: {
-    strategy: 'abort' | 'skip' | 'ask_user';
-  };
 }
 ```
 
@@ -460,12 +430,12 @@ The SDK provides built-in workflow presets for common use cases:
 import { DEFAULT_WORKFLOW, AGENT_WORKFLOW, CODING_WORKFLOW, CHAT_WORKFLOW } from 'toolpack-sdk';
 ```
 
-| Preset | Planning | Steps | Description |
-|--------|----------|-------|-------------|
-| `DEFAULT_WORKFLOW` | Disabled | Disabled | Direct execution, no planning |
-| `AGENT_WORKFLOW` | Enabled (detailed) | Enabled | Full autonomous agent with 11 planning rules |
-| `CODING_WORKFLOW` | Enabled (concise) | Enabled | Minimal prompts optimized for coding tasks |
-| `CHAT_WORKFLOW` | Disabled | Disabled | Simple conversational mode |
+| Preset | Planning | Description |
+|--------|----------|-------------|
+| `DEFAULT_WORKFLOW` | Disabled | Direct execution, no planning |
+| `AGENT_WORKFLOW` | Enabled (detailed) | Full autonomous agent with plan-direct execution |
+| `CODING_WORKFLOW` | Enabled (concise) | Minimal prompts optimized for coding tasks |
+| `CHAT_WORKFLOW` | Disabled | Simple conversational mode |
 
 ### Creating Custom Workflows
 
@@ -488,15 +458,6 @@ Rules:
 3. Generate docs in consistent format
 4. Output JSON: {"summary": "...", "steps": [...]}`,
   },
-  steps: {
-    ...AGENT_WORKFLOW.steps,
-    stepPrompt: `Execute step {stepNumber}: {stepDescription}
-
-Analyze code and write clear documentation.
-Focus on: purpose, parameters, return values, examples.
-
-Previous: {previousStepsResults}`,
-  },
 };
 
 // Use in a custom mode
@@ -511,23 +472,11 @@ const docMode = createMode({
 });
 ```
 
-### Step Prompt Template Variables
-
-When using custom `stepPrompt`, these variables are automatically substituted:
-
-| Variable | Description |
-|----------|-------------|
-| `{stepNumber}` | Current step number (1-indexed) |
-| `{planSummary}` | Summary of the overall plan |
-| `{stepDescription}` | Description of the current step |
-| `{previousStepsResults}` | Output from completed steps (truncated to 2000 chars) |
-
 ### Workflow Prompt Tips
 
 - **Keep planning prompts concise** — LLMs perform better with 5-7 clear rules
 - **Use JSON schema examples** — Include the exact expected output format
-- **Avoid meta-commentary in step prompts** — The AI should just execute, not discuss
-- **Leverage previous results** — The `{previousStepsResults}` variable provides context
+- **Keep prompts task-oriented** — The AI should execute, not discuss
 
 ## Tool Call Events
 
@@ -551,7 +500,7 @@ client.on('tool:failed', (event) => { /* ... */ });
 
 ## Custom Tools
 
-In addition to the 97 built-in tools, you can create and register your own custom tool projects using `createToolProject()`:
+In addition to the 100+ built-in tools, you can create and register your own custom tool projects using `createToolProject()`:
 
 ```typescript
 import { Toolpack, createToolProject } from 'toolpack-sdk';
@@ -647,7 +596,75 @@ const response = await toolpack.chat('How do I configure authentication?');
 - **Progress Events**: Track embedding progress with `onEmbeddingProgress`
 - **Metadata Filtering**: Query with filters like `{ hasCode: true, category: 'api' }`
 
-See the [Knowledge package README](../toolpack-knowledge/README.md) for full documentation.
+See the [Knowledge package README](./packages/toolpack-knowledge/README.md) for full documentation.
+
+## Skills
+
+The skills system lets you define **reusable behavioral instructions** in `.skill.md` files and automatically inject them into requests based on message relevance — no agent code changes required.
+
+### Quick Start
+
+```typescript
+import { Toolpack, createSkillInterceptor, createSkillTools } from 'toolpack-sdk';
+
+const toolpack = await Toolpack.init({
+  provider: 'anthropic',
+  interceptors: [
+    createSkillInterceptor({ dir: '.toolpack/skills', maxSkills: 3, minScore: 0.3 }),
+  ],
+  customTools: [
+    createSkillTools({ dir: '.toolpack/skills' }),
+  ],
+});
+```
+
+Create a skill file at `.toolpack/skills/code-review.skill.md`:
+
+```markdown
+---
+name: code-review
+title: Code Review
+version: 1.0.0
+tags: ["coding", "quality"]
+updated: 2026-01-15T10:00:00.000Z
+---
+
+## Description
+
+Guides the agent through a structured code review process.
+
+## Triggers
+
+- "review this code"
+- "check my pull request"
+- "code review"
+
+## Instructions
+
+When reviewing code:
+1. Check for security vulnerabilities first
+2. Verify test coverage exists
+3. Flag naming inconsistencies
+4. Be constructive — suggest improvements, not just problems
+```
+
+When a user sends "review this PR", the interceptor automatically injects the `## Instructions` block before the LLM sees the message.
+
+### How It Works
+
+- **`createSkillInterceptor`** — An SDK interceptor that runs BM25 search on every user message and prepends matching skill instructions as a `<skill-instructions>` block. Validates all files at `Toolpack.init()` time.
+- **`createSkillTools`** — Four LLM-callable tools (`skill.create`, `skill.read`, `skill.update`, `skill.list`) for managing the skill library at runtime.
+
+### `createSkillInterceptor` Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `dir` | string | `.toolpack/skills` | Path to the skill files directory |
+| `maxSkills` | number | `3` | Maximum number of skills injected per message |
+| `minScore` | number | `0.3` | BM25 relevance threshold |
+| `onValidationError` | `'fail'` \| `'warn'` | `'fail'` | How to handle invalid skill files at startup |
+
+See the [Skills guide](https://toolpacksdk.com/guides/skills) and [Skill Tools reference](https://toolpacksdk.com/tools/skills) for full documentation.
 
 ## AI Agents (@toolpack-sdk/agents)
 
@@ -968,7 +985,7 @@ class FintechResearchAgent extends ResearchAgent {
   systemPrompt = `You are a research agent focused on fintech.
                   Always cite sources and flag regulatory implications.`;
   provider = 'anthropic';
-  model = 'claude-sonnet-4-20250514';
+  model = 'your-model';
 
   async onComplete(result) {
     // Store research in knowledge base
@@ -996,7 +1013,7 @@ class FintechResearchAgent extends ResearchAgent {
 - ✅ **Type-Safe** — Full TypeScript support
 - ✅ **199 Tests Passing** — Production-ready
 
-See the [Agents package README](../toolpack-agents/README.md) for full documentation.
+See the [Agents package README](./packages/toolpack-agents/README.md) for full documentation.
 
 ## Multimodal Support
 
@@ -1474,19 +1491,22 @@ toolpack-sdk/
 │   │   ├── openrouter/    # OpenRouter adapter (OpenAI-compatible, dynamic model discovery)
 │   │   └── ollama/        # Ollama adapter + provider (auto-discovery)
 │   ├── modes/             # Mode system (Agent, Chat, createMode)
-│   ├── workflows/         # Workflow engine (planner, step executor, progress)
-│   ├── tools/             # 97 built-in tools + registry + router + BM25 search
+│   ├── workflows/         # Workflow engine (planner, executor, progress)
+│   ├── tools/             # 100+ built-in tools + registry + router + BM25 search
 │   │   ├── fs-tools/      # File system (18 tools)
 │   │   ├── coding-tools/  # Code analysis (12 tools)
-│   │   ├── git-tools/     # Git operations (9 tools)
-│   │   ├── db-tools/      # Database operations (6 tools)
+│   │   ├── git-tools/     # Git operations (10 tools)
+│   │   ├── db-tools/      # Database operations (7 tools)
 │   │   ├── exec-tools/    # Command execution (6 tools)
 │   │   ├── http-tools/    # HTTP requests (5 tools)
-│   │   ├── web-tools/     # Web interaction (5 tools)
+│   │   ├── web-tools/     # Web interaction (9 tools)
 │   │   ├── system-tools/  # System info (5 tools)
+│   │   ├── github-tools/  # GitHub API (9 tools)
+│   │   ├── slack-tools/   # Slack messaging (6 tools)
 │   │   ├── diff-tools/    # Patch operations (3 tools)
 │   │   ├── cloud-tools/   # Deployments (3 tools)
 │   │   ├── k8s-tools/     # Kubernetes management (11 tools)
+│   │   ├── skill-tools/   # Skill management (4 tools)
 │   │   ├── registry.ts    # Tool registry and loading
 │   │   ├── router.ts      # Tool routing and filtering
 │   │   └── search/        # BM25 tool discovery engine (internal)
@@ -1502,8 +1522,8 @@ toolpack-sdk/
 **Current Version:** 0.1.0
 
 - ✓ **5 Built-in Providers** — OpenAI, Anthropic, Gemini, Ollama, OpenRouter (+ custom provider API)
-- ✓ **90 Built-in Tools** — fs, exec, git, diff, web, coding, db, cloud, http, system, Kubernetes
-- ✓ **Workflow Engine** — AI-driven planning, step execution, retries, dynamic steps, progress events
+- ✓ **100+ Built-in Tools** — fs, exec, git, diff, web, coding, db, cloud, http, system, Kubernetes, GitHub, Slack, Skills
+- ✓ **Workflow Engine** — AI-driven planning, plan-direct execution, parallel tool orchestration, progress events
 - ✓ **Mode System** — Agent, Coding, Chat, and custom modes via `createMode()` with `blockAllTools` support
 - ✓ **Tool Search** — BM25-based on-demand tool discovery for large tool libraries
 - ✓ **545 Tests** passing across 81 test files