CoThink Code Agent

AI-powered development agent integrated into CoThink platform

Plan → Code → Test → Verify → PR workflow, fully automated.

🚀 Quick Start

cd /var/www/cothink

# 1. Build everything
make agent.build

# 2. Start service
make agent.dev

# 3. Run smoke test
make agent.smoke

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 file

examples/agent-example/
├── server.js                 # Simple Express server
├── server.test.js            # Jest tests
├── policy.yaml               # Security policy
└── TASK.md                   # Example goal

🎯 Example Usage

1. Start the Service

make agent.dev

Service runs on http://localhost:8088

2. Create a Project

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. Create and Run a Session

# 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": "<project-id>",
    "goal": "Add /healthz endpoint with tests"
  }' | jq '.session.id'

# Run session
curl -X POST http://localhost:8088/agent/sessions/<session-id>/run \
  -H "X-API-Key: dev-secret-key-change-in-production"

# Check status
curl http://localhost:8088/agent/sessions/<session-id> \
  -H "X-API-Key: dev-secret-key-change-in-production"

4. View Results

# Get logs
curl http://localhost:8088/agent/sessions/<session-id>/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": "<session-id>",
    "title": "Add healthz endpoint"
  }'

🔒 Security

Policy Example

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

Sandbox Features

• ✅ 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

Smoke Test

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

Manual Testing

# 1. Install example deps
cd examples/agent-example
npm install

# 2. Run tests (should have 1 skipped)
npm test

# 3. After agent runs, tests should pass
npm test

🔧 Configuration

Environment Variables

# Database
DATABASE_URL=postgresql://user:pass@localhost:5432/cothink

# Redis (optional)
REDIS_URL=redis://localhost:6379

# Server
PORT=8088
API_KEY=dev-secret-key-change-in-production

# Model 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=1536m

# Limits
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:

// 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

Development

make agent.dev

Production

# 1. Set production env vars
export NODE_ENV=production
export API_KEY=<strong-key>
export MODEL_PROVIDER=openai
export OPENAI_API_KEY=<real-key>

# 2. Build
make agent.build

# 3. Run
cd services/agent && npm start

# Or with PM2
pm2 start npm --name "cothink-agent" -- start

🐛 Troubleshooting

Docker Not Available

# Check Docker
docker ps

# Add user to docker group (Linux)
sudo usermod -aG docker $USER

Database Connection Failed

# Check DATABASE_URL
echo $DATABASE_URL

# Run migrations
make agent.db.push

Session Stuck

# Check logs
make agent.logs

# Check containers
docker ps -a | grep cothink-agent

# Increase timeout
SANDBOX_TIMEOUT_SECONDS=300

📝 Makefile Commands

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

📄 License

Part of the CoThink platform.