@trygentic/agentloop 0.1.1-alpha.1

package/LICENSE

@@ -0,0 +1,39 @@
+**Commercial License Agreement**
+Software: AgentLoop
+Copyright © Troy Edwards Jr, All Rights Reserved
+
+This Software is licensed, not sold.
+
+1. Grant of Use
+   You may install and use this Software only while you have a valid, active paid subscription to Your Service and only for your own internal use.
+
+2. No Redistribution
+   You may not copy, publish, distribute, or share the Software or make it available to any third party.
+
+3. No Reverse Engineering
+   You may not reverse engineer, decompile, disassemble, modify, or attempt to derive the source code, internal logic, or algorithms of the Software, except where such restriction is prohibited by law.
+
+4. Subscription & Access Requirements
+   Use of this Software requires an authenticated account and an active subscription.
+   If your subscription ends or is revoked, your right to use the Software ends immediately.
+
+5. API Keys & Credentials
+   API keys, tokens, and login credentials are personal to you.
+   You may not share them or use them to provide the Service to others.
+
+6. Prohibited Uses
+   You may not use the Software to build or train competing products or services.
+
+7. Ownership
+   All rights, title, and interest in the Software remain with the Licensor. No rights are granted except those explicitly stated in this Agreement.
+
+8. Termination
+   The Licensor may terminate this license if you violate these terms. Upon termination, you must stop using the Software and delete all copies.
+
+9. No Warranty
+   The Software is provided “as is” without warranties of any kind.
+
+10. Limitation of Liability
+    To the maximum extent permitted by law, the Licensor is not liable for any damages arising from the use or inability to use the Software.
+
+By installing or using this Software, you agree to these terms.

package/README.md

