AGENT INTERACTIVITY

Comprehensive guidelines for AI-assisted development within the Editor platform

Real-Time Agent Interactivity Architecture

Status: Proposed + Partial Implementation Date: February 2, 2026 Session: 81

The Problem

Currently, agent communication is human-mediated:

Cowork creates a handoff via HTTP API
Human tells Cursor to check handoffs
Cursor calls check_handoffs, processes, responds
Human relays result to Cowork

Goal: Remove human from the loop for agentic intercommunication.

Architecture Options

Option A: Polling-based (IMPLEMENTED)

┌─────────────┐     HTTP      ┌─────────────────┐
│   Cowork    │ ───────────► │  Backend API    │
│   Agent     │              │  (3001)         │
└─────────────┘              │                 │
                             │  Handoffs DB    │
                             │       ▲         │
┌─────────────┐     MCP      │       │         │
│   Cursor    │ ◄──────────► │  watch_handoffs │
│   Agent     │   (polling)  │  (5s interval)  │
└─────────────┘              └─────────────────┘

How it works:

Cowork creates handoff via POST /api/handoffs
Cursor runs watch_handoffs tool (polling every 5s)
When handoff found, Cursor auto-processes
Cursor calls complete_handoff with result
Cowork polls check_handoffs to see result

Pros: Works with current MCP architecture Cons: 5s latency, not truly real-time

Option B: WebSocket Bridge (FUTURE)

┌─────────────┐     WebSocket ┌─────────────────┐
│   Cowork    │ ◄───────────► │  Backend WS     │
│   Agent     │               │  Gateway        │
└─────────────┘               │       ▲         │
                              │       │         │
┌─────────────┐     WebSocket │       │         │
│   Cursor    │ ◄───────────► │  Native WS      │
│   Agent     │               │  Gateway        │
└─────────────┘               └─────────────────┘

How it works:

Both agents connect to WebSocket gateway
Handoff creation broadcasts to all connected agents
Cursor receives push notification immediately
Processing and response is real-time

Pros: True real-time, bidirectional Cons: Requires MCP server to maintain WebSocket connection

Option C: Event Queue (FUTURE)

┌─────────────┐               ┌─────────────────┐
│   Cowork    │ ──────────►   │  Redis/NATS     │
└─────────────┘    publish    │  Message Queue  │
                              │       │         │
┌─────────────┐    subscribe  │       ▼         │
│   Cursor    │ ◄─────────────│  Event Stream   │
└─────────────┘               └─────────────────┘

Pros: Scalable, reliable, decoupled Cons: Additional infrastructure

Current Implementation (Option A)

New MCP Tool: `watch_handoffs`

{
  name: 'watch_handoffs',
  description: 'Watch for incoming handoffs from external agents. Polls every 5 seconds until a handoff arrives or timeout.',
  inputSchema: {
    type: 'object',
    properties: {
      timeout: { type: 'number', description: 'Max seconds to wait (default: 300 = 5 min)' },
      pollInterval: { type: 'number', description: 'Seconds between polls (default: 5)' },
      autoAccept: { type: 'boolean', description: 'Auto-accept incoming handoffs (default: true)' },
      agentId: { type: 'string', description: 'Agent ID to watch for (default: cursor)' },
    },
  },
}

Handler Flow:

Poll GET /api/handoffs/pending every pollInterval seconds
If handoff found with status 'pending':
- If autoAccept, call POST /api/handoffs/{id}/accept
- Return handoff details to Cursor
If timeout reached, return empty result
Cursor processes the handoff task
Cursor calls complete_handoff with result

New MCP Tool: `agent_broadcast`

{
  name: 'agent_broadcast',
  description: 'Broadcast a message to all connected agents',
  inputSchema: {
    type: 'object',
    properties: {
      channel: { type: 'string', description: 'Channel name (e.g., "general", "urgent")' },
      message: { type: 'string', description: 'Message content' },
      data: { type: 'object', description: 'Additional structured data' },
    },
    required: ['channel', 'message'],
  },
}

