The Agent Protocol

The Agent Protocol is the heart of dkod. It replaces Git's clone/push/pull cycle with six semantic operations designed for the way AI agents actually work: CONNECT, CONTEXT, SUBMIT, VERIFY, MERGE, and WATCH.

Why a New Protocol?

Git was designed in 2005 for humans typing code in text editors. Every operation assumes a human is involved — cloning entire repositories, staging changes, writing commit messages, creating pull requests, waiting for CI.

AI agents don't work that way. They need to:

Understand specific parts of a codebase, not download all of it
Submit structural changes, not text-based diffs
Get verification results instantly, not wait for CI pipelines
Coordinate with other agents in real time

The Agent Protocol is a binary protocol over gRPC connections. It is stateful — agents maintain a session with the platform rather than performing stateless clone/push operations.

The Six Operations

1. CONNECT — Establish Agent Session

Agents don't clone. They connect. The connection is persistent and bidirectional.

Agent → Platform: CONNECT
  agent_id: "claude-code-v3"
  codebase: "org/repo"
  intent: "Refactor auth module to use OAuth2"

Platform → Agent: SESSION_ESTABLISHED
  session_id: "sess_a1b2c3"
  codebase_version: "v1847"
  changeset_id: "cs_abc123"
  workspace_id: "ws_x1y2z3"
  summary: {languages, total_symbols, total_files}
  concurrency: {active_sessions: 3, other_sessions: [...]}

The agent gets an isolated session workspace — a copy-on-write overlay over the current codebase. Changes are invisible to other agents until submitted and integrated.

The concurrency field in the response provides workspace awareness: active_sessions shows the number of concurrent sessions, and other_sessions[] lists each with its agent_id, intent, and active_files — so agents can coordinate and avoid unnecessary conflicts from the start.

Performance: < 50ms — vs. git clone which takes seconds to minutes.

2. CONTEXT — Request Semantic Context

Instead of cloning an entire repo and grepping through files, agents ask for exactly what they need.

Agent → Platform: CONTEXT_REQUEST
  query: "All functions that handle user authentication"
  depth: "full"
  include_tests: true
  include_dependencies: true

Platform → Agent: CONTEXT_RESPONSE
  results: [
    {
      symbol: "authenticate_user",
      file: "src/auth/handler.rs",
      signature: "fn authenticate_user(req: &Request) -> Result<User>",
      test_symbol_ids: ["sym_t1a2b3", "sym_t4c5d6"]
    }
  ]
  estimated_tokens: 4521

The platform serves semantic slices of the codebase, not file trees. An agent asking "give me the auth flow" gets exactly the AST nodes, signatures, and relationships it needs — nothing more. Note that caller/callee data is only included at depth: "call_graph", not at depth: "full". The test_symbol_ids field returns symbol IDs that can be resolved with a follow-up CONTEXT query.

Performance: < 200ms — vs. git clone + file search which takes seconds to minutes.

Write-time conflict awareness: When agents write files during their session via dk_file_write, the platform checks whether another active session has modified the same symbol. If so, the write succeeds but returns a conflict_warnings[] array — an early signal that helps agents adapt before submitting. See Conflict Types for details.

3. SUBMIT — Submit Semantic Changeset

Agents submit complete, atomic changes with structured rationale — no staging, no partial commits.

Agent → Platform: SUBMIT_CHANGESET
  session_id: "sess_a1b2c3"
  intent: "Replaced session auth with OAuth2"
  changes: [
    { type: "modify_function", symbol: "authenticate_user", rationale: "..." },
    { type: "add_function", symbol: "validate_oauth_token", rationale: "..." },
    { type: "delete_function", symbol: "legacy_session_check", rationale: "..." }
  ]
  changeset_id: "cs_abc123"    // assigned by the server during CONNECT, passed back here

Note: Verification runs as a separate step via the VERIFY operation. The changeset_id is server-assigned during the CONNECT handshake (returned in the ConnectResponse) — the agent passes it back to associate the submission with the correct changeset.

Key differences from git push:

The changeset is semantic, not textual — it describes what changed at the AST level
It includes structured rationale for every change (not a commit message)
Verification is a separate VERIFY step, not part of submission
The agent submits the complete, atomic change — no staging area

Performance: < 100ms to acknowledge — vs. git push which takes seconds.

Inline Review Summary

Every successful SUBMIT response now includes a review_summary field with the local code review results:

tier — review tier ("local" for built-in analysis)
score — quality score from 1 (critical issues) to 5 (excellent)
findings_count — number of findings detected
top_severity — highest severity level ("error", "warning", or "info")

This gives agents immediate feedback on code quality without a separate review call. For full review details (individual findings with file, line, category, and suggestions), use the REVIEW operation via dk_review. See Code Review Intelligence for details.

When Conflicts Are Detected

If another agent's changes have already been integrated and conflict with this changeset at the symbol level, the platform returns a ConflictBlock instead of proceeding to verification:

Note: The protocol notation below uses pseudo-code shorthand. In the actual wire format (see SDK Reference), their_change and your_change are objects with { description, change_type } sub-fields.

Platform → Agent: SUBMIT_RESULT
  status: "conflict"
  conflicting_symbols: [
    {
      symbol: "authenticate_user",
      file: "src/auth/handler.rs",
      base_version: "fn authenticate_user(req: &Request) -> Result<User>",
      their_change: { description: "Added rate_limit parameter", change_type: "modified" },
      your_change: { description: "Changed return type to Result<AuthToken>", change_type: "modified" }
    }
  ]
  message: "Symbol-level conflict detected on authenticate_user"

The ConflictBlock contains conflicting_symbols (a list of SubmitSymbolConflictDetail) and a message. The agent pauses, explains the conflict to the user with a summary of what each side changed, and resolves programmatically (e.g., re-reading context and adapting). See Conflict Types for the full taxonomy.

