polyai-agent 1.0.0

package/README.md

@@ -0,0 +1,464 @@
+# polyai-agent
+
+An AI-powered **vibe coder**, **live service debugger**, and **agent session manager** — deployable to npm, usable as a CLI or importable library.
+
+Supports **OpenAI**, **Anthropic**, and **Google Gemini** with streaming responses.
+
+---
+
+## Features
+
+| Feature | Description |
+|---------|-------------|
+| 🤖 Vibe Coder | AI pair-programmer that reads your project context and generates/refactors code |
+| 🔍 Live Debugger | Attach to running services (log files, Docker, processes) and get real-time AI analysis |
+| 📦 Speckits | 7 prebuilt agent configurations: vibe-coder, debugger, code-review, doc-writer, test-writer, refactor, security-audit |
+| 🛡 Guardrails | Per-session rules the AI must follow (allowed paths, denied operations, style rules, custom rules) |
+| 💾 Sessions | Named, persistent sessions with full conversation history and file-change tracking |
+| 🌐 Web UI | Built-in web dashboard to view, manage and export sessions |
+| 📚 Library API | Importable TypeScript module for programmatic use |
+
+---
+
+## Architecture & Flow
+
+### High-Level Architecture
+
+```mermaid
+flowchart TD
+    User([👤 User]) --> CLI["CLI\n<code>ai-agent</code>"]
+    User --> LibAPI["Library API\n<code>import { AgentCLI }</code>"]
+
+    CLI --> Chat["<code>chat</code>\nvibe-coder / speckit"]
+    CLI --> Debug["<code>debug</code>\nLive Debugger"]
+    CLI --> UI["<code>ui</code>\nWeb Dashboard"]
+    CLI --> SessionCmd["<code>session</code>\nSession Manager"]
+    CLI --> Speckit["<code>speckit</code>\nSpeckit Browser"]
+    CLI --> Config["<code>config</code>\nConfiguration"]
+
+    Chat --> SM[Session Manager]
+    LibAPI --> SM
+
+    SM --> Guardrails[🛡 Guardrails]
+    SM --> SpeckitConf[📦 Speckit Config]
+    SM --> Providers
+
+    Debug --> LiveDbg[Live Debugger]
+    LiveDbg --> Providers
+    LiveDbg --> LogSrc[Log Sources]
+
+    LogSrc --> LogFile[📄 Log File]
+    LogSrc --> DockerSrc[🐳 Docker Container]
+    LogSrc --> ProcSrc[⚙️ Process / Command]
+    LogSrc --> HTTPSrc[🌐 HTTP Poll]
+
+    Providers[AI Providers] --> OpenAI[OpenAI]
+    Providers --> Anthropic[Anthropic]
+    Providers --> Gemini[Google Gemini]
+
+    SM --> Storage[(💾 &lt;home&gt;/.polyai-agent/\nsessions)]
+
+    UI --> WebServer["Express + Socket.IO\nWeb Server"]
+    WebServer --> SM
+    SessionCmd --> SM
+```
+
+---
+
+### Chat Session Flow
+
+```mermaid
+sequenceDiagram
+    actor U as User
+    participant CLI as CLI
+    participant SM as Session Manager
+    participant SK as Speckit
+    participant G as Guardrails
+    participant P as AI Provider
+
+    U->>CLI: ai-agent chat --speckit vibe-coder --session my-project
+    CLI->>SM: Create or resume session "my-project"
+    SM->>SK: Load speckit system prompt (vibe-coder)
+    SM->>G: Inject guardrail rules into system prompt
+
+    loop Interactive conversation
+        U->>CLI: Enter message / code request
+        CLI->>P: Send (system prompt + history + message)
+        P-->>CLI: Stream response tokens
+        CLI-->>U: Display streamed response
+        CLI->>SM: Record turn + any file changes
+    end
+
+    U->>CLI: /exit
+    CLI->>SM: Persist session to <home>/.polyai-agent/sessions/
+    SM-->>U: Session saved ✓
+```
+
+---
+
+### Live Debugger Flow
+
+```mermaid
+flowchart LR
+    subgraph Sources["Log Sources"]
+        LF[📄 Log File]
+        DC[🐳 Docker Logs]
+        PR[⚙️ Process stdout]
+        HP[🌐 HTTP Health Poll]
+    end
+
+    subgraph Debugger["Live Debugger"]
+        Collector[Log Collector]
+        Batcher["Batch Buffer\n(configurable size)"]
+        Analyzer[AI Analysis]
+    end
+
+    subgraph Output["Output"]
+        Terminal[Terminal / onAnalysis callback]
+        Session[Session Turn Record]
+    end
+
+    LF --> Collector
+    DC --> Collector
+    PR --> Collector
+    HP --> Collector
+
+    Collector --> Batcher
+    Batcher -->|"batch full or timeout"| Analyzer
+    Analyzer -->|AI Provider| Terminal
+    Analyzer --> Session
+```
+
+---
+
+## Installation
+
+```bash
+# Global install (recommended for CLI use)
+npm install -g polyai-agent
+
+# Dev dependency (for programmatic use)
+npm install --save-dev polyai-agent
+```
+
+---
+
+## Quick Start
+
+### Set your API key
+
+```bash
+export OPENAI_API_KEY=sk-...
+# or
+export ANTHROPIC_API_KEY=sk-ant-...
+# or
+export GEMINI_API_KEY=AIza...
+```
+
+### Start coding
+
+```bash
+ai-agent chat
+```
+
+### Debug a live service
+
+```bash
+ai-agent debug --file /var/log/myapp.log
+ai-agent debug --docker my-container
+ai-agent debug --cmd "node server.js"
+```
+
+### Launch Web UI
+
+```bash
+ai-agent ui
+# Open http://localhost:3000
+```
+
+---
+
+## CLI Reference
+
+```
+Usage: ai-agent [options] [command]
+
+Commands:
+  chat [options]     Start an interactive chat session (vibe coder mode)
+  speckit [name]     List or run a prebuilt speckit
+  debug [options]    Attach to a live service and start AI-assisted debugging
+  session [options]  Manage sessions (list, delete, export)
+  ui [options]       Launch the Web UI
+  config [options]   Configure default settings
+
+Options:
+  -V, --version      output the version number
+  -h, --help         display help for command
+```
+
+### `ai-agent chat`
+
+```bash
+ai-agent chat [options]
+
+Options:
+  -p, --provider <provider>  AI provider (openai|anthropic|gemini)
+  -m, --model <model>        Model name (e.g. gpt-4o)
+  -s, --session <name>       Session name — creates or resumes (default: "default")
+  -k, --speckit <speckit>    Speckit to use (default: vibe-coder)
+  -g, --guardrail <rule>     Add a guardrail rule (repeatable)
+  --context                  Inject project directory structure as context
+```
+
+#### Interactive commands
+
+Inside a chat session:
+
+| Command | Action |
+|---------|--------|
+| `/exit` or `/quit` | End session and save |
+| `/save` | Save current session |
+| `/turns` | Show conversation history |
+| `/context` | Inject current project context |
+
+### `ai-agent speckit`
+
+```bash
+ai-agent speckit           # list all speckits
+ai-agent speckit vibe-coder  # show details of a speckit
+```
+
+### `ai-agent debug`
+
+```bash
+ai-agent debug --file /var/log/app.log         # Watch a log file
+ai-agent debug --docker my-container           # Docker container logs
+ai-agent debug --cmd "node server.js"          # Attach to a process
+ai-agent debug --batch 30 --session my-debug   # Custom batch size
+```
+
+### `ai-agent session`
+
+```bash
+ai-agent session --list           # List all sessions
+ai-agent session --delete <id>    # Delete a session
+ai-agent session --export <id>    # Print session JSON
+```
+
+### `ai-agent ui`
+
+```bash
+ai-agent ui               # Start on default port 3000
+ai-agent ui --port 8080   # Custom port
+```
+
+### `ai-agent config`
+
+```bash
+ai-agent config --show              # Show current config
+ai-agent config --provider openai   # Set default provider
+ai-agent config --model gpt-4o      # Set default model
+ai-agent config --port 3000         # Set default Web UI port
+```
+
+---
+
+## Speckits
+
+Speckits are pre-configured agent personas. Use `--speckit <name>` with `chat`.
+
+| Name | Description |
+|------|-------------|
+| `vibe-coder` | Full-stack AI pair programmer (default) |
+| `debugger` | Root-cause analysis and targeted code fixes |
+| `code-review` | OWASP/quality review with severity grading |
+| `doc-writer` | JSDoc, README, OpenAPI docs generation |
+| `test-writer` | Unit and integration test generation |
+| `refactor` | Structural refactoring without changing behavior |
+| `security-audit` | OWASP Top 10 security vulnerability scan |
+
+```bash
+ai-agent chat --speckit security-audit
+```
+
+---
+
+## Guardrails
+
+Guardrails are rules injected into the AI's system prompt to constrain its behavior.
+
+```bash
+# Only allow changes in src/
+ai-agent chat -g "Only modify files within the src/ directory"
+
+# Enforce code style
+ai-agent chat -g "Always use TypeScript strict mode" -g "Prefer async/await over callbacks"
+
+# Multiple guardrails
+ai-agent chat \
+  -g "Never delete files" \
+  -g "Always write unit tests for new functions" \
+  -g "Use camelCase for all variable names"
+```
+
+### Guardrail types (programmatic API)
+
+```typescript
+import { createGuardrail } from 'polyai-agent';
+
+createGuardrail('allow-paths', ['./src', './tests'])
+createGuardrail('deny-paths', ['./node_modules', './.env'])
+createGuardrail('deny-operations', ['delete', 'overwrite'])
+createGuardrail('max-tokens', 2000)
+createGuardrail('style', 'Use functional programming patterns')
+createGuardrail('custom', 'Always add JSDoc to exported functions')
+```
+
+---
+
+## Configuration File
+
+Create `.polyai-agent.json` in your project root:
+
+```json
+{
+  "provider": "openai",
+  "model": "gpt-4o",
+  "port": 3000,
+  "guardrails": [
+    { "type": "custom", "value": "Always use TypeScript" }
+  ]
+}
+```
+
+Or `~/.polyai-agent/config.json` for global settings.
+
+**API keys are never stored in config files** — use environment variables:
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GEMINI_API_KEY=AIza...
+AI_PROVIDER=openai
+AI_MODEL=gpt-4o
+AI_AGENT_PORT=3000
+```
+
+---
+
+## Library / Programmatic API
+
+```typescript
+import { AgentCLI, createGuardrail } from 'polyai-agent';
+
+// Create an agent instance
+const agent = new AgentCLI({
+  provider: 'openai',   // or 'anthropic', 'gemini'
+  model: 'gpt-4o',
+  apiKey: process.env.OPENAI_API_KEY,
+});
+
+// One-shot chat
+const response = await agent.chat('Write a hello world in Rust');
+console.log(response);
+
+// Session-based chat with guardrails
+const session = agent.createSession({
+  name: 'my-project',
+  speckit: 'vibe-coder',
+  guardrails: [
+    createGuardrail('allow-paths', ['./src']),
+    createGuardrail('custom', 'Always add TypeScript types'),
+  ],
+});
+
+const turn = await session.chat('Add a user authentication middleware');
+console.log(turn.assistantMessage);
+
+// Apply a file change
+session.applyFileChange('./src/middleware/auth.ts', '// new content...');
+
+// Revert the change
+session.revertTurnChanges(turn.id);
+
+// Save session
+agent.sessionManager.persistSession(session);
+```
+
+### Live Debugger API
+
+```typescript
+import { AgentCLI, LiveDebugger } from 'polyai-agent';
+
+const agent = new AgentCLI({ provider: 'openai' });
+const session = agent.createSession({ name: 'debug', speckit: 'debugger' });
+
+const debugger_ = new LiveDebugger({
+  session,
+  batchSize: 20,
+  onLog: (line) => console.log(line),
+  onAnalysis: (analysis) => console.log('AI:', analysis),
+});
+
+// Watch a log file
+debugger_.watchLogFile('/var/log/app.log');
+
+// Or connect to a service
+debugger_.connectToService({ type: 'docker', container: 'my-app' });
+debugger_.connectToService({ type: 'process', command: 'node', args: ['server.js'] });
+debugger_.connectToService({ type: 'http-poll', url: 'http://localhost:8080/health' });
+
+// Stop
+process.on('SIGINT', () => debugger_.stop());
+```
+
+### Web Server API
+
+```typescript
+import { AgentCLI, createWebServer } from 'polyai-agent';
+
+const agent = new AgentCLI({ provider: 'openai' });
+const server = createWebServer({ port: 3000, sessionManager: agent.sessionManager });
+await server.start();
+```
+
+---
+
+## Web UI
+
+Start with `ai-agent ui` and open `http://localhost:3000`.
+
+- **Sessions Dashboard** — view all sessions, status, provider, model
+- **Session Detail** — browse conversation turns, guardrails, file changes
+- **Settings** — configure default provider and model
+- **Export** — download any session as JSON
+- **Real-time updates** — via Socket.IO
+
+---
+
+## Providers & Models
+
+| Provider | Env Variable | Recommended Models |
+|----------|-------------|-------------------|
+| OpenAI | `OPENAI_API_KEY` | `gpt-4o`, `gpt-4o-mini`, `gpt-4-turbo` |
+| Anthropic | `ANTHROPIC_API_KEY` | `claude-3-5-sonnet-20241022`, `claude-3-5-haiku-20241022` |
+| Google Gemini | `GEMINI_API_KEY` | `gemini-1.5-pro`, `gemini-1.5-flash` |
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/fury-r/ai-agent-cli.git
+cd ai-agent-cli
+npm install
+npm run build
+npm test
+npm run dev -- chat   # run CLI in dev mode
+```
+
+---
+
+## License
+
+MIT

package/REQUIREMENTS.md

@@ -0,0 +1,158 @@
+# AI Agent CLI — Requirements Document
+
+## Overview
+**polyai-agent** is an npm-deployable TypeScript tool that integrates with top AI providers and acts as a _vibe coder_, session manager, live-service debugger, and provides a Web UI for managing AI agent sessions.
+
+---
+
+## 1. Functional Requirements
+
+### 1.1 Multi-Provider AI Integration
+- Support **OpenAI** (GPT-4o, GPT-4-turbo, GPT-3.5-turbo)
+- Support **Anthropic** (Claude 3.5 Sonnet, Claude 3 Haiku)
+- Support **Google Gemini** (gemini-1.5-pro, gemini-1.5-flash)
+- Provider selection via config file, environment variable, or CLI flag
+- Streaming responses supported for all providers
+
+### 1.2 Vibe Coder Mode
+- Acts as an AI pair-programmer that understands project context
+- Reads local files and directory structures to build context
+- Generates, modifies, and refactors code based on natural-language prompts
+- Applies changes to files automatically with user confirmation step
+- Uses speckit templates for common coding patterns
+
+### 1.3 Prebuilt Speckits
+Speckits are pre-configured agent configurations (similar to GitHub speckit concept — opinionated starter templates):
+- **vibe-coder**: Full-stack code generation and refactoring
+- **debugger**: Analyze logs, traces, and errors to suggest fixes
+- **code-review**: Review code for quality, security, and best practices
+- **doc-writer**: Generate or improve documentation
+- **test-writer**: Generate unit and integration tests
+- **refactor**: Suggest and apply structural refactoring
+- **security-audit**: Scan code for security vulnerabilities
+
+### 1.4 Live Service Debugger
+- Connect to a running service via:
+  - Log file watching (tail -f)
+  - HTTP endpoint polling
+  - Docker container log streaming
+  - Process stdout/stderr attachment
+- Stream logs to the AI provider in real time
+- AI analyzes errors and proposes code fixes
+- Apply fixes directly to the codebase
+- Supports rollback of applied fixes
+
+### 1.5 Session Management
+- Create named agent sessions with unique IDs
+- Persist session history (conversation, files changed, fixes applied)
+- Resume interrupted sessions
+- Sessions stored in `~/.polyai-agent/sessions/`
+- Session export to JSON
+
+### 1.6 Guardrails & Rules
+Configurable per-session rules that the AI must follow or must not violate:
+- **Allowed file paths**: restrict file access to specific directories
+- **Forbidden operations**: prevent deletion, overwrite of certain files
+- **Max tokens / cost limit**: cap spending per session
+- **Style rules**: enforce coding style (language, framework, patterns)
+- **Custom rules**: free-text rules injected into system prompt
+- Rules defined in `.polyai-agent.json` or per-session config
+
+### 1.7 Web UI
+- Built-in Express + Socket.IO web server
+- **Sessions Dashboard**: list all sessions, status, timestamps
+- **Session Detail**: conversation history, file diffs, guardrails
+- **Live Debugger View**: real-time log stream + AI analysis
+- **Settings**: configure API keys, default provider, global guardrails
+- Accessible at `http://localhost:PORT` (default 3000)
+
+### 1.8 CLI Interface
+```
+ai-agent [command] [options]
+
+Commands:
+  chat          Start an interactive chat session (vibe coder mode)
+  speckit       List or run a prebuilt speckit
+  debug         Attach to a live service and start debugging
+  session       Manage sessions (list, resume, delete, export)
+  ui            Launch the Web UI
+  config        Configure API keys and settings
+
+Options:
+  --provider    AI provider (openai|anthropic|gemini)
+  --model       Specific model to use
+  --session     Session name or ID
+  --speckit     Speckit to use
+  --guardrail   Add a guardrail rule
+  --port        Web UI port (default: 3000)
+```
+
+### 1.9 Library / Programmatic API
+```typescript
+import { AgentCLI, Session, providers, speckits } from 'polyai-agent';
+
+const agent = new AgentCLI({ provider: 'openai', model: 'gpt-4o' });
+const session = await agent.createSession({ name: 'my-session', guardrails: [...] });
+const response = await session.chat('Refactor this function...');
+```
+
+---
+
+## 2. Non-Functional Requirements
+
+- **Language**: TypeScript (compiled to JS for distribution)
+- **Node.js**: >=18.0.0
+- **Streaming**: All AI calls support streaming output
+- **Security**: API keys never logged or stored in plaintext in session files
+- **Configuration**: `.polyai-agent.json` in project root or `~/.polyai-agent/config.json`
+- **Error handling**: Graceful fallback, meaningful error messages
+- **Extensibility**: Provider and speckit plug-in architecture
+
+---
+
+## 3. Architecture
+
+```
+src/
+├── index.ts              # Library entry point
+├── cli.ts                # CLI entry point (bin)
+├── providers/            # AI provider adapters
+│   ├── base.ts
+│   ├── openai.ts
+│   ├── anthropic.ts
+│   └── gemini.ts
+├── session/              # Session management
+│   ├── session.ts
+│   ├── session-manager.ts
+│   └── guardrails.ts
+├── speckits/             # Prebuilt speckit templates
+│   ├── index.ts
+│   ├── vibe-coder.ts
+│   ├── debugger.ts
+│   ├── code-review.ts
+│   ├── doc-writer.ts
+│   ├── test-writer.ts
+│   ├── refactor.ts
+│   └── security-audit.ts
+├── live-debugger/        # Live service debugger
+│   ├── index.ts
+│   ├── log-watcher.ts
+│   └── service-connector.ts
+├── web/                  # Web UI
+│   ├── server.ts
+│   ├── routes/
+│   └── public/
+└── utils/
+    ├── config.ts
+    ├── file-ops.ts
+    └── logger.ts
+```
+
+---
+
+## 4. Deployment
+
+- Published to **npm** as `polyai-agent`
+- Global install: `npm install -g polyai-agent`
+- Local dev dependency: `npm install --save-dev polyai-agent`
+- Binary: `ai-agent` (aliased as `aac`)

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}