Unified Agent Protocol v1.0

One protocol. All platforms. Every AI agent follows the same lifecycle regardless of whether it's Cursor, Claude Code, Vitto, Cowork, or an external API client.

The Session Lifecycle

┌─────────────────────────────────────────────────────────────────┐
│                                                                  │
│   INIT ──────► WORK ──────► VERIFY ──────► CLOSE                │
│                                                                  │
│   1. preflight()      2. Code changes    3. Build/test    4. log_decision()  │
│   2. git checkout     3. Commits with    4. Confirm       5. outcome()       │
│   3. manifest check      [S{N}.{sub}]       changes work  6. reflect()       │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Platform Setup Matrix

Each platform needs ONE env var to identify itself:

MCP Config Template (for new agents)

{
  "mcpServers": {
    "mcp-gograb-ai": {
      "command": "/path/to/workspace/MCP/mcp-gograb-ai/start-server.sh",
      "args": [],
      "env": {
        "WORKSPACE_ROOT": "/path/to/workspace",
        "<PLATFORM>_AGENT": "true"
      }
    }
  }
}

Replace <PLATFORM>_AGENT with the correct env var for your platform.

Step-by-Step: Starting a Session

1. Call Preflight

preflight({ task: "description", sessionNumber: N })

This does:

• Sets the MCP session context (MongoDB + local cache)
• Auto-creates manifest sessions/manifests/S{N}.json if missing
• Auto-creates docs directory docs/english/sessions/S{N}/ if missing
• Returns: past decisions, conventions, warnings, branch status

2. Check Git branch (lane)

git branch --show-current
# Lane must relate to session N: session-{N} OR a range lane (e.g. session-264-269_new)
# If wrong:  git checkout <lane>
# If new:    git checkout -b <lane>

SAGP v1.3 rules:

• Several sessions may share one lane (range / shared branches)
• session-{N} or range lane — no workspace prefix on branch names
• Sub-sessions tracked via commit tags: [S{N}.{sub}] (authoritative on shared lanes)

Full spec: session-git-concurrent-lanes-spec.md

3. Check Sub-Session Number

Read: sessions/manifests/S{N}.json → subSessions[] → last sub + 1
Set:  session({ action: "set", sessionNumber: N, subSessionNumber: X })

Rules:

• Never reuse a sub-session number
• Never skip numbers (always +1)
• Multiple agents on same session each take the next available sub

4. Work and Commit

# Stage specific files
git add path/to/file1 path/to/file2

# Commit with session tag
git commit -m "[S{N}.{sub}] type: description"

Commit types: feat, fix, refactor, test, docs, chore, style

Forbidden:

• git add . or git add -A (stages unrelated files)
• Working on main directly
• Committing files from another session

5. Verify Changes

Check that changes work (running dev server, build, or tests).

6. Close

log_decision({ type, question, chosen, reasoning, confidence })
outcome({ action: "report", decisionId, wasSuccessful, feedback })

For complex tasks:

intelligence({ action: "reflect", taskSummary, outcome, lessonsLearned })

Concurrent Sessions

Multiple agents work simultaneously. Each owns one session.

┌─────────────┐   ┌─────────────┐   ┌─────────────┐
│ Cursor       │   │ Claude Code │   │ Vitto        │
│ Session 190  │   │ Session 193 │   │ Session 194  │
│ session-190  │   │ session-193 │   │ session-194  │
└──────┬───────┘   └──────┬──────┘   └──────┬──────┘
       │                  │                  │
       ▼                  ▼                  ▼
┌─────────────────────────────────────────────────┐
│        sessions/history.json                     │
│  activeSessions: [                               │
│    { session: 190, platform: "cursor" },         │
│    { session: 193, platform: "claude-code" },    │
│    { session: 194, platform: "vitto" }           │
│  ]                                               │
└─────────────────────────────────────────────────┘

Rules:

• NEVER reset or override another agent's session
• Each platform gets its own entry in activeSessions[]
• Use session({ action: "get_info" }) before setting

Vitto Agent Specifics

Vitto is GoGrab's autonomous orchestrator. It runs full tasks from the platform.

4-Phase Workflow:

ANALYZE → PLAN → EXECUTE → VERIFY

Vitto-specific env:

{
  "VITTO_AGENT": "true",
  "VITTO_SESSION_ID": "<task-id-from-platform>"
}

CostGuard limits: 25 iterations, 100K tokens, 5min per task

Backend: backend-vitto-api (port 3003) — separate from backend-ai-api (port 3001)

Cowork Agent Specifics

Cowork (Claude Desktop in collaborative mode) is used for testing and oversight.

Setup:

{
  "COWORK_AGENT": "true",
  "COWORK_SESSION_ID": "<conversation-id>"
}

Typical role: Testing Director — validates work done by coding agents (Cursor/Claude Code).

Troubleshooting

File Reference