Workflow Examples

Example 1: Cowork asks Cursor to review code

Cowork (external):

POST /api/handoffs
{
  "targetAgent": "cursor",
  "task": "Review the new CodeDnaService implementation",
  "context": {
    "files": ["apis/backend-ai-api/src/app/learning/services/code-dna.service.ts"],
    "focusAreas": ["error handling", "performance"]
  },
  "priority": "high"
}

Cursor (watching):

Tool: watch_handoffs
→ Receives handoff
→ Reads specified files
→ Performs code review
→ Calls complete_handoff with review comments

Cowork (polling):

GET /api/handoffs/{id}
→ Sees status: "completed"
→ Reads review comments

Example 2: Cursor delegates testing to Cowork

Cursor:

Tool: create_handoff
{
  targetAgent: "cowork",
  task: "Run E2E tests for groundbreaking features",
  context: { testFile: "groundbreaking-features.test.ts" }
}

Cowork (polling):

GET /api/handoffs/pending?target=cowork
→ Receives handoff
→ Runs tests
→ Reports results via complete_handoff

Backend Changes Required

1. Add Handoff Notification Endpoint

// apis/backend-ai-api/src/app/infrastructure/controllers/handoff.controller.ts

@Get('watch')
async watchForHandoffs(
  @Query('agent') agentId: string,
  @Query('timeout') timeout: number = 30,
): Promise<Handoff | null> {
  // Long-polling: wait for handoff or timeout
  const startTime = Date.now();
  while (Date.now() - startTime < timeout * 1000) {
    const handoff = await this.handoffService.getPendingForAgent(agentId);
    if (handoff.length > 0) return handoff[0];
    await this.sleep(1000); // Check every second
  }
  return null;
}

2. Add WebSocket Events (Future)

// Emit when handoff created
this.wsGateway.broadcast('handoff:created', { handoffId, targetAgent, task });

// Emit when handoff completed
this.wsGateway.broadcast('handoff:completed', { handoffId, result });

Recommended Adoption Path

Phase 1: Polling (NOW)

Implement watch_handoffs tool
Add long-polling endpoint
Create handoff workflow documentation
Latency: 1-5 seconds

Phase 2: WebSocket (NEXT)

Add WebSocket connection from MCP server to backend
Push notifications on handoff events
Latency: <100ms

Phase 3: Full Event System (FUTURE)

Redis/NATS message queue
Event sourcing for handoffs
Multi-agent coordination
Latency: <50ms

Usage Instructions

For External Agents (Cowork)

Create a task for Cursor:

curl -X POST http://localhost:3001/ai-api/infrastructure/handoffs \
  -H "Content-Type: application/json" \
  -d '{
    "fromAgent": "cowork",
    "toAgentType": "cursor",
    "type": "implementation",
    "summary": "Review the CodeDnaService",
    "tasks": [{"description": "Check error handling"}],
    "workspace": "editor2"
  }'

Poll for response:

curl http://localhost:3001/ai-api/infrastructure/handoffs/{id}

For Cursor Agent

Start watching for handoffs:

Call watch_handoffs with timeout: 300, autoAccept: true

Process received handoff (automatic based on task)
Complete with result:

Call complete_handoff with handoffId and result

Security Considerations

Agent authentication via JWT token
Rate limiting on polling endpoints
Handoff validation (task size limits)
Audit logging for all agent communications

Tool Summary

Tool	Purpose	Status
`watch_handoffs`	Poll for incoming handoffs, auto-accept	✅ Implemented
`agent_broadcast`	Broadcast message to all agents	✅ Implemented
`create_handoff`	Create task for another agent	✅ Existing
`check_handoffs`	Check pending handoffs (one-time)	✅ Existing
`complete_handoff`	Complete a handoff with results	✅ Existing

Architecture designed for Session 81 | February 2, 2026