quay-ai-factory 0.3.0 → 0.3.1

package/README.md

@@ -1,18 +1,18 @@
 # Quay - Autonomous AI Software Factory
 
-> Self-hosted AI agents with MCP integration, customizable pipelines, real-time Mission Control dashboard, cost transparency, and full audit trails.
+> Self-hosted AI agents with MCP integration, A3M routing, customizable pipelines, real-time Mission Control dashboard, cost transparency, and full audit trails.
 
 ## 🚀 Features
 
 ### 5 AI-Powered Features (Built on A3M Router)
 
-| Feature | Description |
-|---------|-------------|
-| **Human-in-Loop Verification** | Require approval before critical actions (deploy, delete) |
-| **Determinism & Replay** | Black-box recorder captures every step for reproducibility |
-| **Visual Pipeline Builder** | Drag-drop YAML pipeline generation with built-in templates |
-| **Agent RAG** | Knowledge grounding to reduce hallucinations |
-| **Self-Healing Agents** | Auto-detect and recover from failures |
+| Feature | Description | Agent Integration |
+|---------|-------------|-------------------|
+| **Human-in-Loop Verification** | Require approval before critical actions | Auto-triggers on deploy, delete, rm, etc. |
+| **Determinism & Replay** | Black-box recorder captures every step | Snapshots after each LLM call |
+| **Visual Pipeline Builder** | Drag-drop YAML pipeline generation | Built-in templates for common workflows |
+| **Agent RAG** | Knowledge grounding to reduce hallucinations | Applied before first LLM call |
+| **Self-Healing Agents** | Auto-detect and recover from failures | Detects 7 failure types, 5 recovery strategies |
 
 ### Core Capabilities
 
@@ -25,7 +25,7 @@
 ## 📦 Installation
 
 ```bash
-npm install
+npm install quay-ai-factory
 ```
 
 ## 🏃‍♂️ Running
@@ -42,6 +42,88 @@ node build
 bun test
 ```
 
+## 🤖 Agent Runner
+
+The `AgentRunner` orchestrates the observe→plan→act loop with all 5 AI features:
+
+```typescript
+import { agentRunner } from './server/agents/agentRunner.js';
+
+// Run an agent with all features enabled
+const result = await agentRunner.run(
+  { id: 'task-1', title: 'Deploy to production', description: '...' },
+  { id: 'agent-1', name: 'DeployBot', type: 'coder', provider: 'openai', model: 'gpt-4o', config: '{}' },
+  'run-123',
+  'You are a deployment agent...',
+  ['bash', 'deploy'],
+  {
+    knowledgeBaseId: 'kb-1',        // Enable RAG grounding
+    verificationConfig: {            // Custom verification rules
+      criticalActions: ['deploy', 'delete'],
+      autoApproveBelow: 0.10,
+    },
+    maxSteps: 30,                   // Custom step limit
+  }
+);
+```
+
+### How Features Integrate
+
+```
+User Request
+    ↓
+AgentRunner.run()
+    ↓
+┌─────────────────────────────────────────┐
+│ 1. RAG Grounding                        │
+│    buildGroundedPrompt()                │
+│    → Adds relevant knowledge to prompt  │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 2. LLM Call                             │
+│    callLLM() with A3M routing           │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 3. Self-Healing Check                   │
+│    detectFailure() → getRecoveryStrategy│
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 4. Determinism Snapshot                 │
+│    createSnapshot() with state hash     │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 5. Health Update                        │
+│    updateHealthStatus()                 │
+└─────────────────────────────────────────┘
+    ↓
+┌─────────────────────────────────────────┐
+│ 6. Critical Action Verification        │
+│    createVerificationRequest()          │
+│    → Pauses if approval needed         │
+└─────────────────────────────────────────┘
+    ↓
+Tool Execution → Loop
+```
+
+## 🔧 Configuration
+
+```bash
+# Environment variables
+OPENAI_API_KEY=sk-...                    # OpenAI API key
+ANTHROPIC_API_KEY=sk-ant-...             # Anthropic API key
+QUAY_DEFAULT_LLM_URL=https://api.openai.com/v1  # Default LLM endpoint
+
+EMBEDDING_PROVIDER=openai                # openai, local, or mock
+EMBEDDING_ENDPOINT=http://localhost:11434/api/embeddings
+QUAY_DB_PATH=./quay.db                   # Database path
+SSE_ENABLED=true                         # Enable SSE
+NODE_ENV=production                      # production, development, test
+```
+
 ## 🧪 Features
 
 ### Verification Dashboard (`/verification`)
@@ -64,6 +146,8 @@ const request = await createVerificationRequest(
 approveRequest(request.id, 'admin');
 ```
 
