@praveencs/agent 0.7.2 → 0.7.3

package/README.md

@@ -174,6 +174,17 @@ The runtime consists of several modular components:
 
 ---
 
+
+## 📚 Learning Series
+
+Want to understand how this agent works under the hood? Check out our 5-part architecture series:
+
+1.  [**Vision & Architecture**](docs/articles/01-vision-architecture.md) - The high-level design.
+2.  [**The Brain (Planner)**](docs/articles/02-goal-decomposition.md) - How goal decomposition works.
+3.  [**The Body (Executor)**](docs/articles/03-skill-execution.md) - Secure skill execution.
+4.  [**Memory & Context**](docs/articles/04-memory-persistence.md) - SQLite & Vector storage.
+5.  [**Self-Improvement**](docs/articles/05-self-improvement.md) - Metrics & The Auto-Fixer.
+
 ## 🤝 Contributing
 
 We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to set up your development environment.

package/dist/src/cli/index.js

@@ -18,7 +18,7 @@ export function createCLI() {
     program
         .name('agent')
         .description('Agent Runtime — autonomous, goal-oriented AI agent with skills, plans, memory, and permissioned tools')
-        .version('0.7.2')
+        .version('0.7.3')
         .option('--verbose', 'Enable verbose output')
         .option('--no-color', 'Disable colored output')
         .option('--config <path>', 'Path to config file');

package/docs/articles/01-vision-architecture.md

@@ -0,0 +1,52 @@
+# Building an Autonomous AI Agent: The Vision & Architecture (Part 1/5)
+
+Most AI projects today are chatbots. You type, they type back. But what if your AI could *act* on your behalf? What if it could plan a project, check your code, deploy your app, and even fix itself when things break—all while you sleep?
+
+This is the promise of **Autonomous Agents**. Unlike chatbots, agents have:
+1.  **Goals** (long-term objectives)
+2.  **Memory** (persistence across sessions)
+3.  **Skills** (integrations with real-world tools)
+4.  **Autonomy** (looping execution without constant prompts)
+
+In this 5-part series, we will break down exactly how we built `@praveencs/agent`, a powerful, open-source autonomous agent runtime.
+
+## 🏗️ The Core Architecture
+
+To build a truly functional agent, we need several distinct components working in harmony. We'll use a modular architecture:
+
+### 1. The Brain (Planner)
+Standard LLMs (like GPT-4) are great at answering questions but terrible at long-term execution. To fix this, we need a **Planner**.
+- **Role**: Take a high-level goal ("Build a blog") and decompose it into small, atomic tasks ("Create Next.js app", "Set up DB", "Write About page").
+- **Innovation**: We use a recursive decomposition strategy where the LLM acts as a project manager.
+
+### 2. The Body (Executor)
+Once we have a list of tasks, something needs to *do* them. This is the **Executor**.
+- **Role**: Pick up the next task, determine the right tool (Skill) to use, and execute it.
+- **Innovation**: We treat shell commands as first-class citizens. The agent can run `npm install`, `git commit`, or `docker build` just like a human developer.
+
+### 3. The Memory (Context)
+A developer who forgets the codebase every morning is useless. Our agent needs **Memory**.
+- **Role**: Store project context ("This is a TypeScript project"), facts ("Staging IP is 10.0.0.5"), and learnings ("The last build failed because of a missing dependency").
+- **Innovation**: We use SQLite with FTS5 (Full-Text Search) and a JSON-based vector-like storage to quickly retrieve relevant context for every task.
+
+### 4. The Daemon (Autonomy)
+The secret sauce is the loop. A chatbot waits for input. An agent runs in a loop.
+- **Role**: A background process that constantly checks for pending tasks, file changes, or new goals.
+
+## 🛠️ Tech Stack
+
+We're building this in **TypeScript** (Node.js) because:
+- **Ecosystem**: Access to millions of npm packages.
+- **Safety**: Strong typing prevents runtime errors in complex logic flows.
+- **Performance**: Validated through years of enterprise usage.
+
+**Key Libraries:**
+- `better-sqlite3`: Fast, synchronous SQLite access.
+- `commander`: Powerful CLI framework.
+- `openai/anthropic-sdk`: Interface to the LLM brains.
+
+## 🚀 What's Next?
+
+In **Part 2**, we will dive into the code for **The Brain**. We'll write the `GoalDecomposer` class that turns vague requests into structured project plans.
+
+Stay tuned!

package/docs/articles/02-goal-decomposition.md

@@ -0,0 +1,80 @@
+# Building The Brain: AI Goal Decomposition (Part 2/5)
+
+In **Part 1**, we saw that the key difference between a chatbot and an agent is structure.
+
+A chatbot might say: "Here is a list of steps to build a blog."
+An agent says: "I have created 5 pending tasks for you to approve or let me execute."
+
+This transformation happens in the **Planner**.
+
+## 🧠 The `GoalDecomposer`
+
+### The Problem
+LLMs are notoriously bad at holding long chains of reasoning. If you say "Build me a facebook clone", they might hallucinately spit out 200 lines of code and then stop.
+
+### The Solution: Recursion
+Instead of one massive prompt, we can use **Recursive Decomposition**.
+1.  **Receive Goal**: "Build a blog app"
+2.  **Decompose**: Break it into 3-5 high-level tasks.
+    - "Set up Next.js"
+    - "Create Database schema"
+    - "Implement styling"
+3.  **Refine**: If a task is too complex ("Implement styling" is huge), decompose *that* task further.
+
+### 💻 The Code
+
+We built `src/goals/decomposer.ts` to handle this. Here's the core logic:
+
+```typescript
+// 1. Construct the planning prompt
+const systemPrompt = `You are an expert project manager AI.
+Your goal is to break down a high-level objective into actionable, atomic tasks.
+
+Rules:
+1. Each task must be executable by a single skill (e.g., shell command, file write).
+2. Define dependencies (Task B depends on Task A).
+3. If a task is dangerous (e.g., delete DB), mark it 'requiresApproval: true'.
+
+Output ONLY valid JSON:
+{
+  "tasks": [
+    { "title": "...", "skill": "git-clone", "dependsOn": [] },
+    ...
+  ]
+}`;
+
+// 2. Call the LLM
+const completion = await llm.chat({
+    messages: [
+        { role: 'system', content: systemPrompt },
+        { role: 'user', content: `Goal: ${userGoal}` }
+    ]
+});
+
+// 3. Parse and Store
+const plan = JSON.parse(completion.content);
+for (const task of plan.tasks) {
+    await goalStore.addTask(task);
+}
+```
+
+### Why This Works better
+- **Context Window**: By breaking things down, each step fits comfortably in the LLM's context window.
+- **Error Recovery**: If "Set up Database" fails, the agent knows exactly *which* part failed and can retry just that task, instead of restarting the whole conversation.
+- **Parallelism**: Tasks without dependencies can be executed simultaneously (e.g., designing the logo while the database spins up).
+
+### Real-World Example
+
+**Goal**: "Deploy to Vercel"
+
+**Decomposition**:
+1.  Task #1: `vercel login` (Skill: `shell-exec`)
+2.  Task #2: `vercel link` (Skill: `shell-exec`, Depends on #1)
+3.  Task #3: `vercel build` (Skill: `shell-exec`, Depends on #2)
+4.  Task #4: `vercel deploy --prod` (Skill: `shell-exec`, Depends on #3)
+
+This structured approach transforms vague intents into a reliable execution graph.
+
+## 🚀 Next Up: Execution
+
+In **Part 3**, we'll build the engines that actually *do* the work: The **Skill Executor**. We'll learn how to let an AI safely run shell commands.

package/docs/articles/03-skill-execution.md

@@ -0,0 +1,80 @@
+# Building The Body: Skill Execution & Tools (Part 3/5)
+
+In **Part 2**, we built the Brain that breaks goals into tasks. Now, in **Part 3**, we give our agent hands.
+
+The **Executor** is the engine that actually *performs* actions. It takes a task like "Run tests" and translates it into real-world commands (`npm test`).
+
+## 🛠️ Skills as Code
+
+A "Skill" is simply a prompt that teaches the LLM how to use a specific tool. We store skills as markdown files (`prompt.md`).
+
+Example Skill: `git-commit`
+```markdown
+# Git Commit Skill
+
+## Usage
+When asked to commit changes, determine the message based on diffs.
+
+## Output Format
+```bash
+git add .
+git commit -m "feat: updated user model"
+```
+```
+
+This simple format allows anyone to add new capabilities without writing complex TypeScript logic.
+
+## ⚡ The `TaskExecutor`
+
+The `TaskExecutor` class (`src/goals/executor.ts`) is responsible for:
+1.  **Reading Task**: "Commit changes"
+2.  **Matching Skill**: Find `git-commit` skill.
+3.  **Prompting LLM**: Combine task + skill + context into a prompt.
+4.  **Executing Commands**: Safely run the extracted shell commands.
+
+### Key Logic:
+
+```typescript
+// 1. Prepare Prompt
+const prompt = `You are executing task: "${task.title}".
+Use the skill: "${task.skill}".
+
+Current Directory: ${process.cwd()}
+
+Write the exact shell commands needed inside a bash block.`;
+
+// 2. Get Commands from LLM
+const response = await llm.chat({ messages: [{ content: prompt }] });
+const commands = extractBashBlocks(response.content);
+
+// 3. Execute Safely
+for (const cmd of commands) {
+    if (isDangerous(cmd)) {
+        await requestApproval(cmd); // Human-in-the-loop safety
+    }
+    const result = await execAsync(cmd);
+    task.output += result.stdout;
+}
+```
+
+### Safety First: The Human-in-the-loop
+
+Giving an AI shell access is inherently risky. We mitigate this with:
+- **Permission Scoping**: Skills can be marked `requiresApproval: true`.
+- **Command Whitelisting**: Certain commands (`rm -rf /`) are blocked by default.
+- **Sandboxing**: (Future) Run commands in Docker containers.
+
+## 🔄 The Execution Loop
+
+The agent runs in a loop via the `Daemon` (`src/daemon/service.ts`).
+1.  **Check Queue**: Any pending tasks?
+2.  **Pop Task**: Get highest priority task.
+3.  **Execute**: Run `TaskExecutor.execute(task)`.
+4.  **Analyze**: Did it succeed?
+    - **Success**: Mark task complete, update goal progress.
+    - **Failure**: Auto-retry or mark as failed.
+5.  **Log**: Record activity in persistent memory.
+
+## 🚀 Next Up: Memory
+
+An agent needs to remember what it did yesterday. In **Part 4**, we'll build the **Memory Store** using SQLite and Vector Search.

package/docs/articles/04-memory-persistence.md

@@ -0,0 +1,69 @@
+# Building The Memory: Long-Term Context (Part 4/5)
+
+In **Part 3**, we gave our agent hands to execute tasks. But an agent with amnesia is frustrating.
+
+Imagine hiring a developer who forgets your project structure every morning. That's why we need **Long-Term Memory**.
+
+## 🧠 The Problem of Context
+
+LLMs have limited context windows (e.g., 128k tokens). You can't fit your entire codebase, documentation, and history into every prompt. We need to selectively retrieve only relevant information.
+
+## 💾 The Solution: SQLite + Semantic Search
+
+We built a custom `MemoryStore` using `better-sqlite3`.
+
+### 1. Structured Data (Relational)
+Tasks, Goals, and Metrics fit perfectly into traditional SQL tables.
+- `goals`: Track high-level objectives.
+- `tasks`: Track individual steps and success/failure.
+- `audit_events`: immutable log of every action taken.
+
+### 2. Unstructured Data (Semantic)
+But what about "The login button is broken on mobile"? This is unstructured text.
+We store this in a `memories` table with **Vector Embeddings** or **Full-Text Search (FTS5)**.
+
+We chose FTS5 for simplicity and speed:
+```sql
+CREATE VIRTUAL TABLE memories_fts USING fts5(content, metadata);
+```
+
+When you search for "login bug", SQLite's FTS5 engine finds relevant rows instantly based on keywords, even in large datasets.
+
+### 💻 The Implementation
+
+In `src/memory/store.ts`:
+
+```typescript
+// 1. Save a Memory
+memoryStore.save(
+    "The login button is broken on mobile Safari.",
+    "fact", // Type: fact, rule, learned
+    "web-app", // Domain/Project
+    ["bug", "login", "mobile"] // Tags
+_ );
+
+// 2. Retrieve Context
+const relevant = memoryStore.search("login issues", 5);
+// Returns: [{ content: "The login button is broken...", score: ... }]
+
+// 3. Use in Prompt
+const prompt = `Task: Fix login bug.
+Context:
+${relevant.map(m => `- ${m.content}`).join('\n')}
+
+Based on this context, write a fix.`;
+```
+
+## 🔄 The Learning Loop
+
+Every time a task completes successfully (or fails spectacularly), we record a **Learned Memory**.
+
+- **Success**: "Using `image: node:18-alpine` fixed the build error."
+- **Failure**: "Don't use `rm -rf` without checking path first."
+
+The next time a similar task comes up ("Fix build error"), the agent searches its memory, finds the previous solution, and applies it automatically. This creates a compounding intelligence effect.
+
+## 🚀 Next Up: Self-Improvement
+
+In the final **Part 5**, we'll cover the most exciting feature: **The Auto-Fixer**.
+How can an agent detect its own bugs and rewrite its own code?

package/docs/articles/05-self-improvement.md

@@ -0,0 +1,89 @@
+# Building Self-Improvement: The Auto-Fixer (Part 5/5)
+
+In **Part 1-4**, we built an agent that can plan, execute, and remember. But like any junior developer, it will make mistakes.
+
+What if the `npm-install` skill breaks because of a new error message format?
+
+Normally, you'd fix the code. But an **Autonomous Agent** should fix *itself*.
+
+## ❤️ The Metrics
+
+First, we need to know something is broken. We track **Skill Metrics** (`src/memory/store.ts`):
+
+```sql
+CREATE TABLE skill_metrics (
+    skill TEXT PRIMARY KEY,
+    calls INTEGER DEFAULT 0,
+    successes INTEGER DEFAULT 0,
+    failures INTEGER DEFAULT 0,
+    total_duration_ms INTEGER DEFAULT 0
+);
+```
+
+Whenever a skill runs, we record the outcome:
+- **Success Rate**: `successes / calls`
+- **Avg Duration**: `total_duration_ms / calls`
+
+If `git-commit` fails 5 times in a row, its success rate drops below 20%. This triggers an alert.
+
+## 🩺 The Doctor
+
+We built `src/skills/doctor.ts`. Its job is to diagnose failing skills.
+
+1.  **Check Metrics**: Find skills with >5 failures or <50% success rate.
+2.  **Analyze Logs**: Retrieve specific error messages (e.g., "fatal: not a git repository").
+3.  **Generate Report**: "Skill `git-commit` is failing because it's running outside a repo."
+
+## 🔧 The Auto-Fixer
+
+The magic happens in `doctor.fix(skillName)`. It uses the LLM to patch the code.
+
+### 1. Construct Prompt
+```typescript
+const prompt = `You act as an AI Tool Developer.
+The skill "${skillName}" is failing repeatedly.
+
+Current Source (prompt.md):
+${currentCode}
+
+Recent Errors:
+- ${error1}
+- ${error2}
+
+Rewrite the prompt to handle these errors.`;
+```
+
+### 2. Generate Patch
+The LLM reads the errors ("not a git repository") and decides to add a check:
+```markdown
+# Git Commit Skill
+## Updated Instructions
+1. Run `git status` first to verify repo.
+2. If distinct, add changes.
+3. Commit.
+```
+
+### 3. Apply & Reload
+The agent overwrites `prompt.md` with the new version and reloads the skill instantly. The next execution uses the fixed logic.
+
+## 🚀 Conclusion
+
+We have built a system that:
+1.  **Decomposes** vague goals into tasks.
+2.  **Executes** tasks using defined skills.
+3.  **Remembers** context and learnings.
+4.  **Monitors** itself and **Fixes** its own tools.
+
+This loop—Plan, Do, Check, Act—is the foundation of autonomy.
+
+### 📚 Series Recap
+
+- **Part 1**: Architecture & Vision
+- **Part 2**: The Brain (Goal Decomposition)
+- **Part 3**: The Body (Skill Execution)
+- **Part 4**: The Memory (Persistence)
+- **Part 5**: Self-Improvement (Auto-Fixer)
+
+You can explore the full source code and contribute at [GitHub](https://github.com/praveencs87/agent).
+
+Happy Hacking!

package/package.json

@@ -1,10 +1,11 @@
 {
     "name": "@praveencs/agent",
-    "version": "0.7.2",
+    "version": "0.7.3",
     "files": [
         "dist",
         "bin",
         "README.md",
+        "docs",
         "src/index.d.ts"
     ],
     "description": "CLI agent runtime with Skill Hub, Plan Files, and permissioned tools",