@praveencs/agent 0.9.8 → 0.9.10

package/docs/articles/09-agent-studio.md

@@ -0,0 +1,154 @@
+# Agent Studio — Visual Management Console
+
+> The web-based command center for your Agent Runtime instances.
+
+Agent Studio is the visual companion to the CLI. It provides a unified dashboard where
+you can monitor live instances, manage goals, create skills and commands, control the
+daemon, and explore agent memory — all from your browser.
+
+---
+
+## 🚀 Launching Studio
+
+```bash
+agent studio
+# → Agent Studio running at http://localhost:3333
+```
+
+The command starts an Express server that serves both the REST API and the React frontend.
+
+---
+
+## Dashboard
+
+The landing page shows all active Agent instances — both interactive REPL sessions and
+background daemon processes.
+
+Each instance card displays:
+- **Project name** and working directory  
+- **PID** for process identification  
+- **Status badge** (Active / Daemon)  
+- Quick navigation buttons for Console and Capabilities
+
+![Agent Studio Dashboard](studio-screenshot-1.png)
+
+---
+
+## Instance Control Panel
+
+Click any instance to enter the **control panel** with a sidebar of 9 sections:
+
+| Section | Purpose |
+|---------|---------|
+| **Console** | Live terminal — send commands, see agent output in real-time |
+| **Capabilities** | Read-only view of loaded skills, commands, scripts, plugins |
+| **Goals & Plans** | Create goals, view tasks, update statuses |
+| **Skills** | CRUD manager for skill definitions (skill.json + prompt.md) |
+| **Commands** | Create/delete lightweight command templates |
+| **Scripts** | Create/delete local automation scripts |
+| **Plugins** | View and remove installed plugin bundles |
+| **Daemon** | Start/stop the background worker, view daemon logs |
+| **Memory** | Search, add, and browse persistent agent memories |
+
+![Agent Console View](studio-screenshot-agent-console-2.png)
+
+---
+
+## Goals & Plans
+
+The Goals panel lets you:
+
+1. **Create goals** with title, description, and priority
+2. **View task breakdown** — expand a goal to see its decomposed tasks
+3. **Update status** — pause, resume, or complete goals
+4. **Delete goals** and their associated tasks
+
+Each task shows its execution status (pending → running → completed/failed) and
+the assigned skill.
+
+---
+
+## Skills Manager
+
+Skills are reusable AI capabilities defined by `skill.json` + `prompt.md`.
+
+From the Studio you can:
+- **Create** a new skill with name, description, tools, and prompt content
+- **Edit** the prompt markdown inline with a code editor
+- **Delete** skills you no longer need
+
+Changes are written directly to `.agent/skills/` on disk.
+
+---
+
+## Commands Manager
+
+Commands are lightweight goal templates — just markdown files with YAML frontmatter.
+
+- **Create** commands with name, description, allowed tools, and body
+- **Delete** commands
+- Commands appear as `/slash-commands` in the interactive REPL
+
+---
+
+## Scripts Manager
+
+Scripts are deterministic automation tasks (shell, TypeScript, Python) with a
+`script.yaml` manifest.
+
+- **Create** scripts by choosing a language and writing the entrypoint
+- **Delete** scripts
+- Scripts execute without LLM involvement — perfect for CI/CD
+
+---
+
+## Daemon Control
+
+The daemon is the background worker that processes goals autonomously.
+
+- **Start/Stop** the daemon with one click
+- **Live status** — see PID, uptime, and running state
+- **Log viewer** — color-coded logs with auto-refresh
+
+---
+
+## Memory Explorer
+
+Agent memory is a SQLite-backed persistent store with full-text search.
+
+- **Search** across all memories using FTS5
+- **Add** new memories with category and tags
+- **Browse** memories grouped by category (project, fact, preference, learned, general)
+- **Delete** individual memories
+- **Stats** — see totals broken down by category
+
+---
+
+## REST API
+
+Studio exposes a comprehensive REST API. See [API Reference](../API.md) for full details.
+
+Key endpoints:
+- `GET /api/instances` — list active instances
+- `POST /api/instances/:id/goals` — create a goal
+- `GET /api/instances/:id/skills` — list skills
+- `POST /api/instances/:id/memory` — add a memory
+- `POST /api/instances/:id/daemon/start` — start the daemon
+
+---
+
+## Architecture
+
+```
+Browser (React + Vite)
+      ↕ HTTP/WebSocket
+Studio Server (Express + Socket.IO)
+      ↕
+Agent Runtime (GoalStore, SkillLoader, MemoryStore, DaemonManager)
+      ↕
+File System (.agent/) + SQLite (agent.db)
+```
+
+The Studio server reuses the same classes as the CLI — `GoalStore`, `SkillLoader`,
+`CommandLoader`, `ScriptLoader`, `MemoryStore`, `DaemonManager` — so all operations
+are consistent between CLI and UI.

package/docs/articles/10-llm-providers.md