@@ -0,0 +1,607 @@
+<p align="center">
+  <a href="https://www.agentloop.run">
+    <img src="https://www.agentloop.run/_next/image?url=%2Flogo_no_text_big.png&w=384&q=75&dpl=dpl_8iUBYWKRHdJzWcavR94X4nKpB4aC" alt="AgentLoop Logo" width="150" />
+  </a>
+</p>
+
+<h1 align="center">AgentLoop</h1>
+
+<p align="center">
+  <strong>Autonomous Multi-Agent Orchestration for Software Development</strong>
+</p>
+
+<p align="center">
+  <a href="https://www.agentloop.run">Website</a> &bull;
+  <a href="#installation">Installation</a> &bull;
+  <a href="#features">Features</a> &bull;
+  <a href="#interactive-commands">Commands</a> &bull;
+  <a href="https://discord.gg/B3SQ7mRQY8">Discord</a>
+</p>
+
+---
+
+## Overview
+
+AgentLoop is an autonomous agent orchestrator that coordinates multiple AI agents working together to complete complex software development tasks. Specialized agents analyze, implement, and test your code—all managed through an intelligent workflow with full human oversight.
+
+## Installation
+
+### Global Installation (Recommended)
+
+```bash
+npm install -g @trygentic/agentloop
+```
+
+### Local Installation
+
+```bash
+npm install @trygentic/agentloop
+```
+
+### Run Without Installing
+
+```bash
+npx @trygentic/agentloop
+```
+
+## Quick Start
+
+```bash
+# Start interactive mode
+agentloop
+
+# Run the orchestrator
+agentloop orchestrator
+
+# Send a single query
+agentloop query "Analyze the architecture of this project"
+```
+
+### Interacting with AgentLoop
+
+In interactive mode, you can communicate with agents using natural language—just type your message and press Enter. No slash commands required for conversations. AgentLoop uses tool calls behind the scenes to update the kanban board, manage tasks and dependencies in the DAG, and delegate work to specialized agents like Engineer and QA.
+
+```
+> Break down "user authentication" into tasks and add them to the board
+> What's the status of task 5? Mark it as in-progress
+> Have the engineer agent implement the login API endpoint
+> Ask the QA agent to test the new authentication flow
+> Add a dependency so task 3 must complete before task 7
+> Move all completed tasks to done and show me the kanban board
+```
+
+Slash commands (like `/orchestrator run` or `/tasks`) are available for system operations, but day-to-day interaction—including task management, agent coordination, and board updates—is conversational.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                              AgentLoop CLI                                  │
+│                    Interactive Mode / Query Mode / Daemon                   │
+└─────────────────────────────────┬───────────────────────────────────────────┘
+                                  │
+                                  ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                            ORCHESTRATOR                                     │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                      DAG Task Scheduler                             │    │
+│  │         Manages dependencies, parallelism, and execution order      │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+│  ┌─────────────────────────────────────────────────────────────────────┐    │
+│  │                     Behavior Tree Engine                            │    │
+│  │           Decision logic, validation layers, AI management          │    │
+│  └─────────────────────────────────────────────────────────────────────┘    │
+└─────────────────────────────────┬───────────────────────────────────────────┘
+                                  │
+            ┌─────────────────────┼─────────────────────┐
+            │                     │                     │
+            ▼                     ▼                     ▼
+┌───────────────────┐ ┌───────────────────┐ ┌───────────────────┐
+│  Product Manager  │ │    Engineer(s)    │ │    QA Tester      │
+│      Agent        │ │      Agents       │ │      Agent        │
+│                   │ │                   │ │                   │
+│ • Task breakdown  │ │ • Code changes    │ │ • Test execution  │
+│ • AGILE planning  │ │ • Git operations  │ │ • Validation      │
+│ • User stories    │ │ • PR creation     │ │ • Issue reporting │
+└───────────────────┘ └───────────────────┘ └───────────────────┘
+            │                     │                    │
+            │         ┌───────────┴───────────┐        │
+            │         ▼                       ▼        │
+            │  ┌─────────────┐       ┌─────────────┐   │
+            │  │  Worktree 1 │       │  Worktree 2 │   │
+            │  │  (branch-a) │       │  (branch-b) │   │
+            │  └─────────────┘       └─────────────┘   │
+            │                                          │
+            └──────────────────┬───────────────────────┘
+                               ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                           Kanban Board                                      │
+│  ┌─────────┐  ┌─────────────┐  ┌────────┐  ┌──────┐  ┌─────────┐            │
+│  │  Todo   │  │ In Progress │  │ Review │  │ Done │  │ Blocked │            │
+│  │         │  │             │  │        │  │      │  │         │            │
+│  │ Task 1  │  │   Task 3    │  │ Task 5 │  │Task 7│  │ Task 9  │            │
+│  │ Task 2  │  │   Task 4    │  │ Task 6 │  │Task 8│  │         │            │
+│  └─────────┘  └─────────────┘  └────────┘  └──────┘  └─────────┘            │
+└─────────────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                        External Integrations                                │
+│         ┌──────────┐    ┌──────────┐    ┌──────────┐                        │
+│         │   Jira   │    │  GitHub  │    │   MCP    │                        │
+│         │   Sync   │    │   PRs    │    │ Servers  │                        │
+│         └──────────┘    └──────────┘    └──────────┘                        │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+### How It Works
+
+1. **Task Creation** - Define tasks manually, generate them from descriptions using the Product Manager agent, or sync from Jira
+2. **DAG Scheduling** - The orchestrator analyzes task dependencies and creates an optimal execution plan
+3. **Parallel Execution** - Multiple engineer agents work simultaneously on independent tasks
+4. **Isolated Environments** - Each agent can work in its own git worktree or container sandbox
+5. **Quality Gates** - QA agents validate completed work before marking tasks done
+6. **Continuous Loop** - The orchestrator monitors progress and handles failures with self-healing recovery
+
+## Features
+
+### Multi-Agent Orchestration
+
+AgentLoop coordinates multiple specialized AI agents that work together seamlessly:
+
+- **Orchestrator Agent** - Manages overall workflow, delegates tasks, and ensures smooth handoffs between agents
+- **Product Manager Agent** - Breaks down project descriptions into AGILE tasks, user stories, and sprint plans
+- **Engineer Agent** - Autonomous code implementation with proper git workflows
+- **QA Tester Agent** - Automated testing, issue identification, and validation
+- **Code Analyzer Agent** - Deep codebase analysis for architecture and dependency understanding
+
+### Parallel Agent Execution
+
+Multiple engineer agents can work on different tasks simultaneously, dramatically reducing development time through true concurrency with configurable parallelism limits.
+
+### DAG-Based Task Management
+
+Define task dependencies using a Directed Acyclic Graph (DAG) and let the orchestrator automatically determine the optimal execution order. The system maximizes parallelism while respecting prerequisites and handles complex dependency chains intelligently.
+
+### Interactive Kanban Board
+
+Visual task management with a terminal-based kanban board showing tasks across columns: Todo, In Progress, Review, Done, and Blocked. Navigate, update, and manage tasks directly from the terminal.
+
+### Intelligent Planning
+
+Interactive planning sessions help gather requirements, clarify scope, and generate comprehensive task breakdowns. The questionnaire system adapts based on previous answers for intelligent requirements gathering.
+
+### Self-Healing & Recovery
+
+- Automatic detection and recovery from orphaned tasks
+- Process health monitoring with cleanup of stale executions
+- Race condition prevention for task state consistency
+- Recovery from crashes and restarts
+
+### Behavior Tree System
+
+Configurable, modular decision-making logic for agents using industry-standard behavior tree patterns. Includes validation layers and live AI management for adaptive agent behavior.
+
+### Jira Integration
+
+Bidirectional synchronization with Jira Cloud:
+- OAuth 2.0 and Basic Auth support
+- Automatic task syncing
+- AI-powered DAG planning from Jira issues
+- Sprint and board management
+
+### Plugin System
+
+Extend AgentLoop with custom agents, behavior trees, and configurations:
+- Custom agent templates using markdown
+- Three-layer configuration (build-time, runtime, per-project)
+- MCP (Model Context Protocol) integration for external tools
+
+---
+
+## Git Worktrees
+
+AgentLoop leverages Git worktrees to enable true parallel development. Each worktree is a separate working directory linked to the same repository, allowing multiple agents to work on different branches simultaneously without conflicts.
+
+```
+Main Repository (.git)
+        │
+        ├── Main Working Directory (main branch)
+        │
+        ├── .worktrees/
+        │       ├── feature-auth/     ← Agent 1 working here
+        │       │   └── (branch: feature/auth)
+        │       │
+        │       ├── feature-api/      ← Agent 2 working here
+        │       │   └── (branch: feature/api)
+        │       │
+        │       └── bugfix-login/     ← Agent 3 working here
+        │           └── (branch: bugfix/login)
+```
+
+### Benefits
+
+- **No Merge Conflicts During Work** - Each agent has its own isolated working directory
+- **True Parallelism** - Multiple agents can compile, test, and modify code simultaneously
+- **Branch Isolation** - Changes in one worktree don't affect others until merged
+- **Efficient Storage** - Worktrees share the same Git objects, minimizing disk usage
+
+### Worktree Commands
+
+| Command | Description |
+|---------|-------------|
+| `/worktrees` | Open interactive worktree management view |
+| `/worktrees list` | List all active worktrees |
+| `/worktrees status` | Show worktree status summary |
+| `/worktrees help` | Display worktree usage guide |
+
+---
+
+## Container Sandboxing (Podman)
+
+AgentLoop supports optional container-based isolation using Podman, providing an additional layer of security for agent execution. When enabled, agents run inside containers with restricted filesystem and network access.
+
+> **Note:** Docker support is coming soon.
+
+```
+┌─────────────────────────────────────────────────────────┐
+│                    Host System                          │
+│                                                         │
+│  ┌───────────────────────────────────────────────────┐  │
+│  │              Podman Container                     │  │
+│  │  ┌─────────────────────────────────────────────┐  │  │
+│  │  │            Engineer Agent                   │  │  │
+│  │  │                                             │  │  │
+│  │  │  • Restricted filesystem access             │  │  │
+│  │  │  • Network isolation (configurable)         │  │  │
+│  │  │  • Resource limits (CPU, memory)            │  │  │
+│  │  │  • No access to host system files           │  │  │
+│  │  └─────────────────────────────────────────────┘  │  │
+│  │                       │                           │  │
+│  │              Mount: /workspace                    │  │
+│  │                       │                           │  │
+│  └───────────────────────┼───────────────────────────┘  │
+│                          │                              │
+│                          ▼                              │
+│              Project Directory (read/write)             │
+└─────────────────────────────────────────────────────────┘
+```
+
+### Why Use Sandboxing?
+
+- **Security** - Agents cannot access sensitive files outside the project
+- **Isolation** - Failed or misbehaving agents can't affect the host system
+- **Reproducibility** - Consistent execution environment across different machines
+- **Resource Control** - Limit CPU and memory usage per agent
+
+### Setup Commands
+
+| Command | Description |
+|---------|-------------|
+| `/setup podman` | Interactive Podman installation and configuration |
+| `/setup podman status` | Check Podman installation and container status |
+| `/setup podman help` | Display sandboxing configuration guide |
+| `/orchestrator sandbox` | Manage sandbox settings for agent execution |
+
+---
+
+## Background Daemon
+
+The AgentLoop daemon allows you to run the orchestrator as a persistent background service. This is useful for long-running tasks, CI/CD integration, or when you want sessions to survive terminal closures.
+
+```
+┌──────────────────────────────────────────────────────────────────┐
+│                         User Terminal                            │
+│                                                                  │
+│   $ agentloop                    $ agentloop                     │
+│   > /daemon start                > /orchestrator status          │
+│   Daemon started ✓               Connected to daemon...          │
+│   > /exit                        Orchestrator: running           │
+│   (terminal closed)              Tasks: 3 in-progress            │
+│                                                                  │
+└──────────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌──────────────────────────────────────────────────────────────────┐
+│                    Background Daemon Process                     │
+│                                                                  │
+│   ┌────────────────────────────────────────────────────────┐     │
+│   │                   Orchestrator                         │     │
+│   │                                                        │     │
+│   │  • Continues running after terminal closes             │     │
+│   │  • Processes tasks autonomously                        │     │
+│   │  • Maintains session state and history                 │     │
+│   │  • Reconnectable from any terminal                     │     │
+│   │  • Automatic recovery from interruptions               │     │
+│   └────────────────────────────────────────────────────────┘     │
+│                                                                  │
+│   Session Data: ~/.agentloop/daemon/                             │
+│   Logs: ~/.agentloop/logs/                                       │
+└──────────────────────────────────────────────────────────────────┘
+```
+
+### Use Cases
+
+- **Long-Running Tasks** - Start a large refactoring job and disconnect; reconnect later to check progress
+- **CI/CD Integration** - Run the daemon in your build pipeline for automated code generation
+- **Remote Development** - SSH into a server, start the daemon, disconnect, and reconnect later. You can also work directly on mounted worktrees from your local IDE without needing to SSH
+- **Persistent Sessions** - Conversation history and task state persist across CLI restarts
+
+### Daemon Commands
+
+| Command | Description |
+|---------|-------------|
+| `/daemon start` | Start the background daemon service |
+| `/daemon stop` | Stop the running daemon |
+| `/daemon restart` | Restart the daemon (useful after configuration changes) |
+| `/daemon status` | Check if daemon is running and view connection info |
+
+---
+
+## Interactive Commands
+
+### Core Commands
+
+| Command | Description |
+|---------|-------------|
+| `/help` | Show all available commands |
+| `/exit` | Exit interactive mode |
+| `/clear` | Clear conversation history |
+| `/init` | Detect project type and initialize AgentLoop |
+
+### Orchestrator Commands
+
+| Command | Description |
+|---------|-------------|
+| `/orchestrator run` | Run the orchestrator (processes tasks until complete) |
+| `/orchestrator run --infinite` | Run continuously, watching for new tasks |
+| `/orchestrator generate <description>` | Generate AGILE tasks from a project description |
+| `/orchestrator status` | Show current orchestrator status |
+| `/orchestrator agents` | Live agent monitoring with real-time status |
+| `/orchestrator kanban` | Open interactive kanban board |
+| `/orchestrator stop` | Stop the running orchestrator |
+| `/orchestrator clear` | Clear all tasks for the current project |
+| `/orchestrator logs <task-id>` | Show agent execution logs for a task |
+
+### DAG Commands
+
+| Command | Description |
+|---------|-------------|
+| `/orchestrator dag` | Show DAG status with statistics |
+| `/orchestrator dag ascii` | ASCII visualization of task dependencies |
+| `/orchestrator dag dot` | Export DAG in DOT format |
+
+### Task Commands
+
+| Command | Description |
+|---------|-------------|
+| `/tasks` | List all tasks in the current project |
+| `/tasks --status <status>` | Filter by status (todo, in-progress, review, done, blocked) |
+| `/tasks --priority <priority>` | Filter by priority (low, medium, high, critical) |
+| `/task add <title> <description>` | Add a new task |
+
+### Configuration Commands
+
+| Command | Description |
+|---------|-------------|
+| `/config show` | Show current configuration |
+| `/config set-token <token>` | Set authentication token |
+| `/config set-base-url <url>` | Set API base URL |
+| `/config clear` | Clear configuration |
+| `/settings show` | Show current settings |
+| `/settings telemetry [on\|off]` | Enable or disable telemetry |
+
+### Jira Integration
+
+| Command | Description |
+|---------|-------------|
+| `/jira sync` | Bidirectional sync with Jira |
+| `/jira sync-dag` | AI-powered sync with dependency analysis |
+| `/jira configure siteUrl <url>` | Set Jira site URL |
+| `/jira configure projectKey <key>` | Set Jira project key |
+| `/jira configure boardId <id>` | Set Jira board ID |
+| `/jira set-auth <email> <token>` | Set Basic Auth credentials |
+| `/jira set-oauth <id> <secret>` | Set OAuth credentials |
+| `/jira authorize` | Perform OAuth authorization |
+| `/jira status` | Show Jira integration status |
+
+### Mock & Testing
+
+| Command | Description |
+|---------|-------------|
+| `/mock` | Open mock configuration view |
+| `/mock status` | Show mock configuration status |
+| `/mock enable` | Enable mock mode |
+| `/mock disable` | Disable mock mode |
+
+---
+
+## Configuration
+
+AgentLoop uses TOML configuration files with a layered priority system.
+
+### Configuration File Locations
+
+| Location | Purpose |
+|----------|---------|
+| `./.agentloop/config.toml` | Project-level config (local overrides) |
+| `~/.agentloop/config.toml` | User-level config (global defaults) |
+| `~/.config/agentloop/` | Database, credentials, and cache |
+
+### Configuration Priority (Highest to Lowest)
+
+1. Environment variables
+2. Project config (`./.agentloop/config.toml`)
+3. User config (`~/.agentloop/config.toml`)
+4. Default values
+
+---
+
+### Orchestrator Settings
+
+```toml
+[orchestrator]
+max_parallel_agents = 1        # Number of agents that can run in parallel
+use_worktrees = false          # Enable git worktrees for parallel development
+worktrees_dir = ".worktrees"   # Directory for worktrees (relative to project)
+cleanup_worktrees_on_complete = false  # Auto-cleanup worktrees after completion
+```
+
+| Option | Default | Env Variable | Description |
+|--------|---------|--------------|-------------|
+| `max_parallel_agents` | `1` | `AGENTLOOP_MAX_PARALLEL_AGENTS` | Maximum parallel agents |
+| `use_worktrees` | `false` | `AGENTLOOP_USE_WORKTREES` | Enable git worktrees |
+| `worktrees_dir` | `.worktrees` | `AGENTLOOP_WORKTREES_DIR` | Worktrees directory |
+| `cleanup_worktrees_on_complete` | `false` | `AGENTLOOP_CLEANUP_WORKTREES` | Auto-cleanup worktrees |
+
+---
+
+### Container Sandbox Settings
+
+```toml
+[orchestrator.container_sandbox]
+enabled = false                    # Enable Podman sandboxing
+container_image = "agentloop-worker"
+network_mode = "slirp4netns"       # none, slirp4netns, or host
+memory_limit = "4g"
+cpu_limit = "2"
+
+[orchestrator.container_sandbox.agent_images]
+engineer = "agentloop-worker"
+qa-tester = "agentloop-qa-worker"
+analyzer = "agentloop-worker"
+product-manager = "agentloop-worker"
+```
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `enabled` | `false` | Enable container sandboxing |
+| `container_image` | `agentloop-worker` | Default container image |
+| `network_mode` | `slirp4netns` | Network isolation mode |
+| `memory_limit` | `4g` | Memory limit per container |
+| `cpu_limit` | `2` | CPU limit per container |
+
+---
+
+### GitHub Settings
+
+```toml
+[github]
+enabled = true
+token = "ghp_your_token_here"   # Or use GITHUB_PERSONAL_ACCESS_TOKEN env var
+```
+
+| Option | Default | Env Variable | Description |
+|--------|---------|--------------|-------------|
+| `enabled` | `true` | - | Enable GitHub integration |
+| `token` | - | `GITHUB_PERSONAL_ACCESS_TOKEN` | GitHub PAT (scopes: repo, workflow) |
+
+---
+
+### Jira Settings
+
+```toml
+[jira]
+siteUrl = "https://yourcompany.atlassian.net"
+project = "PROJ"
+boardId = "123"
+
+# Basic Auth (simpler)
+email = "user@example.com"
+apiToken = "your_api_token"
+
+# Or OAuth (more secure) - set via /jira set-oauth command
+# clientId = "your_oauth_client_id"
+# clientSecret = "your_oauth_client_secret"
+```
+
+| Option | Description |
+|--------|-------------|
+| `siteUrl` | Jira site URL |
+| `project` | Jira project key |
+| `boardId` | Board ID for accurate syncing (find in board URL) |
+| `email` | Email for Basic Auth |
+| `apiToken` | API token for Basic Auth |
+
+---
+
+### Example Configuration
+
+**User-level defaults** (`~/.agentloop/config.toml`):
+```toml
+[github]
+enabled = true
+
+[orchestrator]
+max_parallel_agents = 4
+use_worktrees = true
+```
+
+**Project-level overrides** (`./.agentloop/config.toml`):
+```toml
+[orchestrator]
+max_parallel_agents = 10
+
+[orchestrator.container_sandbox]
+enabled = true
+network_mode = "slirp4netns"
+
+[jira]
+siteUrl = "https://company.atlassian.net"
+project = "MYPROJ"
+boardId = "42"
+```
+
+---
+
+## Preview Features (Alpha)
+
+The following features are in active development and available for early testing. They may change significantly or be incomplete.
+
+### Planning & Requirements
+
+| Command | Description |
+|---------|-------------|
+| `/planning` | Start interactive PM agent planning session |
+| `/questionnaire` | Open questionnaire DAG view |
+| `/bt` | Open behavior tree debug view |
+
+---
+
+## CLI Commands
+
+```bash
+# Start interactive session
+agentloop
+
+# Run orchestrator directly
+agentloop orchestrator
+
+# Single query mode
+agentloop query "Your question here"
+
+# Authentication management
+agentloop auth status
+agentloop auth logout
+agentloop auth switch
+
+# Configuration
+agentloop config
+```
+
+## Requirements
+
+- Node.js >= 18.0.0
+- npm or yarn
+- Podman (optional, for container sandboxing)
+
+## License
+
+See [License](./license)
+
+## Support
+
+For issues, questions, or contributions:
+
+- **Discord**: [Join our community](https://discord.gg/B3SQ7mRQY8)
+- **Website**: [agentloop.run](https://www.agentloop.run)