Collaborative Human Agent Protocol (CHAP)

The definitive standard for synergistic cooperation between humans and AI agents.

When an AI agent generates a draft and a human refines it, where is that modification actually stored?

In the CHAP ecosystem, that edit isn't lost in a chat void; it resides within a structured envelope that can be queried, replayed, and audited years down the line.

---

🎯 Why CHAP is Necessary

You are likely already deploying agents to handle substantive workloads:

• Generating code review suggestions.
• Managing ticket triage.
• Proposing legal settlements.
• Analyzing complex contracts.

Currently, the "logic" behind these decisions is scattered across application logs, disjointed chat threads, ticket comments, and the mental models of your employees.

The Problem: When a failure occurs six weeks later, reconstructing the decision path takes roughly 45 minutes of forensic work and is largely based on guesswork.

The Solution: CHAP provides a unified location and a standardized format for these decisions. A human's modification is treated as a structured override, containing:

1. A precise diff.
2. A clear rationale.
3. Customizable tags.

Instead of grep-ing through four different user interfaces, you simply query the decision chain.

Comparison: The Decision Trail

---

🚀 The 90-Second Tour

Imagine a developer utilizing Cursor to manage pull request (PR) reviews. The following workflow executes in approximately 23 seconds across six distinct stages.

🛠️ Implementation Checklist

• Initialize Coordinator
• Establish Persistence (SQLite)
• Define Workspace and Profiles
• Register Participants
• Execute Task Lifecycle
• Apply Human Override

🔄 Logic Flow

💻 Technical Execution

You can implement this using either TypeScript or Python.

1. Setup: Coordinator & Persistence

First, we establish the environment and the participants.

TypeScript

import { Coordinator } from "@brightbeamai/chap-coordinator";
import { SqliteStore } from "@brightbeamai/chap-coordinator/storage/sqlite";

const coord = new Coordinator({
  store: new SqliteStore("./chap.db"),
});

coord.create({
  workspace: "wsp_pr_reviews",
  profiles: ["core/1.0", "review/1.0"],
});

coord.join({ workspace: "wsp_pr_reviews", from: "human:me@local", type: "human" });
coord.join({ workspace: "wsp_pr_reviews", from: "agent:cursor#v1", type: "agent" });

Python

from chap_coordinator import Coordinator
from chap_coordinator.sqlite import SqliteStore

coord = Coordinator(store=SqliteStore("./chap.db"))

def send(method, params):
    return coord.dispatch({
        "jsonrpc": "2.0",
        "id": method,
        "method": method,
        "params": params,
    })

send("workspace.create", {
    "workspace": "wsp_pr_reviews", 
    "profiles": ["core/1.0", "review/1.0"]
})
send("participant.join", { "workspace": "wsp_pr_reviews", "from": "human:me@local", "type": "human" })
send("participant.join", { "workspace": "wsp_pr_reviews", "from": "agent:cursor#v1", "type": "agent" })

2. Execution: The Task & The Override

The agent performs the work, and the human provides the corrective nuance.

TypeScript

// Agent generates the review
coord.create({
  workspace: "wsp_pr_reviews",
  from: "agent:cursor#v1",
  assignee: "agent:cursor#v1",
  kind: "code_review",
  input: { pr_id: "PR-482" },
});

coord.complete({
  workspace: "wsp_pr_reviews",
  from: "agent:cursor#v1",
  task_id,
  output: cursorReview,
});

coord.request({
  workspace: "wsp_pr_reviews",
  from: "agent:cursor#v1",
  task_id,
  artefact: cursorReview,
  to: "human:me@local",
});

// Human corrects a specific detail
coord.override({
  workspace: "wsp_pr_reviews",
  from: "human:me@local",
  task_id,
  intent_preserved: true,
  diff: [{ op: "replace", path: "/comments/0/severity", value: "info" }],
  rationale: "False positive. Framework convention, not a bug.",
  tags: ["false-positive", "framework-pattern-misread"],
});

Python

# Agent generates the review
r = send("task.create", {
    "workspace": "wsp_pr_reviews",
    "from": "agent:cursor#v1",
    "assignee": "agent:cursor#v1",
    "kind": "code_review",
    "input": { "pr_id": "PR-482" },
})
task_id = r["result"]["task_id"]

send("task.complete", {
    "workspace": "wsp_pr_reviews",
    "from": "agent:cursor#v1",
    "task_id": task_id,
    "output": cursor_review,
})

send("review.request", {
    "workspace": "wsp_pr_reviews",
    "from": "agent:cursor#v1",
    "task_id": task_id,
    "artefact": cursor_review,
    "to": "human:me@local",
})

# Human corrects a specific detail
send("decide.override", {
    "workspace": "wsp_pr_reviews",
    "from": "human:me@local",
    "task_id": task_id,
    "intent_preserved": True,
    "diff": [{"op": "replace", "path": "/comments/0/severity", "value": "info"}],
    "rationale": "False positive. Framework convention, not a bug.",
    "tags": ["false-positive", "framework-pattern-misread"],
})

📐 Conceptual Model

The essence of a CHAP decision can be represented as: $\text{Decision} = \text{AgentOutput} + \sum (\text{HumanOverride}(\text{diff}, \text{rationale}, \text{tags}))$

---

📂 Repository Architecture

The project is organized to support both specification and implementation:

• core/: The fundamental protocol logic.
• ceps/: CHAP Enhancement Proposals.
• schemas/: Structural definitions for envelopes.
• integrations/: Connectors for external tools.
• scenarios/: Real-world use cases.
• docs/: Comprehensive guides and the SPECIFICATION.md.

Note on Interfaces: The TypeScript implementation provides a typed facade (coord.api.*), ensuring that developers benefit from full IDE autocomplete and type safety during development.