{
  "ok": true,
  "artifact": "odei.agent-builder.handoff-protocol",
  "protocolVersion": "agent_builder_handoff_v1",
  "generatedAt": "2026-06-13T20:53:34.864Z",
  "endpoint": "/auth/agent-builder/handoff",
  "codeEndpoint": "/auth/agent-builder/handoff-code",
  "tokenEndpoint": "/auth/agent-builder/handoff-code",
  "legacyTokenEndpoint": "/auth/agent-builder/handoff-token",
  "discoveryEndpoint": "/auth/agent-builder/handoff/protocol",
  "supportedOperators": [
    "codex",
    "claude-code",
    "gemini-cli"
  ],
  "capabilities": [
    "protocol_discovery_v1",
    "tokenless_pairing_code",
    "idempotent_setup_callback",
    "bearer_stage_receipts",
    "structured_next_actions",
    "safe_negative_diagnostics",
    "redacted_callback_secrets",
    "rate_limited_public_handoff",
    "helper_request_templates",
    "helper_stage_submission",
    "helper_receipt_validation",
    "helper_offline_receipt_validation",
    "helper_token_inspection",
    "helper_token_file_input",
    "helper_token_file_permission_guard",
    "helper_endpoint_trust_guard",
    "helper_endpoint_path_guard",
    "helper_redirect_guard",
    "helper_token_clock_skew_guard"
  ],
  "helper": {
    "packageScript": "npm run agent-builder:handoff --",
    "connectCommand": "node scripts/agent-builder-handoff.mjs connect ODEI-CODEX-XXXX-XXXX-XXXX --endpoint \"https://app.odei.ai/auth/agent-builder/handoff\"",
    "connectTokenCommand": "node scripts/agent-builder-handoff.mjs connect --callback-token-file .odei-handoff-token --endpoint \"https://app.odei.ai/auth/agent-builder/handoff\"",
    "tokenInfoCommand": "node scripts/agent-builder-handoff.mjs token-info --callback-token-file .odei-handoff-token",
    "protocolCommand": "node scripts/agent-builder-handoff.mjs protocol --endpoint \"https://app.odei.ai/auth/agent-builder/handoff\"",
    "diagnoseCommand": "node scripts/agent-builder-handoff.mjs diagnose --endpoint \"https://app.odei.ai/auth/agent-builder/handoff\"",
    "templateCommand": "node scripts/agent-builder-handoff.mjs template submit_verifier_receipt --endpoint \"https://app.odei.ai/auth/agent-builder/handoff\"",
    "validateCommand": "node scripts/agent-builder-handoff.mjs validate --action submit_verifier_receipt --body-file receipt.json --endpoint \"https://app.odei.ai/auth/agent-builder/handoff\"",
    "offlineValidateCommand": "node scripts/agent-builder-handoff.mjs validate --offline --action submit_verifier_receipt --body-file receipt.json",
    "submitCommand": "node scripts/agent-builder-handoff.mjs submit --action submit_verifier_receipt --body-file receipt.json --callback-token-file .odei-handoff-token --endpoint \"https://app.odei.ai/auth/agent-builder/handoff\"",
    "legacyInlineTokenFlag": "--callback-token <bearer>"
  },
  "authModes": [
    {
      "id": "pairing_code",
      "tokenRequired": false,
      "scope": "current_handoff_run",
      "allowedActions": [
        "mark_setup_running",
        "submit_machine_survey",
        "submit_install_receipt",
        "submit_runtime_config",
        "submit_verifier_receipt",
        "mark_blocked"
      ]
    },
    {
      "id": "bearer_token",
      "tokenRequired": true,
      "scope": "full_live_handoff_run",
      "allowedActions": [
        "mark_setup_running",
        "submit_machine_survey",
        "submit_install_receipt",
        "submit_runtime_config",
        "submit_verifier_receipt",
        "mark_blocked"
      ]
    }
  ],
  "receiptRequirements": {
    "submit_machine_survey": {
      "receiptKey": "machine",
      "statusPath": "machine.status",
      "requiredPaths": [
        "machine.status",
        "machine.summary",
        "machine.evidence"
      ],
      "completedRequiredPaths": [
        "machine.platform",
        "machine.osLabel",
        "machine.arch",
        "machine.nodeVersion",
        "machine.npmVersion",
        "machine.gitVersion",
        "machine.workspacePath"
      ],
      "evidencePath": "machine.evidence",
      "blockerPath": "machine.blockers"
    },
    "submit_install_receipt": {
      "receiptKey": "install",
      "statusPath": "install.status",
      "requiredPaths": [
        "install.status",
        "install.summary",
        "install.evidence"
      ],
      "completedRequiredPaths": [
        "install.platform",
        "install.repoPath",
        "install.repoRef",
        "install.packageManager",
        "install.dependencyStatus",
        "install.buildStatus"
      ],
      "evidencePath": "install.evidence",
      "blockerPath": "install.blockers"
    },
    "submit_runtime_config": {
      "receiptKey": "runtime",
      "statusPath": "runtime.status",
      "requiredPaths": [
        "runtime.status",
        "runtime.summary",
        "runtime.evidence"
      ],
      "completedRequiredPaths": [
        "runtime.platform",
        "runtime.repoPath",
        "runtime.envPath",
        "runtime.mcpConfigPath",
        "runtime.neo4jStatus",
        "runtime.envReady",
        "runtime.mcpReady",
        "runtime.openAiKeyReady"
      ],
      "evidencePath": "runtime.evidence",
      "blockerPath": "runtime.blockers"
    },
    "submit_verifier_receipt": {
      "receiptKey": "receipt",
      "statusPath": "receipt.status",
      "requiredPaths": [
        "receipt.status",
        "receipt.summary",
        "receipt.evidence"
      ],
      "completedRequiredPaths": [
        "receipt.repoPath",
        "receipt.platform",
        "receipt.neo4jReachable",
        "receipt.schemaReady",
        "receipt.graphReadWrite",
        "receipt.doctorCommand",
        "receipt.doctorExitCode"
      ],
      "completedMustEqual": {
        "receipt.neo4jReachable": true,
        "receipt.schemaReady": true,
        "receipt.graphReadWrite": true,
        "receipt.doctorExitCode": 0
      },
      "evidencePath": "receipt.evidence",
      "blockerPath": "receipt.blockers"
    },
    "mark_blocked": {
      "requiredPaths": [
        "stage",
        "summary",
        "blockers"
      ],
      "stagePath": "stage",
      "blockerPath": "blockers"
    }
  },
  "requestShapes": {
    "mark_setup_running": {
      "contentType": "application/json",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "pairingCodeBody": {
        "action": "mark_setup_running",
        "pairingCode": "ODEI-CODEX-XXXX-XXXX-XXXX"
      },
      "bearerBody": {
        "action": "mark_setup_running"
      },
      "successStatuses": [
        "accepted",
        "already_connected"
      ],
      "nextAction": "request_machine_stage"
    },
    "submit_machine_survey": {
      "contentType": "application/json",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "body": {
        "action": "submit_machine_survey",
        "machine": {
          "status": "completed | blocked",
          "summary": "Exact local machine survey summary.",
          "platform": "unix | windows",
          "osLabel": "macOS, Linux, or Windows label from the local shell.",
          "arch": "arm64 | x64 | other",
          "nodeVersion": "Detected Node.js version.",
          "npmVersion": "Detected npm version.",
          "gitVersion": "Detected Git version.",
          "dockerStatus": "available | unavailable | optional",
          "neo4jStatus": "reachable | unavailable | unknown",
          "workspacePath": "Absolute or home-relative workspace path.",
          "evidence": [
            "Real command output summary."
          ],
          "blockers": []
        }
      },
      "nextAction": "request_install_stage"
    },
    "submit_install_receipt": {
      "contentType": "application/json",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "body": {
        "action": "submit_install_receipt",
        "install": {
          "status": "completed | blocked",
          "summary": "Exact source install summary.",
          "platform": "unix | windows",
          "repoPath": "Local canonical repo path.",
          "repoRef": "Pinned ODEI bootstrap ref.",
          "packageManager": "npm",
          "dependencyStatus": "installed | blocked",
          "buildStatus": "completed | blocked",
          "evidence": [
            "Real install/build evidence."
          ],
          "blockers": []
        }
      },
      "nextAction": "request_runtime_stage"
    },
    "submit_runtime_config": {
      "contentType": "application/json",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "body": {
        "action": "submit_runtime_config",
        "runtime": {
          "status": "completed | blocked",
          "summary": "Exact runtime configuration summary.",
          "platform": "unix | windows",
          "repoPath": "Local canonical repo path.",
          "envPath": "Path to .env.",
          "mcpConfigPath": "Path to .mcp.json.",
          "neo4jStatus": "configured | blocked",
          "envReady": true,
          "mcpReady": true,
          "openAiKeyReady": true,
          "evidence": [
            "Real runtime evidence."
          ],
          "blockers": []
        }
      },
      "nextAction": "request_launch_stage"
    },
    "submit_verifier_receipt": {
      "contentType": "application/json",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "body": {
        "action": "submit_verifier_receipt",
        "receipt": {
          "status": "completed | blocked",
          "summary": "What changed and what the verifier proved.",
          "repoPath": "Local canonical repo path.",
          "platform": "unix | windows",
          "neo4jReachable": true,
          "schemaReady": true,
          "graphReadWrite": true,
          "doctorCommand": "Exact verifier command that ran locally.",
          "doctorExitCode": 0,
          "evidence": [
            "Neo4j reachable",
            "Graph write/read succeeded"
          ],
          "blockers": []
        }
      },
      "nextAction": "no_action_required"
    },
    "mark_blocked": {
      "contentType": "application/json",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "body": {
        "action": "mark_blocked",
        "stage": "machine | install | runtime | launch",
        "summary": "Exact local blocker summary.",
        "blockers": [
          "Exact failed command, missing dependency, denied permission, or unavailable service."
        ]
      },
      "nextAction": "resolve_blockers"
    }
  },
  "actions": [
    {
      "id": "mark_setup_running",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "purpose": "Claim a freshly issued run and move the handoff into setup_running.",
      "successStatuses": [
        "accepted",
        "already_connected"
      ],
      "nextAction": "request_machine_stage"
    },
    {
      "id": "submit_machine_survey",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "purpose": "Return real OS, shell, Git, Node/npm, Docker, Neo4j, and workspace evidence.",
      "nextAction": "request_install_stage"
    },
    {
      "id": "submit_install_receipt",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "purpose": "Return canonical repository, dependency, and build evidence.",
      "nextAction": "request_runtime_stage"
    },
    {
      "id": "submit_runtime_config",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "purpose": "Return .env, MCP config, Neo4j, and minimum runtime readiness evidence.",
      "nextAction": "request_launch_stage"
    },
    {
      "id": "submit_verifier_receipt",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "purpose": "Return final verifier evidence and let ODEI decide completed, blocked, or verifier_received.",
      "nextAction": "no_action_required"
    },
    {
      "id": "mark_blocked",
      "authModes": [
        "pairing_code",
        "bearer_token"
      ],
      "purpose": "Return exact blockers without claiming completion.",
      "nextAction": "resolve_blockers"
    }
  ],
  "states": [
    {
      "id": "idle",
      "nextAction": "generate_fresh_handoff"
    },
    {
      "id": "issued",
      "nextAction": "run_setup_callback"
    },
    {
      "id": "claimed",
      "nextAction": "request_machine_stage"
    },
    {
      "id": "setup_running",
      "nextAction": "request_machine_stage"
    },
    {
      "id": "machine_requested",
      "nextAction": "submit_machine_survey"
    },
    {
      "id": "machine_received",
      "nextAction": "request_install_stage"
    },
    {
      "id": "install_requested",
      "nextAction": "submit_install_receipt"
    },
    {
      "id": "install_received",
      "nextAction": "request_runtime_stage"
    },
    {
      "id": "runtime_requested",
      "nextAction": "submit_runtime_config"
    },
    {
      "id": "runtime_received",
      "nextAction": "request_launch_stage"
    },
    {
      "id": "launch_requested",
      "nextAction": "submit_verifier_receipt"
    },
    {
      "id": "verified",
      "nextAction": "no_action_required"
    },
    {
      "id": "blocked",
      "nextAction": "resolve_blockers"
    },
    {
      "id": "expired",
      "nextAction": "generate_fresh_handoff"
    },
    {
      "id": "revoked",
      "nextAction": "generate_fresh_handoff"
    },
    {
      "id": "superseded",
      "nextAction": "generate_fresh_handoff"
    }
  ],
  "replay": {
    "idempotentAction": "mark_setup_running",
    "successStatus": "already_connected",
    "nextAction": "request_machine_stage"
  },
  "responseSafety": {
    "callbackPairingCode": "redacted",
    "bearerToken": "never_returned",
    "acceptedCallbackState": "redacted"
  },
  "errors": [
    {
      "error": "expected_json_request",
      "status": 415,
      "nextAction": "rerun_callback_with_json"
    },
    {
      "error": "invalid_json_body",
      "status": 400,
      "nextAction": "rerun_callback_with_valid_json"
    },
    {
      "error": "request_body_too_large",
      "status": 413,
      "nextAction": "rerun_callback_with_smaller_json"
    },
    {
      "error": "invalid_agent_builder_handoff",
      "status": 401,
      "nextAction": "generate_fresh_handoff"
    },
    {
      "error": "agent_builder_handoff_token_conflict",
      "status": 400,
      "nextAction": "rerun_callback_with_single_token_source"
    },
    {
      "error": "invalid_agent_builder_pairing_code",
      "status": 401,
      "nextAction": "generate_fresh_handoff"
    },
    {
      "error": "agent_builder_handoff_expired",
      "status": 410,
      "nextAction": "generate_fresh_handoff"
    },
    {
      "error": "agent_builder_handoff_not_yet_valid",
      "status": 425,
      "nextAction": "sync_clock_or_generate_fresh_handoff"
    },
    {
      "error": "agent_builder_handoff_token_mismatch",
      "status": 409,
      "nextAction": "copy_latest_handoff_from_odei"
    },
    {
      "error": "agent_builder_handoff_superseded",
      "status": 409,
      "nextAction": "copy_latest_handoff_from_odei"
    },
    {
      "error": "invalid_agent_builder_action",
      "status": 400,
      "nextAction": "run_supported_handoff_action"
    }
  ],
  "limits": {
    "jsonBodyBytes": 24576,
    "handoffTtlMs": 43200000,
    "pairingCodeRandomBytes": 12,
    "helperTokenClockSkewSeconds": 300
  }
}