CoThink Code Agent

AI-powered development agent integrated into CoThink platform

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

🚀 Quick Start

``bash
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

$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 install

2. Run tests (should have 1 skipped)

npm test

3. After agent runs, tests should pass

npm test
`

🔧 Configuration

$3

`bash


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:

`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.build

3. Run

cd services/agent && npm start

Or with PM2

pm2 start npm --name "cothink-agent" -- start
`

🐛 Troubleshooting

$3

`bash


Check Docker

docker ps

Add user to docker group (Linux)

sudo usermod -aG docker $USER
`

$3

`bash


Check DATABASE_URL

echo $DATABASE_URL

Run migrations

make agent.db.push
`

$3

`bash


Check logs

make agent.logs

Check containers

docker ps -a | grep cothink-agent

Increase 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

📄 License

Part of the CoThink platform.