AI-powered code agent with plan → code → test → verify → PR workflow
npm install @cothink/agentAI-powered development agent integrated into CoThink platform
Plan → Code → Test → Verify → PR workflow, fully automated.
``bash
cd /var/www/cothink
Expected output: ✅ All smoke tests passed!
✨ Features
- Plan → Code → Test Loop: Automated workflow from goal to working code
- Secure Sandbox: Docker-based execution with network isolation
- Policy-Driven: YAML-based permissions for tools and commands
- Multiple LLM Support: Mock (default), OpenAI, Anthropic, Bedrock, Vertex
- Cost Control: Token budgets and cost caps per session
- Artifact Tracking: Diffs, test reports, coverage, logs
- Mock PR Creation: Demo PR generation with full diff
📋 Requirements
- Node.js 18+
- Docker (for sandbox)
- PostgreSQL (reuses CoThink database)
- Redis (optional)
🏗️ Architecture
`
User Goal
↓
Planner Agent (breaks into steps)
↓
Coder Agent (writes patches)
↓
Verifier Agent (runs tests)
↓
Artifacts + Mock PR
`📦 What's Included
`
services/agent/
├── src/
│ ├── index.ts # Fastify server
│ ├── runLoop.ts # Core orchestrator
│ ├── modelRouter.ts # LLM provider abstraction
│ ├── policy.ts # Policy enforcement
│ ├── sandbox.ts # Docker container management
│ ├── tools.ts # fs/shell/test/git tools
│ ├── db.ts # Prisma client
│ ├── types.ts # TypeScript types
│ ├── prompts/
│ │ ├── planner.txt # Planner agent prompt
│ │ ├── coder.txt # Coder agent prompt
│ │ └── verifier.txt # Verifier agent prompt
│ └── routes/
│ ├── projects.ts # Project management
│ ├── sessions.ts # Session execution
│ ├── policy.ts # Policy validation
│ └── pr.ts # PR creation (mock)
├── prisma/
│ └── schema.prisma # Database schema
├── sandbox/
│ └── Dockerfile.sandbox # Secure sandbox image
├── smoke-test.js # End-to-end tests
├── RUNBOOK.md # Detailed runbook
└── README.md # This fileexamples/agent-example/
├── server.js # Simple Express server
├── server.test.js # Jest tests
├── policy.yaml # Security policy
└── TASK.md # Example goal
`🎯 Example Usage
$3
`bash
make agent.dev
`Service runs on
http://localhost:8088$3
`bash
curl -X POST http://localhost:8088/agent/projects \
-H "Content-Type: application/json" \
-H "X-API-Key: dev-secret-key-change-in-production" \
-d '{
"name": "my-app",
"repoPath": "/var/www/cothink/examples/agent-example",
"policyYaml": "version: 1\nallow:\n tools: [fs.read, fs.write, test.run]"
}'
`$3
`bash
Create session
curl -X POST http://localhost:8088/agent/sessions \
-H "Content-Type: application/json" \
-H "X-API-Key: dev-secret-key-change-in-production" \
-d '{
"projectId": "",
"goal": "Add /healthz endpoint with tests"
}' | jq '.session.id'Run session
curl -X POST http://localhost:8088/agent/sessions//run \
-H "X-API-Key: dev-secret-key-change-in-production"Check status
curl http://localhost:8088/agent/sessions/ \
-H "X-API-Key: dev-secret-key-change-in-production"
`$3
`bash
Get logs
curl http://localhost:8088/agent/sessions//logs \
-H "X-API-Key: dev-secret-key-change-in-production"Open mock PR
curl -X POST http://localhost:8088/agent/pr/open \
-H "Content-Type: application/json" \
-H "X-API-Key: dev-secret-key-change-in-production" \
-d '{
"sessionId": "",
"title": "Add healthz endpoint"
}'
`🔒 Security
$3
`yaml
version: 1
allow:
tools:
- fs.read
- fs.write
- fs.diff
- test.run
- shell.exec
shell:
cmd_allowlist:
- npm ci
- npm test
net:
egress_allow: [] # No network by default
limits:
max_steps: 20
wall_clock_minutes: 15
`$3
- ✅ Network isolation (disabled by default)
- ✅ Resource limits (1 CPU, 1.5GB RAM)
- ✅ Timeout per tool call (120s)
- ✅ Policy enforcement on every action
- ✅ Command allowlist
- ✅ Egress control
📊 Database Schema
Uses existing CoThink PostgreSQL database, adds tables:
-
agent_projects - Project configurations
- agent_sessions - Execution sessions
- agent_steps - Step-by-step log
- agent_artifacts - Diffs, test reports, logs
- agent_usage - Token usage and costs🧪 Testing
$3
`bash
make agent.smoke
`This will:
1. ✅ Create project from example
2. ✅ Create session with goal "Add /healthz endpoint"
3. ✅ Run full plan → code → test loop
4. ✅ Verify tests pass
5. ✅ Create mock PR
6. ✅ Print PR URL
$3
`bash
1. Install example deps
cd examples/agent-example
npm install2. Run tests (should have 1 skipped)
npm test3. After agent runs, tests should pass
npm test
`🔧 Configuration
$3
`bash
Database
DATABASE_URL=postgresql://user:pass@localhost:5432/cothinkRedis (optional)
REDIS_URL=redis://localhost:6379Server
PORT=8088
API_KEY=dev-secret-key-change-in-productionModel Provider
MODEL_PROVIDER=mock # or openai, anthropic, bedrock, vertex
MODEL_NAME=gpt-4
OPENAI_API_KEY=sk-...Sandbox
SANDBOX_IMAGE=cothink-agent-sandbox:latest
SANDBOX_TIMEOUT_SECONDS=120
SANDBOX_CPU_LIMIT=1
SANDBOX_MEMORY_LIMIT=1536mLimits
DEFAULT_STEP_BUDGET=20
DEFAULT_COST_CAP_USD=5.0
DEFAULT_WALL_CLOCK_MINUTES=15
`📚 Documentation
- RUNBOOK.md - Detailed operational guide
- /var/www/cothink/docs/AGENT_QUICKSTART.md - Quick start guide
- Prisma Schema - Database schema
- Example Project - Working example
🎨 Frontend Integration
To add a UI for the agent, create a new page in
/var/www/cothink/frontend/src/pages/Agent.tsx:`typescript
// Key features to include:
// 1. Project list/create
// 2. Session list/create
// 3. Real-time logs display
// 4. Diff viewer (unified format)
// 5. Artifacts download
// 6. PR creation button
`🚀 Deployment
$3
`bash
make agent.dev
`$3
`bash
1. Set production env vars
export NODE_ENV=production
export API_KEY=
export MODEL_PROVIDER=openai
export OPENAI_API_KEY=2. Build
make agent.build3. Run
cd services/agent && npm startOr with PM2
pm2 start npm --name "cothink-agent" -- start
`🐛 Troubleshooting
$3
`bash
Check Docker
docker psAdd user to docker group (Linux)
sudo usermod -aG docker $USER
`$3
`bash
Check DATABASE_URL
echo $DATABASE_URLRun migrations
make agent.db.push
`$3
`bash
Check logs
make agent.logsCheck containers
docker ps -a | grep cothink-agentIncrease timeout
SANDBOX_TIMEOUT_SECONDS=300
`📝 Makefile Commands
`bash
make agent.dev # Start development server
make agent.build # Build service and sandbox image
make agent.db.push # Push database schema
make agent.smoke # Run smoke tests
make agent.stop # Stop service
make agent.clean # Clean build artifacts
make agent.logs # Tail logs
`🎯 Acceptance Criteria (from spec)
✅ 1. Boot: Service starts, database connects, Docker available
✅ 2. Plan: Creates concrete plan with ≤5 steps
✅ 3. Code + Verify: Executes loop, applies patches, runs tests
✅ 4. Security: Policy blocks disallowed commands
✅ 5. Open PR: Returns mock PR URL with diff
🔗 API Endpoints
-
GET /health - Health check
- POST /agent/projects - Create project
- GET /agent/projects - List projects
- POST /agent/sessions - Create session
- POST /agent/sessions/:id/run - Run session
- GET /agent/sessions/:id - Get session
- GET /agent/sessions/:id/logs - Get logs
- POST /agent/policy/validate - Validate policy
- POST /agent/pr/open - Open mock PR🎉 Success!
If
make agent.smoke` passes, your CoThink Agent is ready to use!Next steps:
1. Try with your own project
2. Integrate with CoThink UI
3. Configure real LLM providers
4. Deploy to production
Part of the CoThink platform.