+**Critical Actions** (auto-detected): `deploy`, `delete`, `rm`, `drop`, `truncate`, `shutdown`, `restart`
+
 ### Health Monitor (`/health`)
 Real-time agent health status with self-healing.
 
@@ -76,8 +160,13 @@ updateHealthStatus('agent-1', { latencyMs: 150, success: true });
 // Detect failure and get recovery strategy
 const failure = detectFailure(new Error('timeout'));
 const strategy = getRecoveryStrategy(failure.type);
+// → { action: 'retry', maxRetries: 3, fallbackModel: 'gpt-4o-mini' }
 ```
 
+**Failure Types**: `timeout`, `rate_limit`, `api_error`, `context_overflow`, `tool_error`, `unknown`
+
+**Recovery Strategies**: `retry`, `fallback_model`, `fallback_agent`, `abort`, `skip_step`
+
 ### Knowledge Base (`/knowledge`)
 RAG-powered knowledge grounding.
 
@@ -103,6 +192,8 @@ const templates = getTemplates('code-review');
 const yaml = generateYAML(nodes, edges);
 ```
 
+**Built-in Templates**: `code-review`, `security-scan`, `data-processing`, `research-agent`
+
 ### Replay (`/replay`)
 Deterministic replay of agent runs.
 
@@ -113,43 +204,34 @@ await createSnapshot(runId, stepIndex, state);
 const session = await startReplay(runId);
 ```
 
-## 🔧 Configuration
-
-```bash
-# Environment variables
-OPENAI_API_KEY=sk-...          # OpenAI API key
-EMBEDDING_PROVIDER=openai       # openai, local, or mock
-EMBEDDING_ENDPOINT=http://localhost:11434/api/embeddings
-QUAY_DB_PATH=./quay.db          # Database path
-SSE_ENABLED=true                # Enable SSE
-NODE_ENV=production             # production, development, test
-```
-
 ## 📁 Project Structure
 
 ```
 quay/
 ├── src/
 │   ├── lib/
-│   │   ├── features/          # 5 AI features
-│   │   │   ├── verification.ts
-│   │   │   ├── determinism.ts
-│   │   │   ├── visualBuilder.ts
-│   │   │   ├── agentRAG.ts
-│   │   │   └── selfHealing.ts
-│   │   ├── components/         # Svelte UI components
-│   │   ├── sse/              # SSE broadcaster
-│   │   ├── a3m.ts            # A3M router integration
-│   │   ├── db.ts             # Database layer
-│   │   └── embedding.ts       # Embedding service
+│   │   ├── features/              # 5 AI features
+│   │   │   ├── verification.ts    # Human-in-loop
+│   │   │   ├── determinism.ts     # Snapshots & replay
+│   │   │   ├── visualBuilder.ts   # Pipeline builder
+│   │   │   ├── agentRAG.ts        # Knowledge grounding
+│   │   │   └── selfHealing.ts     # Auto-recovery
+│   │   ├── components/            # Svelte UI components
+│   │   ├── sse/                  # SSE broadcaster
+│   │   ├── a3m.ts                 # A3M router integration
+│   │   ├── db.ts                  # Database layer
+│   │   └── embedding.ts           # Embedding service
 │   ├── routes/
-│   │   ├── api/              # API endpoints
-│   │   └── [page].svelte     # UI pages
+│   │   ├── api/                   # API endpoints
+│   │   └── [page].svelte          # UI pages
 │   └── server/
-│       ├── db/                # Database schema
-│       └── a3m/               # A3M config
+│       ├── agents/
+│       │   └── agentRunner.ts     # Main agent loop (integrates all features)
+│       ├── db/                    # Database schema
+│       ├── features/              # Feature implementations
+│       └── ...
 └── tests/
-    └── __tests__/             # Integration tests
+    └── __tests__/                 # Integration tests
 ```
 
 ## 🧪 Testing
@@ -172,7 +254,6 @@ Total: 56 tests passing
 | Endpoint | Description |
 |----------|-------------|
 | `GET /api/verification` | List verification requests |
-| `POST /api/verification` | Create verification request |
 | `POST /api/verification/[id]/approve` | Approve request |
 | `POST /api/verification/[id]/reject` | Reject request |
 | `GET /api/agent-health` | Get all agent health status |
@@ -188,7 +269,7 @@ Total: 56 tests passing
 
 | Route | Description |
 |-------|-------------|
-| `/` | Home |
+| `/` | Home / Mission Control |
 | `/features` | Features dashboard |
 | `/verification` | Verification dashboard |
 | `/health` | Agent health monitor |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quay-ai-factory",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Quay — Autonomous AI Software Factory. Self-hosted AI agents, MCP integration, customizable pipelines, real-time Mission Control dashboard, cost transparency, and full audit trails.",
   "keywords": [
     "ai-software-factory",