@@ -0,0 +1,118 @@
+# LLM Providers — Configuration & Routing
+
+> How the Agent Runtime connects to multiple AI providers with automatic fallback.
+
+---
+
+## Supported Providers
+
+| Provider | Module | SDK | Environment Variable |
+|----------|--------|-----|---------------------|
+| **OpenAI** | `openai.ts` | `openai` | `OPENAI_API_KEY` |
+| **Azure OpenAI** | `azure.ts` | `openai` | `AZURE_OPENAI_API_KEY`, `AZURE_OPENAI_ENDPOINT` |
+| **Anthropic** | `anthropic.ts` | `@anthropic-ai/sdk` | `ANTHROPIC_API_KEY` |
+| **Ollama** | `ollama.ts` | HTTP fetch | — (local, port 11434) |
+
+---
+
+## Configuration
+
+Set your preferred provider and model in `agent.config.json` or `.agent/config.json`:
+
+```json
+{
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4o",
+    "temperature": 0.2,
+    "maxTokens": 4096
+  }
+}
+```
+
+### Provider-Specific Config
+
+**OpenAI / Azure:**
+```json
+{
+  "llm": {
+    "provider": "openai",
+    "model": "gpt-4o",
+    "apiKey": "sk-..."
+  }
+}
+```
+
+**Anthropic:**
+```json
+{
+  "llm": {
+    "provider": "anthropic",
+    "model": "claude-sonnet-4-20250514",
+    "apiKey": "sk-ant-..."
+  }
+}
+```
+
+**Ollama (local):**
+```json
+{
+  "llm": {
+    "provider": "ollama",
+    "model": "llama3",
+    "baseUrl": "http://localhost:11434"
+  }
+}
+```
+
+API keys can also be set via environment variables (`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, etc.).
+Environment variables take precedence over config file values.
+
+---
+
+## LLM Router
+
+The **LLM Router** (`src/llm/router.ts`) is the core abstraction that:
+
+1. Selects the correct provider adapter based on config
+2. Sanitizes tool names for provider compatibility (e.g., dots → underscores for OpenAI)
+3. Forwards chat requests with the full message history
+4. Handles tool call serialization for each provider's expected format
+
+### Tool Name Sanitization
+
+Different providers have different naming rules. The router automatically transforms:
+- `fs.read` → `fs_read` (for OpenAI/Azure which reject dots)
+- Tool calls in conversation history are also sanitized to maintain consistency
+
+### Message Mapping
+
+Each provider adapter maps the internal message format to the provider-specific API:
+
+| Internal | OpenAI | Anthropic | Ollama |
+|----------|--------|-----------|--------|
+| `role: 'tool'` | `role: 'tool'` | `role: 'user'` + `tool_result` block | `role: 'tool'` |
+| `toolCalls` on assistant | `tool_calls` array | `tool_use` content blocks | `tool_calls` array |
+| System message | `role: 'system'` | `system` parameter | `role: 'system'` |
+
+---
+
+## Fallback Chain
+
+The router supports fallback to local models when cloud providers fail:
+
+```
+openai/gpt-4o  →  anthropic/claude-sonnet  →  ollama/llama3
+```
+
+If the primary provider returns an error or times out, the router automatically
+retries with the next provider in the chain.
+
+---
+
+## Adding a New Provider
+
+1. Create `src/llm/providers/my-provider.ts`
+2. Implement the `LLMProvider` interface with a `chat(request)` method
+3. Map messages from internal format to provider format
+4. Register in `src/llm/router.ts`

package/docs/articles/11-policy-approvals.md

@@ -0,0 +1,118 @@
+# Policy & Approvals — Permission-Gated Execution
+
+> How the Agent Runtime keeps humans in the loop for sensitive operations.
+
+---
+
+## Overview
+
+The Agent Runtime uses a **Policy Engine** to gate tool execution. Every tool action
+passes through a permission check, and high-risk operations require explicit human
+approval before proceeding.
+
+---
+
+## Risk Levels
+
+Tools are categorized into risk levels:
+
+| Level | Examples | Behavior |
+|-------|----------|----------|
+| **low** | `fs.read`, `project.detect` | Auto-approved, no prompt |
+| **medium** | `fs.write`, `git.status` | Logged, may require approval based on policy |
+| **high** | `cmd.run`, `git.push` | Always requires human approval |
+| **critical** | `fs.delete`, system-level ops | Always requires approval + confirmation |
+
+---
+
+## Approval Flow
+
+### CLI Mode
+
+When a tool requires approval in the interactive REPL:
+
+```
+  ⚡ cmd.run("npm install express")
+  ⚠ This action requires approval.
+  Allow? (y/n) ▊
+```
+
+The REPL pauses execution, displays the tool name and arguments, and waits for
+the user to approve (`y`) or deny (`n`).
+
+### Studio Mode (Remote Approval)
+
+When running via daemon or in a remote session, approval requests are relayed
+via WebSocket to the Studio UI:
+
+```
+Agent CLI  →  Socket.IO  →  Studio Server  →  Browser UI
+                                    ↓
+                            Approval Button
+                                    ↓
+Agent CLI  ←  Socket.IO  ←  Studio Server  ←  User clicks "Allow"
+```
+
+The Studio console shows an approval card with:
+- Tool name and arguments
+- Risk level badge
+- **Allow** / **Deny** buttons
+
+---
+
+## Configuration
+
+Customize the policy in `.agent/config.json`:
+
+```json
+{
+  "policy": {
+    "autoAllow": ["fs.read", "fs.list", "project.detect"],
+    "alwaysAsk": ["cmd.run", "fs.delete"],
+    "denyList": ["cmd.run:rm -rf /"]
+  }
+}
+```
+
+### Fields
+
+| Field | Description |
+|-------|-------------|
+| `autoAllow` | Tools that never require approval |
+| `alwaysAsk` | Tools that always require approval regardless of risk level |
+| `denyList` | Specific tool+args combinations that are always denied |
+
+---
+
+## Audit Trail
+
+Every tool execution is logged to the audit system:
+
+- **Tool name** and arguments
+- **Approval status** (auto-approved, human-approved, denied)
+- **Timestamp** and **run ID**
+- **Duration** and result
+
+Access audit logs via:
+```bash
+agent memory search "audit"
+# or in Studio → Memory Explorer → search "audit"
+```
+
+---
+
+## Task-Level Approval
+
+Goals can mark individual tasks as requiring approval:
+
+```typescript
+goalStore.addTask(goalId, "Deploy to production", {
+    requiresApproval: true,
+    skill: "deploy-staging"
+});
+```
+
+These tasks enter a `pending` state until approved via:
+- CLI: `agent goal approve <taskId>`
+- Studio: Goals panel → Approve button
+- API: `POST /api/instances/:id/tasks/:taskId/approve`

package/docs/articles/12-daemon-automation.md

@@ -0,0 +1,123 @@
+# Daemon & Background Automation
+
+> Autonomous goal execution with scheduling, triggers, and monitoring.
+
+---
+
+## Overview
+
+The **Daemon** is a background worker that processes goals and tasks autonomously
+without human interaction. It picks up queued tasks, executes them using the
+appropriate skills, and handles retries and failures.
+
+---
+
+## Starting the Daemon
+
+### CLI
+```bash
+agent daemon start    # Start background worker
+agent daemon status   # Check if running
+agent daemon stop     # Stop the worker
+agent daemon logs     # View recent logs
+```
+
+### Studio
+Navigate to **Daemon** in the sidebar → click **Start Daemon**.
+
+### API
+```bash
+curl -X POST http://localhost:3333/api/instances/:id/daemon/start
+curl http://localhost:3333/api/instances/:id/daemon/status
+```
+
+---
+
+## How It Works
+
+```
+┌─────────────┐     ┌──────────────┐     ┌─────────────┐
+│  Goal Store  │ ──→ │   Scheduler  │ ──→ │   Executor  │
+│  (SQLite)    │     │  (picks next │     │  (runs task  │
+│              │     │   task)      │     │   via skill) │
+└─────────────┘     └──────────────┘     └─────────────┘
+       ↑                                        │
+       └────────── Results Written Back ────────┘
+```
+
+1. **Goal Store** holds all goals and tasks in SQLite
+2. **Scheduler** polls for the next executable task (respecting dependencies)
+3. **Executor** runs the task using the assigned skill
+4. Results (success/failure) are written back to the store
+5. Goal progress is auto-calculated based on task completion
+
+---
+
+## Task Dependencies
+
+Tasks can depend on other tasks:
+
+```typescript
+goalStore.addTask(goalId, "Install dependencies", { skill: "npm-install" });
+goalStore.addTask(goalId, "Run tests", {
+    skill: "test-runner",
+    dependsOn: [1]  // Won't start until task 1 completes
+});
+```
+
+The scheduler only picks tasks whose dependencies are all `completed`.
+
+---
+
+## Retry & Failure Handling
+
+| Strategy | Behavior |
+|----------|----------|
+| `retry` | Re-execute the task up to `maxRetries` times |
+| `abort` | Stop the entire plan on first failure |
+| `skip` | Mark as failed but continue with remaining tasks |
+
+---
+
+## File Watcher
+
+The daemon includes a file watcher (`src/daemon/watcher.ts`) that can trigger
+tasks when files change:
+
+```json
+{
+  "daemon": {
+    "watch": ["src/**/*.ts"],
+    "onFileChange": "lint-and-test"
+  }
+}
+```
+
+---
+
+## Triggers
+
+Custom triggers (`src/daemon/triggers.ts`) define when tasks should execute:
+
+- **cron** — Schedule tasks on a cron expression
+- **file-change** — React to file system events
+- **webhook** — HTTP POST triggers task execution
+- **manual** — Only execute when explicitly started
+
+---
+
+## Monitoring
+
+### CLI
+```bash
+agent daemon status    # Running | Stopped, PID, uptime
+agent daemon logs      # Last 30 lines of daemon.log
+agent goal status 1    # Task-level progress for goal #1
+```
+
+### Studio
+The Daemon panel provides:
+- Live status indicator (green = running)
+- Start/Stop buttons
+- Color-coded log viewer with auto-refresh
+- PID and uptime display

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@praveencs/agent",
-    "version": "0.9.8",
+    "version": "0.9.10",
     "files": [
         "dist",
         "bin",