Skip to content

AGENT_CONTRACT.md

Latest commit

 

History

History
230 lines (173 loc) · 7.9 KB

AGENT_CONTRACT.md

File metadata and controls

230 lines (173 loc) · 7.9 KB
Raw

Agent Contract

CodeAgora exposes one machine-readable review contract for automation surfaces:

  • CLI agora review --output json
  • CLI agora review --json-stream
  • CLI agora sessions list --json and agora sessions show --json
  • MCP review tools when output_format: "json" is requested

The current contract marker is:

codeagora.review.v1

Only the versioned JSON/NDJSON surfaces in this document are stable machine contracts. Compact MCP output and presentation renderers such as text, Markdown, GitHub-flavored Markdown, HTML, JUnit, and SARIF may change during beta unless they are explicitly versioned here.

JSON Result

agora review --output json writes one JSON object to stdout.

Required top-level fields:

{
  "schemaVersion": "codeagora.review.v1",
  "status": "success",
  "date": "2026-04-27",
  "sessionId": "001",
  "summary": {
    "decision": "ACCEPT",
    "reasoning": "No blocking issues.",
    "totalReviewers": 3,
    "forfeitedReviewers": 0,
    "severityCounts": {
      "HARSHLY_CRITICAL": 0,
      "CRITICAL": 0,
      "WARNING": 0,
      "SUGGESTION": 0
    },
    "topIssues": [],
    "totalDiscussions": 0,
    "resolved": 0,
    "escalated": 0
  },
  "evidenceDocs": [],
  "discussions": []
}

For failed pipeline runs:

{
  "schemaVersion": "codeagora.review.v1",
  "status": "error",
  "date": "2026-04-27",
  "sessionId": "001",
  "error": "Pipeline failed"
}

Consumers should branch first on schemaVersion, then status, then summary.decision.

NDJSON Stream

agora review --json-stream writes newline-delimited JSON only. It does not also print the normal text formatter. Each line is one complete JSON object with a type discriminator. Consumers should ignore unknown fields and continue reading until a type: "result" event arrives.

Progress event:

{"schemaVersion":"codeagora.review.v1","type":"progress","stage":"review","event":"stage-update","progress":40,"message":"2/5 reviewers complete","timestamp":1777248000000}

Final result event:

{"type":"result","schemaVersion":"codeagora.review.v1","status":"success","date":"2026-04-27","sessionId":"001","summary":{"decision":"ACCEPT"}}

Progress event fields:

Field Values
type progress
stage init, review, discuss, verdict, complete
event stage-start, stage-update, stage-complete, stage-error, pipeline-complete
progress integer percentage, 0 to 100
message human-readable status string
timestamp Unix epoch milliseconds

Result event fields are the same as JSON Result plus type: "result". The final result event is always the last contract event emitted by the CLI command.

Desktop review-run event handling

The desktop app consumes agora review --json-stream through its Tauri bridge. The bridge must parse this stable contract first:

  1. Require schemaVersion: "codeagora.review.v1" for contract handling.
  2. Branch on type:
    • progress: preserve stage, event, progress, message, timestamp, and optional sessionId.
    • result: preserve status, sessionId, and summary.decision when present.
  3. Treat unknown contract fields as additive and non-breaking.
  4. Fall back to legacy/best-effort parsing only when schemaVersion is missing or different.

Desktop-specific fields such as kind are presentation adapters and are not part of the CLI NDJSON contract. New integrations should not infer state from ad-hoc aliases such as phase, status, or degradedReason unless they are explicitly in the legacy fallback path.

Exit Codes

agora review uses deterministic exit codes for CI and agent callers:

Code Meaning
0 Review command completed and no requested failure gate tripped
1 Review completed, but --fail-on-reject or --fail-on-severity tripped
2 User-actionable setup/input/config error
3 Runtime or pipeline failure

Notes:

  • A REJECT verdict alone exits 0 unless --fail-on-reject is set.
  • --fail-on-severity exits 1 when any issue is at or above the configured severity.
  • Pipeline results with status: "error" exit 3.

Session JSON

Session JSON is intentionally smaller than review JSON, but uses the same contract marker.

agora sessions list --json:

{
  "schemaVersion": "codeagora.review.v1",
  "sessions": [
    {
      "id": "2026-04-27/001",
      "date": "2026-04-27",
      "sessionId": "001",
      "status": "completed",
      "dirPath": ".ca/sessions/2026-04-27/001"
    }
  ]
}

agora sessions show 2026-04-27/001 --json:

{
  "schemaVersion": "codeagora.review.v1",
  "entry": {
    "id": "2026-04-27/001",
    "date": "2026-04-27",
    "sessionId": "001",
    "status": "completed",
    "dirPath": ".ca/sessions/2026-04-27/001"
  },
  "metadata": {},
  "verdict": {}
}

Session Artifact Contract

Persisted session artifacts under .ca/sessions/{YYYY-MM-DD}/{NNN}/ use a dedicated session artifact marker:

codeagora.session.v1

New metadata.json files include schemaVersion: "codeagora.session.v1". Terminal pipeline paths also persist readable result.json with the same marker for normal reviews, lightweight --skip-head reviews, cache hits, empty diffs, auto-approvals, degraded reviewer failures, and pipeline errors when a session directory exists.

Readers that encounter missing schemaVersion, missing metadata.json, or missing result.json must treat the session as legacy/best-effort: keep rendering whatever artifacts are available, report zero findings or unknown/best-effort decisions where needed, and avoid raw stack traces or filesystem parse errors in user-facing CLI/MCP/desktop output.

agora sessions show --json may annotate old metadata as:

{
  "artifactContract": "legacy/best-effort"
}

Consumers should branch on the persisted artifact schemaVersion when it is present, and otherwise use the legacy/best-effort path without migrating or rewriting user session directories.

MCP Alignment

MCP review tools default to compact output to preserve agent context. review_quick and review_full accept either diff or staged: true; review_pr accepts pr_url or pr_number; review tools also accept shared options such as reviewer_count, reviewer_names, provider, model, timeout_seconds, reviewer_timeout_seconds, no_cache, context_lines, repo_path, and output_format.

When repo_path is supplied, the MCP server validates that it resolves to an accessible directory inside the server cwd/repository root before invoking the review pipeline.

Default compact response shape:

{
  "decision": "ACCEPT",
  "reasoning": "No blocking issues.",
  "issues": [],
  "summary": "No issues found.",
  "sessionId": "2026-04-27/001"
}

For compact MCP output, decision is ACCEPT, REJECT, NEEDS_HUMAN, or ERROR; issues is an array of compact finding objects; summary is a short string; and sessionId is the review session identifier when available.

When a caller requests output_format: "json", MCP delegates to the same CLI JSON formatter and therefore includes schemaVersion: "codeagora.review.v1".

MCP tool failures keep MCP protocol isError: true and return a structured JSON body:

{
  "status": "error",
  "code": "INVALID_REPO_PATH",
  "message": "repo_path is outside the allowed repository boundary",
  "details": {
    "repoPath": "/tmp/outside-repo"
  }
}

MCP error codes are stable strings such as INVALID_INPUT, INVALID_REPO_PATH, REVIEW_FAILED, REVIEW_PR_FAILED, DRY_RUN_FAILED, CONFIG_GET_FAILED, CONFIG_SET_FAILED, EXPLAIN_SESSION_FAILED, LEADERBOARD_FAILED, and STATS_FAILED. Consumers should branch on status and code; details is optional diagnostic context.

Supported non-compact review output formats:

text, json, md, github, html, junit, sarif