4. VERIFY — Explicit Verification

VERIFY runs lint, type-checking, and tests against a submitted changeset. It is called explicitly by the agent or harness — not auto-triggered on submit. VERIFY is a server-streaming RPC — the platform streams individual step results as each verification gate completes, rather than returning a single response.

// Server streams individual step results as they complete:

Platform → Agent: VERIFY_STEP_RESULT
  step_order: 1,
  step_name: "typecheck",
  status: "passed",
  output: "Type checking completed successfully.",
  required: true,
  findings: [],
  suggestions: []

Platform → Agent: VERIFY_STEP_RESULT
  step_order: 2,
  step_name: "lint",
  status: "passed",
  output: "No lint warnings.",
  required: true,
  findings: [],
  suggestions: []

Platform → Agent: VERIFY_STEP_RESULT
  step_order: 3,
  step_name: "affected_tests",
  status: "failed",
  output: "1 test failed",
  required: true,
  findings: [
    { test: "test_api_auth", error: "Expected Session, got OAuthToken",
      file: "tests/api/auth_test.rs", line: 47 }
  ],
  suggestions: ["Update the test to use OAuthToken instead of Session"]

The agent receives structured failure data streamed in real time and can immediately fix and resubmit — no waiting for CI, no parsing log output.

Performance: < 30s for affected tests — vs. 5–30 minutes for full CI.

5. MERGE — Integrate the Verified Changeset

Once all verification gates pass, dkod integrates the changeset internally within the platform — resolving it against the current codebase state using its AST-level understanding. MERGE is the semantic integration step; pushing to GitHub is a separate PUSH RPC.

This is not a Git merge. dkod handles the integration internally at the semantic level.

Platform → Agent: MERGE_RESULT
  commit_hash: "a1b2c3d4e5f6..."
  merged_version: "v1848"
  auto_rebased: true
  auto_rebased_files: ["src/auth/handler.rs", "src/auth/middleware.rs"]
  summary: "Refactored auth from sessions to OAuth2.
            12 functions modified, 3 added, 47 tests updated.
            All verification gates passed."

After MERGE succeeds, a separate PUSH RPC creates a feature branch on the upstream GitHub repository and optionally opens a pull request. The PR on GitHub gives your team the standard review workflow — approvals, CI checks, comments — while dkod has already guaranteed structural correctness.

If human review is required before the PR is created, the platform generates an intent-level summary — not a line-by-line diff, but a clear explanation of what changed, why, and what the impact is.

When Conflicts Arise at Integration

If another agent's changes were integrated between when this changeset passed verification and when it's being merged, a conflict can arise:

Platform → Agent: MERGE_CONFLICT
  conflicting_symbols: [
    {
      symbol: "authenticate_user",
      file: "src/auth/handler.rs",
      base_version: "fn authenticate_user(req: &Request) -> Result<User>",
      their_change: { description: "Modified by agent-2 after your verification passed", change_type: "modified" },
      your_change: { description: "Your verified changeset", change_type: "modified" }
    }
  ]
  message: "Conflict detected during merge — another agent integrated changes after verification passed"

This differs from submit-time conflicts: SUBMIT catches conflicts before verification runs, while MERGE catches conflicts that arose between verification and integration — because another agent's changes were integrated in the interim.

Performance: < 50ms for internal integration + < 2s for GitHub push — vs. the PR merge cycle which takes hours or days.

Implementation note: The conceptual "land" operation maps to two separate RPCs: dk_merge and dk_push. dk_merge integrates the verified changeset into dkod's semantic code graph — this is an internal integration, not a GitHub merge. dk_push then creates a feature branch on GitHub and optionally opens a pull request (returning fields like branch and pull_request_url). The actual GitHub PR merge is done by humans or CI, not by the agent.

6. WATCH — Real-Time Codebase Awareness

Multiple agents working on the same codebase stay aware of each other's changes in real time.

Agent → Platform: WATCH
  filter: "changeset.*"    // glob pattern: "*" (all), "changeset.*", "*.merged", etc.

Platform → Agent: WATCH_EVENT
  event_id: "evt_1a2b3c"
  event_type: "changeset.submitted"
  changeset_id: "cs_xyz789"
  agent_id: "devin-agent-7"
  session_id: "sess_d4e5f6"
  repo_id: "repo_abc123"
  affected_symbols: ["UserSession", "authenticate_user"]
  affected_files: ["src/auth/session.rs", "src/auth/handler.rs"]
  symbol_changes: [
    { symbol: "UserSession", change_type: "modified" }
  ]
  details: "Agent devin-agent-7 modified UserSession field list."

This enables multi-agent coordination without conflicts. Agents know when other agents modify symbols they depend on and can adapt in real time.

End-to-End Performance

Operation	dkod	Git/GitHub
CONNECT (session)	< 50ms	`git clone` — seconds to minutes
CONTEXT (query)	< 200ms	clone + grep — seconds to minutes
SUBMIT (changeset)	< 100ms	`git push` — seconds
VERIFY (tests)	< 30s	Full CI — 5–30 min
MERGE (integrate) + PUSH	< 50ms + < 2s	PR merge — hours/days
End-to-end	< 60 seconds	Hours to days

Wire Format

Transport: gRPC
Serialization: Protocol Buffers + raw bytes for blobs
Compression: Protocol Buffers binary encoding
Authentication: Bearer token (JWT or shared secret)
Encryption: TLS 1.3 (configurable at deployment, not mandated by the protocol)

Next Steps

Session Isolation — how the platform isolates 20+ concurrent agents
Semantic Merging — why structural merging eliminates false conflicts
SDK Reference — the full Python and Rust SDK interface
Code Review Intelligence — automated review on every submission